@takazudo/zudo-doc 0.2.0 → 0.2.2

package/dist/integrations/llms-txt/load.d.ts

@@ -1,45 +1,17 @@
-import { LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsDocEntry } from './types.js';
+import { LlmsTxtLoadOptions, LlmsDocEntry } from './types.js';
+export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl } from '../../md-utils/index.js';
 
 /**
  * Filesystem loader for llms-txt content. Walks a markdown content root,
  * parses frontmatter via `gray-matter`, and emits sorted
  * {@link LlmsDocEntry} records ready for the generator stage.
  *
- * Lives in the framework layer (no `@/...` imports) so any consumer
- * project — Astro today, zfb tomorrow, fixture-driven unit tests in
- * between — can drive the emitter without dragging in the legacy
- * `src/utils/content-files.ts` module.
+ * The directory walk / frontmatter / URL helpers live in the shared
+ * `md-utils` module (one implementation for search-index and llms-txt,
+ * zudo-doc#2024); they are re-exported here so the integration's public
+ * surface is unchanged.
  */
 
-/**
- * Walk `dir` recursively and return every `*.md` / `*.mdx` file's
- * absolute path together with its docs-relative slug. Files (or whole
- * directories) whose name starts with `_` are skipped, matching the
- * Content Collections convention.
- */
-declare function collectMdFiles(dir: string): Array<{
-    filePath: string;
-    slug: string;
-}>;
-/**
- * Compute a docs URL for a given slug + locale. Mirrors the legacy
- * `slugToUrl(slug, locale, true)` call site exactly: when `siteUrl` is
- * empty, the URL is path-only; when `siteUrl` is set, a fully qualified
- * URL is produced.
- */
-declare function slugToUrl(slug: string, locale: string | null, base: string, siteUrl?: string): string;
-/** Whether a given doc should be excluded from the llms.txt index.
- *  `category_no_page` index files are metadata-only with no built route, so
- *  they are excluded alongside search_exclude / draft / unlisted. */
-declare function isExcluded(data: LlmsTxtFrontmatter): boolean;
-/**
- * Parse a markdown file into frontmatter + body. Returns `null` when
- * the file is unreadable so callers can simply skip it.
- */
-declare function parseMarkdownFile(filePath: string): {
-    data: LlmsTxtFrontmatter;
-    content: string;
-} | null;
 /**
  * Build the sorted {@link LlmsDocEntry} list for a single content root.
  * Excluded pages (draft / unlisted / search_exclude) are dropped.
@@ -50,4 +22,4 @@ declare function parseMarkdownFile(filePath: string): {
  */
 declare function loadDocEntries(options: LlmsTxtLoadOptions): LlmsDocEntry[];
 
-export { collectMdFiles, isExcluded, loadDocEntries, parseMarkdownFile, slugToUrl };
+export { loadDocEntries };

package/dist/integrations/llms-txt/load.js

@@ -1,62 +1,29 @@
-import { readFileSync, readdirSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-import matter from "gray-matter";
-import { stripImportsAndJsx, stripMarkdown } from "./strip.js";
-function collectMdFiles(dir) {
-  const results = [];
-  function walk(currentDir, baseDir) {
-    let entries;
-    try {
-      entries = readdirSync(currentDir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const fullPath = join(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        if (entry.name.startsWith("_")) continue;
-        walk(fullPath, baseDir);
-      } else if (/\.mdx?$/.test(entry.name) && !entry.name.startsWith("_")) {
-        const rel = relative(baseDir, fullPath).replace(/\.mdx?$/, "").replace(/\/index$/, "").replace(/^index$/, "");
-        results.push({ filePath: fullPath, slug: rel });
-      }
-    }
-  }
-  walk(dir, dir);
-  return results;
-}
-function slugToUrl(slug, locale, base, siteUrl) {
-  const trimmedBase = base.replace(/\/$/, "");
-  const path = locale ? `${trimmedBase}/${locale}/docs/${slug}` : `${trimmedBase}/docs/${slug}`;
-  if (siteUrl) {
-    return `${siteUrl.replace(/\/$/, "")}${path}`;
-  }
-  return path;
-}
-function isExcluded(data) {
-  return Boolean(
-    data.search_exclude || data.draft || data.unlisted || data.category_no_page
-  );
-}
-function parseMarkdownFile(filePath) {
-  try {
-    const raw = readFileSync(filePath, "utf-8");
-    const parsed = matter(raw);
-    return { data: parsed.data, content: parsed.content };
-  } catch {
-    return null;
-  }
-}
+import { resolve } from "node:path";
+import {
+  collectMdFiles,
+  isExcluded,
+  parseMarkdownFile,
+  slugToUrl,
+  stripMarkdown
+} from "../../md-utils/index.js";
+import { stripImportsAndJsx } from "./strip.js";
+import {
+  collectMdFiles as collectMdFiles2,
+  isExcluded as isExcluded2,
+  parseMarkdownFile as parseMarkdownFile2,
+  slugToUrl as slugToUrl2
+} from "../../md-utils/index.js";
 function loadDocEntries(options) {
   const { contentDir, locale, base, siteUrl } = options;
   const absDir = resolve(contentDir);
   const files = collectMdFiles(absDir);
   const entries = [];
-  for (const { filePath, slug } of files) {
+  for (const { filePath, slug: fileSlug } of files) {
     const parsed = parseMarkdownFile(filePath);
     if (!parsed) continue;
     const { data, content } = parsed;
     if (isExcluded(data)) continue;
+    const slug = data.slug ?? fileSlug;
     let description = data.description ?? "";
     if (!description) {
       const stripped = stripMarkdown(content);
@@ -78,9 +45,9 @@ function loadDocEntries(options) {
   return entries;
 }
 export {
-  collectMdFiles,
-  isExcluded,
+  collectMdFiles2 as collectMdFiles,
+  isExcluded2 as isExcluded,
   loadDocEntries,
-  parseMarkdownFile,
-  slugToUrl
+  parseMarkdownFile2 as parseMarkdownFile,
+  slugToUrl2 as slugToUrl
 };

package/dist/integrations/llms-txt/strip.d.ts

@@ -1,22 +1,24 @@
+export { stripMarkdown } from '../../md-utils/index.js';
+
 /**
  * Markdown / JSX text-stripping helpers.
  *
- * The two functions below match the legacy Astro emitter's behaviour
+ * `stripImportsAndJsx` matches the legacy Astro emitter's behaviour
  * byte-for-byte. Any change here is a behaviour change and must be
  * reflected in the byte-equality fixture corpus.
+ *
+ * `stripMarkdown` (used to derive a fallback `description` from the body
+ * when frontmatter doesn't carry one) lives in the shared `md-utils`
+ * module — one implementation for search-index and llms-txt
+ * (zudo-doc#2024) — and is re-exported here to keep the public surface
+ * unchanged.
  */
+
 /**
  * Strip imports, exports, and HTML/JSX tags from MDX/MD content while
  * keeping the prose layout (headings, lists, blockquotes) intact for
  * LLM consumption. Used by `llms-full.txt`.
  */
 declare function stripImportsAndJsx(content: string): string;
-/**
- * Strip markdown formatting and produce plain prose. Used to derive a
- * fallback `description` from the body when frontmatter doesn't carry
- * one. The regex sequence matches the legacy `stripMarkdown` helper in
- * `src/utils/content-files.ts` — keep them in sync.
- */
-declare function stripMarkdown(md: string): string;
 
-export { stripImportsAndJsx, stripMarkdown };
+export { stripImportsAndJsx };

package/dist/integrations/llms-txt/strip.js

@@ -1,9 +1,7 @@
+import { stripMarkdown } from "../../md-utils/index.js";
 function stripImportsAndJsx(content) {
   return content.replace(/^import\s+.*$/gm, "").replace(/^export\s+.*$/gm, "").replace(/<\/?[a-zA-Z][a-zA-Z0-9]*[^>]*>/g, "").replace(/\n{3,}/g, "\n\n").trim();
 }
-function stripMarkdown(md) {
-  return md.replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/<[^>]+>/g, "").replace(/^#{1,6}\s+/gm, "").replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1").replace(/_{1,3}([^_]+)_{1,3}/g, "$1").replace(/!\[[^\]]*\]\([^)]+\)/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/^[\s]*[-*+]\s+/gm, "").replace(/^[\s]*\d+\.\s+/gm, "").replace(/^import\s+.*$/gm, "").replace(/^export\s+.*$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
-}
 export {
   stripImportsAndJsx,
   stripMarkdown

package/dist/integrations/llms-txt/types.d.ts

@@ -1,3 +1,5 @@
+import { MdDocFrontmatter } from '../../md-utils/index.js';
+
 /**
  * Public types for the framework-agnostic llms-txt build emitter.
  *
@@ -7,29 +9,14 @@
  * markdown content roots — Astro today, zfb tomorrow, plain Node tooling
  * in a unit test, etc.
  */
+
 /**
  * Frontmatter fields the loader reads off of each MDX/MD file. Callers
- * are free to extend this; unrecognised fields are ignored.
+ * are free to extend this; unrecognised fields are ignored. Alias of the
+ * shared {@link MdDocFrontmatter} shape (`md-utils`, zudo-doc#2024) —
+ * search-index and llms-txt read the same fields.
  */
-interface LlmsTxtFrontmatter {
-    title?: string;
-    description?: string;
-    sidebar_position?: number;
-    draft?: boolean;
-    unlisted?: boolean;
-    /**
-     * `true` when the page is excluded from search and llms.txt indexing.
-     * Mirrors the `search_exclude` flag used by the existing project.
-     */
-    search_exclude?: boolean;
-    /**
-     * A `category_no_page` index.mdx carries category metadata only and builds
-     * no route — so it must NOT appear in llms.txt (the link would 404). Mirrors
-     * the route/sitemap/search exclusion in the host project.
-     */
-    category_no_page?: boolean;
-    [key: string]: unknown;
-}
+type LlmsTxtFrontmatter = MdDocFrontmatter;
 /**
  * One entry in the generated llms.txt / llms-full.txt files. Pure data,
  * already sorted, already stripped — generators (`generateLlmsTxt`,

package/dist/integrations/search-index/collect.js

@@ -5,7 +5,7 @@ import {
   parseMarkdownFile,
   slugToUrl,
   stripMarkdown
-} from "./content-files.js";
+} from "../../md-utils/index.js";
 import {
   MAX_BODY_LENGTH
 } from "./types.js";
@@ -16,11 +16,12 @@ function buildEntries(contentDir, locale, base) {
   const absDir = resolve(contentDir);
   const files = collectMdFiles(absDir);
   const entries = [];
-  for (const { filePath, slug } of files) {
+  for (const { filePath, slug: fileSlug } of files) {
     const parsed = parseMarkdownFile(filePath);
     if (!parsed) continue;
     const { data, content } = parsed;
     if (isExcluded(data)) continue;
+    const slug = data.slug ?? fileSlug;
     const id = locale ? `${locale}/${slug}` : slug;
     entries.push({
       id,

package/dist/md-utils/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Frontmatter fields the integrations read off each MDX/MD file. Extra
+ * keys pass through via the index signature. Mirrors the host project's
+ * docs schema (`src/config/docs-schema.ts`) for the fields listed here.
+ */
+interface MdDocFrontmatter {
+    title?: string;
+    description?: string;
+    /**
+     * Route-slug override (docs-schema `slug:`). The route layer resolves
+     * `data.slug ?? toRouteSlug(id)`, so every consumer that derives a URL
+     * must apply the same `data.slug ?? filesystemSlug` fallback at its
+     * call site — otherwise links to overridden pages 404. Deliberately NOT
+     * folded into {@link slugToUrl}: the effective slug is computed where
+     * the frontmatter is in scope and passed through.
+     */
+    slug?: string;
+    sidebar_position?: number;
+    draft?: boolean;
+    unlisted?: boolean;
+    /** `true` when the page is excluded from search and llms.txt indexing. */
+    search_exclude?: boolean;
+    /**
+     * A `category_no_page` index.mdx carries category metadata only and builds
+     * no route — so it must NOT be indexed or linked (the link would 404).
+     * Mirrors the route/sitemap exclusion in the host project.
+     */
+    category_no_page?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Strip markdown formatting to plain text. Conservative-by-design — the
+ * regex pipeline matches the legacy Astro integrations byte-for-byte so
+ * search excerpts and llms-txt descriptions stay byte-equal across the
+ * cutover. Do not add new rules without also updating the byte-equality
+ * fixtures (topic-plugin-audit).
+ */
+declare function stripMarkdown(md: string): string;
+/**
+ * Walk `dir` recursively and return every `*.md` / `*.mdx` file's
+ * absolute path together with its filesystem-derived slug. Files (or
+ * whole directories) whose name starts with `_` are skipped, matching
+ * the Content Collections convention (and zfb's routing): docs under
+ * them are not built as pages, so emitting them would yield entries
+ * whose links 404.
+ */
+declare function collectMdFiles(dir: string): Array<{
+    filePath: string;
+    slug: string;
+}>;
+/**
+ * Compute a docs URL for a given slug + locale, honouring `base`. When
+ * `siteUrl` is empty/omitted the URL is path-only; when set, a fully
+ * qualified URL is produced (matching the legacy llms-txt emitter's
+ * `slugToUrl(slug, locale, true)` call site exactly).
+ *
+ * Callers must pass the EFFECTIVE slug (`data.slug ?? filesystem slug`) —
+ * the frontmatter override is resolved at the call site, not here.
+ */
+declare function slugToUrl(slug: string, locale: string | null, base: string, siteUrl?: string): string;
+/**
+ * Parse a markdown file into frontmatter + body. Returns `null` when
+ * the file is unreadable so callers can simply skip it.
+ */
+declare function parseMarkdownFile(filePath: string): {
+    data: MdDocFrontmatter;
+    content: string;
+} | null;
+/**
+ * A page is excluded from indexing when explicitly opted out, drafted,
+ * unlisted, or a `category_no_page` metadata-only category index (no
+ * built route to link to).
+ */
+declare function isExcluded(data: MdDocFrontmatter): boolean;
+
+export { type MdDocFrontmatter, collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl, stripMarkdown };

package/dist/{integrations/search-index/content-files.js → md-utils/index.js}

@@ -27,20 +27,27 @@ function collectMdFiles(dir) {
   walk(dir, dir);
   return results;
 }
-function slugToUrl(slug, locale, base) {
-  const normalizedBase = base.replace(/\/$/, "");
-  return locale ? `${normalizedBase}/${locale}/docs/${slug}` : `${normalizedBase}/docs/${slug}`;
+function slugToUrl(slug, locale, base, siteUrl) {
+  const trimmedBase = base.replace(/\/$/, "");
+  const path = locale ? `${trimmedBase}/${locale}/docs/${slug}` : `${trimmedBase}/docs/${slug}`;
+  if (siteUrl) {
+    return `${siteUrl.replace(/\/$/, "")}${path}`;
+  }
+  return path;
 }
 function parseMarkdownFile(filePath) {
   try {
     const raw = readFileSync(filePath, "utf-8");
-    return matter(raw);
+    const parsed = matter(raw);
+    return { data: parsed.data, content: parsed.content };
   } catch {
     return null;
   }
 }
 function isExcluded(data) {
-  return !!(data.search_exclude || data.draft || data.unlisted || data.category_no_page);
+  return Boolean(
+    data.search_exclude || data.draft || data.unlisted || data.category_no_page
+  );
 }
 export {
   collectMdFiles,

package/dist/safelist.css

@@ -1,2 +1,2 @@
 /* generated by gen-safelist.mjs — do not edit by hand */
-@source inline("-mb-px [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [doc-history-meta] [doc-layout] a a2 abbr above absolute active actual after after-breadcrumb after-content after-sidebar after-title against agent agents ai-chat ai-chat-trigger align-top all allow-same-origin allow-scripts already-executed an anchor anchored and announce antialiased any application/json applies apply-css-vars are area arg aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow article as asc aside assets assigning assistant async at attach attribute attributes available await away b back backdrop:bg-bg/80 background backtick backticks baked banner bare based be because before below between bg bg-[#fff] bg-accent bg-bg bg-code-bg bg-fg bg-info/10 bg-muted bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blob block blockquote blocks blur body body-end-components body-end-scripts boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-collapse border-fg border-l border-l-[3px] border-muted border-none border-r border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 both br breadcrumb:end breadcrumb:start break-words browser browsers btn bundler but button buttons by caller can cancellation cannot canonical caption cases cat-nav- catch category catppuccin-latte checkbox child ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars click client clip close code code-block-sr-announce col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colors command commands commit component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher concrete configuration configure configured consumer container containers content content-type content-wrapper:end content-wrapper:start contents controller converts copy correct covered covers crashes crumb- css cursor cursor-not-allowed cursor-pointer custom dark data-active data-group-id data-header data-header-logo data-header-nav data-header-right data-mermaid-rendered data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-sidebar-resizer data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-variant data-version-banner data-version-menu data-version-switcher data-version-toggle data-zfb-transition-persist dd decimal declare decoration-muted default defaults del desc description design design-token-panel design-token-trigger desktop desktop-sidebar detached details deterministic dfn diagram diagrams dialog dieser directories directory disc display:none dist div dl doc doc-card- doc-history doc-history-generate does drag draggable dropdown dropdowns dt duration-150 duration-200 during dynamically e2e earlier edge el element elements els else em emit emitting empty en entries entry error escape even eventually every exactly exit expected failed fall fallback falls false fast feed fg fieldset figcaption figure file fill fills finally fire fires first fixed fixtures flex flex-1 flex-col flex-wrap flip flipping flips focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:underline font font-bold font-medium font-mono font-semibold footer for form free from frontmatter frontmatter-preview full function further g gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-sm gap-hsp-xs gap-vsp-lg gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps generate generation geometry get github github-link go got gray-matter grid grid-cols-1 group group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.875rem] h-[1.575rem] h-[1lh] h-[3.5rem] h-[calc(100vh-3.5rem)] h-icon-sm h-icon-xs h1 h2 h3 h4 h5 h6 hand handle handled handlers has hash-link have head head-links head-scripts header header-call:end header-call:start height here hex hidden highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr html i i2 i3 i4 identical if iframe img import imports in index inherit initial initialised inline inline-block inline-flex input ins inset-0 inside instanceof instructions intent into inverse invoke is it italic item- items items-center items-start itself javascript justify-between justify-center justify-end kbd keep keeps kept keydown khroma label landing language-switcher last:border-b-0 launch leading-relaxed leading-snug leading-tight leaf- leaving left left-0 left:calc legend lg lg:block lg:flex lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl li li2 light like line link link- list-disc list-none listener literal lives llms llms-txt load local lostpointercapture luminance m m-0 main make maps mark marks matching max-h-[80vh] max-w-[46rem] max-w-[80rem] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs menu merged mermaid message meta metadata min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode mounted mouseenter mouseleave mt-0 mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-sm mt-vsp-xl must mutates mx-auto my-vsp-lg my-vsp-md name named native nav nav-card- navigating navigation navigations near needs new next no-underline node:fs node:module node:os node:path nodes nofollow noindex non-empty non-string none noopener noreferrer normal not not-object note now null number object observe observer of og:description og:image og:title og:type og:url ol older on once one only opacity-60 option or other others out overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl packages padding page page-loading-overlay page-loading-spinner page-navigate-end pages paint panel panels parent parse parsed pass path pb-vsp-xl per pi pick picked picks pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place pointer-events-none pointercancel pointerdown pointermove pointerup polite polyline populates port position position:fixed pr-hsp-lg pr-hsp-md pr-hsp-xl pre preact preact/hooks preact/jsx-runtime preload pres produced produces production propagating properties property proxy pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q r raw re-render re-run reach reaches reading ready real references regenerates reinit relative remains render rendered renders reorder replaced repopulate requires reserved resize resize-x resolve resolved resolves return returns right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-full rounded-lg running runs runtime s safer samp schema-mismatch schema-missing script script-evaluation scripts scroll scrollbar scrolled scrollend search section section- see sel-bg sel-fg select select-none self-start separator server server-rendered set shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shared shiki ships should show shown shrink-0 sidebar signal single sitemap- size skill skills slash slug sm:flex-row sm:grid-cols-2 sm:items-center sm:justify-between small so solid some source space-y-vsp-2xs spacing span spans spec specifiers sr-only stale state stay sticky still stored stray string strip stroke-linecap stroke-linejoin stroke-width strong style styles stylesheet sub subagents subsequent success summary sup support survives svg synchronous synchronously syntactically syntect tab tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag- tag-item- tbody td temp temp-element template temporary temporary-element test-results text text-accent text-bg text-body text-caption text-center text-code-fg text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-small text-title text-warning textarea tfoot th that the thead them theme theme-color theme-toggle then these they this through time title to toggle toggle-ai-chat toggle-design-token-panel token tokens tolerates too top-0 top-[3.5rem] top-full total tr tracking-wider trade-off transition-[background,color,border-color] transition-colors transition-transform tree-child- tree-item- tree-top- trick trigger trigger:ai-chat trigger:design-token-panel triggers true try twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two u ul unavailable undefined under underline understand unknown unmaintained unobserve unreadable unreleased unreliable unset unsupported up uppercase use used uses utf-8 utf8 utilities v val value values var variable version- version-menu version-switcher vertical via video viewport visible vitesse-dark w w-[0.5rem] w-[0.875rem] w-[1.575rem] w-[16px] w-[280px] w-[var(--zd-sidebar-w)] w-full w-icon-sm w-icon-xs was watching wbr wbr- we when where whereas which while whitespace-nowrap whitespace-pre whole will with without word worktrees would wrap wrapper wrappers written wrote xl:flex xl:hidden y-scrollbar yet z-10 z-30 z-50 zd-content zd-html-preview-code zfb zfb:after-swap zfb:before-preparation zudo-doc-design-tokens/v1 zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge zudo-doc-tweak-state zudo-doc-tweak-state-v2");
+@source inline("-mb-px [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [doc-history-meta] [doc-layout] a a2 abbr above absolute active actual after after-breadcrumb after-content after-sidebar after-title against agent agents ai-chat ai-chat-trigger align-top all allow-same-origin allow-scripts already-executed an anchor anchored and announce antialiased any application/json applies apply-css-vars are area arg aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow article as asc aside assets assigning assistant async at attach attribute attributes available await away b back backdrop:bg-bg/80 background backtick backticks baked banner bare based be because before below between bg bg-[#fff] bg-accent bg-bg bg-code-bg bg-fg bg-info/10 bg-muted bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blob block blockquote blocks blur body body-end-components body-end-scripts boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-collapse border-fg border-l border-l-[3px] border-muted border-none border-r border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 both br breadcrumb:end breadcrumb:start break-words browser browsers btn bundler but button buttons by caller can cancellation cannot canonical caption cases cat-nav- catch category catppuccin-latte checkbox child ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars click client clip close code code-block-sr-announce col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colors command commands commit component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher concrete configuration configure configured consumer container containers content content-type content-wrapper:end content-wrapper:start contents controller converts copy correct covered covers crashes crumb- css cursor cursor-not-allowed cursor-pointer custom dark data-active data-group-id data-header data-header-logo data-header-nav data-header-right data-mermaid-rendered data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-sidebar-resizer data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-variant data-version-banner data-version-menu data-version-switcher data-version-toggle data-zfb-transition-persist dd decimal declare decoration-muted default defaults del desc description design design-token-panel design-token-trigger desktop desktop-sidebar detached details deterministic dfn diagram diagrams dialog dieser directories directory disc display:none dist div dl doc doc-card- doc-history doc-history-generate does drag draggable dropdown dropdowns dt duration-150 duration-200 during dynamically e2e earlier edge el element elements els else em emit emitting empty en entries entry error escape even eventually every exactly exit expected failed fall fallback falls false fast feed fg fieldset figcaption figure file fill fills finally fire fires first fixed fixtures flex flex-1 flex-col flex-wrap flip flipping flips focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:underline font font-bold font-medium font-mono font-semibold footer for form free from frontmatter frontmatter-preview full function further g gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-sm gap-hsp-xs gap-vsp-lg gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps generate generation geometry get github github-link go got gray-matter grid grid-cols-1 group group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.875rem] h-[1.575rem] h-[1lh] h-[3.5rem] h-[calc(100vh-3.5rem)] h-icon-sm h-icon-xs h1 h2 h3 h4 h5 h6 hand handle handled handlers has hash-link have head head-links head-scripts header header-call:end header-call:start height here hex hidden highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr html i i2 i3 i4 identical if iframe img import imports in index inherit initial initialised inline inline-block inline-flex input ins inset-0 inside instanceof instructions intent into inverse invoke is it italic item- items items-center items-start itself javascript justify-between justify-center justify-end kbd keep keeps kept keydown khroma label landing language-switcher last:border-b-0 launch leading-relaxed leading-snug leading-tight leaf- leaving left left-0 left:calc legend lg lg:block lg:flex lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl li li2 light like line link link- list-disc list-none listener literal lives llms llms-txt load local lostpointercapture luminance m m-0 main make maps mark marks matching max-h-[80vh] max-w-[46rem] max-w-[80rem] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs menu merged mermaid message meta metadata min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode mounted mouseenter mouseleave mt-0 mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-sm mt-vsp-xl must mutates mx-auto my-vsp-lg my-vsp-md name named native nav nav-card- navigating navigation navigations near needs new next no-underline node:fs node:module node:path nodes nofollow noindex non-empty non-string none noopener noreferrer normal not not-object note now null number object observe observer of og:description og:image og:title og:type og:url ol older on once one only opacity-60 option or other others out overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl packages padding page page-loading-overlay page-loading-spinner page-navigate-end pages paint panel panels parent parse parsed pass path pb-vsp-xl per pi pick picked picks pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place pointer-events-none pointercancel pointerdown pointermove pointerup polite polyline populates port position position:fixed pr-hsp-lg pr-hsp-md pr-hsp-xl pre preact preact/hooks preact/jsx-runtime preload pres produced produces production propagating properties property proxy pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q r raw re-render re-run reach reaches reading ready real references regenerates reinit relative remains render rendered renders reorder replaced repopulate requires reserved resize resize-x resolve resolved resolves return returns right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-full rounded-lg running runs runtime s safer samp schema-mismatch schema-missing script script-evaluation scripts scroll scrollbar scrolled scrollend search section section- see sel-bg sel-fg select select-none self-start separator server server-rendered set shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shared shiki ships should show shown shrink-0 sidebar signal single sitemap- size skill skills slash slug sm:flex-row sm:grid-cols-2 sm:items-center sm:justify-between small so solid some source space-y-vsp-2xs spacing span spans spec specifiers sr-only stale state stay sticky still stored stray string strip stroke-linecap stroke-linejoin stroke-width strong style styles stylesheet sub subagents subsequent success summary sup support survives svg synchronous synchronously syntactically syntect tab tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag- tag-item- tbody td temp temp-element template temporary temporary-element test-results text text-accent text-bg text-body text-caption text-center text-code-fg text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-small text-title text-warning textarea tfoot th that the thead them theme theme-color theme-toggle then these they this through time title to toggle toggle-ai-chat toggle-design-token-panel token tokens tolerates too top-0 top-[3.5rem] top-full total tr tracking-wider trade-off transition-[background,color,border-color] transition-colors transition-transform tree-child- tree-item- tree-top- trick trigger trigger:ai-chat trigger:design-token-panel triggers true try twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two u ul unavailable undefined under underline understand unknown unmaintained unobserve unreadable unreleased unreliable unset unsupported up uppercase use used uses utf-8 utf8 utilities v val value values var variable version- version-menu version-switcher vertical via video viewport visible vitesse-dark w w-[0.5rem] w-[0.875rem] w-[1.575rem] w-[16px] w-[280px] w-[var(--zd-sidebar-w)] w-full w-icon-sm w-icon-xs was watching wbr wbr- we when where whereas which while whitespace-nowrap whitespace-pre whole will with without word worktrees would wrap wrapper wrappers written wrote xl:flex xl:hidden y-scrollbar yet z-10 z-30 z-50 zd-content zd-doc-content-band zd-html-preview-code zd-sidebar-content-wrapper zfb zfb:after-swap zfb:before-preparation zudo-doc-design-tokens/v1 zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge");

package/dist/sidebar-tree/category-meta.js

@@ -2,7 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 const cache = /* @__PURE__ */ new Map();
 function loadCategoryMeta(contentDir) {
-  const absolute = path.resolve(contentDir);
+  let absolute;
+  try {
+    absolute = path.resolve(contentDir);
+  } catch {
+    absolute = contentDir;
+  }
   const cached = cache.get(absolute);
   if (cached) return cached;
   const result = /* @__PURE__ */ new Map();

package/dist/theme/iframe-bridge.js

@@ -12,7 +12,7 @@ function sendApplyCssVars(iframe, vars) {
     type: "apply-css-vars",
     vars
   };
-  win.postMessage(message, "*");
+  win.postMessage(message, window.location.origin);
 }
 function sendClearCssVars(iframe, names) {
   const win = iframe?.contentWindow;
@@ -22,10 +22,11 @@ function sendClearCssVars(iframe, names) {
     type: "clear-css-vars",
     names
   };
-  win.postMessage(message, "*");
+  win.postMessage(message, window.location.origin);
 }
 function installIframeReceiver(target = window) {
   function handler(event) {
+    if (event.origin !== target.location.origin) return;
     const data = event.data;
     if (!isBridgeMessage(data)) return;
     if (data.type === "apply-css-vars") {
@@ -47,12 +48,13 @@ function installIframeReceiver(target = window) {
   const parent = target.parent;
   if (parent && parent !== target) {
     const ready = { source: BRIDGE_SOURCE, type: "ready" };
-    parent.postMessage(ready, "*");
+    parent.postMessage(ready, target.location.origin);
   }
   return () => target.removeEventListener("message", handler);
 }
 function onIframeReady(expectedSource, callback) {
   function handler(event) {
+    if (event.origin !== window.location.origin) return;
     if (expectedSource && event.source !== expectedSource) return;
     if (!isBridgeMessage(event.data)) return;
     if (event.data.type === "ready") callback();

package/dist/theme/index.d.ts

@@ -5,4 +5,6 @@ export { DESIGN_TOKEN_SCHEMA, DeserializeOptions, DeserializeResult, DesignToken
 export { ColorTweakState, TokenOverrides, TweakState, emptyOverrides } from './design-token-types.js';
 export { ApplyCssVarsMessage, BRIDGE_SOURCE, BridgeMessage, ClearCssVarsMessage, CssVarPair, ErrorMessage, ReadyMessage, installIframeReceiver, isBridgeMessage, onIframeReady, sendApplyCssVars, sendClearCssVars } from './iframe-bridge.js';
 import 'preact';
+import '../theme-toggle/index.js';
+import '../theme-toggle/color-scheme-sync.js';
 import '@takazudo/zdtp';

package/dist/theme/theme-toggle.d.ts

@@ -1,16 +1,17 @@
 import { VNode } from 'preact';
+import { ThemeToggleProps } from '../theme-toggle/index.js';
+import '../theme-toggle/color-scheme-sync.js';
 
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 
-interface ThemeToggleProps {
-    defaultMode?: "light" | "dark";
-}
 /**
- * Default-export click-toggle for color scheme. Wraps `<ThemeToggleInner>`
- * in `<Island when="load">` so the SSG renderer emits a
+ * Default-export click-toggle for color scheme. Wraps the bare
+ * `<ThemeToggle>` in `<Island when="load">` so the SSG renderer emits a
  * `data-zfb-island="ThemeToggle"` marker the hydration runtime can
- * find at boot time.
+ * find at boot time. Call sites that already sit inside an island (or
+ * want to control hydration timing themselves) should import the bare
+ * component from `@takazudo/zudo-doc/theme-toggle` instead.
  */
 declare function ThemeToggle(props?: ThemeToggleProps): VNode;
 

package/dist/theme/theme-toggle.js

@@ -1,88 +1,12 @@
-"use client";
-import { jsx, jsxs } from "preact/jsx-runtime";
-import { useState, useEffect } from "preact/hooks";
+import { jsx } from "preact/jsx-runtime";
 import { Island } from "@takazudo/zfb";
-const STORAGE_KEY = "zudo-doc-theme";
-function SunIcon() {
-  return /* @__PURE__ */ jsxs(
-    "svg",
-    {
-      "aria-hidden": "true",
-      xmlns: "http://www.w3.org/2000/svg",
-      width: "20",
-      height: "20",
-      viewBox: "0 0 24 24",
-      fill: "none",
-      stroke: "currentColor",
-      strokeWidth: "2",
-      strokeLinecap: "round",
-      strokeLinejoin: "round",
-      children: [
-        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "5" }),
-        /* @__PURE__ */ jsx("line", { x1: "12", y1: "1", x2: "12", y2: "3" }),
-        /* @__PURE__ */ jsx("line", { x1: "12", y1: "21", x2: "12", y2: "23" }),
-        /* @__PURE__ */ jsx("line", { x1: "4.22", y1: "4.22", x2: "5.64", y2: "5.64" }),
-        /* @__PURE__ */ jsx("line", { x1: "18.36", y1: "18.36", x2: "19.78", y2: "19.78" }),
-        /* @__PURE__ */ jsx("line", { x1: "1", y1: "12", x2: "3", y2: "12" }),
-        /* @__PURE__ */ jsx("line", { x1: "21", y1: "12", x2: "23", y2: "12" }),
-        /* @__PURE__ */ jsx("line", { x1: "4.22", y1: "19.78", x2: "5.64", y2: "18.36" }),
-        /* @__PURE__ */ jsx("line", { x1: "18.36", y1: "5.64", x2: "19.78", y2: "4.22" })
-      ]
-    }
-  );
-}
-function MoonIcon() {
-  return /* @__PURE__ */ jsx(
-    "svg",
-    {
-      "aria-hidden": "true",
-      xmlns: "http://www.w3.org/2000/svg",
-      width: "20",
-      height: "20",
-      viewBox: "0 0 24 24",
-      fill: "none",
-      stroke: "currentColor",
-      strokeWidth: "2",
-      strokeLinecap: "round",
-      strokeLinejoin: "round",
-      children: /* @__PURE__ */ jsx("path", { d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" })
-    }
-  );
-}
-function ThemeToggleInner({ defaultMode = "dark" }) {
-  const [mode, setMode] = useState(defaultMode);
-  useEffect(() => {
-    const actual = document.documentElement.getAttribute("data-theme") || defaultMode;
-    if (actual !== mode) {
-      setMode(actual);
-    }
-  }, []);
-  function toggle() {
-    const next = mode === "dark" ? "light" : "dark";
-    setMode(next);
-    document.documentElement.setAttribute("data-theme", next);
-    document.documentElement.style.colorScheme = next;
-    localStorage.setItem(STORAGE_KEY, next);
-    localStorage.removeItem("zudo-doc-tweak-state");
-    localStorage.removeItem("zudo-doc-tweak-state-v2");
-    window.dispatchEvent(new CustomEvent("color-scheme-changed"));
-  }
-  const nextMode = mode === "dark" ? "light" : "dark";
-  return /* @__PURE__ */ jsx(
-    "button",
-    {
-      onClick: toggle,
-      "aria-label": `Switch to ${nextMode} mode`,
-      className: "text-muted hover:text-fg transition-colors p-hsp-sm focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2",
-      children: mode === "dark" ? /* @__PURE__ */ jsx(SunIcon, {}) : /* @__PURE__ */ jsx(MoonIcon, {})
-    }
-  );
-}
-ThemeToggleInner.displayName = "ThemeToggle";
+import {
+  ThemeToggle as ThemeToggleBare
+} from "../theme-toggle/index.js";
 function ThemeToggle(props = {}) {
   const rendered = Island({
     when: "load",
-    children: /* @__PURE__ */ jsx(ThemeToggleInner, { ...props })
+    children: /* @__PURE__ */ jsx(ThemeToggleBare, { ...props })
   });
   return rendered;
 }

package/dist/theme-toggle/color-scheme-sync.d.ts

@@ -0,0 +1,38 @@
+type ColorSchemeMode = "light" | "dark";
+declare const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
+/**
+ * Read the active color scheme from `<html data-theme>`. Falls back to
+ * `defaultMode` when the attribute is missing or holds an unexpected
+ * value (e.g. before the ColorSchemeProvider bootstrap script ran).
+ */
+declare function readColorSchemeFromDom(defaultMode: ColorSchemeMode): ColorSchemeMode;
+/**
+ * Apply `next` as the active color scheme: mutate the DOM, persist the
+ * preference, and notify every subscriber (including other mounted
+ * ThemeToggle instances and the zdtp design-token panel) via the
+ * `color-scheme-changed` window event.
+ *
+ * Tweak-state reconciliation is intentionally NOT done here (#2037). The zdtp
+ * panel owns its own storage lifecycle: it persists the unified tweak envelope
+ * under `zudo-doc-tweak-state-v3` (auto-migrating the legacy
+ * `zudo-doc-tweak-state-v2` / `zudo-doc-tweak-state` keys into it), and its own
+ * `color-scheme-changed` listener clears applied inline styles and re-seeds the
+ * color slice from the newly active scheme. An earlier version of this function
+ * deleted `zudo-doc-tweak-state` + `-v2` on every toggle, which (a) targeted
+ * stale keys after zdtp moved to v3 — so it no longer did anything — and
+ * (b) when it did fire, wiped the whole envelope including scheme-independent
+ * spacing/typography/size tweaks, contradicting the documented carry-over
+ * guarantee. So the host no longer touches zdtp's private storage keys.
+ *
+ * Whether palette tweaks should instead persist per-scheme (so a light/dark
+ * round-trip keeps them) is a zdtp design question tracked upstream at
+ * Takazudo/zudo-design-token-panel#343. See zudo-doc#2037.
+ */
+declare function applyColorScheme(next: ColorSchemeMode): void;
+/**
+ * Subscribe to color-scheme changes. Returns an unsubscribe function
+ * (suitable as a `useEffect` cleanup).
+ */
+declare function subscribeColorSchemeChanged(listener: () => void): () => void;
+
+export { COLOR_SCHEME_CHANGED_EVENT, type ColorSchemeMode, applyColorScheme, readColorSchemeFromDom, subscribeColorSchemeChanged };