@takazudo/zudo-doc 5.28.2 → 6.0.0

package/dist/mcp/loader.js

@@ -0,0 +1,202 @@
+import { AGENT_MAX_ITEMS, AGENT_MAX_MANIFEST_BYTES, AGENT_MAX_SEARCH_INDEX_BYTES } from "../agent-docs/limits.js";
+import { buildAgentSearchIndex } from "../agent-docs/search.js";
+import { z } from "zod";
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const pageId = z.string().regex(/^p-[a-f0-9]{16}$/);
+const itemId = z.string().regex(/^p-[a-f0-9]{16}-[0-9]{6}$/);
+const part = z.number().int().positive();
+const itemSchema = z.object({
+  id: itemId,
+  title: z.string(),
+  text: z.string(),
+  url: z.string(),
+  metadata: z.object({
+    locale: z.string(),
+    pageId,
+    fingerprint: digest,
+    part,
+    partCount: part,
+    description: z.string().optional(),
+    section: z.string().optional(),
+    unsupportedDynamicContent: z.boolean().optional()
+  })
+});
+const manifestSchema = z.object({
+  schemaVersion: z.literal(1),
+  fingerprint: digest,
+  site: z.object({ name: z.string(), url: z.string(), base: z.string() }),
+  defaultLocale: z.string(),
+  locales: z.array(z.string()),
+  searchIndex: z.object({ url: z.string(), sha256: digest }),
+  documents: z.array(z.object({
+    id: pageId,
+    key: pageId,
+    locale: z.string(),
+    title: z.string(),
+    url: z.string(),
+    markdownUrl: z.string(),
+    itemIds: z.array(itemId)
+  })),
+  items: z.array(z.object({
+    id: itemId,
+    key: itemId,
+    pageId,
+    url: z.string(),
+    artifactUrl: z.string(),
+    sha256: digest,
+    part,
+    partCount: part
+  })).max(AGENT_MAX_ITEMS)
+});
+const indexSchema = z.object({
+  schemaVersion: z.literal(1),
+  fingerprint: digest,
+  items: z.array(itemSchema).max(AGENT_MAX_ITEMS)
+});
+class CorpusUnavailable extends Error {
+}
+const encoder = new TextEncoder();
+async function sha256(text) {
+  const bytes = await crypto.subtle.digest("SHA-256", encoder.encode(text));
+  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function basePath(base) {
+  return `/${base.split("/").filter(Boolean).join("/")}/agent/v1/`.replace(/^\/\//, "/");
+}
+function safePath(url, root, siteUrl) {
+  let path = url;
+  if (/^https?:\/\//.test(url)) {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new CorpusUnavailable("Invalid agent corpus artifact URL.");
+    }
+    if (!siteUrl || parsed.origin !== new URL(siteUrl).origin || parsed.search || parsed.hash) throw new CorpusUnavailable("Invalid agent corpus artifact origin.");
+    path = parsed.pathname;
+  }
+  if (!path.startsWith(root) || path.includes("?") || path.includes("#") || path.includes("..") || path.includes("%")) {
+    throw new CorpusUnavailable("Invalid agent corpus artifact path.");
+  }
+  return path;
+}
+async function readText(read, path, max) {
+  let response;
+  try {
+    response = await read(path);
+  } catch {
+    throw new CorpusUnavailable(`Cannot read agent corpus artifact: ${path}`);
+  }
+  if (!response.ok || !response.body) throw new CorpusUnavailable(`Missing agent corpus artifact: ${path}`);
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > max) {
+        await reader.cancel();
+        throw new CorpusUnavailable(`Agent corpus artifact exceeds ${max} bytes.`);
+      }
+      chunks.push(value);
+    }
+  } catch (error) {
+    if (error instanceof CorpusUnavailable) throw error;
+    throw new CorpusUnavailable(`Cannot read agent corpus artifact: ${path}`);
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new CorpusUnavailable(`Invalid UTF-8 in agent corpus artifact: ${path}`);
+  }
+}
+function parse(text, label, schema) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new CorpusUnavailable(`Invalid agent ${label} JSON.`);
+  }
+  const result = schema.safeParse(value);
+  if (!result.success) throw new CorpusUnavailable(`Incompatible agent ${label}.`);
+  return result.data;
+}
+class AgentCorpusLoader {
+  constructor(read, base) {
+    this.read = read;
+    this.base = base;
+  }
+  read;
+  base;
+  current;
+  loading;
+  async load(manifest) {
+    const root = basePath(this.base);
+    const indexPath = safePath(manifest.searchIndex.url, root, manifest.site.url);
+    if (indexPath !== `${root}search-index.json`) throw new CorpusUnavailable("Invalid agent search index path.");
+    const raw = await readText(this.read, indexPath, AGENT_MAX_SEARCH_INDEX_BYTES);
+    if (await sha256(raw) !== manifest.searchIndex.sha256) throw new CorpusUnavailable("Agent search index digest mismatch.");
+    const data = parse(raw, "search index", indexSchema);
+    if (data.schemaVersion !== 1 || data.fingerprint !== manifest.fingerprint || !Array.isArray(data.items) || data.items.length > AGENT_MAX_ITEMS) {
+      throw new CorpusUnavailable("Incompatible agent search index.");
+    }
+    const byId = new Map(manifest.items.map((item) => [item.id, item]));
+    if (byId.size !== manifest.items.length || byId.size !== data.items.length || new Set(data.items.map((item) => item.id)).size !== data.items.length || data.items.some((item) => !byId.has(item.id) || item.metadata?.fingerprint !== manifest.fingerprint)) {
+      throw new CorpusUnavailable("Agent search index does not match manifest.");
+    }
+    const loaded = { fingerprint: manifest.fingerprint, manifest, index: buildAgentSearchIndex(data) };
+    this.current = loaded;
+    return loaded;
+  }
+  async corpus() {
+    const root = basePath(this.base);
+    const raw = await readText(this.read, `${root}manifest.json`, AGENT_MAX_MANIFEST_BYTES);
+    const manifest = parse(raw, "manifest", manifestSchema);
+    if (manifest.schemaVersion !== 1 || !/^[a-f0-9]{64}$/.test(manifest.fingerprint) || !Array.isArray(manifest.items) || manifest.items.length > AGENT_MAX_ITEMS || !manifest.searchIndex?.sha256) {
+      throw new CorpusUnavailable("Incompatible agent manifest.");
+    }
+    if (this.current?.fingerprint === manifest.fingerprint && this.current.manifest.searchIndex.sha256 === manifest.searchIndex.sha256) {
+      this.current = { ...this.current, manifest };
+      return this.current;
+    }
+    this.current = void 0;
+    if (this.loading) {
+      try {
+        const loaded = await this.loading;
+        if (loaded.fingerprint === manifest.fingerprint && loaded.manifest.searchIndex.sha256 === manifest.searchIndex.sha256) return { ...loaded, manifest };
+      } catch {
+      }
+    }
+    this.loading = this.load(manifest).finally(() => {
+      this.loading = void 0;
+    });
+    return this.loading;
+  }
+  async item(id) {
+    const { manifest } = await this.corpus();
+    const entry = manifest.items.find((item2) => item2.id === id);
+    if (!entry) return void 0;
+    const root = basePath(this.base);
+    const path = safePath(entry.artifactUrl, `${root}items/`, manifest.site.url);
+    if (path !== `${root}items/${entry.key}.json` || !/^p-[a-f0-9]{16}-[0-9]{6}$/.test(entry.key)) throw new CorpusUnavailable("Invalid agent item path.");
+    const raw = await readText(this.read, path, 256 * 1024);
+    if (await sha256(raw) !== entry.sha256) throw new CorpusUnavailable("Agent item digest mismatch.");
+    const item = parse(raw, "item", itemSchema);
+    if (item.id !== id || item.metadata?.fingerprint !== manifest.fingerprint || item.metadata.pageId !== entry.pageId) throw new CorpusUnavailable("Agent item does not match manifest.");
+    return item;
+  }
+}
+export {
+  AgentCorpusLoader,
+  CorpusUnavailable
+};

package/dist/mdx-components/index.js

@@ -1,4 +1,4 @@
-import { toChildArray } from "preact";
+import { h, flattenChildren } from "@takazudo/zfb/zudo-react";
 import { defaultComponents } from "../content/index.js";
 import { createContentLink } from "../content/content-link.js";
 import { decodeAuthoredHref, assetViewerHref } from "../asset-path/index.js";
@@ -18,58 +18,25 @@ function makeContentImg(base) {
     if (finalTitle !== void 0) {
       mergedProps.title = finalTitle;
     }
-    return { type: "img", props: mergedProps, key: null, constructor: void 0 };
+    return h("img", mergedProps);
   };
 }
-const ENLARGE_SVG = {
-  type: "svg",
-  props: {
+const ENLARGE_SVG = h(
+  "svg",
+  {
     viewBox: "0 0 38.99 38.99",
     fill: "currentColor",
-    focusable: "false",
-    "aria-hidden": "true",
-    children: [
-      {
-        type: "polygon",
-        props: {
-          points: "16.2 13.74 5.92 3.47 11.2 3.47 11.2 0 3.47 0 0 0 0 3.47 0 11.2 3.47 11.2 3.47 5.92 13.74 16.2 16.2 13.74"
-        },
-        key: null,
-        constructor: void 0
-      },
-      {
-        type: "polygon",
-        props: {
-          points: "25.24 16.2 35.52 5.92 35.52 11.2 38.99 11.2 38.99 3.47 38.99 0 35.52 0 27.79 0 27.79 3.47 33.07 3.47 22.79 13.74 25.24 16.2"
-        },
-        key: null,
-        constructor: void 0
-      },
-      {
-        type: "polygon",
-        props: {
-          points: "22.79 25.24 33.07 35.52 27.79 35.52 27.79 38.99 35.52 38.99 38.99 38.99 38.99 35.52 38.99 27.79 35.52 27.79 35.52 33.07 25.24 22.79 22.79 25.24"
-        },
-        key: null,
-        constructor: void 0
-      },
-      {
-        type: "polygon",
-        props: {
-          points: "13.74 22.79 3.47 33.07 3.47 27.79 0 27.79 0 35.52 0 38.99 3.47 38.99 11.2 38.99 11.2 35.52 5.92 35.52 16.2 25.24 13.74 22.79"
-        },
-        key: null,
-        constructor: void 0
-      }
-    ]
+    "aria-hidden": "true"
   },
-  key: null,
-  constructor: void 0
-};
+  h("polygon", { points: "16.2 13.74 5.92 3.47 11.2 3.47 11.2 0 3.47 0 0 0 0 3.47 0 11.2 3.47 11.2 3.47 5.92 13.74 16.2 16.2 13.74" }),
+  h("polygon", { points: "25.24 16.2 35.52 5.92 35.52 11.2 38.99 11.2 38.99 3.47 38.99 0 35.52 0 27.79 0 27.79 3.47 33.07 3.47 22.79 13.74 25.24 16.2" }),
+  h("polygon", { points: "22.79 25.24 33.07 35.52 27.79 35.52 27.79 38.99 35.52 38.99 38.99 38.99 38.99 35.52 38.99 27.79 35.52 27.79 35.52 33.07 25.24 22.79 22.79 25.24" }),
+  h("polygon", { points: "13.74 22.79 3.47 33.07 3.47 27.79 0 27.79 0 35.52 0 38.99 3.47 38.99 11.2 38.99 11.2 35.52 5.92 35.52 16.2 25.24 13.74 22.79" })
+);
 function makeEnlargeableParagraph(imageEnlarge, ContentImg, assetOptions) {
   return function EnlargeableParagraph(props) {
     const { children } = props;
-    const kids = toChildArray(children).filter((child) => {
+    const kids = flattenChildren(children).filter((child) => {
       if (typeof child === "string" || typeof child === "number") {
         return String(child).trim() !== "";
       }
@@ -90,71 +57,36 @@ function makeEnlargeableParagraph(imageEnlarge, ContentImg, assetOptions) {
           ) : void 0;
           const canEnlarge = imageEnlarge && imgProps.title !== "no-enlarge";
           if (canEnlarge || imageEntry) {
-            const enlargeBtn = {
+            const enlargeBtn = h("button", {
               type: "button",
-              props: {
-                type: "button",
-                class: "zd-enlarge-btn",
-                hidden: true,
-                "aria-label": "Enlarge image",
-                children: ENLARGE_SVG
-              },
-              key: null,
-              constructor: void 0
-            };
+              class: "zd-enlarge-btn",
+              hidden: true,
+              "aria-label": "Enlarge image"
+            }, ENLARGE_SVG);
             const captionText = typeof imgProps.alt === "string" ? imgProps.alt.trim() : "";
             const dimensions = imageEntry?.width !== void 0 && imageEntry.height !== void 0 ? ` \xB7 ${imageEntry.width} \xD7 ${imageEntry.height}` : "";
-            const figcaption = imageEntry ? {
-              type: "figcaption",
-              props: {
-                class: "mt-vsp-2xs flex flex-wrap items-baseline justify-center gap-x-hsp-xs text-caption text-muted",
-                children: [
-                  captionText ? {
-                    type: "span",
-                    props: { children: captionText },
-                    key: null,
-                    constructor: void 0
-                  } : null,
-                  captionText ? {
-                    type: "span",
-                    props: { "aria-hidden": "true", children: "|" },
-                    key: null,
-                    constructor: void 0
-                  } : null,
-                  {
-                    type: "a",
-                    props: {
-                      class: "text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline",
-                      href: assetViewerHref({
-                        base: assetOptions.base,
-                        routePrefix: assetOptions.routePrefix,
-                        path: imageEntry.path,
-                        locale: assetOptions.isDefaultLocaleOnlyPath?.(
-                          `/${assetOptions.routePrefix}/${imageEntry.path}`
-                        ) ? void 0 : assetOptions.locale
-                      }),
-                      children: `\u2922 Open asset page${dimensions}`
-                    },
-                    key: null,
-                    constructor: void 0
-                  }
-                ]
-              },
-              key: null,
-              constructor: void 0
-            } : null;
-            return {
-              type: "figure",
-              props: {
-                class: [
-                  canEnlarge ? "zd-enlargeable" : null,
-                  imageEntry ? "p-hsp-lg" : null
-                ].filter((className) => className !== null).join(" "),
-                children: [vnode, canEnlarge ? enlargeBtn : null, figcaption]
+            const figcaption = imageEntry ? h(
+              "figcaption",
+              {
+                class: "mt-vsp-2xs flex flex-wrap items-baseline justify-center gap-x-hsp-xs text-caption text-muted"
               },
-              key: null,
-              constructor: void 0
-            };
+              captionText ? h("span", null, captionText) : null,
+              captionText ? h("span", { "aria-hidden": "true" }, "|") : null,
+              h("a", {
+                class: "text-fg hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline",
+                href: assetViewerHref({
+                  base: assetOptions.base,
+                  routePrefix: assetOptions.routePrefix,
+                  path: imageEntry.path,
+                  locale: assetOptions.isDefaultLocaleOnlyPath?.(
+                    `/${assetOptions.routePrefix}/${imageEntry.path}`
+                  ) ? void 0 : assetOptions.locale
+                })
+              }, `\u2922 Open asset page${dimensions}`)
+            ) : null;
+            return h("figure", {
+              class: [canEnlarge ? "zd-enlargeable" : null, imageEntry ? "p-hsp-lg" : null].filter((name) => name !== null).join(" ")
+            }, vnode, canEnlarge ? enlargeBtn : null, figcaption);
           }
         }
       }
@@ -212,8 +144,8 @@ function createMdxComponents(options) {
     // figures also receive the p-hsp-lg inset. Must come AFTER ...defaultComponents
     // to override ContentParagraph.
     p: EnlargeableParagraph,
-    // Admonitions — real typed Preact components emitting the
-    // `.admonition` / `data-admonition` structure the design-system CSS
+    // Admonitions — server-rendered components emitting the
+    // `data-admonition` / variant-class structure the design-system CSS
     // targets. `:::note` directives emit <Note>; `<Note title="…">` JSX is
     // also authored directly. github-alerts [!IMPORTANT]/[!CAUTION] map to
     // Important/Caution — omitting those two 500s their SSR render.

package/dist/mermaid-enlarge/index.d.ts

@@ -1,11 +1,4 @@
-export declare function MermaidEnlarge(): import("preact").JSX.Element;
+export declare function MermaidEnlarge(): import("@takazudo/zfb").Description;
 export declare namespace MermaidEnlarge {
     var displayName: string;
 }
-/**
- * Static SSR fallback for the {@link MermaidEnlarge} island.
- *
- * Renders an empty, closed `<dialog class="zd-mermaid-dialog ...">` so the
- * dist HTML carries the dialog shell even before hydration.
- */
-export declare function MermaidEnlargeSsrFallback(): import("preact").JSX.Element;