@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/tags-audit.js

@@ -1,19 +1,13 @@
-import { readFile, readdir, writeFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, relative } from "node:path";
 import matter from "gray-matter";
 function buildIndex(vocab) {
   const byId = /* @__PURE__ */ new Map();
-  const byAlias = /* @__PURE__ */ new Map();
-  const aliasToId = /* @__PURE__ */ new Map();
   for (const entry of vocab) {
     byId.set(entry.id, entry);
-    for (const alias of entry.aliases ?? []) {
-      byAlias.set(alias, entry);
-      aliasToId.set(alias, entry.id);
-    }
   }
-  return { byId, byAlias, aliasToId };
+  return { byId };
 }
 async function collectMdxFiles(dir) {
   const out = [];
@@ -69,8 +63,6 @@ function findNearDuplicates(tags, helpers) {
 async function audit(opts) {
   const index = buildIndex(opts.vocabulary);
   const unknowns = [];
-  const deprecated = [];
-  const aliases = [];
   const frequency = {};
   const canonicalsUsed = /* @__PURE__ */ new Set();
   const rawTagsUsed = /* @__PURE__ */ new Set();
@@ -86,39 +78,19 @@ async function audit(opts) {
       const rel = relative(opts.rootDir, file);
       for (const tag of tags) {
         rawTagsUsed.add(tag);
-        const idEntry = index.byId.get(tag);
-        const aliasEntry = index.byAlias.get(tag);
         if (!opts.vocabularyActive) {
           frequency[tag] = (frequency[tag] ?? 0) + 1;
           canonicalsUsed.add(tag);
           continue;
         }
-        if (!idEntry && !aliasEntry) {
+        if (!index.byId.has(tag)) {
           unknowns.push({ file: rel, raw: tag });
           frequency[tag] = (frequency[tag] ?? 0) + 1;
           canonicalsUsed.add(tag);
           continue;
         }
-        const entry = idEntry ?? aliasEntry;
-        let canonical = entry.id;
-        const dep = entry.deprecated;
-        if (dep) {
-          if (typeof dep === "object" && dep.redirect) {
-            const target = index.byId.get(dep.redirect);
-            if (target) {
-              deprecated.push({ file: rel, raw: tag, canonical: entry.id, redirect: target.id });
-              canonical = target.id;
-            } else {
-              deprecated.push({ file: rel, raw: tag, canonical: entry.id });
-            }
-          } else {
-            deprecated.push({ file: rel, raw: tag, canonical: entry.id });
-          }
-        } else if (aliasEntry && tag !== entry.id) {
-          aliases.push({ file: rel, raw: tag, canonical: entry.id });
-        }
-        frequency[canonical] = (frequency[canonical] ?? 0) + 1;
-        canonicalsUsed.add(canonical);
+        frequency[tag] = (frequency[tag] ?? 0) + 1;
+        canonicalsUsed.add(tag);
       }
     }
   }
@@ -127,18 +99,9 @@ async function audit(opts) {
     const nearDupSource = opts.vocabularyActive ? Array.from(canonicalsUsed) : Array.from(rawTagsUsed);
     nearDuplicates.push(...findNearDuplicates(nearDupSource, opts.nearDupHelpers));
   }
-  const orphans = opts.vocabularyActive ? opts.vocabulary.filter((entry) => {
-    if (entry.deprecated) return false;
-    if (canonicalsUsed.has(entry.id)) return false;
-    for (const alias of entry.aliases ?? []) {
-      if (rawTagsUsed.has(alias)) return false;
-    }
-    return true;
-  }).map((entry) => entry.id) : [];
+  const orphans = opts.vocabularyActive ? opts.vocabulary.filter((entry) => !canonicalsUsed.has(entry.id)).map((entry) => entry.id) : [];
   return {
     unknowns,
-    deprecated,
-    aliases,
     nearDuplicates,
     orphans,
     filesScanned,
@@ -146,114 +109,7 @@ async function audit(opts) {
   };
 }
 function hasHardIssues(report) {
-  return report.unknowns.length > 0 || report.deprecated.length > 0;
-}
-function computeRewrites(vocabulary) {
-  const rewrites = /* @__PURE__ */ new Map();
-  const { byId } = buildIndex(vocabulary);
-  for (const entry of vocabulary) {
-    for (const alias of entry.aliases ?? []) {
-      if (alias === entry.id) continue;
-      const dep2 = entry.deprecated;
-      if (dep2 && typeof dep2 === "object" && dep2.redirect) {
-        const target = byId.get(dep2.redirect);
-        rewrites.set(alias, target ? target.id : entry.id);
-      } else {
-        rewrites.set(alias, entry.id);
-      }
-    }
-    const dep = entry.deprecated;
-    if (dep && typeof dep === "object" && dep.redirect) {
-      const target = byId.get(dep.redirect);
-      if (target) rewrites.set(entry.id, target.id);
-    }
-  }
-  return rewrites;
-}
-async function applyFixes(contentDirs, rewrites, rootDir) {
-  const touched = [];
-  for (const dir of contentDirs) {
-    if (!existsSync(dir)) continue;
-    const files = await collectMdxFiles(dir);
-    for (const file of files) {
-      const original = await readFile(file, "utf-8");
-      const { content, changed } = rewriteAliasesByteStable(original, rewrites);
-      if (changed) {
-        await writeFile(file, content, "utf-8");
-        touched.push(relative(rootDir, file));
-      }
-    }
-  }
-  return touched;
-}
-function rewriteAliasesByteStable(content, rewrites) {
-  if (rewrites.size === 0) return { content, changed: false };
-  const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/);
-  if (!fmMatch) return { content, changed: false };
-  const whole = fmMatch[0] ?? "";
-  const open = fmMatch[1] ?? "";
-  const fmBody = fmMatch[2] ?? "";
-  const close = fmMatch[3] ?? "";
-  let changed = false;
-  let newBody = fmBody;
-  newBody = newBody.replace(
-    /^(tags[ \t]*:[ \t]*\[)([^\]\n]*)(\])/m,
-    (_full, pre, inner, post) => {
-      const rewritten = inner.replace(
-        /(^|,)([ \t]*)(?:(")([^"]*)(")|(')([^']*)(')|([^,\s"'][^,]*?))([ \t]*)(?=,|$)/g,
-        (_m, lead, leadWs, dq1, dqVal, dq2, sq1, sqVal, sq2, bareVal, trailWs) => {
-          const val = dqVal ?? sqVal ?? bareVal ?? "";
-          const target = rewrites.get(val.trim());
-          if (!target || target === val) return _m;
-          changed = true;
-          if (dq1) return `${lead}${leadWs}"${target}"${trailWs}`;
-          if (sq1) return `${lead}${leadWs}'${target}'${trailWs}`;
-          return `${lead}${leadWs}${target}${trailWs}`;
-        }
-      );
-      return pre + rewritten + post;
-    }
-  );
-  newBody = newBody.replace(
-    /^(tags[ \t]*:[ \t]*\r?\n)((?:[ \t]+-[^\n]*\r?\n?)+)/m,
-    (_full, pre, items) => {
-      const rewritten = items.replace(
-        /^([ \t]+-[ \t]+)(?:(")([^"]*)(")|(')([^']*)('))?([^\n]*)$/gm,
-        (line, dash, dq1, dqVal, dq2, sq1, sqVal, sq2, bare) => {
-          if (dq1) {
-            const target2 = rewrites.get(dqVal);
-            if (target2 && target2 !== dqVal) {
-              changed = true;
-              return `${dash}"${target2}"${bare}`;
-            }
-            return line;
-          }
-          if (sq1) {
-            const target2 = rewrites.get(sqVal);
-            if (target2 && target2 !== sqVal) {
-              changed = true;
-              return `${dash}'${target2}'${bare}`;
-            }
-            return line;
-          }
-          const trimmed = bare.replace(/[ \t\r]+$/, "");
-          const trailing = bare.slice(trimmed.length);
-          const target = rewrites.get(trimmed);
-          if (target && target !== trimmed) {
-            changed = true;
-            return `${dash}${target}${trailing}`;
-          }
-          return line;
-        }
-      );
-      return pre + rewritten;
-    }
-  );
-  if (!changed) return { content, changed: false };
-  return {
-    content: open + newBody + close + content.slice(whole.length),
-    changed: true
-  };
+  return report.unknowns.length > 0;
 }
 function formatTextReport(report, governance, vocabularyActive, pc) {
   const lines = [];
@@ -271,22 +127,6 @@ function formatTextReport(report, governance, vocabularyActive, pc) {
     }
     lines.push("");
   }
-  if (report.deprecated.length > 0) {
-    lines.push(pc.bold(pc.yellow(`\u26A0 Deprecated tags (${report.deprecated.length})`)));
-    for (const { file, raw, redirect } of report.deprecated) {
-      const suffix = redirect ? pc.dim(` \u2192 ${redirect}`) : pc.dim(" (dropped)");
-      lines.push(`  ${pc.yellow("\u2022")} ${file}  ${raw}${suffix}`);
-    }
-    lines.push("");
-  }
-  if (report.aliases.length > 0) {
-    lines.push(pc.bold(pc.blue(`\u2139 Alias usage (${report.aliases.length})`)));
-    for (const { file, raw, canonical } of report.aliases) {
-      lines.push(`  ${pc.blue("\u2022")} ${file}  ${raw} ${pc.dim(`\u2192 ${canonical}`)}`);
-    }
-    lines.push(pc.dim(`  (run with --fix to rewrite these in place)`));
-    lines.push("");
-  }
   if (report.nearDuplicates.length > 0) {
     lines.push(pc.bold(pc.yellow(`\u26A0 Near-duplicate tags (${report.nearDuplicates.length})`)));
     for (const pair of report.nearDuplicates) {
@@ -302,20 +142,17 @@ function formatTextReport(report, governance, vocabularyActive, pc) {
     }
     lines.push("");
   }
-  if (report.unknowns.length === 0 && report.deprecated.length === 0 && report.aliases.length === 0 && report.nearDuplicates.length === 0 && report.orphans.length === 0) {
+  if (report.unknowns.length === 0 && report.nearDuplicates.length === 0 && report.orphans.length === 0) {
     lines.push(pc.green("\u2713 No tag issues found"));
   }
   return lines.join("\n");
 }
 export {
-  applyFixes,
   audit,
   buildIndex,
   collectMdxFiles,
-  computeRewrites,
   findNearDuplicates,
   formatTextReport,
   hasHardIssues,
-  normalizeTags,
-  rewriteAliasesByteStable
+  normalizeTags
 };

package/dist/theme/color-scheme-provider.d.ts

@@ -17,9 +17,8 @@ export interface ColorSchemeProviderProps {
      */
     cssText: string;
     /**
-     * Active light/dark mode config, or `null` for the persisted-tweak
-     * bootstrap path (no light/dark; the in-browser tweak panel may inject
-     * custom CSS vars from localStorage instead).
+     * Active light/dark mode config, or `null` for a single fixed scheme. The
+     * external design-token panel owns applying any persisted token overrides.
      */
     colorMode: ColorSchemeProviderColorMode | null;
     /** Optional children; preserved for forward compatibility. */

package/dist/theme/color-scheme-provider.js

@@ -17,14 +17,6 @@ document.addEventListener(${afterNav},function(){var s=null;try{s=localStorage.g
 if(respectPrefersColorScheme){window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change",function(){var s=null;try{s=localStorage.getItem(STORAGE_KEY);}catch(e){}if(!s)applyTheme(getSystemMode());});}
 })();`;
 }
-function buildPersistedTweakBootstrap() {
-  const afterNav = JSON.stringify(AFTER_NAVIGATE_EVENT);
-  return `(function(){
-function applyStoredScheme(){var css=localStorage.getItem("zudo-doc-color-scheme-css");if(!css)return;try{var pairs=JSON.parse(css);var root=document.documentElement;for(var i=0;i<pairs.length;i++){root.style.setProperty(pairs[i][0],pairs[i][1]);}}catch(e){localStorage.removeItem("zudo-doc-color-scheme-css");}}
-applyStoredScheme();
-document.addEventListener(${afterNav},applyStoredScheme);
-})();`;
-}
 function ColorSchemeProvider({
   cssText,
   colorMode
@@ -32,10 +24,10 @@ function ColorSchemeProvider({
   const bootstrap = colorMode ? buildColorModeBootstrap(
     colorMode.defaultMode,
     Boolean(colorMode.respectPrefersColorScheme)
-  ) : buildPersistedTweakBootstrap();
+  ) : null;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: cssText } }),
-    /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: bootstrap } })
+    bootstrap !== null && /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: bootstrap } })
   ] });
 }
 export {

package/dist/theme/index.d.ts

@@ -1,7 +1,4 @@
 export { default as ThemeToggle } from "./theme-toggle.js";
 export { default as ColorSchemeProvider } from "./color-scheme-provider.js";
 export type { ColorSchemeProviderProps, ColorSchemeProviderColorMode, } from "./color-scheme-provider.js";
-export { default as ColorTweakExportModal } from "./color-tweak-export-modal.js";
-export { DESIGN_TOKEN_SCHEMA, DesignTokenSchemaError, deserialize, serialize, type DesignTokenJson, type DesignTokenJsonColor, type DesignTokenJsonOverrides, type DesignTokenManifest, type DeserializeOptions, type DeserializeResult, type SerializeOptions, } from "./design-token-serde.js";
-export { emptyOverrides, type ColorTweakState, type TokenOverrides, type TweakState, } from "./design-token-types.js";
-export { BRIDGE_SOURCE, isBridgeMessage, installIframeReceiver, onIframeReady, sendApplyCssVars, sendClearCssVars, type BridgeMessage, type ApplyCssVarsMessage, type ClearCssVarsMessage, type ReadyMessage, type ErrorMessage, type CssVarPair, } from "./iframe-bridge.js";
+export { resolveThemePackSsrSlug } from "./theme-pack-provider.js";

package/dist/theme/index.js

@@ -1,36 +1,8 @@
 import { default as default2 } from "./theme-toggle.js";
 import { default as default3 } from "./color-scheme-provider.js";
-import { default as default4 } from "./color-tweak-export-modal.js";
-import {
-  DESIGN_TOKEN_SCHEMA,
-  DesignTokenSchemaError,
-  deserialize,
-  serialize
-} from "./design-token-serde.js";
-import {
-  emptyOverrides
-} from "./design-token-types.js";
-import {
-  BRIDGE_SOURCE,
-  isBridgeMessage,
-  installIframeReceiver,
-  onIframeReady,
-  sendApplyCssVars,
-  sendClearCssVars
-} from "./iframe-bridge.js";
+import { resolveThemePackSsrSlug } from "./theme-pack-provider.js";
 export {
-  BRIDGE_SOURCE,
   default3 as ColorSchemeProvider,
-  default4 as ColorTweakExportModal,
-  DESIGN_TOKEN_SCHEMA,
-  DesignTokenSchemaError,
   default2 as ThemeToggle,
-  deserialize,
-  emptyOverrides,
-  installIframeReceiver,
-  isBridgeMessage,
-  onIframeReady,
-  sendApplyCssVars,
-  sendClearCssVars,
-  serialize
+  resolveThemePackSsrSlug
 };

package/dist/theme/theme-pack-provider.d.ts

@@ -0,0 +1,42 @@
+import type { JSX } from "preact";
+import type { ThemePackRegistry } from "../theme-packs-registry/index.js";
+export interface ThemePackProviderProps {
+    /** The build-configured pack slug (`settings.themePack`, default `"default"`). */
+    configuredSlug: string;
+    /**
+     * Ordered `{ slug → meta.version }` map of the ENABLED packs — build with
+     * {@link themePackVersionMap} from `ctx.themePackRegistry`. Order carries
+     * the switcher order; versions drive the `?v=` cache-busting query.
+     */
+    enabled: Record<string, string>;
+    /** Resolved base prefix WITH trailing slash (`ctx.withBase("/")`). */
+    base: string;
+}
+/**
+ * Build the ordered `{ slug → version }` map the bootstrap inlines from the
+ * resolved, enabled, ordered registry (`ctx.themePackRegistry`).
+ */
+export declare function themePackVersionMap(registry: ThemePackRegistry): Record<string, string>;
+/**
+ * The `data-theme-pack` value a page's `<html>` element must carry in SSR
+ * output: the CONFIGURED pack slug (build-static, unlike the
+ * user-preference-only `data-theme`) — this is what the no-JS path needs.
+ * Returns `undefined` (attribute omitted, feature inert) when the registry
+ * was not threaded (`themePackRegistry: null`, e.g. a
+ * `packageOwnedRoutes: false` host that builds its own payload).
+ */
+export declare function resolveThemePackSsrSlug(registry: ThemePackRegistry | null, settings: {
+    themePack?: string;
+}): string | undefined;
+/**
+ * Bootstrap script for the theme-pack layer. Values are inlined as JSON
+ * literals so the script body is fully self-contained (the
+ * `buildColorModeBootstrap` pattern).
+ */
+export declare function buildThemePackBootstrap(configuredSlug: string, enabled: Record<string, string>, base: string): string;
+/**
+ * Server-rendered head fragment: the pre-paint bootstrap `<script>` plus the
+ * `<noscript>` configured-pack fallback. No hydration — like
+ * `ColorSchemeProvider` it just emits markup the engine streams into `<head>`.
+ */
+export default function ThemePackProvider({ configuredSlug, enabled, base, }: ThemePackProviderProps): JSX.Element;

package/dist/theme/theme-pack-provider.js

@@ -0,0 +1,75 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+import {
+  DEFAULT_THEME_PACK_SLUG,
+  THEME_PACK_ATTR,
+  THEME_PACK_LINK_ATTR,
+  THEME_PACK_RUNTIME_GLOBAL,
+  THEME_PACK_STORAGE_KEY,
+  buildPackCssUrl
+} from "../theme-pack-switcher/theme-pack-sync.js";
+function themePackVersionMap(registry) {
+  const map = {};
+  for (const entry of registry) {
+    map[entry.slug] = entry.meta.version;
+  }
+  return map;
+}
+function resolveThemePackSsrSlug(registry, settings) {
+  if (registry === null) return void 0;
+  return settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
+}
+function buildThemePackBootstrap(configuredSlug, enabled, base) {
+  const configured = JSON.stringify(configuredSlug);
+  const packs = JSON.stringify(enabled);
+  const b = JSON.stringify(base);
+  const key = JSON.stringify(THEME_PACK_STORAGE_KEY);
+  const attr = JSON.stringify(THEME_PACK_ATTR);
+  const linkAttr = JSON.stringify(THEME_PACK_LINK_ATTR);
+  const defaultSlug = JSON.stringify(DEFAULT_THEME_PACK_SLUG);
+  const runtimeGlobal = JSON.stringify(THEME_PACK_RUNTIME_GLOBAL);
+  const afterNav = JSON.stringify(AFTER_NAVIGATE_EVENT);
+  return `(function(){
+var configured=${configured};
+var packs=${packs};
+var base=${b};
+var KEY=${key};
+var ATTR=${attr};
+var LINK_ATTR=${linkAttr};
+var DEFAULT_SLUG=${defaultSlug};
+function resolveSlug(){var stored=null;try{stored=localStorage.getItem(KEY);}catch(e){}if(stored&&Object.prototype.hasOwnProperty.call(packs,stored))return stored;var live=document.documentElement.getAttribute(ATTR);if(live&&Object.prototype.hasOwnProperty.call(packs,live))return live;return configured;}
+function packHref(slug){return base+"theme-packs/"+slug+"/pack.css?v="+packs[slug];}
+var slug=resolveSlug();
+document.documentElement.setAttribute(ATTR,slug);
+if(slug!==DEFAULT_SLUG){document.write('<link rel="stylesheet" '+LINK_ATTR+' href="'+packHref(slug)+'">');}
+window[${runtimeGlobal}]={base:base,packs:packs,configured:configured};
+document.addEventListener(${afterNav},function(){
+var s=resolveSlug();
+document.documentElement.setAttribute(ATTR,s);
+var links=document.querySelectorAll("link["+LINK_ATTR+"]");
+var want=s===DEFAULT_SLUG?null:packHref(s);
+var found=false;
+for(var i=0;i<links.length;i++){var l=links[i];if(want!==null&&!found&&l.getAttribute("href")===want){found=true;}else if(l.parentNode){l.parentNode.removeChild(l);}}
+if(want!==null&&!found){var nl=document.createElement("link");nl.setAttribute("rel","stylesheet");nl.setAttribute(LINK_ATTR,"");nl.setAttribute("href",want);document.head.appendChild(nl);}
+});
+})();`;
+}
+function ThemePackProvider({
+  configuredSlug,
+  enabled,
+  base
+}) {
+  const bootstrap = buildThemePackBootstrap(configuredSlug, enabled, base);
+  const configuredVersion = enabled[configuredSlug];
+  const noscriptHref = configuredSlug !== DEFAULT_THEME_PACK_SLUG && configuredVersion !== void 0 ? buildPackCssUrl(base, configuredSlug, configuredVersion) : null;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: bootstrap } }),
+    noscriptHref !== null && /* @__PURE__ */ jsx("noscript", { children: /* @__PURE__ */ jsx("link", { rel: "stylesheet", href: noscriptHref }) })
+  ] });
+}
+export {
+  buildThemePackBootstrap,
+  ThemePackProvider as default,
+  resolveThemePackSsrSlug,
+  themePackVersionMap
+};

package/dist/theme-cli/apply.d.ts

@@ -0,0 +1,16 @@
+import { type LoadInstalledThemePackCatalogOptions } from "./registry.js";
+export interface ApplyThemePackOptions extends LoadInstalledThemePackCatalogOptions {
+    cwd?: string;
+    /** Injectable clock for tests — defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+export interface ApplyThemePackResult {
+    ok: boolean;
+    /** Human-readable outcome message (success confirmation, or a refusal
+     *  explaining WHY + the manual one-liner to add by hand). */
+    message: string;
+    /** Whether zfb.config.ts's bytes actually changed (false = idempotent
+     *  re-apply of the slug already configured). Only meaningful when `ok`. */
+    changed?: boolean;
+}
+export declare function applyThemePack(slug: string, options?: ApplyThemePackOptions): Promise<ApplyThemePackResult>;

package/dist/theme-cli/apply.js

@@ -0,0 +1,61 @@
+import fs from "fs-extra";
+import { applyThemePackToConfigSource } from "./config-rewriter.js";
+import { resolveZfbConfigPath } from "./config-io.js";
+import { writeThemePackProvenance } from "./provenance.js";
+import {
+  loadInstalledThemePackCatalog
+} from "./registry.js";
+async function applyThemePack(slug, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  let catalog;
+  try {
+    catalog = loadInstalledThemePackCatalog(options);
+  } catch (err) {
+    return {
+      ok: false,
+      message: `Could not load the installed theme pack catalog: ${err.message}`
+    };
+  }
+  const entry = catalog.find((e) => e.slug === slug);
+  if (!entry) {
+    const available = catalog.map((e) => e.slug).sort().join(", ");
+    return {
+      ok: false,
+      message: `Unknown theme pack "${slug}".
+Available theme packs: ${available}`
+    };
+  }
+  const configPath = resolveZfbConfigPath(cwd);
+  if (!await fs.pathExists(configPath)) {
+    return {
+      ok: false,
+      message: `zfb.config.ts not found at ${configPath}.
+Run this command from your project root.`
+    };
+  }
+  const source = await fs.readFile(configPath, "utf8");
+  const result = applyThemePackToConfigSource(source, slug);
+  if (!result.ok) {
+    return { ok: false, message: `Refusing to modify zfb.config.ts: ${result.reason}` };
+  }
+  if (result.changed) {
+    await fs.writeFile(configPath, result.source, "utf8");
+  }
+  await writeThemePackProvenance(cwd, {
+    schemaVersion: 1,
+    slug,
+    packVersion: entry.meta.version,
+    appliedAt: now().toISOString()
+  });
+  const verb = result.changed ? "Applied" : "Already applied";
+  return {
+    ok: true,
+    changed: result.changed,
+    message: `${verb} theme pack "${slug}" (${entry.meta.name}) to ${configPath}.
+Provenance recorded in .zudo-doc.json.`
+  };
+}
+export {
+  applyThemePack
+};

package/dist/theme-cli/config-io.d.ts

@@ -0,0 +1,15 @@
+export declare const ZFB_CONFIG_FILENAME = "zfb.config.ts";
+export declare function resolveZfbConfigPath(cwd: string): string;
+export interface DetectActiveThemePackResult {
+    slug: string;
+    /** `false` when zfb.config.ts is missing, unreadable, or not in a shape
+     *  this scanner can confidently read — `slug` is then the documented
+     *  default, not a confirmed reading of the project's real config. */
+    detected: boolean;
+}
+/**
+ * Best-effort read of the project's configured `themePack` slug. Never
+ * throws — any parse trouble degrades to the documented default with
+ * `detected: false`.
+ */
+export declare function detectActiveThemePack(cwd: string): Promise<DetectActiveThemePackResult>;

package/dist/theme-cli/config-io.js

@@ -0,0 +1,51 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { DEFAULT_THEME_PACK_SLUG } from "../theme-packs-registry/index.js";
+import {
+  ConfigSyntaxError,
+  findMatchingBrace,
+  findZudoDocCallParens,
+  isPlainStringLiteralSpan,
+  skipWhitespaceAndComments,
+  splitTopLevelMembers,
+  unquoteStringLiteralSpan
+} from "./config-scanner.js";
+const ZFB_CONFIG_FILENAME = "zfb.config.ts";
+function resolveZfbConfigPath(cwd) {
+  return path.join(cwd, ZFB_CONFIG_FILENAME);
+}
+async function detectActiveThemePack(cwd) {
+  const configPath = resolveZfbConfigPath(cwd);
+  const fallback = { slug: DEFAULT_THEME_PACK_SLUG, detected: false };
+  if (!await fs.pathExists(configPath)) return fallback;
+  let source;
+  try {
+    source = await fs.readFile(configPath, "utf8");
+  } catch {
+    return fallback;
+  }
+  try {
+    const calls = findZudoDocCallParens(source);
+    if (calls.length !== 1) return fallback;
+    const braceOpenIdx = skipWhitespaceAndComments(source, calls[0] + 1);
+    if (source[braceOpenIdx] !== "{") return fallback;
+    const braceCloseIdx = findMatchingBrace(source, braceOpenIdx);
+    const members = splitTopLevelMembers(source, braceOpenIdx + 1, braceCloseIdx);
+    if (members.some((m) => m.isSpread)) return fallback;
+    const themePackMember = members.find((m) => m.key === "themePack");
+    if (!themePackMember) return { slug: DEFAULT_THEME_PACK_SLUG, detected: true };
+    if (themePackMember.valueStart === null || themePackMember.valueEnd === null || !isPlainStringLiteralSpan(source, themePackMember.valueStart, themePackMember.valueEnd)) {
+      return fallback;
+    }
+    const slug = unquoteStringLiteralSpan(source, themePackMember.valueStart, themePackMember.valueEnd);
+    return { slug, detected: true };
+  } catch (err) {
+    if (err instanceof ConfigSyntaxError) return fallback;
+    throw err;
+  }
+}
+export {
+  ZFB_CONFIG_FILENAME,
+  detectActiveThemePack,
+  resolveZfbConfigPath
+};

package/dist/theme-cli/config-rewriter.d.ts

@@ -0,0 +1,21 @@
+export interface ApplyThemePackToSourceOk {
+    ok: true;
+    /** The full rewritten file contents. Identical to the input when
+     *  `changed` is false (idempotent re-apply of the already-active slug). */
+    source: string;
+    changed: boolean;
+    mode: "replaced" | "inserted-after-color-mode" | "inserted-after-color-scheme" | "inserted-first";
+}
+export interface ApplyThemePackToSourceRefusal {
+    ok: false;
+    /** Human-readable WHY, ending with the manual one-liner to add by hand.
+     *  The input source is never touched when this is returned. */
+    reason: string;
+}
+export type ApplyThemePackToSourceResult = ApplyThemePackToSourceOk | ApplyThemePackToSourceRefusal;
+/**
+ * Apply `themePack: "<slug>"` to a `zfb.config.ts` source string. Pure and
+ * filesystem-free — callers own reading/writing the actual file (see
+ * `apply.ts`).
+ */
+export declare function applyThemePackToConfigSource(source: string, slug: string): ApplyThemePackToSourceResult;