wiki-formant 0.28.0 → 0.30.0

package/README.md

@@ -148,7 +148,7 @@ handler: async (args, ctx) => {
 }
 ```
 
-`config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope.
+`config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope. `RpcRequest` and `toolText` are exported for a gate to build with; acuiq2's x402 gate is the one that does.
 
 ### Tool arguments and the corpus tool
 
@@ -213,6 +213,13 @@ export async function GET(request: Request) {
 }
 ```
 
+`corpusValidatorsFrom(seed, stamps)` is that pair from an aggregate: the newest of `stamps` (the epoch when every one is null), appended to `seed` for the tag. `corpusRoute(validators, build)` is the whole handler, and skips the build on a 304.
+
+```ts
+const agg = await prisma.page.aggregate({ _count: true, _max: { updatedAt: true } });
+corpusValidatorsFrom([depth, agg._count], [agg._max.updatedAt]);
+```
+
 ## Pagination and versioning
 
 `parsePagination` clamps `page ≥ 1` and `pageSize` to 1–100; `paginatedResponse` always carries `totalPages`. Reshaping that response is a breaking change to every client that pages, which is why it lives here rather than being re-typed per repo.
@@ -311,14 +318,6 @@ import Link from 'next/link';
 
 There is no `next` peer dependency here and there is not going to be one, but a rail that falls back to a bare `<a>` turns every press into a full page load — which is the whole reason a wiki has a persistent rail. So the router arrives through the door.
 
-## Payment gating
-
-`wiki-formant/x402` gates an MCP envelope on payment, for a wiki that charges for a bulk export over HTTP and would otherwise hand the same bytes over free through the equivalent MCP tool. Payment travels in-band — `params._meta["x402/payment"]` in, `result._meta["x402/payment-response"]` out — because one HTTP 402 cannot answer a batch of twenty in which one call is priced and nineteen are not.
-
-`gatePaidCalls` returns what `handleMcp` should dispatch and a `finish` that puts the answer back together. The ordering is the part worth owning once: verify before dispatch, settle only after a non-error answer, splice the challenges back into the caller's original order. A tool that raises cancels rather than settles — the caller pays for an answer, not an attempt.
-
-It imports nothing. `@x402/core`, `@x402/evm`, `@x402/extensions`, `@x402/next` and `viem` are optional peers, and the resource server arrives as a structural port instead of an import, so a wiki that never imports this subpath never resolves any of them. Which surfaces cost what, the prices and the terms text stay with the caller: those are policy, and this is the envelope surgery.
-
 ## AI crawlers
 
 Every wiki kept this roster twice — once in the proxy, keyed by user-agent, to
@@ -490,6 +489,27 @@ leafBlocks(blocks, BLOCK_SHAPE.containers);
 
 The dispatch over a repo's own block union stays in that repo; the bodies come from here. `wiki-formant/text` has a prose body for every core leaf — `statsToText`, `linkGridToText` and `pageListToText` joined the originals when two of the three wikis turned out to extract nothing from them, so their MCP `get_page` answered a hub page as nearly empty.
 
+The core leaves — `content`, `codeTabs`, `banner`, `references`, `stats`, `linkGrid`, `recentPages`, `pageList` — had the same case bodies in every wiki's text export, markdown twin, validator and new-block record. A repo's switch hands those cases over and keeps its own, so it stays exhaustive over its union:
+
+```ts
+import { coreAtomicText, coreAtomicToMarkdown, coreBlockDefaults } from 'wiki-formant/blocks';
+import { coreAtomicValidator } from 'wiki-formant/validation';
+
+switch (block.type) {
+  case 'content': case 'codeTabs': case 'banner': case 'references':
+  case 'stats': case 'linkGrid': case 'recentPages': case 'pageList':
+    return coreAtomicToMarkdown(block, { siteUrl: SITE_URL, referencesTitle: 'Sources' });
+  case 'corpusStats':
+    return block.resolvedHtml ? htmlToMarkdown(block.resolvedHtml) : '';
+}
+
+const BLOCK_DEFAULTS = { ...coreBlockDefaults({ stats }), daoTimeline: () => ({ type: 'daoTimeline', limit: 25 }) };
+const core = coreAtomicValidator({ pageId: id => /^\d{1,9}$/.test(id) });
+// validateAtomic: b => { switch (b.type) { case 'daoTimeline': …; default: return core(b); } }
+```
+
+`coreAtomicToMarkdown` joins a resolved page's site-relative `href` to `siteUrl`, because a twin is read off-site; a wiki whose lists hold its own page rows keeps those two cases. `coreAtomicValidator` caps `recentPages.limit` and `pageIds` at `MAX_BLOCK_ROWS`, a whole number of rows, because both end in a database `take:`; `blockLimit` is the same bound on the read side.
+
 `createBlockValidator` returns `blockIssues` beside the boolean validators: the same walk, reporting where each failure is.
 
 ```ts
@@ -504,7 +524,7 @@ A `codeTabs` tab's `code` is source text in every wiki here, and every view trea
 
 ## Dates
 
-`relativeTime(then, now, { style })` is `compact` (`3h`), `short` (`3h ago`) or `long` (`3 days ago`, day-grained for pages cached for hours), with `absoluteAfterDays` to hand over to the date itself. `now` is always passed in, never read, so a server render and its hydration agree. `formatDay` is always UTC: a stored day formatted in the server's zone, or the browser's, is the previous day for half the world. Both are in `wiki-formant/freshness`, with `isoDate`.
+`relativeTime(then, now, { style })` is `compact` (`3h`), `short` (`3h ago`) or `long` (`3 days ago`, day-grained for pages cached for hours), with `absoluteAfterDays` to hand over to the date itself. `now` is always passed in, never read, so a server render and its hydration agree. `formatDay` is always UTC: a stored day formatted in the server's zone, or the browser's, is the previous day for half the world. It reads `en-US` unless given a `locale`: `formatDay(day, { locale: 'en-GB', month: 'long' })` is `19 September 2026`. Both are in `wiki-formant/freshness`, with `isoDate`.
 
 ## Sanitising stored HTML
 
@@ -562,21 +582,32 @@ top of `src/analytics.ts`.
 
 ```ts
 // src/lib/track.ts
-export const sql: Sql = (query, ...values) => prisma.$queryRawUnsafe(query, ...values);
+const sql: Sql = (query, ...values) => prisma.$queryRawUnsafe(query, ...values);
+export const { trackEvent, trackMcpCall, trackSearch, viewRoute } =
+  createTracker({ sql, defer: after, siteUrl: SITE_URL });
 
 // src/app/api/view/route.ts – the whole beacon route
-export const POST = (request: Request) => collect(request, { sql, defer: after });
+export const POST = viewRoute();
 
 // the root layout, once
 <Beacon />
 ```
 
+`createTracker` records only on a Vercel production deployment unless told
+otherwise (`enabled`), because dev and previews write to production's
+database. `trackMcpCall(request, body, server?)` fits `McpServerConfig.onCall`;
+`trackSearch(headers, query, results, surface?)` takes the headers or Next's
+`headers` itself, which it reads inside the deferred write. `viewRoute({ site })`
+passes a site resolver to `collect`. The module that builds the tracker
+imports the app's database client, so a proxy reaches it through a dynamic
+`import()` inside `event.waitUntil`, never a static one.
+
 `<Beacon>` (`wiki-formant/react`) sends a view each time the path changes,
 client-side moves included, and a click on a link to another host as an
 "Outbound Link: Click" event; `track(name, props)` (`wiki-formant/dom`) sends
-any other browser event. Server code calls `recordEvent` and leaves the
-deferral to the framework, so this package keeps its zero-dependency
-guarantee:
+any other browser event. Underneath the tracker, server code calls
+`recordEvent` and leaves the deferral to the framework, so this package keeps
+its zero-dependency guarantee:
 
 ```ts
 const props = searchQueryProps({ query, results: rows.length, surface: 'wiki' });
@@ -601,9 +632,44 @@ leaves a wiki able to say what every crawler asked for and nothing about what
 its readers asked for. The queries that return zero rows are the valuable ones
 – they name a gap in the corpus in the reader's own words.
 
+## Passkeys and the stats page
+
+`wiki-formant/passkey` is the door to a site's own admin pages: a passkey and
+nothing else, no account, password or email. `createPasskeyGate({ sql, rpName })`
+returns the whole of it. `gate.route` is the sign-in route,
+`gate.signedIn(cookieValue)` is the check a page makes, and `gate.cookie` is the
+cookie's name. The two tables (`Passkey`, `PasskeyToken`) are stated as Prisma
+models at the top of `src/passkey.ts`, and every token is kept only as its hash.
+`@simplewebauthn/server` is an optional peer.
+
+There is no sign-up. The first passkey is saved from a single-use link that the
+`passkey-invite` bin prints from a machine holding `DATABASE_URL`, 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, so localhost needs its own.
+
+```ts
+// src/lib/admin.ts
+export const gate = createPasskeyGate({ sql, rpName: 'Caper' });
+
+// src/app/api/passkey/route.ts
+export const POST = gate.route;
+
+// src/app/stats/page.tsx
+if (!(await gate.signedIn((await cookies()).get(gate.cookie)?.value)))
+  return <PasskeyButton endpoint="/api/passkey" invite={invite} />;
+const days = statsDays((await searchParams).days); // 1, 7, 30 or 90, else 30
+return <Stats digest={await digest(sql, { days })} days={days} />;
+```
+
+`PasskeyButton` (`wiki-formant/passkey-button`) is the browser half and has its
+own subpath, because it imports the optional peer `@simplewebauthn/browser`.
+`Stats` (`wiki-formant/react-server`) renders a `digest` as one page: the
+headline figures against the window before, visitors per day, every non-empty
+ranked list, and `?days=` links between windows. It ships no JavaScript.
+
 ## Base stylesheet
 
-`wiki-formant/base.css` is the layout the package's markup does not work without, and nothing else: columns that stack until there is room, stored tab panels that show one at a time, a copy button pinned to its block's corner and visible on focus and on touch, a stored table's scroll box, and the `aria-sort` arrow as a mask over `currentColor`. No colour and no scale, so a design system's own rules override it at equal specificity.
+`wiki-formant/base.css` is the layout the package's markup does not work without, and nothing else: columns that stack until there is room, stored tab panels that show one at a time, a copy button pinned to its block's corner and visible on focus and on touch, a stored table's scroll box, the `aria-sort` arrow as a mask over `currentColor`, and the stats page's grid and bars. No colour and no scale, so a design system's own rules override it at equal specificity.
 
 ```css
 @import "wiki-formant/base.css" layer(components);
@@ -613,15 +679,23 @@ No view emits a Tailwind utility any more — `ColumnsView` states its gap and a
 
 ## API
 
-Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on.
-The emitted `.d.ts` files are the reference. There is no hand-maintained symbol list
-here, because the one that used to be here drifted from them.
+Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on —
+and there is no root export: `import … from 'wiki-formant'` does not resolve. A
+barrel loads every module it names for the one symbol a route wanted, and had
+already re-exported one module twice. The emitted `.d.ts` files are the reference.
+There is no hand-maintained symbol list here, because the one that used to be here
+drifted from them.
 
-The package root re-exports the runtime modules that need no peer dependency and no
-client boundary, so `import … from 'wiki-formant'` stays importable from a route
-handler with nothing else installed. Everything that reaches for React, a browser
-global, tiptap or a wallet — and the tooling modules, which no route imports — is
-subpath-only.
+`wiki-formant/db` holds `pgPoolConfig(url)`, the options every app here hands to
+`new pg.Pool()`: ten clients on Supabase's 6543 transaction pooler, three on the
+5432 session pooler, whose fifteen-client cap a build's workers share.
+
+`rateLimit` takes `blockMs` (and a `blockKey`, default the bucket's own) for a
+caller already shown to be abusive: running dry blocks the key outright for that
+long, across every bucket that names it, rather than letting the refill trickle
+one token through at a time. `clientIp` reads `x-real-ip` first — Vercel sets it
+and overwrites any inbound copy — and the leftmost `x-forwarded-for` only where no
+`x-real-ip` was set, since a proxy that appends hands the client that slot.
 
 ## A bin
 
@@ -641,6 +715,12 @@ npx analytics-digest --days 30 --handle radixwiki --siblings caper.network,acuiq
 npx analytics-digest --days 7 --gap "Symptom Miss:term"   # adds an event to the search gaps
 ```
 
+`passkey-invite` prints a single-use link that saves a passkey for the page it names, good for a day (`--days n` for longer). Run it the same way:
+
+```sh
+npx passkey-invite https://caper.network/stats
+```
+
 ## Licence
 
 MIT.

package/bin/passkey-invite.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// bin/passkey-invite.mjs – print a single-use link that saves a passkey for a
+// site's admin pages (`wiki-formant/passkey`). The first passkey can only come
+// from here, so the only way in is through someone who holds the database URL.
+//
+// Run from the app's root, where `pg` is installed and `.env` holds
+// DATABASE_URL (read from the environment first). The link is good for a day.
+//
+//   npx passkey-invite https://caper.network/stats
+//   npx passkey-invite http://localhost:3000/stats --days 7
+import pg from 'pg';
+import { createPasskeyGate } from '../dist/passkey.js';
+
+const args = process.argv.slice(2);
+const page = args.find(a => /^https?:\/\//.test(a));
+const days = Number(args[args.indexOf('--days') + 1] ?? 1);
+
+if (!page) {
+  console.error('usage: passkey-invite <page url> [--days n]');
+  process.exit(1);
+}
+if (!process.env.DATABASE_URL) {
+  try {
+    process.loadEnvFile('.env');
+  } catch {
+    // reported below
+  }
+}
+if (!process.env.DATABASE_URL) {
+  console.error('no DATABASE_URL in the environment or ./.env');
+  process.exit(1);
+}
+
+const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
+try {
+  await client.connect();
+  const sql = (query, ...values) => client.query(query, values).then(r => r.rows);
+  const url = new URL(page);
+  url.searchParams.set('invite', await createPasskeyGate({ sql, rpName: '' }).invite(args.includes('--days') ? days : 1));
+  console.log(url.href);
+} finally {
+  await client.end().catch(() => {});
+}

package/dist/analytics.d.ts

@@ -4,8 +4,6 @@ import { type HeaderReader, type RateLimitOptions } from './rate-limit.js';
  * Prisma: `(query, ...values) => prisma.$queryRawUnsafe(query, ...values)`.
  */
 export type Sql = (query: string, ...values: unknown[]) => Promise<unknown>;
-/** Long enough to compare a month with the same month a year before. */
-export declare const KEEP_DAYS = 400;
 /** iPadOS reports itself as a Mac, so its views count as a computer's. */
 export declare const deviceOf: (ua: string) => "phone" | "tablet" | "computer";
 /**
@@ -151,4 +149,56 @@ export interface SearchQueryInput {
  * keeps the prop and the query that produced it the same string.
  */
 export declare function searchQueryProps({ query, results, surface, }: SearchQueryInput): Record<string, string> | null;
+export interface TrackerOptions {
+    sql: Sql;
+    /** `after` in Next: the write runs once the response has gone. */
+    defer: (task: () => Promise<unknown>) => void;
+    /**
+     * Whether anything is recorded. Default: only on a Vercel production
+     * deployment, because dev and previews write to production's database.
+     */
+    enabled?: boolean;
+    /** Where an event with no page of its own is filed: a search with no referer. Default `/`. */
+    siteUrl?: string;
+}
+/** Headers in hand, or a reader for them run inside the deferred write: Next's `headers`. */
+export type HeaderSource = HeaderReader | (() => HeaderReader | Promise<HeaderReader>);
+export interface Tracker {
+    /**
+     * Record one event. `headers` are the request of whoever caused it, so the
+     * event joins their visitor, an agent's included; omit them for an event no
+     * visitor caused. Never rejects, and the caller defers it: `event.waitUntil`
+     * in a proxy, `after` in a route.
+     */
+    trackEvent(name: string, url: string, props: Record<string, string | number>, headers?: HeaderReader): Promise<void>;
+    /**
+     * An "MCP Call" event, deferred. The signature is `McpServerConfig.onCall`'s
+     * plus a server name, so a one-server site passes it as `onCall` as it is.
+     */
+    trackMcpCall(request: Request, body: unknown, server?: string): void;
+    /**
+     * A "Search Query" event, deferred, filed against the page the reader
+     * searched from. A function for `headers` is called inside the deferred
+     * write, and a failure there drops the event rather than the response.
+     */
+    trackSearch(headers: HeaderSource, query: string, results: number, surface?: string): void;
+    /**
+     * The beacon route: `export const POST = tracker.viewRoute()`. `site` is
+     * `collect`'s resolver, for an app that serves many sites or drops a path.
+     */
+    viewRoute(opts?: Pick<CollectOptions, 'site' | 'rateLimit'>): (request: Request) => Promise<Response>;
+}
+/**
+ * Everything an app's `track.ts` had written around the functions above: the
+ * production gate, the deferral and the three named events. Four apps carried
+ * it, two with a search signature of their own.
+ *
+ * The tracker holds `sql`, so the module that builds it imports the app's
+ * database client. A proxy must keep reaching it through a dynamic import
+ * inside `waitUntil`, never a static one, or every request the proxy sees
+ * loads Prisma:
+ *
+ *   event.waitUntil(import('@/lib/track').then(m => m.trackEvent('AI Bot Visit', url, { bot }, request.headers)));
+ */
+export declare function createTracker({ sql, defer, enabled, siteUrl, }: TrackerOptions): Tracker;
 export {};

package/dist/analytics.js

@@ -54,7 +54,7 @@
 // runs anywhere Node 20, a browser or an edge runtime does.
 import { clientIp, clientKey, rateLimit } from './rate-limit.js';
 /** Long enough to compare a month with the same month a year before. */
-export const KEEP_DAYS = 400;
+const KEEP_DAYS = 400;
 const DAY_MS = 86_400_000;
 /** A script that runs a page's JavaScript and says what it is. */
 const BOT = /bot|crawl|spider|slurp|headless|lighthouse|prerender|preview/i;
@@ -264,3 +264,47 @@ export function searchQueryProps({ query, results, surface, }) {
         ...(surface ? { surface } : {}),
     };
 }
+/**
+ * Everything an app's `track.ts` had written around the functions above: the
+ * production gate, the deferral and the three named events. Four apps carried
+ * it, two with a search signature of their own.
+ *
+ * The tracker holds `sql`, so the module that builds it imports the app's
+ * database client. A proxy must keep reaching it through a dynamic import
+ * inside `waitUntil`, never a static one, or every request the proxy sees
+ * loads Prisma:
+ *
+ *   event.waitUntil(import('@/lib/track').then(m => m.trackEvent('AI Bot Visit', url, { bot }, request.headers)));
+ */
+export function createTracker({ sql, defer, enabled = typeof process !== 'undefined' && process.env.VERCEL_ENV === 'production', siteUrl = '/', }) {
+    const trackEvent = (name, url, props, headers) => enabled ? recordEvent(sql, { name, url, props, headers }) : Promise.resolve();
+    return {
+        trackEvent,
+        trackMcpCall(request, body, server) {
+            if (!enabled)
+                return;
+            const props = mcpCallProps(request, body, server);
+            const { url, headers } = request;
+            defer(() => trackEvent('MCP Call', url, props, headers));
+        },
+        trackSearch(source, query, results, surface) {
+            if (!enabled)
+                return;
+            const props = searchQueryProps({ query, results, surface });
+            if (!props)
+                return;
+            defer(async () => {
+                try {
+                    const headers = typeof source === 'function' ? await source() : source;
+                    await trackEvent('Search Query', headers.get('referer') || siteUrl, props, headers);
+                }
+                catch {
+                    // A context with no readable headers loses the event, never the response.
+                }
+            });
+        },
+        viewRoute(opts = {}) {
+            return async (request) => enabled ? collect(request, { sql, defer, ...opts }) : new Response(null, { status: 204 });
+        },
+    };
+}

package/dist/base.css

@@ -116,3 +116,57 @@ pre:hover > .code-copy-btn,
   list-style: none;
 }
 .revision-diff { margin: 0.25em 0 0; }
+
+/* ---- Stats ----------------------------------------------------------------
+   `--share` is a row's value over the largest in its list, 0 to 1. Bars take
+   `currentColor` so they show before a stylesheet colours them. */
+.stats { display: grid; gap: 2rem; }
+.stats-ranges { display: flex; flex-wrap: wrap; gap: 1rem; }
+.stats-ranges a[aria-current] { text-decoration: underline; text-underline-offset: 0.3em; }
+.stats-figures {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
+  gap: 1rem;
+  margin: 0;
+}
+.stats-figures dd { margin: 0; font-variant-numeric: tabular-nums; }
+.stats-chart {
+  display: flex;
+  align-items: flex-end;
+  gap: 2px;
+  height: 8rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.stats-chart li {
+  flex: 1;
+  height: calc(var(--share) * 100%);
+  min-height: 1px;
+  background: currentColor;
+  opacity: 0.4;
+}
+.stats-lists {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
+  gap: 2rem;
+}
+.stats-list ol { display: grid; gap: 2px; margin: 0; padding: 0; list-style: none; }
+.stats-list li {
+  position: relative;
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.25em 0.5em;
+}
+.stats-list li::before {
+  content: '';
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: calc(var(--share) * 100%);
+  background: currentColor;
+  opacity: 0.08;
+  pointer-events: none;
+}
+.stats-list li > span:first-child { min-width: 0; overflow-wrap: anywhere; }
+.stats-count { font-variant-numeric: tabular-nums; }

package/dist/blocks.d.ts

@@ -147,3 +147,142 @@ export declare function statsToMarkdown(items: readonly StatItem[]): string;
 export declare function linkGridToMarkdown(groups: readonly LinkGridGroup[], intro?: string | null): string;
 /** A flat bullet list of links — resolved page lists, feed items, link rails. */
 export declare function linkList(items: readonly LinkGridLink[]): string;
+/**
+ * The core leaves as the helpers below read them: the shape every wiki here
+ * stores, built from the leaf types above. `P` is what a resolved page list
+ * carries, because radix-wiki's lists hold its own page rows and the other two
+ * hold `ResolvedPageRef`s.
+ *
+ * Structural on purpose. A repo's own switch narrows its block to one of these
+ * cases and hands it over — `case 'stats': case 'linkGrid': … return
+ * coreAtomicText(block)` — so the switch stays exhaustive over the repo's union
+ * and the case bodies stop being written three times.
+ */
+export type CoreAtomicBlock<P = ResolvedPageRef> = {
+    type: 'content';
+    text: string;
+} | {
+    type: 'codeTabs';
+    tabs: readonly CodeTab[];
+} | {
+    type: 'banner';
+    variant: string;
+    text?: string | null;
+} | {
+    type: 'references';
+    title?: string | null;
+    items: readonly ReferenceItem[];
+} | {
+    type: 'stats';
+    items: readonly StatItem[];
+} | {
+    type: 'linkGrid';
+    intro?: string | null;
+    groups: readonly LinkGridGroup[];
+} | {
+    type: 'recentPages' | 'pageList';
+    resolvedPages?: readonly P[] | null;
+};
+/**
+ * One core leaf as prose, for the LLM and MCP exports. A page list reads only
+ * after the server has resolved it; unresolved, it extracts to nothing.
+ */
+export declare function coreAtomicText(block: CoreAtomicBlock<{
+    title: string;
+}>): string;
+export interface CoreMarkdownOptions {
+    /**
+     * The origin a resolved page's site-relative `href` is joined to. A twin is
+     * read off-site, where a bare `/wiki/…` resolves to nothing.
+     */
+    siteUrl: string;
+    /** A references block's heading when it stores none. Default `References`. */
+    referencesTitle?: string;
+}
+/** One core leaf as markdown, for a page's `.md` twin. */
+export declare function coreAtomicToMarkdown(block: CoreAtomicBlock, opts: CoreMarkdownOptions): string;
+export interface CoreBlockDefaultsOptions {
+    /** Ids for the nested rows a new block starts with. Default `crypto.randomUUID`. */
+    newId?: () => string;
+    /** A new references block's title. Default `References`. */
+    referencesTitle?: string;
+    /** A new code-tabs block's tabs, each empty. Default Rust and TypeScript. */
+    codeTabs?: ReadonlyArray<{
+        label: string;
+        language: string;
+    }>;
+    /** A new stats block's three placeholder cards. */
+    stats?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+/** What inserting each core type makes, without its `id`. */
+export interface CoreBlockDefaults {
+    content: () => {
+        type: 'content';
+        text: string;
+    };
+    recentPages: () => {
+        type: 'recentPages';
+        limit: number;
+    };
+    pageList: () => {
+        type: 'pageList';
+        pageIds: string[];
+    };
+    columns: () => {
+        type: 'columns';
+        columns: {
+            id: string;
+            blocks: never[];
+        }[];
+        gap: 'md';
+        align: 'start';
+    };
+    infobox: () => {
+        type: 'infobox';
+        blocks: never[];
+    };
+    codeTabs: () => {
+        type: 'codeTabs';
+        tabs: {
+            label: string;
+            language: string;
+            code: string;
+        }[];
+    };
+    stats: () => {
+        type: 'stats';
+        items: {
+            id: string;
+            value: string;
+            label: string;
+        }[];
+        columns: 3;
+    };
+    linkGrid: () => {
+        type: 'linkGrid';
+        groups: {
+            id: string;
+            heading: string;
+            links: never[];
+        }[];
+    };
+    references: () => {
+        type: 'references';
+        title: string;
+        items: never[];
+    };
+    banner: () => {
+        type: 'banner';
+        variant: 'stub';
+    };
+}
+/**
+ * The new-block factories for the core types, which all three wikis had typed
+ * out identically but for a few labels. Spread into a repo's own record beside
+ * its native types, so that record stays keyed by the repo's union:
+ * `{ ...coreBlockDefaults({ stats }), daoTimeline: () => … }`.
+ */
+export declare function coreBlockDefaults(opts?: CoreBlockDefaultsOptions): CoreBlockDefaults;

package/dist/blocks.js

@@ -12,6 +12,7 @@
 // keeps this file free of any one repo's type union.
 import { htmlToMarkdown, inlineToMarkdown } from './markdown.js';
 import { relativeTime } from './freshness.js';
+import { BANNER_LABELS, bannerToText, codeTabsToText, linkGridToText, pageListToText, referencesToText, statsToText, stripHtml, } from './text.js';
 export function pageRef(page, now, style = 'long') {
     return {
         title: page.title,
@@ -194,3 +195,70 @@ export function linkGridToMarkdown(groups, intro) {
 export function linkList(items) {
     return items.map(l => `- [${l.label}](${l.href})`).join('\n');
 }
+const bannerLabel = (variant) => BANNER_LABELS[variant] ?? variant;
+/**
+ * One core leaf as prose, for the LLM and MCP exports. A page list reads only
+ * after the server has resolved it; unresolved, it extracts to nothing.
+ */
+export function coreAtomicText(block) {
+    switch (block.type) {
+        case 'content': return stripHtml(block.text);
+        case 'codeTabs': return codeTabsToText(block.tabs);
+        case 'banner': return bannerToText(bannerLabel(block.variant), block.text);
+        case 'references': return referencesToText(block.items);
+        case 'stats': return statsToText(block.items);
+        case 'linkGrid': return linkGridToText(block.groups, block.intro);
+        case 'recentPages':
+        case 'pageList': return pageListToText(block.resolvedPages ?? []);
+    }
+}
+/** One core leaf as markdown, for a page's `.md` twin. */
+export function coreAtomicToMarkdown(block, opts) {
+    switch (block.type) {
+        case 'content': return htmlToMarkdown(block.text);
+        case 'codeTabs': return codeTabsToMarkdown(block.tabs);
+        case 'banner': return bannerToMarkdown(bannerLabel(block.variant), block.text);
+        case 'references': return referencesToMarkdown(block.items, block.title || opts.referencesTitle || 'References');
+        case 'stats': return statsToMarkdown(block.items);
+        case 'linkGrid': return linkGridToMarkdown(block.groups, block.intro);
+        case 'recentPages':
+        case 'pageList':
+            return linkList((block.resolvedPages ?? []).map(p => ({
+                label: p.title,
+                href: p.href.startsWith('/') ? `${opts.siteUrl}${p.href}` : p.href,
+            })));
+    }
+}
+/**
+ * The new-block factories for the core types, which all three wikis had typed
+ * out identically but for a few labels. Spread into a repo's own record beside
+ * its native types, so that record stays keyed by the repo's union:
+ * `{ ...coreBlockDefaults({ stats }), daoTimeline: () => … }`.
+ */
+export function coreBlockDefaults(opts = {}) {
+    const { newId = () => crypto.randomUUID(), referencesTitle = 'References', codeTabs = [
+        { label: 'Rust', language: 'rust' },
+        { label: 'TypeScript', language: 'typescript' },
+    ], stats = [
+        { value: '100+', label: 'Customers' },
+        { value: '$1M', label: 'Revenue' },
+        { value: '99%', label: 'Uptime' },
+    ], } = opts;
+    return {
+        content: () => ({ type: 'content', text: '' }),
+        recentPages: () => ({ type: 'recentPages', limit: 5 }),
+        pageList: () => ({ type: 'pageList', pageIds: [] }),
+        columns: () => ({
+            type: 'columns',
+            columns: [{ id: newId(), blocks: [] }, { id: newId(), blocks: [] }],
+            gap: 'md',
+            align: 'start',
+        }),
+        infobox: () => ({ type: 'infobox', blocks: [] }),
+        codeTabs: () => ({ type: 'codeTabs', tabs: codeTabs.map(t => ({ ...t, code: '' })) }),
+        stats: () => ({ type: 'stats', items: stats.map(s => ({ id: newId(), ...s })), columns: 3 }),
+        linkGrid: () => ({ type: 'linkGrid', groups: [{ id: newId(), heading: 'Group', links: [] }] }),
+        references: () => ({ type: 'references', title: referencesTitle, items: [] }),
+        banner: () => ({ type: 'banner', variant: 'stub' }),
+    };
+}