@kudzujs/core 0.8.57 → 0.8.59

package/MIGRATION_ROADMAP.md

@@ -2,7 +2,7 @@
 
 This document is the source of truth for Kudzu's product direction, architecture invariants, and future development order. Read it before extending React-shaped syntax or browser capabilities.
 
-The executable post-`0.8.57` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
+The executable post-`0.8.59` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
 
 [`GOAL_A.md`](./GOAL_A.md) and [`GOAL_B.md`](./GOAL_B.md) are completed capability-validation records. Their commerce and realtime dashboard fixtures prove general lifecycle, navigation, async-workflow, and Worker capabilities; they are not separate product verticals or future priority lists.
 
@@ -148,6 +148,8 @@ This queue orders the next investigations by general migration value. Start only
 - Context actions inline into existing route handler ESM and compile to concrete state operations. Private captures, dynamic Provider objects, and multiple Provider implementations remain diagnosed; no browser Context tree, callback registry, or shared runtime was added.
 - In `0.8.46`, the same Notes migration may omit action-only setters from its public Context type and authored Provider value when the corresponding state remains exposed. Kudzu restores those setters only in build scratch so existing concrete state operations, RouteIR signals, CRUD behavior, and zero-Context runtime output remain unchanged. Fully hidden action state and exposed setters without state remain diagnosed.
 - In `0.8.47`, a specialized setter-callback child may initialize local state directly from one primitive parent state prop. Build scratch reads the parent signal's build value while retaining the structural prop signal for handlers/effects. `0.8.57` extends that exact path to a parent state authored with one JSON-safe plain-object literal; independent child draft state and parent commit behavior pass in the FIRE-derived callback fixture. Array props, aliases, property paths, composed expressions, and object `.toString()` remain diagnosed.
+- In `0.8.58`, a direct keyed item prop may initialize one row-owned object draft. Retained keys preserve that draft and DOM identity through reorder; removal releases it, and re-adding the key clones the current item into fresh state. Aliases, property paths, composed expressions, and indirect item props remain diagnosed.
+- In `0.8.59`, the ClimateCompatibleGrowth teaching-kit `Dropdown` migration may initialize local array state from one direct parent array-state prop and commit it through a direct `on*` callback or matching `set*` setter prop. Parent and child arrays remain independently owned, mounted drafts do not auto-synchronize, and aliases, property paths, composed arrays, indirect callbacks, and additional `set*` forwarding remain diagnosed.
 - In `0.8.48`, one setter-callback prop may be called once from each of multiple direct intrinsic event handlers in the specialized leaf. Each call lowers independently to the same parent signal; forwarding fan-out, aliases, non-handler uses, and repeated calls inside one handler remain diagnosed, and no callback registry or handler runtime is added.
 - In `0.8.49`, one component may forward the same destructured setter callback directly through multiple child component `on*` props. Each branch specializes independently to the original parent signal within the existing three-boundary limit; aliases, ordinary props, spreads, and a fourth boundary remain diagnosed.
 

package/PERFORMANCE.md

@@ -6,7 +6,15 @@ Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm ru
 
 The maintained 2026-08-13 comparison used Node 24.14.0 and an Intel Core i5-9500 Linux x64 host, one warm-up, and seven alternating fresh-process samples against clean `v0.8.44`. A narrow fast path skips Kudzu semantic transformation for 450 plain `.ts` modules whose runtime edges are exclusively resolvable relative TypeScript imports or exports; all other modules retain the existing transformer. Compile median fell from 2,323.9 ms to 1,413.2 ms (39.2%) and clean-build median from 3,325.3 ms to 2,382.4 ms (28.4%); every paired sample improved. Compile peak-RSS median fell from 571.2 MiB to 552.6 MiB, while build peak RSS was 570.9 MiB versus 568.8 MiB. Compiler scratch fell from 7,328,390 to 1,971,061 bytes. Both targets emitted the same 50 static HTML files, 10,980 bytes, and deploy SHA-256 `e107d78a7f55bc8a1af0ea6e53efeffa19b3d44d21c892484d103fa346e7ba7b`. This is a source-scale compiler comparison, not a cross-framework result.
 
-## Current 0.8.57 Release Snapshot
+## Current 0.8.59 Release Snapshot
+
+Kudzu 0.8.59 broadens existing compile-time setter-child specialization to one direct parent array-state prop and one direct `set*` setter prop in that prop-derived state shape. It adds no browser runtime code and makes no timing claim.
+
+## Maintained 0.8.58 Release Snapshot
+
+Kudzu 0.8.58 adds one narrow keyed-item initializer descriptor to the existing complex row-state path. Routes without that descriptor, including static siblings, retain their existing capability output. This release makes no timing claim.
+
+## Maintained 0.8.57 Release Snapshot
 
 Kudzu 0.8.57 broadens an existing compiler proof from direct primitive parent state to direct JSON-safe plain-object parent state for specialized child draft initialization. It adds no browser runtime code and makes no timing claim.
 

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.57 - Plain-object prop draft state.** Specialized setter-callback children can initialize independent local draft state from one direct parent state prop authored with a JSON-safe plain-object literal, without new IR or runtime code. Read the [release notes](./RELEASES.md#0857---plain-object-prop-draft-state), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.57), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.59 - Array prop draft state.** Specialized children can initialize independent array draft state from one direct parent state prop and retain an authored direct `set*` setter prop without a component runtime. Read the [release notes](./RELEASES.md#0859---array-prop-draft-state), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.59), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,67 @@
 # Kudzu Releases
 
+## 0.8.59 - Array prop draft state
+
+Kudzu 0.8.59 lets a specialized child initialize independent local array draft state directly from one parent array-state prop while preserving an authored direct `set*` setter prop.
+
+### Changed in 0.8.59
+
+- `const [draft, setDraft] = useState(selectedItems)` compiles when `selectedItems` is one direct prop backed by a parent `useState([...])` literal.
+- A direct parent setter may enter that prop-draft specialization through an `on*` prop or an authored `set*` prop such as `setSelectedItems`.
+- Parent and child retain distinct state IDs and independently serialized arrays.
+- Mounted drafts remain local until the authored handler explicitly commits them to parent state.
+
+### Boundaries
+
+- `set*` support is limited to prop-derived state components; unrelated effect setter props retain their existing path.
+- Additional forwarding remains `on*`-only.
+- Aliases, property paths, array spreads, composed expressions, indirect callbacks, and automatic prop synchronization remain rejected.
+- No runtime module, VDOM, hydration, or retained component tree is added.
+
+### Validation
+
+- A fixture reduced from ClimateCompatibleGrowth's MIT-licensed teaching-kit `Dropdown` preserves its direct `selectedItems` and `setSelectedItems` source shape.
+- Browser coverage proves child draft independence, parent replacement without draft synchronization, explicit commit, and a static zero-JavaScript sibling.
+- Existing conditional-effect `setResult` props remain outside setter-callback specialization.
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 225 tests and 174 generated pages.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.8.59
+```
+
+## 0.8.58 - Keyed item draft state
+
+Kudzu 0.8.58 lets a keyed row initialize independent local object draft state directly from its keyed item prop.
+
+### Changed in 0.8.58
+
+- `const [draft, setDraft] = useState(todo)` compiles when `todo` is the direct item prop of a keyed row.
+- RouteIR marks the state with a narrow `list-item` initializer descriptor.
+- New keys clone the current item into existing key-scoped row-state ownership without a component runtime.
+- Retained keys preserve their draft state and DOM identity through item updates and reorder.
+
+### Boundaries
+
+- Removing a key releases its draft; re-adding that key creates a fresh draft from the current item.
+- Aliases, property paths, composed expressions, and indirect item props remain rejected.
+- This does not add prop-to-state synchronization, array prop drafts, a VDOM, hydration, or a retained component tree.
+- Static sibling routes remain complete HTML with zero JavaScript.
+
+### Validation
+
+- The Todo reducer fixture proves independent row drafts, retained draft and DOM identity through reorder, exact removal, and fresh remount initialization.
+- A dedicated alias fixture remains fail-closed with a source-located diagnostic.
+- RouteIR records the `list-item` initializer and capability planning emits the existing complex row-state path only where required.
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 224 tests and 173 generated pages.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.8.58
+```
+
 ## 0.8.57 - Plain-object prop draft state
 
 Kudzu 0.8.57 lets a specialized setter-callback child initialize independent local draft state directly from one parent state prop authored with a JSON-safe plain-object literal.

package/docs/next-architecture/README.md

@@ -11,7 +11,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
 
-The active post-`0.8.57` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive and plain-object prop state initialization, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, package-neutral shared-state/action IR, browser-only package imports and private mutable refs in owned effects, route/layout CSS closure, structural per-route capability/chunk reporting, signature-keyed runtime families, incremental source and affected-route development builds, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. ResourceIR remains research for cross-owner transports and subscriptions; array prop drafts, range ownership, virtualization, and optimistic transactions still require independent fixtures. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+The active post-`0.8.59` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive, plain-object, array-prop, and keyed-item draft state initialization, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, package-neutral shared-state/action IR, browser-only package imports and private mutable refs in owned effects, route/layout CSS closure, structural per-route capability/chunk reporting, signature-keyed runtime families, incremental source and affected-route development builds, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. ResourceIR remains research for cross-owner transports and subscriptions; range ownership, virtualization, and optimistic transactions still require independent fixtures. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
 
 ## Required Invariants
 

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.57` architecture, built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.8.59` architecture, built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 

package/docs/next-architecture/large-application-ai-native-roadmap.md

@@ -379,7 +379,7 @@ function increment(value) { setCount(value + 1) }; increment(count)
 After the relevant P0 foundations, investigate capabilities in this order:
 
 1. Property-level derived dependencies over ordinary object state. **Completed in `0.8.40`:** direct property paths and top-level immutable primitive locals over object state reuse tagged DerivedIR, subscribe to the source signal, and compare selected values with `Object.is`; whole-object and dynamic dependencies remain rejected.
-2. Multi-boundary component/prop/callback/ref/context dataflow. **Three-boundary callback/ref ownership completed in `0.8.43`; collision-free Context action-private state completed in `0.8.44`; action-only Provider setter exposure removed in `0.8.46`; direct primitive prop state initialization completed in `0.8.47`; repeated direct leaf-handler callback use completed in `0.8.48`; direct child callback fan-out completed in `0.8.49`; direct plain-object prop state initialization completed in `0.8.57`:** forwarding preserves parent SignalIR, Context action lowering uses compiler-owned aliases when consumer locals reuse Provider state/setter names, action-required setters may remain compiler-only when their state is publicly exposed, specialized children may seed local state from a direct parent signal authored with a serializable primitive or plain-object literal, and one callback may branch through multiple component `on*` props and intrinsic handlers. The FIRE-derived object editor proves independent child draft updates and parent commit behavior without new IR or runtime code. A fourth callback boundary, callback aliases/non-handler uses, fully hidden Context state, array prop initializers, aliases, property paths, and composed expressions remain fail-closed. Broader prop, callback, ref, and Context graphs remain migration-led work.
+2. Multi-boundary component/prop/callback/ref/context dataflow. **Three-boundary callback/ref ownership completed in `0.8.43`; collision-free Context action-private state completed in `0.8.44`; action-only Provider setter exposure removed in `0.8.46`; direct primitive prop state initialization completed in `0.8.47`; repeated direct leaf-handler callback use completed in `0.8.48`; direct child callback fan-out completed in `0.8.49`; direct plain-object prop state initialization completed in `0.8.57`; direct keyed item draft initialization completed in `0.8.58`; direct array prop draft initialization completed in `0.8.59`:** forwarding preserves parent SignalIR, Context action lowering uses compiler-owned aliases when consumer locals reuse Provider state/setter names, action-required setters may remain compiler-only when their state is publicly exposed, specialized children may seed local state from a direct parent signal authored with a serializable primitive, plain-object, or array literal, keyed rows may seed object draft state from their direct item prop, and one callback may branch through multiple component `on*` props and intrinsic handlers. A direct first-boundary parent setter may also retain its authored matching `set*` prop name; additional forwarding remains restricted to `on*` props. The ClimateCompatibleGrowth-derived dropdown proves independent array drafts, no automatic mounted prop synchronization, explicit parent commit, and zero-JavaScript static sibling output. A fourth callback boundary, callback aliases/non-handler uses, fully hidden Context state, additional `set*` forwarding, keyed item aliases, property paths, and composed expressions remain fail-closed. Broader prop, callback, ref, and Context graphs remain migration-led work.
 3. Package-neutral shared state/actions and migration of current Zustand internals. **Completed in `0.8.50`:** Zustand source normalization produces one generic shared-state adapter descriptor; selectors and handlers register JSON-safe SharedStateIR/SharedActionIR records, handler lowering consumes package-neutral actions, and existing RouteIR, layout ownership, same-turn updates, navigation persistence, and browser output remain unchanged. Redux/RTK and public adapter APIs remain unsupported.
 4. Browser-only package imports in owned effect/resource modules. **Completed in `0.8.51` for effects:** direct package references in inline effect setup/cleanup callbacks use existing package import records and route-owned effect ESM bundling; build-time component modules and static siblings omit the package. Helper-indirect, render-time, dynamic-import, and ResourceIR package graphs remain unsupported.
 5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics. **Completed in `0.8.52` without ResourceIR for private ownership:** the E2B terminal and route-owned WebSocket fixtures lower refs used exclusively by one inline effect to invocation-private closure objects, while existing effect ownership supplies replacement, cleanup, stale setter invalidation, navigation, and BFCache disposal. ResourceIR remains unapproved and now requires independent cross-owner transport/subscription fixtures that cannot fit this narrower model.
@@ -481,4 +481,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-PR 1 through PR 12, the `0.8.40` property-dependency slice, the `0.8.41` and `0.8.43` direct multi-boundary callback/ref slices, the `0.8.44` Context alias slice, the `0.8.46` action-only Provider setter slice, the `0.8.47` direct primitive and `0.8.57` plain-object prop initializer slices, the `0.8.48` repeated direct leaf-handler callback slice, the `0.8.49` direct child callback fan-out slice, the `0.8.50` package-neutral shared-state/action slice, the `0.8.51` owned-effect package import slice, the `0.8.52` effect-private mutable-ref slice, the `0.8.53` route/layout CSS closure slice, the `0.8.54` structural per-route capability/chunk report, the `0.8.55` signature-keyed runtime families, item 7 incremental source and affected-route builds, and the `0.8.42` measured route-output optimization are complete. Continue migration-led semantic generalization; keep array prop drafts and ResourceIR limited to independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.
+PR 1 through PR 12, the `0.8.40` property-dependency slice, the `0.8.41` and `0.8.43` direct multi-boundary callback/ref slices, the `0.8.44` Context alias slice, the `0.8.46` action-only Provider setter slice, the `0.8.47` direct primitive, `0.8.57` plain-object prop, `0.8.58` direct keyed item, and `0.8.59` direct array prop initializer slices, the `0.8.48` repeated direct leaf-handler callback slice, the `0.8.49` direct child callback fan-out slice, the `0.8.50` package-neutral shared-state/action slice, the `0.8.51` owned-effect package import slice, the `0.8.52` effect-private mutable-ref slice, the `0.8.53` route/layout CSS closure slice, the `0.8.54` structural per-route capability/chunk report, the `0.8.55` signature-keyed runtime families, item 7 incremental source and affected-route builds, and the `0.8.42` measured route-output optimization are complete. Continue migration-led semantic generalization; keep ResourceIR limited to independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.57` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.59` are completed scopes represented by package/release records.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -48,6 +48,8 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.55` | Emit deduplicated signature-keyed runtime families while preserving navigation-group singleton ownership. | Equal standalone signatures share files, different signatures isolate output, grouped routes share one union family, and static routes emit no runtime. |
 | `0.8.56` | Recompile and rerender only source-affected routes during development. | A route-owned helper edit recompiles two of four modules, rerenders one of two pages, and emits byte-identical deploy output to a fresh full build. |
 | `0.8.57` | Initialize specialized child draft state from one direct parent plain-object state prop. | A FIRE-derived editor preserves independent child draft state and parent commit behavior; arrays, aliases, property paths, and composed expressions remain rejected without runtime changes. |
+| `0.8.58` | Initialize keyed row object draft state from the direct keyed item prop. | Todo reducer rows retain independent drafts and DOM identity across reorder, release state on removal, recreate drafts from the current item on remount, reject aliases, and preserve a static zero-JavaScript sibling. |
+| `0.8.59` | Initialize specialized child draft state from one direct parent array-state prop and accept a direct matching `set*` setter prop. | A ClimateCompatibleGrowth-derived dropdown preserves independent array drafts, explicit parent commit, source naming, nearby diagnostics, and a static zero-JavaScript sibling without runtime changes. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -90,7 +90,7 @@ Rendered collection selectors compile immutable local aliases and inline `(item)
 
 The reduced `useReducer` form reuses ordinary state slots and React's pure reducer contract. An optional inline, same-file, or relative-imported synchronous one-parameter initializer may derive a directly serializable literal only from its directly serializable initial argument; the compiler substitutes that argument and lowers the call to the ordinary two-argument ownership path. A direct dispatch in a compiled handler becomes a functional `set` whose reducer is bundled from a relative TypeScript module into that handler graph. Pure reducer-owned keyed lists reuse unchanged item identities for reorder, one removal, and append fast paths; ordinary `useState` lists retain full validation. One direct dispatch prop into a same-file or relative-imported synchronous component, including a direct keyed row, is specialized to intrinsic JSX at the call site, so its handler retains the parent reducer scope and no dispatch capture or child handler asset is emitted. A reducer row reads the latest item through the existing list scope and uses the same multiple serializable state, effect, condition, and object-ref specialization as other keyed rows. Relative TypeScript imports referenced inside that child handler receive collision-free call-site aliases and join the parent handler graph. One nested relative-imported intrinsic child may receive an inline or simple `const` callback containing dispatch; the compiler recursively substitutes that callback once and omits the nested child handler asset. Missing directly serializable literal defaults and direct intrinsic rest props in these reducer specializations are substituted at the same call site. Reducer-free routes and shared runtimes are unchanged; no reducer runtime or browser component instance exists.
 
-A direct setter or inline/simple `const` setter callback may cross one same-file or relative-imported component boundary and two additional direct forwarding components before an intrinsic handler invokes it exactly once. Value adapters such as `event => onValueChange(event.currentTarget.value)` specialize into the parent setter graph instead of serializing a function. Each forwarding component must destructure and directly forward the callback once as an `on*` JSX prop; fourth-boundary forwarding, aliases, spreads, intermediate adapters, and repeated uses remain unsupported. Specialized children may own directly serializable `useState()` values or initialize state from one direct parent state prop authored with a serializable primitive or plain-object literal; zero-argument `.toString()` remains primitive-only. Array props, aliases, property paths, and composed initializers remain unsupported. Specialized children may also own `useId()` values, supported effects, and object refs initialized with `null`. Same-file and relative-imported presentation components recursively specialize away; nested hooks join the same generated owner only on unconditional or statically truthy paths. A parent-owned `null`-initialized object ref may follow the proven tree to the direct intrinsic root. These remain compiler-owned descriptors: conditional removal drops the handler with the element, deletes child state, resolves refs to `null`, and runs effect cleanup, while remount creates fresh ownership and dependency effects synchronize prop-derived state without retaining a component instance.
+A direct setter or inline/simple `const` setter callback may cross one same-file or relative-imported component boundary and two additional direct forwarding components before an intrinsic handler invokes it exactly once. Value adapters such as `event => onValueChange(event.currentTarget.value)` specialize into the parent setter graph instead of serializing a function. The first boundary may pass a direct parent setter through an `on*` or `set*` prop; each additional forwarding component must destructure and directly forward the callback once as an `on*` JSX prop. Fourth-boundary forwarding, additional `set*` forwarding, aliases, spreads, intermediate adapters, and repeated uses remain unsupported. Specialized children may own directly serializable `useState()` values or initialize state from one direct parent state prop authored with a serializable primitive, plain-object, or array literal; zero-argument `.toString()` remains primitive-only. Prop aliases, property paths, and composed initializers remain unsupported. Specialized children may also own `useId()` values, supported effects, and object refs initialized with `null`. Same-file and relative-imported presentation components recursively specialize away; nested hooks join the same generated owner only on unconditional or statically truthy paths. A parent-owned `null`-initialized object ref may follow the proven tree to the direct intrinsic root. These remain compiler-owned descriptors: conditional removal drops the handler with the element, deletes child state, resolves refs to `null`, and runs effect cleanup, while remount creates fresh ownership and dependency effects synchronize prop-derived state without retaining a component instance.
 
 `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.
 

package/framework/compiler/list-runtime-codegen.mjs

@@ -40,7 +40,7 @@ export function generateListRuntime(source, capabilityIR) {
   if (lists.rowHooks && !lists.generalRowHooks) runtime = replaceSequenceRequired(replaceRequired(runtime, /\/\* general-row-hooks \*\/[\s\S]*?\/\* general-row-hooks-end \*\/\n/, "", "general row hooks"), [
     ["initializeGeneralRowHooks", "initializeRowStates", "general row initializer", true],
     ["if (__KUDZU_LIST_ROW_HOOKS__) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index], roots[index], nested?.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && descriptor.rowStates) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index])", "flat row initialization"],
-    ["if (__KUDZU_LIST_ROW_HOOKS__) initializeRowStates(list.descriptor, key, node, list.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)", "flat row add", true],
+    ["if (__KUDZU_LIST_ROW_HOOKS__) initializeRowStates(list.descriptor, key, node, list.owner, item)", "if (__KUDZU_LIST_ROW_HOOKS__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)", "flat row add", true],
     ["for (const node of registration.list.roots.values()) deleteRowStates(registration.list.descriptor, ownershipPaths.get(node))", "for (const token of registration.list.roots.keys()) deleteFlatRowStates(registration.list.descriptor, token)", "flat registration cleanup"],
     ["deleteRowStates(list.descriptor, ownershipPaths.get(node))", "deleteFlatRowStates(list.descriptor, token)", "flat row cleanup", true],
     ["  if (__KUDZU_LIST_ROW_HOOKS__) replaceRowIds(root, rowReplacements.get(root))\n", "", "row ID replacement"],

package/framework/compiler/route-capability-planner.mjs

@@ -70,7 +70,7 @@ export function planRouteCapabilities(records, { navigationRouteCount = 0 } = {}
       lists.effects ||= Boolean(list.effects)
       lists.rowHooks ||= Boolean(list.rowStates?.length || list.rowRefs?.length)
       lists.rowRefs ||= Boolean(list.rowRefs?.length)
-      lists.complexRowState ||= Boolean(list.rowStates?.some(state => state.initialValue !== null && typeof state.initialValue === "object"))
+      lists.complexRowState ||= Boolean(list.rowStates?.some(state => state.initializer === "list-item" || state.initialValue !== null && typeof state.initialValue === "object"))
       lists.nested ||= Boolean(list.ownerField)
       lists.selectors ||= Boolean(list.selector)
       lists.calculated ||= Boolean(list.source)

package/framework/compiler/route-ir.mjs

@@ -155,7 +155,7 @@ function assertList(list, index, ids, stateIds, listIds, parentByChild) {
     if (!isRecord(child) || !nonempty(child.id) || !nonempty(child.field) || typeof child.key !== "string" && child.key !== null || parentByChild.has(child.id)) throw new Error(`${label} has invalid or duplicate child ${JSON.stringify(child?.id)}`)
     parentByChild.set(child.id, list.id)
   }
-  for (const row of list.rowStates ?? []) if (!isRecord(row) || !rowTemplate(row.id) || !Object.hasOwn(row, "initialValue")) throw new Error(`${label} has invalid row state`)
+  for (const row of list.rowStates ?? []) if (!isRecord(row) || !rowTemplate(row.id) || !Object.hasOwn(row, "initialValue") || row.initializer !== undefined && row.initializer !== "list-item") throw new Error(`${label} has invalid row state`)
   for (const row of [...(list.rowRefs ?? []), ...(list.rowConditions ?? [])]) if (!rowTemplate(row)) throw new Error(`${label} has invalid row ownership ID`)
   if (list.seed && list.valueSeed || list.seed !== undefined && !validSeed(list.seed) || list.valueSeed !== undefined && !validSeed(list.valueSeed)) throw new Error(`${label} has invalid seed`)
 }

package/framework/compiler/source-compiler.mjs

@@ -1157,7 +1157,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           for (const state of aggregate.ordinaryStates) setters.set(state.setter, state.state)
           const stateOwners = new Map(parentStateOwners)
           for (const state of aggregate.ordinaryStates) stateOwners.set(state.state, state.analysisReference)
-          const callbackProps = jsxSetterCallbackProps(node, setters, functionsForNode(node), reducersForNode(node, reducersByFunction))
+          const callbackProps = supportedSetterCallbackProps(component, jsxSetterCallbackProps(node, setters, functionsForNode(node), reducersForNode(node, reducersByFunction)))
           const callbackSubstitutions = new Map()
           if (callbackProps.length) {
             if (!callbackDepth) fail(node, "Setter callbacks cannot cross more than three component boundaries")
@@ -1295,7 +1295,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     }
     for (const [name, component] of components) {
       for (const call of jsxTagUses(sourceFile, name)) {
-        const callbackProps = jsxSetterCallbackProps(call, settersByFunction.get(nearestFunction(call)) ?? new Map(), functionsForNode(call), reducersForNode(call, reducersByFunction))
+        const callbackProps = supportedSetterCallbackProps(component.function, jsxSetterCallbackProps(call, settersByFunction.get(nearestFunction(call)) ?? new Map(), functionsForNode(call), reducersForNode(call, reducersByFunction)))
         if (callbackProps.length) specializeSetterCallbacks(call, component.function, callbackProps, false)
       }
     }
@@ -1311,7 +1311,10 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       } catch {
         fail(callbackCalls[0].call, "Setter callback props require a component imported from a relative TypeScript module")
       }
-      for (const { call, callbackProps } of callbackCalls) specializeSetterCallbacks(call, component, callbackProps, true)
+      for (const { call, callbackProps } of callbackCalls) {
+        const supportedProps = supportedSetterCallbackProps(component, callbackProps)
+        if (supportedProps.length) specializeSetterCallbacks(call, component, supportedProps, true)
+      }
     }
     for (const [name, component] of components) {
       const calls = jsxTagUses(sourceFile, name)
@@ -2114,14 +2117,26 @@ function jsxCallHasDirectStateProp(call, setters) {
 function jsxSetterCallbackProps(call, setters, functions, reducers) {
   const attributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
   return attributes.properties.flatMap(attribute => {
-    if (!ts.isJsxAttribute(attribute) || !/^on[A-Z]/.test(attribute.name.text) || !attribute.initializer || !ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression) return []
+    if (!ts.isJsxAttribute(attribute) || !attribute.initializer || !ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression) return []
     const value = unwrapExpression(attribute.initializer.expression)
-    if (ts.isIdentifier(value) && setters.has(value.text)) return [attribute.name.text]
+    if (ts.isIdentifier(value) && setters.has(value.text) && (/^on[A-Z]/.test(attribute.name.text) || /^set[A-Z]/.test(attribute.name.text))) return [attribute.name.text]
+    if (!/^on[A-Z]/.test(attribute.name.text)) return []
     const callback = ts.isArrowFunction(value) || ts.isFunctionExpression(value) ? value : ts.isIdentifier(value) ? functions.get(value.text) : undefined
     return callback && !nativeCaptureNames(callback, setters).size && !referencedReducerDispatches(callback.body, reducers, callback).size && referencedStateNames(callback.body, setters, callback).size ? [attribute.name.text] : []
   })
 }
 
+function componentHasDirectPropStateInitializer(component) {
+  if (!component || component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name) || !ts.isBlock(component.body)) return false
+  const props = new Set(component.parameters[0].name.elements.filter(element => !element.dotDotDotToken && ts.isIdentifier(element.name)).map(element => element.name.text))
+  return component.body.statements.some(statement => ts.isVariableStatement(statement) && statement.declarationList.declarations.some(declaration => declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useState" && declaration.initializer.arguments.length === 1 && ts.isIdentifier(declaration.initializer.arguments[0]) && props.has(declaration.initializer.arguments[0].text)))
+}
+
+function supportedSetterCallbackProps(component, props) {
+  const acceptsSetProp = componentHasDirectPropStateInitializer(component)
+  return props.filter(prop => /^on[A-Z]/.test(prop) || acceptsSetProp)
+}
+
 function jsxCallHasDirectReducerProp(call, reducers) {
   const attributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
   return attributes.properties.some(attribute => {
@@ -2182,6 +2197,7 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
   const analysis = { values: [], conditions: [], nested: [] }
   const root = parts.root
   const item = parts.item
+  for (const state of rowStates) if (state.initializer && state.initializer !== item) throw sourceNodeError(state.source.initializer, state.source.getSourceFile(), "Keyed row useState() item initializer must be the direct keyed item prop")
   const nestedDiagnostic = "Nested keyed list collections must be a direct property of the parent item"
   const validateElement = node => {
     const tag = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName
@@ -2492,13 +2508,15 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
       if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useState") {
         const hookLabel = ordinaryHooks ? "Setter-callback component" : "Keyed row"
         const initialArgument = declaration.initializer.arguments[0]
-        const propReceiver = ordinaryHooks && initialArgument && (ts.isIdentifier(initialArgument) ? initialArgument : ts.isCallExpression(initialArgument) && initialArgument.arguments.length === 0 && !initialArgument.questionDotToken && ts.isPropertyAccessExpression(initialArgument.expression) && !initialArgument.expression.questionDotToken && initialArgument.expression.name.text === "toString" && ts.isIdentifier(initialArgument.expression.expression) ? initialArgument.expression.expression : undefined)
+        const propReceiver = initialArgument && (ordinaryHooks ? ts.isIdentifier(initialArgument) ? initialArgument : ts.isCallExpression(initialArgument) && initialArgument.arguments.length === 0 && !initialArgument.questionDotToken && ts.isPropertyAccessExpression(initialArgument.expression) && !initialArgument.expression.questionDotToken && initialArgument.expression.name.text === "toString" && ts.isIdentifier(initialArgument.expression.expression) ? initialArgument.expression.expression : undefined : ts.isIdentifier(initialArgument) ? initialArgument : undefined)
         const substitutedProp = propReceiver ? substitutions.get(propReceiver.text) : undefined
         const substitutedState = substitutedProp && ts.isIdentifier(unwrapExpression(substitutedProp)) ? unwrapExpression(substitutedProp).text : undefined
         const directProp = ts.isIdentifier(initialArgument)
         const parentInitializer = substitutedState ? directStateInitializer(call, substitutedState) : undefined
-        const propInitializer = substitutedState && ordinaryStateNames.has(substitutedState) && parentInitializer && (isPrimitiveDefaultLiteral(parentInitializer) || directProp && ts.isObjectLiteralExpression(parentInitializer))
-        if (declaration.initializer.arguments.length !== 1 || !isSerializableStateLiteral(initialArgument) && !propInitializer) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useState() must use one directly serializable primitive, plain object, or array initial value${ordinaryHooks ? " or direct state prop initialized with a primitive or plain object; .toString() requires a primitive prop" : ""}; other dynamic initializers are not supported`)
+        const propInitializer = ordinaryHooks && substitutedState && ordinaryStateNames.has(substitutedState) && parentInitializer && (isPrimitiveDefaultLiteral(parentInitializer) || directProp && (ts.isObjectLiteralExpression(parentInitializer) || ts.isArrayLiteralExpression(parentInitializer)))
+        const rowItemProp = propReceiver && elements.find(element => !element.dotDotDotToken && ts.isIdentifier(element.name) && element.name.text === propReceiver.text)
+        const rowItemInitializer = !ordinaryHooks && directProp && substitutedState && rowItemProp && directProps.has((rowItemProp.propertyName ?? rowItemProp.name).text)
+        if (declaration.initializer.arguments.length !== 1 || !isSerializableStateLiteral(initialArgument) && !propInitializer && !rowItemInitializer) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useState() must use one directly serializable primitive, plain object, or array initial value${ordinaryHooks ? " or direct state prop initialized with a primitive, plain object, or array; .toString() requires a primitive prop" : " or the direct keyed item prop"}; other dynamic initializers are not supported`)
         if (!ts.isArrayBindingPattern(declaration.name) || declaration.name.elements.length !== 2 || declaration.name.elements.some(element => !element || !ts.isBindingElement(element) || !ts.isIdentifier(element.name) || element.initializer || element.dotDotDotToken)) throw sourceNodeError(declaration.name, component.getSourceFile(), `${hookLabel} useState() must use [state, setter] identifier destructuring`)
         const suffix = `${Math.max(0, call.pos)}_${ordinaryHooks ? ordinaryStates.length : rowStates.length}`
         const state = ordinaryHooks ? `__kComponentState${suffix}` : `__kRowState${suffix}`
@@ -2509,16 +2527,18 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
           factory.createBindingElement(undefined, undefined, factory.createIdentifier(state)),
           factory.createBindingElement(undefined, undefined, factory.createIdentifier(setter))
         ])
-        const initialValue = propInitializer
+        const initialValue = rowItemInitializer
+          ? cloneAst(substitutedProp, factory, context)
+          : propInitializer
           ? ts.isIdentifier(initialArgument)
             ? factory.createPropertyAccessExpression(cloneAst(substitutedProp, factory, context), "value")
             : substituteClone(initialArgument, substitutions, factory, context)
           : cloneAst(initialArgument, factory, context)
         synthesizeTree(initialValue)
-        const initializer = factory.createCallExpression(factory.createIdentifier(ordinaryHooks ? "__kComponentUseState" : "__kRowUseState"), undefined, [initialValue])
+        const initializer = factory.createCallExpression(factory.createIdentifier(ordinaryHooks ? "__kComponentUseState" : "__kRowUseState"), undefined, rowItemInitializer ? [initialValue, factory.createStringLiteral(state), factory.createStringLiteral("list-item")] : [initialValue])
         hookDeclarations.push(factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(binding, undefined, undefined, initializer)], ts.NodeFlags.Const)))
         if (ordinaryHooks) ordinaryStates.push({ state, setter, source: declaration })
-        else rowStates.push({ state, setter, source: declaration })
+        else rowStates.push({ state, setter, source: declaration, ...(rowItemInitializer ? { initializer: substitutedState } : {}) })
         continue
       }
       if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useRef") {

package/framework/core.d.ts

@@ -125,7 +125,7 @@ export type ListDescriptor = {
   expressions?: true
   expressionAttributes?: true
   expressionStates?: string[]
-  rowStates?: Array<{ id: string; initialValue: unknown }>
+  rowStates?: Array<{ id: string; initialValue: unknown; initializer?: "list-item" }>
   rowConditions?: string[]
   rowRefs?: string[]
   fastRelease?: true

package/framework/core.mjs

@@ -53,12 +53,12 @@ export function useId() {
   return `k-${nextRenderId("i")}`
 }
 
-export function useState(initialValue, name) {
+export function useState(initialValue, name, initializer) {
   if (!renderContext) {
     throw new Error("useState() can only run while rendering a Kudzu component")
   }
 
-  const id = renderContext.listRoot || renderContext.listRowRoot ? nextRowRenderId("s", initialValue) : nextRenderId("s")
+  const id = renderContext.listRoot || renderContext.listRowRoot ? nextRowRenderId("s", initialValue, initializer) : nextRenderId("s")
   const signal = createSignal(id, initialValue)
 
   const setter = () => {
@@ -1005,7 +1005,7 @@ function nextRenderId(kind) {
   return `${kind}${renderContext[counters[kind]]++}`
 }
 
-function nextRowRenderId(kind, initialValue) {
+function nextRowRenderId(kind, initialValue, initializer) {
   const root = renderContext.listRoot ?? renderContext.listRowRoot
   const index = root.rowIndexes[kind]++
   const entries = kind === "s" ? renderContext.listRowStates : kind === "r" ? renderContext.listRowRefs : renderContext.listRowConditions
@@ -1013,7 +1013,7 @@ function nextRowRenderId(kind, initialValue) {
     const entry = entries[index]
     if (entry) return entry.id
     const id = `${nextRenderId(kind)}:$k`
-    entries[index] = kind === "s" ? { id, initialValue } : { id }
+    entries[index] = kind === "s" ? { id, initialValue, ...(initializer ? { initializer } : {}) } : { id }
     return id
   }
   const entry = entries[index]

package/framework/list-runtime.js

@@ -237,7 +237,7 @@ function updateList(list) {
       if (!node) throw new Error("Keyed list template has no root element")
       node.removeAttribute("data-k-list-root")
       if (__KUDZU_NESTED_LISTS__ && list.childPrototypes) childPrototypes.set(node, list.childPrototypes)
-      if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner)
+      if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner, item)
       if (staticRoot) listItems.set(node, item)
       else if (list.parts.directFill) {
         listItems.set(node, item)
@@ -401,7 +401,7 @@ function updateStableList(list, items) {
     if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
     if (!node) throw new Error("Keyed list template has no root element")
     node.removeAttribute("data-k-list-root")
-    if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner)
+    if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner, item)
     if (list.parts.directFill) fillStructuralListParts(list.parts, node, item)
     else fillListItem(node, item, list.descriptor.nested, index, mapListItemParts(list.parts, node, list.descriptor.nested))
     fragment.append(node)
@@ -578,7 +578,7 @@ function addListRoot(list, { item, index = list.roots.size, key, token, value })
   if (!node) throw new Error("Keyed list template has no root element")
   node.removeAttribute("data-k-list-root")
   if (__KUDZU_NESTED_LISTS__ && list.childPrototypes) childPrototypes.set(node, list.childPrototypes)
-  if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner)
+  if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner, item)
   mapListItemParts(list.parts, node, list.descriptor.nested)
   fillListItem(node, item, list.descriptor.nested, index)
   const parent = list.container ?? list.start.parentNode
@@ -1046,7 +1046,7 @@ function keyToken(key) {
 }
 
 /* general-row-hooks */
-function initializeGeneralRowHooks(descriptor, key, root, owner) {
+function initializeGeneralRowHooks(descriptor, key, root, owner, item) {
   const token = keyToken(key)
   const path = [...(ownershipPaths.get(owner) ?? []), `${descriptor.id}=${token}`]
   ownershipPaths.set(root, path)
@@ -1055,7 +1055,7 @@ function initializeGeneralRowHooks(descriptor, key, root, owner) {
   const replacements = new Map()
   for (const state of descriptor.rowStates ?? []) {
     const id = rowStateId(state.id, statePath)
-    if (!browserState.has(id)) browserState.set(id, __KUDZU_COMPLEX_LIST_ROW_STATE__ && state.initialValue !== null && typeof state.initialValue === "object" ? structuredClone(state.initialValue) : state.initialValue)
+    if (!browserState.has(id)) browserState.set(id, state.initializer === "list-item" ? structuredClone(item) : __KUDZU_COMPLEX_LIST_ROW_STATE__ && state.initialValue !== null && typeof state.initialValue === "object" ? structuredClone(state.initialValue) : state.initialValue)
     replacements.set(state.id, id)
   }
   if (__KUDZU_LIST_ROW_REFS__) for (const ref of descriptor.rowRefs ?? []) replacements.set(ref, rowStateId(ref, statePath))

package/package.json

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