wiki-formant 0.20.0 → 0.21.0

package/README.md

@@ -145,6 +145,12 @@ handler: async (args, ctx) => {
 
 `config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope.
 
+### Tool arguments and the corpus tool
+
+`readArgs` reads a tool's raw arguments as typed, clamped values and records every value it had to override, so a result can say `adjustments: [{ param: 'limit', requested: -4, used: 1, … }]` instead of silently answering a different question. Defaults belong in the tool description; the result echoes only overrides.
+
+`wiki-formant/corpus` is the arithmetic behind a `get_full_corpus` tool: a `sizeOnly` preflight with per-branch and largest-page breakdowns, then page-aligned slices under a `maxChars` budget (`CORPUS_BUDGET`) with `truncated`, `nextSkip` and `clippedPage`. The corpus itself — which rows, how a page becomes a section — is the wiki's; `sliceCorpus` takes the sections it builds.
+
 ## Conformance
 
 `wiki-formant/conformance` is the half of an MCP conformance run that is not about any one server's tools: a JSON-RPC client that backs off on a 429, the transport assertions (CORS preflight, `GET`→405, a notification answering 202 with no body, `-32700`, the batch cap, honest `capabilities`, version negotiation), version coherence across every descriptor a surface publishes, A2A card parity, conditional-GET and `robots` checks, and a pass/fail table with an exit code.
@@ -263,7 +269,7 @@ are unit-tested without a DOM.
 
 `wiki-formant/react` carries `'use client'`, and that is a module-level boundary: anything exported from it hydrates in the consumer's tree whether or not it uses a hook. `wiki-formant/react-server` is the same React, without the directive — for the parts of a wiki that are pure functions of their props and should ship no JavaScript at all.
 
-`FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site.
+`FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
 
 `PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
 
@@ -318,10 +324,7 @@ between the copies; they differed only in what each had learned since.
 const diff = computeRevisionDiff({
   currentVersion: page.version,
   oldContent, newContent, oldTitle, newTitle,
-  containers: b =>
-    b.type === 'infobox' ? [{ path: 'blocks', blocks: b.blocks }]
-    : b.type === 'columns' ? b.columns.map((c, i) => ({ path: `columns.${i}.blocks`, blocks: c.blocks }))
-    : null,
+  // containers: defaults to coreBlockGroups — `columns.i.blocks` and an infobox's `blocks`
 });
 ```
 
@@ -330,9 +333,9 @@ const diff = computeRevisionDiff({
 - **Container keys are never diffed as attributes.** They are walked as their own
   entries, and comparing them here would report an infobox as edited every time
   anything inside it changed — turning a prose edit into a structural bump.
-- **The path segment is a parameter**, because `root.1.columns.0.blocks.2` is
-  what a reviewing UI anchors on and only the consumer knows how its containers
-  are addressed.
+- **The path segment is part of the contract**, because `root.1.columns.0.blocks.2`
+  is what a reviewing UI anchors on. A wiki with a container beyond the core two
+  passes its own `containers` and says how it is addressed.
 
 One copy also built two Maps keyed by a recursive `JSON.stringify` of every
 block, on every save, and never read either one. Matching is by id and always
@@ -383,6 +386,45 @@ const off = onTweetResize(h => sizeTweetEmbeds(el, h));
 
 `TWITTER_ORIGIN` is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
 
+## Block trees
+
+Every wiki here stores the same two containers the same way — `columns[i].blocks` and an infobox's `blocks` — and between them had hand-written that walk seven times. Bind it once and hand it to every walk:
+
+```ts
+import { coreBlockShape, leafBlocks, mapBlockTree } from 'wiki-formant/blocks';
+
+export const BLOCK_SHAPE = coreBlockShape<Block>();
+mapBlockTree(blocks, processLeaf, BLOCK_SHAPE);
+leafBlocks(blocks, BLOCK_SHAPE.containers);
+```
+
+`computeRevisionDiff` defaults to the same shape, path-addressed, so a repo whose containers are the core two passes none.
+
+The dispatch over a repo's own block union stays in that repo; the bodies come from here. `wiki-formant/text` has a prose body for every core leaf — `statsToText`, `linkGridToText` and `pageListToText` joined the originals when two of the three wikis turned out to extract nothing from them, so their MCP `get_page` answered a hub page as nearly empty.
+
+`createBlockValidator` returns `blockIssues` beside the boolean validators: the same walk, reporting where each failure is.
+
+```ts
+const issues = blockIssues(body.content);
+if (issues.length) return badRequest(`Invalid content: ${describeBlockIssues(issues)}`);
+// Invalid content: [2].columns[0].blocks[1]: malformed linkGrid block
+```
+
+## Sanitising stored HTML
+
+`wiki-formant/sanitize` is the allowlist between an author's saved HTML and a reader's browser. The block views render three HTML fields themselves, and a repo renders `content.text` beside them, so the guard ships with the renderer. `sanitize-html` is an optional peer; run it server-side, on the render path, so it covers rows written before it existed and no sanitiser ships to the client.
+
+```ts
+import { createHtmlSanitizer, sanitizeCoreLeaf } from 'wiki-formant/sanitize';
+
+const clean = createHtmlSanitizer({ iframeHosts: FRAME_HOSTS });   // pair with CSP frame-src
+const safe = mapBlockTree(blocks, b => sanitizeCoreLeaf(b, clean), BLOCK_SHAPE);
+```
+
+The default list is derived from what the editor nodes in `wiki-formant/tiptap` store — the embed wrappers' data attributes, the tab markup `activateTabGroups` reads back, the table classes — plus the presentational SVG subset the infographics pipeline embeds. Extend it with `tags`, `attributes`, `classes` and `schemesByTag` derived from your stored HTML, never from memory: a list written from memory erases content on the first render.
+
+Classes pass by name only. Limiting `style` to layout and paint is worth nothing while `class` is free, because every site's own stylesheet ships `fixed inset-0 z-50`, and those draw a fake prompt over the chrome as well as `position` does.
+
 ## Editor nodes
 
 `wiki-formant/tiptap` carries the custom nodes both wiki editors had written twice: `Iframe`, `YouTube` (the stock extension plus the paste rule it does not ship with), `TwitterEmbed`, `createMapEmbed`, `createCodeBlock` and `createTabs`. The four `@tiptap/*` packages are optional peers, so a consumer taking only the taxonomy still installs a package with no runtime dependencies.
@@ -399,6 +441,12 @@ The ones that take config take it because that is exactly where the two copies d
 
 `createTabs` returns `TabGroup` and `TabItem` together: `tabGroup`'s content expression is `tabItem+`, so registering one without the other leaves a node type the schema cannot satisfy. A pasted short map link inserts immediately with `about:blank` and swaps its `src` when the redirect resolves — pasting must not block on a network hop, and the node has to exist for the reader to see anything happen.
 
+The redirect resolves through the wiki's own route, because the editor cannot read it cross-origin. `resolveMapUrl` is the client half and `resolveMapHandler` the whole route: exact shortener hosts, one hop, an allowlisted landing host, a timeout, and your sign-in check as `authorize`. One of the two copies it replaced matched `goo.gl` as a substring and followed every redirect for anyone who asked.
+
+```ts
+export const GET = resolveMapHandler({ authorize: async () => !!(await currentUser()) });
+```
+
 ## Analytics
 
 Two lanes, one events helper. `mcpCallProps` reads a tool name out of a JSON-RPC

package/dist/blocks.d.ts

@@ -1,3 +1,4 @@
+import type { BlockGroup } from './revisions.js';
 export interface CodeTab {
     label: string;
     language?: string;
@@ -57,13 +58,42 @@ export interface BlockTreeShape<B> {
     rebuild: (block: B, groups: B[][]) => B;
 }
 /**
- * Every block in the tree, transformed, with the tree's shape preserved.
+ * The core containers' nested groups, each with the path segment that
+ * addresses it: `columns` holds `columns[i].blocks`, `infobox` holds `blocks`.
+ * Every other type is a leaf.
+ *
+ * All three wikis store these two identically, and between them had written
+ * this walk seven times — once per markdown twin, text export, revision diff,
+ * resolver and checker. A walk that forgot a container shipped a code block
+ * unhighlighted or dropped a link from the checker. The path-addressed form is
+ * what `computeRevisionDiff` defaults to.
+ */
+export declare function coreBlockGroups<B extends {
+    type: string;
+}>(block: B): BlockGroup<B>[] | null;
+/**
+ * `coreBlockGroups` as a `BlockTreeShape`: read the groups, and put mapped
+ * groups back where they came from. Bind it once per repo,
+ * `const BLOCK_SHAPE = coreBlockShape<Block>()`, and hand it to every walk.
+ */
+export declare function coreBlockShape<B extends {
+    type: string;
+}>(): BlockTreeShape<B>;
+/** Every leaf in document order, with the containers flattened away. */
+export declare function leafBlocks<B>(blocks: readonly B[], containers: (block: B) => B[][] | null): B[];
+/**
+ * Every leaf in the tree, transformed, with the tree's shape preserved.
  *
  * The three-branch walk this replaces — columns to `columns[].blocks`, infobox
  * to `.blocks`, everything else atomic — was written by hand for heading
  * injection, syntax highlighting, server-side data resolution, feed rendering
  * and twice more besides. Each copy was correct and each had to be found again
  * whenever a container type was added.
+ *
+ * It recurses, so `map` only ever sees leaves, however deep. It used to stop
+ * one level down and hand a nested container to `map` as if it were a leaf —
+ * harmless while every validator here rejects nesting, and a hole the moment a
+ * sanitising pass is the thing being mapped.
  */
 export declare function mapBlockTree<B>(blocks: readonly B[], map: (block: B) => B, shape: BlockTreeShape<B>): B[];
 /** The async twin. Highlighting and data resolution both await per leaf. */

package/dist/blocks.js

@@ -19,36 +19,95 @@ import { htmlToMarkdown, inlineToMarkdown } from './markdown.js';
  */
 export function renderBlockTree(blocks, opts) {
     const { atomic, containers, groupSeparator = '\n\n' } = opts;
-    return blocks
-        .map(block => {
+    const render = (block) => {
         const groups = containers?.(block);
         if (!groups)
             return atomic(block);
         return groups
-            .map(group => group.map(atomic).filter(Boolean).join(groupSeparator))
+            .map(group => group.map(render).filter(Boolean).join(groupSeparator))
             .filter(Boolean)
             .join(groupSeparator);
-    })
+    };
+    return blocks
+        .map(render)
         .filter(Boolean)
         .join('\n\n')
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
+const list = (v) => (Array.isArray(v) ? v : []);
 /**
- * Every block in the tree, transformed, with the tree's shape preserved.
+ * The core containers' nested groups, each with the path segment that
+ * addresses it: `columns` holds `columns[i].blocks`, `infobox` holds `blocks`.
+ * Every other type is a leaf.
+ *
+ * All three wikis store these two identically, and between them had written
+ * this walk seven times — once per markdown twin, text export, revision diff,
+ * resolver and checker. A walk that forgot a container shipped a code block
+ * unhighlighted or dropped a link from the checker. The path-addressed form is
+ * what `computeRevisionDiff` defaults to.
+ */
+export function coreBlockGroups(block) {
+    const b = block;
+    if (b.type === 'columns') {
+        return list(b.columns).map((col, i) => ({
+            path: `columns.${i}.blocks`,
+            blocks: list(col?.blocks),
+        }));
+    }
+    if (b.type === 'infobox')
+        return [{ path: 'blocks', blocks: list(b.blocks) }];
+    return null;
+}
+/**
+ * `coreBlockGroups` as a `BlockTreeShape`: read the groups, and put mapped
+ * groups back where they came from. Bind it once per repo,
+ * `const BLOCK_SHAPE = coreBlockShape<Block>()`, and hand it to every walk.
+ */
+export function coreBlockShape() {
+    return {
+        containers: block => coreBlockGroups(block)?.map(group => group.blocks) ?? null,
+        rebuild: (block, groups) => {
+            const b = block;
+            if (b.type === 'columns') {
+                return {
+                    ...block,
+                    columns: list(b.columns).map((col, i) => ({ ...col, blocks: groups[i] ?? [] })),
+                };
+            }
+            if (b.type === 'infobox')
+                return { ...block, blocks: groups[0] ?? [] };
+            return block;
+        },
+    };
+}
+/** Every leaf in document order, with the containers flattened away. */
+export function leafBlocks(blocks, containers) {
+    return blocks.flatMap(block => {
+        const groups = containers(block);
+        return groups ? groups.flatMap(group => leafBlocks(group, containers)) : [block];
+    });
+}
+/**
+ * Every leaf in the tree, transformed, with the tree's shape preserved.
  *
  * The three-branch walk this replaces — columns to `columns[].blocks`, infobox
  * to `.blocks`, everything else atomic — was written by hand for heading
  * injection, syntax highlighting, server-side data resolution, feed rendering
  * and twice more besides. Each copy was correct and each had to be found again
  * whenever a container type was added.
+ *
+ * It recurses, so `map` only ever sees leaves, however deep. It used to stop
+ * one level down and hand a nested container to `map` as if it were a leaf —
+ * harmless while every validator here rejects nesting, and a hole the moment a
+ * sanitising pass is the thing being mapped.
  */
 export function mapBlockTree(blocks, map, shape) {
     return blocks.map(block => {
         const groups = shape.containers(block);
         if (!groups)
             return map(block);
-        return shape.rebuild(block, groups.map(group => group.map(map)));
+        return shape.rebuild(block, groups.map(group => mapBlockTree(group, map, shape)));
     });
 }
 /** The async twin. Highlighting and data resolution both await per leaf. */
@@ -57,7 +116,7 @@ export async function mapBlockTreeAsync(blocks, map, shape) {
         const groups = shape.containers(block);
         if (!groups)
             return map(block);
-        const mapped = await Promise.all(groups.map(group => Promise.all(group.map(map))));
+        const mapped = await Promise.all(groups.map(group => mapBlockTreeAsync(group, map, shape)));
         return shape.rebuild(block, mapped);
     }));
 }

package/dist/corpus.d.ts

@@ -0,0 +1,65 @@
+/** One page as it appears in the document. */
+export interface CorpusSection {
+    /** The page's address, `tag/path/slug`. */
+    path: string;
+    /** Its branch, for the preflight's per-branch breakdown. */
+    tagPath: string;
+    /** Heading, URL, date and body, exactly as the document will carry them. */
+    section: string;
+}
+/** `maxChars` bounds: the default, the floor and the ceiling. Quote them in the tool's schema. */
+export declare const CORPUS_BUDGET: {
+    readonly default: 200000;
+    readonly min: 1000;
+    readonly max: 1000000;
+};
+export interface CorpusSliceOptions {
+    /** The returned document's heading. */
+    title: string;
+    /** Sizes and breakdowns only, no document. */
+    sizeOnly?: boolean;
+    /** First section to include: the previous call's `nextSkip`. */
+    skip?: number;
+    /** Character budget for `document`. */
+    maxChars?: number;
+    /** The preflight's closing advice: what is cheaper than pulling everything. */
+    hint?: string;
+}
+/**
+ * A preflight (`sizeOnly`) or one page-aligned slice of `sections`.
+ *
+ * `truncated` is true whenever content was cut: whole pages left over, or one
+ * page clipped mid-way because it alone exceeds the budget. `nextSkip` appears
+ * only when paging forward can return something; a clipped page is skipped
+ * past, since resuming on it would stall paging forever.
+ */
+export declare function sliceCorpus(sections: readonly CorpusSection[], opts: CorpusSliceOptions): {
+    branches: {
+        pages: number;
+        chars: number;
+        path: string;
+    }[];
+    largestPages: {
+        path: string;
+        chars: number;
+    }[];
+    hint: string;
+    totalPages: number;
+    characters: number;
+    estimatedTokens: number;
+    tokenNote: string;
+} | {
+    document: string;
+    clippedPage?: string | undefined;
+    clippedHint?: string | undefined;
+    nextSkip?: number | undefined;
+    skip: number;
+    includedPages: number;
+    omittedPages: number;
+    returnedCharacters: number;
+    truncated: boolean;
+    totalPages: number;
+    characters: number;
+    estimatedTokens: number;
+    tokenNote: string;
+};

package/dist/corpus.js

@@ -0,0 +1,82 @@
+// corpus.ts — a wiki's whole corpus, sliced to something a tool result can hold.
+//
+// /llms-full.txt can afford to be 3 MB: a fetch streams to disk under an ETag.
+// A tool result lands in a context window, so the MCP twin of that export needs
+// a preflight, a character budget and a page-aligned resume. Two wikis wrote
+// that loop and called the second a copy of the first "field for field". It was
+// not: the fields had different names, one reported `truncated: false` after
+// clipping the last page — while its own prompt told agents to page until
+// `truncated` was false — and the other sized its preflight on page bodies but
+// sliced on whole sections, so the preflight undercounted what it would send.
+//
+// The corpus itself — which rows, in what order, how a page becomes a section —
+// stays with each wiki. This is the arithmetic over the sections it hands in.
+/** `maxChars` bounds: the default, the floor and the ceiling. Quote them in the tool's schema. */
+export const CORPUS_BUDGET = { default: 200_000, min: 1_000, max: 1_000_000 };
+const CLIP_MARKER = '\n\n[…page clipped at maxChars…]';
+/**
+ * A preflight (`sizeOnly`) or one page-aligned slice of `sections`.
+ *
+ * `truncated` is true whenever content was cut: whole pages left over, or one
+ * page clipped mid-way because it alone exceeds the budget. `nextSkip` appears
+ * only when paging forward can return something; a clipped page is skipped
+ * past, since resuming on it would stall paging forever.
+ */
+export function sliceCorpus(sections, opts) {
+    const { title, sizeOnly = false, skip = 0, maxChars = CORPUS_BUDGET.default, hint } = opts;
+    const characters = sections.reduce((n, s) => n + s.section.length, 0);
+    const head = {
+        totalPages: sections.length,
+        characters,
+        estimatedTokens: Math.round(characters / 4),
+        tokenNote: 'estimatedTokens is characters/4, a rough guide only.',
+    };
+    if (sizeOnly) {
+        const branches = new Map();
+        for (const s of sections) {
+            const b = branches.get(s.tagPath) ?? { pages: 0, chars: 0 };
+            branches.set(s.tagPath, { pages: b.pages + 1, chars: b.chars + s.section.length });
+        }
+        return {
+            ...head,
+            branches: [...branches.entries()].map(([path, b]) => ({ path, ...b })).sort((a, b) => b.chars - a.chars),
+            largestPages: sections
+                .map(s => ({ path: s.path, chars: s.section.length }))
+                .sort((a, b) => b.chars - a.chars)
+                .slice(0, 5),
+            hint: hint ?? 'Pull with maxChars, or one branch at a time with tagPath.',
+        };
+    }
+    const parts = [];
+    let used = 0;
+    let index = skip;
+    let clippedPage;
+    for (; index < sections.length; index++) {
+        const s = sections[index];
+        if (used + s.section.length > maxChars) {
+            if (!parts.length) {
+                parts.push(`${s.section.slice(0, maxChars)}${CLIP_MARKER}`);
+                clippedPage = s.path;
+                used = maxChars;
+                index++;
+            }
+            break;
+        }
+        parts.push(s.section);
+        used += s.section.length;
+    }
+    const morePages = index < sections.length;
+    return {
+        ...head,
+        skip,
+        includedPages: parts.length,
+        omittedPages: sections.length - index,
+        returnedCharacters: used,
+        truncated: morePages || clippedPage !== undefined,
+        ...(morePages ? { nextSkip: index } : {}),
+        ...(clippedPage
+            ? { clippedPage, clippedHint: 'This page alone exceeds maxChars; raise maxChars to read the rest of it.' }
+            : {}),
+        document: [`# ${title}\n\n> pages ${skip + 1}-${index} of ${sections.length}`, ...parts].join('\n\n'),
+    };
+}

package/dist/link-check.d.ts

@@ -88,5 +88,30 @@ export declare function extractEmbeds(html: string): Array<{
     kind: string;
     url: string;
 }>;
+/** What a page links to, split the way a checker probes it. */
+export interface BlockLinks {
+    /** Absolute http(s) targets. */
+    external: string[];
+    /** Site-relative paths, fragment and trailing slash dropped. `/` stays `/`. */
+    internal: string[];
+    /** `<iframe>` and `<img>` sources. */
+    embeds: Array<{
+        kind: string;
+        url: string;
+    }>;
+}
+/**
+ * Every link in a block tree, from every core type that carries one.
+ *
+ * The two checkers that walked this had each fixed a bug the other still had.
+ * One read reference URLs, which live in `items[].url` and never in an anchor;
+ * the other missed every citation. The other decoded `&amp;` before probing —
+ * a stored href is an attribute, and probing it raw turns query-sensitive APIs
+ * into false failures — and stopped a bare `/` collapsing to `''`, the
+ * homepage reported broken. Neither read link-grid hrefs. This does all four.
+ */
+export declare function collectBlockLinks<B extends {
+    type: string;
+}>(blocks: readonly B[], containers?: (block: B) => B[][] | null): BlockLinks;
 /** `Promise.all` with a ceiling, preserving input order in the results. */
 export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/link-check.js

@@ -11,6 +11,8 @@
 // rather than death, which serialising per hostname fixes. A sweep missing any
 // one of these strips good citations.
 import { stripTags } from './html.js';
+import { decodeEntities } from './markdown.js';
+import { coreBlockShape, leafBlocks } from './blocks.js';
 const DEFAULTS = { timeoutMs: 12_000, slowTimeoutMs: 40_000 };
 /**
  * TLS-verification failures are NOT death.
@@ -228,6 +230,57 @@ export function extractEmbeds(html) {
     }
     return out;
 }
+const records = (v) => Array.isArray(v) ? v.filter((x) => !!x && typeof x === 'object') : [];
+const text = (v) => (typeof v === 'string' ? v : '');
+/**
+ * Every link in a block tree, from every core type that carries one.
+ *
+ * The two checkers that walked this had each fixed a bug the other still had.
+ * One read reference URLs, which live in `items[].url` and never in an anchor;
+ * the other missed every citation. The other decoded `&` before probing —
+ * a stored href is an attribute, and probing it raw turns query-sensitive APIs
+ * into false failures — and stopped a bare `/` collapsing to `''`, the
+ * homepage reported broken. Neither read link-grid hrefs. This does all four.
+ */
+export function collectBlockLinks(blocks, containers = coreBlockShape().containers) {
+    const out = { external: [], internal: [], embeds: [] };
+    const href = (raw) => {
+        const url = decodeEntities(raw).trim();
+        if (/^https?:\/\//i.test(url))
+            out.external.push(url);
+        else if (url.startsWith('/') && !url.startsWith('//'))
+            out.internal.push(url.split('#')[0].replace(/(.)\/+$/, '$1'));
+    };
+    const html = (fragment) => {
+        for (const link of extractLinks(fragment))
+            href(link.href);
+        for (const embed of extractEmbeds(fragment)) {
+            const url = decodeEntities(embed.url).trim();
+            if (/^https?:\/\//i.test(url))
+                out.embeds.push({ kind: embed.kind, url });
+        }
+    };
+    for (const block of leafBlocks(blocks, containers)) {
+        if (block.type === 'content')
+            html(text(block.text));
+        if (block.type === 'references') {
+            for (const item of records(block.items)) {
+                html(text(item.text));
+                if (text(item.url))
+                    href(text(item.url));
+            }
+        }
+        if (block.type === 'linkGrid') {
+            for (const group of records(block.groups)) {
+                html(text(group.description));
+                for (const link of records(group.links))
+                    if (text(link.href))
+                        href(text(link.href));
+            }
+        }
+    }
+    return out;
+}
 // ---- concurrency ------------------------------------------------------------
 /** `Promise.all` with a ceiling, preserving input order in the results. */
 export async function mapLimit(items, limit, fn) {

package/dist/maps.d.ts

@@ -14,5 +14,28 @@ export declare function extractCoordsFromUrl(url: string): MapCoords | null;
  * understands. Already-embeddable URLs pass through untouched.
  */
 export declare function toMapEmbedUrl(url: string): string | null;
-/** True for the shortener forms that only a redirect can resolve. */
-export declare const isShortMapUrl: (url: string) => boolean;
+/** True for the shortener forms only a redirect can resolve. Exact hostnames, never a substring. */
+export declare function isShortMapUrl(url: string): boolean;
+/**
+ * Follow a shortened maps link ONE hop, server-side, and return where it
+ * lands — or null unless both ends are on the allowlists. Never follows a
+ * redirect chain: every hop is a request to a host this code did not choose.
+ */
+export declare function resolveShortMapUrl(url: string, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<string | null>;
+/**
+ * The whole `GET /api/resolve-map?url=…` route. `authorize` is the wiki's own
+ * sign-in check: the route makes an outbound request per call, so it belongs
+ * behind the same gate as the editor that calls it.
+ */
+export declare function resolveMapHandler(opts: {
+    authorize: (request: Request) => boolean | Promise<boolean>;
+    timeoutMs?: number;
+}): (request: Request) => Promise<Response>;
+/**
+ * A pasted map URL as an embeddable one, following a shortener through the
+ * wiki's resolve route when the URL cannot be read directly. The editor's map
+ * node and embed dialog both take this as their `resolveMapUrl`.
+ */
+export declare function resolveMapUrl(url: string, endpoint?: string): Promise<string | null>;

package/dist/maps.js

@@ -1,8 +1,9 @@
 // maps.ts — turn a map URL a human pasted into one an <iframe> will accept.
 //
-// Both wikis carried this byte-for-byte apart from one `export` keyword. It is
-// pure string work over Google and Apple Maps URL shapes, with no framework or
-// database in it, which is why neither copy had a reason to diverge.
+// Both wikis carried the parsing byte-for-byte apart from one `export`
+// keyword. It is pure string work over Google and Apple Maps URL shapes. The
+// shortener hop at the bottom is the one part that makes a request, and the
+// part the two copies did NOT agree on.
 /** A plain embed URL for a coordinate pair. */
 function mapsEmbedUrl(lat, lon, zoom = 15) {
     return `https://maps.google.com/maps?q=${lat},${lon}&z=${zoom}&output=embed`;
@@ -73,5 +74,90 @@ export function toMapEmbedUrl(url) {
     }
     return null;
 }
-/** True for the shortener forms that only a redirect can resolve. */
-export const isShortMapUrl = (url) => /maps\.app\.goo\.gl|goo\.gl\/maps/.test(url);
+// ---- shortened links ---------------------------------------------------------
+//
+// A `maps.app.goo.gl` link only resolves through a redirect, which the editor
+// cannot read cross-origin, so each wiki runs a route that follows it. One of
+// the two copies matched its host as a SUBSTRING — `https://evil.example/?goo.gl`
+// passed — then followed every redirect with no timeout and no login: an
+// anonymous fetcher for any URL. The other followed one hop, between exact
+// host lists, with a timeout, for signed-in members only. That one is below.
+const SHORTLINK_HOSTS = new Set(['goo.gl', 'maps.app.goo.gl']);
+/**
+ * Where a resolved shortlink may land: Google Maps on a Google country domain
+ * (google.com, maps.google.com, www.google.co.uk, www.google.com.au). An
+ * anchored list, because the suffix match it replaced, `google\.[a-z.]+`,
+ * admitted google.evil.com.
+ */
+const RESOLVED_HOST = /^(?:www\.|maps\.)?google\.(?:com|com?\.[a-z]{2}|[a-z]{2})$/;
+const parse = (url, base) => {
+    try {
+        return new URL(url, base);
+    }
+    catch {
+        return null;
+    }
+};
+/** True for the shortener forms only a redirect can resolve. Exact hostnames, never a substring. */
+export function isShortMapUrl(url) {
+    const u = parse(url);
+    if (!u || !SHORTLINK_HOSTS.has(u.hostname))
+        return false;
+    return u.hostname === 'maps.app.goo.gl' || u.pathname.startsWith('/maps');
+}
+/**
+ * Follow a shortened maps link ONE hop, server-side, and return where it
+ * lands — or null unless both ends are on the allowlists. Never follows a
+ * redirect chain: every hop is a request to a host this code did not choose.
+ */
+export async function resolveShortMapUrl(url, { timeoutMs = 5_000 } = {}) {
+    const source = parse(url);
+    if (!source || source.protocol !== 'https:' || !isShortMapUrl(url))
+        return null;
+    try {
+        const res = await fetch(source, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        const location = res.headers.get('location');
+        const target = location ? parse(location, source) : null;
+        return target && target.protocol === 'https:' && RESOLVED_HOST.test(target.hostname) ? target.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The whole `GET /api/resolve-map?url=…` route. `authorize` is the wiki's own
+ * sign-in check: the route makes an outbound request per call, so it belongs
+ * behind the same gate as the editor that calls it.
+ */
+export function resolveMapHandler(opts) {
+    return async (request) => {
+        if (!(await opts.authorize(request)))
+            return Response.json({ error: 'Unauthorized' }, { status: 401 });
+        const url = new URL(request.url).searchParams.get('url') ?? '';
+        if (!url.startsWith('https:') || !isShortMapUrl(url)) {
+            return Response.json({ error: 'Invalid URL' }, { status: 400 });
+        }
+        const resolved = await resolveShortMapUrl(url, opts);
+        return resolved
+            ? Response.json({ resolved })
+            : Response.json({ error: 'Failed to resolve' }, { status: 502 });
+    };
+}
+/**
+ * A pasted map URL as an embeddable one, following a shortener through the
+ * wiki's resolve route when the URL cannot be read directly. The editor's map
+ * node and embed dialog both take this as their `resolveMapUrl`.
+ */
+export async function resolveMapUrl(url, endpoint = '/api/resolve-map') {
+    const direct = toMapEmbedUrl(url);
+    if (direct || !isShortMapUrl(url))
+        return direct;
+    try {
+        const res = await fetch(`${endpoint}?url=${encodeURIComponent(url)}`);
+        const { resolved } = (await res.json());
+        return resolved ? toMapEmbedUrl(resolved) : null;
+    }
+    catch {
+        return null;
+    }
+}