@kudzujs/core 0.16.6 → 0.16.8

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.19.0` 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,36 @@
 
 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.8 Shared Lazy Capability Graph
+
+Measured 2026-08-31 on Linux x64 with Node 24.14.0 and Chrome. Two route owners
+share one deferred CodeMirror chunk measuring 250,086 raw / 80,890 aggregate
+gzip B. Their eager graphs are 21,599 raw / 9,466 gzip B and 21,609 raw / 9,468
+gzip B. The static sibling remains complete HTML with zero JavaScript.
+
+Required Chrome proves zero deferred requests before interaction, one request on
+the first owner, no navigation-triggered prefetch, no duplicate request for the
+second owner, and exact owner/document cleanup. Native ESM supplies the
+document-lifetime cache; no loader, prefetch registry, cache, or runtime concept
+was added. 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 696.6 ms median on this loaded host; timing is not compared.
+
+## 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.8 - Shared lazy capability graphs.** Multiple route owners now share one interaction-triggered CodeMirror graph, with lexical ownership validation and no loader, cache, or eager prefetch. Read the [release notes](./RELEASES.md#0168---shared-lazy-capability-graphs), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.8), 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,82 @@
 # Kudzu Releases
 
+## 0.16.8 - Shared Lazy Capability Graphs
+
+Kudzu 0.16.8 shares one deferred package graph across route owners while
+keeping loading interaction-triggered and ownership validation lexical.
+
+### Changed in 0.16.8
+
+- Records one deferred CodeMirror chunk as shared by both route owners without
+  duplicating its package graph.
+- Keeps the shared chunk out of route HTML, module preload, navigation prefetch,
+  and static siblings until an owner activates.
+- Uses the native browser module map for document-scoped deduplication and adds
+  no loader, prefetch registry, cache, or browser runtime.
+- Resolves lazy `useEffect` ownership through lexical imports so a local
+  same-named function cannot bypass ordinary dynamic-import diagnostics.
+- Preserves exact owner cleanup; native in-flight imports remain non-cancellable
+  and late callbacks cannot mount after disposal.
+- Updates `create-kudzu@0.1.133` to generate projects on
+  `@kudzujs/core@^0.16.8`.
+
+### Output And Browser Evidence
+
+- Both owners share one 250,086 raw / 80,890 gzip byte deferred chunk. Their
+  eager graphs are 21,599 raw / 9,466 gzip and 21,609 raw / 9,468 gzip bytes.
+- Required Chrome proves zero initial requests, one first-owner request, no
+  route-prefetch request, no second-owner duplicate, and exact 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.8
+```
+
+## 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.19.0`. 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.
@@ -1540,6 +1570,37 @@ as the actual `0.16.6` patch to retain the public `0.16.x` version line.
 - **Done condition:** policy minimizes unused transfer while meeting accepted
   interaction latency.
 
+**Completion evidence:** two enhanced-navigation route owners now use one
+deferred CodeMirror graph. Existing multi-entry esbuild splitting emits one
+250,086 raw / 80,890 gzip byte chunk, and the existing artifact report records
+that exact lazy path as shared by `/` and `/second`. Their eager graphs remain
+21,599 raw / 9,466 gzip and 21,609 raw / 9,468 gzip bytes. Neither route HTML
+preloads the deferred chunk, navigation document prefetch does not request it,
+and the static sibling remains complete HTML with 0 B JavaScript.
+
+Required Chrome proves zero requests before interaction, one request when the
+first owner activates, exact disposal, no route-triggered request, and no second
+request when the second owner activates. The selected policy is therefore no
+optional package preload: interaction calls native `import()` immediately, the
+browser module map deduplicates it for the document lifetime, and Kudzu owns no
+additional cache. Native ESM imports cannot be cancelled after request; owner
+cleanup invalidates the callback and prevents a late mount rather than claiming
+network cancellation.
+
+The released lazy-import gate is also hardened before closing the packet.
+`ownedLazyPackageImport()` now resolves the callback callee through the existing
+lexical binding index and accepts only named `useEffect` imports from React or
+Kudzu. A local function with the same text can no longer bypass the ordinary
+dynamic-import diagnostic. The packet adds no semantic primitive, IR kind,
+compiler pass, public API, runtime concept/file, loader, prefetch registry, or
+cache. Four existing compiler files change by 17 added and eight removed lines.
+The artifact collector covers ten fixtures and 32 routes. `npm run check`, 288
+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 loaded Linux host records a 696.6 ms seven-build median without a timing
+comparison. This packet ships as the actual `0.16.8` patch to retain the public
+`0.16.x` line.
+
 ## `0.19.x`: React Ecosystem Migration
 
 ### `0.19.0`: Compatibility Boundary And Inventory
@@ -1837,4 +1898,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` | Released as `0.16.8` | Preserve shared deferred ownership, interaction-only loading, native document module-map deduplication, exact owner cleanup, binding-aware import validation, and static exclusion. | Patch release retained the `0.16.x` public version line |

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.8` 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.19.0`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 
@@ -10,7 +10,7 @@ This maps the current `0.16.6` architecture, built on the completed `0.9.0` sema
 | Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler. Production builds use one session; development retains it across rebuilds. Omitted roots resolve from call-time CWD. |
 | Parsed module cache and symbols | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs) | Parses each unchanged source module once per ProjectSession and records source-local declaration/import/re-export sites. Stable ModuleSymbol records resolve direct, aliased, barrel, and `export *` exports with cycle and ambiguity checks; repeated resolutions are cached against their source dependencies, and normalization consumers locate the resolved SiteId in a fresh clone with independent parent links. |
 | Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()`, `buildWithSession()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. A retained session caches source results and pre-family route renders by page graph; successful builds alone replace that cache. |
-| Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. |
+| Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. A lazy package edge must resolve lexically to a named React or Kudzu `useEffect` import. |
 | 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, inclusive ancestry, effect-return, and source-location analysis. |

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.19.0`. 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.19.0`; 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.19.0` Compatibility Boundary And Inventory 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.19.0`; 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.133` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.8`.
 
 ## Release Boundary
 

package/framework/compiler/descriptor-session.mjs

@@ -172,7 +172,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     const dynamicImports = []
     const visitDynamicImports = node => {
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-        if (role !== "effect" || !ownedLazyPackageImport(node)) throw new Error("Dynamic package imports require one literal import() directly inside an inline owned effect")
+        if (role !== "effect" || !ownedLazyPackageImport(node, bindingIndex)) throw new Error("Dynamic package imports require one literal import() directly inside an inline owned effect")
         dynamicImports.push({ kind: "dynamic", local: node.arguments[0].text, target: node.arguments[0].text, package: true })
       }
       ts.forEachChild(node, visitDynamicImports)

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

@@ -1,7 +1,10 @@
 import ts from "typescript"
+import { createBindingIndex } from "./analysis/binding-index.mjs"
 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 bindingIndex = createBindingIndex(sourceFile)
     const frameCall = (node, name) => ts.isCallExpression(node) && (
       ts.isIdentifier(node.expression) && node.expression.text === name ||
       ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === "window" && node.expression.name.text === name
@@ -22,6 +25,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, bindingIndex)) 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), bindingIndex) && 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 +86,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 +98,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 +109,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/framework/compiler/source-compiler.mjs

@@ -2032,7 +2032,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         if (!ts.isBlock(callback.body)) effectFail(callback, "useEffect() callback must use a block body")
         const lazyPackageImports = []
         const collectLazyPackageImports = current => {
-          if (ownedLazyPackageImport(current)) lazyPackageImports.push(current)
+          if (ownedLazyPackageImport(current, bindingIndex)) lazyPackageImports.push(current)
           else ts.forEachChild(current, collectLazyPackageImports)
         }
         collectLazyPackageImports(callback)
@@ -2136,7 +2136,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         ]) : factory.createNull()) : []
         let hasLazyPackageImport = false
         const findLazyPackageImport = current => {
-          if (ownedLazyPackageImport(current)) hasLazyPackageImport = true
+          if (ownedLazyPackageImport(current, bindingIndex)) hasLazyPackageImport = true
           else ts.forEachChild(current, findLazyPackageImport)
         }
         findLazyPackageImport(callback)

package/framework/compiler/source-graph.mjs

@@ -1,5 +1,6 @@
 import { dirname, extname, join, relative, resolve } from "node:path"
 import ts from "typescript"
+import { createBindingIndex } from "./analysis/binding-index.mjs"
 import { sourceNodeError } from "./ast-helpers.mjs"
 
 export function createSourceGraph(root) {
@@ -17,11 +18,12 @@ export function createSourceGraph(root) {
 
   const ordinaryRuntimeDependencies = (file, sourceFile, sourceFiles, isStaticImport) => {
     const dependencies = []
+    const bindingIndex = createBindingIndex(sourceFile)
     const rejectDynamicImports = node => {
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
         const argument = node.arguments[0]
         const specifier = node.arguments.length === 1 && ts.isStringLiteralLike(argument) ? JSON.stringify(argument.text) : argument?.getText(sourceFile) ?? "<missing>"
-        if (ownedLazyPackageImport(node)) return
+        if (ownedLazyPackageImport(node, bindingIndex)) return
         throw sourceNodeError(node, sourceFile, `Dynamic import ${specifier} is not supported in ordinary source modules`)
       }
       ts.forEachChild(node, rejectDynamicImports)
@@ -45,14 +47,19 @@ export function createSourceGraph(root) {
   return { ordinaryRuntimeDependencies, parseSourceFile, resolveSourceImport, runtimeModuleReference }
 }
 
-export function ownedLazyPackageImport(node) {
+export function ownedLazyPackageImport(node, bindingIndex) {
   if (!ts.isCallExpression(node) || node.expression.kind !== ts.SyntaxKind.ImportKeyword || node.arguments.length !== 1 || !ts.isStringLiteral(node.arguments[0])) return false
   const target = node.arguments[0].text
   if (!target || target.startsWith(".") || target.startsWith("/") || /^[a-z][a-z\d+.-]*:/i.test(target)) return false
   for (let current = node.parent; current; current = current.parent) {
     if (!ts.isArrowFunction(current) && !ts.isFunctionExpression(current)) continue
     const call = current.parent
-    return ts.isCallExpression(call) && call.arguments[0] === current && ts.isIdentifier(call.expression) && call.expression.text === "useEffect" && !current.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)
+    if (!ts.isCallExpression(call) || call.arguments[0] !== current || !ts.isIdentifier(call.expression) || current.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) return false
+    const binding = bindingIndex.resolveReference(call.expression, node.getSourceFile())
+    const declaration = binding?.kind === "import" ? binding.declaration : undefined
+    const specifier = declaration?.parent
+    const importDeclaration = specifier?.parent?.parent?.parent
+    return Boolean(specifier && ts.isImportSpecifier(specifier) && (specifier.propertyName ?? specifier.name).text === "useEffect" && importDeclaration && ts.isImportDeclaration(importDeclaration) && ts.isStringLiteral(importDeclaration.moduleSpecifier) && ["react", "@kudzujs/core"].includes(importDeclaration.moduleSpecifier.text))
   }
   return false
 }

package/package.json

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