create-zudo-doc 5.13.1 → 5.14.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `create-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.14.0] - 2026-08-31
+
+### Features
+
+- Added the `--asset-viewer` feature flag. Generated projects now emit `assetViewer: true` in `zfb.config.ts`, enabling the package-owned viewer for files under `public/assets/` without adding a host route stub or extra template files. (`45dc50cdb`)
+- Generated doc-history projects now use the package-owned `run-parallel` command for their concurrent development servers, removing `npm-run-all2` and reporting unsupported trailing arguments instead of silently ignoring them. (`9402ff157`, `3ebfa6e9c`)
+
+### Bug Fixes
+
+- Updated the generated link checker to recognize valid unquoted HTML attributes, decode character references, resolve percent-encoded routes, and avoid serialized-markup false positives. (`db9a07018`)
+
+### Other Changes
+
+- Updated newly generated projects to use the zfb 2.14.0 package family and `@takazudo/zdtp` 0.4.14. (`dbe8553c7`, `038870c94`)
+
 ## [5.13.1] - 2026-08-28
 
 ### Bug Fixes

package/README.md

@@ -76,6 +76,7 @@ Each feature has a `--[no-]<flag>` form. Passing `--feature` enables it; `--no-f
 | `--[no-]search` | Full-text search | on |
 | `--[no-]sidebar-filter` | Real-time sidebar filter | on |
 | `--[no-]image-enlarge` | Click-to-enlarge for oversized images | on |
+| `--[no-]asset-viewer` | Viewer pages for files under `public/assets/` | off |
 | `--[no-]tag-governance` | Vocabulary-aware tag audit + suggest scripts | off |
 | `--[no-]claude-resources` | Auto-generate Claude Code docs from `.claude/` | off |
 | `--[no-]codex-resources` | Auto-generate Codex docs from `.codex/` + `AGENTS.md` | off |

package/dist/claude-md-gen.js

@@ -29,10 +29,10 @@ export function generateCLAUDEFile(choices) {
     lines.push(``);
     const pm = choices.packageManager;
     if (choices.features.includes("docHistory")) {
-        lines.push(`- \`${pmRunCommand(pm, "dev")}\` — runs the zfb dev server (port 4321) and the doc-history API server (port 4322) concurrently via \`run-p\` (\`${pmRunCommand(pm, "dev:zfb")}\` / \`${pmRunCommand(pm, "dev:history")}\` individually)`);
+        lines.push(`- \`${pmRunCommand(pm, "dev")}\` — runs the zfb dev server (port 4321) and the doc-history API server (port 4322) concurrently via \`run-parallel\` (a bin from @takazudo/zudo-doc) (\`${pmRunCommand(pm, "dev:zfb")}\` / \`${pmRunCommand(pm, "dev:history")}\` individually)`);
         lines.push(`- \`${pmRunCommand(pm, "dev:network")}\` — same, but zfb binds \`--host 0.0.0.0\` for LAN access (\`${pmRunCommand(pm, "dev:zfb:network")}\` individually); the doc-history server stays loopback-only and LAN clients reach it through zfb's \`/doc-history/*\` dev proxy`);
         lines.push(`- **Trusted networks only:** this also serves your git doc-history — including UNPUBLISHED local commits — to anyone on the LAN via the \`/doc-history/*\` proxy`);
-        lines.push(`- \`run-p\` swallows trailing args, so other zfb flags don't forward through \`${pmRunCommand(pm, "dev")}\` — pass them directly instead: \`${pm} run dev:zfb -- <flags>\``);
+        lines.push(`- \`run-parallel\` does not forward trailing args — it rejects them with an error rather than silently ignoring them, so pass other zfb flags directly instead: \`${pm} run dev:zfb -- <flags>\``);
     }
     else {
         lines.push(`- \`${pmRunCommand(pm, "dev")}\` — zfb dev server (port 4321)`);
@@ -114,7 +114,7 @@ export function generateCLAUDEFile(choices) {
         lines.push(`- ${defaultLabel} (default): \`/docs/...\` — content in \`src/content/docs/\``);
         lines.push(`- ${secondaryLabel}: \`/${secondaryLang}/docs/...\` — content in \`src/content/docs-${secondaryLang}/\``);
         lines.push(`- ${secondaryLabel} docs should mirror the ${defaultLabel} directory structure`);
-        lines.push(`- Both \`pages/docs/[[...slug]].tsx\` and \`pages/[locale]/docs/[[...slug]].tsx\` are self-contained doc-route stubs shipped by the generator — required so \`${pm} dev\` doesn't 404 on doc pages (a zfb dev-mode limitation on package-injected dynamic routes). Don't delete them.`);
+        lines.push(`- Both \`pages/docs/[[...slug]].tsx\` and \`pages/[locale]/docs/[[...slug]].tsx\` are self-contained doc-route stubs shipped by the generator as explicit host-owned seams. zfb 2.13.1 also renders package-injected dynamic routes in dev; keep these files so the generated project retains route ownership and customization.`);
         lines.push(``);
     }
     // Enabled features

package/dist/constants.js

@@ -331,6 +331,13 @@ export const FEATURES = [
         default: true,
         cliFlag: "image-enlarge",
     },
+    {
+        value: "assetViewer",
+        label: "Asset viewer",
+        hint: "Viewer pages for files under public/assets",
+        default: false,
+        cliFlag: "asset-viewer",
+    },
     {
         value: "dynamicPageTransition",
         label: "Dynamic page transition",

package/dist/features/asset-viewer.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureModule } from "../compose.js";
+/**
+ * Asset-viewer feature.
+ *
+ * Purely a `zudoDoc({ assetViewer: true })` field (see `zfb-config-gen.ts`).
+ * The scanner, viewer route, and all supporting UI are package-owned by
+ * `@takazudo/zudo-doc`; generated projects only need the config toggle.
+ * Nothing is injected or copied into the scaffold.
+ */
+export declare const assetViewerFeature: FeatureModule;

package/dist/features/asset-viewer.js

@@ -0,0 +1,12 @@
+/**
+ * Asset-viewer feature.
+ *
+ * Purely a `zudoDoc({ assetViewer: true })` field (see `zfb-config-gen.ts`).
+ * The scanner, viewer route, and all supporting UI are package-owned by
+ * `@takazudo/zudo-doc`; generated projects only need the config toggle.
+ * Nothing is injected or copied into the scaffold.
+ */
+export const assetViewerFeature = () => ({
+    name: "assetViewer",
+    injections: [],
+});

package/dist/features/doc-tags.d.ts

@@ -9,7 +9,7 @@ import type { FeatureModule } from "../compose.js";
  * since the host catch-all stubs were retired in favor of package
  * injection — there is nothing left to copy or postProcess.
  *
- * Known limitation: same injected-DYNAMIC-route dev-mode gap noted on the
- * versioning feature — the tag routes may 404 in `zfb dev` (build is fine).
+ * zfb 2.13.1 renders these injected tag routes in both dev and build. This
+ * feature has no host stubs because package injection owns the routes.
  */
 export declare const docTagsFeature: FeatureModule;

package/dist/features/doc-tags.js

@@ -8,8 +8,8 @@
  * since the host catch-all stubs were retired in favor of package
  * injection — there is nothing left to copy or postProcess.
  *
- * Known limitation: same injected-DYNAMIC-route dev-mode gap noted on the
- * versioning feature — the tag routes may 404 in `zfb dev` (build is fine).
+ * zfb 2.13.1 renders these injected tag routes in both dev and build. This
+ * feature has no host stubs because package injection owns the routes.
  */
 export const docTagsFeature = () => ({
     name: "docTags",

package/dist/features/i18n.d.ts

@@ -4,8 +4,8 @@ import type { FeatureModule } from "../compose.js";
  *
  * Locked manifest (#2653 Decision 4, i18n addendum): "i18n ON adds
  * `pages/[locale]/docs/[[...slug]].tsx` (a second doc stub, locale variant)
- * … No other pages." That ONE self-contained stub — required for the same
- * injected-DYNAMIC-route dev-mode 404 gap the default-locale stub fixes —
+ * … No other pages." That ONE self-contained stub — retained as an explicit
+ * host-owned route seam; zfb 2.13.1 also serves injected dynamic routes in dev —
  * is shipped under `templates/features/i18n/files/pages/[locale]/docs/`
  * and copied by `composeFeatures → copyFeatureFiles` whenever `i18n` is
  * selected. The old `pages/[locale]/index.tsx` home-route template is GONE

package/dist/features/i18n.js

@@ -6,8 +6,8 @@ import { fileURLToPath } from "url";
  *
  * Locked manifest (#2653 Decision 4, i18n addendum): "i18n ON adds
  * `pages/[locale]/docs/[[...slug]].tsx` (a second doc stub, locale variant)
- * … No other pages." That ONE self-contained stub — required for the same
- * injected-DYNAMIC-route dev-mode 404 gap the default-locale stub fixes —
+ * … No other pages." That ONE self-contained stub — retained as an explicit
+ * host-owned route seam; zfb 2.13.1 also serves injected dynamic routes in dev —
  * is shipped under `templates/features/i18n/files/pages/[locale]/docs/`
  * and copied by `composeFeatures → copyFeatureFiles` whenever `i18n` is
  * selected. The old `pages/[locale]/index.tsx` home-route template is GONE

package/dist/features/index.js

@@ -22,6 +22,7 @@ import { versioningFeature } from "./versioning.js";
 import { tauriFeature } from "./tauri.js";
 import { tauriDevFeature } from "./tauri-dev.js";
 import { imageEnlargeFeature } from "./image-enlarge.js";
+import { assetViewerFeature } from "./asset-viewer.js";
 import { dynamicPageTransitionFeature } from "./dynamic-page-transition.js";
 import { tagGovernanceFeature } from "./tag-governance.js";
 import { footerTaglistFeature } from "./footer-taglist.js";
@@ -50,6 +51,7 @@ export const featureModules = {
     tauri: tauriFeature,
     tauriDev: tauriDevFeature,
     imageEnlarge: imageEnlargeFeature,
+    assetViewer: assetViewerFeature,
     dynamicPageTransition: dynamicPageTransitionFeature,
     // skillSymlinker — handled in scaffold.ts
     // claudeSkills — handled in scaffold.ts (copies zudo-doc-* skills from monorepo)

package/dist/features/versioning.d.ts

@@ -9,11 +9,8 @@ import type { FeatureModule } from "../compose.js";
  * `renderDocPage` chrome. `templates/features/versioning/files/` has been
  * empty since #2390 — there is no host stub left to copy or postProcess.
  *
- * Known limitation (pre-existing, not introduced by the minimal-scaffold
- * cutover — inherited from the same injected-DYNAMIC-route dev-mode gap the
- * locked manifest's `pages/docs/[[...slug]].tsx` stub exists to fix for the
- * primary doc route, tracked as a #2667 follow-up): the versioned doc
- * routes may still 404 in `zfb dev` since versioning has no stub of its own
- * in the locked manifest. `zfb build` is unaffected.
+ * zfb 2.13.1 renders these injected version routes in both dev and build, so
+ * versioning needs no version-specific host stub. The primary and locale doc
+ * stubs remain explicit host-owned seams.
  */
 export declare const versioningFeature: FeatureModule;

package/dist/features/versioning.js

@@ -8,12 +8,9 @@
  * `renderDocPage` chrome. `templates/features/versioning/files/` has been
  * empty since #2390 — there is no host stub left to copy or postProcess.
  *
- * Known limitation (pre-existing, not introduced by the minimal-scaffold
- * cutover — inherited from the same injected-DYNAMIC-route dev-mode gap the
- * locked manifest's `pages/docs/[[...slug]].tsx` stub exists to fix for the
- * primary doc route, tracked as a #2667 follow-up): the versioned doc
- * routes may still 404 in `zfb dev` since versioning has no stub of its own
- * in the locked manifest. `zfb build` is unaffected.
+ * zfb 2.13.1 renders these injected version routes in both dev and build, so
+ * versioning needs no version-specific host stub. The primary and locale doc
+ * stubs remain explicit host-owned seams.
  */
 export const versioningFeature = () => ({
     name: "versioning",

package/dist/scaffold.d.ts

@@ -32,5 +32,5 @@ export declare function deriveDocSkillName(projectName: string): string;
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^5.13.1";
+export declare const ZUDO_DOC_PIN = "^5.14.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -43,7 +43,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.13.1";
+export const ZUDO_DOC_PIN = "^5.14.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -715,15 +715,15 @@ function generatePackageJson(choices) {
         // one CSS entrypoint without route discovery or page rendering, and fixes
         // a Back race before ClientRouter DOM swaps. Both changes are additive
         // tooling/runtime behavior; a fresh scaffold needs no config migration.
-        // 2.13.1: toolchain-only. The published JS tarballs for `@takazudo/zfb`,
-        // `zfb-runtime`, and `zfb-adapter-cloudflare` differ from 2.12.0 in their
-        // package.json version fields alone — 2.13.0 made CI-attested publishing
-        // the default, and 2.13.1's livereload bfcache-lifecycle fix lives in the
-        // per-platform Rust binary. `zfb-md-wasm` rebuilt its WASM with a
-        // byte-identical export surface. No generator-side migration.
-        "@takazudo/zfb": "2.13.1",
-        "@takazudo/zfb-runtime": "2.13.1",
-        "@takazudo/zfb-md-wasm": "2.13.1",
+        // 2.14.0: additive behavior and bug fixes. zfb can bundle authored CSS
+        // imports when Tailwind is off, scans claimed root-package CSS sources,
+        // and adds the optional `strictPlainCssImports` flag (default false).
+        // Parser fixes also ship in zfb-md-wasm; runtime and the Cloudflare adapter
+        // have no package-specific behavior change. Public exports and engine
+        // requirements stay unchanged, so a fresh scaffold needs no migration.
+        "@takazudo/zfb": "2.14.0",
+        "@takazudo/zfb-runtime": "2.14.0",
+        "@takazudo/zfb-md-wasm": "2.14.0",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -735,6 +735,13 @@ function generatePackageJson(choices) {
         // ties this pin to packages/zudo-doc's version, so the lockstep release
         // bumps both together; do not cut a create-zudo-doc release until the
         // matching @takazudo/zudo-doc version (with content.css) is on npm.
+        // RELEASE DEPENDENCY (same shape as the content.css one above): the
+        // docHistory `dev`/`dev:network` scripts now invoke `run-parallel`, a bin
+        // added to @takazudo/zudo-doc in this monorepo but NOT present in published
+        // 5.13.1. `^5.13.1` floats up, so a fresh install resolves the bumped
+        // version — but do not cut a create-zudo-doc release until a
+        // @takazudo/zudo-doc that ships bin/run-parallel.mjs is on npm, or every
+        // docHistory scaffold fails at `dev` with `run-parallel: not found`.
         // ZUDO_DOC_PIN is the shared constant — scaffold() uses the same value
         // to seed .zudo-doc.json so the provenance and the dep can never drift.
         "@takazudo/zudo-doc": ZUDO_DOC_PIN,
@@ -796,9 +803,9 @@ function generatePackageJson(choices) {
         // same reason. This is the ACCEPTED, permanent contract per #2668 — see
         // the "@takazudo/zdtp dep implication" note in
         // packages/zudo-doc/docs/adr/route-injection-seam.md.
-        "@takazudo/zdtp": "0.4.12",
+        "@takazudo/zdtp": "0.4.14",
         // (@takazudo/zudo-doc-history-server is NOT here — it is gated on the
-        // docHistory feature, see the block below. It was briefly unconditional
+        // docHistory or assetViewer features, see the block below. It was briefly unconditional
         // (#3080) to work around doc-history-area importing its `/exclude` subpath
         // at module scope; that root cause was fixed in #3110 by moving
         // compileExclude into @takazudo/zudo-doc itself, so the workaround is gone
@@ -824,36 +831,31 @@ function generatePackageJson(choices) {
     // search ships as @takazudo/zudo-doc's own self-contained generated
     // search-widget script (custom word-match scorer) — no third-party search
     // engine dependency is needed here. Do not re-add minisearch/pagefind.
-    if (choices.features.includes("docHistory")) {
+    if (choices.features.includes("docHistory") ||
+        choices.features.includes("assetViewer")) {
         // (`diff` remains an unconditional base dep — see the `deps` block above:
         // packageOwnedRoutes always bundles the doc-history-area path, whose
         // module-scope `diff` import is pulled in regardless of this flag. #2342.)
         //
-        // @takazudo/zudo-doc-history-server is gated HERE, on the feature, because
-        // that is the only graph that actually reaches it: the zfb plugin
-        // (@takazudo/zudo-doc/plugins/doc-history) eagerly imports
-        // @takazudo/zudo-doc-history-server/git-history at plugin-init time, and the
-        // plugin is only wired when docHistory is on (W8A #1739). It is an optional
-        // peerDependency of @takazudo/zudo-doc and pnpm does not auto-install peers,
-        // so a docHistory-ON project must declare it directly. The pin stays lockstep
+        // @takazudo/zudo-doc-history-server is gated HERE because docHistory and
+        // assetViewer are the only feature graphs that reach it. The doc-history
+        // plugin imports `/git-history` at plugin-init time; the asset viewer loads
+        // that same subpath lazily to populate Created/Updated/Author metadata.
+        // It is an optional peerDependency of @takazudo/zudo-doc and is not
+        // auto-installed for those feature graphs, so either feature must declare
+        // it directly. The pin stays lockstep
         // with the root version (parity-guarded — INTERNAL_PINNED_PACKAGES in
         // scripts/check-pin-parity.mjs, and rewritten at release time by
         // scripts/release-create-zudo-doc.sh step 2d).
         //
         // It was briefly unconditional (#3080) because doc-history-area imported
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
-        // moved compileExclude into @takazudo/zudo-doc, so docHistory-OFF projects
-        // no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^5.13.1";
+        // moved compileExclude into @takazudo/zudo-doc, so projects with both
+        // docHistory and assetViewer off no longer need the package at all.
+        deps["@takazudo/zudo-doc-history-server"] = "^5.14.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).
-        // npm-run-all2 provides `run-p`, used by the docHistory `dev` script
-        // (below) to run the zfb dev server and the doc-history API server
-        // concurrently — otherwise the :4322 proxy target never starts and the
-        // feature silently looks broken (#2926). Same maintained fork/pin this
-        // monorepo's own root package.json uses.
-        devDeps["npm-run-all2"] = "^7.0.2";
     }
     // claudeResources: tsx is no longer needed. The relocated package plugin
     // (@takazudo/zudo-doc/plugins/claude-resources) imports the runner directly
@@ -879,20 +881,25 @@ function generatePackageJson(choices) {
         // running concurrently — otherwise the Created/Updated/Author block
         // silently never appears in dev (#2926). `doc-history-server` is the bin
         // shipped by the @takazudo/zudo-doc-history-server dep added above;
-        // `run-p` (npm-run-all2, added to devDependencies above) runs both.
-        scripts.dev = "run-p dev:zfb dev:history";
+        // `run-parallel` runs both. It is a bin shipped by @takazudo/zudo-doc — an
+        // unconditional dep added above — so concurrency costs this project no extra
+        // devDependency. It replaced npm-run-all2's `run-p`, which was the sole
+        // source of four advisories (shell-quote DoS; brace-expansion@2 DoS x3).
+        scripts.dev = "run-parallel dev:zfb dev:history";
         scripts["dev:zfb"] = "zfb dev";
-        // run-p swallows trailing args and npm-run-all2 v7's `{@}` placeholder
-        // strips flag names, so `pnpm dev -- --host 0.0.0.0` is silently ignored
-        // (verified in issue #2940) — dev:network is a dedicated LAN-bound script
+        // Neither runner forwards trailing args, but they differ in how loudly: run-p
+        // SILENTLY ignored `pnpm dev -- --host 0.0.0.0` (verified in issue #2940),
+        // whereas run-parallel rejects it with an error naming the remedy — silence
+        // about a flag the user clearly meant is the "quiet lie" #3129 argues against.
+        // Either way dev:network is the LAN-bound script
         // instead. Only zfb binds 0.0.0.0; the history server stays loopback-only
         // and LAN clients reach it through zfb's `/doc-history/*` dev proxy.
         scripts["dev:zfb:network"] = "zfb dev --host 0.0.0.0";
-        scripts["dev:network"] = "run-p dev:zfb:network dev:history";
+        scripts["dev:network"] = "run-parallel dev:zfb:network dev:history";
         // Relative --content-dir/--locale paths are resolved by resolveContentPath
         // (packages/doc-history-server/src/args.ts) against INIT_CWD (falling back
         // to process.cwd()) — correct for the supported invocation (`<pm> dev` /
-        // `<pm> run dev` from the project root, which is what run-p's child
+        // `<pm> run dev` from the project root, which is what run-parallel's child
         // processes inherit). It resolves against the WRONG directory only if this
         // generated project is itself nested inside a larger pnpm/npm workspace
         // and dev:history is invoked via `<pm> --filter <this-package> ...` from

package/dist/zfb-config-gen.js

@@ -62,6 +62,11 @@ export const DEFAULT_MIRROR = {
     dynamicPageTransition: false,
     docHistory: false,
     docHistoryExclude: [],
+    assetViewer: false,
+    assetViewerDir: "assets",
+    assetViewerRoutePrefix: "files",
+    assetViewerExclude: [],
+    assetViewerIndex: false,
     bodyFootUtilArea: false,
     versions: false,
     claudeResources: false,
@@ -230,6 +235,7 @@ function buildDesiredConfig(choices) {
     desired.findInPage = choices.features.includes("tauri");
     desired.dynamicPageTransition = choices.features.includes("dynamicPageTransition");
     desired.docHistory = choices.features.includes("docHistory");
+    desired.assetViewer = choices.features.includes("assetViewer");
     if (choices.features.includes("bodyFootUtil")) {
         desired.bodyFootUtilArea = {
             docHistory: choices.features.includes("docHistory"),
@@ -391,6 +397,11 @@ const FIELD_ORDER = [
     "findInPage",
     "dynamicPageTransition",
     "docHistory",
+    "assetViewer",
+    "assetViewerDir",
+    "assetViewerRoutePrefix",
+    "assetViewerExclude",
+    "assetViewerIndex",
     "bodyFootUtilArea",
     "versions",
     "claudeResources",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "5.13.1",
+  "version": "5.14.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/docs/[[...slug]].tsx

@@ -1,10 +1,8 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locked manifest (#2653 Decision 4): a SELF-CONTAINED doc-route stub —
-// REQUIRED because the injected DYNAMIC `/docs/[[...slug]]` route 404s in
-// `zfb dev` (real pre-existing gap in zfb's dev-mode dynamic-route rendering,
-// distinct from the `/`-injection gap zfb#1227; empirically confirmed on
-// #2653). This stub reconstructs the doc route from scratch using ONLY the
+// Locked manifest (#2653 Decision 4): a SELF-CONTAINED doc-route stub retained
+// for explicit host route ownership. zfb 2.13.1 also serves injected dynamic
+// routes in dev. This stub reconstructs the doc route from scratch using ONLY the
 // sanctioned package entrypoints — no `pages/lib`, no `@/config`:
 //   1. the `virtual:zudo-doc-route-context` virtual module (serializable
 //      settings/translations/tagVocabulary/colorSchemes payload),
@@ -14,9 +12,9 @@
 // The bindings import is unconditional: the routes plugin supplies an empty
 // object when `chromeBindingsModule` is unset, while configured projects get
 // their MDX/chrome bindings without editing this stub.
-// Makes `/docs/getting-started/` return 200 in BOTH `zfb dev` and `zfb build`
-// (see the "TM negative guard" case in route-injection-build.slow.test.ts for
-// the no-stub 404 proof this fixes).
+// Makes `/docs/getting-started/` return 200 in BOTH `zfb dev` and `zfb build`.
+// The route-injection build test covers the corresponding package-owned route;
+// this kept file remains the explicit host-owned seam.
 //
 // docHistory note: when the docHistory feature is selected, the generator
 // patches this file to statically import DocHistory from

package/templates/base/scripts/check-links.js

@@ -425,14 +425,34 @@ export async function parseContentDirs(configPath) {
 // Shared link and anchor logic
 // ---------------------------------------------------------------------------
 
+const HTML_NAMED_CHARACTER_REFERENCES = {
+  amp: "&",
+  apos: "'",
+  gt: ">",
+  lt: "<",
+  quot: '"',
+};
+
+function decodeHtmlAttributeValue(value) {
+  return value.replace(
+    /&(?:#([0-9]+)|#x([0-9a-f]+)|(amp|apos|gt|lt|quot));/gi,
+    (_reference, decimal, hexadecimal, named) => {
+      if (named !== undefined) return HTML_NAMED_CHARACTER_REFERENCES[named.toLowerCase()];
+      const codePoint = Number.parseInt(hexadecimal ?? decimal, hexadecimal === undefined ? 10 : 16);
+      if (codePoint === 0 || codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) return "\uFFFD";
+      return String.fromCodePoint(codePoint);
+    },
+  );
+}
+
 export function extractHtmlLinks(html) {
   const links = [];
-  const regex = /<a\s[^>]*?href=(?:"([^"]*)"|'([^']*)')[^>]*>/gi;
+  const regex = /<a(?=\s)[^>]*?\shref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))[^>]*>/gi;
   let match;
   let lastIndex = 0;
   let line = 1;
   while ((match = regex.exec(html)) !== null) {
-    const href = match[1] ?? match[2];
+    const href = decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]);
     if (/^(?:https?:|mailto:|javascript:|data:|tel:)/i.test(href)) continue;
     for (let i = lastIndex; i < match.index; i += 1) if (html[i] === "\n") line += 1;
     lastIndex = match.index;
@@ -441,6 +461,16 @@ export function extractHtmlLinks(html) {
   return links;
 }
 
+export function extractHtmlIds(html) {
+  const ids = [];
+  const regex = /<[A-Za-z][^>]*?\sid\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))[^>]*>/gi;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    ids.push(decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]));
+  }
+  return ids;
+}
+
 function safeDecodePath(path) {
   try {
     return decodeURIComponent(path);
@@ -455,12 +485,12 @@ function parseHref(href) {
   const queryAt = beforeFragment.indexOf("?");
   const rawPath = queryAt === -1 ? beforeFragment : beforeFragment.slice(0, queryAt);
   const rawFragment = hashAt === -1 ? null : href.slice(hashAt + 1);
-  if (rawFragment === null) return { path: safeDecodePath(rawPath), fragment: null, fragmentError: null };
-  if (rawFragment === "") return { path: safeDecodePath(rawPath), fragment: "", fragmentError: "empty fragment" };
+  if (rawFragment === null) return { path: safeDecodePath(rawPath), rawPath, fragment: null, fragmentError: null };
+  if (rawFragment === "") return { path: safeDecodePath(rawPath), rawPath, fragment: "", fragmentError: "empty fragment" };
   try {
-    return { path: safeDecodePath(rawPath), fragment: decodeURIComponent(rawFragment), fragmentError: null };
+    return { path: safeDecodePath(rawPath), rawPath, fragment: decodeURIComponent(rawFragment), fragmentError: null };
   } catch {
-    return { path: safeDecodePath(rawPath), fragment: rawFragment, fragmentError: "malformed percent-encoding" };
+    return { path: safeDecodePath(rawPath), rawPath, fragment: rawFragment, fragmentError: "malformed percent-encoding" };
   }
 }
 
@@ -646,23 +676,40 @@ export async function checkMdxAnchors(contentDirs, rootDir, basePath = "/", loca
   return anchors;
 }
 
-async function resolveDistTarget(href, distDir, basePath = "/", fileDir = "", sourceFile = null) {
-  const { path: clean, fragment, fragmentError } = parseHref(href);
-  if (!clean) return { type: "root", targetFile: sourceFile ?? join(distDir, "index.html"), fragment, fragmentError };
-  let absolute = clean;
-  if (!clean.startsWith("/")) absolute = "/" + join(fileDir ? relative(distDir, fileDir) : "", clean);
+async function resolveBuiltPath(path, distDir, basePath, fileDir) {
+  let absolute = path;
+  if (!path.startsWith("/")) absolute = "/" + join(fileDir ? relative(distDir, fileDir) : "", path);
   let stripped = absolute;
   if (basePath !== "/" && stripped.startsWith(basePath)) stripped = "/" + stripped.slice(basePath.length);
   const relPath = stripped.startsWith("/") ? stripped.slice(1) : stripped;
-  if (!relPath) return { type: "root", targetFile: join(distDir, "index.html"), fragment, fragmentError };
+  if (!relPath) return { type: "root", targetFile: join(distDir, "index.html") };
+  // A terminal slash is an explicit directory request, even when the
+  // directory name contains a dot (for example, /files/demo/x.js/). Check it
+  // before extname() so viewer pages can keep their trailing-slash route and
+  // still receive fragment validation against index.html.
+  if (relPath.endsWith("/")) {
+    const indexFile = join(distDir, relPath, "index.html");
+    return (await fileExists(indexFile)) ? { type: "directoryIndex", targetFile: indexFile } : { type: "missing", targetFile: null };
+  }
   if (extname(relPath)) {
     const targetFile = join(distDir, relPath);
-    return { type: (await fileExists(targetFile)) ? "file" : "missing", targetFile, fragment, fragmentError };
+    return (await fileExists(targetFile)) ? { type: "file", targetFile } : { type: "missing", targetFile: null };
   }
   const indexFile = join(distDir, relPath, "index.html");
-  if (await fileExists(indexFile)) return { type: "directoryIndex", targetFile: indexFile, fragment, fragmentError };
+  if (await fileExists(indexFile)) return { type: "directoryIndex", targetFile: indexFile };
   const htmlFile = join(distDir, relPath + ".html");
-  if (await fileExists(htmlFile)) return { type: "file", targetFile: htmlFile, fragment, fragmentError };
+  if (await fileExists(htmlFile)) return { type: "file", targetFile: htmlFile };
+  return { type: "missing", targetFile: null };
+}
+
+async function resolveDistTarget(href, distDir, basePath = "/", fileDir = "", sourceFile = null) {
+  const { path: decodedPath, rawPath, fragment, fragmentError } = parseHref(href);
+  if (!rawPath) return { type: "root", targetFile: sourceFile ?? join(distDir, "index.html"), fragment, fragmentError };
+  const pathCandidates = rawPath === decodedPath ? [rawPath] : [rawPath, decodedPath];
+  for (const path of pathCandidates) {
+    const detail = await resolveBuiltPath(path, distDir, basePath, fileDir);
+    if (detail.type !== "missing") return { ...detail, fragment, fragmentError };
+  }
   return { type: "missing", targetFile: null, fragment, fragmentError };
 }
 
@@ -686,9 +733,19 @@ export async function checkHtmlLinksAndTrailing(
   const trailingSlash = [];
   const idCache = new Map();
   const cache = new Map();
+  const pages = [];
+  const scanned = { links: 0, ids: 0 };
   for (const file of await collectFiles(distDir, [".html"])) {
     const content = await readFile(file, "utf-8");
-    for (const { href, line } of extractHtmlLinks(content)) {
+    const links = extractHtmlLinks(content);
+    const ids = extractHtmlIds(content);
+    scanned.links += links.length;
+    scanned.ids += ids.length;
+    idCache.set(file, new Set(ids));
+    pages.push({ file, links });
+  }
+  for (const { file, links } of pages) {
+    for (const { href, line } of links) {
       if (excludePatterns.some((pattern) => pattern.test(href))) continue;
       const cacheKey = href.startsWith("/") ? href : `${file}:${href}`;
       let detail = cache.get(cacheKey);
@@ -703,10 +760,9 @@ export async function checkHtmlLinksAndTrailing(
           let ids = idCache.get(detail.targetFile);
           if (ids === undefined) {
             const targetHtml = await readFile(detail.targetFile, "utf-8");
-            ids = new Set();
-            const idRegex = /\bid\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
-            let idMatch;
-            while ((idMatch = idRegex.exec(targetHtml)) !== null) ids.add(idMatch[1] ?? idMatch[2]);
+            const targetIds = extractHtmlIds(targetHtml);
+            scanned.ids += targetIds.length;
+            ids = new Set(targetIds);
             idCache.set(detail.targetFile, ids);
           }
           if (!ids.has(detail.fragment)) reason = "missing target id";
@@ -721,7 +777,7 @@ export async function checkHtmlLinksAndTrailing(
       }
     }
   }
-  return { broken, anchors, trailingSlash };
+  return { broken, anchors, trailingSlash, scanned };
 }
 
 export async function checkMdxLinks(
@@ -796,8 +852,8 @@ async function main() {
   console.log(`Checking links (base: ${config.basePath}, trailingSlash: ${config.trailingSlash})...`);
   console.log(`Source scan: ${contentDirs.map((dir) => relative(rootDir, dir) || ".").join(", ")}${hasDist ? "; dist/ pass enabled" : "; dist/ absent (source-only)"}\n`);
 
-  const [{ broken, anchors: htmlAnchors, trailingSlash }, mdxWarnings, mdxAnchors] = await Promise.all([
-    hasDist ? checkHtmlLinksAndTrailing(distDir, rootDir, config.basePath, excludePatterns, config.trailingSlash) : Promise.resolve({ broken: [], anchors: [], trailingSlash: [] }),
+  const [{ broken, anchors: htmlAnchors, trailingSlash, scanned }, mdxWarnings, mdxAnchors] = await Promise.all([
+    hasDist ? checkHtmlLinksAndTrailing(distDir, rootDir, config.basePath, excludePatterns, config.trailingSlash) : Promise.resolve({ broken: [], anchors: [], trailingSlash: [], scanned: { links: 0, ids: 0 } }),
     checkMdxLinks(contentDirs, rootDir, hasDist ? distDir : null, config.basePath, config.localeKeys),
     checkMdxAnchors(contentDirs, rootDir, config.basePath, config.localeKeys, excludePatterns),
   ]);
@@ -810,6 +866,7 @@ async function main() {
   const realAnchors = filter(anchorWarnings);
   const realTrailing = filter(trailingSlash);
   console.log(formatReport(broken, mdxWarnings, trailingSlash, anchorWarnings));
+  if (hasDist) console.log(`\nBuilt HTML scan: ${scanned.links} internal link${scanned.links === 1 ? "" : "s"} and ${scanned.ids} ID attribute${scanned.ids === 1 ? "" : "s"} inspected.`);
   const skipped = broken.length - realBroken.length + mdxWarnings.length - realAbsolute.length + anchorWarnings.length - realAnchors.length + trailingSlash.length - realTrailing.length;
   if (skipped > 0) console.log(`\nAllowlist: ${skipped} known exception${skipped === 1 ? "" : "s"} excluded from strict-mode counts (${allowlistPath}).`);
   let failed = false;

package/templates/features/i18n/files/pages/[locale]/docs/[[...slug]].tsx

@@ -1,8 +1,8 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 // Locked manifest (#2653 Decision 4, i18n addendum): the locale-prefixed
-// counterpart of pages/docs/[[...slug]].tsx — required for the same reason
-// (injected DYNAMIC routes 404 in `zfb dev`). Self-contained: only the
+// counterpart of pages/docs/[[...slug]].tsx, retained for explicit host route
+// ownership; zfb 2.13.1 also serves injected dynamic routes in dev. Self-contained: only the
 // sanctioned package entrypoints — no `pages/lib`, no `@/config`. The
 // `virtual:zudo-doc-chrome-bindings` import is unconditional, just like the
 // default-locale stub: the routes plugin supplies `{}` when no host module is