@kudzujs/core 0.6.1 → 0.6.3

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 independent shared-layout groups were added post-Goal-A; conditional/keyed DOM-owned effects inside a navigation group remain a deliberate limit.
 
 - **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,12 @@ 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 post-Goal-A multiple-group fixture emits a 7,448 B raw / 3,099 B gzip (`gzip -9`) mixed runtime/effect group asset, including one native exclusion for an overlapping ungrouped exact route, and a separately specialized 5,681 B raw / 2,448 B gzip exact effect-free group asset. These measurements do not revise the historical Goal A benchmark.
+
+A current 0.6.2 desktop rerun of the matched six-route commerce fixture measured Kudzu at 462.1 ms build, 35,355 deploy bytes, 7,334 B gzip product JavaScript, 324/152 ms cold/warm LCP, 109.3 ms startup task, 3.9 ms interaction, and 6.1 ms product-cart navigation. React measured 508.5 ms build, 61,464 B gzip product JavaScript, 340/244 ms LCP, 166.2 ms startup task, 10.9 ms interaction, and 8.9 ms navigation. Raw arrays and the consolidated report are retained under the local demo benchmark workspace.
+
 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.
@@ -108,7 +114,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,30 @@ 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.
+The legacy single-group form remains supported. Applications with multiple shared layouts use mutually exclusive `groups`:
 
-Runtime bracket routes, multiple layout groups, and conditional or keyed effects inside a navigation group are not supported yet.
+```js
+export default {
+  navigation: { groups: [
+    { routes: ["/product", "/items/[id]"] },
+    { routes: ["/account", "/settings"] }
+  ] }
+}
+```
+
+Every configured identity must be a unique emitted exact route or `runtimeParams` bracket pattern. Routes within each group must export the same layout function identity; different groups may export different layouts. Kudzu emits one deterministic, route-set-hashed navigation asset per group containing only that group's records and capabilities. Path domains may overlap within a group, where exact and more-specific matching wins, but overlapping exact/runtime or runtime/runtime domains across groups fail the build.
+
+The layout DOM, state, and top-level effects persist within its group; route state, parameters, and top-level effects reset after cleanup on each transition. Eligible same-group anchors prefetch validated complete documents into a finite memory cache. Cross-group links, ungrouped routes, direct requests, reloads, malformed runtime paths, JavaScript failures, and unsupported links retain native document navigation.
+
+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 +511,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:
@@ -519,22 +532,22 @@ Browser medians use seven rotating fresh Chrome profiles per target with 4x CPU
 
 | Target | Product JS gzip | Cold transfer | Cold LCP | Warm LCP | Startup task | Heap | Interaction | Product → cart |
 |---|---:|---:|---:|---:|---:|---:|---:|---:|
-| Kudzu | **7,215 B** | **34,809 B** | 324 ms | **140 ms** | **103.3 ms** | **648,844 B** | **3.7 ms** | **5.7 ms** |
-| React + Vite | 61,464 B | 202,842 B | 324 ms | 232 ms | 160.0 ms | 1,062,520 B | 10.5 ms | 8.3 ms |
-| Next.js | 190,090 B | 546,581 B | **316 ms** | 156 ms | 357.7 ms | 2,157,020 B | 11.4 ms | 26.9 ms |
-| Nuxt | 67,620 B | 195,953 B | 320 ms | 204 ms | 205.1 ms | 1,721,348 B | 3.9 ms | 33.0 ms |
-| SvelteKit | 32,473 B | 90,929 B | 340 ms | 172 ms | 125.8 ms | 999,496 B | 4.7 ms | 20.3 ms |
+| Kudzu | **7,334 B** | **35,260 B** | 324 ms | **152 ms** | **109.3 ms** | **650,708 B** | **3.9 ms** | **6.1 ms** |
+| React + Vite | 61,464 B | 202,842 B | 340 ms | 244 ms | 166.2 ms | 1,062,512 B | 10.9 ms | 8.9 ms |
+| Next.js | 190,090 B | 546,581 B | **320 ms** | 168 ms | 413.0 ms | 2,158,160 B | 14.3 ms | 29.8 ms |
+| Nuxt | 67,620 B | 195,953 B | 328 ms | 216 ms | 243.8 ms | 1,721,348 B | 4.3 ms | 28.4 ms |
+| SvelteKit | 32,475 B | 90,934 B | 352 ms | 176 ms | 150.5 ms | 999,496 B | 5.2 ms | 24.0 ms |
 
-The Kudzu application emits 34,879 deploy bytes. Its 7,215 B gzip product graph includes the 2,306 B navigation capability. The first implementation paid a 128.7 ms HTML round trip during product-to-cart navigation; validated near-viewport document prefetch reduced the measured median to 5.7 ms while preserving complete documents and native fallback.
+The current Kudzu application emits 35,355 deploy bytes. Its 7,334 B gzip product graph includes the 2,425 B navigation capability. The first implementation paid a 128.7 ms HTML round trip during product-to-cart navigation; validated near-viewport document prefetch measured 6.1 ms in the current run while preserving complete documents and native fallback.
 
-The mobile profile uses a 390x844 viewport, 6x CPU slowdown, 150 ms latency, and 150 KiB/s throughput:
+The mobile row is retained from the previous matched run using a 390x844 viewport, 6x CPU slowdown, 150 ms latency, and 150 KiB/s throughput:
 
 | Profile | Cold LCP | Warm LCP | Interaction | Product → cart | Reject feedback | Rollback/error | CLS |
 |---|---:|---:|---:|---:|---:|---:|---:|
-| Desktop | 324 ms | 140 ms | 3.7 ms | 5.7 ms | 3.3 ms | 110.8 ms | 0 |
+| Desktop | 324 ms | 152 ms | 3.9 ms | 6.1 ms | 2.6 ms | 111.7 ms | 0 |
 | Mobile | 420 ms | 220 ms | 5.6 ms | 8.7 ms | 4.1 ms | 158 ms | 0 |
 
-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.
+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. The current seven-run matched commerce build measured Kudzu at 462.1 ms and React at 508.5 ms, making Kudzu 9.1% 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/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, specialized once per configured shared-layout group.
 - `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 legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported 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. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects mount once per group 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. Fragment payloads and coordinated View Transitions 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 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.
+The current matched commerce profile emits 35,355 deploy bytes and loads 7,334 B gzip of product-route JavaScript, including 2,425 B for navigation. Validated prefetch reduced the original 128.7 ms product-to-cart navigation to 6.1 ms in the current run. Seven interleaved artifact-clean builds after warm-up measured Kudzu at 462.1 ms and React at 508.5 ms. Cache-disabled output is byte-for-byte identical.

package/framework/build.mjs

@@ -20,14 +20,18 @@ export async function build({ quiet = false, minify = true } = {}) {
   const config = await loadConfig()
   const base = normalizeBase(config.base)
   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
-  const layoutId = navigationId ? `l-${navigationId}` : undefined
-  let navigationLayout
+  const navigationGroups = normalizeNavigation(config.navigation)
+  const navigationRoutes = navigationGroups.flatMap(group => group.routes)
+  const navigationByRoute = new Map(navigationGroups.flatMap(group => group.routes.map(route => [route, group])))
+  for (const group of navigationGroups) {
+    group.assetPath = assetPath(base, `assets/${group.assetName}`)
+    group.applicationId = `a-${group.id}`
+    group.layoutId = `l-${group.id}`
+    group.records = []
+    group.routeRecords = []
+    group.hasEffects = false
+    group.hasParams = false
+  }
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
   await mkdir(workDirectory, { recursive: true })
@@ -63,6 +67,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const rewrites = []
   const emittedRoutes = new Set()
   const emittedApplicationRoutes = new Set()
+  const emittedNavigationRecords = []
   const styleUrls = [...new Set([
     ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
     ...configuredStyles
@@ -92,17 +97,25 @@ export async function build({ quiet = false, minify = true } = {}) {
       const route = runtimeSchema?.route ?? routeFromPage(pageFile, params)
       const applicationRoute = `/${route}`
       const routePath = withBase(base, `/${route}`)
-      const navigable = navigationSet.has(applicationRoute)
+      const navigationGroup = navigationByRoute.get(applicationRoute)
+      const navigable = Boolean(navigationGroup)
       const effectPath = `effects/${route ? `${route}/index` : "index"}.js`
       const paramPath = `params/${route}/index.js`
       if (emittedRoutes.has(routePath)) throw new Error(`Duplicate route: ${routePath}`)
       emittedRoutes.add(routePath)
       emittedApplicationRoutes.add(applicationRoute)
+      const navigationRecord = runtimeSchema
+        ? { id: applicationRoute, base: browserPath(base), segments: runtimeSchema.segments.map(segment => segment.literal ?? null) }
+        : { id: applicationRoute, path: routePath }
+      const routeRecord = { route: applicationRoute, segments: runtimeSchema ? navigationRecord.segments : exactRouteSegments(applicationRoute), record: navigationRecord, group: navigationGroup }
+      emittedNavigationRecords.push(routeRecord)
       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 (navigationLayout && navigationLayout !== module.layout) throw new Error("kudzu.config navigation routes must export the same layout function identity")
-        navigationLayout = module.layout
+        if (typeof module.layout !== "function") throw new Error(`${navigationGroup.label} emitted route ${JSON.stringify(routePath)} must export a layout function so Kudzu can emit route markers`)
+        if (navigationGroup.layoutIdentity && navigationGroup.layoutIdentity !== module.layout) throw new Error(`${navigationGroup.label} routes ${JSON.stringify(navigationGroup.layoutRoute)} and ${JSON.stringify(applicationRoute)} must export the same layout function identity`)
+        navigationGroup.layoutIdentity = module.layout
+        navigationGroup.layoutRoute ??= applicationRoute
+        navigationGroup.records.push(navigationRecord)
+        navigationGroup.routeRecords.push(routeRecord)
       }
       const result = await renderPage(module.default, {
         ...(module.metadata ?? {}),
@@ -112,13 +125,17 @@ 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: navigationGroup.assetPath, applicationId: navigationGroup.applicationId, layoutId: navigationGroup.layoutId, routeId: applicationRoute } : {})
       }, props, module.layout)
+      if (navigationGroup) {
+        navigationGroup.hasEffects ||= result.hasEffects
+        navigationGroup.hasParams ||= result.hasParams
+      }
       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 +151,13 @@ 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 group of navigationGroups) for (const route of group.routes) if (!emittedApplicationRoutes.has(route)) throw new Error(`${group.label} route ${JSON.stringify(route)} is not an emitted route`)
+  rejectNavigationOverlap(navigationGroups)
+  for (const group of navigationGroups) {
+    const runtimeRecords = group.routeRecords.filter(record => record.record.segments)
+    for (const entry of emittedNavigationRecords) if (!entry.group && runtimeRecords.some(record => navigationDomainsOverlap(record, entry))) group.records.push({ ...entry.record, native: true })
+    group.records.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 })
@@ -233,13 +256,17 @@ export async function build({ quiet = false, minify = true } = {}) {
       "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
     })
   }
-  if (navigationRoutes.length) {
-    const navigationRuntime = (await readFile(new URL("./navigation-runtime.js", import.meta.url), "utf8"))
-      .replace("__KUDZU_NAVIGATION_ROUTES__", inlineJson(browserNavigationRoutes))
-      .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)
+  if (navigationGroups.length) {
+    const navigationSource = await readFile(new URL("./navigation-runtime.js", import.meta.url), "utf8")
+    for (const group of navigationGroups) {
+      let navigationRuntime = navigationSource
+        .replace("__KUDZU_NAVIGATION_ROUTES__", inlineJson(group.records))
+        .replace("__KUDZU_APPLICATION_ID__", JSON.stringify(group.applicationId))
+        .replace("__KUDZU_LAYOUT_ID__", JSON.stringify(group.layoutId))
+        .replace('"./shared-runtime.js"', '"./kudzu.js"')
+      navigationRuntime = specializeNavigationPatterns(navigationRuntime, group.records.some(record => record.segments))
+      await writeJavaScript(join(assetsDirectory, group.assetName), specializeNavigationEffects(navigationRuntime, group.hasEffects || group.hasParams), minify)
+    }
   }
   for (const handlerModule of handlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
@@ -249,7 +276,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 +346,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 +965,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 +1000,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) {
@@ -2860,19 +2905,64 @@ function normalizeStyles(value, base) {
 export function normalizeNavigation(value) {
   if (value === undefined) return []
   if (!isPlainRecord(value)) throw new Error("kudzu.config navigation must be a plain object")
-  if (Object.keys(value).some(key => key !== "routes")) throw new Error("kudzu.config navigation only supports routes")
-  if (!Array.isArray(value.routes) || !value.routes.length) throw new Error("kudzu.config navigation.routes must be a nonempty array")
-  const routes = value.routes.map((route, index) => {
-    if (typeof route !== "string" || !route.startsWith("/") || route.startsWith("//") || /[?#\\\0]/.test(route) || /%(?:2f|5c)/i.test(route)) throw new Error(`kudzu.config navigation.routes[${index}] must be a root-relative path without query, hash, or traversal`)
+  if (Object.keys(value).some(key => !["routes", "groups"].includes(key))) throw new Error("kudzu.config navigation only supports routes or groups")
+  if ((value.routes === undefined) === (value.groups === undefined)) throw new Error("kudzu.config navigation must define exactly one of routes or groups")
+  const inputs = value.routes === undefined ? value.groups : [{ routes: value.routes }]
+  if (!Array.isArray(inputs) || !inputs.length) throw new Error("kudzu.config navigation.groups must be a nonempty array")
+  const groups = inputs.map((group, groupIndex) => {
+    const label = value.routes === undefined ? `kudzu.config navigation.groups[${groupIndex}]` : "kudzu.config navigation"
+    if (!isPlainRecord(group)) throw new Error(`${label} must be a plain object`)
+    if (Object.keys(group).some(key => key !== "routes")) throw new Error(`${label} only supports routes`)
+    if (!Array.isArray(group.routes) || !group.routes.length) throw new Error(`${label}.routes must be a nonempty array`)
+    const routes = normalizeNavigationRoutes(group.routes, `${label}.routes`)
+    const id = createHash("sha256").update(JSON.stringify([...routes].sort())).digest("hex").slice(0, 16)
+    return { label, index: groupIndex, routes, routeSet: new Set(routes), id, assetName: value.routes === undefined ? `kudzu-navigation-${id}.js` : "kudzu-navigation.js" }
+  })
+  const identities = groups.flatMap(group => group.routes.map(route => [route, group.label]))
+  const seenRoutes = new Map()
+  for (const [route, label] of identities) {
+    if (seenRoutes.has(route)) throw new Error(`${label} route ${JSON.stringify(route)} duplicates ${seenRoutes.get(route)}`)
+    seenRoutes.set(route, label)
+  }
+  const seenAssets = new Map()
+  for (const group of groups) {
+    if (seenAssets.has(group.assetName)) throw new Error(`${group.label} navigation hash/asset collision with ${seenAssets.get(group.assetName)}`)
+    seenAssets.set(group.assetName, group.label)
+  }
+  return groups
+}
+
+function normalizeNavigationRoutes(values, label) {
+  const routes = values.map((route, index) => {
+    if (typeof route !== "string" || !route.startsWith("/") || route.startsWith("//") || /[?#\\\0]/.test(route) || /%(?:2f|5c)/i.test(route)) throw new Error(`${label}[${index}] must be a root-relative path without query, hash, or traversal`)
     let decoded
-    try { decoded = decodeURIComponent(route) } catch { throw new Error(`kudzu.config navigation.routes[${index}] must be a root-relative path without query, hash, or traversal`) }
-    if (decoded.split("/").includes("..") || /[?#\\\0]/.test(decoded)) throw new Error(`kudzu.config navigation.routes[${index}] must be a root-relative path without query, hash, or traversal`)
+    try { decoded = decodeURIComponent(route) } catch { throw new Error(`${label}[${index}] must be a root-relative path without query, hash, or traversal`) }
+    if (decoded.split("/").includes("..") || /[?#\\\0]/.test(decoded)) throw new Error(`${label}[${index}] must be a root-relative path without query, hash, or traversal`)
     return route
   })
-  if (new Set(routes).size !== routes.length) throw new Error("kudzu.config navigation.routes must contain unique paths")
+  if (new Set(routes).size !== routes.length) throw new Error(`${label} must contain unique paths`)
   return routes
 }
 
+function exactRouteSegments(route) {
+  return route.slice(1).split("/").map(segment => decodeURIComponent(segment))
+}
+
+function rejectNavigationOverlap(groups) {
+  for (let leftIndex = 0; leftIndex < groups.length; leftIndex++) for (let rightIndex = leftIndex + 1; rightIndex < groups.length; rightIndex++) {
+    const leftGroup = groups[leftIndex]
+    const rightGroup = groups[rightIndex]
+    for (const left of leftGroup.routeRecords) for (const right of rightGroup.routeRecords) {
+      if (!navigationDomainsOverlap(left, right)) continue
+      throw new Error(`Navigation path domains overlap between ${leftGroup.label} route ${JSON.stringify(left.route)} and ${rightGroup.label} route ${JSON.stringify(right.route)}`)
+    }
+  }
+}
+
+function navigationDomainsOverlap(left, right) {
+  return left.segments.length === right.segments.length && left.segments.every((segment, index) => segment === null || right.segments[index] === null || segment === right.segments[index])
+}
+
 function specializeNavigationTextDescriptors(source) {
   const dynamic = source
     .replace("const textDescriptors = globalThis.__KUDZU_TEXT_BINDINGS__ && typeof document !== \"undefined\" ? JSON.parse(document.body.dataset.kTextBindings ?? \"[]\") : []", "const textDescriptors = () => globalThis.__KUDZU_TEXT_BINDINGS__ ? JSON.parse(document.body.dataset.kTextBindings ?? \"[]\") : []")

package/framework/core.d.ts

@@ -57,6 +57,7 @@ export function renderPage<Props = Record<string, never>>(
     navigationAsset?: string
     applicationId?: string
     layoutId?: string
+    routeId?: string
   },
   props?: Props,
   layout?: (props: { children: unknown }) => unknown | Promise<unknown>

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.native ? undefined : 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.native ? undefined : 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.1",
+  "version": "0.6.3",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",