wiki-formant 0.4.1 → 0.8.0

package/dist/dom.d.ts

@@ -0,0 +1,69 @@
+export interface CopyButtonOptions {
+    /** Class on the injected button. Style it in your own stylesheet. */
+    className?: string;
+    label?: string;
+    /** How long the tick shows before reverting to the copy glyph, in ms. */
+    revertAfter?: number;
+}
+/**
+ * Give every `<pre>` under `root` a copy button, once.
+ *
+ * Idempotent by inspection rather than by selector: both wikis called this
+ * through `pre:not(:has(.code-copy-btn))`, which puts the guard at the call
+ * site — where it can be, and was, retyped. Checking inside means a caller
+ * that passes a plain `pre` selector still cannot double up, and it drops the
+ * `:has()` dependency along the way.
+ *
+ * Returns the number of buttons added, so a caller can skip work when zero.
+ */
+export declare function addCopyButtons(root: ParentNode, options?: CopyButtonOptions): number;
+/**
+ * The one place this origin is written down. It is both the embed host and the
+ * allow-list the resize listener checks, and it was previously spelled out at
+ * four call sites across the two wikis.
+ */
+export declare const TWITTER_ORIGIN = "https://platform.twitter.com";
+/** The embed iframe's src. `dnt=true` opts the embed out of Twitter's tracking. */
+export declare const tweetEmbedSrc: (tweetId: string | number) => string;
+/**
+ * Subscribe to the height the embed posts back once it has laid itself out.
+ *
+ * The iframe renders at an unknown height and there is no other way to learn
+ * it. The caller decides which iframes the height applies to; this only owns
+ * the origin check and the message shape. Returns a disposer.
+ */
+export declare function onTweetResize(resize: (height: number) => void): () => void;
+/**
+ * Point every un-hydrated `[data-twitter-embed]` placeholder under `root` at
+ * the real embed URL.
+ *
+ * Stored article HTML carries the placeholder markup; the iframe only gets a
+ * live `src` once it is in the document. Marked with `data-init` so a re-render
+ * of the same content does not reload every embed on the page.
+ */
+export declare function hydrateTweetEmbeds(root: ParentNode): void;
+/** Apply a measured height to every embed iframe under `root`. */
+export declare function sizeTweetEmbeds(root: ParentNode, height: number): void;
+export interface TabGroupClassNames {
+    list?: string;
+    panels?: string;
+    button?: string;
+    panel?: string;
+    /** Added to the open button and its panel. */
+    active?: string;
+}
+/**
+ * Turn stored `[data-tabs]` markup into a working tab group.
+ *
+ * The editor stores tabs as nested `[data-tab-item]` divs, which is the right
+ * thing to persist — it survives a markdown twin, a plain-HTML render and a
+ * reader with JavaScript off, which all show every tab's content in order.
+ * Making one of them pressable is a reader-side job, and it belongs beside the
+ * other passes rather than inside a component: it is the same shape as the copy
+ * buttons, and the second wiki to render tabs would otherwise write it again.
+ *
+ * Idempotent via `data-tabs-init`, so a re-render does not rebuild the group and
+ * silently reset it to the first tab.
+ */
+export declare function activateTabGroups(root: ParentNode, classNames?: TabGroupClassNames): void;
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAgCxF;AAID;;;;GAIG;AACH,eAAO,MAAM,cAAc,iCAAiC,CAAC;AAE7D,mFAAmF;AACnF,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,GAAG,MAAM,KAAG,MACI,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAU1E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAazD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAItE;AAID,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,GAAE,kBAAuB,GAAG,IAAI,CAkD7F"}

package/dist/dom.js

@@ -0,0 +1,167 @@
+// dom.ts — the imperative passes a rendered article needs after it is in the DOM.
+//
+// Not in `react.tsx`, because none of this is React: it runs against an element
+// a `dangerouslySetInnerHTML` just filled, and both wikis call it from an effect
+// they already had. Keeping it out of the `'use client'` file also means a
+// consumer can call it from anywhere it has an element.
+//
+// Both routines were duplicated. `addCopyButton` was BYTE-IDENTICAL in the two
+// BlockRenderers, down to the SVG path data. The Twitter embed was worse: one
+// wiki had extracted it to a module, the other wrote the origin allow-list and
+// the embed URL out at three separate call sites — a duplicated origin check is
+// the kind that goes stale quietly.
+// ---- copy buttons -----------------------------------------------------------
+const COPY_SVG = '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
+const CHECK_SVG = '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>';
+/**
+ * Give every `<pre>` under `root` a copy button, once.
+ *
+ * Idempotent by inspection rather than by selector: both wikis called this
+ * through `pre:not(:has(.code-copy-btn))`, which puts the guard at the call
+ * site — where it can be, and was, retyped. Checking inside means a caller
+ * that passes a plain `pre` selector still cannot double up, and it drops the
+ * `:has()` dependency along the way.
+ *
+ * Returns the number of buttons added, so a caller can skip work when zero.
+ */
+export function addCopyButtons(root, options = {}) {
+    const { className = 'code-copy-btn', label = 'Copy code', revertAfter = 2000 } = options;
+    let added = 0;
+    for (const pre of Array.from(root.querySelectorAll('pre'))) {
+        if (pre.querySelector(`.${className}`))
+            continue;
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = className;
+        btn.setAttribute('aria-label', label);
+        btn.innerHTML = COPY_SVG;
+        btn.onclick = () => {
+            const code = pre.querySelector('code')?.textContent || pre.textContent || '';
+            // A rejected clipboard write (permissions, insecure origin) must not
+            // leave an unhandled rejection behind — the button simply does nothing.
+            navigator.clipboard.writeText(code).then(() => {
+                btn.innerHTML = CHECK_SVG;
+                setTimeout(() => {
+                    btn.innerHTML = COPY_SVG;
+                }, revertAfter);
+            }, () => { });
+        };
+        pre.style.position = 'relative';
+        pre.appendChild(btn);
+        added++;
+    }
+    return added;
+}
+// ---- twitter embeds ---------------------------------------------------------
+/**
+ * The one place this origin is written down. It is both the embed host and the
+ * allow-list the resize listener checks, and it was previously spelled out at
+ * four call sites across the two wikis.
+ */
+export const TWITTER_ORIGIN = 'https://platform.twitter.com';
+/** The embed iframe's src. `dnt=true` opts the embed out of Twitter's tracking. */
+export const tweetEmbedSrc = (tweetId) => `${TWITTER_ORIGIN}/embed/Tweet.html?id=${tweetId}&dnt=true`;
+/**
+ * Subscribe to the height the embed posts back once it has laid itself out.
+ *
+ * The iframe renders at an unknown height and there is no other way to learn
+ * it. The caller decides which iframes the height applies to; this only owns
+ * the origin check and the message shape. Returns a disposer.
+ */
+export function onTweetResize(resize) {
+    const handleMessage = (e) => {
+        if (e.origin !== TWITTER_ORIGIN)
+            return;
+        const data = e.data?.['twttr.embed'];
+        if (data?.method !== 'twttr.private.resize')
+            return;
+        const height = data.params?.[0]?.height;
+        if (height)
+            resize(height);
+    };
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+}
+/**
+ * Point every un-hydrated `[data-twitter-embed]` placeholder under `root` at
+ * the real embed URL.
+ *
+ * Stored article HTML carries the placeholder markup; the iframe only gets a
+ * live `src` once it is in the document. Marked with `data-init` so a re-render
+ * of the same content does not reload every embed on the page.
+ */
+export function hydrateTweetEmbeds(root) {
+    for (const container of Array.from(root.querySelectorAll('[data-twitter-embed]:not([data-init])'))) {
+        container.setAttribute('data-init', '');
+        const tweetId = container.getAttribute('data-tweet-id');
+        if (!tweetId)
+            continue;
+        const iframe = container.querySelector('iframe');
+        if (iframe) {
+            iframe.src = tweetEmbedSrc(tweetId);
+            iframe.setAttribute('scrolling', 'no');
+        }
+    }
+}
+/** Apply a measured height to every embed iframe under `root`. */
+export function sizeTweetEmbeds(root, height) {
+    for (const iframe of Array.from(root.querySelectorAll('[data-twitter-embed] iframe'))) {
+        iframe.style.height = `${height}px`;
+    }
+}
+/**
+ * Turn stored `[data-tabs]` markup into a working tab group.
+ *
+ * The editor stores tabs as nested `[data-tab-item]` divs, which is the right
+ * thing to persist — it survives a markdown twin, a plain-HTML render and a
+ * reader with JavaScript off, which all show every tab's content in order.
+ * Making one of them pressable is a reader-side job, and it belongs beside the
+ * other passes rather than inside a component: it is the same shape as the copy
+ * buttons, and the second wiki to render tabs would otherwise write it again.
+ *
+ * Idempotent via `data-tabs-init`, so a re-render does not rebuild the group and
+ * silently reset it to the first tab.
+ */
+export function activateTabGroups(root, classNames = {}) {
+    const { list = 'tabs-list', panels = 'tabs-panels', button = 'tab-button', panel = 'tab-panel', active = 'active', } = classNames;
+    for (const group of Array.from(root.querySelectorAll('[data-tabs]:not([data-tabs-init])'))) {
+        const items = group.querySelectorAll('[data-tab-item]');
+        if (!items.length)
+            continue;
+        group.setAttribute('data-tabs-init', '');
+        const tabList = document.createElement('div');
+        tabList.className = list;
+        tabList.setAttribute('role', 'tablist');
+        const tabPanels = document.createElement('div');
+        tabPanels.className = panels;
+        items.forEach((item, i) => {
+            const btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = i === 0 ? `${button} ${active}` : button;
+            btn.setAttribute('role', 'tab');
+            btn.setAttribute('aria-selected', String(i === 0));
+            btn.textContent = item.getAttribute('data-tab-title') || `Tab ${i + 1}`;
+            btn.onclick = () => {
+                for (const b of Array.from(tabList.children)) {
+                    b.classList.remove(active);
+                    b.setAttribute('aria-selected', 'false');
+                }
+                for (const p of Array.from(tabPanels.children))
+                    p.classList.remove(active);
+                btn.classList.add(active);
+                btn.setAttribute('aria-selected', 'true');
+                tabPanels.children[i]?.classList.add(active);
+            };
+            tabList.appendChild(btn);
+            const body = document.createElement('div');
+            body.className = i === 0 ? `${panel} ${active}` : panel;
+            body.setAttribute('role', 'tabpanel');
+            body.innerHTML = item.innerHTML;
+            tabPanels.appendChild(body);
+        });
+        group.innerHTML = '';
+        group.appendChild(tabList);
+        group.appendChild(tabPanels);
+    }
+}
+//# sourceMappingURL=dom.js.map

package/dist/dom.js.map

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

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export * from './blocks.js';
 export * from './text.js';
 export * from './maps.js';
 export * from './freshness.js';
+export * from './combobox.js';
+export * from './crawlers.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -18,4 +18,6 @@ export * from './blocks.js';
 export * from './text.js';
 export * from './maps.js';
 export * from './freshness.js';
+export * from './combobox.js';
+export * from './crawlers.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AAEnB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AAEnB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/pagination.d.ts

@@ -9,9 +9,18 @@ export interface PaginatedResponse<T> extends Pagination {
 }
 export declare const MAX_PAGE_SIZE = 100;
 export declare const DEFAULT_PAGE_SIZE = 20;
-/** `page` clamped to ≥1, `pageSize` clamped to 1–100. Never trust either. */
+/**
+ * `page` clamped to ≥1, `pageSize` clamped to 1–`max`. Never trust either.
+ *
+ * `max` defaults to 100 and exists because the cap is a per-route decision, not
+ * a package-wide one: a route whose rows are whole pages caps lower than one
+ * whose rows are titles. Without it the one consumer that caps at 50 could not
+ * express itself here, so it kept its own clamp — and then disagreed with
+ * itself, capping at 50 in the REST route and 100 in the MCP tool beside it.
+ */
 export declare function parsePagination(searchParams: URLSearchParams, defaults?: {
     pageSize?: number;
+    max?: number;
 }): Pagination;
 export declare function paginatedResponse<T>(items: T[], total: number, page: number, pageSize: number): PaginatedResponse<T>;
 /** The `skip`/`take` an ORM wants, from the same clamped pair. */

package/dist/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,UAAU;IACtD,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,6EAA6E;AAC7E,wBAAgB,eAAe,CAC7B,YAAY,EAAE,eAAe,EAC7B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,UAAU,CAYZ;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAAC,CAAC,CAAC,CAEtB;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEvF"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,UAAU;IACtD,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,eAAe,EAC7B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,UAAU,CASZ;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAAC,CAAC,CAAC,CAEtB;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEvF"}

package/dist/pagination.js

@@ -5,15 +5,23 @@
 // codes against, so reshaping it per repo is a breaking change nobody declared.
 export const MAX_PAGE_SIZE = 100;
 export const DEFAULT_PAGE_SIZE = 20;
-/** `page` clamped to ≥1, `pageSize` clamped to 1–100. Never trust either. */
+/**
+ * `page` clamped to ≥1, `pageSize` clamped to 1–`max`. Never trust either.
+ *
+ * `max` defaults to 100 and exists because the cap is a per-route decision, not
+ * a package-wide one: a route whose rows are whole pages caps lower than one
+ * whose rows are titles. Without it the one consumer that caps at 50 could not
+ * express itself here, so it kept its own clamp — and then disagreed with
+ * itself, capping at 50 in the REST route and 100 in the MCP tool beside it.
+ */
 export function parsePagination(searchParams, defaults) {
+    const max = defaults?.max ?? MAX_PAGE_SIZE;
+    const fallbackSize = Math.min(max, defaults?.pageSize ?? DEFAULT_PAGE_SIZE);
     const rawPage = parseInt(searchParams.get('page') || '1', 10);
-    const rawSize = parseInt(searchParams.get('pageSize') || String(defaults?.pageSize ?? DEFAULT_PAGE_SIZE), 10);
+    const rawSize = parseInt(searchParams.get('pageSize') || String(fallbackSize), 10);
     return {
         page: Number.isFinite(rawPage) ? Math.max(1, rawPage) : 1,
-        pageSize: Number.isFinite(rawSize)
-            ? Math.min(MAX_PAGE_SIZE, Math.max(1, rawSize))
-            : (defaults?.pageSize ?? DEFAULT_PAGE_SIZE),
+        pageSize: Number.isFinite(rawSize) ? Math.min(max, Math.max(1, rawSize)) : fallbackSize,
     };
 }
 export function paginatedResponse(items, total, page, pageSize) {

package/dist/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAahF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAC7B,YAA6B,EAC7B,QAAgC;IAEhC,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,QAAQ,CACtB,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ,IAAI,iBAAiB,CAAC,EAC/E,EAAE,CACH,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;YAChC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,IAAI,iBAAiB,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAU,EACV,KAAa,EACb,IAAY,EACZ,QAAgB;IAEhB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAc;IACrD,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAahF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,YAA6B,EAC7B,QAA8C;IAE9C,MAAM,GAAG,GAAG,QAAQ,EAAE,GAAG,IAAI,aAAa,CAAC;IAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,IAAI,iBAAiB,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;IACnF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY;KACxF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAU,EACV,KAAa,EACb,IAAY,EACZ,QAAgB;IAEhB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAc;IACrD,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,226 @@
+import { type ComboboxAria } from './combobox.js';
+import { type CSSProperties, type KeyboardEvent, type ReactNode } from 'react';
+export interface SidebarOptions {
+    /**
+     * Where the reader's choice is remembered, in `localStorage`. Give each wiki
+     * its own key; they are different sites and may deserve different answers.
+     */
+    storageKey?: string;
+    /** Below this width (px) the rail defaults to closed. */
+    breakpoint?: number;
+}
+export interface SidebarState {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    /** True below `breakpoint`. Drives "close the rail after following a link". */
+    isMobile: boolean;
+    /**
+     * False until the effect has read storage and matchMedia. Render the rail
+     * without its open/closed transition while this is false, so a remembered
+     * closed rail does not animate shut on every load.
+     */
+    ready: boolean;
+}
+/**
+ * Collapse state for a wiki rail: remembered across loads, defaulted from the
+ * viewport only when the reader has never chosen.
+ *
+ * The reader's choice outranks the breakpoint. Someone who collapses the rail
+ * on a laptop and then narrows the window has still collapsed the rail.
+ */
+export declare function useCollapsibleSidebar(options?: SidebarOptions): SidebarState;
+export interface SidebarProviderProps extends SidebarOptions {
+    children: ReactNode;
+}
+/** Wrap the layout that contains both the rail and its toggle. */
+export declare function SidebarProvider({ children, ...options }: SidebarProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SidebarState | null>>;
+/**
+ * The rail's collapse state. Throws outside a provider rather than silently
+ * handing back a second, unconnected copy — two sources of truth for one rail
+ * is the failure this context exists to prevent.
+ */
+export declare function useSidebar(): SidebarState;
+export interface TocHeading {
+    id: string;
+    text: string;
+    /** 1 for `<h1>`, 2 for `<h2>`, and so on. */
+    level: number;
+}
+export interface TocClassNames {
+    root?: string;
+    button?: string;
+    label?: string;
+    list?: string;
+    item?: string;
+    /** Applied alongside `item` on the section currently under the viewport top. */
+    itemActive?: string;
+}
+export interface TableOfContentsProps {
+    /**
+     * The element holding the article. A wiki whose content streams in as blocks
+     * has to read the DOM, which is why a selector is the default route — by the
+     * time the rail mounts, the article may not be there yet.
+     *
+     * Optional when `headings` is given: a wiki that renders its article on the
+     * server already knows them and should not pay for a MutationObserver to
+     * rediscover what it just wrote.
+     */
+    containerSelector?: string;
+    /**
+     * Headings known ahead of time. Supplying these skips the DOM scan entirely;
+     * scroll-spy still runs, since that needs the rendered elements either way.
+     */
+    headings?: TocHeading[];
+    /** Re-query and re-observe when this changes. Pass the pathname. */
+    resetKey?: string;
+    classNames?: TocClassNames;
+    /** Rendered before the label. Receives the current expanded state. */
+    icon?: (expanded: boolean) => ReactNode;
+    label?: string;
+    /**
+     * Mint an id for a heading that lacks one. Wikis that inject ids server-side
+     * (see `wiki-formant/headings`) should leave this off — an id is a URL, and
+     * one minted in the browser is not the one the server published.
+     */
+    slug?: (text: string) => string;
+    /**
+     * CSS custom property holding the sticky header's height, used to place the
+     * scroll-spy line. e.g. `'--header-height'`.
+     */
+    offsetVar?: string;
+    /** Fallback offset in px when `offsetVar` is unset or unparseable. */
+    offsetFallback?: number;
+    /** Indent per heading level, in rem. Set 0 for a flat list. */
+    indentRem?: number;
+    /** Rendered instead of nothing when the article has no headings. */
+    empty?: ReactNode;
+}
+/**
+ * An "on this page" rail with scroll-spy, read from the rendered article.
+ *
+ * Both wikis this came from had written the same thing: a debounced
+ * MutationObserver to survive content arriving late, an IntersectionObserver to
+ * track the section under the viewport top, and the same reference-stability
+ * trick so an unrelated DOM mutation (a price ticker, an RSS feed) does not tear
+ * the observer down.
+ */
+export declare function TableOfContents({ containerSelector, headings: providedHeadings, resetKey, classNames, icon, label, slug, offsetVar, offsetFallback, indentRem, empty, }: TableOfContentsProps): import("react").JSX.Element;
+/**
+ * Calls `onClose` on any mousedown outside the returned ref's element.
+ *
+ * The `offsetParent` check is the whole reason this is shared. All three wikis
+ * had written this hook; only one had that line, and without it a container
+ * that is `display: none` at the current breakpoint still claims outside-clicks
+ * — so a tap anywhere on a phone dismisses a popover the reader is looking at,
+ * because the hidden desktop copy of it answered first.
+ *
+ * `onClose` is an effect dependency: wrap it in `useCallback` or hoist it, or
+ * the listener is torn down and rebuilt on every render.
+ */
+export declare function useClickOutside<T extends HTMLElement>(onClose: () => void): import("react").RefObject<T | null>;
+export interface TypeaheadOptions<T> {
+    /**
+     * Runs the search. MUST be referentially stable — a module function, a server
+     * action, or something wrapped in `useCallback` — because it is an effect
+     * dependency and an inline arrow re-runs the search on every render.
+     *
+     * The `signal` is optional to implement: a REST fetcher should forward it, a
+     * server action simply declares one parameter and ignores it.
+     */
+    fetch: (query: string, signal: AbortSignal) => Promise<T[]>;
+    onPick: (item: T) => void;
+    /** Runs after Escape has cleared the list, for surface-level dismissal. */
+    onEscape?: () => void;
+    /** Debounce, in ms. */
+    delay?: number;
+    /** Queries shorter than this never reach `fetch`. */
+    minLength?: number;
+    /** Remember results per query for this mount. */
+    cache?: boolean;
+}
+export interface TypeaheadState<T> {
+    query: string;
+    setQuery: (query: string) => void;
+    debouncedQuery: string;
+    items: T[];
+    highlight: number;
+    setHighlight: (index: number) => void;
+    isSearching: boolean;
+    onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
+    /** Drop the results, keep the query. For an outside click. */
+    clearItems: () => void;
+    /** Drop everything. For a pick, or a closing popover. */
+    reset: () => void;
+    /**
+     * The listbox contract, ready to spread: `inputProps` on the field,
+     * `listProps` on the results container, `optionProps(i)` on each row.
+     *
+     * Pass a `listKey` when one hook feeds more than one rendered list — a header
+     * with a desktop and a mobile field renders both into the same document, and
+     * one id set across the two duplicates every option id.
+     */
+    combobox: (listKey?: string) => ComboboxAria;
+}
+/**
+ * The debounced-search state machine behind every typeahead on these sites.
+ *
+ * Five surfaces across the three wikis had three implementations, and no two
+ * agreed on what a search field does. This is their union, because each had a
+ * piece the others were missing:
+ *
+ *   - a **request-id guard**, so a slow response cannot paint over a newer one.
+ *     Two of the five surfaces had no guard at all: type fast enough and the
+ *     results you are reading are for a query you have already replaced.
+ *   - **keyboard navigation**. Two surfaces had none — the header dropdown of a
+ *     wiki whose search is its primary navigation was mouse-only.
+ *   - **abort and a per-query cache**, which only the third had. The cache is
+ *     per mount, not module-level, so a stale result cannot outlive the page.
+ *
+ * The debounce is inlined rather than pulled from a package: this one is nine
+ * lines, and the point of the package is to have no runtime dependencies.
+ */
+export declare function useTypeahead<T>({ fetch, onPick, onEscape, delay, minLength, cache, }: TypeaheadOptions<T>): TypeaheadState<T>;
+export interface LinkPreviewOptions<T> {
+    /**
+     * Which anchors get a card. Both wikis scope this to the article container
+     * (`a.closest('.prose-content')`) as well as testing the href, and the scope
+     * is exactly the part that differs — so the whole predicate is yours.
+     */
+    eligible: (anchor: HTMLAnchorElement) => boolean;
+    /** Resolve a preview for a href, or null for "no card". REST or server action. */
+    fetch: (href: string) => Promise<T | null>;
+    /** Must match the class on the element you spread `cardProps` onto. */
+    cardClassName?: string;
+    cardWidth?: number;
+    /** Used to decide whether the card flips above the link. */
+    cardHeight?: number;
+    /** Hover this long before fetching, in ms. */
+    showDelay?: number;
+    /** Grace period for the cursor to travel from link to card, in ms. */
+    hideDelay?: number;
+    /** Minimum gap from the viewport edge, in px. */
+    margin?: number;
+}
+export interface LinkPreviewState<T> {
+    /** The resolved preview, or null when no card should render. */
+    preview: T | null;
+    /** Spread onto your card element: position, and the keep-open handlers. */
+    cardProps: {
+        style: CSSProperties;
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+}
+/**
+ * Wikipedia-style hover cards over a rendered article.
+ *
+ * One delegated listener on `document` rather than a component per link, which
+ * is what makes this viable over an article holding hundreds of anchors. Two
+ * wikis had written the same ~90 lines: the same 350ms intent delay, the same
+ * 200ms grace so the cursor can cross the gap into the card, the same
+ * viewport-clamp arithmetic, the same per-href cache. They differed in exactly
+ * three things, and those three are the options above.
+ */
+export declare function useLinkPreview<T>({ eligible, fetch, cardClassName, cardWidth, cardHeight, showDelay, hideDelay, margin, }: LinkPreviewOptions<T>): LinkPreviewState<T>;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

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