@kudzujs/core 0.8.21 → 0.8.22

package/MIGRATION_ROADMAP.md

@@ -223,6 +223,19 @@ This queue orders the next investigations by general migration value. Start only
 - Previous transformer-wide keyed value, condition, event, nested-list, effect, and rendered-list AST side tables were removed. AST remains private only inside immediate source-local validation and lowering.
 - `core.mjs` remains authoritative for final list IDs, key paths, route descriptors, complete HTML, DOM identity, and exact state/effect/ref release; accepted syntax and browser output are unchanged.
 
+### Completed In 0.8.21
+
+- Every supported effect finalizes into JSON-safe EffectIR with setup HandlerIR, cleanup, ordered signal/DerivedIR dependencies, component/keyed ownership, source provenance, and Worker edges.
+- Effect dependency/resource analysis and Worker rewriting return explicit results; transformer-wide effect AST side tables and build-wide mutable Worker references were removed.
+- Existing route/layout/conditional/keyed lifetime allocation, stale-write invalidation, cleanup order, accepted syntax, and browser output remain unchanged.
+
+### Completed In 0.8.22
+
+- The existing rendered route plan is RouteIR v1, with route-local numeric state slots beside unchanged browser IDs and readable state names; it is not duplicated in ModuleIR.
+- The existing pure capability projection is CapabilityIR v1 and every runtime/list codegen consumer rejects unsupported versions.
+- List, parameter, core, effect, binding, native, and navigation source generation moved out of `build.mjs` behind focused fail-closed generators; `build.mjs` decreased by 267 lines and coordinates stage outputs.
+- Complete-site and representative deploy artifacts remain byte-identical to `v0.8.21`; only additive RouteIR version/slot metadata changes build plans.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

package/PERFORMANCE.md

@@ -1,5 +1,29 @@
 # Performance Records
 
+## 0.8.22 Versioned Compiler Foundation
+
+Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, and npm 11.18.0. Baseline tag `v0.8.21` at `ff38092` and the current `0.8.22` compiler candidate used the same local volume and identical installed dependencies.
+
+The candidate implementation patch over `v0.8.21` had SHA-256 `e1d89c97dd8dfb60d41ae9c14ac64dfbb50466e024f80076f430ae9e725fb28f`, produced by:
+
+```bash
+git diff --binary v0.8.21 -- framework/build.mjs framework/compiler/list-runtime-codegen.mjs framework/compiler/param-codegen.mjs framework/compiler/route-capability-planner.mjs framework/compiler/runtime-codegen.mjs framework/core.mjs framework/core.d.ts | shasum -a 256
+```
+
+Both targets received one warm-up followed by seven clean `worker-effects` production builds in alternating round-robin order. Cleanup remained outside timing. Both medians were exactly 250.1 ms; the distributions overlap and establish no material change.
+
+| Target | Build median | Worker raw / gzip | Window raw / gzip |
+|---|---:|---:|---:|
+| 0.8.21 baseline | 250.1 ms | 907 B / 475 B | 12,148 B / 5,427 B |
+| 0.8.22 candidate | 250.1 ms | 907 B / 475 B | 12,148 B / 5,427 B |
+
+```text
+0.8.21: [249.7,252.0,250.1,251.2,250.0,254.8,249.1]
+0.8.22: [250.1,247.3,255.1,249.3,253.1,250.3,248.7]
+```
+
+Before release-content updates, the complete 135-page site and the `bindings`, `keyed-row-hooks`, `effect-dependencies`, `worker-effects`, `runtime-params`, and `navigation` deploy trees had identical file lists and bytes. Their build plans were equivalent after removing the intentional additive RouteIR `version` and state `slot` fields. Every measured Worker/window artifact name, raw byte count, and gzip byte count was identical. `build.mjs` decreased from 3,999 to 3,732 lines; this source-organization metric is not a runtime performance claim.
+
 ## 0.8.21 Explicit Effect Ownership
 
 Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, and npm 11.18.0. Baseline tag `v0.8.20` at `7fb6e37` and the current `0.8.21` compiler candidate used the same local volume and identical installed dependencies.

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.21 - Explicit effect ownership.** Effects now retain deterministic JSON-safe setup, cleanup, dependency, component/keyed ownership, source, and Worker-edge records while final route lifecycle allocation remains unchanged. Read the [release notes](./RELEASES.md#0821---explicit-effect-ownership), open the [release page](https://kudzujs.cloud/releases/0.8.21), or follow the [next architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.22 - Versioned compiler foundation.** Existing rendered route plans and capability manifests are now RouteIR v1 and CapabilityIR v1, with route-local state slots, stable runtime IDs, and readable names. Runtime generators consume those contracts while `build.mjs` coordinates their emission. Read the [release notes](./RELEASES.md#0822---versioned-compiler-foundation), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.22), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,41 @@
 # Kudzu Releases
 
+## 0.8.22 - Versioned compiler foundation
+
+Kudzu 0.8.22 completes Goal A: source-local ModuleIR seams accompany the existing rendered route plan as RouteIR v1, while CapabilityIR v1 selects shared runtime families and branches for focused artifact generators.
+
+### Changed in 0.8.22
+
+- The existing `renderPage().plan` is RouteIR v1 rather than a duplicated route representation.
+- Route states add a deterministic route-local numeric `slot`; existing string `id` values remain authoritative browser/DOM identities and `name` remains readable development metadata.
+- The existing pure capability manifest is CapabilityIR v1. Route and capability consumers reject unsupported versions.
+- List, parameter, core, effect, binding, native, and navigation runtime generation moved from `build.mjs` into focused generator modules with narrow inputs and no filesystem ownership.
+- Required authored-runtime source anchors fail closed instead of silently retaining stale branches.
+- `build.mjs` decreased from 3,999 to 3,732 lines and now coordinates generator results and artifact emission rather than containing those feature semantics.
+
+### Goal A boundary
+
+- ModuleIR slots identify source-local compiler records; RouteIR state slots identify positions in one rendered plan; browser IDs continue to own DOM/runtime behavior. The namespaces are deliberately independent.
+- `core.mjs` remains authoritative for complete HTML, route/layout IDs, conditions, keyed paths, effect lifetimes, and exact cleanup.
+- CapabilityIR selects shared runtime families and branches; RouteIR and ModuleIR references retain route entries, handlers, and Workers. Static pages remain complete documents with zero JavaScript.
+- Goal B optimization remains deferred; `0.8.22` is its recorded baseline if explicitly started later.
+- No accepted syntax, public API behavior, runtime capability, VDOM, hydration, component rerender, or retained browser component tree was added.
+
+### Validation
+
+- The complete suite passes 170/170 tests, including RouteIR JSON round-trip and slots, CapabilityIR JSON round-trip/version rejection, fail-closed generator contracts, list/parameter/navigation generation, lifecycle cleanup, and development restoration by readable state name.
+- `npm run check`, focused Node 22 compiler tests, and a Node 22 complete-site build pass.
+- The complete site plus six representative binding, list, effect, Worker, runtime-parameter, and navigation deploy trees are byte-identical to `v0.8.21`; normalized RouteIR meaning is identical in all seven comparisons.
+- Worker and window graph files remain byte-identical. Seven interleaved clean builds measured equal 250.1 ms medians; raw arrays and provenance are recorded in `PERFORMANCE.md`.
+- Release-blocking architecture audits drove full IR schema validation, accurate reachability ownership, and fail-closed source contracts before publication.
+- `create-kudzu` remains 0.1.101 because its unchanged template already accepts `@kudzujs/core@^0.8.15`.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.22
+```
+
 ## 0.8.21 - Explicit effect ownership
 
 Kudzu 0.8.21 completes the next Goal A source-analysis seam: every supported effect now registers deterministic JSON-safe setup, cleanup, dependency, ownership, source, and Worker-edge data before existing build-time rendering allocates concrete lifecycle IDs.

package/docs/next-architecture/README.md

@@ -6,8 +6,8 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 
 | Goal | Decision | Start condition |
 |---|---|---|
-| A: compiler foundation | `0.8.21` EffectIR source-analysis seam complete | Continue with `0.8.22` RouteIR, CapabilityIR, and the architecture/output audit after the release boundary. |
-| B: optimization benchmarks | Deferred | Goal A complete and its output baseline recorded |
+| A: compiler foundation | Complete in `0.8.22` | RouteIR v1, CapabilityIR v1, source IR seams, generator boundaries, and output baseline recorded. |
+| B: optimization benchmarks | Deferred | Start only by explicit decision from the recorded `0.8.22` baseline. |
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
 

package/docs/next-architecture/compiler-current-architecture.md

@@ -1,13 +1,13 @@
 # Current Compiler Architecture
 
-This maps the EffectIR boundary prepared for `0.8.21`. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves code.
+This maps the completed `0.8.22` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 
 | Responsibility | Current owner | Current contract |
 |---|---|---|
 | CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
-| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Loads config; discovers reachable source, CSS, and assets; compiles sources; renders routes; plans capabilities; emits `dist/`; invokes `afterBuild`. |
+| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Coordinates config, discovery, source compilation, RouteIR rendering, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. |
 | Reachability/import resolution | `framework/build.mjs`, `reachableSourceFiles()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, and excludes unreachable migration source. |
 | Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; `framework/build.mjs`, `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every pass. Imported source uses the same pipeline. |
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
@@ -22,10 +22,11 @@ This maps the EffectIR boundary prepared for `0.8.21`. File and function names a
 | Handler module codegen | [`framework/compiler/handler-codegen.mjs`](../../framework/compiler/handler-codegen.mjs) | Renders finalized ordered imports and concatenates generated module-export source without TypeScript AST or semantic discovery. |
 | Effect analysis | [`framework/compiler/effect-analysis.mjs`](../../framework/compiler/effect-analysis.mjs) | Classifies ordered signal, derived, and keyed-item dependencies and validates cleanup-owned browser resources before EffectIR registration. |
 | Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Returns functional Worker rewrite results and JSON-safe EffectIR edges, validates relative graphs, emits content-hashed ESM, and resolves placeholders only for rendered effects. |
-| Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns the serializable route plan and capability booleans. |
-| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Purely folds rendered route plans and route facts into aggregate runtime/artifact requirements. |
+| Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns RouteIR v1 plus capability facts. |
+| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Validates RouteIR v1 and purely folds rendered plans and route facts into CapabilityIR v1. |
 | Effect entry generation | [`framework/compiler/effect-codegen.mjs`](../../framework/compiler/effect-codegen.mjs) | Generates ordinary, dependency, owned, and navigable effect entries from rendered descriptors. |
-| Runtime specialization/emission | `framework/build.mjs` | Selects runtime files and currently removes branches through feature booleans, string replacement, compile-time defines, and esbuild. |
+| Runtime generation | [`framework/compiler/runtime-codegen.mjs`](../../framework/compiler/runtime-codegen.mjs), [`framework/compiler/list-runtime-codegen.mjs`](../../framework/compiler/list-runtime-codegen.mjs), [`framework/compiler/param-codegen.mjs`](../../framework/compiler/param-codegen.mjs) | Consumes versioned contracts, specializes authored capability sources with fail-closed anchors, and returns source/define results without filesystem ownership. |
+| Artifact emission | `framework/build.mjs` | Selects required files from CapabilityIR and writes or bundles generated sources with esbuild. |
 | Browser capabilities | [`framework/*.js`](../../framework/) | Small optional modules for commands, bindings, lists, effects, native handlers, serialization, parameters, and navigation; no component runtime. |
 | Opt-in navigation | [`framework/navigation-runtime.js`](../../framework/navigation-runtime.js) plus `framework/build.mjs` navigation configuration/emission | Fetches and validates complete same-origin documents, replaces only the marked route range, manages route/layout disposal, history, focus, finite prefetch retention, and native fallback. |
 | Development serving | [`framework/dev-server.mjs`](../../framework/dev-server.mjs) and [`framework/dev-state.js`](../../framework/dev-state.js) | Rebuild/watch/SSE and response-only short-lived state restoration; never changes production `dist/`. |
@@ -44,11 +45,11 @@ src/pages entries + config
        -> generated handler/effect/binding/list-evaluator modules
   -> import page modules and execute renderPage()
        -> complete HTML
-       -> serializable route plan
+       -> RouteIR v1
        -> referenced handler URLs and route facts
   -> remove unrendered handlers/effects/Workers
-  -> planRouteCapabilities(route plans, route facts)
-       -> aggregate capability manifest
+   -> planRouteCapabilities(RouteIR records, route facts)
+       -> CapabilityIR v1
   -> specialize and emit only selected runtime/capability ESM
   -> write route index.html, CSS/assets, Worker graphs, rewrites, and .kudzu/kudzu-plan.json
   -> optional afterBuild()
@@ -56,15 +57,15 @@ src/pages entries + config
 
 The browser consumes static HTML first. State seeds and descriptors in that HTML connect only to emitted command, binding, list, native-handler, effect, parameter, or navigation modules. Browser execution patches owned DOM directly; it does not invoke component functions or reconstruct a component tree.
 
-## Current Coupling To Remove
+## Residual Coupling
 
 - `createKudzuTransformer()` combines discovery, validation, specialization, descriptor registration, and transformed-source emission.
 - Transient component rewrite indexes remain source-local AST indexes; handler, binding, derived, keyed, effect, and component ownership now have explicit JSON-safe source results.
-- `build()` destructures a broad capability manifest into many booleans and performs artifact-specific source surgery.
-- Runtime specialization relies on exact source-string and regular-expression replacements in `framework/build.mjs`.
-- Route facts, rendered plans, artifact requirements, and emitted-file decisions are represented at adjacent but not fully explicit boundaries.
+- `build()` still owns explicit artifact selection and filesystem writes after generator results are produced.
+- Runtime generators intentionally specialize readable authored sources through exact anchors; every required anchor fails closed, but a future generator format may remove this transitional dependency.
+- The main transformer remains the largest source-analysis unit even though its durable outputs are explicit JSON-safe records.
 
-Goal A addresses these couplings without changing source support, output semantics, or browser architecture.
+These are future simplification opportunities, not incomplete Goal A contracts. Goal A changed no source support, browser output semantics, or browser architecture.
 
 ## Continuation Checklist
 

package/docs/next-architecture/goal-a-compiler-foundation.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-The `0.8.21` EffectIR source-analysis seam is complete. Goal A continues with the planned `0.8.22` RouteIR, CapabilityIR, and architecture/output audit while preserving accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
+Goal A is complete in `0.8.22`. ModuleIR source seams, RouteIR v1, CapabilityIR v1, focused runtime generators, and the architecture/output baseline preserve accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
 
 ## Target Boundaries
 
@@ -77,7 +77,7 @@ Analysis produces plain data:
 }
 ```
 
-The `0.8.21` source result adds deterministic EffectIR setup HandlerIR links, cleanup, ordered dependencies and subscriptions, DerivedIR references, component/keyed ownership, source provenance, and Worker edges beside the existing command, component, handler, binding, derived, and KeyedBlockIR results. Source-local effect AST analysis is consumed during lowering and does not cross this boundary. Final route/layout/conditional/keyed effect IDs and lifetime allocation remain authoritative in `core.mjs`; the existing route plan is not duplicated in ModuleIR.
+The completed source result contains deterministic command, component, HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, and EffectIR records. Source-local AST analysis is consumed during lowering and does not cross this boundary. Final route/layout/conditional/keyed IDs and lifetime allocation remain authoritative in `core.mjs`; no component tree or duplicate route plan exists.
 
 Source codegen lowers that data through the existing build ABI:
 
@@ -93,11 +93,11 @@ One source-local result owns transformed source plus the sparse ModuleIR, genera
 
 ### Route Result
 
-`renderPage()` remains the build-time authority for complete HTML and ownership IDs. Its serializable plan remains the behavioral source for states, events, effects, bindings, conditions, lists, parameters, and search parameters. Route-level facts such as navigability and dependency-runtime selection accompany rather than mutate that plan.
+`renderPage()` remains the build-time authority for complete HTML and ownership IDs. Its existing plan is RouteIR v1, the behavioral source for states, events, effects, bindings, conditions, lists, parameters, and search parameters. Each state has a route-local numeric `slot`, its unchanged browser/DOM `id`, and readable `name` metadata used by development restoration. RouteIR slots are not ModuleIR signal slots or persistent browser identities. Route-level facts such as navigability and dependency-runtime selection accompany rather than mutate the plan.
 
 ### Artifact Plan
 
-A pure projection determines which shared runtimes, route entries, handler modules, Worker roots, and optional branches are required. Artifact generators consume that projection; they do not rediscover syntax or inspect application AST.
+CapabilityIR v1 determines shared runtime families and optional branches. Rendered RouteIR descriptors and ModuleIR references independently retain route entries, handler modules, and Worker reachability. Runtime, list, parameter, effect, and handler generators consume those explicit results; they do not rediscover TSX semantics or inspect application AST.
 
 ## Generator Strategy
 
@@ -122,17 +122,14 @@ No generator may analyze TSX, invent runtime component abstractions, or broaden
 - Preserve current runtime files until their corresponding generator has artifact parity.
 - Treat deterministic byte changes as review items even when tests pass.
 
-## Acceptance
-
-- Build orchestration reads as stage coordination rather than feature analysis or source generation.
-- Source normalization, semantic analysis, route planning, artifact planning, generation, and writing have explicit ownership.
-- Codegen consumes descriptors/manifests and does not discover compiler semantics.
-- No module-global mutable analysis state or new broad context object is added.
-- Static routes still emit complete HTML and zero JavaScript.
-- Interactive and navigation routes preserve capability selection, ownership, stale-write, and cleanup behavior.
-- Unreachable handlers, effects, package helpers, and Workers remain absent.
-- Diagnostics retain source file and location.
-- [`performance-gates.md`](./performance-gates.md) passes for every patch.
+## Acceptance Record
+
+- `build.mjs` decreased from 3,999 to 3,732 lines and coordinates focused generators rather than containing list, parameter, core, effect, binding, native, or navigation source generation.
+- Source normalization, semantic analysis, RouteIR rendering, CapabilityIR projection, generation, and writing have explicit ownership without a broad context object.
+- RouteIR and CapabilityIR reject unsupported versions; required runtime source anchors fail closed.
+- Static routes retain complete HTML and zero JavaScript; deploy output across the complete site and representative binding, list, effect, Worker, parameter, and navigation fixtures is byte-identical to `v0.8.21`.
+- Interactive and navigation routes preserve capability selection, ownership, stale-write, and cleanup behavior; unreachable handlers, effects, package helpers, and Workers remain absent.
+- Diagnostics retain source file and location, and [`performance-gates.md`](./performance-gates.md) records no build or artifact-size regression.
 
 ## Non-Goals
 

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.21` are completed scopes represented by package/release records; later rows remain planned until their package version and release record exist.
+This is an execution sequence, not release history. `0.8.16` through `0.8.22` are completed scopes represented by package/release records.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -16,7 +16,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 
 ## Sequence Rules
 
-- Do not start Goal B optimization before `0.8.22` Goal A acceptance and baseline recording.
+- Goal A is complete. Goal B optimization remains deferred until explicitly started from the recorded `0.8.22` baseline.
 - Keep Goal C research out of these patches and publish no store/resource API.
 - Keep Goal D behavior unchanged: complete HTML, native default, opt-in groups, no islands.
 - A planned patch may ship under a different actual version only if this table and release-facing documentation are updated before release.

package/framework/README.md

@@ -39,6 +39,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, import, and client-root finalization.
 - `compiler/effect-analysis.mjs`: ordered effect dependency classification and cleanup-owned browser resource validation before EffectIR registration.
 - `compiler/normalization-pipeline.mjs`: ordered source normalization with parent-pointer repair after every compiler pass.
+- `compiler/param-codegen.mjs`: runtime pathname and search-parameter entry generation from rendered route descriptors.
 - `compiler/react-migration-pass.mjs`: React import, memo, callback, `forwardRef`, and `useId` migration validation and lowering.
 - `compiler/custom-hook-timer-pass.mjs`: private custom-hook timeout-ref validation and compiler-owned timer-state lowering.
 - `compiler/effect-codegen.mjs`: route-specific ordinary, owned, and navigable effect entry generation.
@@ -47,7 +48,9 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/handler-codegen.mjs`: AST-free ordered import rendering and finalized handler/binding export-source assembly.
 - `compiler/render-control-pass.mjs`: render-function early-return and exhaustive adjacent-assignment normalization.
 - `compiler/router-pass.mjs`: React Router import validation and native Link, pathname parameter, search parameter, and imperative navigation lowering.
-- `compiler/route-capability-planner.mjs`: pure route-plan projection into runtime and artifact capability requirements.
+- `compiler/route-capability-planner.mjs`: RouteIR v1 validation and pure CapabilityIR v1 projection into runtime and artifact requirements.
+- `compiler/runtime-codegen.mjs`: fail-closed core, effect, binding, native, and navigation runtime generation from CapabilityIR.
+- `compiler/list-runtime-codegen.mjs`: fail-closed keyed-list runtime generation from CapabilityIR list/effect sections.
 - `compiler/worker-compiler.mjs`: relative TypeScript Worker candidate validation, effect rewriting, graph validation, and content-hashed ESM emission.
 - `compiler/zustand-pass.mjs`: reduced Zustand store analysis, diagnostics, and migration normalization.
 - `dev-server.mjs`: development HTTP server, source watching, rebuild serialization, SSE reloads, runtime-route fallback serving, and response-only state restoration injection.
@@ -65,7 +68,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Compiler ownership follows four explicit stages. `build.mjs` owns project discovery, route planning, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and repairs parent pointers after every source transform; migration passes keep per-file state local and return additional metadata explicitly. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. Keyed blocks link deterministic parent/child sites, component specializations, row states/refs, and generated handlers/bindings without replacing `core.mjs` final DOM ownership. Effects link setup handlers, dependencies, cleanup, lexical/keyed ownership, provenance, and Worker edges without duplicating the rendered route plan. `compiler/collection-analysis.mjs` owns the shared pure collection language used by React migration, reactive expressions, effects, and keyed lists. After build-time rendering, `compiler/route-capability-planner.mjs` projects serializable route plans into one capability manifest consumed by runtime specialization and artifact emission. Codegen modules turn descriptors into route-specific ESM without participating in source analysis. The versioned continuation plan lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
+Compiler ownership follows explicit stages. `build.mjs` coordinates project discovery, source compilation, RouteIR rendering, CapabilityIR planning, generator calls, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and parent repair. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. `core.mjs` emits complete HTML and RouteIR v1: route-local state `slot` is an internal array reference, `id` remains the browser/DOM identity, and `name` remains readable development metadata. `compiler/route-capability-planner.mjs` validates those plans and projects CapabilityIR v1. Focused codegen modules consume IR/descriptors and return route-specific source without source analysis or filesystem ownership. The completed architecture record lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
 
 New syntax support belongs in an existing pass or a focused new pass only when a reduced migration fixture proves it. Passes must preserve source-located diagnostics, avoid module-global analysis state, and expose metadata through return values rather than AST-identity side channels. Build orchestration stays in `build.mjs`; feature-specific graph validation or code generation moves under `compiler/` when it has a stable input/output boundary.
 

package/framework/build.mjs

@@ -15,18 +15,22 @@ import { analyzeEffectDependencies, validateEffectOwnedBrowserResources } from "
 import { createEffectCodegen } from "./compiler/effect-codegen.mjs"
 import { createHandlerCodegen } from "./compiler/handler-codegen.mjs"
 import { createHandlerLowering } from "./compiler/handler-lowering.mjs"
+import { generateListRuntime } from "./compiler/list-runtime-codegen.mjs"
 import { createCommandSpecializer } from "./compiler/optimize/command-specialization.mjs"
 import { applyNormalizationPasses } from "./compiler/normalization-pipeline.mjs"
+import { createParamCodegen } from "./compiler/param-codegen.mjs"
 import { createReactMigrationPass, reactMemoExpression } from "./compiler/react-migration-pass.mjs"
 import { normalizeRenderControlFlow } from "./compiler/render-control-pass.mjs"
 import { createRouterPass } from "./compiler/router-pass.mjs"
 import { planRouteCapabilities, usesRouteDependencyRuntime } from "./compiler/route-capability-planner.mjs"
+import { generateBindingRuntime, generateCoreRuntime, generateEffectRuntime, generateNativeRuntime, generateNavigationRuntime, specializeRuntime } from "./compiler/runtime-codegen.mjs"
 import { createWorkerCompiler } from "./compiler/worker-compiler.mjs"
 import { createZustandPass } from "./compiler/zustand-pass.mjs"
 import { renderPage } from "./core.mjs"
 import { parseDevHost, parseDevPort, startDevServer } from "./dev-server.mjs"
 
 export { parseDevHost, parseDevPort }
+export { specializeRuntime }
 
 const root = process.cwd()
 const sourceDirectory = join(root, "src")
@@ -213,41 +217,16 @@ export async function build({ quiet = false, minify = true } = {}) {
     }
     if (module.code.includes("/__kudzu_worker_")) throw new Error(`Worker URL placeholder survived in ${module.path}`)
   }
-  const capabilityManifest = planRouteCapabilities(plans, { routes: routeCapabilities, navigationRouteCount: navigationRoutes.length })
+  const capabilityIR = planRouteCapabilities(plans, { routes: routeCapabilities, navigationRouteCount: navigationRoutes.length })
   const {
-    routes: { behaviors: behaviorCount, regularBehaviors: regularBehaviorCount, regularStateSeeds: regularStateSeedCount, dependencyStateSeeds: dependencyStateSeedCount },
-    events: { command: commandEvents, native: nativeEvents, hasNativeHandlers },
-    bindings: { count: bindingCount, text: hasTextBindings, svgConditions: hasSvgConditions },
-    lists: {
-      count: listCount,
-      styleCount: listStyleCount,
-      conditions: hasListConditions,
-      svg: hasSvgLists,
-      deepConditions: hasDeepListConditions,
-      textRanges: hasListTextRanges,
-      attributes: hasListAttributes,
-      events: hasListEvents,
-      expressions: hasListExpressions,
-      expressionAttributes: hasListExpressionAttributes,
-      seeds: hasListSeeds,
-      effects: hasListEffects,
-      rowHooks: hasListRowHooks,
-      rowRefs: hasListRowRefs,
-      complexRowState: hasComplexListRowState,
-      nested: hasNestedLists,
-      selectors: hasCollectionSelectors,
-      calculated: hasCalculatedCollections,
-      static: hasStaticCollections,
-      indexes: hasListIndexes,
-      stableFastPaths: hasListStableFastPaths,
-      generalRowHooks: hasGeneralListRowHooks,
-      asyncParts: hasListAsyncParts,
-      mounts: hasListMounts
-    },
-    effects: { any: hasEffects, derivedDependencies: hasDerivedEffectDependencies, itemDependencies: hasItemDependencies, captures: hasEffectCaptures, navigable: hasNavigableEffects, navigableOwners: hasNavigableOwners },
+    routes: { behaviors: behaviorCount, regularBehaviors: regularBehaviorCount, dependencyStateSeeds: dependencyStateSeedCount },
+    events: { command: commandEvents, hasNativeHandlers },
+    bindings: { count: bindingCount },
+    lists,
+    effects: { any: hasEffects, derivedDependencies: hasDerivedEffectDependencies, captures: hasEffectCaptures },
     captures: { nestedState: hasNestedStateCaptures, setter: hasSetterCaptures },
     runtime: { shared: hasSharedRuntime, dependency: hasDependencyRuntime }
-  } = capabilityManifest
+  } = capabilityIR
   const runtimeName = usesDependencyRuntime => usesDependencyRuntime ? "kudzu-deps.js" : "kudzu.js"
   for (const entry of pageEntries) {
     const routeDirectory = join(outputDirectory, entry.route)
@@ -257,12 +236,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   }
   if (navigationRoutes.length || behaviorCount && (hasSharedRuntime || regularBehaviorCount)) {
     const runtimeFile = hasSharedRuntime ? "./shared-runtime.js" : "./runtime.js"
-    let runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, regularStateSeedCount > 0)
-    if (!hasItemDependencies) runtime = runtime.replace(/\/\* list-item-hooks \*\/[\s\S]*?\/\* list-item-hooks-end \*\/\n/, "")
-    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}")
+    const runtime = generateCoreRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), capabilityIR)
     await writeJavaScript(join(assetsDirectory, "kudzu.js"), runtime, minify)
   }
   if (hasDependencyRuntime) {
@@ -274,129 +248,30 @@ export async function build({ quiet = false, minify = true } = {}) {
     "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
   })
   if (hasEffects) {
-    let effectRuntime = await readFile(new URL("./effect-runtime.js", import.meta.url), "utf8")
-    effectRuntime = hasEffectCaptures ? effectRuntime.replace('"./serialization.js"', '"./kudzu-serialization.js"') : effectRuntime.replace(/^import[^\n]+\n/, "")
-    await writeBundledJavaScript(join(assetsDirectory, "kudzu-effect.js"), effectRuntime, minify, {
-      "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures),
-      "globalThis.__KUDZU_EFFECT_CAPTURES__": String(hasEffectCaptures)
-    })
+    const generated = generateEffectRuntime(await readFile(new URL("./effect-runtime.js", import.meta.url), "utf8"), capabilityIR)
+    await writeBundledJavaScript(join(assetsDirectory, "kudzu-effect.js"), generated.source, minify, generated.define)
   }
-  if (bindingCount || listStyleCount) await writeJavaScript(join(assetsDirectory, "kudzu-style.js"), await readFile(new URL("./style.js", import.meta.url), "utf8"), minify)
+  if (bindingCount || lists.styleCount) await writeJavaScript(join(assetsDirectory, "kudzu-style.js"), await readFile(new URL("./style.js", import.meta.url), "utf8"), minify)
   if (bindingCount) {
-    let bindingRuntime = (await readFile(new URL("./binding-runtime.js", import.meta.url), "utf8"))
-      .replace('"./shared-runtime.js"', '"./kudzu.js"')
-      .replace('"./serialization.js"', '"./kudzu-serialization.js"')
-      .replace('"./style.js"', '"./kudzu-style.js"')
-    if (navigationRoutes.length) bindingRuntime = specializeNavigationTextDescriptors(bindingRuntime)
-    await writeBundledJavaScript(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime, minify, {
-      "globalThis.__KUDZU_TEXT_BINDINGS__": String(hasTextBindings),
-      "globalThis.__KUDZU_SVG_CONDITIONS__": String(hasSvgConditions),
-      "globalThis.__KUDZU_CAPTURE_STATE__": String(hasNestedStateCaptures)
-    })
+    const generated = generateBindingRuntime(await readFile(new URL("./binding-runtime.js", import.meta.url), "utf8"), capabilityIR, navigationRoutes.length > 0)
+    await writeBundledJavaScript(join(assetsDirectory, "kudzu-binding.js"), generated.source, minify, generated.define)
   }
   if (hasDerivedEffectDependencies) await writeJavaScript(join(assetsDirectory, "kudzu-collection-selector.js"), await readFile(new URL("./collection-selector.js", import.meta.url), "utf8"), minify)
-  if (listCount) {
-    if (hasCollectionSelectors && !hasDerivedEffectDependencies) await writeJavaScript(join(assetsDirectory, "kudzu-collection-selector.js"), await readFile(new URL("./collection-selector.js", import.meta.url), "utf8"), minify)
-    let listRuntime = (await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"))
-      .replace('"./shared-runtime.js"', '"./kudzu.js"')
-    listRuntime = hasCalculatedCollections
-      ? listRuntime.replace('"./binding-runtime.js"', '"./kudzu-binding.js"')
-      : listRuntime.replace(/^const loadListEvaluator[^\n]+\n/m, "")
-    listRuntime = hasCollectionSelectors
-      ? listRuntime.replace('"./collection-selector.js"', '"./kudzu-collection-selector.js"')
-      : listRuntime.replace(/^import \{ selectCollection \}[^\n]+\n/m, "")
-    if (!hasListIndexes) listRuntime = listRuntime
-      .replace("for (const [index, item] of items.entries()) {", "for (const item of items) {")
-      .replace("const key = list.descriptor.key === null ? index : item?.[list.descriptor.key]", "const key = item?.[list.descriptor.key]")
-      .replace("entries.push({ item, index, key, token, value:", "entries.push({ item, key, token, value:")
-      .replace("for (const { item, index, key, token, value } of entries) {", "for (const { item, key, token, value } of entries) {")
-      .replaceAll("fillListItem(node, item, list.descriptor.nested, index)", "fillListItem(node, item, list.descriptor.nested)")
-      .replace("fillListItem(node, item, list.descriptor.nested, index, mapListItemParts", "fillListItem(node, item, list.descriptor.nested, 0, mapListItemParts")
-      .replace("function addListRoot(list, { item, index = list.roots.size, key, token, value })", "function addListRoot(list, { item, key, token, value })")
-      .replace("fillListParts(root, listItemParts(root), listItems.get(owner), 0, __KUDZU_LIST_INDEXES__ ? listIndexes.get(owner) ?? 0 : 0)", "fillListParts(root, listItemParts(root), listItems.get(owner), 0)")
-      .replace("function fillListItem(root, item, nested = false, index = 0)", "function fillListItem(root, item, nested = false)")
-      .replace("fillListParts(root, parts, item, revision, index, previous)", "fillListParts(root, parts, item, revision, previous)")
-      .replace("function fillListParts(root, parts, item, revision, index = 0, previous)", "function fillListParts(root, parts, item, revision, previous)")
-      .replace("fillListExpressions(root, parts, item, revision, index)", "fillListExpressions(root, parts, item, revision)")
-      .replaceAll('value?.type === "list-item" ? serializeItem(item) : value?.type === "list-index" ? index : value', 'value?.type === "list-item" ? serializeItem(item) : value')
-      .replaceAll("evaluate(descriptor, item, index)", "evaluate(descriptor, item)")
-      .replaceAll("evaluate({ module, handler }, item, index)", "evaluate({ module, handler }, item)")
-      .replace("updateListCondition(marker, descriptor.kind, value, item, index)", "updateListCondition(marker, descriptor.kind, value, item)")
-      .replace("function updateListCondition(marker, kind, value, item, index)", "function updateListCondition(marker, kind, value, item)")
-      .replace("fillListParts(marker, listItemParts(fragment), item, revision, index)", "fillListParts(marker, listItemParts(fragment), item, revision)")
-      .replace("function evaluate(descriptor, item, index)", "function evaluate(descriptor, item)")
-      .replace("exports[descriptor.handler](item, index)", "exports[descriptor.handler](item)")
-      .replace("exports[descriptor.handler](item, index, {", "exports[descriptor.handler](item, undefined, {")
-    if (!hasCollectionSelectors) listRuntime = listRuntime.replaceAll(" && !list.descriptor.selector", "")
-    if (!hasListIndexes) listRuntime = listRuntime
-      .replaceAll(" && !list.descriptor.indexed", "")
-      .replaceAll(" && list.descriptor.key !== null", "")
-      .replaceAll("list.descriptor.key !== null && !list.descriptor.indexed && ", "")
-      .replace("list.descriptor.key !== null && !list.descriptor.indexed && !list.descriptor.selector && list.values.size", "list.values.size")
-      .replace("(referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value) || list.descriptor.indexed || list.descriptor.key === null", "referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value")
-    if (hasListRowHooks && !hasGeneralListRowHooks) listRuntime = listRuntime
-      .replace(/\/\* general-row-hooks \*\/[\s\S]*?\/\* general-row-hooks-end \*\/\n/, "")
-      .replaceAll("initializeGeneralRowHooks", "initializeRowStates")
-      .replace("if (__KUDZU_LIST_ROW_HOOKS__) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index], roots[index], nested?.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && descriptor.rowStates) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index])")
-      .replaceAll("if (__KUDZU_LIST_ROW_HOOKS__) initializeRowStates(list.descriptor, key, node, list.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)")
-      .replace("for (const node of registration.list.roots.values()) deleteRowStates(registration.list.descriptor, ownershipPaths.get(node))", "for (const token of registration.list.roots.keys()) deleteFlatRowStates(registration.list.descriptor, token)")
-      .replaceAll("deleteRowStates(list.descriptor, ownershipPaths.get(node))", "deleteFlatRowStates(list.descriptor, token)")
-      .replace("  if (__KUDZU_LIST_ROW_HOOKS__) replaceRowIds(root, rowReplacements.get(root))\n", "")
-      .replace("  if (!replacements) return\n", "")
-    if (!hasItemDependencies) listRuntime = listRuntime.replace(", notifyListItem", "")
-    if (!hasListStableFastPaths) listRuntime = listRuntime.replace(/\/\* stable-list-fast-path \*\/[\s\S]*?\/\* stable-list-fast-path-end \*\/\n/, "")
-    const stylePatch = `  if (target === "style") {
-    const style = serializeStyle(value)
-    if (style) node.setAttribute("style", style)
-    else node.removeAttribute("style")
-    return
-  }`
-    listRuntime = listRuntime.replace("  /* list-style */", listStyleCount ? stylePatch : "")
-    if (listStyleCount) listRuntime = `import { serializeStyle } from "./kudzu-style.js"\n${listRuntime}`
-    await writeBundledJavaScript(join(assetsDirectory, "kudzu-list.js"), listRuntime, minify, {
-      __KUDZU_LIST_CONDITIONS__: String(hasListConditions),
-      __KUDZU_DEEP_LIST_CONDITIONS__: String(hasDeepListConditions),
-      __KUDZU_LIST_TEXT_RANGES__: String(hasListTextRanges),
-      __KUDZU_LIST_ATTRIBUTES__: String(hasListAttributes),
-      __KUDZU_LIST_EVENTS__: String(hasListEvents),
-      __KUDZU_LIST_EXPRESSIONS__: String(hasListExpressions),
-      __KUDZU_LIST_EXPRESSION_ATTRIBUTES__: String(hasListExpressionAttributes),
-      __KUDZU_LIST_SEEDS__: String(hasListSeeds),
-      __KUDZU_LIST_EFFECTS__: String(hasListEffects),
-      __KUDZU_LIST_ASYNC_PARTS__: String(hasListAsyncParts),
-      __KUDZU_LIST_MOUNTS__: String(hasListMounts),
-      __KUDZU_LIST_ITEM_HOOKS__: String(hasItemDependencies),
-      __KUDZU_LIST_ROW_HOOKS__: String(hasListRowHooks),
-      __KUDZU_LIST_ROW_REFS__: String(hasListRowRefs),
-      __KUDZU_COMPLEX_LIST_ROW_STATE__: String(hasComplexListRowState),
-      __KUDZU_NESTED_LISTS__: String(hasNestedLists),
-      __KUDZU_COLLECTION_SELECTORS__: String(hasCollectionSelectors),
-      __KUDZU_STATIC_COLLECTIONS__: String(hasStaticCollections),
-      __KUDZU_LIST_INDEXES__: String(hasListIndexes),
-      __KUDZU_LIST_STABLE_FAST_PATHS__: String(hasListStableFastPaths),
-      __KUDZU_SVG_LISTS__: String(hasSvgLists)
-    })
-    if (hasCollectionSelectors && !hasDerivedEffectDependencies) await rm(join(assetsDirectory, "kudzu-collection-selector.js"))
+  if (lists.count) {
+    if (lists.selectors && !hasDerivedEffectDependencies) await writeJavaScript(join(assetsDirectory, "kudzu-collection-selector.js"), await readFile(new URL("./collection-selector.js", import.meta.url), "utf8"), minify)
+    const generated = generateListRuntime(await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"), capabilityIR)
+    await writeBundledJavaScript(join(assetsDirectory, "kudzu-list.js"), generated.source, minify, generated.define)
+    if (lists.selectors && !hasDerivedEffectDependencies) await rm(join(assetsDirectory, "kudzu-collection-selector.js"))
   }
   if (hasNativeHandlers) {
-    const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"))
-      .replace('"./shared-runtime.js"', '"./kudzu.js"')
-      .replace('"./serialization.js"', '"./kudzu-serialization.js"')
-    await writeJavaScript(join(assetsDirectory, "kudzu-native.js"), specializeEvents(nativeRuntime, nativeEvents), minify, {
-      "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
-    })
+    const generated = generateNativeRuntime(await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"), capabilityIR)
+    await writeJavaScript(join(assetsDirectory, "kudzu-native.js"), generated.source, minify, generated.define)
     for (const entry of nativeEntries) await printNativeEntry(entry, assetsDirectory, base, 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)
+      await writeJavaScript(join(assetsDirectory, group.assetName), generateNavigationRuntime(navigationSource, group), minify)
     }
   }
   for (const handlerModule of emittedHandlerModules) {
@@ -483,64 +358,6 @@ function preloadModules(html) {
   return html.replace(scripts[0][0], `${links}${scripts[0][0]}`)
 }
 
-function specializeEvents(source, events) {
-  return source.replace(/const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`)
-}
-
-function specializeNavigationEffects(source, enabled) {
-  if (enabled) return source
-  return source
-    .replace("const noDispose = async () => {}\nlet routeDispose = noDispose\nlet layoutDispose = noDispose\nconst ready = mountInitial()\n", "")
-    .replace(`addEventListener("pagehide", event => {
-  if (event.persisted) return
-  ++revision
-  request?.abort()
-  void (async () => {
-    await routeDispose()
-    await layoutDispose()
-  })()
-})
-`, "")
-    .replace(`
-async function mountInitial() {
-  try {
-    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, location.search)
-    layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
-    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
-  } catch (error) {
-    console.error(error)
-  }
-}
-`, "")
-    .replace("  await ready\n", "")
-    .replace("    const { incoming, parsed, capabilities } = documentResult\n", "    const { incoming, parsed } = documentResult\n")
-    .replace("    await routeDispose()\n    if (current !== revision) return\n", "")
-    .replace("    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)\n", "    commit(incoming, parsed.nodes)\n")
-    .replace("    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "")
-    .replace("  return { incoming, parsed, capabilities: await loadCapabilities(parsed), record }\n", "  await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n  return { incoming, parsed, record }\n")
-    .replace(`
-async function loadCapabilities(parsed) {
-  const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
-  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`)
-}
-
 async function printNativeEntry(entry, assetsDirectory, base, minify) {
   const output = join(assetsDirectory, entry.path)
   await mkdir(dirname(output), { recursive: true })
@@ -566,83 +383,6 @@ function runtimeEffects(effects, lifetimes = false) {
   }))
 }
 
-function printParamEntry(schema, params, searchParams, searchParamsWritable, output, assetsDirectory, base, runtimeName, navigable) {
-  const hasSearch = searchParams.length || searchParamsWritable
-  const signature = hasSearch ? "pathname, search" : "pathname"
-  const prefix = navigable ? `export function initializeParams(${signature}) {\n${searchParamsWritable ? "globalThis.__kSetSearchParams = setSearchParams\n" : ""}` : `${schema ? "let pathname = location.pathname\n" : ""}${hasSearch ? "let search = location.search\n" : ""}`
-  const suffix = navigable ? "\n}" : ""
-  const pathname = schema ? `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 = 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")
-  path = "/" + pathSegments.slice(base.length).join("/")
-}
-if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
-const segments = path.slice(1).split("/")
-if (segments.length !== schema.length) throw new Error("Runtime route does not match its fallback pattern")
-const values = Object.create(null)
-for (let index = 0; index < schema.length; index++) {
-  const segment = schema[index]
-  const value = decodeSegment(segments[index], Boolean(segment.param))
-  if (segment.literal !== undefined && value !== segment.literal) throw new Error("Runtime route literal does not match")
-  if (segment.param) values[segment.param] = value
-}
-for (const param of params) {
-  const value = values[param.name]
-  browserState.set(param.id, value)
-  commitDom(param.id, value)
-}
-function decodeSegment(raw, param) {
-  if (param && /%(?:2f|5c)/i.test(raw)) throw new Error("Runtime route parameter contains an encoded separator")
-  let value
-  try { value = decodeURIComponent(raw) } catch { throw new Error("Runtime route parameter has malformed encoding") }
-  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
-}
-` : ""
-  const searchInitializer = searchParamsWritable && searchParams.length ? `function initializeSearch(search) {
-const query = new URLSearchParams(search)
-for (const param of ${inlineJson(searchParams)}) {
-  const value = query.get(param.name)
-  browserState.set(param.id, value)
-  commitDom(param.id, value)
-}
-}
-` : ""
-  const query = searchParams.length ? searchParamsWritable ? "initializeSearch(search)\n" : `const query = new URLSearchParams(search)
-for (const param of ${inlineJson(searchParams)}) {
-  const value = query.get(param.name)
-  browserState.set(param.id, value)
-  commitDom(param.id, value)
-}
-` : ""
-  const writer = searchParamsWritable ? `
-function setSearchParams(update, replace) {
-  const next = update(new URLSearchParams(location.search))
-  if (!(next instanceof URLSearchParams)) throw new Error("React Router search parameter updater must return URLSearchParams")
-  const url = new URL(location.href)
-  url.search = next.toString()
-  history[replace ? "replaceState" : "pushState"](null, "", url)
-  ${searchParams.length ? "initializeSearch(location.search)" : ""}
-}
-${navigable ? "" : `globalThis.__kSetSearchParams = setSearchParams
-addEventListener("popstate", () => ${searchParams.length ? "initializeSearch(location.search)" : "undefined"})`}` : ""
-  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
-${searchInitializer}${prefix}${pathname}${query}${suffix}${writer}`
-}
-
-export function specializeRuntime(source, events, hasStateSeed) {
-  const specialized = specializeEvents(source, events)
-  if (hasStateSeed) return specialized
-  return specialized
-    .replace("  const initialState = document.body.dataset.kState\n", "")
-    .replace(/^  if \(initialState\).*\n/m, "")
-}
-
 async function writeJavaScript(file, source, minify, define) {
   const code = minify || define ? (await transform(source, { define, format: "esm", legalComments: "none", minify, target: "es2022" })).code : source
   await writeFile(file, code)
@@ -3866,14 +3606,6 @@ 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 ?? \"[]\") : []")
-    .replace("const descriptor = textDescriptors[Number(node.data.slice(\"k-text:\".length))]", "const descriptor = textDescriptors()[Number(node.data.slice(\"k-text:\".length))]")
-  if (dynamic === source) throw new Error("Navigation text descriptor specialization did not match binding-runtime.js")
-  return dynamic
-}
-
 function normalizeBase(value) {
   if (value == null || value === "" || value === "/") return ""
   if (typeof value !== "string" || !value.startsWith("/") || /[?#\0]/.test(value) || /%(?:2f|5c)/i.test(value)) throw new Error("kudzu.config base must be a root-relative path")
@@ -3906,6 +3638,7 @@ const workerCompiler = createWorkerCompiler({
 })
 
 const printEffectEntry = createEffectCodegen({ assetPath, inlineJson, relativeModulePath })
+const printParamEntry = createParamCodegen({ browserPath, inlineJson, relativeModulePath })
 const handlerLowering = createHandlerLowering({ cloneAst, synthesizeTree })
 const printHandlerModule = createHandlerCodegen({
   resolveClientImport: (entry, handlerPath) => entry.package ? entry.target : relativeModulePath(handlerPath, clientModulePath(entry.target))

package/framework/compiler/list-runtime-codegen.mjs

@@ -0,0 +1,95 @@
+import { assertCapabilityIR } from "./route-capability-planner.mjs"
+
+export function generateListRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  const { lists, effects } = capabilityIR
+  let runtime = replaceRequired(source, '"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import")
+  runtime = lists.calculated
+    ? replaceRequired(runtime, '"./binding-runtime.js"', '"./kudzu-binding.js"', "binding runtime import")
+    : replaceRequired(runtime, /^const loadListEvaluator[^\n]+\n/m, "", "list evaluator loader")
+  runtime = lists.selectors
+    ? replaceRequired(runtime, '"./collection-selector.js"', '"./kudzu-collection-selector.js"', "collection selector import")
+    : replaceRequired(runtime, /^import \{ selectCollection \}[^\n]+\n/m, "", "collection selector import")
+  if (!lists.indexes) {
+    runtime = replaceSequenceRequired(runtime, [
+      ["for (const [index, item] of items.entries()) {", "for (const item of items) {", "item iteration"],
+      ["const key = list.descriptor.key === null ? index : item?.[list.descriptor.key]", "const key = item?.[list.descriptor.key]", "index key"],
+      ["entries.push({ item, index, key, token, value:", "entries.push({ item, key, token, value:", "indexed entry"],
+      ["for (const { item, index, key, token, value } of entries) {", "for (const { item, key, token, value } of entries) {", "indexed entry loop"],
+      ["fillListItem(node, item, list.descriptor.nested, index)", "fillListItem(node, item, list.descriptor.nested)", "indexed item fill", true],
+      ["fillListItem(node, item, list.descriptor.nested, index, mapListItemParts", "fillListItem(node, item, list.descriptor.nested, 0, mapListItemParts", "mapped item fill"],
+      ["function addListRoot(list, { item, index = list.roots.size, key, token, value })", "function addListRoot(list, { item, key, token, value })", "indexed list root"],
+      ["fillListParts(root, listItemParts(root), listItems.get(owner), 0, __KUDZU_LIST_INDEXES__ ? listIndexes.get(owner) ?? 0 : 0)", "fillListParts(root, listItemParts(root), listItems.get(owner), 0)", "indexed root parts"],
+      ["fillListParts(root, parts, item, revision, index, previous)", "fillListParts(root, parts, item, revision, previous)", "indexed fill call"],
+      ["function fillListParts(root, parts, item, revision, index = 0, previous)", "function fillListParts(root, parts, item, revision, previous)", "indexed parts signature"],
+      ["fillListExpressions(root, parts, item, revision, index)", "fillListExpressions(root, parts, item, revision)", "indexed expressions"],
+      ['value?.type === "list-item" ? serializeItem(item) : value?.type === "list-index" ? index : value', 'value?.type === "list-item" ? serializeItem(item) : value', "index capture", true],
+      ["evaluate(descriptor, item, index)", "evaluate(descriptor, item)", "indexed evaluator", true],
+      ["updateListCondition(marker, descriptor.kind, value, item, index)", "updateListCondition(marker, descriptor.kind, value, item)", "indexed condition"],
+      ["function updateListCondition(marker, kind, value, item, index)", "function updateListCondition(marker, kind, value, item)", "indexed condition signature"],
+      ["fillListParts(marker, listItemParts(fragment), item, revision, index)", "fillListParts(marker, listItemParts(fragment), item, revision)", "indexed condition parts"],
+      ["exports[descriptor.handler](item, index, {", "exports[descriptor.handler](item, undefined, {", "indexed state handler call"]
+    ])
+  }
+  if (!lists.selectors) runtime = replaceRequired(runtime, " && !list.descriptor.selector", "", "selector guards", true)
+  if (!lists.indexes) runtime = replaceSequenceRequired(runtime, [
+    [" && !list.descriptor.indexed", "", "indexed guards", true],
+    [" && list.descriptor.key !== null", "", "key guards", true],
+    ["(referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value) || list.descriptor.indexed || list.descriptor.key === null", "referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value", "indexed value comparison"]
+  ])
+  if (lists.rowHooks && !lists.generalRowHooks) runtime = replaceSequenceRequired(replaceRequired(runtime, /\/\* general-row-hooks \*\/[\s\S]*?\/\* general-row-hooks-end \*\/\n/, "", "general row hooks"), [
+    ["initializeGeneralRowHooks", "initializeRowStates", "general row initializer", true],
+    ["if (__KUDZU_LIST_ROW_HOOKS__) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index], roots[index], nested?.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && descriptor.rowStates) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index])", "flat row initialization"],
+    ["if (__KUDZU_LIST_ROW_HOOKS__) initializeRowStates(list.descriptor, key, node, list.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)", "flat row add", true],
+    ["for (const node of registration.list.roots.values()) deleteRowStates(registration.list.descriptor, ownershipPaths.get(node))", "for (const token of registration.list.roots.keys()) deleteFlatRowStates(registration.list.descriptor, token)", "flat registration cleanup"],
+    ["deleteRowStates(list.descriptor, ownershipPaths.get(node))", "deleteFlatRowStates(list.descriptor, token)", "flat row cleanup", true],
+    ["  if (__KUDZU_LIST_ROW_HOOKS__) replaceRowIds(root, rowReplacements.get(root))\n", "", "row ID replacement"],
+    ["  if (!replacements) return\n", "", "row replacement guard"]
+  ])
+  if (!effects.itemDependencies) runtime = replaceRequired(runtime, ", notifyListItem", "", "item notification import")
+  if (!lists.stableFastPaths) runtime = replaceRequired(runtime, /\/\* stable-list-fast-path \*\/[\s\S]*?\/\* stable-list-fast-path-end \*\/\n/, "", "stable list fast path")
+  const stylePatch = `  if (target === "style") {
+    const style = serializeStyle(value)
+    if (style) node.setAttribute("style", style)
+    else node.removeAttribute("style")
+    return
+  }`
+  runtime = replaceRequired(runtime, "  /* list-style */", lists.styleCount ? stylePatch : "", "list style")
+  if (lists.styleCount) runtime = `import { serializeStyle } from "./kudzu-style.js"\n${runtime}`
+  return {
+    source: runtime,
+    define: {
+      __KUDZU_LIST_CONDITIONS__: String(lists.conditions),
+      __KUDZU_DEEP_LIST_CONDITIONS__: String(lists.deepConditions),
+      __KUDZU_LIST_TEXT_RANGES__: String(lists.textRanges),
+      __KUDZU_LIST_ATTRIBUTES__: String(lists.attributes),
+      __KUDZU_LIST_EVENTS__: String(lists.events),
+      __KUDZU_LIST_EXPRESSIONS__: String(lists.expressions),
+      __KUDZU_LIST_EXPRESSION_ATTRIBUTES__: String(lists.expressionAttributes),
+      __KUDZU_LIST_SEEDS__: String(lists.seeds),
+      __KUDZU_LIST_EFFECTS__: String(lists.effects),
+      __KUDZU_LIST_ASYNC_PARTS__: String(lists.asyncParts),
+      __KUDZU_LIST_MOUNTS__: String(lists.mounts),
+      __KUDZU_LIST_ITEM_HOOKS__: String(effects.itemDependencies),
+      __KUDZU_LIST_ROW_HOOKS__: String(lists.rowHooks),
+      __KUDZU_LIST_ROW_REFS__: String(lists.rowRefs),
+      __KUDZU_COMPLEX_LIST_ROW_STATE__: String(lists.complexRowState),
+      __KUDZU_NESTED_LISTS__: String(lists.nested),
+      __KUDZU_COLLECTION_SELECTORS__: String(lists.selectors),
+      __KUDZU_STATIC_COLLECTIONS__: String(lists.static),
+      __KUDZU_LIST_INDEXES__: String(lists.indexes),
+      __KUDZU_LIST_STABLE_FAST_PATHS__: String(lists.stableFastPaths),
+      __KUDZU_SVG_LISTS__: String(lists.svg)
+    }
+  }
+}
+
+function replaceRequired(source, search, replacement, label, all = false) {
+  const output = all ? source.replaceAll(search, replacement) : source.replace(search, replacement)
+  if (output === source) throw new Error(`${label} specialization did not match list-runtime.js`)
+  return output
+}
+
+function replaceSequenceRequired(source, replacements) {
+  return replacements.reduce((output, [search, replacement, label, all]) => replaceRequired(output, search, replacement, label, all), source)
+}

package/framework/compiler/param-codegen.mjs

@@ -0,0 +1,72 @@
+import { join } from "node:path"
+
+export function createParamCodegen({ browserPath, inlineJson, relativeModulePath }) {
+  return function printParamEntry(schema, params, searchParams, searchParamsWritable, output, assetsDirectory, base, runtimeName, navigable) {
+    const hasSearch = searchParams.length || searchParamsWritable
+    const signature = hasSearch ? "pathname, search" : "pathname"
+    const prefix = navigable ? `export function initializeParams(${signature}) {\n${searchParamsWritable ? "globalThis.__kSetSearchParams = setSearchParams\n" : ""}` : `${schema ? "let pathname = location.pathname\n" : ""}${hasSearch ? "let search = location.search\n" : ""}`
+    const suffix = navigable ? "\n}" : ""
+    const pathname = schema ? `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 = 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")
+  path = "/" + pathSegments.slice(base.length).join("/")
+}
+if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
+const segments = path.slice(1).split("/")
+if (segments.length !== schema.length) throw new Error("Runtime route does not match its fallback pattern")
+const values = Object.create(null)
+for (let index = 0; index < schema.length; index++) {
+  const segment = schema[index]
+  const value = decodeSegment(segments[index], Boolean(segment.param))
+  if (segment.literal !== undefined && value !== segment.literal) throw new Error("Runtime route literal does not match")
+  if (segment.param) values[segment.param] = value
+}
+for (const param of params) {
+  const value = values[param.name]
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+function decodeSegment(raw, param) {
+  if (param && /%(?:2f|5c)/i.test(raw)) throw new Error("Runtime route parameter contains an encoded separator")
+  let value
+  try { value = decodeURIComponent(raw) } catch { throw new Error("Runtime route parameter has malformed encoding") }
+  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
+}
+` : ""
+    const searchInitializer = searchParamsWritable && searchParams.length ? `function initializeSearch(search) {
+const query = new URLSearchParams(search)
+for (const param of ${inlineJson(searchParams)}) {
+  const value = query.get(param.name)
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+}
+` : ""
+    const query = searchParams.length ? searchParamsWritable ? "initializeSearch(search)\n" : `const query = new URLSearchParams(search)
+for (const param of ${inlineJson(searchParams)}) {
+  const value = query.get(param.name)
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+` : ""
+    const writer = searchParamsWritable ? `
+function setSearchParams(update, replace) {
+  const next = update(new URLSearchParams(location.search))
+  if (!(next instanceof URLSearchParams)) throw new Error("React Router search parameter updater must return URLSearchParams")
+  const url = new URL(location.href)
+  url.search = next.toString()
+  history[replace ? "replaceState" : "pushState"](null, "", url)
+  ${searchParams.length ? "initializeSearch(location.search)" : ""}
+}
+${navigable ? "" : `globalThis.__kSetSearchParams = setSearchParams
+addEventListener("popstate", () => ${searchParams.length ? "initializeSearch(location.search)" : "undefined"})`}` : ""
+    return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
+${searchInitializer}${prefix}${pathname}${query}${suffix}${writer}`
+  }
+}

package/framework/compiler/route-capability-planner.mjs

@@ -1,9 +1,11 @@
 export function usesRouteDependencyRuntime({ plan, navigable, hasBindings, hasLists }) {
+  assertRouteIR(plan)
   const hasDependencies = plan.effects.some(effect => effect.dependencies?.length)
   return !navigable && hasDependencies && !plan.effects.some(effect => effect.owner) && !hasBindings && !hasLists && !plan.events.some(event => event.native)
 }
 
 export function planRouteCapabilities(plans, { routes = new Map(), navigationRouteCount = 0 } = {}) {
+  for (const plan of plans) assertRouteIR(plan)
   const commandEvents = new Set()
   const nativeEvents = new Set()
   const bindings = { count: 0, text: false, svgConditions: false }
@@ -90,6 +92,7 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
   lists.mounts ||= lists.conditions || lists.nested
 
   return {
+    version: 1,
     routes: routeCounts,
     events: { command: [...commandEvents].sort(), native: [...nativeEvents].sort(), hasNativeHandlers: nativeEvents.size > 0 },
     bindings,
@@ -103,6 +106,38 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
   }
 }
 
+function assertRouteIR(plan) {
+  if (plan?.version !== 1) throw new Error(`Unsupported RouteIR version: ${JSON.stringify(plan?.version)}`)
+  if (!["states", "params", "searchParams", "events", "effects", "bindings", "conditions", "lists"].every(name => Array.isArray(plan[name])) || typeof plan.searchParamsWritable !== "boolean") throw new Error("Invalid RouteIR v1 structure")
+  if (plan.states.some((state, slot) => state?.slot !== slot || typeof state.id !== "string" || typeof state.name !== "string" || !Object.hasOwn(state, "initialValue") || state.lifetime !== undefined && !["layout", "route"].includes(state.lifetime) || state.internal !== undefined && state.internal !== true)) throw new Error("Invalid RouteIR v1 state")
+  if ([...plan.params, ...plan.searchParams].some(param => !isRecord(param) || typeof param.name !== "string" || typeof param.id !== "string")) throw new Error("Invalid RouteIR v1 parameter")
+  if (plan.events.some(event => !isRecord(event) || typeof event.event !== "string" || event.commands !== undefined && (!Array.isArray(event.commands) || event.commands.some(command => !Array.isArray(command))) || event.native !== undefined && (!isRecord(event.native) || typeof event.native.module !== "string" || typeof event.native.handler !== "string" || !isRecord(event.native.states) || !isRecord(event.native.scope)))) throw new Error("Invalid RouteIR v1 event")
+  if (plan.effects.some(effect => !isRecord(effect) || typeof effect.module !== "string" || typeof effect.handler !== "string" || !isRecord(effect.states) || !isRecord(effect.scope))) throw new Error("Invalid RouteIR v1 effect")
+  if (plan.bindings.some(binding => !isRecord(binding) || typeof binding.target !== "string") || plan.conditions.some(condition => !isRecord(condition) || condition.svg !== undefined && typeof condition.svg !== "boolean") || plan.lists.some(list => !isRouteList(list))) throw new Error("Invalid RouteIR v1 binding, condition, or list")
+}
+
+export function assertCapabilityIR(capabilityIR) {
+  if (capabilityIR?.version !== 1) throw new Error(`Unsupported CapabilityIR version: ${JSON.stringify(capabilityIR?.version)}`)
+  const sections = ["routes", "events", "bindings", "lists", "effects", "captures", "runtime"]
+  if (!sections.every(name => isRecord(capabilityIR[name]))) throw new Error("Invalid CapabilityIR v1 structure")
+  if (!["behaviors", "regularBehaviors", "regularStateSeeds", "dependencyStateSeeds"].every(name => isCount(capabilityIR.routes[name]))) throw new Error("Invalid CapabilityIR v1 route counts")
+  if (!["command", "native"].every(name => Array.isArray(capabilityIR.events[name]) && capabilityIR.events[name].every(event => typeof event === "string")) || typeof capabilityIR.events.hasNativeHandlers !== "boolean") throw new Error("Invalid CapabilityIR v1 events")
+  if (!isCount(capabilityIR.bindings.count) || !["text", "svgConditions"].every(name => typeof capabilityIR.bindings[name] === "boolean")) throw new Error("Invalid CapabilityIR v1 bindings")
+  const listFlags = ["conditions", "svg", "deepConditions", "textRanges", "attributes", "events", "expressions", "expressionAttributes", "seeds", "effects", "rowHooks", "rowRefs", "complexRowState", "nested", "selectors", "calculated", "static", "indexes", "stableFastPaths", "generalRowHooks", "asyncParts", "mounts"]
+  if (!isCount(capabilityIR.lists.count) || !isCount(capabilityIR.lists.styleCount) || !listFlags.every(name => typeof capabilityIR.lists[name] === "boolean")) throw new Error("Invalid CapabilityIR v1 lists")
+  if (!["any", "derivedDependencies", "itemDependencies", "captures", "navigable", "navigableOwners"].every(name => typeof capabilityIR.effects[name] === "boolean") || !["nestedState", "setter"].every(name => typeof capabilityIR.captures[name] === "boolean") || !["shared", "dependency"].every(name => typeof capabilityIR.runtime[name] === "boolean")) throw new Error("Invalid CapabilityIR v1 effect, capture, or runtime flags")
+}
+
+const isRecord = value => value !== null && typeof value === "object" && !Array.isArray(value)
+const isCount = value => Number.isSafeInteger(value) && value >= 0
+const isRouteList = list => isRecord(list)
+  && typeof list.id === "string"
+  && typeof list.state === "string"
+  && (typeof list.key === "string" || list.key === null)
+  && Array.isArray(list.keys)
+  && ["svg", "static", "indexed", "reducer", "mount", "nested", "effects", "conditions", "conditionHandlers", "textRanges", "attributes", "events", "expressions", "expressionAttributes", "fastRelease"].every(name => list[name] === undefined || list[name] === true)
+  && ["selector", "children", "expressionStates", "rowStates", "rowConditions", "rowRefs"].every(name => list[name] === undefined || Array.isArray(list[name]))
+
 function hasCaptureType(value, type) {
   if (!value || typeof value !== "object") return false
   if (value.type === type) return true

package/framework/compiler/runtime-codegen.mjs

@@ -0,0 +1,146 @@
+import { assertCapabilityIR } from "./route-capability-planner.mjs"
+
+export function generateCoreRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  const { effects, events, routes } = capabilityIR
+  let runtime = specializeRuntime(source, events.command, routes.regularStateSeeds > 0)
+  if (!effects.itemDependencies && capabilityIR.runtime.shared) runtime = replaceRequired(runtime, /\/\* list-item-hooks \*\/[\s\S]*?\/\* list-item-hooks-end \*\/\n/, "", "list item hooks", "shared-runtime.js")
+  if (effects.navigable) runtime = replaceRequired(runtime, "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}", "navigable committer", "shared-runtime.js")
+  if (effects.navigableOwners) runtime = replaceSequenceRequired(runtime, [
+    ["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}", "navigable mount hook"],
+    ["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}", "navigable unmount hook"]
+  ], "shared-runtime.js")
+  return runtime
+}
+
+export function generateEffectRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  const { captures, effects } = capabilityIR
+  return {
+    source: effects.captures ? replaceRequired(source, '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "effect-runtime.js") : replaceRequired(source, /^import[^\n]+\n/, "", "serialization import", "effect-runtime.js"),
+    define: {
+      "globalThis.__KUDZU_CAPTURE_SETTER__": String(captures.setter),
+      "globalThis.__KUDZU_EFFECT_CAPTURES__": String(effects.captures)
+    }
+  }
+}
+
+export function generateBindingRuntime(source, capabilityIR, navigable) {
+  assertCapabilityIR(capabilityIR)
+  let runtime = replaceRequired(source, '"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import", "binding-runtime.js")
+  runtime = replaceRequired(runtime, '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "binding-runtime.js")
+  runtime = replaceRequired(runtime, '"./style.js"', '"./kudzu-style.js"', "style import", "binding-runtime.js")
+  if (navigable) runtime = specializeNavigationTextDescriptors(runtime)
+  return {
+    source: runtime,
+    define: {
+      "globalThis.__KUDZU_TEXT_BINDINGS__": String(capabilityIR.bindings.text),
+      "globalThis.__KUDZU_SVG_CONDITIONS__": String(capabilityIR.bindings.svgConditions),
+      "globalThis.__KUDZU_CAPTURE_STATE__": String(capabilityIR.captures.nestedState)
+    }
+  }
+}
+
+export function generateNativeRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  return {
+    source: specializeEvents(replaceRequired(replaceRequired(source, '"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import", "native-runtime.js"), '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "native-runtime.js"), capabilityIR.events.native),
+    define: { "globalThis.__KUDZU_CAPTURE_SETTER__": String(capabilityIR.captures.setter) }
+  }
+}
+
+export function generateNavigationRuntime(source, group) {
+  let runtime = replaceSequenceRequired(source, [
+    ["__KUDZU_NAVIGATION_ROUTES__", JSON.stringify(group.records).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029"), "route records"],
+    ["__KUDZU_APPLICATION_ID__", JSON.stringify(group.applicationId), "application ID"],
+    ["__KUDZU_LAYOUT_ID__", JSON.stringify(group.layoutId), "layout ID"],
+    ['"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import"]
+  ], "navigation-runtime.js")
+  runtime = specializeNavigationPatterns(runtime, group.records.some(record => record.segments))
+  return specializeNavigationEffects(runtime, group.hasEffects || group.hasParams)
+}
+
+export function specializeRuntime(source, events, hasStateSeed) {
+  const specialized = specializeEvents(source, events)
+  if (hasStateSeed) return specialized
+  return replaceSequenceRequired(specialized, [
+    ["  const initialState = document.body.dataset.kState\n", "", "initial state read"],
+    [/^  if \(initialState\).*\n/m, "", "initial state parse"]
+  ], "runtime source")
+}
+
+function specializeEvents(source, events) {
+  return replaceRequired(source, /const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`, "event names", "runtime source")
+}
+
+function replaceRequired(source, search, replacement, label, file) {
+  const output = source.replace(search, replacement)
+  if (output === source) throw new Error(`${label} specialization did not match ${file}`)
+  return output
+}
+
+function replaceSequenceRequired(source, replacements, file) {
+  return replacements.reduce((output, [search, replacement, label]) => replaceRequired(output, search, replacement, label, file), source)
+}
+
+function specializeNavigationEffects(source, enabled) {
+  if (enabled) return source
+  return replaceSequenceRequired(source, [
+    ["const noDispose = async () => {}\nlet routeDispose = noDispose\nlet layoutDispose = noDispose\nconst ready = mountInitial()\n", "", "initial effect lifecycle"],
+    [`addEventListener("pagehide", event => {
+  if (event.persisted) return
+  ++revision
+  request?.abort()
+  void (async () => {
+    await routeDispose()
+    await layoutDispose()
+  })()
+})
+`, "", "pagehide effect lifecycle"],
+    [`
+async function mountInitial() {
+  try {
+    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, location.search)
+    layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
+    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
+  } catch (error) {
+    console.error(error)
+  }
+}
+`, "", "initial effect mount"],
+    ["  await ready\n", "", "initial effect readiness"],
+    ["    const { incoming, parsed, capabilities } = documentResult\n", "    const { incoming, parsed } = documentResult\n", "navigation capability result"],
+    ["    await routeDispose()\n    if (current !== revision) return\n", "", "route effect disposal"],
+    ["    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)\n", "    commit(incoming, parsed.nodes)\n", "navigation capability commit"],
+    ["    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "", "route effect mount"],
+    ["  return { incoming, parsed, capabilities: await loadCapabilities(parsed), record }\n", "  await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n  return { incoming, parsed, record }\n", "navigation capability load"],
+    [`
+async function loadCapabilities(parsed) {
+  const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
+  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] }
+}
+`, "", "capability loader"]
+  ], "navigation-runtime.js")
+}
+
+function specializeNavigationPatterns(source, enabled) {
+  if (enabled) return source
+  return replaceRequired(source, /function matchRoute\(pathname\) \{[\s\S]+?\n\}\n\nfunction fallback/, `function matchRoute(pathname) {
+  return routes.find(record => record.path === pathname)
+}
+
+function fallback`, "exact route matcher", "navigation-runtime.js")
+}
+
+function specializeNavigationTextDescriptors(source) {
+  return replaceSequenceRequired(source, [
+    ["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 ?? \"[]\") : []", "text descriptor reader"],
+    ["const descriptor = textDescriptors[Number(node.data.slice(\"k-text:\".length))]", "const descriptor = textDescriptors()[Number(node.data.slice(\"k-text:\".length))]", "text descriptor lookup"]
+  ], "binding-runtime.js")
+}

package/framework/core.d.ts

@@ -131,6 +131,46 @@ export type ListDescriptor = {
   valueSeed?: Record<string, string | number | boolean | null>
 }
 
+export interface RouteIR {
+  version: 1
+  states: Array<{ slot: number; id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route"; internal?: true }>
+  params: Array<{ name: string; id: string }>
+  searchParams: Array<{ name: string; id: string }>
+  searchParamsWritable: boolean
+  events: Array<{
+    event: string
+    commands?: Array<[string, string, unknown]>
+    native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
+  }>
+  effects: Array<{
+    module: string
+    handler: string
+    states: Record<string, string>
+    scope: Record<string, unknown>
+    lifetime?: "layout" | "route"
+    dependencies?: string[]
+    dependencyExpressions?: unknown[]
+    dependencyStates?: Record<string, string>
+    itemDependencies?: string[]
+    listState?: string
+    cleanup?: true
+    owner?: string
+    list?: true
+  }>
+  bindings: Array<{
+    target: string
+    state?: string
+    module?: string
+    handler?: string
+    states?: Record<string, string>
+    scope?: Record<string, unknown>
+    scopeStates?: Record<string, string>
+    scopeBindings?: Record<string, unknown>
+  }>
+  conditions: Array<Record<string, unknown>>
+  lists: ListDescriptor[]
+}
+
 export function renderPage<Props = Record<string, never>>(
   component: (props: Props) => unknown | Promise<unknown>,
   metadata?: PageMetadata,
@@ -146,42 +186,5 @@ export function renderPage<Props = Record<string, never>>(
   hasListStyles: boolean
   hasStateSeed: boolean
   handlerModules: string[]
-  plan: {
-    states: Array<{ id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route"; internal?: true }>
-    params: Array<{ name: string; id: string }>
-    searchParams: Array<{ name: string; id: string }>
-    searchParamsWritable: boolean
-    events: Array<{
-      event: string
-      commands?: Array<[string, string, unknown]>
-      native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
-    }>
-    effects: Array<{
-      module: string
-      handler: string
-      states: Record<string, string>
-      scope: Record<string, unknown>
-      lifetime?: "layout" | "route"
-      dependencies?: string[]
-      dependencyExpressions?: unknown[]
-      dependencyStates?: Record<string, string>
-      itemDependencies?: string[]
-      listState?: string
-      cleanup?: true
-      owner?: string
-      list?: true
-    }>
-    bindings: Array<{
-      target: string
-      state?: string
-      module?: string
-      handler?: string
-      states?: Record<string, string>
-      scope?: Record<string, unknown>
-      scopeStates?: Record<string, string>
-      scopeBindings?: Record<string, unknown>
-    }>
-    conditions: Array<Record<string, unknown>>
-    lists: ListDescriptor[]
-  }
+  plan: RouteIR
 }>

package/framework/core.mjs

@@ -527,7 +527,8 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
       hasStateSeed: initialState.length > 0,
       handlerModules: [...renderContext.handlerModules],
       plan: {
-        states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
+        version: 1,
+        states: Object.entries(renderContext.states).map(([id, state], slot) => ({ slot, id, ...state })),
         params: renderContext.paramEntries,
         searchParams: renderContext.searchParamEntries,
         searchParamsWritable: renderContext.searchParamsWritable,

package/package.json

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