wiki-formant 0.105.1 → 0.107.0

package/README.md

@@ -40,7 +40,7 @@ const { items, total } = await store.search('validators', { take: 20 });
 await store.save({ tagPath, slug, content, authorId, message, baseVersion: page.version });
 ```
 
-- **A save is one statement**: the page update and its revision in a CTE guarded on the version read. A lost race, a stale `baseVersion`, a page deleted since or a rename onto a taken slug writes nothing and throws a 409 `HttpError`.
+- **A save is one statement**: the page update and its revision in a CTE guarded on the version read. A lost race, a stale `baseVersion`, a page deleted since or a rename onto a taken slug writes nothing and throws a 409 `HttpError` whose body names the reason as `conflict`: `stale` and `deleted` mean reload, `taken` means another slug (`ConflictReason`).
 - **The bump is the diff's**: added, removed or moved blocks are `major`, changed prose or title `minor`; `change` overrides it. A metadata-only save moves no version and writes no revision.
 - **History is diffed on read.** A revision stores the page as saved. `history(pageId, { limit })` reads one row more than it returns, so the oldest entry shown has its real predecessor.
 - **Listings carry a snippet, not the article**: `list`, `recent` and `byIds` drop `content`.
@@ -318,8 +318,8 @@ function LinkPreview() {
 - `RailShell` renders the rail's landmark, scroll wrapper and collapse states, and closes a mobile drawer on a followed link; mark the active link with `isRailLinkActive`. With `RailShell prefix="wiki-sidebar"` in a `.wiki-layout` beside `.wiki-layout__main`, `base.css` lays it out: a sticky column from 1024px, a drawer above the article below it. The site supplies `--rail-top`, `--rail-border` and the surface.
 - The breakpoint is known twice, in `matchMedia` and in CSS. `base.css` sets `--rail-floating: 1` inside its media query and the hook warns in development when the two disagree; a rail laid out by its own CSS sets the property the same way. `railBreakpointMismatch` and `readRailFloating` (`wiki-formant/sidebar`) are the mechanism.
 - `TableOfContents` is the "on this page" list with scroll-spy.
-- `useLinkPreview` is the hover card: one delegated listener, an intent delay, a grace period into the card, viewport clamping and a per-href cache. `LinkPreviewCard` is its markup (`link-preview-card`, `-banner`, `-body`, `-title`, `-excerpt`); a caller that must move the card passes its own `style`.
-- `useTypeahead` is the search field's state machine: a request-id guard, keyboard navigation, abort and a per-mount cache. `fetch` must be referentially stable. Its `combobox(listKey)` hands out `inputProps`, `listProps` and `optionProps(i)`, with `aria-activedescendant` omitted rather than emptied; `listKey` keeps two rendered lists' ids apart. The arithmetic is `wiki-formant/combobox`, which imports nothing.
+- `useLinkPreview` is the hover card: one delegated listener, an intent delay, a grace period into the card, viewport clamping and a per-href cache of answers; a `fetch` that throws is asked again on the next hover, a null is cached as no card. `LinkPreviewCard` is its markup (`link-preview-card`, `-banner`, `-body`, `-title`, `-excerpt`); a caller that must move the card passes its own `style`.
+- `useTypeahead` is the search field's state machine: a request-id guard, keyboard navigation, abort and a per-mount cache. `results` is `idle`, `searching`, `found` or `failed`, so "no results" is `found` with none and a failed search is never cached; `items` is the rows on screen. `fetch` must be referentially stable. Its `combobox(listKey)` hands out `inputProps`, `listProps` and `optionProps(i)`, with `aria-activedescendant` omitted rather than emptied; `listKey` keeps two rendered lists' ids apart. The arithmetic is `wiki-formant/combobox`, which imports nothing.
 - `useSnapRow` is a carousel as a scroll-snapped row: `step`, `go(i)` and `at`, no markup.
 - `useClickOutside` ignores a container hidden at the current breakpoint (`offsetParent`).
 - `useUnsavedChanges(dirty)` asks before leaving and returns `confirmLeave()` for a client-side navigation; `useSaveShortcut(save)` binds ⌘S / Ctrl+S; `useSearchShortcut(open)` is "/" to search, with `focusShown(input)`.
@@ -445,6 +445,7 @@ export const generateMetadata = () => ({
 ```
 
 - Next replaces `openGraph` and `twitter` per segment rather than merging, so `pageMetadata` sets both; `sitePageMetadata({ siteName, handle })` binds the fields every page's card needs.
+- `sitePageMetadata({ ..., card: `${SITE_URL}/og` })` binds the site's card route, and a page then passes `card: { title, eyebrow, description, banner }` in place of `image`. `cardUrl(base, fields)` is the same address for JSON-LD: empty fields left out, the order fixed, so one card has one URL.
 - `articleLd` requires `image`. `collectionLd` is an index over an `ItemList`. `siteGraphLd` is the Organization, WebSite and `WebAPI` `@graph` for the root layout, and `siteRefs(url)` hands out the same `@id`s for a page's `publisher` and `isPartOf`.
 - `questionPairs(html)` reads a FAQ from headings ending in `?`; `faqPageLd(pairs, url)` is null under two pairs.
 - `describe(text)` is a meta description from any prose within `DESCRIPTION_LIMIT` (160): whole sentences where they fill half, else cut at a word with an ellipsis.
@@ -585,7 +586,7 @@ const banner = freshnessBanner(page, Date.now(), { against: 'current sources and
 const queues = maintenanceQueues(pages, { href, required, nowMs, verify, listedIds });
 ```
 
-- `freshnessBanner` is the `outdated` banner once a page goes unchecked for `maxAgeDays` (180), or null.
+- `freshnessBanner` is the `outdated` banner once a page goes unchecked for `maxAgeDays` (180), or null. `freshnessAge` is the days since a page was verified, or edited if never, and null when it carries neither, which `isStale` counts as stale.
 - `maintenanceQueues` returns the outdated, orphaned, unsourced and missing-facts queues, empty ones dropped. Pass every page but the home page and the back office. `MaintenanceQueues` draws them on a `noindex` page.
 - `citation({ publisher, title, date, url })` (`wiki-formant/react-server`) is the line `Cite` shows.
 
@@ -669,7 +670,7 @@ const url = useUrlPrompt(editor, { resolveMapUrl });
 - `WikiToolbar` shows each command the editor's extensions support (`supports`) and nothing else, in fixed groups, with the table controls while the cursor is in a table.
 - `useUrlPrompt` is the link and embed field: it opens on the current link, unlinks on an emptied one, and closes when its editor changes.
 - `WikiLine` is a one-line field with its own `marks`, undo and `onFocus`, so one toolbar can drive the field last touched. Its `style` mark is `wikiTextStyle`: a font, colour and size on a run of words, which an article editor takes through `nodes` and an app's own controls set with `setTextStyle`.
-- A link is stored as its `href` and the `link` class only; whether it is external is decided at render by `articleHtml`'s `links` pass. `uploadImageTo('/api/upload')` is the `uploadImage` an editor passes.
+- A link is stored as its `href` and the `link` class only; whether it is external is decided at render by `articleHtml`'s `links` pass. `uploadImageTo('/api/upload')` is the `uploadImage` an editor passes: it resolves the URL or throws the route's reason, and `useWikiEditor`'s `upload` is `idle`, `uploading` or `failed` with that reason for the editor to show.
 
 ## Block editor
 
@@ -805,7 +806,7 @@ import { prismaConfig } from 'wiki-formant/db';
 export default defineConfig(prismaConfig(import.meta.dirname));
 ```
 
-`wiki-formant/scripts`: what a seed or sweep script shares: `withClient` (a `pg` client that rolls back on a throw and expires the cache tag after a write), `readPage`, `writeRevision` (refused if the page moved on), `upsertWikiPage`, the block builders `content`, `banner` and `infobox`, and `assertLinkShapes`.
+`wiki-formant/scripts`: what a seed or sweep script shares: `withClient` (a `pg` client that rolls back on a throw and expires the cache tag after a write), `readPage`, `writeRevision` (refused if the page moved on), `upsertWikiPage` (`created`, `updated` or `unchanged`), the block builders `content`, `banner` and `infobox`, and `assertLinkShapes`.
 
 ```ts
 import { withClient, readPage, writeRevision } from 'wiki-formant/scripts';
@@ -815,7 +816,7 @@ await withClient(async client => {
 }, { tag: 'wiki' });
 ```
 
-`wiki-formant/link-check`: `auditLinks`, each link once with the pages that carry it, probed with `probeExternal` or the checker's own, and `printLinkAudit`.
+`wiki-formant/link-check`: `auditLinks`, each link once with the pages that carry it, probed with `probeExternal` or the checker's own, and `printLinkAudit`. `verdictOf` reads a probe as `alive`, `dead`, `walled`, `tls` or `unreachable`; only `dead` lands in `brokenExternal`, the rest in `unverifiableExternal`, which a sweep confirms by hand and never strips.
 
 `wiki-formant/knip`: the shared knip configuration, spread into each app's `knip.ts`.
 

package/bin/check-pages.mjs

@@ -58,7 +58,7 @@ const get = async url => {
 
 // The sitemap is the URL list.
 async function sitemapUrls(origin) {
-  const seen = (await readSitemap(`${origin}/sitemap.xml`, url => fetch(url, { headers: { 'user-agent': UA } })).catch(() => [])).map(e => e.url);
+  const seen = (await readSitemap(`${origin}/sitemap.xml`, url => fetch(url, { headers: { 'user-agent': UA } }))).map(e => e.url);
   // A sitemap states absolute production URLs by definition, so pointing
   // --site at a dev server would otherwise crawl production and report the
   // build you were trying to replace. The path is what the sitemap contributes;
@@ -82,7 +82,12 @@ const descriptionOf = html => {
   return m ? (m[0].match(/content=["']([\s\S]*?)["']/i)?.[1] ?? '').trim() : null;
 };
 
-const urls = await sitemapUrls(site);
+// A sitemap that does not answer is a fault, not an empty site: read as no
+// URLs, a down sitemap passed the gate it exists to hold.
+const urls = await sitemapUrls(site).catch(e => {
+  console.error(`check-pages: ${site}/sitemap.xml could not be read: ${e.message}`);
+  process.exit(WARN_ONLY ? 0 : 1);
+});
 if (!urls.length) {
   console.log(`check-pages: no URLs in ${site}/sitemap.xml — nothing to check. Skipping.`);
   process.exit(0);

package/dist/editor.d.ts

@@ -157,9 +157,18 @@ export declare function useUrlPrompt(editor: Editor | null, options: {
 }): UrlPromptState;
 /**
  * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
- * back. Two editors carried it character for character, `alert` included.
+ * back, throwing the route's own reason when there is none.
  */
-export declare function uploadImageTo(endpoint: string): (file: File) => Promise<string | null>;
+export declare function uploadImageTo(endpoint: string): (file: File) => Promise<string>;
+/** An upload in the editor: the failure is the editor's to say, beside the field, not an `alert`. */
+export type UploadState = {
+    status: 'idle';
+} | {
+    status: 'uploading';
+} | {
+    status: 'failed';
+    error: string;
+};
 export interface WikiEditorOptions {
     value: string;
     onChange: (html: string) => void;
@@ -167,15 +176,15 @@ export interface WikiEditorOptions {
     nodes?: readonly AnyExtension[];
     /** The prose class the editor body renders under. */
     proseClass: string;
-    /** Upload a chosen file, returning its URL or null. The route is the app's. */
-    uploadImage: (file: File) => Promise<string | null>;
+    /** Upload a chosen file and resolve its URL; throw with the reason it failed. The route is the app's. */
+    uploadImage: (file: File) => Promise<string>;
     /** Debounce before `onChange` fires, in ms. */
     debounceMs?: number;
 }
 export interface WikiEditorState {
     editor: Editor | null;
     fileInputRef: RefObject<HTMLInputElement | null>;
-    isUploading: boolean;
+    upload: UploadState;
     handleFileChange: (e: ChangeEvent<HTMLInputElement>) => Promise<void>;
     /** Open the file picker — what an upload toolbar button calls. */
     triggerUpload: () => void;

package/dist/editor.js

@@ -395,34 +395,30 @@ export function useUrlPrompt(editor, options) {
 // ---- 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.
+ * back, throwing the route's own reason when there is none.
  */
 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;
-        }
+        const res = await fetch(endpoint, { method: 'POST', body: form }).catch(() => {
+            throw new Error('The upload did not reach the server. Try again.');
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok || !body.url)
+            throw new Error(body.error || 'The upload failed. Try again.');
+        return body.url;
     };
 }
+const UPLOAD_IDLE = { status: 'idle' };
 /**
  * The editor and its upload plumbing. `WikiToolbar` given the editor draws
  * the buttons its extensions allow; the icons and classes are the app's.
  */
 export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], proseClass, uploadImage, debounceMs = 150, }) {
     const fileInputRef = useRef(null);
-    const [isUploading, setIsUploading] = useState(false);
+    const [upload, setUpload] = useState(UPLOAD_IDLE);
+    const uploadAttempt = useRef(0);
     const initialValueRef = useRef(value);
     const onChangeRef = useRef(onChange);
     const debounceRef = useRef(undefined);
@@ -481,21 +477,26 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
         const file = e.target.files?.[0];
         if (!file || !editor)
             return;
-        setIsUploading(true);
+        // Cleared so choosing the same file twice in a row still fires a change.
+        if (fileInputRef.current)
+            fileInputRef.current.value = '';
+        // The state belongs to the latest upload: an earlier one landing late
+        // still places its picture but does not speak over the one in flight.
+        const attempt = ++uploadAttempt.current;
+        setUpload({ status: 'uploading' });
         try {
             const url = await uploadImage(file);
-            if (url)
-                editor.chain().focus().setImage({ src: url }).run();
+            editor.chain().focus().setImage({ src: url }).run();
+            if (attempt === uploadAttempt.current)
+                setUpload(UPLOAD_IDLE);
         }
-        finally {
-            setIsUploading(false);
-            // Cleared so choosing the same file twice in a row still fires a change.
-            if (fileInputRef.current)
-                fileInputRef.current.value = '';
+        catch (err) {
+            if (attempt === uploadAttempt.current)
+                setUpload({ status: 'failed', error: err instanceof Error ? err.message : 'The upload failed. Try again.' });
         }
     }, [editor, uploadImage]);
     const triggerUpload = useCallback(() => fileInputRef.current?.click(), []);
-    return { editor, fileInputRef, isUploading, handleFileChange, triggerUpload };
+    return { editor, fileInputRef, upload, handleFileChange, triggerUpload };
 }
 // A line's whole document is the line, so Enter has nowhere to go.
 const LineDoc = TiptapNode.create({

package/dist/freshness.d.ts

@@ -7,10 +7,13 @@ export interface FreshnessInput {
 /** Whole days between `date` and `now`, or null when there is no usable date. */
 export declare function daysSince(date: Date | string | null | undefined, now: number): number | null;
 /**
- * Stale when the page has never been verified, or was verified longer ago than
- * `maxAgeDays`. Falls back to `updatedAt` when `lastVerifiedAt` is unset: an
- * edit is a weaker signal than a verification, but it is a signal.
+ * Days since the page was last checked: since its verification, or, unverified,
+ * since its last edit, a weaker signal but a signal. Null when it carries
+ * neither, which is never fresh; a caller that read it as 0 called an undated
+ * page new.
  */
+export declare function freshnessAge(page: FreshnessInput, now: number): number | null;
+/** Stale when undated, or checked longer ago than `maxAgeDays`. */
 export declare function isStale(page: FreshnessInput, now: number, maxAgeDays?: number): boolean;
 export interface FreshnessOptions {
     /** Older than this, unverified, and the page is stale. */

package/dist/freshness.js

@@ -23,12 +23,17 @@ export function daysSince(date, now) {
     return Math.floor((now - t) / DAY_MS);
 }
 /**
- * Stale when the page has never been verified, or was verified longer ago than
- * `maxAgeDays`. Falls back to `updatedAt` when `lastVerifiedAt` is unset: an
- * edit is a weaker signal than a verification, but it is a signal.
+ * Days since the page was last checked: since its verification, or, unverified,
+ * since its last edit, a weaker signal but a signal. Null when it carries
+ * neither, which is never fresh; a caller that read it as 0 called an undated
+ * page new.
  */
+export function freshnessAge(page, now) {
+    return daysSince(page.lastVerifiedAt ?? page.updatedAt, now);
+}
+/** Stale when undated, or checked longer ago than `maxAgeDays`. */
 export function isStale(page, now, maxAgeDays = DEFAULT_MAX_AGE_DAYS) {
-    const age = daysSince(page.lastVerifiedAt ?? page.updatedAt, now);
+    const age = freshnessAge(page, now);
     return age === null || age > maxAgeDays;
 }
 /**

package/dist/link-check.d.ts

@@ -15,6 +15,28 @@ export interface Probe {
      */
     walled?: boolean;
 }
+/**
+ * What a probe says about a link. Only `dead` is grounds to touch a citation:
+ * a wall, a lapsed certificate and a host that did not answer in time are
+ * unverifiable, and a sweep that read them off `!ok` stripped good citations.
+ */
+export type LinkVerdict = {
+    kind: 'alive';
+} | {
+    kind: 'dead';
+    status: number;
+} | {
+    kind: 'walled';
+    status: number;
+} | {
+    kind: 'tls';
+    code: string;
+} | {
+    kind: 'unreachable';
+    error: string;
+};
+/** The one reading of a probe. A name that does not resolve is dead; any other failure to answer is not. */
+export declare function verdictOf(probe: Probe): LinkVerdict;
 export interface ProbeOptions {
     /** Ordinary per-attempt budget. */
     timeoutMs?: number;
@@ -94,11 +116,16 @@ export interface AuditOptions<B extends {
     concurrency?: number;
     containers?: (block: B) => B[][] | null;
 }
+export type AuditedLink = Probe & {
+    verdict: LinkVerdict;
+    pages: string[];
+};
 export interface LinkAudit {
     externalChecked: number;
-    brokenExternal: Array<Probe & {
-        pages: string[];
-    }>;
+    /** Links whose verdict is `dead`. */
+    brokenExternal: AuditedLink[];
+    /** Walled, TLS-failed or unanswered: confirm by hand, never strip. */
+    unverifiableExternal: AuditedLink[];
     brokenInternal: Array<{
         url: string;
         pages: string[];

package/dist/link-check.js

@@ -13,6 +13,18 @@
 import { stripTags } from './html.js';
 import { decodeEntities } from './markdown.js';
 import { coreBlockShape, leafBlocks } from './blocks.js';
+/** The one reading of a probe. A name that does not resolve is dead; any other failure to answer is not. */
+export function verdictOf(probe) {
+    if (probe.ok)
+        return { kind: 'alive' };
+    if (probe.walled)
+        return { kind: 'walled', status: probe.status };
+    if (probe.tls)
+        return { kind: 'tls', code: probe.tls };
+    if (probe.status === 0 && probe.code !== 'ENOTFOUND')
+        return { kind: 'unreachable', error: probe.error ?? probe.code ?? 'no answer' };
+    return { kind: 'dead', status: probe.status };
+}
 const DEFAULTS = { timeoutMs: 12_000, slowTimeoutMs: 40_000 };
 /**
  * TLS-verification failures are NOT death.
@@ -368,9 +380,11 @@ export async function auditLinks(pages, opts) {
     }
     const urls = [...external.keys()];
     const results = await mapLimit(urls, concurrency, url => probe(url));
+    const audited = results.map(r => ({ ...r, verdict: verdictOf(r), pages: external.get(r.url) }));
     return {
         externalChecked: urls.length,
-        brokenExternal: results.filter(r => !r.ok).map(r => ({ ...r, pages: external.get(r.url) })),
+        brokenExternal: audited.filter(r => r.verdict.kind === 'dead'),
+        unverifiableExternal: audited.filter(r => r.verdict.kind !== 'dead' && r.verdict.kind !== 'alive'),
         brokenInternal: [...internalLinks.entries()]
             .filter(([u]) => {
             const p = u.split('?')[0];
@@ -381,13 +395,17 @@ export async function auditLinks(pages, opts) {
         skipped,
     };
 }
+const verdictLabel = (v) => v.kind === 'walled' ? `walled ${v.status}` : v.kind === 'tls' ? `tls ${v.code}` : v.kind === 'unreachable' ? v.error : v.kind;
 /** The human report's first lines: what was checked, and what is broken. */
 export function printLinkAudit(audit, { scope = '(entire wiki)', pagesScanned }) {
     console.log(`\nLink check — scope: ${scope}`);
     console.log(`Pages scanned: ${pagesScanned} | external links checked: ${audit.externalChecked}`);
     console.log(`\nBroken external (${audit.brokenExternal.length}):`);
     for (const b of audit.brokenExternal)
-        console.log(`  [${b.status || b.code || b.error}] ${b.url}\n      ← ${b.pages.join(', ')}`);
+        console.log(`  [${b.status || b.code}] ${b.url}\n      ← ${b.pages.join(', ')}`);
+    console.log(`\nUnverifiable external — confirm by hand, never strip (${audit.unverifiableExternal.length}):`);
+    for (const b of audit.unverifiableExternal)
+        console.log(`  [${verdictLabel(b.verdict)}] ${b.url}\n      ← ${b.pages.join(', ')}`);
     console.log(`\nBroken internal (${audit.brokenInternal.length}):`);
     for (const b of audit.brokenInternal)
         console.log(`  ${b.url}\n      ← ${b.pages.join(', ')}`);

package/dist/metadata.d.ts

@@ -209,7 +209,10 @@ export declare function sitePageMetadata(site: {
     siteName: string;
     locale?: string;
     handle?: string;
-}): (o: Omit<PageMetadataOptions, "siteName" | "locale" | "handle">) => {
+    card?: string;
+}): ({ card, ...o }: Omit<PageMetadataOptions, "siteName" | "locale" | "handle"> & {
+    card?: CardFields;
+}) => {
     openGraph: {
         publishedTime?: string;
         modifiedTime?: string;
@@ -243,6 +246,26 @@ export declare function sitePageMetadata(site: {
         canonical: string;
     } | undefined;
 };
+/**
+ * What a generated card draws: the text, and a banner that replaces its art.
+ * Any other key is a parameter only one site's route reads, such as the palette
+ * a radix-wiki section picks.
+ */
+export interface CardFields {
+    title?: string;
+    eyebrow?: string;
+    description?: string;
+    banner?: string | null;
+    [param: string]: string | null | undefined;
+}
+/**
+ * The address of a card route drawing `fields`, e.g. `cardUrl(`${SITE_URL}/og`, { title })`.
+ * Empty fields are left out, and the order is fixed (title, eyebrow,
+ * description, any site key, banner) whatever order the caller wrote, so one
+ * card has one URL and the CDN and X cache it once. Three wikis each built this
+ * query string by hand; the route that reads it is each site's own.
+ */
+export declare function cardUrl(base: string, fields: CardFields): string;
 /** The `@id` references a page's own node points at for `publisher` and `isPartOf`. */
 export declare function siteRefs(url: string): {
     organization: LdNode;

package/dist/metadata.js

@@ -257,8 +257,30 @@ export function describe(text, limit = DESCRIPTION_LIMIT) {
  * locale at all of them.
  */
 export function sitePageMetadata(site) {
-    const bound = { locale: 'en_US', ...site };
-    return (o) => pageMetadata({ ...o, ...bound });
+    const { card: base, ...rest } = site;
+    const bound = { locale: 'en_US', ...rest };
+    return ({ card, ...o }) => {
+        if (card && !base)
+            throw new Error('sitePageMetadata: a page passed `card` but the site bound no card route');
+        return pageMetadata({ ...o, ...(card ? { image: cardUrl(base, card) } : {}), ...bound });
+    };
+}
+const CARD_HEAD = ['title', 'eyebrow', 'description'];
+/**
+ * The address of a card route drawing `fields`, e.g. `cardUrl(`${SITE_URL}/og`, { title })`.
+ * Empty fields are left out, and the order is fixed (title, eyebrow,
+ * description, any site key, banner) whatever order the caller wrote, so one
+ * card has one URL and the CDN and X cache it once. Three wikis each built this
+ * query string by hand; the route that reads it is each site's own.
+ */
+export function cardUrl(base, fields) {
+    const keys = [...CARD_HEAD, ...Object.keys(fields).filter(k => !CARD_HEAD.includes(k) && k !== 'banner'), 'banner'];
+    const q = new URLSearchParams();
+    for (const k of keys)
+        if (fields[k])
+            q.set(k, fields[k]);
+    const query = q.toString();
+    return query ? `${base}?${query}` : base;
 }
 /** The `@id` references a page's own node points at for `publisher` and `isPartOf`. */
 export function siteRefs(url) {

package/dist/queues.js

@@ -12,7 +12,7 @@
 // radix-wiki wrote it over its own Prisma rows; caper, acuiq2 and miow's wikis
 // had none. What differs is how a page is addressed and which facts its
 // category requires, so those are the arguments.
-import { daysSince, isStale, DEFAULT_MAX_AGE_DAYS } from './freshness.js';
+import { freshnessAge, isStale, DEFAULT_MAX_AGE_DAYS } from './freshness.js';
 import { metaValue } from './taxonomy.js';
 // An href inside stored JSON, its quotes escaped or not.
 const HREF = /href=\\?"([^"\\?#]+)/g;
@@ -66,7 +66,10 @@ export function maintenanceQueues(pages, o) {
             description: `Not checked or changed in ${maxAgeDays} days. Re-check the facts against current sources${o.verify ? `, then ${o.verify}` : ''}.`,
             items: pages
                 .filter(p => isStale(p, o.nowMs, maxAgeDays))
-                .map(p => item(p, `${daysSince(p.lastVerifiedAt ?? p.updatedAt, o.nowMs)} days`)),
+                .map(p => {
+                const age = freshnessAge(p, o.nowMs);
+                return item(p, age === null ? 'never dated' : `${age} days`);
+            }),
         },
         {
             key: 'orphaned',

package/dist/react.d.ts

@@ -132,14 +132,34 @@ export interface TypeaheadOptions<T> {
     /** Remember results per query for this mount. */
     cache?: boolean;
 }
+/**
+ * What the list is answering. A failed search is its own state, never an empty
+ * list: "no pages found" for a 429 tells the reader the page does not exist.
+ * `searching` keeps the last answer's items on screen until this one lands.
+ */
+export type TypeaheadResults<T> = {
+    status: 'idle';
+} | {
+    status: 'searching';
+    query: string;
+    items: T[];
+} | {
+    status: 'found';
+    query: string;
+    items: T[];
+} | {
+    status: 'failed';
+    query: string;
+};
 export interface TypeaheadState<T> {
     query: string;
     setQuery: (query: string) => void;
     debouncedQuery: string;
+    results: TypeaheadResults<T>;
+    /** The rows on screen: `results.items` where it has any, else none. */
     items: T[];
     highlight: number;
     setHighlight: (index: number) => void;
-    isSearching: boolean;
     onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
     /** Drop the results, keep the query. For an outside click. */
     clearItems: () => void;
@@ -181,7 +201,11 @@ export interface LinkPreviewOptions<T> {
      * is exactly the part that differs — so the whole predicate is yours.
      */
     eligible: (anchor: HTMLAnchorElement) => boolean;
-    /** Resolve a preview for a href, or null for "no card". REST or server action. */
+    /**
+     * Resolve a preview for a href, or null for "no card". REST or server action.
+     * Throw when the answer could not be read (a 429, a 5xx): null is cached for
+     * the visit, a throw is asked again on the next hover.
+     */
     fetch: (href: string) => Promise<T | null>;
     /** Must match the class on the element you spread `cardProps` onto. */
     cardClassName?: string;

package/dist/react.js

@@ -293,6 +293,9 @@ export function useClickOutside(onClose) {
     }, [onClose]);
     return ref;
 }
+// ---- typeahead --------------------------------------------------------------
+const TYPEAHEAD_IDLE = { status: 'idle' };
+const NO_ITEMS = [];
 /**
  * The debounced-search state machine behind every typeahead on these sites.
  *
@@ -314,11 +317,11 @@ export function useClickOutside(onClose) {
 export function useTypeahead({ fetch, onPick, onEscape, delay = 200, minLength = 1, cache = true, }) {
     const [query, setQuery] = useState('');
     const [debounced, setDebounced] = useState('');
-    const [items, setItems] = useState([]);
+    const [results, setResults] = useState(TYPEAHEAD_IDLE);
     const [highlight, setHighlight] = useState(0);
-    const [isSearching, setIsSearching] = useState(false);
     const requestId = useRef(0);
     const cached = useRef(new Map());
+    const items = results.status === 'searching' || results.status === 'found' ? results.items : NO_ITEMS;
     useEffect(() => {
         const timer = setTimeout(() => setDebounced(query), delay);
         return () => clearTimeout(timer);
@@ -329,36 +332,32 @@ export function useTypeahead({ fetch, onPick, onEscape, delay = 200, minLength =
             // Bump the id so an in-flight request for a longer query cannot land
             // after the field has been cleared.
             requestId.current++;
-            setItems([]);
-            setIsSearching(false);
+            setResults(TYPEAHEAD_IDLE);
             return;
         }
         const hit = cache ? cached.current.get(q) : undefined;
         if (hit) {
             requestId.current++;
-            setItems(hit);
+            setResults({ status: 'found', query: q, items: hit });
             setHighlight(0);
-            setIsSearching(false);
             return;
         }
         const id = ++requestId.current;
         const controller = new AbortController();
-        setIsSearching(true);
+        setResults(r => ({ status: 'searching', query: q, items: r.status === 'searching' || r.status === 'found' ? r.items : NO_ITEMS }));
         fetch(q, controller.signal).then(rows => {
             if (id !== requestId.current)
                 return;
             if (cache)
                 cached.current.set(q, rows);
-            setItems(rows);
+            setResults({ status: 'found', query: q, items: rows });
             setHighlight(0);
-            setIsSearching(false);
         }, () => {
-            // An abort is the expected path for every superseded query, so it must
-            // not surface as an error. A real failure reads as "no results".
+            // An abort is the expected path for every superseded query, and the id
+            // check drops it. A real failure is never cached, so asking again retries.
             if (id !== requestId.current)
                 return;
-            setItems([]);
-            setIsSearching(false);
+            setResults({ status: 'failed', query: q });
         });
         return () => controller.abort();
     }, [debounced, fetch, minLength, cache]);
@@ -366,16 +365,14 @@ export function useTypeahead({ fetch, onPick, onEscape, delay = 200, minLength =
     // bring back the list the reader just closed.
     const clearItems = useCallback(() => {
         requestId.current++;
-        setItems([]);
-        setIsSearching(false);
+        setResults(TYPEAHEAD_IDLE);
     }, []);
     const reset = useCallback(() => {
         requestId.current++;
         setQuery('');
         setDebounced('');
-        setItems([]);
+        setResults(TYPEAHEAD_IDLE);
         setHighlight(0);
-        setIsSearching(false);
     }, []);
     const onKeyDown = (e) => {
         if (e.key === 'Escape') {
@@ -396,7 +393,7 @@ export function useTypeahead({ fetch, onPick, onEscape, delay = 200, minLength =
         else if (e.key === 'Enter') {
             // The list answers the last settled query. Typed past it, Enter falls
             // through to the form, so it submits what was typed, not a stale pick.
-            if (query !== debounced || isSearching)
+            if (query !== debounced || results.status !== 'found')
                 return;
             e.preventDefault();
             const target = items[highlight];
@@ -412,10 +409,10 @@ export function useTypeahead({ fetch, onPick, onEscape, delay = 200, minLength =
         query,
         setQuery,
         debouncedQuery: debounced,
+        results,
         items,
         highlight,
         setHighlight,
-        isSearching,
         onKeyDown,
         clearItems,
         reset,
@@ -475,11 +472,14 @@ export function useLinkPreview({ eligible, fetch, cardClassName = 'link-preview-
             showTimer.current = setTimeout(async () => {
                 let data = cache.current.get(href);
                 if (data === undefined) {
+                    // Only an answer is cached. A failed fetch shows no card this time and
+                    // is asked again on the next hover, where caching it as "no preview"
+                    // hid that link's card for the rest of the visit.
                     try {
                         data = await opts.current.fetch(href);
                     }
                     catch {
-                        data = null;
+                        return;
                     }
                     cache.current.set(href, data);
                 }

package/dist/scripts.d.ts

@@ -92,5 +92,5 @@ export declare function writeRevision(client: ScriptClient, page: WikiPageRow<An
 export declare function upsertWikiPage(client: ScriptClient, input: SaveInput<AnyBlock> & {
     content: AnyBlock[];
     siteId?: string;
-}): Promise<'created' | 'updated'>;
+}): Promise<'created' | 'updated' | 'unchanged'>;
 export {};

package/dist/scripts.js

@@ -139,6 +139,6 @@ export async function writeRevision(client, page, blocks, { change = 'minor', me
 export async function upsertWikiPage(client, input) {
     assertLinkShapes(input.content, `${input.tagPath}/${input.slug}`);
     const { siteId, ...save } = input;
-    const { created } = await storeFor(client, siteId).save(save);
-    return created ? 'created' : 'updated';
+    const { created, changeType } = await storeFor(client, siteId).save(save);
+    return created ? 'created' : changeType === 'none' ? 'unchanged' : 'updated';
 }

package/dist/store.d.ts

@@ -112,6 +112,14 @@ export declare function toListing<R extends {
 }>(row: R): Omit<R, 'content'> & {
     snippet: string;
 };
+/**
+ * Why a save was refused, carried in the 409 body as `conflict`. `stale` and
+ * `deleted` mean reload: the page moved on, so saving again cannot succeed.
+ * `taken` means pick another slug, which reloading does not fix. A client that
+ * guessed this from its own state filed a rename of a stale page as a slug
+ * clash and kept offering Save for a 409 every retry would meet again.
+ */
+export type ConflictReason = 'stale' | 'deleted' | 'taken';
 /** Re-order rows to match an id list, dropping ids that no longer resolve. */
 export declare function orderByIds<T extends {
     id: string;

package/dist/store.js

@@ -34,7 +34,7 @@ export function toListing(row) {
     const { content, ...rest } = row;
     return { ...rest, snippet: describe(openingText(content)) };
 }
-const conflict = (message) => new HttpError(409, message);
+const conflict = (reason, message) => new HttpError(409, message, { conflict: reason });
 const SLUG_TAKEN = 'A page with that slug already exists in this category';
 /** Re-order rows to match an id list, dropping ids that no longer resolve. */
 export function orderByIds(rows, ids) {
@@ -220,7 +220,7 @@ export function wikiStore(o) {
        )
        SELECT * FROM up`, site, input.tagPath, input.slug, input.title, JSON.stringify(input.content), JSON.stringify(input.metadata ?? {}), INITIAL_VERSION, input.authorId ?? null, input.verified === true, input.message ?? 'Initial version');
         if (!page)
-            throw conflict('A page at that path was created while this one was being written');
+            throw conflict('taken', 'A page at that path was created while this one was being written');
         return { page, created: true, changeType: 'major', summary: 'page created' };
     };
     /**
@@ -232,17 +232,17 @@ export function wikiStore(o) {
     const save = async (input) => {
         const existing = await get(input.tagPath, input.slug);
         if (!existing && input.baseVersion !== undefined) {
-            throw conflict(`This page was deleted since it was opened at v${input.baseVersion}. Saving now would create it again; reload to decide.`);
+            throw conflict('deleted', `This page was deleted since it was opened at v${input.baseVersion}. Saving now would create it again; reload to decide.`);
         }
         if (!existing)
             return create(input);
         if (input.baseVersion !== undefined && input.baseVersion !== existing.version) {
-            throw conflict(`This page changed since it was opened: it is at v${existing.version} now, not v${input.baseVersion}. Reload it and apply the edit again.`);
+            throw conflict('stale', `This page changed since it was opened: it is at v${existing.version} now, not v${input.baseVersion}. Reload it and apply the edit again.`);
         }
         const slug = input.newSlug && input.newSlug !== existing.slug ? input.newSlug : existing.slug;
         const slugTaken = async () => slug !== existing.slug && (await get(existing.tagPath, slug)) !== null;
         if (await slugTaken())
-            throw conflict(SLUG_TAKEN);
+            throw conflict('taken', SLUG_TAKEN);
         const title = input.title ?? existing.title;
         const content = input.content ?? existing.content;
         const diff = computeRevisionDiff({
@@ -269,11 +269,11 @@ export function wikiStore(o) {
             // A page that took the slug after the check above fails the unique index.
             // Asked again rather than read off the error, whose shape is the driver's.
             if (await slugTaken())
-                throw conflict(SLUG_TAKEN);
+                throw conflict('taken', SLUG_TAKEN);
             throw err;
         });
         if (!page)
-            throw conflict('This page was saved by someone else while this edit was being written. Reload it and apply the edit again.');
+            throw conflict('stale', 'This page was saved by someone else while this edit was being written. Reload it and apply the edit again.');
         return { page, created: false, changeType, summary: diff.summary };
     };
     /** Put a page back as a revision had it, as a major change of its own. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.105.1",
+  "version": "0.107.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, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",