@kudzujs/core 0.6.2 → 0.6.4

package/GOAL_A.md

@@ -8,12 +8,12 @@ The benchmark runner, framework fixtures, generated artifacts, and raw arrays ar
 
 ## Implementation Status
 
-**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.
+**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 and conditional/keyed DOM-owned effects within layout and route lifetimes were added post-Goal-A.
 
 - **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.
 - **Phase 3 complete**: page-exported layouts render complete documents with compiler-owned route boundaries, collision-free layout/route IDs, and state/effect ownership metadata. Effects remain document effects and client navigation is unchanged.
-- **Phase 4 route/layout effects implemented**: top-level layout effects mount once per document session, top-level route effects remount after awaited route cleanup, and primitive dependency subscriptions exist only while their lifetime is mounted. Disposed effect setters and queued commits are inactive. Conditional/keyed DOM-owned effects remain unsupported inside navigation groups.
+- **Phase 4 route/layout effects implemented**: layout effects mount once per document session, route effects remount after awaited route cleanup, and primitive dependency subscriptions exist only while their lifetime is mounted. Conditional/keyed effects use per-lifetime owner registries; route registries are fresh on cached revisits. Disposed effect setters and queued commits are inactive. Keyed item-property dependencies remain unsupported.
 - **Phase 4 document prefetch implemented**: visible, near-visible, hovered, or focused eligible group anchors prefetch and validate complete documents without importing target capabilities. The finite in-memory full-URL cache removes the measured product-cart HTML RTT while preserving retry and native fallback.
 - **Phase 5 complete**: matched async cart success/rejection flows prove immediate optimistic updates, duplicate prevention, accessible errors, rollback, route-local reset, and stale-write suppression without new framework APIs.
 - **Phase 6 expansion probe complete**: one layout-owned mock `EventTarget` stream and one route-owned imperative chart stub use existing effects and a relative TypeScript helper across repeated navigation, with exact listener and disposal assertions. This proves only the compatibility seam; Kudzu does not provide telemetry or chart support.
@@ -25,6 +25,12 @@ In the focused effect-enabled navigation fixture, mount support adds 171 B gzip
 
 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.
+
+In a matched one-effect navigation build with the same conditional capability, moving the effect from the route body into the conditional owner changes the route effect entry from 2,181 B raw / 1,036 B gzip to 4,135 B raw / 1,807 B gzip (`+1,954 B` raw / `+771 B` gzip). Owner-hook unsubscription changes the shared runtime from 1,347 B raw / 718 B gzip to 1,459 B raw / 732 B gzip (`+112 B` raw / `+14 B` gzip). Top-level-only and effect-free navigation builds retain their smaller generators.
+
+A 0.6.4 release-tree desktop rerun of the matched six-route commerce fixture measured Kudzu at 486.8 ms build, 35,355 deploy bytes, 7,334 B gzip product JavaScript, 332/156 ms cold/warm LCP, 122.6 ms startup task, 4.8 ms interaction, and 5.6 ms product-cart navigation. React measured 545.4 ms build, 61,464 B gzip product JavaScript, 332/264 ms LCP, 179.9 ms startup task, 10.2 ms interaction, and 9.9 ms navigation. Kudzu built 10.7% faster and its top-level-only fixture retained byte-identical deploy, product-graph, and navigation-asset sizes after navigation-owned effects were added. 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.
@@ -110,7 +116,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 emitted exact/runtime-parameter 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 layout/route effects, including conditional/keyed DOM ownership.**
 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

@@ -457,9 +457,20 @@ export default {
 }
 ```
 
-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.
+The legacy single-group form remains supported. Applications with multiple shared layouts use mutually exclusive `groups`:
 
-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 effects persist within its group; route state, parameters, and effects reset after cleanup on each transition. Conditional effects mount only while their DOM is connected. Keyed row effects mount per connected row, survive reorder, read the latest row item when a supported state dependency reruns, and clean up on removal. Cached route modules create fresh route owner records and subscriptions on every revisit. Keyed item-property dependencies remain unsupported. 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.
 
 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.
 
@@ -500,6 +511,7 @@ Supported:
 - Page-exported shared layouts with layout/route state lifetimes
 - Opt-in exact/runtime-route navigation with complete-document prefetch and native fallback
 - Layout- and route-lifetime effect mounts in navigation groups
+- Conditional/keyed DOM-owned effects in navigation groups
 
 Not implemented yet:
 
@@ -507,7 +519,6 @@ Not implemented yet:
 - Server actions and request-time SSR
 - React package islands
 - HMR and framework DevTools
-- Conditional/keyed DOM-owned effects inside navigation groups
 
 ## Benchmarks
 
@@ -519,22 +530,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** | 332 ms | **156 ms** | **122.6 ms** | **650,708 B** | **4.8 ms** | **5.6 ms** |
+| React + Vite | 61,464 B | 202,842 B | 332 ms | 264 ms | 179.9 ms | 1,062,520 B | 10.2 ms | 9.9 ms |
+| Next.js | 190,090 B | 547,615 B | **324 ms** | 176 ms | 434.4 ms | 2,168,412 B | 14.0 ms | 30.0 ms |
+| Nuxt | 67,620 B | 195,953 B | **324 ms** | 224 ms | 247.9 ms | 1,721,348 B | **4.5 ms** | 29.6 ms |
+| SvelteKit | 32,474 B | 90,939 B | 376 ms | 184 ms | 143.8 ms | 999,496 B | 6.3 ms | 21.8 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; all three sizes are unchanged by conditional/keyed navigation effects because this top-level-only fixture retains the smaller specialized path. The first implementation paid a 128.7 ms HTML round trip during product-to-cart navigation; validated near-viewport document prefetch measured 5.6 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 | 332 ms | 156 ms | 4.8 ms | 5.6 ms | 4.0 ms | 112.1 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 486.8 ms and React at 545.4 ms, making Kudzu 10.7% faster in that run. Kudzu also shipped 88.1% less product JavaScript, used 38.8% less measured heap, and measured 52.9% faster interaction and 43.4% faster product-to-cart navigation than React. 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 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.
+- `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 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.
+`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, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Primitive dependencies and cleanup are supported, while keyed item-property dependencies remain unsupported. 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. These sizes are unchanged because its top-level-only navigation effects retain the smaller specialized path. Validated prefetch reduced the original 128.7 ms product-to-cart navigation to 5.6 ms in the current run. Seven interleaved artifact-clean builds after warm-up measured Kudzu at 486.8 ms and React at 545.4 ms, making Kudzu 10.7% faster. Cache-disabled output is byte-for-byte identical.

package/framework/build.mjs

@@ -20,13 +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 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 })
@@ -62,7 +67,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const rewrites = []
   const emittedRoutes = new Set()
   const emittedApplicationRoutes = new Set()
-  const navigationRecords = []
+  const emittedNavigationRecords = []
   const styleUrls = [...new Set([
     ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
     ...configuredStyles
@@ -92,19 +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 (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 })
+        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 ?? {}),
@@ -114,8 +125,12 @@ 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, routeId: applicationRoute } : {})
+        ...(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 })
@@ -136,8 +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 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))
+  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 })
@@ -161,7 +181,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 hasNavigableOwners = effectEntries.some(entry => entry.navigable && entry.effects.some(effect => effect.owner))
   const hasSharedRuntime = bindingCount || listCount || hasNativeHandlers || navigationRoutes.length
   const hasDependencyRuntime = pageEntries.some(entry => entry.usesDependencyRuntime)
   const runtimeName = usesDependencyRuntime => usesDependencyRuntime ? "kudzu-deps.js" : "kudzu.js"
@@ -175,6 +195,9 @@ export async function build({ quiet = false, minify = true } = {}) {
     const runtimeFile = hasSharedRuntime ? "./shared-runtime.js" : "./runtime.js"
     let runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, regularStateSeedCount > 0)
     if (hasNavigableEffects) runtime = runtime.replace("export function registerCommitter(commit) {\n  committers.push(commit)\n}", "export function registerCommitter(commit) {\n  committers.push(commit)\n  return () => {\n    const index = committers.indexOf(commit)\n    if (index !== -1) committers.splice(index, 1)\n  }\n}")
+    if (hasNavigableOwners) runtime = runtime
+      .replace("export function registerMountHook(mount) {\n  mountHooks.push(mount)\n}", "export function registerMountHook(mount) {\n  mountHooks.push(mount)\n  return () => {\n    const index = mountHooks.indexOf(mount)\n    if (index !== -1) mountHooks.splice(index, 1)\n  }\n}")
+      .replace("export function registerUnmountHook(unmount) {\n  unmountHooks.push(unmount)\n}", "export function registerUnmountHook(unmount) {\n  unmountHooks.push(unmount)\n  return () => {\n    const index = unmountHooks.indexOf(unmount)\n    if (index !== -1) unmountHooks.splice(index, 1)\n  }\n}")
     await writeJavaScript(join(assetsDirectory, "kudzu.js"), runtime, minify)
   }
   if (hasDependencyRuntime) {
@@ -237,14 +260,17 @@ export async function build({ quiet = false, minify = true } = {}) {
       "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
     })
   }
-  if (navigationRoutes.length) {
-    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"')
-    navigationRuntime = specializeNavigationPatterns(navigationRuntime, navigationRecords.some(record => record.segments))
-    await writeJavaScript(join(assetsDirectory, "kudzu-navigation.js"), specializeNavigationEffects(navigationRuntime, hasNavigableEffects || hasNavigableParams), 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)
@@ -260,7 +286,9 @@ export async function build({ quiet = false, minify = true } = {}) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
     await writeJavaScript(output, entry.navigable
-      ? printNavigableEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base)
+      ? entry.effects.some(effect => effect.owner)
+        ? printOwnedNavigableEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base)
+        : printNavigableEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base)
       : printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath, runtimeName(entry.usesDependencyRuntime)), minify)
   }
   const clientModules = await collectClientModules(handlerModules.flatMap(module => module.clientImports), sourceFileSet)
@@ -655,6 +683,237 @@ function mount(lifetime) {
 }`
 }
 
+function printOwnedNavigableEffectEntry(effects, output, handlerModules, assetsDirectory, base) {
+  const moduleUrls = [...new Set(effects.map(effect => effect.module))]
+  const modules = moduleUrls.map(url => {
+    const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
+    if (!module) throw new Error(`Effect handler module was not emitted: ${url}`)
+    return module
+  })
+  const imports = [
+    `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}`,
+    `import { createEffectContext } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu-effect.js")))}`,
+    ...modules.map((module, index) => `import * as __kEffectModule${index} from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, module.path)))}`)
+  ]
+  const entries = moduleUrls.map((url, index) => `[${JSON.stringify(url)}, __kEffectModule${index}]`).join(",")
+  return `${imports.join("\n")}
+const effects = ${inlineJson(effects)}
+const modules = new Map([${entries}])
+export const mountLayoutEffects = () => mount("layout")
+export const mountRouteEffects = () => mount("route")
+function mount(lifetime) {
+  let active = true
+  let flushing
+  let order = 0
+  const selectedEffects = effects.map((effect, index) => ({ effect, index })).filter(entry => entry.effect.lifetime === lifetime)
+  const records = new Set()
+  const owners = new Map()
+  const listTemplates = new Map()
+  const registrations = new WeakMap()
+  const dependencies = new Map()
+  const pending = new Set()
+  const startedCleanups = new Set()
+  let scheduled = false
+  for (const template of selectedEffects) {
+    if (template.effect.list) listTemplates.set(template.effect.owner, template)
+    else {
+      const record = createRecord(template, !template.effect.owner)
+      if (template.effect.owner) owners.set(template.effect.owner, record)
+    }
+  }
+  const unsubscribeCommitter = selectedEffects.some(({ effect }) => effect.dependencies?.length) ? __kRuntime.registerCommitter(id => {
+    if (!active) return
+    for (const record of dependencies.get(id) ?? []) if (record.mounted) pending.add(record)
+    schedule()
+  }) : undefined
+  const unsubscribeMount = __kRuntime.registerMountHook(mountOwned)
+  const unsubscribeUnmount = __kRuntime.registerUnmountHook(unmountOwned)
+  for (const record of records) if (record.mounted) start(record)
+  mountOwned(document)
+  function createRecord(template, mounted = true) {
+    const record = { ...template, order: order++, mounted, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined, token: undefined }
+    records.add(record)
+    registerDependencies(record)
+    return record
+  }
+  function registerDependencies(record) {
+    for (const id of record.effect.dependencies ?? []) {
+      const subscribers = dependencies.get(id) ?? new Set()
+      subscribers.add(record)
+      dependencies.set(id, subscribers)
+    }
+  }
+  function unregisterDependencies(record) {
+    for (const id of record.effect.dependencies ?? []) {
+      const subscribers = dependencies.get(id)
+      subscribers?.delete(record)
+      if (!subscribers?.size) dependencies.delete(id)
+    }
+  }
+  function mountOwned(root) {
+    if (!active) return
+    for (const marker of matching(root)) {
+      if (!marker.isConnected) continue
+      if (marker.dataset.kEffects) {
+        if (registrations.has(marker)) continue
+        const rowRecords = JSON.parse(marker.dataset.kEffects).flatMap(owner => {
+          const template = listTemplates.get(owner)
+          if (!template) return []
+          const record = createRecord(template)
+          record.marker = marker
+          start(record)
+          return [record]
+        })
+        if (rowRecords.length) registrations.set(marker, rowRecords)
+        continue
+      }
+      const record = owners.get(marker.dataset.kEffect)
+      if (record && !record.mounted) mountRecord(record, marker)
+    }
+  }
+  function unmountOwned(root) {
+    if (!active) return
+    for (const marker of matching(root)) {
+      const rowRecords = registrations.get(marker)
+      if (rowRecords) {
+        for (const record of rowRecords) unmountRecord(record, true)
+        registrations.delete(marker)
+        continue
+      }
+      const record = owners.get(marker.dataset.kEffect)
+      if (record?.marker === marker) unmountRecord(record)
+    }
+  }
+  function matching(root) {
+    const selector = "template[data-k-effect],[data-k-effects]"
+    return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
+  }
+  function mountRecord(record, marker) {
+    record.mounted = true
+    record.marker = marker
+    const version = ++record.version
+    const begin = () => {
+      if (active && record.mounted && record.version === version && marker.isConnected) start(record)
+    }
+    if (record.disposal) record.disposal.then(begin)
+    else begin()
+  }
+  function unmountRecord(record, dynamic = false) {
+    if (!record.mounted) return
+    record.mounted = false
+    record.marker = undefined
+    record.version++
+    pending.delete(record)
+    if (dynamic) {
+      unregisterDependencies(record)
+      records.delete(record)
+    }
+    void cleanup(record)
+  }
+  function start(record) {
+    try {
+      record.values = readDependencies(record)
+      invoke(record)
+    } catch (error) {
+      console.error(error)
+    }
+  }
+  function schedule() {
+    if (!pending.size || scheduled || flushing) return
+    scheduled = true
+    queueMicrotask(flush)
+  }
+  async function flush() {
+    scheduled = false
+    if (!active) return pending.clear()
+    const operation = (async () => {
+      const changed = []
+      const selected = [...pending].filter(record => record.mounted).sort((left, right) => left.index - right.index || left.order - right.order)
+      pending.clear()
+      for (const record of selected) {
+        try {
+          const values = readDependencies(record)
+          if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
+            record.values = values
+            changed.push([record, record.version])
+          }
+        } catch (error) {
+          console.error(error)
+        }
+      }
+      for (const [record] of changed) await cleanup(record)
+      if (active) for (const [record, version] of changed) if (record.mounted && record.version === version) invoke(record)
+    })()
+    flushing = operation
+    try { await operation } finally {
+      if (flushing === operation) flushing = undefined
+      if (active) schedule()
+    }
+  }
+  function readDependencies(record) {
+    return (record.effect.dependencies ?? []).map(id => {
+      const value = __kRuntime.browserState.get(id)
+      if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive")
+      return value
+    })
+  }
+  function invoke(record) {
+    const token = { active: true }
+    record.token = token
+    try {
+      const effect = record.effect
+      const scope = effect.list
+        ? Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, value?.type === "list-item" ? JSON.parse(record.marker.dataset.kEffectItem) : value]))
+        : effect.scope
+      const result = modules.get(effect.module)[effect.handler](createEffectContext(__kRuntime.browserState, effect.states, __kRuntime.commitDom, scope, () => active && token.active && record.token === token))
+      if (effect.cleanup && typeof result === "function") record.cleanup = result
+      else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+    } catch (error) {
+      console.error(error)
+    }
+  }
+  function cleanup(record) {
+    if (record.token) record.token.active = false
+    record.token = undefined
+    if (record.disposal) return record.disposal
+    const current = record.cleanup
+    record.cleanup = undefined
+    if (!current) return Promise.resolve()
+    const disposal = (async () => {
+      try { await current() } catch (error) { console.error(error) }
+    })()
+    record.disposal = disposal
+    startedCleanups.add(disposal)
+    disposal.finally(() => {
+      startedCleanups.delete(disposal)
+      if (record.disposal === disposal) record.disposal = undefined
+    })
+    return disposal
+  }
+  let disposal
+  return async function dispose() {
+    if (disposal) return disposal
+    disposal = (async () => {
+      active = false
+      unsubscribeCommitter?.()
+      unsubscribeMount()
+      unsubscribeUnmount()
+      pending.clear()
+      for (const record of records) if (record.token) record.token.active = false
+      if (flushing) await flushing
+      const mounted = [...records].filter(record => record.mounted).sort((left, right) => left.index - right.index || left.order - right.order)
+      for (const record of mounted) {
+        record.mounted = false
+        await cleanup(record)
+      }
+      await Promise.all([...startedCleanups])
+      records.clear()
+    })()
+    return disposal
+  }
+}`
+}
+
 function runtimeEffects(effects, lifetimes = false) {
   return effects.map(effect => ({
     module: effect.module,
@@ -685,7 +944,7 @@ let flushing = false
 let active = true
 for (const record of records) registerDependencies(record)
 function createRecord(effect, index) {
-  return { effect, index, mounted: !effect.owner, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined }
+  return { effect, index, mounted: !effect.owner, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined, token: undefined }
 }
 function registerDependencies(record) {
   for (const id of record.effect.dependencies ?? []) {
@@ -823,12 +1082,14 @@ function readDependencies(record) {
   })
 }
 function invoke(record) {
+  const token = { active: true }
+  record.token = token
   try {
     const effect = record.effect
     const scope = effect.list
       ? Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, value?.type === "list-item" ? JSON.parse(record.marker.dataset.kEffectItem) : value]))
       : effect.scope
-    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope))
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope, () => active && token.active && record.token === token))
     if (effect.cleanup && typeof result === "function") record.cleanup = result
     else if (result && typeof result.then === "function") result.catch(error => console.error(error))
   } catch (error) {
@@ -836,6 +1097,8 @@ function invoke(record) {
   }
 }
 function invokeCleanup(record) {
+  if (record.token) record.token.active = false
+  record.token = undefined
   if (record.disposal) return record.disposal
   const cleanup = record.cleanup
   record.cleanup = undefined
@@ -2883,19 +3146,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

@@ -298,7 +298,6 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
     const body = await renderNode(layout ? { type: layout, props: { children: page } } : { type: component, props })
     renderContext.effects = renderContext.effects.map(effect => {
       try {
-        if (metadata.navigationAsset && effect.owner) throw new Error("useEffect() inside conditional or keyed DOM is not supported in a configured navigation group yet; move the effect to the layout or route component body, or remove the route from navigation")
         const descriptor = nativeDescriptor(effect.states.map(([name, read]) => [name, read()]), effect.scope.map(([name, read]) => [name, typeof read === "function" ? read() : read]))
         return {
           module: effect.module,

package/framework/navigation-runtime.js

@@ -195,7 +195,7 @@ function commit(incoming, incomingNodes, initializeParams, pathname) {
 
 function matchRoute(pathname) {
   const exact = routes.find(record => record.path === pathname)
-  if (exact) return exact
+  if (exact) return exact.native ? undefined : exact
   for (const record of routes) {
     if (!record.segments) continue
     try {
@@ -212,7 +212,7 @@ function matchRoute(pathname) {
       if (record.segments.every((literal, index) => {
         const value = decodeSegment(segments[index], literal === null)
         return literal === null || value === literal
-      })) return record
+      })) return record.native ? undefined : record
     } catch {}
   }
 }

package/package.json

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