@takazudo/zudo-doc 5.14.0 → 5.16.0

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.16.0] - 2026-09-02
+
+### Features
+
+- Added opt-in Markdown/MDX transclusion through `transclude`, plus independent `assetViewerIndexing` controls for search, llms.txt, and sitemap output. (`8145aae41`)
+- Generated asset-viewer pages can now be enumerated in sitemaps and indexed in search and llms outputs, with locale, base-path, exclusion, and bounded content-extraction handling. (`5da03612e`, `b48009d7e`, `3de313585`, `76b90bc48`)
+
+### Bug Fixes
+
+- Long unbroken titles now wrap across documentation, home, asset, version, and tag pages. (`f21c6b73d`)
+- Asset search excerpts now use bounded reads for large files. (`6c81a13b3`)
+- Asset links in llms outputs now honor the configured `siteUrl`. (`67482a1d5`)
+
+### Other Changes
+
+- Raised the optional `@takazudo/zudo-doc-history-server` peer floor to the already-published 5.15.0 release. (`01bd83bc7`)
+
+## [5.15.0] - 2026-09-01
+
+### Features
+
+- Added an accessible language dropdown that scales to every configured locale instead of assuming a two-language site. (`607121e9`)
+- Generated locale-owned Claude/Codex resource indexes and Asset Viewer routes for every configured locale, with translated page chrome, locale-preserving links, and safe handling of generated versus authored indexes. (`781fb820`, `8ceca53e`, `44ae7812`, `1e558854`, `5d682bc1`)
+- Localized all seven `HtmlPreview` control labels and added per-preview `labels`, `showSource`, and `showViewportControls` overrides while preserving host-provided MDX bindings. (`ffee673f`, `6538184a`)
+- Added `loading="visible"` for route-bound `HtmlPreview` instances, deferring iframe markup, scripts, and external resources until the reserved preview area enters the viewport. (`df63d981`)
+- Kept auto-height previews synchronized after delayed content changes and viewport reflows, including both growth and shrink. (`df3d4b56`)
+- Added escaped, nonblank language and title metadata to generated preview documents, with explicit author `<title>` content retaining precedence. (`2b8b0ee3`, `55e66300`)
+
+### Bug Fixes
+
+- Retained package English strings when a configured locale supplies only partial translations. (`0a3619cb`)
+- Preserved an explicit empty `sandbox` attribute in generated HTML so strict opaque previews remain sandboxed as authored. (`c8b1cac7`)
+- Increased interactive `HtmlPreview` controls to accessible minimum hit-target dimensions. (`a35f1573`)
+
+### Other Changes
+
+- Updated the zfb peer family to 2.14.2. (`5c5bfd2f`)
+
 ## [5.14.0] - 2026-08-31
 
 ### Features
@@ -23,6 +61,8 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 ### Other Changes
 
+- Enabled Asset Viewer routes now localize automatically for existing multi-locale consumers after a package bump, unless `/${assetViewerRoutePrefix}/` is explicitly present in `defaultLocaleOnlyPrefixes`. Existing apps that already carry the legacy Claude/Codex resource prefixes remain default-locale-only after upgrading; remove the prefixes for resource sections you want generated in every configured locale. (#3820)
+- Migration: before building with 5.14.0, remove or rename any authored locale resource overview/category `index.mdx` at a generator target and move custom titles, descriptions, and labels to `ZudoDocConfig.translations`. The generator refuses to overwrite an existing file unless its frontmatter contains `generated: true`. (#3820)
 - Updated the zfb peer family to 2.14.0, `@takazudo/zdtp` to 0.4.14, and the doc-history-server peer floor to 5.13.1. (`dbe8553c7`, `038870c94`, `95a82f15f`)
 
 ## [5.13.1] - 2026-08-28

package/dist/asset-components/asset-card.js

@@ -2,6 +2,7 @@ import { jsx, jsxs } from "preact/jsx-runtime";
 import { assetRawHref, assetViewerHref } from "../asset-path/index.js";
 import {
   AssetFileIcon,
+  assetComponentViewerLocale,
   assetComponentText,
   formatAssetBytes,
   formatAssetLanguage,
@@ -23,7 +24,8 @@ function createAssetCard(context) {
     const viewerHref = assetViewerHref({
       base: context.base,
       routePrefix: context.routePrefix,
-      path
+      path,
+      locale: assetComponentViewerLocale(context, path)
     });
     const rawHref = assetRawHref({ base: context.base, dir: context.dir, path });
     const details = [

package/dist/asset-components/asset-code.js

@@ -2,6 +2,7 @@ import { jsx, jsxs } from "preact/jsx-runtime";
 import { assetViewerHref } from "../asset-path/index.js";
 import {
   AssetFileIcon,
+  assetComponentViewerLocale,
   assetComponentText,
   MissingAssetWarning,
   resolveAssetEntry
@@ -43,6 +44,7 @@ function createAssetCode(context) {
       base: context.base,
       routePrefix: context.routePrefix,
       path: resolved.path,
+      locale: assetComponentViewerLocale(context, resolved.path),
       fragment: excerpt.viewerLineAvailable ? `L${excerpt.startLine}` : void 0
     });
     const shown = Math.max(0, excerpt.endLine - excerpt.startLine + 1);

package/dist/asset-components/shared.d.ts

@@ -7,9 +7,14 @@ export interface AssetComponentContext {
     assetManifest: AssetManifest | null;
     routePrefix: string;
     dir: string;
+    /** Non-default locale segment for viewer links. */
+    locale?: string;
+    /** Match viewer paths that intentionally remain default-locale-only. */
+    isDefaultLocaleOnlyPath?: (path: string) => boolean;
     /** Locale-bound package translator. Omitted callers retain English fallbacks. */
     t?: (key: string) => string;
 }
+export declare function assetComponentViewerLocale(context: AssetComponentContext, path: string): string | undefined;
 export declare function assetComponentText(context: AssetComponentContext, key: string, fallback: string, values?: Record<string, string | number>): string;
 export declare function resolveAssetEntry(src: string, context: AssetComponentContext): {
     path: string;

package/dist/asset-components/shared.js

@@ -1,5 +1,11 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { decodeAuthoredHref } from "../asset-path/index.js";
+function assetComponentViewerLocale(context, path) {
+  if (context.isDefaultLocaleOnlyPath?.(`/${context.routePrefix}/${path}`)) {
+    return void 0;
+  }
+  return context.locale;
+}
 function assetComponentText(context, key, fallback, values = {}) {
   let text = context.t?.(key) ?? fallback;
   for (const [name, value] of Object.entries(values)) {
@@ -83,6 +89,7 @@ export {
   AssetFileIcon,
   MissingAssetWarning,
   assetComponentText,
+  assetComponentViewerLocale,
   formatAssetBytes,
   formatAssetLanguage,
   resolveAssetEntry

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

@@ -14,6 +14,7 @@ export interface AssetTreeNode {
 }
 export interface AssetIndexPageViewProps {
     entries: AssetIndexEntry[];
+    locale?: string;
 }
 /** Build a sorted directory tree and aggregate every directory's subtree totals. */
 export declare function buildAssetTree(entries: AssetIndexEntry[]): AssetTreeNode;

package/dist/asset-index-page/index.js

@@ -86,7 +86,7 @@ function iconFor(asset) {
 function countLabel(count, plural, single) {
   return (count === 1 ? single : plural).replace("{count}", String(count));
 }
-function AssetTree({ node, base, routePrefix, fileCountLabel, fileCountSingleLabel, linesLabel, root = false }) {
+function AssetTree({ node, base, routePrefix, locale, fileCountLabel, fileCountSingleLabel, linesLabel, root = false }) {
   return /* @__PURE__ */ jsxs("ul", { "data-zd-asset-tree": root ? true : void 0, children: [
     node.dirs.map((dir) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("details", { open: true, children: [
       /* @__PURE__ */ jsxs("summary", { class: "flex cursor-pointer items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small hover:bg-accent/10 focus-visible:bg-accent/10", children: [
@@ -103,13 +103,13 @@ function AssetTree({ node, base, routePrefix, fileCountLabel, fileCountSingleLab
           formatAssetBytes(dir.bytes)
         ] })
       ] }),
-      /* @__PURE__ */ jsx(AssetTree, { node: dir, base, routePrefix, fileCountLabel, fileCountSingleLabel, linesLabel })
+      /* @__PURE__ */ jsx(AssetTree, { node: dir, base, routePrefix, locale, fileCountLabel, fileCountSingleLabel, linesLabel })
     ] }) })),
     node.files.map((asset) => {
       const Icon = iconFor(asset);
       const facet = facetLabel(asset, linesLabel);
       const meta = [kindLabel(asset), facet, formatAssetBytes(asset.bytes)].filter(Boolean).join(" \xB7 ");
-      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", { href: assetViewerHref({ base, routePrefix, path: asset.path }), title: asset.name, class: "flex min-w-0 items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:underline", children: [
+      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", { href: assetViewerHref({ base, routePrefix, path: asset.path, locale }), title: asset.name, class: "flex min-w-0 items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:underline", children: [
         /* @__PURE__ */ jsx(Icon, { className: "h-icon-sm w-icon-sm shrink-0 text-muted" }),
         /* @__PURE__ */ jsx("span", { class: "min-w-0 truncate font-mono", children: basename(asset.path) }),
         /* @__PURE__ */ jsx("span", { class: "ml-auto hidden whitespace-nowrap pl-hsp-lg text-caption text-muted sm:block", children: meta })
@@ -120,17 +120,18 @@ function AssetTree({ node, base, routePrefix, fileCountLabel, fileCountSingleLab
 function createAssetIndexPageView(ctx) {
   assertChromeContext(ctx, "createAssetIndexPageView");
   const settings = ctx.settings;
-  const locale = ctx.defaultLocale;
   const t = ctx.t;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
   const { Header: HeaderWithDefaults, Footer: FooterWithDefaults, Breadcrumb: BreadcrumbWithDefaults } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const dataThemePack = resolveThemePackSsrSlug(ctx.themePackRegistry, settings);
-  return function AssetIndexPageView({ entries }) {
+  return function AssetIndexPageView({ entries, locale = ctx.defaultLocale }) {
+    const localeSegment = locale === ctx.defaultLocale ? void 0 : locale;
     const routePrefix = ctx.assetManifest?.routePrefix ?? settings.assetViewerRoutePrefix;
     const dir = ctx.assetManifest?.dir ?? settings.assetViewerDir;
-    const indexUrl = ctx.withBase(`/${routePrefix}/`);
+    const indexUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}${routePrefix}/`);
+    const homeUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}`);
     const tree = buildAssetTree(entries);
     const folders = folderCount(tree);
     const fileCountLabel = t("asset.fileCount", locale);
@@ -138,13 +139,13 @@ function createAssetIndexPageView(ctx) {
     const folderCountLabel = t("asset.folderCount", locale);
     const folderCountSingleLabel = t("asset.folderCountSingle", locale);
     const title = t("asset.crumb", locale);
-    return /* @__PURE__ */ jsx(DocLayoutWithDefaults, { title: composeMetaTitle(title), head: /* @__PURE__ */ jsx(HeadWithDefaults, { title, description: t("asset.indexDescription", locale), canonical: ctx.absoluteUrl(indexUrl) }), lang: locale, dataThemePack, noindex: settings.noindex, hideSidebar: true, hideToc: true, sidebarOverride: false, contentWide: true, breadcrumbOverride: /* @__PURE__ */ jsx(BreadcrumbWithDefaults, { items: [{ label: "", href: ctx.withBase("/") }, { label: title }] }), headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: indexUrl, hideSidebarToggle: true }), footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }), bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }), enableClientRouter: settings.dynamicPageTransition, children: /* @__PURE__ */ jsxs("div", { "data-zd-asset-index-page": true, children: [
+    return /* @__PURE__ */ jsx(DocLayoutWithDefaults, { title: composeMetaTitle(title), head: /* @__PURE__ */ jsx(HeadWithDefaults, { title, description: t("asset.indexDescription", locale), canonical: ctx.absoluteUrl(indexUrl) }), lang: locale, dataThemePack, noindex: settings.noindex, hideSidebar: true, hideToc: true, sidebarOverride: false, contentWide: true, breadcrumbOverride: /* @__PURE__ */ jsx(BreadcrumbWithDefaults, { items: [{ label: "", href: homeUrl }, { label: title }] }), headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: indexUrl, hideSidebarToggle: true }), footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }), bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }), enableClientRouter: settings.dynamicPageTransition, children: /* @__PURE__ */ jsxs("div", { "data-zd-asset-index-page": true, children: [
       /* @__PURE__ */ jsxs("header", { children: [
         /* @__PURE__ */ jsxs("div", { class: "mb-vsp-xs flex flex-wrap items-center gap-hsp-xs text-micro tracking-wide uppercase", children: [
           /* @__PURE__ */ jsx("span", { class: "rounded-full border border-muted px-hsp-sm py-vsp-3xs text-fg", children: title }),
           /* @__PURE__ */ jsx("span", { class: "rounded-full border border-muted px-hsp-sm py-vsp-3xs text-muted", children: t("asset.indexBadge", locale) })
         ] }),
-        /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight", children: title }),
+        /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight break-words", children: title }),
         /* @__PURE__ */ jsxs("div", { "data-doc-metainfo": true, class: "mb-vsp-md flex flex-wrap items-center gap-x-hsp-md gap-y-vsp-2xs text-caption text-fg", children: [
           /* @__PURE__ */ jsx("span", { children: countLabel(tree.fileCount, fileCountLabel, fileCountSingleLabel) }),
           /* @__PURE__ */ jsx("span", { children: countLabel(folders, folderCountLabel, folderCountSingleLabel) }),
@@ -163,7 +164,7 @@ function createAssetIndexPageView(ctx) {
           /* @__PURE__ */ jsx("button", { type: "button", disabled: true, "data-zd-asset-index-action": "collapse", class: "text-fg hover:text-accent focus-visible:text-accent", children: t("asset.collapseAll", locale) })
         ] })
       ] }),
-      entries.length > 0 ? /* @__PURE__ */ jsx(AssetTree, { root: true, node: tree, base: settings.base, routePrefix, fileCountLabel, fileCountSingleLabel, linesLabel: t("asset.lines", locale) }) : /* @__PURE__ */ jsx("p", { class: "text-small text-muted", "data-zd-asset-index-empty": true, children: t("asset.indexEmpty", locale) }),
+      entries.length > 0 ? /* @__PURE__ */ jsx(AssetTree, { root: true, node: tree, base: settings.base, routePrefix, locale: localeSegment, fileCountLabel, fileCountSingleLabel, linesLabel: t("asset.lines", locale) }) : /* @__PURE__ */ jsx("p", { class: "text-small text-muted", "data-zd-asset-index-empty": true, children: t("asset.indexEmpty", locale) }),
       /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: ASSET_INDEX_PAGE_SCRIPT } })
     ] }) });
   };

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

@@ -8,6 +8,7 @@ export { ASSET_PAGE_SCRIPT } from "./script.js";
 export type { AssetRecord } from "../plugins/internal/asset-viewer/types.js";
 export interface AssetPageViewProps {
     entry: AssetRecord;
+    locale?: string;
 }
 export declare function AssetEyebrow({ asset, badge }: {
     asset: AssetRecord;
@@ -36,9 +37,17 @@ export declare function AssetCodeBody({ asset, copyLabel, wrapLabel, truncatedLa
     truncatedLabel: string;
     linesLabel?: string;
 }): VNode;
-export declare function AssetImageStage({ asset, rawUrl }: {
+export interface AssetImageStageLabels {
+    fit: string;
+    actualSize: string;
+    checker: string;
+    dark: string;
+    enlarge: string;
+}
+export declare function AssetImageStage({ asset, rawUrl, labels }: {
     asset: AssetRecord;
     rawUrl: string;
+    labels: AssetImageStageLabels;
 }): VNode;
 export declare function AssetVideoStage({ asset, rawUrl }: {
     asset: AssetRecord;
@@ -60,8 +69,17 @@ export declare function AssetLinkedFrom({ asset, label }: {
     asset: AssetRecord;
     label: string;
 }): VNode | null;
-export declare function AssetDetails({ asset }: {
+export interface AssetDetailsLabels {
+    heading: string;
+    type: string;
+    size: string;
+    path: string;
+    dimensions: string;
+    updated: string;
+}
+export declare function AssetDetails({ asset, labels }: {
     asset: AssetRecord;
+    labels: AssetDetailsLabels;
 }): VNode;
 /** Build the package-owned wide asset viewer page from a chrome context. */
 export declare function createAssetPageView<S extends Settings = Settings>(ctx: ChromeContext<S>): (props: AssetPageViewProps) => JSX.Element;

package/dist/asset-page/index.js

@@ -42,7 +42,7 @@ function AssetHeader({ asset, locale, badge, updatedLabel, linesLabel }) {
   const facet = facetLabel(asset, linesLabel);
   return /* @__PURE__ */ jsxs("header", { children: [
     /* @__PURE__ */ jsx(AssetEyebrow, { asset, badge }),
-    /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight", children: asset.name }),
+    /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight break-words", children: asset.name }),
     /* @__PURE__ */ jsxs("div", { "data-doc-metainfo": true, class: "mb-vsp-md flex flex-wrap items-center gap-x-hsp-md gap-y-vsp-2xs text-caption text-fg", children: [
       asset.dir && /* @__PURE__ */ jsx("span", { children: asset.dir }),
       facet && /* @__PURE__ */ jsx("span", { children: facet }),
@@ -93,21 +93,21 @@ function AssetCodeBody({ asset, copyLabel, wrapLabel, truncatedLabel, linesLabel
 function EnlargeIcon() {
   return /* @__PURE__ */ jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { fill: "none", stroke: "currentColor", "stroke-linecap": "round", "stroke-linejoin": "round", "stroke-width": "2", d: "M8 3H3v5m13-5h5v5M8 21H3v-5m13 5h5v-5M3 8l6-6m12 6-6-6M3 16l6 6m12-6-6 6" }) });
 }
-function AssetImageStage({ asset, rawUrl }) {
+function AssetImageStage({ asset, rawUrl, labels }) {
   return /* @__PURE__ */ jsxs("section", { children: [
     /* @__PURE__ */ jsxs("div", { class: "mb-vsp-xs flex flex-wrap gap-hsp-sm text-caption", children: [
       /* @__PURE__ */ jsxs("div", { class: "flex rounded border border-muted", children: [
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "fit", class: "px-hsp-sm py-vsp-3xs", children: "Fit" }),
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "1to1", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: "1:1" })
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "fit", class: "px-hsp-sm py-vsp-3xs", children: labels.fit }),
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "1to1", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: labels.actualSize })
       ] }),
       /* @__PURE__ */ jsxs("div", { class: "flex rounded border border-muted", children: [
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "checker", class: "px-hsp-sm py-vsp-3xs", children: "Checker" }),
-        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "dark", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: "Dark" })
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "true", "data-zd-asset-action": "checker", class: "px-hsp-sm py-vsp-3xs", children: labels.checker }),
+        /* @__PURE__ */ jsx("button", { type: "button", "aria-pressed": "false", "data-zd-asset-action": "dark", class: "border-l border-muted px-hsp-sm py-vsp-3xs", children: labels.dark })
       ] })
     ] }),
     /* @__PURE__ */ jsxs("figure", { class: "zd-enlargeable zd-asset-stage is-checker flex min-h-[20rem] items-center justify-center overflow-auto rounded border border-muted bg-surface p-hsp-lg", children: [
       /* @__PURE__ */ jsx("img", { src: rawUrl, alt: asset.description ?? asset.name, width: asset.width, height: asset.height }),
-      /* @__PURE__ */ jsx("button", { type: "button", class: "zd-enlarge-btn", hidden: true, "aria-label": "Enlarge image", children: /* @__PURE__ */ jsx(EnlargeIcon, {}) })
+      /* @__PURE__ */ jsx("button", { type: "button", class: "zd-enlarge-btn", hidden: true, "aria-label": labels.enlarge, children: /* @__PURE__ */ jsx(EnlargeIcon, {}) })
     ] })
   ] });
 }
@@ -147,12 +147,12 @@ function AssetLinkedFrom({ asset, label }) {
     ] })) })
   ] });
 }
-function AssetDetails({ asset }) {
-  const rows = [["Type", asset.mime], ["Size", formatAssetBytes(asset.bytes)], ["Path", asset.path]];
-  if (asset.width !== void 0 && asset.height !== void 0) rows.splice(1, 0, ["Dimensions", `${asset.width} \xD7 ${asset.height}`]);
-  if (asset.updatedDate) rows.push(["Updated", asset.updatedDate]);
+function AssetDetails({ asset, labels }) {
+  const rows = [[labels.type, asset.mime], [labels.size, formatAssetBytes(asset.bytes)], [labels.path, asset.path]];
+  if (asset.width !== void 0 && asset.height !== void 0) rows.splice(1, 0, [labels.dimensions, `${asset.width} \xD7 ${asset.height}`]);
+  if (asset.updatedDate) rows.push([labels.updated, asset.updatedDate]);
   return /* @__PURE__ */ jsxs("section", { children: [
-    /* @__PURE__ */ jsx("h2", { class: "mb-vsp-xs text-title font-bold", children: "Details" }),
+    /* @__PURE__ */ jsx("h2", { class: "mb-vsp-xs text-title font-bold", children: labels.heading }),
     /* @__PURE__ */ jsx("dl", { class: "grid grid-cols-[auto_1fr] gap-x-hsp-md gap-y-vsp-2xs text-caption", children: rows.map(([term, value]) => /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx("dt", { class: "font-medium text-muted", children: term }),
       /* @__PURE__ */ jsx("dd", { class: "min-w-0 break-words text-fg", children: value })
@@ -171,53 +171,72 @@ function MediaLayout({ stage, details, linked }) {
 function createAssetPageView(ctx) {
   assertChromeContext(ctx, "createAssetPageView");
   const settings = ctx.settings;
-  const locale = ctx.defaultLocale;
   const t = ctx.t;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
   const { Header: HeaderWithDefaults, Footer: FooterWithDefaults, Breadcrumb: BreadcrumbWithDefaults } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const dataThemePack = resolveThemePackSsrSlug(ctx.themePackRegistry, settings);
-  return function AssetPageView({ entry: asset }) {
+  return function AssetPageView({ entry: asset, locale = ctx.defaultLocale }) {
+    const localeSegment = locale === ctx.defaultLocale ? void 0 : locale;
     const routePrefix = ctx.assetManifest?.routePrefix ?? settings.assetViewerRoutePrefix;
     const dir = ctx.assetManifest?.dir ?? settings.assetViewerDir;
-    const viewerUrl = assetViewerHref({ base: settings.base, routePrefix, path: asset.path });
+    const viewerUrl = assetViewerHref({ base: settings.base, routePrefix, path: asset.path, locale: localeSegment });
     const rawUrl = assetRawHref({ base: settings.base, dir, path: asset.path });
     const linesLabel = t("asset.lines", locale).replace(
       "{count}",
       String(asset.lines ?? 0)
     );
     const dirSegments = asset.dir.split("/").filter(Boolean);
-    const indexUrl = ctx.withBase(`/${routePrefix}/`);
+    const indexUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}${routePrefix}/`);
+    const homeUrl = ctx.withBase(`/${localeSegment ? `${localeSegment}/` : ""}`);
+    const backLink = locale === ctx.defaultLocale ? asset.linkedFrom[0] : asset.linkedFrom.find((link) => link.locale === locale) ?? asset.linkedFrom[0];
     const breadcrumbItems = [
-      { label: "", href: ctx.withBase("/") },
+      { label: "", href: homeUrl },
       { label: t("asset.crumb", locale), ...settings.assetViewerIndex ? { href: indexUrl } : {} },
       ...dirSegments.map((label) => ({ label })),
       { label: asset.name }
     ];
     const linked = /* @__PURE__ */ jsx(AssetLinkedFrom, { asset, label: t("asset.linkedFrom", locale) });
-    const details = /* @__PURE__ */ jsx(AssetDetails, { asset });
+    const detailsLabels = {
+      heading: t("asset.details", locale),
+      type: t("asset.type", locale),
+      size: t("asset.size", locale),
+      path: t("asset.path", locale),
+      dimensions: t("asset.dimensions", locale),
+      updated: t("doc.updated", locale)
+    };
+    const imageStageLabels = {
+      fit: t("asset.fit", locale),
+      actualSize: t("asset.actualSize", locale),
+      checker: t("asset.checker", locale),
+      dark: t("asset.dark", locale),
+      enlarge: t("asset.enlarge", locale)
+    };
+    const details = /* @__PURE__ */ jsx(AssetDetails, { asset, labels: detailsLabels });
     const downloadPanel = /* @__PURE__ */ jsx(AssetDownloadPanel, { asset, rawUrl, noPreview: t("asset.noPreview", locale), downloadLabel: t("asset.download", locale), copyLabel: t("asset.copy", locale) });
     let body;
     const isMedia = asset.previewable && asset.sniffOk && ["image", "video", "pdf"].includes(asset.kind);
     if (!asset.previewable || !asset.sniffOk) body = /* @__PURE__ */ jsxs(Fragment, { children: [
       downloadPanel,
-      /* @__PURE__ */ jsx(AssetDetails, { asset }),
+      /* @__PURE__ */ jsx(AssetDetails, { asset, labels: detailsLabels }),
       linked
     ] });
-    else if (asset.kind === "image") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetImageStage, { asset, rawUrl }), details, linked });
+    else if (asset.kind === "image") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetImageStage, { asset, rawUrl, labels: imageStageLabels }), details, linked });
     else if (asset.kind === "video") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetVideoStage, { asset, rawUrl }), details, linked });
     else if (asset.kind === "pdf") body = /* @__PURE__ */ jsx(MediaLayout, { stage: /* @__PURE__ */ jsx(AssetPdfStage, { asset, rawUrl, children: downloadPanel }), details, linked });
     else body = /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(AssetCodeBody, { asset, copyLabel: t("asset.copy", locale), wrapLabel: t("asset.wrap", locale), truncatedLabel: t("asset.truncated", locale), linesLabel }),
-      /* @__PURE__ */ jsx(AssetDetails, { asset }),
+      /* @__PURE__ */ jsx(AssetDetails, { asset, labels: detailsLabels }),
       linked
     ] });
     const showSource = settings.bodyFootUtilArea !== false && settings.bodyFootUtilArea.viewSourceLink !== false;
     return /* @__PURE__ */ jsx(DocLayoutWithDefaults, { title: composeMetaTitle(asset.name), head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: asset.name, description: asset.description, canonical: ctx.absoluteUrl(viewerUrl) }), lang: locale, dataThemePack, noindex: settings.noindex, hideSidebar: true, hideToc: true, sidebarOverride: false, contentWide: true, breadcrumbOverride: /* @__PURE__ */ jsx(BreadcrumbWithDefaults, { items: breadcrumbItems }), headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: viewerUrl, hideSidebarToggle: true }), footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }), bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/", forceImageEnlarge: asset.kind === "image" && asset.previewable && asset.sniffOk }), enableClientRouter: settings.dynamicPageTransition, children: /* @__PURE__ */ jsxs("div", { class: "zd-asset-page", "data-zd-asset-page": true, children: [
-      asset.linkedFrom[0] && /* @__PURE__ */ jsx("p", { class: "mb-vsp-xs text-caption", children: /* @__PURE__ */ jsxs("a", { href: asset.linkedFrom[0].href, class: "text-muted hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline", children: [
-        "\u2190 Back to ",
-        asset.linkedFrom[0].title
+      backLink && /* @__PURE__ */ jsx("p", { class: "mb-vsp-xs text-caption", children: /* @__PURE__ */ jsxs("a", { href: backLink.href, class: "text-muted hover:text-accent focus-visible:text-accent hover:underline focus-visible:underline", children: [
+        "\u2190 ",
+        t("asset.backTo", locale),
+        " ",
+        backLink.title
       ] }) }),
       /* @__PURE__ */ jsx(AssetHeader, { asset, locale, badge: t("asset.badge", locale), updatedLabel: t("doc.updated", locale), linesLabel }),
       /* @__PURE__ */ jsx(AssetActions, { rawUrl, downloadLabel: t("asset.download", locale), openRawLabel: t("asset.openRaw", locale), copyLabel: t("asset.copy", locale), wrapLabel: t("asset.wrap", locale), code: !isMedia && asset.previewable && asset.sniffOk }),

package/dist/asset-path/index.d.ts

@@ -9,6 +9,8 @@ export interface AssetViewerHrefOptions {
     base: string;
     routePrefix: string;
     path: string;
+    /** Non-default locale segment. Omit for the unprefixed default locale. */
+    locale?: string;
     /** A fragment with or without its leading `#`. */
     fragment?: string;
 }

package/dist/asset-path/index.js

@@ -59,9 +59,10 @@ function decodeAuthoredHref(href, options) {
 }
 function assetViewerHref(options) {
   const routePrefix = normalizeSettingPath(options.routePrefix, "routePrefix");
+  const localePrefix = options.locale === void 0 ? "" : `/${encodeURIComponent(normalizeLocaleSegment(options.locale))}`;
   const href = withBase(
     options.base,
-    `/${routePrefix}/${encodeAssetPathForUrl(options.path)}/`
+    `${localePrefix}/${routePrefix}/${encodeAssetPathForUrl(options.path)}/`
   );
   if (options.fragment == null || options.fragment === "") return href;
   if (CONTROL_CHARS.test(options.fragment)) {
@@ -69,6 +70,15 @@ function assetViewerHref(options) {
   }
   return href + (options.fragment.startsWith("#") ? options.fragment : `#${options.fragment}`);
 }
+function normalizeLocaleSegment(locale) {
+  if (locale.length === 0 || locale.includes("/") || locale.includes("\\")) {
+    throw new Error("Asset viewer locale must be a non-empty URL segment");
+  }
+  if (locale === "." || locale === ".." || CONTROL_CHARS.test(locale)) {
+    throw new Error("Asset viewer locale must be a safe URL segment");
+  }
+  return locale.normalize("NFC");
+}
 function assetRawHref(options) {
   const dir = normalizeSettingPath(options.dir, "dir");
   return withBase(options.base, `/${dir}/${encodeAssetPathForUrl(options.path)}`);

package/dist/chrome/derive.js

@@ -314,12 +314,6 @@ function deriveMdxComponents(ctx) {
     t: (key, locale) => ctx.t(key, locale),
     versionedDocsUrl: ctx.versionedDocsUrl
   });
-  function HtmlPreviewBound(props) {
-    return HtmlPreviewWrapper({
-      globalConfig: ctx.settings.htmlPreview ?? null,
-      ...props
-    });
-  }
   const assetComponentContext = {
     base: ctx.settings.base,
     assetManifest: ctx.assetManifest,
@@ -329,8 +323,37 @@ function deriveMdxComponents(ctx) {
   function createMdxComponentsBound(lang = ctx.defaultLocale, currentVersion, currentSlug = "") {
     const localizedAssetContext = {
       ...assetComponentContext,
+      locale: lang === ctx.defaultLocale ? void 0 : lang,
+      isDefaultLocaleOnlyPath: ctx.isDefaultLocaleOnlyPath,
       t: (key) => ctx.t(key, lang)
     };
+    const localizedHtmlPreviewLabels = {
+      mobile: ctx.t("htmlPreview.viewport.mobile", lang),
+      tablet: ctx.t("htmlPreview.viewport.tablet", lang),
+      full: ctx.t("htmlPreview.viewport.full", lang),
+      viewportSize: ctx.t("htmlPreview.viewport.label", lang),
+      showCode: ctx.t("htmlPreview.source.show", lang),
+      hideCode: ctx.t("htmlPreview.source.hide", lang),
+      preview: ctx.t("htmlPreview.iframe.title", lang)
+    };
+    function HtmlPreviewBound(props) {
+      const labels = props.labels;
+      const effectiveLang = props.lang?.trim() ? props.lang : lang.trim() ? lang : "en";
+      return HtmlPreviewWrapper({
+        globalConfig: ctx.settings.htmlPreview ?? null,
+        ...props,
+        lang: effectiveLang,
+        labels: {
+          mobile: labels?.mobile ?? localizedHtmlPreviewLabels.mobile,
+          tablet: labels?.tablet ?? localizedHtmlPreviewLabels.tablet,
+          full: labels?.full ?? localizedHtmlPreviewLabels.full,
+          viewportSize: labels?.viewportSize ?? localizedHtmlPreviewLabels.viewportSize,
+          showCode: labels?.showCode ?? localizedHtmlPreviewLabels.showCode,
+          hideCode: labels?.hideCode ?? localizedHtmlPreviewLabels.hideCode,
+          preview: labels?.preview ?? localizedHtmlPreviewLabels.preview
+        }
+      });
+    }
     const mdxExtrasDefault = {
       Asset: createAssetCard(localizedAssetContext),
       AssetCode: createAssetCode(localizedAssetContext),
@@ -348,6 +371,8 @@ function deriveMdxComponents(ctx) {
     return createMdxComponents({
       settings: ctx.settings,
       assetManifest: ctx.assetManifest,
+      assetViewerLocale: lang === ctx.defaultLocale ? void 0 : lang,
+      isDefaultLocaleOnlyPath: ctx.isDefaultLocaleOnlyPath,
       locale: lang,
       currentVersion,
       currentSlug,

package/dist/compiled.css

@@ -658,6 +658,9 @@
 .min-h-\[20rem\] {
   min-height: 20rem;
 }
+.min-h-\[44px\] {
+  min-height: 44px;
+}
 .min-h-\[60vh\] {
   min-height: 60vh;
 }
@@ -754,6 +757,9 @@
 .w-icon-xs {
   width: var(--spacing-icon-xs);
 }
+.max-w-\[16rem\] {
+  max-width: 16rem;
+}
 .max-w-\[64rem\] {
   max-width: 64rem;
 }
@@ -772,6 +778,9 @@
 .max-w-\[calc\(100vw-2rem\)\] {
   max-width: calc(100vw - 2rem);
 }
+.max-w-\[calc\(100vw-var\(--spacing-hsp-xl\)\)\] {
+  max-width: calc(100vw - var(--spacing-hsp-xl));
+}
 .max-w-\[clamp\(50rem\,75vw\,90rem\)\] {
   max-width: clamp(50rem, 75vw, 90rem);
 }
@@ -793,6 +802,9 @@
 .min-w-\[10rem\] {
   min-width: 10rem;
 }
+.min-w-\[44px\] {
+  min-width: 44px;
+}
 .flex-1 {
   flex: 1;
 }

package/dist/config.d.ts

@@ -18,11 +18,13 @@
  * `zudoDoc()` SHALLOW-merges the user's fields over {@link DEFAULT_SETTINGS} —
  * top-level fields only (`{ ...DEFAULT_SETTINGS, ...user }`). A supplied nested
  * object (e.g. `colorMode`, `metaTags`) REPLACES the default wholesale; it is
- * NOT deep-merged key-by-key. This is safe because every nested config type is
- * all-required-fields, so a caller supplying one supplies all of its fields.
- * ONE exception: `FaviconConfig` is all-optional — wholesale replacement IS its
- * semantics (only the supplied slots emit a `<link rel="icon">`), and its
- * default is `undefined`, so there is nothing for a partial object to clobber.
+ * NOT deep-merged key-by-key. Nested config types that intentionally expose
+ * optional keys (such as `FrontmatterPreviewConfig` and
+ * `AssetViewerIndexingConfig`) get their per-key defaults at the read site;
+ * this shallow merge never fills nested keys. `FaviconConfig` is also
+ * all-optional — wholesale replacement IS its semantics (only the supplied
+ * slots emit a `<link rel="icon">`), and its default is `undefined`, so there
+ * is nothing for a partial object to clobber.
  * `zudoDoc()` also supplies the Wave-3 package defaults
  * (`buildDocsSchema`/`directiveVocabulary`/`translations`/`colorSchemes`/tag
  * vocabulary) unless overridden, and returns a **complete `ZfbConfig`** — the
@@ -65,7 +67,7 @@ import type { ZfbConfig, BundleConfig } from "@takazudo/zfb/config";
 import type { ZodType } from "zod";
 import type { DirectiveVocabulary, PresetTranslations, PresetTagVocabularyEntry } from "./preset.js";
 import type { ColorScheme } from "./color-scheme-utils.js";
-import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig, FaviconConfig } from "./settings.js";
+import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, AssetViewerIndexingConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig, FaviconConfig } from "./settings.js";
 /** The `settings.claudeResources` block (or `false` when disabled). */
 type ClaudeResourcesConfig = {
     claudeDir: string;
@@ -188,6 +190,11 @@ export interface ZudoDocConfig {
      * @default true
      */
     mermaid?: boolean;
+    /**
+     * Enable transclusion of other Markdown/MDX files via `:::include`.
+     * @default false
+     */
+    transclude?: boolean;
     /**
      * Add `noindex,nofollow` to every page (for internal docs).
      * @default false
@@ -377,6 +384,8 @@ export interface ZudoDocConfig {
     assetViewerExclude?: string[];
     /** When `true` (and `assetViewer` is `true`), generate a listing page at `/<assetViewerRoutePrefix>/` showing every managed asset as a folder tree. No effect when `assetViewer` is `false`. @default false */
     assetViewerIndex?: boolean;
+    /** Per-output opt-in controls for indexing generated asset-viewer pages. Omitted keys are off; `false` disables all asset-page indexing. @default false */
+    assetViewerIndexing?: AssetViewerIndexingConfig | false;
     /**
      * Body-foot utility area (doc-history / view-source), or `false` to disable.
      * @default false

package/dist/config.js

@@ -53,6 +53,7 @@ const DEFAULT_SETTINGS = {
   defaultLocale: "en",
   locales: {},
   mermaid: true,
+  transclude: false,
   noindex: false,
   editUrl: false,
   githubUrl: false,
@@ -98,6 +99,7 @@ const DEFAULT_SETTINGS = {
   assetViewerRoutePrefix: "files",
   assetViewerExclude: [],
   assetViewerIndex: false,
+  assetViewerIndexing: false,
   bodyFootUtilArea: false,
   htmlPreview: void 0,
   versions: false,

package/dist/content/content-link.d.ts

@@ -9,10 +9,14 @@ export interface CreateContentLinkOptions {
     assetManifest: AssetManifest | null;
     routePrefix: string;
     dir: string;
+    /** Non-default locale segment used by asset-viewer links. */
+    locale?: string;
+    /** Match viewer paths that intentionally remain default-locale-only. */
+    isDefaultLocaleOnlyPath?: (path: string) => boolean;
 }
 /**
  * Bind ContentLink to an asset manifest. Only exact manifest entries are
  * decorated and redirected; every other anchor follows ContentLink verbatim.
  */
-export declare function createContentLink({ base, assetManifest, routePrefix, dir, }: CreateContentLinkOptions): (props: Props) => JSX.Element;
+export declare function createContentLink({ base, assetManifest, routePrefix, dir, locale, isDefaultLocaleOnlyPath, }: CreateContentLinkOptions): (props: Props) => JSX.Element;
 export {};