@kudzujs/core 0.6.4 → 0.6.6

package/GOAL_A.md

@@ -13,7 +13,7 @@ The benchmark runner, framework fixtures, generated artifacts, and raw arrays ar
 - **Phase 1 complete**: a local six-route commerce fixture, locked React/Next/Nuxt/SvelteKit comparisons, and a reproducible artifact/build/Chrome runner validate the implementation.
 - **Phase 2 complete**: effects inside conditional ranges and supported keyed row components mount with their DOM owner, unsubscribe and clean up on removal, and remount without affecting effect-free output.
 - **Phase 3 complete**: page-exported layouts render complete documents with compiler-owned route boundaries, collision-free layout/route IDs, and state/effect ownership metadata. Effects remain document effects and client navigation is unchanged.
-- **Phase 4 route/layout effects implemented**: layout effects mount once per document session, route effects remount after awaited route cleanup, and primitive dependency subscriptions exist only while their lifetime is mounted. Conditional/keyed effects use per-lifetime owner registries; route registries are fresh on cached revisits. Disposed effect setters and queued commits are inactive. Keyed item-property dependencies remain unsupported.
+- **Phase 4 route/layout effects implemented**: layout effects mount once per document session, route effects remount after awaited route cleanup, and primitive dependency subscriptions exist only while their lifetime is mounted. Conditional/keyed effects use per-lifetime owner registries; route registries are fresh on cached revisits. Direct primitive keyed-item properties rerun only changed rows; reorder does not rerun and key changes remount. Disposed effect setters and queued commits are inactive.
 - **Phase 4 document prefetch implemented**: visible, near-visible, hovered, or focused eligible group anchors prefetch and validate complete documents without importing target capabilities. The finite in-memory full-URL cache removes the measured product-cart HTML RTT while preserving retry and native fallback.
 - **Phase 5 complete**: matched async cart success/rejection flows prove immediate optimistic updates, duplicate prevention, accessible errors, rollback, route-local reset, and stale-write suppression without new framework APIs.
 - **Phase 6 expansion probe complete**: one layout-owned mock `EventTarget` stream and one route-owned imperative chart stub use existing effects and a relative TypeScript helper across repeated navigation, with exact listener and disposal assertions. This proves only the compatibility seam; Kudzu does not provide telemetry or chart support.
@@ -29,6 +29,10 @@ The post-Goal-A multiple-group fixture emits a 7,448 B raw / 3,099 B gzip (`gzip
 
 In a matched one-effect navigation build with the same conditional capability, moving the effect from the route body into the conditional owner changes the route effect entry from 2,181 B raw / 1,036 B gzip to 4,135 B raw / 1,807 B gzip (`+1,954 B` raw / `+771 B` gzip). Owner-hook unsubscription changes the shared runtime from 1,347 B raw / 718 B gzip to 1,459 B raw / 732 B gzip (`+112 B` raw / `+14 B` gzip). Top-level-only and effect-free navigation builds retain their smaller generators.
 
+In matched state-only and item-property keyed-row builds, targeted notification adds 821 B raw / 255 B gzip across the route effect entry, shared runtime, and list runtime. Builds without item-property dependencies retain their previous generated path.
+
+In the matched 1,000-row keyed-effect runtime microbenchmark, Kudzu measured 3.4 ms selected-row cleanup/update/setup, 2.9 ms unrelated-field update, and 7.8 ms reorder after all rows and effects were ready. React CSR measured 12.3, 6.8, and 19.0 ms; Vue measured 4.7, 2.3, and 10.1 ms; and Svelte measured 5.2, 3.0, and 48.1 ms. Targeted changed-root notification reduced Kudzu's selected update from 6.2 to 3.4 ms; list reconciliation remains O(n). Kudzu emits initial rows while these framework fixtures are CSR, so their JavaScript, output, and build observations are not architecture-equivalent claims.
+
 A 0.6.4 release-tree desktop rerun of the matched six-route commerce fixture measured Kudzu at 486.8 ms build, 35,355 deploy bytes, 7,334 B gzip product JavaScript, 332/156 ms cold/warm LCP, 122.6 ms startup task, 4.8 ms interaction, and 5.6 ms product-cart navigation. React measured 545.4 ms build, 61,464 B gzip product JavaScript, 332/264 ms LCP, 179.9 ms startup task, 10.2 ms interaction, and 9.9 ms navigation. Kudzu built 10.7% faster and its top-level-only fixture retained byte-identical deploy, product-graph, and navigation-asset sizes after navigation-owned effects were added. Raw arrays and the consolidated report are retained under the local demo benchmark workspace.
 
 The Phase 6 chart probe's complete initial module graph is 11,902 B raw / 5,331 B gzip. It adds no framework API or package and does not change the commerce benchmark fixture.

package/GOAL_B.md

@@ -0,0 +1,153 @@
+# Goal B: Static Realtime Dashboards
+
+Goal B makes Kudzu sufficient for a ThingsBoard-shaped realtime device dashboard without turning Kudzu into a stream runtime, widget framework, or server platform. It preserves complete static documents, zero-JavaScript routes that use no browser capabilities, direct DOM ownership, native navigation fallback, and the absence of React, a VDOM, hydration, or a retained browser component tree.
+
+`MIGRATION_ROADMAP.md` remains the source of truth for compiler invariants and fixture-first development. This document is the implementation contract for realtime dashboard work.
+
+## Product Target
+
+A user can statically deploy this flow:
+
+```text
+dashboard -> devices -> device detail -> alarms -> settings
+```
+
+The first vertical slice is deliberately smaller:
+
+```text
+plain route <-> realtime device dashboard
+```
+
+The dashboard receives a logical 1,000 telemetry samples per second, keeps a bounded history in a module Worker, downsamples it, and updates one imperative chart without routing samples through `useState()`.
+
+## Runtime Model
+
+```text
+Complete static dashboard shell
+  -> route-specific effect ESM
+  -> route-owned module Worker
+  -> bounded telemetry buffer and downsampling
+  -> batched imperative chart updates
+```
+
+Kudzu state is for low-frequency UI state such as selected device, time range, filters, tabs, connection status, alarm status, and widget configuration. High-frequency samples belong in a Worker or imperative browser module.
+
+The Worker is a capability, not a framework runtime. Routes that do not create one must not load its graph. Static routes must remain JavaScript-free.
+
+## Milestone 1: Relative TypeScript Workers
+
+Status: implemented and verified. The compiler recognizes only the exact inline-effect form below, emits its validated graph separately, rewrites the constructor to the base-aware same-origin asset, and leaves routes without this capability on their existing output paths.
+
+Support this exact shape inside a compiled inline `useEffect` callback:
+
+```tsx
+useEffect(() => {
+  const worker = new Worker(
+    new URL("../telemetry.worker.ts", import.meta.url),
+    { type: "module" },
+  )
+
+  const onMessage = (event: MessageEvent<ChartFrame>) => chart.render(event.data)
+  worker.addEventListener("message", onMessage)
+
+  return () => {
+    worker.removeEventListener("message", onMessage)
+    worker.terminate()
+    chart.dispose()
+  }
+}, [])
+```
+
+Compiler requirements:
+
+- accept only an unshadowed `Worker` with `new URL(relativeLiteral, import.meta.url)` and literal `{ type: "module" }`;
+- resolve one `.worker.ts` entry under project source and bundle its relative TypeScript graph separately from window code;
+- emit deterministic content-hashed ESM under `assets/workers` and rewrite the constructor to the base-aware emitted URL;
+- reject package imports, JSX, TypeScript import-equals declarations, dynamic imports, `require()`, paths outside source, malformed options, and unsupported Worker forms with source locations;
+- reject ordinary runtime imports or re-exports of `.worker.ts`; type-only imports may erase normally;
+- do not mark Worker files as navigation capability scripts or import them into the window;
+- create the Worker only when the owning effect mounts;
+- preserve byte-for-byte generated shared/list/effect paths for builds without relative TypeScript Workers where practical;
+- reject generated/public asset collisions instead of silently overwriting output.
+
+Worker construction inside imported helpers or imported keyed-row effects, `SharedWorker`, classic workers, inline Blob workers, and arbitrary dynamic Worker URLs are outside Milestone 1. Imported keyed rows must move Worker ownership to a directly compiled page or local component effect so lexical global analysis remains tied to the original source tree.
+
+## Ownership
+
+| Owner | Lifetime | Dashboard responsibility |
+|---|---|---|
+| Document | Full document | authentication expiry and global diagnostics |
+| Layout | Enhanced navigation session | tenant session or shared transport |
+| Route | Current dashboard/device | Worker, telemetry subscription, request cancellation |
+| DOM range | Current widget | chart, gauge, map, table, animation frame |
+| Worker | Explicit owner cleanup | parsing, bounded buffering, aggregation, downsampling |
+
+Leaving a route must remove message listeners, stop chart work, terminate its Worker, and invalidate stale UI writes before another route mounts. BFCache-preserved documents must retain their live ownership until a real document exit.
+
+## Fixture Contract
+
+The first fixture must provide:
+
+- one complete realtime dashboard document and one complete plain document in an opt-in navigation group;
+- one unrelated static route with zero JavaScript;
+- a relative TypeScript Worker importing at least one relative helper;
+- a fixed-capacity ring buffer with deterministic eviction;
+- logical 1,000 samples/second input in batches rather than a 1 ms browser timer;
+- bounded downsampled frames delivered at no more than display cadence;
+- one imperative canvas or DOM chart updated without sample-level Kudzu setters;
+- direct load, dashboard-to-plain navigation, back/forward, and repeated cached revisits;
+- exact counters for Worker starts, terminations, messages, renders, listeners, and stale post-cleanup work;
+- native document fallback when JavaScript or Worker creation fails.
+
+## Acceptance Criteria
+
+- the Worker graph is absent from static and plain route HTML and is fetched only after the dashboard effect mounts;
+- two unchanged production builds emit identical Worker names and bytes;
+- changing Worker source changes its content hash;
+- base-prefixed deployment produces a valid same-origin Worker URL;
+- 30 dashboard/plain cycles create and terminate exactly 30 route Workers with no growing listener or chart ownership;
+- messages arriving after cleanup cannot update removed route DOM;
+- the ring buffer remains at its configured capacity under sustained input;
+- chart rendering is batched and sample ingestion does not call `useState()`;
+- routes without Worker capabilities remain byte-for-byte unaffected;
+- output raw/gzip cost, clean build time, sample throughput, render cadence, and lifecycle counters are recorded;
+- `npm run check`, `npm test`, package dry-run, and browser checks pass.
+
+Verified measurements for the focused `/dash` fixture: the minified Worker graph is `assets/workers/telemetry.worker-BVG2SA55.js`, 907 B raw and 477 B gzip. The dashboard window graph is 11,388 B raw and 5,148 B gzip across its shared runtime, effect runtime, navigation, route effect entry, and handler module; the Worker is not part of that graph. Seven clean minified builds measured 455.1, 459.9, 460.7, 463.5, 467.6, 472.6, and 475.2 ms, with a 463.5 ms median.
+
+The real-Worker browser check uses real wall time and requires sustained generation beyond 1,130 samples at 700-1,300 logical samples/second, an exact 128-sample ring bound, batches of 10, exactly 24 displayed points, multiple renders, and a render ceiling below 25 Hz. Delayed Worker ticks catch up in batches to the logical 1,000 samples/second clock; frames emit no more often than every 50 ms. The imperative chart performs a minimal canvas path draw. The navigation ownership check completed 30 dashboard/plain cycles with exactly 30 starts and 30 terminations, exactly 60 listener additions and removals across message and error listeners, zero retained listeners after every cleanup, disposed every old chart canvas, fresh ownership on back/forward and cached revisits, and no render from a removed message listener invoked after cleanup. Dashboard, plain, and static HTML contain no Worker asset URL; plain does not load the route effect graph, and static contains no script, capability marker, or state payload. A no-Worker equivalent emitted byte-identical shared runtime, effect runtime, navigation, and route effect entry files with no `assets/workers` directory. An unreachable imported-row effect referencing `unused.worker.ts` emitted no Worker asset. Two unchanged builds emitted identical Worker names and bytes, and a controlled downsample-source change changed the emitted hash.
+
+## Delivery Order
+
+1. **Worker compiler capability**: exact syntax, graph bundling, hashing, base rewriting, diagnostics, and zero-cost exclusion.
+2. **Realtime vertical slice**: mock telemetry Worker, bounded buffer, downsampling, imperative chart, and route cleanup.
+3. **Shared transport**: add a layout-owned mock connection only if multiple routes prove that one Worker per route is wasteful.
+4. **Device workflows**: filters, commands, timeout/error handling, and stale response suppression.
+5. **Alarm workflows**: active/history views and optimistic acknowledgement with rollback.
+6. **Widget expansion**: add one gauge, table, map, or real chart engine at a time only when a fixture requires it.
+
+Each phase starts with one failing fixture and ends with correctness, lifecycle, browser, size, and build measurements.
+
+## Performance Gates
+
+- sustained 1,000 samples/second does not create one main-thread task or Kudzu state commit per sample;
+- Worker memory is bounded by declared buffer capacity;
+- chart updates are batched to at most one per display frame;
+- dashboard departure stops observable messages and renders before the next route mounts;
+- repeated navigation leaves no growing Worker, timer, listener, chart, state, DOM, or heap ownership;
+- Worker support adds no bytes to routes and builds that do not use it;
+- material losses are profiled and fixed or documented as explicit tradeoffs using matched initial content and behavior.
+
+## Non-Goals
+
+- implementing ThingsBoard's server, protocol, rule engine, database, or complete UI;
+- storing telemetry samples in Kudzu component state;
+- adding a general observable, scheduler, stream, state, or widget runtime;
+- retaining a browser component tree;
+- request-time SSR, Server Actions, or a hidden application server;
+- a plugin marketplace or arbitrary third-party React widgets;
+- claiming Worker isolation as a security sandbox.
+
+## Completion Definition
+
+Goal B Milestone 1 is complete when the focused realtime fixture proves deterministic relative TypeScript Worker emission, bounded high-frequency processing, imperative chart updates, exact route ownership and cleanup across repeated navigation, native/static fallback, zero-cost exclusion, source diagnostics, and recorded production measurements.

package/README.md

@@ -330,9 +330,9 @@ const rows = items.map(item => <ItemRow
 />)
 ```
 
-The original component remains reusable across multiple lists and ordinary JSX. No component function or component runtime is shipped to the browser. Kudzu emits initial items as static HTML, then adds, removes, updates, styles, conditional branches, and moves keyed elements directly. The map may appear directly in JSX or in one top-level immutable `const` rendered once as a JSX child. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Single-level item-local `&&` and ternary JSX conditions patch only their bounded branch and mount or unmount its handlers. Item-local handlers and effects receive the latest JSON-safe item for their key. Effects mount after a row is connected, clean up when it is removed, and do not rerun during reorder. The item remains stored once in shared list state; runtime descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
+The original component remains reusable across multiple lists and ordinary JSX. No component function or component runtime is shipped to the browser. Kudzu emits initial items as static HTML, then adds, removes, updates, styles, conditional branches, and moves keyed elements directly. The map may appear directly in JSX or in one top-level immutable `const` rendered once as a JSX child. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Single-level item-local `&&` and ternary JSX conditions patch only their bounded branch and mount or unmount its handlers. Item-local handlers and effects receive the latest JSON-safe item for their key. Effects mount after a row is connected and clean up when it is removed. A direct primitive item dependency such as `[item.name]`, optionally mixed with state as `[version, item.name]`, reruns only rows whose selected value changed; the replacement setup receives the complete latest item. Unrelated fields and reorder do not rerun it, while a key change removes and mounts the row. The item remains stored once in shared list state; runtime descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
 
-Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level local or relative-imported row component, and `key={item.<field>}`. Row components accept destructured projected props, top-level single-`const` calculations and inline effects before one intrinsic return. Effect dependencies inside a row may be empty or direct primitive Kudzu state identifiers; item-property dependencies remain unsupported. A list alias may only be rendered once and cannot be read by other JavaScript. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions, lists, or component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level local or relative-imported row component, and `key={item.<field>}`. Row components accept destructured projected props, top-level single-`const` calculations and inline effects before one intrinsic return. Effect dependencies inside a row may be empty, direct primitive Kudzu state identifiers, or direct `item.<field>` properties whose selected values remain JSON-safe primitives. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` dependencies are rejected. A list alias may only be rendered once and cannot be read by other JavaScript. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions, lists, or component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 ## Effects
 
@@ -380,6 +380,20 @@ Dependency values are limited to JSON-safe strings, finite numbers, booleans, an
 
 Effect callbacks must be inline and block-bodied. Named or dynamically obtained cleanup functions, cleanup parameters or generators, other return values, callback parameters, and non-serializable captures are rejected. Async effects cannot return cleanup functions; the cleanup itself may be async. Pages without effects receive no effect entry. Empty-dependency effects retain their smaller output, and dependency-only capability code is isolated to the routes that use `kudzu-deps.js` unless another capability already requires the shared runtime.
 
+An inline effect may own an exact relative TypeScript module Worker:
+
+```tsx
+useEffect(() => {
+  const worker = new Worker(
+    new URL("../telemetry.worker.ts", import.meta.url),
+    { type: "module" },
+  )
+  return () => worker.terminate()
+}, [])
+```
+
+Kudzu resolves the path from the callback source, bundles the Worker and its relative TypeScript imports separately as content-hashed ESM under `assets/workers`, and rewrites the constructor to the base-prefixed same-origin asset URL. The Worker is fetched only when the effect mounts; it is not a capability script, preload, or window import. Unrendered effect handlers do not cause their Worker root to be emitted. This slice requires unshadowed global `Worker` and `URL`, exact `import.meta.url`, a relative `.worker.ts` string literal, and exactly `{ type: "module" }`. Worker graphs reject JSX, package runtime imports, TypeScript import-equals declarations, dynamic imports, `require()`, missing files, and paths outside `src`. Worker source cannot be imported or re-exported as an ordinary runtime module. Construction in event handlers, imported helpers, or imported keyed-row effects is rejected; move keyed-row Worker ownership to a directly compiled page or local component effect. Public or absolute JavaScript Workers remain ordinary browser code and are not transformed.
+
 A matched mount-fetch benchmark renders a title and two keyed rows from local JSON. With one warm-up and seven rotating clean builds, Kudzu shipped initial HTML, 3.4 KB initial JS gzip, 8.1 KB total output, and built in 374 ms. React CSR shipped no initial content, 59.3 KB initial JS gzip, 189.2 KB total output, and built in 992 ms. Hand-written ESM shipped 534 B initial JS gzip, 1.2 KB total output, and built in 210 ms. Fresh-profile Chrome medians to loaded data were 157.9 ms, 166.5 ms, and 153.4 ms respectively.
 
 A matched resize-listener cleanup fixture, measured with the same warm-up and seven rotating clean builds, shipped 1.2 KB JavaScript gzip and built in 402 ms with Kudzu. Svelte shipped 10.1 KB and built in 861 ms, Vue shipped 23.6 KB and built in 768 ms, and React shipped 59.1 KB and built in 1,058 ms. Kudzu and the 127 B hand-written Astro baseline emitted initial HTML; the CSR fixtures did not.
@@ -470,7 +484,7 @@ export default {
 
 Every configured identity must be a unique emitted exact route or `runtimeParams` bracket pattern. Routes within each group must export the same layout function identity; different groups may export different layouts. Kudzu emits one deterministic, route-set-hashed navigation asset per group containing only that group's records and capabilities. Path domains may overlap within a group, where exact and more-specific matching wins, but overlapping exact/runtime or runtime/runtime domains across groups fail the build.
 
-The layout DOM, state, and effects persist within its group; route state, parameters, and effects reset after cleanup on each transition. Conditional effects mount only while their DOM is connected. Keyed row effects mount per connected row, survive reorder, read the latest row item when a supported state dependency reruns, and clean up on removal. Cached route modules create fresh route owner records and subscriptions on every revisit. Keyed item-property dependencies remain unsupported. Eligible same-group anchors prefetch validated complete documents into a finite memory cache. Cross-group links, ungrouped routes, direct requests, reloads, malformed runtime paths, JavaScript failures, and unsupported links retain native document navigation.
+The layout DOM, state, and effects persist within its group; route state, parameters, and effects reset after cleanup on each transition. Conditional effects mount only while their DOM is connected. Keyed row effects mount per connected row, survive reorder, rerun only rows whose selected direct primitive item dependency changed, receive the latest complete item, and clean up on removal. Cached route modules create fresh route owner records and subscriptions on every revisit. Eligible same-group anchors prefetch validated complete documents into a finite memory cache. Cross-group links, ungrouped routes, direct requests, reloads, malformed runtime paths, JavaScript failures, and unsupported links retain native document navigation.
 
 This produces fast same-document route changes, but it does not add a coordinated transition animation. CSS entry animations can style newly inserted route content; exit and shared-element View Transitions are not integrated yet.
 
@@ -495,6 +509,7 @@ Supported:
 - Base-path deployments, multiple CSS files, and `afterBuild`
 - Primitive `useState` bindings
 - Mount-only `useEffect(fn, [])` compiled to route-specific ESM
+- Relative TypeScript module Workers owned by inline effects
 - Conditional and keyed-row effect ownership with cleanup on DOM removal
 - Synchronous and async event handlers
 - Relative imported helpers in native handlers
@@ -645,7 +660,21 @@ An intrinsic-root versus projected-prop row-component A/B build produced byte-fo
 
 Astro is the hand-authored native DOM baseline in the interactive fixtures. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. Kudzu's keyed-list operations total 23.2 ms, 10.7 ms behind the hand-authored Astro baseline and 7.1 ms ahead of React across all four operations.
 
-Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
+### 1,000-item Keyed Effect
+
+Each keyed row owns one effect depending on `item.name`. The measured actions rename only row 500 and wait for exactly one cleanup/setup, change an unrelated detail and require no lifecycle work, then reverse all rows and again require no lifecycle work. Medians use seven fresh Chrome profiles; builds use one warm-up and seven rotating clean runs.
+
+| Framework | Initial rows | Initial JS gzip | Total output | Build | Selected update | Unrelated update | Reverse |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Astro native | Yes | **381 B** | **90,734 B** | 1,022 ms | **0.4 ms** | **0.2 ms** | **5.5 ms** |
+| Kudzu | Yes | 7,070 B | 221,056 B | **437 ms** | 3.4 ms | 2.9 ms | 7.8 ms |
+| Vue CSR | No | 25,091 B | 63,368 B | 893 ms | 4.7 ms | **2.3 ms** | 10.1 ms |
+| Svelte CSR | No | 12,848 B | 33,222 B | 1,012 ms | 5.2 ms | 3.0 ms | 48.1 ms |
+| React CSR | No | 60,921 B | 194,301 B | 1,132 ms | 12.3 ms | 6.8 ms | 19.0 ms |
+
+This is a post-initialization runtime microbenchmark, not an architecture-equivalent loading comparison. Kudzu and Astro emit all 1,000 rows in HTML while React, Vue, and Svelte use empty CSR shells, so their JavaScript, output, and build columns are observations rather than framework-size or startup claims. Once every target has 1,000 rows and effects ready, targeted changed-root notification reduces Kudzu's selected update from 6.2 to 3.4 ms, versus Vue at 4.7 ms, Svelte at 5.2 ms, and React at 12.3 ms. It adds 126 B gzip to Kudzu's initial graph. List reconciliation remains O(n), which dominates unrelated-field updates; Vue measures 2.3 ms there versus Kudzu's 2.9 ms. Astro is the hand-written direct-DOM lower bound.
+
+The general benchmark snapshot was collected on July 22, 2026 and the keyed-effect comparison on July 27, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
 
 ## Development
 

package/framework/README.md

@@ -17,8 +17,16 @@
 
 Static routes receive no browser runtime. Command routes receive `runtime.js`; dependency effects use route-specific `kudzu-deps.js` unless that route already requires shared commit hooks; runtime bracket pages using `useParams()` add one route-specific pathname matcher; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; effects add `effect-runtime.js` and one route-specific entry. Generated module scripts live in the document head, so cold downloads overlap HTML transfer while standard module deferral preserves execution after parsing. A single effect with one dependency compiles to a direct runner; generic maps, sets, and ordering are reserved for larger effect graphs. Dependency commits coalesce in a microtask; affected cleanups are awaited in declaration order before replacement setups run. Document cleanup integrates with shared unmount hooks when present and otherwise disposes directly on non-persisted `pagehide`. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. Runtime fallback rewrites are ordered by specificity in `.kudzu/kudzu-plan.json` and passed to `afterBuild()`; exact static files take precedence in development. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
 
+Exact relative `.worker.ts` constructors in inline effects are validated and bundled in a separate content-hashed ESM graph under `dist/assets/workers/`. Those files are referenced only by rendered effect handlers and never become document capability scripts, preloads, or window imports; unreachable source effects do not emit their Worker roots. Worker graphs allow relative TypeScript ESM runtime imports only and reject JSX, package runtime imports, import-equals declarations, dynamic imports, `require()`, and paths outside `src`. Ordinary runtime imports or re-exports of `.worker.ts` and Worker construction in imported keyed-row effects are rejected.
+
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime. Source CSS and global `kudzu.config` styles are emitted in document heads before `afterBuild()` runs; static stylesheet links in component JSX fail compilation instead of loading from the body.
 
-`kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Primitive dependencies and cleanup are supported, while keyed item-property dependencies remain unsupported. Fragment payloads and coordinated View Transitions are not implemented.
+Direct JSON-safe primitive keyed-item dependencies subscribe each row record to its owning list commit and compare selected fields after `list-runtime.js` synchronously refreshes the row marker. Only changed rows rerun with the complete latest item; reorder compares equal, unrelated fields do nothing, and key changes remain remove plus mount. Builds without item dependencies emit no item reader or list-state subscription code.
+
+`kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Direct primitive state, runtime parameter, and keyed-item property dependencies and cleanup are supported. Fragment payloads and coordinated View Transitions are not implemented.
 
 The current matched commerce profile emits 35,355 deploy bytes and loads 7,334 B gzip of product-route JavaScript, including 2,425 B for navigation. These sizes are unchanged because its top-level-only navigation effects retain the smaller specialized path. Validated prefetch reduced the original 128.7 ms product-to-cart navigation to 5.6 ms in the current run. Seven interleaved artifact-clean builds after warm-up measured Kudzu at 486.8 ms and React at 545.4 ms, making Kudzu 10.7% faster. Cache-disabled output is byte-for-byte identical.
+
+In matched state-only and item-property keyed-row builds, the minified route effect entry changes from 3,829 B raw/1,667 B gzip to 4,392 B raw/1,823 B gzip, the shared runtime from 1,291 B raw/671 B gzip to 1,503 B raw/751 B gzip, and the list runtime from 6,606 B raw/2,474 B gzip to 6,652 B raw/2,493 B gzip. The complete targeted-notification capability costs +821 B raw/+255 B gzip and remains absent from builds without item dependencies. Seven clean builds of the expanded three-route fixture measured 420-440 ms with a 430 ms median; this records current build cost rather than claiming a cross-version speed change.
+
+The matched 1,000-row cross-framework effect fixture measured Kudzu at 7,070 B initial JavaScript gzip, 437 ms build, 3.4 ms selected-row cleanup/update/setup, 2.9 ms unrelated-field update, and 7.8 ms reorder. React CSR measured 60,921 B, 1,132 ms, 12.3 ms, 6.8 ms, and 19.0 ms respectively; Vue measured 4.7, 2.3, and 10.1 ms for the browser operations, and Svelte measured 5.2, 3.0, and 48.1 ms. Browser operations begin only after all targets have 1,000 rows and effects ready. Kudzu emits those rows in HTML while the framework CSR fixtures begin from empty shells, so JavaScript, output, and build values are not architecture-equivalent comparisons. Targeted changed-root notification removed the extra O(n) effect-record scan and reduced Kudzu's selected update from 6.2 to 3.4 ms. List validation, serialization, and reconciliation remain O(n).

package/framework/build.mjs

@@ -45,8 +45,10 @@ export async function build({ quiet = false, minify = true } = {}) {
   const sourceIndex = new Map(await Promise.all(sourceFiles.map(async file => [file, await readFile(file, "utf8")])))
 
   const handlerModules = []
+  const workerReferences = []
   for (const file of sourceFiles) {
-    const handlerModule = await compile(file, sourceFileSet, sourceIndex, base)
+    if (file.endsWith(".worker.ts")) continue
+    const handlerModule = await compile(file, sourceFileSet, sourceIndex, base, workerReferences)
     if (handlerModule) handlerModules.push(handlerModule)
   }
 
@@ -161,6 +163,18 @@ export async function build({ quiet = false, minify = true } = {}) {
 
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
+  const renderedEffects = new Set(plans.flatMap(plan => plan.effects.map(effect => `${effect.module}:${effect.handler}`)))
+  const renderedWorkerReferences = workerReferences.filter(reference => renderedEffects.has(`${reference.module}:${reference.handler}`))
+  if (renderedWorkerReferences.length && await exists(join(root, "public", "assets", "workers"))) throw new Error("public/assets/workers collides with Kudzu's generated Worker asset namespace")
+  const workerAssets = await emitWorkers(renderedWorkerReferences, sourceFileSet, assetsDirectory, base, minify)
+  for (const module of handlerModules) {
+    for (const reference of workerReferences) {
+      if (reference.module !== assetPath(base, `assets/${module.path}`)) continue
+      const url = workerAssets.get(reference.placeholder) ?? "about:blank"
+      module.code = module.code.replaceAll(JSON.stringify(reference.placeholder), JSON.stringify(url))
+    }
+    if (module.code.includes("/__kudzu_worker_")) throw new Error(`Worker URL placeholder survived in ${module.path}`)
+  }
   const commandEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.commands).map(event => event.event)))].sort()
   const nativeEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.native).map(event => event.event)))].sort()
   const hasTextBindings = plans.some(plan => plan.bindings.some(binding => binding.target === "text"))
@@ -172,6 +186,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasListExpressionAttributes = plans.some(plan => plan.lists.some(list => list.expressionAttributes))
   const hasListSeeds = plans.some(plan => plan.lists.some(list => list.seed))
   const hasListEffects = plans.some(plan => plan.lists.some(list => list.effects))
+  const hasItemDependencies = plans.some(plan => plan.effects.some(effect => effect.itemDependencies?.length))
   const hasListAsyncParts = hasListExpressions || hasListExpressionAttributes || hasListConditions
   const hasListMounts = hasListConditions || plans.some(plan => plan.lists.some(list => list.mount))
   const hasNestedStateCaptures = hasNestedCaptureState(plans)
@@ -194,6 +209,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   if (navigationRoutes.length || behaviorCount && (hasSharedRuntime || regularBehaviorCount)) {
     const runtimeFile = hasSharedRuntime ? "./shared-runtime.js" : "./runtime.js"
     let runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, regularStateSeedCount > 0)
+    if (!hasItemDependencies) runtime = runtime.replace(/\/\* list-item-hooks \*\/[\s\S]*?\/\* list-item-hooks-end \*\/\n/, "")
     if (hasNavigableEffects) runtime = runtime.replace("export function registerCommitter(commit) {\n  committers.push(commit)\n}", "export function registerCommitter(commit) {\n  committers.push(commit)\n  return () => {\n    const index = committers.indexOf(commit)\n    if (index !== -1) committers.splice(index, 1)\n  }\n}")
     if (hasNavigableOwners) runtime = runtime
       .replace("export function registerMountHook(mount) {\n  mountHooks.push(mount)\n}", "export function registerMountHook(mount) {\n  mountHooks.push(mount)\n  return () => {\n    const index = mountHooks.indexOf(mount)\n    if (index !== -1) mountHooks.splice(index, 1)\n  }\n}")
@@ -231,6 +247,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   if (listCount) {
     let listRuntime = (await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"))
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
+    if (!hasItemDependencies) listRuntime = listRuntime.replace(", notifyListItem", "")
     const stylePatch = `  if (target === "style") {
     const style = serializeStyle(value)
     if (style) node.setAttribute("style", style)
@@ -249,7 +266,8 @@ export async function build({ quiet = false, minify = true } = {}) {
       __KUDZU_LIST_SEEDS__: String(hasListSeeds),
       __KUDZU_LIST_EFFECTS__: String(hasListEffects),
       __KUDZU_LIST_ASYNC_PARTS__: String(hasListAsyncParts),
-      __KUDZU_LIST_MOUNTS__: String(hasListMounts)
+      __KUDZU_LIST_MOUNTS__: String(hasListMounts),
+      __KUDZU_LIST_ITEM_HOOKS__: String(hasItemDependencies)
     })
   }
   if (hasNativeHandlers) {
@@ -396,7 +414,7 @@ function specializeNativeRuntime(source, events, modules) {
 
 function printEffectEntry(effects, output, handlerModules, assetsDirectory, base, paramPath, runtimeName) {
   const hasCleanup = effects.some(effect => effect.cleanup)
-  const hasDependencies = effects.some(effect => effect.dependencies?.length)
+  const hasDependencies = effects.some(effect => effect.dependencies?.length || effect.itemDependencies?.length)
   const hasOwners = effects.some(effect => effect.owner)
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
@@ -684,6 +702,7 @@ function mount(lifetime) {
 }
 
 function printOwnedNavigableEffectEntry(effects, output, handlerModules, assetsDirectory, base) {
+  const hasItemDependencies = effects.some(effect => effect.itemDependencies?.length)
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
     const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
@@ -728,7 +747,12 @@ function mount(lifetime) {
   }) : undefined
   const unsubscribeMount = __kRuntime.registerMountHook(mountOwned)
   const unsubscribeUnmount = __kRuntime.registerUnmountHook(unmountOwned)
-  for (const record of records) if (record.mounted) start(record)
+  ${hasItemDependencies ? `const unsubscribeItems = [...new Set(selectedEffects.filter(({ effect }) => effect.itemDependencies?.length).map(({ effect }) => effect.listState))].map(listState => __kRuntime.registerListItemHook(listState, root => {
+    if (!active) return
+    for (const record of registrations.get(root) ?? []) if (record.mounted && record.effect.itemDependencies) pending.add(record)
+    schedule()
+  }))
+  ` : ""}for (const record of records) if (record.mounted) start(record)
   mountOwned(document)
   function createRecord(template, mounted = true) {
     const record = { ...template, order: order++, mounted, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined, token: undefined }
@@ -833,16 +857,21 @@ function mount(lifetime) {
       for (const record of selected) {
         try {
           const values = readDependencies(record)
-          if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
-            record.values = values
-            changed.push([record, record.version])
-          }
+          if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) changed.push([record, record.version])
         } catch (error) {
           console.error(error)
         }
       }
       for (const [record] of changed) await cleanup(record)
-      if (active) for (const [record, version] of changed) if (record.mounted && record.version === version) invoke(record)
+      if (active) for (const [record, version] of changed) if (record.mounted && record.version === version) {
+        try {
+          record.values = readDependencies(record)
+          invoke(record)
+        } catch (error) {
+          record.values = undefined
+          console.error(error)
+        }
+      }
     })()
     flushing = operation
     try { await operation } finally {
@@ -851,11 +880,20 @@ function mount(lifetime) {
     }
   }
   function readDependencies(record) {
-    return (record.effect.dependencies ?? []).map(id => {
+    const values = (record.effect.dependencies ?? []).map(id => {
       const value = __kRuntime.browserState.get(id)
       if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive")
       return value
     })
+    ${hasItemDependencies ? `if (record.effect.itemDependencies) {
+      const item = JSON.parse(record.marker.dataset.kEffectItem)
+      for (const field of record.effect.itemDependencies) {
+        const value = item[field]
+        if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error(\`useEffect() keyed item dependency "\${field}" must remain a JSON-safe primitive\`)
+        values.push(value)
+      }
+    }` : ""}
+    return values
   }
   function invoke(record) {
     const token = { active: true }
@@ -896,7 +934,7 @@ function mount(lifetime) {
     disposal = (async () => {
       active = false
       unsubscribeCommitter?.()
-      unsubscribeMount()
+      ${hasItemDependencies ? "for (const unsubscribe of unsubscribeItems) unsubscribe()\n      " : ""}unsubscribeMount()
       unsubscribeUnmount()
       pending.clear()
       for (const record of records) if (record.token) record.token.active = false
@@ -919,6 +957,7 @@ function runtimeEffects(effects, lifetimes = false) {
     module: effect.module,
     handler: effect.handler,
     ...(effect.dependencies ? { dependencies: effect.dependencies } : {}),
+    ...(effect.itemDependencies ? { itemDependencies: effect.itemDependencies, listState: effect.listState } : {}),
     ...(effect.cleanup ? { cleanup: true } : {}),
     ...(effect.owner ? { owner: effect.owner } : {}),
     ...(effect.list ? { list: true } : {}),
@@ -929,10 +968,12 @@ function runtimeEffects(effects, lifetimes = false) {
 }
 
 function printOwnedEffectEntry(imports, effects, entries) {
+  const hasItemDependencies = effects.some(effect => effect.itemDependencies?.length)
+  const hasOrdinaryDependencies = effects.some(effect => effect.dependencies?.length)
   return `${imports.join("\n")}
 const effects = ${inlineJson(effects)}
 const modules = new Map([${entries}])
-const records = effects.map((effect, index) => effect.list ? undefined : createRecord(effect, index)).filter(Boolean)
+${hasItemDependencies ? "let order = 0\n" : ""}const records = effects.map((effect, index) => effect.list ? undefined : createRecord(effect, index)).filter(Boolean)
 const listTemplates = new Map(effects.map((effect, index) => effect.list ? [effect.owner, { effect, index }] : undefined).filter(Boolean))
 const owners = new Map(records.filter(record => record.effect.owner).map(record => [record.effect.owner, record]))
 const listRegistrations = new WeakMap()
@@ -944,7 +985,7 @@ let flushing = false
 let active = true
 for (const record of records) registerDependencies(record)
 function createRecord(effect, index) {
-  return { effect, index, mounted: !effect.owner, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined, token: undefined }
+  return { effect, index, ${hasItemDependencies ? "order: order++, " : ""}mounted: !effect.owner, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined, token: undefined }
 }
 function registerDependencies(record) {
   for (const id of record.effect.dependencies ?? []) {
@@ -960,12 +1001,17 @@ function unregisterDependencies(record) {
     if (!subscribers?.size) dependencies.delete(id)
   }
 }
-__kRuntime.registerCommitter(id => {
+${hasItemDependencies ? `if (${hasOrdinaryDependencies}) ` : ""}__kRuntime.registerCommitter(id => {
   if (!active) return
   for (const record of dependencies.get(id) ?? []) if (record.mounted) pending.add(record)
   schedule()
 })
-__kRuntime.registerMountHook(root => {
+${hasItemDependencies ? `for (const listState of new Set(effects.filter(effect => effect.itemDependencies?.length).map(effect => effect.listState))) __kRuntime.registerListItemHook(listState, root => {
+  if (!active) return
+  for (const record of listRegistrations.get(root) ?? []) if (record.mounted && record.effect.itemDependencies) pending.add(record)
+  schedule()
+})
+` : ""}__kRuntime.registerMountHook(root => {
   if (!active) return
   for (const marker of matching(root)) {
     if (marker.dataset.kEffects) {
@@ -1053,33 +1099,47 @@ async function flush() {
   if (!active) return pending.clear()
   flushing = true
   try {
-    const selected = [...pending].filter(record => record.mounted).sort((left, right) => left.index - right.index)
+    const selected = [...pending].filter(record => record.mounted).sort((left, right) => left.index - right.index${hasItemDependencies ? " || left.order - right.order" : ""})
     pending.clear()
     const changed = []
     for (const record of selected) {
       try {
         const values = readDependencies(record)
-        if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
-          record.values = values
-          changed.push([record, record.version])
-        }
+        if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) changed.push([record, record.version])
       } catch (error) {
         console.error(error)
       }
     }
     for (const [record] of changed) await invokeCleanup(record)
-    if (active) for (const [record, version] of changed) if (record.mounted && record.version === version) invoke(record)
+    if (active) for (const [record, version] of changed) if (record.mounted && record.version === version) {
+      try {
+        record.values = readDependencies(record)
+        invoke(record)
+      } catch (error) {
+        record.values = undefined
+        console.error(error)
+      }
+    }
   } finally {
     flushing = false
     if (active) schedule()
   }
 }
 function readDependencies(record) {
-  return (record.effect.dependencies ?? []).map(id => {
+  const values = (record.effect.dependencies ?? []).map(id => {
     const value = browserState.get(id)
     if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive")
     return value
   })
+  ${hasItemDependencies ? `if (record.effect.itemDependencies) {
+    const item = JSON.parse(record.marker.dataset.kEffectItem)
+    for (const field of record.effect.itemDependencies) {
+      const value = item[field]
+      if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error(\`useEffect() keyed item dependency "\${field}" must remain a JSON-safe primitive\`)
+      values.push(value)
+    }
+  }` : ""}
+  return values
 }
 function invoke(record) {
   const token = { active: true }
@@ -1482,7 +1542,7 @@ function escapeAttribute(value) {
   return escapeHtml(value).replaceAll('"', """).replaceAll("'", "'")
 }
 
-async function compile(file, sourceFiles, sourceIndex, base) {
+async function compile(file, sourceFiles, sourceIndex, base, workerReferences) {
   const source = sourceIndex.get(file)
   const nativeHandlers = []
   const effectHandlers = []
@@ -1498,7 +1558,7 @@ async function compile(file, sourceFiles, sourceIndex, base) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, clientImports)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, clientImports, workerReferences)] },
     reportDiagnostics: true
   })
 
@@ -1528,12 +1588,13 @@ async function compile(file, sourceFiles, sourceIndex, base) {
   return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0, hasEffects: effectHandlers.length > 0, clientImports: [...clientImports] }
 }
 
-function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports) {
+function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports, workerReferences) {
   return context => sourceFile => {
     const factory = context.factory
     const hasLinkElements = /<link/i.test(sourceFile.text)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
+    rejectOrdinaryWorkerImports(sourceFile, file, sourceFiles)
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && statement.moduleSpecifier.text === "@kudzujs/core" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
     const importedSources = new Map()
@@ -1563,6 +1624,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     let usesConditional = false
     let usesList = false
     let usesListEffects = false
+    let usesListItem = false
 
     const collect = node => {
       if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer)) {
@@ -1782,10 +1844,23 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         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")
-        if (listEffect && dependencies.elements.some(dependency => referencesIdentifier(dependency, listEffect.item))) {
-          effectFail(dependencies, "useEffect() item-property dependencies are not supported in keyed lists; use [] or primitive Kudzu state identifiers")
+        const itemDependencies = []
+        const ordinaryDependencies = []
+        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 = dependencies.elements.find(dependency => !ts.isIdentifier(dependency))
+        const invalidDependency = ordinaryDependencies.find(dependency => !ts.isIdentifier(dependency))
         if (invalidDependency) effectFail(invalidDependency, "useEffect() dependencies must be direct state or runtime parameter identifiers")
         if (!nearestFunction(node)) fail(node, "useEffect() cannot be used outside a Kudzu component")
         if (!ts.isBlock(callback.body)) effectFail(callback, "useEffect() callback must use a block body")
@@ -1795,17 +1870,31 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         if (invalidCleanup) effectFail(invalidCleanup, "useEffect() cleanup functions cannot declare parameters or be generators")
         if (returns.cleanup && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) effectFail(callback, "useEffect() async callbacks cannot return cleanup functions")
         const setters = settersForNode(node, settersByFunction)
-        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", listEffect?.item, true, returns.cleanup)
+        const callbackSource = listEffect?.sourceFile ?? sourceFile
+        const callbackFile = callbackSource.fileName
+        const workerStart = workerReferences.length
+        let compiledCallback
+        if (listEffect && callbackFile !== file) {
+          const originalCallback = listEffect.source.arguments[0]
+          rejectWorkerConstructions(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")
+          compiledCallback = callback
+        } else {
+          compiledCallback = rewriteEffectWorkers(callback, callbackFile, callbackSource, sourceFiles, workerReferences, factory, context)
+        }
+        const descriptor = compileNativeCallback(compiledCallback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
+        for (const reference of workerReferences.slice(workerStart)) Object.assign(reference, { module: handlerUrl, handler: descriptor.exportName })
+        usesListItem ||= Boolean(itemDependencies.length && !listEffect)
         usesBehavior = true
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [
           callback,
-          dependencies,
+          factory.createArrayLiteralExpression(ordinaryDependencies),
           factory.createStringLiteral(handlerUrl),
           factory.createStringLiteral(descriptor.exportName),
           descriptor.states,
           descriptor.scope,
           factory.createStringLiteral(listEffect ? sourceLocation(listEffect.source, listEffect.sourceFile) : sourceLocation(node, sourceFile)),
-          returns.cleanup ? factory.createTrue() : factory.createFalse()
+          returns.cleanup ? factory.createTrue() : factory.createFalse(),
+          factory.createArrayLiteralExpression(itemDependencies.map(field => factory.createStringLiteral(field)))
         ])
       }
 
@@ -1918,6 +2007,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listItem"), factory.createIdentifier("__kListItem")))
       behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listConditional"), factory.createIdentifier("__kListConditional")))
     }
+    if (usesListItem && !usesList) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listItem"), factory.createIdentifier("__kListItem")))
     if (usesListEffects) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useEffect"), factory.createIdentifier("__kListUseEffect")))
     if (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
@@ -2484,6 +2574,7 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   const optimized = compileOptimizedEvent(expression, setters, factory)
   if (optimized) return optimized
 
+  rejectWorkerConstructions(expression, expression.getSourceFile(), "Relative TypeScript Worker construction is only supported directly inside an inline useEffect() callback")
   const descriptor = compileNativeCallback(expression, setters, factory, nativeHandlers, importBindings, clientImports, "handler", listItem)
   return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
     factory.createStringLiteral(handlerUrl),
@@ -2546,9 +2637,81 @@ function compileOptimizedEvent(expression, setters, factory) {
 }
 
 const nativeGlobals = new Set([
-  "Array", "ArrayBuffer", "BigInt", "Boolean", "Date", "Error", "Event", "FormData", "Infinity", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "atob", "btoa", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "location", "navigator", "parseFloat", "parseInt", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
+  "Array", "ArrayBuffer", "BigInt", "Boolean", "Date", "Error", "Event", "FormData", "Infinity", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "Worker", "atob", "btoa", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "location", "navigator", "parseFloat", "parseInt", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
 ])
 
+function rewriteEffectWorkers(callback, file, sourceFile, sourceFiles, workerReferences, factory, context) {
+  const visit = node => {
+    const candidate = relativeWorkerCandidate(node, sourceFile)
+    if (candidate) {
+      if (nearestFunction(node) !== callback) throw sourceNodeError(node, sourceFile, "Relative TypeScript Worker construction must be directly inside the inline useEffect() callback, not a nested function")
+      const { worker, url, specifier, options } = validateWorkerCandidate(candidate, sourceFile)
+      const target = resolve(dirname(file), specifier)
+      const sourceRelative = relative(sourceDirectory, target)
+      if (sourceRelative.startsWith(`..${sep}`) || sourceRelative === ".." || resolve(sourceDirectory, sourceRelative) !== target) throw sourceNodeError(url.arguments[0], sourceFile, "Relative TypeScript Worker source must remain under src/")
+      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 })
+      return factory.updateNewExpression(worker, worker.expression, worker.typeArguments, [factory.createStringLiteral(placeholder), options])
+    }
+    return ts.visitEachChild(node, visit, context)
+  }
+  return ts.visitEachChild(callback, visit, context)
+}
+
+function rejectWorkerConstructions(expression, sourceFile, message) {
+  const visit = node => {
+    if (relativeWorkerCandidate(node, sourceFile)) throw sourceNodeError(node, sourceFile, message)
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body ?? expression)
+}
+
+function relativeWorkerCandidate(node, sourceFile) {
+  if (!ts.isNewExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== "Worker") return undefined
+  const first = node.arguments?.[0]
+  if (!first || !ts.isNewExpression(first) || !ts.isIdentifier(first.expression) || first.expression.text !== "URL") return undefined
+  const specifier = first.arguments?.[0]
+  const base = first.arguments?.[1]
+  const relativeLiteral = ts.isStringLiteral(specifier) && (specifier.text.startsWith("./") || specifier.text.startsWith("../"))
+  if (!relativeLiteral && !(specifier && !ts.isStringLiteral(specifier) && base && isImportMetaUrl(base))) return undefined
+  return { worker: node, url: first, sourceFile }
+}
+
+function validateWorkerCandidate(candidate, sourceFile) {
+  const { worker, url } = candidate
+  if (!isUnshadowedGlobal(worker.expression, sourceFile)) throw sourceNodeError(worker.expression, sourceFile, "Relative TypeScript Workers require the unshadowed global Worker constructor")
+  if (!isUnshadowedGlobal(url.expression, sourceFile)) throw sourceNodeError(url.expression, sourceFile, "Relative TypeScript Workers require the unshadowed global URL constructor")
+  if (url.arguments?.length !== 2 || !isImportMetaUrl(url.arguments[1])) throw sourceNodeError(url, sourceFile, "Relative TypeScript Workers require new URL(relativeLiteral, import.meta.url)")
+  const specifierNode = url.arguments[0]
+  if (!ts.isStringLiteral(specifierNode) || !(specifierNode.text.startsWith("./") || specifierNode.text.startsWith("../"))) throw sourceNodeError(specifierNode, sourceFile, "Relative TypeScript Worker paths must be relative string literals")
+  if (/[\\?#]/.test(specifierNode.text) || !specifierNode.text.endsWith(".worker.ts")) throw sourceNodeError(specifierNode, sourceFile, "Relative TypeScript Worker paths must end in .worker.ts")
+  if (worker.arguments?.length !== 2) throw sourceNodeError(worker, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+  const options = worker.arguments[1]
+  if (!ts.isObjectLiteralExpression(options) || options.properties.length !== 1) throw sourceNodeError(options, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+  const property = options.properties[0]
+  const name = ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined
+  if (name !== "type" || !ts.isStringLiteral(property.initializer) || property.initializer.text !== "module") throw sourceNodeError(property, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+  return { worker, url, specifier: specifierNode.text, options }
+}
+
+function isImportMetaUrl(node) {
+  return ts.isPropertyAccessExpression(node) && node.name.text === "url" && ts.isMetaProperty(node.expression) && node.expression.keywordToken === ts.SyntaxKind.ImportKeyword && node.expression.name.text === "meta"
+}
+
+function isUnshadowedGlobal(identifier, sourceFile) {
+  if (isShadowedIdentifier(identifier, sourceFile)) return false
+  return !sourceFile.statements.some(statement => {
+    if (statementDeclaresName(statement, identifier.text)) return true
+    if (!ts.isImportDeclaration(statement) || !statement.importClause) return false
+    const clause = statement.importClause
+    if (clause.name?.text === identifier.text) return true
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) return clause.namedBindings.name.text === identifier.text
+    return clause.namedBindings && ts.isNamedImports(clause.namedBindings) ? clause.namedBindings.elements.some(entry => entry.name.text === identifier.text) : false
+  })
+}
+
 function nativeCaptureNames(expression, setters) {
   return captureNames(expression, expression.body, setters)
 }
@@ -2641,7 +2804,31 @@ function isShadowedIdentifier(node, scopeRoot) {
 
 function statementDeclaresName(statement, name) {
   if (ts.isVariableStatement(statement)) return statement.declarationList.declarations.some(declaration => bindingNames(declaration.name).includes(name))
-  return (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name?.text === name
+  if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isImportEqualsDeclaration(statement)) return statement.name?.text === name
+  if ((ts.isEnumDeclaration(statement) || ts.isModuleDeclaration(statement)) && !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DeclareKeyword)) return ts.isIdentifier(statement.name) && statement.name.text === name
+  return false
+}
+
+function rejectOrdinaryWorkerImports(sourceFile, file, sourceFiles) {
+  for (const node of sourceFile.statements) {
+    let specifier
+    let runtime = false
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      specifier = node.moduleSpecifier
+      runtime = runtimeModuleReference(node)
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && ts.isStringLiteral(node.moduleReference.expression)) {
+      specifier = node.moduleReference.expression
+      runtime = !node.isTypeOnly
+    }
+    if (!runtime || !specifier?.text.startsWith(".")) continue
+    let target
+    try {
+      target = resolveSourceImport(file, specifier.text, sourceFiles)
+    } catch {
+      continue
+    }
+    if (target.endsWith(".worker.ts")) throw sourceNodeError(specifier, sourceFile, "Worker source modules cannot be imported or re-exported as ordinary runtime modules; use new Worker(new URL(relative.worker.ts, import.meta.url), { type: \"module\" }) inside an inline useEffect() callback")
+  }
 }
 
 function loopDeclaresName(loop, name) {
@@ -2673,7 +2860,12 @@ function clientImportBindings(sourceFile, file, sourceFiles) {
   const bindings = new Map()
   for (const node of sourceFile.statements) {
     if (!ts.isImportDeclaration(node) || !node.importClause || node.importClause.isTypeOnly || !ts.isStringLiteral(node.moduleSpecifier) || !node.moduleSpecifier.text.startsWith(".")) continue
-    const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
+    let target
+    try {
+      target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
+    } catch (error) {
+      throw sourceNodeError(node.moduleSpecifier, sourceFile, error.message)
+    }
     if (node.importClause.name) bindings.set(node.importClause.name.text, { kind: "default", local: node.importClause.name.text, target })
     const named = node.importClause.namedBindings
     if (named && ts.isNamespaceImport(named)) bindings.set(named.name.text, { kind: "namespace", local: named.name.text, target })
@@ -2782,6 +2974,71 @@ function printClientImports(entries, handlerPath) {
   return imports.join("\n")
 }
 
+async function emitWorkers(references, sourceFiles, assetsDirectory, base, minify) {
+  const roots = [...new Set(references.map(reference => reference.root))].sort()
+  if (!roots.length) return new Map()
+  await validateWorkerGraphs(roots, sourceFiles)
+  const workerDirectory = join(assetsDirectory, "workers")
+  await mkdir(workerDirectory, { recursive: true })
+  const result = await bundle({
+    absWorkingDir: root,
+    entryPoints: roots,
+    outbase: sourceDirectory,
+    outdir: workerDirectory,
+    entryNames: "[dir]/[name]-[hash]",
+    chunkNames: "chunks/[name]-[hash]",
+    bundle: true,
+    splitting: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    minify,
+    legalComments: "none",
+    metafile: true,
+    logLevel: "silent"
+  })
+  const emitted = new Map()
+  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 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)}`)
+  return emitted
+}
+
+async function validateWorkerGraphs(roots, sourceFiles) {
+  const visited = new Set()
+  const queue = [...roots]
+  while (queue.length) {
+    const file = queue.shift()
+    if (visited.has(file)) continue
+    visited.add(file)
+    const sourceFile = parseSourceFile(file, await readFile(file, "utf8"))
+    if (containsJsx(sourceFile)) throw sourceNodeError(sourceFile, sourceFile, "Worker modules must not contain JSX")
+    const visit = node => {
+      if (ts.isImportEqualsDeclaration(node)) throw sourceNodeError(node, sourceFile, "TypeScript import-equals declarations are not supported in Worker modules; use a relative ESM import")
+      if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) throw sourceNodeError(node, sourceFile, "Dynamic imports are not supported in Worker modules")
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require") throw sourceNodeError(node, sourceFile, "require() is not supported in Worker modules")
+      ts.forEachChild(node, visit)
+    }
+    visit(sourceFile)
+    for (const node of sourceFile.statements) {
+      if ((!ts.isImportDeclaration(node) && !ts.isExportDeclaration(node)) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier) || !runtimeModuleReference(node)) continue
+      if (!node.moduleSpecifier.text.startsWith(".")) throw sourceNodeError(node.moduleSpecifier, sourceFile, "Worker modules may only use relative runtime imports")
+      try {
+        queue.push(resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles))
+      } catch (error) {
+        const message = error.message.slice(error.message.indexOf("Relative import"))
+        throw sourceNodeError(node.moduleSpecifier, sourceFile, message)
+      }
+    }
+  }
+}
+
 async function collectClientModules(entries, sourceFiles) {
   const modules = new Set()
   const queue = [...new Set(entries)]
@@ -2790,6 +3047,7 @@ async function collectClientModules(entries, sourceFiles) {
     if (modules.has(file)) continue
     const source = await readFile(file, "utf8")
     const sourceFile = parseSourceFile(file, source)
+    rejectWorkerConstructions(sourceFile, sourceFile, "Relative TypeScript Worker construction is only supported directly inside an inline useEffect() callback, not imported client helpers")
     if (containsJsx(sourceFile)) throw new Error(`${relative(root, file)} Imported client helpers must not contain JSX`)
     rejectUnsupportedClientImports(sourceFile, file)
     modules.add(file)

package/framework/core.d.ts

@@ -78,7 +78,7 @@ 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[]; 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[]; itemDependencies?: string[]; listState?: string; cleanup?: true; owner?: string; list?: true }>
     bindings: Array<{
       target: string
       state?: string

package/framework/core.mjs

@@ -66,9 +66,10 @@ function createSignal(id, value) {
   }
 }
 
-export function useEffect(callback, dependencies, module, handler, states, scope, source, cleanup) {
+export function useEffect(callback, dependencies, module, handler, states, scope, source, cleanup, itemDependencies = []) {
   if (!renderContext) throw new Error("useEffect() can only run while rendering a Kudzu component")
   if (typeof callback !== "function" || !Array.isArray(dependencies) || !module || !handler) throw new Error("useEffect() must be compiled with a literal dependency array")
+  if (itemDependencies.length && !renderContext.listDepth) throw new Error(`${source} useEffect() item-property dependencies are only supported in direct keyed row components`)
   const dependencyIds = dependencies.map(dependency => {
     if (!dependency?.[signalMarker] || !validEffectDependency(dependency.value)) throw new Error(`${source} useEffect() dependencies must be primitive Kudzu state or runtime parameter identifiers`)
     return dependency.id
@@ -88,13 +89,16 @@ export function useEffect(callback, dependencies, module, handler, states, scope
       if (!owner) throw new Error(`${source} Keyed row effects must have the same hook order for every item`)
     }
     effects.push(owner)
+    if (!renderContext.listRoot.template) for (const field of itemDependencies) {
+      if (!validEffectDependency(renderContext.listRoot.item[field])) throw new Error(`${source} useEffect() keyed item dependency "${field}" must be a JSON-safe primitive`)
+    }
   } else if (renderContext.conditionDepth) {
     const owners = renderContext.effectOwners.at(-1)
     if (!owners) throw new Error(`${source} useEffect() inside conditional DOM must belong to a rendered function component`)
     owner = nextRenderId("e")
     owners.push(owner)
   }
-  if (!renderContext.listDepth || list) renderContext.effects.push({ module, handler, states, scope, source, renderScope: renderContext.renderScope, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(cleanup ? { cleanup: true } : {}), ...(owner ? { owner } : {}), ...(list ? { list: true } : {}) })
+  if (!renderContext.listDepth || list) renderContext.effects.push({ module, handler, states, scope, source, renderScope: renderContext.renderScope, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(itemDependencies.length ? { itemDependencies, listState: renderContext.listRoot.state } : {}), ...(cleanup ? { cleanup: true } : {}), ...(owner ? { owner } : {}), ...(list ? { list: true } : {}) })
   renderContext.hasBehaviors = true
   renderContext.hasEffects = true
 }
@@ -303,6 +307,7 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
           module: effect.module,
           handler: effect.handler,
           ...(effect.dependencies ? { dependencies: effect.dependencies } : {}),
+          ...(effect.itemDependencies ? { itemDependencies: effect.itemDependencies, listState: effect.listState } : {}),
           ...(effect.cleanup ? { cleanup: true } : {}),
           ...(effect.owner ? { owner: effect.owner } : {}),
           ...(effect.list ? { list: true } : {}),
@@ -682,7 +687,7 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listTemplate = true
     renderContext.listEffectOwners = []
     renderContext.listFields = new Set([node.keyField])
-    renderContext.listRoot = { id, template: true, effects: [], item: {} }
+    renderContext.listRoot = { id, state: node.items.id, template: true, effects: [], item: {} }
     const template = await renderNode(node.render({}), namespace, selectValue)
     if (template.includes("data-k-native-") || template.includes("data-k-effects=")) descriptor.mount = true
     if (template.includes("data-k-effects=")) descriptor.effects = true
@@ -698,7 +703,7 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listTemplate = false
     renderContext.listInitialMarkers = Boolean(descriptor.conditions)
     for (const item of node.items.value) {
-      renderContext.listRoot = { id, key: item[node.keyField], template: false, effects: [], item }
+      renderContext.listRoot = { id, state: node.items.id, key: item[node.keyField], template: false, effects: [], item }
       current += await renderNode(node.render(item), namespace, selectValue)
     }
     renderContext.lists.push(descriptor)

package/framework/list-runtime.js

@@ -1,4 +1,4 @@
-import { browserState, mountDom, registerCommitter, registerMountHook, registerUnmountHook, unmountDom } from "./shared-runtime.js"
+import { browserState, mountDom, notifyListItem, registerCommitter, registerMountHook, registerUnmountHook, unmountDom } from "./shared-runtime.js"
 
 const listTargets = new Map()
 const listRegistrations = new WeakMap()
@@ -102,6 +102,7 @@ function updateList(list) {
       added = true
     } else if (list.values.get(token) !== value) {
       fillListItem(node, item)
+      if (__KUDZU_LIST_ITEM_HOOKS__) notifyListItem(list.descriptor.state, node)
     }
     next.push([token, node])
     values.set(token, value)

package/framework/shared-runtime.js

@@ -19,6 +19,24 @@ const committers = []
 const mountHooks = []
 const unmountHooks = []
 
+/* list-item-hooks */
+const listItemHooks = new Map()
+
+export function registerListItemHook(id, hook) {
+  const hooks = listItemHooks.get(id) ?? new Set()
+  hooks.add(hook)
+  listItemHooks.set(id, hooks)
+  return () => {
+    hooks.delete(hook)
+    if (!hooks.size) listItemHooks.delete(id)
+  }
+}
+
+export function notifyListItem(id, root) {
+  for (const hook of listItemHooks.get(id) ?? []) hook(root)
+}
+/* list-item-hooks-end */
+
 export function registerCommitter(commit) {
   committers.push(commit)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "bin/",
     "framework/",
     "GOAL_A.md",
+    "GOAL_B.md",
     "README.md",
     "LICENSE"
   ],