wiki-formant 0.20.0 → 0.22.0

package/dist/sanitize.js

@@ -0,0 +1,191 @@
+// sanitize.ts — the allowlist between an author's saved HTML and every reader's
+// browser.
+//
+// Every wiki here stores raw editor HTML and renders it through
+// `dangerouslySetInnerHTML`, and `wiki-formant/block-views` renders three more
+// such fields itself. Only one of the three had a sanitiser. Another gated
+// writes on an $XRD balance, which is a price rather than a trust boundary, on
+// a site whose readers connect wallets. The renderer that trusts those fields
+// ships from here, so the guard does too.
+//
+// Everything is an allowlist: unknown tags, unknown attributes (every on*
+// handler among them) and non-http(s) URLs are dropped, not escaped. Run it
+// server-side, on the render path, so it covers rows written before it existed
+// and no sanitiser ships to the client. `sanitize-html` is an optional peer.
+import sanitizeHtml from 'sanitize-html';
+// Inline SVG, presentational elements only. The infographics pipeline embeds
+// diagrams as inline SVG in two of the wikis, so a prose-only list would erase
+// them. `foreignObject` (arbitrary HTML), `use`/`image` (external refs),
+// `script` and the animation elements are deliberately absent.
+const SVG_TAGS = [
+    'svg', 'g', 'defs', 'title', 'desc', 'path', 'rect', 'circle', 'ellipse',
+    'line', 'polyline', 'polygon', 'text', 'tspan', 'linearGradient',
+    'radialGradient', 'stop', 'clipPath', 'mask', 'pattern',
+];
+// Inert geometry and paint values, applied to every SVG tag rather than per
+// element: the tag list above is what bounds the surface.
+const SVG_ATTRS = [
+    'x', 'y', 'x1', 'x2', 'y1', 'y2', 'cx', 'cy', 'r', 'rx', 'ry', 'd', 'points',
+    'width', 'height', 'transform', 'viewBox', 'preserveAspectRatio', 'xmlns',
+    'fill', 'fill-opacity', 'fill-rule', 'stroke', 'stroke-width', 'stroke-opacity',
+    'stroke-dasharray', 'stroke-linecap', 'stroke-linejoin', 'opacity',
+    'font-family', 'font-size', 'font-weight', 'letter-spacing', 'text-anchor',
+    'dominant-baseline', 'offset', 'stop-color', 'stop-opacity', 'gradientUnits',
+    'gradientTransform', 'clip-path', 'mask', 'role', 'aria-label', 'style',
+];
+/**
+ * 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 const DEFAULT_IFRAME_HOSTS = [
+    'www.youtube.com', 'youtube.com',
+    'www.youtube-nocookie.com', 'youtube-nocookie.com',
+    'platform.twitter.com',
+    'www.google.com', 'maps.google.com',
+    'embed.apple.com', 'maps.apple.com',
+];
+// Layout and paint only. `position`, `z-index` and friends are left out so a
+// page cannot lay a fake signing prompt over the site's chrome.
+const STYLE_PROPS = [
+    'width', 'height', 'max-width', 'max-height', 'min-width', 'min-height',
+    'margin', 'margin-top', 'margin-bottom', 'margin-left', 'margin-right',
+    'padding', 'padding-top', 'padding-bottom', 'padding-left', 'padding-right',
+    'border', 'border-top', 'border-bottom', 'border-left', 'border-right',
+    'border-radius', 'border-color', 'border-width', 'border-style',
+    'background', 'background-color', 'color', 'opacity',
+    'font-size', 'font-weight', 'font-style', 'line-height',
+    'text-align', 'vertical-align', 'display', 'overflow',
+];
+// Ordinary CSS tokens plus rgb()/rgba(). Excluding quotes, backslashes, angle
+// brackets and any other `(` keeps `url(...)` and `expression(...)` out of
+// every property without a per-property regex.
+const SAFE_CSS_VALUE = /^(?:[a-z0-9#%.,\-+/ ]|rgba?\([\d\s,.%]+\))*$/i;
+const PROSE_TAGS = [
+    'p', 'br', 'hr', 'div', 'span', 'blockquote', 'pre', 'code',
+    'strong', 'em', 'b', 'i', 's', 'u', 'sub', 'sup', 'mark', 'small',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+    'a', 'img', 'figure', 'figcaption',
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'caption', 'colgroup', 'col',
+    'iframe',
+];
+const PROSE_ATTRS = {
+    a: ['href', 'target', 'rel', 'id', 'title', 'aria-label', 'tabindex'],
+    img: ['src', 'alt', 'title', 'width', 'height', 'loading'],
+    // Every data attribute the `wiki-formant/tiptap` nodes store: the embed
+    // wrappers, and the tab markup `activateTabGroups` reads back. An allowlist
+    // written without the tab pair strips them, and stored tabs never activate.
+    div: [
+        'id', 'style',
+        'data-twitter-embed', 'data-tweet-id', 'data-url', 'data-map-embed', 'data-iframe-embed', 'data-youtube-video',
+        'data-tabs', 'data-active-tab', 'data-tab-item', 'data-tab-title',
+    ],
+    iframe: ['src', 'width', 'height', 'frameborder', 'allowfullscreen', 'scrolling', 'loading', 'referrerpolicy', 'title'],
+    figure: ['style', 'data-graphic'],
+    figcaption: ['style'],
+    span: ['id', 'style', 'title'],
+    p: ['id', 'style'],
+    // `cite-n` back-link targets ride on the superscript.
+    sup: ['id'],
+    sub: ['id'],
+    th: ['colspan', 'rowspan', 'colwidth', 'scope'],
+    td: ['colspan', 'rowspan', 'colwidth'],
+    col: ['span', 'width'],
+    // Heading ids back the crawlable anchors `injectHeadingIds` writes.
+    h1: ['id'], h2: ['id'], h3: ['id'], h4: ['id'], h5: ['id'], h6: ['id'],
+    li: ['id'],
+    blockquote: ['cite'],
+};
+/**
+ * Classes are allowed by NAME, never by attribute. Restricting `style` to
+ * layout and paint means nothing while `class` is free: every wiki here ships
+ * utility classes like `fixed inset-0 z-50`, which lay a fake prompt over the
+ * chrome as well as `position` would. These are the classes the package's own
+ * editor nodes write; a wiki adds the ones its stored content uses.
+ */
+const EDITOR_CLASSES = {
+    a: ['link'],
+    code: ['language-*'],
+    div: ['iframe-embed', 'map-embed', 'twitter-embed'],
+    img: ['rounded-lg', 'max-w-full'],
+    table: ['tiptap-table'],
+    th: ['p-2', 'font-semibold', 'bg-surface-1'],
+    td: ['p-2'],
+};
+// The editor keeps a pasted image inline as base64 (`allowBase64`), so an
+// `<img>` may carry data: — where nothing it holds can run.
+const EDITOR_SCHEMES = { img: ['http', 'https', 'data'] };
+/**
+ * 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 function createHtmlSanitizer(options = {}) {
+    const { iframeHosts = DEFAULT_IFRAME_HOSTS, svg = true, tags = [], attributes = {}, classes = {}, schemesByTag = {} } = options;
+    const merge = (base, extra) => {
+        const out = { ...base };
+        for (const [tag, more] of Object.entries(extra))
+            out[tag] = [...new Set([...(out[tag] ?? []), ...more])];
+        return out;
+    };
+    const allowedAttributes = merge(svg ? { ...PROSE_ATTRS, ...Object.fromEntries(SVG_TAGS.map(t => [t, SVG_ATTRS])) } : PROSE_ATTRS, attributes);
+    // `class` only ever arrives through `allowedClasses`, which admits the
+    // attribute for the tags it names and filters its value by name.
+    for (const tag of Object.keys(allowedAttributes)) {
+        allowedAttributes[tag] = allowedAttributes[tag].filter(a => a !== 'class');
+    }
+    const config = {
+        allowedTags: [...PROSE_TAGS, ...(svg ? SVG_TAGS : []), ...tags],
+        allowedAttributes,
+        allowedClasses: merge(EDITOR_CLASSES, classes),
+        allowedSchemesByTag: merge(EDITOR_SCHEMES, schemesByTag),
+        allowedStyles: { '*': Object.fromEntries(STYLE_PROPS.map(p => [p, [SAFE_CSS_VALUE]])) },
+        allowedSchemes: ['http', 'https', 'mailto'],
+        allowedSchemesAppliedToAttributes: ['href', 'src', 'cite'],
+        allowProtocolRelative: false,
+        allowedIframeHostnames: [...iframeHosts],
+        // SVG names are camelCase (clipPath, viewBox). Lower-casing them would still
+        // render, since the HTML parser re-adjusts known SVG names, but keeping the
+        // case means what is stored is what was allowlisted.
+        parser: { lowerCaseTags: false, lowerCaseAttributeNames: false },
+        // Drop the contents of a disallowed <script> or <style>, not just the tags.
+        nonTextTags: ['script', 'style', 'textarea', 'option', 'noscript'],
+    };
+    return (html) => (!html || !html.includes('<') ? html : sanitizeHtml(html, config));
+}
+const each = (v, map) => Array.isArray(v) ? v.map(item => (item && typeof item === 'object' ? map(item) : item)) : v;
+const str = (v) => typeof v === '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 function sanitizeCoreLeaf(block, clean) {
+    const b = block;
+    switch (b.type) {
+        case 'content':
+            return str(b.text) ? { ...b, text: clean(b.text) } : block;
+        case 'codeTabs':
+            return { ...b, tabs: each(b.tabs, t => (str(t.code) ? { ...t, code: clean(t.code) } : t)) };
+        case 'linkGrid':
+            return {
+                ...b,
+                groups: each(b.groups, g => (str(g.description) ? { ...g, description: clean(g.description) } : g)),
+            };
+        case 'references':
+            return { ...b, items: each(b.items, i => (str(i.text) ? { ...i, text: clean(i.text) } : i)) };
+        default:
+            return block;
+    }
+}

package/dist/search.d.ts

@@ -32,6 +32,26 @@ export declare const PROSE_PATTERN = "<[^>]*>|&nbsp;|\\\\[nrt\"\\\\/]|\", \"|\\[
  * tiers.
  */
 export declare function searchTsvSql(content?: string, title?: string): string;
+/**
+ * The statements that (re)build a table's `search_tsv` column and its GIN index.
+ * Run `column` inside one transaction: DROP then ADD, so no reader ever sees
+ * the table without it; then `index`.
+ *
+ * Rebuilt unconditionally rather than skipped when the column exists. A skip
+ * is idempotent about the column and blind to its EXPRESSION: a changed prose
+ * expression re-runs clean and changes nothing, and Postgres normalises the
+ * stored expression, so comparing it to this string would only produce false
+ * rebuilds. The column is derived from `content`, so dropping it loses nothing.
+ * Run it BEFORE declaring the column in a Prisma schema: `prisma db push` reads
+ * a generated column it does not know about as drift and drops it.
+ */
+export declare function searchTsvDdl(table: string, { content, title }?: {
+    content?: string;
+    title?: string;
+}): {
+    column: string[];
+    index: string;
+};
 /**
  * `ts_headline` options for a search result snippet: one fragment, wide enough
  * to read as a sentence, with no highlight markers (the caller styles it).

package/dist/search.js

@@ -60,6 +60,28 @@ export function searchTsvSql(content = 'content', title = 'title') {
     return `setweight(to_tsvector('english', coalesce(${title},'')), 'A') || ` +
         `setweight(to_tsvector('english', coalesce(${proseSql(content)}, '')), 'B')`;
 }
+/**
+ * The statements that (re)build a table's `search_tsv` column and its GIN index.
+ * Run `column` inside one transaction: DROP then ADD, so no reader ever sees
+ * the table without it; then `index`.
+ *
+ * Rebuilt unconditionally rather than skipped when the column exists. A skip
+ * is idempotent about the column and blind to its EXPRESSION: a changed prose
+ * expression re-runs clean and changes nothing, and Postgres normalises the
+ * stored expression, so comparing it to this string would only produce false
+ * rebuilds. The column is derived from `content`, so dropping it loses nothing.
+ * Run it BEFORE declaring the column in a Prisma schema: `prisma db push` reads
+ * a generated column it does not know about as drift and drops it.
+ */
+export function searchTsvDdl(table, { content = 'content', title = 'title' } = {}) {
+    return {
+        column: [
+            `ALTER TABLE ${table} DROP COLUMN IF EXISTS search_tsv`,
+            `ALTER TABLE ${table} ADD COLUMN search_tsv tsvector GENERATED ALWAYS AS (${searchTsvSql(content, title)}) STORED`,
+        ],
+        index: `CREATE INDEX IF NOT EXISTS ${table}_search_tsv_idx ON ${table} USING GIN (search_tsv)`,
+    };
+}
 /**
  * `ts_headline` options for a search result snippet: one fragment, wide enough
  * to read as a sentence, with no highlight markers (the caller styles it).

package/dist/text.d.ts

@@ -1,4 +1,4 @@
-import type { CodeTab, ReferenceItem } from './blocks.js';
+import type { CodeTab, LinkGridGroup, ReferenceItem, StatItem } from './blocks.js';
 /**
  * HTML to readable text. Links keep their href in parentheses so a model can
  * still follow a citation; block-level tags become newlines; list items get a
@@ -27,10 +27,27 @@ export declare const BANNER_VARIANTS: ReadonlyArray<{
     value: BannerVariant;
     label: string;
 }>;
+/** A stored variant this package knows, or `cleanup` for one it does not. */
+export declare function bannerVariant(variant: string): BannerVariant;
 /** A maintenance notice, inline: `[Notice: Needs citations] …`. */
 export declare function bannerToText(label: string, text?: string | null): string;
 /** Each tab under its label, tags stripped — highlighted markup is noise here. */
 export declare function codeTabsToText(tabs: readonly CodeTab[]): string;
+/** Metric cards, one per line: `99% Uptime`. */
+export declare function statsToText(items: readonly StatItem[]): string;
+/**
+ * Each group's heading over its links, hrefs in parentheses the way
+ * `stripHtml` keeps them.
+ *
+ * Two of the three wikis extracted nothing from a link grid, or from stats or
+ * page lists, so a hub page read to an agent as far emptier than it is. The
+ * third had its own three bodies. These are those bodies.
+ */
+export declare function linkGridToText(groups: readonly LinkGridGroup[], intro?: string | null): string;
+/** A resolved page list: one title per line. */
+export declare function pageListToText(pages: readonly {
+    title: string;
+}[]): string;
 /** A numbered reference list, or `''` when there are none. */
 export declare function referencesToText(items: readonly ReferenceItem[]): string;
 /**

package/dist/text.js

@@ -50,6 +50,10 @@ export const BANNER_VARIANTS = Object.keys(BANNER_LABELS).map(value => ({
     value,
     label: BANNER_LABELS[value],
 }));
+/** A stored variant this package knows, or `cleanup` for one it does not. */
+export function bannerVariant(variant) {
+    return Object.hasOwn(BANNER_LABELS, variant) ? variant : 'cleanup';
+}
 /** A maintenance notice, inline: `[Notice: Needs citations] …`. */
 export function bannerToText(label, text) {
     return `[Notice: ${label}]${text ? ' ' + stripHtml(text) : ''}`;
@@ -58,6 +62,32 @@ export function bannerToText(label, text) {
 export function codeTabsToText(tabs) {
     return tabs.map(t => `[${t.label}]\n${t.code}`).join('\n');
 }
+/** Metric cards, one per line: `99% Uptime`. */
+export function statsToText(items) {
+    return items.map(s => `${s.value}${s.suffix ?? ''} ${s.label}`).join('\n');
+}
+/**
+ * Each group's heading over its links, hrefs in parentheses the way
+ * `stripHtml` keeps them.
+ *
+ * Two of the three wikis extracted nothing from a link grid, or from stats or
+ * page lists, so a hub page read to an agent as far emptier than it is. The
+ * third had its own three bodies. These are those bodies.
+ */
+export function linkGridToText(groups, intro) {
+    return [
+        ...(intro ? [stripHtml(intro)] : []),
+        ...groups.map(g => [
+            g.heading,
+            ...(g.description ? [stripHtml(g.description)] : []),
+            ...g.links.map(l => `- ${l.label} (${l.href})`),
+        ].join('\n')),
+    ].join('\n\n');
+}
+/** A resolved page list: one title per line. */
+export function pageListToText(pages) {
+    return pages.map(p => p.title).join('\n');
+}
 /** A numbered reference list, or `''` when there are none. */
 export function referencesToText(items) {
     if (!items.length)

package/dist/tiptap.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import { Node as TiptapNode } from '@tiptap/core';
+import { Extension, Node as TiptapNode } from '@tiptap/core';
 /** Local `cn`. Both wikis import one; the package will not depend on one. */
 export declare const Iframe: TiptapNode<any, any>;
 /** The stock extension plus the paste rule it does not ship with. */
@@ -76,3 +76,16 @@ export declare function createTabs({ classNames, icons, tabLabel, }?: TabsOption
     TabGroup: TiptapNode<any, any>;
     TabItem: TiptapNode<any, any>;
 };
+/**
+ * Gives each heading in the editor the id its published copy will carry, so an
+ * "on this page" rail can list it while the page is being written.
+ *
+ * A decoration, not an attribute: the id is in the editor's DOM and never in
+ * `getHTML()`, so stored HTML stays id-free and `injectHeadingIds` still mints
+ * the published ids. Pass the same `slug` the wiki passes there. The dedupe is
+ * `uniqueHeadingId`, the one `injectHeadingIds` uses; the copy this replaced
+ * restated it, and would have drifted the first time either changed.
+ */
+export declare function createHeadingIds({ slug }?: {
+    slug?: (text: string) => string;
+}): Extension<any, any>;

package/dist/tiptap.js

@@ -12,7 +12,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // and the other `text-accent` without either forking the node. It also keeps
 // this file from dragging an icon library in behind it.
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { Node as TiptapNode, mergeAttributes } from '@tiptap/core';
+import { Extension, Node as TiptapNode, mergeAttributes } from '@tiptap/core';
+import { Plugin } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
 import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from '@tiptap/react';
 import TiptapYoutube from '@tiptap/extension-youtube';
 import TiptapCodeBlock from '@tiptap/extension-code-block';
@@ -20,6 +22,7 @@ import { onTweetResize, tweetEmbedSrc } from './dom.js';
 import { toMapEmbedUrl } from './maps.js';
 import { useClickOutside } from './react.js';
 import { cx } from './html.js';
+import { slugifyHeading, uniqueHeadingId } from './headings.js';
 /** Local `cn`. Both wikis import one; the package will not depend on one. */
 // ---- iframe -----------------------------------------------------------------
 export const Iframe = TiptapNode.create({
@@ -336,3 +339,40 @@ export function createTabs({ classNames = {}, icons = {}, tabLabel = i => `Tab $
     });
     return { TabGroup, TabItem };
 }
+// ---- heading ids while editing ---------------------------------------------------
+/**
+ * Gives each heading in the editor the id its published copy will carry, so an
+ * "on this page" rail can list it while the page is being written.
+ *
+ * A decoration, not an attribute: the id is in the editor's DOM and never in
+ * `getHTML()`, so stored HTML stays id-free and `injectHeadingIds` still mints
+ * the published ids. Pass the same `slug` the wiki passes there. The dedupe is
+ * `uniqueHeadingId`, the one `injectHeadingIds` uses; the copy this replaced
+ * restated it, and would have drifted the first time either changed.
+ */
+export function createHeadingIds({ slug = slugifyHeading } = {}) {
+    return Extension.create({
+        name: 'headingIds',
+        addProseMirrorPlugins: () => [
+            new Plugin({
+                props: {
+                    decorations: ({ doc }) => {
+                        const used = new Set();
+                        const decorations = [];
+                        doc.descendants((node, pos) => {
+                            if (node.type.name !== 'heading')
+                                return;
+                            const id = uniqueHeadingId(slug(node.textContent), used);
+                            if (!id)
+                                return false;
+                            used.add(id);
+                            decorations.push(Decoration.node(pos, pos + node.nodeSize, { id }));
+                            return false;
+                        });
+                        return DecorationSet.create(doc, decorations);
+                    },
+                },
+            }),
+        ],
+    });
+}

package/dist/validation.d.ts

@@ -15,6 +15,10 @@ export declare const okUrl: (u: unknown) => boolean;
 export declare function validateReferenceItems(items: unknown): boolean;
 /** `[{ id, heading, links: [{ label, href }] }]` — a link-grid block's groups. */
 export declare function validateLinkGroups(groups: unknown): boolean;
+/** `[{ label, language?, code }]` — a code-tabs block's tabs. `code` renders as HTML. */
+export declare function validateCodeTabs(tabs: unknown): boolean;
+/** `[{ value, label, suffix? }]` — a stats block's cards. */
+export declare function validateStatItems(items: unknown): boolean;
 export interface BlockValidatorOptions {
     /** True for a type this wiki knows at all. */
     isKnownType: (type: string) => boolean;
@@ -23,10 +27,20 @@ export interface BlockValidatorOptions {
     /** This wiki's switch over its leaf types. Runs only after id/type pass. */
     validateAtomic: (block: Record<string, unknown>) => boolean;
 }
+/** Where a block tree fails, and why: `{ path: '[2].columns[0].blocks[1]', reason }`. */
+export interface BlockIssue {
+    path: string;
+    reason: string;
+}
 /**
  * The block-tree walk, with one wiki's leaf switch plugged into it. The caller
  * keeps its own type parameter, so this stays free of any repo's types while
  * the call site still gets a real type guard.
+ *
+ * `blockIssues` is the same walk reporting WHERE. Every write path here
+ * answered a bad tree with "invalid block structure" and nothing else, which
+ * leaves an agent writing through MCP to guess, and one repo's seed guard had
+ * to walk the tree a second time just to name the offending link.
  */
 export declare function createBlockValidator(opts: BlockValidatorOptions): {
     /** One leaf block; container types are rejected. */
@@ -35,7 +49,11 @@ export declare function createBlockValidator(opts: BlockValidatorOptions): {
     validateBlock: (block: unknown) => boolean;
     /** A whole page's content array. */
     validateBlocks: (content: unknown) => boolean;
+    /** Every failure in a page's content array, each with the path to it. */
+    blockIssues: (content: unknown) => BlockIssue[];
 };
+/** One line for an error response: the first few issues, then a count. */
+export declare function describeBlockIssues(issues: readonly BlockIssue[], max?: number): string;
 /**
  * A copy of a block with a fresh id at every level, so a duplicated container
  * does not share child ids with its original.
@@ -43,4 +61,4 @@ export declare function createBlockValidator(opts: BlockValidatorOptions): {
 export declare function duplicateBlockIds<B extends {
     type: string;
     id: string;
-}>(block: B, newId: () => string): B;
+}>(block: B, newId?: () => string): B;

package/dist/validation.js

@@ -56,55 +56,109 @@ export function validateLinkGroups(groups) {
             Array.isArray(g.links) &&
             g.links.every(l => isRecord(l) && typeof l.label === 'string' && okUrl(l.href))));
 }
+/** `[{ label, language?, code }]` — a code-tabs block's tabs. `code` renders as HTML. */
+export function validateCodeTabs(tabs) {
+    return (Array.isArray(tabs) &&
+        tabs.every(t => isRecord(t) &&
+            typeof t.label === 'string' &&
+            typeof t.code === 'string' &&
+            (t.language === undefined || typeof t.language === 'string')));
+}
+/** `[{ value, label, suffix? }]` — a stats block's cards. */
+export function validateStatItems(items) {
+    return (Array.isArray(items) &&
+        items.every(s => isRecord(s) &&
+            typeof s.label === 'string' &&
+            (typeof s.value === 'string' || typeof s.value === 'number') &&
+            (s.suffix === undefined || s.suffix === null || typeof s.suffix === 'string')));
+}
 /**
  * The block-tree walk, with one wiki's leaf switch plugged into it. The caller
  * keeps its own type parameter, so this stays free of any repo's types while
  * the call site still gets a real type guard.
+ *
+ * `blockIssues` is the same walk reporting WHERE. Every write path here
+ * answered a bad tree with "invalid block structure" and nothing else, which
+ * leaves an agent writing through MCP to guess, and one repo's seed guard had
+ * to walk the tree a second time just to name the offending link.
  */
 export function createBlockValidator(opts) {
     const { isKnownType, isAtomicType, validateAtomic } = opts;
-    const atomic = (block) => {
-        if (!isRecord(block))
-            return false;
-        if (typeof block.id !== 'string')
-            return false;
-        if (typeof block.type !== 'string' || !isKnownType(block.type) || !isAtomicType(block.type))
-            return false;
-        return validateAtomic(block);
-    };
-    const one = (block) => {
-        if (!isRecord(block))
-            return false;
+    const check = (block, path, nested, out) => {
+        if (!isRecord(block)) {
+            out.push({ path, reason: 'not a block object' });
+            return;
+        }
         if (typeof block.id !== 'string')
-            return false;
-        if (typeof block.type !== 'string' || !isKnownType(block.type))
-            return false;
-        if (block.type === 'columns') {
-            return (Array.isArray(block.columns) &&
-                block.columns.every(col => isRecord(col) &&
-                    typeof col.id === 'string' &&
-                    Array.isArray(col.blocks) &&
-                    col.blocks.every(atomic)));
+            out.push({ path, reason: '`id` must be a string' });
+        if (typeof block.type !== 'string' || !isKnownType(block.type)) {
+            out.push({ path, reason: `unknown block type ${JSON.stringify(block.type)}` });
+            return;
+        }
+        if (!nested && block.type === 'columns') {
+            if (!Array.isArray(block.columns)) {
+                out.push({ path: `${path}.columns`, reason: 'must be an array' });
+                return;
+            }
+            block.columns.forEach((col, i) => {
+                const at = `${path}.columns[${i}]`;
+                if (!isRecord(col) || typeof col.id !== 'string' || !Array.isArray(col.blocks)) {
+                    out.push({ path: at, reason: 'a column needs a string `id` and a `blocks` array' });
+                    return;
+                }
+                col.blocks.forEach((b, j) => check(b, `${at}.blocks[${j}]`, true, out));
+            });
+            return;
+        }
+        if (!nested && block.type === 'infobox') {
+            if (!Array.isArray(block.blocks)) {
+                out.push({ path: `${path}.blocks`, reason: 'must be an array' });
+                return;
+            }
+            block.blocks.forEach((b, j) => check(b, `${path}.blocks[${j}]`, true, out));
+            return;
         }
-        if (block.type === 'infobox') {
-            return Array.isArray(block.blocks) && block.blocks.every(atomic);
+        if (!isAtomicType(block.type)) {
+            out.push({ path, reason: nested ? `a ${block.type} block cannot sit inside a container` : `${block.type} blocks are not accepted` });
+            return;
         }
-        return atomic(block);
+        if (!validateAtomic(block))
+            out.push({ path, reason: `malformed ${block.type} block` });
+    };
+    const issuesOf = (block, nested) => {
+        const out = [];
+        check(block, '', nested, out);
+        return out;
+    };
+    const blockIssues = (content) => {
+        if (!Array.isArray(content))
+            return [{ path: '', reason: 'content must be an array of blocks' }];
+        const out = [];
+        content.forEach((block, i) => check(block, `[${i}]`, false, out));
+        return out;
     };
     return {
         /** One leaf block; container types are rejected. */
-        validateAtomicBlock: atomic,
+        validateAtomicBlock: (block) => issuesOf(block, true).length === 0,
         /** One block of any kind, containers included. */
-        validateBlock: one,
+        validateBlock: (block) => issuesOf(block, false).length === 0,
         /** A whole page's content array. */
-        validateBlocks: (content) => Array.isArray(content) && content.every(one),
+        validateBlocks: (content) => blockIssues(content).length === 0,
+        /** Every failure in a page's content array, each with the path to it. */
+        blockIssues,
     };
 }
+/** One line for an error response: the first few issues, then a count. */
+export function describeBlockIssues(issues, max = 3) {
+    const shown = issues.slice(0, max).map(i => (i.path ? `${i.path}: ${i.reason}` : i.reason));
+    const more = issues.length - shown.length;
+    return `${shown.join('; ')}${more > 0 ? ` (+${more} more)` : ''}`;
+}
 /**
  * A copy of a block with a fresh id at every level, so a duplicated container
  * does not share child ids with its original.
  */
-export function duplicateBlockIds(block, newId) {
+export function duplicateBlockIds(block, newId = () => crypto.randomUUID()) {
     const b = block;
     if (block.type === 'columns' && Array.isArray(b.columns)) {
         return {