@takazudo/zudo-doc 5.9.0 → 5.10.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.10.0] - 2026-08-22
+
+### Features
+
+- Added first-class multi-package changelogs, including nested package navigation, per-package release pages, bilingual guidance, and the `create-zudo-doc --changelog-packages` option. (`91f179c8`, `302eac4f`)
+- Upgraded the zfb package family to 2.9.0 and moved HtmlPreview to the public highlight-only WASM runtime, reducing the emitted WASM payload by about 55%. (`52291ec5`, `2911a651`)
+
+### Bug Fixes
+
+- Hardened nested changelog navigation and added diagnostics when an emitter targets a multi-package landing directory instead of a package release directory. (`302eac4f`, `c4266e4a`)
+- Normalized non-pill sidebar current rows in Drift, Hearth, Sakura, Scandi, and Timberline while preserving each pack's nested active treatment. (`7c4e0444`)
+
+### Other Changes
+
+- Added bilingual documentation, publish-contract coverage, and positive browser detectors for the highlight-only runtime. (`b97ef30c`, `92269d49`)
+- Added package-test hook headroom for concurrent CI load without changing subprocess deadlines. (`4d1417a9`)
+
 ## [5.9.0] - 2026-08-20
 
 ### Features

package/README.md

@@ -59,7 +59,7 @@ const breadcrumbs = buildBreadcrumbs(tree, "guides/color", homeHref);
 
 ## Optional peer dependency: `@takazudo/zfb-md-wasm`
 
-`./html-preview-wrapper`'s `<HighlightedCode>` lazily imports the package root and calls `highlightCode()` for client-side semantic syntax highlighting. `@takazudo/zfb-md-wasm` is declared as an **optional peerDependency** — install the same prerelease version as the rest of your zfb packages if you use that subpath:
+`./html-preview-wrapper`'s `<HighlightedCode>` lazily imports the public `@takazudo/zfb-md-wasm/highlight` subpath and calls `highlightCode()` for client-side semantic syntax highlighting. `@takazudo/zfb-md-wasm` is declared as an **optional peerDependency** — install the same version as the rest of your zfb packages if you use that subpath:
 
 ```sh
 pnpm add @takazudo/zfb-md-wasm

package/dist/chrome/derive.d.ts

@@ -152,7 +152,7 @@ export declare function deriveInlineVersionSwitcher(ctx: ChromeContext, getUnava
  * happens one layer up in `createMdxComponents()`, after the wrapper choice.
  */
 export declare function deriveMdxComponents(ctx: ChromeContext): {
-    createMdxComponentsBound: (lang?: string, currentVersion?: string) => Record<string, unknown>;
+    createMdxComponentsBound: (lang?: string, currentVersion?: string, currentSlug?: string) => Record<string, unknown>;
     SiteTreeNavWrapper: FactoryComponent;
 };
 export type { Settings };

package/dist/chrome/derive.js

@@ -14,6 +14,7 @@ import { DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.
 import { SearchWidget } from "../search-widget/index.js";
 import { createMdxComponents } from "../mdx-components/index.js";
 import { createCategoryNavWrapper } from "../category-nav/index.js";
+import { createNoteTrayIndexWrapper } from "../note-tray-index/index.js";
 import { createCategoryTreeNavWrapper } from "../category-tree-nav/index.js";
 import { createSiteTreeNavWrapper } from "../site-tree-nav/index.js";
 import { Details } from "../details/index.js";
@@ -271,6 +272,25 @@ function deriveMdxComponents(ctx) {
     getCategoryOrder: ctx.getCategoryOrder,
     versionedDocsUrl: ctx.versionedDocsUrl
   });
+  const NoteTrayIndexWrapper = createNoteTrayIndexWrapper({
+    defaultLocale: ctx.defaultLocale,
+    docTags: ctx.settings.docTags,
+    resolveNavSource: ctx.resolveNavSource,
+    buildNavTree: ((docs, locale, categoryMeta) => ctx.buildNavTree(
+      docs,
+      locale,
+      categoryMeta,
+      (slug, loc) => ctx.docsUrl(slug, loc)
+    )),
+    findNode: ctx.findNode,
+    toRouteSlug: ctx.toRouteSlug,
+    resolveTag: (raw) => ctx.resolveTagBound(raw).canonical,
+    tagHref: (tag, locale) => ctx.withBase(
+      locale === ctx.defaultLocale ? `/docs/tags/${encodeURIComponent(tag)}` : `/${locale}/docs/tags/${encodeURIComponent(tag)}`
+    ),
+    t: (key, locale) => ctx.t(key, locale),
+    versionedDocsUrl: ctx.versionedDocsUrl
+  });
   function HtmlPreviewBound(props) {
     return HtmlPreviewWrapper({
       globalConfig: ctx.settings.htmlPreview ?? null,
@@ -286,15 +306,17 @@ function deriveMdxComponents(ctx) {
     PresetGenerator: (_props) => null
   };
   const mdxExtras = { ...mdxExtrasDefault, ...ctx.hostBindings.mdxExtras ?? {} };
-  function createMdxComponentsBound(lang = ctx.defaultLocale, currentVersion) {
+  function createMdxComponentsBound(lang = ctx.defaultLocale, currentVersion, currentSlug = "") {
     return createMdxComponents({
       settings: ctx.settings,
       locale: lang,
       currentVersion,
+      currentSlug,
       navData: {
         CategoryNav: CategoryNavWrapper,
         CategoryTreeNav: CategoryTreeNavWrapper,
-        SiteTreeNav: SiteTreeNavWrapper
+        SiteTreeNav: SiteTreeNavWrapper,
+        NoteTrayIndex: NoteTrayIndexWrapper
       },
       // Package-owned content components wired here so an INJECTED docs route
       // renders MDX using these tags without the "MDX requires '<X>' to be

package/dist/config-assertions/index.d.ts

@@ -1,4 +1,17 @@
 import type { FaviconConfig } from "../settings.js";
+/** Structural subset of a header dropdown read by the category-match guard. */
+export interface AmbiguousDropdownCategoryMatchItem {
+    label?: string;
+    categoryMatch?: string;
+    children?: Array<{
+        label?: string;
+        categoryMatch?: string;
+    }>;
+}
+/** Logger surface accepted by the non-throwing header-nav diagnostic. */
+export interface ConfigAssertionLogger {
+    warn(message: string): void;
+}
 /** Structural subset of `Settings` {@link assertNoEmptyStringFaviconOrLogo} reads. */
 export interface EmptyStringFaviconOrLogoSubject {
     logo?: string | false;
@@ -29,3 +42,20 @@ export interface EmptyStringFaviconOrLogoSubject {
  * object is not an empty string).
  */
 export declare function assertNoEmptyStringFaviconOrLogo(settings: EmptyStringFaviconOrLogoSubject): void;
+/**
+ * Warn about `categoryMatch` values that cannot express the intended
+ * dropdown grouping.
+ *
+ * A category matcher is compared with the first slug segment by the nav-scope
+ * resolver, so a value containing `/` never matches. Likewise, duplicate
+ * child values make every matching child category-active. Children grouped
+ * under one top-level directory should omit `categoryMatch` and rely on the
+ * deepest matching child path; Learn-style children should use distinct
+ * top-level values.
+ *
+ * This is intentionally a diagnostic rather than a config assertion: malformed
+ * navigation should remain buildable, and each offending value is reported at
+ * most once per parent dropdown. The `"!"` matcher is the intentional default
+ * bucket and is excluded from both checks.
+ */
+export declare function warnAmbiguousDropdownCategoryMatch(headerNav: readonly AmbiguousDropdownCategoryMatchItem[] | undefined, logger?: ConfigAssertionLogger): void;

package/dist/config-assertions/index.js

@@ -19,6 +19,46 @@ function assertNoEmptyStringFaviconOrLogo(settings) {
     }
   }
 }
+function warnAmbiguousDropdownCategoryMatch(headerNav, logger = console) {
+  if (!headerNav) return;
+  for (const item of headerNav) {
+    const children = item.children;
+    if (!children || children.length === 0) continue;
+    const childCounts = /* @__PURE__ */ new Map();
+    for (const child of children) {
+      const value = child.categoryMatch;
+      if (value == null || value === "!") continue;
+      childCounts.set(value, (childCounts.get(value) ?? 0) + 1);
+    }
+    const offendingValues = [];
+    const addOffendingValue = (value) => {
+      if (value == null || value === "!" || offendingValues.includes(value)) return;
+      offendingValues.push(value);
+    };
+    if (item.categoryMatch?.includes("/")) {
+      addOffendingValue(item.categoryMatch);
+    }
+    for (const child of children) {
+      if (child.categoryMatch?.includes("/")) {
+        addOffendingValue(child.categoryMatch);
+      }
+    }
+    for (const [value, count] of childCounts) {
+      if (count >= 2) addOffendingValue(value);
+    }
+    for (const value of offendingValues) {
+      const reasons = [
+        ...value.includes("/") ? ["contains `/` and never matches a top-level slug"] : [],
+        ...(childCounts.get(value) ?? 0) >= 2 ? ["is shared by multiple children"] : []
+      ].join("; ");
+      const parentLabel = item.label ?? "(unnamed)";
+      logger.warn(
+        `zudo-doc: header dropdown "${parentLabel}" has categoryMatch "${value}" that ${reasons}. Children grouped under one top-level directory should omit categoryMatch (active state follows the deepest matching child path); Learn-style children should use distinct top-level values.`
+      );
+    }
+  }
+}
 export {
-  assertNoEmptyStringFaviconOrLogo
+  assertNoEmptyStringFaviconOrLogo,
+  warnAmbiguousDropdownCategoryMatch
 };

package/dist/doc-content-header/index.js

@@ -3,6 +3,7 @@ import { FrontmatterPreview } from "../metainfo/index.js";
 import { createDocMetainfoArea } from "../doc-metainfo-area/index.js";
 import { createDocTagsArea } from "../doc-tags-area/index.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
+import { formatDate } from "../format-date/index.js";
 function createDocContentHeader(ctx) {
   assertChromeContext(ctx, "createDocContentHeader");
   const t = ctx.t;
@@ -27,6 +28,11 @@ function createDocContentHeader(ctx) {
         isFallback,
         version
       }),
+      (entry.data.date || entry.data.updated) && /* @__PURE__ */ jsxs("p", { class: "text-caption text-muted mb-vsp-md", "data-doc-date": true, children: [
+        entry.data.date ? formatDate(entry.data.date, locale) : null,
+        entry.data.date && entry.data.updated ? " \xB7 " : null,
+        entry.data.updated ? `${t("doc.updated", locale)} ${formatDate(entry.data.updated, locale)}` : null
+      ] }),
       !version && /* @__PURE__ */ jsx(DocMetainfoArea, { slug, locale, isFallback }),
       !version && /* @__PURE__ */ jsx(DocTagsArea, { slug, locale, tags: entry.data.tags }),
       isFallback && !entry.data.generated && /* @__PURE__ */ jsx(

package/dist/doc-metainfo-area/index.js

@@ -2,20 +2,7 @@ import { jsx } from "preact/jsx-runtime";
 import { DocMetainfo } from "../metainfo/index.js";
 import { toHistorySlug } from "../slug/index.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
-const LOCALE_TO_BCP47 = {
-  en: "en-US",
-  ja: "ja-JP",
-  de: "de-DE"
-};
-function formatDate(isoDate, locale) {
-  const d = new Date(isoDate);
-  if (isNaN(d.getTime())) return isoDate;
-  return d.toLocaleDateString(LOCALE_TO_BCP47[locale] ?? "en-US", {
-    year: "numeric",
-    month: "short",
-    day: "numeric"
-  });
-}
+import { formatDate } from "../format-date/index.js";
 function createDocMetainfoArea(ctx) {
   assertChromeContext(ctx, "createDocMetainfoArea");
   const settings = ctx.settings;

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

@@ -48,10 +48,10 @@ export interface DocPageRendererDeps {
      * Build locale-aware MDX components bag.
      * Host passes `createMdxComponents` (from `pages/_mdx-components.ts`).
      * `currentVersion` (#3218) threads the active `/v/{version}` slug into the
-     * nav-card wrappers (CategoryNav/CategoryTreeNav/SiteTreeNav) so their hrefs
-     * resolve within the version — undefined on latest/unversioned pages.
+     * nav wrappers so their data and hrefs resolve within the version. The
+     * current slug lets NoteTrayIndex infer its containing tray.
      */
-    createMdxComponents: (locale: string, currentVersion?: string) => Record<string, unknown>;
+    createMdxComponents: (locale: string, currentVersion: string | undefined, currentSlug: string) => Record<string, unknown>;
     /** Translate a UI string key for a locale. */
     t: (key: string, locale: string) => string;
     /**

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

@@ -35,7 +35,7 @@ function createRenderDocPage(ctx) {
     const slug = props.kind === "autoIndex" ? props.autoIndex.slug : props.entry.data.slug ?? toRouteSlug(props.entry.slug);
     const title = props.kind === "autoIndex" ? props.autoIndex.label : props.entry.data.title;
     const description = props.kind === "autoIndex" ? props.autoIndex.description : props.entry.data.description;
-    const components = createMdxComponents(locale, version?.slug);
+    const components = createMdxComponents(locale, version?.slug, slug);
     const autoIndexChildren = props.kind === "autoIndex" ? version ? props.autoIndex.children.filter((c) => c.hasPage || c.children.length > 0) : props.autoIndex.children.filter((c) => c.hasPage || c.children.length > 0).map((c) => ({
       ...c,
       href: c.href ?? docsUrl(c.slug, locale)

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

@@ -22,6 +22,12 @@ export interface DocPageNavNode {
     href?: string;
     hasPage: boolean;
     children: DocPageNavNode[];
+    shape?: "note-tray";
+    noteTrayDated?: boolean;
+    noteTraySidebar?: "index" | "year" | "month";
+    date?: string;
+    updated?: string;
+    rank?: number;
 }
 /** Slots and parameters that vary between the 4 doc routes. */
 export interface DocPageShellProps {

package/dist/doc-pager/index.d.ts

@@ -6,6 +6,12 @@ import type { Settings } from "../settings.js";
 interface PagerNode {
     href?: string;
     label: string;
+    shape?: "note-tray";
+    noteTrayDated?: boolean;
+    noteTraySidebar?: "index" | "year" | "month";
+    date?: string;
+    updated?: string;
+    rank?: number;
 }
 export interface DocPagerProps {
     /** Previous page node (null = no previous page → renders placeholder). */

package/dist/doc-pager/index.js

@@ -1,6 +1,7 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { ChevronLeft, ChevronRight } from "../icons/index.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
+import { formatDate } from "../format-date/index.js";
 function createDocPager(ctx) {
   assertChromeContext(ctx, "createDocPager");
   const t = ctx.t;
@@ -16,7 +17,8 @@ function createDocPager(ctx) {
               /* @__PURE__ */ jsx(ChevronLeft, { className: "h-[1.125rem] w-[1.125rem]" }),
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.previous", locale) })
             ] }),
-            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold underline group-hover:text-accent", children: prev.label })
+            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold underline group-hover:text-accent", children: prev.label }),
+            prev.date && /* @__PURE__ */ jsx("p", { class: "text-caption text-muted", children: formatDate(prev.date, locale) })
           ]
         }
       ) : /* @__PURE__ */ jsx("div", {}),
@@ -30,7 +32,8 @@ function createDocPager(ctx) {
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.next", locale) }),
               /* @__PURE__ */ jsx(ChevronRight, { className: "h-[1.125rem] w-[1.125rem]" })
             ] }),
-            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold underline group-hover:text-accent", children: next.label })
+            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold underline group-hover:text-accent", children: next.label }),
+            next.date && /* @__PURE__ */ jsx("p", { class: "text-caption text-muted", children: formatDate(next.date, locale) })
           ]
         }
       ) : /* @__PURE__ */ jsx("div", {})

package/dist/docs-schema/index.d.ts

@@ -58,6 +58,17 @@ export declare function buildDocsSchema(opts?: BuildDocsSchemaOptions): z.ZodObj
         asc: "asc";
         desc: "desc";
     }>>;
+    category_shape: z.ZodOptional<z.ZodEnum<{
+        "note-tray": "note-tray";
+    }>>;
+    note_tray_dated: z.ZodOptional<z.ZodBoolean>;
+    note_tray_sidebar: z.ZodOptional<z.ZodEnum<{
+        index: "index";
+        year: "year";
+        month: "month";
+    }>>;
+    date: z.ZodOptional<z.ZodString>;
+    updated: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 /**
  * TypeScript type inferred from the default docs frontmatter zod schema.

package/dist/docs-schema/index.js

@@ -35,7 +35,14 @@ function buildDocsSchema(opts) {
     // `category_sort_order` sets the child sort direction. Frontmatter wins
     // over the sidecar.
     category_no_page: z.boolean().optional(),
-    category_sort_order: z.enum(["asc", "desc"]).optional()
+    category_sort_order: z.enum(["asc", "desc"]).optional(),
+    category_shape: z.enum(["note-tray"]).optional(),
+    note_tray_dated: z.boolean().optional(),
+    note_tray_sidebar: z.enum(["index", "year", "month"]).optional(),
+    // Quote these values in YAML (for example, date: "2026-08-22") so
+    // parsers do not coerce them into Date objects before schema validation.
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    updated: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
   }).passthrough();
 }
 export {

package/dist/format-date/index.d.ts

@@ -0,0 +1,12 @@
+export interface IsoDateParts {
+    year: number;
+    month: number;
+    day: number;
+}
+export declare function parseIsoDate(iso: string): IsoDateParts | undefined;
+/** Format an ISO date for display while retaining the established locale map. */
+export declare function formatDate(iso: string, locale: string): string;
+/** Format a year/month label with the year first in every locale. */
+export declare function formatYearMonth(iso: string, locale: string): string;
+/** Return the stable numeric month/day portion of a calendar-valid ISO date. */
+export declare function formatMonthDay(iso: string): string;

package/dist/format-date/index.js

@@ -0,0 +1,64 @@
+const LOCALE_TO_BCP47 = {
+  en: "en-US",
+  ja: "ja-JP",
+  de: "de-DE"
+};
+function parseIsoDate(iso) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!match) return void 0;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = /* @__PURE__ */ new Date(0);
+  date.setUTCHours(0, 0, 0, 0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    return void 0;
+  }
+  return { year, month, day };
+}
+function toUtcDate(iso) {
+  const parts = parseIsoDate(iso);
+  if (parts) {
+    const date = /* @__PURE__ */ new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(parts.year, parts.month - 1, parts.day);
+    return date;
+  }
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(iso)) return void 0;
+  const timestamp = new Date(iso);
+  return Number.isNaN(timestamp.getTime()) ? void 0 : timestamp;
+}
+function formatDate(iso, locale) {
+  const date = toUtcDate(iso);
+  if (!date) return iso;
+  return new Intl.DateTimeFormat(LOCALE_TO_BCP47[locale] ?? "en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    timeZone: "UTC"
+  }).format(date);
+}
+function formatYearMonth(iso, locale) {
+  const date = toUtcDate(iso.length === 7 ? `${iso}-01` : iso);
+  if (!date) return iso;
+  const year = new Intl.DateTimeFormat(LOCALE_TO_BCP47[locale] ?? "en-US", {
+    year: "numeric",
+    timeZone: "UTC"
+  }).format(date);
+  const month = new Intl.DateTimeFormat(LOCALE_TO_BCP47[locale] ?? "en-US", {
+    month: "long",
+    timeZone: "UTC"
+  }).format(date);
+  return locale === "ja" ? `${year}${month}` : `${year} ${month}`;
+}
+function formatMonthDay(iso) {
+  const parts = parseIsoDate(iso);
+  return parts ? `${String(parts.month).padStart(2, "0")}-${String(parts.day).padStart(2, "0")}` : iso;
+}
+export {
+  formatDate,
+  formatMonthDay,
+  formatYearMonth,
+  parseIsoDate
+};

package/dist/frontmatter-preview-defaults/index.js

@@ -18,7 +18,12 @@ const defaultFrontmatterPreviewIgnoreKeys = [
   "slug",
   "generated",
   "category_no_page",
-  "category_sort_order"
+  "category_sort_order",
+  "category_shape",
+  "note_tray_dated",
+  "note_tray_sidebar",
+  "date",
+  "updated"
 ];
 export {
   defaultFrontmatterPreviewIgnoreKeys

package/dist/header/header.js

@@ -44,7 +44,8 @@ function Header(props) {
   } = props;
   const isNonDefaultLocale = lang != null && lang !== i18n.defaultLocale;
   const pathWithoutBase = urlHelpers.stripBase(currentPath);
-  const matchPath = pathForMatch(pathWithoutBase, lang, i18n.defaultLocale);
+  const pathWithoutVersion = stripCurrentVersionPrefix(pathWithoutBase, currentVersion);
+  const matchPath = pathForMatch(pathWithoutVersion, lang, i18n.defaultLocale);
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
   const rightItemDispatch = createRightItemDispatch(headerRightComponents);
   return /* @__PURE__ */ jsxs(
@@ -249,6 +250,13 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
     }
   );
 }
+function stripCurrentVersionPrefix(path, currentVersion) {
+  if (currentVersion == null || currentVersion === "") return path;
+  const prefix = `/v/${currentVersion}`;
+  if (path === prefix) return "/";
+  if (path.startsWith(`${prefix}/`)) return path.slice(prefix.length);
+  return path;
+}
 function TriggerButton({
   index,
   id,

package/dist/home-page/index.js

@@ -132,7 +132,9 @@ function createHomePageView(ctx) {
                 tree,
                 categoryOrder,
                 categoryIgnore: ["inbox", "develop"],
-                initiallyCollapsedCategorySlugs
+                initiallyCollapsedCategorySlugs,
+                locale,
+                updatedLabel: t("doc.updated", locale)
               }
             )
           }),

package/dist/html-preview-wrapper/highlight-runtime.d.ts

@@ -1,5 +1,5 @@
-import type { HighlightCodeOptions, HighlightCodeResult } from "@takazudo/zfb-md-wasm";
-type HighlightModule = Pick<typeof import("@takazudo/zfb-md-wasm"), "highlightCode">;
+import type { HighlightCodeOptions, HighlightCodeResult } from "@takazudo/zfb-md-wasm/highlight";
+type HighlightModule = Pick<typeof import("@takazudo/zfb-md-wasm/highlight"), "highlightCode">;
 export type HighlightModuleImporter = () => Promise<HighlightModule>;
 export interface HtmlPreviewHighlightRuntime {
     highlightCode(code: string, options: HighlightCodeOptions): Promise<HighlightCodeResult>;
@@ -7,11 +7,11 @@ export interface HtmlPreviewHighlightRuntime {
 /**
  * Build the HTML Preview's lazy zfb highlighting adapter.
  *
- * The cached value is only the public package-root module import. A rejected
- * import is evicted so a later source-panel mount can retry a transient chunk
- * load. Calls to `highlightCode` are deliberately not cached: the upstream
- * package owns WASM initialization and trap recovery, while the component owns
- * request cancellation and stale-result protection.
+ * The cached value is only the public `./highlight` subpath module import. A
+ * rejected import is evicted so a later source-panel mount can retry a transient
+ * chunk load. Calls to `highlightCode` are deliberately not cached: the
+ * upstream package owns WASM initialization and trap recovery, while the
+ * component owns request cancellation and stale-result protection.
  */
 export declare function createHighlightRuntime(importModule: HighlightModuleImporter): HtmlPreviewHighlightRuntime;
 /**

package/dist/html-preview-wrapper/highlight-runtime.js

@@ -20,7 +20,7 @@ function createHighlightRuntime(importModule) {
   };
 }
 const defaultRuntime = createHighlightRuntime(
-  () => import("@takazudo/zfb-md-wasm")
+  () => import("@takazudo/zfb-md-wasm/highlight")
 );
 function getUsableHighlightHtml(result) {
   if (result.html == null || result.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {

package/dist/integrations/changelog/emit.js

@@ -1,5 +1,5 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { generateChangelogMarkdown } from "./generate.js";
 import { loadChangelogEntries } from "./load.js";
 function emitChangelogs(options) {
@@ -8,6 +8,16 @@ function emitChangelogs(options) {
     const sourceDir = resolve(options.projectRoot, config.sourceDir);
     const outputFile = resolve(options.projectRoot, config.outputFile);
     const entries = loadChangelogEntries({ sourceDir });
+    if (entries.length === 0) {
+      const nestedMdxDirs = findNestedMdxDirs(sourceDir);
+      if (nestedMdxDirs.length > 0) {
+        options.logger?.warn?.(
+          `Changelog sourceDir "${config.sourceDir}" (${sourceDir}) yielded 0 releases but contains .mdx files in sub-directories: ${nestedMdxDirs.join(
+            ", "
+          )}. In a multi-changelog layout, each changelogs[] entry must point at a per-package directory (for example "${config.sourceDir}/<name>") whose per-release files are non-index .mdx files; the loader intentionally skips index.mdx.`
+        );
+      }
+    }
     const markdown = generateChangelogMarkdown(entries, {
       title: config.title,
       packageName: config.packageName
@@ -19,6 +29,13 @@ function emitChangelogs(options) {
   }
   return { written };
 }
+function findNestedMdxDirs(sourceDir) {
+  return readdirSync(sourceDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter(
+    (entry) => readdirSync(join(sourceDir, entry.name), { withFileTypes: true }).some(
+      (nestedEntry) => nestedEntry.isFile() && nestedEntry.name.endsWith(".mdx")
+    )
+  ).map((entry) => entry.name).sort();
+}
 export {
   emitChangelogs
 };

package/dist/mdx-components/index.d.ts

@@ -2,7 +2,7 @@ import type { Settings } from "../settings.js";
 /** Any Preact-renderable component (function returning a VNode/children). */
 type AnyComponent = (props: Record<string, unknown>) => unknown;
 /**
- * The 4 host-supplied, locale-aware nav wrappers. Each accepts a `lang` prop;
+ * The host-supplied, locale-aware nav wrappers. Each accepts a `lang` prop;
  * the factory injects the active `locale` so the wrapper queries the correct
  * collection. `SiteTreeNav` is reused for both the `SiteTreeNav` and
  * `SiteTreeNavDemo` MDX tags (matching the showcase mapping).
@@ -11,6 +11,7 @@ export interface MdxNavData {
     CategoryNav: AnyComponent;
     CategoryTreeNav: AnyComponent;
     SiteTreeNav: AnyComponent;
+    NoteTrayIndex: AnyComponent;
 }
 export interface CreateMdxComponentsOptions {
     /**
@@ -35,6 +36,8 @@ export interface CreateMdxComponentsOptions {
      * which wrapper `navData` holds.
      */
     currentVersion?: string;
+    /** Canonical slug of the page being rendered, used to infer its containing note tray. */
+    currentSlug: string;
     /** Host-supplied locale-aware nav wrappers. */
     navData: MdxNavData;
     /**

package/dist/mdx-components/index.js

@@ -109,7 +109,7 @@ function makeEnlargeableParagraph(imageEnlarge, ContentImg) {
   };
 }
 function createMdxComponents(options) {
-  const { settings, locale, currentVersion, navData, extras } = options;
+  const { settings, locale, currentVersion, currentSlug, navData, extras } = options;
   const ContentImg = makeContentImg(settings.base);
   const EnlargeableParagraph = makeEnlargeableParagraph(
     settings.imageEnlarge,
@@ -118,6 +118,7 @@ function createMdxComponents(options) {
   const CategoryNavBound = (props) => navData.CategoryNav({ ...props, lang: locale, currentVersion });
   const CategoryTreeNavBound = (props) => navData.CategoryTreeNav({ ...props, lang: locale, currentVersion });
   const SiteTreeNavBound = (props) => navData.SiteTreeNav({ ...props, lang: locale, currentVersion });
+  const NoteTrayIndexBound = (props) => navData.NoteTrayIndex({ ...props, lang: locale, currentVersion, currentSlug });
   return {
     ...defaultComponents,
     // img override: rewrites root-relative src to include settings.base.
@@ -151,6 +152,7 @@ function createMdxComponents(options) {
     CategoryTreeNav: CategoryTreeNavBound,
     SiteTreeNav: SiteTreeNavBound,
     SiteTreeNavDemo: SiteTreeNavBound,
+    NoteTrayIndex: NoteTrayIndexBound,
     // Host extras win over any same-named default above (Details, HtmlPreview,
     // Island, PresetGenerator, showcase stubs, etc.).
     ...extras ?? {}

package/dist/nav-indexing/index.d.ts

@@ -34,4 +34,6 @@ export { DocCardGrid } from "./doc-card-grid.js";
 export type { DocCardGridProps, DocCardItem } from "./doc-card-grid.js";
 export { VersionsPageContent } from "./versions-page-content.js";
 export type { VersionsPageContentProps } from "./versions-page-content.js";
+export { NoteTrayIndex } from "./note-tray-index.js";
+export type { NoteTrayIndexItem, NoteTrayIndexProps, NoteTrayIndexStyle, } from "./note-tray-index.js";
 export type { NavNode, TagItem, TagLink, TagNavLabels, VersionPageEntry, VersionsPageLabels, } from "./types.js";

package/dist/nav-indexing/index.js

@@ -6,12 +6,14 @@ import { DocsSitemap } from "./docs-sitemap.js";
 import { NavCardGrid } from "./nav-card-grid.js";
 import { DocCardGrid } from "./doc-card-grid.js";
 import { VersionsPageContent } from "./versions-page-content.js";
+import { NoteTrayIndex } from "./note-tray-index.js";
 export {
   CategoryNav,
   CategoryTreeNav,
   DocCardGrid,
   DocsSitemap,
   NavCardGrid,
+  NoteTrayIndex,
   SiteTreeNavDemo,
   TagNav,
   VersionsPageContent