@kudzujs/core 0.8.20 → 0.8.21

package/PERFORMANCE.md

@@ -1,5 +1,29 @@
 # Performance Records
 
+## 0.8.21 Explicit Effect Ownership
+
+Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, and npm 11.18.0. Baseline tag `v0.8.20` at `7fb6e37` and the current `0.8.21` compiler candidate used the same local volume and identical installed dependencies.
+
+The candidate implementation patch over `v0.8.20` had SHA-256 `ac0b1921bbbfb72f45d9b53338bec96bf9ab3d1680446148dfd8548b871bcbe4`, produced by:
+
+```bash
+git diff --binary v0.8.20 -- framework/build.mjs framework/compiler/descriptor-session.mjs framework/compiler/effect-analysis.mjs framework/compiler/ir/module-ir.mjs framework/compiler/worker-compiler.mjs framework/core.d.ts | shasum -a 256
+```
+
+Both targets received one warm-up followed by seven clean `worker-effects` production builds in alternating round-robin order. Cleanup remained outside timing. The distributions overlap; the 1.02% lower candidate median does not establish a material change.
+
+| Target | Build median | Worker raw / gzip | Window raw / gzip |
+|---|---:|---:|---:|
+| 0.8.20 baseline | 255.6 ms | 907 B / 475 B | 12,148 B / 5,427 B |
+| 0.8.21 candidate | 253.0 ms | 907 B / 475 B | 12,148 B / 5,427 B |
+
+```text
+0.8.20: [253.2,263.4,276.5,255.6,251.3,252.1,266.1]
+0.8.21: [253.7,249.7,260.4,253.0,251.1,250.1,265.7]
+```
+
+The complete site `dist` and the `effect-dependencies`, `keyed-effects`, and `worker-effects` fixture output trees had identical file lists and bytes before release-content updates. The Worker graph and every window graph file were byte-identical, including the content-hashed Worker name. This measurement covers compiler clean-build startup and generated artifact size; lifecycle behavior remains covered by the complete effect, Worker, conditional, keyed, and navigation integration tests.
+
 ## 0.8.20 Explicit Keyed Ownership
 
 Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, and npm 11.18.0. Baseline `0.8.19` commit `c516173` and the current `0.8.20` compiler candidate used the same local volume and identical installed dependencies.

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.20 - Explicit keyed ownership.** Keyed collections now retain deterministic JSON-safe parent/child, selector, component-specialization, row state/ref, handler, and binding ownership while final DOM allocation remains unchanged. Read the [release notes](./RELEASES.md#0820---explicit-keyed-ownership), open the [release page](https://kudzujs.cloud/releases/0.8.20), or follow the [next architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.21 - Explicit effect ownership.** Effects now retain deterministic JSON-safe setup, cleanup, dependency, component/keyed ownership, source, and Worker-edge records while final route lifecycle allocation remains unchanged. Read the [release notes](./RELEASES.md#0821---explicit-effect-ownership), open the [release page](https://kudzujs.cloud/releases/0.8.21), or follow the [next 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,40 @@
 # Kudzu Releases
 
+## 0.8.21 - Explicit effect ownership
+
+Kudzu 0.8.21 completes the next Goal A source-analysis seam: every supported effect now registers deterministic JSON-safe setup, cleanup, dependency, ownership, source, and Worker-edge data before existing build-time rendering allocates concrete lifecycle IDs.
+
+### Changed in 0.8.21
+
+- EffectIR links setup to finalized HandlerIR and records cleanup, ordered signal and DerivedIR dependencies, subscriptions, dependency state snapshots, and keyed-item fields.
+- Component and keyed ownership retain lexical component provenance and KeyedBlockIR slots, including specialized imported rows.
+- Relative TypeScript Worker rewriting returns functional callback and edge results; rendered Worker emission derives only from EffectIR rather than a build-wide mutable reference array.
+- Transformed effect calls consume the registered EffectIR dependency and ownership record before final setup HandlerIR slot resolution.
+- Effect dependency classification and cleanup-owned browser resource validation moved to `compiler/effect-analysis.mjs`; transformer-wide component and keyed effect AST side tables were removed.
+- Mixed direct and derived dependencies create DerivedIR only for derived expressions while preserving authored dependency order.
+
+### Goal A boundary
+
+- `core.mjs` and the existing route plan remain authoritative for concrete route/layout/conditional/keyed effect IDs, mounting, stale-write invalidation, and cleanup order; ModuleIR does not duplicate RouteIR.
+- EffectIR owns source-analysis facts and Worker graph edges. Route-specific effect codegen continues to consume rendered descriptors without rediscovering TSX semantics.
+- No accepted syntax, public API, browser capability, VDOM, hydration, component rerender, or retained browser component tree was added.
+- Goal A continues with the `0.8.22` RouteIR, CapabilityIR, numeric-slot, and final architecture/output audit.
+
+### Validation
+
+- The complete suite passes 170/170 tests, including EffectIR JSON round-trip, mixed dependencies, imported keyed provenance, Worker rendered exclusion and `about:blank` replacement, conditional/navigation ownership, stale-write isolation, and cleanup.
+- `npm run check`, focused Node 22 compiler tests, and a Node 22 complete-site build pass.
+- Before release-content updates, the complete 135-page site plus `effect-dependencies`, `keyed-effects`, and `worker-effects` output trees were byte-identical to `v0.8.20`.
+- Worker and window graph files remain byte-identical. Seven interleaved clean builds measured a 253.0 ms candidate median against 255.6 ms for `v0.8.20`; raw arrays and provenance are recorded in `PERFORMANCE.md`.
+- A release-blocking architecture audit found no implementation or runtime-correctness blockers.
+- `create-kudzu` remains 0.1.101 because its unchanged template already accepts `@kudzujs/core@^0.8.15`.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.21
+```
+
 ## 0.8.20 - Explicit keyed ownership
 
 Kudzu 0.8.20 completes the next Goal A source-analysis boundary: keyed collection sites now finalize into deterministic JSON-safe ownership records before the existing build-time renderer allocates DOM identity and lifecycle state.

package/docs/next-architecture/README.md

@@ -6,7 +6,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 
 | Goal | Decision | Start condition |
 |---|---|---|
-| A: compiler foundation | `0.8.20` KeyedBlockIR ownership complete | Continue with `0.8.21` EffectIR ownership after the release boundary. |
+| A: compiler foundation | `0.8.21` EffectIR source-analysis seam complete | Continue with `0.8.22` RouteIR, CapabilityIR, and the architecture/output audit after the release boundary. |
 | B: optimization benchmarks | Deferred | Goal A complete and its output baseline recorded |
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the completed `0.8.20` keyed ownership boundary. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves code.
+This maps the EffectIR boundary prepared for `0.8.21`. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves code.
 
 ## Responsibility Map
 
@@ -13,14 +13,15 @@ This maps the completed `0.8.20` keyed ownership boundary. File and function nam
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
 | Pure collection language | [`framework/compiler/collection-analysis.mjs`](../../framework/compiler/collection-analysis.mjs) | Analyzes collection roots/selectors and serializes the allowed pure expression language used by lists and derived dependencies. |
-| Main semantic analysis | `framework/build.mjs`, `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, and keyed ownership results while still owning effect-lifetime side tables. |
+| Main semantic analysis | `framework/build.mjs`, `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, keyed, and effect ownership results. |
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Retains ordered JSON-safe owner and specialization records for state, setters, props, refs, IDs, direct signal links, and source provenance; AST identity remains private to its source-local session. |
-| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, imports, and client roots into ModuleIR. |
+| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, imports, and client roots into ModuleIR. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Supported command handlers specialize to JSON-safe ModuleIR, then emit the existing `__kBehavior` AST without changing route plans. |
 | Build module generation | `framework/build.mjs`, `compile()` | Runs TypeScript with the Kudzu transformer, writes build-executable modules to `.kudzu`, rejects surviving React/Router runtime references, and generates handler source when descriptors exist. |
 | Handler/evaluator lowering | [`framework/compiler/handler-lowering.mjs`](../../framework/compiler/handler-lowering.mjs) | Completes source-local callback/binding/list AST rewriting and diagnostics before the JSON-safe IR boundary. |
 | Handler module codegen | [`framework/compiler/handler-codegen.mjs`](../../framework/compiler/handler-codegen.mjs) | Renders finalized ordered imports and concatenates generated module-export source without TypeScript AST or semantic discovery. |
-| Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Validates the exact effect-owned Worker form, validates its relative graph, emits content-hashed ESM, and resolves placeholders only for rendered effects. |
+| Effect analysis | [`framework/compiler/effect-analysis.mjs`](../../framework/compiler/effect-analysis.mjs) | Classifies ordered signal, derived, and keyed-item dependencies and validates cleanup-owned browser resources before EffectIR registration. |
+| Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Returns functional Worker rewrite results and JSON-safe EffectIR edges, validates relative graphs, emits content-hashed ESM, and resolves placeholders only for rendered effects. |
 | Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns the serializable route plan and capability booleans. |
 | Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Purely folds rendered route plans and route facts into aggregate runtime/artifact requirements. |
 | Effect entry generation | [`framework/compiler/effect-codegen.mjs`](../../framework/compiler/effect-codegen.mjs) | Generates ordinary, dependency, owned, and navigable effect entries from rendered descriptors. |
@@ -58,7 +59,7 @@ The browser consumes static HTML first. State seeds and descriptors in that HTML
 ## Current Coupling To Remove
 
 - `createKudzuTransformer()` combines discovery, validation, specialization, descriptor registration, and transformed-source emission.
-- Effect ownership relationships and transient component rewrite indexes remain source-local AST indexes; handler, binding, derived, keyed, and component ownership now have explicit JSON-safe source results.
+- Transient component rewrite indexes remain source-local AST indexes; handler, binding, derived, keyed, effect, and component ownership now have explicit JSON-safe source results.
 - `build()` destructures a broad capability manifest into many booleans and performs artifact-specific source surgery.
 - Runtime specialization relies on exact source-string and regular-expression replacements in `framework/build.mjs`.
 - Route facts, rendered plans, artifact requirements, and emitted-file decisions are represented at adjacent but not fully explicit boundaries.

package/docs/next-architecture/goal-a-compiler-foundation.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-The `0.8.20` KeyedBlockIR ownership result is complete. Goal A continues with the planned `0.8.21` EffectIR seam while preserving accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
+The `0.8.21` EffectIR source-analysis seam is complete. Goal A continues with the planned `0.8.22` RouteIR, CapabilityIR, and architecture/output audit while preserving accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
 
 ## Target Boundaries
 
@@ -49,7 +49,7 @@ Existing representations are promoted rather than copied:
 | `HandlerIR` | Plain command data or a stable generated-module export reference. |
 | `BindingIR` | Promote existing binding descriptors. |
 | `DerivedIR` | Reuse the existing tagged Collection Expression IR. |
-| `EffectIR` | Replace effect AST side tables with one explicit result when that seam is ready. |
+| `EffectIR` | Records setup HandlerIR, cleanup, ordered signal/DerivedIR dependencies and subscriptions, component/keyed ownership, source provenance, and Worker edges. |
 | `KeyedBlockIR` | Promote the existing list descriptor after ownership analysis is explicit. |
 | `CapabilityIR` | Reuse the current pure route capability manifest. |
 
@@ -77,7 +77,7 @@ Analysis produces plain data:
 }
 ```
 
-The `0.8.20` source result adds deterministic KeyedBlockIR parent/child ownership, collection and selector references, complete specialization membership, row state/ref provenance, and keyed HandlerIR/BindingIR links beside the existing command, component, handler, binding, and derived results. Source-local keyed AST validation is consumed during lowering and does not cross this boundary. Initial values, final state IDs, and effect lifetime ownership join their explicit results in later planned patches; `core.mjs` remains authoritative for route allocation today.
+The `0.8.21` source result adds deterministic EffectIR setup HandlerIR links, cleanup, ordered dependencies and subscriptions, DerivedIR references, component/keyed ownership, source provenance, and Worker edges beside the existing command, component, handler, binding, derived, and KeyedBlockIR results. Source-local effect AST analysis is consumed during lowering and does not cross this boundary. Final route/layout/conditional/keyed effect IDs and lifetime allocation remain authoritative in `core.mjs`; the existing route plan is not duplicated in ModuleIR.
 
 Source codegen lowers that data through the existing build ABI:
 
@@ -89,7 +89,7 @@ __kBehavior([["add", count, 1]])
 
 ### Source Result
 
-One source-local result owns transformed source plus the sparse ModuleIR, generated handler/effect/binding/list evaluator source, client imports, Worker references, and explicit pass metadata. AST-bearing data is consumed inside analysis/codegen and does not become IR or cross-build state.
+One source-local result owns transformed source plus the sparse ModuleIR, generated handler/effect/binding/list evaluator source, client imports, and explicit pass metadata. Worker ownership is recorded as EffectIR edges; AST-bearing data is consumed inside analysis/lowering and does not become IR or cross-build state.
 
 ### Route Result
 
@@ -117,7 +117,7 @@ No generator may analyze TSX, invent runtime component abstractions, or broaden
 
 - One patch, one boundary, with no migration feature mixed in.
 - Extract only code whose callers and outputs are understood.
-- Replace AST side tables only when an explicit keyed result can preserve ownership and source diagnostics.
+- Replace AST side tables only when an explicit feature result can preserve ownership and source diagnostics.
 - Keep `build()` as orchestration; do not replace it with a service container or plugin framework.
 - Preserve current runtime files until their corresponding generator has artifact parity.
 - Treat deterministic byte changes as review items even when tests pass.

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.20` are completed scopes represented by package/release records; later rows remain planned until their package version and release record exist.
+This is an execution sequence, not release history. `0.8.16` through `0.8.21` are completed scopes represented by package/release records; later rows remain planned until their package version and release record exist.
 
 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.
 

package/framework/README.md

@@ -36,12 +36,13 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/animation-frame-pass.mjs`: effect-owned animation-frame ref validation and plain mutable effect-scope lowering.
 - `compiler/browser-signal-passes.mjs`: static media-query external-store and navigator capability-condition normalization.
 - `compiler/collection-analysis.mjs`: pure collection expression IR, selector pipeline, alias, and imported-transform analysis.
-- `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, import, and client-root finalization.
+- `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, import, and client-root finalization.
+- `compiler/effect-analysis.mjs`: ordered effect dependency classification and cleanup-owned browser resource validation before EffectIR registration.
 - `compiler/normalization-pipeline.mjs`: ordered source normalization with parent-pointer repair after every compiler pass.
 - `compiler/react-migration-pass.mjs`: React import, memo, callback, `forwardRef`, and `useId` migration validation and lowering.
 - `compiler/custom-hook-timer-pass.mjs`: private custom-hook timeout-ref validation and compiler-owned timer-state lowering.
 - `compiler/effect-codegen.mjs`: route-specific ordinary, owned, and navigable effect entry generation.
-- `compiler/optimize/command-specialization.mjs`, `compiler/ir/module-ir.mjs`, and `compiler/codegen/command-codegen.mjs`: JSON-safe command and keyed ownership registration, sparse per-source ModuleIR, and source-analysis-free existing behavior-call generation.
+- `compiler/optimize/command-specialization.mjs`, `compiler/ir/module-ir.mjs`, and `compiler/codegen/command-codegen.mjs`: JSON-safe command, keyed, and effect ownership registration, sparse per-source ModuleIR, and source-analysis-free existing behavior-call generation.
 - `compiler/handler-lowering.mjs`: source-local native/effect callback, reducer, Context, Zustand, reactive-binding, and list-evaluator AST lowering before IR finalization.
 - `compiler/handler-codegen.mjs`: AST-free ordered import rendering and finalized handler/binding export-source assembly.
 - `compiler/render-control-pass.mjs`: render-function early-return and exhaustive adjacent-assignment normalization.
@@ -64,7 +65,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Compiler ownership follows four explicit stages. `build.mjs` owns project discovery, route planning, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and repairs parent pointers after every source transform; migration passes keep per-file state local and return additional metadata explicitly. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing handler, effect callback, binding, keyed block, and client-import descriptors. Keyed blocks link deterministic parent/child sites, component specializations, row states/refs, and generated handlers/bindings without replacing `core.mjs` final DOM ownership. `compiler/collection-analysis.mjs` owns the shared pure collection language used by React migration, reactive expressions, effects, and keyed lists. After build-time rendering, `compiler/route-capability-planner.mjs` projects serializable route plans into one capability manifest consumed by runtime specialization and artifact emission. Codegen modules turn descriptors into route-specific ESM without participating in source analysis. The versioned continuation plan lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
+Compiler ownership follows four explicit stages. `build.mjs` owns project discovery, route planning, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and repairs parent pointers after every source transform; migration passes keep per-file state local and return additional metadata explicitly. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. Keyed blocks link deterministic parent/child sites, component specializations, row states/refs, and generated handlers/bindings without replacing `core.mjs` final DOM ownership. Effects link setup handlers, dependencies, cleanup, lexical/keyed ownership, provenance, and Worker edges without duplicating the rendered route plan. `compiler/collection-analysis.mjs` owns the shared pure collection language used by React migration, reactive expressions, effects, and keyed lists. After build-time rendering, `compiler/route-capability-planner.mjs` projects serializable route plans into one capability manifest consumed by runtime specialization and artifact emission. Codegen modules turn descriptors into route-specific ESM without participating in source analysis. The versioned continuation plan lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
 
 New syntax support belongs in an existing pass or a focused new pass only when a reduced migration fixture proves it. Passes must preserve source-located diagnostics, avoid module-global analysis state, and expose metadata through return values rather than AST-identity side channels. Build orchestration stays in `build.mjs`; feature-specific graph validation or code generation moves under `compiler/` when it has a stable input/output boundary.
 

package/framework/build.mjs

@@ -11,6 +11,7 @@ import { normalizeMediaQueryExternalStores, normalizeNavigatorCapabilityConditio
 import { analyzeCollectionPipeline, collectionExpression, collectionParameters, isArrayFromCall, mutatingCollectionMethods as mutatingListMethods, pureCollectionMathMethods as pureMathMethods, pureCollectionMethods as pureListMethods } from "./compiler/collection-analysis.mjs"
 import { normalizeCustomHookTimerRefs } from "./compiler/custom-hook-timer-pass.mjs"
 import { captureNames, createDescriptorSession, createSemanticArtifact, nativeCaptureNames, referencedReducerDispatches, referencedStateNames } from "./compiler/descriptor-session.mjs"
+import { analyzeEffectDependencies, validateEffectOwnedBrowserResources } from "./compiler/effect-analysis.mjs"
 import { createEffectCodegen } from "./compiler/effect-codegen.mjs"
 import { createHandlerCodegen } from "./compiler/handler-codegen.mjs"
 import { createHandlerLowering } from "./compiler/handler-lowering.mjs"
@@ -75,12 +76,16 @@ export async function build({ quiet = false, minify = true } = {}) {
   const { cssModules, cssOutputs } = await prepareSourceStyles(cssFiles, staticFiles, importedAssets, base)
 
   const sourceResults = []
-  const workerReferences = []
   for (const file of sourceFiles) {
     if (file.endsWith(".worker.ts")) continue
-    sourceResults.push(await compile(file, sourceFileSet, sourceIndex, staticFiles, importedAssets, cssModules, base, workerReferences))
+    sourceResults.push(await compile(file, sourceFileSet, sourceIndex, staticFiles, importedAssets, cssModules, base))
   }
   const handlerModules = sourceResults.flatMap(result => result.handlerModule ? [result.handlerModule] : [])
+  const workerReferences = sourceResults.flatMap(result => result.moduleIR.effects.flatMap(effect => {
+    const handler = result.moduleIR.handlers[effect.setup.handler]
+    if (!handler || handler.kind !== "module-export" || handler.role !== "effect") throw new Error(`EffectIR ${effect.slot} has no effect HandlerIR`)
+    return effect.workers.map(worker => ({ ...worker, module: assetPath(base, `assets/${result.handlerModule.path}`), handler: handler.exportName }))
+  }))
 
   const plans = []
   const routeCapabilities = new Map()
@@ -678,7 +683,7 @@ function escapeAttribute(value) {
   return escapeHtml(value).replaceAll('"', """).replaceAll("'", "'")
 }
 
-async function compile(file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base, workerReferences) {
+async function compile(file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base) {
   const source = sourceIndex.get(file)
   const semantic = createSemanticArtifact(relative(root, file).replaceAll(sep, "/"))
   const handlerPath = `handlers/${relative(sourceDirectory, file).replaceAll(sep, "/").replace(/\.(?:ts|tsx)$/, ".js")}`
@@ -690,7 +695,7 @@ async function compile(file, sourceFiles, sourceIndex, staticFiles, importedAsse
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer({ semantic, handlerUrl: assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base, workerReferences })] },
+    transformers: { before: [createKudzuTransformer({ semantic, handlerUrl: assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base })] },
     reportDiagnostics: true
   })
 
@@ -882,7 +887,7 @@ function normalizeCompilerSource(sourceFile, { base, context, file, importedColl
   return { sourceFile, customHookTimerStates }
 }
 
-function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base, workerReferences }) {
+function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base }) {
   const { moduleIR } = semantic
   return context => sourceFile => {
     const hasLinkElements = /<link/i.test(sourceFile.text)
@@ -954,7 +959,6 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const jsxLocalsByFunction = new Map()
     const listLocalDeclarations = []
     const listLocalUses = []
-    const componentEffectEntries = new WeakMap()
     const analysisSource = node => {
       const original = ts.getOriginalNode(node)
       return original.pos >= 0 && original.end >= 0 ? { file: sourceName(original.getSourceFile()), start: original.getStart(), end: original.end } : undefined
@@ -1724,8 +1728,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         const effectStatements = specialization.effects.map(entry => {
           const effectCall = factory.updateCallExpression(entry.call, factory.createIdentifier("__kComponentUseEffect"), entry.call.typeArguments, entry.call.arguments)
           synthesizeTree(effectCall)
-          const effectSource = entry.source.getSourceFile()
-          componentEffectEntries.set(effectCall, { source: entry.source, sourceFile: effectSource, imports: clientImportBindings(effectSource, effectSource.fileName, sourceFiles) })
+          ts.setOriginalNode(effectCall, entry.source)
           return factory.createExpressionStatement(effectCall)
         })
         const helper = factory.createFunctionDeclaration(
@@ -1956,15 +1959,14 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       return expanded
     }
     const preparedRenderedLists = []
-    const prepareListCallback = (callback, root, specialization, item, effectEntries) => {
+    const prepareListCallback = (callback, root, specialization) => {
       const statements = [...specialization.hookDeclarations]
       if (specialization.effects.length) {
         usesListEffects = true
         statements.push(...specialization.effects.map(entry => {
           const call = factory.updateCallExpression(entry.call, factory.createIdentifier("__kListUseEffect"), entry.call.typeArguments, entry.call.arguments)
           synthesizeTree(call)
-          const effectSource = entry.source.getSourceFile()
-          effectEntries.push({ node: call, item, source: entry.source, sourceFile: effectSource, imports: clientImportBindings(effectSource, effectSource.fileName, sourceFiles) })
+          ts.setOriginalNode(call, entry.source)
           return factory.createExpressionStatement(call)
         }))
       }
@@ -1995,13 +1997,11 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         ts.setParentRecursive(callback, false)
         callback.parent = originalParts.callback.parent
       }
-      const effectEntries = []
-      callback = prepareListCallback(callback, root, specialization, originalParts.item, effectEntries)
+      callback = prepareListCallback(callback, root, specialization)
       const parts = {
         ...originalParts,
         root,
         callback,
-        effectEntries,
         specializations: [specialization.analysis?.slot, ...(specialization.specializations ?? [])].filter(slot => slot !== undefined),
         rowStates: [...specialization.rowStates, ...specialization.ordinaryStates],
         rowRefs: specialization.rowRefs,
@@ -2138,10 +2138,14 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         return factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, factory.createStringLiteral(relativeModulePath(compiledPath(file), compiledPath(target))), node.attributes)
       }
 
-      const listEffect = ts.isCallExpression(node) ? keyedEntry(activeKeyedBlock?.analysis.effects ?? [], node) : undefined
-      const componentEffect = ts.isCallExpression(node) ? componentEffectEntries.get(node) : undefined
-      const specializedEffect = listEffect ?? componentEffect
-      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (hasUseEffectImport && node.expression.text === "useEffect" || specializedEffect)) {
+      const effectAlias = ts.isCallExpression(node) && ts.isIdentifier(node.expression) ? node.expression.text : undefined
+      const listEffect = effectAlias === "__kListUseEffect"
+      const specializedEffect = listEffect || effectAlias === "__kComponentUseEffect" ? (() => {
+        const source = ts.getOriginalNode(node)
+        const sourceFile = source.getSourceFile()
+        return { source, sourceFile, imports: clientImportBindings(sourceFile, sourceFile.fileName, sourceFiles) }
+      })() : undefined
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (hasUseEffectImport && effectAlias === "useEffect" || specializedEffect)) {
         const effectFail = (target, message) => {
           if (specializedEffect) throw sourceNodeError(specializedEffect.source, specializedEffect.sourceFile, message)
           fail(target, message)
@@ -2162,58 +2166,18 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         if (callback.asteriskToken) effectFail(callback, "useEffect() callback cannot be a generator")
         if (callback.parameters.length) effectFail(callback, "useEffect() callback cannot declare parameters")
         if (!ts.isArrayLiteralExpression(dependencies)) effectFail(dependencies, "useEffect() dependencies must be a literal array")
-        const itemDependencies = []
-        const ordinaryDependencies = []
         const setters = settersForNode(node, settersByFunction)
-        let dependencyItem = listEffect?.item
-        for (const dependency of dependencies.elements) {
-          const value = unwrapExpression(dependency)
-          if (!dependencyItem && ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression) && isDestructuredParameter(value.expression, nearestFunction(node))) dependencyItem = value.expression.text
-          const field = dependencyItem && directProperty(dependency, dependencyItem)
-          if (field) {
-            if (["__proto__", "constructor", "prototype"].includes(field)) effectFail(dependency, `useEffect() keyed item property "${field}" is not supported`)
-            itemDependencies.push(field)
-          } else if (dependencyItem && referencesIdentifier(dependency, dependencyItem)) {
-            effectFail(dependency, "useEffect() keyed item dependencies must be direct item.<field> properties")
-          } else {
-            ordinaryDependencies.push(dependency)
-          }
-        }
-        const invalidDependency = ordinaryDependencies.find(dependency => !ts.isIdentifier(dependency))
-        if (invalidDependency) effectFail(invalidDependency, "useEffect() dependencies must be direct state or runtime parameter identifiers")
-        const dependencyDerived = []
-        const dependencyStates = new Map()
-        const dependencySubstitutions = new Map()
-        const subscriptionDependencies = []
-        let hasDerivedDependency = false
-        const stateNames = new Set(setters.values())
-        const localDeclarations = jsxLocalDeclarations.get(nearestFunction(node))
-        for (const dependency of ordinaryDependencies) {
-          const entries = localDeclarations?.get(dependency.text)
-          const initializer = entries?.length === 1 ? entries[0].initializer : undefined
-          const directAlias = initializer && ts.isIdentifier(unwrapExpression(initializer)) && stateNames.has(unwrapExpression(initializer).text)
-          const derivedStates = initializer && !directAlias ? referencedStateNames(initializer, setters) : new Set()
-          if (derivedStates.size) {
-            const usedStates = new Set()
-            const expression = collectionExpression(initializer, { fail: effectFail, stateNames, selectorStates: usedStates })
-            if (!usedStates.size) effectFail(dependency, `useEffect() derived dependency "${dependency.text}" must read direct primitive state`)
-            dependencyDerived.push({ expression, states: usedStates, source: initializer })
-            for (const name of usedStates) {
-              subscriptionDependencies.push(factory.createIdentifier(name))
-              dependencyStates.set(name, factory.createIdentifier(name))
-            }
-            dependencySubstitutions.set(dependency.text, initializer)
-            hasDerivedDependency = true
-          } else {
-            subscriptionDependencies.push(dependency)
-            dependencyDerived.push({ expression: ["state", dependency.text], states: [dependency.text], source: dependency })
-            dependencyStates.set(dependency.text, dependency)
-          }
-        }
-        if (!hasDerivedDependency) {
-          dependencyDerived.length = 0
-          dependencyStates.clear()
-        }
+        const dependencyAnalysis = analyzeEffectDependencies({
+          dependencies,
+          node,
+          listEffect,
+          keyedItem: activeKeyedBlock?.parts.item,
+          setters,
+          localDeclarations: jsxLocalDeclarations.get(nearestFunction(node)),
+          factory,
+          fail: effectFail
+        })
+        const { dependencyItem, itemDependencies, ordinaryDependencies, entries: dependencyEntries, dependencyStates, substitutions: dependencySubstitutions, subscriptions: subscriptionDependencies, hasDerived: hasDerivedDependency } = dependencyAnalysis
         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 cleanupSubstitutions = new Map()
@@ -2239,17 +2203,19 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         validateEffectOwnedBrowserResources(callback, returns, effectFail)
         const callbackSource = specializedEffect?.sourceFile ?? sourceFile
         const callbackFile = callbackSource.fileName
-        const workerStart = workerReferences.length
         let compiledCallback = dependencySubstitutions.size ? substituteClone(callback, dependencySubstitutions, factory, context) : callback
         if (compiledCallback !== callback) {
           ts.setParentRecursive(compiledCallback, false)
           compiledCallback.parent = callback.parent
         }
+        let workers = []
         if (listEffect && callbackFile !== file) {
-          const originalCallback = listEffect.source.arguments[0]
+          const originalCallback = specializedEffect.source.arguments[0]
           workerCompiler.rejectConstructions(originalCallback, callbackSource, "Relative TypeScript Worker construction in imported keyed-row effects is not supported; construct the Worker in a directly compiled page or local component effect")
         } else {
-          compiledCallback = workerCompiler.rewriteEffect(compiledCallback, callbackFile, callbackSource, sourceFiles, workerReferences, factory, context)
+          const rewritten = workerCompiler.rewriteEffect(compiledCallback, callbackFile, callbackSource, sourceFiles, factory, context)
+          compiledCallback = rewritten.callback
+          workers = rewritten.workers
         }
         const descriptor = descriptors.compileEffectCallback(compiledCallback, {
           setters,
@@ -2261,22 +2227,38 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           snapshotNested: returns.cleanup,
           liveStates: customHookTimerStates
         })
-        for (const reference of workerReferences.slice(workerStart)) Object.assign(reference, { module: handlerUrl, handler: descriptor.exportName })
         usesListItem ||= Boolean(itemDependencies.length && !listEffect)
         usesBehavior = true
-        const derivedDependencies = hasDerivedDependency ? dependencyDerived.map(entry => descriptors.registerDerived("expression", entry.expression, entry.states, entry.source)) : []
+        const derivedDependencies = hasDerivedDependency ? dependencyEntries.map(entry => entry.kind === "derived" ? descriptors.registerDerived("expression", entry.expression, entry.states, entry.source) : undefined) : []
+        const effectSource = specializedEffect?.source ?? node
+        const lexicalOwner = nearestFunction(effectSource)
+        const effect = descriptors.registerEffect(descriptor, {
+          cleanup: returns.cleanup,
+          dependencies: hasDerivedDependency ? dependencyEntries.map((entry, index) => entry.kind === "derived" ? { kind: "derived", derived: derivedDependencies[index].slot, sources: [...entry.states] } : { kind: "signal", name: entry.name }) : ordinaryDependencies.map(dependency => ({ kind: "signal", name: dependency.text })),
+          subscriptions: (hasDerivedDependency ? subscriptionDependencies : ordinaryDependencies).map(dependency => dependency.text),
+          dependencyStates: [...dependencyStates.keys()],
+          itemDependencies,
+          ownership: {
+            kind: activeKeyedBlock ? "keyed" : "component",
+            ...(activeKeyedBlock ? { keyedBlock: activeKeyedBlock.block.slot } : {}),
+            ...(lexicalOwner ? { component: { name: ownerName(lexicalOwner), ...(analysisSource(lexicalOwner) ? { source: analysisSource(lexicalOwner) } : {}) } } : {})
+          },
+          workers,
+          ...(analysisSource(effectSource) ? { source: analysisSource(effectSource) } : {})
+        })
+        const dependencyExpressions = effect.dependencies.map(dependency => dependency.kind === "derived" ? moduleIR.derived[dependency.derived].expression : ["state", dependency.name])
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [
           callback,
-          factory.createArrayLiteralExpression(hasDerivedDependency ? subscriptionDependencies : ordinaryDependencies),
+          factory.createArrayLiteralExpression(effect.subscriptions.map(name => factory.createIdentifier(name))),
           factory.createStringLiteral(handlerUrl),
-          factory.createStringLiteral(descriptor.exportName),
+          factory.createStringLiteral(effect.setup.exportName),
           descriptor.states,
           descriptor.scope,
           factory.createStringLiteral(specializedEffect ? sourceLocation(specializedEffect.source, specializedEffect.sourceFile) : sourceLocation(node, sourceFile)),
-          returns.cleanup ? factory.createTrue() : factory.createFalse(),
-          factory.createArrayLiteralExpression(itemDependencies.map(field => factory.createStringLiteral(field))),
-          hasDerivedDependency ? jsonExpression(derivedDependencies.map(entry => entry.expression), factory) : factory.createArrayLiteralExpression(),
-          factory.createArrayLiteralExpression([...dependencyStates].map(([name, state]) => factory.createArrayLiteralExpression([factory.createStringLiteral(name), state])))
+          effect.cleanup ? factory.createTrue() : factory.createFalse(),
+          factory.createArrayLiteralExpression(effect.itemDependencies.map(field => factory.createStringLiteral(field))),
+          hasDerivedDependency ? jsonExpression(dependencyExpressions, factory) : factory.createArrayLiteralExpression(),
+          factory.createArrayLiteralExpression(effect.dependencyStates.map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)])))
         ])
       }
 
@@ -2618,7 +2600,7 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
   const fail = (node, message) => {
     throw sourceNodeError(node, sourceFile, message)
   }
-  const analysis = { values: [], conditions: [], nested: [], effects: parts.effectEntries ?? [] }
+  const analysis = { values: [], conditions: [], nested: [] }
   const root = parts.root
   const item = parts.item
   const nestedDiagnostic = "Nested keyed list collections must be a direct property of the parent item"
@@ -2657,8 +2639,7 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
           ts.setParentRecursive(callback, false)
           callback.parent = nested.callback.parent
         }
-        const effectEntries = []
-        callback = prepareListCallback(callback, root, specialization ?? { hookDeclarations: [], effects: [] }, nested.item, effectEntries)
+        callback = prepareListCallback(callback, root, specialization ?? { hookDeclarations: [], effects: [] })
         const specializedStates = [...(specialization?.rowStates ?? []), ...(specialization?.ordinaryStates ?? [])]
         const nestedParts = {
           ...nested,
@@ -2666,7 +2647,6 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
           callback,
           state: parts.state,
           nested: true,
-          effectEntries,
           specializations: [specialization?.analysis?.slot, ...(specialization?.specializations ?? [])].filter(slot => slot !== undefined),
           rowStates: specializedStates,
           rowRefs: specialization?.rowRefs ?? [],
@@ -3429,30 +3409,6 @@ function localComponentDeclaration(sourceFile, name) {
   return undefined
 }
 
-function validateEffectOwnedBrowserResources(callback, returns, fail) {
-  const observers = []
-  const frameAssignments = []
-  const cancellations = new Set()
-  const disconnected = new Set()
-  const insideCleanup = node => returns.cleanups.some(cleanup => {
-    for (let current = node; current; current = current.parent) if (current === cleanup) return true
-    return false
-  })
-  const visit = node => {
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isNewExpression(unwrapExpression(node.initializer)) && ts.isIdentifier(unwrapExpression(node.initializer).expression) && unwrapExpression(node.initializer).expression.text === "IntersectionObserver") observers.push(node)
-    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(unwrapExpression(node.left)) && ts.isCallExpression(unwrapExpression(node.right)) && ts.isIdentifier(unwrapExpression(node.right).expression) && unwrapExpression(node.right).expression.text === "requestAnimationFrame") frameAssignments.push(node)
-    if (insideCleanup(node) && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "cancelAnimationFrame" && node.arguments.length === 1 && ts.isIdentifier(unwrapExpression(node.arguments[0]))) cancellations.add(unwrapExpression(node.arguments[0]).text)
-    if (insideCleanup(node) && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.name.text === "disconnect" && node.arguments.length === 0) disconnected.add(node.expression.expression.text)
-    ts.forEachChild(node, visit)
-  }
-  visit(callback.body)
-  for (const observer of observers) if (!disconnected.has(observer.name.text)) fail(observer, `IntersectionObserver effects must disconnect ${JSON.stringify(observer.name.text)} in cleanup`)
-  for (const assignment of frameAssignments) {
-    const name = unwrapExpression(assignment.left).text
-    if (!cancellations.has(name)) fail(assignment, `Animation loop effects must cancel ${JSON.stringify(name)} in cleanup`)
-  }
-}
-
 async function collectClientModules(entries, sourceFiles) {
   const modules = new Set()
   const queue = [...new Set(entries)]

package/framework/compiler/descriptor-session.mjs

@@ -2,7 +2,7 @@ import ts from "typescript"
 import { createComponentAnalysis } from "./analysis/component-analysis.mjs"
 import { bindingNames, isFunctionLike, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, unwrapExpression } from "./ast-helpers.mjs"
 import { generateCommandBehavior } from "./codegen/command-codegen.mjs"
-import { createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerKeyedBlock, registerModuleHandler } from "./ir/module-ir.mjs"
+import { createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerEffect, registerKeyedBlock, registerModuleHandler } from "./ir/module-ir.mjs"
 
 export function createSemanticArtifact(file) {
   return { componentAnalysis: createComponentAnalysis(file), moduleIR: createModuleIR(file) }
@@ -160,6 +160,10 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return registerKeyedBlock(moduleIR, descriptor)
   }
 
+  function registerEffectResult(handler, descriptor) {
+    return registerEffect(moduleIR, { ...descriptor, setup: { exportName: handler.exportName } })
+  }
+
   function finalize() {
     const callbacks = [...nativeHandlers, ...effectHandlers]
     for (const entry of callbacks) {
@@ -210,6 +214,11 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       code: handlerLowering.lowerListExpression(entry),
       ...(source(entry.expression) ? { source: source(entry.expression) } : {})
     })
+    for (const effect of moduleIR.effects) {
+      const handler = moduleIR.handlers.find(candidate => candidate.kind === "module-export" && candidate.role === "effect" && candidate.exportName === effect.setup.exportName)
+      if (!handler) throw new Error(`Effect handler ${JSON.stringify(effect.setup.exportName)} was not finalized`)
+      effect.setup = { handler: handler.slot }
+    }
     const imports = [...callbacks, ...reactiveBindings].flatMap(entry => entry.imports ?? []).map(importRecord)
     moduleIR.imports = [...new Map(imports.map(entry => [`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`, entry])).values()]
     moduleIR.clientModules = [...clientModules]
@@ -223,7 +232,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   const importRecord = entry => ({ target: entry.target, kind: entry.kind, local: entry.local, ...(entry.imported ? { imported: entry.imported } : {}), package: Boolean(entry.package) })
 
-  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult, registerKeyedBlock: registerKeyedBlockResult }
+  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult, registerEffect: registerEffectResult, registerKeyedBlock: registerKeyedBlockResult }
 }
 
 function directStateIdentifier(expression, setters) {

package/framework/compiler/effect-analysis.mjs

@@ -0,0 +1,89 @@
+import ts from "typescript"
+import { nearestFunction, referencesIdentifier, unwrapExpression } from "./ast-helpers.mjs"
+import { collectionExpression } from "./collection-analysis.mjs"
+import { referencedStateNames } from "./descriptor-session.mjs"
+
+export function analyzeEffectDependencies({ dependencies, node, listEffect, keyedItem, setters, localDeclarations, factory, fail }) {
+  const itemDependencies = []
+  const ordinaryDependencies = []
+  let dependencyItem = listEffect ? keyedItem : undefined
+  for (const dependency of dependencies.elements) {
+    const value = unwrapExpression(dependency)
+    if (!dependencyItem && ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression) && isDestructuredParameter(value.expression, nearestFunction(node))) dependencyItem = value.expression.text
+    const field = dependencyItem && directProperty(dependency, dependencyItem)
+    if (field) {
+      if (["__proto__", "constructor", "prototype"].includes(field)) fail(dependency, `useEffect() keyed item property "${field}" is not supported`)
+      itemDependencies.push(field)
+    } else if (dependencyItem && referencesIdentifier(dependency, dependencyItem)) {
+      fail(dependency, "useEffect() keyed item dependencies must be direct item.<field> properties")
+    } else {
+      ordinaryDependencies.push(dependency)
+    }
+  }
+  const invalidDependency = ordinaryDependencies.find(dependency => !ts.isIdentifier(dependency))
+  if (invalidDependency) fail(invalidDependency, "useEffect() dependencies must be direct state or runtime parameter identifiers")
+
+  const entries = []
+  const dependencyStates = new Map()
+  const substitutions = new Map()
+  const subscriptions = []
+  let hasDerived = false
+  const stateNames = new Set(setters.values())
+  for (const dependency of ordinaryDependencies) {
+    const declarations = localDeclarations?.get(dependency.text)
+    const initializer = declarations?.length === 1 ? declarations[0].initializer : undefined
+    const directAlias = initializer && ts.isIdentifier(unwrapExpression(initializer)) && stateNames.has(unwrapExpression(initializer).text)
+    const derivedStates = initializer && !directAlias ? referencedStateNames(initializer, setters) : new Set()
+    if (derivedStates.size) {
+      const usedStates = new Set()
+      const expression = collectionExpression(initializer, { fail, stateNames, selectorStates: usedStates })
+      if (!usedStates.size) fail(dependency, `useEffect() derived dependency "${dependency.text}" must read direct primitive state`)
+      entries.push({ kind: "derived", name: dependency.text, expression, states: usedStates, source: initializer })
+      for (const name of usedStates) {
+        subscriptions.push(factory.createIdentifier(name))
+        dependencyStates.set(name, factory.createIdentifier(name))
+      }
+      substitutions.set(dependency.text, initializer)
+      hasDerived = true
+    } else {
+      subscriptions.push(dependency)
+      entries.push({ kind: "signal", name: dependency.text })
+      dependencyStates.set(dependency.text, dependency)
+    }
+  }
+  if (!hasDerived) dependencyStates.clear()
+  return { dependencyItem, itemDependencies, ordinaryDependencies, entries, dependencyStates, substitutions, subscriptions, hasDerived }
+}
+
+export function validateEffectOwnedBrowserResources(callback, returns, fail) {
+  const observers = []
+  const frameAssignments = []
+  const cancellations = new Set()
+  const disconnected = new Set()
+  const insideCleanup = node => returns.cleanups.some(cleanup => {
+    for (let current = node; current; current = current.parent) if (current === cleanup) return true
+    return false
+  })
+  const visit = node => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isNewExpression(unwrapExpression(node.initializer)) && ts.isIdentifier(unwrapExpression(node.initializer).expression) && unwrapExpression(node.initializer).expression.text === "IntersectionObserver") observers.push(node)
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(unwrapExpression(node.left)) && ts.isCallExpression(unwrapExpression(node.right)) && ts.isIdentifier(unwrapExpression(node.right).expression) && unwrapExpression(node.right).expression.text === "requestAnimationFrame") frameAssignments.push(node)
+    if (insideCleanup(node) && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "cancelAnimationFrame" && node.arguments.length === 1 && ts.isIdentifier(unwrapExpression(node.arguments[0]))) cancellations.add(unwrapExpression(node.arguments[0]).text)
+    if (insideCleanup(node) && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.name.text === "disconnect" && node.arguments.length === 0) disconnected.add(node.expression.expression.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(callback.body)
+  for (const observer of observers) if (!disconnected.has(observer.name.text)) fail(observer, `IntersectionObserver effects must disconnect ${JSON.stringify(observer.name.text)} in cleanup`)
+  for (const assignment of frameAssignments) {
+    const name = unwrapExpression(assignment.left).text
+    if (!cancellations.has(name)) fail(assignment, `Animation loop effects must cancel ${JSON.stringify(name)} in cleanup`)
+  }
+}
+
+function isDestructuredParameter(identifier, fn) {
+  return fn?.parameters.some(parameter => ts.isObjectBindingPattern(parameter.name) && parameter.name.elements.some(element => ts.isIdentifier(element.name) && element.name.text === identifier.text)) ?? false
+}
+
+function directProperty(expression, objectName) {
+  const value = unwrapExpression(expression)
+  return ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression) && value.expression.text === objectName ? value.name.text : undefined
+}

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

@@ -1,5 +1,5 @@
 export function createModuleIR(file) {
-  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], keyedBlocks: [], imports: [], clientModules: [] }
+  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
 }
 
 export function registerCommandHandler(moduleIR, commands, source, scope = "module") {
@@ -40,6 +40,12 @@ export function registerDerived(moduleIR, descriptor) {
   return derived
 }
 
+export function registerEffect(moduleIR, descriptor) {
+  const effect = { slot: moduleIR.effects.length, ...descriptor }
+  moduleIR.effects.push(effect)
+  return effect
+}
+
 export function registerKeyedBlock(moduleIR, descriptor) {
   const block = { slot: moduleIR.keyedBlocks.length, ...descriptor }
   moduleIR.keyedBlocks.push(block)

package/framework/compiler/worker-compiler.mjs

@@ -44,7 +44,8 @@ export function createWorkerCompiler({
     return { worker, url, specifier: specifierNode.text, options }
   }
 
-  const rewriteEffect = (callback, file, sourceFile, sourceFiles, workerReferences, factory, context) => {
+  const rewriteEffect = (callback, file, sourceFile, sourceFiles, factory, context) => {
+    const workers = []
     const visit = node => {
       const value = candidate(node, sourceFile)
       if (value) {
@@ -56,12 +57,17 @@ export function createWorkerCompiler({
         if (!sourceFiles.has(target)) throw sourceNodeError(url.arguments[0], sourceFile, `Relative TypeScript Worker ${JSON.stringify(specifier)} must resolve to an existing .worker.ts file under src/`)
         const identity = `${sourceRelative.replaceAll(sep, "/")}:${ts.getOriginalNode(node).getStart(sourceFile)}`
         const placeholder = `/__kudzu_worker_${createHash("sha256").update(identity).digest("hex").slice(0, 16)}__.js`
-        workerReferences.push({ root: target, placeholder })
+        const original = ts.getOriginalNode(node)
+        workers.push({
+          root: sourceRelative.replaceAll(sep, "/"),
+          placeholder,
+          source: { file: relative(root, sourceFile.fileName).replaceAll(sep, "/"), start: original.getStart(sourceFile), end: original.end }
+        })
         return factory.updateNewExpression(worker, worker.expression, worker.typeArguments, [factory.createStringLiteral(placeholder), options])
       }
       return ts.visitEachChild(node, visit, context)
     }
-    return ts.visitEachChild(callback, visit, context)
+    return { callback: ts.visitEachChild(callback, visit, context), workers }
   }
 
   const rejectConstructions = (expression, sourceFile, message) => {
@@ -124,7 +130,7 @@ export function createWorkerCompiler({
   }
 
   const emit = async (references, sourceFiles, assetsDirectory, base, minify) => {
-    const roots = [...new Set(references.map(reference => reference.root))].sort()
+    const roots = [...new Set(references.map(reference => resolve(sourceDirectory, reference.root)))].sort()
     if (!roots.length) return new Map()
     await validateGraphs(roots, sourceFiles)
     const workerDirectory = resolve(assetsDirectory, "workers")
@@ -150,12 +156,12 @@ export function createWorkerCompiler({
     for (const [output, metadata] of Object.entries(result.metafile.outputs)) {
       if (!metadata.entryPoint) continue
       const entry = resolve(root, metadata.entryPoint)
-      const rootReferences = references.filter(reference => reference.root === entry)
+      const rootReferences = references.filter(reference => resolve(sourceDirectory, reference.root) === entry)
       const outputFile = resolve(root, output)
       const url = assetPath(base, relative(outputDirectory, outputFile).replaceAll(sep, "/"))
       for (const reference of rootReferences) emitted.set(reference.placeholder, url)
     }
-    for (const reference of references) if (!emitted.has(reference.placeholder)) throw new Error(`Worker entry was not emitted: ${relative(root, reference.root)}`)
+    for (const reference of references) if (!emitted.has(reference.placeholder)) throw new Error(`Worker entry was not emitted: ${reference.root}`)
     return emitted
   }
 

package/framework/core.d.ts

@@ -156,7 +156,21 @@ export function renderPage<Props = Record<string, never>>(
       commands?: Array<[string, string, unknown]>
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
-    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown>; lifetime?: "layout" | "route"; dependencies?: string[]; itemDependencies?: string[]; listState?: string; cleanup?: true; owner?: string; list?: true }>
+    effects: Array<{
+      module: string
+      handler: string
+      states: Record<string, string>
+      scope: Record<string, unknown>
+      lifetime?: "layout" | "route"
+      dependencies?: string[]
+      dependencyExpressions?: unknown[]
+      dependencyStates?: Record<string, string>
+      itemDependencies?: string[]
+      listState?: string
+      cleanup?: true
+      owner?: string
+      list?: true
+    }>
     bindings: Array<{
       target: string
       state?: string

package/package.json

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