feat(directory): a category leads with what has just been published (#218)

/podcasts opened on whichever show the importer reached last and showed no
dates at all, so a directory of 318,000 podcasts fronted shows that had
published nothing for six weeks and gave a reader no way to tell.

Two changes to the same complaint:

  * the river. `view=latest` — now the default for podcasts — is the newest
    episodes across every show, picked by `latestItems`: the 400 feeds with the
    newest material, then their items through feed_items_feed_pub_idx, rather
    than the feeds-to-items aggregate 0030 measured at 215 seconds. New index
    feeds_category_published_idx makes that pick affordable for the rare
    categories the river was built for.
  * the roster. `view=shows` is ordered by when each feed last published and
    says so on every row ("Latest episode Aug 12, 2026", with the gap on
    hover). Feeds with no publish date yet — 42,000 still waiting on a first
    crawl, including everything submitted this week — keep their arrival order
    and follow the dated ones, so the pager still reaches them and a submitter
    can still watch their feed turn up.

listFeedsByPublished is deliberately two queries rather than one `nulls last`:
that ordering cannot be served by an index here, and sorting a category of
318,000 rows on every request is not a page load.

Also on this branch: per-category follow filters, and the directory feed and
following feed follow the view they advertise.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ralyodio

apps/web/next.config.mjs

@@ -257,6 +257,21 @@ const nextConfig = {
           destination: '/api/fb/:page/feed/:format',
         },
 
+        // The playlist spellings, for the categories that publish their own
+        // entries at this address rather than the feeds that carry them — the
+        // ones marked `river` in CATEGORIES, which today is podcasts alone.
+        // /podcasts.m3u is the newest episode of every show in one file.
+        //
+        // Named before the rule below rather than folded into its format list,
+        // because every other category's `.m3u` must keep 404ing: a directory
+        // entry is a feed, and a playlist of feeds is an empty file with a
+        // confident name. apps/web/test/subscribe.test.js asserts this list is
+        // exactly the river categories.
+        {
+          source: '/:kind(podcasts).:format(m3u|pls)',
+          destination: '/api/directory/:kind/feed/:format',
+        },
+
         // One category of it. The segments are the category pages' own paths,
         // duplicated from CATEGORIES in apps/web/src/lib/categories.js — this
         // file is evaluated before the workspace resolves, so it cannot import
@@ -314,6 +329,11 @@ const nextConfig = {
       // type looking for it, including us.
       { source: '/crawlstatus', destination: '/crawlstats', permanent: true },
 
+      // The river lives at /following; /follow is what it gets called. Query
+      // preserved by default, which is the half that matters now the page
+      // takes a `?kind=` filter — /follow?kind=podcast has to arrive intact.
+      { source: '/follow', destination: '/following', permanent: true },
+
       // /register is also where an OAuth client looks for dynamic registration
       // when it has found no metadata anywhere else, and it POSTs JSON to do
       // it. A redirect to a page of HTML is a confusing answer to that, so a

apps/web/src/app/CategoryIndex.jsx

@@ -18,5 +18,12 @@ export async function GET(req, { params }) {
   const { kind, format } = await params;
   const url = new URL(req.url);
 
-  return directoryRiver({ kind, format, limit: url.searchParams.get('limit') });
+  return directoryRiver({
+    kind,
+    format,
+    limit: url.searchParams.get('limit'),
+    // The caller's own query does survive the rewrite, which is what lets
+    // `/podcasts.rss?view=shows` ask for the other half of the page.
+    view: url.searchParams.get('view'),
+  });
 }

apps/web/src/app/api/directory/[kind]/feed/[format]/route.js

@@ -8,7 +8,13 @@ import {
 
 import { db, siteUrl } from '../../../../../lib/db.js';
 import { fetchFeedAds } from '../../../../../lib/feedAds.js';
-import { RIVER_LIMIT, following, followingFeedUrl } from '../../../../../lib/following.js';
+import { CATEGORIES } from '../../../../../lib/categories.js';
+import {
+  RIVER_LIMIT,
+  following,
+  followingFeedUrl,
+  riverKinds,
+} from '../../../../../lib/following.js';
 
 export const dynamic = 'force-dynamic';
 
@@ -42,7 +48,12 @@ export async function GET(req, { params }) {
     return fail(format, 404, `unsupported format: ${format}`, 'Supported: rss, atom, json, xml');
   }
 
-  const token = new URL(req.url).searchParams.get('t') ?? '';
+  const query = new URL(req.url).searchParams;
+  const token = query.get('t') ?? '';
+  // The same filter the page offers as chips, so a reader who narrowed the
+  // river to podcasts and then took the feed away gets the podcasts. Anything
+  // unrecognised is the whole river, exactly as on the page.
+  const kinds = riverKinds(query.get('kind'));
   const client = db();
   const user = await accounts.userByFeedToken(client, token);
 
@@ -60,6 +71,7 @@ export async function GET(req, { params }) {
 
   const { feeds, topics, authors, items } = await following(client, String(user.id), {
     limit: RIVER_LIMIT,
+    kinds,
   });
 
   const origin = siteUrl();
@@ -84,14 +96,21 @@ export async function GET(req, { params }) {
   const body = buildSyndication(
     format,
     {
-      title: 'Following — RSS Amplifier',
-      description: `Recent posts from the ${count(topics.length, 'topic')}, ${count(
+      // A filtered river says so in its own title: a reader subscribed to both
+      // this and the whole thing must be able to tell them apart in a list of
+      // feeds, and "Following" twice over cannot.
+      title: kinds
+        ? `Following: ${CATEGORIES[kinds[0]].heading} — RSS Amplifier`
+        : 'Following — RSS Amplifier',
+      description: `Recent ${
+        kinds ? CATEGORIES[kinds[0]].item : 'posts'
+      } from the ${count(topics.length, 'topic')}, ${count(
         authors.length,
         'person',
         'people',
       )} and ${count(feeds.length, 'blog')} this RSS Amplifier account follows.`,
-      link: `${origin}/following`,
-      selfUrl: followingFeedUrl(origin, token, format),
+      link: `${origin}/following${kinds ? `?kind=${kinds[0]}` : ''}`,
+      selfUrl: followingFeedUrl(origin, token, format, kinds),
     },
     interleaveAds(rows, ads),
   );

apps/web/src/app/api/following/feed/[format]/route.js

@@ -9,12 +9,15 @@ import { FILTER_FROM } from '../../lib/listFilter.js';
 import { db, siteUrl } from '../../lib/db.js';
 import { currentUser, hasSessionCookie } from '../../lib/auth.js';
 import { postThumb } from '../../lib/thumbs.js';
+import { CATEGORIES } from '../../lib/categories.js';
 import {
   RIVER_LIMIT,
   RIVER_AUTHORS,
   RIVER_TOPICS,
   following as loadFollowing,
   followingFeedUrl,
+  kindsAvailable,
+  riverKinds,
   topicLabel,
 } from '../../lib/following.js';
 
@@ -67,7 +70,14 @@ export async function generateMetadata() {
  * about this" — but they have the same answer shape, and a reader who has asked
  * both wants one list back rather than two pages to check.
  *
- * @param {{ searchParams: Promise<{ feed?: string, rotated?: string }> }} props
+ * `?kind=` narrows the river to one category of the directory — podcasts,
+ * videos, blogs — without touching what is followed. That distinction is the
+ * whole design of it: the lists above the river are the inventory of follows
+ * and stay whole, because a filter that hid follows would look like an
+ * unfollow, and the river below is the reading, which is what somebody
+ * narrowing to "podcasts" actually means.
+ *
+ * @param {{ searchParams: Promise<{ feed?: string, rotated?: string, kind?: string }> }} props
  */
 export default async function FollowingPage({ searchParams }) {
   const params = await searchParams;
@@ -82,14 +92,17 @@ export default async function FollowingPage({ searchParams }) {
 
   const client = db();
   const userId = String(user.id);
+  const kinds = riverKinds(params.kind);
 
   const [{ feeds, topics, authors, items, topicsUsed, authorsUsed }, token] = await Promise.all([
-    loadFollowing(client, userId, { limit: RIVER_LIMIT }),
+    loadFollowing(client, userId, { limit: RIVER_LIMIT, kinds }),
     accounts.feedToken(client, userId),
   ]);
 
   const origin = siteUrl();
   const nothing = feeds.length === 0 && topics.length === 0 && authors.length === 0;
+  const filters = kindsAvailable({ feeds, topics, authors });
+  const filtered = kinds?.[0] ?? null;
 
   return (
     <>
@@ -220,20 +233,32 @@ export default async function FollowingPage({ searchParams }) {
         asking your reader to sign in: it grants read of these posts and nothing else — it cannot
         sign in, and it cannot change what you follow. Treat it as private anyway, because it says
         what you read.
+        {/* The filter travels with the address, so "just the podcasts" is
+            something to subscribe to rather than something to remember to do
+            each visit. Said out loud because the URL below changes under the
+            reader as they press the chips, and silently handing them a
+            different feed than the one they copied last time would be worse. */}
+        {filtered && (
+          <>
+            {' '}
+            While the river is filtered, these addresses carry the filter: they are your{' '}
+            {CATEGORIES[filtered].heading.toLowerCase()} alone.
+          </>
+        )}
       </p>
 
       {token ? (
         <>
           <p className="format-links">
             <span>Subscribe:</span>
             {['rss', 'atom', 'json'].map((ext) => (
-              <a key={ext} href={followingFeedUrl(origin, token, ext)}>
+              <a key={ext} href={followingFeedUrl(origin, token, ext, kinds)}>
                 {`.${ext}`}
               </a>
             ))}
           </p>
           <p className="hint">
-            <code>{followingFeedUrl(origin, token, 'rss')}</code>
+            <code>{followingFeedUrl(origin, token, 'rss', kinds)}</code>
           </p>
           <form action="/api/following/token" method="post" className="submit-actions">
             <input type="hidden" name="action" value="rotate" />
@@ -251,6 +276,34 @@ export default async function FollowingPage({ searchParams }) {
 
       <h2>Latest</h2>
 
+      {/* By kind, not by follow. Plain links in the same nav the topic pages
+          use for their sub-groups, so it works with JavaScript off and so each
+          filtered river is an address a reader can bookmark or hand to
+          somebody. Only the kinds this account actually follows are offered —
+          see kindsAvailable — and the bar is left out entirely when there is
+          only one, because a filter with a single setting filters nothing. */}
+      {filters.length > 1 && (
+        <nav className="topic-groups" aria-label="Filter the river by kind">
+          <a
+            href="/following"
+            aria-current={filtered ? undefined : 'page'}
+            className={filtered ? undefined : 'is-current'}
+          >
+            Everything
+          </a>
+          {filters.map((kind) => (
+            <a
+              key={kind}
+              href={`/following?kind=${kind}`}
+              aria-current={kind === filtered ? 'page' : undefined}
+              className={kind === filtered ? 'is-current' : undefined}
+            >
+              {CATEGORIES[kind].heading}
+            </a>
+          ))}
+        </nav>
+      )}
+
       {/* The river is the reason to come back to this page, and it is the one
           list here long enough that finding a post in it means scrolling. */}
       {items.length >= FILTER_FROM && (
@@ -259,9 +312,20 @@ export default async function FollowingPage({ searchParams }) {
 
       {items.length === 0 ? (
         <p className="empty">
-          {nothing
-            ? 'Nothing to show until you follow something.'
-            : 'Nothing published recently by anything you follow.'}
+          {nothing ? (
+            'Nothing to show until you follow something.'
+          ) : filtered ? (
+            // Names the filter as the reason. Without this a reader who
+            // narrowed to podcasts last week and came back to the bookmark
+            // would read an empty page as everything they follow having gone
+            // quiet at once.
+            <>
+              Nothing published recently under {CATEGORIES[filtered].heading.toLowerCase()}.{' '}
+              <a href="/following">Show everything</a>.
+            </>
+          ) : (
+            'Nothing published recently by anything you follow.'
+          )}
         </p>
       ) : (
         items.map((p) => {

apps/web/src/app/following/page.jsx

@@ -1,6 +1,5 @@
 import { siteUrl } from '../../lib/db.js';
-import { feedAlternates } from '../../lib/subscribe.js';
-import CategoryIndex, { CATEGORIES, pageNumber } from '../CategoryIndex.jsx';
+import CategoryIndex, { CATEGORIES, listHref, pageNumber, viewName } from '../CategoryIndex.jsx';
 
 export const dynamic = 'force-dynamic';
 
@@ -10,26 +9,38 @@ const CATEGORY = CATEGORIES.podcast;
  * @param {{ searchParams: Promise<Record<string, string|string[]|undefined>> }} props
  */
 export async function generateMetadata({ searchParams }) {
-  const page = pageNumber((await searchParams).page);
+  const params = await searchParams;
+  const page = pageNumber(params.page);
+  const view = viewName(params.view, CATEGORY);
+
+  const what = view === 'shows' ? 'every show' : 'the newest episodes';
+  const title = view === 'shows' ? 'Podcasts · every show' : CATEGORY.title;
 
   return {
-    title: page === 1 ? CATEGORY.title : `${CATEGORY.title} · page ${page}`,
-    description: CATEGORY.lede,
-    alternates: {
-      canonical:
-        page === 1 ? `${siteUrl()}${CATEGORY.path}` : `${siteUrl()}${CATEGORY.path}?page=${page}`,
-      // The category's own feed: what has just been added to it. Announced on
-      // every page of the listing rather than only the first, because it is the
-      // same feed either way and a reader deep in the directory is exactly the
-      // one who wants telling when more arrives.
-      types: feedAlternates(`${siteUrl()}${CATEGORY.path}`, CATEGORY.heading),
-    },
+    title: page === 1 ? title : `${title} · page ${page}`,
+    description:
+      view === 'shows'
+        ? 'Every podcast in the directory, newest show first.'
+        : CATEGORY.lede,
+    // Each page of each view canonicalises to itself: they hold different
+    // episodes and different shows, so collapsing them would ask crawlers to
+    // drop everything but the first sixty rows of one of them.
+    alternates: { canonical: `${siteUrl()}${listHref(CATEGORY.path, view, page)}` },
+    openGraph: { title, description: `Podcasts on RSS Amplifier — ${what}.` },
   };
 }
 
 /**
  * @param {{ searchParams: Promise<Record<string, string|string[]|undefined>> }} props
  */
 export default async function PodcastsPage({ searchParams }) {
-  return <CategoryIndex kind="podcast" page={pageNumber((await searchParams).page)} />;
+  const params = await searchParams;
+
+  return (
+    <CategoryIndex
+      kind="podcast"
+      page={pageNumber(params.page)}
+      view={viewName(params.view, CATEGORY)}
+    />
+  );
 }

apps/web/src/app/podcasts/page.jsx

@@ -45,10 +45,16 @@ export const CATEGORIES = {
     noun: 'podcasts',
     one: 'podcast',
     title: 'Podcasts',
-    lede: 'Shows with audio in their feed and a publisher who filled in the podcast namespaces, newest first. Episodes play in the reader while you read the show notes.',
+    lede: 'Every show with audio in its feed and a publisher who filled in the podcast namespaces. The newest episodes across all of them first — press play on any of them here.',
     schemaType: 'PodcastSeries',
+    entrySchemaType: 'PodcastEpisode',
     item: 'episodes',
     entry: 'episode',
+    // The category leads with what has just been published rather than with
+    // the feeds that published it. Only podcasts for now: it is the category
+    // where "what is new" is unarguably the question being asked, and the one
+    // whose entries the site can play where they stand. See CategoryIndex.
+    river: true,
   },
   music: {
     path: '/music',
@@ -122,3 +128,52 @@ export const CATEGORIES = {
 export const CATEGORY_SEGMENTS = new Map(
   Object.entries(CATEGORIES).map(([kind, meta]) => [meta.path.replace(/^\//, ''), kind]),
 );
+
+/**
+ * Read `?view=` as one of the two ways to look at a category.
+ *
+ * 'latest' is what has just been published across the whole category; 'shows'
+ * is the directory of who is in it. Only categories that say `river` in the
+ * table above offer the first, and for those it is the default — somebody
+ * opening /podcasts came for episodes, not for a list of feeds in the order we
+ * happened to index them.
+ *
+ * Anything unrecognised falls back the way a bad `?page=` does, and for the
+ * same reason: this is a parameter in a URL people edit, share and guess at,
+ * and a directory listing has no business refusing to render over one.
+ *
+ * @param {unknown} raw
+ * @param {{ river?: boolean }} [category]
+ * @returns {'latest'|'shows'}
+ */
+export function viewName(raw, category = {}) {
+  if (!category.river) return 'shows';
+
+  // A repeated parameter arrives as an array. Taking the first spelling rather
+  // than letting `String(['a','b'])` coerce to "a,b" — which matches nothing
+  // and would silently fall back — so `?view=shows&view=shows` means what it
+  // plainly says.
+  const value = String((Array.isArray(raw) ? raw[0] : raw) ?? '').toLowerCase();
+  return value === 'shows' ? 'shows' : 'latest';
+}
+
+/**
+ * A link to one page of one view of a category.
+ *
+ * Page 1 of the default view is the bare path, never `?page=1` and never
+ * `?view=latest`: the same listing under two URLs is a duplicate-content signal
+ * to the crawlers this directory exists for.
+ *
+ * @param {string} path
+ * @param {'latest'|'shows'} view
+ * @param {number} page
+ * @returns {string}
+ */
+export function listHref(path, view, page) {
+  const params = new URLSearchParams();
+  if (view === 'shows') params.set('view', 'shows');
+  if (page > 1) params.set('page', String(page));
+
+  const query = params.toString();
+  return query ? `${path}?${query}` : path;
+}