wiki-formant 0.22.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.
 
@@ -269,6 +274,10 @@ 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.
@@ -280,6 +289,8 @@ are unit-tested without a DOM.
 
 `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
@@ -332,6 +343,12 @@ export const generateMetadata = () => ({
 });
 ```
 
+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
@@ -366,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
@@ -437,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';
@@ -470,6 +497,8 @@ The ones that take config take it because that is exactly where the two copies d
 
 `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
@@ -500,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

package/dist/block-views.js

@@ -23,18 +23,16 @@ 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
- * 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.
@@ -43,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 ---------------------------------------------------------------
 /**
@@ -71,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

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>;

package/dist/conformance.js

@@ -40,20 +40,26 @@ export function createTester(opts) {
     const endpoint = opts.endpoint ?? `${base}/api/mcp`;
     const results = [];
     let calls = 0;
+    // The server's own rate limit is part of what is under test elsewhere; here
+    // it is noise, so it is waited out — for as long as `Retry-After` says, and a
+    // bounded number of times. This used to say "once" and recurse forever at a
+    // fixed 5s, so a suite pointed at a budget it could never get under hung.
+    const RETRIES = 4;
     const rpc = async (method, params) => {
-        calls++;
-        const res = await fetch(endpoint, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'User-Agent': opts.clientName },
-            body: JSON.stringify({ jsonrpc: '2.0', id: calls, method, params }),
-        });
-        // The server's own rate limit is part of what is under test elsewhere; here
-        // it is just noise, so wait it out once rather than failing the run.
-        if (res.status === 429) {
-            await new Promise(r => setTimeout(r, 5000));
-            return rpc(method, params);
+        for (let attempt = 1;; attempt++) {
+            calls++;
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'User-Agent': opts.clientName },
+                body: JSON.stringify({ jsonrpc: '2.0', id: calls, method, params }),
+            });
+            if (res.status !== 429)
+                return (await res.json());
+            if (attempt === RETRIES)
+                throw new Error(`${method}: still rate-limited after ${RETRIES} tries`);
+            const wait = Number(res.headers.get('retry-after'));
+            await new Promise(r => setTimeout(r, Math.min(60, Number.isFinite(wait) && wait > 0 ? wait : 5) * 1000));
         }
-        return (await res.json());
     };
     return {
         base,

package/dist/editor.d.ts

@@ -1,5 +1,5 @@
 import type { AnyExtension, Editor } from '@tiptap/core';
-import { type ChangeEvent, type RefObject } from 'react';
+import { type ChangeEvent, type ReactNode, type RefObject } from 'react';
 /**
  * Re-exported so the COMMAND AUGMENTATIONS reach consumers.
  *
@@ -46,6 +46,38 @@ 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>];
+/** Run one of `TABLE_ACTIONS` — the one place the command name is looked up untyped. */
+export declare function runTableAction(editor: Editor, command: string): void;
+export type ToolbarKey = 'bold' | 'italic' | 'code' | 'link' | 'h2' | 'h3' | 'h4' | 'bulletList' | 'orderedList' | 'blockquote' | 'codeBlock' | 'divider' | 'table' | 'tabs';
+export interface ToolbarAction {
+    key: ToolbarKey;
+    /** What a screen reader announces and a tooltip shows. */
+    label: string;
+    active?: ActiveDescriptor;
+    /** Absent on `link`, which needs a URL: call `withUrl` once you have one. */
+    run?: (editor: Editor) => void;
+    withUrl?: (editor: Editor, url: string) => void;
+}
+/**
+ * The formatting commands, labelled. Three toolbars ran these identically and
+ * two titled their buttons with the internal key — a screen reader said
+ * "codeBlock", and inline code and code block shared one icon and one name.
+ * Upload and embed stay with the caller: they are the parts that differ.
+ */
+export declare const TOOLBAR_ACTIONS: readonly ToolbarAction[];
+/** The actions a toolbar shows, in the order it shows them. */
+export declare function toolbarActions(keys: readonly ToolbarKey[]): ToolbarAction[];
+/**
+ * A toolbar button that says what it is and whether it is on. `aria-pressed`
+ * is right here, unlike on a facet link: this is a toggle.
+ */
+export declare function ToolbarButton({ label, pressed, onPress, className, children, }: {
+    label: string;
+    pressed?: boolean;
+    onPress: () => void;
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
  * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
  * back. Two editors carried it character for character, `alert` included.

package/dist/editor.js

@@ -1,4 +1,5 @@
 'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
 // editor.tsx — the wiki rich-text editor's engine, minus its chrome.
 //
 // `tiptap.tsx` holds the custom NODES both wikis needed (iframe, tweet, map,
@@ -136,6 +137,63 @@ export const TABLE_ACTIONS = [
     ['deleteRow', '-Row', true],
     ['deleteTable', '-Tbl', true],
 ];
+/** Run one of `TABLE_ACTIONS` — the one place the command name is looked up untyped. */
+export function runTableAction(editor, command) {
+    const chain = editor.chain().focus();
+    chain[command]?.().run();
+}
+/**
+ * The formatting commands, labelled. Three toolbars ran these identically and
+ * two titled their buttons with the internal key — a screen reader said
+ * "codeBlock", and inline code and code block shared one icon and one name.
+ * Upload and embed stay with the caller: they are the parts that differ.
+ */
+export const TOOLBAR_ACTIONS = [
+    { key: 'bold', label: 'Bold', active: 'bold', run: e => e.chain().focus().toggleBold().run() },
+    { key: 'italic', label: 'Italic', active: 'italic', run: e => e.chain().focus().toggleItalic().run() },
+    { key: 'code', label: 'Inline code', active: 'code', run: e => e.chain().focus().toggleCode().run() },
+    { key: 'link', label: 'Link', active: 'link', withUrl: (e, href) => e.chain().focus().setLink({ href }).run() },
+    { key: 'h2', label: 'Heading 2', active: ['heading', { level: 2 }], run: e => e.chain().focus().toggleHeading({ level: 2 }).run() },
+    { key: 'h3', label: 'Heading 3', active: ['heading', { level: 3 }], run: e => e.chain().focus().toggleHeading({ level: 3 }).run() },
+    { key: 'h4', label: 'Heading 4', active: ['heading', { level: 4 }], run: e => e.chain().focus().toggleHeading({ level: 4 }).run() },
+    { key: 'bulletList', label: 'Bulleted list', active: 'bulletList', run: e => e.chain().focus().toggleBulletList().run() },
+    { key: 'orderedList', label: 'Numbered list', active: 'orderedList', run: e => e.chain().focus().toggleOrderedList().run() },
+    { key: 'blockquote', label: 'Quote', active: 'blockquote', run: e => e.chain().focus().toggleBlockquote().run() },
+    { key: 'codeBlock', label: 'Code block', active: 'codeBlock', run: e => e.chain().focus().toggleCodeBlock().run() },
+    { key: 'divider', label: 'Divider', run: e => e.chain().focus().setHorizontalRule().run() },
+    {
+        key: 'table',
+        label: 'Table',
+        active: 'table',
+        run: e => e.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run(),
+    },
+    {
+        key: 'tabs',
+        label: 'Tabs',
+        active: 'tabGroup',
+        // Two, not one: a group of one is a heading with extra steps, and the node
+        // refuses to delete its last tab anyway.
+        run: e => e
+            .chain()
+            .focus()
+            .insertContent({
+            type: 'tabGroup',
+            content: [1, 2].map(n => ({ type: 'tabItem', attrs: { title: `Tab ${n}` }, content: [{ type: 'paragraph' }] })),
+        })
+            .run(),
+    },
+];
+/** The actions a toolbar shows, in the order it shows them. */
+export function toolbarActions(keys) {
+    return keys.flatMap(key => TOOLBAR_ACTIONS.filter(a => a.key === key));
+}
+/**
+ * A toolbar button that says what it is and whether it is on. `aria-pressed`
+ * is right here, unlike on a facet link: this is a toggle.
+ */
+export function ToolbarButton({ label, pressed, onPress, className, children, }) {
+    return (_jsx("button", { type: "button", title: label, "aria-label": label, "aria-pressed": pressed, className: className, onClick: onPress, children: children }));
+}
 // ---- the editor -------------------------------------------------------------
 /**
  * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`

package/dist/feed.d.ts

@@ -54,3 +54,13 @@ export interface FeedChannel {
  */
 export declare function renderFeed(channel: FeedChannel, items: readonly FeedItem[]): string;
 export declare const FEED_HEADERS: Record<string, string>;
+/**
+ * The feed as a response, with the validators a poller revalidates against.
+ *
+ * All four feeds in the workspace were `new Response(renderFeed(...))` with
+ * `Cache-Control: public` and no ETag or Last-Modified, so a reader polling
+ * hourly could never be told "unchanged" and took the whole channel every time.
+ * The tag comes from the rendered XML, so it moves exactly when the feed does;
+ * Last-Modified is the channel's build date.
+ */
+export declare function feedResponse(request: Request, channel: FeedChannel, items: readonly FeedItem[], headers?: Record<string, string>): Response;