wiki-formant 0.21.0 → 0.23.0

package/README.md

@@ -78,7 +78,12 @@ const toc  = headingsFrom(html);            // [{ id, text, level }]
 Two behaviours worth knowing:
 
 - **The slug rule is a parameter.** A heading id is a live URL — readers link to `#the-shape-of-a-code`, and so does the page's own permalink anchor. The two wikis this was lifted from had drifted onto different rules, and unifying them would have silently moved every published anchor on whichever one lost. Pass `slug` to keep the rule you already ship.
-- **Deduping is not a parameter.** Two headings with the same text otherwise mint the same id twice, and every link to the second lands on the first. The copy that lacked it had that bug.
+- **Deduping is not a parameter, but its scope is.** Two headings with the same text otherwise mint the same id twice, and every link to the second lands on the first. The unit that must be unique is the page, so a block wiki that injects block by block passes one `used` set to every call — seeded with any id the template renders itself, such as the title's. All three consumers once passed none, and a heading repeated across two blocks shipped two identical ids.
+
+```ts
+const used = new Set([slug(page.title)]);
+const blocks = page.blocks.map(b => ({ ...b, text: injectHeadingIds(b.text, { used }) }));
+```
 
 `headingsFrom` reads the string, not the rendered DOM — possible only where the body IS a string at render time. A wiki whose content streams in as blocks after mount has to query the DOM, and uses only the injector.
 
@@ -165,6 +170,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 +199,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';
 
@@ -265,16 +274,23 @@ const { inputProps, listProps, optionProps } = combobox();
 The arithmetic is `wiki-formant/combobox`, which imports nothing, so the rules
 are unit-tested without a DOM.
 
+`SortHeader` is the React half of `sortTables`: spread `useTableSort`'s `headerProps(key)` onto it and it renders a `<th aria-sort>` holding a `<button>`, the markup `sortTables` writes into stored tables, so one stylesheet rule draws both arrows. One of the copies it replaced put `onClick` on the cell, which no keyboard can reach.
+
+`useBlockOperations(blocks, setBlocks, { duplicate })` is the five list edits every block editor makes, with ref-stable callbacks, and `BlockActions` is their button bar — every button named, the moves disabled at the ends, clicks kept from bubbling into a row that selects on click. `useRevisionRestore(restore, { onRestored })` confirms, restores and reports an error; `restoreViaPost(endpoint)` is the `restore` for a wiki whose route takes `{ revisionId }`. Of the three restores it replaced, one asked no confirmation and one dropped a failure silently.
+
 ## Server components
 
 `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.
 
 `RailShell` stays in `wiki-formant/react`, because it calls `useSidebar` and genuinely is a client component. It renders the rail's landmark, its scroll wrapper and the three collapse states — including the `--instant` class that keeps a remembered-closed rail from animating shut on first paint, and the close-on-tap that a mobile rail needs. Compose your own rail inside it and mark the active link with `isRailLinkActive`; all three wikis do, and the pre-composed component that used to sit here had one consumer and had already lost both of those behaviours.
 
+`FacetSummary` is the line under the facet bar — how much of the section is showing, and a Clear link when anything is narrowed — with the filtered-empty and empty-section states. `RelatedPages` is the see-also list: a labelled `<aside>` over a `<ul>`, its heading linked to the set `rankRelated` found in common. `InfoboxAside` is the facts panel's named landmark with its "Part of a series on" line, and `InfoboxFacts` renders `metadataRows` as a row-headed table. That table was an HTML string in two wikis, injected as a fake content block; one re-escaped a `"` before each href by hand and the other did not. As React nodes there is nothing to escape. `formatFactValue` is its default cell: a date as its day, a URL or bare domain as an outbound link, `<br>`-separated values as lines.
+
 All three take the router's link component as a prop:
 
 ```tsx
@@ -314,6 +330,25 @@ 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 }),
+});
+```
+
+The schema.org nodes sit beside it, because they state the same facts to a different reader. `articleLd` requires `image` — two of three wikis shipped articles without one while their og:image named a card — so pass it the card `pageMetadata` got. `collectionLd` is an index page over an `ItemList`, and `citationsFromReferences` turns a `references` block into `Article.citation`.
+
+```tsx
+<JsonLd data={articleLd({ headline: title, url, image, published, modified, publisher: { '@id': `${SITE_URL}/#organization` }, citation: citationsFromReferences(refs) })} />
+```
+
 ## Revisions
 
 What changed between two versions of a page, and therefore which semver bump to
@@ -348,9 +383,11 @@ verbatim in two of them, the comment explaining why the apostrophe escapes
 numerically. `renderFeed` is the union.
 
 ```ts
-return new Response(renderFeed(channel, items), { headers: FEED_HEADERS });
+export const GET = async (request: Request) => feedResponse(request, channel, await items());
 ```
 
+`feedResponse` renders the channel and answers a conditional GET: the ETag is the XML's own, Last-Modified the build date. All four feeds used to return the XML bare, so a poller could never be told the channel was unchanged.
+
 **`lastBuildDate` comes from the newest item, not the clock.** One copy stamped
 `new Date()` on every request, telling every poller the feed had changed when it
 had not — the recrawl the conditional-GET helpers exist to prevent. An empty feed
@@ -358,6 +395,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 +405,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 +420,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:
@@ -410,9 +456,17 @@ if (issues.length) return badRequest(`Invalid content: ${describeBlockIssues(iss
 // Invalid content: [2].columns[0].blocks[1]: malformed linkGrid block
 ```
 
+A `codeTabs` tab's `code` is source text in every wiki here, and every view treats it that way: `CodeTabsView` escapes it into a `<pre><code>`, the sanitiser leaves it alone, the markdown twin fences it verbatim. A wiki that escapes and highlights on the server passes `highlighted` to the view. The package used to assume editors stored highlighted markup; none ever had, and every twin printed `Vec<u8>` as `Vec`.
+
+`recentPages` and `pageList` resolve to `ResolvedPageRef`s — build each with `pageRef(page, now)`, which carries the ISO date a `<time>` needs — and `PageRefsView` renders them as a list, with a `renderItem` slot for a wiki that has its own row.
+
+## 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`.
+
 ## Sanitising stored HTML
 
-`wiki-formant/sanitize` is the allowlist between an author's saved HTML and a reader's browser. The block views render three HTML fields themselves, and a repo renders `content.text` beside them, so the guard ships with the renderer. `sanitize-html` is an optional peer; run it server-side, on the render path, so it covers rows written before it existed and no sanitiser ships to the client.
+`wiki-formant/sanitize` is the allowlist between an author's saved HTML and a reader's browser. The block views render two HTML fields themselves — `linkGrid` descriptions and `references` text — and a repo renders `content.text` beside them, so the guard ships with the renderer. `codeTabs` is not one of them: its code is source. `sanitize-html` is an optional peer; run it server-side, on the render path, so it covers rows written before it existed and no sanitiser ships to the client.
 
 ```ts
 import { createHtmlSanitizer, sanitizeCoreLeaf } from 'wiki-formant/sanitize';
@@ -441,6 +495,10 @@ 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.
+
+`TOOLBAR_ACTIONS` are the formatting commands with the labels a screen reader announces — two toolbars titled buttons with the internal key, so one said "codeBlock". Pick yours in order with `toolbarActions([...])`, render each through `ToolbarButton` (named, and `aria-pressed`, since these are toggles), and run a table command with `runTableAction`. Upload and embed stay with the caller; they are the parts that differ.
+
 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
@@ -471,6 +529,16 @@ 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.
 
+## 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, 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.
+
+```css
+@import "wiki-formant/base.css" layer(components);
+```
+
+No view emits a Tailwind utility any more — `ColumnsView` states its gap and alignment as data attributes, and an inactive code tab is `hidden` — so a site no longer needs its Tailwind to scan this package for the markup to work.
+
 ## API
 
 Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on.

package/dist/base.css

@@ -0,0 +1,100 @@
+/* wiki-formant/base.css — the layout the package's markup does not work without.
+
+   Structure only: no colour, no type scale, no design token. Every value that
+   is a look rather than a mechanism is left to the importing stylesheet, which
+   loads this first and overrides anything here with an equally specific rule.
+
+     @import "wiki-formant/base.css" layer(components);
+
+   Three wikis had each restated these rules, and each had one missing: one
+   emitted the stored-tab and copy-button markup with no CSS for it, so every
+   panel showed at once; one never received the utility classes ColumnsView
+   used to emit, so two of its four alignments did nothing. */
+
+/* ---- ColumnsView ----------------------------------------------------------
+   Stacked until there is room for a row. `data-gap` and `data-align` replace
+   the Tailwind utilities the view used to emit, which only reached a site whose
+   Tailwind happened to scan node_modules. */
+.columns-layout {
+  display: flex;
+  flex-direction: column;
+  gap: var(--columns-gap, 1rem);
+}
+.columns-layout[data-gap='sm'] { --columns-gap: 0.5rem; }
+.columns-layout[data-gap='lg'] { --columns-gap: 1.5rem; }
+.columns-layout[data-align='start'] { align-items: flex-start; }
+.columns-layout[data-align='center'] { align-items: center; }
+.columns-layout[data-align='end'] { align-items: flex-end; }
+.columns-layout[data-align='stretch'] { align-items: stretch; }
+.column-view {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+@media (min-width: 48rem) {
+  .columns-layout { flex-direction: row; }
+  .column-view { flex: 1 1 0%; }
+}
+/* A stacked column is as wide as the row, whatever the alignment. */
+@media (max-width: 47.99rem) {
+  .columns-layout > .column-view { align-self: stretch; }
+}
+
+/* ---- stored tab groups (activateTabGroups) --------------------------------
+   Only the active panel shows. Before the script runs, the first tab's content
+   stands in for the group rather than every tab at once. */
+.tab-panel:not(.active) { display: none; }
+[data-tabs]:not([data-tabs-init]) [data-tab-item] ~ [data-tab-item] { display: none; }
+
+/* ---- code copy buttons (addCopyButtons) -----------------------------------
+   The script positions the <pre>; this pins the button in its corner. Shown
+   on hover, on keyboard focus, and always where there is no hover to show it. */
+.code-copy-btn {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  display: inline-flex;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 120ms ease;
+}
+pre:hover > .code-copy-btn,
+.code-copy-btn:focus-visible { opacity: 1; }
+@media (hover: none) {
+  .code-copy-btn { opacity: 1; }
+}
+
+/* ---- sortable headers (SortHeader, sortTables) ----------------------------
+   The arrow is read from `aria-sort` on the cell, so it cannot point one way
+   while the rows go the other. It is a mask over currentColor, so it takes the
+   header's colour, whatever that is. */
+.sort-header {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25em;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  text-align: inherit;
+  cursor: pointer;
+}
+.sort-header::after {
+  content: '';
+  flex: none;
+  width: 0.75em;
+  height: 0.75em;
+  background-color: currentColor;
+  opacity: 0.4;
+  --sort-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m7 15 5 5 5-5'/%3E%3Cpath d='m7 9 5-5 5 5'/%3E%3C/svg%3E");
+  mask: var(--sort-icon) center / contain no-repeat;
+}
+:is([aria-sort='ascending'], [aria-sort='descending']) > .sort-header::after { opacity: 1; }
+[aria-sort='ascending'] > .sort-header::after {
+  --sort-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m5 12 7-7 7 7'/%3E%3Cpath d='M12 19V5'/%3E%3C/svg%3E");
+}
+[aria-sort='descending'] > .sort-header::after {
+  --sort-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 5v14'/%3E%3Cpath d='m19 12-7 7-7-7'/%3E%3C/svg%3E");
+}

package/dist/block-views.d.ts

@@ -1,15 +1,22 @@
 import { type ReactNode } from 'react';
-import type { CodeTab, LinkGridGroup, ReferenceItem, StatItem } from './blocks.js';
+import type { CodeTab, LinkGridGroup, ReferenceItem, ResolvedPageRef, StatItem } from './blocks.js';
 import type { WikiLinkComponent } from './react-server.js';
+export interface CodeTabsViewProps {
+    tabs: readonly CodeTab[];
+    /**
+     * Every tab's `code` has already been escaped and highlighted into markup on
+     * the server, and is written as HTML. Only a wiki whose render path does that
+     * for every tree reaching this view may pass it: without it, `code` is source
+     * and renders escaped in a `<pre><code>`, which is the safe default.
+     */
+    highlighted?: boolean;
+}
 /**
  * Tabbed code samples. Every tab's body stays mounted and the inactive ones are
- * hidden rather than unmounted: the panels carry pre-highlighted markup, and
- * remounting one would re-run whatever the consumer's highlighter attached to
- * it on every tab press.
+ * hidden rather than unmounted: remounting a highlighted panel would re-run
+ * whatever the consumer's highlighter attached to it on every tab press.
  */
-export declare function CodeTabsView({ tabs }: {
-    tabs: readonly CodeTab[];
-}): import("react").JSX.Element | null;
+export declare function CodeTabsView({ tabs, highlighted }: CodeTabsViewProps): import("react").JSX.Element | null;
 export interface ColumnsViewProps<B extends {
     id: string;
 }> {
@@ -29,6 +36,10 @@ export interface ColumnsViewProps<B extends {
  * it was a layout bug rather than a style: `.column-view` is the flow context
  * its stylesheet spaces children in, and an extra element between them means
  * every gap rule inside a column silently matches nothing.
+ *
+ * Gap and alignment are data attributes that `wiki-formant/base.css` reads.
+ * They were Tailwind utilities, which reached a page only if the site's
+ * Tailwind scanned this package — and on one site `end` and `stretch` did not.
  */
 export declare function ColumnsView<B extends {
     id: string;
@@ -48,6 +59,23 @@ export declare function LinkGridView({ groups, intro, link: Link, }: {
     intro?: string;
     link?: WikiLinkComponent;
 }): import("react").JSX.Element;
+/**
+ * A list of resolved page references — the body of a `recentPages` or
+ * `pageList` block. A real list, with each age in a `<time>` carrying its ISO
+ * date: the copies this replaced were bare `<div>` rows, one emitted a
+ * `<time>` with no `dateTime`, and their empty states were three different
+ * things (a sentence, a different sentence, nothing).
+ *
+ * `renderItem` replaces the row's inner markup for a wiki with its own row
+ * component; the list, its semantics and the empty state stay here.
+ */
+export declare function PageRefsView({ refs, empty, link: Link, renderItem, }: {
+    refs: readonly ResolvedPageRef[];
+    /** Said when there are none. Omit to render nothing. */
+    empty?: string;
+    link?: WikiLinkComponent;
+    renderItem?: (ref: ResolvedPageRef) => ReactNode;
+}): import("react").JSX.Element | null;
 /**
  * The numbered citation list, with the `#cite-n` back-links the inline markers
  * point at. `processHtml` is a prop because only one wiki runs reference text
@@ -79,19 +107,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,18 +22,17 @@ import { Fragment, useState } from 'react';
 import { Anchor } from './react-server.js';
 import { safeLinkHref } from './validation.js';
 import { cx } from './html.js';
-// ---- codeTabs ---------------------------------------------------------------
+import { BANNER_LABELS, bannerVariant } from './text.js';
 /**
  * Tabbed code samples. Every tab's body stays mounted and the inactive ones are
- * hidden rather than unmounted: the panels carry pre-highlighted markup, and
- * remounting one would re-run whatever the consumer's highlighter attached to
- * it on every tab press.
+ * hidden rather than unmounted: remounting a highlighted panel would re-run
+ * whatever the consumer's highlighter attached to it on every tab press.
  */
-export function CodeTabsView({ tabs }) {
+export function CodeTabsView({ tabs, highlighted = false }) {
     const [activeTab, setActiveTab] = useState(0);
     if (!tabs.length)
         return null;
-    return (_jsxs("div", { className: "code-tabs", children: [_jsx("div", { className: "code-tabs-list", children: tabs.map((tab, i) => (_jsx("button", { type: "button", className: cx('code-tabs-btn', i === activeTab && 'code-tabs-btn-active'), onClick: () => setActiveTab(i), children: tab.label }, i))) }), tabs.map((tab, i) => (_jsx("div", { className: i === activeTab ? 'block' : 'hidden', dangerouslySetInnerHTML: { __html: tab.code } }, i)))] }));
+    return (_jsxs("div", { className: "code-tabs", children: [_jsx("div", { className: "code-tabs-list", children: tabs.map((tab, i) => (_jsx("button", { type: "button", className: cx('code-tabs-btn', i === activeTab && 'code-tabs-btn-active'), onClick: () => setActiveTab(i), children: tab.label }, i))) }), tabs.map((tab, i) => highlighted ? (_jsx("div", { className: "code-tabs-panel", hidden: i !== activeTab, dangerouslySetInnerHTML: { __html: tab.code } }, i)) : (_jsx("div", { className: "code-tabs-panel", hidden: i !== activeTab, children: _jsx("pre", { children: _jsx("code", { className: tab.language ? `language-${tab.language}` : undefined, children: tab.code }) }) }, i)))] }));
 }
 /**
  * A row of columns, each holding blocks the caller renders.
@@ -42,16 +41,13 @@ export function CodeTabsView({ tabs }) {
  * it was a layout bug rather than a style: `.column-view` is the flow context
  * its stylesheet spaces children in, and an extra element between them means
  * every gap rule inside a column silently matches nothing.
+ *
+ * Gap and alignment are data attributes that `wiki-formant/base.css` reads.
+ * They were Tailwind utilities, which reached a page only if the site's
+ * Tailwind scanned this package — and on one site `end` and `stretch` did not.
  */
 export function ColumnsView({ columns, gap = 'md', align = 'start', render, }) {
-    const gapClass = { sm: 'gap-2', md: 'gap-4', lg: 'gap-6' }[gap];
-    const alignClass = {
-        start: 'items-start',
-        center: 'items-center',
-        end: 'items-end',
-        stretch: 'items-stretch',
-    }[align];
-    return (_jsx("div", { className: cx('columns-layout', gapClass, alignClass), children: columns.map(col => (_jsx("div", { className: "column-view", children: (col.blocks ?? []).map(bl => (_jsx(Fragment, { children: render(bl) }, bl.id))) }, col.id))) }));
+    return (_jsx("div", { className: "columns-layout", "data-gap": gap, "data-align": align, children: columns.map(col => (_jsx("div", { className: "column-view", children: (col.blocks ?? []).map(bl => (_jsx(Fragment, { children: render(bl) }, bl.id))) }, col.id))) }));
 }
 // ---- linkGrid ---------------------------------------------------------------
 /**
@@ -70,6 +66,23 @@ export function LinkGridView({ groups, intro, link: Link = Anchor, }) {
                             return /^https?:\/\//.test(href) ? (_jsx("a", { href: href, target: "_blank", rel: "noopener", children: item.label }, i)) : (_jsx(Link, { href: href, children: item.label }, i));
                         }) })] }, group.id ?? gi)))] }));
 }
+// ---- recentPages / pageList -------------------------------------------------
+/**
+ * A list of resolved page references — the body of a `recentPages` or
+ * `pageList` block. A real list, with each age in a `<time>` carrying its ISO
+ * date: the copies this replaced were bare `<div>` rows, one emitted a
+ * `<time>` with no `dateTime`, and their empty states were three different
+ * things (a sentence, a different sentence, nothing).
+ *
+ * `renderItem` replaces the row's inner markup for a wiki with its own row
+ * component; the list, its semantics and the empty state stay here.
+ */
+export function PageRefsView({ refs, empty, link: Link = Anchor, renderItem, }) {
+    if (!refs.length)
+        return empty ? _jsx("p", { className: "page-refs-empty", children: empty }) : null;
+    return (_jsx("ul", { className: "page-refs", children: refs.map(ref => (_jsx("li", { children: renderItem ? (renderItem(ref)) : (_jsxs(Link, { href: ref.href, className: "page-ref", children: [_jsx("span", { className: "page-ref-title", children: ref.title }), ref.timeAgo &&
+                        (ref.updated ? (_jsx("time", { className: "page-ref-time", dateTime: ref.updated, children: ref.timeAgo })) : (_jsx("span", { className: "page-ref-time", children: ref.timeAgo })))] })) }, ref.href))) }));
+}
 // ---- references -------------------------------------------------------------
 /**
  * The numbered citation list, with the `#cite-n` back-links the inline markers
@@ -106,13 +119,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/blocks.d.ts

@@ -1,9 +1,30 @@
+import { type RelativeTimeStyle } from './freshness.js';
 import type { BlockGroup } from './revisions.js';
 export interface CodeTab {
     label: string;
     language?: string;
+    /** Source text, never markup: every view escapes it unless told otherwise. */
     code: string;
 }
+/**
+ * A page a `recentPages` or `pageList` block points at, resolved on the server
+ * so the list renders with no client fetch and no client clock. Build it with
+ * `pageRef`, which is what fills `updated`: a `<time>` with no `dateTime`
+ * states an age no machine can read.
+ */
+export interface ResolvedPageRef {
+    title: string;
+    href: string;
+    /** `relativeTime` of `updated`, as of the render. */
+    timeAgo?: string;
+    /** ISO timestamp. */
+    updated?: string;
+}
+export declare function pageRef(page: {
+    title: string;
+    href: string;
+    updatedAt: Date | string;
+}, now: number, style?: RelativeTimeStyle): ResolvedPageRef;
 export interface ReferenceItem {
     text: string;
     url?: string | null;
@@ -109,9 +130,11 @@ export declare function someBlock<B>(blocks: readonly B[], predicate: (block: B)
 /**
  * Fenced blocks, one per tab, each under its label.
  *
- * The editor stores highlighted code, so the tags come out before the fence
- * goes on — a fenced block full of `<span class="hljs-keyword">` is worse than
- * no code at all.
+ * `code` is source, so it goes in verbatim. This used to strip tags on the
+ * belief that editors stored highlighted markup; none of the three wikis ever
+ * did, and the strip turned `Vec<u8>` into `Vec` in every markdown twin. The
+ * fence outgrows any backtick run in the code, so a sample that itself
+ * contains a fence cannot close this one early.
  */
 export declare function codeTabsToMarkdown(tabs: readonly CodeTab[]): string;
 /** A maintenance notice as a blockquote. `label` is the caller's display string. */

package/dist/blocks.js

@@ -10,8 +10,16 @@
 // new block type is a compile error until it is handled) and the bodies come
 // from here. Each renderer takes the block's DATA rather than the block, which
 // keeps this file free of any one repo's type union.
-import { decodeEntities } from './markdown.js';
 import { htmlToMarkdown, inlineToMarkdown } from './markdown.js';
+import { relativeTime } from './freshness.js';
+export function pageRef(page, now, style = 'long') {
+    return {
+        title: page.title,
+        href: page.href,
+        timeAgo: relativeTime(page.updatedAt, now, { style }),
+        updated: new Date(page.updatedAt).toISOString(),
+    };
+}
 /**
  * The whole tree as markdown. Containers flatten in document order, because a
  * reader following prose does not have columns — and an agent quoting the page
@@ -139,13 +147,19 @@ export function someBlock(blocks, predicate, containers) {
 /**
  * Fenced blocks, one per tab, each under its label.
  *
- * The editor stores highlighted code, so the tags come out before the fence
- * goes on — a fenced block full of `<span class="hljs-keyword">` is worse than
- * no code at all.
+ * `code` is source, so it goes in verbatim. This used to strip tags on the
+ * belief that editors stored highlighted markup; none of the three wikis ever
+ * did, and the strip turned `Vec<u8>` into `Vec` in every markdown twin. The
+ * fence outgrows any backtick run in the code, so a sample that itself
+ * contains a fence cannot close this one early.
  */
 export function codeTabsToMarkdown(tabs) {
     return tabs
-        .map(t => `**${t.label}**\n\n\`\`\`${t.language || ''}\n${decodeEntities(t.code.replace(/<[^>]+>/g, '')).trim()}\n\`\`\``)
+        .map(t => {
+        const longest = Math.max(0, ...(t.code.match(/`+/g) ?? []).map(run => run.length));
+        const fence = '`'.repeat(Math.max(3, longest + 1));
+        return `**${t.label}**\n\n${fence}${t.language || ''}\n${t.code.trim()}\n${fence}`;
+    })
         .join('\n\n');
 }
 /** A maintenance notice as a blockquote. `label` is the caller's display string. */

package/dist/conformance.d.ts

@@ -66,7 +66,7 @@ export interface TesterOptions {
 export interface Tester {
     base: string;
     endpoint: string;
-    /** One JSON-RPC call. Backs off once and retries on a 429. */
+    /** One JSON-RPC call. Waits out a 429 as `Retry-After` asks, up to four tries. */
     rpc(method: string, params?: unknown): Promise<Rpc>;
     /** `tools/call` shorthand. */
     call(name: string, args?: Record<string, unknown>): Promise<Rpc>;
@@ -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.
  *