@kudzujs/core 0.8.46 → 0.8.48

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.46` 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.48` 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.
 
@@ -144,6 +144,8 @@ This queue orders the next investigations by general migration value. Start only
 - A React Notes migration preserves its Provider, relative `useNotes()` alias, consumer components, and parameterized CRUD actions. A direct custom-hook `useContext(Context)` return resolves one local or named relative Context module whose Provider value exposes direct state/setter pairs and synchronous actions.
 - 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; direct object/array props, aliases, and composed initializer expressions 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.
 
 ### Completed In 0.8.10
 

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.46 Release Snapshot
+## Current 0.8.48 Release Snapshot
+
+Kudzu 0.8.48 broadens compiler-only setter-callback validation to multiple direct intrinsic handlers while retaining the existing command descriptors and browser runtimes. No new performance claim is made.
+
+## Maintained 0.8.47 Release Snapshot
+
+Kudzu 0.8.47 changes compiler-only specialized child initialization and retains existing parent/child state ownership, handler capabilities, and browser runtimes. No new performance claim is made.
+
+## Maintained 0.8.46 Release Snapshot
 
 Kudzu 0.8.46 changes compiler-only Context Provider scratch and retains the same concrete Notes state operations, RouteIR signals, runtime modules, and static sibling output. No new performance claim is made.
 

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.46 - Private Context action setters.** Context actions may use Provider setters without exposing those implementation details in the authored Provider value or public Context type. Kudzu restores required setters only in compiler scratch and still emits concrete state operations without a Context runtime. Read the [release notes](./RELEASES.md#0846---private-context-action-setters), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.46), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.48 - Multi-handler setter callbacks.** One specialized setter-callback prop may be called once from each of multiple direct intrinsic event handlers. Kudzu lowers every call to the same parent signal without shipping callbacks or a component runtime. Read the [release notes](./RELEASES.md#0848---multi-handler-setter-callbacks), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.48), 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,63 @@
 # Kudzu Releases
 
+## 0.8.48 - Multi-handler setter callbacks
+
+Kudzu 0.8.48 lets one compiler-specialized setter-callback prop be called once from each of multiple direct intrinsic event handlers.
+
+### Changed in 0.8.48
+
+- A specialized leaf may call the same setter callback from multiple intrinsic `on*` attributes.
+- Each handler call lowers independently to the same parent state signal.
+- Direct callback forwarding through the existing three-boundary limit remains supported.
+- Repeated calls inside one handler, aliases, non-handler uses, forwarding fan-out, and a fourth callback boundary remain source-diagnosed.
+
+### Output and performance
+
+- Command-only handlers continue to emit plain state-operation descriptors.
+- No callback registry, component runtime, browser runtime module, or public Kudzu API is added.
+- This release makes no new performance claim.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 213 tests and 163 generated pages.
+- A positive fixture emits two independent click descriptors targeting the same parent signal.
+- A focused negative fixture retains a source diagnostic for calling the callback twice inside one event handler.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.48
+```
+
+## 0.8.47 - Direct primitive prop state
+
+Kudzu 0.8.47 lets a compiler-specialized setter-callback child initialize local state directly from one primitive parent state prop without a migration-only wrapper expression.
+
+### Changed in 0.8.47
+
+- `useState(value)` is accepted when `value` is a direct specialized prop linked to parent state with a proven primitive literal initializer.
+- Build scratch reads the parent signal's initial primitive value while preserving the structural prop signal for handlers and effects.
+- Existing direct `value.toString()` initialization remains supported for string input buffers.
+- Composed expressions, aliases, and object/array state props remain source-diagnosed.
+
+### Output and performance
+
+- Parent and child retain independent state IDs and JSON-safe initial values.
+- Handler specialization continues to target the same parent and child signals without a component runtime.
+- No browser runtime module, public Kudzu API, or new performance claim is added.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 212 tests and 162 generated pages.
+- A direct string-state prop emits complete initial input HTML and two matching RouteIR state seeds.
+- Focused negative fixtures retain diagnostics for composed initializer expressions and object-state props.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.47
+```
+
 ## 0.8.46 - Private Context action setters
 
 Kudzu 0.8.46 lets relative Context-hook actions use Provider-owned setters without forcing those implementation-only setters into the authored Provider value or public Context type.

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.46` 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, collision-free and private Context action setters, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete; broader prop, callback, ref, and Context dataflow remains migration-backed work. 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.48` 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 prop state initialization, repeated direct leaf-handler callback use, collision-free and private Context action setters, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete; broader prop, callback, ref, and Context dataflow remains migration-backed work. 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.46` 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.48` 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`:** forwarding preserves parent SignalIR, Context action lowering uses compiler-owned aliases when consumer locals reuse Provider state/setter names, and action-required setters may remain compiler-only when their state is publicly exposed. A fourth callback boundary and fully hidden Context state 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`:** 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 primitive parent signal, and one leaf callback may lower independently in multiple intrinsic handlers. A fourth callback boundary, callback fan-out/aliases, fully hidden Context state, and object/array prop initializers 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.
 4. Browser-only package imports in owned effect/resource modules.
 5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics.
@@ -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, and the `0.8.42` measured route-output optimization are complete. Continue broader **component/prop/callback/ref/context dataflow** only from the next real migration blocker. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.
+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 prop initializer slice, the `0.8.48` repeated direct leaf-handler callback slice, and the `0.8.42` measured route-output optimization are complete. Continue broader **component/prop/callback/ref/context dataflow** only from the next real migration blocker. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.

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.46` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.48` 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.
 
@@ -37,6 +37,8 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.44` | Remove consumer-local name collisions from specialized Context actions. | Action-private Provider state/setter fields receive deterministic collision-free aliases; CRUD browser behavior, direct state operations, diagnostics, and zero Context runtime output pass. |
 | `0.8.45` | Add a source-scale benchmark and skip Kudzu semantic transformation for proven plain TypeScript modules. | Seven alternating samples improve compile and clean-build medians with identical deploy output; uncertain modules retain the existing transformer. |
 | `0.8.46` | Remove action-only setter fields from authored Context Provider APIs. | Compiler scratch restores required setters while Notes CRUD, RouteIR signals, concrete state operations, diagnostics, and zero Context runtime output pass. |
+| `0.8.47` | Initialize specialized child state from one direct primitive parent state prop. | Build-known primitive seeds, independent state ownership, existing handler specialization, and negative object/expression diagnostics pass without a runtime change. |
+| `0.8.48` | Allow one setter-callback prop in multiple direct intrinsic handlers. | Each handler lowers once to the same parent signal; repeated same-handler calls and escaped uses fail without a runtime change. |
 
 ## Sequence Rules
 

package/framework/compiler/source-compiler.mjs

@@ -1087,7 +1087,23 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           ts.forEachChild(node, collectReferences)
         }
         collectReferences(component.body)
-        if (references.length !== 1) fail(element, `Setter-callback prop ${JSON.stringify(prop)} must be used exactly once in the component`)
+        if (!references.length) fail(element, `Setter-callback prop ${JSON.stringify(prop)} must be called by at least one intrinsic event handler`)
+        if (references.length === 1 && ts.isJsxExpression(references[0].parent) && ts.isJsxAttribute(references[0].parent.parent) && /^on[A-Z]/.test(references[0].parent.parent.name.text)) continue
+        const handlers = new Set()
+        for (const reference of references) {
+          if (!ts.isCallExpression(reference.parent) || reference.parent.expression !== reference) fail(reference, `Setter-callback prop ${JSON.stringify(prop)} must be called directly inside an intrinsic event handler`)
+          let attribute
+          for (let current = reference.parent; current && current !== component.body; current = current.parent) {
+            if (ts.isJsxAttribute(current) && /^on[A-Z]/.test(current.name.text)) {
+              attribute = current
+              break
+            }
+          }
+          const tag = attribute?.parent?.parent && (ts.isJsxOpeningElement(attribute.parent.parent) || ts.isJsxSelfClosingElement(attribute.parent.parent)) ? attribute.parent.parent.tagName : undefined
+          if (!attribute || !ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(reference, `Setter-callback prop ${JSON.stringify(prop)} must be called directly inside an intrinsic event handler`)
+          if (handlers.has(attribute)) fail(reference, `Setter-callback prop ${JSON.stringify(prop)} may only be called once per event handler`)
+          handlers.add(attribute)
+        }
       }
     }
     const expandSetterComponents = (root, componentSource, trail, aggregate, parentSetters, parentStateOwners, callbackDepth = 2) => {
@@ -2440,10 +2456,12 @@ 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.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 = 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 substitutedProp = propReceiver ? substitutions.get(propReceiver.text) : undefined
-        const propStringInitializer = substitutedProp && ts.isIdentifier(unwrapExpression(substitutedProp)) && ordinaryStateNames.has(unwrapExpression(substitutedProp).text)
-        if (declaration.initializer.arguments.length !== 1 || !isSerializableStateLiteral(initialArgument) && !propStringInitializer) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useState() must use one directly serializable primitive, plain object, or array initial value${ordinaryHooks ? " or direct primitive state prop.toString()" : ""}; other dynamic initializers are not supported`)
+        const substitutedState = substitutedProp && ts.isIdentifier(unwrapExpression(substitutedProp)) ? unwrapExpression(substitutedProp).text : undefined
+        const directProp = ts.isIdentifier(initialArgument)
+        const propInitializer = substitutedState && ordinaryStateNames.has(substitutedState) && (!directProp || hasPrimitiveStateInitializer(call, substitutedState))
+        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 primitive state prop, optionally followed by .toString()" : ""}; 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}`
@@ -2454,7 +2472,11 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
           factory.createBindingElement(undefined, undefined, factory.createIdentifier(state)),
           factory.createBindingElement(undefined, undefined, factory.createIdentifier(setter))
         ])
-        const initialValue = propStringInitializer ? substituteClone(initialArgument, substitutions, factory, context) : cloneAst(initialArgument, factory, context)
+        const initialValue = 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])
         hookDeclarations.push(factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(binding, undefined, undefined, initializer)], ts.NodeFlags.Const)))
@@ -2537,6 +2559,20 @@ function isSerializableStateLiteral(node) {
   return value.properties.every(property => ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && property.name.text !== "__proto__" && isSerializableStateLiteral(property.initializer))
 }
 
+function hasPrimitiveStateInitializer(call, name) {
+  const owner = nearestFunction(call)
+  if (!owner || !ts.isBlock(owner.body)) return false
+  for (const statement of owner.body.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isArrayBindingPattern(declaration.name) || !declaration.initializer || !ts.isCallExpression(declaration.initializer) || !ts.isIdentifier(declaration.initializer.expression) || declaration.initializer.expression.text !== "useState") continue
+      const state = declaration.name.elements[0]
+      if (state && ts.isBindingElement(state) && ts.isIdentifier(state.name) && state.name.text === name) return declaration.initializer.arguments.length === 1 && isPrimitiveDefaultLiteral(unwrapExpression(declaration.initializer.arguments[0]))
+    }
+  }
+  return false
+}
+
 function synthesizeSerializableStateLiteral(node, factory) {
   node = unwrapExpression(node)
   if (ts.isStringLiteral(node)) return factory.createStringLiteral(node.text)

package/package.json

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