@kudzujs/core 0.16.6 → 0.16.7

package/MIGRATION_ROADMAP.md

@@ -51,7 +51,7 @@ Syntax compatibility does not mean reproducing React wholesale. Kudzu accepts th
 - stronger JavaScript failure resilience;
 - no remaining material large-route build-scaling weakness.
 
-The completed 0.9 plan defines the cross-framework comparison and release gate. The active application packet is `0.18.2` in the capability release plan below. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
+The completed 0.9 plan defines the cross-framework comparison and release gate. The active application packet is `0.18.3` in the capability release plan below. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
 
 ### 0.10.0 Through 0.21.x: Application Capability Release Train
 
@@ -128,7 +128,7 @@ The following are available building blocks, not future vertical roadmaps:
 - `useState`, independent repeated non-keyed child state with conditional mount ownership, reduced relative-imported `useReducer`, direct dispatch specialization, and reduced Zustand-shaped shared state lowered through package-neutral shared-state/action IR and proven by migration fixtures.
 - Mount and dependency effects with cleanup, route/layout lifetimes, conditional/keyed ownership, stale-write isolation, and relative TypeScript Workers.
 - Direct browser-only package references in inline effect setup/cleanup callbacks bundle into route-owned effect ESM without entering build-time component execution or static sibling output.
-- A CodeMirror-class editor may retain one package instance across one mount effect and later dependency update effects through a null-initialized ref with one direct setup assignment and null-reset cleanup. The ref lowers to existing owner-scoped object state; package DOM, bidirectional updates, errors, accessibility, conditional disposal, and fresh remount require no widget runtime or React island.
+- A CodeMirror-class editor may retain one package instance across one mount or guarded lazy activation effect and later dependency update effects through a null-initialized ref with one direct setup assignment and null-reset cleanup. The lazy form assigns only inside the literal package import's direct `.then()` callback. The ref lowers to existing owner-scoped object state; package DOM, bidirectional updates, errors, accessibility, conditional disposal, and fresh remount require no loader, widget runtime, or React island.
 - A Chart.js-class canvas instance uses the same retained-handle contract. One mount effect owns construction, resize listeners, and destroy/reset cleanup; later data effects read the instance without replacing it. Enhanced route disposal and fresh remount require no chart runtime or package-specific IR.
 - A SortableJS-class drag engine may temporarily move keyed DOM during a gesture, but Kudzu state remains the durable order owner. The package callback restores authored DOM order before one immutable state reorder; existing keyed reconciliation then preserves row identity. Keyboard controls use the same state operation, package disposal is effect-owned, and static siblings exclude the package.
 - Keyed local-state and imported static collections, pure selectors, nested direct-property lists, recursive and directly exported row specialization, static/keyed component reuse, analyzable specialized prop spreads, serializable literal defaults, direct intrinsic rest forwarding, forwarded JSX children, latest-item handlers, row state/effects/refs, and stable keyed identity.

package/PERFORMANCE.md

@@ -2,6 +2,21 @@
 
 Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, `npm run benchmark:module-cache`, `npm run benchmark:project-navigation`, `npm run benchmark:project-state`, and `npm run benchmark:source-scale` 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.16.7 Lazy Retained Editor Lifecycle
+
+Measured 2026-08-30 on macOS arm64 with Node 24.14.0 and Chrome. The existing
+eager real CodeMirror editor owns 214,968 raw / 71,607 aggregate gzip B. The
+lazy retained journey initially owns 15,896 raw / 7,230 gzip B and defers
+250,086 raw / 80,890 gzip B, reducing initial gzip by 64,377 B (89.9%). Its
+static sibling remains complete HTML with zero JavaScript.
+
+Required Chrome proves zero initial deferred requests, one activation request,
+bidirectional updates, accessible update-error recovery, retained editor DOM,
+conditional cleanup, cached fresh remount, and document disposal. The maintained
+Worker benchmark remains 907 raw / 477 gzip B for the Worker graph and 14,456
+raw / 6,160 gzip B for the window graph. Seven clean builds record a 230.5 ms
+median. No browser runtime file or concept was added.
+
 ## 0.16.6 Owner-Triggered Capability Imports
 
 Measured 2026-08-29 on macOS arm64 with Node 24.14.0 and Chrome. The existing

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.16.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.16.6 - Owner-triggered capability imports.** One literal package dependency may stay out of the initial route graph until its guarded effect owner activates, while static siblings remain JavaScript-free. Read the [release notes](./RELEASES.md#0166---owner-triggered-capability-imports), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.6), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.16.7 - Lazy retained editor lifecycle.** A real CodeMirror editor now loads on first activation while preserving bidirectional updates, accessible error recovery, retained identity, and exact disposal. Read the [release notes](./RELEASES.md#0167---lazy-retained-editor-lifecycle), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.7), 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,47 @@
 # Kudzu Releases
 
+## 0.16.7 - Lazy Retained Editor Lifecycle
+
+Kudzu 0.16.7 applies owner-triggered package loading to the real retained
+CodeMirror editor journey without losing update, error, identity, or cleanup
+behavior.
+
+### Changed in 0.16.7
+
+- Lets one retained `useRef(null)` package handle receive its single setup
+  assignment inside the direct `.then()` callback of a guarded literal package
+  import.
+- Reuses existing owner-scoped retained state across the lazy activation effect
+  and later read-only update effects.
+- Keeps indirect promise callbacks, multiple assignments, update-effect writes,
+  attached refs, missing null-reset cleanup, and broader dynamic imports
+  unsupported.
+- Preserves application-to-editor and editor-to-application updates, accessible
+  package errors and recovery, retained DOM identity, conditional disposal, and
+  fresh state on remount.
+- Uses the native browser module map for cached remount and adds no loader,
+  resource registry, widget runtime, React, VDOM, hydration, or retained browser
+  component tree.
+- Updates `create-kudzu@0.1.132` to generate projects on
+  `@kudzujs/core@^0.16.7`.
+
+### Output And Browser Evidence
+
+- The eager real editor owns 214,968 raw / 71,607 gzip bytes. The lazy journey
+  initially owns 15,896 raw / 7,230 gzip bytes and defers 250,086 raw / 80,890
+  gzip bytes, reducing initial gzip by 64,377 bytes (89.9%).
+- Required Chrome proves zero initial chunk requests, one on-demand request,
+  bidirectional updates, accessible failure recovery, retained identity, exact
+  conditional cleanup, cached fresh remount, and document cleanup.
+- The static sibling emits zero JavaScript. The maintained Worker and window
+  graphs remain 907 raw / 477 gzip bytes and 14,456 raw / 6,160 gzip bytes.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.7
+```
+
 ## 0.16.6 - Owner-Triggered Capability Imports
 
 Kudzu 0.16.6 lets one guarded effect load a literal package dependency only

package/docs/next-architecture/README.md

@@ -15,7 +15,7 @@ The completed `0.9.0` milestone is recorded in [`0.9-semantic-compression.md`](.
 
 [`1.0-large-application-compatibility-audit.md`](./1.0-large-application-compatibility-audit.md) records the first post-0.9 probes against Memos, Apache Answer, and Actual Budget. The audit finds that reduced slices build but whole-application source retention and behavior parity do not yet pass.
 
-[`application-capability-release-plan.md`](./application-capability-release-plan.md) is the authoritative post-0.9 execution queue, currently at `0.18.2`. It assigns one application-capability section to each minor release and one independently accepted evidence packet to each patch release from `0.10.0` through the `1.0.0` gate. It supersedes the provisional 0.10/0.11/0.12 tool-first ordering in the completed 0.9 handoff without rewriting that historical record.
+[`application-capability-release-plan.md`](./application-capability-release-plan.md) is the authoritative post-0.9 execution queue, currently at `0.18.3`. It assigns one application-capability section to each minor release and one independently accepted evidence packet to each patch release from `0.10.0` through the `1.0.0` gate. It supersedes the provisional 0.10/0.11/0.12 tool-first ordering in the completed 0.9 handoff without rewriting that historical record.
 
 ## Required Invariants
 

package/docs/next-architecture/application-capability-release-plan.md

@@ -1531,6 +1531,36 @@ as the actual `0.16.6` patch to retain the public `0.16.x` version line.
 - **Done condition:** initial route bytes fall by the exact deferred package
   graph without losing behavior.
 
+**Completion evidence:** a real retained CodeMirror editor now begins closed and
+uses the `0.18.1` guarded literal package edge for its mount. The existing
+effect-private-ref normalization recognizes its one direct `.then()` assignment
+as the retained setup write, lowers the handle to owner-scoped state, and leaves
+later value effects read-only. Indirect callbacks, repeated writes, attached
+refs, update-effect writes, missing null-reset cleanup, and broader dynamic
+imports retain diagnostics. Package evaluation remains entirely in browser
+effect ESM.
+
+Required Chrome records zero chunk requests before activation and one afterward.
+It proves initial content and accessible name, application-to-editor and
+editor-to-application updates, retained DOM identity, authored update failure
+and recovery, exact conditional disposal, fresh `Alpha` state on remount, no
+second package request, and final document disposal. Native ESM evaluation
+failure retry remains outside this packet as recorded in `0.18.1`.
+
+The eager editor owns 214,968 raw / 71,607 gzip bytes. The lazy retained editor
+initially owns 15,896 raw / 7,230 gzip bytes and defers 250,086 raw / 80,890 gzip
+bytes, reducing initial gzip by 64,377 bytes (89.9%). Its static sibling remains
+0 B JavaScript. The artifact collector covers nine fixtures and 29 routes with
+no ownerless JavaScript or preload mismatch.
+
+The packet adds no semantic primitive, IR kind, compiler pass, public API,
+browser runtime concept/file, loader, resource registry, or widget runtime. One
+existing normalization pass changes by 15 added and four removed production
+lines. `npm run check`, 285 required-Chrome tests, package smoke, and the
+maintained benchmark pass. Worker and window graphs remain 907 raw / 477 gzip
+and 14,456 raw / 6,160 gzip bytes; the seven-build median is 230.5 ms. This
+packet ships as the actual `0.16.7` patch to retain the public `0.16.x` line.
+
 ### `0.18.3`: Shared Chunks And Prefetch Policy
 
 - **Purpose:** avoid duplicate large feature graphs and define optional preload.
@@ -1837,4 +1867,5 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.17.2` | Released as `0.16.5` | Preserve stale-prefetch rejection and bounded document, state, resource, listener, DOM, and external-instance ownership. | Patch release retained the `0.16.x` public version line |
 | `0.18.0` | Closed by existing artifact reporting | Preserve exact route/source ownership, bytes, hashes, preload equality, zero-JavaScript controls, and bounded prefetch policy. | No production change; no release consumed |
 | `0.18.1` | Released as `0.16.6` | Preserve one guarded literal package edge, native module-map deduplication, exact owner cleanup, deferred artifact ownership, and static exclusion. | Patch release retained the `0.16.x` public version line |
-| `0.18.2` | Active | Apply the bounded edge to the retained editor mount/update/dispose journey without broadening dynamic imports. | None |
+| `0.18.2` | Released as `0.16.7` | Preserve on-demand retained editor mount, bidirectional updates, failure recovery, identity, exact cleanup, cached fresh remount, and static exclusion. | Patch release retained the `0.16.x` public version line |
+| `0.18.3` | Active | Measure shared deferred graphs and choose the smallest evidence-backed prefetch policy. | None |

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.6` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The active application packet is `0.18.2`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.16.7` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The active application packet is `0.18.3`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 

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

@@ -2,9 +2,9 @@
 
 ## Status
 
-Completed compiler-foundation record and longer-term plan after `0.8.35`. The [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) execution queue is complete. The active queue for current work is [`application-capability-release-plan.md`](./application-capability-release-plan.md) at packet `0.18.2`. This document does not mark any remaining 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.
+Completed compiler-foundation record and longer-term plan after `0.8.35`. The [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) execution queue is complete. The active queue for current work is [`application-capability-release-plan.md`](./application-capability-release-plan.md) at packet `0.18.3`. This document does not mark any remaining 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 the product authority for product invariants and fixture-driven feature selection. [`application-capability-release-plan.md`](./application-capability-release-plan.md) is authoritative for current work order and evidence at packet `0.18.2`; this plan retains the completed foundation, deferred program, and long-term production gates. If implementation evidence changes either boundary, update the relevant document before broadening a patch.
+[`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains the product authority for product invariants and fixture-driven feature selection. [`application-capability-release-plan.md`](./application-capability-release-plan.md) is authoritative for current work order and evidence at packet `0.18.3`; this plan retains the completed foundation, deferred program, and long-term production gates. If implementation evidence changes either boundary, update the relevant document before broadening a patch.
 
 ## Product Outcome
 
@@ -483,4 +483,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-All listed foundation and `0.9` slices are complete. Current work continues at `0.18.2` Lazy Editor Journey under the [`application-capability-release-plan.md`](./application-capability-release-plan.md); keep ResourceIR limited to qualifying independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.
+All listed foundation and `0.9` slices are complete. Current work continues at `0.18.3` Shared Chunks And Prefetch Policy under the [`application-capability-release-plan.md`](./application-capability-release-plan.md); keep ResourceIR limited to qualifying independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.

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.62` are completed scopes represented by package/release records. The `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md), currently at `0.18.2`; that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
+This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records. The `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md), currently at `0.18.3`; that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
 
 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.
 
@@ -66,7 +66,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 
 ## Generator Versions
 
-`create-kudzu@0.1.131` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.6`.
+`create-kudzu@0.1.132` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.7`.
 
 ## Release Boundary
 

package/framework/compiler/effect-private-ref-pass.mjs

@@ -1,5 +1,6 @@
 import ts from "typescript"
 import { effectReturns, importDeclarationNames, isNodeWithin, isShadowedIdentifier, nearestFunction, referenceIdentifiers, referencesIdentifier, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
+import { ownedLazyPackageImport } from "./source-graph.mjs"
 
 export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
     const frameCall = (node, name) => ts.isCallExpression(node) && (
@@ -22,6 +23,16 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
       if (isNegated) condition = unwrapExpression(condition.operand)
       return isNegated === negated && currentAccess(condition, name)
     }
+    const containsLazyImport = node => {
+      if (ownedLazyPackageImport(node)) return true
+      let found = false
+      ts.forEachChild(node, child => { if (!found) found = containsLazyImport(child) })
+      return found
+    }
+    const directLazyImportCallback = (callback, effectCallback) => {
+      const call = callback?.parent
+      return (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) && ts.isCallExpression(call) && call.arguments[0] === callback && ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === "then" && ownedLazyPackageImport(unwrapExpression(call.expression.expression)) && isNodeWithin(callback, effectCallback)
+    }
     const hasUseRefImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && ["react", "@kudzujs/core"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useRef"))
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && ["react", "@kudzujs/core"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
     const hasUseStateImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && ["react", "@kudzujs/core"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useState"))
@@ -73,8 +84,8 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
         const callbacks = owners.map(effect => effect.arguments[0])
         const directCallbacks = callbacks.every(callback => (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) && ts.isBlock(callback.body))
         const everyAccessOwned = accesses.every(access => callbacks.filter(callback => isNodeWithin(access, callback)).length === 1)
-        const mountEffects = owners.filter(effect => ts.isArrayLiteralExpression(effect.arguments[1]) && !effect.arguments[1].elements.length)
-        const updateEffects = owners.filter(effect => ts.isArrayLiteralExpression(effect.arguments[1]) && effect.arguments[1].elements.length)
+        const mountEffects = owners.filter(effect => ts.isArrayLiteralExpression(effect.arguments[1]) && (!effect.arguments[1].elements.length || containsLazyImport(effect.arguments[0])))
+        const updateEffects = owners.filter(effect => !mountEffects.includes(effect))
         if (owners.length >= 2 && directCallbacks && everyAccessOwned && mountEffects.length === 1 && updateEffects.length === owners.length - 1 && owners[0] === mountEffects[0]) {
           const mount = mountEffects[0]
           const callback = mount.arguments[0]
@@ -85,7 +96,7 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
           const cleanupWrites = cleanup ? writes.filter(access => isNodeWithin(access, cleanup)) : []
           const setupStatement = setupWrites[0]?.parent.parent
           const cleanupStatement = cleanupWrites[0]?.parent.parent
-          const directSetup = setupWrites.length === 1 && ts.isExpressionStatement(setupStatement) && setupStatement.parent === callback.body && unwrapExpression(setupWrites[0].parent.right).kind !== ts.SyntaxKind.NullKeyword
+          const directSetup = setupWrites.length === 1 && ts.isExpressionStatement(setupStatement) && (setupStatement.parent === callback.body || directLazyImportCallback(nearestFunction(setupWrites[0]), callback)) && unwrapExpression(setupWrites[0].parent.right).kind !== ts.SyntaxKind.NullKeyword
           const directCleanup = cleanup && ts.isBlock(cleanup.body) && cleanupWrites.length === 1 && ts.isExpressionStatement(cleanupStatement) && cleanupStatement.parent === cleanup.body && unwrapExpression(cleanupWrites[0].parent.right).kind === ts.SyntaxKind.NullKeyword
           const updateWrites = mutations.some(access => updateEffects.some(effect => isNodeWithin(access, effect.arguments[0])))
           if (directSetup && directCleanup && !updateWrites) {
@@ -96,7 +107,7 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
             return
           }
         }
-        if (owners.length >= 2) throw sourceNodeError(node, sourceFile, "Retained instance refs require one empty-dependency mount effect with one direct assignment and null-reset cleanup followed by read-only dependency effects")
+        if (owners.length >= 2) throw sourceNodeError(node, sourceFile, "Retained instance refs require one empty-dependency mount effect or guarded lazy activation effect with one direct assignment and null-reset cleanup followed by read-only dependency effects")
       }
       if (!frameAssignments.length) {
         const callback = effects.length === 1 ? effects[0].arguments[0] : undefined

package/package.json

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