wiki-formant 0.2.1 → 0.4.0

package/dist/links.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A readable label for an anchor whose text is empty, derived from its href.
+ * Without one, crawlers and screen readers meet a link with nothing in it.
+ */
+export declare function fallbackAnchorText(href: string): string;
+export interface NormaliseLinkOptions {
+    /**
+     * This wiki's own origin. An absolute link back to it is really internal, so
+     * it is folded to a relative path and navigates in place instead of opening a
+     * new tab. Matched case-insensitively, with or without a `www.` prefix.
+     * e.g. `'radix.wiki'` or `'caper.network'`.
+     */
+    selfHost?: string;
+    /**
+     * Shared across one document so a `#ref-n` citation can be given a
+     * `id="cite-n"` target exactly once — the reference list renders a `^`
+     * back-link to it. Pass the same Set for every block of a page.
+     */
+    citedRefs?: Set<number>;
+    /**
+     * Give an empty anchor a synthesised label. On by default; pass `false` to
+     * keep an empty anchor empty.
+     */
+    fallbackText?: boolean;
+}
+/**
+ * Tag every anchor in `html` as internal or external. Attribute-order agnostic;
+ * nested `<a>` is not handled, being invalid HTML anyway.
+ */
+export declare function normaliseLinks(html: string, options?: NormaliseLinkOptions): string;
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAyCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAMvF"}

package/dist/links.js

@@ -0,0 +1,81 @@
+// links.ts — internal vs. external link normalisation for wiki content.
+//
+// The editor stores whatever href an author types. At render time a wiki has to
+// draw the line between *internal* links (relative paths, in-page anchors, and
+// absolute links back to its own host) and *external* ones: externals open in a
+// new tab with a safe rel, internals navigate in place, and CSS keys off the
+// same distinction to tint one and badge the other.
+//
+// Both wikis had written this out — caper's `normaliseLinks`, radix-wiki's
+// anchor branch in `processHtml` — down to identical `getAttr` and `removeAttr`
+// helpers and the same `#ref-n` -> `id="cite-n"` citation wiring. caper's file
+// said "ported from radix-wiki" at the top, which is the drift admitting itself.
+//
+// What they drifted on: only radix-wiki synthesised a label for an anchor with
+// no visible text. That is an accessibility fix, not a preference, so it is the
+// default here and caper gains it by adopting this module.
+/** Read one double-quoted attribute out of a tag's attribute string. */
+const getAttr = (attrs, name) => attrs.match(new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? null;
+/** Drop every occurrence of one attribute from a tag's attribute string. */
+const removeAttr = (attrs, name) => attrs.replace(new RegExp(`\\s${name}\\s*=\\s*"[^"]*"`, 'gi'), '');
+const stripTags = (s) => s.replace(/<[^>]*>/g, '').trim();
+/**
+ * A readable label for an anchor whose text is empty, derived from its href.
+ * Without one, crawlers and screen readers meet a link with nothing in it.
+ */
+export function fallbackAnchorText(href) {
+    if (href.startsWith('#'))
+        return href.slice(1).replace(/-/g, ' ') || 'section';
+    if (href.startsWith('/')) {
+        const last = href.split('/').filter(Boolean).pop();
+        return last ? last.replace(/-/g, ' ') : 'page';
+    }
+    try {
+        return new URL(href).hostname.replace(/^www\./, '') || href;
+    }
+    catch {
+        return href;
+    }
+}
+const ANCHOR = /<a\b([^>]*)>([\s\S]*?)<\/a>/gi;
+function selfHostPattern(host) {
+    const escaped = host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^https?://(?:www\\.)?${escaped}(/[^\\s"]*)?$`, 'i');
+}
+function normaliseAnchor(attrs, inner, opts, self) {
+    // Injected heading permalink anchors carry their glyph via CSS. Leave them
+    // alone — in particular the empty-text synthesis below must not fill them,
+    // or the label leaks into the heading's textContent and out into a TOC.
+    if (/\bheading-anchor\b/.test(attrs))
+        return `<a${attrs}>${inner}</a>`;
+    const rawHref = getAttr(attrs, 'href');
+    if (rawHref == null)
+        return `<a${attrs}>${inner}</a>`;
+    const href = self ? rawHref.replace(self, (_m, path) => path || '/') : rawHref;
+    const isInternal = href.startsWith('/') || href.startsWith('#');
+    // Drop any author-supplied target/rel; both are re-derived from the link kind.
+    let rest = removeAttr(removeAttr(removeAttr(attrs, 'href'), 'rel'), 'target');
+    const refMatch = opts.citedRefs ? href.match(/^#ref-(\d+)$/) : null;
+    if (refMatch && !/\bid\s*=/.test(rest)) {
+        const n = Number(refMatch[1]);
+        if (!opts.citedRefs.has(n)) {
+            opts.citedRefs.add(n);
+            rest = ` id="cite-${n}"${rest}`;
+        }
+    }
+    const safeInner = opts.fallbackText === false || stripTags(inner) ? inner : fallbackAnchorText(href);
+    return isInternal
+        ? `<a href="${href}"${rest}>${safeInner}</a>`
+        : `<a href="${href}"${rest} target="_blank" rel="noopener">${safeInner}</a>`;
+}
+/**
+ * Tag every anchor in `html` as internal or external. Attribute-order agnostic;
+ * nested `<a>` is not handled, being invalid HTML anyway.
+ */
+export function normaliseLinks(html, options = {}) {
+    if (!html.trim())
+        return html;
+    const self = options.selfHost ? selfHostPattern(options.selfHost) : null;
+    return html.replace(ANCHOR, (_m, attrs, inner) => normaliseAnchor(attrs, inner, options, self));
+}
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,6EAA6E;AAC7E,oDAAoD;AACpD,EAAE;AACF,2EAA2E;AAC3E,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AACjF,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,2DAA2D;AAE3D,wEAAwE;AACxE,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,IAAY,EAAiB,EAAE,CAC7D,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,oBAAoB,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAE5E,4EAA4E;AAC5E,MAAM,UAAU,GAAG,CAAC,KAAa,EAAE,IAAY,EAAU,EAAE,CACzD,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,kBAAkB,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;AAEpE,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAE1E;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,SAAS,CAAC;IAC/E,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjD,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAuBD,MAAM,MAAM,GAAG,+BAA+B,CAAC;AAE/C,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,MAAM,CAAC,wBAAwB,OAAO,eAAe,EAAE,GAAG,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,eAAe,CAAC,KAAa,EAAE,KAAa,EAAE,IAA0B,EAAE,IAAmB;IACpG,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,KAAK,IAAI,KAAK,MAAM,CAAC;IAEvE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACvC,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,KAAK,KAAK,IAAI,KAAK,MAAM,CAAC;IAEtD,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACvF,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAEhE,+EAA+E;IAC/E,IAAI,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IAE9E,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpE,IAAI,QAAQ,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,SAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,SAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvB,IAAI,GAAG,aAAa,CAAC,IAAI,IAAI,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GACb,IAAI,CAAC,YAAY,KAAK,KAAK,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAErF,OAAO,UAAU;QACf,CAAC,CAAC,YAAY,IAAI,IAAI,IAAI,IAAI,SAAS,MAAM;QAC7C,CAAC,CAAC,YAAY,IAAI,IAAI,IAAI,mCAAmC,SAAS,MAAM,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAAgC,EAAE;IAC7E,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,KAAa,EAAE,KAAa,EAAE,EAAE,CAC/D,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAC7C,CAAC;AACJ,CAAC"}

package/dist/maps.d.ts

@@ -0,0 +1,21 @@
+export interface MapCoords {
+    lat: number;
+    lon: number;
+    zoom?: number | undefined;
+}
+/** A plain embed URL for a coordinate pair. */
+export declare function mapsEmbedUrl(lat: number, lon: number, zoom?: number): string;
+/**
+ * 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 declare function extractCoordsFromUrl(url: string): MapCoords | null;
+/**
+ * An embeddable URL for `url`, or null when it is not a map link this
+ * 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;
+//# sourceMappingURL=maps.d.ts.map

package/dist/maps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maps.d.ts","sourceRoot":"","sources":["../src/maps.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAExE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAoBlE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6BxD;AAED,qEAAqE;AACrE,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,OACE,CAAC"}

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":"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"}

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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"}