wiki-formant 0.21.0 → 0.22.0

package/README.md

@@ -165,6 +165,8 @@ process.exit(t.summary());
 
 What stays in your repo is fixtures: which tools you expect, what a good answer from each looks like, and which text surfaces you publish. `payloadBudget` weighs every listed call **and** every read-only tool that takes no required arguments, because the one tool nobody thought to list is the one that answers with 3.3 MB; pass a per-call `maxBytes` for a bulk-export tool that is deliberately large. It also asserts that a JSON answer arrived with `structuredContent`.
 
+`descriptorChecks(t)` defaults to `S10_DESCRIPTORS`, the six JSON descriptors every surface here serves, and `distinctEtagChecks(t, ['llms.txt', 'llms-index.txt', 'llms-full.txt'])` asserts that depths projecting one corpus carry different ETags — every one present, which a bare Set-size check misses.
+
 ## Markdown twins
 
 Pass an `etag` and answer `notModified` before rendering: a twin is the single most recrawled URL a page has, so a twin with no validator is a full render on every pass, forever — the same arithmetic that justifies the corpus ETag, applied per page.
@@ -192,6 +194,8 @@ Block trees stay in your app — every project owns its own type set. Give this
 
 The `llms.txt` / `llms-index.txt` / `llms-full.txt` trio are the most-recrawled URLs a wiki serves and the most expensive to render. Without a corpus-derived ETag, every AI crawler pays full price on every pass, forever.
 
+A URL that answers JSON or markdown by `Accept` asks `wantsMarkdown(request)` and sends `VARY_ACCEPT` on both branches. Without the Vary, a shared cache hands one client the other's format.
+
 ```ts
 import { corpusEtag, notModified, textHeaders } from 'wiki-formant/http';
 
@@ -269,7 +273,8 @@ are unit-tested without a DOM.
 
 `wiki-formant/react` carries `'use client'`, and that is a module-level boundary: anything exported from it hydrates in the consumer's tree whether or not it uses a hook. `wiki-formant/react-server` is the same React, without the directive — for the parts of a wiki that are pure functions of their props and should ship no JavaScript at all.
 
-`FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
+`FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site.
+`FacetBar` takes a `count` class to render each count as its own element, and `alphaFirst` to lead with the A–Z row. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
 
 `PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
 
@@ -314,6 +319,19 @@ and a crawler obeys only its most-specific matching group, so an agent with no
 group of its own falls through to `*`. Three wikis were measuring five crawlers
 they had never addressed.
 
+Every group also allows `AGENT_SURFACE_PATHS` — `/api/mcp`, the three `llms` exports, `/openapi.json`, `/.well-known/` — without being told. `aiAllow` is what an origin serves beyond that.
+
+## Page metadata
+
+`wiki-formant/metadata`'s `pageMetadata` builds a page's canonical, markdown-twin alternate, Open Graph and Twitter card from one input. Next replaces those objects per route segment rather than merging them, and fills a missing twitter card from `openGraph` only when no `twitter` object was inherited — so under a layout that sets its own card, a page that sets one and forgets the other shows the layout's. Two wikis wrote a helper around that, covering different halves.
+
+```ts
+export const generateMetadata = () => ({
+  title,
+  ...pageMetadata({ title, description, url, type: 'article', image: ogImageUrl(title), siteName, handle, markdownTwin: true }),
+});
+```
+
 ## Revisions
 
 What changed between two versions of a page, and therefore which semver bump to
@@ -358,6 +376,7 @@ carries no build date rather than a fictional one.
 
 ## Licence declarations
 
+
 S10 wants a licence on every surface, and each repo satisfied that by writing the
 same block again. What is genuinely per-project is the *scope* — which half of a
 site the grant covers and what it excludes — so that is the parameter.
@@ -367,6 +386,8 @@ const license = ccBy40({ siteName: 'AcuiQ', siteUrl: SITE_URL });
 const block = licenseBlock({ license, scope: 'The protocol compilation and prose', excludes });
 ```
 
+The same `License` goes to `agentCard({ license, licenseScope })` and to `openApiLicense(license)` for a spec's `info.license`. The three cards and three specs here had each projected it differently, one from a hand-typed name.
+
 ## Rendered-article passes
 
 `wiki-formant/dom` holds what runs against an article element after it is in the document. Not React, so not in `react.tsx`.
@@ -380,12 +401,18 @@ const off = onTweetResize(h => sizeTweetEmbeds(el, h));
 
 `addCopyButton` was **byte-identical** in two BlockRenderers, down to the SVG path data. Its idempotence guard now lives inside the function rather than in a `pre:not(:has(…))` at the call site, where it can be — and was — retyped.
 
+In React, `useArticlePasses(ref, [blocks])` runs the three passes and `useTweetEmbeds(ref, [html])` the embed pair, from `wiki-formant/react`. Three renderers had the effect written out and disagreed on its dependencies: two ran once on mount, so a page swapped in without a remount kept its old tables unsortable.
+
 `activateTabGroups` turns stored `[data-tabs]` markup into a working tab group. The editor persists tabs as nested divs, which is the right thing to store — it survives a markdown twin, a plain HTML render and a reader with JavaScript off, all of which show every tab in order. Making one of them pressable is a reader-side job, and it sits beside the other passes rather than inside a component.
 
 `sortTables` makes the tables stored in article HTML sortable by their headers. They arrive as a string a `dangerouslySetInnerHTML` wrote, so React never sees their rows and cannot sort them. A column is dates if every filled cell starts with one, numbers if every one does, and text otherwise — one stray value makes the whole column text, which beats sorting half of it by one rule and half by another. A third press restores the author's order, which is often chronological or ranked and otherwise needs a reload. Label/value tables and tables with merged cells are left alone. The markup it writes — `aria-sort` on the cell, a `.sort-header` button inside it — is the markup a React sortable header should write too, so both kinds of table draw their arrows from one stylesheet rule.
 
 `TWITTER_ORIGIN` is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
 
+## Search
+
+`proseSql`, `searchTsvSql`, `HEADLINE_OPTIONS` and `FTS_RANK_NORMALIZATION` are what a literal tier and a full-text tier must agree on. `searchTsvDdl(table)` is the statements that build the generated `search_tsv` column and its index — dropped and re-added in one transaction every run, because a skip-if-present script is blind to a changed expression.
+
 ## Block trees
 
 Every wiki here stores the same two containers the same way — `columns[i].blocks` and an infobox's `blocks` — and between them had hand-written that walk seven times. Bind it once and hand it to every walk:
@@ -441,6 +468,8 @@ The ones that take config take it because that is exactly where the two copies d
 
 `createTabs` returns `TabGroup` and `TabItem` together: `tabGroup`'s content expression is `tabItem+`, so registering one without the other leaves a node type the schema cannot satisfy. A pasted short map link inserts immediately with `about:blank` and swaps its `src` when the redirect resolves — pasting must not block on a network hop, and the node has to exist for the reader to see anything happen.
 
+`createHeadingIds({ slug })` decorates each heading in the editor with the id its published copy will carry, through `uniqueHeadingId` — the dedupe `injectHeadingIds` uses — so a rail listing headings mid-edit links to the anchors readers will get. `uploadImageTo('/api/upload')` is the `uploadImage` two editors had written identically.
+
 The redirect resolves through the wiki's own route, because the editor cannot read it cross-origin. `resolveMapUrl` is the client half and `resolveMapHandler` the whole route: exact shortener hosts, one hop, an allowlisted landing host, a timeout, and your sign-in check as `authorize`. One of the two copies it replaced matched `goo.gl` as a substring and followed every redirect for anyone who asked.
 
 ```ts

package/dist/block-views.d.ts

@@ -79,19 +79,16 @@ export declare function StatsView({ items, columns, }: {
 /**
  * A maintenance notice.
  *
- * The label and the fallback message arrive as `meta` because they are this
- * wiki's editorial voice — "You can help RADIX Wiki by expanding it" has a name
- * in it. The markup, the `role="note"` and the variant class are shared, and
- * were identical in both repos. `icon` is optional: one wiki sets one, and a
- * component library that hardcoded an icon set would make its consumers install
- * that icon set.
+ * The label is `BANNER_LABELS`, looked up here: three renderers each did the
+ * unknown-variant fallback and the lookup, and one restated all six labels.
+ * The fallback `message` arrives as a prop because it is the wiki's editorial
+ * voice — "You can help RADIX Wiki by expanding it" has a name in it. `icon`
+ * is optional: a component library that hardcoded an icon set would make its
+ * consumers install that icon set.
  */
-export declare function BannerView({ variant, text, meta, icon, }: {
+export declare function BannerView({ variant, text, message, icon, }: {
     variant: string;
     text?: string | null;
-    meta: {
-        label: string;
-        message: string;
-    };
+    message: string;
     icon?: ReactNode;
 }): import("react").JSX.Element;

package/dist/block-views.js

@@ -22,6 +22,7 @@ import { Fragment, useState } from 'react';
 import { Anchor } from './react-server.js';
 import { safeLinkHref } from './validation.js';
 import { cx } from './html.js';
+import { BANNER_LABELS, bannerVariant } from './text.js';
 // ---- codeTabs ---------------------------------------------------------------
 /**
  * Tabbed code samples. Every tab's body stays mounted and the inactive ones are
@@ -106,13 +107,14 @@ export function StatsView({ items, columns = 4, }) {
 /**
  * A maintenance notice.
  *
- * The label and the fallback message arrive as `meta` because they are this
- * wiki's editorial voice — "You can help RADIX Wiki by expanding it" has a name
- * in it. The markup, the `role="note"` and the variant class are shared, and
- * were identical in both repos. `icon` is optional: one wiki sets one, and a
- * component library that hardcoded an icon set would make its consumers install
- * that icon set.
+ * The label is `BANNER_LABELS`, looked up here: three renderers each did the
+ * unknown-variant fallback and the lookup, and one restated all six labels.
+ * The fallback `message` arrives as a prop because it is the wiki's editorial
+ * voice — "You can help RADIX Wiki by expanding it" has a name in it. `icon`
+ * is optional: a component library that hardcoded an icon set would make its
+ * consumers install that icon set.
  */
-export function BannerView({ variant, text, meta, icon, }) {
-    return (_jsxs("div", { className: cx('editorial-banner', `editorial-banner-${variant}`), role: "note", children: [icon, _jsxs("p", { className: "editorial-banner-body", children: [_jsxs("strong", { children: [meta.label, "."] }), " ", text?.trim() || meta.message] })] }));
+export function BannerView({ variant, text, message, icon, }) {
+    const known = bannerVariant(variant);
+    return (_jsxs("div", { className: cx('editorial-banner', `editorial-banner-${known}`), role: "note", children: [icon, _jsxs("p", { className: "editorial-banner-body", children: [_jsxs("strong", { children: [BANNER_LABELS[known], "."] }), " ", text?.trim() || message] })] }));
 }

package/dist/conformance.d.ts

@@ -134,7 +134,19 @@ export declare function conditionalGetChecks(t: Tester, paths: readonly string[]
  * document moving, which is worse than none. The body-derived ETag is the whole
  * validator, and it is enough.
  */
-export declare function descriptorChecks(t: Tester, paths: readonly string[]): Promise<void>;
+/** The JSON descriptors every S10 origin serves: the two agent-card paths, the OpenAPI pair, the MCP manifest and the server card. */
+export declare const S10_DESCRIPTORS: readonly string[];
+export declare function descriptorChecks(t: Tester, paths?: readonly string[]): Promise<void>;
+/**
+ * Documents that project one corpus at different depths carry different ETags.
+ *
+ * Depths sharing a validator pass every conditional-GET check and still never
+ * move when only one of them changes. Every one must also HAVE an ETag: a Set
+ * of three nulls is size one and fails, but one null among two tags would pass
+ * a size check alone — the copy of this check one repo carried had exactly
+ * that hole.
+ */
+export declare function distinctEtagChecks(t: Tester, paths: readonly string[], label?: string): Promise<void>;
 /**
  * Every tool carries behavioural hints, and the ones that write say so.
  *

package/dist/conformance.js

@@ -312,7 +312,16 @@ export async function conditionalGetChecks(t, paths) {
  * document moving, which is worse than none. The body-derived ETag is the whole
  * validator, and it is enough.
  */
-export async function descriptorChecks(t, paths) {
+/** The JSON descriptors every S10 origin serves: the two agent-card paths, the OpenAPI pair, the MCP manifest and the server card. */
+export const S10_DESCRIPTORS = [
+    '.well-known/agent-card.json',
+    '.well-known/agent.json',
+    '.well-known/openapi.json',
+    'openapi.json',
+    '.well-known/mcp.json',
+    'api/mcp/server-card',
+];
+export async function descriptorChecks(t, paths = S10_DESCRIPTORS) {
     for (const path of paths) {
         const url = path.startsWith('http') ? path : `${t.base}/${path.replace(/^\//, '')}`;
         const label = path.replace(t.base, '');
@@ -326,6 +335,19 @@ export async function descriptorChecks(t, paths) {
         t.check(`${label} states a freshness`, /max-age=\d+/.test(fresh.headers.get('cache-control') ?? ''), `cache-control: ${fresh.headers.get('cache-control')}`);
     }
 }
+/**
+ * Documents that project one corpus at different depths carry different ETags.
+ *
+ * Depths sharing a validator pass every conditional-GET check and still never
+ * move when only one of them changes. Every one must also HAVE an ETag: a Set
+ * of three nulls is size one and fails, but one null among two tags would pass
+ * a size check alone — the copy of this check one repo carried had exactly
+ * that hole.
+ */
+export async function distinctEtagChecks(t, paths, label = 'llms depths have distinct ETags') {
+    const tags = await Promise.all(paths.map(p => fetch(`${t.base}/${p.replace(/^\//, '')}`).then(r => r.headers.get('etag'))));
+    t.check(label, tags.every(Boolean) && new Set(tags).size === paths.length, tags.join(' '));
+}
 /**
  * Every tool carries behavioural hints, and the ones that write say so.
  *

package/dist/crawlers.d.ts

@@ -29,6 +29,12 @@ export interface RobotsGroup {
     allow?: string | string[];
     disallow?: string | string[];
 }
+/**
+ * The agent surface an S10 origin serves, allowed in every group. All three
+ * `robots.ts` files listed these by hand, and a path missing from one list is
+ * an endpoint the origin advertises and then closes to the callers it named.
+ */
+export declare const AGENT_SURFACE_PATHS: readonly string[];
 /**
  * The wildcard group followed by one group per crawler.
  *
@@ -40,5 +46,6 @@ export interface RobotsGroup {
 export declare function aiCrawlerRules(opts: {
     allow: string | string[];
     disallow: string | string[];
-    aiAllow: string | string[];
+    /** Beyond `AGENT_SURFACE_PATHS`, which every group gets regardless. */
+    aiAllow?: string | string[];
 }): RobotsGroup[];

package/dist/crawlers.js

@@ -53,6 +53,19 @@ export function detectAiBot(userAgent) {
 export function aiCrawlerTokens() {
     return AI_CRAWLERS.map(c => c.token);
 }
+/**
+ * The agent surface an S10 origin serves, allowed in every group. All three
+ * `robots.ts` files listed these by hand, and a path missing from one list is
+ * an endpoint the origin advertises and then closes to the callers it named.
+ */
+export const AGENT_SURFACE_PATHS = [
+    '/api/mcp',
+    '/llms.txt',
+    '/llms-index.txt',
+    '/llms-full.txt',
+    '/openapi.json',
+    '/.well-known/',
+];
 /**
  * The wildcard group followed by one group per crawler.
  *
@@ -62,7 +75,7 @@ export function aiCrawlerTokens() {
  * agent everything, because it stops matching `*` the moment it matches itself.
  */
 export function aiCrawlerRules(opts) {
-    const aiAllow = [opts.aiAllow].flat();
+    const aiAllow = [...new Set([...[opts.aiAllow ?? []].flat(), ...AGENT_SURFACE_PATHS])];
     return [
         // `aiAllow` rides on the default group too, not only on the named roster.
         // The agent surface an origin advertises has to be reachable by a caller it

package/dist/editor.d.ts

@@ -46,6 +46,11 @@ export declare function insertEmbed(editor: Editor, url: string, { resolveMapUrl
 export declare const TABLE_ACTIONS: ReadonlyArray<[command: string, label: string, danger?: boolean]>;
 /** `editor.isActive` as a toolbar button's `active` descriptor expresses it. */
 export type ActiveDescriptor = string | [string, Record<string, unknown>];
+/**
+ * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
+ * back. Two editors carried it character for character, `alert` included.
+ */
+export declare function uploadImageTo(endpoint: string): (file: File) => Promise<string | null>;
 export interface WikiEditorOptions {
     value: string;
     onChange: (html: string) => void;

package/dist/editor.js

@@ -136,6 +136,30 @@ export const TABLE_ACTIONS = [
     ['deleteRow', '-Row', true],
     ['deleteTable', '-Tbl', true],
 ];
+// ---- the editor -------------------------------------------------------------
+/**
+ * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
+ * back. Two editors carried it character for character, `alert` included.
+ */
+export function uploadImageTo(endpoint) {
+    return async (file) => {
+        const form = new FormData();
+        form.append('file', file);
+        try {
+            const res = await fetch(endpoint, { method: 'POST', body: form });
+            const body = (await res.json());
+            if (!res.ok) {
+                alert(body.error || 'Upload failed');
+                return null;
+            }
+            return body.url ?? null;
+        }
+        catch {
+            alert('Upload failed');
+            return null;
+        }
+    };
+}
 /**
  * The editor, its upload plumbing and the state a toolbar reads.
  *

package/dist/freshness.d.ts

@@ -17,3 +17,17 @@ export declare function isStale(page: FreshnessInput, now: number, maxAgeDays?:
  * being re-typed either side of the extraction.
  */
 export declare function freshnessNotice(page: FreshnessInput): string;
+/**
+ * A synthetic `outdated` banner block for a stale page, or null when it is
+ * fresh — the shape every wiki's `banner` type already stores, so it drops
+ * into the tree the renderer walks. Two wikis carried this function
+ * identically. `nowMs` comes from a server component: reading the clock
+ * during a client render would let a page near the boundary be stale on the
+ * server and fresh in the browser.
+ */
+export declare function freshnessBanner(page: FreshnessInput, nowMs: number, maxAgeDays?: number): {
+    id: string;
+    type: 'banner';
+    variant: 'outdated';
+    text: string;
+} | null;

package/dist/freshness.js

@@ -40,3 +40,16 @@ export function freshnessNotice(page) {
         : 'not yet verified against sources';
     return `This page was ${when} and may be out of date. Please help re-check its facts against current sources and the live ledger.`;
 }
+/**
+ * A synthetic `outdated` banner block for a stale page, or null when it is
+ * fresh — the shape every wiki's `banner` type already stores, so it drops
+ * into the tree the renderer walks. Two wikis carried this function
+ * identically. `nowMs` comes from a server component: reading the clock
+ * during a client render would let a page near the boundary be stale on the
+ * server and fresh in the browser.
+ */
+export function freshnessBanner(page, nowMs, maxAgeDays = DEFAULT_MAX_AGE_DAYS) {
+    if (!isStale(page, nowMs, maxAgeDays))
+        return null;
+    return { id: '__freshness__', type: 'banner', variant: 'outdated', text: freshnessNotice(page) };
+}

package/dist/headings.d.ts

@@ -7,6 +7,13 @@ export interface Heading {
 }
 /** The default slug rule: lowercase words joined by hyphens. */
 export declare function slugifyHeading(text: string): string;
+/**
+ * `base`, or `base-2`, `base-3`… — the first one `used` does not hold. Records
+ * nothing: the caller adds the id it keeps. Shared with the editor's heading
+ * decoration, so the id a heading shows while it is being written is the id it
+ * is published under.
+ */
+export declare function uniqueHeadingId(base: string, used: ReadonlySet<string>): string;
 export interface HeadingIdOptions {
     /**
      * How heading text becomes an id. Defaults to `slugifyHeading`. Pass the rule

package/dist/headings.js

@@ -20,6 +20,20 @@ export function slugifyHeading(text) {
         .replace(/[\s_-]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+/**
+ * `base`, or `base-2`, `base-3`… — the first one `used` does not hold. Records
+ * nothing: the caller adds the id it keeps. Shared with the editor's heading
+ * decoration, so the id a heading shows while it is being written is the id it
+ * is published under.
+ */
+export function uniqueHeadingId(base, used) {
+    if (!base)
+        return base;
+    let id = base;
+    for (let n = 2; used.has(id); n++)
+        id = `${base}-${n}`;
+    return id;
+}
 const HEADING = /<(h[1-6])([^>]*)>([\s\S]*?)<\/\1>/gi;
 const defaultAnchor = (id) => `<a class="heading-anchor" href="#${id}" aria-label="Permalink to this section" tabindex="-1"></a>`;
 /**
@@ -37,15 +51,9 @@ export function injectHeadingIds(html, options = {}) {
         if (content.includes('heading-anchor'))
             return match;
         const existing = getAttr(attrs, 'id');
-        let id = existing || slug(stripTags(content));
+        const id = existing || uniqueHeadingId(slug(stripTags(content)), used);
         if (!id)
             return match;
-        if (!existing) {
-            const base = id;
-            let n = 2;
-            while (used.has(id))
-                id = `${base}-${n++}`;
-        }
         used.add(id);
         return `<${tag}${existing ? attrs : `${attrs} id="${id}"`}>${content}${anchor(id)}</${tag}>`;
     });

package/dist/http.d.ts

@@ -9,7 +9,15 @@ export declare function corpusEtag(parts: Array<string | number | Date | null |
  * prefix, and a crawler reformats the date. Each of those took a full render
  * from a response that was already fresh.
  */
-export declare function notModified(request: Request, etag: string, lastModified?: string | null): Response | null;
+export declare function notModified(request: Request, etag: string, lastModified?: string | null, 
+/**
+ * The headers the 200 would carry. RFC 9110 15.4.5 requires a 304 to send
+ * the Cache-Control and Vary a 200 would have, and a cross-origin client
+ * needs the CORS header on it too; without them a revalidated copy loses its
+ * freshness and a negotiated URL loses its Vary. The body's own headers
+ * (Content-Type, Content-Length) are dropped.
+ */
+sent?: Record<string, string>): Response | null;
 /**
  * A 404 that teaches, for the plain-GET half of an agent surface.
  *
@@ -49,6 +57,25 @@ export declare function markdownHeaders(lastModified?: string | null, opts?: {
     etag?: string;
     extra?: Record<string, string>;
 }): Record<string, string>;
+/**
+ * Whether a request to a URL that serves both JSON and markdown asked for the
+ * markdown: `?format=text`, or an Accept naming text/markdown or text/plain.
+ * The `.md` suffix is the caller's to add — it lives in the path, not here.
+ *
+ * Both branches of such a route must send `VARY_ACCEPT`. Two wikis answered
+ * one URL in two formats under `public, s-maxage` with no Vary, so a shared
+ * cache could hand the markdown to the next JSON client, or the reverse.
+ */
+export declare function wantsMarkdown(request: {
+    url: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}): boolean;
+/** The header every response from a content-negotiated URL carries. */
+export declare const VARY_ACCEPT: {
+    readonly Vary: "Accept";
+};
 /**
  * Headers for a JSON descriptor — an agent card, an OpenAPI document, a
  * registry manifest. These are the documents a client refetches most and the

package/dist/http.js

@@ -30,8 +30,17 @@ const bareTag = (tag) => tag.trim().replace(/^W\//, '');
  * prefix, and a crawler reformats the date. Each of those took a full render
  * from a response that was already fresh.
  */
-export function notModified(request, etag, lastModified) {
+export function notModified(request, etag, lastModified, 
+/**
+ * The headers the 200 would carry. RFC 9110 15.4.5 requires a 304 to send
+ * the Cache-Control and Vary a 200 would have, and a cross-origin client
+ * needs the CORS header on it too; without them a revalidated copy loses its
+ * freshness and a negotiated URL loses its Vary. The body's own headers
+ * (Content-Type, Content-Length) are dropped.
+ */
+sent = {}) {
     const headers = {
+        ...Object.fromEntries(Object.entries(sent).filter(([k]) => !/^content-(type|length)$/i.test(k))),
         ETag: etag,
         ...(lastModified ? { 'Last-Modified': lastModified } : {}),
     };
@@ -110,6 +119,21 @@ export function markdownHeaders(lastModified, opts = {}) {
         ...opts.extra,
     };
 }
+/**
+ * Whether a request to a URL that serves both JSON and markdown asked for the
+ * markdown: `?format=text`, or an Accept naming text/markdown or text/plain.
+ * The `.md` suffix is the caller's to add — it lives in the path, not here.
+ *
+ * Both branches of such a route must send `VARY_ACCEPT`. Two wikis answered
+ * one URL in two formats under `public, s-maxage` with no Vary, so a shared
+ * cache could hand the markdown to the next JSON client, or the reverse.
+ */
+export function wantsMarkdown(request) {
+    return (new URL(request.url).searchParams.get('format') === 'text' ||
+        /text\/(markdown|plain)/.test(request.headers.get('accept') ?? ''));
+}
+/** The header every response from a content-negotiated URL carries. */
+export const VARY_ACCEPT = { Vary: 'Accept' };
 /**
  * Headers for a JSON descriptor — an agent card, an OpenAPI document, a
  * registry manifest. These are the documents a client refetches most and the
@@ -137,7 +161,8 @@ export function descriptorHeaders(etag, opts = {}) {
 export function descriptorResponse(request, body, opts = {}) {
     const text = JSON.stringify(body);
     const etag = corpusEtag([text]);
-    return notModified(request, etag) ?? new Response(text, { headers: descriptorHeaders(etag, opts) });
+    const sent = descriptorHeaders(etag, opts);
+    return notModified(request, etag, null, sent) ?? new Response(text, { headers: sent });
 }
 /** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
 export function cleanSnippet(text, max = 160) {
@@ -172,7 +197,7 @@ export function pageLine(opts) {
 export function corpusRoute(validators, build, headers = textHeaders) {
     return async (request) => {
         const { etag, lastModified } = await validators();
-        return (notModified(request, etag, lastModified) ??
-            new Response(await build(), { headers: headers(etag, lastModified) }));
+        const sent = headers(etag, lastModified);
+        return notModified(request, etag, lastModified, sent) ?? new Response(await build(), { headers: sent });
     };
 }

package/dist/index.d.ts

@@ -19,3 +19,4 @@ export * from './revisions.js';
 export * from './feed.js';
 export * from './license.js';
 export * from './seeded.js';
+export * from './metadata.js';

package/dist/index.js

@@ -24,3 +24,4 @@ export * from './revisions.js';
 export * from './feed.js';
 export * from './license.js';
 export * from './seeded.js';
+export * from './metadata.js';

package/dist/license.d.ts

@@ -43,3 +43,12 @@ export declare function licenseLines({ license, scope, scopeVerb, excludes, head
 export declare function licenseBlock(opts: LicenseBlockOptions): string;
 /** The one-line form, for a frontmatter field or a feed's `<copyright>`. */
 export declare function licenseNote(license: License): string;
+/**
+ * The OpenAPI 3.1 `info.license` object. Name plus SPDX `identifier` — the
+ * spec makes `identifier` and `url` mutually exclusive, and the three specs
+ * here had each picked a different pair, one of them a hand-typed name.
+ */
+export declare function openApiLicense(license: License): {
+    name: string;
+    identifier: string;
+};

package/dist/license.js

@@ -47,3 +47,11 @@ export function licenseBlock(opts) {
 export function licenseNote(license) {
     return `${license.name} (${license.spdx}): ${license.url}`;
 }
+/**
+ * The OpenAPI 3.1 `info.license` object. Name plus SPDX `identifier` — the
+ * spec makes `identifier` and `url` mutually exclusive, and the three specs
+ * here had each picked a different pair, one of them a hand-typed name.
+ */
+export function openApiLicense(license) {
+    return { name: license.name, identifier: license.spdx };
+}

package/dist/link-check.js

@@ -182,7 +182,9 @@ export async function probeYouTube(videoId, opts = {}) {
 }
 /** An external anchor, with a video treated as a video. */
 export async function probeExternal(url, opts = {}) {
-    const yt = url.match(YOUTUBE_WATCH);
+    // Watch and embed URLs alike: an /embed/ page answers 200 for a deleted
+    // video, so a checker that probed embeds as plain URLs never saw one die.
+    const yt = url.match(YOUTUBE_WATCH) ?? url.match(YOUTUBE_EMBED);
     if (yt?.[1])
         return { url, videoId: yt[1], ...(await probeYouTube(yt[1], opts)) };
     return probeUrl(url, opts);

package/dist/metadata.d.ts

@@ -0,0 +1,69 @@
+export interface ArticleMeta {
+    publishedTime?: string;
+    modifiedTime?: string;
+    section?: string;
+    tags?: string[];
+}
+export interface PageMetadataOptions {
+    /** The social title. */
+    title: string;
+    description?: string;
+    /** Absolute canonical URL. Omit on a page that should not declare one (a layout default). */
+    url?: string;
+    type?: 'website' | 'article';
+    /** Absolute URL of the card. Omit to let a file-convention `opengraph-image` supply it. */
+    image?: string;
+    /** Its intrinsic size. Defaults to the 1200×630 of a summary_large_image card. */
+    imageSize?: {
+        width: number;
+        height: number;
+    };
+    /** Defaults to `title`. */
+    imageAlt?: string;
+    siteName?: string;
+    locale?: string;
+    /** `@handle`, as both site and creator. */
+    handle?: string;
+    /**
+     * Advertise the page's markdown twin at `${url}.md`, beside the canonical —
+     * the only place it can go, since a separate `alternates` would replace this
+     * one. Pages only: a section or index has no twin.
+     */
+    markdownTwin?: boolean;
+    /** Open Graph article fields, for `type: 'article'`. */
+    article?: ArticleMeta;
+}
+export declare function pageMetadata(o: PageMetadataOptions): {
+    openGraph: {
+        publishedTime?: string;
+        modifiedTime?: string;
+        section?: string;
+        tags?: string[];
+        images?: {
+            alt: string;
+            width: number;
+            height: number;
+            url: string;
+        }[] | undefined;
+        locale?: string | undefined;
+        siteName?: string | undefined;
+        url?: string | undefined;
+        description?: string | undefined;
+        type: "article" | "website";
+        title: string;
+    };
+    twitter: {
+        images?: string[] | undefined;
+        site?: string | undefined;
+        creator?: string | undefined;
+        description?: string | undefined;
+        card: "summary_large_image";
+        title: string;
+    };
+    alternates?: {
+        types?: {
+            'text/markdown': string;
+        } | undefined;
+        canonical: string;
+    } | undefined;
+};

package/dist/metadata.js

@@ -0,0 +1,45 @@
+// metadata.ts — one page's canonical, markdown twin, Open Graph and Twitter
+// card, from one input.
+//
+// Next *replaces* rather than merges these objects per route segment. It does
+// fill a missing twitter title, description and image from `openGraph`, but
+// only when no `twitter` object was inherited — so under a layout that sets its
+// own card, a page that sets openGraph and forgets twitter shows the layout's
+// generic card, and a page that restates `alternates` for its twin clobbers its
+// canonical. Two
+// wikis wrote a helper around exactly that and covered different halves: one
+// had the twin and no siteName, the other the siteName and no twin. The third
+// wrote each page's metadata by hand.
+//
+// Plain objects in the shape Next's `Metadata` wants, so no `next` import.
+export function pageMetadata(o) {
+    const { title, description, url, type = 'website', image, imageSize = { width: 1200, height: 630 }, siteName, locale, handle, markdownTwin, article } = o;
+    const images = image ? [{ url: image, ...imageSize, alt: o.imageAlt ?? title }] : undefined;
+    return {
+        ...(url
+            ? {
+                alternates: {
+                    canonical: url,
+                    ...(markdownTwin ? { types: { 'text/markdown': `${url}.md` } } : {}),
+                },
+            }
+            : {}),
+        openGraph: {
+            type,
+            title,
+            ...(description ? { description } : {}),
+            ...(url ? { url } : {}),
+            ...(siteName ? { siteName } : {}),
+            ...(locale ? { locale } : {}),
+            ...(images ? { images } : {}),
+            ...(type === 'article' ? article : {}),
+        },
+        twitter: {
+            card: 'summary_large_image',
+            title,
+            ...(description ? { description } : {}),
+            ...(handle ? { site: handle, creator: handle } : {}),
+            ...(images ? { images: images.map(i => i.url) } : {}),
+        },
+    };
+}

package/dist/react-server.d.ts

@@ -37,6 +37,8 @@ export interface FacetBarClassNames {
     label?: string;
     control?: string;
     controlActive?: string;
+    /** Set it and each count is its own `<span>` with this class, not ` (n)` text. */
+    count?: string;
 }
 export interface FacetBarProps {
     link: WikiLinkComponent;
@@ -44,6 +46,8 @@ export interface FacetBarProps {
     letters: Control[];
     /** The label on the A–Z row. */
     alphaLabel?: string;
+    /** Lead with the A–Z row: two lines against a facet block's twenty. */
+    alphaFirst?: boolean;
     classNames?: FacetBarClassNames;
 }
 /**
@@ -56,7 +60,7 @@ export interface FacetBarProps {
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export declare function FacetBar({ link: Link, facets, letters, alphaLabel, classNames, }: FacetBarProps): import("react").JSX.Element | null;
+export declare function FacetBar({ link: Link, facets, letters, alphaLabel, alphaFirst, classNames, }: FacetBarProps): import("react").JSX.Element | null;
 /**
  * A JSON-LD payload, safe to place inside `<script type="application/ld+json">`.
  *

package/dist/react-server.js

@@ -36,11 +36,22 @@ export const Anchor = ({ href, className, children }) => _jsx("a", { href: href,
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', classNames = {}, }) {
+export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', alphaFirst = false, classNames = {}, }) {
     if (!facets.length && !letters.length)
         return null;
-    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', } = classNames;
-    return (_jsxs("div", { className: root, children: [facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(option => (_jsxs(Link, { href: option.href, className: option.active ? controlActive : control, "aria-current": option.active ? 'true' : undefined, children: [option.value, " (", option.count, ")"] }, option.value)))] }, facet.key))), letters.length > 0 && (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(letter => (_jsxs(Link, { href: letter.href, className: letter.active ? controlActive : control, "aria-current": letter.active ? 'true' : undefined, children: [letter.label, " (", letter.count, ")"] }, letter.value || 'all')))] }))] }));
+    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', count, } = classNames;
+    const chip = (c) => (_jsxs(Link, { href: c.href, className: c.active ? controlActive : control, "aria-current": c.active ? 'true' : undefined, ...(c.title ? { title: c.title } : {}), children: [c.text, count ? _jsx("span", { className: count, children: c.n }) : ` (${c.n})`] }, c.key));
+    const facetRows = facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(o => chip({ key: o.value, href: o.href, active: o.active, text: o.value, n: o.count }))] }, facet.key)));
+    // The reset control leads the letters and says what it resets to.
+    const alphaRow = letters.length > 0 && (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(l => chip({
+                key: l.value || 'all',
+                href: l.href,
+                active: l.active,
+                text: l.label,
+                n: l.count,
+                ...(l.reset ? { title: `All ${l.count} pages` } : {}),
+            }))] }, "alpha"));
+    return _jsx("div", { className: root, children: alphaFirst ? [alphaRow, ...facetRows] : [...facetRows, alphaRow] });
 }
 // ---- structured data --------------------------------------------------------
 /**

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { type ComboboxAria } from './combobox.js';
-import { Component, type CSSProperties, type KeyboardEvent, type ReactNode } from 'react';
+import { Component, type CSSProperties, type DependencyList, type RefObject, type KeyboardEvent, type ReactNode } from 'react';
 export interface SidebarOptions {
     /**
      * Where the reader's choice is remembered, in `localStorage`. Give each wiki
@@ -110,7 +110,7 @@ export declare function TableOfContents({ containerSelector, headings: providedH
  * `onClose` is an effect dependency: wrap it in `useCallback` or hoist it, or
  * the listener is torn down and rebuilt on every render.
  */
-export declare function useClickOutside<T extends HTMLElement>(onClose: () => void): import("react").RefObject<T | null>;
+export declare function useClickOutside<T extends HTMLElement>(onClose: () => void): RefObject<T | null>;
 export interface TypeaheadOptions<T> {
     /**
      * Runs the search. MUST be referentially stable — a module function, a server
@@ -344,3 +344,13 @@ export declare function RailShell({ children, prefix, label, className }: RailSh
  */
 export declare function isRailLinkActive(activePath: string, href: string, tree?: boolean): boolean;
 export type { WikiLinkComponent, WikiLinkProps } from './react-server.js';
+/**
+ * The `wiki-formant/dom` passes over a rendered article: tab groups, copy
+ * buttons, sortable tables. All three renderers ran the same three in an
+ * effect, and they disagreed on when: two ran it once on mount, so a page
+ * swapped in without a remount kept its old tables unsortable. Each pass is
+ * idempotent, so running on every `deps` change is safe.
+ */
+export declare function useArticlePasses(ref: RefObject<HTMLElement | null>, deps: DependencyList): void;
+/** Tweet placeholders hydrated, and their iframes kept sized to the posted height. */
+export declare function useTweetEmbeds(ref: RefObject<HTMLElement | null>, deps: DependencyList): void;

package/dist/react.js

@@ -27,6 +27,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 //      state on <html> before first paint. The hook keeps that attribute in
 //      sync afterwards, so CSS has one source of truth either side of hydration.
 import { resolveSidebarOpen, SIDEBAR_ATTRIBUTE } from './sidebar.js';
+import { activateTabGroups, addCopyButtons, hydrateTweetEmbeds, onTweetResize, sizeTweetEmbeds, sortTables } from './dom.js';
 import { comboboxAria } from './combobox.js';
 import { Component, createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from 'react';
 const readStored = (key) => {
@@ -622,3 +623,33 @@ export function RailShell({ children, prefix, label, className }) {
 export function isRailLinkActive(activePath, href, tree = false) {
     return tree ? activePath === href || activePath.startsWith(`${href}/`) : activePath === href;
 }
+// ---- rendered-article passes --------------------------------------------------
+/**
+ * The `wiki-formant/dom` passes over a rendered article: tab groups, copy
+ * buttons, sortable tables. All three renderers ran the same three in an
+ * effect, and they disagreed on when: two ran it once on mount, so a page
+ * swapped in without a remount kept its old tables unsortable. Each pass is
+ * idempotent, so running on every `deps` change is safe.
+ */
+export function useArticlePasses(ref, deps) {
+    useEffect(() => {
+        const root = ref.current;
+        if (!root)
+            return;
+        activateTabGroups(root);
+        addCopyButtons(root);
+        sortTables(root);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+}
+/** Tweet placeholders hydrated, and their iframes kept sized to the posted height. */
+export function useTweetEmbeds(ref, deps) {
+    useEffect(() => {
+        const root = ref.current;
+        if (!root)
+            return;
+        hydrateTweetEmbeds(root);
+        return onTweetResize(height => sizeTweetEmbeds(root, height));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+}

package/dist/search.d.ts

@@ -32,6 +32,26 @@ export declare const PROSE_PATTERN = "<[^>]*>|&nbsp;|\\\\[nrt\"\\\\/]|\", \"|\\[
  * tiers.
  */
 export declare function searchTsvSql(content?: string, title?: string): string;
+/**
+ * The statements that (re)build a table's `search_tsv` column and its GIN index.
+ * Run `column` inside one transaction: DROP then ADD, so no reader ever sees
+ * the table without it; then `index`.
+ *
+ * Rebuilt unconditionally rather than skipped when the column exists. A skip
+ * is idempotent about the column and blind to its EXPRESSION: a changed prose
+ * expression re-runs clean and changes nothing, and Postgres normalises the
+ * stored expression, so comparing it to this string would only produce false
+ * rebuilds. The column is derived from `content`, so dropping it loses nothing.
+ * Run it BEFORE declaring the column in a Prisma schema: `prisma db push` reads
+ * a generated column it does not know about as drift and drops it.
+ */
+export declare function searchTsvDdl(table: string, { content, title }?: {
+    content?: string;
+    title?: string;
+}): {
+    column: string[];
+    index: string;
+};
 /**
  * `ts_headline` options for a search result snippet: one fragment, wide enough
  * to read as a sentence, with no highlight markers (the caller styles it).

package/dist/search.js

@@ -60,6 +60,28 @@ export function searchTsvSql(content = 'content', title = 'title') {
     return `setweight(to_tsvector('english', coalesce(${title},'')), 'A') || ` +
         `setweight(to_tsvector('english', coalesce(${proseSql(content)}, '')), 'B')`;
 }
+/**
+ * The statements that (re)build a table's `search_tsv` column and its GIN index.
+ * Run `column` inside one transaction: DROP then ADD, so no reader ever sees
+ * the table without it; then `index`.
+ *
+ * Rebuilt unconditionally rather than skipped when the column exists. A skip
+ * is idempotent about the column and blind to its EXPRESSION: a changed prose
+ * expression re-runs clean and changes nothing, and Postgres normalises the
+ * stored expression, so comparing it to this string would only produce false
+ * rebuilds. The column is derived from `content`, so dropping it loses nothing.
+ * Run it BEFORE declaring the column in a Prisma schema: `prisma db push` reads
+ * a generated column it does not know about as drift and drops it.
+ */
+export function searchTsvDdl(table, { content = 'content', title = 'title' } = {}) {
+    return {
+        column: [
+            `ALTER TABLE ${table} DROP COLUMN IF EXISTS search_tsv`,
+            `ALTER TABLE ${table} ADD COLUMN search_tsv tsvector GENERATED ALWAYS AS (${searchTsvSql(content, title)}) STORED`,
+        ],
+        index: `CREATE INDEX IF NOT EXISTS ${table}_search_tsv_idx ON ${table} USING GIN (search_tsv)`,
+    };
+}
 /**
  * `ts_headline` options for a search result snippet: one fragment, wide enough
  * to read as a sentence, with no highlight markers (the caller styles it).

package/dist/text.d.ts

@@ -27,6 +27,8 @@ export declare const BANNER_VARIANTS: ReadonlyArray<{
     value: BannerVariant;
     label: string;
 }>;
+/** A stored variant this package knows, or `cleanup` for one it does not. */
+export declare function bannerVariant(variant: string): BannerVariant;
 /** A maintenance notice, inline: `[Notice: Needs citations] …`. */
 export declare function bannerToText(label: string, text?: string | null): string;
 /** Each tab under its label, tags stripped — highlighted markup is noise here. */

package/dist/text.js

@@ -50,6 +50,10 @@ export const BANNER_VARIANTS = Object.keys(BANNER_LABELS).map(value => ({
     value,
     label: BANNER_LABELS[value],
 }));
+/** A stored variant this package knows, or `cleanup` for one it does not. */
+export function bannerVariant(variant) {
+    return Object.hasOwn(BANNER_LABELS, variant) ? variant : 'cleanup';
+}
 /** A maintenance notice, inline: `[Notice: Needs citations] …`. */
 export function bannerToText(label, text) {
     return `[Notice: ${label}]${text ? ' ' + stripHtml(text) : ''}`;

package/dist/tiptap.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import { Node as TiptapNode } from '@tiptap/core';
+import { Extension, Node as TiptapNode } from '@tiptap/core';
 /** Local `cn`. Both wikis import one; the package will not depend on one. */
 export declare const Iframe: TiptapNode<any, any>;
 /** The stock extension plus the paste rule it does not ship with. */
@@ -76,3 +76,16 @@ export declare function createTabs({ classNames, icons, tabLabel, }?: TabsOption
     TabGroup: TiptapNode<any, any>;
     TabItem: TiptapNode<any, any>;
 };
+/**
+ * Gives each heading in the editor the id its published copy will carry, so an
+ * "on this page" rail can list it while the page is being written.
+ *
+ * A decoration, not an attribute: the id is in the editor's DOM and never in
+ * `getHTML()`, so stored HTML stays id-free and `injectHeadingIds` still mints
+ * the published ids. Pass the same `slug` the wiki passes there. The dedupe is
+ * `uniqueHeadingId`, the one `injectHeadingIds` uses; the copy this replaced
+ * restated it, and would have drifted the first time either changed.
+ */
+export declare function createHeadingIds({ slug }?: {
+    slug?: (text: string) => string;
+}): Extension<any, any>;

package/dist/tiptap.js

@@ -12,7 +12,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // and the other `text-accent` without either forking the node. It also keeps
 // this file from dragging an icon library in behind it.
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { Node as TiptapNode, mergeAttributes } from '@tiptap/core';
+import { Extension, Node as TiptapNode, mergeAttributes } from '@tiptap/core';
+import { Plugin } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
 import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from '@tiptap/react';
 import TiptapYoutube from '@tiptap/extension-youtube';
 import TiptapCodeBlock from '@tiptap/extension-code-block';
@@ -20,6 +22,7 @@ import { onTweetResize, tweetEmbedSrc } from './dom.js';
 import { toMapEmbedUrl } from './maps.js';
 import { useClickOutside } from './react.js';
 import { cx } from './html.js';
+import { slugifyHeading, uniqueHeadingId } from './headings.js';
 /** Local `cn`. Both wikis import one; the package will not depend on one. */
 // ---- iframe -----------------------------------------------------------------
 export const Iframe = TiptapNode.create({
@@ -336,3 +339,40 @@ export function createTabs({ classNames = {}, icons = {}, tabLabel = i => `Tab $
     });
     return { TabGroup, TabItem };
 }
+// ---- heading ids while editing ---------------------------------------------------
+/**
+ * Gives each heading in the editor the id its published copy will carry, so an
+ * "on this page" rail can list it while the page is being written.
+ *
+ * A decoration, not an attribute: the id is in the editor's DOM and never in
+ * `getHTML()`, so stored HTML stays id-free and `injectHeadingIds` still mints
+ * the published ids. Pass the same `slug` the wiki passes there. The dedupe is
+ * `uniqueHeadingId`, the one `injectHeadingIds` uses; the copy this replaced
+ * restated it, and would have drifted the first time either changed.
+ */
+export function createHeadingIds({ slug = slugifyHeading } = {}) {
+    return Extension.create({
+        name: 'headingIds',
+        addProseMirrorPlugins: () => [
+            new Plugin({
+                props: {
+                    decorations: ({ doc }) => {
+                        const used = new Set();
+                        const decorations = [];
+                        doc.descendants((node, pos) => {
+                            if (node.type.name !== 'heading')
+                                return;
+                            const id = uniqueHeadingId(slug(node.textContent), used);
+                            if (!id)
+                                return false;
+                            used.add(id);
+                            decorations.push(Decoration.node(pos, pos + node.nodeSize, { id }));
+                            return false;
+                        });
+                        return DecorationSet.create(doc, decorations);
+                    },
+                },
+            }),
+        ],
+    });
+}

package/dist/well-known.d.ts

@@ -1,3 +1,4 @@
+import type { License } from './license.js';
 export interface RegistryAuthRecord {
     body: string;
     contentType: string;
@@ -48,13 +49,6 @@ export interface SkillSource {
  * capability the server does not have. `search_pages` becomes "Search Pages".
  */
 export declare function skillsFromTools(tools: readonly SkillSource[]): AgentSkill[];
-export interface AgentCardLicense {
-    name: string;
-    url: string;
-    spdx?: string;
-    /** What the licence covers, e.g. `'content'`. */
-    scope?: string;
-}
 export interface AgentCardConfig {
     name: string;
     description: string;
@@ -62,7 +56,10 @@ export interface AgentCardConfig {
     url: string;
     version: string;
     skills: AgentSkill[];
-    license?: AgentCardLicense;
+    /** The grant, as `ccBy40()` builds it. Projected once here, not per repo. */
+    license?: License;
+    /** What the grant covers, e.g. `'content'`, or which half of the site. */
+    licenseScope?: string;
     /** Defaults to `name`. */
     organization?: string;
     /** Defaults to `${url}/llms.txt`. */
@@ -127,3 +124,45 @@ protocolVersions: readonly string[]): Record<string, unknown>;
  * configured" instead of failing verification for a reason nobody sees.
  */
 export declare function registryAuthHandler(publicKey?: string | undefined, keyType?: string | undefined): () => Response;
+/** A tool as `/.well-known/mcp.json` lists it: what tools/list says, no handler. */
+export interface ManifestTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: unknown;
+    annotations?: unknown;
+}
+export interface McpManifestConfig {
+    /** The server's display name. */
+    name: string;
+    /** Its registry name, from server.json. */
+    registryName: string;
+    version: string;
+    description: string;
+    /** Origin, no trailing slash. */
+    url: string;
+    /** Who runs it. Defaults to `name`. */
+    provider?: string;
+    tools: readonly ManifestTool[];
+    /** Auth notes, per-tenant endpoints, payment terms — what this origin has that others do not. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * `/.well-known/mcp.json`: the third path an arriving agent probes, after the
+ * agent card and the OpenAPI spec. All three origins wrote the same envelope,
+ * and one had already dropped the tool titles the other two listed. The
+ * protocol versions and the rate limit come from the transport that answers,
+ * so the manifest cannot advertise a version the server does not speak.
+ */
+export declare function mcpManifest(config: McpManifestConfig): Record<string, unknown>;
+/**
+ * A GET handler serving a descriptor built from code: ETag, 304, freshness.
+ * The agent cards, the manifest and the server card were each a three-line
+ * route around `descriptorResponse`, written out nine times.
+ */
+export declare function descriptorHandler(body: unknown, opts?: {
+    maxAge?: number;
+    extra?: Record<string, string>;
+}): (request: Request) => Response;
+/** The whole `<mcp-url>/server-card` route, projected from server.json. */
+export declare const serverCardHandler: (manifest: ServerManifest) => ((request: Request) => Response);

package/dist/well-known.js

@@ -9,6 +9,9 @@
 // Nothing here touches a framework: these return plain values, and the caller
 // wraps them in whatever its router wants. That keeps this package free of a
 // Next dependency and keeps each app's route a two-liner.
+import { MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS } from './mcp.js';
+import { MCP_RATE_LIMIT_TEXT } from './rate-limit.js';
+import { descriptorResponse } from './http.js';
 /**
  * The `v=MCPv1` record the official MCP registry fetches from
  * `/.well-known/mcp-registry-auth` to prove domain ownership. `mcp-publisher
@@ -70,7 +73,7 @@ const A2A_PROTOCOL_VERSION = '0.3.0';
  * means half the callers conclude the origin has no agent at all.
  */
 export function agentCard(config) {
-    const { name, description, url, version, skills, license, organization, documentationUrl, mcpEndpoint, extra } = config;
+    const { name, description, url, version, skills, license, licenseScope, organization, documentationUrl, mcpEndpoint, extra } = config;
     const endpoint = mcpEndpoint === null ? url : (mcpEndpoint ?? `${url}/api/mcp`);
     return {
         protocolVersion: A2A_PROTOCOL_VERSION,
@@ -89,7 +92,14 @@ export function agentCard(config) {
         provider: { organization: organization ?? name, url },
         documentationUrl: documentationUrl ?? `${url}/llms.txt`,
         ...(mcpEndpoint === null ? {} : { mcpEndpoint: endpoint }),
-        ...(license ? { license } : {}),
+        // The same two discovery URLs on every card. The three cards here named the
+        // spec `apiSpecUrl`, `apiSpecUrl` and `openapiUrl`, and one omitted the
+        // server card, so a client reading one card could not read the next.
+        apiSpecUrl: `${url}/.well-known/openapi.json`,
+        ...(mcpEndpoint === null ? {} : { mcpServerCard: `${endpoint}/server-card` }),
+        ...(license
+            ? { license: { name: license.name, spdx: license.spdx, url: license.url, ...(licenseScope ? { scope: licenseScope } : {}) } }
+            : {}),
         ...extra,
         defaultInputModes: ['text/plain', 'application/json'],
         defaultOutputModes: ['text/plain', 'application/json', 'text/markdown'],
@@ -155,3 +165,49 @@ export function registryAuthHandler(publicKey = process.env.MCP_REGISTRY_PUBLIC_
         });
     };
 }
+/**
+ * `/.well-known/mcp.json`: the third path an arriving agent probes, after the
+ * agent card and the OpenAPI spec. All three origins wrote the same envelope,
+ * and one had already dropped the tool titles the other two listed. The
+ * protocol versions and the rate limit come from the transport that answers,
+ * so the manifest cannot advertise a version the server does not speak.
+ */
+export function mcpManifest(config) {
+    const { name, registryName, version, description, url, provider, tools, extra } = config;
+    return {
+        schema_version: '1.0',
+        name,
+        registryName,
+        version,
+        description,
+        url,
+        provider: { name: provider ?? name, url },
+        api: { type: 'openapi', url: `${url}/.well-known/openapi.json` },
+        mcp: {
+            endpoint: `${url}/api/mcp`,
+            transport: 'streamable-http',
+            protocol: 'JSON-RPC 2.0',
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            supportedProtocolVersions: MCP_PROTOCOL_VERSIONS,
+            rateLimit: MCP_RATE_LIMIT_TEXT,
+        },
+        ...extra,
+        tools: tools.map(({ name, title, description, inputSchema, annotations }) => ({
+            name,
+            ...(title ? { title } : {}),
+            description,
+            inputSchema,
+            ...(annotations ? { annotations } : {}),
+        })),
+    };
+}
+/**
+ * A GET handler serving a descriptor built from code: ETag, 304, freshness.
+ * The agent cards, the manifest and the server card were each a three-line
+ * route around `descriptorResponse`, written out nine times.
+ */
+export function descriptorHandler(body, opts = {}) {
+    return request => descriptorResponse(request, body, opts);
+}
+/** The whole `<mcp-url>/server-card` route, projected from server.json. */
+export const serverCardHandler = (manifest) => descriptorHandler(serverCard(manifest, MCP_PROTOCOL_VERSIONS));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -167,6 +167,10 @@
     "./corpus": {
       "types": "./dist/corpus.d.ts",
       "import": "./dist/corpus.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata.d.ts",
+      "import": "./dist/metadata.js"
     }
   },
   "bin": {
@@ -223,7 +227,8 @@
     "@tiptap/starter-kit": ">=2.10",
     "jose": ">=5",
     "react": ">=18",
-    "sanitize-html": ">=2"
+    "sanitize-html": ">=2",
+    "@tiptap/pm": ">=2.10"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -273,6 +278,9 @@
     },
     "sanitize-html": {
       "optional": true
+    },
+    "@tiptap/pm": {
+      "optional": true
     }
   }
 }