npm - @takazudo/zfb-runtime - Versions diffs - 0.1.0-next.9 → 0.1.0-next.90 - Mend

@takazudo/zfb-runtime 0.1.0-next.9 → 0.1.0-next.90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/CHANGELOG.md +6 -0
package/README.md +220 -15
package/dist/client-router/events.d.ts +0 -1
package/dist/client-router/events.js +2 -2
package/dist/client-router/events.js.map +1 -1
package/dist/client-router/index.d.ts +2 -3
package/dist/client-router/index.js +2 -2
package/dist/client-router/index.js.map +1 -1
package/dist/client-router/prefetch.d.ts +0 -1
package/dist/client-router/prefetch.js +126 -53
package/dist/client-router/prefetch.js.map +1 -1
package/dist/client-router/router.d.ts +28 -2
package/dist/client-router/router.js +364 -30
package/dist/client-router/router.js.map +1 -1
package/dist/client-router/swap-functions.d.ts +0 -1
package/dist/client-router/swap-functions.js +71 -11
package/dist/client-router/swap-functions.js.map +1 -1
package/dist/client-router/types.d.ts +4 -1
package/dist/client-router/types.js.map +1 -1
package/dist/client-router.d.ts +38 -2
package/dist/client-router.js +56 -20
package/dist/client-router.js.map +1 -1
package/dist/framework.d.ts +0 -1
package/dist/framework.js.map +1 -1
package/dist/index.d.ts +2 -4
package/dist/index.js +13 -4
package/dist/index.js.map +1 -1
package/dist/router.d.ts +32 -2
package/dist/router.js +163 -33
package/dist/router.js.map +1 -1
package/dist/server.d.ts +2 -0
package/dist/server.js +14 -0
package/dist/server.js.map +1 -0
package/dist/snapshot.d.ts +0 -1
package/dist/snapshot.js +3 -2
package/dist/snapshot.js.map +1 -1
package/dist/view-transitions.d.ts +0 -1
package/dist/view-transitions.js.map +1 -1
package/package.json +26 -4
package/dist/client-router/cssesc.d.ts +0 -9
package/dist/client-router/cssesc.d.ts.map +0 -1
package/dist/client-router/cssesc.js +0 -95
package/dist/client-router/cssesc.js.map +0 -1
package/dist/client-router/events.d.ts.map +0 -1
package/dist/client-router/index.d.ts.map +0 -1
package/dist/client-router/prefetch.d.ts.map +0 -1
package/dist/client-router/router.d.ts.map +0 -1
package/dist/client-router/swap-functions.d.ts.map +0 -1
package/dist/client-router/types.d.ts.map +0 -1
package/dist/client-router.d.ts.map +0 -1
package/dist/framework.d.ts.map +0 -1
package/dist/index.d.ts.map +0 -1
package/dist/router.d.ts.map +0 -1
package/dist/snapshot.d.ts.map +0 -1
package/dist/view-transitions.d.ts.map +0 -1

package/dist/client-router.js CHANGED Viewed

@@ -12,21 +12,29 @@
 //   via `init()`. The component calls `init()` as a side effect on first import.
 //   No inline <script> dangerouslySetInnerHTML is emitted.
 //
-// Named-cause deviation — no JSX (W1B: "follow existing component-emission pattern"):
-//   `@takazudo/zfb-runtime` does not depend on Preact and has no JSX compiler
-//   options configured in its tsconfig. The existing component-emission pattern
-//   (established by `Island` in @takazudo/zfb, and `ViewTransitions` in this
-//   package) uses plain VNode-shaped objects with `constructor: undefined` — the
-//   sentinel recognised by both Preact and React renderers. Following that pattern
-//   avoids adding Preact as a dependency and avoids tsconfig JSX changes.
+// Framework-agnostic element minting (no JSX syntax):
+//   `@takazudo/zfb-runtime` does not depend on a framework runtime. Head nodes
+//   are minted by calling `jsx` from `react/jsx-runtime` directly — NOT JSX
+//   syntax, so this stays a plain `.ts` file with no tsconfig JSX changes. The
+//   engine alias-rewrites `react/jsx-runtime` → `preact/jsx-runtime` in Preact
+//   mode (bundler.rs ~2886) and resolves it natively in React mode, so the same
+//   call mints a real element for whichever framework the project configured.
+//   The previous approach (a hand-rolled `{ type, props, key, constructor:
+//   undefined }` object literal — the Preact diff-path sentinel) only worked for
+//   Preact: React's renderer rejects such an object as a child with React error
+//   #31 ("Objects are not valid as a React child"), because a real React element
+//   carries `$$typeof: Symbol.for("react.element")` a literal cannot fake. Same
+//   migration as `Island` in @takazudo/zfb.
 //
-// The component renders three sibling elements to <head>:
+// The component renders three base sibling elements to <head> (plus optional
+// metas emitted conditionally — see `prefetchDisabled` and `preserveHtmlAttrs`):
 //   1. A <style> tag with the `.zfb-route-announcer` ARIA helper class.
 //   2. <meta name="zfb-view-transitions-enabled" content="true" />
 //   3. <meta name="zfb-view-transitions-fallback" content={fallback} />
 //
 // The route-announcer <div> is injected into <body> by `announce()` in
 // `client-router/router.ts` on every navigation.
+import { jsx } from "react/jsx-runtime";
 import { init } from "./client-router/router.js";
 import { init as prefetchInit } from "./client-router/prefetch.js";
 // Side-effect: wire click + submit intercepts on first import of this component.
@@ -39,14 +47,23 @@ if (typeof document !== "undefined") {
 // lifetime even if <ClientRouter prefetchAll /> is mounted multiple times (#276).
 let prefetchBootstrapped = false;
 /**
- * Construct a VNode-shaped object. Sets `constructor: undefined` so that both
- * Preact's and React's renderers treat it as a structural VNode rather than
- * foreign data. (Mirrors the `makeVNode` pattern in `@takazudo/zfb`'s Island.)
+ * Mint a head element through the per-project JSX runtime.
+ *
+ * Calls `jsx` from `react/jsx-runtime` (alias-rewritten to
+ * `preact/jsx-runtime` in Preact mode by the engine, native in React mode)
+ * so the returned value is a real element for whichever framework the
+ * project configured — NOT a hand-rolled `{ type, props, key }` literal,
+ * which only Preact accepts and which makes React throw error #31. A stable
+ * `key` is passed because `ClientRouter()` returns these nodes in a plain
+ * array (React warns about keyless list children otherwise). Mirrors the
+ * `Island` migration in `@takazudo/zfb`.
  */
-function makeVNode(type, props) {
-    const v = { type, props, key: null };
-    v.constructor = undefined;
-    return v;
+function makeVNode(type, props, key) {
+    // `jsx`'s `type` param is typed `ElementType` (string-literal intrinsic
+    // tags or component types), which rejects an arbitrary runtime `string`.
+    // The tag is dynamic here, so cast to the factory's own first-param type —
+    // robust whether the engine aliases `jsx` to react or preact at build time.
+    return jsx(type, props, key);
 }
 // CSS for the route-announcer element. Ported verbatim from Astro's
 // `<style is:global>` block in ClientRouter.astro (lines 11–23), renaming
@@ -81,7 +98,7 @@ const announcerCss = `
  * <ClientRouter fallback="animate" />
  * ```
  */
-export function ClientRouter({ fallback = "animate", prefetchAll: prefetchAllProp = false, } = {}) {
+export function ClientRouter({ fallback = "animate", prefetchAll: prefetchAllProp = false, preserveHtmlAttrs = [], traverseRefetch = false, } = {}) {
     // Bootstrap prefetch exactly once on the client when prefetchAll is true.
     // The initialized flag inside prefetchInit() provides a second safety layer
     // in case of concurrent hydration or manual callers (#276).
@@ -91,11 +108,11 @@ export function ClientRouter({ fallback = "animate", prefetchAll: prefetchAllPro
     }
     const nodes = [
         // Global styles for the ARIA route-announcer div injected into <body>.
-        makeVNode("style", { dangerouslySetInnerHTML: { __html: announcerCss } }),
+        makeVNode("style", { dangerouslySetInnerHTML: { __html: announcerCss } }, "zfb-vt-style"),
         // Opt-in meta tag: router checks for this to decide whether to intercept navigations.
-        makeVNode("meta", { name: "zfb-view-transitions-enabled", content: "true" }),
+        makeVNode("meta", { name: "zfb-view-transitions-enabled", content: "true" }, "zfb-vt-enabled"),
         // Fallback strategy meta tag: read by getFallback() in router.ts.
-        makeVNode("meta", { name: "zfb-view-transitions-fallback", content: fallback }),
+        makeVNode("meta", { name: "zfb-view-transitions-fallback", content: fallback }, "zfb-vt-fallback"),
     ];
     // Prefetch-disabled meta tag (#277): emitted when the bundler set
     // `globalThis.__zfb.prefetchDisabled = true` (from `zfb.config.ts`
@@ -110,7 +127,26 @@ export function ClientRouter({ fallback = "animate", prefetchAll: prefetchAllPro
     // Pin the contract verbatim — the attribute names and content value are
     // shared with the sibling prefetch-core sub-issue (#276).
     if (globalThis.__zfb?.prefetchDisabled === true) {
-        nodes.push(makeVNode("meta", { name: "zfb-prefetch-disabled", content: "true" }));
+        nodes.push(makeVNode("meta", { name: "zfb-prefetch-disabled", content: "true" }, "zfb-prefetch-disabled"));
+    }
+    // Consumer-extensible <html> attribute preserve-list (#1103). swapRootAttributes
+    // reads this meta and re-applies the listed attributes' runtime values after each
+    // swap, so persisted-island state on <html> (data-theme, data-sidebar-hidden, …)
+    // survives navigation. Emitted only when non-empty, so non-opt-in output stays
+    // byte-identical. Same conditional-emission shape as the prefetch-disabled meta.
+    const preserveList = preserveHtmlAttrs.filter(Boolean);
+    if (preserveList.length > 0) {
+        nodes.push(makeVNode("meta", { name: "zfb-preserve-html-attrs", content: preserveList.join(" ") }, "zfb-preserve-html-attrs"));
+    }
+    // Traverse-refetch opt-out meta (#1376). A same-page Back/Forward traversal
+    // skips the re-fetch/re-swap by default (the router's traverse fast-path);
+    // this meta opts a per-request SSR page (`prerender = false`) back INTO the
+    // fetch, since skipping it would pin stale server-rendered content. Emitted
+    // only when opted in, so non-opt-in output stays byte-identical. Same
+    // conditional-emission shape as the prefetch-disabled / preserve-html-attrs
+    // metas; the router reads meta[name="zfb-traverse-refetch"][content="true"].
+    if (traverseRefetch) {
+        nodes.push(makeVNode("meta", { name: "zfb-traverse-refetch", content: "true" }, "zfb-traverse-refetch"));
     }
     return nodes;
 }

package/dist/client-router.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"client-router.js","sourceRoot":"","sources":["../src/client-router.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,wDAAwD;AACxD,uDAAuD;AACvD,yEAAyE;AACzE,EAAE;AACF,2DAA2D;AAC3D,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,iFAAiF;AACjF,2DAA2D;AAC3D,EAAE;AACF,sFAAsF;AACtF,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,iFAAiF;AACjF,mFAAmF;AACnF,0EAA0E;AAC1E,EAAE;AACF,0DAA0D;AAC1D,wEAAwE;AACxE,mEAAmE;AACnE,wEAAwE;AACxE,EAAE;AACF,uEAAuE;AACvE,iDAAiD;AAEjD,OAAO,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AACjD,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEnE,iFAAiF;AACjF,gFAAgF;AAChF,oEAAoE;AACpE,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;IACpC,IAAI,EAAE,CAAC;AACT,CAAC;AAED,8EAA8E;AAC9E,kFAAkF;AAClF,IAAI,oBAAoB,GAAG,KAAK,CAAC;AAuBjC;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,KAA8B;IAC7D,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAKjC,CAAC;IACF,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAwB,CAAC;AAClC,CAAC;AAED,oEAAoE;AACpE,0EAA0E;AAC1E,gEAAgE;AAChE,uEAAuE;AACvE,+EAA+E;AAC/E,MAAM,YAAY,GAAG;;;;;;;;;;;;CAYpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,QAAQ,GAAG,SAAS,EACpB,WAAW,EAAE,eAAe,GAAG,KAAK,MACf,EAAE;IACvB,0EAA0E;IAC1E,4EAA4E;IAC5E,4DAA4D;IAC5D,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,eAAe,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAChF,oBAAoB,GAAG,IAAI,CAAC;QAC5B,YAAY,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,KAAK,GAA0B;QACnC,uEAAuE;QACvE,SAAS,CAAC,OAAO,EAAE,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,CAAC;QACzE,sFAAsF;QACtF,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAC5E,kEAAkE;QAClE,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,+BAA+B,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;KAChF,CAAC;IAEF,kEAAkE;IAClE,mEAAmE;IACnE,0EAA0E;IAC1E,iFAAiF;IACjF,gDAAgD;IAChD,EAAE;IACF,yEAAyE;IACzE,+EAA+E;IAC/E,iBAAiB;IACjB,EAAE;IACF,wEAAwE;IACxE,0DAA0D;IAC1D,IAAK,UAAyD,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAChG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
1	+ {"version":3,"file":"client-router.js","sourceRoot":"","sources":["../src/client-router.ts"],"names":[],"mappings":"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","sourcesContent":["// `@takazudo/zfb-runtime` — `<ClientRouter />` component.\n//\n// Ported from Astro's `ClientRouter.astro` (155 lines).\n// Source: packages/astro/components/ClientRouter.astro\n// Issue: zudolab/zudo-doc#1519 (W3D), parent epic zudolab/zudo-doc#1510.\n//\n// Named-cause deviation — inline script split (W1B §13.6):\n// Astro's <script> block is processed by Vite at build time as a bundled\n// module with virtual-module imports (`astro:transitions/client`). The zfb\n// port emits meta tags + global styles from the JSX component, while the\n// click/form intercepts live in `client-router/router.ts` and are registered\n// via `init()`. The component calls `init()` as a side effect on first import.\n// No inline <script> dangerouslySetInnerHTML is emitted.\n//\n// Framework-agnostic element minting (no JSX syntax):\n// `@takazudo/zfb-runtime` does not depend on a framework runtime. Head nodes\n// are minted by calling `jsx` from `react/jsx-runtime` directly — NOT JSX\n// syntax, so this stays a plain `.ts` file with no tsconfig JSX changes. The\n// engine alias-rewrites `react/jsx-runtime` → `preact/jsx-runtime` in Preact\n// mode (bundler.rs ~2886) and resolves it natively in React mode, so the same\n// call mints a real element for whichever framework the project configured.\n// The previous approach (a hand-rolled `{ type, props, key, constructor:\n// undefined }` object literal — the Preact diff-path sentinel) only worked for\n// Preact: React's renderer rejects such an object as a child with React error\n// #31 (\"Objects are not valid as a React child\"), because a real React element\n// carries `$$typeof: Symbol.for(\"react.element\")` a literal cannot fake. Same\n// migration as `Island` in @takazudo/zfb.\n//\n// The component renders three base sibling elements to <head> (plus optional\n// metas emitted conditionally — see `prefetchDisabled` and `preserveHtmlAttrs`):\n// 1. A <style> tag with the `.zfb-route-announcer` ARIA helper class.\n// 2. <meta name=\"zfb-view-transitions-enabled\" content=\"true\" />\n// 3. <meta name=\"zfb-view-transitions-fallback\" content={fallback} />\n//\n// The route-announcer <div> is injected into <body> by `announce()` in\n// `client-router/router.ts` on every navigation.\n\nimport { jsx } from \"react/jsx-runtime\";\n\nimport { init } from \"./client-router/router.js\";\nimport { init as prefetchInit } from \"./client-router/prefetch.js\";\n\n// Side-effect: wire click + submit intercepts on first import of this component.\n// Guarded by the idempotent `initialized` flag in router.ts — safe for multiple\n// <ClientRouter /> mounts and HMR re-runs. (W3C3 init idempotency.)\nif (typeof document !== \"undefined\") {\n init();\n}\n\n// Module-level guard: prefetch bootstrap is triggered at most once per module\n// lifetime even if <ClientRouter prefetchAll /> is mounted multiple times (#276).\nlet prefetchBootstrapped = false;\n\nexport interface ClientRouterProps {\n /** Fallback animation strategy when native View Transitions are not supported. /\n fallback?: \"none\" \| \"animate\" \| \"swap\";\n /\n When true, opts every same-origin link into the default prefetch strategy\n * (hover) by calling prefetchInit({ prefetchAll: true }) once on the client.\n /\n prefetchAll?: boolean;\n /\n Extra `<html>` attribute names to preserve across SPA swaps. By default the\n * client router copies the incoming server-rendered document's `<html>`\n * attributes onto the live root, dropping any current attribute that isn't\n * internal to the transition machinery — so a runtime attribute a consumer\n * sets from a persisted island (e.g. `data-theme` or `data-sidebar-hidden`\n * driven from `localStorage`) is lost on every navigation. List those names\n * here and the router re-applies their current value after each swap. Emitted\n * as a `<meta name=\"zfb-preserve-html-attrs\">` tag that `swapRootAttributes`\n * reads at swap time.\n \n Mount with the same list on every page that participates in SPA\n * navigation: the preserve-list is read from the current (outgoing) page's\n * meta at swap time, so a page that omits an entry drops that attribute when\n * navigating away from it. Names are matched case-insensitively (DOM attribute\n * names are lowercased). For dynamic/computed cases, mutate\n * `event.newDocument.documentElement` in a `zfb:before-swap` listener instead.\n * @see https://github.com/Takazudo/zudo-front-builder/issues/1103\n /\n preserveHtmlAttrs?: string[];\n /\n Opt this page OUT of the same-page traverse fast-path (default `false` —\n * fast-path ON). By default a Back/Forward traversal between two history\n * entries sharing the same `pathname + search` is served instantly from the\n * live DOM — no re-fetch, no re-swap, so island/client state is preserved.\n \n Set this on a per-request SSR page (`prerender = false`) whose\n * server-rendered content can legitimately differ between two visits to the\n * same URL: with the fast-path skipped such a traverse would pin the stale\n * first-render content. Emitted as\n * `<meta name=\"zfb-traverse-refetch\" content=\"true\">`, which the router reads\n * on the current (target) page to force the fetch back on. Mount with the\n * same value on every page that participates in SPA navigation, mirroring\n * the `preserveHtmlAttrs` guidance.\n * @see https://github.com/Takazudo/zudo-front-builder/issues/1376\n /\n traverseRefetch?: boolean;\n}\n\n/\n Public element shape for each node returned by `<ClientRouter />`.\n * Structural type — intentionally matches the Preact/React VNode object shape\n * so consumers do not type-infer through the internal representation.\n /\nexport type ClientRouterElement = {\n readonly type: string;\n readonly props: Readonly<Record<string, unknown>>;\n readonly key: unknown;\n};\n\n/\n Mint a head element through the per-project JSX runtime.\n \n Calls `jsx` from `react/jsx-runtime` (alias-rewritten to\n * `preact/jsx-runtime` in Preact mode by the engine, native in React mode)\n * so the returned value is a real element for whichever framework the\n * project configured — NOT a hand-rolled `{ type, props, key }` literal,\n * which only Preact accepts and which makes React throw error #31. A stable\n * `key` is passed because `ClientRouter()` returns these nodes in a plain\n * array (React warns about keyless list children otherwise). Mirrors the\n * `Island` migration in `@takazudo/zfb`.\n /\nfunction makeVNode(type: string, props: Record<string, unknown>, key: string): ClientRouterElement {\n // `jsx`'s `type` param is typed `ElementType` (string-literal intrinsic\n // tags or component types), which rejects an arbitrary runtime `string`.\n // The tag is dynamic here, so cast to the factory's own first-param type —\n // robust whether the engine aliases `jsx` to react or preact at build time.\n return jsx(type as Parameters<typeof jsx>[0], props, key) as unknown as ClientRouterElement;\n}\n\n// CSS for the route-announcer element. Ported verbatim from Astro's\n// `<style is:global>` block in ClientRouter.astro (lines 11–23), renaming\n// `.astro-route-announcer` → `.zfb-route-announcer` per W1B §5.\n// This is a global (non-scoped) <style> because the announcer <div> is\n// appended to document.body at runtime, outside any Preact-controlled subtree.\nconst announcerCss = `\n.zfb-route-announcer {\n\tposition: absolute;\n\tleft: 0;\n\ttop: 0;\n\tclip: rect(0 0 0 0);\n\tclip-path: inset(50%);\n\toverflow: hidden;\n\twhite-space: nowrap;\n\twidth: 1px;\n\theight: 1px;\n}\n`;\n\n/\n `<ClientRouter />` — SPA soft-swap navigation with View Transition animations.\n \n Mount once in your page `<head>`. Emits the opt-in meta tags and the global\n * `.zfb-route-announcer` stylesheet that the route-announcer ARIA div needs.\n * Click and form-submit intercepts are registered as a side effect of importing\n * this component (idempotent — safe to mount multiple times).\n \n @example\n * ```tsx\n * import { ClientRouter } from \"@takazudo/zfb-runtime\";\n * // In your page <head>:\n * <ClientRouter fallback=\"animate\" />\n * ```\n */\nexport function ClientRouter({\n fallback = \"animate\",\n prefetchAll: prefetchAllProp = false,\n preserveHtmlAttrs = [],\n traverseRefetch = false,\n}: ClientRouterProps = {}): readonly ClientRouterElement[] {\n // Bootstrap prefetch exactly once on the client when prefetchAll is true.\n // The initialized flag inside prefetchInit() provides a second safety layer\n // in case of concurrent hydration or manual callers (#276).\n if (typeof document !== \"undefined\" && prefetchAllProp && !prefetchBootstrapped) {\n prefetchBootstrapped = true;\n prefetchInit({ prefetchAll: true });\n }\n\n const nodes: ClientRouterElement[] = [\n // Global styles for the ARIA route-announcer div injected into <body>.\n makeVNode(\"style\", { dangerouslySetInnerHTML: { __html: announcerCss } }, \"zfb-vt-style\"),\n // Opt-in meta tag: router checks for this to decide whether to intercept navigations.\n makeVNode(\"meta\", { name: \"zfb-view-transitions-enabled\", content: \"true\" }, \"zfb-vt-enabled\"),\n // Fallback strategy meta tag: read by getFallback() in router.ts.\n makeVNode(\n \"meta\",\n { name: \"zfb-view-transitions-fallback\", content: fallback },\n \"zfb-vt-fallback\",\n ),\n ];\n\n // Prefetch-disabled meta tag (#277): emitted when the bundler set\n // `globalThis.__zfb.prefetchDisabled = true` (from `zfb.config.ts`\n // `prefetch: { disabled: true }`). The sibling prefetch-core module reads\n // `document.querySelector('meta[name=\"zfb-prefetch-disabled\"][content=\"true\"]')`\n // at `init()` time and short-circuits if found.\n //\n // The flag is site-wide and static — set once at bundle-emit time, never\n // per-page. This meta tag appears on every page that mounts `<ClientRouter />`\n // or not at all.\n //\n // Pin the contract verbatim — the attribute names and content value are\n // shared with the sibling prefetch-core sub-issue (#276).\n if ((globalThis as { __zfb?: { prefetchDisabled?: boolean } }).__zfb?.prefetchDisabled === true) {\n nodes.push(\n makeVNode(\n \"meta\",\n { name: \"zfb-prefetch-disabled\", content: \"true\" },\n \"zfb-prefetch-disabled\",\n ),\n );\n }\n\n // Consumer-extensible <html> attribute preserve-list (#1103). swapRootAttributes\n // reads this meta and re-applies the listed attributes' runtime values after each\n // swap, so persisted-island state on <html> (data-theme, data-sidebar-hidden, …)\n // survives navigation. Emitted only when non-empty, so non-opt-in output stays\n // byte-identical. Same conditional-emission shape as the prefetch-disabled meta.\n const preserveList = preserveHtmlAttrs.filter(Boolean);\n if (preserveList.length > 0) {\n nodes.push(\n makeVNode(\n \"meta\",\n { name: \"zfb-preserve-html-attrs\", content: preserveList.join(\" \") },\n \"zfb-preserve-html-attrs\",\n ),\n );\n }\n\n // Traverse-refetch opt-out meta (#1376). A same-page Back/Forward traversal\n // skips the re-fetch/re-swap by default (the router's traverse fast-path);\n // this meta opts a per-request SSR page (`prerender = false`) back INTO the\n // fetch, since skipping it would pin stale server-rendered content. Emitted\n // only when opted in, so non-opt-in output stays byte-identical. Same\n // conditional-emission shape as the prefetch-disabled / preserve-html-attrs\n // metas; the router reads meta[name=\"zfb-traverse-refetch\"][content=\"true\"].\n if (traverseRefetch) {\n nodes.push(\n makeVNode(\"meta\", { name: \"zfb-traverse-refetch\", content: \"true\" }, \"zfb-traverse-refetch\"),\n );\n }\n\n return nodes;\n}\n"]}

package/dist/framework.d.ts CHANGED Viewed

@@ -14,4 +14,3 @@ export interface FrameworkAdapter {
      */
     renderToString: (vnode: unknown) => string;
 }
-//# sourceMappingURL=framework.d.ts.map

package/dist/framework.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"framework.js","sourceRoot":"","sources":["../src/framework.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,wEAAwE;AACxE,iEAAiE;AACjE,wEAAwE;AACxE,8DAA8D;AAC9D,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,4EAA4E"}
1	+ {"version":3,"file":"framework.js","sourceRoot":"","sources":["../src/framework.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,wEAAwE;AACxE,iEAAiE;AACjE,wEAAwE;AACxE,8DAA8D;AAC9D,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,4EAA4E","sourcesContent":["// `@takazudo/zfb-runtime` — framework adapter contract.\n//\n// The runtime is JSX-runtime-agnostic: it never imports preact or react\n// directly. Instead, the caller of [`createPageRouter`] passes a\n// [`FrameworkAdapter`] that pins how a JSX vnode (the value returned by\n// a page module's `default` export) becomes a string of HTML.\n//\n// This mirrors ADR-002's framework-adapter pattern on the Rust side — the\n// runtime owns the page-module evaluation lifecycle, the adapter owns the\n// JSX-runtime-specific render call. Wave 2 (T6) wires the embedded V8 host\n// with an adapter built on `preact-render-to-string` (or `react-dom/server`).\n//\n// BCI-5: `hydrate` reservation field removed — it was never called by the\n// runtime and no real consumer set it; adding it back when a real\n// implementation exists is a smaller change than carrying dead API surface.\n\n/*\n Pluggable per-framework SSR contract.\n \n `renderToString` takes whatever shape the framework's JSX pragma\n * produces (Preact's VNode, React's element, etc.) and returns a string\n * of HTML. The runtime treats both the input and the return value as\n * opaque — it neither inspects the vnode nor escapes the output.\n /\nexport interface FrameworkAdapter {\n /\n Render a JSX vnode to an HTML string. Must be synchronous; SSR\n * happens inside a Hono request handler that resolves the response\n * body in one step.\n */\n renderToString: (vnode: unknown) => string;\n}\n"]}

package/dist/index.d.ts CHANGED Viewed

@@ -1,14 +1,12 @@
-export { createPageRouter } from "./router.js";
 export type { CreatePageRouterOptions, PageDefinition, PageHeading, PageModule, PageRouter, } from "./router.js";
 export type { FrameworkAdapter } from "./framework.js";
 export type { ContentSnapshot, EntrySnapshot } from "./snapshot.js";
 export { ViewTransitions, type ViewTransitionsElement } from "./view-transitions.js";
 export { ClientRouter, type ClientRouterProps } from "./client-router.js";
-export { navigate, supportsViewTransitions, transitionEnabledOnThisPage, } from "./client-router/router.js";
+export { navigate, supportsViewTransitions, transitionEnabledOnThisPage, syncHistoryEntry, } from "./client-router/router.js";
 export { prefetch, init as prefetchInit } from "./client-router/prefetch.js";
 export type { PrefetchStrategy, PrefetchInitOptions, PrefetchOptions, } from "./client-router/prefetch.js";
 export { TRANSITION_BEFORE_PREPARATION, TRANSITION_AFTER_PREPARATION, TRANSITION_BEFORE_SWAP, TRANSITION_AFTER_SWAP, TRANSITION_PAGE_LOAD, TRANSITION_NAVIGATION_ABORTED, TransitionBeforePreparationEvent, TransitionBeforeSwapEvent, isTransitionBeforePreparationEvent, isTransitionBeforeSwapEvent, } from "./client-router/events.js";
 export { swapFunctions, swap } from "./client-router/swap-functions.js";
-export type { Direction, Fallback, NavigationTypeString, Options } from "./client-router/types.js";
+export type { Direction, Fallback, NavigationTypeString, Options, SyncHistoryEntryOptions, } from "./client-router/types.js";
 export type { ZfbPlugin, ZfbPluginLogger, ZfbBuildHookContext, ZfbDevMiddlewareContext, ZfbDevMiddlewareHandler, ZfbDevMiddlewareRequest, ZfbDevMiddlewareResponse, ZfbRouteEntry, ZfbRouteManifest, ZfbSetupContext, ZfbVirtualModuleLoader, } from "@takazudo/zfb/plugins";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js CHANGED Viewed

@@ -1,9 +1,19 @@
 // Public entry point for `@takazudo/zfb-runtime`.
 //
-// Worker bundles produced by T3 import this module and invoke
+// This is the **client-safe** barrel: everything re-exported here must be
+// bundleable for `--platform=browser` without pulling a server-only
+// dependency. In particular `createPageRouter` (and the Hono server router
+// it builds) is intentionally NOT re-exported here — it lives at the
+// server-only subpath `@takazudo/zfb-runtime/server`. Re-exporting it from
+// this barrel makes any island that does `import ... from "@takazudo/zfb-runtime"`
+// drag `hono` into the browser graph, which esbuild must then resolve
+// (issue #1298). The page-router *types* below are `export type` only, so
+// esbuild strips them and no runtime edge to `./router.js` survives.
+//
+// Worker bundles produced by T3 import the server subpath and invoke
 // `createPageRouter` once, at module top, to obtain the fetch handler:
 //
-//   import { createPageRouter } from "@takazudo/zfb-runtime";
+//   import { createPageRouter } from "@takazudo/zfb-runtime/server";
 //
 //   const router = createPageRouter({
 //     pages: [...],
@@ -14,12 +24,11 @@
 //   export default { fetch: router };
 //
 // The README documents the bundle shape T6 (embedded V8 host) consumes.
-export { createPageRouter } from "./router.js";
 export { ViewTransitions } from "./view-transitions.js";
 // Client-router public surface (W3D — mirrors @takazudo/zfb-runtime/client-router barrel).
 // See W1B §2 for the full public API spec.
 export { ClientRouter } from "./client-router.js";
-export { navigate, supportsViewTransitions, transitionEnabledOnThisPage, } from "./client-router/router.js";
+export { navigate, supportsViewTransitions, transitionEnabledOnThisPage, syncHistoryEntry, } from "./client-router/router.js";
 // Prefetch public surface (#276).
 // `init` from prefetch.ts is re-exported as `prefetchInit` to avoid collision
 // with the router's `init`.

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,~~8DAA8D~~;~~AAC9D~~,uEAAuE;AACvE,EAAE;AACF,~~8DAA8D~~;~~AAC9D~~,EAAE;AACF,sCAAsC;AACtC,oBAAoB;AACpB,4EAA4E;AAC5E,iFAAiF;AACjF,QAAQ;AACR,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,wEAAwE;~~AAExE~~,OAAO,EAAE,~~gBAAgB,EAAE,MAAM,aAAa,CAAC;AAU/C,OAAO,EAAE,~~eAAe,EAA+B,MAAM,uBAAuB,CAAC;AAErF,2FAA2F;AAC3F,2CAA2C;AAC3C,OAAO,EAAE,YAAY,EAA0B,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,uBAAuB,EACvB,2BAA2B,~~GAC5B~~,MAAM,2BAA2B,CAAC;AAEnC,kCAAkC;AAClC,8EAA8E;AAC9E,4BAA4B;AAC5B,OAAO,EAAE,QAAQ,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAM7E,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,EAChC,yBAAyB,EACzB,kCAAkC,EAClC,2BAA2B,GAC5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,mCAAmC,CAAC"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,0EAA0E;AAC1E,oEAAoE;AACpE,2EAA2E;AAC3E,qEAAqE;AACrE,2EAA2E;AAC3E,mFAAmF;AACnF,sEAAsE;AACtE,0EAA0E;AAC1E,qEAAqE;AACrE,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,EAAE;AACF,qEAAqE;AACrE,EAAE;AACF,sCAAsC;AACtC,oBAAoB;AACpB,4EAA4E;AAC5E,iFAAiF;AACjF,QAAQ;AACR,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,wEAAwE;AAWxE,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AAErF,2FAA2F;AAC3F,2CAA2C;AAC3C,OAAO,EAAE,YAAY,EAA0B,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAEnC,kCAAkC;AAClC,8EAA8E;AAC9E,4BAA4B;AAC5B,OAAO,EAAE,QAAQ,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAM7E,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,EAChC,yBAAyB,EACzB,kCAAkC,EAClC,2BAA2B,GAC5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,mCAAmC,CAAC","sourcesContent":["// Public entry point for `@takazudo/zfb-runtime`.\n//\n// This is the client-safe barrel: everything re-exported here must be\n// bundleable for `--platform=browser` without pulling a server-only\n// dependency. In particular `createPageRouter` (and the Hono server router\n// it builds) is intentionally NOT re-exported here — it lives at the\n// server-only subpath `@takazudo/zfb-runtime/server`. Re-exporting it from\n// this barrel makes any island that does `import ... from \"@takazudo/zfb-runtime\"`\n// drag `hono` into the browser graph, which esbuild must then resolve\n// (issue #1298). The page-router types below are `export type` only, so\n// esbuild strips them and no runtime edge to `./router.js` survives.\n//\n// Worker bundles produced by T3 import the server subpath and invoke\n// `createPageRouter` once, at module top, to obtain the fetch handler:\n//\n// import { createPageRouter } from \"@takazudo/zfb-runtime/server\";\n//\n// const router = createPageRouter({\n// pages: [...],\n// contentSnapshot: __ZFB_CONTENT_SNAPSHOT__, // embedded by the bundler\n// framework: { renderToString: render }, // preact-render-to-string etc.\n// });\n//\n// export default { fetch: router };\n//\n// The README documents the bundle shape T6 (embedded V8 host) consumes.\n\nexport type {\n CreatePageRouterOptions,\n PageDefinition,\n PageHeading,\n PageModule,\n PageRouter,\n} from \"./router.js\";\nexport type { FrameworkAdapter } from \"./framework.js\";\nexport type { ContentSnapshot, EntrySnapshot } from \"./snapshot.js\";\nexport { ViewTransitions, type ViewTransitionsElement } from \"./view-transitions.js\";\n\n// Client-router public surface (W3D — mirrors @takazudo/zfb-runtime/client-router barrel).\n// See W1B §2 for the full public API spec.\nexport { ClientRouter, type ClientRouterProps } from \"./client-router.js\";\nexport {\n navigate,\n supportsViewTransitions,\n transitionEnabledOnThisPage,\n syncHistoryEntry,\n} from \"./client-router/router.js\";\n\n// Prefetch public surface (#276).\n// `init` from prefetch.ts is re-exported as `prefetchInit` to avoid collision\n// with the router's `init`.\nexport { prefetch, init as prefetchInit } from \"./client-router/prefetch.js\";\nexport type {\n PrefetchStrategy,\n PrefetchInitOptions,\n PrefetchOptions,\n} from \"./client-router/prefetch.js\";\nexport {\n TRANSITION_BEFORE_PREPARATION,\n TRANSITION_AFTER_PREPARATION,\n TRANSITION_BEFORE_SWAP,\n TRANSITION_AFTER_SWAP,\n TRANSITION_PAGE_LOAD,\n TRANSITION_NAVIGATION_ABORTED,\n TransitionBeforePreparationEvent,\n TransitionBeforeSwapEvent,\n isTransitionBeforePreparationEvent,\n isTransitionBeforeSwapEvent,\n} from \"./client-router/events.js\";\nexport { swapFunctions, swap } from \"./client-router/swap-functions.js\";\nexport type {\n Direction,\n Fallback,\n NavigationTypeString,\n Options,\n SyncHistoryEntryOptions,\n} from \"./client-router/types.js\";\n\n// Plugin lifecycle types (#255). The runtime package re-exports the\n// `@takazudo/zfb/plugins` surface so consumers writing plugins from a\n// project that only depends on `@takazudo/zfb-runtime` can still\n// import the canonical types (e.g. `import type { ZfbPlugin } from\n// \"@takazudo/zfb-runtime\"`).\nexport type {\n ZfbPlugin,\n ZfbPluginLogger,\n ZfbBuildHookContext,\n ZfbDevMiddlewareContext,\n ZfbDevMiddlewareHandler,\n ZfbDevMiddlewareRequest,\n ZfbDevMiddlewareResponse,\n ZfbRouteEntry,\n ZfbRouteManifest,\n ZfbSetupContext,\n ZfbVirtualModuleLoader,\n} from \"@takazudo/zfb/plugins\";\n"]}

package/dist/router.d.ts CHANGED Viewed

@@ -16,7 +16,10 @@ export interface PageHeading {
  * - `default`: the JSX page component. Called with the props returned by
  *   `getStaticProps` (if exported) or the `props` from the matching
  *   `paths()` entry (for dynamic routes). The return value is fed straight
- *   to the framework adapter's `renderToString`.
+ *   to the framework adapter's `renderToString`. A dynamic route with no
+ *   `paths()` export is called with `{ params: urlParams }` instead of
+ *   `{}` — see `createPageRouter`'s JSDoc for the full componentInput
+ *   derivation table.
  * - `prerender`: literal `false` opts a route OUT of build-time SSG (T5
  *   contract). The page router still serves it under the embedded V8 host
  *   so dev mode behaves identically; SSG callers filter the route list before
@@ -30,6 +33,12 @@ export interface PageHeading {
  *   for this route template. May be async. Returns an array of
  *   `{ params, props? }` objects identical in shape to the Astro/zfb
  *   `paths()` contract.
+ *   **Evaluated once per router instance** — the result is memoised and
+ *   shared across the `/__paths__` handler and all per-page render
+ *   requests. This matches the build-time-enumerator contract: every
+ *   entry rendered within a single build sees the same paths() snapshot.
+ *   Dev mode is safe because each file-save triggers a fresh bundle,
+ *   which creates a new router instance with a clean memo.
  * - `getStaticProps`: optional async function for static routes that need
  *   to fetch data at build/render time. Called once per request (before
  *   `default`). Must return `{ props: Record<string, unknown> }`. The
@@ -69,6 +78,17 @@ export interface CreatePageRouterOptions {
     readonly contentSnapshot: ContentSnapshot;
     /** Framework adapter pinning the SSR call. */
     readonly framework: FrameworkAdapter;
+    /**
+     * When `true`, the 500 body for render errors includes the full JS stack
+     * trace. When `false`, only the message + route are included. When
+     * omitted, the runtime checks `globalThis.__zfb.ssrDebug` at request time:
+     * that flag is set by the embedded V8 build/dev host (`globals_shim.js`)
+     * and is absent on the production Cloudflare Workers runtime.
+     *
+     * Default is effectively OFF for production (no flag ⇒ message + route only).
+     * Useful for explicit injection in unit tests without global mutation.
+     */
+    readonly includeErrorStack?: boolean;
 }
 /**
  * Fetch-handler shape returned by [`createPageRouter`]. Shaped as a plain
@@ -89,9 +109,19 @@ export type PageRouter = (request: Request) => Promise<Response>;
  *      `framework.renderToString(module.default({}))`, and returns the
  *      string in a `Response` with the appropriate `Content-Type`.
  *
+ * Per-route `componentInput` (the object passed to `module.default(...)`) is
+ * derived from the route pattern and the page module's exports:
+ *   - Dynamic route + `paths()` export: match the URL params against the
+ *     `paths()` entries and pass `{ params, ...props }` (404 on no match).
+ *   - Static route + `getStaticProps()` export: pass the returned `props`.
+ *   - Dynamic route with NO `paths()` export (e.g. a per-request SSR page
+ *     whose slugs can't be enumerated ahead of time): pass `{ params:
+ *     urlParams }` so the component still knows which URL params it is
+ *     serving, rather than being invoked with `{}`.
+ *   - Anything else (static route, no `getStaticProps`): pass `{}`.
+ *
  * The returned function is a plain `(request) => Promise<Response>` so a
  * Worker entry point can `export default { fetch: createPageRouter(...) }`
  * directly.
  */
 export declare function createPageRouter(opts: CreatePageRouterOptions): PageRouter;
-//# sourceMappingURL=router.d.ts.map

package/dist/router.js CHANGED Viewed

@@ -77,6 +77,26 @@ function ensureHtml5Doctype(body, contentType) {
     }
     return body;
 }
+/**
+ * Evaluate `pathsFn` once per `routeKey`, sharing the result across all
+ * concurrent and subsequent callers via a Promise stored in `memo`.
+ *
+ * Rejections are evicted from the memo so that a transient paths() failure
+ * does not permanently poison the cache — the next request retries.
+ */
+async function getOrEvalPaths(memo, routeKey, pathsFn) {
+    const existing = memo.get(routeKey);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const promise = Promise.resolve(pathsFn()).then((v) => v, (err) => {
+        // Evict on rejection so the next request retries.
+        memo.delete(routeKey);
+        return Promise.reject(err);
+    });
+    memo.set(routeKey, promise);
+    return promise;
+}
 /**
  * Build a page router for the SSG-first architecture (ADR-005).
  *
@@ -90,6 +110,17 @@ function ensureHtml5Doctype(body, contentType) {
  *      `framework.renderToString(module.default({}))`, and returns the
  *      string in a `Response` with the appropriate `Content-Type`.
  *
+ * Per-route `componentInput` (the object passed to `module.default(...)`) is
+ * derived from the route pattern and the page module's exports:
+ *   - Dynamic route + `paths()` export: match the URL params against the
+ *     `paths()` entries and pass `{ params, ...props }` (404 on no match).
+ *   - Static route + `getStaticProps()` export: pass the returned `props`.
+ *   - Dynamic route with NO `paths()` export (e.g. a per-request SSR page
+ *     whose slugs can't be enumerated ahead of time): pass `{ params:
+ *     urlParams }` so the component still knows which URL params it is
+ *     serving, rather than being invoked with `{}`.
+ *   - Anything else (static route, no `getStaticProps`): pass `{}`.
+ *
  * The returned function is a plain `(request) => Promise<Response>` so a
  * Worker entry point can `export default { fetch: createPageRouter(...) }`
  * directly.
@@ -104,6 +135,21 @@ export function createPageRouter(opts) {
     for (const page of opts.pages) {
         pagesByRoute.set(page.route, page);
     }
+    // Per-router-instance memo for paths() results.
+    //
+    // Keyed on page.route (e.g. "/blog/:slug"). Stores the in-flight or
+    // settled Promise so that concurrent requests share one evaluation.
+    // Rejections are NOT cached: if paths() throws the Promise is removed
+    // from the map so the next request retries rather than re-propagating
+    // the same error indefinitely.
+    //
+    // Production SSR isolates evaluate paths() once per isolate, which
+    // matches the documented build-time-enumerator contract. Dev mode is
+    // safe because each re-bundle creates a fresh router instance
+    // (dev.rs reload_renderer), so stale paths() results never persist
+    // across a file-save cycle. Watch-time invalidation is explicitly
+    // out of scope per issue #507.
+    const pathsMemo = new Map();
     // Sanity check: a user-authored route that happens to start with
     // `/__paths__` (or a top-level catchall like `/:slug{.+}`) would
     // shadow the synthetic endpoint registered below if Hono dispatched
@@ -153,7 +199,7 @@ export function createPageRouter(opts) {
         }
         let result;
         try {
-            result = await mod.paths();
+            result = await getOrEvalPaths(pathsMemo, routeKey, mod.paths);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -193,14 +239,28 @@ export function createPageRouter(opts) {
             // an empty object — the component signature has no required props.
             // For dynamic routes whose URL params do not match any paths()
             // entry, we return a 404 rather than rendering with empty props.
-            const rawUrlParams = c.req.param();
-            const urlParams = (rawUrlParams ?? {});
-            const hasDynamicParams = Object.keys(urlParams).length > 0;
+            //
+            // Whether the route is dynamic is derived from the ROUTE PATTERN,
+            // not from the captured params: for an optional catchall
+            // (`/docs/:slug{.+}?`), Hono matches the bare `/docs` with NO
+            // params captured at all, so `Object.keys(c.req.param())` would
+            // be empty and the old gate skipped paths() entirely — rendering
+            // with `{}` instead of the entry whose `slug` is `[]`.
+            const declaredParams = routeParamSpecs(page.route);
+            const rawUrlParams = c.req.param() ?? {};
+            const urlParams = {};
+            for (const [k, v] of Object.entries(rawUrlParams)) {
+                // Unmatched optional params may surface as undefined — drop them
+                // so "param absent" is represented uniformly.
+                if (typeof v === "string")
+                    urlParams[k] = v;
+            }
+            const isDynamicRoute = declaredParams.length > 0;
             let componentInput = {};
-            if (hasDynamicParams && typeof mod.paths === "function") {
+            if (isDynamicRoute && typeof mod.paths === "function") {
                 let pathsResult;
                 try {
-                    pathsResult = await mod.paths();
+                    pathsResult = await getOrEvalPaths(pathsMemo, page.route, mod.paths);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -226,15 +286,27 @@ export function createPageRouter(opts) {
                 // /docs/[...slug]), Hono returns a slash-joined string (e.g.
                 // "guides/install"), so we compare against the paths() entry's
                 // params.slug joined with "/".
+                //
+                // Matching iterates the params DECLARED by the route pattern so
+                // the zero-segment optional-catchall case is covered: when Hono
+                // matched `/docs` for `/docs/:slug{.+}?` no `slug` param exists
+                // in the URL, and the matching entry is the one whose param is
+                // the explicit empty array (`{ slug: [] }`).
                 const match = pathsResult.find((entry) => {
-                    return Object.entries(urlParams).every(([k, v]) => {
-                        const paramVal = entry.params[k];
+                    return declaredParams.every(({ name, optionalCatchall }) => {
+                        const urlVal = urlParams[name];
+                        const paramVal = entry.params[name];
+                        if (urlVal === undefined) {
+                            // Param absent from the URL: only valid for an optional
+                            // catchall, and only against the explicit `[]` entry.
+                            return optionalCatchall && Array.isArray(paramVal) && paramVal.length === 0;
+                        }
                         if (Array.isArray(paramVal)) {
                             // catchall: paths() emits slug as string[] but Hono
                             // provides it as a "/"-joined string
-                            return paramVal.join("/") === v;
+                            return paramVal.join("/") === urlVal;
                         }
-                        return String(paramVal) === v;
+                        return String(paramVal) === urlVal;
                     });
                 });
                 if (!match) {
@@ -253,7 +325,17 @@ export function createPageRouter(opts) {
                     ...(match.props ?? {}),
                 };
             }
-            else if (!hasDynamicParams && typeof mod.getStaticProps === "function") {
+            else if (isDynamicRoute) {
+                // Dynamic route with no `paths()` export: the natural shape for a
+                // per-request SSR page whose slugs can't be enumerated ahead of
+                // time. Neither branch above applies (no paths() to match against,
+                // and getStaticProps only fires for static routes), so without this
+                // the component would be invoked with `{}` — no params, no
+                // diagnostic, and no way to know which slug it is serving. Pass the
+                // URL params through directly instead.
+                componentInput = { params: urlParams };
+            }
+            else if (!isDynamicRoute && typeof mod.getStaticProps === "function") {
                 // Static route with `getStaticProps`: call it to fetch build-time
                 // data and pass the returned props to the default component. This
                 // supports the `export async function getStaticProps()` pattern
@@ -279,24 +361,44 @@ export function createPageRouter(opts) {
             // `await` so async page modules (e.g. API routes typed as
             // `(): Promise<Response>`) resolve before we inspect the value.
             // For sync pages that return a VNode/string the await is a no-op.
-            const result = await mod.default(componentInput);
-            // API route short-circuit: a page module that returns a Response
-            // directly (e.g. `pages/api/*.tsx` handlers that use Web Fetch
-            // primitives instead of returning JSX) is responsible for its own
-            // status, headers, and body — return it as-is rather than running
-            // it through the framework SSR path.
-            if (result instanceof Response) {
-                return result;
+            //
+            // Wrapped in a try/catch so that any error thrown by the component
+            // or by renderToString surfaces as a descriptive 500 rather than
+            // escaping to Hono's generic error handler (which discards the real
+            // message). Mirrors the getStaticProps catch above.
+            try {
+                const result = await mod.default(componentInput);
+                // API route short-circuit: a page module that returns a Response
+                // directly (e.g. `pages/api/*.tsx` handlers that use Web Fetch
+                // primitives instead of returning JSX) is responsible for its own
+                // status, headers, and body — return it as-is rather than running
+                // it through the framework SSR path. A `return` from inside a
+                // `try` does not trigger the `catch`, so this passes through
+                // correctly without special-casing.
+                if (result instanceof Response) {
+                    return result;
+                }
+                // Non-HTML routes (e.g. `sitemap.xml.tsx`, `feed.xml.tsx`) commonly
+                // return their body as a pre-serialised `string` instead of a
+                // VNode. Routing those through `framework.renderToString` would
+                // HTML-escape the angle brackets and ampersands, producing
+                // garbage XML. Pass strings through verbatim; only wrap actual
+                // VNodes.
+                const html = typeof result === "string" ? result : opts.framework.renderToString(result);
+                const contentType = mod.contentType ?? DEFAULT_CONTENT_TYPE;
+                return c.body(ensureHtml5Doctype(html, contentType), 200, { "Content-Type": contentType });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // __zfb.ssrDebug is set only by the embedded V8 build/dev host
+                // (globals_shim.js), never by the production Workers runtime.
+                const includeStack = opts.includeErrorStack ??
+                    globalThis.__zfb?.ssrDebug === true;
+                const stack = includeStack && err instanceof Error && err.stack ? `\n${err.stack}` : "";
+                return c.body(`[zfb-runtime] render threw for "${page.route}": ${msg}${stack}`, 500, {
+                    "Content-Type": "text/plain; charset=utf-8",
+                });
             }
-            // Non-HTML routes (e.g. `sitemap.xml.tsx`, `feed.xml.tsx`) commonly
-            // return their body as a pre-serialised `string` instead of a
-            // VNode. Routing those through `framework.renderToString` would
-            // HTML-escape the angle brackets and ampersands, producing
-            // garbage XML. Pass strings through verbatim; only wrap actual
-            // VNodes.
-            const html = typeof result === "string" ? result : opts.framework.renderToString(result);
-            const contentType = mod.contentType ?? DEFAULT_CONTENT_TYPE;
-            return c.body(ensureHtml5Doctype(html, contentType), 200, { "Content-Type": contentType });
         });
     }
     // Hono's `app.fetch` returns `Response | Promise<Response>`. The
@@ -317,14 +419,39 @@ function isPathsEntry(x) {
     const params = x.params;
     return typeof params === "object" && params !== null;
 }
+/**
+ * Parse the params declared by a Hono route pattern (the `route` string
+ * the build pipeline registers, e.g. `/blog/:slug`, `/docs/:slug{.+}`,
+ * `/docs/:slug{.+}?`). Static routes return an empty list.
+ *
+ * Only the pattern shapes emitted by `bracket_to_hono` (zfb-build) are
+ * recognised — `:name`, `:name{.+}`, `:name{.+}?` — which is the entire
+ * grammar the file router produces.
+ */
+function routeParamSpecs(route) {
+    const specs = [];
+    for (const seg of route.split("/")) {
+        if (!seg.startsWith(":"))
+            continue;
+        const optionalCatchall = seg.endsWith("?");
+        const body = optionalCatchall ? seg.slice(1, -1) : seg.slice(1);
+        const braceIdx = body.indexOf("{");
+        const name = braceIdx === -1 ? body : body.slice(0, braceIdx);
+        if (name.length > 0) {
+            specs.push({ name, optionalCatchall });
+        }
+    }
+    return specs;
+}
 /**
  * Heuristic check for user-authored routes that may shadow the
  * synthetic `/__paths__/<encoded-route-key>` endpoint.
  *
  * Returns true when the route literal contains `/__paths__` (an
  * obvious collision) or when its first segment is a Hono catchall
- * (`:name{.+}`) or a file-system catchall (`[...name]`) at the root —
- * those would match `/__paths__/...` once Hono dispatches to them.
+ * (`:name{.+}`, optionally `:name{.+}?`) or a file-system catchall
+ * (`[...name]` / `[[...name]]`) at the root — those would match
+ * `/__paths__/...` once Hono dispatches to them.
  */
 function routeShadowsPathsEndpoint(route) {
     if (route.includes("/__paths__")) {
@@ -334,14 +461,17 @@ function routeShadowsPathsEndpoint(route) {
     // anything deeper cannot match `/__paths__` because the literal
     // first segment differs.
     const firstSeg = route.replace(/^\/+/, "").split("/")[0] ?? "";
-    // Hono regex-quantifier catchall: `:name{.+}`.
-    if (/^:[A-Za-z_][\w]*\{\.[+*]\}$/.test(firstSeg)) {
+    // Hono regex-quantifier catchall: `:name{.+}` / optional `:name{.+}?`.
+    if (/^:[A-Za-z_][\w]*\{\.[+*]\}\??$/.test(firstSeg)) {
         return true;
     }
-    // File-system catchall (pre-bracket-to-hono): `[...name]`.
+    // File-system catchall (pre-bracket-to-hono): `[...name]` / `[[...name]]`.
     if (/^\[\.\.\.[A-Za-z_][\w]*\]$/.test(firstSeg)) {
         return true;
     }
+    if (/^\[\[\.\.\.[A-Za-z_][\w]*\]\]$/.test(firstSeg)) {
+        return true;
+    }
     return false;
 }
 //# sourceMappingURL=router.js.map