wiki-formant 0.83.1 → 0.84.0

package/README.md

@@ -422,7 +422,7 @@ const { ref, onScroll, at, step, go } = useSnapRow();
 
 `useClickOutside` is fifteen lines and was in all three. Only one had the `offsetParent` check, and without it a container hidden at the current breakpoint still answers outside-clicks — so on a phone, a tap anywhere dismisses the popover the reader is looking at, because the hidden desktop copy got there first.
 
-`useUnsavedChanges(dirty)` asks before an edit with unsaved changes is left: the browser's own prompt on a reload or a closed tab, and the `confirmLeave()` it returns for a Back link or Cancel, which a client-side navigation never sends through `beforeunload`. If a save leaves by a full page load, pass false once it has landed, or the save's own exit asks. `useSaveShortcut(save)` binds ⌘S and Ctrl+S, reading `save` when the key is pressed.
+`useUnsavedChanges(dirty)` asks before an edit with unsaved changes is left: the browser's own prompt on a reload or a closed tab, and the `confirmLeave()` it returns for a Back link or Cancel, which a client-side navigation never sends through `beforeunload`. If a save leaves by a full page load, pass false once it has landed, or the save's own exit asks. `useSaveShortcut(save)` binds ⌘S and Ctrl+S, reading `save` when the key is pressed. `useSearchShortcut(open)` is Wikipedia's "/" to search, ignored while the reader types in a field: `open` focuses the field or opens what holds it, and returns false to leave the key alone, which `focusShown(input)` does for a field hidden at this width.
 
 ### The listbox contract
 
@@ -765,6 +765,14 @@ A `codeTabs` tab's `code` is source text in every wiki here, and every view trea
 
 `relativeTime(then, now, { style })` is `compact` (`3h`), `short` (`3h ago`) or `long` (`3 days ago`, day-grained for pages cached for hours), with `absoluteAfterDays` to hand over to the date itself. `now` is always passed in, never read, so a server render and its hydration agree. `formatDay` is always UTC: a stored day formatted in the server's zone, or the browser's, is the previous day for half the world. It reads `en-US` unless given a `locale`: `formatDay(day, { locale: 'en-GB', month: 'long' })` is `19 September 2026`. Both are in `wiki-formant/freshness`, with `isoDate`.
 
+## Freshness and the maintenance queues
+
+`freshnessBanner(page, nowMs, { maxAgeDays, against })` is the synthetic `outdated` banner a page carries once it has gone unchecked for `maxAgeDays` (180), or null. Its notice asks the reader to re-check the facts against `current sources`; the two Radix wikis pass `against: 'current sources and the live ledger'`, which a shop's wiki has no use for.
+
+`wiki-formant/queues` gathers the signals each page shows into Wikipedia's tracking categories: `maintenanceQueues(pages, { href, required, nowMs, verify, listedIds })` returns the outdated, orphaned, unsourced and missing-facts queues, empty ones dropped, from one pass over the pages' content. Pass every page but the home page and the back office, since an orphan is a page no other page links to. `href` is a page's address as its links name it, `required` the facts its category requires, `verify` how a page is stamped as checked here (it closes the outdated queue's sentence), and `listedIds` the ids a list block names its pages by. `MaintenanceQueues` (`wiki-formant/react-server`) draws them, a heading and a count each, under classes `maintenance-*`; the page around them is the wiki's, `noindex`. All four apps serve one at `/maintenance` (on miow, the owner page).
+
+`Cite` (`wiki-formant/react-server`) is "Cite" in an article's meta line, a `<details>` opening on `citation({ publisher, title, date, url })`: `AcuiQ. "Point codes." October 2, 2026. https://…`.
+
 ## Sanitising stored HTML
 
 `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. Run it server-side, on the render path, so it covers rows written before it existed and no sanitiser ships to the client.

package/dist/freshness.d.ts

@@ -12,6 +12,16 @@ export declare function daysSince(date: Date | string | null | undefined, now: n
  * edit is a weaker signal than a verification, but it is a signal.
  */
 export declare function isStale(page: FreshnessInput, now: number, maxAgeDays?: number): boolean;
+export interface FreshnessOptions {
+    /** Older than this, unverified, and the page is stale. */
+    maxAgeDays?: number;
+    /**
+     * What the notice asks a reader to re-check the facts against: `current
+     * sources` unless the wiki has more to name. The two Radix wikis add the live
+     * ledger, which a shop's wiki or a medical one has no use for.
+     */
+    against?: string;
+}
 /**
  * A synthetic `outdated` banner block for a stale page, or null when it is
  * fresh — the shape every wiki's `banner` type already stores, so it drops
@@ -20,7 +30,7 @@ export declare function isStale(page: FreshnessInput, now: number, maxAgeDays?:
  * during a client render would let a page near the boundary be stale on the
  * server and fresh in the browser.
  */
-export declare function freshnessBanner(page: FreshnessInput, nowMs: number, maxAgeDays?: number): {
+export declare function freshnessBanner(page: FreshnessInput, nowMs: number, { maxAgeDays, against }?: FreshnessOptions): {
     id: string;
     type: 'banner';
     variant: 'outdated';

package/dist/freshness.js

@@ -32,17 +32,17 @@ export function isStale(page, now, maxAgeDays = DEFAULT_MAX_AGE_DAYS) {
     return age === null || age > maxAgeDays;
 }
 /**
- * The sentence the notice carries. Both wikis shipped this string identically,
- * down to the ISO date and the closing request, so it lives here rather than
- * being re-typed either side of the extraction.
+ * The sentence the notice carries. Both Radix wikis shipped this string
+ * identically, down to the ISO date and the closing request; what to re-check
+ * against is the one part that differs between wikis.
  *
  * @internal
  */
-export function freshnessNotice(page) {
+export function freshnessNotice(page, against = 'current sources') {
     const when = page.lastVerifiedAt
         ? `last verified ${isoDate(new Date(page.lastVerifiedAt))}`
         : 'not yet verified against sources';
-    return `This page was ${when} and may be out of date. Please help re-check its facts against current sources and the live ledger.`;
+    return `This page was ${when} and may be out of date. Please help re-check its facts against ${against}.`;
 }
 /**
  * A synthetic `outdated` banner block for a stale page, or null when it is
@@ -52,10 +52,10 @@ export function freshnessNotice(page) {
  * during a client render would let a page near the boundary be stale on the
  * server and fresh in the browser.
  */
-export function freshnessBanner(page, nowMs, maxAgeDays = DEFAULT_MAX_AGE_DAYS) {
+export function freshnessBanner(page, nowMs, { maxAgeDays = DEFAULT_MAX_AGE_DAYS, against } = {}) {
     if (!isStale(page, nowMs, maxAgeDays))
         return null;
-    return { id: '__freshness__', type: 'banner', variant: 'outdated', text: freshnessNotice(page) };
+    return { id: '__freshness__', type: 'banner', variant: 'outdated', text: freshnessNotice(page, against) };
 }
 const toMs = (d) => (typeof d === 'number' ? d : d instanceof Date ? d.getTime() : Date.parse(d));
 /**

package/dist/link-check.d.ts

@@ -8,6 +8,12 @@ export interface Probe {
     note?: string;
     contentType?: string;
     bytes?: number;
+    /**
+     * The host refused a script rather than the page being gone: a bot challenge,
+     * a 429, or a 403/503 whose body is a challenge page. Report it as
+     * unverifiable, never as dead.
+     */
+    walled?: boolean;
 }
 export interface ProbeOptions {
     /** Ordinary per-attempt budget. */

package/dist/link-check.js

@@ -106,23 +106,41 @@ export function perHost(url, fn) {
     hostQueues.set(host, next.catch(() => undefined));
     return next;
 }
+/**
+ * A browser's request headers. A scholarly publisher or a standards body 403s
+ * Node's own user agent whatever the page's health; acuiq2's sweep, which
+ * checks PubMed and journal citations, sent these and saw a fraction of the
+ * false deaths.
+ */
+const BROWSER = {
+    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36',
+    Accept: 'text/html,application/xhtml+xml,*/*;q=0.8',
+    'Accept-Language': 'en',
+};
+const CHALLENGE = /recaptcha|cf-chl|challenge-platform|just a moment|captcha/i;
 async function attempt(url, budgetMs) {
     // One signal for both requests, so the budget covers the HEAD *and* the GET
     // rather than resetting between them. `engines.node` is >= 20, so this needs
     // no controller and no `clearTimeout` in a `finally` that could be forgotten.
     const signal = AbortSignal.timeout(budgetMs);
     try {
-        let res = await fetch(url, { method: 'HEAD', redirect: 'follow', signal });
+        let res = await fetch(url, { method: 'HEAD', redirect: 'follow', headers: BROWSER, signal });
         // Some hosts reject HEAD outright; retry with GET before believing a 4xx.
+        let body = '';
         if (res.status >= 400) {
-            res = await fetch(url, { method: 'GET', redirect: 'follow', signal });
+            res = await fetch(url, { method: 'GET', redirect: 'follow', headers: BROWSER, signal });
+            if (res.status >= 400)
+                body = await res.text().catch(() => '');
         }
+        // A 429 is the host rationing us, which says nothing about the page.
+        const walled = res.headers.get('cf-mitigated') === 'challenge' || res.status === 429 || ([403, 503].includes(res.status) && CHALLENGE.test(body));
         return {
             url,
             status: res.status,
             ok: res.status < 400,
             contentType: (res.headers.get('content-type') || '').split(';')[0]?.trim(),
             bytes: Number(res.headers.get('content-length') || 0),
+            ...(walled && { walled }),
         };
     }
     catch (err) {

package/dist/queues.d.ts

@@ -0,0 +1,45 @@
+export interface QueuePage {
+    id: string;
+    title: string;
+    tagPath: string;
+    slug: string;
+    content: unknown;
+    metadata: unknown;
+    updatedAt: Date | string;
+    lastVerifiedAt?: Date | string | null;
+}
+export interface QueueItem {
+    title: string;
+    href: string;
+    tagPath: string;
+    detail: string;
+}
+export type QueueKey = 'outdated' | 'orphaned' | 'unsourced' | 'incomplete';
+export interface MaintenanceQueue {
+    key: QueueKey;
+    title: string;
+    description: string;
+    items: QueueItem[];
+}
+export interface QueueOptions<P extends QueuePage> {
+    /** A page's address as its links name it: `/guides/install`, no trailing slash. */
+    href: (page: P) => string;
+    /** The facts a page's category requires, by key and label. */
+    required?: (tagPath: string) => readonly {
+        key: string;
+        label: string;
+    }[];
+    nowMs: number;
+    maxAgeDays?: number;
+    /** How a page is stamped as checked here, closing the outdated queue's description. */
+    verify?: string;
+    /** The ids a block names its pages by, for a list that picks pages by id rather than by link. */
+    listedIds?: (content: unknown) => Iterable<string>;
+}
+/**
+ * The four queues over a wiki's pages, empty ones dropped. Pass every page
+ * outside the home page and the back office: an orphan is a page nothing else
+ * links to, so the link graph needs them all. One pass reads each page's
+ * content for both the links in and the sources out.
+ */
+export declare function maintenanceQueues<P extends QueuePage>(pages: readonly P[], o: QueueOptions<P>): MaintenanceQueue[];

package/dist/queues.js

@@ -0,0 +1,85 @@
+// queues.ts — tracking categories, Wikipedia's hidden maintenance categories,
+// as work queues.
+//
+// A cleanup template files a page into `Articles needing update` or `Orphaned
+// articles`, and contributors pick work off the list. Every wiki here already
+// computed the same signals: `isStale` drives the outdated banner, the content
+// standard asks for linked sources, a category declares required facts. Each
+// surfaced only on the affected page, where nobody looking for work sees it.
+// These are those predicates gathered into lists, derived on every read, so
+// fixing a page takes it off the list with no ticket to close.
+//
+// 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';
+// An href inside stored JSON, its quotes escaped or not.
+const HREF = /href=\\?"([^"\\?#]+)/g;
+/** A `references` block keeps each citation in a `url` field, not an href. */
+const REF_URL = /"url":"https?:/g;
+/**
+ * The four queues over a wiki's pages, empty ones dropped. Pass every page
+ * outside the home page and the back office: an orphan is a page nothing else
+ * links to, so the link graph needs them all. One pass reads each page's
+ * content for both the links in and the sources out.
+ */
+export function maintenanceQueues(pages, o) {
+    const maxAgeDays = o.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS;
+    const ids = new Set(pages.map(p => p.id));
+    const linkedPaths = new Set();
+    const linkedIds = new Set();
+    const sources = new Map();
+    for (const page of pages) {
+        const text = JSON.stringify(page.content ?? '');
+        let outbound = 0;
+        for (const [, target] of text.matchAll(HREF)) {
+            if (!target)
+                continue;
+            if (target.startsWith('/'))
+                linkedPaths.add(target.replace(/\/+$/, '') || '/');
+            else if (/^https?:/i.test(target))
+                outbound++;
+        }
+        sources.set(page.id, outbound + (text.match(REF_URL)?.length ?? 0));
+        for (const id of o.listedIds?.(page.content) ?? [])
+            if (id !== page.id && ids.has(id))
+                linkedIds.add(id);
+    }
+    const item = (p, detail) => ({ title: p.title, href: o.href(p), tagPath: p.tagPath, detail });
+    const facts = (p) => (p.metadata && typeof p.metadata === 'object' ? p.metadata : {});
+    const incomplete = pages.flatMap(p => {
+        const missing = (o.required?.(p.tagPath) ?? [])
+            .filter(k => { const v = facts(p)[k.key]; return typeof v !== 'string' || !v.trim(); })
+            .map(k => k.label.replace(/:$/, ''));
+        return missing.length ? [item(p, `missing ${missing.join(', ')}`)] : [];
+    });
+    const queues = [
+        {
+            key: 'outdated',
+            title: 'Outdated',
+            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`)),
+        },
+        {
+            key: 'orphaned',
+            title: 'Orphaned',
+            description: 'No other page links here, so readers arrive only by search or the category list. Link it from a related page.',
+            items: pages.filter(p => !linkedPaths.has(o.href(p)) && !linkedIds.has(p.id)).map(p => item(p, 'no links in')),
+        },
+        {
+            key: 'unsourced',
+            title: 'Unsourced',
+            description: 'No link out anywhere on the page. Every claim of fact should link to the source it came from.',
+            items: pages.filter(p => !sources.get(p.id)).map(p => item(p, 'no links out')),
+        },
+        {
+            key: 'incomplete',
+            title: 'Missing facts',
+            description: 'A fact the page’s category requires is empty, so its facts panel and the category’s filters leave it out.',
+            items: incomplete,
+        },
+    ];
+    return queues.filter(q => q.items.length > 0);
+}

package/dist/react-server.d.ts

@@ -1,6 +1,7 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { Control, FacetControlGroup, MetadataRow } from './taxonomy.js';
 import type { HistoryChange } from './history.js';
+import type { MaintenanceQueue } from './queues.js';
 /**
  * The shape a router's link component has to satisfy here.
  *
@@ -298,3 +299,34 @@ export interface RevisionChangesProps {
  * are the importing stylesheet's.
  */
 export declare function RevisionChanges({ changes, label }: RevisionChangesProps): import("react").JSX.Element | null;
+export interface MaintenanceQueuesProps {
+    queues: readonly MaintenanceQueue[];
+    link?: WikiLinkComponent;
+    /** Shown when every queue is empty. */
+    empty?: ReactNode;
+    /** The level each queue's heading takes. */
+    headingLevel?: 'h2' | 'h3';
+}
+/**
+ * `maintenanceQueues`' lists, a heading and a count each. The page around them
+ * (its title, a sentence on what the queues are) is the wiki's.
+ */
+export declare function MaintenanceQueues({ queues, link: Link, empty, headingLevel: H }: MaintenanceQueuesProps): import("react").JSX.Element;
+export interface CiteProps {
+    /** Who publishes the page: the site's name. */
+    publisher: string;
+    title: string;
+    /** The day the page last changed, or was published where a wiki keeps that. */
+    date: Date | string;
+    /** The page's one canonical address. */
+    url: string;
+    className?: string;
+}
+/** The citation for a page, one line: `Publisher. "Title." October 22, 2026. url`, as acuiq2 first wrote it. */
+export declare const citation: ({ publisher, title, date, url }: Omit<CiteProps, "className">) => string;
+/**
+ * "Cite" in an article's meta line, opening on the citation to copy. Shown,
+ * not copied by a button, so it works with no script and a reader can take
+ * part of it.
+ */
+export declare function Cite({ className, ...page }: CiteProps): import("react").JSX.Element;

package/dist/react-server.js

@@ -22,6 +22,7 @@ import { Fragment } from 'react';
 import { safeLinkHref } from './validation.js';
 import { isoDate } from './html.js';
 import { blockLocation } from './revisions.js';
+import { formatDay } from './freshness.js';
 /**
  * The default for anything that does not need client-side navigation.
  *
@@ -250,3 +251,22 @@ export function RevisionChanges({ changes, label = type => type }) {
         return null;
     return (_jsx("ul", { className: "revision-changes", children: changes.map((c, i) => (_jsxs("li", { className: "revision-change", "data-action": c.action, children: [_jsx("span", { className: "revision-change-action", children: ACTION_LABEL[c.action] }), ` – ${label(c.type)} at ${blockLocation(c.path)}`, c.leafDiff && (_jsx("p", { className: "revision-diff", children: c.leafDiff.map(([op, text], j) => op === -1 ? _jsx("del", { children: text }, j) : op === 1 ? _jsx("ins", { children: text }, j) : _jsx("span", { children: text }, j)) }))] }, i))) }));
 }
+/**
+ * `maintenanceQueues`' lists, a heading and a count each. The page around them
+ * (its title, a sentence on what the queues are) is the wiki's.
+ */
+export function MaintenanceQueues({ queues, link: Link = Anchor, empty = _jsx("p", { children: "Nothing needs attention." }), headingLevel: H = 'h2' }) {
+    if (!queues.length)
+        return _jsx(_Fragment, { children: empty });
+    return (_jsx(_Fragment, { children: queues.map(queue => (_jsxs("section", { className: "maintenance-queue", "aria-labelledby": `queue-${queue.key}`, children: [_jsxs(H, { id: `queue-${queue.key}`, children: [queue.title, " ", _jsx("span", { className: "maintenance-count", children: queue.items.length })] }), _jsx("p", { className: "maintenance-description", children: queue.description }), _jsx("ul", { className: "maintenance-list", children: queue.items.map(item => (_jsxs("li", { className: "maintenance-item", children: [_jsx(Link, { href: item.href, children: item.title }), _jsxs("span", { className: "maintenance-detail", children: [item.tagPath ? `${item.tagPath} · ` : '', item.detail] })] }, item.href))) })] }, queue.key))) }));
+}
+/** The citation for a page, one line: `Publisher. "Title." October 22, 2026. url`, as acuiq2 first wrote it. */
+export const citation = ({ publisher, title, date, url }) => `${publisher}. "${title}." ${formatDay(date, { month: 'long' })}. ${url}`;
+/**
+ * "Cite" in an article's meta line, opening on the citation to copy. Shown,
+ * not copied by a button, so it works with no script and a reader can take
+ * part of it.
+ */
+export function Cite({ className = 'article-cite', ...page }) {
+    return (_jsxs("details", { className: className, children: [_jsx("summary", { children: "Cite" }), _jsx("code", { children: citation(page) })] }));
+}

package/dist/react.d.ts

@@ -330,6 +330,15 @@ export declare function useUnsavedChanges(dirty: boolean, message?: string): ()
  * file. `save` is read when the key is pressed, so it may close over state.
  */
 export declare function useSaveShortcut(save: () => void): void;
+/**
+ * "/" opens search from anywhere, Wikipedia's key, unless the reader is
+ * already typing. `open` focuses the field, or opens whatever holds it, and
+ * returns false when there is nothing to open (a field hidden at this width),
+ * which leaves the key to the page.
+ */
+export declare function useSearchShortcut(open: () => boolean | void): void;
+/** Focus a search field that is shown: `useSearchShortcut(() => focusShown(ref.current))`. */
+export declare const focusShown: (input: HTMLInputElement | null) => boolean;
 /** Resolves to an error message to show, or null on success. */
 export type RestoreRevision<Id> = (id: Id) => Promise<string | null>;
 /**

package/dist/react.js

@@ -654,6 +654,39 @@ export function useSaveShortcut(save) {
         return () => window.removeEventListener('keydown', onKey);
     }, []);
 }
+/**
+ * "/" opens search from anywhere, Wikipedia's key, unless the reader is
+ * already typing. `open` focuses the field, or opens whatever holds it, and
+ * returns false when there is nothing to open (a field hidden at this width),
+ * which leaves the key to the page.
+ */
+export function useSearchShortcut(open) {
+    const latest = useRef(open);
+    useEffect(() => {
+        latest.current = open;
+    });
+    useEffect(() => {
+        const onKey = (e) => {
+            if (e.key !== '/' || e.metaKey || e.ctrlKey || e.altKey)
+                return;
+            const t = e.target;
+            if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.tagName === 'SELECT' || t.isContentEditable))
+                return;
+            if (latest.current() !== false)
+                e.preventDefault();
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+}
+/** Focus a search field that is shown: `useSearchShortcut(() => focusShown(ref.current))`. */
+export const focusShown = (input) => {
+    // A field hidden at this width has no offsetParent.
+    if (!input?.offsetParent)
+        return false;
+    input.focus();
+    return true;
+};
 /**
  * POST `{ revisionId }` to `endpoint`, the transport two of the wikis use; the
  * third passes its server action instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.83.1",
+  "version": "0.84.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",
@@ -57,6 +57,11 @@
       "import": "./dist/sitemap.js",
       "default": "./dist/sitemap.js"
     },
+    "./queues": {
+      "types": "./dist/queues.d.ts",
+      "import": "./dist/queues.js",
+      "default": "./dist/queues.js"
+    },
     "./versioning": {
       "types": "./dist/versioning.d.ts",
       "import": "./dist/versioning.js",