@kudzujs/core 0.8.30 → 0.8.31

package/MIGRATION_ROADMAP.md

@@ -2,7 +2,7 @@
 
 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.30` 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.
+The executable post-`0.8.31` 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.
 
@@ -28,6 +28,7 @@ Syntax compatibility does not mean reproducing React wholesale. Kudzu accepts th
 - Interactive routes ship only the capabilities they use.
 - Prefer build-time execution whenever all inputs are available during the build.
 - State setters update logical state immediately and batch direct DOM writes at synchronous-turn boundaries.
+- Async handler state writes, queued commits, and captured ref resolution end when its mounted DOM owner is released; application promises and ordinary reads may finish without reviving that ownership.
 - Preserve familiar function components, props, children, JSX, hooks, conditions, collections, and event handlers where Kudzu can compile them safely.
 - Prefer compiler specialization over asking migrated applications to replace ordinary declarative React UI with imperative DOM code.
 - Unknown browser-only data receives a static shell plus only the ESM needed to obtain and patch it.
@@ -288,6 +289,13 @@ This queue orders the next investigations by general migration value. Start only
 - Ordinary dynamic `import()` fails during graph discovery rather than surviving into generated `.kudzu` modules; relative, package, template, and computed forms share one source-located boundary.
 - Ordinary and Worker graph ownership remain separate, while type-only and unreachable source stay excluded. Export-name validation, ProjectSession, runtime behavior, and public APIs remain unchanged.
 
+### Completed In 0.8.31
+
+- Pending async native handlers lose state-write, queued-commit, and captured-ref authority when enhanced navigation, keyed removal, conditional removal, or document disposal releases their mounted DOM owner.
+- Direct and captured setters cannot recreate released state, queued commits clear without touching replacement DOM, and captured object refs resolve to `null` after release.
+- Chrome coverage removes and recreates the same route and keyed row before old work resolves, proving replacement ownership stays fresh without cancelling application promises or adding a scheduler.
+- The focused 5,000-event Chrome dispatch median remains 6.4 ms; the native fixture retains its emitted paths with a measured 209 B raw / 94 B aggregate gzip correctness cost.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

package/PERFORMANCE.md

@@ -1,6 +1,41 @@
 # Performance Records
 
-Reproducibility classes: `npm run benchmark` and `npm run benchmark:keyed` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
+Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, and `npm run benchmark:native` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
+
+## 0.8.31 Async Native Handler Ownership
+
+Measured UTC 2026-08-10 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, npm 11.18.0, and Chrome 151.0.7922.76. The baseline was clean tag `v0.8.30` at `9bb5ce8`; baseline and candidate used the same installed dependencies.
+
+The implementation and maintained-check patch over `v0.8.30` had SHA-256 `c67956b67b558052885dd48a9dbe35f238b8ce042876537952355aa05b8cdc10`, produced by:
+
+```bash
+git diff --binary v0.8.30 -- framework/native-runtime.js framework/serialization.js test/fixtures/navigation/src/Shell.tsx test/fixtures/navigation/src/pages/product.tsx test/fixtures/navigation/public/browser-test.js test/framework.test.mjs test/native-performance.mjs package.json | shasum -a 256
+```
+
+The maintained browser runner built the same `test/fixtures/native-bubbling` source with each framework root. After one warm-up, 21 alternating headless Chrome processes dispatched 5,000 synchronous clicks through the real DOM listener, handler-module lookup, generated handler, state context, and queued-flush scheduling path. Both medians were 6.4 ms; the 6.1-6.8 ms baseline and 6.2-6.7 ms candidate ranges overlap, so no dispatch regression is established.
+
+```bash
+git worktree add --detach /tmp/kudzu-v0.8.30 v0.8.30
+ln -s "$PWD/node_modules" /tmp/kudzu-v0.8.30/node_modules
+BASELINE_ROOT=/tmp/kudzu-v0.8.30 RUNS=21 ITERATIONS=5000 \
+CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+npm run benchmark:native
+```
+
+```text
+0.8.30: [6.6,6.3,6.4,6.3,6.3,6.8,6.3,6.6,6.3,6.4,6.5,6.4,6.5,6.5,6.4,6.1,6.3,6.2,6.5,6.4,6.4]
+0.8.31: [6.4,6.7,6.2,6.4,6.6,6.6,6.5,6.4,6.5,6.4,6.4,6.4,6.6,6.5,6.4,6.3,6.4,6.4,6.6,6.2,6.4]
+```
+
+The maintained `native-bubbling` fixture retained the same eight JavaScript paths. The browser runner hashes every file and permits only the ownership-bearing native and capture-deserialization runtimes to change:
+
+| Artifact | 0.8.30 raw / gzip | 0.8.31 raw / gzip | Delta raw / gzip |
+|---|---:|---:|---:|
+| `assets/kudzu-native.js` | 1,528 B / 842 B | 1,715 B / 925 B | +187 B / +83 B |
+| `assets/kudzu-serialization.js` | 675 B / 381 B | 697 B / 392 B | +22 B / +11 B |
+| Complete native fixture JavaScript | 13,629 B / 6,177 B | 13,838 B / 6,271 B | +209 B / +94 B |
+
+The timing is a focused synchronous event-dispatch measurement, not a general interaction or asynchronous task benchmark. The runtime does not cancel application promises or arbitrary browser API work; it invalidates Kudzu state writes, queued commits, and captured ref resolution after the listener's DOM ownership is released.
 
 ## 0.8.26 Goal B Benchmark Hardening
 

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.30 - Graph failure diagnostics.** Reachable ordinary modules now validate relative runtime imports and re-exports and reject dynamic `import()` at the original importer location before generated module loading. Worker ownership, type-only edges, and unreachable source remain distinct. Read the [release notes](./RELEASES.md#0830---graph-failure-diagnostics), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.30), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.31 - Async native-handler ownership.** Pending async handlers lose state-write, queued-commit, and captured-ref authority when enhanced navigation or keyed/conditional removal releases their DOM owner. The focused synchronous native event-dispatch benchmark shows no material regression. Read the [release notes](./RELEASES.md#0831---async-native-handler-ownership), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.31), 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,36 @@
 # Kudzu Releases
 
+## 0.8.31 - Async native-handler ownership
+
+Kudzu 0.8.31 completes P0.4 by tying every mounted native-handler context to its DOM registration lifetime. Async work may finish after route, keyed, or conditional removal, but it cannot write through ownership that no longer exists.
+
+### Changed in 0.8.31
+
+- Native registrations expose one active lifetime to direct setters, captured setters, queued commits, and captured object refs.
+- `unmountNative()` invalidates the registration before removing its listener. Enhanced navigation, keyed removal, and conditional removal use the shared unmount hook; non-persisted `pagehide` directly releases document registrations.
+- Late state writes become no-ops instead of recreating released state IDs; already queued commits clear without touching replacement DOM.
+- Captured object refs resolve to `null` after release, so a late handler cannot find a replacement node that reused the same compiler-owned ref ID.
+- Application promises are not cancelled, and no scheduler, task registry, component runtime, or public API is added.
+
+### Performance
+
+- Twenty-one alternating headless Chrome processes measured 5,000 synchronous native event dispatches at a 6.4 ms median for both `0.8.30` and `0.8.31`; the recorded ranges overlap.
+- The maintained `native-bubbling` fixture keeps the same eight JavaScript paths. `kudzu-native.js` and `kudzu-serialization.js` add 209 B raw / 94 B aggregate gzip; the runner rejects any other artifact change.
+- Environment, raw arrays, artifact bytes, methodology, and limitations are recorded in `PERFORMANCE.md`.
+
+### Validation
+
+- `npm run check`, `npm test`, `npm run test:package`, and all 189 tests pass.
+- Chrome starts async route and keyed-row handlers, releases and recreates their owners, and proves late state writes and refs cannot mutate replacement ownership. A persistent layout handler also proves non-persisted document disposal invalidates pending work.
+- Focused context checks cover queued direct commits and captured setters. The browser suite retains normal synchronous native event semantics; unaffected static routes remain zero JavaScript.
+- P0.5 atomic and collision-safe output is next.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.31
+```
+
 ## 0.8.30 - Graph failure diagnostics
 
 Kudzu 0.8.30 completes P0.3 by making ordinary source-graph failures stop at the original importer before compilation, generated module loading, or `.kudzu` paths can obscure the source error.

package/docs/next-architecture/README.md

@@ -11,7 +11,7 @@ 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.30` 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.
+The active post-`0.8.31` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.4 native-handler ownership is complete; P0.5 atomic and collision-safe output is next. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
 
 ## Required Invariants
 

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.30` 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.31` 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
 
@@ -29,7 +29,7 @@ This maps the current `0.8.30` architecture built on the completed `0.8.23` Goal
 | Effect entry generation | [`framework/compiler/effect-codegen.mjs`](../../framework/compiler/effect-codegen.mjs) | Generates ordinary, dependency, owned, and navigable effect entries from rendered descriptors. |
 | Runtime generation | [`framework/compiler/runtime-codegen.mjs`](../../framework/compiler/runtime-codegen.mjs), [`framework/compiler/list-runtime-codegen.mjs`](../../framework/compiler/list-runtime-codegen.mjs), [`framework/compiler/param-codegen.mjs`](../../framework/compiler/param-codegen.mjs) | Consumes versioned contracts, specializes authored capability sources with fail-closed anchors, and returns source/define results without filesystem ownership. |
 | Artifact emission | `framework/build.mjs` | Selects required files from CapabilityIR and writes or bundles generated sources with esbuild. Byte-identical native, parameter, and effect route entries reuse one exact-source transform result within the current build only. |
-| Browser capabilities | [`framework/*.js`](../../framework/) | Small optional modules for commands, bindings, lists, effects, native handlers, serialization, parameters, and navigation; no component runtime. |
+| Browser capabilities | [`framework/*.js`](../../framework/) | Small optional modules for commands, bindings, lists, effects, native handlers, serialization, parameters, and navigation; native contexts invalidate writes and refs at DOM ownership release, with no component runtime. |
 | Opt-in navigation | [`framework/navigation-runtime.js`](../../framework/navigation-runtime.js) plus `framework/build.mjs` navigation configuration/emission | Fetches and validates complete same-origin documents, replaces only the marked route range, manages route/layout disposal, history, focus, finite prefetch retention, and native fallback. |
 | Development serving | [`framework/dev-server.mjs`](../../framework/dev-server.mjs) and [`framework/dev-state.js`](../../framework/dev-state.js) | Rebuild/watch/SSE and response-only short-lived state restoration; never changes production `dist/`. |
 
@@ -67,7 +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.
+- Imported, specialized, and compiler-synthesized trees still use conservative name/scope fallback where the source-local binding index does not own the complete AST; cross-module semantics remain deferred to stable ModuleSymbol and SiteId work.
 
 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/large-application-ai-native-roadmap.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Active execution plan after `0.8.30`. 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.
+Active execution plan after `0.8.31`. 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.
 
@@ -43,7 +43,7 @@ The current limiting architecture is observable in these files:
 | 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 |
+| Browser lifetime | `native-runtime.js`, `effect-runtime.js`, `navigation-runtime.js` | Effects and native handlers invalidate stale writes at their existing effect or DOM ownership boundary |
 | 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 |
 
@@ -132,7 +132,8 @@ This is an incremental evolution of the current repository:
 - [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.
 - [x] P0.2 Symbol-aware descriptor discovery is complete in `0.8.29`. Native handler, effect, remaining binding, list evaluator, optimized-command, and effect-resource discovery/lowering use the source-local binding index when it owns the complete AST; synthesized trees retain the existing fail-safe path. Focused lexical-shadow, JSON-safe IR, resource-ownership checks, all 187 tests, and packed-package smoke pass.
 - [x] P0.3 Graph diagnostics is complete in `0.8.30`. Reachable ordinary modules validate relative runtime imports/re-exports and reject every dynamic `import()` at the importer source location before compilation or generated module loading. Ordinary and Worker traversal retain separate ownership, type-only and unreachable edges remain excluded, focused page/helper/re-export/dynamic fixtures pass with all 189 tests and packed-package smoke, and no export-symbol graph, ProjectSession, runtime, or public API is added.
-- [ ] P0.4 Async native handler ownership is next. Pending handlers must not write after route or DOM ownership is released.
+- [x] P0.4 Async native handler ownership is complete in `0.8.31`. Mounted native registrations invalidate direct/captured setters, queued commits, and captured refs before listener removal. Chrome route, keyed-row, document-disposal, and synchronous event-dispatch checks, all 189 tests, and packed-package smoke pass without cancelling application promises or adding a scheduler.
+- [ ] P0.5 Atomic and collision-safe output is next. Failed builds must preserve prior output and public content must not overwrite generated artifacts.
 
 ### P0: Semantic Correctness And Compiler Foundation
 
@@ -272,6 +273,8 @@ Every result carries a stable source-local binding slot, debug name, declaration
 
 **Done condition:** a handler resolving after enhanced navigation or row removal cannot recreate or mutate released state, refs, or DOM.
 
+**Completed in `0.8.31`:** the existing native registration lifetime now guards state mutation, queued commits, and captured ref lookup. Route and keyed-row browser checks recreate the same ownership IDs before old work resolves, and document disposal invalidates a pending layout handler. Replacement state and DOM remain fresh. Both 5,000-event Chrome dispatch medians are 6.4 ms, and the 209 B raw / 94 B aggregate gzip runtime cost is recorded in `PERFORMANCE.md`.
+
 ### PR 5: Atomic And Collision-Safe Output
 
 **Objective:** make production builds safe before scaling the build graph.
@@ -454,6 +457,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## 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 4: Async Native Handler Invalidation**. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.
+PR 1 through PR 4 are complete. The next PR is **PR 5: Atomic And Collision-Safe Output**. 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.30` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.31` 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.
 
@@ -21,6 +21,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `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. |
 | `0.8.29` | Move native handler, effect, remaining binding, list evaluator, optimized-command, and effect-resource discovery/lowering onto source-local lexical identity. | Shadowed imports/globals/state/resources remain distinct, HandlerIR/BindingIR round trips pass, synthesized trees retain the fallback, and no runtime or public API is added. |
 | `0.8.30` | Validate ordinary runtime graph edges before code generation and reject dynamic imports at the importer source. | Page/helper/re-export/dynamic fixtures report original file/range/specifier without `.kudzu` paths; Worker, type-only, unreachable, output, and runtime behavior remain unchanged. |
+| `0.8.31` | Invalidate pending native-handler contexts when their route, keyed, conditional, or document DOM owner is released. | Late setters, queued commits, and captured refs cannot mutate replacement ownership; synchronous dispatch remains within the performance gate and runtime bytes are recorded. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -63,7 +63,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `list-runtime.js`: optional keyed list validation, external item-expression evaluation, item-local conditional ranges, dynamic styles, item handler/effect scopes, moves, and cleanup.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `effect-runtime.js`: optional state and capture context for route-specific mount-effect entries.
-- `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
+- `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers; DOM unmount invalidates late state writes, queued commits, and captured refs.
 - `navigation-runtime.js`: optional emitted-route complete-document prefetch, runtime segment matching, validation, finite memory caching, route-range replacement, history, focus, and native fallback, specialized once per configured shared-layout group.
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
@@ -90,4 +90,4 @@ A direct setter may cross one same-file or relative-imported component boundary
 
 `kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Direct primitive state, runtime parameter, and keyed-item property dependencies and cleanup are supported. Fragment payloads and coordinated View Transitions are not implemented.
 
-Cross-framework performance tables are historical snapshots from excluded workspaces and are not current rankings. `npm run benchmark` tracks the Worker build/graph fixture; `RUNS=21 npm run benchmark:keyed` tracks large keyed restoration with fresh Chrome profiles. Current methodology, raw arrays, external-fixture limits, and artifact deltas live in `PERFORMANCE.md` and the web docs.
+Cross-framework performance tables are historical snapshots from excluded workspaces and are not current rankings. `npm run benchmark` tracks the Worker build/graph fixture; `RUNS=21 npm run benchmark:keyed` tracks large keyed restoration; `BASELINE_ROOT=... npm run benchmark:native` tracks native dispatch and exact artifact changes. Current methodology, raw arrays, external-fixture limits, and artifact deltas live in `PERFORMANCE.md` and the web docs.

package/framework/native-runtime.js

@@ -8,18 +8,20 @@ export function registerNativeModules(entries) {
   for (const [url, module] of entries) modules.set(url, module)
 }
 
-export function createNativeContext(state, stateIds, commit, serializedScope = {}) {
+export function createNativeContext(state, stateIds, commit, serializedScope = {}, active = () => true) {
   const changed = new Set()
   let scheduled = false
 
   const flush = () => {
     scheduled = false
+    if (!active()) return changed.clear()
     const ids = [...changed]
     changed.clear()
     for (const id of ids) commit(id, state.get(id))
   }
 
   const setId = globalThis.__KUDZU_CAPTURE_SETTER__ ? (id, value) => {
+    if (!active()) return
     const current = state.get(id)
     state.set(id, typeof value === "function" ? value(current) : value)
     changed.add(id)
@@ -29,7 +31,7 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
     }
   } : undefined
 
-  const scope = Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value, id => state.get(id), globalThis.__KUDZU_CAPTURE_SETTER__ ? setId : undefined)]))
+  const scope = Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value, id => state.get(id), globalThis.__KUDZU_CAPTURE_SETTER__ ? setId : undefined, active)]))
 
   return {
     get(name) {
@@ -43,6 +45,7 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
         setId(stateIds[name], value)
         return
       }
+      if (!active()) return
       const id = stateIds[name]
       const current = state.get(id)
       state.set(id, typeof value === "function" ? value(current) : value)
@@ -61,6 +64,9 @@ if (typeof document !== "undefined") {
   registerMountHook(mount)
   registerUnmountHook(unmountNative)
   mount(document)
+  addEventListener("pagehide", event => {
+    if (!event.persisted) unmountNative(document)
+  })
 }
 
 function mountNative(root, eventNames, modules) {
@@ -71,14 +77,16 @@ function mountNative(root, eventNames, modules) {
       let encoded = node.dataset[`kNative${capitalize(eventName)}`]
       let native = JSON.parse(encoded)
       let handler
-      let context = createNativeContext(browserState, native.states, commitDom, native.scope)
+      const registration = { active: true }
+      const active = () => registration.active
+      let context = createNativeContext(browserState, native.states, commitDom, native.scope, active)
       const listener = event => {
         try {
           const current = node.dataset[`kNative${capitalize(eventName)}`]
           if (current !== encoded) {
             native = JSON.parse(current)
             encoded = current
-            context = createNativeContext(browserState, native.states, commitDom, native.scope)
+            context = createNativeContext(browserState, native.states, commitDom, native.scope, active)
             handler = undefined
           }
           handler ??= modules.get(native.module)[native.handler]
@@ -88,8 +96,9 @@ function mountNative(root, eventNames, modules) {
           console.error(error)
         }
       }
+      registration.listener = listener
       node.addEventListener(eventName, listener)
-      listeners.set(eventName, listener)
+      listeners.set(eventName, registration)
       registrations.set(node, listeners)
     }
   }
@@ -97,7 +106,10 @@ function mountNative(root, eventNames, modules) {
 
 function unmountNative(root) {
   for (const node of matching(root, "*")) {
-    for (const [eventName, listener] of registrations.get(node) ?? []) node.removeEventListener(eventName, listener)
+    for (const [eventName, registration] of registrations.get(node) ?? []) {
+      registration.active = false
+      node.removeEventListener(eventName, registration.listener)
+    }
     registrations.delete(node)
   }
 }

package/framework/serialization.js

@@ -1,8 +1,8 @@
-export function deserialize(value, getState, setState) {
+export function deserialize(value, getState, setState, active) {
   if (!value || typeof value !== "object") return value
   if (value.type === "undefined") return undefined
   if (value.type === "number") return value.value === "NaN" ? NaN : value.value === "Infinity" ? Infinity : value.value === "-Infinity" ? -Infinity : -0
-  if (value.type === "ref") return { get current() { return typeof document === "undefined" ? null : document.querySelector(`[data-k-ref="${value.id}"]`) } }
+  if (value.type === "ref") return { get current() { return typeof document === "undefined" || active?.() === false ? null : document.querySelector(`[data-k-ref="${value.id}"]`) } }
   if (globalThis.__KUDZU_CAPTURE_STATE__ && value.type === "state") return getState?.(value.id)
   if (globalThis.__KUDZU_CAPTURE_SETTER__ && value.type === "setter") return next => {
     if (!setState) throw new Error("Captured state setter is not available in this context")
@@ -10,20 +10,20 @@ export function deserialize(value, getState, setState) {
   }
   if (value.type === "array") {
     const array = []
-    for (const [index, entry] of value.value.entries()) defineCapture(array, String(index), entry, getState, setState)
+    for (const [index, entry] of value.value.entries()) defineCapture(array, String(index), entry, getState, setState, active)
     return array
   }
   if (value.type === "object") {
     const object = value.nullPrototype ? Object.create(null) : {}
-    for (const [key, entry] of value.value) defineCapture(object, key, entry, getState, setState)
+    for (const [key, entry] of value.value) defineCapture(object, key, entry, getState, setState, active)
     return object
   }
   return value
 }
 
-function defineCapture(target, key, entry, getState, setState) {
+function defineCapture(target, key, entry, getState, setState, active) {
   const descriptor = globalThis.__KUDZU_CAPTURE_STATE__ && entry?.type === "state" && getState
     ? { get: () => getState(entry.id) }
-    : { value: deserialize(entry, getState, setState), writable: true }
+    : { value: deserialize(entry, getState, setState, active), writable: true }
   Object.defineProperty(target, key, { ...descriptor, enumerable: true, configurable: true })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.8.30",
+  "version": "0.8.31",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,7 @@
     "benchmark": "node test/performance.mjs",
     "benchmark:keyed": "node test/keyed-performance.mjs",
     "benchmark:commerce": "node test/commerce-build-performance.mjs",
+    "benchmark:native": "node test/native-performance.mjs",
     "prepublishOnly": "npm run check && npm test",
     "deploy": "wrangler deploy",
     "preview": "wrangler dev"