@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/theme-packs-registry/meta-schema.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const THEME_PACK_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const DEFAULT_THEME_PACK_SLUG = "default";
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const themePackSwatchesSchema = z.object({
+  bg: z.string().min(1),
+  fg: z.string().min(1),
+  accent: z.string().min(1),
+  syntax: z.object({
+    keyword: z.string().min(1),
+    string: z.string().min(1),
+    comment: z.string().min(1),
+    callable: z.string().min(1)
+  })
+});
+const themePackMetaSchema = z.object({
+  schemaVersion: z.literal(1),
+  slug: z.string().regex(THEME_PACK_SLUG_RE, "must match [a-z0-9][a-z0-9-]*"),
+  name: z.string().min(1),
+  description: z.string().min(1),
+  mode: z.enum(["light", "dark"]),
+  version: z.string().regex(SEMVER_RE, "must be a semver string, e.g. 1.0.0"),
+  fonts: z.object({
+    sans: z.string().min(1),
+    mono: z.string().min(1),
+    display: z.string().min(1).optional(),
+    loaded: z.array(z.string().min(1))
+  }),
+  preview: z.object({
+    light: themePackSwatchesSchema,
+    dark: themePackSwatchesSchema
+  })
+});
+export {
+  DEFAULT_THEME_PACK_SLUG,
+  THEME_PACK_SLUG_RE,
+  themePackMetaSchema
+};

package/dist/theme-packs-registry/resolve-enabled-packs.d.ts

@@ -0,0 +1,25 @@
+import type { ThemePackRegistry } from "./load-registry.js";
+/** The subset of settings this resolver reads. */
+export interface ResolveEnabledPacksSettings {
+    /** Active pack slug — must end up a member of the resolved list. */
+    themePack?: string;
+    /** Explicit enabled-pack order, or `undefined` for the canonical default
+     *  order (`"default"` first, then the rest alphabetically). */
+    themePacks?: string[];
+}
+/**
+ * Resolve the ENABLED, ORDERED subset of `registry` per `settings.themePacks`
+ * / `settings.themePack` (Decision 7):
+ *
+ * - `themePacks` omitted → every bundled pack, `"default"` first, then the
+ *   rest in canonical (alphabetical-by-slug) order.
+ * - `themePacks` an explicit array → authoritative: may omit `"default"`,
+ *   reorder freely. Duplicate or unknown slugs throw loudly.
+ * - `themePack` (the active slug, default `"default"`) must be a member of
+ *   the resolved list — an unknown/excluded active slug throws loudly,
+ *   naming the bad slug and the available ones.
+ *
+ * Pure — throws synchronously on misconfiguration; never returns a partial
+ * or silently-corrected result.
+ */
+export declare function resolveEnabledPacks(registry: ThemePackRegistry, settings: ResolveEnabledPacksSettings): ThemePackRegistry;

package/dist/theme-packs-registry/resolve-enabled-packs.js

@@ -0,0 +1,43 @@
+import { DEFAULT_THEME_PACK_SLUG } from "./meta-schema.js";
+function resolveEnabledPacks(registry, settings) {
+  const bySlug = new Map(registry.map((entry) => [entry.slug, entry]));
+  const availableSlugs = registry.map((e) => e.slug);
+  let orderedSlugs;
+  if (settings.themePacks === void 0) {
+    const hasDefault = bySlug.has(DEFAULT_THEME_PACK_SLUG);
+    const rest = availableSlugs.filter((s) => s !== DEFAULT_THEME_PACK_SLUG).sort();
+    orderedSlugs = hasDefault ? [DEFAULT_THEME_PACK_SLUG, ...rest] : rest;
+  } else {
+    const requested = settings.themePacks;
+    const seen = /* @__PURE__ */ new Set();
+    const duplicates = [];
+    const unknown = [];
+    for (const slug of requested) {
+      if (seen.has(slug)) duplicates.push(slug);
+      seen.add(slug);
+      if (!bySlug.has(slug)) unknown.push(slug);
+    }
+    if (duplicates.length > 0) {
+      throw new Error(
+        `zudo-doc: settings.themePacks contains duplicate slug(s): ${[...new Set(duplicates)].join(", ")}.`
+      );
+    }
+    if (unknown.length > 0) {
+      throw new Error(
+        `zudo-doc: settings.themePacks references unknown theme pack slug(s): ${unknown.join(", ")}. Available packs: ${availableSlugs.join(", ") || "(none)"}.`
+      );
+    }
+    orderedSlugs = [...requested];
+  }
+  const enabled = orderedSlugs.map((slug) => bySlug.get(slug));
+  const activeSlug = settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
+  if (!enabled.some((e) => e.slug === activeSlug)) {
+    throw new Error(
+      `zudo-doc: settings.themePack "${activeSlug}" is not one of the enabled theme packs. Enabled packs: ${enabled.map((e) => e.slug).join(", ") || "(none)"}.`
+    );
+  }
+  return enabled;
+}
+export {
+  resolveEnabledPacks
+};

package/dist/theme-packs-registry/token-manifest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The full closed set of custom-property names a `pack.css` may declare —
+ * every `--zd-*` semantic + syntax role, every `--zdc-*` component token,
+ * the allowed `--font-*` family tokens, and the `--zfb-hi-*` bridge. Anything
+ * else (a typo'd `--zd-syntx-keyword`, or a net-new invented property) fails
+ * the validator's known-token-name check.
+ */
+export declare const KNOWN_THEME_PACK_TOKEN_NAMES: ReadonlySet<string>;
+/**
+ * Commercial type-face names that may never appear in a pack's `@font-face`
+ * `src`/`local()` list or any `font-family` stack (ADR Decision 5 — a
+ * commercial face is never load-bearing; the pack's actual loaded face is
+ * always a designated OFL substitute, e.g. Jost for Futura). Case-insensitive
+ * substring match.
+ */
+export declare const COMMERCIAL_FONT_DENYLIST: readonly string[];
+/** Soft budget for total pack payload (css + font bytes) — Decision 6.7 /
+ *  Decision 5 "Budget (soft)". Exceeding it is a WARNING, not an error. */
+export declare const THEME_PACK_SOFT_BUDGET_BYTES: number;

package/dist/theme-packs-registry/token-manifest.js

@@ -0,0 +1,57 @@
+import { SEMANTIC_CSS_NAMES, SYNTAX_CSS_NAMES } from "../color-scheme-utils.js";
+import { COMPONENT_TOKENS } from "../config/component-tokens.js";
+const ZD_BASE_ROLE_NAMES = [
+  "--zd-bg",
+  "--zd-fg",
+  "--zd-selection-bg",
+  "--zd-selection-fg"
+];
+const FONT_TOKEN_NAMES = ["--font-sans", "--font-mono", "--font-display"];
+const ZFB_HI_BRIDGE_NAMES = [
+  "--zfb-hi-fg",
+  "--zfb-hi-bg",
+  "--zfb-hi-esc",
+  "--zfb-hi-op",
+  "--zfb-hi-com",
+  "--zfb-hi-str",
+  "--zfb-hi-num",
+  "--zfb-hi-const",
+  "--zfb-hi-kw",
+  "--zfb-hi-fn",
+  "--zfb-hi-ty",
+  "--zfb-hi-ns",
+  "--zfb-hi-prop",
+  "--zfb-hi-var",
+  "--zfb-hi-tag",
+  "--zfb-hi-attr",
+  "--zfb-hi-punct",
+  "--zfb-hi-ins",
+  "--zfb-hi-ins-bg",
+  "--zfb-hi-del",
+  "--zfb-hi-del-bg",
+  "--zfb-hi-hd"
+];
+const KNOWN_THEME_PACK_TOKEN_NAMES = /* @__PURE__ */ new Set([
+  ...ZD_BASE_ROLE_NAMES,
+  ...Object.values(SEMANTIC_CSS_NAMES),
+  ...Object.values(SYNTAX_CSS_NAMES),
+  ...COMPONENT_TOKENS.map((t) => t.cssVar),
+  ...FONT_TOKEN_NAMES,
+  ...ZFB_HI_BRIDGE_NAMES
+]);
+const COMMERCIAL_FONT_DENYLIST = [
+  "Futura",
+  "Helvetica Neue",
+  "Helvetica",
+  "Avenir",
+  "Gill Sans",
+  "Univers",
+  "Frutiger",
+  "Garamond Premier"
+];
+const THEME_PACK_SOFT_BUDGET_BYTES = 250 * 1024;
+export {
+  COMMERCIAL_FONT_DENYLIST,
+  KNOWN_THEME_PACK_TOKEN_NAMES,
+  THEME_PACK_SOFT_BUDGET_BYTES
+};

package/dist/theme-packs-registry/validator.d.ts

@@ -0,0 +1,35 @@
+import { type ThemePackMeta } from "./meta-schema.js";
+export type ThemePackValidationSeverity = "error" | "warning";
+export interface ThemePackValidationIssue {
+    /** Short machine-readable rule id, e.g. `"scoping"` or `"known-token-names"`. */
+    rule: string;
+    message: string;
+    severity: ThemePackValidationSeverity;
+}
+export interface ThemePackValidationInput {
+    /** The pack's directory name (used for slug/dir-name parity). */
+    dirName: string;
+    /** `JSON.parse`-d `meta.json` content, pre-schema-validation. */
+    metaRaw: unknown;
+    /** `pack.css` text content, or `null` when the file is absent. */
+    cssContent: string | null;
+    /** Basenames of every file inside the pack's `fonts/` directory (`[]` when
+     *  the directory is absent or empty). */
+    fontFiles: string[];
+    /** Optional total payload size (css + font bytes) for the soft budget
+     *  check. Omit to skip that check entirely. */
+    totalPayloadBytes?: number;
+}
+export interface ThemePackValidationResult {
+    /** `true` iff no issue has `severity: "error"`. */
+    valid: boolean;
+    issues: ThemePackValidationIssue[];
+    /** The schema-parsed meta, present iff the schema check passed. */
+    meta?: ThemePackMeta;
+}
+/**
+ * Validate a single theme pack against every Decision 6.7 authoring-
+ * convention rule. Filesystem-free — pass in the raw content the caller
+ * already read from disk (or, in a test, constructed directly).
+ */
+export declare function validateThemePack(input: ThemePackValidationInput): ThemePackValidationResult;

package/dist/theme-packs-registry/validator.js

@@ -0,0 +1,284 @@
+import {
+  themePackMetaSchema,
+  THEME_PACK_SLUG_RE,
+  DEFAULT_THEME_PACK_SLUG
+} from "./meta-schema.js";
+import {
+  KNOWN_THEME_PACK_TOKEN_NAMES,
+  COMMERCIAL_FONT_DENYLIST,
+  THEME_PACK_SOFT_BUDGET_BYTES
+} from "./token-manifest.js";
+function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+function parseTopLevelRules(css) {
+  const text = stripComments(css);
+  const rules = [];
+  const n = text.length;
+  let i = 0;
+  while (i < n) {
+    const braceIdx = text.indexOf("{", i);
+    if (braceIdx === -1) break;
+    const preludeRaw = text.slice(i, braceIdx).replace(/@[a-zA-Z-]+[^{;]*;/g, "");
+    const prelude = preludeRaw.trim();
+    let depth = 1;
+    let j = braceIdx + 1;
+    while (j < n && depth > 0) {
+      const ch = text[j];
+      if (ch === "{") depth++;
+      else if (ch === "}") depth--;
+      j++;
+    }
+    const body = text.slice(braceIdx + 1, Math.max(braceIdx + 1, j - 1));
+    if (prelude.length > 0) rules.push({ prelude, body });
+    i = j;
+  }
+  return rules;
+}
+function isFontFaceRule(rule) {
+  return /^@font-face\b/i.test(rule.prelude);
+}
+function extractFontFaceFamilies(cssContent) {
+  const families = [];
+  for (const rule of parseTopLevelRules(cssContent)) {
+    if (!isFontFaceRule(rule)) continue;
+    const m = rule.body.match(/font-family\s*:\s*([^;]+);/i);
+    if (!m) continue;
+    const raw = m[1].trim();
+    families.push(raw.replace(/^["']|["']$/g, ""));
+  }
+  return families;
+}
+function checkSlugAndDirParity(dirName, meta, issues) {
+  if (!THEME_PACK_SLUG_RE.test(dirName)) {
+    issues.push({
+      rule: "slug-dir-parity",
+      severity: "error",
+      message: `directory name "${dirName}" does not match the required slug pattern [a-z0-9][a-z0-9-]*`
+    });
+  }
+  if (meta && meta.slug !== dirName) {
+    issues.push({
+      rule: "slug-dir-parity",
+      severity: "error",
+      message: `meta.json "slug" ("${meta.slug}") must equal the directory name ("${dirName}")`
+    });
+  }
+}
+function checkCssPresence(dirName, cssContent, issues) {
+  if (dirName === DEFAULT_THEME_PACK_SLUG) {
+    if (cssContent !== null) {
+      issues.push({
+        rule: "css-presence",
+        severity: "error",
+        message: `the reserved "${DEFAULT_THEME_PACK_SLUG}" pack must NOT ship pack.css (it is the no-op stock look)`
+      });
+    }
+    return;
+  }
+  if (cssContent === null || cssContent.trim().length === 0) {
+    issues.push({
+      rule: "css-presence",
+      severity: "error",
+      message: `pack "${dirName}" must ship a non-empty pack.css`
+    });
+  }
+}
+function checkScoping(slug, cssContent, issues) {
+  const prefix = `html[data-theme-pack="${slug}"]`;
+  for (const rule of parseTopLevelRules(cssContent)) {
+    if (isFontFaceRule(rule)) continue;
+    for (const rawBranch of rule.prelude.split(",")) {
+      const branch = rawBranch.trim();
+      if (branch.length === 0) continue;
+      if (!branch.startsWith(prefix)) {
+        issues.push({
+          rule: "scoping",
+          severity: "error",
+          message: `selector "${branch}" is not scoped under ${prefix}`
+        });
+      }
+    }
+  }
+}
+function checkKnownTokenNames(cssContent, issues) {
+  const re = /--([a-zA-Z0-9-]+)\s*:/g;
+  const text = stripComments(cssContent);
+  const reported = /* @__PURE__ */ new Set();
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const name = `--${m[1]}`;
+    if (reported.has(name) || KNOWN_THEME_PACK_TOKEN_NAMES.has(name)) continue;
+    reported.add(name);
+    issues.push({
+      rule: "known-token-names",
+      severity: "error",
+      message: `unknown custom property "${name}" \u2014 not part of the --zd-*/--zdc-*/--font-*/--zfb-hi-* token contract (possible typo)`
+    });
+  }
+}
+function checkImportantAllowlist(cssContent, issues) {
+  const text = stripComments(cssContent);
+  const re = /([a-zA-Z-]+)\s*:\s*[^;{}]*!important[^;{}]*;/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const prop = m[1].toLowerCase();
+    if (prop !== "border-image") {
+      issues.push({
+        rule: "important-allowlist",
+        severity: "error",
+        message: `"!important" is only allowed on a "border-image" declaration (the h2\u2013h4 heading-rule gradient carve-out, Decision 6.6) \u2014 found on "${prop}"`
+      });
+    }
+  }
+}
+function checkNoColorScheme(cssContent, issues) {
+  const text = stripComments(cssContent);
+  if (/(^|[;{}\s])color-scheme\s*:/.test(text)) {
+    issues.push({
+      rule: "no-color-scheme",
+      severity: "error",
+      message: `pack.css must not declare "color-scheme:" \u2014 mode is exclusively owned by the light/dark toggle machinery`
+    });
+  }
+}
+function checkNoDataThemeSelector(cssContent, issues) {
+  const text = stripComments(cssContent);
+  if (/\[data-theme(?:=|\])/.test(text)) {
+    issues.push({
+      rule: "no-data-theme-selector",
+      severity: "error",
+      message: `pack.css must not select on "[data-theme]" \u2014 that attribute is owned by the light/dark mode toggle, not theme packs`
+    });
+  }
+}
+function checkFontFaceParity(cssContent, meta, issues) {
+  const declaredFamilies = new Set(cssContent ? extractFontFaceFamilies(cssContent) : []);
+  const loadedFamilies = new Set(meta.fonts.loaded);
+  for (const loaded of loadedFamilies) {
+    if (!declaredFamilies.has(loaded)) {
+      issues.push({
+        rule: "font-face-parity",
+        severity: "error",
+        message: `fonts.loaded lists "${loaded}" but pack.css has no matching @font-face`
+      });
+    }
+  }
+  for (const declared of declaredFamilies) {
+    if (!loadedFamilies.has(declared)) {
+      issues.push({
+        rule: "font-face-parity",
+        severity: "error",
+        message: `pack.css declares @font-face for "${declared}" but fonts.loaded does not list it`
+      });
+    }
+  }
+}
+function isPlainColorValue(value) {
+  const v = value.trim();
+  if (/var\(|light-dark\(/i.test(v)) return false;
+  if (/^#[0-9a-f]{3,8}$/i.test(v)) return true;
+  if (/^(oklch|oklab|rgb|rgba|hsl|hsla|lab|lch|color)\(/i.test(v)) return true;
+  if (/^[a-z]+$/i.test(v)) return true;
+  return false;
+}
+function checkPreviewSwatches(meta, issues) {
+  for (const mode of ["light", "dark"]) {
+    const sw = meta.preview[mode];
+    const entries = [
+      ["bg", sw.bg],
+      ["fg", sw.fg],
+      ["accent", sw.accent],
+      ["syntax.keyword", sw.syntax.keyword],
+      ["syntax.string", sw.syntax.string],
+      ["syntax.comment", sw.syntax.comment],
+      ["syntax.callable", sw.syntax.callable]
+    ];
+    for (const [key, value] of entries) {
+      if (!isPlainColorValue(value)) {
+        issues.push({
+          rule: "preview-swatch-color",
+          severity: "error",
+          message: `preview.${mode}.${key} ("${value}") is not a plain resolved CSS color \u2014 var()/light-dark() are not allowed`
+        });
+      }
+    }
+  }
+}
+function checkCommercialDenylist(cssContent, meta, issues) {
+  const scannedCss = (cssContent ?? "").replace(/\[data-theme-pack="[^"]*"\]/g, "");
+  const haystack = [
+    scannedCss,
+    meta.fonts.sans,
+    meta.fonts.mono,
+    meta.fonts.display ?? "",
+    ...meta.fonts.loaded
+  ].join("\n").toLowerCase();
+  for (const denied of COMMERCIAL_FONT_DENYLIST) {
+    if (haystack.includes(denied.toLowerCase())) {
+      issues.push({
+        rule: "commercial-font-denylist",
+        severity: "error",
+        message: `commercial typeface "${denied}" must not appear in pack.css or meta.json fonts \u2014 ship a self-hosted OFL substitute instead`
+      });
+    }
+  }
+}
+function checkOflPresence(fontFiles, issues) {
+  const hasFontBinary = fontFiles.some((f) => /\.(woff2?|ttf|otf)$/i.test(f));
+  const hasOfl = fontFiles.some((f) => f.toUpperCase() === "OFL.TXT");
+  if (hasFontBinary && !hasOfl) {
+    issues.push({
+      rule: "ofl-required",
+      severity: "error",
+      message: `fonts/ ships font binaries but no OFL.txt license file (OFL redistribution requirement)`
+    });
+  }
+}
+function checkPayloadBudget(totalPayloadBytes, issues) {
+  if (typeof totalPayloadBytes === "number" && totalPayloadBytes > THEME_PACK_SOFT_BUDGET_BYTES) {
+    issues.push({
+      rule: "payload-budget",
+      severity: "warning",
+      message: `total pack payload (~${Math.round(totalPayloadBytes / 1024)} KB) exceeds the ~250 KB soft budget`
+    });
+  }
+}
+function validateThemePack(input) {
+  const issues = [];
+  const metaParseResult = themePackMetaSchema.safeParse(input.metaRaw);
+  let meta;
+  if (!metaParseResult.success) {
+    for (const issue of metaParseResult.error.issues) {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      issues.push({
+        rule: "meta-schema",
+        severity: "error",
+        message: `meta.json "${path}": ${issue.message}`
+      });
+    }
+  } else {
+    meta = metaParseResult.data;
+  }
+  checkSlugAndDirParity(input.dirName, meta, issues);
+  checkCssPresence(input.dirName, input.cssContent, issues);
+  if (input.cssContent) {
+    checkScoping(input.dirName, input.cssContent, issues);
+    checkKnownTokenNames(input.cssContent, issues);
+    checkImportantAllowlist(input.cssContent, issues);
+    checkNoColorScheme(input.cssContent, issues);
+    checkNoDataThemeSelector(input.cssContent, issues);
+  }
+  if (meta) {
+    checkFontFaceParity(input.cssContent, meta, issues);
+    checkPreviewSwatches(meta, issues);
+    checkCommercialDenylist(input.cssContent, meta, issues);
+  }
+  checkOflPresence(input.fontFiles, issues);
+  checkPayloadBudget(input.totalPayloadBytes, issues);
+  const valid = !issues.some((i) => i.severity === "error");
+  return { valid, issues, ...meta ? { meta } : {} };
+}
+export {
+  validateThemePack
+};

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

@@ -13,10 +13,8 @@ export declare function readColorSchemeFromDom(defaultMode: ColorSchemeMode): Co
  * `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-v4` (auto-migrating the legacy
- * `zudo-doc-tweak-state-v3` / `-v2` / `zudo-doc-tweak-state` (v1) keys into
- * it), and its own `color-scheme-changed` listener clears applied inline
+ * panel owns its own storage lifecycle and current persisted-state contract;
+ * 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