wiki-formant 0.13.0 → 0.16.0

package/dist/editor.js

@@ -0,0 +1,218 @@
+'use client';
+// editor.tsx — the wiki rich-text editor's engine, minus its chrome.
+//
+// `tiptap.tsx` holds the custom NODES both wikis needed (iframe, tweet, map,
+// code block, tabs). This holds what sits around them: which extensions are
+// configured how, what a paste is scrubbed down to, how a pasted URL becomes
+// the right embed, and the state a toolbar reads. Those were byte-identical in
+// both repos — the same twelve-entry extension array, the same paste scrubber,
+// the same embed dispatch including the shortened-map async swap.
+//
+// TWO BUGS ARE FIXED HERE RATHER THAN PROPAGATED, and the reason this file
+// exists at all is that each repo had exactly one of them:
+//
+//   1. `onChangeRef.current = onChange` was written DURING render in one copy.
+//      A ref mutated mid-render can tear under concurrent rendering. It is
+//      written in an effect here, and only read from events and timeouts, which
+//      run later.
+//   2. The other copy had no `onBlur`. The change is debounced 150ms, and
+//      clicking Save blurs the editor before the click lands — so the final
+//      keystroke of every edit that ended in a click was dropped. Blur flushes
+//      the pending debounce.
+//
+// Neither repo was "behind": each had shipped the fix the other lacked, which
+// is the drift that costs the most, because neither file looks like the one to
+// fix.
+//
+// Every @tiptap package here is an OPTIONAL PEER. A consumer that only wants
+// the taxonomy or the MCP transport installs none of them.
+import StarterKit from '@tiptap/starter-kit';
+import TiptapLink from '@tiptap/extension-link';
+import TiptapImage from '@tiptap/extension-image';
+import TiptapTable from '@tiptap/extension-table';
+import TiptapTableRow from '@tiptap/extension-table-row';
+import TiptapTableCell from '@tiptap/extension-table-cell';
+import TiptapTableHeader from '@tiptap/extension-table-header';
+import Placeholder from '@tiptap/extension-placeholder';
+import { useEditor } from '@tiptap/react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { toMapEmbedUrl } from './maps.js';
+// ---- paste scrubbing --------------------------------------------------------
+/**
+ * Reduce pasted HTML to structure plus the three attributes that carry meaning.
+ *
+ * A paste from a word processor or a web page arrives carrying its whole
+ * stylesheet inline. Keeping any of it means the wiki's own typography loses to
+ * whatever the author copied from, per paragraph, invisibly — and `style` on a
+ * pasted node is also the cheapest way to smuggle a full-bleed overlay into a
+ * page body.
+ *
+ * Browser-only: it parses with `DOMParser`. Called from `transformPastedHTML`,
+ * which only ever runs in response to a paste.
+ */
+export function cleanPastedHtml(html) {
+    const doc = new DOMParser().parseFromString(html, 'text/html');
+    doc.querySelectorAll('style, script, meta, link, svg, canvas, noscript').forEach(el => el.remove());
+    doc.querySelectorAll('*').forEach(el => {
+        el.removeAttribute('style');
+        el.removeAttribute('class');
+        el.removeAttribute('id');
+        Array.from(el.attributes).forEach(attr => {
+            if (!['href', 'src', 'alt'].includes(attr.name))
+                el.removeAttribute(attr.name);
+        });
+    });
+    return doc.body.innerHTML;
+}
+/**
+ * The editor's extension set.
+ *
+ * `codeBlock: false` on StarterKit is load-bearing: the consumer registers its
+ * own via `createCodeBlock`, and leaving StarterKit's in place would give the
+ * schema two nodes claiming the same name. Headings stop at h2 — the page title
+ * is the only h1 a wiki page has.
+ */
+export function wikiEditorExtensions({ placeholder = '', nodes = [], } = {}) {
+    return [
+        StarterKit.configure({ heading: { levels: [2, 3, 4] }, codeBlock: false }),
+        TiptapLink.configure({ openOnClick: false, HTMLAttributes: { class: 'link' } }),
+        TiptapImage.configure({
+            inline: false,
+            allowBase64: true,
+            HTMLAttributes: { class: 'rounded-lg max-w-full' },
+        }),
+        TiptapTable.configure({ resizable: false, HTMLAttributes: { class: 'tiptap-table' } }),
+        TiptapTableRow,
+        TiptapTableCell.configure({ HTMLAttributes: { class: 'p-2' } }),
+        TiptapTableHeader.configure({ HTMLAttributes: { class: 'p-2 font-semibold bg-surface-1' } }),
+        ...nodes,
+        Placeholder.configure({ placeholder }),
+    ];
+}
+// ---- pasted URLs ------------------------------------------------------------
+const YOUTUBE = /(?:youtube\.com\/(?:watch\?v=|embed\/|shorts\/)|youtu\.be\/)([a-zA-Z0-9_-]+)/;
+const TWEET = /(?:twitter\.com|x\.com)\/\w+\/status\/(\d+)/;
+const SHORT_MAP = /maps\.app\.goo\.gl|goo\.gl\/maps/;
+/**
+ * Turn a pasted URL into the richest node that fits it, falling back to a bare
+ * iframe. Order matters: a YouTube URL is also a valid iframe source, so the
+ * specific cases have to be tried before the general one.
+ *
+ * A shortened map link inserts IMMEDIATELY with `about:blank` and swaps its
+ * `src` once the redirect resolves. Pasting must not block on a network hop,
+ * and the node has to already exist for the reader to see anything happen. The
+ * swap re-finds the node by its `url` attribute rather than caching a position,
+ * because every keystroke between the paste and the resolve moves it.
+ */
+export function insertEmbed(editor, url, { resolveMapUrl }) {
+    const yt = url.match(YOUTUBE);
+    if (yt) {
+        editor.chain().focus().setYoutubeVideo({ src: url }).run();
+        return;
+    }
+    const tw = url.match(TWEET);
+    if (tw) {
+        editor.chain().focus().insertContent({ type: 'twitterEmbed', attrs: { tweetId: tw[1], url } }).run();
+        return;
+    }
+    const mapSrc = toMapEmbedUrl(url);
+    if (mapSrc) {
+        editor.chain().focus().insertContent({ type: 'mapEmbed', attrs: { src: mapSrc, url } }).run();
+        return;
+    }
+    if (SHORT_MAP.test(url)) {
+        editor.chain().focus().insertContent({ type: 'mapEmbed', attrs: { src: 'about:blank', url } }).run();
+        void resolveMapUrl(url).then(src => {
+            if (!src)
+                return;
+            editor.state.doc.descendants((node, pos) => {
+                if (node.type.name === 'mapEmbed' && node.attrs.url === url && node.attrs.src === 'about:blank') {
+                    editor.chain().setNodeSelection(pos).updateAttributes('mapEmbed', { src }).run();
+                    return false;
+                }
+                return true;
+            });
+        });
+        return;
+    }
+    editor.chain().focus().insertContent({ type: 'iframe', attrs: { src: url } }).run();
+}
+/** The table controls, shown only while the selection is inside a table. */
+export const TABLE_ACTIONS = [
+    ['addColumnAfter', '+Col'],
+    ['addRowAfter', '+Row'],
+    ['deleteColumn', '-Col', true],
+    ['deleteRow', '-Row', true],
+    ['deleteTable', '-Tbl', true],
+];
+/**
+ * The editor, its upload plumbing and the state a toolbar reads.
+ *
+ * The toolbar itself stays with the consumer: the two wikis differ on which
+ * buttons exist, which icon set draws them, and whether a link is entered in a
+ * `window.prompt` or an inline field. Those are real differences. What they had
+ * no business differing on is everything below.
+ */
+export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], proseClass, uploadImage, debounceMs = 150, }) {
+    const fileInputRef = useRef(null);
+    const [isUploading, setIsUploading] = useState(false);
+    const initialValueRef = useRef(value);
+    const onChangeRef = useRef(onChange);
+    const debounceRef = useRef(undefined);
+    // Written AFTER render, not during: a ref mutated mid-render can tear under
+    // concurrent rendering. Only read from events and timeouts, which run later.
+    useEffect(() => {
+        onChangeRef.current = onChange;
+    });
+    const extensions = useMemo(() => wikiEditorExtensions({ placeholder, nodes }), 
+    // `nodes` is built with `useMemo` by the consumer; rebuilding the array on
+    // every render would tear the editor down and lose the selection.
+    [placeholder, nodes]);
+    const editor = useEditor({
+        extensions,
+        editorProps: {
+            attributes: { class: `outline-none focus:outline-none ${proseClass} min-h-20` },
+            transformPastedHTML: cleanPastedHtml,
+        },
+        onUpdate: ({ editor }) => {
+            clearTimeout(debounceRef.current);
+            debounceRef.current = setTimeout(() => onChangeRef.current(editor.getHTML()), debounceMs);
+        },
+        // Flush the pending debounce on blur, so a quick Save — which blurs the
+        // editor before the click fires — never drops the final keystroke.
+        onBlur: ({ editor }) => {
+            clearTimeout(debounceRef.current);
+            onChangeRef.current(editor.getHTML());
+        },
+        immediatelyRender: false,
+        onCreate: ({ editor }) => {
+            if (initialValueRef.current) {
+                queueMicrotask(() => editor.commands.setContent(initialValueRef.current));
+            }
+        },
+    });
+    useEffect(() => () => clearTimeout(debounceRef.current), []);
+    // Accept an outside change, but never while the author is typing into it.
+    useEffect(() => {
+        if (!editor || editor.isFocused)
+            return;
+        if (editor.getHTML() !== value)
+            editor.commands.setContent(value);
+    }, [value, editor]);
+    const handleFileChange = useCallback(async (e) => {
+        const file = e.target.files?.[0];
+        if (!file || !editor)
+            return;
+        setIsUploading(true);
+        const url = await uploadImage(file);
+        if (url)
+            editor.chain().focus().setImage({ src: url }).run();
+        setIsUploading(false);
+        // Cleared so choosing the same file twice in a row still fires a change.
+        if (fileInputRef.current)
+            fileInputRef.current.value = '';
+    }, [editor, uploadImage]);
+    const triggerUpload = useCallback(() => fileInputRef.current?.click(), []);
+    const isActive = useCallback((a) => a ? Boolean(Array.isArray(a) ? editor?.isActive(a[0], a[1]) : editor?.isActive(a)) : false, [editor]);
+    return { editor, fileInputRef, isUploading, handleFileChange, triggerUpload, isActive };
+}

package/dist/feed.d.ts

@@ -54,4 +54,3 @@ export interface FeedChannel {
  */
 export declare function renderFeed(channel: FeedChannel, items: readonly FeedItem[]): string;
 export declare const FEED_HEADERS: Record<string, string>;
-//# sourceMappingURL=feed.d.ts.map

package/dist/feed.js

@@ -92,4 +92,3 @@ export const FEED_HEADERS = {
     'Content-Type': 'application/rss+xml; charset=utf-8',
     'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
 };
-//# sourceMappingURL=feed.js.map

package/dist/freshness.d.ts

@@ -17,4 +17,3 @@ export declare function isStale(page: FreshnessInput, now: number, maxAgeDays?:
  * being re-typed either side of the extraction.
  */
 export declare function freshnessNotice(page: FreshnessInput): string;
-//# sourceMappingURL=freshness.d.ts.map

package/dist/freshness.js

@@ -8,6 +8,7 @@
 // `now` is a parameter rather than a `Date.now()` call inside the function.
 // This runs during SSR, and a render that reads the clock is a render that can
 // disagree with the one the server just sent.
+import { isoDate } from './html.js';
 export const DEFAULT_MAX_AGE_DAYS = 180;
 const DAY_MS = 86_400_000;
 /** Whole days between `date` and `now`, or null when there is no usable date. */
@@ -35,8 +36,7 @@ export function isStale(page, now, maxAgeDays = DEFAULT_MAX_AGE_DAYS) {
  */
 export function freshnessNotice(page) {
     const when = page.lastVerifiedAt
-        ? `last verified ${new Date(page.lastVerifiedAt).toISOString().slice(0, 10)}`
+        ? `last verified ${isoDate(new Date(page.lastVerifiedAt))}`
         : 'not yet verified against sources';
     return `This page was ${when} and may be out of date. Please help re-check its facts against current sources and the live ledger.`;
 }
-//# sourceMappingURL=freshness.js.map

package/dist/headings.d.ts

@@ -39,4 +39,3 @@ export declare function injectHeadingIds(html: string, options?: HeadingIdOption
  * consumers use only the injector above.
  */
 export declare function headingsFrom(html: string): Heading[];
-//# sourceMappingURL=headings.d.ts.map

package/dist/headings.js

@@ -17,6 +17,7 @@
 // otherwise mint the same id twice and every link to the second one lands on
 // the first. That was already a bug in the copy that lacked it, so this always
 // dedupes.
+import { getAttr, stripTags } from './html.js';
 /** The default slug rule: lowercase words joined by hyphens. */
 export function slugifyHeading(text) {
     return text
@@ -27,8 +28,6 @@ export function slugifyHeading(text) {
         .replace(/^-+|-+$/g, '');
 }
 const HEADING = /<(h[1-6])([^>]*)>([\s\S]*?)<\/\1>/gi;
-const stripTags = (s) => s.replace(/<[^>]*>/g, '').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').trim();
-const getAttr = (attrs, name) => attrs.match(new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? null;
 const defaultAnchor = (id) => `<a class="heading-anchor" href="#${id}" aria-label="Permalink to this section" tabindex="-1"></a>`;
 /**
  * Give every heading in `html` an id and a permalink anchor. Headings that
@@ -78,4 +77,3 @@ export function headingsFrom(html) {
     }
     return out;
 }
-//# sourceMappingURL=headings.js.map

package/dist/html.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tags out, the two entities that survive a strip decoded, whitespace trimmed.
+ *
+ * The ` `/`&` pass is not decoration: an anchor whose text is only a
+ * non-breaking space is an empty anchor, and without decoding it reads as
+ * non-empty and keeps its blank label.
+ */
+export declare const stripTags: (s: string) => string;
+/** Read one double-quoted attribute out of a tag's attribute string. */
+export declare const getAttr: (attrs: string, name: string) => string | null;
+/** Drop every occurrence of one attribute from a tag's attribute string. */
+export declare const removeAttr: (attrs: string, name: string) => string;
+/** `YYYY-MM-DD`, from either a Date or a string that already starts with one. */
+export declare const isoDate: (d: Date | string) => string;
+/** Join class names, dropping the falsy ones. The package depends on no `cn`. */
+export declare const cx: (...parts: (string | false | undefined)[]) => string;

package/dist/html.js

@@ -0,0 +1,23 @@
+// html.ts — the small string helpers several modules had each written for
+// themselves. Internal: no subpath, not in the root barrel.
+//
+// Every one of these existed two, three or four times in this package, which is
+// the same fault it was extracted to fix — the module headers in `headings.ts`
+// and `text.ts` both record having inherited a copy from a sibling repo, and
+// then the extraction kept the copy.
+/**
+ * Tags out, the two entities that survive a strip decoded, whitespace trimmed.
+ *
+ * The ` `/`&` pass is not decoration: an anchor whose text is only a
+ * non-breaking space is an empty anchor, and without decoding it reads as
+ * non-empty and keeps its blank label.
+ */
+export const stripTags = (s) => s.replace(/<[^>]*>/g, '').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').trim();
+/** Read one double-quoted attribute out of a tag's attribute string. */
+export 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. */
+export const removeAttr = (attrs, name) => attrs.replace(new RegExp(`\\s${name}\\s*=\\s*"[^"]*"`, 'gi'), '');
+/** `YYYY-MM-DD`, from either a Date or a string that already starts with one. */
+export const isoDate = (d) => (typeof d === 'string' ? d : d.toISOString()).split('T')[0];
+/** Join class names, dropping the falsy ones. The package depends on no `cn`. */
+export const cx = (...parts) => parts.filter(Boolean).join(' ');

package/dist/http.d.ts

@@ -81,4 +81,23 @@ export declare function pageLine(opts: {
     excerpt?: string;
     updated?: Date | string | null;
 }): string;
-//# sourceMappingURL=http.d.ts.map
+/** The pair every corpus endpoint computes before it decides to render. */
+export interface CorpusValidators {
+    etag: string;
+    lastModified: string;
+}
+/**
+ * A GET handler serving `build()` under corpus validators — or a 304 instead.
+ *
+ * The build is not called on a 304, which is the whole point: these are the
+ * most-recrawled and most expensive URLs a wiki serves, and rendering a corpus
+ * to discard it is the cost this exists to avoid.
+ *
+ * `validators` is a thunk rather than a value because it is a query. The depth
+ * or scope it closes over belongs in the seed — three depths sharing one ETag
+ * is legal (a tag is scoped to its URI) and still wrong in the case that
+ * matters: an edit to one depth's own preamble moves no page row, so the tag
+ * would not move and the stale document would be served until something else
+ * in the corpus changed.
+ */
+export declare function corpusRoute(validators: () => Promise<CorpusValidators> | CorpusValidators, build: () => Promise<string> | string, headers?: (etag: string, lastModified: string) => Record<string, string>): (request: Request) => Promise<Response>;

package/dist/http.js

@@ -4,6 +4,7 @@
 // most-recrawled URLs a wiki serves and the most expensive to render. With a
 // corpus-derived ETag a recrawl costs a 304 instead of a full corpus build.
 // Without one, every AI crawler pays full price on every pass, forever.
+import { isoDate } from './html.js';
 /** A stable ETag from whatever the corpus revision is (count + newest stamp). */
 export function corpusEtag(parts) {
     const seed = parts
@@ -151,9 +152,27 @@ export function cleanSnippet(text, max = 160) {
 /** One markdown bullet: linked title, excerpt, and the date an agent diffs on. */
 export function pageLine(opts) {
     const excerpt = opts.excerpt ? `: ${cleanSnippet(opts.excerpt)}` : '';
-    const stamp = opts.updated
-        ? (typeof opts.updated === 'string' ? opts.updated : opts.updated.toISOString()).split('T')[0]
-        : '';
+    const stamp = opts.updated ? isoDate(opts.updated) : '';
     return `- [${opts.title}](${opts.url})${excerpt}${stamp ? ` _(updated ${stamp})_` : ''}`;
 }
-//# sourceMappingURL=http.js.map
+/**
+ * A GET handler serving `build()` under corpus validators — or a 304 instead.
+ *
+ * The build is not called on a 304, which is the whole point: these are the
+ * most-recrawled and most expensive URLs a wiki serves, and rendering a corpus
+ * to discard it is the cost this exists to avoid.
+ *
+ * `validators` is a thunk rather than a value because it is a query. The depth
+ * or scope it closes over belongs in the seed — three depths sharing one ETag
+ * is legal (a tag is scoped to its URI) and still wrong in the case that
+ * matters: an edit to one depth's own preamble moves no page row, so the tag
+ * would not move and the stale document would be served until something else
+ * in the corpus changed.
+ */
+export function corpusRoute(validators, build, headers = textHeaders) {
+    return async (request) => {
+        const { etag, lastModified } = await validators();
+        return (notModified(request, etag, lastModified) ??
+            new Response(await build(), { headers: headers(etag, lastModified) }));
+    };
+}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export * from './mcp.js';
 export * from './headings.js';
 export * from './links.js';
 export * from './markdown.js';
-export * from './entities.js';
+export * from './markdown.js';
 export * from './http.js';
 export * from './pagination.js';
 export * from './versioning.js';
@@ -18,4 +18,4 @@ export * from './crawlers.js';
 export * from './revisions.js';
 export * from './feed.js';
 export * from './license.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './seeded.js';

package/dist/index.js

@@ -8,7 +8,7 @@ export * from './mcp.js';
 export * from './headings.js';
 export * from './links.js';
 export * from './markdown.js';
-export * from './entities.js';
+export * from './markdown.js';
 export * from './http.js';
 export * from './pagination.js';
 export * from './versioning.js';
@@ -23,4 +23,4 @@ export * from './crawlers.js';
 export * from './revisions.js';
 export * from './feed.js';
 export * from './license.js';
-//# sourceMappingURL=index.js.map
+export * from './seeded.js';

package/dist/license.d.ts

@@ -43,4 +43,3 @@ export declare function licenseLines({ license, scope, scopeVerb, excludes, head
 export declare function licenseBlock(opts: LicenseBlockOptions): string;
 /** The one-line form, for a frontmatter field or a feed's `<copyright>`. */
 export declare function licenseNote(license: License): string;
-//# sourceMappingURL=license.d.ts.map

package/dist/license.js

@@ -47,4 +47,3 @@ export function licenseBlock(opts) {
 export function licenseNote(license) {
     return `${license.name} (${license.spdx}): ${license.url}`;
 }
-//# sourceMappingURL=license.js.map

package/dist/link-check.d.ts

@@ -0,0 +1,92 @@
+export interface Probe {
+    url: string;
+    status: number;
+    ok: boolean;
+    error?: string;
+    code?: string;
+    tls?: string;
+    note?: string;
+    contentType?: string;
+    bytes?: number;
+}
+export interface ProbeOptions {
+    /** Ordinary per-attempt budget. */
+    timeoutMs?: number;
+    /** Second-attempt budget for a host that is merely slow. */
+    slowTimeoutMs?: number;
+}
+/**
+ * Codes that flap. A sweep found 16 status-0 rows and 15 were one host, every
+ * one answering 200 when probed alone. Carry the code through so a caller can
+ * treat these as retryable rather than banking a death.
+ */
+export declare const TRANSIENT_CODES: Set<string>;
+/** A failure as a report row: the message, the code, and the TLS caveat. */
+export declare function describeFailure(err: unknown): Pick<Probe, 'error' | 'code' | 'tls' | 'note'>;
+/**
+ * The URL to probe INSTEAD, where the public page lies about its own health.
+ *
+ * npmjs.com serves 403 to scripted requests whether or not the package exists,
+ * which made every package citation a permanent false positive. The registry
+ * answers honestly.
+ */
+export declare function probeUrlFor(url: string): string;
+/**
+ * Run `fn` with at most one request in flight against this hostname.
+ *
+ * ECONNREFUSED looks deterministic and is not. A delayed retry was tried first
+ * and made things worse — 269 to 277 broken, the refusals unchanged and 8 fresh
+ * timeouts on hosts that had been fine — because the problem is not timing, it
+ * is how many sockets one host is asked for at once. The global pool still runs
+ * wide across DIFFERENT hosts; any single host is probed one request at a time,
+ * exactly as a hand re-probe does it.
+ */
+export declare function perHost<T>(url: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Probe one URL, honestly.
+ *
+ * A timeout is not a death and neither is a dropped connection: slow replays —
+ * web.archive.org above all, which a sweep leans on to rescue dying citations —
+ * exceed the ordinary budget and land as status 0. So a status-0 result with a
+ * transient code earns one more attempt on the longer budget before it is
+ * reported. A 404 does not: it is an answer.
+ */
+export declare function probeUrl(url: string, opts?: ProbeOptions): Promise<Probe>;
+export declare const YOUTUBE_EMBED: RegExp;
+/**
+ * A YouTube `/embed/<id>` URL answers 200 for private, deleted and
+ * playback-restricted videos alike, so HEADing it can never spot a dead hero
+ * video. oEmbed can:
+ *
+ *   200 → public and embeddable | 404 → deleted | 401/403 → private or embedding off
+ */
+export declare function probeYouTube(videoId: string, opts?: ProbeOptions): Promise<{
+    status: number;
+    ok: boolean;
+    reason?: string;
+    error?: string;
+}>;
+/** An external anchor, with a video treated as a video. */
+export declare function probeExternal(url: string, opts?: ProbeOptions): Promise<Probe & {
+    videoId?: string;
+}>;
+/**
+ * Hosts that answer 200 with a JavaScript loader shell regardless of whether
+ * the deck / store / dataset behind the query string still exists. A status
+ * check on these is meaningless, so a caller should report them as unverifiable
+ * rather than healthy — a green row is worse than an unknown one, because
+ * nobody looks at it again.
+ */
+export declare function unverifiableReason(url: string, hosts: ReadonlyMap<string, string>): string | null;
+/** Every anchor in a fragment, as `{ href, text }`. */
+export declare function extractLinks(html: string): Array<{
+    href: string;
+    text: string;
+}>;
+/** Every `<iframe>` and `<img>` source in a fragment. */
+export declare function extractEmbeds(html: string): Array<{
+    kind: string;
+    url: string;
+}>;
+/** `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[]>;