wiki-formant 0.3.0 → 0.4.0

package/dist/maps.js

@@ -0,0 +1,77 @@
+// 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.
+/** A plain embed URL for a coordinate pair. */
+export function mapsEmbedUrl(lat, lon, zoom = 15) {
+    return `https://maps.google.com/maps?q=${lat},${lon}&z=${zoom}&output=embed`;
+}
+/**
+ * Dig a coordinate pair out of a maps URL. Four shapes in descending
+ * specificity: the `@lat,lon,zoom` path segment, a `/search/lat,lon`, the
+ * `!3d…!4d…` data blob, and finally an `ll`/`sll` query parameter.
+ */
+export function extractCoordsFromUrl(url) {
+    const coords = url.match(/@(-?\d+\.?\d*),(-?\d+\.?\d*),?(\d+\.?\d*)?z?/);
+    if (coords)
+        return { lat: +coords[1], lon: +coords[2], zoom: coords[3] ? +coords[3] : undefined };
+    const search = url.match(/\/search\/(-?\d+\.?\d*),[\s+]*(-?\d+\.?\d*)/);
+    if (search)
+        return { lat: +search[1], lon: +search[2] };
+    const data = url.match(/!3d(-?\d+\.?\d*)!4d(-?\d+\.?\d*)/);
+    if (data)
+        return { lat: +data[1], lon: +data[2] };
+    try {
+        const ll = new URL(url).searchParams.get('ll') ?? new URL(url).searchParams.get('sll');
+        if (ll) {
+            const [lat, lon] = ll.split(',').map(Number);
+            if (lat !== undefined && lon !== undefined && !isNaN(lat) && !isNaN(lon))
+                return { lat, lon };
+        }
+    }
+    catch {
+        /* not a valid URL */
+    }
+    return null;
+}
+/**
+ * An embeddable URL for `url`, or null when it is not a map link this
+ * understands. Already-embeddable URLs pass through untouched.
+ */
+export function toMapEmbedUrl(url) {
+    if (/google\.[a-z.]+\/maps\/embed/.test(url))
+        return url;
+    if (/embed\.apple\.com\/maps/.test(url))
+        return url;
+    const c = extractCoordsFromUrl(url);
+    if (c)
+        return mapsEmbedUrl(c.lat, c.lon, c.zoom);
+    if (/google\.[a-z.]+\/maps/.test(url)) {
+        const place = url.match(/\/place\/([^/@]+)/);
+        if (place) {
+            const q = encodeURIComponent(decodeURIComponent(place[1]).replace(/\+/g, ' '));
+            return `https://maps.google.com/maps?q=${q}&output=embed`;
+        }
+    }
+    if (/maps\.apple\.com/.test(url)) {
+        try {
+            const u = new URL(url);
+            const ll = u.searchParams.get('ll') ?? u.searchParams.get('sll');
+            const q = u.searchParams.get('q') ?? u.searchParams.get('address');
+            const params = new URLSearchParams();
+            if (ll)
+                params.set('ll', ll);
+            if (q)
+                params.set('q', q);
+            return `https://embed.apple.com/maps?${params.toString()}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    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);
+//# sourceMappingURL=maps.js.map

package/dist/maps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maps.js","sourceRoot":"","sources":["../src/maps.ts"],"names":[],"mappings":"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"}

package/dist/text.d.ts

@@ -0,0 +1,41 @@
+import type { CodeTab, ReferenceItem } 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
+ * bullet. Entities are decoded last, after the tags are gone, so a `<` in
+ * prose cannot become a tag the strip has already run past.
+ */
+export declare function stripHtml(html: string): string;
+/** The six maintenance-banner variants every wiki here renders. */
+export type BannerVariant = 'stub' | 'unsourced' | 'outdated' | 'promotional' | 'cleanup' | 'coi';
+/**
+ * Display labels for the maintenance banners. Canonical: the prose extractor,
+ * the markdown twin and the MDX export all render the same six strings.
+ */
+export declare const BANNER_LABELS: Record<BannerVariant, string>;
+/** 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;
+/** A numbered reference list, or `''` when there are none. */
+export declare function referencesToText(items: readonly ReferenceItem[]): string;
+/**
+ * Every `text` value at any depth of a block tree, in document order.
+ *
+ * Deliberately NOT the typed extractor above: that walks a switch and formats
+ * for reading (labels, bullets, reference numbering), so it can surface text a
+ * search index never matched and miss text it did. A snippet claiming to show
+ * why a row matched has to read the same bytes the match was made against.
+ */
+export declare function collectText(node: unknown, out?: string[]): string[];
+/**
+ * The passage that matched `query`, not the opening of the page.
+ *
+ * Wiki pages open with an infobox far more often than not — 243 of 269 on caper
+ * when this was measured — so an opening-line snippet hands nine search rows in
+ * ten a flattened metadata table, whatever the query was. Falls back to the
+ * opening when the term appears only in the title, which is a real case rather
+ * than a failure: title-only hits are how the top tiers match.
+ */
+export declare function matchSnippet(blocks: unknown, query: string, opening: () => string, maxLen?: number): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW9C;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,KAAK,CAAC;AAElG;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAOvD,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAExE;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAE/D;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAIxE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAYvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,MAAM,EAAE,MAAM,SAAM,GAAG,MAAM,CAwBxG"}

package/dist/text.js

@@ -0,0 +1,112 @@
+// text.ts — a block tree as plain prose, for LLM and MCP exports.
+//
+// The markdown twin in `blocks.ts` is for a reader; this is for a model reading
+// the page as evidence. Both wikis had the same `stripHtml`, the same six
+// banner labels and the same four leaf bodies, character for character.
+//
+// As in `blocks.ts`, the dispatch stays with the caller — a `switch` over its
+// own block union, where a new type is a compile error until it is handled —
+// and only the bodies live here.
+import { decodeEntities } from './entities.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
+ * bullet. Entities are decoded last, after the tags are gone, so a `<` in
+ * prose cannot become a tag the strip has already run past.
+ */
+export function stripHtml(html) {
+    return decodeEntities(html
+        .replace(/<a[^>]+href="([^"]*)"[^>]*>(.*?)<\/a>/gi, ' $2 ($1) ')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(?:p|h[1-6]|li|tr|th|td|div)>/gi, '\n')
+        .replace(/<(?:li)>/gi, '- ')
+        .replace(/<[^>]+>/g, ''))
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/**
+ * Display labels for the maintenance banners. Canonical: the prose extractor,
+ * the markdown twin and the MDX export all render the same six strings.
+ */
+export const BANNER_LABELS = {
+    stub: 'Stub',
+    unsourced: 'Needs citations',
+    outdated: 'May be outdated',
+    promotional: 'Written like an advertisement',
+    cleanup: 'Needs cleanup',
+    coi: 'Conflict of interest',
+};
+/** A maintenance notice, inline: `[Notice: Needs citations] …`. */
+export function bannerToText(label, text) {
+    return `[Notice: ${label}]${text ? ' ' + stripHtml(text) : ''}`;
+}
+/** Each tab under its label, tags stripped — highlighted markup is noise here. */
+export function codeTabsToText(tabs) {
+    return tabs.map(t => `[${t.label}]\n${t.code}`).join('\n');
+}
+/** A numbered reference list, or `''` when there are none. */
+export function referencesToText(items) {
+    if (!items.length)
+        return '';
+    const lines = items.map((it, i) => `${i + 1}. ${stripHtml(it.text)}${it.url ? ` (${it.url})` : ''}`);
+    return `References:\n${lines.join('\n')}`;
+}
+/**
+ * Every `text` value at any depth of a block tree, in document order.
+ *
+ * Deliberately NOT the typed extractor above: that walks a switch and formats
+ * for reading (labels, bullets, reference numbering), so it can surface text a
+ * search index never matched and miss text it did. A snippet claiming to show
+ * why a row matched has to read the same bytes the match was made against.
+ */
+export function collectText(node, out = []) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectText(item, out);
+        return out;
+    }
+    if (node && typeof node === 'object') {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'text' && typeof value === 'string')
+                out.push(value);
+            else
+                collectText(value, out);
+        }
+    }
+    return out;
+}
+/**
+ * The passage that matched `query`, not the opening of the page.
+ *
+ * Wiki pages open with an infobox far more often than not — 243 of 269 on caper
+ * when this was measured — so an opening-line snippet hands nine search rows in
+ * ten a flattened metadata table, whatever the query was. Falls back to the
+ * opening when the term appears only in the title, which is a real case rather
+ * than a failure: title-only hits are how the top tiers match.
+ */
+export function matchSnippet(blocks, query, opening, maxLen = 200) {
+    const term = query.trim();
+    if (!term)
+        return opening();
+    // Collapse tags and non-breaking spaces the way SQL does, so a phrase broken
+    // by markup is still one searchable string, then decode what is left: editors
+    // store typographic punctuation named, and without this a snippet reads back
+    // "docs &middot; Related".
+    const text = decodeEntities(collectText(blocks).join(' ').replace(/<[^>]*>|&nbsp;/g, ' '))
+        .replace(/\s+/g, ' ') // JS \s covers U+00A0, which SQL has to translate by hand
+        .trim();
+    const at = text.toLowerCase().indexOf(term.toLowerCase());
+    if (at === -1)
+        return opening();
+    // Keep about a line of lead-in, cut to a word boundary so it does not open
+    // mid-word.
+    let start = Math.max(0, at - 60);
+    if (start > 0) {
+        const boundary = text.indexOf(' ', start);
+        if (boundary > -1 && boundary < at)
+            start = boundary + 1;
+    }
+    const end = Math.min(text.length, start + maxLen);
+    return `${start > 0 ? '…' : ''}${text.slice(start, end).trimEnd()}${end < text.length ? '…' : ''}`;
+}
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,iCAAiC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,cAAc,CACnB,IAAI;SACD,OAAO,CAAC,yCAAyC,EAAE,WAAW,CAAC;SAC/D,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC;SAC7B,OAAO,CAAC,oCAAoC,EAAE,IAAI,CAAC;SACnD,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAC3B;SACE,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,IAAI,EAAE,CAAC;AACZ,CAAC;AAKD;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAkC;IAC1D,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,iBAAiB;IAC5B,QAAQ,EAAE,iBAAiB;IAC3B,WAAW,EAAE,+BAA+B;IAC5C,OAAO,EAAE,eAAe;IACxB,GAAG,EAAE,sBAAsB;CAC5B,CAAC;AAEF,mEAAmE;AACnE,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,IAAoB;IAC9D,OAAO,YAAY,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAClE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,KAA+B;IAC9D,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrG,OAAO,gBAAgB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,MAAgB,EAAE;IAC3D,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,GAAG,KAAK,MAAM,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;gBAC5D,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe,EAAE,KAAa,EAAE,OAAqB,EAAE,MAAM,GAAG,GAAG;IAC9F,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC,IAAI;QAAE,OAAO,OAAO,EAAE,CAAC;IAE5B,6EAA6E;IAC7E,8EAA8E;IAC9E,6EAA6E;IAC7E,2BAA2B;IAC3B,MAAM,IAAI,GAAG,cAAc,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;SACvF,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,0DAA0D;SAC/E,IAAI,EAAE,CAAC;IAEV,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,OAAO,EAAE,CAAC;IAEhC,2EAA2E;IAC3E,YAAY;IACZ,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACjC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,QAAQ,GAAG,CAAC,CAAC,IAAI,QAAQ,GAAG,EAAE;YAAE,KAAK,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;IAClD,OAAO,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACrG,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * An href acceptable to persist: http, https, mailto, or a relative path or
+ * fragment. Everything else — `javascript:`, `data:`, `vbscript:`, a
+ * protocol-relative `//host` — comes back null.
+ *
+ * React 19 already neutralises `javascript:` in an href at render time, so this
+ * is defence in depth rather than the only thing between an editor and a
+ * reader. Its value is at the write path: a URL that can never render safely is
+ * better rejected than stored.
+ */
+export declare function safeLinkHref(raw: string | null | undefined): string | null;
+/** An author-supplied URL is fine iff it is empty (unset) or resolves safely. */
+export declare const okUrl: (u: unknown) => boolean;
+/** `[{ id, text, url? }]` — the shape a references block stores. */
+export declare function validateReferenceItems(items: unknown, urlCheck?: (u: unknown) => boolean): boolean;
+/** `[{ id, heading, links: [{ label, href }] }]` — a link-grid block's groups. */
+export declare function validateLinkGroups(groups: unknown, urlCheck?: (u: unknown) => boolean): boolean;
+export interface BlockValidatorOptions {
+    /** True for a type this wiki knows at all. */
+    isKnownType: (type: string) => boolean;
+    /** True for a type that may nest inside a container. */
+    isAtomicType: (type: string) => boolean;
+    /** This wiki's switch over its leaf types. Runs only after id/type pass. */
+    validateAtomic: (block: Record<string, unknown>) => boolean;
+}
+/**
+ * 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.
+ */
+export declare function createBlockValidator(opts: BlockValidatorOptions): {
+    /** One leaf block; container types are rejected. */
+    validateAtomicBlock: (block: unknown) => boolean;
+    /** One block of any kind, containers included. */
+    validateBlock: (block: unknown) => boolean;
+    /** A whole page's content array. */
+    validateBlocks: (content: unknown) => boolean;
+};
+/**
+ * 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 declare function duplicateBlockIds<B extends {
+    type: string;
+    id: string;
+}>(block: B, newId: () => string): B;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAWA;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAa1E;AAED,iFAAiF;AACjF,eAAO,MAAM,KAAK,GAAI,GAAG,OAAO,KAAG,OAC8B,CAAC;AAKlE,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAe,GAAG,OAAO,CAWzG;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAe,GAAG,OAAO,CAYtG;AAED,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,wDAAwD;IACxD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,4EAA4E;IAC5E,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;CAC7D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB;IAkC5D,oDAAoD;iCA/B/B,OAAO,KAAG,OAAO;IAiCtC,kDAAkD;2BA1BhC,OAAO,KAAG,OAAO;IA4BnC,oCAAoC;8BACV,OAAO,KAAG,OAAO;EAE9C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,MAAM,GAAG,CAAC,CAgB1G"}

package/dist/validation.js

@@ -0,0 +1,124 @@
+// validation.ts — the block-tree checks that are the same wiki to wiki.
+//
+// Both wikis validate a block tree before it reaches the database, and both had
+// written the same walk: an id-and-type gate, a container branch for
+// columns/infobox, and a switch over leaf types. Only the switch is a project's
+// own — its type set is. So the walk and the two fiddly nested validators live
+// here, and the switch is passed in.
+//
+// As elsewhere in this package, the dispatch stays with the caller so a new
+// block type is a compile error there until it is handled.
+/**
+ * An href acceptable to persist: http, https, mailto, or a relative path or
+ * fragment. Everything else — `javascript:`, `data:`, `vbscript:`, a
+ * protocol-relative `//host` — comes back null.
+ *
+ * React 19 already neutralises `javascript:` in an href at render time, so this
+ * is defence in depth rather than the only thing between an editor and a
+ * reader. Its value is at the write path: a URL that can never render safely is
+ * better rejected than stored.
+ */
+export function safeLinkHref(raw) {
+    if (!raw)
+        return null;
+    // Strip C0 controls (including tab, newline and CR) and DEL before reading
+    // the scheme, so a newline cannot smuggle one past the match below.
+    const href = raw.replace(/[\u0000-\u0020\u007f]/g, '').trim();
+    if (!href)
+        return null;
+    if (href.startsWith('//'))
+        return null; // protocol-relative -> external host
+    const scheme = href.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+    if (scheme) {
+        const s = scheme[1].toLowerCase();
+        if (s !== 'http' && s !== 'https' && s !== 'mailto')
+            return null;
+    }
+    return href;
+}
+/** An author-supplied URL is fine iff it is empty (unset) or resolves safely. */
+export const okUrl = (u) => typeof u === 'string' && (u === '' || safeLinkHref(u) !== null);
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** `[{ id, text, url? }]` — the shape a references block stores. */
+export function validateReferenceItems(items, urlCheck = okUrl) {
+    return (Array.isArray(items) &&
+        items.every(it => isRecord(it) &&
+            typeof it.id === 'string' &&
+            typeof it.text === 'string' &&
+            (it.url === undefined || urlCheck(it.url))));
+}
+/** `[{ id, heading, links: [{ label, href }] }]` — a link-grid block's groups. */
+export function validateLinkGroups(groups, urlCheck = okUrl) {
+    return (Array.isArray(groups) &&
+        groups.every(g => isRecord(g) &&
+            typeof g.id === 'string' &&
+            typeof g.heading === 'string' &&
+            Array.isArray(g.links) &&
+            g.links.every(l => isRecord(l) && typeof l.label === 'string' && urlCheck(l.href))));
+}
+/**
+ * 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.
+ */
+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;
+        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)));
+        }
+        if (block.type === 'infobox') {
+            return Array.isArray(block.blocks) && block.blocks.every(atomic);
+        }
+        return atomic(block);
+    };
+    return {
+        /** One leaf block; container types are rejected. */
+        validateAtomicBlock: atomic,
+        /** One block of any kind, containers included. */
+        validateBlock: one,
+        /** A whole page's content array. */
+        validateBlocks: (content) => Array.isArray(content) && content.every(one),
+    };
+}
+/**
+ * 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) {
+    const b = block;
+    if (block.type === 'columns' && Array.isArray(b.columns)) {
+        return {
+            ...block,
+            id: newId(),
+            columns: b.columns.map(col => {
+                const c = col;
+                return { ...c, id: newId(), blocks: (c.blocks ?? []).map(x => ({ ...x, id: newId() })) };
+            }),
+        };
+    }
+    if (block.type === 'infobox' && Array.isArray(b.blocks)) {
+        return { ...block, id: newId(), blocks: b.blocks.map(x => ({ ...x, id: newId() })) };
+    }
+    return { ...block, id: newId() };
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/well-known.d.ts

@@ -0,0 +1,83 @@
+export interface RegistryAuthRecord {
+    body: string;
+    contentType: string;
+    cacheControl: string;
+}
+/**
+ * The `v=MCPv1` record the official MCP registry fetches from
+ * `/.well-known/mcp-registry-auth` to prove domain ownership. `mcp-publisher
+ * login http --domain=<host>` checks the key here against the private key
+ * signing the login, which is what grants publish rights over the reversed-
+ * domain namespace the server's name sits in.
+ *
+ * Returns null when no key is configured, so the caller can 404 rather than
+ * serve a malformed record — a missing key should read as "not configured",
+ * not as a verification failure nobody can explain.
+ *
+ * The key material belongs in an env var rather than the repo: the public half
+ * is harmless to serve but pointless to commit, and keeping it out gives the
+ * private half an obvious home too (a keychain, never git).
+ *
+ *   openssl genpkey -algorithm Ed25519 -out key.pem
+ *   openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
+ */
+export declare function registryAuthRecord(publicKey?: string, keyType?: string): RegistryAuthRecord | null;
+/** A day at the edge, a week stale-while-revalidate. A card changes rarely. */
+export declare const AGENT_CARD_CACHE_CONTROL = "public, s-maxage=86400, stale-while-revalidate=604800";
+export interface AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples?: string[];
+    authentication?: unknown;
+}
+/** The shape a tool needs to carry to become a skill. */
+export interface SkillSource {
+    name: string;
+    description: string;
+    skill?: {
+        id: string;
+        tags: string[];
+        examples?: string[];
+    } | undefined;
+    auth?: unknown;
+}
+/**
+ * Skills derived from the MCP tool manifest, so a card can never advertise a
+ * capability the server does not have. `search_pages` becomes "Search Pages".
+ */
+export declare function skillsFromTools(tools: readonly SkillSource[]): AgentSkill[];
+export interface AgentCardLicense {
+    name: string;
+    url: string;
+    spdx?: string;
+    /** What the licence covers, e.g. `'content'`. */
+    scope?: string;
+}
+export interface AgentCardConfig {
+    name: string;
+    description: string;
+    /** Origin, no trailing slash. Every derived URL below hangs off it. */
+    url: string;
+    version: string;
+    skills: AgentSkill[];
+    license?: AgentCardLicense;
+    /** Defaults to `name`. */
+    organization?: string;
+    /** Defaults to `${url}/llms.txt`. */
+    documentationUrl?: string;
+    /** Defaults to `${url}/api/mcp`. Pass null for an origin with no MCP server. */
+    mcpEndpoint?: string | null;
+    /** Anything this origin advertises that the others do not. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * An A2A Agent Card. Serve the same object at both `/.well-known/agent.json`
+ * and `/.well-known/agent-card.json`: v0.3 renamed the path and defined no
+ * fallback in either direction, so a spec-current client probes only the new
+ * one and a client on an older SDK probes only the old one. Serving one path
+ * means half the callers conclude the origin has no agent at all.
+ */
+export declare function agentCard(config: AgentCardConfig): Record<string, unknown>;
+//# sourceMappingURL=well-known.d.ts.map

package/dist/well-known.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.d.ts","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAQlG;AAID,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,0DAA0D,CAAC;AAEhG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,EAAE,CAW3E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiB1E"}

package/dist/well-known.js

@@ -0,0 +1,84 @@
+// well-known.ts — the descriptors an agent finds before it knows anything else
+// about an origin: the A2A Agent Card and the MCP registry's domain proof.
+//
+// All three apps here serve both, and all three had written them out. The
+// registry-auth handler was identical bar a domain named in a comment; the
+// agent cards shared an envelope, a skills mapping and a cache header, and
+// differed only in the fields a card is *supposed* to differ in.
+//
+// Nothing here touches a framework: these return plain values, and the caller
+// wraps them in whatever its router wants. That keeps this package free of a
+// Next dependency and keeps each app's route a two-liner.
+/**
+ * The `v=MCPv1` record the official MCP registry fetches from
+ * `/.well-known/mcp-registry-auth` to prove domain ownership. `mcp-publisher
+ * login http --domain=<host>` checks the key here against the private key
+ * signing the login, which is what grants publish rights over the reversed-
+ * domain namespace the server's name sits in.
+ *
+ * Returns null when no key is configured, so the caller can 404 rather than
+ * serve a malformed record — a missing key should read as "not configured",
+ * not as a verification failure nobody can explain.
+ *
+ * The key material belongs in an env var rather than the repo: the public half
+ * is harmless to serve but pointless to commit, and keeping it out gives the
+ * private half an obvious home too (a keychain, never git).
+ *
+ *   openssl genpkey -algorithm Ed25519 -out key.pem
+ *   openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
+ */
+export function registryAuthRecord(publicKey, keyType) {
+    if (!publicKey)
+        return null;
+    return {
+        // ed25519 unless a P-384 key was used instead (the LibreSSL-friendly path).
+        body: `v=MCPv1; k=${keyType || 'ed25519'}; p=${publicKey}\n`,
+        contentType: 'text/plain; charset=utf-8',
+        cacheControl: 'no-store',
+    };
+}
+// ---- A2A Agent Card ---------------------------------------------------------
+/** A day at the edge, a week stale-while-revalidate. A card changes rarely. */
+export const AGENT_CARD_CACHE_CONTROL = 'public, s-maxage=86400, stale-while-revalidate=604800';
+/**
+ * Skills derived from the MCP tool manifest, so a card can never advertise a
+ * capability the server does not have. `search_pages` becomes "Search Pages".
+ */
+export function skillsFromTools(tools) {
+    return tools
+        .filter(t => t.skill)
+        .map(t => ({
+        id: t.skill.id,
+        name: t.name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+        description: t.description,
+        tags: t.skill.tags,
+        ...(t.skill.examples ? { examples: t.skill.examples } : {}),
+        ...(t.auth ? { authentication: t.auth } : {}),
+    }));
+}
+/**
+ * An A2A Agent Card. Serve the same object at both `/.well-known/agent.json`
+ * and `/.well-known/agent-card.json`: v0.3 renamed the path and defined no
+ * fallback in either direction, so a spec-current client probes only the new
+ * one and a client on an older SDK probes only the old one. Serving one path
+ * means half the callers conclude the origin has no agent at all.
+ */
+export function agentCard(config) {
+    const { name, description, url, version, skills, license, organization, documentationUrl, mcpEndpoint, extra } = config;
+    return {
+        name,
+        description,
+        url,
+        version,
+        capabilities: { streaming: false, pushNotifications: false },
+        skills,
+        provider: { organization: organization ?? name, url },
+        documentationUrl: documentationUrl ?? `${url}/llms.txt`,
+        ...(mcpEndpoint === null ? {} : { mcpEndpoint: mcpEndpoint ?? `${url}/api/mcp` }),
+        ...(license ? { license } : {}),
+        ...extra,
+        defaultInputModes: ['text/plain', 'application/json'],
+        defaultOutputModes: ['text/plain', 'application/json', 'text/markdown'],
+    };
+}
+//# sourceMappingURL=well-known.js.map

package/dist/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,2EAA2E;AAC3E,iEAAiE;AACjE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,0DAA0D;AAU1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAkB,EAAE,OAAgB;IACrE,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO;QACL,4EAA4E;QAC5E,IAAI,EAAE,cAAc,OAAO,IAAI,SAAS,OAAO,SAAS,IAAI;QAC5D,WAAW,EAAE,2BAA2B;QACxC,YAAY,EAAE,UAAU;KACzB,CAAC;AACJ,CAAC;AAED,gFAAgF;AAEhF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,uDAAuD,CAAC;AAmBhG;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAA6B;IAC3D,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACT,EAAE,EAAE,CAAC,CAAC,KAAM,CAAC,EAAE;QACf,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACtE,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,IAAI,EAAE,CAAC,CAAC,KAAM,CAAC,IAAI;QACnB,GAAG,CAAC,CAAC,CAAC,KAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC,CAAC,CAAC;AACR,CAAC;AA4BD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAuB;IAC/C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACxH,OAAO;QACL,IAAI;QACJ,WAAW;QACX,GAAG;QACH,OAAO;QACP,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE;QAC5D,MAAM;QACN,QAAQ,EAAE,EAAE,YAAY,EAAE,YAAY,IAAI,IAAI,EAAE,GAAG,EAAE;QACrD,gBAAgB,EAAE,gBAAgB,IAAI,GAAG,GAAG,WAAW;QACvD,GAAG,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,IAAI,GAAG,GAAG,UAAU,EAAE,CAAC;QACjF,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,KAAK;QACR,iBAAiB,EAAE,CAAC,YAAY,EAAE,kBAAkB,CAAC;QACrD,kBAAkB,EAAE,CAAC,YAAY,EAAE,kBAAkB,EAAE,eAAe,CAAC;KACxE,CAAC;AACJ,CAAC"}