@takazudo/zudo-doc 2.5.1 → 3.1.0

package/dist/color-scheme-utils.js

@@ -1,27 +1,58 @@
-const SEMANTIC_DEFAULTS = {
-  surface: 0,
-  muted: 8,
-  accent: 5,
-  accentHover: 14,
-  codeBg: 10,
-  codeFg: 11,
-  success: 2,
-  danger: 1,
-  warning: 3,
-  info: 4,
-  mermaidNodeBg: 9,
-  mermaidText: 11,
-  mermaidLine: 8,
-  mermaidLabelBg: 10,
-  mermaidNoteBg: 0,
-  chatUserBg: 5,
-  chatUserText: 9,
-  chatAssistantBg: 9,
-  chatAssistantText: 11,
-  imageOverlayBg: 0,
-  imageOverlayFg: 11,
-  matchedKeywordBg: 3,
-  matchedKeywordFg: 15
+const STATE_ROLES = ["danger", "success", "warning", "info"];
+const SEMANTIC_KEYS = [
+  "surface",
+  "muted",
+  "accent",
+  "accentHover",
+  "codeBg",
+  "codeFg",
+  "success",
+  "danger",
+  "warning",
+  "info",
+  "mermaidNodeBg",
+  "mermaidText",
+  "mermaidLine",
+  "mermaidLabelBg",
+  "mermaidNoteBg",
+  "chatUserBg",
+  "chatUserText",
+  "chatAssistantBg",
+  "chatAssistantText",
+  "imageOverlayBg",
+  "imageOverlayFg",
+  "matchedKeywordBg",
+  "matchedKeywordFg"
+];
+const SEMANTIC_RAMP_DEFAULTS = {
+  // Re-pointed for the 5-base / 3-accent minimized ramp (#2602); mirrors the
+  // Default Dark reference wiring (surface/chatAssistantBg/imageOverlayBg merged
+  // onto bg=b4). Every index is < 5 (base) / < 3 (accent).
+  surface: { base: 4 },
+  muted: { base: 1 },
+  accent: { accent: 1 },
+  accentHover: { accent: 0 },
+  codeBg: { base: 3 },
+  codeFg: { base: 0 },
+  success: { state: "success" },
+  danger: { state: "danger" },
+  warning: { state: "warning" },
+  info: { state: "info" },
+  mermaidNodeBg: { base: 3 },
+  mermaidText: { base: 0 },
+  mermaidLine: { base: 1 },
+  mermaidLabelBg: { base: 3 },
+  mermaidNoteBg: { base: 2 },
+  chatUserBg: { accent: 1 },
+  chatUserText: { base: 4 },
+  chatAssistantBg: { base: 4 },
+  chatAssistantText: { base: 0 },
+  imageOverlayBg: { base: 4 },
+  imageOverlayFg: { base: 0 },
+  // Search-result <mark> highlight — amber fill with dark text (the classic
+  // highlighter look, matching the shipped schemes). Kept as raw OKLCH literals.
+  matchedKeywordBg: "oklch(0.700 0.158 62)",
+  matchedKeywordFg: "oklch(0.300 0.003 65)"
 };
 const SEMANTIC_CSS_NAMES = {
   surface: "--zd-surface",
@@ -48,74 +79,106 @@ const SEMANTIC_CSS_NAMES = {
   matchedKeywordBg: "--zd-matched-keyword-bg",
   matchedKeywordFg: "--zd-matched-keyword-fg"
 };
-function resolveColor(value, palette, fallback) {
-  if (value === void 0) return fallback;
-  if (typeof value === "number") return palette[value] ?? fallback;
-  return value;
+function resolveRampRef(ref, ramps) {
+  if (typeof ref === "string") return ref;
+  if ("base" in ref) {
+    const color = ramps.base[ref.base];
+    if (color === void 0) {
+      throw new RangeError(`RampRef {base:${ref.base}} out of range (base ramp has ${ramps.base.length} stops)`);
+    }
+    return color;
+  }
+  if ("accent" in ref) {
+    const color = ramps.accent[ref.accent];
+    if (color === void 0) {
+      throw new RangeError(`RampRef {accent:${ref.accent}} out of range (accent ramp has ${ramps.accent.length} stops)`);
+    }
+    return color;
+  }
+  return ramps.state[ref.state];
 }
 function resolveSemanticColors(scheme) {
-  const p = scheme.palette;
-  return {
-    surface: resolveColor(scheme.semantic?.surface, p, p[0]),
-    muted: resolveColor(scheme.semantic?.muted, p, p[8]),
-    accent: resolveColor(scheme.semantic?.accent, p, p[5]),
-    accentHover: resolveColor(scheme.semantic?.accentHover, p, p[14]),
-    codeBg: resolveColor(scheme.semantic?.codeBg, p, p[10]),
-    codeFg: resolveColor(scheme.semantic?.codeFg, p, p[11]),
-    success: resolveColor(scheme.semantic?.success, p, p[2]),
-    danger: resolveColor(scheme.semantic?.danger, p, p[1]),
-    warning: resolveColor(scheme.semantic?.warning, p, p[3]),
-    info: resolveColor(scheme.semantic?.info, p, p[4]),
-    mermaidNodeBg: resolveColor(scheme.semantic?.mermaidNodeBg, p, p[9]),
-    mermaidText: resolveColor(scheme.semantic?.mermaidText, p, p[11]),
-    mermaidLine: resolveColor(scheme.semantic?.mermaidLine, p, p[8]),
-    mermaidLabelBg: resolveColor(scheme.semantic?.mermaidLabelBg, p, p[10]),
-    mermaidNoteBg: resolveColor(scheme.semantic?.mermaidNoteBg, p, p[0]),
-    chatUserBg: resolveColor(scheme.semantic?.chatUserBg, p, p[5]),
-    chatUserText: resolveColor(scheme.semantic?.chatUserText, p, p[9]),
-    chatAssistantBg: resolveColor(scheme.semantic?.chatAssistantBg, p, p[9]),
-    chatAssistantText: resolveColor(scheme.semantic?.chatAssistantText, p, p[11]),
-    imageOverlayBg: resolveColor(scheme.semantic?.imageOverlayBg, p, p[0]),
-    imageOverlayFg: resolveColor(scheme.semantic?.imageOverlayFg, p, p[11]),
-    matchedKeywordBg: resolveColor(scheme.semantic?.matchedKeywordBg, p, p[3]),
-    matchedKeywordFg: resolveColor(scheme.semantic?.matchedKeywordFg, p, p[15])
-  };
+  const { ramps, map } = scheme;
+  const out = {};
+  for (const key of SEMANTIC_KEYS) {
+    out[key] = resolveRampRef(map.semantic[key], ramps);
+  }
+  return out;
 }
-function schemeToCssPairs(scheme) {
-  const p = scheme.palette;
-  const sem = resolveSemanticColors(scheme);
-  return [
-    ["--zd-bg", resolveColor(scheme.background, p, p[0])],
-    ["--zd-fg", resolveColor(scheme.foreground, p, p[15])],
-    ["--zd-cursor", resolveColor(scheme.cursor, p, p[6])],
-    // intentionally inert/vestigial: exposed in the design-token panel but no CSS rule consumes it (no caret-color wiring); mirrors shikiTheme's status
-    ["--zd-sel-bg", resolveColor(scheme.selectionBg, p, resolveColor(scheme.background, p, p[0]))],
-    ["--zd-sel-fg", resolveColor(scheme.selectionFg, p, resolveColor(scheme.foreground, p, p[15]))],
-    ...p.map((color, i) => [`--zd-${i}`, color]),
-    ["--zd-surface", sem.surface],
-    ["--zd-muted", sem.muted],
-    ["--zd-accent", sem.accent],
-    ["--zd-accent-hover", sem.accentHover],
-    ["--zd-code-bg", sem.codeBg],
-    ["--zd-code-fg", sem.codeFg],
-    ["--zd-success", sem.success],
-    ["--zd-danger", sem.danger],
-    ["--zd-warning", sem.warning],
-    ["--zd-info", sem.info],
-    ["--zd-mermaid-node-bg", sem.mermaidNodeBg],
-    ["--zd-mermaid-text", sem.mermaidText],
-    ["--zd-mermaid-line", sem.mermaidLine],
-    ["--zd-mermaid-label-bg", sem.mermaidLabelBg],
-    ["--zd-mermaid-note-bg", sem.mermaidNoteBg],
-    ["--zd-chat-user-bg", sem.chatUserBg],
-    ["--zd-chat-user-text", sem.chatUserText],
-    ["--zd-chat-assistant-bg", sem.chatAssistantBg],
-    ["--zd-chat-assistant-text", sem.chatAssistantText],
-    ["--zd-image-overlay-bg", sem.imageOverlayBg],
-    ["--zd-image-overlay-fg", sem.imageOverlayFg],
-    ["--zd-matched-keyword-bg", sem.matchedKeywordBg],
-    ["--zd-matched-keyword-fg", sem.matchedKeywordFg]
+function rampRefToPanelDefault(ref) {
+  if (typeof ref === "string") return ref;
+  if ("base" in ref) return `base:base-${ref.base}`;
+  if ("accent" in ref) return `accent:accent-${ref.accent}`;
+  return `state:state-${ref.state}`;
+}
+function buildSemanticTierItems(scheme) {
+  const { map } = scheme;
+  const items = [
+    {
+      id: "bg",
+      cssVar: "--zd-bg",
+      label: "bg",
+      default: rampRefToPanelDefault(map.bg),
+      type: { kind: "color", format: "oklch" }
+    },
+    {
+      id: "fg",
+      cssVar: "--zd-fg",
+      label: "fg",
+      default: rampRefToPanelDefault(map.fg),
+      type: { kind: "color", format: "oklch" }
+    },
+    {
+      id: "selection-bg",
+      cssVar: "--zd-selection-bg",
+      label: "selection-bg",
+      default: rampRefToPanelDefault(map.selectionBg),
+      type: { kind: "color", format: "oklch" }
+    },
+    {
+      id: "selection-fg",
+      cssVar: "--zd-selection-fg",
+      label: "selection-fg",
+      default: rampRefToPanelDefault(map.selectionFg),
+      type: { kind: "color", format: "oklch" }
+    }
   ];
+  for (const key of SEMANTIC_KEYS) {
+    items.push({
+      id: key,
+      cssVar: SEMANTIC_CSS_NAMES[key],
+      label: key,
+      default: rampRefToPanelDefault(map.semantic[key]),
+      type: { kind: "color", format: "oklch" }
+    });
+  }
+  return items;
+}
+function schemeToCssPairs(scheme, scope = "all") {
+  const { ramps, map } = scheme;
+  const pairs = [];
+  if (scope === "all" || scope === "roles") {
+    pairs.push(
+      ["--zd-bg", resolveRampRef(map.bg, ramps)],
+      ["--zd-fg", resolveRampRef(map.fg, ramps)],
+      ["--zd-selection-bg", resolveRampRef(map.selectionBg, ramps)],
+      ["--zd-selection-fg", resolveRampRef(map.selectionFg, ramps)]
+    );
+  }
+  if (scope === "all" || scope === "palette") {
+    ramps.base.forEach((color, i) => pairs.push([`--palette-base-${i}`, color]));
+    ramps.accent.forEach((color, i) => pairs.push([`--palette-accent-${i}`, color]));
+    for (const role of STATE_ROLES) {
+      pairs.push([`--palette-state-${role}`, ramps.state[role]]);
+    }
+  }
+  if (scope === "all" || scope === "roles") {
+    const sem = resolveSemanticColors(scheme);
+    for (const key of SEMANTIC_KEYS) {
+      pairs.push([SEMANTIC_CSS_NAMES[key], sem[key]]);
+    }
+  }
+  return pairs;
 }
 function generateCssCustomProperties(scheme) {
   const pairs = schemeToCssPairs(scheme);
@@ -123,15 +186,19 @@ function generateCssCustomProperties(scheme) {
   return lines.join("\n");
 }
 function generateLightDarkCssProperties(light, dark) {
-  const lightPairs = schemeToCssPairs(light);
-  const darkPairs = schemeToCssPairs(dark);
-  if (lightPairs.length !== darkPairs.length) {
-    throw new Error(`Light scheme has ${lightPairs.length} properties but dark scheme has ${darkPairs.length}`);
+  const palettePairs = schemeToCssPairs(light, "palette");
+  const lightRoles = schemeToCssPairs(light, "roles");
+  const darkRoles = schemeToCssPairs(dark, "roles");
+  if (lightRoles.length !== darkRoles.length) {
+    throw new Error(`Light scheme has ${lightRoles.length} role properties but dark scheme has ${darkRoles.length}`);
   }
   const lines = [":root {", "  color-scheme: light dark;"];
-  for (let i = 0; i < lightPairs.length; i++) {
-    const lightPair = lightPairs[i];
-    const darkPair = darkPairs[i];
+  for (const [prop, value] of palettePairs) {
+    lines.push(`  ${prop}: ${value};`);
+  }
+  for (let i = 0; i < lightRoles.length; i++) {
+    const lightPair = lightRoles[i];
+    const darkPair = darkRoles[i];
     if (!lightPair || !darkPair) continue;
     const [prop, lightVal] = lightPair;
     const darkVal = darkPair[1];
@@ -142,10 +209,14 @@ function generateLightDarkCssProperties(light, dark) {
 }
 export {
   SEMANTIC_CSS_NAMES,
-  SEMANTIC_DEFAULTS,
+  SEMANTIC_KEYS,
+  SEMANTIC_RAMP_DEFAULTS,
+  STATE_ROLES,
+  buildSemanticTierItems,
   generateCssCustomProperties,
   generateLightDarkCssProperties,
-  resolveColor,
+  rampRefToPanelDefault,
+  resolveRampRef,
   resolveSemanticColors,
   schemeToCssPairs
 };

package/dist/content.css

@@ -28,7 +28,7 @@
  * 2. DESIGN TOKENS — the consumer's `@theme` MUST define every custom property
  *    consumed below:
  *      --color-{fg,bg,muted,accent,accent-hover,code-bg,code-fg,info,success,
- *               warning,danger,p5}
+ *               warning,danger}
  *      --spacing-{vsp-2xs,vsp-xs,vsp-sm,vsp-md,vsp-lg,vsp-xl,vsp-2xl,
  *                 hsp-2xs,hsp-xs,hsp-sm,hsp-md,hsp-lg,hsp-xl}
  *      --text-{body,small}   --font-mono   --font-weight-{medium,semibold}
@@ -405,16 +405,16 @@
   content: "🚨";
 }
 
-/* github-alerts [!IMPORTANT] → magenta/accent-adjacent (p5 = magenta palette slot) */
+/* github-alerts [!IMPORTANT] → shares the orange accent (--color-accent → --zd-accent → accent ramp); ❗ icon differentiates it from other admonitions */
 [data-admonition="important"],
 .admonition-important {
-  border-left-color: var(--color-p5);
-  background-color: color-mix(in srgb, var(--color-p5) 12%, var(--color-bg));
+  border-left-color: var(--color-accent);
+  background-color: color-mix(in srgb, var(--color-accent) 12%, var(--color-bg));
 }
 
 [data-admonition="important"] .admonition-title,
 .admonition-important .admonition-title {
-  color: var(--color-p5);
+  color: var(--color-accent);
 }
 
 [data-admonition="important"] .admonition-title::before,

package/dist/design-token-panel-bootstrap.d.ts

@@ -1,20 +1,28 @@
 /**
  * Design-token panel (zdtp) WIRING MECHANISM.
  *
- * A side-effect module that calls `configurePanel(panelConfig)` and wires
- * zdtp's lifecycle hooks to zfb's navigation events via
- * `setLifecycleAdapter()`. Projects import this with their own
- * `designTokenPanelConfig` object — the DATA stays project-side.
+ * A side-effect module that configures zdtp's panel and wires its lifecycle
+ * hooks to zfb's navigation events via `setLifecycleAdapter()`. Projects import
+ * this with their own PanelConfig DATA — which stays project-side.
  *
- * Usage (project-side `src/lib/design-token-panel-bootstrap.ts`):
+ * Two calling shapes (both supported):
  *
+ *   // Mode-scoped builder (showcase host) — rebuilds the panel per light/dark
+ *   // mode on every `color-scheme-changed` toggle:
  *   import { bootstrapDesignTokenPanel } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
+ *   import { buildDesignTokenPanelConfig } from "@/config/design-token-panel-config";
+ *   bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);
+ *
+ *   // Plain config (back-compat — generated projects on the old shape):
  *   import { designTokenPanelConfig } from "@/config/design-token-panel-config";
  *   bootstrapDesignTokenPanel(designTokenPanelConfig);
  *
+ * A plain-config caller gets NO toggle listener (a static config has nothing to
+ * rebuild), so existing generated projects keep working with zero changes.
+ *
  * Moved from the host's `src/lib/design-token-panel-bootstrap.ts` as part of
- * the package-first migration (S9a zudolab/zudo-doc#2333). The PanelConfig
- * DATA stays project-side.
+ * the package-first migration (S9a zudolab/zudo-doc#2333); mode-scoped rebuild
+ * wiring added in zudolab/zudo-doc#2610.
  *
  * CSS is pulled via `@import "@takazudo/zdtp/styles.css"` in the project's
  * `src/styles/global.css` so the panel chrome lands in the main page CSS
@@ -23,16 +31,29 @@
  * required pull point. See @takazudo/zdtp PORTABLE-CONTRACT.md §7.
  */
 import { type PanelConfig } from "@takazudo/zdtp";
+/** Active color-scheme mode, read from `<html data-theme>`. */
+type ColorSchemeMode = "light" | "dark";
 /**
- * Bootstrap zdtp for a project. Calls `configurePanel(panelConfig)`,
- * drains any pre-hydration click queue, and wires the zdtp lifecycle
- * adapter to zfb's navigation events so persisted token overrides are
- * re-applied on every soft navigation.
+ * A per-mode PanelConfig factory. Supplied by hosts that want the panel's
+ * defaults to follow the live light/dark mode (see `buildDesignTokenPanelConfig`
+ * in the host's `design-token-panel-config.ts`).
+ */
+export type PanelConfigBuilder = (mode: ColorSchemeMode) => PanelConfig;
+/**
+ * Bootstrap zdtp for a project. Configures the panel, drains any pre-hydration
+ * click queue, and wires the zdtp lifecycle adapter to zfb's navigation events
+ * so persisted token overrides re-apply on every soft navigation.
+ *
+ * When passed a `PanelConfigBuilder`, also wires a `color-scheme-changed`
+ * listener that rebuilds the panel per light/dark mode (see the toggle sequence
+ * below). When passed a plain `PanelConfig`, no toggle listener is registered.
  *
- * Call this once, as a side-effect import from the project's island
- * wrapper (`src/components/design-token-panel-bootstrap.tsx`).
+ * Call this once, as a side-effect import from the project's island wrapper
+ * (`src/components/design-token-panel-bootstrap.tsx`).
  *
- * @param panelConfig - The project's `PanelConfig` object (data stays
- *   project-side in `src/config/design-token-panel-config.ts`).
+ * @param configOrBuilder - The project's `PanelConfig`, or a `(mode) =>
+ *   PanelConfig` builder for mode-scoped rebuilds. DATA stays project-side in
+ *   `src/config/design-token-panel-config.ts`.
  */
-export declare function bootstrapDesignTokenPanel(panelConfig: PanelConfig): void;
+export declare function bootstrapDesignTokenPanel(configOrBuilder: PanelConfig | PanelConfigBuilder): void;
+export {};

package/dist/design-token-panel-bootstrap.js

@@ -1,28 +1,56 @@
-import { configurePanel, setLifecycleAdapter } from "@takazudo/zdtp";
+import {
+  configurePanel,
+  setLifecycleAdapter,
+  showDesignTokenPanel
+} from "@takazudo/zdtp";
 import {
   BEFORE_NAVIGATE_EVENT,
   AFTER_NAVIGATE_EVENT
 } from "./transitions/page-events.js";
-function bootstrapDesignTokenPanel(panelConfig) {
-  configurePanel(panelConfig);
-  if (typeof window !== "undefined") {
-    window.__zdtpReadyClicks?.();
+const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
+function openStateKey(instancePrefix) {
+  return `${instancePrefix}-open`;
+}
+function readMode() {
+  return document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light";
+}
+function bootstrapDesignTokenPanel(configOrBuilder) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
   }
-  if (typeof document !== "undefined") {
-    const adapter = {
-      onBeforeSwap(cb) {
-        const handler = () => cb();
-        document.addEventListener(BEFORE_NAVIGATE_EVENT, handler);
-        return () => document.removeEventListener(BEFORE_NAVIGATE_EVENT, handler);
-      },
-      onPageLoad(cb) {
-        const handler = () => cb();
-        document.addEventListener(AFTER_NAVIGATE_EVENT, handler);
-        return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handler);
-      }
-    };
-    setLifecycleAdapter(adapter);
+  const isBuilder = typeof configOrBuilder === "function";
+  const builder = isBuilder ? configOrBuilder : () => configOrBuilder;
+  let handle = configurePanel(builder(readMode()));
+  if (isBuilder) {
+    let pendingMode = readMode();
+    let timer = null;
+    window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, () => {
+      pendingMode = readMode();
+      if (timer !== null) return;
+      timer = setTimeout(() => {
+        timer = null;
+        const mode = pendingMode;
+        const wasOpen = localStorage.getItem(openStateKey(handle.instanceId)) === "1";
+        handle.destroy();
+        handle = configurePanel(builder(mode));
+        if (wasOpen) showDesignTokenPanel();
+      }, 0);
+    });
   }
+  window.__zdtpReadyClicks?.();
+  const adapter = {
+    onBeforeSwap(cb) {
+      const handler = () => cb();
+      document.addEventListener(BEFORE_NAVIGATE_EVENT, handler);
+      return () => document.removeEventListener(BEFORE_NAVIGATE_EVENT, handler);
+    },
+    onPageLoad(cb) {
+      const handler = () => cb();
+      document.addEventListener(AFTER_NAVIGATE_EVENT, handler);
+      return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handler);
+    }
+  };
+  setLifecycleAdapter(adapter);
 }
 export {
   bootstrapDesignTokenPanel

package/dist/doc-page-renderer/index.d.ts

@@ -82,6 +82,7 @@ export interface DocPageRendererDeps {
         sidebarPersistKey: string | undefined;
         hideSidebar?: boolean;
         hideToc?: boolean;
+        contentWide?: boolean;
         currentPath: string;
         currentVersion?: string;
         versionSwitcher: JSX.Element | undefined;

package/dist/doc-page-renderer/index.js

@@ -47,6 +47,7 @@ function createRenderDocPage(ctx) {
     const standalone = entryData?.standalone;
     const hideSidebar = entryData ? entryData.hide_sidebar || standalone : void 0;
     const hideToc = entryData ? entryData.hide_toc || standalone : void 0;
+    const contentWide = entryData ? entryData.wide : void 0;
     const sidebarPersistKey = hideSidebar ? void 0 : `sidebar-${locale}-${navSection ?? "default"}`;
     const ContentComponent = props.kind === "entry" ? props.entry.Content : null;
     return /* @__PURE__ */ jsx(
@@ -66,6 +67,7 @@ function createRenderDocPage(ctx) {
         sidebarPersistKey,
         hideSidebar,
         hideToc,
+        contentWide,
         currentPath,
         currentVersion: version?.slug,
         versionSwitcher: buildInlineVersionSwitcher(slug, locale, version?.slug),

package/dist/doc-page-shell/index.d.ts

@@ -52,6 +52,8 @@ export interface DocPageShellProps {
     hideSidebar?: boolean;
     /** Whether to hide the TOC (entry frontmatter). */
     hideToc?: boolean;
+    /** Whether to widen the content band to the wide layout (entry frontmatter `wide`). */
+    contentWide?: boolean;
     /** Path of THIS page used by Header/Sidebar to mark the active item. */
     currentPath: string;
     /** Version slug for Header/Sidebar active-state, or undefined on latest routes. */

package/dist/doc-page-shell/index.js

@@ -50,6 +50,7 @@ function createDocPageShell(ctx) {
       sidebarPersistKey,
       hideSidebar,
       hideToc,
+      contentWide,
       currentPath,
       currentVersion,
       versionSwitcher,
@@ -86,6 +87,7 @@ function createDocPageShell(ctx) {
         noindex: settings.noindex,
         hideSidebar,
         hideToc,
+        contentWide,
         headings,
         canonical,
         sidebarPersistKey,

package/dist/doclayout/doc-layout.d.ts

@@ -85,6 +85,15 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
     toc?: ComponentChildren;
     /** Hide the TOC (both desktop and mobile) regardless of slot value. */
     hideToc?: boolean;
+    /**
+     * Opt the content band into the **wide** layout. Sets `data-zd-wide` on
+     * `.zd-doc-content-band`, letting the reading column fill most of the
+     * viewport instead of the standard capped width (see the
+     * `.zd-doc-content-band[data-zd-wide]` rule in `features.css`). Mirrors the
+     * `wide` page frontmatter flag; also passed directly by route components
+     * (home page, etc.) that want a full-width grid. Defaults to `false`.
+     */
+    contentWide?: boolean;
     /** Optional footer rendered below the content. */
     footer?: ComponentChildren;
     /**

package/dist/doclayout/doc-layout.js

@@ -22,6 +22,7 @@ function DocLayout(props) {
     afterContent,
     toc,
     hideToc = false,
+    contentWide = false,
     footer,
     bodyEndComponents,
     bodyEndScripts,
@@ -72,6 +73,7 @@ function DocLayout(props) {
               {
                 class: "zd-doc-content-band flex w-full gap-[clamp(1.5rem,3vw,4rem)]",
                 ...!showSidebar ? { "data-zd-nosidebar": "" } : {},
+                ...contentWide ? { "data-zd-wide": "" } : {},
                 children: [
                   /* @__PURE__ */ jsxs("main", { class: "flex-1 min-w-0 px-hsp-xl py-vsp-xl lg:px-hsp-2xl lg:py-vsp-2xl", children: [
                     breadcrumb,

package/dist/features.css

@@ -335,6 +335,25 @@ pre[class^="syntect-"] .line .highlighted-word {
   max-width: 80rem;
 }
 
+/* Wide band — opt-in full-width content layout (the `wide` frontmatter flag or
+ * the `contentWide` DocLayout prop set `data-zd-wide` on the band). Widens the
+ * reading column past the standard cap so grid-heavy / dashboard pages (e.g. the
+ * site home page) fill most of the viewport. Must beat BOTH capped variants:
+ *   • the static hide_sidebar cap `.zd-doc-content-band[data-zd-nosidebar]`
+ *     (specificity 0,2,0) — the first selector below is also 0,2,0 and wins by
+ *     source order (it is placed after that rule);
+ *   • the JS-toggle cap `html[data-sidebar-hidden] .zd-doc-content-band`
+ *     (specificity 0,2,1) — the second selector below is 0,3,1 and wins on
+ *     specificity.
+ * The literal clamp mirrors the established band-width pattern (see the
+ * `[data-zd-nosidebar]` 80rem literal and the `--zdc-content-max-width`
+ * default): fills up to ~92.5vw, floored at 50rem, capped at 120rem so
+ * ultra-wide monitors stay readable. Unlayered, so it beats Tailwind utilities. */
+.zd-doc-content-band[data-zd-wide],
+html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
+  max-width: clamp(50rem, 92.5vw, 120rem);
+}
+
 /* Sidebar toggle button — left position uses CSS variable, needs global rule */
 @media (min-width: 1024px) {
   .zd-desktop-sidebar-toggle {

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

@@ -33,6 +33,14 @@ export interface HomePageViewProps {
     /** Unique tag count for the current locale — gates the "all tags" section
      *  together with `settings.docTags`. */
     tagCount: number;
+    /**
+     * Opt the home page into the **wide** content layout (full-viewport
+     * category grid instead of the standard capped reading column). Threaded to
+     * the underlying `DocLayoutWithDefaults` as `contentWide`. Defaults to
+     * `false` so downstream projects keep the narrower grid unless they opt in;
+     * this showcase passes `wide` from `pages/index.tsx`.
+     */
+    wide?: boolean;
 }
 /**
  * Create a `HomePageView` component from the unified {@link ChromeContext}

package/dist/home-page/index.js

@@ -25,7 +25,8 @@ function createHomePageView(ctx) {
     extras,
     tree,
     categoryOrder,
-    tagCount
+    tagCount,
+    wide
   }) {
     const prefix = locale === defaultLocale ? "" : `/${locale}`;
     const ctaNav = settings.headerNav[0] ?? null;
@@ -41,6 +42,7 @@ function createHomePageView(ctx) {
         noindex: settings.noindex,
         hideSidebar: true,
         hideToc: true,
+        contentWide: wide,
         sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
         headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase(`${prefix}/`) }),
         footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),

package/dist/integrations/changelog/emit.d.ts

@@ -0,0 +1,2 @@
+import type { ChangelogEmitOptions, ChangelogEmitResult } from "./types.js";
+export declare function emitChangelogs(options: ChangelogEmitOptions): ChangelogEmitResult;