@takazudo/zudo-doc 4.3.0 → 4.4.0

package/dist/eject-logo/config-rewriter.d.ts

@@ -0,0 +1,22 @@
+export declare const EJECTED_LOGO_VALUE = "/img/logo.svg";
+export interface ApplyLogoFieldToSourceOk {
+    ok: true;
+    /** The full rewritten file contents. Identical to the input when
+     *  `changed` is false (idempotent re-run of an already-ejected logo). */
+    source: string;
+    changed: boolean;
+    mode: "replaced" | "inserted-after-site-name" | "inserted-first";
+}
+export interface ApplyLogoFieldToSourceRefusal {
+    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 ApplyLogoFieldToSourceResult = ApplyLogoFieldToSourceOk | ApplyLogoFieldToSourceRefusal;
+/**
+ * Apply `logo: "/img/logo.svg"` to a `zfb.config.ts` source string. Pure and
+ * filesystem-free — callers own reading/writing the actual file (see
+ * `eject.ts`).
+ */
+export declare function applyLogoFieldToConfigSource(source: string): ApplyLogoFieldToSourceResult;

package/dist/eject-logo/config-rewriter.js

@@ -0,0 +1,68 @@
+import { isPlainStringLiteralSpan } from "../theme-cli/config-scanner.js";
+import { parseZudoDocConfigMembers } from "./config-parse.js";
+const EJECTED_LOGO_VALUE = "/img/logo.svg";
+function manualHint() {
+  return `Add the field manually inside your zudoDoc({ ... }) call: logo: ${JSON.stringify(EJECTED_LOGO_VALUE)},`;
+}
+function refuse(reason) {
+  return { ok: false, reason: `${reason} ${manualHint()}` };
+}
+function isPlainFalseLiteralSpan(source, start, end) {
+  return source.slice(start, end).trim() === "false";
+}
+function detectIndent(source, members) {
+  const ref = members[0];
+  const refPos = ref ? ref.keyStart ?? ref.memberStart : null;
+  if (refPos !== null && refPos !== void 0) {
+    const newlineIdx = source.lastIndexOf("\n", refPos);
+    const lineStart = newlineIdx === -1 ? 0 : newlineIdx + 1;
+    const line = source.slice(lineStart, refPos);
+    if (/^[ \t]*$/.test(line) && line.length > 0) return line;
+  }
+  return "  ";
+}
+function applyLogoFieldToConfigSource(source) {
+  const parsed = parseZudoDocConfigMembers(source);
+  if (!parsed.ok) return refuse(parsed.reason);
+  const { members, braceOpenIdx } = parsed;
+  const newValueLiteral = JSON.stringify(EJECTED_LOGO_VALUE);
+  const logoMembers = members.filter((m) => m.key === "logo");
+  if (logoMembers.length > 1) {
+    return refuse(
+      'zfb.config.ts declares "logo" more than once inside zudoDoc({ ... }). This CLI only rewrites a single canonical field; remove the duplicate and re-run.'
+    );
+  }
+  const logoMember = logoMembers[0];
+  if (logoMember) {
+    if (logoMember.valueStart === null || logoMember.valueEnd === null) {
+      return refuse('the existing "logo" field in zfb.config.ts is not a simple `key: value` property this CLI understands.');
+    }
+    const isReplaceableLiteral = isPlainStringLiteralSpan(source, logoMember.valueStart, logoMember.valueEnd) || isPlainFalseLiteralSpan(source, logoMember.valueStart, logoMember.valueEnd);
+    if (!isReplaceableLiteral) {
+      return refuse(
+        'the existing "logo" field\'s value is not a plain string literal or `false` \u2014 cannot safely rewrite it without risking corruption.'
+      );
+    }
+    const newSource2 = source.slice(0, logoMember.valueStart) + newValueLiteral + source.slice(logoMember.valueEnd);
+    return { ok: true, source: newSource2, changed: newSource2 !== source, mode: "replaced" };
+  }
+  const siteNameMember = members.find((m) => m.key === "siteName");
+  const indent = detectIndent(source, members);
+  if (siteNameMember) {
+    const insertAt2 = siteNameMember.commaIndex !== null ? siteNameMember.commaIndex + 1 : siteNameMember.memberEnd;
+    const prefix = siteNameMember.commaIndex !== null ? "" : ",";
+    const insertText2 = `${prefix}
+${indent}logo: ${newValueLiteral},`;
+    const newSource2 = source.slice(0, insertAt2) + insertText2 + source.slice(insertAt2);
+    return { ok: true, source: newSource2, changed: true, mode: "inserted-after-site-name" };
+  }
+  const insertAt = braceOpenIdx + 1;
+  const insertText = `
+${indent}logo: ${newValueLiteral},`;
+  const newSource = source.slice(0, insertAt) + insertText + source.slice(insertAt);
+  return { ok: true, source: newSource, changed: true, mode: "inserted-first" };
+}
+export {
+  EJECTED_LOGO_VALUE,
+  applyLogoFieldToConfigSource
+};

package/dist/eject-logo/eject.d.ts

@@ -0,0 +1,18 @@
+export interface EjectLogoOptions {
+    cwd?: string;
+    /** Explicit seed override (already validated non-empty by the CLI arg
+     *  parser in bin/zudo-doc.mjs). When omitted, the seed is resolved from
+     *  zfb.config.ts's siteName field. */
+    seed?: string;
+    force?: boolean;
+}
+export interface EjectLogoResult {
+    ok: boolean;
+    /** Human-readable outcome message (success confirmation, or a refusal
+     *  explaining WHY). */
+    message: string;
+    /** True when the SVG was written but the config rewrite was refused — a
+     *  nonzero-exit partial success, not a total failure. */
+    partial?: boolean;
+}
+export declare function ejectLogo(options?: EjectLogoOptions): Promise<EjectLogoResult>;

package/dist/eject-logo/eject.js

@@ -0,0 +1,66 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { renderAutoLogoStandaloneSvg } from "../auto-logo/standalone.js";
+import { applyLogoFieldToConfigSource } from "./config-rewriter.js";
+import { resolveSiteNameFromConfigSource } from "./site-name.js";
+const ZFB_CONFIG_FILENAME = "zfb.config.ts";
+const LOGO_RELATIVE_PATH = path.join("public", "img", "logo.svg");
+const DEFAULT_SEED = "Docs";
+async function ejectLogo(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const force = options.force ?? false;
+  const configPath = path.join(cwd, ZFB_CONFIG_FILENAME);
+  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");
+  let seed;
+  if (options.seed) {
+    seed = options.seed;
+  } else {
+    const resolution = resolveSiteNameFromConfigSource(source);
+    if (resolution.kind === "unresolvable") {
+      return {
+        ok: false,
+        message: `Could not determine a logo seed from zfb.config.ts: ${resolution.reason}
+Pass --seed <name> to specify the logo seed explicitly.`
+      };
+    }
+    seed = resolution.kind === "literal" ? resolution.value : DEFAULT_SEED;
+  }
+  const rewriteResult = applyLogoFieldToConfigSource(source);
+  const svgPath = path.join(cwd, LOGO_RELATIVE_PATH);
+  if (!force && await fs.pathExists(svgPath)) {
+    return {
+      ok: false,
+      message: `${LOGO_RELATIVE_PATH} already exists.
+Pass --force to overwrite it.`
+    };
+  }
+  const svg = renderAutoLogoStandaloneSvg(seed);
+  await fs.ensureDir(path.dirname(svgPath));
+  await fs.writeFile(svgPath, svg, "utf8");
+  if (!rewriteResult.ok) {
+    return {
+      ok: false,
+      partial: true,
+      message: `Wrote ${LOGO_RELATIVE_PATH}, but could not update zfb.config.ts: ${rewriteResult.reason}`
+    };
+  }
+  if (rewriteResult.changed) {
+    await fs.writeFile(configPath, rewriteResult.source, "utf8");
+  }
+  const verb = rewriteResult.changed ? "Ejected logo" : "Ejected logo (field already set)";
+  return {
+    ok: true,
+    message: `${verb} \u2192 ${LOGO_RELATIVE_PATH}
+Updated zfb.config.ts's logo field.`
+  };
+}
+export {
+  ejectLogo
+};

package/dist/eject-logo/index.d.ts

@@ -0,0 +1,4 @@
+export { ejectLogo, type EjectLogoOptions, type EjectLogoResult } from "./eject.js";
+export { applyLogoFieldToConfigSource, EJECTED_LOGO_VALUE, type ApplyLogoFieldToSourceOk, type ApplyLogoFieldToSourceRefusal, type ApplyLogoFieldToSourceResult, } from "./config-rewriter.js";
+export { resolveSiteNameFromConfigSource, type SiteNameResolution } from "./site-name.js";
+export { parseZudoDocConfigMembers, type ParsedZudoDocConfig, type ParsedZudoDocConfigRefusal, type ParseZudoDocConfigResult, } from "./config-parse.js";

package/dist/eject-logo/index.js

@@ -0,0 +1,16 @@
+import { ejectLogo } from "./eject.js";
+import {
+  applyLogoFieldToConfigSource,
+  EJECTED_LOGO_VALUE
+} from "./config-rewriter.js";
+import { resolveSiteNameFromConfigSource } from "./site-name.js";
+import {
+  parseZudoDocConfigMembers
+} from "./config-parse.js";
+export {
+  EJECTED_LOGO_VALUE,
+  applyLogoFieldToConfigSource,
+  ejectLogo,
+  parseZudoDocConfigMembers,
+  resolveSiteNameFromConfigSource
+};

package/dist/eject-logo/site-name.d.ts

@@ -0,0 +1,21 @@
+export type SiteNameResolution = {
+    kind: "literal";
+    value: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+/**
+ * Resolve `siteName` from a `zfb.config.ts` source string.
+ *
+ * - Literal `siteName: "..."` → `{ kind: "literal", value }`.
+ * - Canonical literal config with no `siteName` field → `{ kind: "absent" }`
+ *   (the runtime default `"Docs"` genuinely applies — this IS a confirmed
+ *   reading, the caller decides the default value).
+ * - Anything else (no/duplicate zudoDoc call, spread argument, computed or
+ *   duplicate `siteName`, non-string value) → `{ kind: "unresolvable",
+ *   reason }`; the caller must require `--seed`.
+ */
+export declare function resolveSiteNameFromConfigSource(source: string): SiteNameResolution;

package/dist/eject-logo/site-name.js

@@ -0,0 +1,31 @@
+import { isPlainStringLiteralSpan, unquoteStringLiteralSpan } from "../theme-cli/config-scanner.js";
+import { parseZudoDocConfigMembers } from "./config-parse.js";
+function resolveSiteNameFromConfigSource(source) {
+  const parsed = parseZudoDocConfigMembers(source);
+  if (!parsed.ok) return { kind: "unresolvable", reason: parsed.reason };
+  const siteNameMembers = parsed.members.filter((m) => m.key === "siteName");
+  if (siteNameMembers.length > 1) {
+    return {
+      kind: "unresolvable",
+      reason: 'zfb.config.ts declares "siteName" more than once inside zudoDoc({ ... }) \u2014 cannot safely determine which one the runtime reads.'
+    };
+  }
+  const member = siteNameMembers[0];
+  if (!member) return { kind: "absent" };
+  if (member.valueStart === null || member.valueEnd === null) {
+    return {
+      kind: "unresolvable",
+      reason: 'the "siteName" field in zfb.config.ts is not a simple `key: value` property this CLI understands.'
+    };
+  }
+  if (!isPlainStringLiteralSpan(source, member.valueStart, member.valueEnd)) {
+    return {
+      kind: "unresolvable",
+      reason: `the "siteName" field's value in zfb.config.ts is not a plain string literal.`
+    };
+  }
+  return { kind: "literal", value: unquoteStringLiteralSpan(source, member.valueStart, member.valueEnd) };
+}
+export {
+  resolveSiteNameFromConfigSource
+};

package/dist/header/header.js

@@ -6,6 +6,14 @@ import {
   pathForMatch
 } from "./nav-active.js";
 import { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-script.js";
+import {
+  NAV_CHEVRON_ACTIVE,
+  NAV_CHEVRON_INACTIVE,
+  NAV_CHILD_ACTIVE,
+  NAV_CHILD_INACTIVE,
+  NAV_TOP_ACTIVE,
+  NAV_TOP_INACTIVE
+} from "./nav-class-tokens.js";
 import { LANGUAGE_SWITCHER_INIT_SCRIPT } from "../i18n-version/language-switcher.js";
 import { VERSION_SWITCHER_REWIRE_SCRIPT } from "../i18n-version/version-switcher.js";
 import { GitHub as GitHubIcon } from "../icons/index.js";
@@ -81,7 +89,7 @@ function Header(props) {
                   "button",
                   {
                     type: "button",
-                    class: "px-hsp-md py-vsp-2xs text-small font-medium text-muted hover:underline cursor-pointer",
+                    class: "px-hsp-md py-vsp-2xs text-small font-medium text-muted hover:text-accent hover:underline focus-visible:text-accent focus-visible:underline cursor-pointer",
                     "data-nav-more-toggle": true,
                     "aria-expanded": "false",
                     children: "\xB7\xB7\xB7"
@@ -177,7 +185,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
               "aria-expanded": "false",
               class: [
                 "flex items-center gap-x-hsp-xs px-hsp-md py-vsp-2xs text-small font-medium transition-colors",
-                isActive ? "bg-fg text-bg" : "text-muted hover:underline focus:underline"
+                isActive ? NAV_TOP_ACTIVE.join(" ") : NAV_TOP_INACTIVE.join(" ")
               ].join(" "),
               children: [
                 label,
@@ -186,7 +194,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
                   {
                     class: [
                       "h-[0.5rem] w-[0.5rem] shrink-0",
-                      isActive ? "text-bg" : "text-muted"
+                      isActive ? NAV_CHEVRON_ACTIVE.join(" ") : NAV_CHEVRON_INACTIVE.join(" ")
                     ].join(" "),
                     fill: "none",
                     viewBox: "0 0 24 24",
@@ -216,8 +224,8 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
                 href: childHref,
                 "data-active": childActive ? "" : void 0,
                 class: [
-                  "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline",
-                  childActive ? "font-bold text-accent" : "text-fg"
+                  "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline",
+                  childActive ? NAV_CHILD_ACTIVE.join(" ") : NAV_CHILD_INACTIVE.join(" ")
                 ].join(" "),
                 children: childLabel
               }
@@ -235,7 +243,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
       "data-nav-item": true,
       class: [
         "px-hsp-md py-vsp-2xs text-small font-medium transition-colors shrink-0",
-        isActive ? "bg-fg text-bg" : "text-muted hover:underline focus:underline"
+        isActive ? NAV_TOP_ACTIVE.join(" ") : NAV_TOP_INACTIVE.join(" ")
       ].join(" "),
       children: label
     }

package/dist/header/nav-class-tokens.d.ts

@@ -0,0 +1,12 @@
+export declare const NAV_TOP_ACTIVE: readonly string[];
+export declare const NAV_TOP_INACTIVE: readonly string[];
+export declare const NAV_CHEVRON_ACTIVE: readonly string[];
+export declare const NAV_CHEVRON_INACTIVE: readonly string[];
+export declare const NAV_CHILD_ACTIVE: readonly string[];
+export declare const NAV_CHILD_INACTIVE: readonly string[];
+export declare const NAV_MENU_PARENT: readonly string[];
+export declare const NAV_MENU_PARENT_ACTIVE_SUFFIX: readonly string[];
+export declare const NAV_MENU_PLAIN: readonly string[];
+export declare const NAV_MENU_PLAIN_ACTIVE_SUFFIX: readonly string[];
+export declare const NAV_MENU_CHILD_ACTIVE: readonly string[];
+export declare const NAV_MENU_CHILD_INACTIVE: readonly string[];

package/dist/header/nav-class-tokens.js

@@ -0,0 +1,80 @@
+const NAV_TOP_ACTIVE = ["bg-fg", "text-bg"];
+const NAV_TOP_INACTIVE = [
+  "text-muted",
+  "hover:text-accent",
+  "hover:underline",
+  "focus:underline",
+  "focus:text-accent"
+];
+const NAV_CHEVRON_ACTIVE = ["text-bg"];
+const NAV_CHEVRON_INACTIVE = ["text-muted"];
+const NAV_CHILD_ACTIVE = ["font-bold", "text-accent"];
+const NAV_CHILD_INACTIVE = [
+  "text-fg",
+  "hover:text-accent",
+  "focus-visible:text-accent"
+];
+const MENU_ROW_BASE = [
+  "block",
+  "px-hsp-md",
+  "py-vsp-2xs",
+  "text-small"
+];
+const MENU_CHILD_BASE = [
+  "block",
+  "pl-hsp-xl",
+  "pr-hsp-md",
+  "py-vsp-2xs",
+  "text-small"
+];
+const MENU_ROW_RESTING = [
+  "hover:bg-accent/10",
+  "hover:underline",
+  "focus-visible:underline",
+  "focus-visible:text-accent",
+  "text-fg",
+  "hover:text-accent"
+];
+const NAV_MENU_PARENT = [
+  ...MENU_ROW_BASE,
+  "font-bold",
+  ...MENU_ROW_RESTING
+];
+const NAV_MENU_PARENT_ACTIVE_SUFFIX = ["text-accent"];
+const NAV_MENU_PLAIN = [
+  ...MENU_ROW_BASE,
+  ...MENU_ROW_RESTING
+];
+const NAV_MENU_PLAIN_ACTIVE_SUFFIX = [
+  ...NAV_CHILD_ACTIVE
+];
+const NAV_MENU_CHILD_ACTIVE = [
+  ...MENU_CHILD_BASE,
+  ...NAV_CHILD_ACTIVE,
+  "hover:bg-accent/10",
+  "hover:underline",
+  "focus-visible:underline"
+];
+const NAV_MENU_CHILD_INACTIVE = [
+  ...MENU_CHILD_BASE,
+  "text-fg",
+  "hover:bg-accent/10",
+  "hover:text-accent",
+  "hover:underline",
+  "focus-visible:underline",
+  "focus-visible:text-accent"
+];
+export {
+  NAV_CHEVRON_ACTIVE,
+  NAV_CHEVRON_INACTIVE,
+  NAV_CHILD_ACTIVE,
+  NAV_CHILD_INACTIVE,
+  NAV_MENU_CHILD_ACTIVE,
+  NAV_MENU_CHILD_INACTIVE,
+  NAV_MENU_PARENT,
+  NAV_MENU_PARENT_ACTIVE_SUFFIX,
+  NAV_MENU_PLAIN,
+  NAV_MENU_PLAIN_ACTIVE_SUFFIX,
+  NAV_TOP_ACTIVE,
+  NAV_TOP_INACTIVE
+};

package/dist/header/nav-overflow-script.js

@@ -1,4 +1,21 @@
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+import {
+  NAV_CHEVRON_ACTIVE,
+  NAV_CHEVRON_INACTIVE,
+  NAV_CHILD_ACTIVE,
+  NAV_CHILD_INACTIVE,
+  NAV_MENU_CHILD_ACTIVE,
+  NAV_MENU_CHILD_INACTIVE,
+  NAV_MENU_PARENT,
+  NAV_MENU_PARENT_ACTIVE_SUFFIX,
+  NAV_MENU_PLAIN,
+  NAV_MENU_PLAIN_ACTIVE_SUFFIX,
+  NAV_TOP_ACTIVE,
+  NAV_TOP_INACTIVE
+} from "./nav-class-tokens.js";
+const clsArgs = (tokens) => tokens.map((token) => JSON.stringify(token)).join(", ");
+const clsLiteral = (tokens) => JSON.stringify(tokens.join(" "));
+const clsAppend = (tokens) => JSON.stringify(" " + tokens.join(" "));
 const NAV_OVERFLOW_SCRIPT = `(function () {
   var cleanupNavOverflow = null;
 
@@ -56,12 +73,12 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
     function setTopActive(a, active) {
       if (!a) return;
       if (active) {
-        a.classList.add("bg-fg", "text-bg");
-        a.classList.remove("text-muted", "hover:underline", "focus:underline");
+        a.classList.add(${clsArgs(NAV_TOP_ACTIVE)});
+        a.classList.remove(${clsArgs(NAV_TOP_INACTIVE)});
         a.setAttribute("aria-current", "page");
       } else {
-        a.classList.remove("bg-fg", "text-bg");
-        a.classList.add("text-muted", "hover:underline", "focus:underline");
+        a.classList.remove(${clsArgs(NAV_TOP_ACTIVE)});
+        a.classList.add(${clsArgs(NAV_TOP_INACTIVE)});
         a.removeAttribute("aria-current");
       }
     }
@@ -79,19 +96,19 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
           if (childActive) {
             anyChild = true;
             c.setAttribute("data-active", "");
-            c.classList.add("font-bold", "text-accent");
-            c.classList.remove("text-fg");
+            c.classList.add(${clsArgs(NAV_CHILD_ACTIVE)});
+            c.classList.remove(${clsArgs(NAV_CHILD_INACTIVE)});
           } else {
             c.removeAttribute("data-active");
-            c.classList.remove("font-bold", "text-accent");
-            c.classList.add("text-fg");
+            c.classList.remove(${clsArgs(NAV_CHILD_ACTIVE)});
+            c.classList.add(${clsArgs(NAV_CHILD_INACTIVE)});
           }
         });
         topActive = parentMatch || anyChild;
         var svg = topA ? topA.querySelector("svg") : null;
         if (svg) {
-          if (topActive) { svg.classList.add("text-bg"); svg.classList.remove("text-muted"); }
-          else { svg.classList.add("text-muted"); svg.classList.remove("text-bg"); }
+          if (topActive) { svg.classList.add(${clsArgs(NAV_CHEVRON_ACTIVE)}); svg.classList.remove(${clsArgs(NAV_CHEVRON_INACTIVE)}); }
+          else { svg.classList.add(${clsArgs(NAV_CHEVRON_INACTIVE)}); svg.classList.remove(${clsArgs(NAV_CHEVRON_ACTIVE)}); }
         }
       } else {
         topActive = activePath !== "" && navPathname(topA) === activePath;
@@ -173,9 +190,9 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
             a.href = parentLink.href;
             var parentText = parentLink.textContent ? parentLink.textContent.trim().replace(/\\s+/g, " ") : "";
             a.textContent = parentText;
-            a.className = "block px-hsp-md py-vsp-2xs text-small font-bold hover:bg-accent/10 hover:underline focus-visible:underline text-fg";
+            a.className = ${clsLiteral(NAV_MENU_PARENT)};
             if (parentLink.getAttribute("aria-current") === "page") {
-              a.className += " text-accent";
+              a.className += ${clsAppend(NAV_MENU_PARENT_ACTIVE_SUFFIX)};
             }
             li.appendChild(a);
             moreMenu.appendChild(li);
@@ -187,8 +204,8 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
             a.textContent = child.textContent ? child.textContent.trim() : "";
             var isChildActive = child.hasAttribute("data-active");
             a.className = isChildActive
-              ? "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small font-bold text-accent hover:bg-accent/10 hover:underline focus-visible:underline"
-              : "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small text-muted hover:bg-accent/10 hover:text-fg hover:underline focus-visible:underline";
+              ? ${clsLiteral(NAV_MENU_CHILD_ACTIVE)}
+              : ${clsLiteral(NAV_MENU_CHILD_INACTIVE)};
             li.appendChild(a);
             moreMenu.appendChild(li);
           });
@@ -198,9 +215,9 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
           var a2 = document.createElement("a");
           a2.href = anchor.href;
           a2.textContent = anchor.textContent ? anchor.textContent.trim() : "";
-          a2.className = "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline text-fg";
+          a2.className = ${clsLiteral(NAV_MENU_PLAIN)};
           if (anchor.getAttribute("aria-current") === "page") {
-            a2.className += " font-bold text-accent";
+            a2.className += ${clsAppend(NAV_MENU_PLAIN_ACTIVE_SUFFIX)};
           }
           li2.appendChild(a2);
           moreMenu.appendChild(li2);

package/dist/home-page/index.d.ts

@@ -1,6 +1,7 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 import type { ComponentChildren, JSX } from "preact";
+import type { TagItem } from "../nav-indexing/types.js";
 import type { DocNavNode } from "../doc-page-props/index.js";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
@@ -12,9 +13,10 @@ export interface HomePageViewProps {
      *  `hostBindings.homeExtras({ locale })` call when `extras` is absent. */
     locale: string;
     /**
-     * Extra content rendered after the links row, inside the hero text column.
-     * A VALUE (already-rendered children) — the host-PAGE path. Takes
-     * precedence over `ctx.hostBindings.homeExtras` when both are present.
+     * Extra content rendered INLINE at the end of the links row, `/`-separated
+     * from whatever precedes it (the primary link and/or the GitHub link). A
+     * VALUE (already-rendered children) — the host-PAGE path. Takes precedence
+     * over `ctx.hostBindings.homeExtras` when both are present.
      *
      * This value-vs-renderer asymmetry (prop = value, `hostBindings.homeExtras`
      * = renderer) is INTENTIONAL, not an oversight to "unify": a host page
@@ -24,6 +26,17 @@ export interface HomePageViewProps {
      * locale })`.
      */
     extras?: ComponentChildren;
+    /**
+     * Overrides the default first hero link, which is otherwise
+     * `settings.headerNav[0]` + `t("nav.overview", locale)`. `path` is
+     * locale-relative (the view prefixes it with the locale-URL prefix and
+     * resolves it through `withBase`, same as the default); `labelKey`
+     * resolves through `t(labelKey, locale)`.
+     */
+    heroLink?: {
+        path: string;
+        labelKey: string;
+    };
     /** Prepared nav tree for the `SiteTreeNav` grid (already grouped via
      *  `groupSatelliteNodes` by the caller — the two routes group their own
      *  locale-specific tree before handing it here). */
@@ -32,9 +45,25 @@ export interface HomePageViewProps {
     categoryOrder: string[];
     /** Root-category slugs that should start collapsed in `SiteTreeNav`. */
     initiallyCollapsedCategorySlugs?: string[];
-    /** Unique tag count for the current locale — gates the "all tags" section
-     *  together with `settings.docTags`. */
+    /** Unique tag count for the current locale — gates the "Tags" section
+     *  together with `settings.docTags`. Part of the documented public
+     *  `@takazudo/zudo-doc/home-page` props shape (kept for back-compat). */
     tagCount: number;
+    /**
+     * Alphabetically-sorted tag list (tag + doc count + pre-resolved href) for
+     * the current locale. When provided (and non-empty) the section renders the
+     * tag chips (first {@link HomePageViewProps.tagLimit}) plus a "see all tags"
+     * nav. When omitted — legacy callers that pass only `tagCount` — the section
+     * falls back to the pre-#3027 single "All Tags" link, so existing
+     * `@takazudo/zudo-doc/home-page` consumers are not broken.
+     */
+    tags?: TagItem[];
+    /**
+     * Max number of tag chips rendered in the home "Tags" section before a "…"
+     * overflow indicator is shown. The full set stays reachable via the
+     * "see all tags" link. @default 30
+     */
+    tagLimit?: number;
     /**
      * Opt the home page into the **wide** content layout (full-viewport
      * category grid instead of the standard capped reading column). Threaded to