pmtiles-swarm 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## master
 ### ✨ Features and improvements
+- _...Add new stuff here..._
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.24.0
+### ✨ Features and improvements
+- **A mirror now inherits the archive summary from the feed it follows.** `renderItem` has always
+  published `pmtiles:format`, the zoom range, the bounds and the tile count, and `parseFeed` has
+  always thrown them away — so the fact that a feed is more useful than a generic torrent feed was
+  true of the XML and of nothing else. It matters more than it sounds: an archive is servable when
+  `entry.pmtiles` exists, so a fresh mirror served nothing at all until it had read the header out
+  of the swarm itself. On an 80 GiB planet archive whose only seed is busy that is hours of a node
+  that looks joined, downloads steadily, and answers every tile request with 400. The summary now
+  comes across with the item and the archive is servable the moment it is added. It is marked
+  `source: 'feed'`, because a summary taken on trust is not the same fact as one read off the
+  header, and the head warmer still replaces it with the latter as soon as it can read one.
 - **A watched folder can ask for its stable name to be a hard link.**
   `latestLinkType: "hard"` reverses the order the two kinds are attempted in,
   for a folder whose archives are read *through* that name rather than followed
@@ -58,6 +75,13 @@
   `/api/categories`, filtered by the same `feedCategories` rule, so it can show nothing that was
   not already published — and it is not the console, which stays on the admin port.
   `publicIndex: false` turns it off, withdrawing the three paths it needs with it.
+- **A category can be previewed, and the preview is the category's own URL.** `/latest/<category>/preview`
+  reads the TileJSON beside it, so it renders whatever build is current rather than pinning to the
+  one that was newest when the link was made — the same URL a style holds, demonstrating itself.
+  The preview page now derives its source from wherever it is served instead of assembling one from
+  an infohash, so one page serves both forms.
+- **The public page gained a filter and a sort.** Search by name, infohash or category; order by name,
+  newest or largest. Both re-render from what was already loaded rather than asking the node again.
 - **`GET /latest/` lists the categories, without a credential.** Everything else under
   `/latest/` is public — the TileJSON, the torrent, the magnet, the per-category feed — so the
   index of what it offers belongs beside them rather than behind the console's door. The public
@@ -77,6 +101,33 @@
   never checked.
 
 ### 🐞 Bug fixes
+- **Head warming now says whether it is running.** Every way it could decline was a bare `return`:
+  `tiles.prewarm` false, `prewarmIntervalSeconds` at zero, a node with no tile store to read with,
+  and — the one that actually bites — a pass that finds no archive eligible to warm. All four
+  produced an identical empty log, so "warming is switched off" and "warming is working and has
+  nothing to do" could not be told apart, and on a node whose mirrors were stuck at 400 the only
+  way to tell was to read the source. It now names the reason at startup, or says how often it will
+  look; and after ten idle passes it says either that everything has been summarised or which
+  archives it is skipping for want of a recognised kind. That last case is what an archive joined by
+  magnet looks like before its metainfo arrives: `guessKind` cannot tell it is PMTiles, `due`
+  refuses it, and nothing said so.
+- **One archive whose metainfo never arrived stopped every other archive being warmed.** A sweep
+  warms a single archive, chosen as the first one due, and an archive joined by magnet that has no
+  metainfo yet is answered "not yet" and deliberately left unstamped so the next pass retries in
+  seconds rather than after the full backoff. The two together meant an archive stuck that way
+  stayed due at no cost, was chosen again on every pass, and its neighbours were never attempted at
+  all — for as long as it was stuck, which where no peer ever answers is indefinitely. A node with
+  two mirrors could therefore warm neither, having genuinely tried only one. The fast retry is now
+  bounded: after five consecutive passes the wait has plainly stopped being nearly over, and it is
+  charged as an attempt like any other so the backoff spreads them out and lets its neighbours
+  through. It says so when it makes that switch, which is otherwise the quietest moment in the
+  process — the point where an archive goes from "about to work" to "may never work".
+- **A mutable magnet had nowhere to announce.** `mutableMagnet()` was never passed trackers, so the
+  BEP 46 form carried `xt`, `xs`, `dn`, `s` and `ws` and no `tr=` at all. The infohash added in
+  0.21.0 was therefore unusable from a browser, which has neither DHT nor peer exchange to fall
+  back on and so had nothing to ask — leaving the web seed, which is just HTTP, as the only source.
+  The archive's own trackers are now lifted across in all three places one is built: the TileJSON's
+  torrent block, the `styleUrl` fragment, and the publisher's own magnet.
 - **The public front page could not read its own catalogue.** `/api/catalog` is on the list of
   paths that belong on a public listener, but that is a separate gate from the credential check,
   which guards everything under `/api/` except login and session — so on any node with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/api.js

@@ -14,7 +14,7 @@ import {
   isPublicSurface,
 } from './auth.js';
 import { normalizeCategories } from './catalog.js';
-import { mutableMagnet } from './mutable.js';
+import { mutableMagnet, trackersFromMagnet } from './mutable.js';
 import { guessKind } from './library.js';
 import { QBittorrentEngine } from './engines/qbittorrent.js';
 import { RESTART_REQUIRED, redactConfig, saveConfig } from './config.js';
@@ -80,6 +80,10 @@ function styleUrlFor(category, newest, base) {
         // of this URL — a client that cannot reach the tiles.json in front of
         // it, or cannot resolve a public key, still has something to join.
         infoHash: newest.infoHash,
+        // Somewhere to announce it, lifted from the archive's own magnet. A
+        // fragment carrying an infohash and no tracker gives a browser
+        // something to join and nobody to ask for it.
+        trackers: trackersFromMagnet(newest.magnet),
         salt: newest.mutable.salt ?? category,
         // The category, since that is what this magnet resolves to.
         name: newest.mutable.salt ?? category,
@@ -1802,6 +1806,11 @@ export function createApp({
             // newest build's own magnet, which pins that build but still
             // beats a blank map when the fallback is needed at all.
             styleUrl: servable ? styleUrlFor(category, newest, base) : null,
+            // Points at the category, not at a build. The page reads the
+            // TileJSON beside it, so it renders whatever is current — which
+            // makes it the same URL a style holds, demonstrating itself rather
+            // than pinning to today's infohash.
+            preview: servable ? `${base}/latest/${category}/preview` : null,
             torrent: `${base}/latest/${category}/archive.torrent`,
             magnet: `${base}/latest/${category}/magnet`,
             feed: `${base}/feed/${category}.xml`,
@@ -1973,6 +1982,17 @@ export function createApp({
   // shareable and says what it shows. The page reads the TileJSON next to it —
   // which is a complete, valid TileJSON already, so nothing here has to invent
   // a source description.
+  // The same page for a category, which is the more useful one to hand
+  // somebody: it reads /latest/<category>/tiles.json, so it renders whatever
+  // build is current rather than pinning to the one that happened to be newest
+  // when the link was made. That is exactly what a style points at, so this is
+  // the URL demonstrating itself.
+  //
+  // The page works out which by its own path, so there is nothing to pass.
+  app.get('/latest/:category/preview', (_req, res) => {
+    res.sendFile(path.join(here, 'web', 'preview.html'));
+  });
+
   app.get('/archives/:infoHash/preview', (_req, res) => {
     res.sendFile(path.join(here, 'web', 'preview.html'));
   });

package/src/feed.js

@@ -165,8 +165,62 @@ export function formatBytes(bytes) {
  * @property {string} [category] - Item category.
  * @property {string} [mtime] - The archive's mtime on the node that built it.
  * @property {string} [mutableMagnet] - BEP 46 magnet, when the publisher has an identity for it.
+ * @property {object} [pmtiles] - Coverage summary, when the feed carries one.
  */
 
+/**
+ * Reads the `pmtiles:*` summary out of a feed item, when it has one.
+ *
+ * renderItem publishes format, zoom range, bounds, tile count and attribution
+ * for exactly this — so a subscriber can tell what an archive holds before
+ * committing to 80 GiB of it. For a long time nothing read them back, which had
+ * a consequence well beyond the feed being less informative than it looked: a
+ * mirror's `servable` flag is `Boolean(entry.pmtiles)`, so an archive arrived
+ * with no summary, was unservable, and stayed unservable until the head warmer
+ * managed to read the header out of the swarm — while the answer had been in
+ * the feed all along.
+ *
+ * Deliberately partial. There is no `vectorLayers` here, because the publisher
+ * has none to give: planetiler writes that section after every tile, so on a
+ * planet archive it is the very end of the file. An entry summarised from a
+ * feed therefore stays due for warming, which is what fills the rest in.
+ *
+ * @param {string} block - The item XML.
+ * @returns {object | undefined} - The summary, or undefined if absent.
+ */
+function mapSummary(block) {
+  const format = tag(block, 'pmtiles:format');
+  // Format is the field `servable` and the tile routes key off, so a summary
+  // without it is not a summary. Better no object at all than one that reports
+  // an archive as readable and then cannot say what is in it.
+  if (!format) return undefined;
+
+  const number = (name) => {
+    const raw = tag(block, name);
+    if (raw === undefined || raw.trim() === '') return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+  };
+
+  const bounds = (tag(block, 'pmtiles:bounds') ?? '')
+    .split(',')
+    .map((part) => Number(part.trim()))
+    .filter((part) => Number.isFinite(part));
+
+  return {
+    format,
+    minZoom: number('pmtiles:minzoom'),
+    maxZoom: number('pmtiles:maxzoom'),
+    bounds: bounds.length === 4 ? bounds : undefined,
+    tileCount: number('pmtiles:tiles'),
+    attribution: tag(block, 'pmtiles:attribution'),
+    // Says where this came from, because a summary taken on trust from another
+    // node is not the same fact as one read off the archive's own header, and
+    // the difference matters when the two disagree.
+    source: 'feed',
+  };
+}
+
 /**
  * Parses a subscribed feed.
  *
@@ -222,6 +276,10 @@ export function parseFeed(body) {
       // more than once, so take all of them.
       md5: tag(block, 'pmtiles:md5'),
       mtime: isoDate(tag(block, 'pmtiles:mtime')),
+      // What the publisher already knows about the archive's contents. Absent
+      // from a generic torrent feed, and absent from ours for an archive the
+      // publishing node has not summarised either.
+      pmtiles: mapSummary(block),
       categories: [...block.matchAll(/<category>([\s\S]*?)<\/category>/g)]
         .map((match) => decode(match[1]).trim())
         .filter(Boolean),

package/src/library.js

@@ -836,6 +836,17 @@ export class Library {
       complete,
       // Held until the download finishes, which may be hours away.
       originMtime: options.originMtime,
+      // What the peer that offered this says it holds, where it said anything.
+      // The head warmer replaces it with what the archive's own header says as
+      // soon as it can read one; until then this is what makes the archive
+      // servable at all, since `servable` is simply whether a summary exists.
+      //
+      // Spread rather than set, because catalog.put merges by spreading the
+      // record over the existing one -- and a key present with an undefined
+      // value still overwrites. Setting it unconditionally would mean an
+      // archive re-added from a feed that carries no summary silently lost the
+      // one it had already read for itself.
+      ...(options.pmtiles ? { pmtiles: options.pmtiles } : {}),
     });
 
     // The engine's add resolves once metadata is in hand, so for a magnet

package/src/mutable.js

@@ -90,6 +90,22 @@ function rawPublicKey(publicKey) {
  * @param {string} [options.salt] - Salt, when one key publishes several archives.
  * @returns {string} - A BEP 46 magnet URI.
  */
+/**
+ * The trackers a magnet announces to.
+ *
+ * A BEP 46 magnet is assembled rather than parsed from a torrent, so it has no
+ * announce list of its own — but the archive it names does, in the plain magnet
+ * beside it. Lifting them across is what makes the mutable form joinable: an
+ * infohash with nowhere to announce is an infohash a browser cannot act on,
+ * having neither DHT nor peer exchange to fall back on.
+ * @param {string} [magnet] - A magnet URI to read `tr=` out of.
+ * @returns {string[]} - The announce URLs, in the order they appeared.
+ */
+export function trackersFromMagnet(magnet) {
+  if (typeof magnet !== 'string' || !magnet.startsWith('magnet:?')) return [];
+  return new URLSearchParams(magnet.slice('magnet:?'.length)).getAll('tr');
+}
+
 export function mutableMagnet(publicKey, options = {}) {
   // Buffer.from(string) would read hex as UTF-8 and produce a 64-byte key, so
   // the two forms have to be told apart rather than coerced.

package/src/prewarm.js

@@ -20,6 +20,39 @@ const DEFAULT_MAX_BACKOFF_SECONDS = 600;
 /** How long to let the node settle before the first attempt. */
 const DEFAULT_INITIAL_DELAY_SECONDS = 10;
 
+/** How often to look for an archive that needs its head read. */
+const DEFAULT_INTERVAL_SECONDS = 30;
+
+/**
+ * How many consecutive passes may find nothing to warm before saying so.
+ *
+ * Silence is the right output for a node whose archives are all summarised, and
+ * it is also what a node produces when every archive is being skipped for a
+ * reason nobody can see — an entry whose kind is not yet known, most often,
+ * because it was joined by magnet and its metainfo has not arrived. One line
+ * after a few minutes of that separates the two without turning a healthy node
+ * into a log generator.
+ */
+const IDLE_PASSES_BEFORE_REPORTING = 10;
+
+/**
+ * How many passes in a row an archive may claim on the strength of "not yet".
+ *
+ * An archive joined from a magnet has no metainfo until BEP 9 finishes, which
+ * is usually seconds, so charging it the full backoff wastes a wait that was
+ * nearly over — hence the fast retry. What that must not do is cost nothing for
+ * ever. A pass warms one archive, chosen as the *first* that is due, and an
+ * entry that stays due at no cost is chosen again on the next pass and on every
+ * pass after it. One archive stuck this way therefore stops every other archive
+ * on the node from being warmed at all, silently, and for as long as it is
+ * stuck — which on a node whose peer never answers is indefinitely.
+ *
+ * Past this many passes the wait has plainly stopped being nearly over, and it
+ * is charged as an attempt like any other so the backoff can spread the
+ * attempts out and let its neighbours through.
+ */
+const MAX_CONSECUTIVE_EARLY_PASSES = 5;
+
 /**
  * Whether a failure means "not yet" rather than "not working".
  *
@@ -47,8 +80,11 @@ export class HeadWarmer {
   #tried = new Map();
   #attempts = new Map();
   #waiting = new Set();
+  /** Consecutive passes each archive has answered "not yet" to. */
+  #early = new Map();
   #running = false;
   #runningSince = 0;
+  #idlePasses = 0;
 
   /**
    * @param {object} tiles - The tile store, for `summarize`.
@@ -71,6 +107,31 @@ export class HeadWarmer {
     );
   }
 
+  /**
+   * Why this node is not warming, or null when it is.
+   *
+   * Exists so `start()` can say which of its several reasons applied. They are
+   * each a bare `return` on a condition, and the difference between them was
+   * invisible: a node with warming switched off, a node whose interval was set
+   * to zero, and a node warming perfectly well with nothing to do all produced
+   * exactly the same empty log.
+   * @returns {string | null} - The reason, or null.
+   */
+  get disabledReason() {
+    if (this.#config.tiles?.prewarm === false) {
+      return 'tiles.prewarm is false';
+    }
+    if (typeof this.#tiles?.summarize !== 'function') {
+      return 'this node has no tile store to read headers with';
+    }
+    const seconds =
+      this.#config.tiles?.prewarmIntervalSeconds ?? DEFAULT_INTERVAL_SECONDS;
+    if (seconds <= 0) {
+      return `tiles.prewarmIntervalSeconds is ${seconds}`;
+    }
+    return null;
+  }
+
   /**
    * Whether an archive is worth reading the head of right now.
    *
@@ -162,7 +223,11 @@ export class HeadWarmer {
     }
 
     const entry = this.#catalog.list().find((candidate) => this.due(candidate));
-    if (!entry) return null;
+    if (!entry) {
+      this.#reportIdle();
+      return null;
+    }
+    this.#idlePasses = 0;
 
     this.#running = true;
     this.#runningSince = this.#now();
@@ -175,6 +240,11 @@ export class HeadWarmer {
 
       this.#tried.set(entry.infoHash, this.#now());
       this.#waiting.delete(entry.infoHash);
+      // The metainfo evidently arrived, so the run of "not yet" answers is
+      // over. Cleared rather than left standing, since a later magnet re-add of
+      // the same archive starts its own wait and should get its own fast
+      // retries rather than inheriting a spent allowance.
+      this.#early.delete(entry.infoHash);
       // Counted even on success, because a read that got the header and not
       // the metadata has not finished and will be back. The count only matters
       // while an archive is still due, and one that is done is never asked
@@ -210,44 +280,103 @@ export class HeadWarmer {
       return stored;
     } catch (error) {
       if (tooEarly(error)) {
-        // Not stamped, so the next pass tries again in seconds rather than in
-        // minutes — and said once, because a node that has just started will
-        // answer this way until the metainfo lands.
-        if (!this.#waiting.has(entry.infoHash)) {
-          this.#waiting.add(entry.infoHash);
-          console.log(
-            `[warm] ${entry.name}: waiting for the torrent metadata before ` +
-              'reading its head',
-          );
+        const passes = (this.#early.get(entry.infoHash) ?? 0) + 1;
+        this.#early.set(entry.infoHash, passes);
+
+        if (passes <= MAX_CONSECUTIVE_EARLY_PASSES) {
+          // Not stamped, so the next pass tries again in seconds rather than in
+          // minutes — and said once, because a node that has just started will
+          // answer this way until the metainfo lands.
+          if (!this.#waiting.has(entry.infoHash)) {
+            this.#waiting.add(entry.infoHash);
+            console.log(
+              `[warm] ${entry.name}: waiting for the torrent metadata before ` +
+                'reading its head',
+            );
+          }
+          return null;
         }
-        return null;
+
+        // Waited long enough to stop calling it a wait. Said out loud, because
+        // this is the moment the archive goes from "about to work" to "may
+        // never work", and it is otherwise the quietest possible transition.
+        console.warn(
+          `[warm] ${entry.name}: still has no torrent metadata after ` +
+            `${passes} passes; treating that as a failure so other archives ` +
+            'get a turn',
+        );
+      } else {
+        // A real attempt: it reached the swarm and found nothing. Ordinary
+        // while an archive is young, since the piece holding the header may not
+        // exist anywhere reachable yet. Worth saying, because it is the answer
+        // to "why is my preview blank", and the backoff keeps it from becoming
+        // noise.
+        console.warn(`[warm] ${entry.name}: ${error.message}`);
+        this.#early.delete(entry.infoHash);
       }
 
-      // A real attempt: it reached the swarm and found nothing. Ordinary while
-      // an archive is young, since the piece holding the header may not exist
-      // anywhere reachable yet. Worth saying, because it is the answer to "why
-      // is my preview blank", and the backoff keeps it from becoming noise.
       this.#tried.set(entry.infoHash, this.#now());
       this.#waiting.delete(entry.infoHash);
       this.#attempts.set(
         entry.infoHash,
         (this.#attempts.get(entry.infoHash) ?? 0) + 1,
       );
-      console.warn(`[warm] ${entry.name}: ${error.message}`);
       return null;
     } finally {
       this.#running = false;
     }
   }
 
+  /**
+   * Says why nothing is being warmed, when that has gone on long enough to be
+   * worth explaining.
+   *
+   * Distinguishes the two ways a pass finds nothing: everything is summarised,
+   * which is the goal, and everything is being skipped, which is a fault that
+   * otherwise looks identical. The archives that are neither summarised nor
+   * eligible are named, because the reason is almost always visible in the name
+   * — an entry still called by its infohash has no metainfo yet, so `guessKind`
+   * cannot tell it is PMTiles and `due` refuses it.
+   * @returns {void}
+   */
+  #reportIdle() {
+    this.#idlePasses++;
+    if (this.#idlePasses !== IDLE_PASSES_BEFORE_REPORTING) return;
+
+    const unread = this.#catalog
+      .list()
+      .filter((entry) => !entry.pmtiles?.format);
+    if (unread.length === 0) {
+      console.log('[warm] every archive has been summarised; nothing to warm');
+      return;
+    }
+    console.warn(
+      `[warm] ${unread.length} archive(s) have no summary and none are ` +
+        'eligible to be warmed; their kind is not PMTiles, or is not yet ' +
+        `known: ${unread
+          .slice(0, 5)
+          .map((entry) => entry.name ?? entry.infoHash)
+          .join(', ')}${unread.length > 5 ? ', …' : ''}`,
+    );
+  }
+
   /**
    * Starts warming, and keeps at it.
    * @returns {void}
    */
   start() {
-    if (!this.enabled) return;
-    const seconds = this.#config.tiles?.prewarmIntervalSeconds ?? 30;
-    if (seconds <= 0) return;
+    // Said once at startup, either way. A node that is not warming is a node
+    // whose mirrored archives will not become servable on their own, and that
+    // is far too important to be inferred from the absence of log lines --
+    // which is exactly how it had to be diagnosed before.
+    const reason = this.disabledReason;
+    if (reason) {
+      console.warn(`[warm] not warming: ${reason}`);
+      return;
+    }
+    const seconds =
+      this.#config.tiles?.prewarmIntervalSeconds ?? DEFAULT_INTERVAL_SECONDS;
+    console.log(`[warm] reading archive heads every ${seconds}s`);
 
     const run = () =>
       this.sweep().catch((error) =>

package/src/publisher.js

@@ -17,7 +17,11 @@
  * docs/internals.md — "Why a third DHT".
  */
 
-import { mutableMagnet, publishInfoHash } from './mutable.js';
+import {
+  mutableMagnet,
+  publishInfoHash,
+  trackersFromMagnet,
+} from './mutable.js';
 
 /** Republish well inside the ~2h a DHT keeps an item. */
 const DEFAULT_INTERVAL_MS = 30 * 60 * 1000;
@@ -197,6 +201,9 @@ export class MutablePublisher {
       // The current build, for a client that cannot resolve the key. Absent
       // when no entry was given, which leaves the series-only form.
       infoHash: entry?.infoHash,
+      // Somewhere to announce it, lifted from the archive's own magnet. An
+      // infohash with no tracker beside it is one a browser cannot act on.
+      trackers: trackersFromMagnet(entry?.magnet),
       salt: category,
       // The category rather than the build. This magnet resolves to whichever
       // archive is current, so naming one of them dates the string the moment

package/src/subscriptions.js

@@ -409,6 +409,16 @@ export class SubscriptionManager {
       // The mtime on the node that built it, which BitTorrent will not carry.
       // Restored when the download completes.
       originMtime: item.mtime,
+      // What the publisher says the archive holds: format, zoom range, bounds.
+      //
+      // This is the difference between a mirror that can serve tiles the moment
+      // it joins and one that cannot serve them until it has read the header out
+      // of the swarm -- which, for an 80 GiB archive whose only seed is busy,
+      // can be a very long time, and used to be the only way an entry ever got
+      // a summary at all. The head warmer still runs and still overwrites this
+      // with what the archive itself says; this only means the wait is not
+      // spent unservable.
+      pmtiles: item.pmtiles,
     };
 
     // The .torrent is preferred where there is one: it carries the trackers

package/src/tilejson.js

@@ -1,4 +1,4 @@
-import { mutableMagnet } from './mutable.js';
+import { mutableMagnet, trackersFromMagnet } from './mutable.js';
 import { TileStore } from './tiles.js';
 
 /**
@@ -106,6 +106,9 @@ function buildTorrentBlock(entry, root) {
         // can join from this string alone rather than having to come back for
         // an infohash.
         infoHash: entry.infoHash,
+        // And somewhere to announce it. Without these the infohash above is
+        // unusable from a page: no DHT, no peer exchange, nothing to ask.
+        trackers: trackersFromMagnet(entry.magnet),
         salt: entry.mutable.salt,
         // The category, not this build: the record resolves to whichever
         // archive is current, and `dn` is a label the metadata replaces.

package/src/web/preview.html

@@ -79,8 +79,17 @@
       import * as maplibregl from '/vendor/maplibre-gl/maplibre-gl.mjs';
       import MaplibreInspect from '/vendor/maplibre-gl-inspect/maplibre-gl-inspect.mjs';
 
-      const infoHash = location.pathname.split('/')[2];
-      const tileJsonUrl = `/archives/${infoHash}/tiles.json`;
+      // Derived from wherever this page is served rather than assembled from
+      // an infohash, so one page previews both an archive and a category:
+      //   /archives/<infohash>/preview  ->  /archives/<infohash>/tiles.json
+      //   /latest/<category>/preview    ->  /latest/<category>/tiles.json
+      // The second is the one worth having, because it is what a style should
+      // actually point at — it follows the newest build instead of pinning to
+      // the one that happened to be current when the link was made.
+      const tileJsonUrl = location.pathname.replace(
+        /\/preview\/?$/,
+        '/tiles.json',
+      );
       const $ = (id) => document.getElementById(id);
 
       const fail = (message) => {
@@ -104,7 +113,7 @@
       const vector =
         vectorLayers.length > 0 || /\.(pbf|mvt)(\?|$)/.test(tilejson.tiles?.[0] ?? '');
 
-      $('name').textContent = tilejson.name ?? infoHash;
+      $('name').textContent = tilejson.name ?? tileJsonUrl;
       $('summary').textContent =
         `${vector ? 'vector' : 'raster'} · z${tilejson.minzoom ?? 0}–${tilejson.maxzoom ?? 14}` +
         (vector

package/src/web/public.html

@@ -159,6 +159,42 @@
         display: block;
         margin-bottom: 1.5rem;
       }
+      .toolbar {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.6rem 0.9rem;
+        align-items: center;
+        margin-bottom: 1.5rem;
+      }
+      .toolbar input[type='search'] {
+        flex: 1 1 18rem;
+        min-width: 0;
+        padding: 0.45rem 0.6rem;
+        border: 1px solid var(--line);
+        border-radius: 6px;
+        background: var(--card);
+        color: inherit;
+        font: inherit;
+      }
+      .toolbar label {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.4rem;
+        color: var(--muted);
+        font-size: 0.9rem;
+      }
+      .toolbar select {
+        padding: 0.35rem 0.4rem;
+        border: 1px solid var(--line);
+        border-radius: 6px;
+        background: var(--card);
+        color: inherit;
+        font: inherit;
+      }
+      .count {
+        color: var(--muted);
+        font-size: 0.85rem;
+      }
     </style>
   </head>
   <body>
@@ -176,6 +212,25 @@
         </p>
       </noscript>
 
+      <div class="toolbar" id="toolbar" hidden>
+        <input
+          type="search"
+          id="filter"
+          placeholder="Filter by name or category…"
+          autocomplete="off"
+          spellcheck="false"
+        />
+        <label>
+          Sort
+          <select id="sort">
+            <option value="name">name</option>
+            <option value="newest">newest first</option>
+            <option value="largest">largest first</option>
+          </select>
+        </label>
+        <span class="count" id="count"></span>
+      </div>
+
       <div id="categories"></div>
       <div id="archives"><p class="empty">Loading…</p></div>
 
@@ -337,6 +392,9 @@
           };
           const ends = entry.endpoints;
           if (ends.tileJson) add(ends.tileJson, 'TileJSON');
+          // The newest build's preview, which is what "show me this
+          // category" means.
+          if (ends.preview) add(ends.preview, 'preview');
           if (ends.torrent) add(ends.torrent, '.torrent');
           if (ends.magnet) add(ends.magnet, 'magnet');
           if (ends.feed) add(ends.feed, 'RSS');
@@ -407,6 +465,58 @@
         });
       };
 
+      // Held so the filter and the sort re-render from memory rather than
+      // asking the node again on every keystroke.
+      let loadedArchives = [];
+      let loadedCategories = [];
+
+      const matches = (text, needle) =>
+        String(text ?? '')
+          .toLowerCase()
+          .includes(needle);
+
+      const sorters = {
+        name: (a, b) => String(a.name ?? '').localeCompare(String(b.name ?? '')),
+        newest: (a, b) =>
+          new Date(b.createdAt ?? 0) - new Date(a.createdAt ?? 0),
+        largest: (a, b) => (b.size ?? 0) - (a.size ?? 0),
+      };
+
+      // Re-renders both lists against the current filter and sort.
+      const apply = () => {
+        const needle = (document.getElementById('filter').value ?? '')
+          .trim()
+          .toLowerCase();
+        const order = document.getElementById('sort').value;
+
+        const archives = loadedArchives
+          .filter(
+            (archive) =>
+              needle === '' ||
+              matches(archive.name, needle) ||
+              matches(archive.infoHash, needle) ||
+              (archive.categories ?? []).some((c) => matches(c, needle)),
+          )
+          .sort(sorters[order] ?? sorters.name);
+
+        const categories = loadedCategories.filter(
+          (entry) =>
+            needle === '' ||
+            matches(entry.category, needle) ||
+            matches(entry.newest?.name, needle),
+        );
+
+        renderCategories(categories);
+        render(archives);
+
+        const count = document.getElementById('count');
+        count.textContent =
+          needle === ''
+            ? `${loadedArchives.length} archives, ${loadedCategories.length} categories`
+            : `${archives.length} of ${loadedArchives.length} archives, ` +
+              `${categories.length} of ${loadedCategories.length} categories`;
+      };
+
       const load = async () => {
         let archives = null;
 
@@ -440,7 +550,9 @@
           }
         }
 
-        render(archives.filter((archive) => archive.infoHash));
+        loadedArchives = archives.filter((archive) => archive.infoHash);
+        document.getElementById('toolbar').hidden = false;
+        apply();
 
         // /latest/ rather than /api/categories: the same list, without a
         // credential. This is the part most visitors actually want -- an
@@ -451,13 +563,17 @@
           const response = await fetch('/latest/');
           if (response.ok) {
             const body = await response.json();
-            renderCategories(body.categories ?? []);
+            loadedCategories = body.categories ?? [];
+            apply();
           }
         } catch {
           // Nothing to say. The archives above are the substance.
         }
       };
 
+      document.getElementById('filter').addEventListener('input', apply);
+      document.getElementById('sort').addEventListener('change', apply);
+
       load();
     </script>
   </body>