wiki-formant 0.20.0 → 0.22.0

package/dist/mcp.js

@@ -80,6 +80,67 @@ export class McpToolError extends Error {
         this.name = 'McpToolError';
     }
 }
+/**
+ * Typed, clamped reads over a tool's raw arguments, recording every value it
+ * had to override.
+ *
+ * Defaults belong in the tool's description, where a model reads them; what a
+ * result should echo is only the case where the server overrode what the
+ * caller actually asked for, so `adjustments` stays signal. The three servers
+ * here had one of these, one inline `clamp`, and one server coercing per tool,
+ * where `Math.min(Number(limit) || 12, 50)` let a negative limit through.
+ */
+export function readArgs(raw) {
+    const adjustments = [];
+    // A numeric string is read as its number without comment — the transport
+    // accepts them, and parsing is not overriding what the caller asked for.
+    const number = (name, def, min, max, whole) => {
+        const value = raw[name];
+        if (value === undefined || value === null || value === '')
+            return def;
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) {
+            adjustments.push({ param: name, requested: value, used: def, reason: 'not a number' });
+            return def;
+        }
+        const clamped = Math.min(max, Math.max(min, whole ? Math.trunc(parsed) : parsed));
+        if (clamped !== parsed) {
+            adjustments.push({
+                param: name,
+                requested: value,
+                used: clamped,
+                reason: `must be a ${whole ? 'whole number' : 'number'} between ${min} and ${max}`,
+            });
+        }
+        return clamped;
+    };
+    return {
+        adjustments,
+        note(a) {
+            adjustments.push(a);
+        },
+        /** A whole number in `[min, max]`; `def` when absent or not a number at all. */
+        num: (name, def, min, max) => number(name, def, min, max, true),
+        /** Any number in `[min, max]` — an age that is a cohort mean, a price; `def` (often null) when absent. */
+        decimal: (name, def, min, max) => number(name, def, min, max, false),
+        /** Trimmed text; `def` when absent. */
+        str(name, def = '') {
+            const value = raw[name];
+            return value === undefined || value === null ? def : String(value).trim();
+        },
+        /** True only for a JSON `true`. */
+        bool(name) {
+            return raw[name] === true;
+        },
+        /** The string members of an array argument; `[]` when absent. */
+        list(name) {
+            const value = raw[name];
+            return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+        },
+    };
+}
+/** `result`, plus `adjustments` when `readArgs` had to override anything. */
+export const withAdjustments = (args, result) => args.adjustments.length ? { ...result, adjustments: args.adjustments } : result;
 /** How many entries one JSON-RPC batch may carry. Quoted by the conformance suite. */
 export const DEFAULT_MAX_BATCH = 20;
 const quote = (list) => list.map(s => `"${s}"`).join(', ');

package/dist/metadata.d.ts

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

package/dist/metadata.js

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

package/dist/react-server.d.ts

@@ -37,6 +37,8 @@ export interface FacetBarClassNames {
     label?: string;
     control?: string;
     controlActive?: string;
+    /** Set it and each count is its own `<span>` with this class, not ` (n)` text. */
+    count?: string;
 }
 export interface FacetBarProps {
     link: WikiLinkComponent;
@@ -44,6 +46,8 @@ export interface FacetBarProps {
     letters: Control[];
     /** The label on the A–Z row. */
     alphaLabel?: string;
+    /** Lead with the A–Z row: two lines against a facet block's twenty. */
+    alphaFirst?: boolean;
     classNames?: FacetBarClassNames;
 }
 /**
@@ -56,7 +60,23 @@ export interface FacetBarProps {
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export declare function FacetBar({ link: Link, facets, letters, alphaLabel, classNames, }: FacetBarProps): import("react").JSX.Element | null;
+export declare function FacetBar({ link: Link, facets, letters, alphaLabel, alphaFirst, classNames, }: FacetBarProps): import("react").JSX.Element | null;
+/**
+ * A JSON-LD payload, safe to place inside `<script type="application/ld+json">`.
+ *
+ * The body has to go in through `dangerouslySetInnerHTML` — React escapes a
+ * text child's `<`, which breaks the parser Google reads — and these payloads
+ * carry authored strings: page titles, display names, excerpts. An authored
+ * `</script>` closes the tag and the rest parses as markup. Re-encoding every
+ * `<` as its JSON escape closes that; every JSON parser decodes it back, so the
+ * data a crawler reads is unchanged. One of the three wikis did this; the
+ * other two, and this package's own breadcrumb trail, did not.
+ */
+export declare function jsonLdScript(data: unknown): string;
+/** A `<script type="application/ld+json">` for `data`, escaped by `jsonLdScript`. */
+export declare function JsonLd({ data }: {
+    data: unknown;
+}): import("react").JSX.Element;
 export interface BreadcrumbItem {
     label: string;
     /**

package/dist/react-server.js

@@ -36,11 +36,41 @@ export const Anchor = ({ href, className, children }) => _jsx("a", { href: href,
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', classNames = {}, }) {
+export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', alphaFirst = false, classNames = {}, }) {
     if (!facets.length && !letters.length)
         return null;
-    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', } = classNames;
-    return (_jsxs("div", { className: root, children: [facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(option => (_jsxs(Link, { href: option.href, className: option.active ? controlActive : control, "aria-current": option.active ? 'true' : undefined, children: [option.value, " (", option.count, ")"] }, option.value)))] }, facet.key))), letters.length > 0 && (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(letter => (_jsxs(Link, { href: letter.href, className: letter.active ? controlActive : control, "aria-current": letter.active ? 'true' : undefined, children: [letter.label, " (", letter.count, ")"] }, letter.value || 'all')))] }))] }));
+    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', count, } = classNames;
+    const chip = (c) => (_jsxs(Link, { href: c.href, className: c.active ? controlActive : control, "aria-current": c.active ? 'true' : undefined, ...(c.title ? { title: c.title } : {}), children: [c.text, count ? _jsx("span", { className: count, children: c.n }) : ` (${c.n})`] }, c.key));
+    const facetRows = facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(o => chip({ key: o.value, href: o.href, active: o.active, text: o.value, n: o.count }))] }, facet.key)));
+    // The reset control leads the letters and says what it resets to.
+    const alphaRow = letters.length > 0 && (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(l => chip({
+                key: l.value || 'all',
+                href: l.href,
+                active: l.active,
+                text: l.label,
+                n: l.count,
+                ...(l.reset ? { title: `All ${l.count} pages` } : {}),
+            }))] }, "alpha"));
+    return _jsx("div", { className: root, children: alphaFirst ? [alphaRow, ...facetRows] : [...facetRows, alphaRow] });
+}
+// ---- structured data --------------------------------------------------------
+/**
+ * A JSON-LD payload, safe to place inside `<script type="application/ld+json">`.
+ *
+ * The body has to go in through `dangerouslySetInnerHTML` — React escapes a
+ * text child's `<`, which breaks the parser Google reads — and these payloads
+ * carry authored strings: page titles, display names, excerpts. An authored
+ * `</script>` closes the tag and the rest parses as markup. Re-encoding every
+ * `<` as its JSON escape closes that; every JSON parser decodes it back, so the
+ * data a crawler reads is unchanged. One of the three wikis did this; the
+ * other two, and this package's own breadcrumb trail, did not.
+ */
+export function jsonLdScript(data) {
+    return JSON.stringify(data).replace(/</g, '\\u003c');
+}
+/** A `<script type="application/ld+json">` for `data`, escaped by `jsonLdScript`. */
+export function JsonLd({ data }) {
+    return _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: jsonLdScript(data) } });
 }
 /**
  * The trail, plus the `BreadcrumbList` that makes it a rich result.
@@ -70,16 +100,16 @@ export function Breadcrumbs({ items, base, className = '', link: Link = Anchor,
                         const isLast = i === items.length - 1;
                         const Last = lastAs === 'h1' ? 'h1' : 'span';
                         return (_jsxs(Fragment, { children: [i > 0 && _jsx("li", { className: "separator", "aria-hidden": "true", children: "/" }), _jsx("li", { children: isLast ? (_jsx(Last, { className: lastAs === 'h1' ? 'breadcrumb-h1' : 'breadcrumb-current', "aria-current": "page", children: item.label })) : item.href ? (_jsx(Link, { href: item.href, className: "breadcrumb-link", title: item.label, children: item.label })) : (_jsx("span", { className: "breadcrumb-current", children: item.label })) })] }, item.href ?? `${item.label}-${i}`));
-                    }) }) }), structured && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify({
-                        '@context': 'https://schema.org',
-                        '@type': 'BreadcrumbList',
-                        itemListElement: items.map((item, i) => ({
-                            '@type': 'ListItem',
-                            position: i + 1,
-                            name: item.label,
-                            ...(item.href ? { item: absolute(item.href) } : {}),
-                        })),
-                    }) } }))] }));
+                    }) }) }), structured && (_jsx(JsonLd, { data: {
+                    '@context': 'https://schema.org',
+                    '@type': 'BreadcrumbList',
+                    itemListElement: items.map((item, i) => ({
+                        '@type': 'ListItem',
+                        position: i + 1,
+                        name: item.label,
+                        ...(item.href ? { item: absolute(item.href) } : {}),
+                    })),
+                } }))] }));
 }
 /**
  * The standard page-top row: the trail, plus optional right-aligned actions.

package/dist/react.d.ts

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

package/dist/react.js

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

package/dist/revisions.d.ts

@@ -39,8 +39,12 @@ export interface RevisionDiff<L = unknown> {
     summary: string;
 }
 export interface DiffOptions<B, L> {
-    /** Nested groups in document order, or `null` for a leaf. */
-    containers: (block: B) => BlockGroup<B>[] | null;
+    /**
+     * Nested groups in document order, or `null` for a leaf. Defaults to
+     * `coreBlockGroups` — `columns.i.blocks` and an infobox's `blocks` — which is
+     * every container any wiki here stores.
+     */
+    containers?: (block: B) => BlockGroup<B>[] | null;
     /**
      * A richer diff for one leaf, when the consumer has one to give. `from` is
      * null for an addition, `to` is null for a removal. Return `undefined` to
@@ -83,7 +87,7 @@ export declare function computeRevisionDiff<B extends DiffBlock, L = unknown>(op
     newMeta?: unknown;
     /** What to call that value in the summary. Defaults to `banner`. */
     metaLabel?: string;
-    containers: DiffOptions<B, L>['containers'];
+    containers?: DiffOptions<B, L>['containers'];
     leafDiff?: DiffOptions<B, L>['leafDiff'];
 }): RevisionDiff<L>;
 export {};

package/dist/revisions.js

@@ -5,6 +5,7 @@
 // page's banner, and a `patch` classification for when only that flag moved.
 // Matching is by id.
 import { incrementVersion, parseVersion } from './versioning.js';
+import { coreBlockGroups } from './blocks.js';
 /** Every block in the tree, flattened, each with the path that addresses it. */
 export function extractBlocks(blocks, containers, basePath = 'root') {
     const out = [];
@@ -52,8 +53,9 @@ function diffAttributes(oldBlock, newBlock, containers) {
  */
 export function diffBlocks(oldBlocks, newBlocks, opts) {
     const changes = [];
-    const oldFlat = extractBlocks(oldBlocks, opts.containers);
-    const newFlat = extractBlocks(newBlocks, opts.containers);
+    const containers = opts.containers ?? coreBlockGroups;
+    const oldFlat = extractBlocks(oldBlocks, containers);
+    const newFlat = extractBlocks(newBlocks, containers);
     const matchedOld = new Set();
     const matchedNew = new Set();
     const oldById = new Map(oldFlat.map(item => [item.block.id, item]));
@@ -73,7 +75,7 @@ export function diffBlocks(oldBlocks, newBlocks, opts) {
                 attributes: { position: { from: oldItem.path, to: newItem.path } },
             });
         }
-        const attributes = diffAttributes(oldItem.block, newItem.block, opts.containers);
+        const attributes = diffAttributes(oldItem.block, newItem.block, containers);
         if (attributes) {
             changes.push({
                 id,

package/dist/sanitize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The embed hosts the editor's iframe, YouTube, tweet and map nodes produce.
+ * This is half of a pair: the CSP `frame-src` in each `next.config.ts` must
+ * allow the same hosts, or an iframe survives sanitising and is then blocked.
+ */
+export declare const DEFAULT_IFRAME_HOSTS: readonly string[];
+export interface HtmlSanitizerOptions {
+    /** Hosts an `<iframe src>` may point at. Defaults to `DEFAULT_IFRAME_HOSTS`. */
+    iframeHosts?: readonly string[];
+    /** Keep the presentational SVG subset. Defaults to true. */
+    svg?: boolean;
+    /** Tags this wiki's stored HTML needs beyond the prose set. */
+    tags?: readonly string[];
+    /** Attributes to add, per tag. Merged with the defaults, never replacing them. Not `class`: see `classes`. */
+    attributes?: Readonly<Record<string, readonly string[]>>;
+    /** Class names to allow, per tag (`'language-*'` globs work). Merged with the editor's own. */
+    classes?: Readonly<Record<string, readonly string[]>>;
+    /** URL schemes per tag, where one tag needs more than http/https/mailto. `img` already takes data:. */
+    schemesByTag?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * A sanitiser bound to one wiki's allowlist.
+ *
+ * Derive `tags`, `attributes` and `classes` from the HTML actually stored in
+ * your pages and revisions, not from guesswork: that is how the SVG set above
+ * got here, and a list written from memory erases content on the first render.
+ */
+export declare function createHtmlSanitizer(options?: HtmlSanitizerOptions): (html: string) => string;
+/**
+ * The core leaf types' HTML fields, cleaned: `content.text`, `codeTabs` code,
+ * `linkGrid` group descriptions and `references` item text. Every other field
+ * those blocks carry renders as a React text node and is escaped already.
+ *
+ * Returns any other block untouched, so it drops straight into a
+ * `mapBlockTree` pass — a repo whose own types render HTML cleans those itself.
+ *
+ * `codeTabs` code is treated as stored HTML, which is what the editor writes.
+ * A wiki whose highlighter takes the code as SOURCE and escapes it on render
+ * must not pass it through here — every `<T>` in a signature would go — and
+ * cleans its other three fields with its own switch.
+ */
+export declare function sanitizeCoreLeaf<B extends {
+    type: string;
+}>(block: B, clean: (html: string) => string): B;