@kudzujs/core 0.8.26 → 0.8.28

package/MIGRATION_ROADMAP.md

@@ -2,6 +2,8 @@
 
 This document is the source of truth for Kudzu's product direction, architecture invariants, and future development order. Read it before extending React-shaped syntax or browser capabilities.
 
+The executable post-`0.8.28` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
+
 [`GOAL_A.md`](./GOAL_A.md) and [`GOAL_B.md`](./GOAL_B.md) are completed capability-validation records. Their commerce and realtime dashboard fixtures prove general lifecycle, navigation, async-workflow, and Worker capabilities; they are not separate product verticals or future priority lists.
 
 ## North Star
@@ -262,6 +264,18 @@ This queue orders the next investigations by general migration value. Start only
 - The standard suite counts exact route-entry transforms across repeated, distinct, and new-build sources and protects the safe keyed bulk-mount guard plus its per-root fallback.
 - Goal B records which build, output, keyed, Worker, integration, and heap evidence exists; no new optimization is authorized without another reproduced material loss.
 
+### Characterized In 0.8.27
+
+- A reduced E2B Dashboard terminal fixture establishes callback-shared mutable browser resources, asynchronous generation invalidation, and BFCache retain/resume/discard behavior as a concrete Goal C boundary.
+- Unsupported page-level mutable value refs fail during source analysis with a source location and the existing effect-owned animation-frame exception; no resource API or runtime is added.
+- The large-application and AI-native execution plan orders symbol resolution, semantic operations, project/module analysis, IR authority, application foundations, ecosystem compatibility, AI tooling, and scale validation before broad feature work.
+
+### Completed In 0.8.28
+
+- A source-local binding index assigns deterministic lexical identities to locals, parameters, imports, captures, known globals, and unresolved references after normalization.
+- Reactive binding capture/import discovery and lowering distinguish outer application values from same-named browser globals and nested callback parameters without changing source syntax or adding browser bytes.
+- Synthesized keyed expressions retain the existing fail-safe lowering path; native handler, effect, and remaining descriptor consumers stay ordered behind the next symbol-aware compiler patch.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

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.26 - Goal B benchmark hardening.** Commerce comparisons now require byte-identical output by default, and the standard suite protects exact route-entry transform reuse plus safe keyed bulk-mount selection. Read the [release notes](./RELEASES.md#0826---goal-b-benchmark-hardening), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.26), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.28 - Source-local binding index.** The first large-application compiler foundation classifies locals, parameters, imports, captures, globals, and unresolved references by lexical identity, then uses that index for reactive binding capture/import discovery and lowering. Read the [release notes](./RELEASES.md#0828---source-local-binding-index), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.28), 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,65 @@
 # Kudzu Releases
 
+## 0.8.28 - Source-local binding index
+
+Kudzu 0.8.28 completes the first large-application compiler foundation by resolving source-local lexical bindings before descriptor discovery and lowering.
+
+### Changed in 0.8.28
+
+- A source-local binding index classifies value references as local declarations, parameters, imports, outer captures, known globals, or unresolved names with deterministic slots and source ranges.
+- The index models module, function parameter/body, block, loop, catch, switch, class, computed method, namespace, import, destructuring, `var`, `let`, and `const` scopes without adding a TypeScript Program or cross-module graph.
+- Reactive binding capture/import discovery uses lexical identity, so component locals named `document`, `location`, `history`, `navigator`, or `console` no longer become browser globals and shadowed callback parameters no longer become imports.
+- Reactive binding lowering rewrites only the indexed occurrences that resolve to state or capture bindings. Same-named nested parameters remain local.
+- Synthesized keyed expressions use the existing fail-safe path unless the complete expression can be indexed, preserving keyed row state and identity behavior.
+
+### Performance And Architecture
+
+- A focused 1,000-reference guard verifies one index construction followed by direct indexed lookups and reports construction/lookup timing without making a cross-machine performance claim.
+- The index is constructed after ordered normalization and parent repair, once per compiled source. It adds no public API, browser runtime, client metadata, or JavaScript bytes.
+- Native handler, effect, and remaining descriptor discovery still use the existing analysis path; symbol-aware migration of those consumers remains the next P0.2 scope.
+
+### Validation
+
+- `npm run check`, `npm run test:package`, and all 185 tests pass.
+- Browser integration verifies shadowed browser-global names through initial HTML and reactive evaluator updates.
+- React, Router, Zustand, keyed row, nested list, effect, Worker, navigation, and static-route zero-JavaScript behavior remain covered.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.28
+```
+
+## 0.8.27 - Large-application compiler roadmap
+
+Kudzu 0.8.27 records the evidence-backed path from the current static-first compiler to large production applications without adding a React runtime, generic client framework, or speculative resource API.
+
+### Changed in 0.8.27
+
+- A reduced fixture from E2B Dashboard preserves a callback-shared terminal handle, asynchronous generation token, BFCache retention, resume, and discard cleanup as the first concrete Goal C resource-ownership boundary.
+- Unsupported page-level mutable value refs now fail during source analysis with the source location and the existing effect-owned animation-frame exception instead of reaching the build-time DOM-ref runtime error.
+- Goal C records independent WebSocket/SSE, shared request, and optimistic transaction candidates while explicitly withholding store, resource, query, cache, Provider, subscription, and scheduler APIs.
+- The new large-application and AI-native execution plan audits the current compiler, IR, runtime, navigation, package, build, fixture, and benchmark boundaries and orders the next twelve independently verifiable PRs.
+- The next implementation is fixed as a source-local binding index followed by symbol-aware descriptor discovery; ecosystem features cannot skip those semantic dependencies.
+
+### Architecture Boundary
+
+- Existing ComponentAnalysis, ModuleIR, RouteIR, CapabilityIR, complete HTML, direct DOM ownership, native navigation, and capability runtimes remain the incremental foundation.
+- The plan generalizes symbol identity, semantic state operations, component/module dataflow, resource/range ownership, artifact references, code splitting, diagnostics, migration analysis, and application-scale evidence without introducing a browser component tree.
+- React ecosystem support is classified as Native, Compiled, Migrated, Adapter, Partial, or Unsupported so package-specific knowledge can move behind a compatibility boundary instead of accumulating in the core compiler.
+
+### Validation
+
+- `npm run check`, `npm run test:package`, and all 176 tests pass.
+- The E2B fixture remains an expected failure at its proven source boundary; no browser resource runtime or public API is emitted.
+- Static-route zero JavaScript, existing animation-frame support, keyed-row diagnostics, setter-child diagnostics, and all current browser ownership behavior remain covered.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.27
+```
+
 ## 0.8.26 - Goal B benchmark hardening
 
 Kudzu 0.8.26 makes the retained Goal B optimizations reproducible and directly regression-tested without changing generated runtime behavior or authoring support.

package/docs/next-architecture/README.md

@@ -11,6 +11,8 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 | 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 |
 
+The active post-`0.8.28` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). It orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+
 ## Required Invariants
 
 - Every route remains a complete static HTML document.
@@ -24,16 +26,18 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 ## Reading Order
 
 1. [`compiler-current-architecture.md`](./compiler-current-architecture.md): exact current responsibilities and data flow.
-2. [`goal-a-compiler-foundation.md`](./goal-a-compiler-foundation.md): approved extraction and generator work.
-3. [`versioning.md`](./versioning.md): planned patch sequence and completion rules.
-4. [`performance-gates.md`](./performance-gates.md): output, build, and browser gates.
-5. [`goal-b-optimization-benchmarks.md`](./goal-b-optimization-benchmarks.md): active measurements, retained optimizations, and continuation rules.
-6. [`goal-c-state-resource-research.md`](./goal-c-state-resource-research.md): research boundary only.
-7. [`goal-d-routing-compatibility-decisions.md`](./goal-d-routing-compatibility-decisions.md): routing and islands decisions.
+2. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md): active direction, priorities, PR queue, and completion evidence.
+3. [`goal-a-compiler-foundation.md`](./goal-a-compiler-foundation.md): completed extraction and generator foundation.
+4. [`versioning.md`](./versioning.md): completed patch sequence and future sequencing rules.
+5. [`performance-gates.md`](./performance-gates.md): output, build, and browser gates.
+6. [`goal-b-optimization-benchmarks.md`](./goal-b-optimization-benchmarks.md): active measurements, retained optimizations, and continuation rules.
+7. [`goal-c-state-resource-research.md`](./goal-c-state-resource-research.md): research boundary only.
+8. [`goal-d-routing-compatibility-decisions.md`](./goal-d-routing-compatibility-decisions.md): routing and islands decisions.
 
 ## Resume Checklist
 
 - [ ] Read [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) and this directory before planning migration work.
+- [ ] Follow the PR dependency order in [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md); update it before broadening or reordering a patch.
 - [ ] Confirm `package.json` still reports the actual current version; never infer release status from this plan.
 - [ ] Inspect the worktree and preserve unrelated or uncommitted changes.
 - [ ] Start later architecture work only by an explicit decision from the completed Goal A baseline.

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.26` architecture built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.8.28` architecture built on the completed `0.8.23` 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
 
@@ -12,6 +12,7 @@ This maps the current `0.8.26` architecture built on the completed `0.8.23` Goal
 | Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every structural change. 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. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
+| Source-local binding index | [`framework/compiler/analysis/binding-index.mjs`](../../framework/compiler/analysis/binding-index.mjs) | After normalization, assigns deterministic lexical slots and classifies local, parameter, import, capture, global, and unresolved references. Reactive binding discovery/lowering consumes complete indexed expressions; synthesized expressions retain the existing fallback. |
 | 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/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, keyed, and effect ownership results. |
 | 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. |
@@ -38,7 +39,9 @@ This maps the current `0.8.26` architecture built on the completed `0.8.23` Goal
 src/pages entries + config
   -> project discovery and reachable relative graph
   -> compileSource()
-       -> ordered normalization and main transformer semantic analysis
+       -> ordered normalization and parent repair
+       -> source-local binding index
+       -> main transformer semantic analysis
        -> TypeScript transpilation
        -> JSON-safe build module, ModuleIR, handler module, and imported assets
   -> build orchestration writes .kudzu executable and handler modules
@@ -64,6 +67,7 @@ The browser consumes static HTML first. State seeds and descriptors in that HTML
 - `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.
 - Source reachability and source compilation share one module because both consume the same normalization and import graph contracts.
+- Native handler, effect, state/setter, list, Router, React, and Zustand discovery still contains name-based analysis. The binding index is intentionally adopted one consumer family at a time; P0.2 moves the next descriptor consumers without changing cross-module semantics.
 
 These are future simplification opportunities, not incomplete Goal A contracts. Goal A changed no source support, browser output semantics, or browser architecture.
 

package/docs/next-architecture/goal-c-state-resource-research.md

@@ -36,6 +36,40 @@ Before any proposal, provide:
 - output and ownership costs;
 - an explanation of why existing async build rendering, state/effects, layout ownership, native platform storage, or effect-owned resources are insufficient.
 
+## First Application Survey
+
+The first GitHub survey used active licensed React/TypeScript applications rather than library demos. It found four distinct pressure families:
+
+| Application evidence | Ownership pressure | Research disposition |
+|---|---|---|
+| [E2B Dashboard terminal](https://github.com/e2b-dev/dashboard/blob/97164c9cbc8ced05b9039415318550f4e4df3874/src/features/dashboard/terminal/dashboard-terminal.tsx) | Mutable remote handle and generation tokens survive callbacks; BFCache entry retains the handle, real discard closes it, and restore resumes it | First reduced fixture because it is the smallest precise lifetime |
+| [Mattermost WebSocket client](https://github.com/mattermost/mattermost/blob/53373e3752c6e8d7979b787f342fea4c56e68472/webapp/platform/client/src/websocket.ts) and [Twenty SSE provider](https://github.com/twentyhq/twenty/blob/cd288d84470503ba897c0823a9d98701fa9986ab/packages/twenty-front/src/modules/sse-db-event/components/SSEProvider.tsx) | One document/layout transport has many independently mounted route subscribers plus reconnect and replay state | Strong cross-owner subscription research; too broad for the first fixture |
+| [Actual Budget queries](https://github.com/actualbudget/actual/blob/87e33e49eb4d666c33e0c0f172faf340d1b7aa0a/packages/desktop-client/src/payees/queries.ts) and [Plane workspace wrapper](https://github.com/makeplane/plane/blob/31853ab2b8b7810c59dc30d22e52c8f4b5a71a47/apps/web/core/layouts/auth-layout/workspace-wrapper.tsx) | Shared keyed request results outlive route consumers and are invalidated by external events or owner changes | Candidate for keyed layout/document ownership, not authorization for a query API |
+| [InstantDB optimistic update](https://github.com/instantdb/instant/blob/30561b01ea850514dd4e0270bdd6ff3ed159bbb1/client/www/lib/auth.ts) and [Raven reaction update](https://github.com/The-Commit-Company/raven/blob/a29a274466b7a060754839b3c8e29bbee012a61d/packages/lib/hooks/useReactToMessage.ts) | Multiple consumers observe one optimistic snapshot that must commit or roll back atomically | Two independent examples of shared optimistic transactions; still research only |
+
+### E2B Reduced Fixture
+
+The repository-owned fixture at `test/fixtures/goal-c-e2b-terminal` preserves the relevant conventional React shape without E2B's UI, SDK, or `useEffectEvent` dependency:
+
+- one `null`-initialized remote handle ref;
+- one numeric generation ref invalidating late asynchronous opens;
+- `pagehide.persisted` retaining the handle for BFCache;
+- non-persisted `pagehide` and effect cleanup closing it;
+- `pageshow.persisted` resuming the retained handle;
+- one unrelated static sibling route.
+
+The build fails before BFCache behavior can be evaluated:
+
+```text
+src/pages/index.tsx:7:25 Mutable value useRef() is unsupported except for an effect-owned useRef(0) animation-frame handle; otherwise keep resource-private mutable values inside the owning effect
+```
+
+The failure is triggered by the ordinary `useRef(0)` generation token during source analysis. Existing animation-frame specialization cannot safely cover this shape: the generation token has different writes and callback ownership, while the remote handle is a browser-only non-serializable value rather than a DOM ref. Supporting only the token would expose incorrect DOM-ref semantics for the handle.
+
+The remaining question before any state/resource API discussion is whether independent fixtures justify a narrow specialization for callback-shared effect resources with document and BFCache ownership. Until then, the source-located diagnostic preserves the current boundary.
+
+An effect-local rewrite is a useful control, but requiring applications to restructure ordinary callback-shared refs is not automatically an acceptable migration solution. The fixture remains an expected failure until research answers that boundary.
+
 ## Decision Boundary
 
 Research may produce notes, fixtures, measurements, or a narrow compiler-specialization proposal. It must not publish `createStore`, `resource`, `query`, cache, Provider, subscription, or scheduler APIs. A public API requires separate approval after at least two independent migration fixtures establish the same semantics and after zero-cost exclusion is demonstrated.

package/docs/next-architecture/large-application-ai-native-roadmap.md

@@ -0,0 +1,457 @@
+# Large Application And AI-Native Development Plan
+
+## Status
+
+Active execution plan after `0.8.28`. This document turns the current compiler audit into an ordered implementation program. It does not mark any planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
+
+[`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains authoritative for product invariants and fixture-driven feature selection. This plan is authoritative for the order and completion evidence of compiler generalization, large-application foundations, compatibility boundaries, AI tooling, and scale validation. If implementation evidence changes a boundary, update this document before broadening a patch.
+
+## Product Outcome
+
+Kudzu must support ordinary React-shaped TypeScript and TSX from small static sites through production SaaS, dashboards, CRUD, commerce, authenticated applications, realtime collaboration, data-heavy interfaces, and large module graphs. The browser should receive complete HTML and only the capabilities required by each route or application lifetime.
+
+The differentiating KPI is `cost per successful task`, not source line count alone. A successful task includes build, browser behavior, accessibility, output, and ownership checks. Track input/output/reasoning tokens, files read and modified, tool calls, compiler attempts, failed attempts, correction cycles, completion time, source retention, and final client bytes.
+
+The governing principle is:
+
+> Write what AI already knows. Compile away what AI should not need to reason about.
+
+## Audited Baseline
+
+The current implementation already provides:
+
+- complete route HTML and zero JavaScript for static routes;
+- synchronous logical state with direct DOM commits;
+- route, layout, conditional, keyed, effect, ref, and Worker ownership;
+- stable keyed row identity with nested lists, state, refs, effects, and SVG;
+- stale effect-invocation isolation and explicit cleanup;
+- narrow React, React Router, and Zustand-shaped normalization;
+- JSON-safe ComponentAnalysis, ModuleIR, RouteIR v1, and CapabilityIR v1;
+- no-write source compilation and capability-specific runtime emission;
+- source-located fail-closed diagnostics and broad reduced-fixture coverage.
+
+The current limiting architecture is observable in these files:
+
+| Concern | Current owner | Limitation to remove |
+|---|---|---|
+| Project graph | `framework/compiler/source-graph.mjs`, `framework/build.mjs` | Global root, repeated parsing, narrow export resolution, no incremental project session |
+| Normalization | `framework/compiler/source-compiler.mjs`, focused passes | Pass order and package ownership are implicit; semantically equal source often follows different shape-specific paths |
+| Component/state analysis | `framework/compiler/source-compiler.mjs`, `analysis/component-analysis.mjs` | AST identity, identifier text, source offsets, and caller-side AST specialization remain central |
+| Handler/binding analysis | `framework/compiler/descriptor-session.mjs`, `handler-lowering.mjs` | Capture/import/state discovery is name-based and arbitrary handlers become code before IR finalization |
+| Effect/resource analysis | `effect-analysis.mjs`, resource-specific passes | Selected browser APIs have exact-shape ownership checks; there is no package-neutral resource model |
+| Lists/ranges | `source-compiler.mjs`, `list-runtime.js` | Strong keyed ownership, but syntax recognition and runtime branches are list-specific and not a general range/window primitive |
+| ModuleIR | `compiler/ir/module-ir.mjs` | Numeric slots, names, export strings, and formatted owner strings coexist; several sections are descriptive rather than authoritative inputs |
+| RouteIR/CapabilityIR | `route-capability-planner.mjs` | Validation is shallow and capability selection is site-wide across interactive routes |
+| Build/codegen | `framework/build.mjs`, runtime generators | Full destructive builds, serialized-string handler reachability, source-text runtime surgery, no route chunk/CSS closure report |
+| Browser lifetime | `native-runtime.js`, `effect-runtime.js`, `navigation-runtime.js` | Effects invalidate stale work, but pending native handlers can write after route unmount |
+| Compatibility | React/Router/Zustand passes plus core branches | Package-specific knowledge is not contained behind one adapter boundary |
+| AI interface | CLI and string diagnostics | No stable diagnostic codes, semantic index, explain, fix, or migration analysis output |
+
+## Architecture Direction
+
+```text
+ProjectSession
+  -> parsed module and package graph
+  -> compatibility adapter registry
+  -> normalized modules with stable declaration/site identities
+  -> binding and symbol resolution
+  -> source semantic analysis
+       component and prop edges
+       state, derived, event, and operation edges
+       effect and resource ownership
+       collection and range ownership
+  -> strengthened existing ModuleIR
+  -> build-time render instantiation
+  -> RouteBuildRecord with RouteIR and artifact edges
+  -> per-route capability signature and chunk closure
+  -> HTML, CSS, and capability-specific ESM
+```
+
+This is an incremental evolution of the current repository:
+
+- Keep ComponentAnalysis and ModuleIR; make their references stable and their records authoritative.
+- Keep `renderPage()` for build-known execution and concrete route ownership IDs; stop using it to rediscover source semantics already present in ModuleIR.
+- Keep RouteIR and CapabilityIR; deepen validation and replace parallel route facts with one RouteBuildRecord.
+- Keep existing browser runtimes; extract package-neutral semantic primitives only after fixtures prove repeated ownership needs.
+- Do not introduce a general JavaScript bytecode VM or model the complete TypeScript language in a new IR.
+
+## Required Invariants
+
+- Static routes remain zero JavaScript.
+- Interactive routes add no capability unrelated to their source and route lifetime.
+- Complete HTML remains the initial document.
+- Native navigation remains the fallback and default.
+- React and ecosystem package source may be accepted, normalized, migrated, or adapted without executing React.
+- Package-specific knowledge must not leak beyond the compatibility boundary into generic ownership, dataflow, IR, or browser runtime code.
+- New semantic support starts from a real or reduced failing application fixture.
+- Every patch is independently reviewable, fail-closed, and measured against representative output.
+- A compiler refactor must preserve accepted source, diagnostics, RouteIR, HTML, assets, and browser ownership unless its scope explicitly changes one contract.
+
+## Preserve, Refactor, Avoid
+
+### Preserve
+
+- Build-known execution and complete static output.
+- Direct DOM ownership and synchronous logical state.
+- Route/layout/key-path lifetime semantics.
+- Keyed identity and exact state/effect/ref release.
+- Effect invalidation and cleanup.
+- JSON-safe, versioned stage boundaries.
+- Source-located diagnostics.
+- Rendered Worker exclusion and content hashing.
+- Capability-specific output with no React runtime.
+
+### Refactor
+
+- Identifier text into resolved SymbolRef records.
+- AST identity and `pos:end` keys into stable source-local declaration/site IDs.
+- Exact setter syntax into semantic value and state-operation analysis.
+- Caller-side component AST copying into a component/prop/callback graph.
+- Manual export discovery into a project module-symbol graph.
+- Primitive-only dependencies into property-path and derived dependencies.
+- Resource-specific ownership passes into a package-neutral ResourceIR when evidence permits.
+- Serialized handler URL searches into explicit artifact references.
+- Site-wide capability unions into route capability signatures.
+- Full destructive development builds into project-session invalidation and atomic output.
+- String-only diagnostics into structured diagnostics suitable for machines and AI agents.
+
+### Avoid
+
+- React runtime fallback, hydration, islands, or a browser component tree.
+- Public Kudzu-specific router, query, store, form, or scheduler APIs before migration evidence.
+- One core pass per ecosystem package.
+- A generic rerender engine or general callback registry.
+- Incomplete dynamic import support.
+- Speculative cache, virtualization, portal, stream, or resource runtimes.
+- File splitting that does not reduce semantic coupling.
+
+## Priority Program
+
+### Execution Status
+
+- [x] P0.1 Source-local binding index is complete in `0.8.28`. Reactive binding capture/import discovery and lowering use the index only when the complete expression is indexed; synthesized keyed expressions retain the existing fail-safe path. Focused scope tests, a 1,000-reference guard, browser integration, all 185 tests, and packed-package smoke pass.
+- [ ] P0.2 Symbol-aware descriptor discovery is next. It must migrate native handler, effect, and remaining binding discovery without broadening into cross-module symbols, semantic StateWrite IR, or ecosystem features.
+
+### P0: Semantic Correctness And Compiler Foundation
+
+P0 creates the semantic base required by every later large-application capability. Do not begin broad ecosystem or application features before the relevant P0 dependencies are complete.
+
+| Order | Objective | Dependency | Completion evidence |
+|---|---|---|---|
+| P0.1 | Source-local binding index | None | Local, parameter, import, capture, global, and unresolved references are classified consistently |
+| P0.2 | Descriptor consumers use SymbolRef | P0.1 | Handler/effect/binding capture and import discovery no longer depends only on text names |
+| P0.3 | Graph diagnostics | P0.1 | Relative dynamic imports and unresolved runtime edges fail at the source location |
+| P0.4 | Async native handler ownership | None | Pending handlers cannot write after route or DOM ownership is released |
+| P0.5 | Atomic collision-safe build | None | Failed builds preserve prior output and public files cannot overwrite generated artifacts |
+| P0.6 | Explicit ProjectSession | P0.1 | Root and caches are build-scoped; two projects can compile safely in one process |
+| P0.7 | Parsed module/export cache | P0.6 | Shared modules are parsed and summarized once per build |
+| P0.8 | Stable ModuleSymbol and SiteId | P0.6-P0.7 | Imports, re-exports, aliases, owners, and call sites use stable identities outside a pass |
+| P0.9 | Semantic state-operation analysis | P0.1, P0.8 | Equivalent setter/helper forms lower to the same state operation |
+| P0.10 | ModuleIR reference unification | P0.8-P0.9 | Signals, bindings, effects, keyed blocks, handlers, and owners use validated slots/symbols |
+| P0.11 | Explicit route artifact graph | P0.10 | Handler/Worker/CSS/chunk retention uses structural references, not serialized string searches |
+| P0.12 | Deep RouteIR and CapabilityIR validation | P0.10-P0.11 | Invalid state, effect, binding, list, ownership, and artifact references fail before codegen |
+
+### P1: Large Application Foundations
+
+| Objective | Required result |
+|---|---|
+| Cross-module component and prop dataflow | Deep composition, callbacks, setters, refs, context, and children retain semantic links without repeated AST inlining |
+| Property-level derived dependencies | Object state can expose path-level dependencies without splitting application state into artificial primitives |
+| Package-neutral shared state and actions | Existing Zustand support lowers through generic signal/action records; Redux-shaped research has a reusable target |
+| Resource ownership | WebSocket, SSE, subscriptions, timers, observers, Workers, and imperative SDKs can share acquire/owner/dependency/cleanup semantics |
+| Browser-only package modules | Native JS packages may be bundled only into effect/handler/resource chunks without build-time execution |
+| Range ownership | Conditional, keyed, overlay, and future virtualized DOM ranges share release and identity primitives where semantics match |
+| Route/layout graph | Nested persistent layouts and route lifetimes remain complete-document based and recoverable through native navigation |
+| Route capability and chunk closure | Every route reports exact runtime, handler, package, Worker, and shared chunk edges |
+| Route/layout CSS closure | Unrelated feature CSS is absent from a route unless configured global |
+| Incremental development build | A source change recompiles and rerenders only affected modules/routes while preserving full reload correctness |
+| Source-scale benchmark | At least 500 reachable modules, 50,000 TS/TSX lines, 50 routes, phase timings, and peak RSS |
+
+### P2: Compatibility And Migration
+
+- Add an internal compatibility adapter registry.
+- Consolidate React compatibility ownership behind one adapter contract.
+- Register React Router ownership without changing native navigation semantics.
+- Move Zustand-specific logic out of generic core, handler, and state paths onto package-neutral shared-state/action IR.
+- Characterize Redux/RTK, TanStack Query, React Hook Form, Zod, Radix/Headless UI/MUI, CSS-in-JS, animation, chart, drag/drop, virtualization, auth, REST, and GraphQL against real application fixtures.
+- Prefer native packages and Web APIs, then compilation, deterministic migration, adapters, partial support, or explicit unsupported status in that order.
+- Publish no public adapter API until an external adapter requires independent versioning.
+
+### P3: AI Compiler Interface
+
+- `kudzu check --json` with stable code, stage, file/range, symbols, module/component/ownership paths, compatibility status, suggestions, and safe fixes.
+- `kudzu explain [route|symbol] --json` from the semantic and artifact graphs.
+- `kudzu fix` only for deterministic changes whose preconditions the compiler proves.
+- `kudzu migrate --analyze` for module, component, route, package, state, effect, resource, and blocker inventory.
+- Migration readiness percentages must be calculated from actual classified modules/use sites, never estimated.
+
+### P4: Production And Scale Validation
+
+- Maintain Tier 1 reduced fixtures, Tier 2 complete small/medium apps, Tier 3 large production slices, and Tier 4 whole existing React applications.
+- Require Chrome, Firefox, and WebKit journeys for production candidates.
+- Add source maps, accessibility automation, keyboard journeys, security checks, output manifests, long-navigation heap tests, and deployment/cache guidance.
+- Compare Kudzu and React + Vite first with the same agent, model, tools, task, and acceptance checks; expand only after the protocol is stable.
+- Report median and range for tokens, cost, file reads, tool calls, builds, failures, completion time, source retention, output bytes, and accepted behavior.
+
+## PR Execution Queue
+
+### PR 1: Source-Local Binding Index
+
+**Objective:** establish one correct reference classifier before further compiler generalization.
+
+**Current problem:** `descriptor-session.mjs`, migration passes, and source analysis use identifier text plus separate shadow walkers. A local named like a browser global or import can be classified incorrectly, and later cross-module work has no stable foundation.
+
+**Files:**
+
+- Add `framework/compiler/analysis/binding-index.mjs`.
+- Add `test/binding-index.test.mjs`.
+- Update `framework/compiler/ast-helpers.mjs` only for shared scope primitives proven necessary.
+- Update a narrow capture/import consumer in `framework/compiler/descriptor-session.mjs`.
+
+**Internal contract:**
+
+```text
+resolveReference(identifier)
+  -> local declaration
+  -> parameter
+  -> import
+  -> outer lexical capture
+  -> known global
+  -> unresolved
+```
+
+Every result carries a stable source-local binding slot, debug name, declaration range when present, and reference range. AST nodes remain source-session-local and do not enter JSON-safe IR.
+
+**Not in scope:**
+
+- Cross-module TypeScript Program.
+- Component graph changes.
+- New accepted React syntax.
+- Handler operation IR.
+- Public API or runtime changes.
+
+**Tests:**
+
+- Shadowed `document`, `location`, `history`, `navigator`, and `console`.
+- Imported name shadowed by callback parameter or local declaration.
+- Outer component capture versus callback-local binding.
+- State/setter name collision across owners.
+- Existing Router, React, binding, native handler, and effect fixtures.
+
+**Performance check:** create a focused synthetic source with at least 1,000 references and record index construction and lookup time. The purpose is a regression guard, not an optimization claim.
+
+**Done condition:** capture/import classification uses the binding index for the selected consumer, all existing tests pass, representative generated artifacts remain byte-identical except for an explicitly corrected shadowing case, and no browser bytes are added.
+
+### PR 2: Symbol-Aware Descriptor Discovery
+
+**Objective:** move native handler, effect, and binding capture/import discovery onto the P0.1 binding index.
+
+**Files:** `descriptor-session.mjs`, `handler-lowering.mjs`, `effect-analysis.mjs`, compiler tests.
+
+**Tests:** shadowed imports/globals in native handlers, effects, bindings, and list evaluators; JSON-safe HandlerIR/BindingIR round trips.
+
+**Done condition:** these analyses no longer decide identity from identifier text alone; output and diagnostics remain equivalent for existing accepted source.
+
+### PR 3: Graph Failure Diagnostics
+
+**Objective:** fail early for runtime graph edges the compiler cannot emit safely.
+
+**Files:** `source-graph.mjs`, `source-compiler.mjs`; add page/helper/re-export invalid fixtures.
+
+**Done condition:** unresolved relative imports/re-exports and ordinary dynamic imports report importer, source range, and specifier; no generated `.kudzu` path is the primary diagnostic.
+
+### PR 4: Async Native Handler Invalidation
+
+**Objective:** prevent late async event work from mutating released route/keyed ownership.
+
+**Files:** `native-runtime.js`, navigation/list ownership integration, browser test fixture.
+
+**Performance check:** compare synchronous event dispatch before and after; no material regression.
+
+**Done condition:** a handler resolving after enhanced navigation or row removal cannot recreate or mutate released state, refs, or DOM.
+
+### PR 5: Atomic And Collision-Safe Output
+
+**Objective:** make production builds safe before scaling the build graph.
+
+**Files:** `build.mjs`, build integration tests.
+
+**Tests:** public collisions with route HTML, core runtime, handler entry, chunk, Worker namespace, source CSS, and configured CSS; failed build preserves prior `dist`.
+
+**Done condition:** output is staged, validated, and atomically promoted; public content cannot silently replace generated artifacts.
+
+### PR 6: ProjectSession And Explicit Root
+
+**Objective:** remove import-time project globals and establish build-scoped graph/cache ownership.
+
+**Files:** add `compiler/project-session.mjs`; update build, source graph, source compiler, and tests.
+
+**Done condition:** two independent roots compile in one process, current CLI behavior and artifacts remain unchanged, and source caches cannot leak between projects.
+
+### PR 7: Parsed Module And Export Summary Cache
+
+**Objective:** make work proportional to unique modules instead of importer edges.
+
+**Dependency:** PR 6.
+
+**Test fixture:** at least 100 importers sharing component/helper modules; expose parse/summary counters in tests without production logging.
+
+**Done condition:** each unchanged module is parsed and summarized once per project session; transformed mutable AST is not shared across transformer contexts.
+
+### PR 8: Stable ModuleSymbol And SiteId
+
+**Objective:** represent declarations, imports, re-exports, component calls, hooks, and ownership sites independently of transformed AST identity.
+
+**Tests:** default/named exports, aliases, barrel chains, `export *`, cycles, and deterministic IDs after repeated compilation.
+
+**Done condition:** cross-module semantic consumers use ModuleSymbol records and source-local SiteId values; readable names remain diagnostic metadata.
+
+### PR 9: Semantic State Operations
+
+**Objective:** lower semantically equivalent state updates to the existing structured HandlerIR path.
+
+**Required source equivalence:**
+
+```tsx
+setCount(count + 1)
+const next = count + 1; setCount(next)
+const increment = () => setCount(count + 1); increment()
+function increment(value) { setCount(value + 1) }; increment(count)
+```
+
+**Internal scope:** extend existing command/value representation only for proven pure state operations. Keep arbitrary safe browser handlers as generated ESM; do not invent a general JavaScript IR.
+
+**Done condition:** the equivalent forms produce the same StateWrite semantics, browser result, ownership references, and zero-unused-runtime behavior; recursion, escape, mutation, and dynamic dispatch fail with explicit diagnostics.
+
+### PR 10: ModuleIR Reference Unification
+
+**Objective:** replace mixed state names, export strings, formatted owner strings, and slots with validated source-local slots and SymbolRef records.
+
+**Tests:** malformed references, duplicate exports, parent/child reciprocity, cycles, version rejection, and JSON round trips.
+
+**Done condition:** every HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and component specialization edge validates before build-module generation.
+
+### PR 11: RouteBuildRecord And Artifact Graph
+
+**Objective:** make route artifact selection structural.
+
+**Files:** add a focused route-artifact module; update `build.mjs` and capability planning.
+
+**Done condition:** handler, effect, Worker, CSS, package, and chunk reachability derives from explicit route edges; serialized `includes()` searches and parallel route-fact maps are removed.
+
+### PR 12: Deep RouteIR And CapabilityIR Validation
+
+**Objective:** fail before codegen for invalid concrete route references and capability projections.
+
+**Done condition:** duplicate/missing state IDs, invalid event/effect dependencies, broken list ownership, invalid binding descriptors, and artifact mismatches have focused tests and deterministic diagnostics.
+
+## Large Application Capability Order
+
+After the relevant P0 foundations, investigate capabilities in this order:
+
+1. Property-level derived dependencies over ordinary object state.
+2. Multi-boundary component/prop/callback/ref/context dataflow.
+3. Package-neutral shared state/actions and migration of current Zustand internals.
+4. Browser-only package imports in owned effect/resource modules.
+5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics.
+6. Route/layout capability and CSS chunk closure.
+7. Incremental source and affected-route builds.
+8. Range ownership and virtualization only after a real data-heavy fixture establishes direct DOM limits.
+9. Optimistic shared transactions only after independent mutation fixtures establish commit/rollback semantics.
+
+## Compatibility Strategy
+
+Classify every package or category as one of:
+
+- Native: ordinary JS/TS/Web package; use it directly in an allowed build or browser module.
+- Compiled: package-shaped source lowers to package-neutral semantics and the import is erased.
+- Migrated: deterministic source transformation replaces a React runtime implementation with native/Kudzu source.
+- Adapter: repeated package semantics justify an internal compatibility adapter.
+- Partial: only an explicit API subset is supported.
+- Unsupported: safe transformation is not proven; report the reason and migration path.
+
+Current factual baseline:
+
+| Ecosystem | Current classification |
+|---|---|
+| React source | Compiled, partial |
+| React Router | Compiled, partial |
+| Zustand | Compiled, partial, insufficiently isolated |
+| Redux/RTK | Unsupported |
+| TanStack Query | Migrated recipe, partial |
+| React Hook Form | Migrated recipe, partial |
+| Zod | Unsupported in ordinary shared schema placement; native-package candidate after module work |
+| Radix dialog | Migrated to native dialog, partial |
+| Headless UI/MUI | Unsupported |
+| Plain CSS | Native |
+| CSS Modules | Compiled, partial |
+| Tailwind | Application-owned CSS adapter boundary |
+| CSS-in-JS | Unsupported |
+| Native SVG/canvas charts | Native/compiled |
+| React chart, animation, drag/drop, virtualization packages | Unsupported or migration candidates |
+| REST `fetch` | Native/compiled, partial async model |
+| GraphQL/auth/browser SDKs | Unsupported until browser package/resource ownership exists |
+
+## Application Corpus
+
+| Tier | Required evidence |
+|---|---|
+| Tier 1 | Existing reduced positive/negative fixtures with exact semantic boundaries |
+| Tier 2 | Complete small/medium React applications such as CRUD, forms, commerce, admin, chat, and calendar |
+| Tier 3 | Production slices with 100-500 modules, shared state, routing, packages, forms, server state, charts, auth, and resources |
+| Tier 4 | At least two whole existing React applications, including one stateful/realtime app, with 500+ modules and 100,000+ reachable lines where available |
+
+Every corpus entry records upstream URL/commit/license, acquisition hash, original source, migration patch, retained-source percentage, package classification, unsupported census, route/module/component counts, browser/a11y journeys, artifact bytes, build/rebuild/RSS metrics, and AI task traces.
+
+## AI Cost And Tooling Gates
+
+Architecture work must connect to measurable AI cost reduction:
+
+| Compiler capability | Expected cost reduction |
+|---|---|
+| Symbol graph | Fewer file searches, alias mistakes, and capture debugging cycles |
+| Semantic operations | Fewer rewrites into exact compiler-recognized syntax |
+| Component dataflow | Less component flattening and callback forwarding surgery |
+| Property dependencies | Less artificial primitive-state decomposition |
+| Compatibility registry | Less Kudzu-specific package knowledge and documentation lookup |
+| Structured diagnostics | Fewer log-parsing and source-location tool calls |
+| Explain graph | Fewer files read to understand a route or mutation |
+| Deterministic fixes | Fewer repetitive source edits and retries |
+| Incremental build | Lower feedback time per compiler attempt |
+| Artifact graph | Faster runtime/chunk/debugging attribution |
+
+The first comparison is Kudzu versus React + Vite using the same agent, model, tools, prompt, task, and acceptance suite. Record at least five attempts per task and report medians and ranges. A build-only result is not success.
+
+## Production Gates Before 1.0
+
+- Async native and effect work cannot write after ownership release.
+- Build output is atomic and collision-safe.
+- Source maps connect generated route code to TS/TSX diagnostics.
+- Chrome, Firefox, and WebKit pass required journeys.
+- Accessibility automation and keyboard checks cover forms, navigation, dialogs, menus, charts, and errors.
+- Route, module, package, CSS, Worker, and chunk closures are inspectable.
+- Clean build, one-file rebuild, peak RSS, long-navigation heap, and mixed keyed ownership benchmarks have maintained baselines.
+- Package compatibility status and version guarantees are public and machine-readable.
+- Deployment cache, CSP, authentication, private-data, upload, and error-handling guidance is explicit.
+- At least one complete content application and one complete stateful/realtime application pass production gates.
+- AI benchmark results report cost per successful task and context surface area per successful task.
+
+## Per-PR Required Evidence
+
+- [ ] State the exact producer and consumer boundary changed.
+- [ ] Name the real fixture or correctness failure authorizing the patch.
+- [ ] Add a focused check that fails before the implementation.
+- [ ] Preserve unrelated source support and diagnostics.
+- [ ] Compare representative ModuleIR, RouteIR, HTML, emitted paths, and bytes.
+- [ ] Prove static sibling routes remain zero JavaScript.
+- [ ] Prove identity, cleanup, cancellation, and late-completion behavior where ownership changes.
+- [ ] Record build/runtime measurements for nontrivial paths.
+- [ ] Run `npm run check`, `npm test`, and package smoke when package output changes.
+- [ ] Update this plan before combining or reordering scopes.
+- [ ] Update release notes only after the implementation is complete and published.
+
+## Immediate Decision
+
+The first implementation PR is **PR 1: Source-Local Binding Index**. It is compile-time only, adds no browser bytes or public API, fixes an existing correctness class, and creates the stable semantic foundation required by component graphs, state operations, cross-module analysis, compatibility adapters, structured diagnostics, and AI explanation tooling.
+
+The next PR is **PR 2: Symbol-Aware Descriptor Discovery**. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.

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.26` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.28` 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.
 
@@ -17,6 +17,8 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.24` | Start Goal B with measured large keyed restoration and no-op normalization optimizations. | Fresh-profile keyed restoration improves materially; alternating 1,000-product builds improve materially; correctness, output, and byte deltas are recorded. |
 | `0.8.25` | Reuse byte-identical generated native, parameter, and effect route-entry transforms within one build and strengthen compiler/release boundaries. | Alternating 1,011-page builds improve materially with identical deploy hashes; normalization and ModuleIR fail closed; Node, Chrome, package, and registry gates pass. |
 | `0.8.26` | Harden Goal B benchmark reproducibility and ordinary regression coverage without changing runtime behavior. | Commerce comparison defaults to exact output; route transform counts and keyed bulk/fallback guards are protected by the standard suite; baseline coverage and limits are explicit. |
+| `0.8.27` | Characterize the first Goal C browser-resource boundary and publish the ordered large-application and AI-native compiler execution plan. | The E2B-derived fixture fails with a source-located diagnostic, no resource runtime or API is added, and the next PR dependencies and completion evidence are explicit. |
+| `0.8.28` | Add the source-local binding index and adopt it for reactive binding capture/import discovery and lowering. | Lexical shadowing is identity-based for complete indexed bindings, synthesized keyed expressions retain their fallback, the 1,000-reference guard passes, and no browser bytes or public API are added. |
 
 ## Sequence Rules
 

package/framework/compiler/analysis/binding-index.mjs

@@ -0,0 +1,273 @@
+import ts from "typescript"
+
+export const knownGlobalNames = new Set([
+  "Array", "ArrayBuffer", "BigInt", "Blob", "Boolean", "Date", "Error", "Event", "FileReader", "FormData", "Infinity", "IntersectionObserver", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "Worker", "alert", "atob", "btoa", "cancelAnimationFrame", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "localStorage", "location", "navigator", "parseFloat", "parseInt", "performance", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
+])
+
+export function createBindingIndex(sourceFile) {
+  const scopeByNode = new WeakMap()
+  const referenceBindings = new WeakMap()
+  const originalReferenceBindings = new WeakMap()
+  const bindings = []
+  const rootScope = createScope(undefined, sourceFile, "module")
+  const pseudoBindings = new Map()
+
+  collect(sourceFile, rootScope)
+  resolveReferences(sourceFile)
+
+  function createScope(parent, node, kind) {
+    return { parent, node, kind, bindings: new Map() }
+  }
+
+  function mark(node, scope) {
+    scopeByNode.set(node, scope)
+  }
+
+  function declare(identifier, scope, declarationKind) {
+    mark(identifier, scope)
+    let binding = scope.bindings.get(identifier.text)
+    if (!binding) {
+      binding = { slot: bindings.length, debugName: identifier.text, declarationKind, declaration: identifier }
+      bindings.push(binding)
+      scope.bindings.set(identifier.text, binding)
+    }
+    return binding
+  }
+
+  function declareName(name, scope, declarationKind) {
+    mark(name, scope)
+    if (ts.isIdentifier(name)) {
+      declare(name, scope, declarationKind)
+      return
+    }
+    for (const element of name.elements) if (ts.isBindingElement(element)) declareName(element.name, scope, declarationKind)
+  }
+
+  function collectBindingExpressions(name, scope) {
+    if (ts.isIdentifier(name)) return
+    for (const element of name.elements) if (ts.isBindingElement(element)) {
+      if (element.propertyName && ts.isComputedPropertyName(element.propertyName)) collect(element.propertyName.expression, scope)
+      if (element.initializer) collect(element.initializer, scope)
+      collectBindingExpressions(element.name, scope)
+    }
+  }
+
+  function nearestVarScope(scope) {
+    for (let current = scope; current; current = current.parent) if (["function", "module"].includes(current.kind)) return current
+    return rootScope
+  }
+
+  function collectFunction(node, scope) {
+    if (ts.isFunctionDeclaration(node) && node.name) declare(node.name, scope, "function")
+    const parameterScope = createScope(scope, node, "parameters")
+    const functionScope = createScope(parameterScope, node.body ?? node, "function")
+    mark(node, parameterScope)
+    if (ts.isFunctionExpression(node) && node.name) declare(node.name, parameterScope, "function-name")
+    for (const parameter of node.parameters) {
+      mark(parameter, parameterScope)
+      declareName(parameter.name, parameterScope, "parameter")
+      collectBindingExpressions(parameter.name, parameterScope)
+      if (parameter.initializer) collect(parameter.initializer, parameterScope)
+    }
+    if (node.body) collect(node.body, functionScope)
+  }
+
+  function collectClass(node, scope) {
+    if (ts.isClassDeclaration(node) && node.name) declare(node.name, scope, "class")
+    const classScope = createScope(scope, node, "class")
+    mark(node, classScope)
+    if (ts.isClassExpression(node) && node.name) declare(node.name, classScope, "class-name")
+    for (const heritage of node.heritageClauses ?? []) for (const type of heritage.types) collect(type.expression, classScope)
+    for (const member of node.members) collect(member, classScope)
+  }
+
+  function collectLoop(node, scope) {
+    const loopScope = createScope(scope, node, "block")
+    mark(node, loopScope)
+    if (node.initializer) collect(node.initializer, loopScope)
+    if (ts.isForStatement(node)) {
+      if (node.condition) collect(node.condition, loopScope)
+      if (node.incrementor) collect(node.incrementor, loopScope)
+    } else collect(node.expression, loopScope)
+    collect(node.statement, loopScope)
+  }
+
+  function collect(node, scope) {
+    mark(node, scope)
+    if (ts.isTypeNode(node)) return
+    if (ts.isSourceFile(node)) {
+      for (const statement of node.statements) collect(statement, scope)
+      return
+    }
+    if (ts.isImportDeclaration(node)) {
+      const clause = node.importClause
+      if (!clause || clause.isTypeOnly) return
+      if (clause.name) declare(clause.name, scope, "import-default")
+      if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) declare(clause.namedBindings.name, scope, "import-namespace")
+      if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) for (const element of clause.namedBindings.elements) if (!element.isTypeOnly) declare(element.name, scope, "import-named")
+      return
+    }
+    if (ts.isImportEqualsDeclaration(node)) {
+      if (!node.isTypeOnly) declare(node.name, scope, "import-equals")
+      return
+    }
+    if (isFunctionLike(node)) {
+      if (node.name && ts.isComputedPropertyName(node.name)) collect(node.name.expression, scope)
+      collectFunction(node, scope)
+      return
+    }
+    if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+      collectClass(node, scope)
+      return
+    }
+    if (ts.isBlock(node)) {
+      const blockScope = createScope(scope, node, "block")
+      mark(node, blockScope)
+      for (const statement of node.statements) collect(statement, blockScope)
+      return
+    }
+    if (ts.isCaseBlock(node)) {
+      const caseScope = createScope(scope, node, "block")
+      mark(node, caseScope)
+      for (const clause of node.clauses) collect(clause, caseScope)
+      return
+    }
+    if (ts.isCatchClause(node)) {
+      const catchScope = createScope(scope, node, "block")
+      mark(node, catchScope)
+      if (node.variableDeclaration) {
+        declareName(node.variableDeclaration.name, catchScope, "catch")
+        collectBindingExpressions(node.variableDeclaration.name, catchScope)
+      }
+      collect(node.block, catchScope)
+      return
+    }
+    if (ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) {
+      collectLoop(node, scope)
+      return
+    }
+    if (ts.isVariableDeclaration(node)) {
+      const list = node.parent
+      const declarationKind = ts.isVariableDeclarationList(list) && (list.flags & ts.NodeFlags.Const) ? "const" : ts.isVariableDeclarationList(list) && (list.flags & ts.NodeFlags.Let) ? "let" : "var"
+      const declarationScope = declarationKind === "var" ? nearestVarScope(scope) : scope
+      declareName(node.name, declarationScope, declarationKind)
+      collectBindingExpressions(node.name, scope)
+      if (node.initializer) collect(node.initializer, scope)
+      return
+    }
+    if (ts.isEnumDeclaration(node)) declare(node.name, scope, "enum")
+    if (ts.isModuleDeclaration(node) && ts.isIdentifier(node.name)) {
+      declare(node.name, scope, "namespace")
+      const moduleScope = createScope(scope, node, "module")
+      if (node.body && ts.isModuleBlock(node.body)) {
+        mark(node.body, moduleScope)
+        for (const statement of node.body.statements) collect(statement, moduleScope)
+      } else if (node.body) collect(node.body, moduleScope)
+      return
+    }
+    ts.forEachChild(node, child => collect(child, scope))
+  }
+
+  function lexicalBinding(scope, name) {
+    for (let current = scope; current; current = current.parent) {
+      const binding = current.bindings.get(name)
+      if (binding) return binding
+    }
+  }
+
+  function pseudoBinding(kind, name) {
+    const key = `${kind}:${name}`
+    let binding = pseudoBindings.get(key)
+    if (!binding) {
+      binding = { slot: bindings.length, debugName: name, declarationKind: kind }
+      bindings.push(binding)
+      pseudoBindings.set(key, binding)
+    }
+    return binding
+  }
+
+  function resolveReferences(node) {
+    if (ts.isTypeNode(node)) return
+    if (ts.isIdentifier(node) && isValueReference(node)) {
+      const lexical = lexicalBinding(scopeByNode.get(node) ?? rootScope, node.text)
+      const binding = lexical ?? pseudoBinding(knownGlobalNames.has(node.text) ? "global" : "unresolved", node.text)
+      referenceBindings.set(node, binding)
+      const original = ts.getOriginalNode(node)
+      if (original !== node) originalReferenceBindings.set(original, binding)
+    }
+    ts.forEachChild(node, resolveReferences)
+  }
+
+  function resolveReference(identifier, boundary = sourceFile) {
+    const original = ts.getOriginalNode(identifier)
+    const binding = referenceBindings.get(identifier) ?? referenceBindings.get(original) ?? originalReferenceBindings.get(original)
+    if (!binding) return undefined
+    let kind
+    if (binding.declarationKind.startsWith("import")) kind = "import"
+    else if (binding.declarationKind === "global") kind = "global"
+    else if (binding.declarationKind === "unresolved") kind = "unresolved"
+    else if (inside(binding.declaration, ts.getOriginalNode(boundary))) kind = binding.declarationKind === "parameter" ? "parameter" : "local"
+    else kind = "capture"
+    return {
+      kind,
+      slot: binding.slot,
+      debugName: binding.debugName,
+      declarationKind: binding.declarationKind,
+      ...(binding.declaration ? { declaration: binding.declaration, declarationRange: range(binding.declaration) } : {}),
+      referenceRange: range(original)
+    }
+  }
+
+  function references(root, boundary = root) {
+    const found = []
+    let complete = true
+    const visit = node => {
+      if (ts.isTypeNode(node)) return
+      if (ts.isIdentifier(node) && isValueReference(node)) {
+        const resolution = resolveReference(node, boundary)
+        if (resolution) found.push(resolution)
+        else complete = false
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(root)
+    return complete ? found : undefined
+  }
+
+  return { bindings: () => bindings.map(({ declaration, ...binding }) => ({ ...binding, ...(declaration ? { declarationRange: range(declaration) } : {}) })), references, resolveReference }
+}
+
+function inside(node, boundary) {
+  for (let current = node; current; current = current.parent) if (current === boundary) return true
+  return false
+}
+
+function range(node) {
+  return node.pos >= 0 && node.end >= 0 ? { start: node.getStart(), end: node.end } : undefined
+}
+
+function isFunctionLike(node) {
+  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node)
+}
+
+function isValueReference(node) {
+  const parent = node.parent
+  if (!parent) return true
+  if (ts.isTypeNode(parent)) return false
+  if ((ts.isPropertyAccessExpression(parent) && parent.name === node)
+    || (ts.isPropertyAssignment(parent) && parent.name === node)
+    || ((ts.isMethodDeclaration(parent) || ts.isGetAccessorDeclaration(parent) || ts.isSetAccessorDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertySignature(parent) || ts.isMethodSignature(parent)) && parent.name === node)
+    || (ts.isVariableDeclaration(parent) && parent.name === node)
+    || (ts.isParameter(parent) && parent.name === node)
+    || ((ts.isFunctionDeclaration(parent) || ts.isFunctionExpression(parent) || ts.isClassDeclaration(parent) || ts.isClassExpression(parent) || ts.isEnumDeclaration(parent) || ts.isModuleDeclaration(parent)) && parent.name === node)
+    || (ts.isJsxAttribute(parent) && parent.name === node)
+    || (ts.isBindingElement(parent) && (parent.name === node || parent.propertyName === node))
+    || ts.isImportSpecifier(parent) || ts.isImportClause(parent) || ts.isNamespaceImport(parent) || ts.isImportEqualsDeclaration(parent)
+    || ts.isExportSpecifier(parent)
+    || ts.isLabeledStatement(parent) || ts.isBreakStatement(parent) || ts.isContinueStatement(parent)
+    || (ts.isEnumMember(parent) && parent.name === node)) return false
+  if ((ts.isTypeAliasDeclaration(parent) || ts.isInterfaceDeclaration(parent)) && parent.name === node) return false
+  if (ts.isJsxClosingElement(parent) && parent.tagName === node) return false
+  if ((ts.isJsxOpeningElement(parent) || ts.isJsxSelfClosingElement(parent)) && parent.tagName === node) return node.text[0] === node.text[0].toUpperCase()
+  return true
+}

package/framework/compiler/descriptor-session.mjs

@@ -1,5 +1,6 @@
 import ts from "typescript"
 import { createComponentAnalysis } from "./analysis/component-analysis.mjs"
+import { knownGlobalNames } from "./analysis/binding-index.mjs"
 import { bindingNames, isFunctionLike, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, unwrapExpression } from "./ast-helpers.mjs"
 import { generateCommandBehavior } from "./codegen/command-codegen.mjs"
 import { assertModuleIRReferences, createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerEffect, registerKeyedBlock, registerModuleHandler } from "./ir/module-ir.mjs"
@@ -8,7 +9,7 @@ export function createSemanticArtifact(file) {
   return { componentAnalysis: createComponentAnalysis(file), moduleIR: createModuleIR(file) }
 }
 
-export function createDescriptorSession({ semantic, handlerUrl, factory, context, compileEventCommand, handlerLowering, isPrimitiveLiteral, rejectWorkerConstructions, sourceName = source => source.fileName }) {
+export function createDescriptorSession({ semantic, handlerUrl, factory, context, bindingIndex, compileEventCommand, handlerLowering, isPrimitiveLiteral, rejectWorkerConstructions, sourceName = source => source.fileName }) {
   const { moduleIR } = semantic
   const nativeHandlers = []
   const effectHandlers = []
@@ -66,12 +67,16 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   function compileReactiveExpression(expression, setters, importBindings = new Map(), keyedBlock) {
     const usedStates = referencedStateNames(expression, setters)
-    const importedNames = referencedImportedBindings(expression, importBindings)
+    const indexed = bindingIndex?.references(expression, expression)
+    const importedNames = indexed ? new Set(indexed.filter(reference => reference.kind === "import" && importBindings.has(reference.debugName)).map(reference => reference.debugName)) : 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 allStateNames = new Set(setters.values())
+    const captures = indexed
+      ? new Set(indexed.filter(reference => ["capture", "unresolved"].includes(reference.kind) && !setters.has(reference.debugName) && !allStateNames.has(reference.debugName) && !importedNames.has(reference.debugName)).map(reference => reference.debugName))
+      : 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", keyedBlock })
+    reactiveBindings.push({ exportName, expression, captures, states: usedStates, imports, role: "binding", keyedBlock, ...(indexed ? { bindingIndex } : {}) })
     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)
@@ -303,14 +308,10 @@ export function captureNames(declarationRoot, referenceRoot, setters) {
     if (ts.isTypeNode(node)) return
     if (ts.isIdentifier(node)) {
       const declared = isFunctionLike(declarationRoot) ? isShadowedIdentifier(node, declarationRoot) : local.has(node.text)
-      if (isReferenceIdentifier(node) && !declared && !setters.has(node.text) && !stateNames.has(node.text) && !nativeGlobals.has(node.text)) captures.add(node.text)
+      if (isReferenceIdentifier(node) && !declared && !setters.has(node.text) && !stateNames.has(node.text) && !knownGlobalNames.has(node.text)) captures.add(node.text)
     }
     ts.forEachChild(node, visit)
   }
   visit(referenceRoot)
   return captures
 }
-
-const nativeGlobals = new Set([
-  "Array", "ArrayBuffer", "BigInt", "Blob", "Boolean", "Date", "Error", "Event", "FileReader", "FormData", "Infinity", "IntersectionObserver", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "Worker", "alert", "atob", "btoa", "cancelAnimationFrame", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "localStorage", "location", "navigator", "parseFloat", "parseInt", "performance", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
-])

package/framework/compiler/handler-lowering.mjs

@@ -189,11 +189,15 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
     return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"), undefined, [factory.createStringLiteral(reducer.state), update])
   }
 
-  function printReactiveBinding({ exportName, expression, captures, states }) {
+  function printReactiveBinding({ exportName, expression, captures, states, bindingIndex }) {
     const factory = ts.factory
     const transformer = context => root => {
       const visitor = node => {
-        if (ts.isShorthandPropertyAssignment(node) && states.has(node.name.text)) {
+        const reference = ts.isShorthandPropertyAssignment(node) ? node.name : ts.isIdentifier(node) ? node : undefined
+        const resolution = reference ? bindingIndex?.resolveReference(reference, expression) : undefined
+        const indexedState = resolution?.kind === "capture" && states.has(resolution.debugName)
+        const indexedCapture = ["capture", "unresolved"].includes(resolution?.kind) && captures.has(resolution.debugName)
+        if (ts.isShorthandPropertyAssignment(node) && states.has(node.name.text) && (!bindingIndex || indexedState)) {
           return factory.createPropertyAssignment(
             node.name,
             factory.createCallExpression(
@@ -203,17 +207,17 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
             )
           )
         }
-        if (ts.isIdentifier(node) && states.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression)) {
+        if (ts.isIdentifier(node) && states.has(node.text) && isReferenceIdentifier(node) && (bindingIndex ? indexedState : !isShadowedByParameter(node, expression))) {
           return factory.createCallExpression(
             factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"),
             undefined,
             [factory.createStringLiteral(node.text)]
           )
         }
-        if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text)) {
+        if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text) && (!bindingIndex || indexedCapture)) {
           return factory.createPropertyAssignment(node.name, scopeRead(factory, node.name.text))
         }
-        if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node)) {
+        if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node) && (!bindingIndex || indexedCapture)) {
           return scopeRead(factory, node.text)
         }
         return ts.visitEachChild(node, visitor, context)

package/framework/compiler/source-compiler.mjs

@@ -1,6 +1,7 @@
 import { readFile, realpath, stat } from "node:fs/promises"
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import ts from "typescript"
+import { createBindingIndex } from "./analysis/binding-index.mjs"
 import { createComponentAnalysisSession } from "./analysis/component-analysis.mjs"
 import { normalizeEffectAnimationFrameRefs } from "./animation-frame-pass.mjs"
 import { bindingNames, containsJsx, effectReturns, functionVarDeclaresName, importDeclarationNames, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, isUnshadowedGlobal, nearestFunction, referenceIdentifiers, referencesIdentifier, sourceLocation, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
@@ -248,6 +249,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const normalized = normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedStaticCollections, sourceFiles, sourceIndex })
     sourceFile = normalized.sourceFile
     const { customHookTimerStates } = normalized
+    const bindingIndex = createBindingIndex(sourceFile)
     const factory = context.factory
     const sourceName = source => relative(root, source.fileName).replaceAll(sep, "/")
     const componentAnalysis = createComponentAnalysisSession(semantic.componentAnalysis)
@@ -256,6 +258,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       handlerUrl,
       factory,
       context,
+      bindingIndex,
       compileEventCommand,
       handlerLowering,
       isPrimitiveLiteral: isPrimitiveDefaultLiteral,
@@ -629,9 +632,13 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       }
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression)) {
         const owner = nearestFunction(node)
-        if (owner && node.initializer.expression.text === "useRef" && node.initializer.arguments.length === 1 && node.initializer.arguments[0].kind === ts.SyntaxKind.NullKeyword) {
-          ensureOwner(owner)
-          componentAnalysis.registerRef(owner, { name: node.name.text, source: analysisSource(node) })
+        if (owner && node.initializer.expression.text === "useRef") {
+          const nullInitializer = node.initializer.arguments.length === 1 && node.initializer.arguments[0].kind === ts.SyntaxKind.NullKeyword
+          if (!nullInitializer && owner.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) throw sourceNodeError(node.initializer, sourceFile, "Mutable value useRef() is unsupported except for an effect-owned useRef(0) animation-frame handle; otherwise keep resource-private mutable values inside the owning effect")
+          if (nullInitializer) {
+            ensureOwner(owner)
+            componentAnalysis.registerRef(owner, { name: node.name.text, source: analysisSource(node) })
+          }
         }
         if (owner && node.initializer.expression.text === "useId" && node.initializer.arguments.length === 0) {
           ensureOwner(owner)

package/package.json

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