wiki-formant 0.28.0 → 0.30.0

package/dist/db.d.ts

@@ -0,0 +1,21 @@
+/** The options `new pg.Pool()` takes, for the fields set here. */
+export interface PgPoolConfig {
+    connectionString: string | undefined;
+    max: number;
+    idleTimeoutMillis: number;
+    connectionTimeoutMillis: number;
+}
+/**
+ * Pool options sized by which Supabase pooler the URL names, because the
+ * ceiling belongs to the pooler and not to the app. Port 6543 is the
+ * TRANSACTION pooler, which exists to hold many short-lived clients; anything
+ * else is treated as the SESSION pooler on 5432, capped at 15 clients per
+ * project and shared with a build's workers, so three each is what fits.
+ *
+ * `pg` reports an exhausted pool as "timeout exceeded when trying to connect",
+ * which reads as a network fault and is not one: connecting takes well under a
+ * second, while an acquire queued behind busy clients waits the full
+ * `connectionTimeoutMillis`. `max: 1` was serial, and three everywhere rendered
+ * a page that fans out more than three queries in thirty seconds.
+ */
+export declare function pgPoolConfig(url: string | undefined): PgPoolConfig;

package/dist/db.js

@@ -0,0 +1,27 @@
+// db.ts — the pool settings every app here hands to `pg`.
+//
+// Four Prisma client modules carried the same block, comment and all. It is a
+// value, not a client: the app still owns `new pg.Pool(...)`, the adapter and
+// the globalThis cache, so this imports nothing.
+/**
+ * Pool options sized by which Supabase pooler the URL names, because the
+ * ceiling belongs to the pooler and not to the app. Port 6543 is the
+ * TRANSACTION pooler, which exists to hold many short-lived clients; anything
+ * else is treated as the SESSION pooler on 5432, capped at 15 clients per
+ * project and shared with a build's workers, so three each is what fits.
+ *
+ * `pg` reports an exhausted pool as "timeout exceeded when trying to connect",
+ * which reads as a network fault and is not one: connecting takes well under a
+ * second, while an acquire queued behind busy clients waits the full
+ * `connectionTimeoutMillis`. `max: 1` was serial, and three everywhere rendered
+ * a page that fans out more than three queries in thirty seconds.
+ */
+export function pgPoolConfig(url) {
+    return {
+        connectionString: url,
+        max: (url ?? '').includes(':6543') ? 10 : 3,
+        idleTimeoutMillis: 20_000,
+        // The acquire timeout, despite the message it fails with.
+        connectionTimeoutMillis: 30_000,
+    };
+}

package/dist/feed.d.ts

@@ -53,7 +53,6 @@ export interface FeedChannel {
  * exist to prevent. An empty feed has no build date rather than a fictional one.
  */
 export declare function renderFeed(channel: FeedChannel, items: readonly FeedItem[]): string;
-export declare const FEED_HEADERS: Record<string, string>;
 /**
  * The feed as a response, with the validators a poller revalidates against.
  *

package/dist/feed.js

@@ -89,7 +89,7 @@ export function renderFeed(channel, items) {
     ].join('\n');
 }
 const lastBuild = (channel, items) => channel.lastBuild ?? items.reduce((max, item) => (!max || item.date > max ? item.date : max), null);
-export const FEED_HEADERS = {
+const FEED_HEADERS = {
     'Content-Type': 'application/rss+xml; charset=utf-8',
     'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
 };

package/dist/freshness.d.ts

@@ -39,8 +39,13 @@ type When = Date | string | number;
  * timestamp formatted in the server's zone, or the browser's, lands on the
  * previous day for half the world, and the server and the hydrating client
  * disagree about which day it is.
+ *
+ * `locale` defaults to `en-US`; `{ locale: 'en-GB', month: 'long' }` reads
+ * `19 September 2026`.
  */
-export declare function formatDay(date: When, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDay(date: When, options?: Intl.DateTimeFormatOptions & {
+    locale?: string;
+}): string;
 /**
  * - `compact`: `now`, `2m`, `3h`, `5d`, `2mo`, `1y` — for dense rows.
  * - `short`: `just now`, `2m ago` … `1y ago`.

package/dist/freshness.js

@@ -60,14 +60,18 @@ const toMs = (d) => (typeof d === 'number' ? d : d instanceof Date ? d.getTime()
  * timestamp formatted in the server's zone, or the browser's, lands on the
  * previous day for half the world, and the server and the hydrating client
  * disagree about which day it is.
+ *
+ * `locale` defaults to `en-US`; `{ locale: 'en-GB', month: 'long' }` reads
+ * `19 September 2026`.
  */
-export function formatDay(date, options) {
-    return new Date(toMs(date)).toLocaleDateString('en-US', {
+export function formatDay(date, options = {}) {
+    const { locale = 'en-US', ...format } = options;
+    return new Date(toMs(date)).toLocaleDateString(locale, {
         year: 'numeric',
         month: 'short',
         day: 'numeric',
         timeZone: 'UTC',
-        ...options,
+        ...format,
     });
 }
 const plural = (n, unit) => `${n} ${unit}${n === 1 ? '' : 's'} ago`;

package/dist/http.d.ts

@@ -123,6 +123,16 @@ export interface CorpusValidators {
     etag: string;
     lastModified: string;
 }
+/**
+ * The validators for an aggregate: the ETag seeded from `seed` (the depth or
+ * scope, then the row count) with the newest stamp appended, and that stamp as
+ * Last-Modified. A corpus with no rows, or stamps all null, dates from the
+ * epoch, so an empty corpus still revalidates rather than throwing.
+ *
+ * Every wiki here wrote this after its `aggregate` call: newest of the `_max`
+ * columns, `?? new Date(0)`, then the same two lines.
+ */
+export declare function corpusValidatorsFrom(seed: ReadonlyArray<string | number | null | undefined>, stamps: ReadonlyArray<Date | null | undefined>): CorpusValidators;
 /**
  * A GET handler serving `build()` under corpus validators — or a 304 instead.
  *

package/dist/http.js

@@ -191,6 +191,19 @@ export function pageLine(opts) {
     const stamp = opts.updated ? isoDate(opts.updated) : '';
     return `- [${opts.title}](${opts.url})${excerpt}${stamp ? ` _(updated ${stamp})_` : ''}`;
 }
+/**
+ * The validators for an aggregate: the ETag seeded from `seed` (the depth or
+ * scope, then the row count) with the newest stamp appended, and that stamp as
+ * Last-Modified. A corpus with no rows, or stamps all null, dates from the
+ * epoch, so an empty corpus still revalidates rather than throwing.
+ *
+ * Every wiki here wrote this after its `aggregate` call: newest of the `_max`
+ * columns, `?? new Date(0)`, then the same two lines.
+ */
+export function corpusValidatorsFrom(seed, stamps) {
+    const newest = stamps.reduce((max, d) => (d instanceof Date && d.getTime() > max.getTime() ? d : max), new Date(0));
+    return { etag: corpusEtag([...seed, newest]), lastModified: newest.toUTCString() };
+}
 /**
  * A GET handler serving `build()` under corpus validators — or a 304 instead.
  *

package/dist/link-check.d.ts

@@ -42,30 +42,6 @@ export declare function probeUrlFor(url: string): string;
  * exactly as a hand re-probe does it.
  */
 export declare function perHost<T>(url: string, fn: () => Promise<T>): Promise<T>;
-/**
- * Probe one URL, honestly.
- *
- * A timeout is not a death and neither is a dropped connection: slow replays —
- * web.archive.org above all, which a sweep leans on to rescue dying citations —
- * exceed the ordinary budget and land as status 0. So a status-0 result with a
- * transient code earns one more attempt on the longer budget before it is
- * reported. A 404 does not: it is an answer.
- */
-export declare function probeUrl(url: string, opts?: ProbeOptions): Promise<Probe>;
-export declare const YOUTUBE_EMBED: RegExp;
-/**
- * A YouTube `/embed/<id>` URL answers 200 for private, deleted and
- * playback-restricted videos alike, so HEADing it can never spot a dead hero
- * video. oEmbed can:
- *
- *   200 → public and embeddable | 404 → deleted | 401/403 → private or embedding off
- */
-export declare function probeYouTube(videoId: string, opts?: ProbeOptions): Promise<{
-    status: number;
-    ok: boolean;
-    reason?: string;
-    error?: string;
-}>;
 /** An external anchor, with a video treated as a video. */
 export declare function probeExternal(url: string, opts?: ProbeOptions): Promise<Probe & {
     videoId?: string;

package/dist/link-check.js

@@ -134,7 +134,7 @@ async function attempt(url, budgetMs) {
  * transient code earns one more attempt on the longer budget before it is
  * reported. A 404 does not: it is an answer.
  */
-export async function probeUrl(url, opts = {}) {
+async function probeUrl(url, opts = {}) {
     const { timeoutMs, slowTimeoutMs } = { ...DEFAULTS, ...opts };
     const target = probeUrlFor(url);
     const first = await perHost(target, () => attempt(target, timeoutMs));
@@ -145,7 +145,7 @@ export async function probeUrl(url, opts = {}) {
     return { ...second, url };
 }
 // ---- YouTube ----------------------------------------------------------------
-export const YOUTUBE_EMBED = /^https?:\/\/(?:www\.)?(?:youtube-nocookie\.com|youtube\.com)\/embed\/([\w-]+)/;
+const YOUTUBE_EMBED = /^https?:\/\/(?:www\.)?(?:youtube-nocookie\.com|youtube\.com)\/embed\/([\w-]+)/;
 /**
  * The same video cited as a LINK rather than an iframe. `youtu.be/<id>` 303s and
  * `youtube.com/watch?v=<id>` 200s for deleted and private videos alike, so an
@@ -160,7 +160,7 @@ const YOUTUBE_WATCH = /^https?:\/\/(?:(?:www\.)?youtube\.com\/(?:watch\?(?:[^#]*
  *
  *   200 → public and embeddable | 404 → deleted | 401/403 → private or embedding off
  */
-export async function probeYouTube(videoId, opts = {}) {
+async function probeYouTube(videoId, opts = {}) {
     const { timeoutMs } = { ...DEFAULTS, ...opts };
     const oembed = `https://www.youtube.com/oembed?url=https%3A//www.youtube.com/watch%3Fv%3D${videoId}&format=json`;
     try {

package/dist/mcp.d.ts

@@ -10,7 +10,7 @@ export declare const MCP_MODERN_VERSIONS: readonly ["2026-07-28"];
  * endpoint speak both, and a legacy client meeting a dual-era server works;
  * going modern-only would fail the handshake of every client in the field.
  */
-export declare const MCP_LEGACY_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+declare const MCP_LEGACY_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
 /**
  * Every version this transport speaks, newest first. It is the `supported` list
  * a `-32022` names and the `supportedVersions` of `server/discover`, so a modern
@@ -239,8 +239,8 @@ export declare const withAdjustments: <T extends object>(args: {
 }, result: T) => T | (T & {
     adjustments: readonly ArgAdjustment[];
 });
-/** One entry in a JSON-RPC envelope. Exported because `wiki-formant/x402`
- *  gates the envelope before `handleMcp` ever sees it. */
+/** One entry in a JSON-RPC envelope. Exported for an `McpServerConfig.gate`,
+ *  which rewrites the envelope before `handleMcp` sees it (acuiq2's x402 gate). */
 export type RpcRequest = {
     jsonrpc: '2.0';
     id: string | number | null;
@@ -250,8 +250,9 @@ export type RpcRequest = {
 /** How many entries one JSON-RPC batch may carry. Quoted by the conformance suite. */
 export declare const DEFAULT_MAX_BATCH = 20;
 /**
- * A tool result envelope. Exported because `x402.ts` builds the same shape when
- * it withholds a paid call, and had grown two more copies of it doing so.
+ * A tool result envelope. Exported for an envelope gate, which builds the same
+ * shape when it withholds a call: acuiq2's x402 gate had grown two more copies
+ * of it doing so.
  */
 export declare const toolText: (id: RpcRequest["id"], text: string, isError?: boolean, extra?: Record<string, unknown>) => {
     jsonrpc: "2.0";

package/dist/mcp.js

@@ -25,7 +25,7 @@ export const MCP_MODERN_VERSIONS = ['2026-07-28'];
  * endpoint speak both, and a legacy client meeting a dual-era server works;
  * going modern-only would fail the handshake of every client in the field.
  */
-export const MCP_LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const MCP_LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 /**
  * Every version this transport speaks, newest first. It is the `supported` list
  * a `-32022` names and the `supportedVersions` of `server/discover`, so a modern
@@ -157,8 +157,9 @@ const rpcError = (id, code, message, data) => ({
     error: { code, message, ...(data ? { data } : {}) },
 });
 /**
- * A tool result envelope. Exported because `x402.ts` builds the same shape when
- * it withholds a paid call, and had grown two more copies of it doing so.
+ * A tool result envelope. Exported for an envelope gate, which builds the same
+ * shape when it withholds a call: acuiq2's x402 gate had grown two more copies
+ * of it doing so.
  */
 export const toolText = (id, text, isError = false, extra = {}) => ({
     jsonrpc: '2.0',

package/dist/passkey-button.d.ts

@@ -0,0 +1,9 @@
+export interface PasskeyButtonProps {
+    /** The route that serves `gate.route`. */
+    endpoint: string;
+    /** The invite token from the link, when there is one. */
+    invite?: string | undefined;
+    className?: string;
+    errorClassName?: string;
+}
+export declare function PasskeyButton({ endpoint, invite, className, errorClassName }: PasskeyButtonProps): import("react").JSX.Element;

package/dist/passkey-button.js

@@ -0,0 +1,36 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// passkey-button.tsx – the browser half of `wiki-formant/passkey`.
+//
+// Its own subpath because it imports `@simplewebauthn/browser`, an optional
+// peer that only an app with a passkey door installs. With an invite it saves a
+// new passkey; without one it signs in with a saved one. Either way, success
+// reloads the page without the invite, and the server sees the new cookie.
+import { startAuthentication, startRegistration } from '@simplewebauthn/browser';
+import { useState } from 'react';
+async function post(endpoint, body) {
+    const res = await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    if (!res.ok)
+        throw new Error((await res.json().catch(() => null))?.error ?? 'Sign-in failed.');
+    return res.status === 204 ? null : res.json();
+}
+export function PasskeyButton({ endpoint, invite, className, errorClassName }) {
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    async function go() {
+        setBusy(true);
+        setError(null);
+        try {
+            const optionsJSON = await post(endpoint, { invite });
+            const response = invite ? await startRegistration({ optionsJSON }) : await startAuthentication({ optionsJSON });
+            await post(endpoint, { invite, response });
+            location.replace(location.pathname + location.search.replace(/([?&])invite=[^&]*&?/, '$1').replace(/[?&]$/, ''));
+        }
+        catch (e) {
+            // A prompt the person closed throws NotAllowedError, which needs no message.
+            setError(e instanceof Error && e.name !== 'NotAllowedError' ? e.message : null);
+            setBusy(false);
+        }
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: go, disabled: busy, children: invite ? 'Save a passkey' : 'Sign in with a passkey' }), error && (_jsx("p", { role: "alert", className: errorClassName, children: error }))] }));
+}

package/dist/passkey.d.ts

@@ -0,0 +1,27 @@
+import type { Sql } from './analytics.js';
+export type { Sql };
+export interface PasskeyGateOptions {
+    sql: Sql;
+    /** The name the browser shows when it offers to save the passkey. */
+    rpName: string;
+    /** Default `passkey_session`. */
+    cookie?: string;
+    /** How long a sign-in lasts. Default 90 days. */
+    sessionDays?: number;
+}
+export interface PasskeyGate {
+    /** The session cookie's name, for the app to read it with. */
+    cookie: string;
+    /** Whether a session cookie's value is a live session. */
+    signedIn(session: string | undefined): Promise<boolean>;
+    /** A single-use invite token, good for `days`. The bin turns it into a link. */
+    invite(days?: number): Promise<string>;
+    /**
+     * The whole sign-in route: `export const POST = gate.route`. The body is
+     * `{ invite?, response? }`: without `response` it answers with the options
+     * for the browser's prompt, with one it verifies it and sets the cookie. An
+     * invite turns the prompt into saving a new passkey.
+     */
+    route(request: Request): Promise<Response>;
+}
+export declare function createPasskeyGate({ sql, rpName, cookie, sessionDays }: PasskeyGateOptions): PasskeyGate;

package/dist/passkey.js

@@ -0,0 +1,130 @@
+// passkey.ts – the door to a site's own admin pages: a passkey, and nothing else.
+//
+// No account, no password, no email. Whoever holds a passkey saved for the
+// site is in. The first one is saved from an invite link that the
+// `passkey-invite` bin prints from a machine holding the database URL, and any
+// passkey after that comes from another invite. So the only way in is through
+// someone who can already reach the database.
+//
+// A passkey is bound to the host it was saved on. One saved on localhost does
+// not open the deployed site, and one saved on the site does not open localhost.
+//
+// Like analytics, the package owns the SQL and the app owns the connection. The
+// app declares the two tables in its own schema:
+//
+//   model Passkey {
+//     id         String   @id // the credential id, base64url
+//     publicKey  String       // base64url
+//     counter    Int
+//     transports String[]
+//     createdAt  DateTime @default(now()) @db.Timestamptz(3)
+//   }
+//
+//   model PasskeyToken {
+//     hash      String   @id // sha-256 of the token, base64url
+//     kind      String       // session | invite | challenge
+//     expiresAt DateTime @db.Timestamptz(3)
+//   }
+//
+// Every token is stored as its hash, so a read of the table opens nothing. A
+// challenge is spent the moment a response quotes it, and an invite the moment
+// a passkey is saved with it.
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse, } from '@simplewebauthn/server';
+import { clientKey, rateLimit, rateLimitedResponse } from './rate-limit.js';
+const MINUTE = 60_000;
+const DAY = 86_400_000;
+const CHALLENGE_MS = 5 * MINUTE;
+const b64url = (bytes) => Buffer.from(bytes).toString('base64url');
+const token = () => b64url(crypto.getRandomValues(new Uint8Array(32)));
+const hash = async (value) => b64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value))));
+/** Store a token's hash; the token is returned and kept nowhere else. */
+async function issue(sql, kind, ms, value = token()) {
+    await sql(`DELETE FROM "PasskeyToken" WHERE "expiresAt" < now()`);
+    await sql(`INSERT INTO "PasskeyToken" (hash, kind, "expiresAt") VALUES ($1, $2, now() + make_interval(secs => $3::int))`, await hash(value), kind, Math.round(ms / 1000));
+    return value;
+}
+/** True once for a live token of this kind; it is gone either way. */
+async function spend(sql, kind, value) {
+    const rows = (await sql(`DELETE FROM "PasskeyToken" WHERE hash = $1 AND kind = $2 RETURNING "expiresAt" > now() AS live`, await hash(value), kind));
+    return rows[0]?.live === true;
+}
+async function live(sql, kind, value) {
+    const rows = (await sql(`SELECT 1 FROM "PasskeyToken" WHERE hash = $1 AND kind = $2 AND "expiresAt" > now()`, await hash(value), kind));
+    return rows.length > 0;
+}
+/** Any request that fails is told only that it failed. */
+const refuse = (status, error) => Response.json({ error }, { status });
+export function createPasskeyGate({ sql, rpName, cookie = 'passkey_session', sessionDays = 90 }) {
+    async function session(secure) {
+        const value = await issue(sql, 'session', sessionDays * DAY);
+        const attrs = [`${cookie}=${value}`, 'Path=/', 'HttpOnly', 'SameSite=Lax', `Max-Age=${sessionDays * 86_400}`];
+        if (secure)
+            attrs.push('Secure');
+        return new Response(null, { status: 204, headers: { 'set-cookie': attrs.join('; ') } });
+    }
+    return {
+        cookie,
+        signedIn: async (value) => !!value && live(sql, 'session', value),
+        invite: (days = 1) => issue(sql, 'invite', days * DAY),
+        async route(request) {
+            const limited = rateLimit(clientKey('passkey', request.headers), { capacity: 10, refillPerSec: 0.2 });
+            if (!limited.ok)
+                return rateLimitedResponse(limited.retryAfterSec);
+            // The browser writes the page's origin into what it signs, and binds the
+            // passkey to the host, so the request's own origin is the one to expect.
+            const { origin, hostname: rpID, protocol } = new URL(request.url);
+            const body = (await request.json().catch(() => null));
+            const invite = typeof body?.invite === 'string' ? body.invite : undefined;
+            const response = body?.response;
+            const expectedChallenge = (challenge) => spend(sql, 'challenge', challenge);
+            if (!response) {
+                if (invite && !(await live(sql, 'invite', invite)))
+                    return refuse(403, 'This invite has expired.');
+                const options = invite
+                    ? await generateRegistrationOptions({
+                        rpName,
+                        rpID,
+                        userName: rpName,
+                        attestationType: 'none',
+                        // Discoverable, so signing in later asks for nothing: the device offers it.
+                        authenticatorSelection: { residentKey: 'required', userVerification: 'preferred' },
+                    })
+                    : await generateAuthenticationOptions({ rpID, userVerification: 'preferred' });
+                await issue(sql, 'challenge', CHALLENGE_MS, options.challenge);
+                return Response.json(options);
+            }
+            if (invite) {
+                const result = await verifyRegistrationResponse({
+                    response,
+                    expectedChallenge,
+                    expectedOrigin: origin,
+                    expectedRPID: rpID,
+                    requireUserVerification: false,
+                }).catch(() => null);
+                if (!result?.verified)
+                    return refuse(400, 'That passkey could not be saved.');
+                // Spent after the check, so a failed prompt leaves the invite to try again.
+                if (!(await spend(sql, 'invite', invite)))
+                    return refuse(403, 'This invite has expired.');
+                const { credential } = result.registrationInfo;
+                await sql(`INSERT INTO "Passkey" (id, "publicKey", counter, transports) VALUES ($1, $2, $3, $4::text[])`, credential.id, b64url(credential.publicKey), credential.counter, credential.transports ?? []);
+                return session(protocol === 'https:');
+            }
+            const [passkey] = (await sql(`SELECT id, "publicKey", counter, transports FROM "Passkey" WHERE id = $1`, String(response.id)));
+            if (!passkey)
+                return refuse(403, 'This passkey is not one this site knows.');
+            const result = await verifyAuthenticationResponse({
+                response,
+                expectedChallenge,
+                expectedOrigin: origin,
+                expectedRPID: rpID,
+                credential: { ...passkey, publicKey: new Uint8Array(Buffer.from(passkey.publicKey, 'base64url')) },
+                requireUserVerification: false,
+            }).catch(() => null);
+            if (!result?.verified)
+                return refuse(403, 'Sign-in failed.');
+            await sql(`UPDATE "Passkey" SET counter = $2 WHERE id = $1`, passkey.id, result.authenticationInfo.newCounter);
+            return session(protocol === 'https:');
+        },
+    };
+}

package/dist/rate-limit.d.ts

@@ -3,19 +3,38 @@ export interface RateLimitOptions {
     capacity: number;
     /** Tokens added per second: the sustained rate. */
     refillPerSec: number;
+    /**
+     * Running dry blocks `blockKey` outright for this long, rather than letting
+     * the bucket refill a token at a time. For a caller already established as
+     * abusive, the trickle the refill allows is the wrong answer.
+     */
+    blockMs?: number;
+    /**
+     * What a block shuts out. Default the bucket's own key; pass the bare
+     * address (`rest:1.2.3.4`) to lock a caller out of every endpoint that names
+     * the same `blockKey` once it blows one endpoint's budget.
+     */
+    blockKey?: string;
 }
 export type RateLimitResult = {
     ok: true;
     remaining: number;
-} | {
+}
+/** `blocked` is true when an earlier block refused the call, rather than this one's bucket. */
+ | {
     ok: false;
     retryAfterSec: number;
+    blocked?: boolean;
 };
 /**
  * Spend one token against `key`.
  *
  * Keys are namespaced by the caller (`"mcp:1.2.3.4"`, `"write:page:17"`), so
  * one map backs every limiter in a process without them colliding.
+ *
+ * With `blockMs`, a block on `blockKey` is checked before any token is spent,
+ * and running the bucket dry starts one; the refusal then states the block's
+ * length as its wait.
  */
 export declare function rateLimit(key: string, opts: RateLimitOptions): RateLimitResult;
 /** Anything with a header getter: a `Request`'s headers, or Next's `headers()`. */
@@ -23,7 +42,14 @@ export interface HeaderReader {
     get(name: string): string | null | undefined;
 }
 /**
- * The caller's address, from the proxy header the edge sets.
+ * The caller's address, from the header the edge sets.
+ *
+ * `x-real-ip` first: Vercel sets it to the connecting client and overwrites any
+ * inbound copy, so a client cannot choose it. The leftmost `x-forwarded-for`
+ * entry is only as trustworthy as every proxy in front of the app — one that
+ * appends rather than replaces hands the client the first slot, and with it a
+ * fresh bucket and a fresh visitor per request. It stays as the fallback for a
+ * host that sets no `x-real-ip`.
  *
  * Falls back to a single shared bucket rather than to per-caller buckets, so an
  * unidentifiable caller is still limited — collectively, but limited. Keying on

package/dist/rate-limit.js

@@ -14,14 +14,53 @@
 const buckets = new Map();
 /** Bounds memory under high-cardinality keying — one bucket per attacker IP. */
 const MAX_KEYS = 10_000;
+/**
+ * Blocks, held as an expiry timestamp rather than a setTimeout: a pending timer
+ * keeps a serverless instance's event loop alive for no reason.
+ */
+const blocks = new Map();
+/** Seconds left on a block, or 0. An expired block is dropped on the way past. */
+function blockedFor(key, now) {
+    const until = blocks.get(key);
+    if (until === undefined)
+        return 0;
+    if (now < until)
+        return Math.ceil((until - now) / 1000);
+    blocks.delete(key);
+    return 0;
+}
+function block(key, until, now) {
+    if (blocks.size >= MAX_KEYS) {
+        for (const [k, expiry] of blocks)
+            if (expiry <= now)
+                blocks.delete(k);
+        // Still full of live blocks: the oldest goes, as with buckets.
+        if (blocks.size >= MAX_KEYS) {
+            const oldest = blocks.keys().next().value;
+            if (oldest !== undefined)
+                blocks.delete(oldest);
+        }
+    }
+    blocks.set(key, until);
+}
 /**
  * Spend one token against `key`.
  *
  * Keys are namespaced by the caller (`"mcp:1.2.3.4"`, `"write:page:17"`), so
  * one map backs every limiter in a process without them colliding.
+ *
+ * With `blockMs`, a block on `blockKey` is checked before any token is spent,
+ * and running the bucket dry starts one; the refusal then states the block's
+ * length as its wait.
  */
 export function rateLimit(key, opts) {
     const now = Date.now();
+    const blockKey = opts.blockKey ?? key;
+    if (opts.blockMs) {
+        const blockedSec = blockedFor(blockKey, now);
+        if (blockedSec)
+            return { ok: false, retryAfterSec: blockedSec, blocked: true };
+    }
     const existing = buckets.get(key);
     if (!existing && buckets.size >= MAX_KEYS) {
         // Map iteration is insertion-ordered, so this evicts the oldest key.
@@ -35,13 +74,24 @@ export function rateLimit(key, opts) {
     bucket.updatedAt = now;
     buckets.set(key, bucket);
     if (bucket.tokens < 1) {
+        if (opts.blockMs) {
+            block(blockKey, now + opts.blockMs, now);
+            return { ok: false, retryAfterSec: Math.ceil(opts.blockMs / 1000) };
+        }
         return { ok: false, retryAfterSec: Math.ceil((1 - bucket.tokens) / opts.refillPerSec) };
     }
     bucket.tokens -= 1;
     return { ok: true, remaining: Math.floor(bucket.tokens) };
 }
 /**
- * The caller's address, from the proxy header the edge sets.
+ * The caller's address, from the header the edge sets.
+ *
+ * `x-real-ip` first: Vercel sets it to the connecting client and overwrites any
+ * inbound copy, so a client cannot choose it. The leftmost `x-forwarded-for`
+ * entry is only as trustworthy as every proxy in front of the app — one that
+ * appends rather than replaces hands the client the first slot, and with it a
+ * fresh bucket and a fresh visitor per request. It stays as the fallback for a
+ * host that sets no `x-real-ip`.
  *
  * Falls back to a single shared bucket rather than to per-caller buckets, so an
  * unidentifiable caller is still limited — collectively, but limited. Keying on
@@ -50,8 +100,9 @@ export function rateLimit(key, opts) {
  * meant to catch.
  */
 export function clientIp(headers) {
-    const forwarded = headers.get('x-forwarded-for');
-    return forwarded?.split(',')[0]?.trim() || headers.get('x-real-ip')?.trim() || 'anon';
+    return (headers.get('x-real-ip')?.trim() ||
+        headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+        'anon');
 }
 /** `prefix:ip` — the key `rateLimit` expects for a per-IP gate. */
 export function clientKey(prefix, headers) {
@@ -109,6 +160,7 @@ export function withRateLimit(res, result, opts) {
 /** Test seam: the bucket map is module state and outlives a single test. */
 export function resetRateLimits() {
     buckets.clear();
+    blocks.clear();
 }
 // ---- the MCP budget ---------------------------------------------------------
 /**

package/dist/react-server.d.ts

@@ -1,6 +1,7 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { Control, FacetControlGroup, MetadataRow } from './taxonomy.js';
 import type { HistoryChange } from './history.js';
+import type { Digest } from './analytics.js';
 /**
  * The shape a router's link component has to satisfy here.
  *
@@ -267,3 +268,22 @@ export interface RevisionChangesProps {
  * are the importing stylesheet's.
  */
 export declare function RevisionChanges({ changes, label }: RevisionChangesProps): import("react").JSX.Element | null;
+export interface StatsProps {
+    /** One window's figures, from `digest` in `wiki-formant/analytics`. */
+    digest: Digest;
+    /** The window the digest covers, in days. */
+    days: number;
+    /** The windows offered as `?days=` links on the same page. */
+    ranges?: readonly number[];
+}
+/** The windows the stats page offers, in days. */
+export declare const STATS_RANGES: readonly [1, 7, 30, 90];
+/** A `?days=` value as one of `ranges`, else `fallback`: the page's only input. */
+export declare const statsDays: (param: unknown, ranges?: readonly number[], fallback?: number) => number;
+/**
+ * A site's own analytics on one page: the headline figures against the window
+ * before, visitors per day, and every ranked list the digest carries. Lists
+ * with nothing in them are left out. Bars are `currentColor` until the
+ * importing stylesheet gives them a colour.
+ */
+export declare function Stats({ digest: d, days, ranges }: StatsProps): import("react").JSX.Element;