@kudzujs/core 0.16.5 → 0.16.6

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.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.
+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.
 
 ### 0.10.0 Through 0.21.x: Application Capability Release Train
 

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.6 Owner-Triggered Capability Imports
+
+Measured 2026-08-29 on macOS arm64 with Node 24.14.0 and Chrome. The existing
+eager CodeMirror route owns 214,968 raw / 71,607 aggregate gzip B. Its guarded
+lazy counterpart initially owns 12,982 raw / 6,153 gzip B and defers 250,086
+raw / 80,890 gzip B, reducing initial gzip by 65,454 B (91.4%). Its static
+sibling remains complete HTML with zero JavaScript.
+
+Required Chrome proves zero initial deferred requests, one request on owner
+activation, mount, exact cleanup, cached remount without another request, 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 222.8 ms median. No browser runtime file or concept was
+added.
+
 ## 0.16.5 Bounded Navigation Cache
 
 Measured 2026-08-28 on Linux x64 with Node 24.14.0 and Chrome. Before the

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.5 - Bounded navigation cache.** Superseded navigations can no longer resurrect pruned prefetched documents, and the maintained endurance gate now covers cache races, route ownership, keyed state, dialogs, and external editors. Read the [release notes](./RELEASES.md#0165---bounded-navigation-cache), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.5), or follow the [architecture packet](./docs/next-architecture/README.md).
+**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).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,45 @@
 # Kudzu Releases
 
+## 0.16.6 - Owner-Triggered Capability Imports
+
+Kudzu 0.16.6 lets one guarded effect load a literal package dependency only
+when its owner activates, using native ESM code splitting without a loader or
+component runtime.
+
+### Changed in 0.16.6
+
+- Accepts one literal bare-package `import()` directly inside an inline
+  synchronous `useEffect` with a direct dependency-state early-return guard.
+- Keeps relative, URL, render-time, event-handler, indirect, async-effect, and
+  multiple dynamic imports unsupported with source diagnostics.
+- Removes the package edge from build-time component execution and preserves it
+  only in the route-owned effect bundle.
+- Reports deferred handler closure separately as `handlers.lazyChunks` while
+  retaining exact route ownership and shared-chunk accounting.
+- Uses native module-map deduplication across owner remounts and exact effect
+  cleanup on owner and document release.
+- Adds no loader, retry cache, component runtime, React, VDOM, hydration, or
+  retained browser component tree.
+- Updates `create-kudzu@0.1.131` to generate projects on
+  `@kudzujs/core@^0.16.6`.
+
+### Output And Browser Evidence
+
+- The eager CodeMirror route owns 214,968 raw / 71,607 gzip bytes. The lazy
+  route initially owns 12,982 raw / 6,153 gzip bytes and defers 250,086 raw /
+  80,890 gzip bytes, reducing initial gzip by 65,454 bytes (91.4%).
+- Required Chrome proves zero initial chunk requests, one activation request,
+  package mount, exact owner cleanup, cached remount without another request,
+  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.6
+```
+
 ## 0.16.5 - Bounded Navigation Cache
 
 Kudzu 0.16.5 prevents superseded enhanced navigations from resurrecting pruned

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.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.
+[`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.
 
 ## Required Invariants
 

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

@@ -1333,6 +1333,16 @@ runtime files, and public APIs change by zero; one test fixture and one browser
 harness were added. This evidence changed no production source by itself and was
 published with the later stale-prefetch fix in the actual `0.16.5` patch.
 
+Release transaction complete at commit
+`f23db7403060df7615b684f3a4a39781e600ed23` and immutable tag `v0.16.5`.
+CI run `33235364419` passed Node 22, required-Chrome Node 24, and the Cloudflare
+deployment. The GitHub release is
+[`v0.16.5`](https://github.com/kudzujs/kudzu/releases/tag/v0.16.5), and publish
+workflow run `33235705347` published and verified `@kudzujs/core@0.16.5` and
+`create-kudzu@0.1.130`. A fresh registry-only install imported core, confirmed
+both exact package versions, generated a two-route application, and passed its
+TypeScript and production build check.
+
 ## `0.17.x`: Long-Lived Applications
 
 ### `0.17.0`: WebSocket Application Journey
@@ -1437,6 +1447,37 @@ retain the public `0.16.x` version line.
   measured.
 - **Done condition:** every eager dependency has a structural reason.
 
+**Result:** closed by the existing RouteBuildRecord and artifact report. A
+test-only collector builds the greenfield project, real CodeMirror editor, four
+separate Apache Answer reductions, and Memos outline reduction: seven fixtures
+and 25 routes total. It joins each route's source page to HTML, runtime entries
+and requirements, handler entries/chunks, Worker entries/chunks, and styles,
+then records exact raw/gzip bytes and SHA-256 values. Every generated JavaScript
+file has at least one route owner, every direct module script has one matching
+`modulepreload`, and every static control owns zero JavaScript and zero preload.
+No measured fixture emits a shared chunk.
+
+The greenfield deploy is 45 files and 196,678 raw / 60,880 aggregate gzip
+bytes. Its project routes own 38,652-69,178 raw JavaScript bytes; `/login` owns
+12,093 raw bytes and `/help` owns zero. The editor route owns 214,968 raw /
+71,607 gzip bytes, including its 200,260 raw / 64,949 gzip CodeMirror handler;
+its static sibling owns zero. The Answer question reduction owns 32,022 raw /
+12,408 gzip bytes. Its route-shell static pages own zero while the two runtime
+parameter pages own 2,134 and 2,078 raw bytes. Answer auth routes own 25,684 and
+26,818 raw bytes with a zero-byte public sibling; authoring/admin routes own
+12,251 and 20,919 raw bytes with a zero-byte legal sibling. The Memos outline
+owns 14,701 raw / 7,044 gzip bytes and its static sibling owns zero.
+
+Current navigation prefetch remains structurally bounded: eligible same-origin
+group links prefetch on hover, focus, viewport proximity, or idle fallback;
+promises deduplicate, failures leave the cache, current/eligible URLs define the
+retained set, and the `0.16.5` revision check rejects stale navigation results
+before cache insertion. The report intentionally records emitted closure rather
+than esbuild input-byte attribution. Answer and Memos remain disconnected
+reductions, not whole-application claims. Semantic primitives, IR kinds,
+compiler passes, production compiler/runtime LOC, runtime concepts/files, and
+public APIs change by zero. No release is consumed.
+
 ### `0.18.1`: Bounded Lazy Capability Import
 
 - **Purpose:** permit one statically analyzable feature dependency to load only
@@ -1450,6 +1491,36 @@ retain the public `0.16.x` version line.
 - **Done condition:** the feature loader is capability-specific, not a component
   runtime.
 
+**Completion evidence:** one direct literal bare-package `import()` may remain
+inside an inline synchronous effect when its first statement is the exact
+dependency-state guard `if (!state) return`. The source graph, descriptor
+session, ModuleIR validation, build-module erasure, esbuild split graph, and
+route artifact report preserve that edge without adding a loader. Relative,
+URL, render-time, event, indirect, async-effect, unguarded, and multiple dynamic
+imports remain rejected. Failed native ESM evaluation remains visible through
+application-owned error state; same-document retry of the failed URL is not
+claimed because the browser module map cannot be reset without adding the
+loader forbidden by this packet.
+
+The CodeMirror-derived fixture initially requests no deferred chunk. Activation
+requests one chunk, mounts the editor, and owner release destroys it. Remount
+uses the browser module map without another request, and document disposal
+balances the second mount. The initial eager graph is 12,982 raw / 6,153 gzip
+bytes versus 214,968 raw / 71,607 gzip bytes for the existing eager editor;
+250,086 raw / 80,890 gzip bytes move to the deferred graph. Initial gzip falls
+by 65,454 bytes (91.4%), while the static sibling remains 0 B JavaScript.
+
+The packet adds no semantic primitive, compiler pass, public API, browser
+runtime concept/file, React, VDOM, hydration, retained component tree, or retry
+cache. It adds one validated `ImportIR` kind and additive
+`handlers.lazyChunks` reporting. Production compiler sources change by 76 added
+and 11 removed lines. The artifact collector now covers eight fixtures and 27
+routes with no ownerless JavaScript or preload mismatch. `npm run check`, 284
+required-Chrome tests, package smoke, and the maintained benchmark pass. The
+Worker graph remains 907 raw / 477 gzip bytes; the window graph remains 14,456
+raw / 6,160 gzip bytes, with a seven-build median of 222.8 ms. This packet ships
+as the actual `0.16.6` patch to retain the public `0.16.x` version line.
+
 ### `0.18.2`: Lazy Editor Journey
 
 - **Purpose:** apply `0.18.1` to the real editor.
@@ -1764,4 +1835,6 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.17.0` | Closed by existing layout effect ownership | Preserve project notification connect, keyed update, reconnect, stale rejection, offline recovery, retained navigation, and exact cleanup evidence. | No production change; no release consumed |
 | `0.17.1` | Closed by stop condition | Preserve independent effect ownership until three applications prove the complete shared transport and bounded replay contract. | Zero qualifying applications; no release consumed |
 | `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` | Active | Record exact current route and feature artifact ownership before adding lazy loading. | None |
+| `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 |

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.5` 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.0`; 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.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.
 
 ## 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.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.
+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.
 
-[`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.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.
+[`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.
 
 ## 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.0` Route And Feature Artifact Baseline 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.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.

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.0`; 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.2`; 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.130` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.5`.
+`create-kudzu@0.1.131` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.6`.
 
 ## Release Boundary
 

package/framework/compiler/descriptor-session.mjs

@@ -4,6 +4,7 @@ import { knownGlobalNames } from "./analysis/binding-index.mjs"
 import { bindingNames, isFunctionLike, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, unwrapExpression } from "./ast-helpers.mjs"
 import { generateCommandBehavior } from "./codegen/command-codegen.mjs"
 import { assertModuleIRReferences, createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerEffect, registerKeyedBlock, registerModuleHandler, registerSignal } from "./ir/module-ir.mjs"
+import { ownedLazyPackageImport } from "./source-graph.mjs"
 
 export function createSemanticArtifact(file) {
   return { componentAnalysis: createComponentAnalysis(file), moduleIR: createModuleIR(file) }
@@ -168,6 +169,17 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     const usedReducers = referencedReducerDispatches(expression.body, reducers, expression, indexedBindingIndex)
     const imports = [...referencedImportedBindings(expression, importBindings, indexedBindingIndex)].map(name => importBindings.get(name))
     imports.push(...[...usedReducers].map(name => reducers.get(name).import).filter(Boolean))
+    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")
+        dynamicImports.push({ kind: "dynamic", local: node.arguments[0].text, target: node.arguments[0].text, package: true })
+      }
+      ts.forEachChild(node, visitDynamicImports)
+    }
+    visitDynamicImports(expression)
+    if (dynamicImports.length > 1) throw new Error("An owned effect may contain only one dynamic package import")
+    imports.push(...dynamicImports)
     const captures = new Set([...allCaptures].filter(name => !importBindings.has(name) && !usedReducers.has(name)))
     registerClientImports(imports)
     const usedStates = referencedStateNames(expression.body, setters, expression, indexedBindingIndex)

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

@@ -24,6 +24,11 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
   indexed("EffectIR", moduleIR.effects)
   indexed("KeyedBlockIR", moduleIR.keyedBlocks)
   indexed("ImportIR", moduleIR.imports)
+  const dynamicImports = new Set()
+  for (const imported of moduleIR.imports) if (imported.kind === "dynamic") {
+    if (!imported.package || typeof imported.target !== "string" || !imported.target || imported.target.startsWith(".") || imported.target.startsWith("/") || /^[a-z][a-z\d+.-]*:/i.test(imported.target) || imported.local !== imported.target) throw new Error(`ImportIR ${imported.slot} has an invalid dynamic package target`)
+    dynamicImports.add(imported.slot)
+  }
   for (const action of moduleIR.sharedActions) slot(moduleIR.sharedStates, action.state, `SharedActionIR ${action.slot}`, "SharedStateIR")
   if (componentAnalysis) {
     indexed("Component owner", componentAnalysis.owners)
@@ -82,7 +87,10 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
     exported(handler, `HandlerIR ${handler.slot}`)
     for (const [index, command] of (handler.commands ?? []).entries()) slot(moduleIR.signals, command.signal, `HandlerIR ${handler.slot} command ${index}`, "SignalIR")
     for (const [index, signal] of (handler.signals ?? []).entries()) slot(moduleIR.signals, signal.signal, `HandlerIR ${handler.slot} signal ${index}`, "SignalIR")
-    for (const [index, imported] of (handler.imports ?? []).entries()) slot(moduleIR.imports, imported, `HandlerIR ${handler.slot} import ${index}`, "ImportIR")
+    for (const [index, imported] of (handler.imports ?? []).entries()) {
+      slot(moduleIR.imports, imported, `HandlerIR ${handler.slot} import ${index}`, "ImportIR")
+      if (dynamicImports.has(imported) && handler.role !== "effect") throw new Error(`HandlerIR ${handler.slot} dynamic import ${index} requires role "effect"`)
+    }
     for (const [index, capture] of (handler.captures ?? []).entries()) if (capture.symbol !== undefined) slot(moduleIR.symbols, capture.symbol, `HandlerIR ${handler.slot} capture ${index}`, "SymbolRef")
     for (const [index, action] of (handler.actions ?? []).entries()) slot(moduleIR.sharedActions, action, `HandlerIR ${handler.slot} action ${index}`, "SharedActionIR")
     if (handler.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, handler.keyedBlock, `HandlerIR ${handler.slot} keyed block`, "KeyedBlockIR")
@@ -90,7 +98,10 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
   for (const binding of moduleIR.bindings) {
     exported(binding, `BindingIR ${binding.slot}`)
     for (const [index, signal] of (binding.signals ?? []).entries()) slot(moduleIR.signals, signal, `BindingIR ${binding.slot} signal ${index}`, "SignalIR")
-    for (const [index, imported] of (binding.imports ?? []).entries()) slot(moduleIR.imports, imported, `BindingIR ${binding.slot} import ${index}`, "ImportIR")
+    for (const [index, imported] of (binding.imports ?? []).entries()) {
+      slot(moduleIR.imports, imported, `BindingIR ${binding.slot} import ${index}`, "ImportIR")
+      if (dynamicImports.has(imported)) throw new Error(`BindingIR ${binding.slot} cannot reference a dynamic import`)
+    }
     for (const [index, capture] of (binding.captures ?? []).entries()) if (capture.symbol !== undefined) slot(moduleIR.symbols, capture.symbol, `BindingIR ${binding.slot} capture ${index}`, "SymbolRef")
     if (binding.derived) {
       const derived = slot(moduleIR.derived, binding.derived.derived, `BindingIR ${binding.slot} derived value`, "DerivedIR")

package/framework/compiler/route-artifact-report.mjs

@@ -39,7 +39,8 @@ export function createRouteArtifactReport(records, {
       runtime: routeRuntimeEdges(record, capability, family, base, navigationAssets.get(record.route)),
       handlers: {
         entries: handlerEntries,
-        chunks: handlerOutputs.filter(output => !handlerEntries.includes(output))
+        chunks: handlerOutputs.eager.filter(output => !handlerEntries.includes(output)),
+        lazyChunks: handlerOutputs.lazy
       },
       workers,
       styles: [...record.artifacts.styles].sort()
@@ -47,7 +48,7 @@ export function createRouteArtifactReport(records, {
   }).sort((left, right) => left.route.localeCompare(right.route))
   const owners = new Map()
   for (const route of routes) {
-    for (const path of [...route.handlers.chunks, ...route.workers.flatMap(worker => worker.chunks)]) {
+    for (const path of [...route.handlers.chunks, ...route.handlers.lazyChunks, ...route.workers.flatMap(worker => worker.chunks)]) {
       const paths = owners.get(path) ?? new Set()
       paths.add(route.route)
       owners.set(path, paths)
@@ -109,7 +110,7 @@ function outputGraph(metafile, outputDirectory, base) {
   for (const [output, metadata] of Object.entries(metafile.outputs)) {
     const absolute = resolve(output)
     const url = paths.get(absolute)
-    const imports = (metadata.imports ?? []).filter(entry => !entry.external).map(entry => paths.get(resolve(entry.path)) ?? paths.get(resolve(dirname(absolute), entry.path))).filter(Boolean)
+    const imports = (metadata.imports ?? []).filter(entry => !entry.external).map(entry => ({ path: paths.get(resolve(entry.path)) ?? paths.get(resolve(dirname(absolute), entry.path)), kind: entry.kind })).filter(entry => entry.path)
     graph.set(url, [...new Set(imports)].sort())
   }
   return graph
@@ -123,12 +124,20 @@ function outputUrl(output, outputDirectory, base) {
 
 function closure(entries, graph, requireEntries) {
   const visited = new Set()
-  const visit = output => {
-    if (visited.has(output)) return
+  const eager = new Set()
+  const lazy = new Set()
+  const visit = (output, deferred = false) => {
+    const key = `${Number(deferred)}:${output}`
+    if (visited.has(key)) return
+    visited.add(key)
     if (requireEntries && !graph.has(output)) throw new Error(`Bundled handler entry was not emitted: ${output}`)
-    visited.add(output)
-    for (const imported of graph.get(output) ?? []) visit(imported)
+    if (deferred && !eager.has(output)) lazy.add(output)
+    else {
+      eager.add(output)
+      lazy.delete(output)
+    }
+    for (const imported of graph.get(output) ?? []) visit(imported.path, deferred || imported.kind === "dynamic-import")
   }
   for (const entry of entries) visit(entry)
-  return [...visited].sort()
+  return { eager: [...eager].sort(), lazy: [...lazy].sort() }
 }

package/framework/compiler/source-compiler.mjs

@@ -22,6 +22,7 @@ import { createReactMigrationPass, reactMemoExpression } from "./react-migration
 import { normalizeRenderControlFlow } from "./render-control-pass.mjs"
 import { createRouterPass } from "./router-pass.mjs"
 import { createProjectSession } from "./project-session.mjs"
+import { ownedLazyPackageImport } from "./source-graph.mjs"
 import { createZustandPass } from "./zustand-pass.mjs"
 
 export function createSourceCompiler(project) {
@@ -2029,6 +2030,19 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         if (calculationEntries.length && (calculationEntries.length !== 1 || dependencyEntries.length !== 1)) effectFail(dependencies, "useEffect() selected calculation fields must be the only dependency")
         if (!effectOwner) fail(node, "useEffect() cannot be used outside a Kudzu component")
         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)
+          else ts.forEachChild(current, collectLazyPackageImports)
+        }
+        collectLazyPackageImports(callback)
+        if (lazyPackageImports.length) {
+          const guard = callback.body.statements[0]
+          const condition = guard && ts.isIfStatement(guard) ? unwrapExpression(guard.expression) : undefined
+          const guardedState = condition && ts.isPrefixUnaryExpression(condition) && condition.operator === ts.SyntaxKind.ExclamationToken && ts.isIdentifier(unwrapExpression(condition.operand)) ? unwrapExpression(condition.operand).text : undefined
+          const exits = guard && ts.isIfStatement(guard) && ts.isReturnStatement(guard.thenStatement) && !guard.thenStatement.expression
+          if (lazyPackageImports.length !== 1 || !guardedState || !exits || !ordinaryDependencies.some(dependency => dependency.text === guardedState)) effectFail(lazyPackageImports[0], "Dynamic package import requires one direct dependency-state guard as the first effect statement")
+        }
         const cleanupSubstitutions = new Map()
         const collectNamedCleanups = current => {
           if (current !== callback && isFunctionLike(current)) return
@@ -2120,7 +2134,13 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           factory.createSpreadAssignment(evaluator.descriptor),
           factory.createPropertyAssignment("field", factory.createStringLiteral(dependencyEntries[index].field))
         ]) : factory.createNull()) : []
-        const buildCallback = [...packageBindings].some(([name]) => referenceIdentifiers(callback, name).length)
+        let hasLazyPackageImport = false
+        const findLazyPackageImport = current => {
+          if (ownedLazyPackageImport(current)) hasLazyPackageImport = true
+          else ts.forEachChild(current, findLazyPackageImport)
+        }
+        findLazyPackageImport(callback)
+        const buildCallback = hasLazyPackageImport || [...packageBindings].some(([name]) => referenceIdentifiers(callback, name).length)
           ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createBlock([], false))
           : callback
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [

package/framework/compiler/source-graph.mjs

@@ -21,6 +21,7 @@ export function createSourceGraph(root) {
       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
         throw sourceNodeError(node, sourceFile, `Dynamic import ${specifier} is not supported in ordinary source modules`)
       }
       ts.forEachChild(node, rejectDynamicImports)
@@ -44,6 +45,18 @@ export function createSourceGraph(root) {
   return { ordinaryRuntimeDependencies, parseSourceFile, resolveSourceImport, runtimeModuleReference }
 }
 
+export function ownedLazyPackageImport(node) {
+  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)
+  }
+  return false
+}
+
 export function runtimeModuleReference(node) {
   if (ts.isExportDeclaration(node)) return !node.isTypeOnly && (!node.exportClause || !ts.isNamedExports(node.exportClause) || node.exportClause.elements.some(entry => !entry.isTypeOnly))
   const clause = node.importClause

package/package.json

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