@kudzujs/core 0.8.19 → 0.8.20

package/MIGRATION_ROADMAP.md

@@ -216,6 +216,13 @@ This queue orders the next investigations by general migration value. Start only
 - Existing tagged collection expressions and selectors are canonical DerivedIR for rendered lists and derived effect dependencies; transformed source embeds the registered records rather than parallel analyzer values.
 - AST, `Map`, and `Set` callback descriptors remain private only until source-local lowering completes. Handler codegen now performs no TypeScript traversal or state/capture/reducer/import discovery, while command-only routes retain zero handler ESM.
 
+### Completed In 0.8.20
+
+- Every rendered keyed collection now finalizes into JSON-safe KeyedBlockIR with deterministic slots, explicit parent/child links, collection and selector ownership, key/index policy, source provenance, and complete component-specialization membership.
+- Keyed row states and refs retain their declaration source and specialization owner. Command, native, effect, list-expression, list-conditional, and calculated-collection records link back to their owning keyed block.
+- 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.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

package/PERFORMANCE.md

@@ -1,5 +1,47 @@
 # Performance Records
 
+## 0.8.20 Explicit Keyed 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 `0.8.19` commit `c516173` and the current `0.8.20` compiler candidate used the same local volume and identical installed dependencies.
+
+The candidate implementation patch over `c516173` had SHA-256 `137f68090f6024374077f46cb61767f48dff27a193d33c9e92409b8dd7bb7d21`, produced by:
+
+```bash
+git diff --binary c516173 -- framework/build.mjs framework/compiler/descriptor-session.mjs framework/compiler/ir/module-ir.mjs framework/core.d.ts | shasum -a 256
+```
+
+Both targets received one warm-up followed by 21 clean `keyed-row-hooks` production builds in round-robin alternating order. Cleanup remained outside timing. The distributions overlap; the candidate median was 0.52% lower and does not establish a material change.
+
+| Target | Build median | List runtime raw / gzip |
+|---|---:|---:|
+| 0.8.19 baseline | 266.8 ms | 21,831 B / 6,930 B |
+| 0.8.20 candidate | 265.4 ms | 21,831 B / 6,930 B |
+
+```text
+0.8.19: [272.5,269.7,262.6,267.3,262.9,265.2,268.0,264.7,262.0,268.3,267.1,262.5,263.7,266.8,263.2,267.5,263.3,268.8,266.7,266.9,271.4]
+0.8.20: [262.5,267.4,266.2,261.7,265.1,262.9,269.9,264.1,275.0,268.2,263.4,263.7,265.4,268.7,263.8,266.1,265.4,265.3,267.2,270.1,263.2]
+```
+
+The recorded cleanup, warm-up, timing, median, and runtime-size measurement is reproducible with:
+
+```bash
+BASELINE_ROOT="/var/folders/bt/3r_ntp5x65j81brs6_p93rl00000gn/T/opencode/kudzu-0820-baseline" CANDIDATE_ROOT="/Users/songchibong/Documents/GitHub/kudzu" node --input-type=module -e 'import { spawnSync } from "node:child_process"; import { rmSync,readFileSync } from "node:fs"; import { gzipSync } from "node:zlib"; import { performance } from "node:perf_hooks"; import { resolve } from "node:path"; const roots={baseline:process.env.BASELINE_ROOT,candidate:process.env.CANDIDATE_ROOT}; const runs={baseline:[],candidate:[]}; const fixture="keyed-row-hooks"; const build=name=>{const root=roots[name],cwd=resolve(root,"test/fixtures",fixture); rmSync(resolve(cwd,"dist"),{recursive:true,force:true}); rmSync(resolve(cwd,".kudzu"),{recursive:true,force:true}); const start=performance.now(); const result=spawnSync(process.execPath,[resolve(root,"bin/kudzu.mjs"),"build"],{cwd,encoding:"utf8"}); if(result.status) throw new Error(result.stderr||result.stdout); return Number((performance.now()-start).toFixed(1));}; build("baseline"); build("candidate"); for(let index=0;index<21;index++) for(const name of index%2?["candidate","baseline"]:["baseline","candidate"]) runs[name].push(build(name)); const median=values=>[...values].sort((a,b)=>a-b)[Math.floor(values.length/2)]; const sizes={}; for(const [name,root] of Object.entries(roots)){const file=readFileSync(resolve(root,"test/fixtures",fixture,"dist/assets/kudzu-list.js")); sizes[name]=[file.length,gzipSync(file).length];} console.log(JSON.stringify({runs,medians:{baseline:median(runs.baseline),candidate:median(runs.candidate)},sizes}));'
+```
+
+Before release-content updates, the complete site `dist` was byte-identical. Seven representative keyed fixtures retained identical file lists and SHA-256 content; `.kudzu` comparison replaced only each worktree's absolute root in existing source-location strings. The complete compared lists were:
+
+```text
+lists: dist/assets/handlers/pages/index.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu-style.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/index.html, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs
+nested-lists: dist/assets/effects/index.js, dist/assets/handlers/pages/index.js, dist/assets/kudzu-effect.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/index.html, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs
+keyed-row-hooks: dist/assets/effects/index.js, dist/assets/handlers/pages/index.js, dist/assets/kudzu-binding.js, dist/assets/kudzu-effect.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu-style.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/index.html, .kudzu/HookRow.mjs, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs
+svg-structures: dist/assets/handlers/pages/index.js, dist/assets/kudzu-binding.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu-style.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/index.html, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs
+calculated-collections: dist/assets/handlers/pages/index.js, dist/assets/handlers/pages/ordinary.js, dist/assets/kudzu-binding.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu-style.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/assets/native/ordinary/index.js, dist/index.html, dist/ordinary/index.html, dist/static/index.html, .kudzu/calculate.mjs, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs, .kudzu/pages/ordinary.mjs, .kudzu/pages/static.mjs
+rendered-collections: dist/assets/handlers/pages/index.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/index.html, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs, .kudzu/selectVisible.mjs
+keyed-effects: dist/assets/effects/index.js, dist/assets/effects/item-only/index.js, dist/assets/effects/state-only/index.js, dist/assets/handlers/pages/index.js, dist/assets/handlers/pages/item-only.js, dist/assets/handlers/pages/state-only.js, dist/assets/kudzu-binding.js, dist/assets/kudzu-effect.js, dist/assets/kudzu-list.js, dist/assets/kudzu-native.js, dist/assets/kudzu-serialization.js, dist/assets/kudzu-style.js, dist/assets/kudzu.js, dist/assets/native/index.js, dist/index.html, dist/item-only/index.html, dist/state-only/index.html, .kudzu/EffectRow.mjs, .kudzu/kudzu-plan.json, .kudzu/pages/index.mjs, .kudzu/pages/item-only.mjs, .kudzu/pages/state-only.mjs
+```
+
+This measurement covers compiler clean-build startup and generated list-runtime size, not browser reconciliation latency. Browser behavior remains covered by the existing insert/update/reorder/remove/nested/SVG/state/effect/ref integration checks.
+
 ## 0.8.19 Handler, Binding, And Derived IR
 
 Measured UTC 2026-08-08 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 `0.8.18` tag `3598be0` and the `0.8.19` compiler-only candidate used detached worktrees on the same temporary volume with 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.19 - Handler, binding, and derived IR.** Native callbacks, reactive bindings, list evaluators, imports, and pure derived expressions now cross one JSON-safe ModuleIR boundary before source-only artifact codegen. Read the [release notes](./RELEASES.md#0819---handler-binding-and-derived-ir), open the [release page](https://kudzujs.cloud/releases/0.8.19), or follow the [next architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.20 - Explicit keyed ownership.** Keyed collections now retain deterministic JSON-safe parent/child, selector, component-specialization, row state/ref, handler, and binding ownership while final DOM allocation remains unchanged. Read the [release notes](./RELEASES.md#0820---explicit-keyed-ownership), open the [release page](https://kudzujs.cloud/releases/0.8.20), or follow the [next 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,37 @@
 # Kudzu Releases
 
+## 0.8.20 - Explicit keyed ownership
+
+Kudzu 0.8.20 completes the next Goal A source-analysis boundary: keyed collection sites now finalize into deterministic JSON-safe ownership records before the existing build-time renderer allocates DOM identity and lifecycle state.
+
+### Changed in 0.8.20
+
+- KeyedBlockIR records parent/child slots, collection signal or calculated binding, key/index policy, owner field, selector reference and states, source provenance, and static status.
+- Recursive same-file and imported row expansion records every component-specialization slot, including stateless intermediate components.
+- Row states and refs retain their specialization owner and declaration source.
+- Command, native, effect, list-expression, list-conditional, and calculated-collection HandlerIR/BindingIR records link to their owning keyed block.
+- Transformer-wide keyed value, condition, event, nested-list, effect, rendered-list, and alias AST side tables were removed; temporary AST stays inside immediate source-local validation and lowering.
+- The existing route list descriptor now has an explicit TypeScript shape without changing its serialized data.
+
+### Goal A boundary
+
+- `core.mjs` remains authoritative for final list IDs, row key paths, route descriptors, complete HTML, SVG context, state/ref/effect allocation, and exact release.
+- Effect setup, cleanup, dependency, Worker, and lifetime ownership remains on the existing path until EffectIR in `0.8.21`.
+- No accepted syntax, public API, browser capability, VDOM, hydration, component rerender, or retained browser component tree was added.
+
+### Validation
+
+- The complete suite passes 168/168 tests, including deterministic KeyedBlockIR JSON round-trip and calculated, nested, recursive-component, selector, state, ref, handler, binding, effect, and SVG ownership.
+- Before release-content updates, the complete site `dist` and seven representative keyed fixture output trees matched `v0.8.19`; detached-worktree roots were normalized only in existing `.kudzu` source strings.
+- The keyed list runtime remains byte-identical at 21,831 B raw / 6,930 B gzip. A same-volume 21-run interleaved comparison measured a 0.52% lower candidate median; raw arrays and provenance are recorded in `PERFORMANCE.md`.
+- `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.20
+```
+
 ## 0.8.19 - Handler, binding, and derived IR
 
 Kudzu 0.8.19 completes the next Goal A source-analysis boundary: native callbacks, reactive bindings, list evaluators, imports, and pure derived expressions now finalize into JSON-safe ModuleIR before mechanical artifact codegen.

package/docs/next-architecture/README.md

@@ -6,7 +6,7 @@ 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.19` handler/binding/derived IR complete | Continue with `0.8.20` KeyedBlockIR ownership after the release boundary. |
+| A: compiler foundation | `0.8.20` KeyedBlockIR ownership complete | Continue with `0.8.21` EffectIR ownership after the release boundary. |
 | B: optimization benchmarks | Deferred | Goal A complete and its output baseline recorded |
 | 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,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the completed `0.8.19` handler, binding, and derived IR boundary. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves code.
+This maps the completed `0.8.20` keyed ownership boundary. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves code.
 
 ## Responsibility Map
 
@@ -13,9 +13,9 @@ This maps the completed `0.8.19` handler, binding, and derived IR boundary. File
 | 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. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
 | Pure collection language | [`framework/compiler/collection-analysis.mjs`](../../framework/compiler/collection-analysis.mjs) | Analyzes collection roots/selectors and serializes the allowed pure expression language used by lists and derived dependencies. |
-| Main semantic analysis | `framework/build.mjs`, `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, and derived results while still owning effect and keyed-list ownership side tables. |
+| Main semantic analysis | `framework/build.mjs`, `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, and keyed ownership results while still owning effect-lifetime side tables. |
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Retains ordered JSON-safe owner and specialization records for state, setters, props, refs, IDs, direct signal links, and source provenance; AST identity remains private to its source-local session. |
-| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, imports, and client roots into ModuleIR. |
+| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, imports, and client roots into ModuleIR. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Supported command handlers specialize to JSON-safe ModuleIR, then emit the existing `__kBehavior` AST without changing route plans. |
 | Build module generation | `framework/build.mjs`, `compile()` | Runs TypeScript with the Kudzu transformer, writes build-executable modules to `.kudzu`, rejects surviving React/Router runtime references, and generates handler source when descriptors exist. |
 | Handler/evaluator lowering | [`framework/compiler/handler-lowering.mjs`](../../framework/compiler/handler-lowering.mjs) | Completes source-local callback/binding/list AST rewriting and diagnostics before the JSON-safe IR boundary. |
@@ -58,7 +58,7 @@ The browser consumes static HTML first. State seeds and descriptors in that HTML
 ## Current Coupling To Remove
 
 - `createKudzuTransformer()` combines discovery, validation, specialization, descriptor registration, and transformed-source emission.
-- Effect/keyed ownership relationships and transient component rewrite indexes remain in `WeakMap`/`WeakSet` tables keyed by AST identity; handler, binding, derived, and component ownership now have explicit JSON-safe source results.
+- Effect ownership relationships and transient component rewrite indexes remain source-local AST indexes; handler, binding, derived, keyed, 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.

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

@@ -2,7 +2,7 @@
 
 ## Status
 
-The `0.8.19` HandlerIR, BindingIR, and DerivedIR seam is complete. Goal A continues with the planned `0.8.20` KeyedBlockIR ownership result while preserving accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
+The `0.8.20` KeyedBlockIR ownership result is complete. Goal A continues with the planned `0.8.21` EffectIR seam while preserving 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.19` source result adds module-export HandlerIR, BindingIR, ordered imports/client roots, and canonical tagged DerivedIR beside command and component ownership. Source-local AST lowering completes before this boundary; artifact codegen consumes finalized records without semantic traversal. Initial values, final state IDs, effect ownership, and keyed blocks join their explicit results in later planned patches; `core.mjs` remains authoritative for route allocation today.
+The `0.8.20` source result adds deterministic KeyedBlockIR parent/child ownership, collection and selector references, complete specialization membership, row state/ref provenance, and keyed HandlerIR/BindingIR links beside the existing command, component, handler, binding, and derived results. Source-local keyed AST validation is consumed during lowering and does not cross this boundary. Initial values, final state IDs, and effect lifetime ownership join their explicit results in later planned patches; `core.mjs` remains authoritative for route allocation today.
 
 Source codegen lowers that data through the existing build ABI:
 

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.19` 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.20` are completed scopes represented by package/release records; later rows remain planned until their package version and release record exist.
 
 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.
 

package/framework/README.md

@@ -36,12 +36,12 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/animation-frame-pass.mjs`: effect-owned animation-frame ref validation and plain mutable effect-scope lowering.
 - `compiler/browser-signal-passes.mjs`: static media-query external-store and navigator capability-condition normalization.
 - `compiler/collection-analysis.mjs`: pure collection expression IR, selector pipeline, alias, and imported-transform analysis.
-- `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, import, and client-root finalization.
+- `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, import, and client-root finalization.
 - `compiler/normalization-pipeline.mjs`: ordered source normalization with parent-pointer repair after every compiler pass.
 - `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.
-- `compiler/optimize/command-specialization.mjs`, `compiler/ir/module-ir.mjs`, and `compiler/codegen/command-codegen.mjs`: JSON-safe command analysis, sparse per-source ModuleIR, and source-analysis-free existing behavior-call generation.
+- `compiler/optimize/command-specialization.mjs`, `compiler/ir/module-ir.mjs`, and `compiler/codegen/command-codegen.mjs`: JSON-safe command and keyed ownership registration, sparse per-source ModuleIR, and source-analysis-free existing behavior-call generation.
 - `compiler/handler-lowering.mjs`: source-local native/effect callback, reducer, Context, Zustand, reactive-binding, and list-evaluator AST lowering before IR finalization.
 - `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.
@@ -64,7 +64,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 handler, effect, binding, list, and client-import descriptors. `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 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 handler, effect callback, binding, keyed block, and client-import descriptors. Keyed blocks link deterministic parent/child sites, component specializations, row states/refs, and generated handlers/bindings without replacing `core.mjs` final DOM ownership. `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.
 
 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

@@ -952,13 +952,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const customHooks = new Map()
     const jsxLocalDeclarations = new Map()
     const jsxLocalsByFunction = new Map()
-    const listLocalDeclarations = new WeakSet()
-    const listLocalUses = new WeakMap()
-    const listValues = new WeakMap()
-    const listEventItems = new WeakMap()
-    const listConditions = new WeakMap()
-    const nestedLists = new WeakMap()
-    const listEffectEntries = new WeakMap()
+    const listLocalDeclarations = []
+    const listLocalUses = []
     const componentEffectEntries = new WeakMap()
     const analysisSource = node => {
       const original = ts.getOriginalNode(node)
@@ -1340,8 +1335,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           const position = sourceFile.getLineAndCharacterOfPosition(declaration.node.getStart(sourceFile))
           if (uses.length > 1) throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} Keyed list local "${name}" must be rendered exactly once`)
           if (references !== uses.length) throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} Keyed list local "${name}" may only be used as a JSX child`)
-          listLocalDeclarations.add(declaration.node)
-          if (uses.length) listLocalUses.set(uses[0], parts)
+          listLocalDeclarations.push(declaration.node)
+          if (uses.length) listLocalUses.push({ node: uses[0], parts })
         }
       }
     }
@@ -1484,6 +1479,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         ids: result.ordinaryIds.map(({ name, source }) => ({ name, ...(analysisSource(source) ? { source: analysisSource(source) } : {}) }))
       })
       for (const state of [...result.rowStates, ...result.ordinaryStates]) state.analysisOwner = `specialization:${result.analysis.slot}`
+      for (const ref of [...result.rowRefs, ...result.ordinaryRefs]) ref.analysisOwner = `specialization:${result.analysis.slot}`
       return result
     }
     const registerRowHooks = (call, specialization) => {
@@ -1847,20 +1843,20 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           if (expanded === value || !referencedStateNames(expanded, setters).size) fail(value, "Calculated collection fields must directly depend on local state")
           return expanded
         }
-        const parts = listLocalUses.get(node) ?? keyedListParts(node.expression, setters, jsxLocalDeclarations.get(owner), fail, new Set(), importedCollections, factory, context, importedCollectionTransforms, calculatedCollection, staticCollection)
+        const parts = listLocalUses.find(entry => entry.node === node)?.parts ?? keyedListParts(node.expression, setters, jsxLocalDeclarations.get(owner), fail, new Set(), importedCollections, factory, context, importedCollectionTransforms, calculatedCollection, staticCollection)
         if (parts) {
-          for (const declaration of parts.aliasDeclarations ?? []) listLocalDeclarations.add(declaration)
+          for (const declaration of parts.aliasDeclarations ?? []) if (!listLocalDeclarations.includes(declaration)) listLocalDeclarations.push(declaration)
           rawRenderedLists.push({ node, parts })
         }
       }
       ts.forEachChild(node, collectRenderedLists)
     }
     collectRenderedLists(sourceFile)
-    const collectionAliasUses = new WeakSet(rawRenderedLists.flatMap(({ parts }) => parts.aliasUses ?? []))
+    const collectionAliasUses = rawRenderedLists.flatMap(({ parts }) => parts.aliasUses ?? [])
     const collectionAliasDeclarations = new Set(rawRenderedLists.flatMap(({ parts }) => parts.aliasDeclarations ?? []))
     for (const declaration of collectionAliasDeclarations) {
       const owner = nearestFunction(declaration)
-      const unsupported = identifierReferences(owner.body, declaration.name.text).find(reference => !collectionAliasUses.has(reference))
+      const unsupported = identifierReferences(owner.body, declaration.name.text).find(reference => !collectionAliasUses.includes(reference))
       if (unsupported) fail(unsupported, `Rendered collection alias "${declaration.name.text}" may only be used as a rendered collection source`)
     }
     const rejectUnsupportedRenderControl = node => {
@@ -1912,7 +1908,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       let count = 0
       const visit = (node, currentAggregate = aggregate) => {
         if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) {
-          const nestedAggregate = { calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [] }
+          const nestedAggregate = { calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [], specializations: [] }
           for (const argument of node.arguments) visit(argument, nestedAggregate)
           if (nestedAggregate.hookDeclarations.length || nestedAggregate.effects.length) nestedRowSpecializations.set(`${node.pos}:${node.end}`, nestedAggregate)
           return
@@ -1939,6 +1935,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           if (imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, component.getSourceFile(), node, specialization.effects))
           expandedRowSpecializations.set(specialization.root, specialization)
           if (currentAggregate) {
+            currentAggregate.specializations ??= []
+            currentAggregate.specializations.push(specialization.analysis.slot, ...(specialization.specializations ?? []))
             currentAggregate.effects.push(...specialization.effects)
             currentAggregate.hookDeclarations.push(...specialization.hookDeclarations)
             currentAggregate.rowStates.push(...specialization.rowStates)
@@ -1957,8 +1955,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       expanded.parent = root.parent
       return expanded
     }
-    const renderedLists = new WeakMap()
-    const prepareListCallback = (callback, root, specialization, item) => {
+    const preparedRenderedLists = []
+    const prepareListCallback = (callback, root, specialization, item, effectEntries) => {
       const statements = [...specialization.hookDeclarations]
       if (specialization.effects.length) {
         usesListEffects = true
@@ -1966,7 +1964,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           const call = factory.updateCallExpression(entry.call, factory.createIdentifier("__kListUseEffect"), entry.call.typeArguments, entry.call.arguments)
           synthesizeTree(call)
           const effectSource = entry.source.getSourceFile()
-          listEffectEntries.set(call, { item, source: entry.source, sourceFile: effectSource, imports: clientImportBindings(effectSource, effectSource.fileName, sourceFiles) })
+          effectEntries.push({ node: call, item, source: entry.source, sourceFile: effectSource, imports: clientImportBindings(effectSource, effectSource.fileName, sourceFiles) })
           return factory.createExpressionStatement(call)
         }))
       }
@@ -1997,15 +1995,25 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         ts.setParentRecursive(callback, false)
         callback.parent = originalParts.callback.parent
       }
-      callback = prepareListCallback(callback, root, specialization, originalParts.item)
-      const parts = { ...originalParts, root, callback, analysisStateOwners: new Map([...stateOwnersForNode(originalParts.root), ...[...specialization.rowStates, ...specialization.ordinaryStates].map(state => [state.state, state.analysisOwner])]) }
+      const effectEntries = []
+      callback = prepareListCallback(callback, root, specialization, originalParts.item, effectEntries)
+      const parts = {
+        ...originalParts,
+        root,
+        callback,
+        effectEntries,
+        specializations: [specialization.analysis?.slot, ...(specialization.specializations ?? [])].filter(slot => slot !== undefined),
+        rowStates: [...specialization.rowStates, ...specialization.ordinaryStates],
+        rowRefs: specialization.rowRefs,
+        analysisStateOwners: new Map([...stateOwnersForNode(originalParts.root), ...[...specialization.rowStates, ...specialization.ordinaryStates].map(state => [state.state, state.analysisOwner])])
+      }
       for (const calculation of specialization.calculations) {
         ts.setParentRecursive(calculation, false)
         calculation.parent = callback
         validateListExpression(calculation, parts.item, originalParts.root, fail)
       }
-      validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, settersForNode(originalParts.root, settersByFunction), specialization.rowStates, nestedLists, componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback)
-      renderedLists.set(node, parts)
+      const analysis = validateKeyedList(parts, sourceFile, settersForNode(originalParts.root, settersByFunction), specialization.rowStates, componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback)
+      preparedRenderedLists.push({ node, parts, analysis })
     }
 
     const compileRenderExpression = (expression, anchor) => {
@@ -2027,6 +2035,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     }
 
     let activeStateOwners
+    let activeKeyedBlock
     const visitWithStateOwners = (node, stateOwners) => {
       const previous = activeStateOwners
       activeStateOwners = new Map([...(previous ?? []), ...stateOwners])
@@ -2034,6 +2043,58 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       activeStateOwners = previous
       return result
     }
+    const keyedEntry = (entries, node) => entries.find(entry => entry.node === node)
+    const compileKeyedBlock = (node, { parts: listParts, analysis }) => {
+      usesBehavior = true
+      usesList = true
+      const blockSlot = moduleIR.keyedBlocks.length
+      let listSource = listParts.state
+      let collection = { kind: "signal", name: listParts.state?.text }
+      if (listParts.calculation) {
+        usesBinding = true
+        listSource = descriptors.compileReactiveBinding(listParts.calculation, { setters: settersForNode(node, settersByFunction), importBindings, keyedBlock: blockSlot })
+        const exportName = ts.isCallExpression(listSource) && ts.isStringLiteral(listSource.arguments[2]) ? listSource.arguments[2].text : undefined
+        collection = { kind: "binding", ...(exportName ? { exportName } : {}) }
+      }
+      const derived = listParts.selector?.length ? descriptors.registerDerived("selector", listParts.selector, listParts.selectorStates, node) : undefined
+      const parent = activeKeyedBlock?.block
+      const rowStates = (listParts.rowStates ?? []).map(state => ({ name: state.state, setter: state.setter, owner: state.analysisOwner, ...(analysisSource(state.source) ? { source: analysisSource(state.source) } : {}) }))
+      const rowRefs = (listParts.rowRefs ?? []).map(ref => ({ name: ref.name, owner: ref.analysisOwner, ...(analysisSource(ref.source) ? { source: analysisSource(ref.source) } : {}) }))
+      const specializations = [...new Set([...(listParts.specializations ?? []), ...rowStates.map(state => state.owner), ...rowRefs.map(ref => ref.owner)].filter(value => value !== undefined).map(value => typeof value === "string" ? Number(value.slice(value.lastIndexOf(":") + 1)) : value))]
+      const block = descriptors.registerKeyedBlock({
+        ...(analysisSource(node) ? { source: analysisSource(node) } : {}),
+        ...(parent ? { parent: parent.slot } : {}),
+        children: [],
+        collection,
+        key: listParts.keyField,
+        ...(listParts.ownerField ? { ownerField: listParts.ownerField } : {}),
+        item: listParts.item,
+        ...(listParts.index ? { index: listParts.index } : {}),
+        indexed: listParts.indexed,
+        static: Boolean(listParts.static),
+        ...(derived ? { selector: derived.slot } : {}),
+        selectorStates: [...(listParts.selectorStates ?? [])],
+        specializations,
+        rowStates,
+        rowRefs
+      })
+      if (parent) parent.children.push(block.slot)
+      const previous = activeKeyedBlock
+      activeKeyedBlock = { analysis, block, parts: listParts }
+      const callback = visitWithStateOwners(listParts.callback, listParts.analysisStateOwners ?? new Map())
+      activeKeyedBlock = previous
+      const arguments_ = [
+        listSource,
+        block.key === null ? factory.createNull() : factory.createStringLiteral(block.key),
+        callback,
+        factory.createStringLiteral(block.ownerField ?? ""),
+        jsonExpression(derived?.selector ?? listParts.selector ?? [], factory),
+        block.indexed ? factory.createTrue() : factory.createFalse()
+      ]
+      if (block.selectorStates.length || block.static) arguments_.push(factory.createArrayLiteralExpression(block.selectorStates.map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
+      if (block.static) arguments_.push(factory.createTrue())
+      return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, arguments_))
+    }
     const visitor = node => {
       if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && customHookPrivateFields.has(node)) {
         const privateFields = customHookPrivateFields.get(node)
@@ -2077,7 +2138,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         return factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, factory.createStringLiteral(relativeModulePath(compiledPath(file), compiledPath(target))), node.attributes)
       }
 
-      const listEffect = ts.isCallExpression(node) ? listEffectEntries.get(node) : undefined
+      const listEffect = ts.isCallExpression(node) ? keyedEntry(activeKeyedBlock?.analysis.effects ?? [], node) : undefined
       const componentEffect = ts.isCallExpression(node) ? componentEffectEntries.get(node) : undefined
       const specializedEffect = listEffect ?? componentEffect
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (hasUseEffectImport && node.expression.text === "useEffect" || specializedEffect)) {
@@ -2195,6 +2256,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           reducers: reducersForNode(node, reducersByFunction),
           importBindings: specializedEffect?.imports ?? importBindings,
           listItem: dependencyItem,
+          keyedBlock: activeKeyedBlock?.block.slot,
           deferValues: true,
           snapshotNested: returns.cleanup,
           liveStates: customHookTimerStates
@@ -2228,7 +2290,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, initializer)
       }
 
-      if (ts.isVariableDeclaration(node) && listLocalDeclarations.has(node)) {
+      if (ts.isVariableDeclaration(node) && listLocalDeclarations.includes(node)) {
         return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, factory.createIdentifier("undefined"))
       }
 
@@ -2253,47 +2315,31 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         if (compiled !== node.expression) return factory.updateReturnStatement(node, compiled)
       }
 
-      if (ts.isJsxExpression(node) && node.expression && listConditions.has(node.expression)) {
-        const entry = listConditions.get(node.expression)
+      const listCondition = ts.isJsxExpression(node) && node.expression ? keyedEntry(activeKeyedBlock?.analysis.conditions ?? [], node.expression) : undefined
+      if (listCondition) {
+        const entry = listCondition.value
         return factory.updateJsxExpression(node, descriptors.compileListConditional({
           ...entry,
+          keyedBlock: activeKeyedBlock.block.slot,
           truthy: ts.visitNode(entry.truthy, visitor),
           falsy: ts.visitNode(entry.falsy, visitor)
         }))
       }
 
-      if (ts.isJsxExpression(node) && node.expression && listValues.has(node.expression)) {
-        return factory.updateJsxExpression(node, descriptors.compileListValue(node.expression, listValues.get(node.expression)))
+      const listValue = ts.isJsxExpression(node) && node.expression ? keyedEntry(activeKeyedBlock?.analysis.values ?? [], node.expression) : undefined
+      if (listValue) {
+        return factory.updateJsxExpression(node, descriptors.compileListValue(node.expression, { ...listValue.value, keyedBlock: activeKeyedBlock.block.slot }))
       }
 
-      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && listValues.has(node.initializer.expression)) {
-        return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, descriptors.compileListValue(node.initializer.expression, listValues.get(node.initializer.expression))))
+      const attributeListValue = ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression ? keyedEntry(activeKeyedBlock?.analysis.values ?? [], node.initializer.expression) : undefined
+      if (attributeListValue) {
+        return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, descriptors.compileListValue(node.initializer.expression, { ...attributeListValue.value, keyedBlock: activeKeyedBlock.block.slot })))
       }
 
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
-        const nestedParts = nestedLists.get(unwrapExpression(node.expression))
-        const listParts = renderedLists.get(node) ?? nestedParts
-        if (listParts) {
-          usesBehavior = true
-          usesList = true
-          let listSource = listParts.state
-          if (listParts.calculation) {
-            usesBinding = true
-            listSource = descriptors.compileReactiveBinding(listParts.calculation, { setters: settersForNode(node, settersByFunction), importBindings })
-          }
-          const selector = listParts.selector?.length ? descriptors.registerDerived("selector", listParts.selector, listParts.selectorStates, node).selector : listParts.selector ?? []
-          const arguments_ = [
-            listSource,
-            listParts.keyField === null ? factory.createNull() : factory.createStringLiteral(listParts.keyField),
-            visitWithStateOwners(listParts.callback, listParts.analysisStateOwners ?? new Map()),
-            factory.createStringLiteral(listParts.ownerField ?? ""),
-            jsonExpression(selector, factory),
-            listParts.indexed ? factory.createTrue() : factory.createFalse()
-          ]
-          if (listParts.selectorStates?.size || listParts.static) arguments_.push(factory.createArrayLiteralExpression([...(listParts.selectorStates ?? [])].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
-          if (listParts.static) arguments_.push(factory.createTrue())
-          return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, arguments_))
-        }
+        const renderedList = keyedEntry(preparedRenderedLists, node)
+        const nestedList = keyedEntry(activeKeyedBlock?.analysis.nested ?? [], unwrapExpression(node.expression))
+        if (renderedList || nestedList) return compileKeyedBlock(node, renderedList ?? nestedList)
         const conditional = conditionalParts(node.expression)
         if (conditional) {
           const compiled = compileRenderExpression(node.expression, node)
@@ -2332,7 +2378,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           setters,
           reducers: reducersForNode(node, reducersByFunction),
           functions: functionsForNode(node),
-          listItem: listEventItems.get(node),
+          listItem: activeKeyedBlock ? { item: activeKeyedBlock.parts.item, index: activeKeyedBlock.parts.index } : undefined,
+          keyedBlock: activeKeyedBlock?.block.slot,
           importBindings: new Map([...importBindings, ...packageBindings])
         })
         if (event) {
@@ -2567,10 +2614,11 @@ function insideJsxEventHandler(node, root) {
   return false
 }
 
-function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, setters, rowStates, nestedLists, componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback) {
+function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback) {
   const fail = (node, message) => {
     throw sourceNodeError(node, sourceFile, message)
   }
+  const analysis = { values: [], conditions: [], nested: [], effects: parts.effectEntries ?? [] }
   const root = parts.root
   const item = parts.item
   const nestedDiagnostic = "Nested keyed list collections must be a direct property of the parent item"
@@ -2585,7 +2633,6 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
     if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, nestedDiagnostic)
     if (ts.isJsxSpreadAttribute(node) && referencesIdentifier(node.expression, item)) fail(node, "Keyed list item spreads are not supported")
     if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.text)) {
-      listEventItems.set(node, { item, index: parts.index })
       return
     }
     if (ts.isJsxExpression(node) && node.expression) {
@@ -2610,16 +2657,28 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
           ts.setParentRecursive(callback, false)
           callback.parent = nested.callback.parent
         }
-        callback = prepareListCallback(callback, root, specialization ?? { hookDeclarations: [], effects: [] }, nested.item)
+        const effectEntries = []
+        callback = prepareListCallback(callback, root, specialization ?? { hookDeclarations: [], effects: [] }, nested.item, effectEntries)
         const specializedStates = [...(specialization?.rowStates ?? []), ...(specialization?.ordinaryStates ?? [])]
-        const nestedParts = { ...nested, root, callback, state: parts.state, nested: true, analysisStateOwners: new Map([...(parts.analysisStateOwners ?? []), ...specializedStates.map(state => [state.state, state.analysisOwner])]) }
+        const nestedParts = {
+          ...nested,
+          root,
+          callback,
+          state: parts.state,
+          nested: true,
+          effectEntries,
+          specializations: [specialization?.analysis?.slot, ...(specialization?.specializations ?? [])].filter(slot => slot !== undefined),
+          rowStates: specializedStates,
+          rowRefs: specialization?.rowRefs ?? [],
+          analysisStateOwners: new Map([...(parts.analysisStateOwners ?? []), ...specializedStates.map(state => [state.state, state.analysisOwner])])
+        }
         for (const calculation of specialization?.calculations ?? []) {
           ts.setParentRecursive(calculation, false)
           calculation.parent = callback
           validateListExpression(calculation, nested.item, nested.root, fail)
         }
-        nestedLists.set(expression, nestedParts)
-        validateKeyedList(nestedParts, sourceFile, listValues, listEventItems, listConditions, setters, specialization?.rowStates ?? [], nestedLists, componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback)
+        const nestedAnalysis = validateKeyedList(nestedParts, sourceFile, setters, specialization?.rowStates ?? [], componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback)
+        analysis.nested.push({ node: expression, parts: nestedParts, analysis: nestedAnalysis })
         return
       }
       const condition = conditionalParts(expression)
@@ -2631,7 +2690,7 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
         }
         if (!referencesIdentifier(condition.condition, item) && !(parts.index && referencesIdentifier(condition.condition, parts.index))) fail(node, "Keyed list item conditions must read the item or index")
         validateListExpression(condition.condition, item, node, fail, parts.index)
-        listConditions.set(node.expression, { ...condition, item, index: parts.index })
+        analysis.conditions.push({ node: node.expression, value: { ...condition, item, index: parts.index } })
         visit(condition.truthy)
         visit(condition.falsy)
         return
@@ -2642,7 +2701,7 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
       if (field && ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.text.toLowerCase())) fail(node, `Keyed list item ${node.parent.name.text} is not supported`)
       if (isRootKey) return
       if (field) {
-        listValues.set(node.expression, { field })
+        analysis.values.push({ node: node.expression, value: { field } })
         return
       }
       if (referencesIdentifier(expression, item) || parts.index && referencesIdentifier(expression, parts.index)) {
@@ -2651,13 +2710,14 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
         if (parts.nested && states.size) fail(node, "Nested keyed list item expressions cannot read parent state")
         validateListExpression(expression, item, node, fail, parts.index, states)
         if (ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.text.toLowerCase())) fail(node, `Keyed list item ${node.parent.name.text} is not supported`)
-        listValues.set(node.expression, { item, index: parts.index, states })
+        analysis.values.push({ node: node.expression, value: { item, index: parts.index, states } })
         return
       }
     }
     ts.forEachChild(node, visit)
   }
   visit(root)
+  return analysis
 }
 
 function directConstObjectLiteral(expression, call) {

package/framework/compiler/descriptor-session.mjs

@@ -2,7 +2,7 @@ import ts from "typescript"
 import { createComponentAnalysis } from "./analysis/component-analysis.mjs"
 import { bindingNames, isFunctionLike, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, unwrapExpression } from "./ast-helpers.mjs"
 import { generateCommandBehavior } from "./codegen/command-codegen.mjs"
-import { createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerModuleHandler } from "./ir/module-ir.mjs"
+import { createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerKeyedBlock, registerModuleHandler } from "./ir/module-ir.mjs"
 
 export function createSemanticArtifact(file) {
   return { componentAnalysis: createComponentAnalysis(file), moduleIR: createModuleIR(file) }
@@ -16,9 +16,9 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
   const listExpressions = []
   const clientModules = new Set()
 
-  function compileListExpression(read, expression, item, index, states = new Set()) {
+  function compileListExpression(read, expression, item, index, states = new Set(), keyedBlock) {
     const exportName = `listExpression${listExpressions.length}`
-    listExpressions.push({ exportName, expression, item, index, states, role: "list-expression" })
+    listExpressions.push({ exportName, expression, item, index, states, role: "list-expression", keyedBlock })
     const arguments_ = [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)]
     if (states.size) arguments_.push(factory.createArrayLiteralExpression([...states].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
     return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, arguments_)
@@ -26,7 +26,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   function compileListConditional(entry) {
     const exportName = `listExpression${listExpressions.length}`
-    listExpressions.push({ exportName, expression: entry.condition, item: entry.item, index: entry.index, role: "list-conditional" })
+    listExpressions.push({ exportName, expression: entry.condition, item: entry.item, index: entry.index, role: "list-conditional", keyedBlock: entry.keyedBlock })
     const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), entry.condition)
     const thunk = branch => factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), branch)
     return factory.createCallExpression(factory.createIdentifier("__kListConditional"), undefined, [
@@ -44,16 +44,16 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), initial)
     return entry.field
       ? factory.createCallExpression(factory.createIdentifier("__kListField"), undefined, [read, factory.createStringLiteral(entry.field)])
-      : compileListExpression(read, expression, entry.item, entry.index, entry.states)
+      : compileListExpression(read, expression, entry.item, entry.index, entry.states, entry.keyedBlock)
   }
 
-  function compileReactiveBinding(expression, { setters, importBindings = new Map() }) {
+  function compileReactiveBinding(expression, { setters, importBindings = new Map(), keyedBlock }) {
     const parts = conditionalParts(expression)
     const state = parts && directStateIdentifier(parts.condition, setters)
     if (state && isPrimitiveLiteral(parts.truthy) && isPrimitiveLiteral(parts.falsy)) {
       return factory.createCallExpression(factory.createIdentifier("__kSelect"), undefined, [state, parts.truthy, parts.falsy])
     }
-    return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, importBindings))
+    return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, importBindings, keyedBlock))
   }
 
   function compileConditional(kind, expression, truthy, falsy, setters) {
@@ -64,14 +64,14 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return factory.createCallExpression(factory.createIdentifier("__kConditional"), undefined, [factory.createStringLiteral(kind), initial, thunk(truthy), thunk(falsy), ...descriptor])
   }
 
-  function compileReactiveExpression(expression, setters, importBindings = new Map()) {
+  function compileReactiveExpression(expression, setters, importBindings = new Map(), keyedBlock) {
     const usedStates = referencedStateNames(expression, setters)
     const importedNames = referencedImportedBindings(expression, importBindings)
     const imports = [...importedNames].map(name => importBindings.get(name))
     registerClientImports(imports)
     const captures = new Set([...captureNames(expression, expression, setters)].filter(name => !importedNames.has(name)))
     const exportName = `binding${reactiveBindings.length}`
-    reactiveBindings.push({ exportName, expression, captures, states: usedStates, imports, role: "binding" })
+    reactiveBindings.push({ exportName, expression, captures, states: usedStates, imports, role: "binding", keyedBlock })
     const states = [...usedStates].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))
     const scope = [...captures].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))
     const stateNames = new Set(usedStates)
@@ -91,13 +91,13 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     ]
   }
 
-  function compileEvent(expression, { owner = "module", stateOwners = new Map(), setters, reducers, functions, listItem, importBindings }) {
+  function compileEvent(expression, { owner = "module", stateOwners = new Map(), setters, reducers, functions, listItem, keyedBlock, importBindings }) {
     if (ts.isIdentifier(expression)) expression = functions.get(expression.text)
     if (!expression || (!ts.isArrowFunction(expression) && !ts.isFunctionExpression(expression) && !ts.isFunctionDeclaration(expression))) return undefined
-    const optimized = referencedReducerDispatches(expression.body, reducers, expression).size ? undefined : compileOptimizedEvent(expression, setters, stateOwners, owner)
+    const optimized = referencedReducerDispatches(expression.body, reducers, expression).size ? undefined : compileOptimizedEvent(expression, setters, stateOwners, owner, keyedBlock)
     if (optimized) return optimized
     rejectWorkerConstructions(expression)
-    const descriptor = compileNativeCallback(expression, { setters, reducers, entries: nativeHandlers, importBindings, prefix: "handler", role: "native", listItem })
+    const descriptor = compileNativeCallback(expression, { setters, reducers, entries: nativeHandlers, importBindings, prefix: "handler", role: "native", listItem, keyedBlock })
     return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
       factory.createStringLiteral(handlerUrl), factory.createStringLiteral(descriptor.exportName), descriptor.states, descriptor.scope
     ])
@@ -107,7 +107,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return compileNativeCallback(expression, { ...options, entries: effectHandlers, prefix: "effect", role: "effect" })
   }
 
-  function compileNativeCallback(expression, { setters, reducers, entries, importBindings, prefix, role, listItem, deferValues = false, snapshotNested = false, liveStates = new Set() }) {
+  function compileNativeCallback(expression, { setters, reducers, entries, importBindings, prefix, role, listItem, keyedBlock, deferValues = false, snapshotNested = false, liveStates = new Set() }) {
     const allCaptures = nativeCaptureNames(expression, setters)
     const usedReducers = referencedReducerDispatches(expression.body, reducers, expression)
     const imports = [...referencedImportedBindings(expression, importBindings)].map(name => importBindings.get(name))
@@ -120,7 +120,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       if (reducer.contextAction) for (const state of referencedStateNames(reducer.contextAction.body, reducer.states, reducer.contextAction)) usedStates.add(state)
     }
     const exportName = `${prefix}${entries.length}`
-    entries.push({ exportName, expression, captures, deferValues, imports, listItem, liveStates, role, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested, usedStates })
+    entries.push({ exportName, expression, captures, deferValues, imports, listItem, keyedBlock, liveStates, role, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested, usedStates })
     const value = name => deferValues
       ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createIdentifier(name))
       : factory.createIdentifier(name)
@@ -136,13 +136,14 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     }
   }
 
-  function compileOptimizedEvent(expression, setters, stateOwners, owner) {
+  function compileOptimizedEvent(expression, setters, stateOwners, owner, keyedBlock) {
     const statements = ts.isBlock(expression.body) ? expression.body.statements : [factory.createExpressionStatement(expression.body)]
     const commands = statements.map(statement => ts.isExpressionStatement(statement) ? compileEventCommand(statement.expression, setters) : undefined)
     if (!commands.length || commands.some(command => !command)) return undefined
     const original = ts.getOriginalNode(expression)
     const source = original.pos >= 0 && original.end >= 0 ? { file: sourceName(original.getSourceFile()), start: original.getStart(), end: original.end } : undefined
     const handler = registerCommandHandler(moduleIR, commands.map(command => ({ ...command, owner: stateOwners.get(command.state) ?? owner })), source, owner)
+    if (keyedBlock !== undefined) handler.keyedBlock = keyedBlock
     return generateCommandBehavior(moduleIR, handler, factory)
   }
 
@@ -155,6 +156,10 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return registerDerived(moduleIR, { kind, [kind]: normalized, states: [...states], ...(source(node) ? { source: source(node) } : {}) })
   }
 
+  function registerKeyedBlockResult(descriptor) {
+    return registerKeyedBlock(moduleIR, descriptor)
+  }
+
   function finalize() {
     const callbacks = [...nativeHandlers, ...effectHandlers]
     for (const entry of callbacks) {
@@ -162,6 +167,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       const setters = Map.groupBy(entry.setters, ([, state]) => state)
       registerModuleHandler(moduleIR, {
         role: entry.role,
+        ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
         exportName: entry.exportName,
         async: Boolean(entry.expression.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)),
         generator: Boolean(entry.expression.asteriskToken),
@@ -184,6 +190,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     }
     for (const entry of reactiveBindings) registerBinding(moduleIR, {
       role: entry.role,
+      ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
       exportName: entry.exportName,
       parameters: ["__k"],
       states: [...entry.states],
@@ -194,6 +201,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     })
     for (const entry of listExpressions) registerBinding(moduleIR, {
       role: entry.role,
+      ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
       exportName: entry.exportName,
       parameters: [entry.item, entry.index ?? "__kIndex", "__k"],
       states: [...(entry.states ?? [])],
@@ -215,7 +223,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   const importRecord = entry => ({ target: entry.target, kind: entry.kind, local: entry.local, ...(entry.imported ? { imported: entry.imported } : {}), package: Boolean(entry.package) })
 
-  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult }
+  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult, registerKeyedBlock: registerKeyedBlockResult }
 }
 
 function directStateIdentifier(expression, setters) {

package/framework/compiler/ir/module-ir.mjs

@@ -1,5 +1,5 @@
 export function createModuleIR(file) {
-  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], imports: [], clientModules: [] }
+  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], keyedBlocks: [], imports: [], clientModules: [] }
 }
 
 export function registerCommandHandler(moduleIR, commands, source, scope = "module") {
@@ -39,3 +39,9 @@ export function registerDerived(moduleIR, descriptor) {
   moduleIR.derived.push(derived)
   return derived
 }
+
+export function registerKeyedBlock(moduleIR, descriptor) {
+  const block = { slot: moduleIR.keyedBlocks.length, ...descriptor }
+  moduleIR.keyedBlocks.push(block)
+  return block
+}

package/framework/core.d.ts

@@ -80,6 +80,57 @@ export type MetadataContext<Props = Record<string, unknown>> = {
   props: Props
 }
 
+export type ListSourceDescriptor =
+  | { state: string; truthy?: unknown; falsy?: unknown }
+  | {
+      module: string
+      handler: string
+      states: Record<string, string>
+      scope: Record<string, unknown>
+      scopeStates: Record<string, string>
+      scopeBindings: Record<string, unknown>
+    }
+
+export type ChildListDescriptor = {
+  id: string
+  field: string
+  key: string | null
+  selector?: unknown[]
+}
+
+export type ListDescriptor = {
+  id: string
+  state: string
+  key: string | null
+  keys: Array<string | number>
+  svg?: true
+  static?: true
+  source?: ListSourceDescriptor
+  ownerField?: string
+  selector?: unknown[]
+  selectorStates?: Record<string, string>
+  indexed?: true
+  reducer?: true
+  children?: ChildListDescriptor[]
+  mount?: true
+  nested?: true
+  effects?: true
+  conditions?: true
+  conditionHandlers?: true
+  textRanges?: true
+  attributes?: true
+  events?: true
+  expressions?: true
+  expressionAttributes?: true
+  expressionStates?: string[]
+  rowStates?: Array<{ id: string; initialValue: unknown }>
+  rowConditions?: string[]
+  rowRefs?: string[]
+  fastRelease?: true
+  seed?: Record<string, string | number | boolean | null>
+  valueSeed?: Record<string, string | number | boolean | null>
+}
+
 export function renderPage<Props = Record<string, never>>(
   component: (props: Props) => unknown | Promise<unknown>,
   metadata?: PageMetadata,
@@ -117,6 +168,6 @@ export function renderPage<Props = Record<string, never>>(
       scopeBindings?: Record<string, unknown>
     }>
     conditions: Array<Record<string, unknown>>
-    lists: Array<Record<string, unknown>>
+    lists: ListDescriptor[]
   }
 }>

package/package.json

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