@takazudo/zudo-doc 5.28.2 → 6.0.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [6.0.0] - 2026-10-11
+
+### Breaking Changes
+
+- Moves the framework to the zfb 4 engine family. `@takazudo/zfb`, `@takazudo/zfb-runtime` and `@takazudo/zfb-md-wasm` are now required at `^4.3.1`. Follow the [migration guide](https://zudo-doc.takazudomodular.com/docs/guides/migrating-to-zudo-doc-6/) to upgrade a 5.x project. (b9dd43b0d)
+- Rendering uses zfb's owned zudo-react runtime instead of Preact, so Preact is no longer a peer of the core package. Extend `@takazudo/zudo-doc/tsconfig.base.json`, remove React→Preact compatibility paths, and port host or ejected components to zudo-react signals and `on:*` events. (b9dd43b0d)
+- Styling uses the zudo-wind utility compiler instead of Tailwind. Remove Tailwind directives from your CSS entry and declare tokens as plain `:root` variables. The `./safelist.css` and `./theme-no-reset.css` exports are removed, and `./wind.json` is added and registered automatically by `zudoDoc()`. (b9dd43b0d)
+- Public types move to zudo-react. Element descriptions use `Description`/`Child` and component callbacks use `Component`. Intrinsic-compatible components take `class` instead of `className`. `useModalDialog(...)` becomes `modalDialog(scope, options)`, and `ThemePackDialogProps.open` is a `ReadonlySignal<boolean>`. (b9dd43b0d)
+- `DocHistory` and `DesignTokenPanelBootstrap` chrome-binding overrides are now server boundaries that own their Island mount. Use the exported `DocHistoryBoundary` for standard history. (84333fa7e)
+- The optional `@takazudo/zudo-doc-history-server` peer now requires `^6.0.0`.
+
+### Features
+
+- Adds an opt-in agent-readable documentation export (`agentExport`) and a read-only MCP server (`mcp`) with full-text search and fetch tools, plus agent discovery links. Both default to `false`. (4591145b0, 860eda41e, 578abf4ec)
+- Adds Broader Tree sidebar controls: broaden the tree to its editorial parent, show only one branch, and restore the current page's local tree. Object-form sidebar configs with `items` and `initialPath` supply editorial parents outside a local view. (9c9826dcc)
+
+### Bug Fixes
+
+- Heading references and code-fence anchors now match zfb's native heading IDs. (3f35bff85)
+- The agent export honors `copyPublicWithBase: false` when it places `agent/v1`. (db8e8495d)
+- The search shortcut placeholder survives reconnects. (05c35801e, dab099db9)
+
 ## [5.28.2] - 2026-09-28
 
 ### Bug Fixes

package/README.md

@@ -9,14 +9,14 @@ instead of editing the generated markdown directly.
 This package provides the missing-by-design framework concerns:
 
 - **Sidebar tree builder** (`./sidebar-tree`) — turns collection entries + `_category_.json` into breadcrumb/navigation nodes.
-- **Theme controls** (`./theme`) — color scheme provider + design-token tweak panel (Preact island that wraps an iframe).
+- **Theme controls** (`./theme`) — color scheme provider + design-token panel bootstrap (the optional zdtp package owns its opaque Preact UI).
 - **Theme toggle (bare)** (`./theme-toggle`) — the un-wrapped ThemeToggle component for call sites that compose their own `<Island>` (the `./theme` barrel exports an Island-wrapped variant of the same component).
-- **TOC** (`./toc`) — desktop and mobile TOC Preact islands fed by MDX `headings` export.
+- **TOC** (`./toc`) — desktop and mobile TOC zudo-react islands fed by MDX `headings` export.
 - **Breadcrumb** (`./breadcrumb`) — JSX breadcrumb fed by the sidebar tree.
 - **DocLayout** (`./doclayout`) — composable layout shell with explicit `<Header>`, `<Sidebar>`, `<Main>`, `<Toc>`, `<Footer>` props; ships a `<DocLayoutWithDefaults>` wrapper that holds the 16 `create-zudo-doc` injection anchors.
 - **View Transitions** (`./transitions`) — native View Transitions API shim (Chrome/Edge/Safari 18+); persistent regions via `view-transition-name`. No-op fallback in Firefox.
 - **Head injection** (`./head`) — canonical, og:\*, twitter:\*, robots, preload hints, RSS link, sitemap link, and theme-color output.
-- **SSR-skip wrappers** (`./ssr-skip`) — `<AiChatModalIsland>`, `<ImageEnlargeIsland>`, `<DesignTokenTweakPanelIsland>`, `<MockInitIsland>` — wrap zfb's `<Island ssrFallback>` with the right fallback markup so doc pages don't have to re-implement the SSR-skip pattern.
+- **SSR fallbacks** — fixed-target Island boundaries keep server fallback markup outside serialized client props; the image/mermaid fallback components remain public.
 - **Site schema** (`./site-schema`) — browser-safe nav tree / breadcrumb / pager domain, with zero zfb engine or filesystem coupling. See below.
 
 ## `./site-schema` — the browser-safe site-shape domain
@@ -105,25 +105,58 @@ If your project renders **semi-trusted or user-submitted** HTML in a preview, ov
 
 **Caveat:** removing `allow-same-origin` gives the iframe an opaque origin, which blocks the parent from reading `iframe.contentDocument`. That **disables auto-height** — always pair a stricter `sandbox` with a fixed `height`. Passing the empty string `""` is honored verbatim (only omitting the prop falls back to the computed default).
 
-## Styling — Tailwind setup for consumers
-
-This package ships **no precompiled CSS** — the component utility classes are inlined in the `dist/` JavaScript, and Tailwind v4 does not scan `node_modules`. Without help, those utilities never make it into your build, so the components render unstyled.
-
-The fix is to import the package's build-generated safelist into your Tailwind CSS entry, right next to your `@import "tailwindcss";`:
+## 6.0 migration and peers
+
+**6.0.0** is the coordinated major release of `@takazudo/zudo-doc`,
+`@takazudo/zudo-doc-history-server` and `create-zudo-doc`. It targets the
+published **zfb 4.3.1** family (peer floor **^4.3.1**).
+[Upstream #4097](https://github.com/Takazudo/zudo-front-builder/issues/4097) is
+resolved; its strict published 4.3.1 consumer control passed 3/3 with no skips or
+retries in the [source-bound verification](../../docs/findings/zfb-4.3.1/verification.md).
+That is Linux Chromium evidence; native macOS WebKit and the human/platform
+limits retain their [recorded disposition](../../docs/findings/4430-zfb3-migration/2026-10-11-post-merge-status.md). See the
+[5.x → 6.0 migration guide](../../src/content/docs/guides/migrating-to-zudo-doc-6.mdx)
+for the full public API and host-boundary census.
+
+Core rendering uses `@takazudo/zfb/zudo-react`, not Preact. Extend
+`@takazudo/zudo-doc/tsconfig.base.json`, remove React→Preact compatibility paths,
+and port host/ejected components to owned JSX/signals. zod remains required;
+`katex`, `diff`, `@takazudo/zfb-md-wasm`, history-server, zdtp and MCP SDK peers
+are feature-dependent. Package defaults for `agentExport`, `mcp`, and `llmsTxt`
+are all `false`. The create-zudo-doc initializer enables `llmsTxt` by default;
+agent export and MCP remain opt-in.
+
+For the panel, the installed **zdtp 0.8.6** manifest carries **Preact ^10.29.1** as
+its own dependency (it was a peer through 0.8.5) and exports `./styles.css` (also `./styles`) to `dist/zdtp.css`. Its internal
+Tailwind browser dependency and Preact subtree are isolated from host JSX.
+Install `@takazudo/zdtp` and import `@takazudo/zdtp/styles.css` when enabling it.
+
+## Styling — Wind and public CSS
+
+`zudoDoc()` registers the public `@takazudo/zudo-doc/wind.json` manifest and
+var-backed Wind defaults automatically. No package-dist scanning or consumer
+manifest import is needed. Remove the retired `safelist.css` and
+`theme-no-reset.css` imports, Tailwind imports/directives and palette reset.
 
 ```css
-@import "tailwindcss";
-@import "@takazudo/zudo-doc/safelist.css";
-```
+@layer zw-reset, zd-flow;
+@import "@takazudo/zudo-doc/theme.css";
+@import "@takazudo/zudo-doc/content.css";
+@import "@takazudo/zudo-doc/page-loading.css";
+@import "@takazudo/zudo-doc/features.css";
 
-`dist/safelist.css` is generated at package build time and contains an `@source inline()` set covering every utility the components use (including arbitrary-value classes like `w-[var(--zd-sidebar-w)]`). It auto-syncs whenever you upgrade the package — no drift, no manual maintenance. Available in `@takazudo/zudo-doc` **>= 0.2.0**.
-
-> **Don't `@source` into `node_modules`.** A glob like `@source "../node_modules/@takazudo/zudo-doc/dist/**"` looks plausible but is unreliable: pnpm surfaces packages via symlinks and Tailwind v4's file scanner does not reliably traverse them, so utilities get intermittently dropped across rebuilds (see zudolab/zudo-doc#1989). Import the package safelist instead.
+:root { --spacing-hsp-md: 1rem; }
+```
 
-**Migrating from a pre-0.2.0 workaround?** If you vendored or copied the package `dist/` to get its styles, delete that workaround and replace it with the single `@import "@takazudo/zudo-doc/safelist.css";` line above.
+Override CSS variable values in `:root` after package imports, or utility token
+mappings with `zudoDoc({ wind: { tokens: { colors: { accent: "var(--brand-accent)" } } } })`.
+The top-level `wind` override deep-merges over package defaults; reset is
+selected with `wind.reset` (default `"owned-v1"`), and `wind: false` disables it.
+Public `compiled.css` remains the browser-ready embedding option when not using
+zfb CSS generation. Do not use physical package `dist/*.css` import paths.
 
 ## Dev workflow (in this repo)
 
 This package is published to npm as `@takazudo/zudo-doc` (since `0.2.0`, `latest` tracks the current line). Inside this repo the host site consumes it as a workspace package through its compiled `dist/` — `pnpm dev` at the repo root runs two watchers in parallel, `tsup --watch` for the JS and `tsc -p tsconfig.build.json --watch` for the `.d.ts`, so edits under `src/` rebuild both halves automatically; for a one-off rebuild use `pnpm --filter @takazudo/zudo-doc build`.
 
-zfb itself comes from npm (versions pinned in the root `package.json`). To develop against a local zfb checkout, use the temporary `pnpm.overrides` link escape hatch documented in the root `CLAUDE.md` — do not commit the override.
+zfb itself comes from npm (versions pinned in the root `package.json`). To develop against a local zfb checkout, use the temporary `pnpm.overrides` link escape hatch documented in root `CONTRIBUTING.md` — do not commit the override.

package/bin/gen-z-index.mjs

@@ -10,10 +10,10 @@
 //   - CSS:    src/styles/global.css (override with --css <path>)
 //
 // Usage (after pnpm install, via scripts in package.json):
-//   gen-z-index                               # rewrite the @theme block (conventional paths)
+//   gen-z-index                               # rewrite the :root block (conventional paths)
 //   gen-z-index --check                       # verify committed block is up to date (exit 1 on drift)
 //   gen-z-index --tokens <path> --css <path>  # use non-conventional source/destination paths
-//   gen-z-index --no-theme-wrapper            # emit bare --z-index-<name> declarations, no @theme wrapper
+//   gen-z-index --no-theme-wrapper            # emit bare --z-index-<name> declarations, no :root wrapper
 //   gen-z-index --md-table <path>             # also generate/verify a Z_INDEX_TABLE region in a
 //                                              # markdown/MDX file (opt-in, no conventional default path)
 //
@@ -27,11 +27,11 @@
 // this repo's own b4push or CI; that integration was retired in
 // zudolab/zudo-doc#2661.
 //
-// The block is a Tailwind v4 `@theme { --z-index-<name>: <value>; }` for every
-// tier, so Tailwind generates `z-<name>` utilities and raw CSS can reference
-// `z-index: var(--z-index-<name>)`. `--no-theme-wrapper` drops the `@theme`
+// The block is an authored `:root { --z-index-<name>: <value>; }` for every
+// tier. Matching wind tokens generate `z-<name>` utilities and raw CSS can reference
+// `z-index: var(--z-index-<name>)`. `--no-theme-wrapper` drops the `:root`
 // wrapper and emits bare `--z-index-<name>: <value>;` declarations instead,
-// for projects that want to compose the block into their own `@theme` block.
+// for projects that want to compose the block into their own `:root` block.
 //
 // `--md-table <path>` additionally generates/verifies a second, independent
 // `GENERATED:Z_INDEX_TABLE` region — a `| Token | Kind | Role |` table, one
@@ -660,7 +660,7 @@ function buildRerunCommand({ tokensPath, cssPath, themeWrapper, mdTablePath }) {
 
 /**
  * Build the full generated block (markers included). Two leading spaces of
- * indentation match the surrounding `@theme` style in global.css.
+ * indentation match the surrounding `:root` style in global.css.
  *
  * `options.tokensPath`/`options.cssPath` feed the "Source of truth:" and
  * rerun-guidance lines in the header comment — pass the SAME path strings
@@ -670,9 +670,9 @@ function buildRerunCommand({ tokensPath, cssPath, themeWrapper, mdTablePath }) {
  * its default, the header is byte-identical to the pre-flag generator.
  *
  * `options.themeWrapper` (default `true`) wraps the declarations in an
- * `@theme { ... }` block; `false` (the `--no-theme-wrapper` CLI flag) emits
+ * `:root { ... }` block; `false` (the `--no-theme-wrapper` CLI flag) emits
  * bare `--z-index-<name>: <value>;` declarations at 2-space indent instead,
- * for projects composing the block into their own `@theme` block.
+ * for projects composing the block into their own `:root` block.
  *
  * Deliberately does NOT accept `mdTablePath`: the CSS block's own content
  * must depend only on the CSS-region flags (--tokens/--css/--no-theme-
@@ -696,12 +696,12 @@ export function buildBlock(tiers, options = {}) {
   lines.push(
     `   * GENERATED:Z_INDEX — do not hand-edit; run ${buildRerunCommand({ tokensPath, cssPath, themeWrapper })}.`,
   );
-  lines.push(`   * Source of truth: ${tokensPath}. Tailwind v4 reads the`);
+  lines.push(`   * Source of truth: ${tokensPath}. zudo-wind reads the`);
   lines.push(
-    `   * --z-index-<name> theme key and generates a z-<name> utility. */`,
+    `   * --z-index-<name> custom property and generates a z-<name> utility. */`,
   );
   if (themeWrapper) {
-    lines.push(`  @theme {`);
+    lines.push(`  :root {`);
     for (const tier of tiers) {
       lines.push(`    --z-index-${tier.name}: ${tier.value};`);
     }
@@ -867,7 +867,7 @@ export function scanMarkerLines(source, marker, options = {}) {
  * error for each failure mode: missing (the block must be seeded once by
  * hand), duplicated, or inverted markers.
  *
- * `beginMarker`/`endMarker` default to the CSS `@theme` block's markers so
+ * `beginMarker`/`endMarker` default to the CSS `:root` block's markers so
  * existing call sites (the CSS region) are unaffected; the `--md-table`
  * region passes `MD_TABLE_BEGIN_MARKER`/`MD_TABLE_END_MARKER` instead — same
  * function, parameterized, mirroring how gen-component-tokens.mjs reuses one
@@ -1053,7 +1053,7 @@ function readNamedFile(absPath, asGivenPath, label) {
  * message and into the generated header — never the resolved absolute path —
  * so the committed CSS/md file never embeds a machine-specific path.
  *
- * The CSS `@theme` region is always generated/verified. The `--md-table`
+ * The CSS `:root` region is always generated/verified. The `--md-table`
  * region is entirely opt-in: when `--md-table <path>` isn't passed, no md
  * file is read, built, or written, and `--check` only covers the CSS region
  * (unchanged from pre-`--md-table` behavior). When it IS passed, `--check`
@@ -1114,19 +1114,19 @@ export function main(argv = process.argv.slice(2)) {
     }
     console.log(
       mdTablePath !== undefined
-        ? `OK — z-index @theme block and md table are up to date (${tiers.length} tiers).`
-        : `OK — z-index @theme block is up to date (${tiers.length} tiers).`,
+        ? `OK — z-index :root block and md table are up to date (${tiers.length} tiers).`
+        : `OK — z-index :root block is up to date (${tiers.length} tiers).`,
     );
     return 0;
   }
 
   if (nextCss === css) {
     console.log(
-      `z-index @theme block already up to date (${tiers.length} tiers); no change.`,
+      `z-index :root block already up to date (${tiers.length} tiers); no change.`,
     );
   } else {
     writeFileSync(cssAbsPath, nextCss);
-    console.log(`Wrote z-index @theme block to ${cssPath} (${tiers.length} tiers).`);
+    console.log(`Wrote z-index :root block to ${cssPath} (${tiers.length} tiers).`);
   }
 
   if (mdTablePath !== undefined) {

package/dist/agent-docs/identity.d.ts

@@ -0,0 +1,4 @@
+/** Stable filename-safe key for the actual locale and effective route slug. */
+export declare function agentPageKey(locale: string, effectiveRouteSlug: string): string;
+/** One-based part key. The exporter checks duplicate keys and validates part counts. */
+export declare function agentItemKey(pageId: string, oneBasedPart: number): string;

package/dist/agent-docs/identity.js

@@ -0,0 +1,24 @@
+const FNV_OFFSET = 14695981039346656037n;
+const FNV_PRIME = 1099511628211n;
+const FNV_MASK = (1n << 64n) - 1n;
+function agentPageKey(locale, effectiveRouteSlug) {
+  const bytes = new TextEncoder().encode(JSON.stringify([locale, effectiveRouteSlug]));
+  let hash = FNV_OFFSET;
+  for (const byte of bytes) {
+    hash = (hash ^ BigInt(byte)) * FNV_PRIME & FNV_MASK;
+  }
+  return `p-${hash.toString(16).padStart(16, "0")}`;
+}
+function agentItemKey(pageId, oneBasedPart) {
+  if (!/^p-[0-9a-f]{16}$/.test(pageId)) {
+    throw new Error("Invalid agent page ID.");
+  }
+  if (!Number.isSafeInteger(oneBasedPart) || oneBasedPart < 1 || oneBasedPart > 999999) {
+    throw new Error("Agent item part must be between 1 and 999999.");
+  }
+  return `${pageId}-${String(oneBasedPart).padStart(6, "0")}`;
+}
+export {
+  agentItemKey,
+  agentPageKey
+};

package/dist/agent-docs/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./limits.js";
+export * from "./identity.js";
+export * from "./tokenize.js";
+export * from "./search.js";

package/dist/agent-docs/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./limits.js";
+export * from "./identity.js";
+export * from "./tokenize.js";
+export * from "./search.js";

package/dist/agent-docs/limits.d.ts

@@ -0,0 +1,11 @@
+export declare const AGENT_SCHEMA_VERSION: 1;
+export declare const AGENT_MAX_ITEM_TEXT_UNITS = 8000;
+export declare const AGENT_MAX_TOOL_RESPONSE_BYTES = 131072;
+export declare const AGENT_MAX_SEARCH_RESULTS = 10;
+export declare const AGENT_MAX_QUERY_UNITS = 500;
+export declare const AGENT_MAX_POST_BYTES = 65536;
+export declare const AGENT_MAX_MANIFEST_BYTES: number;
+export declare const AGENT_MAX_SEARCH_INDEX_BYTES: number;
+export declare const AGENT_MAX_ITEMS = 10000;
+export declare const AGENT_RETAINED_MEMORY_TARGET_BYTES: number;
+export declare const AGENT_COLD_LOAD_TARGET_MS = 2000;

package/dist/agent-docs/limits.js

@@ -0,0 +1,24 @@
+const AGENT_SCHEMA_VERSION = 1;
+const AGENT_MAX_ITEM_TEXT_UNITS = 8e3;
+const AGENT_MAX_TOOL_RESPONSE_BYTES = 131072;
+const AGENT_MAX_SEARCH_RESULTS = 10;
+const AGENT_MAX_QUERY_UNITS = 500;
+const AGENT_MAX_POST_BYTES = 65536;
+const AGENT_MAX_MANIFEST_BYTES = 8 * 1024 * 1024;
+const AGENT_MAX_SEARCH_INDEX_BYTES = 16 * 1024 * 1024;
+const AGENT_MAX_ITEMS = 1e4;
+const AGENT_RETAINED_MEMORY_TARGET_BYTES = 64 * 1024 * 1024;
+const AGENT_COLD_LOAD_TARGET_MS = 2e3;
+export {
+  AGENT_COLD_LOAD_TARGET_MS,
+  AGENT_MAX_ITEMS,
+  AGENT_MAX_ITEM_TEXT_UNITS,
+  AGENT_MAX_MANIFEST_BYTES,
+  AGENT_MAX_POST_BYTES,
+  AGENT_MAX_QUERY_UNITS,
+  AGENT_MAX_SEARCH_INDEX_BYTES,
+  AGENT_MAX_SEARCH_RESULTS,
+  AGENT_MAX_TOOL_RESPONSE_BYTES,
+  AGENT_RETAINED_MEMORY_TARGET_BYTES,
+  AGENT_SCHEMA_VERSION
+};

package/dist/agent-docs/search.d.ts

@@ -0,0 +1,14 @@
+import type { AgentSearchIndex, AgentSearchResult, AgentItem } from "./types.js";
+interface Posting {
+    item: number;
+    weight: number;
+}
+export interface BuiltAgentSearchIndex {
+    readonly items: readonly AgentItem[];
+    readonly postings: ReadonlyMap<string, readonly Posting[]>;
+}
+/** Build postings from complete item text, including content after UI-search truncation. */
+export declare function buildAgentSearchIndex(source: AgentSearchIndex | readonly AgentItem[]): BuiltAgentSearchIndex;
+/** Returns a validation result for bad queries and [] for valid queries with no matches. */
+export declare function searchAgentIndex(index: BuiltAgentSearchIndex, query: string, topK?: number): AgentSearchResult;
+export {};

package/dist/agent-docs/search.js

@@ -0,0 +1,82 @@
+import { AGENT_MAX_ITEMS, AGENT_MAX_QUERY_UNITS, AGENT_MAX_SEARCH_RESULTS } from "./limits.js";
+import { tokenizeAgentText } from "./tokenize.js";
+const HEADING = /^#{1,6}\s+(.+)$/gm;
+function buildAgentSearchIndex(source) {
+  const artifact = Array.isArray(source) ? void 0 : source;
+  if (artifact && artifact.schemaVersion !== 1) {
+    throw new Error("Unsupported agent search index schema version.");
+  }
+  const items = artifact ? artifact.items : source;
+  if (items.length > AGENT_MAX_ITEMS) throw new Error(`Agent search index exceeds ${AGENT_MAX_ITEMS} items.`);
+  const postings = /* @__PURE__ */ new Map();
+  items.forEach((item, itemIndex) => {
+    const weights = /* @__PURE__ */ new Map();
+    const add = (text, weight) => {
+      for (const token of tokenizeAgentText(text)) {
+        weights.set(token, (weights.get(token) ?? 0) + weight);
+      }
+    };
+    add(item.text, 1);
+    add(item.title, 12);
+    if (item.metadata.description) add(item.metadata.description, 5);
+    if (item.metadata.section) add(item.metadata.section, 7);
+    for (const match of item.text.matchAll(HEADING)) add(match[1], 6);
+    for (const [token, weight] of weights) {
+      const list = postings.get(token);
+      if (list) list.push({ item: itemIndex, weight });
+      else postings.set(token, [{ item: itemIndex, weight }]);
+    }
+  });
+  return { items, postings };
+}
+function displayTitle(item, duplicateTitle, duplicateQualifier) {
+  const { locale, section, part, partCount } = item.metadata;
+  const qualifiers = [locale];
+  if (section && section !== item.title) qualifiers.push(section);
+  if (partCount > 1) qualifiers.push(`part ${part}/${partCount}`);
+  if (duplicateQualifier) qualifiers.push(item.id);
+  return duplicateTitle || qualifiers.length > 1 ? `${item.title} (${qualifiers.join(" \xB7 ")})` : item.title;
+}
+function searchAgentIndex(index, query, topK = AGENT_MAX_SEARCH_RESULTS) {
+  if (query.length > AGENT_MAX_QUERY_UNITS) {
+    return { ok: false, error: `Query exceeds ${AGENT_MAX_QUERY_UNITS} UTF-16 code units.` };
+  }
+  if (!query.trim()) return { ok: false, error: "Query must not be empty." };
+  const tokens = tokenizeAgentText(query);
+  if (tokens.length === 0) return { ok: false, error: "Query has no searchable terms." };
+  const scores = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    const list = index.postings.get(token);
+    if (!list) continue;
+    const idf = 1 + Math.log((index.items.length + 1) / (list.length + 1));
+    const specificity = Array.from(token).length === 1 ? 0.25 : 1;
+    for (const { item, weight } of list) {
+      scores.set(item, (scores.get(item) ?? 0) + weight * idf * specificity);
+    }
+  }
+  const boundedK = Number.isFinite(topK) ? Math.max(0, Math.min(AGENT_MAX_SEARCH_RESULTS, Math.floor(topK))) : AGENT_MAX_SEARCH_RESULTS;
+  const ranked = [...scores.keys()].sort((a, b) => {
+    const difference = scores.get(b) - scores.get(a);
+    if (difference) return difference;
+    const first = index.items[a].id;
+    const second = index.items[b].id;
+    return first < second ? -1 : first > second ? 1 : 0;
+  }).slice(0, boundedK);
+  const titleCounts = /* @__PURE__ */ new Map();
+  for (const item of index.items) titleCounts.set(item.title, (titleCounts.get(item.title) ?? 0) + 1);
+  const qualifiedCounts = /* @__PURE__ */ new Map();
+  for (const item of index.items) {
+    const title = displayTitle(item, (titleCounts.get(item.title) ?? 0) > 1, false);
+    qualifiedCounts.set(title, (qualifiedCounts.get(title) ?? 0) + 1);
+  }
+  const results = ranked.map((i) => {
+    const item = index.items[i];
+    const title = displayTitle(item, (titleCounts.get(item.title) ?? 0) > 1, false);
+    return { id: item.id, title: displayTitle(item, (titleCounts.get(item.title) ?? 0) > 1, (qualifiedCounts.get(title) ?? 0) > 1), url: item.url };
+  });
+  return { ok: true, results };
+}
+export {
+  buildAgentSearchIndex,
+  searchAgentIndex
+};

package/dist/agent-docs/tokenize.d.ts

@@ -0,0 +1,2 @@
+/** Pure tokenizer shared by Node export code and workerd retrieval. */
+export declare function tokenizeAgentText(input: string): string[];

package/dist/agent-docs/tokenize.js

@@ -0,0 +1,22 @@
+const TOKEN_RUN = /[a-z0-9_]+|[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}ー]+/gu;
+const IDENTIFIER = /^[a-z0-9_]+$/;
+function tokenizeAgentText(input) {
+  const normalized = input.normalize("NFKC").toLowerCase();
+  const tokens = /* @__PURE__ */ new Set();
+  for (const match of normalized.matchAll(TOKEN_RUN)) {
+    const run = match[0];
+    if (IDENTIFIER.test(run)) {
+      tokens.add(run);
+      continue;
+    }
+    const points = Array.from(run);
+    for (let i = 0; i < points.length; i += 1) {
+      tokens.add(points[i]);
+      if (i + 1 < points.length) tokens.add(points[i] + points[i + 1]);
+    }
+  }
+  return [...tokens].sort();
+}
+export {
+  tokenizeAgentText
+};

package/dist/agent-docs/types.d.ts

@@ -0,0 +1,68 @@
+/** Version 1 of the published, read-only agent corpus. */
+export interface AgentItem {
+    id: string;
+    title: string;
+    text: string;
+    url: string;
+    metadata: {
+        locale: string;
+        pageId: string;
+        fingerprint: string;
+        part: number;
+        partCount: number;
+        description?: string;
+        section?: string;
+        unsupportedDynamicContent?: boolean;
+    };
+}
+export interface AgentManifest {
+    schemaVersion: 1;
+    fingerprint: string;
+    site: {
+        name: string;
+        url: string;
+        base: string;
+    };
+    defaultLocale: string;
+    locales: string[];
+    searchIndex: {
+        url: string;
+        sha256: string;
+    };
+    documents: Array<{
+        id: string;
+        key: string;
+        locale: string;
+        title: string;
+        url: string;
+        markdownUrl: string;
+        itemIds: string[];
+    }>;
+    items: Array<{
+        id: string;
+        key: string;
+        pageId: string;
+        url: string;
+        artifactUrl: string;
+        sha256: string;
+        part: number;
+        partCount: number;
+    }>;
+}
+export interface AgentSearchIndex {
+    schemaVersion: 1;
+    fingerprint: string;
+    items: AgentItem[];
+}
+export interface AgentSearchResultItem {
+    id: string;
+    title: string;
+    url: string;
+}
+export type AgentSearchResult = {
+    ok: true;
+    results: AgentSearchResultItem[];
+} | {
+    ok: false;
+    error: string;
+};

package/dist/ai-chat-modal/index.d.ts

@@ -1,8 +1,5 @@
 interface AiChatModalProps {
     basePath: string;
 }
-export declare function AiChatModal({ basePath }: AiChatModalProps): import("preact").JSX.Element;
-export declare namespace AiChatModal {
-    var displayName: string;
-}
+export declare function AiChatModal({ basePath }: AiChatModalProps): import("@takazudo/zfb").Description;
 export {};