@kudzujs/core 0.7.26 → 0.7.29

package/README.md

@@ -10,7 +10,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.7.26 - React-shaped migration and faster lists.** React-compatible JSX typing, setter-adapter specialization, imported collection normalization, and indexed keyed-row release make ordinary migrations easier while moving the measured 500-card search ahead of React. Read the [release notes](./RELEASES.md#0726---react-shaped-migration-and-faster-lists) or open the [release page](https://kudzujs.cloud/releases/0.7.26).
+**Latest release: 0.7.29 - Hermetic TypeScript checks.** Project and fixture typechecks no longer inherit unrelated ambient types or third-party declarations from ancestor `node_modules` directories. Read the [release notes](./RELEASES.md#0729---hermetic-typescript-checks) or open the [release page](https://kudzujs.cloud/releases/0.7.29).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,77 @@
 # Kudzu Releases
 
+## 0.7.29 - Hermetic TypeScript checks
+
+Kudzu 0.7.29 makes project and migration-fixture typechecks independent of unrelated ambient types and package declarations installed in ancestor directories.
+
+### New in 0.7.29
+
+- The root TypeScript configuration declares an empty ambient `types` set instead of scanning every visible ancestor `node_modules/@types` directory.
+- `create-kudzu` emits the same isolated TypeScript configuration for new projects.
+- Migration fixture checks skip third-party declaration bodies while continuing to typecheck fixture TS and TSX against Kudzu's reduced declarations.
+- A clean `npm ci` checkout nested below conflicting `@types/minimatch`, React, and React Router installations now passes `npm run check`.
+- The complete suite continues to pass 122/122 tests.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.29
+```
+
+## 0.7.28 - Nested component specialization
+
+Kudzu 0.7.28 recursively specializes components rendered inside setter-adapter children, allowing conventional optional UI such as an imported hookful Tooltip to remain declarative without adding a browser component runtime.
+
+### New in 0.7.28
+
+- Setter-adapter children may recursively render synchronous same-file or relative-imported components.
+- Nested component props, defaults, JSX children, static assets, handlers, and relative TypeScript imports reuse the existing call-site specialization path.
+- Nested `useState()`, `useId()`, `useRef()`, and supported effects join the outer generated owner on unconditional or statically truthy paths.
+- Literal `&&` and ternary conditions fold before specialization, so omitted and false optional components allocate no hooks or browser capabilities.
+- Recursive component cycles, namespace/package components, and unresolved component imports retain source diagnostics.
+- Hookful nested components on dynamic paths fail instead of receiving incorrect unconditional ownership.
+- Setter callbacks cannot cross a second component boundary.
+- A migration-derived FIRE `AgeInput` now restores its imported hookful `Tooltip`, including generated ARIA identity and hover/focus state.
+- The complete suite passes 122/122 tests with Chrome coverage for nested tooltip state, omitted optional UI, and existing parent/child lifecycle behavior.
+
+### Boundary
+
+Nested hooks are accepted only when the nested component is unconditional or guarded by a statically truthy literal after outer prop substitution. Dynamic conditional hook ownership and forwarding the setter through another component remain unsupported. Components still erase to intrinsic HTML and route-specific capabilities; React is never emitted or executed.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.28
+```
+
+## 0.7.27 - Stateful component migration
+
+Kudzu 0.7.27 lets ordinary setter-adapter components keep their local hooks and derived render values while compiling them into static HTML plus existing route-specific capabilities, not a browser component runtime.
+
+### New in 0.7.27
+
+- Same-file and relative-imported children receiving one supported setter callback may own multiple directly serializable `useState()` values.
+- A child string draft may initialize from one direct primitive state prop through zero-argument `.toString()`, covering conventional controlled age and numeric inputs.
+- Setter-adapter children may use deterministic build-time `useId()` values and `null`-initialized object refs.
+- Supported child effects reuse existing route ESM, dependency comparison, cleanup, conditional ownership, and stale-work isolation.
+- Conditional removal deletes child state, resolves refs to `null`, and runs cleanup; remount creates fresh ownership and prop dependency effects synchronize drafts to the latest parent value.
+- Inline and simple `const` parent callbacks continue to specialize into the generated child helper instead of becoming serialized function captures.
+- Reactive JSX text and attributes may read recursively chained top-level immutable locals built from supported pure primitive state expressions.
+- Impure derived render calls, non-null child refs, unsupported dynamic state initializers, repeated callback use, and wider callback forwarding retain source-located diagnostics.
+- React Router normalization now safely ignores local export declarations without module specifiers.
+- A migration-derived FIRE age input verifies local draft editing, parent updates, blur validation, effect synchronization, and remount after a hidden parent update.
+- The complete suite passes 121/121 tests, including same-file/imported hook ownership and Chrome lifecycle coverage.
+
+### Boundary
+
+This remains one compiler-specialized component boundary with one supported setter callback use. Prop-derived state initialization accepts only a direct primitive state prop's zero-argument `.toString()`; other dynamic initializers remain unsupported. Refs must initialize with `null`, effects must use the existing supported callback and dependency forms, and React is never emitted or executed.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.27
+```
+
 ## 0.7.26 - React-shaped migration and faster lists
 
 Kudzu 0.7.26 broadens ordinary React-shaped migration input and removes repeated keyed-row cleanup scans, making the matched 500-card search faster than React without adding a VDOM, hydration, or a retained component tree.

package/framework/README.md

@@ -14,7 +14,7 @@ A named or aliased React Router `useNavigate` import may initialize one top-leve
 
 Direct `clsx` calls over literal strings, numbers, arrays, object conditions, and conditional expressions are similarly lowered to ordinary concatenation and conditional expressions. The package import is erased, and dynamic classes continue through the existing binding compiler without serializing or shipping the `clsx` function.
 
-Repeated ordinary same-file and relative-imported child components execute independently at build time, so each `useState` call receives a distinct concrete state ID while shared native handler modules retain per-element state maps and captures. A direct JSON-safe primitive parent state passed to a destructured child prop remains the same signal for child DOM bindings and effect dependencies; repeated calls own independent effect records, and conditional removal cleans up before remount recreates the effect. Multiple direct primitive dependencies share the existing commit batching path: every value is compared with `Object.is`, and one or more same-turn changes cause one cleanup and rerun. A top-level immutable local derived through a supported pure primitive expression from direct state may also be an effect dependency: source state commits schedule evaluation, the derived result is compared with `Object.is`, and the expression is substituted into setup and cleanup handlers. Effect setup and directly returned cleanup callbacks may each resolve one top-level simple `const` function in the same component; those functions are substituted into the existing handler graph rather than retained in a browser registry. Reactive conditional descriptors own state created by their direct branch: initial visible output reuses the rendered template IDs, removal deletes those slots, and remount recreates them from serialized initial values. Static sibling routes and branches without local state add no ownership metadata, component function, hook dispatcher, or rerender loop.
+Repeated ordinary same-file and relative-imported child components execute independently at build time, so each `useState` call receives a distinct concrete state ID while shared native handler modules retain per-element state maps and captures. A direct JSON-safe primitive parent state passed to a destructured child prop remains the same signal for child DOM bindings and effect dependencies; repeated calls own independent effect records, and conditional removal cleans up before remount recreates the effect. Reactive text and attributes may reference recursively chained top-level immutable locals derived through supported pure primitive expressions from direct state; the compiler substitutes those expressions into the existing binding evaluator and subscribes every source state. Multiple direct primitive dependencies share the existing commit batching path: every value is compared with `Object.is`, and one or more same-turn changes cause one cleanup and rerun. A top-level immutable local derived through a supported pure primitive expression from direct state may also be an effect dependency: source state commits schedule evaluation, the derived result is compared with `Object.is`, and the expression is substituted into setup and cleanup handlers. Effect setup and directly returned cleanup callbacks may each resolve one top-level simple `const` function in the same component; those functions are substituted into the existing handler graph rather than retained in a browser registry. Reactive conditional descriptors own state created by their direct branch: initial visible output reuses the rendered template IDs, removal deletes those slots, and remount recreates them from serialized initial values. Static sibling routes and branches without local state add no ownership metadata, component function, hook dispatcher, or rerender loop.
 
 Reduced Zustand migration stores lower to one ordinary layout-lifetime state slot. The compiler accepts one exported `create(set => ({ data, ...actions }))` store with one serializable data property, direct property selectors, and synchronous capture-free actions using one-argument merge-form `set`; selected actions reuse the reducer-style functional update compiler, so same-turn calls observe current logical state and DOM writes still batch. The shared layout must initialize the store before route consumers, outside keyed rows. No Zustand import, store subscription runtime, React hook, or generic external-store capability is emitted.
 
@@ -47,7 +47,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 may cross one same-file or relative-imported component boundary when the child invokes it exactly once inside an intrinsic event handler. Inline and simple `const` setter callbacks may use that adapter shape or direct event forwarding. Value adapters such as `event => onValueChange(event.currentTarget.value)` specialize into the parent setter graph instead of serializing a function. A `null`-initialized object ref may cross the same boundary to the direct intrinsic root. Both remain compiler-owned descriptors: conditional removal drops the handler with the element and makes the ref resolve to `null`, while remount creates a fresh element without retaining a component instance.
+A direct setter may cross one same-file or relative-imported component boundary when the child invokes it exactly once inside an intrinsic event handler. Inline and simple `const` setter callbacks may use that adapter shape or direct event forwarding. Value adapters such as `event => onValueChange(event.currentTarget.value)` specialize into the parent setter graph instead of serializing a function. The child may also own directly serializable `useState()` values or initialize string state with one direct primitive state prop's zero-argument `.toString()`, plus `useId()` values, supported effects, and object refs initialized with `null`. Same-file and relative-imported nested components recursively specialize away; nested hooks join the same generated owner only on unconditional or statically truthy paths. Dynamic nested hook paths, forwarding the setter through a second boundary, and other dynamic state initializers remain unsupported. A parent-owned `null`-initialized object ref may cross the same boundary 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/build.mjs

@@ -1790,7 +1790,7 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
   const searchHooks = new Set()
   const navigateHooks = new Set()
   for (const statement of sourceFile.statements) {
-    if ((ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement)) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react-router-dom") {
+    if ((ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react-router-dom") {
       if (ts.isExportDeclaration(statement)) throw sourceNodeError(statement, sourceFile, "React Router exports are not supported; import Link directly where it renders")
       const clause = statement.importClause
       if (clause?.isTypeOnly) continue
@@ -2584,6 +2584,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     const listConditions = new WeakMap()
     const nestedLists = new WeakMap()
     const listEffectEntries = new WeakMap()
+    const componentEffectEntries = new WeakMap()
     let usesBehavior = false
     let usesBinding = false
     let usesConditional = false
@@ -2592,6 +2593,10 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     let usesListItem = false
     let usesRowState = false
     let usesRowRef = false
+    let usesComponentState = false
+    let usesComponentId = false
+    let usesComponentRef = false
+    let usesComponentEffects = false
 
     const collect = node => {
       if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)) {
@@ -2717,7 +2722,47 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     const fail = (node, message) => {
       throw sourceNodeError(node, sourceFile, message)
     }
+    const resolveReactiveJsxExpression = (expression, owner, setters) => {
+      const declarations = jsxLocalDeclarations.get(owner)
+      if (!declarations) return expression
+      const substitutions = new Map()
+      const resolving = []
+      const resolve = (name, reference) => {
+        if (substitutions.has(name)) return
+        const entries = declarations.get(name)
+        if (!entries?.length) return
+        if (jsxLocalsByFunction.get(owner)?.has(name)) return
+        if (entries.length !== 1 || entries[0].node.parent?.parent?.parent !== owner?.body) return
+        const cycle = resolving.indexOf(name)
+        if (cycle >= 0) fail(reference, `Reactive JSX local cycle: ${[...resolving.slice(cycle), name].join(" -> ")}`)
+        resolving.push(name)
+        const initializer = entries[0].initializer
+        const visit = node => {
+          if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isShadowedByParameter(node, initializer) && declarations.has(node.text)) resolve(node.text, node)
+          ts.forEachChild(node, visit)
+        }
+        visit(initializer)
+        substitutions.set(name, substituteClone(initializer, substitutions, factory, context))
+        resolving.pop()
+      }
+      const visit = node => {
+        if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression) && declarations.has(node.text)) resolve(node.text, node)
+        ts.forEachChild(node, visit)
+      }
+      visit(expression)
+      if (!substitutions.size) return expression
+      const expanded = substituteClone(expression, substitutions, factory, context)
+      ts.setParentRecursive(expanded, false)
+      expanded.parent = expression.parent
+      const usedStates = referencedStateNames(expanded, setters)
+      if (!usedStates.size) return expression
+      const captures = captureNames(expanded, expanded, setters)
+      const allowedNames = new Set([...setters.values(), ...captures])
+      collectionExpression(expanded, {}, (node, message) => fail(node, message.replace("Rendered collection", "Reactive JSX local")), allowedNames)
+      return expanded
+    }
     const componentSpecializations = new WeakMap()
+    const setterHookHelpers = new WeakMap()
     const expandedRowSpecializations = new WeakMap()
     const nestedRowSpecializations = new Map()
     const reducerComponentCalls = new WeakSet()
@@ -2806,6 +2851,89 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       expanded.parent = root.parent
       return expanded
     }
+    const staticConditionValue = expression => {
+      const value = unwrapExpression(expression)
+      if (value.kind === ts.SyntaxKind.TrueKeyword) return true
+      if (value.kind === ts.SyntaxKind.FalseKeyword || value.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(value) && value.text === "undefined") return false
+      if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) return Boolean(value.text)
+      if (ts.isNumericLiteral(value)) return Number(value.text) !== 0
+      return undefined
+    }
+    const foldSetterStaticConditions = root => {
+      const visit = node => {
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+          const condition = staticConditionValue(node.left)
+          if (condition !== undefined) return condition ? ts.visitNode(node.right, visit) : node.left
+        }
+        if (ts.isConditionalExpression(node)) {
+          const condition = staticConditionValue(node.condition)
+          if (condition !== undefined) return ts.visitNode(condition ? node.whenTrue : node.whenFalse, visit)
+        }
+        return ts.visitEachChild(node, visit, context)
+      }
+      const folded = ts.visitNode(root, visit)
+      ts.setParentRecursive(folded, false)
+      folded.parent = root.parent
+      return folded
+    }
+    const expandSetterComponents = (root, componentSource, trail, aggregate, parentSetters) => {
+      root = foldSetterStaticConditions(root)
+      const replacements = new WeakMap()
+      let count = 0
+      const visit = (node, dynamic = false) => {
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+          visit(node.left, dynamic)
+          visit(node.right, true)
+          return
+        }
+        if (ts.isConditionalExpression(node)) {
+          visit(node.condition, dynamic)
+          visit(node.whenTrue, true)
+          visit(node.whenFalse, true)
+          return
+        }
+        const tag = jsxTagName(node)
+        if (tag && (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase())) {
+          if (!ts.isIdentifier(tag)) fail(node, "Nested setter-callback components must use identifier JSX tags")
+          const name = tag.text
+          let component = localComponentDeclaration(componentSource, name)
+          let imported = false
+          if (!component) {
+            const binding = clientImportBindings(componentSource, componentSource.fileName, sourceFiles).get(name)
+            if (!binding || binding.kind === "namespace") fail(node, `Nested setter-callback component ${name} must be declared locally or imported from a relative TypeScript module`)
+            component = resolveComponentExport(binding.target, binding.kind === "default" ? "default" : binding.imported, importedSource, sourceFiles)
+            imported = true
+          }
+          if (trail.includes(component)) {
+            const chain = [...trail, component].map(entry => entry.name?.text || "anonymous").join(" -> ")
+            fail(node, `Nested setter-callback component cycle: ${chain}`)
+          }
+          const setters = new Map(parentSetters)
+          for (const state of aggregate.ordinaryStates) setters.set(state.setter, state.state)
+          if (jsxSetterCallbackProps(node, setters, functions, reducersForNode(node, reducersByFunction)).length) fail(node, "Setter callbacks cannot cross a second component boundary")
+          const nested = specializeComponentCall(node, component, sourceFile, factory, context, fail, "Nested setter-callback", true, true, new Set(setters.values()))
+          if (dynamic && (nested.hookDeclarations.length || nested.effects.length)) fail(node, "Hookful nested setter-callback components require an unconditional or statically truthy render path")
+          nested.root = expandSetterComponents(nested.root, component.getSourceFile(), [...trail, component], nested, setters)
+          if (imported) synthesizeTree(nested.root = mergeSpecializedImports(nested.root, component.getSourceFile(), node, nested.effects))
+          aggregate.calculations.push(...nested.calculations)
+          aggregate.effects.push(...nested.effects)
+          aggregate.hookDeclarations.push(...nested.hookDeclarations)
+          aggregate.ordinaryStates.push(...nested.ordinaryStates)
+          aggregate.ordinaryRefs.push(...nested.ordinaryRefs)
+          aggregate.usesComponentId ||= nested.usesComponentId
+          replacements.set(node, nested.root)
+          count++
+          return
+        }
+        ts.forEachChild(node, child => visit(child, dynamic))
+      }
+      visit(root)
+      if (!count) return root
+      const expanded = replaceSpecializedCalls(root, replacements, context)
+      ts.setParentRecursive(expanded, false)
+      expanded.parent = root.parent
+      return expanded
+    }
     for (const [name, component] of components) {
       const calls = jsxTagUses(sourceFile, name)
       const stateBackedCalls = calls.filter(call => isStateBackedListComponentCall(call, component.function, settersByFunction.get(nearestFunction(call)) ?? new Map()))
@@ -2856,9 +2984,57 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         collectReferences(component.body)
         if (references.length !== 1) fail(element, `Setter-callback prop ${JSON.stringify(prop)} must be used exactly once in the component`)
       }
-      const specialization = specializeComponentCall(call, component, sourceFile, factory, context, fail, "Setter-callback")
-      if (specialization.effects.length || specialization.hookDeclarations.length) fail(call, "Setter-callback components cannot declare hooks")
+      const specialization = specializeComponentCall(call, component, sourceFile, factory, context, fail, "Setter-callback", false, true, new Set(settersForNode(call, settersByFunction).values()))
+      if (specialization.hookDeclarations.length || specialization.effects.length) {
+        const substitutions = new Map()
+        const attributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
+        for (const attribute of attributes.properties) {
+          if (!ts.isJsxAttribute(attribute) || !callbackProps.includes(attribute.name.text) || !attribute.initializer || !ts.isJsxExpression(attribute.initializer) || !ts.isIdentifier(attribute.initializer.expression)) continue
+          const callback = functions.get(attribute.initializer.expression.text)
+          if (callback) substitutions.set(attribute.initializer.expression.text, callback)
+        }
+        if (substitutions.size) {
+          specialization.root = substituteClone(specialization.root, substitutions, factory, context)
+          for (const effect of specialization.effects) effect.call = substituteClone(effect.call, substitutions, factory, context)
+        }
+      }
+      specialization.root = expandSetterComponents(specialization.root, component.getSourceFile(), [component], specialization, settersForNode(call, settersByFunction))
       if (imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, component.getSourceFile(), call, specialization.effects))
+      if (specialization.hookDeclarations.length || specialization.effects.length) {
+        const owner = nearestFunction(call)
+        const name = `KSetterComponent${Math.max(0, call.pos)}`
+        const effectStatements = specialization.effects.map(entry => {
+          const effectCall = factory.updateCallExpression(entry.call, factory.createIdentifier("__kComponentUseEffect"), entry.call.typeArguments, entry.call.arguments)
+          synthesizeTree(effectCall)
+          const effectSource = entry.source.getSourceFile()
+          componentEffectEntries.set(effectCall, { source: entry.source, sourceFile: effectSource, imports: clientImportBindings(effectSource, effectSource.fileName, sourceFiles) })
+          return factory.createExpressionStatement(effectCall)
+        })
+        const helper = factory.createFunctionDeclaration(
+          undefined,
+          undefined,
+          name,
+          undefined,
+          [],
+          undefined,
+          factory.createBlock([...specialization.hookDeclarations, ...effectStatements, factory.createReturnStatement(specialization.root)], true)
+        )
+        ts.setParentRecursive(helper, false)
+        helper.parent = owner.body
+        const helpers = setterHookHelpers.get(owner.body) ?? []
+        helpers.push(helper)
+        setterHookHelpers.set(owner.body, helpers)
+        const setters = new Map(settersForNode(call, settersByFunction))
+        for (const state of specialization.ordinaryStates) setters.set(state.setter, state.state)
+        settersByFunction.set(helper, setters)
+        usesComponentState ||= specialization.ordinaryStates.length > 0
+        usesComponentId ||= specialization.usesComponentId
+        usesComponentRef ||= specialization.ordinaryRefs.length > 0
+        usesComponentEffects ||= specialization.effects.length > 0
+        specialization.root = factory.createJsxSelfClosingElement(factory.createIdentifier(name), undefined, factory.createJsxAttributes([]))
+        ts.setParentRecursive(specialization.root, false)
+        specialization.root.parent = call.parent
+      }
       componentSpecializations.set(call, specialization)
     }
     for (const [name, component] of components) {
@@ -3114,6 +3290,9 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     }
 
     const visitor = node => {
+      if (ts.isBlock(node) && setterHookHelpers.has(node)) {
+        return ts.visitEachChild(factory.updateBlock(node, [...setterHookHelpers.get(node), ...node.statements]), visitor, context)
+      }
       if (specializedDeclarations.has(node)) return node
       if (componentSpecializations.has(node)) return ts.visitNode(componentSpecializations.get(node).root, visitor)
 
@@ -3139,9 +3318,11 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       }
 
       const listEffect = ts.isCallExpression(node) ? listEffectEntries.get(node) : undefined
-      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (hasUseEffectImport && node.expression.text === "useEffect" || listEffect)) {
+      const componentEffect = ts.isCallExpression(node) ? componentEffectEntries.get(node) : undefined
+      const specializedEffect = listEffect ?? componentEffect
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (hasUseEffectImport && node.expression.text === "useEffect" || specializedEffect)) {
         const effectFail = (target, message) => {
-          if (listEffect) throw sourceNodeError(listEffect.source, listEffect.sourceFile, message)
+          if (specializedEffect) throw sourceNodeError(specializedEffect.source, specializedEffect.sourceFile, message)
           fail(target, message)
         }
         if (node.arguments.length !== 2) effectFail(node, "useEffect() requires exactly a callback and literal dependency array")
@@ -3234,7 +3415,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         const invalidCleanup = returns.cleanups.find(cleanup => cleanup.parameters.length || cleanup.asteriskToken)
         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 callbackSource = listEffect?.sourceFile ?? sourceFile
+        const callbackSource = specializedEffect?.sourceFile ?? sourceFile
         const callbackFile = callbackSource.fileName
         const workerStart = workerReferences.length
         let compiledCallback = dependencySubstitutions.size ? substituteClone(callback, dependencySubstitutions, factory, context) : callback
@@ -3248,7 +3429,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         } else {
           compiledCallback = rewriteEffectWorkers(compiledCallback, callbackFile, callbackSource, sourceFiles, workerReferences, factory, context)
         }
-        const descriptor = compileNativeCallback(compiledCallback, setters, reducersForNode(node, reducersByFunction), factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
+        const descriptor = compileNativeCallback(compiledCallback, setters, reducersForNode(node, reducersByFunction), factory, effectHandlers, specializedEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
         for (const reference of workerReferences.slice(workerStart)) Object.assign(reference, { module: handlerUrl, handler: descriptor.exportName })
         usesListItem ||= Boolean(itemDependencies.length && !listEffect)
         usesBehavior = true
@@ -3259,7 +3440,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           factory.createStringLiteral(descriptor.exportName),
           descriptor.states,
           descriptor.scope,
-          factory.createStringLiteral(listEffect ? sourceLocation(listEffect.source, listEffect.sourceFile) : sourceLocation(node, sourceFile)),
+          factory.createStringLiteral(specializedEffect ? sourceLocation(specializedEffect.source, specializedEffect.sourceFile) : sourceLocation(node, sourceFile)),
           returns.cleanup ? factory.createTrue() : factory.createFalse(),
           factory.createArrayLiteralExpression(itemDependencies.map(field => factory.createStringLiteral(field))),
           hasDerivedDependency ? jsonExpression(dependencyExpressions, factory) : factory.createArrayLiteralExpression(),
@@ -3267,7 +3448,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         ])
       }
 
-      if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression) && ((node.initializer.expression.text === "useState" || node.initializer.expression.text === "__kRowUseState") && node.initializer.arguments.length === 1 || node.initializer.expression.text === "useReducer" && node.initializer.arguments.length === 2)) {
+      if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression) && ((node.initializer.expression.text === "useState" || node.initializer.expression.text === "__kRowUseState" || node.initializer.expression.text === "__kComponentUseState") && node.initializer.arguments.length === 1 || node.initializer.expression.text === "useReducer" && node.initializer.arguments.length === 2)) {
         const stateElement = node.name.elements[0]
         if (!stateElement || !ts.isBindingElement(stateElement) || !ts.isIdentifier(stateElement.name)) return node
         const initializer = factory.updateCallExpression(node.initializer, node.initializer.expression, node.initializer.typeArguments, [
@@ -3331,18 +3512,20 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           if (compiled !== node.expression) return factory.updateJsxExpression(node, compiled)
         }
         const setters = settersForNode(node, settersByFunction)
-        const usedStates = referencedStateNames(node.expression, setters)
-        const captures = captureNames(node.expression, node.expression, setters)
-        if ((usedStates.size || captures.size) && !ts.isIdentifier(node.expression) && !containsJsx(node.expression)) {
+        const expression = resolveReactiveJsxExpression(node.expression, nearestFunction(node), setters)
+        const usedStates = referencedStateNames(expression, setters)
+        const captures = captureNames(expression, expression, setters)
+        if ((usedStates.size || captures.size) && !ts.isIdentifier(expression) && !containsJsx(expression)) {
           usesBehavior = true
           usesBinding = true
-          return factory.updateJsxExpression(node, compileReactiveBinding(node.expression, setters, factory, context, reactiveBindings, handlerUrl))
+          return factory.updateJsxExpression(node, compileReactiveBinding(expression, setters, factory, context, reactiveBindings, handlerUrl))
         }
       }
 
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && !isContextProviderValue(node, contexts) && !/^on/i.test(node.name.text) && !["key", "ref", "dangerouslysetinnerhtml"].includes(node.name.text.toLowerCase())) {
-        const expression = node.initializer.expression
+        const sourceExpression = node.initializer.expression
         const setters = settersForNode(node, settersByFunction)
+        const expression = resolveReactiveJsxExpression(sourceExpression, nearestFunction(node), setters)
         const usedStates = referencedStateNames(expression, setters)
         const captures = captureNames(expression, expression, setters)
         if ((usedStates.size || captures.size) && !ts.isIdentifier(expression)) {
@@ -3393,6 +3576,10 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     if (usesListEffects) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useEffect"), factory.createIdentifier("__kListUseEffect")))
     if (usesRowState) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useState"), factory.createIdentifier("__kRowUseState")))
     if (usesRowRef) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useRef"), factory.createIdentifier("__kRowUseRef")))
+    if (usesComponentState) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useState"), factory.createIdentifier("__kComponentUseState")))
+    if (usesComponentId) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useId"), factory.createIdentifier("__kComponentUseId")))
+    if (usesComponentRef) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useRef"), factory.createIdentifier("__kComponentUseRef")))
+    if (usesComponentEffects) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useEffect"), factory.createIdentifier("__kComponentUseEffect")))
     if (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
       undefined,
@@ -4029,7 +4216,7 @@ function expandSpecializedRest(root, returned, component, rest, entries, factory
   return factory.updateJsxElement(root, opening, root.children, root.closingElement)
 }
 
-function specializeComponentCall(call, component, sourceFile, factory, context, fail, label = "Keyed list", allowComponentRoot = false) {
+function specializeComponentCall(call, component, sourceFile, factory, context, fail, label = "Keyed list", allowComponentRoot = false, ordinaryHooks = false, ordinaryStateNames = new Set()) {
   if (component.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || component.asteriskToken) fail(component, `${label} components must be synchronous`)
   if (component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name)) fail(component, `${label} components must use one destructured props parameter`)
   const callAttributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
@@ -4090,6 +4277,9 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   const hookDeclarations = []
   const rowStates = []
   const rowRefs = []
+  const ordinaryStates = []
+  const ordinaryRefs = []
+  let usesComponentId = false
   if (!ts.isBlock(component.body)) {
     returned = component.body
   } else {
@@ -4104,35 +4294,52 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
       if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0 || statement.declarationList.declarations.length !== 1) fail(statement, `${label} component locals must be single const declarations`)
       const declaration = statement.declarationList.declarations[0]
       if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useState") {
-        if (declaration.initializer.arguments.length !== 1 || !isSerializableStateLiteral(declaration.initializer.arguments[0])) throw sourceNodeError(declaration.initializer, component.getSourceFile(), "Keyed row useState() must use one directly serializable primitive, plain object, or array initial value; 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(), "Keyed row useState() must use [state, setter] identifier destructuring")
-        const suffix = `${Math.max(0, call.pos)}_${rowStates.length}`
-        const state = `__kRowState${suffix}`
-        const setter = `__kRowSetter${suffix}`
+        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 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`)
+        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}`
+        const setter = ordinaryHooks ? `__kComponentSetter${suffix}` : `__kRowSetter${suffix}`
         substitutions.set(declaration.name.elements[0].name.text, factory.createIdentifier(state))
         substitutions.set(declaration.name.elements[1].name.text, factory.createIdentifier(setter))
         const binding = factory.createArrayBindingPattern([
           factory.createBindingElement(undefined, undefined, factory.createIdentifier(state)),
           factory.createBindingElement(undefined, undefined, factory.createIdentifier(setter))
         ])
-        const initialValue = cloneAst(declaration.initializer.arguments[0], factory, context)
+        const initialValue = propStringInitializer ? substituteClone(initialArgument, substitutions, factory, context) : cloneAst(initialArgument, factory, context)
         synthesizeTree(initialValue)
-        const initializer = factory.createCallExpression(factory.createIdentifier("__kRowUseState"), undefined, [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)))
-        rowStates.push({ state, setter })
+        if (ordinaryHooks) ordinaryStates.push({ state, setter })
+        else rowStates.push({ state, setter })
         continue
       }
       if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useRef") {
-        if (declaration.initializer.arguments.length !== 1 || declaration.initializer.arguments[0].kind !== ts.SyntaxKind.NullKeyword) throw sourceNodeError(declaration.initializer, component.getSourceFile(), "Keyed row useRef() must use the direct initial value null")
-        if (!ts.isIdentifier(declaration.name)) throw sourceNodeError(declaration.name, component.getSourceFile(), "Keyed row useRef() must be assigned to one identifier")
-        const name = `__kRowRef${Math.max(0, call.pos)}_${rowRefs.length}`
+        const hookLabel = ordinaryHooks ? "Setter-callback component" : "Keyed row"
+        if (declaration.initializer.arguments.length !== 1 || declaration.initializer.arguments[0].kind !== ts.SyntaxKind.NullKeyword) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useRef() must use the direct initial value null`)
+        if (!ts.isIdentifier(declaration.name)) throw sourceNodeError(declaration.name, component.getSourceFile(), `${hookLabel} useRef() must be assigned to one identifier`)
+        const refs = ordinaryHooks ? ordinaryRefs : rowRefs
+        const name = `${ordinaryHooks ? "__kComponentRef" : "__kRowRef"}${Math.max(0, call.pos)}_${refs.length}`
+        substitutions.set(declaration.name.text, factory.createIdentifier(name))
+        const initializer = factory.createCallExpression(factory.createIdentifier(ordinaryHooks ? "__kComponentUseRef" : "__kRowUseRef"), declaration.initializer.typeArguments?.map(type => cloneAst(type, factory, context)), [factory.createNull()])
+        hookDeclarations.push(factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(factory.createIdentifier(name), undefined, undefined, initializer)], ts.NodeFlags.Const)))
+        refs.push({ name })
+        continue
+      }
+      if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useId") {
+        if (!ordinaryHooks) throw sourceNodeError(declaration.initializer, component.getSourceFile(), "useId() is not supported in keyed row components")
+        if (declaration.initializer.arguments.length || !ts.isIdentifier(declaration.name)) throw sourceNodeError(declaration.initializer, component.getSourceFile(), "Setter-callback component useId() must initialize one top-level const identifier without arguments")
+        const name = `__kComponentId${Math.max(0, call.pos)}_${hookDeclarations.length}`
         substitutions.set(declaration.name.text, factory.createIdentifier(name))
-        const initializer = factory.createCallExpression(factory.createIdentifier("__kRowUseRef"), declaration.initializer.typeArguments?.map(type => cloneAst(type, factory, context)), [factory.createNull()])
+        const initializer = factory.createCallExpression(factory.createIdentifier("__kComponentUseId"), undefined, [])
         hookDeclarations.push(factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(factory.createIdentifier(name), undefined, undefined, initializer)], ts.NodeFlags.Const)))
-        rowRefs.push({ name })
+        usesComponentId = true
         continue
       }
-      if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useId") throw sourceNodeError(declaration.initializer, component.getSourceFile(), "useId() is not supported in keyed row components")
       if (!ts.isIdentifier(declaration.name) || !declaration.initializer) fail(declaration, `${label} component locals must be initialized identifiers`)
       const calculation = substituteClone(declaration.initializer, substitutions, factory, context)
       calculations.push({ name: declaration.name.text, expression: calculation })
@@ -4143,12 +4350,12 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   let unsupportedHook
   const findUnsupportedHook = node => {
     if (unsupportedHook) return
-    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && ["useState", "useRef"].includes(node.expression.text)) unsupportedHook = node
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && ["useState", "useRef", "useId"].includes(node.expression.text)) unsupportedHook = node
     ts.forEachChild(node, findUnsupportedHook)
   }
   findUnsupportedHook(returned)
   for (const calculation of calculations) findUnsupportedHook(calculation.expression)
-  if (unsupportedHook) throw sourceNodeError(unsupportedHook, component.getSourceFile(), `Keyed row ${unsupportedHook.expression.text}() must be one top-level const declaration`)
+  if (unsupportedHook) throw sourceNodeError(unsupportedHook, component.getSourceFile(), `${ordinaryHooks ? "Setter-callback component" : "Keyed row"} ${unsupportedHook.expression.text}() must be one top-level const declaration`)
   let root = unwrapExpression(flattenForwardedComponentChildren(substituteClone(returned, substitutions, factory, context), factory, context))
   if (rest) root = expandSpecializedRest(root, returned, component, rest, restEntries, factory, context, fail, label)
   if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) fail(returned, `${label} component must return one JSX element`)
@@ -4168,7 +4375,10 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
     effects,
     hookDeclarations,
     rowStates,
-    rowRefs
+    rowRefs,
+    ordinaryStates,
+    ordinaryRefs,
+    usesComponentId
   }
 }
 

package/package.json

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