@kudzujs/core 0.6.0 → 0.6.2

package/GOAL_A.md

@@ -8,7 +8,7 @@ The benchmark runner, framework fixtures, generated artifacts, and raw arrays ar
 
 ## Implementation Status
 
-**Goal A is complete for one explicitly configured exact-static route group with one shared layout.** Complete standalone documents, native fallback, persistent layout state/effects, disposable route state/effects, optimistic workflows, desktop/mobile performance gates, and the dashboard expansion seam are covered. Runtime bracket navigation, multiple layout groups, and conditional/keyed DOM-owned effects inside a navigation group remain deliberate post-Goal-A limits.
+**Goal A is complete for one explicitly configured emitted-route group with one shared layout.** Complete standalone documents, exact and runtime-parameter navigation, native fallback, persistent layout state/effects, disposable route state/effects, optimistic workflows, desktop/mobile performance gates, and the dashboard expansion seam are covered. Multiple layout groups and conditional/keyed DOM-owned effects inside a navigation group remain deliberate post-Goal-A limits.
 
 - **Phase 1 complete**: a local six-route commerce fixture, locked React/Next/Nuxt/SvelteKit comparisons, and a reproducible artifact/build/Chrome runner validate the implementation.
 - **Phase 2 complete**: effects inside conditional ranges and supported keyed row components mount with their DOM owner, unsubscribe and clean up on removal, and remount without affecting effect-free output.
@@ -23,6 +23,8 @@ The capability-local prefetch/cache increased the commerce navigation asset from
 
 In the focused effect-enabled navigation fixture, mount support adds 171 B gzip to the same-route navigation asset and 37 B gzip to the shared runtime. The active-context guard adds 18 B gzip to `kudzu-effect.js` (257 B total); cache-safe route entries are 1,059-1,116 B gzip. The effect-free commerce specialization remains byte-for-byte unchanged.
 
+The post-Goal-A runtime-pattern matcher increases the exact-only commerce navigation asset from 2,306 B to 2,461 B gzip. The mixed exact/runtime navigation fixture emits a 3,105 B gzip navigation asset and a 703 B gzip cache-safe parameter initializer.
+
 The Phase 6 chart probe's complete initial module graph is 11,902 B raw / 5,331 B gzip. It adds no framework API or package and does not change the commerce benchmark fixture.
 
 The app-mode Kudzu fixture emits 34,879 deploy bytes. Its product route loads 15,800 raw / 7,215 gzip bytes of initial JavaScript, including the 2,306 B gzip navigation capability. Routes outside a configured application group retain the static zero-JavaScript and byte-for-byte gates.
@@ -39,7 +41,7 @@ The latest matched run used seven rotating production builds and seven rotating
 
 The navigation capability initially measured 128.7 ms because it paid one HTML round trip. Validated near-viewport document prefetch reduced the final seven-run median to 5.7 ms while Kudzu still transferred 62% less than SvelteKit and 83% less than React on the cold product load. A progressive-HTML grid shift found by the benchmark was fixed in the matched CSS; 30 focused Kudzu profiles and the final desktop/mobile cross-framework runs then recorded zero cold and warm CLS.
 
-The final seven-run build table measured 460.8 ms for Kudzu and 429.5 ms for React. A focused 21-run interleaved follow-up measured 578.6 ms and 542.5 ms under different machine load, leaving a repeatable 6-7% Kudzu loss. CPU profiling attributes the small-project difference primarily to TypeScript ESM/compiler startup. Replacing that parser or hiding startup work is outside Goal A; this is an explicit build-time tradeoff, while deploy bytes and every measured browser CPU, memory, and navigation metric remain lower than React.
+The original final table measured 460.8 ms for Kudzu and 429.5 ms for React, and a focused follow-up confirmed a 6-7% loss primarily from TypeScript ESM/compiler startup. A post-gate startup fix now enables Node's native module compile cache before lazily loading the compiler. The first empty-cache build measured 541.4 ms against the previous 547.6 ms path; after one warm-up, 31 interleaved artifact-clean builds measured Kudzu at 425.8 ms and React at 483.4 ms, making Kudzu 11.9% faster in that run. Cache-disabled and cached builds emit byte-for-byte identical output.
 
 The mobile profile uses a 390x844 viewport, 6x CPU slowdown, 150 ms latency, and 150 KiB/s download. Kudzu measured 420 ms cold LCP, 220 ms warm LCP, 5.6 ms interaction, 8.7 ms product-cart navigation, 4.1 ms optimistic rejection, and 158 ms rollback/error.
 
@@ -108,7 +110,7 @@ Each phase starts with one failing fixture and ends with correctness, browser, s
 1. **Benchmark harness**: freeze the commerce journey, network profiles, framework versions, generated artifacts, and measurement scripts before optimizing Kudzu.
 2. **Owned effects**: complete cleanup for conditional ranges and keyed items using the existing mount and unmount hooks. **Complete.**
 3. **Layout and route scopes**: retain only declared layout state and dispose route-owned behavior on every completed transition. **Compiler ownership complete; transition behavior belongs to Phase 4.**
-4. **Opt-in navigation**: support eligible links, history, aborts, stale responses, focus, scroll, metadata, and native fallback. **Complete for exact static routes and top-level layout/route effects; conditional/keyed DOM-owned effects remain excluded.**
+4. **Opt-in navigation**: support eligible links, history, aborts, stale responses, focus, scroll, metadata, and native fallback. **Complete for emitted exact/runtime-parameter routes and top-level layout/route effects; conditional/keyed DOM-owned effects remain excluded.**
 5. **Business workflows**: close only fixture-proven gaps in forms, async requests, optimistic updates, and diagnostics. **Complete for the matched cart success/rejection flow.**
 6. **Expansion probe**: prove that one persistent mock stream and one imperative chart stub can mount, update, navigate, and dispose without adding a component runtime. **Compatibility probe complete; real telemetry and chart engines remain outside Goal A.**
 

package/README.md

@@ -449,17 +449,17 @@ export default function ProductPage() {
 }
 ```
 
-Opt exact static routes into same-document navigation:
+Opt emitted exact or runtime-parameter routes into same-document navigation:
 
 ```js
 export default {
-  navigation: { routes: ["/product", "/cart"] }
+  navigation: { routes: ["/product", "/items/[id]"] }
 }
 ```
 
-Every configured route must be an exact static route and export the same layout function. The layout DOM, state, and top-level effects persist; route state and top-level effects reset after cleanup on each transition. Eligible ordinary anchors prefetch validated complete documents into a finite memory cache. Direct requests, reloads, JavaScript failures, unsupported links, and routes outside the group retain native document navigation.
+Every configured identity must be an emitted exact route or `runtimeParams` bracket pattern and export the same layout function. The layout DOM, state, and top-level effects persist; route state, parameters, and top-level effects reset after cleanup on each transition. Eligible ordinary anchors prefetch validated complete documents into a finite memory cache. Direct requests, reloads, malformed runtime paths, JavaScript failures, unsupported links, and routes outside the group retain native document navigation.
 
-Runtime bracket routes, multiple layout groups, and conditional or keyed effects inside a navigation group are not supported yet.
+Multiple layout groups and conditional or keyed effects inside a navigation group are not supported yet.
 
 This produces fast same-document route changes, but it does not add a coordinated transition animation. CSS entry animations can style newly inserted route content; exit and shared-element View Transitions are not integrated yet.
 
@@ -498,7 +498,7 @@ Supported:
 - Top-level and block-scoped JSX locals, terminal early returns, and exhaustive JSX assignment
 - Direct keyed local-state lists
 - Page-exported shared layouts with layout/route state lifetimes
-- Opt-in exact-route navigation with complete-document prefetch and native fallback
+- Opt-in exact/runtime-route navigation with complete-document prefetch and native fallback
 - Layout- and route-lifetime effect mounts in navigation groups
 
 Not implemented yet:
@@ -534,7 +534,7 @@ The mobile profile uses a 390x844 viewport, 6x CPU slowdown, 150 ms latency, and
 | Desktop | 324 ms | 140 ms | 3.7 ms | 5.7 ms | 3.3 ms | 110.8 ms | 0 |
 | Mobile | 420 ms | 220 ms | 5.6 ms | 8.7 ms | 4.1 ms | 158 ms | 0 |
 
-Small clean builds are the known tradeoff. Seven rotating production builds measured Kudzu at 460.8 ms and React at 429.5 ms; a separate 21-run interleaved check measured 578.6 ms and 542.5 ms. The repeatable 6–7% difference is primarily TypeScript ESM/compiler startup. Attempts to replace generated-handler lowering or share one TypeScript Program did not improve the combined median and were not retained.
+Initial runs found a repeatable 6–7% small-build loss from TypeScript and esbuild module startup. Kudzu now enables Node's native module compile cache before lazily loading the compiler. An empty-cache build measured 541.4 ms against the previous 547.6 ms path; after one warm-up, 31 interleaved artifact-clean builds measured Kudzu at 425.8 ms and React at 483.4 ms, making Kudzu 11.9% faster in that run. Disabling the cache preserves byte-for-byte output. Attempts to replace generated-handler lowering or share one TypeScript Program did not improve the combined median and were not retained.
 
 These results describe this six-route fixture on one machine, not framework ecosystem size or every rendering mode. Prefetch improves an eligible warm application transition; it does not hide cold transfer, and direct loads remain complete standalone documents.
 

package/bin/kudzu.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
-import { build, dev } from "../framework/build.mjs"
+import * as module from "node:module"
 
 const command = process.argv[2] ?? "dev"
 
-if (command === "build") {
-  await build()
-} else if (command === "dev") {
-  await dev()
+if (command === "build" || command === "dev") {
+  module.enableCompileCache?.()
+  const { build, dev } = await import("../framework/build.mjs")
+  await (command === "build" ? build : dev)()
 } else {
   console.error(`Unknown command: ${command}\nUse: kudzu <build|dev>`)
   process.exitCode = 1

package/framework/README.md

@@ -11,7 +11,7 @@
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `effect-runtime.js`: optional state and capture context for route-specific mount-effect entries.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
-- `navigation-runtime.js`: optional exact-route complete-document prefetch, validation, finite memory caching, route-range replacement, history, focus, and native fallback for one configured shared layout.
+- `navigation-runtime.js`: optional emitted-route complete-document prefetch, runtime segment matching, validation, finite memory caching, route-range replacement, history, focus, and native fallback for one configured shared layout.
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
@@ -19,6 +19,6 @@ Static routes receive no browser runtime. Command routes receive `runtime.js`; d
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime. Source CSS and global `kudzu.config` styles are emitted in document heads before `afterBuild()` runs; static stylesheet links in component JSX fail compilation instead of loading from the body.
 
-`kudzu.config` may opt one exact static shared-layout group into same-document navigation with `navigation: { routes: ["/product", "/cart"] }`. The routes must be unique emitted paths and export the same layout function identity. Route effect entries export cache-safe layout and route mount functions: layout effects mount once per document session, route effects remount after each route insertion, and non-persisted page disposal cleans route before layout. Primitive dependencies and cleanup are supported; conditional/keyed DOM-owned effects fail with a source-located diagnostic in navigation groups. Eligible same-origin anchors prefetch complete documents when near the viewport, hovered, or focused; validated documents are cached only in memory by full URL while represented by the current route. Runtime bracket enhancement, multiple groups, and fragment payloads are not implemented.
+`kudzu.config` may opt one emitted shared-layout group into same-document navigation with `navigation: { routes: ["/product", "/items/[id]"] }`. The configured identities must be unique emitted exact paths or `runtimeParams` patterns and export the same layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Route effect entries export cache-safe layout and route mount functions: layout effects mount once per document session, route effects remount after each route insertion, and non-persisted page disposal cleans route before layout. Primitive dependencies and cleanup are supported; conditional/keyed DOM-owned effects fail with a source-located diagnostic in navigation groups. Eligible same-origin anchors prefetch complete documents when near the viewport, hovered, or focused; validated documents are cached only in memory by full URL while represented by the current route. Multiple groups and fragment payloads are not implemented.
 
-The matched Goal A commerce profile emits 34,879 deploy bytes and loads 7,215 B gzip of product-route JavaScript, including 2,306 B for navigation. Validated prefetch reduced product-to-cart navigation from 128.7 ms to 5.7 ms. The known tradeoff is a repeatable 6-7% clean-build loss against the matched small React build, primarily from TypeScript startup; failed handler-lowering and shared-Program experiments were not retained.
+The matched Goal A commerce profile emits 34,879 deploy bytes and loads 7,215 B gzip of product-route JavaScript, including 2,306 B for navigation. Validated prefetch reduced product-to-cart navigation from 128.7 ms to 5.7 ms. The CLI enables Node's native module compile cache before lazily importing the compiler: 31 interleaved artifact-clean builds after one warm-up measured Kudzu at 425.8 ms and React at 483.4 ms. The first empty-cache invocation remains unchanged within noise, and cache-disabled output is byte-for-byte identical.

package/framework/build.mjs

@@ -22,7 +22,6 @@ export async function build({ quiet = false, minify = true } = {}) {
   const configuredStyles = normalizeStyles(config.styles, base)
   const navigationRoutes = normalizeNavigation(config.navigation)
   const navigationSet = new Set(navigationRoutes)
-  const browserNavigationRoutes = navigationRoutes.map(route => withBase(base, route))
   const navigationAsset = assetPath(base, "assets/kudzu-navigation.js")
   const navigationId = navigationRoutes.length ? createHash("sha256").update(JSON.stringify([...navigationRoutes].sort())).digest("hex").slice(0, 16) : undefined
   const applicationId = navigationId ? `a-${navigationId}` : undefined
@@ -63,6 +62,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const rewrites = []
   const emittedRoutes = new Set()
   const emittedApplicationRoutes = new Set()
+  const navigationRecords = []
   const styleUrls = [...new Set([
     ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
     ...configuredStyles
@@ -99,10 +99,12 @@ export async function build({ quiet = false, minify = true } = {}) {
       emittedRoutes.add(routePath)
       emittedApplicationRoutes.add(applicationRoute)
       if (navigable) {
-        if (runtimeSchema) throw new Error(`kudzu.config navigation route ${JSON.stringify(routePath)} must be an exact static route; runtime bracket routes are not supported`)
-        if (typeof module.layout !== "function") throw new Error(`kudzu.config navigation route ${JSON.stringify(routePath)} must export a layout function so Kudzu can emit route markers`)
+        if (typeof module.layout !== "function") throw new Error(`kudzu.config navigation emitted route ${JSON.stringify(routePath)} must export a layout function so Kudzu can emit route markers`)
         if (navigationLayout && navigationLayout !== module.layout) throw new Error("kudzu.config navigation routes must export the same layout function identity")
         navigationLayout = module.layout
+        navigationRecords.push(runtimeSchema
+          ? { id: applicationRoute, base: browserPath(base), segments: runtimeSchema.segments.map(segment => segment.literal ?? null) }
+          : { id: applicationRoute, path: routePath })
       }
       const result = await renderPage(module.default, {
         ...(module.metadata ?? {}),
@@ -112,13 +114,13 @@ export async function build({ quiet = false, minify = true } = {}) {
         effectAsset: assetPath(base, `assets/${effectPath}`),
         paramAsset: assetPath(base, `assets/${paramPath}`),
         runtimeParams: runtimeSchema?.params,
-        ...(navigable ? { navigationAsset, applicationId, layoutId } : {})
+        ...(navigable ? { navigationAsset, applicationId, layoutId, routeId: applicationRoute } : {})
       }, props, module.layout)
       const hasDependencies = result.plan.effects.some(effect => effect.dependencies?.length)
       const usesDependencyRuntime = !navigable && hasDependencies && !result.plan.effects.some(effect => effect.owner) && !result.hasBindings && !result.hasLists && !result.plan.events.some(event => event.native)
       pageEntries.push({ route, html: result.html, usesDependencyRuntime })
       plans.push({ route: routePath, ...result.plan })
-      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, usesDependencyRuntime })
+      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, usesDependencyRuntime, navigable })
       if (result.hasEffects) effectEntries.push({ path: effectPath, effects: runtimeEffects(result.plan.effects, navigable), paramPath: result.hasParams ? paramPath : undefined, usesDependencyRuntime, navigable })
       if (result.hasBehaviors) {
         behaviorCount++
@@ -134,7 +136,8 @@ export async function build({ quiet = false, minify = true } = {}) {
     }
   }
 
-  for (const route of navigationRoutes) if (!emittedApplicationRoutes.has(route)) throw new Error(`kudzu.config navigation route ${JSON.stringify(route)} is not an exact emitted route`)
+  for (const route of navigationRoutes) if (!emittedApplicationRoutes.has(route)) throw new Error(`kudzu.config navigation route ${JSON.stringify(route)} is not an emitted route`)
+  navigationRecords.sort((left, right) => (right.segments?.filter(segment => segment !== null).length ?? 0) - (left.segments?.filter(segment => segment !== null).length ?? 0) || left.id.localeCompare(right.id))
 
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
@@ -158,6 +161,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasNativeHandlers = nativeModules.length > 0
   const hasEffects = effectEntries.length > 0
   const hasNavigableEffects = effectEntries.some(entry => entry.navigable)
+  const hasNavigableParams = paramEntries.some(entry => entry.navigable)
   const hasSharedRuntime = bindingCount || listCount || hasNativeHandlers || navigationRoutes.length
   const hasDependencyRuntime = pageEntries.some(entry => entry.usesDependencyRuntime)
   const runtimeName = usesDependencyRuntime => usesDependencyRuntime ? "kudzu-deps.js" : "kudzu.js"
@@ -234,12 +238,13 @@ export async function build({ quiet = false, minify = true } = {}) {
     })
   }
   if (navigationRoutes.length) {
-    const navigationRuntime = (await readFile(new URL("./navigation-runtime.js", import.meta.url), "utf8"))
-      .replace("__KUDZU_NAVIGATION_ROUTES__", inlineJson(browserNavigationRoutes))
+    let navigationRuntime = (await readFile(new URL("./navigation-runtime.js", import.meta.url), "utf8"))
+      .replace("__KUDZU_NAVIGATION_ROUTES__", inlineJson(navigationRecords))
       .replace("__KUDZU_APPLICATION_ID__", JSON.stringify(applicationId))
       .replace("__KUDZU_LAYOUT_ID__", JSON.stringify(layoutId))
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
-    await writeJavaScript(join(assetsDirectory, "kudzu-navigation.js"), specializeNavigationEffects(navigationRuntime, hasNavigableEffects), minify)
+    navigationRuntime = specializeNavigationPatterns(navigationRuntime, navigationRecords.some(record => record.segments))
+    await writeJavaScript(join(assetsDirectory, "kudzu-navigation.js"), specializeNavigationEffects(navigationRuntime, hasNavigableEffects || hasNavigableParams), minify)
   }
   for (const handlerModule of handlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
@@ -249,7 +254,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   for (const entry of paramEntries) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
-    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base, runtimeName(entry.usesDependencyRuntime)), minify)
+    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base, runtimeName(entry.usesDependencyRuntime), entry.navigable), minify)
   }
   for (const entry of effectEntries) {
     const output = join(assetsDirectory, entry.path)
@@ -319,26 +324,42 @@ function specializeNavigationEffects(source, enabled) {
     .replace(`
 async function mountInitial() {
   try {
-    const effects = await loadCapabilities(validate(document))
-    layoutDispose = await effects?.mountLayoutEffects?.() ?? noDispose
-    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose
+    const record = matchRoute(location.pathname)
+    if (!record) throw new Error("Initial navigation route does not match")
+    const capabilities = await loadCapabilities(validate(document, record))
+    capabilities.params?.(location.pathname)
+    layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
+    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
   } catch (error) {
     console.error(error)
   }
 }
 `, "")
     .replace("  await ready\n", "")
-    .replace("    const effects = await loadCapabilities(parsed)\n", "    await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n")
+    .replace("    const capabilities = await loadCapabilities(parsed)\n", "    await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n")
     .replace("    await routeDispose()\n    if (current !== revision) return\n", "")
-    .replace("    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose\n", "")
+    .replace("    commit(incoming, parsed.nodes, capabilities.params, url.pathname)\n", "    commit(incoming, parsed.nodes)\n")
+    .replace("    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "")
     .replace(`
 async function loadCapabilities(parsed) {
   const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
-  return modules.find(module => typeof module.mountRouteEffects === "function")
+  const params = modules.filter(module => typeof module.initializeParams === "function")
+  const effects = modules.filter(module => typeof module.mountRouteEffects === "function")
+  if (params.length > 1 || effects.length > 1) throw new Error("Navigation document has duplicate route capabilities")
+  return { params: params[0]?.initializeParams, effects: effects[0] }
 }
 `, "")
 }
 
+function specializeNavigationPatterns(source, enabled) {
+  if (enabled) return source
+  return source.replace(/function matchRoute\(pathname\) \{[\s\S]+?\n\}\n\nfunction fallback/, `function matchRoute(pathname) {
+  return routes.find(record => record.path === pathname)
+}
+
+function fallback`)
+}
+
 function specializeNativeRuntime(source, events, modules) {
   const imports = modules.map((module, index) => `import * as __kNativeModule${index} from ${JSON.stringify(module)}`).join("\n")
   const entries = modules.map((module, index) => `[${JSON.stringify(module)}, __kNativeModule${index}]`).join(",")
@@ -922,12 +943,14 @@ async function invokeCleanup() {
 }${disposal}`
 }
 
-function printParamEntry(schema, params, output, assetsDirectory, base, runtimeName) {
+function printParamEntry(schema, params, output, assetsDirectory, base, runtimeName, navigable) {
+  const prefix = navigable ? "export function initializeParams(pathname) {\n" : "let pathname = location.pathname\n"
+  const suffix = navigable ? "\n}" : ""
   return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
 const base = ${inlineJson(browserPath(base).slice(1).split("/").filter(Boolean).map(segment => decodeURIComponent(segment)))}
 const schema = ${inlineJson(schema.segments)}
 const params = ${inlineJson(params)}
-let path = location.pathname
+${prefix}let path = pathname
 if (base.length) {
   const pathSegments = path.slice(1).split("/")
   if (pathSegments.length < base.length || base.some((segment, index) => decodeSegment(pathSegments[index], false) !== segment)) throw new Error("Runtime route is outside the configured base")
@@ -955,7 +978,7 @@ function decodeSegment(raw, param) {
   const decodedDots = value.replace(/%2e/gi, ".")
   if (param && (!value || value === "." || value === ".." || decodedDots === "." || decodedDots === ".." || /[\\/?#]/.test(value) || [...value].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159) || /%(?:2f|5c)/i.test(value))) throw new Error("Runtime route parameter is invalid")
   return value
-}`
+}${suffix}`
 }
 
 function hasCaptureType(value, type) {

package/framework/core.mjs

@@ -358,7 +358,7 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
       : ""
 
     return {
-      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}${navigationRuntime}</head><body${state}${textBindings}${metadata.applicationId ? ` data-k-application="${escapeAttribute(metadata.applicationId)}" data-k-layout="${escapeAttribute(metadata.layoutId)}"` : ""}>${body}</body></html>`,
+      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}${navigationRuntime}</head><body${state}${textBindings}${metadata.applicationId ? ` data-k-application="${escapeAttribute(metadata.applicationId)}" data-k-layout="${escapeAttribute(metadata.layoutId)}" data-k-route="${escapeAttribute(metadata.routeId)}"` : ""}>${body}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasEffects: renderContext.hasEffects,
       hasParams: renderContext.hasParams,

package/framework/navigation-runtime.js

@@ -1,6 +1,6 @@
 import { browserState, mountDom, unmountDom } from "./shared-runtime.js"
 
-const routes = new Set(__KUDZU_NAVIGATION_ROUTES__)
+const routes = __KUDZU_NAVIGATION_ROUTES__
 const applicationId = __KUDZU_APPLICATION_ID__
 const layoutId = __KUDZU_LAYOUT_ID__
 const navigationAsset = new URL(import.meta.url).pathname
@@ -46,9 +46,12 @@ discover()
 
 async function mountInitial() {
   try {
-    const effects = await loadCapabilities(validate(document))
-    layoutDispose = await effects?.mountLayoutEffects?.() ?? noDispose
-    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose
+    const record = matchRoute(location.pathname)
+    if (!record) throw new Error("Initial navigation route does not match")
+    const capabilities = await loadCapabilities(validate(document, record))
+    capabilities.params?.(location.pathname)
+    layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
+    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
   } catch (error) {
     console.error(error)
   }
@@ -64,7 +67,7 @@ function eligibleAnchor(anchor) {
   if (anchor.relList?.contains("external")) return false
   const url = new URL(anchor.href)
   if (url.hash && url.pathname === location.pathname && url.search === location.search) return false
-  return url.origin === location.origin && routes.has(url.pathname)
+  return url.origin === location.origin && Boolean(matchRoute(url.pathname))
 }
 
 function discover() {
@@ -94,7 +97,7 @@ function prefetchAnchor(anchor) {
   const url = new URL(anchor.href)
   prune([...document.querySelectorAll("a[href]")].filter(eligibleAnchor))
   if (documents.has(url.href)) return
-  const pending = fetchDocument(url)
+  const pending = fetchDocument(url, matchRoute(url.pathname))
   documents.set(url.href, pending)
   pending.catch(() => {
     if (documents.get(url.href) === pending) documents.delete(url.href)
@@ -108,6 +111,8 @@ function prune(anchors) {
 
 async function navigate(url, push) {
   await ready
+  const record = matchRoute(url.pathname)
+  if (!record) return fallback(url, push)
   const current = ++revision
   request?.abort()
   request = new AbortController()
@@ -117,17 +122,17 @@ async function navigate(url, push) {
     const cached = documents.get(url.href)
     if (cached) {
       try { documentResult = await cached }
-      catch { documentResult = await fetchDocument(url, request.signal) }
-    } else documentResult = await fetchDocument(url, request.signal)
+      catch { documentResult = await fetchDocument(url, record, request.signal) }
+    } else documentResult = await fetchDocument(url, record, request.signal)
     documents.set(url.href, Promise.resolve(documentResult))
     const { incoming, parsed } = documentResult
-    const effects = await loadCapabilities(parsed)
+    const capabilities = await loadCapabilities(parsed)
     if (current !== revision) return
     await routeDispose()
     if (current !== revision) return
-    commit(incoming, parsed.nodes)
-    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose
+    commit(incoming, parsed.nodes, capabilities.params, url.pathname)
     committed = true
+    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
     if (push) history.pushState(null, "", url)
     updateHead(incoming)
     focusAndScroll(url)
@@ -135,26 +140,28 @@ async function navigate(url, push) {
     discover()
   } catch (error) {
     if (current !== revision || error.name === "AbortError") return
-    if (push) location.assign(url.href)
-    else location.reload()
+    fallback(url, push)
     if (committed) return
   }
 }
 
 async function loadCapabilities(parsed) {
   const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
-  return modules.find(module => typeof module.mountRouteEffects === "function")
+  const params = modules.filter(module => typeof module.initializeParams === "function")
+  const effects = modules.filter(module => typeof module.mountRouteEffects === "function")
+  if (params.length > 1 || effects.length > 1) throw new Error("Navigation document has duplicate route capabilities")
+  return { params: params[0]?.initializeParams, effects: effects[0] }
 }
 
-async function fetchDocument(url, signal) {
+async function fetchDocument(url, record, signal) {
   const response = await fetch(url, { signal, redirect: "manual", headers: { accept: "text/html" } })
   if (!response.ok || response.redirected || response.type === "opaqueredirect" || !response.headers.get("content-type")?.toLowerCase().includes("text/html")) throw new Error("Navigation response is not successful nonredirected HTML")
   const incoming = new DOMParser().parseFromString(await response.text(), "text/html")
-  return { incoming, parsed: validate(incoming) }
+  return { incoming, parsed: validate(incoming, record), record }
 }
 
-function validate(incoming) {
-  if (incoming.body.dataset.kApplication !== applicationId || incoming.body.dataset.kLayout !== layoutId) throw new Error("Navigation document identity does not match")
+function validate(incoming, record) {
+  if (incoming.body.dataset.kApplication !== applicationId || incoming.body.dataset.kLayout !== layoutId || incoming.body.dataset.kRoute !== record.id) throw new Error("Navigation document identity does not match")
   const starts = incoming.querySelectorAll("template[data-k-route-start]")
   const ends = incoming.querySelectorAll("template[data-k-route-end]")
   if (starts.length !== 1 || ends.length !== 1) throw new Error("Navigation document must contain exactly one route marker pair")
@@ -168,7 +175,7 @@ function validate(incoming) {
   return { nodes, assets: [...new Set(assets)] }
 }
 
-function commit(incoming, incomingNodes) {
+function commit(incoming, incomingNodes, initializeParams, pathname) {
   const start = document.querySelector("template[data-k-route-start]")
   const end = document.querySelector("template[data-k-route-end]")
   if (!start || !end || document.querySelectorAll("template[data-k-route-start],template[data-k-route-end]").length !== 2) throw new Error("Current route markers are invalid")
@@ -179,11 +186,50 @@ function commit(incoming, incomingNodes) {
   for (const [id, value, compact] of JSON.parse(incoming.body.dataset.kState ?? "[]")) if (id.startsWith("r")) browserState.set(id, compact ? value[1].map(row => Object.fromEntries(value[0].map((field, index) => [field, row[index]]))) : value)
   if (incoming.body.dataset.kTextBindings === undefined) delete document.body.dataset.kTextBindings
   else document.body.dataset.kTextBindings = incoming.body.dataset.kTextBindings
+  document.body.dataset.kRoute = incoming.body.dataset.kRoute
   const nodes = incomingNodes.map(node => document.importNode(node, true))
   end.before(...nodes)
+  initializeParams?.(pathname)
   for (const node of nodes) mountDom(node)
 }
 
+function matchRoute(pathname) {
+  const exact = routes.find(record => record.path === pathname)
+  if (exact) return exact
+  for (const record of routes) {
+    if (!record.segments) continue
+    try {
+      let path = pathname
+      if (record.base) {
+        const pathSegments = path.slice(1).split("/")
+        const baseSegments = record.base.slice(1).split("/").map(segment => decodeURIComponent(segment))
+        if (pathSegments.length < baseSegments.length || baseSegments.some((segment, index) => decodeSegment(pathSegments[index], false) !== segment)) continue
+        path = `/${pathSegments.slice(baseSegments.length).join("/")}`
+      }
+      if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
+      const segments = path.slice(1).split("/")
+      if (segments.length !== record.segments.length) continue
+      if (record.segments.every((literal, index) => {
+        const value = decodeSegment(segments[index], literal === null)
+        return literal === null || value === literal
+      })) return record
+    } catch {}
+  }
+}
+
+function decodeSegment(raw, param) {
+  if (param && /%(?:2f|5c)/i.test(raw)) throw new Error("Encoded separator")
+  const value = decodeURIComponent(raw)
+  const decodedDots = value.replace(/%2e/gi, ".")
+  if (param && (!value || value === "." || value === ".." || decodedDots === "." || decodedDots === ".." || /[\\/?#]/.test(value) || [...value].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159) || /%(?:2f|5c)/i.test(value))) throw new Error("Invalid runtime parameter")
+  return value
+}
+
+function fallback(url, push) {
+  if (push) location.assign(url.href)
+  else location.reload()
+}
+
 function between(start, end) {
   if (start.parentNode !== end.parentNode) throw new Error("Route markers must share a parent")
   const nodes = []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",