@kudzujs/core 0.8.60 → 0.8.61

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.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.
+The executable post-`0.8.61` 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.
 
@@ -96,6 +96,7 @@ This queue orders the next investigations by general migration value. Start only
 ### Completed In 0.8.0
 
 - Relative zero-argument custom hooks expose direct shorthand state/setter pairs and state-capturing callbacks to one top-level caller destructuring.
+- In `0.8.61`, a ClimateCompatibleGrowth-shaped relative `useDebounce(value, delay)` hook may accept one direct primitive state and numeric literal delay, initialize one returned state from the source build value, and own one exact timeout dependency effect with cleanup. Dynamic delays, non-primitive state, aliases, additional effects, intervals, and missing cleanup remain diagnosed.
 - Writable React Router search parameters use native inline `URLSearchParams` updaters, push/replace history, signal recommits, and `popstate` synchronization.
 - Guarded `localStorage` restoration and persistence compose through existing mount/dependency effects, preserving deterministic static fallbacks without a storage runtime.
 - Reachable source compilation excludes unused React/Vite modules while preserving source diagnostics for every reachable module.

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.60 - Array draft effect sync.** A specialized child can synchronize direct prop-derived array draft state through its matching parent setter in an ordinary dependency effect without a component runtime. Read the [release notes](./RELEASES.md#0860---array-draft-effect-sync), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.60), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.61 - Parameterized debounce hooks.** Relative `useDebounce(state, literalDelay)` hooks compile through existing state, effect, timeout cleanup, and ownership paths without a debounce runtime. Read the [release notes](./RELEASES.md#0861---parameterized-debounce-hooks), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.61), 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,34 @@
 # Kudzu Releases
 
+## 0.8.61 - Parameterized debounce hooks
+
+Kudzu 0.8.61 compiles the common relative `useDebounce(state, literalDelay)` custom-hook shape through existing state and effect ownership.
+
+### Changed in 0.8.61
+
+- A named or default relative synchronous hook may accept one direct primitive state value and one numeric literal delay.
+- The hook may initialize one state from that value, own one timeout dependency effect with exact cleanup, and directly return the debounced state.
+- The compiler preserves the source signal dependency, treats the literal delay as stable scope, and initializes the debounced signal from the source signal's build value.
+
+### Boundaries
+
+- The hook body must be the direct `useState(value)`, `useEffect()`, and returned-state shape proven by the ClimateCompatibleGrowth fixture.
+- Dynamic delays, non-primitive source state, aliases, additional statements/effects, intervals, and missing timeout cleanup remain rejected.
+- No debounce/timer runtime, component tree, hydration, or new effect capability is added.
+
+### Validation
+
+- A fixture reduced from ClimateCompatibleGrowth's MIT-licensed `useDebouce.ts` preserves its generic parameterized custom-hook source shape.
+- Browser coverage proves rapid replacement, pending-timeout cleanup on conditional removal, fresh remount state, and latest-value commit.
+- A static sibling remains zero JavaScript and dynamic delay input fails at its authored call site.
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 230 tests and 174 generated pages.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.8.61
+```
+
 ## 0.8.60 - Array draft effect sync
 
 Kudzu 0.8.60 lets a specialized child synchronize direct prop-derived array draft state through the matching parent setter in an ordinary dependency effect.

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.60` 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, keyed-item draft state initialization, matching array-draft setter effects, 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.
+The active post-`0.8.61` 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, keyed-item draft state initialization, matching array-draft setter effects, parameterized primitive debounce hooks, 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.60` 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.61` 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`; direct keyed item draft initialization completed in `0.8.58`; direct array prop draft initialization completed in `0.8.59`; matching array-draft setter effects completed in `0.8.60`:** 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, exact direct setter-effect synchronization through existing effect ownership, stable setter-dependency erasure, no automatic mounted prop synchronization, and zero-JavaScript static sibling output. A fourth callback boundary, callback aliases/non-handler uses, mismatched state/setter effect pairs, 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.
+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`; matching array-draft setter effects completed in `0.8.60`; parameterized primitive debounce hooks completed in `0.8.61`:** 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 and exact direct setter-effect synchronization, while its relative debounce hook specializes one direct primitive source and literal delay through existing timeout cleanup ownership. A fourth callback boundary, callback aliases/non-handler uses, dynamic debounce delays, non-primitive debounce inputs, mismatched state/setter effect pairs, 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, `0.8.57` plain-object prop, `0.8.58` direct keyed item, `0.8.59` direct array prop initializer, and `0.8.60` matching array-draft setter-effect 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.
+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, `0.8.59` direct array prop initializer, `0.8.60` matching array-draft setter-effect, and `0.8.61` parameterized primitive debounce-hook 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.60` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.61` 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.
 
@@ -51,6 +51,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `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. |
 | `0.8.60` | Synchronize direct prop-derived array draft state through its matching parent setter in a dependency effect. | The ClimateCompatibleGrowth-derived dropdown preserves its exact direct effect/dependency shape, stable setter erasure, array identity comparison, independent parent replacement, nearby diagnostics, and a static zero-JavaScript sibling without runtime changes. |
+| `0.8.61` | Specialize one parameterized relative primitive debounce hook through existing state and dependency-effect ownership. | The ClimateCompatibleGrowth-derived hook preserves direct state initialization, literal delay scope, timeout replacement/cleanup, conditional release, latest-value commit, nearby diagnostics, and a static zero-JavaScript sibling without runtime changes. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -6,7 +6,7 @@ Migration source may retain conventional `react` imports for supported named or
 
 Compilation begins from page entries and follows relative runtime imports, re-exports, and validated Worker references; unreachable TypeScript migration files are not transformed. Direct maps over imported immutable JSON-safe arrays fold to literals for zero-JavaScript static rows. Synchronous relative calculation functions may return objects whose direct static fields feed reactive JSX bindings; build rendering uses current signal values and route-specific binding ESM reevaluates the same helper after state commits. One direct array field may instead feed a keyed intrinsic map: its evaluator refreshes a compiler-owned array anchor before the existing list reconciler runs, preserving keyed DOM and SVG identity without a calculation runtime. That field must remain a JSON-safe array after every source-state commit. Package imports have a separate narrow boundary: direct references inside intrinsic JSX event callbacks are erased from build modules and bundled into route handler ESM, while render-time, effect, helper-indirect, and mixed package use fails.
 
-Native platform work remains ordinary source. A direct async handler or directly returned relative custom-hook callback may call `navigator.clipboard.writeText()` and update application-owned success/failure state; Kudzu emits only its existing route handler ESM. Debounced synchronization uses a dependency effect that creates `setTimeout()` work and directly returns `clearTimeout()` cleanup, reusing dependency, conditional, keyed, and route ownership. One directly returned relative custom-hook callback may own one `null`-initialized private timeout ref when it directly clears the previous value, assigns a numeric-literal-delay `setTimeout()`, and an empty-dependency effect directly clears the timer on cleanup. Kudzu lowers that ref to compiler-owned state shared by existing handler and effect contexts. An ordinary inline effect may exclusively own top-level `useRef(null)` and `useRef(0)` values through direct `.current` references; Kudzu moves them into the setup invocation's closure for browser SDK handles, WebSockets, generation tokens, and animation frames without serialized captures or a resource runtime. Multiple timers, dynamic delays, intervals, ref aliases, cross-effect/event mutable refs, unowned delayed writes, and arbitrary timed callback graphs remain unsupported.
+Native platform work remains ordinary source. A direct async handler or directly returned relative custom-hook callback may call `navigator.clipboard.writeText()` and update application-owned success/failure state; Kudzu emits only its existing route handler ESM. Debounced synchronization uses a dependency effect that creates `setTimeout()` work and directly returns `clearTimeout()` cleanup, reusing dependency, conditional, keyed, and route ownership. A relative `useDebounce(value, delay)` hook may accept one direct primitive state and numeric literal delay, initialize and return one debounced state, and reuse that same effect ownership. One directly returned relative custom-hook callback may own one `null`-initialized private timeout ref when it directly clears the previous value, assigns a numeric-literal-delay `setTimeout()`, and an empty-dependency effect directly clears the timer on cleanup. Kudzu lowers that ref to compiler-owned state shared by existing handler and effect contexts. An ordinary inline effect may exclusively own top-level `useRef(null)` and `useRef(0)` values through direct `.current` references; Kudzu moves them into the setup invocation's closure for browser SDK handles, WebSockets, generation tokens, and animation frames without serialized captures or a resource runtime. Multiple timers, dynamic delays, intervals, ref aliases, cross-effect/event mutable refs, unowned delayed writes, and arbitrary timed callback graphs remain unsupported.
 
 Imperative canvas migrations use the same effect ownership rather than a component or canvas runtime. One `null`-initialized canvas DOM ref may feed an inline effect whose local variables persist across a recursive animation-frame callback, an `IntersectionObserver`, and native canvas/window listeners; the returned cleanup must cancel the latest frame, disconnect the observer, and remove every listener. Bare `IntersectionObserver` and `performance` identifiers remain browser globals in emitted effect ESM. Component-level mutable value refs and callbacks shared across effects or JSX handlers remain unsupported; move resource-private state and listeners into the owning effect.
 

package/framework/compiler/source-compiler.mjs

@@ -240,6 +240,60 @@ function normalizeLazyStateInitializers(sourceFile, factory, context, file, sour
   return ts.visitNode(sourceFile, visitor)
 }
 
+function parameterizedDebounceHook(hook) {
+  if (!hook || hook.parameters.length !== 2 || hook.asteriskToken || hook.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || !ts.isBlock(hook.body) || hook.body.statements.length !== 3) return undefined
+  const sourceFile = hook.getSourceFile()
+  if (!hasFrameworkImport(sourceFile, "useState") || !hasFrameworkImport(sourceFile, "useEffect")) return undefined
+  const [valueParameter, delayParameter] = hook.parameters
+  if (!ts.isIdentifier(valueParameter.name) || valueParameter.initializer || valueParameter.dotDotDotToken || !ts.isIdentifier(delayParameter.name) || delayParameter.initializer || delayParameter.dotDotDotToken) return undefined
+  const [stateStatement, effectStatement, returnStatement] = hook.body.statements
+  if (!ts.isVariableStatement(stateStatement) || !(stateStatement.declarationList.flags & ts.NodeFlags.Const) || stateStatement.declarationList.declarations.length !== 1) return undefined
+  const stateDeclaration = stateStatement.declarationList.declarations[0]
+  if (!ts.isArrayBindingPattern(stateDeclaration.name) || stateDeclaration.name.elements.length !== 2 || !ts.isIdentifier(stateDeclaration.name.elements[0]?.name) || !ts.isIdentifier(stateDeclaration.name.elements[1]?.name) || !stateDeclaration.initializer || !ts.isCallExpression(stateDeclaration.initializer) || !ts.isIdentifier(stateDeclaration.initializer.expression) || stateDeclaration.initializer.expression.text !== "useState" || stateDeclaration.initializer.arguments.length !== 1) return undefined
+  const stateArgument = unwrapExpression(stateDeclaration.initializer.arguments[0])
+  const directValue = ts.isIdentifier(stateArgument) && stateArgument.text === valueParameter.name.text
+  const normalizedValue = ts.isPropertyAccessExpression(stateArgument) && ts.isIdentifier(stateArgument.expression) && stateArgument.expression.text === valueParameter.name.text && stateArgument.name.text === "value"
+  if (!directValue && !normalizedValue) return undefined
+  if (!ts.isExpressionStatement(effectStatement) || !ts.isCallExpression(effectStatement.expression) || !ts.isIdentifier(effectStatement.expression.expression) || effectStatement.expression.expression.text !== "useEffect" || effectStatement.expression.arguments.length !== 2) return undefined
+  const [setup, dependencies] = effectStatement.expression.arguments
+  if ((!ts.isArrowFunction(setup) && !ts.isFunctionExpression(setup)) || setup.parameters.length || setup.asteriskToken || setup.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || !ts.isBlock(setup.body) || setup.body.statements.length !== 2 || !ts.isArrayLiteralExpression(dependencies)) return undefined
+  const normalizedDependencies = dependencies.elements.length === 1 && ts.isIdentifier(dependencies.elements[0]) && dependencies.elements[0].text === valueParameter.name.text
+  const sourceDependencies = dependencies.elements.length === 2 && ts.isIdentifier(dependencies.elements[0]) && dependencies.elements[0].text === valueParameter.name.text && ts.isIdentifier(dependencies.elements[1]) && dependencies.elements[1].text === delayParameter.name.text
+  if (!normalizedDependencies && !sourceDependencies) return undefined
+  const timerStatement = setup.body.statements[0]
+  if (!ts.isVariableStatement(timerStatement) || !(timerStatement.declarationList.flags & ts.NodeFlags.Const) || timerStatement.declarationList.declarations.length !== 1) return undefined
+  const timerDeclaration = timerStatement.declarationList.declarations[0]
+  if (!ts.isIdentifier(timerDeclaration.name) || !timerDeclaration.initializer || !ts.isCallExpression(timerDeclaration.initializer) || !ts.isIdentifier(timerDeclaration.initializer.expression) || timerDeclaration.initializer.expression.text !== "setTimeout" || !isUnshadowedGlobal(timerDeclaration.initializer.expression, sourceFile) || timerDeclaration.initializer.arguments.length !== 2 || !ts.isIdentifier(timerDeclaration.initializer.arguments[1]) || timerDeclaration.initializer.arguments[1].text !== delayParameter.name.text) return undefined
+  const timeoutCallback = timerDeclaration.initializer.arguments[0]
+  const timeoutBody = (ts.isArrowFunction(timeoutCallback) || ts.isFunctionExpression(timeoutCallback)) && !timeoutCallback.parameters.length && !timeoutCallback.asteriskToken && !timeoutCallback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) ? timeoutCallback.body : undefined
+  const setterCall = timeoutBody && (ts.isBlock(timeoutBody) ? timeoutBody.statements.length === 1 && ts.isExpressionStatement(timeoutBody.statements[0]) ? timeoutBody.statements[0].expression : undefined : timeoutBody)
+  if (!setterCall || !ts.isCallExpression(setterCall) || !ts.isIdentifier(setterCall.expression) || setterCall.expression.text !== stateDeclaration.name.elements[1].name.text || setterCall.arguments.length !== 1 || !ts.isIdentifier(setterCall.arguments[0]) || setterCall.arguments[0].text !== valueParameter.name.text) return undefined
+  const cleanupReturn = setup.body.statements[1]
+  const cleanup = ts.isReturnStatement(cleanupReturn) && cleanupReturn.expression && (ts.isArrowFunction(cleanupReturn.expression) || ts.isFunctionExpression(cleanupReturn.expression)) && !cleanupReturn.expression.parameters.length ? cleanupReturn.expression : undefined
+  const cleanupBody = cleanup && (ts.isBlock(cleanup.body) ? cleanup.body.statements.length === 1 && ts.isExpressionStatement(cleanup.body.statements[0]) ? cleanup.body.statements[0].expression : undefined : cleanup.body)
+  if (!cleanupBody || !ts.isCallExpression(cleanupBody) || !ts.isIdentifier(cleanupBody.expression) || cleanupBody.expression.text !== "clearTimeout" || !isUnshadowedGlobal(cleanupBody.expression, sourceFile) || cleanupBody.arguments.length !== 1 || !ts.isIdentifier(cleanupBody.arguments[0]) || cleanupBody.arguments[0].text !== timerDeclaration.name.text) return undefined
+  if (!ts.isReturnStatement(returnStatement) || !returnStatement.expression || !ts.isIdentifier(returnStatement.expression) || returnStatement.expression.text !== stateDeclaration.name.elements[0].name.text) return undefined
+  return { dependencies, delay: delayParameter.name.text, normalized: normalizedValue && normalizedDependencies, stateCall: stateDeclaration.initializer, state: stateDeclaration.name.elements[0].name.text, setter: stateDeclaration.name.elements[1].name.text, value: valueParameter.name.text }
+}
+
+function normalizeParameterizedDebounceHooks(sourceFile, factory, context) {
+  const visitor = node => {
+    if (ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+      const hook = parameterizedDebounceHook(node)
+      if (hook && !hook.normalized) {
+        const rewrite = current => {
+          if (current === hook.stateCall) return factory.updateCallExpression(current, current.expression, current.typeArguments, [factory.createPropertyAccessExpression(factory.createIdentifier(hook.value), "value")])
+          if (current === hook.dependencies) return factory.updateArrayLiteralExpression(current, [factory.createIdentifier(hook.value)])
+          return ts.visitEachChild(current, rewrite, context)
+        }
+        return ts.visitEachChild(node, rewrite, context)
+      }
+    }
+    return ts.visitEachChild(node, visitor, context)
+  }
+  return ts.visitNode(sourceFile, visitor)
+}
+
 function normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedStaticCollections, sourceFiles, sourceIndex }) {
   const factory = context.factory
   let customHookTimerStates = new Set()
@@ -250,6 +304,7 @@ function normalizeCompilerSource(sourceFile, { base, context, file, importedColl
     source => normalizeMediaQueryExternalStores(source, factory, context),
     source => normalizeReactMigrationSyntax(source, factory, context, importedCollections ?? importedSerializableCollectionNames(source, file, sourceFiles, sourceIndex)),
     source => normalizeNavigatorCapabilityConditions(source, factory, context),
+    source => normalizeParameterizedDebounceHooks(source, factory, context),
     source => normalizeEffectPrivateRefs(source, factory, context),
     source => {
       const result = normalizeCustomHookTimerRefs(source, factory, context)
@@ -365,6 +420,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const components = new Map()
     const contexts = new Set()
     const customHooks = new Map()
+    const parameterizedDebounceCalls = new WeakSet()
+    const resolvedParameterizedDebounceHooks = new Map()
     const jsxLocalDeclarations = new Map()
     const jsxLocalsByFunction = new Map()
     const listLocalDeclarations = []
@@ -550,11 +607,36 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       customHooks.set(key, analysis)
       return analysis
     }
+    const resolveParameterizedDebounceHook = binding => {
+      const exportName = binding.kind === "default" ? "default" : binding.imported
+      const key = `${binding.target}:${exportName}`
+      if (resolvedParameterizedDebounceHooks.has(key)) return resolvedParameterizedDebounceHooks.get(key)
+      const hook = resolveComponentExport(binding.target, exportName, importedSource, sourceFiles)
+      const analysis = parameterizedDebounceHook(hook)
+      resolvedParameterizedDebounceHooks.set(key, analysis)
+      return analysis
+    }
 
     const collect = node => {
       if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)) {
         const callName = ts.isIdentifier(node.initializer.expression) ? node.initializer.expression.text : ""
-        if (callName && /^use[A-Z]/.test(callName) && importBindings.has(callName) && importBindings.get(callName).kind !== "namespace" && !resolvedSharedState(importBindings.get(callName))) {
+        const customHookImport = callName && /^use[A-Z]/.test(callName) && importBindings.has(callName) && importBindings.get(callName).kind !== "namespace" && !resolvedSharedState(importBindings.get(callName))
+        const debounce = customHookImport && ts.isIdentifier(node.name) ? resolveParameterizedDebounceHook(importBindings.get(callName)) : undefined
+        if (debounce) {
+          if (!isLocalConst(node)) throw sourceNodeError(node, sourceFile, "Parameterized debounce hooks must initialize one top-level const identifier")
+          const owner = nearestFunction(node)
+          const value = node.initializer.arguments[0] && unwrapExpression(node.initializer.arguments[0])
+          const delay = node.initializer.arguments[1] && unwrapExpression(node.initializer.arguments[1])
+          const setters = owner ? settersByFunction.get(owner) ?? new Map() : new Map()
+          if (!owner) throw sourceNodeError(node, sourceFile, "Parameterized debounce hooks cannot be used outside a Kudzu component")
+          if (node.initializer.arguments.length !== 2 || !ts.isIdentifier(value) || !new Set(setters.values()).has(value.text) || !componentHasDirectPrimitiveState(owner, value.text)) throw sourceNodeError(node.initializer, sourceFile, "Parameterized debounce hooks require one direct primitive state argument")
+          if (!ts.isNumericLiteral(delay)) throw sourceNodeError(node.initializer.arguments[1] ?? node.initializer, sourceFile, "Parameterized debounce hook delays must be numeric literals")
+          const syntheticSetter = `__kSetDebounced_${Math.max(0, node.pos)}`
+          setters.set(syntheticSetter, node.name.text)
+          registerState(owner, node.name.text, syntheticSetter, "custom-hook", node)
+          settersByFunction.set(owner, setters)
+          parameterizedDebounceCalls.add(node.initializer)
+        } else if (customHookImport) {
           if (!isLocalConst(node) || !ts.isObjectBindingPattern(node.name) || node.initializer.arguments.length) throw sourceNodeError(node, sourceFile, "Relative custom hooks must initialize one top-level const object destructuring with no arguments")
           const hook = resolveCustomHook(importBindings.get(callName), node.initializer)
           const names = new Set()
@@ -711,6 +793,13 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         if (node.parent === sourceFile) {
           components.set(node.name.text, { function: node, declaration: node })
           ensureOwner(node)
+          const debounce = parameterizedDebounceHook(node)
+          if (debounce) {
+            const setters = settersByFunction.get(node) ?? new Map()
+            setters.set(`__kDebounceSource_${Math.max(0, node.pos)}`, debounce.value)
+            registerState(node, debounce.value, `__kDebounceSource_${Math.max(0, node.pos)}`, "custom-hook", node.parameters[0])
+            settersByFunction.set(node, setters)
+          }
         }
       }
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
@@ -736,7 +825,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         }
       }
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression) && node.initializer.expression.text === "createContext") contexts.add(node.name.text)
-      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && isLocalConst(node)) {
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && isLocalConst(node) && !(ts.isCallExpression(node.initializer) && parameterizedDebounceCalls.has(node.initializer))) {
         const owner = nearestFunction(node)
         const declarations = jsxLocalDeclarations.get(owner) ?? new Map()
         const entries = declarations.get(node.name.text) ?? []
@@ -1857,6 +1946,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       }
 
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression) && importBindings.has(node.initializer.expression.text)) {
+        if (parameterizedDebounceCalls.has(node.initializer)) return node
         const setters = settersForNode(node, settersByFunction)
         const stateNames = new Set(setters.values())
         const rewrite = current => {
@@ -2148,6 +2238,10 @@ function componentHasDirectPropStateInitializer(component) {
   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 componentHasDirectPrimitiveState(component, state) {
+  return Boolean(component && ts.isBlock(component.body) && component.body.statements.some(statement => ts.isVariableStatement(statement) && statement.declarationList.declarations.some(declaration => ts.isArrayBindingPattern(declaration.name) && ts.isIdentifier(declaration.name.elements[0]?.name) && declaration.name.elements[0].name.text === state && declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useState" && declaration.initializer.arguments.length === 1 && isPrimitiveDefaultLiteral(unwrapExpression(declaration.initializer.arguments[0])))))
+}
+
 function componentHasDirectArrayState(component, state) {
   return Boolean(component && ts.isBlock(component.body) && component.body.statements.some(statement => ts.isVariableStatement(statement) && statement.declarationList.declarations.some(declaration => ts.isArrayBindingPattern(declaration.name) && ts.isIdentifier(declaration.name.elements[0]?.name) && declaration.name.elements[0].name.text === state && declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useState" && declaration.initializer.arguments.length === 1 && ts.isArrayLiteralExpression(unwrapExpression(declaration.initializer.arguments[0])))))
 }

package/package.json

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