@kudzujs/core 0.6.4 → 0.6.5

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/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
 
@@ -470,7 +470,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.
 
@@ -645,7 +645,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

@@ -19,6 +19,12 @@ Static routes receive no browser runtime. Command routes receive `runtime.js`; d
 
 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

@@ -172,6 +172,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 +195,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 +233,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 +252,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 +400,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 +688,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 +733,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 +843,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 +866,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 +920,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 +943,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 +954,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 +971,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 +987,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 +1085,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 }
@@ -1563,6 +1609,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 +1829,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 +1855,19 @@ 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 descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
+        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 +1980,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(

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.5",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",