@kudzujs/core 0.6.8 → 0.6.10

package/README.md

@@ -6,7 +6,7 @@
 
 HTML-first TSX framework with synchronous state semantics and no virtual DOM.
 
-Kudzu keeps the familiar function-component, props, children, event-handler, `useState`, and mount-effect shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers and mount effects compile to external ESM.
+Kudzu keeps the familiar function-component, props, children, event-handler, `useState`, `useReducer`, and mount-effect shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers and mount effects compile to external ESM.
 
 > Experimental `0.6.x`: the compiler API and supported TSX surface may change.
 
@@ -171,6 +171,17 @@ return <p>{weather.temperature}° {weather.label}</p>
 
 Derived text uses comment-bounded text nodes rather than wrapper elements, so table cells, options, SVG text, layout, and element selectors keep their authored structure.
 
+Reducer state uses the same immediate logical updates and batched DOM commit:
+
+```tsx
+import todoReducer from "../todoReducer"
+
+const [todos, dispatch] = useReducer(todoReducer, [])
+dispatch({ type: "add", title: "Ship" })
+```
+
+The reduced migration form requires `[state, dispatch]`, exactly two hook arguments, and a synchronous two-parameter reducer exported as a default or named value from a relative TypeScript module. Dispatches in compiled handlers lower to functional state updates; lazy initializers, package, namespace, local, async, and generator reducers are not supported. Reducer dispatch functions cannot be passed through props or context.
+
 ## Reactive Attributes
 
 `className`, `disabled`, controlled `value`, and controlled `checked` accept normal state-dependent TSX expressions. The same `value` binding works for inputs and selects:
@@ -523,7 +534,7 @@ Supported:
 - Runtime bracket parameters with static fallback documents and host rewrite metadata
 - Static trusted `dangerouslySetInnerHTML`
 - Base-path deployments, multiple CSS files, and `afterBuild`
-- Primitive `useState` bindings
+- `useState` and relative-imported `useReducer` bindings
 - Mount-only `useEffect(fn, [])` compiled to route-specific ESM
 - Relative TypeScript module Workers owned by inline effects
 - Conditional and keyed-row effect ownership with cleanup on DOM removal

package/framework/README.md

@@ -23,6 +23,8 @@ Page `metadata` can emit description, canonical, favicon, manifest, Open Graph,
 
 Same-file and relative-imported components receiving a direct local-state array prop are specialized to intrinsic JSX before keyed-list analysis, so their component function is not retained in the browser. Handler modules are emitted only when a rendered descriptor references them, preventing specialized imported components from adding dead browser assets. Direct JSON-safe primitive keyed-item dependencies subscribe each row record to its owning list commit and compare selected fields after `list-runtime.js` synchronously refreshes the row marker. Only changed rows rerun with the complete latest item; reorder compares equal, unrelated fields do nothing, and key changes remain remove plus mount. Builds without item dependencies emit no item reader or list-state subscription code.
 
+The reduced `useReducer` form reuses ordinary state slots. A direct dispatch in a compiled handler becomes a functional `set` whose reducer is bundled from a relative TypeScript module into that handler graph. Reducer-free routes and shared runtimes are unchanged; no reducer runtime or browser component instance exists.
+
 `kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Direct primitive state, runtime parameter, and keyed-item property dependencies and cleanup are supported. Fragment payloads and coordinated View Transitions are not implemented.
 
 The current matched commerce profile emits 35,355 deploy bytes and loads 7,334 B gzip of product-route JavaScript, including 2,425 B for navigation. These sizes are unchanged because its top-level-only navigation effects retain the smaller specialized path. Validated prefetch reduced the original 128.7 ms product-to-cart navigation to 5.6 ms in the current run. Seven interleaved artifact-clean builds after warm-up measured Kudzu at 486.8 ms and React at 545.4 ms, making Kudzu 10.7% faster. Cache-disabled output is byte-for-byte identical.

package/framework/build.mjs

@@ -1611,6 +1611,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       return imported
     }
     const settersByFunction = new Map()
+    const reducersByFunction = new Map()
     const functions = new Map()
     const components = new Map()
     const contexts = new Set()
@@ -1630,15 +1631,41 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     let usesListItem = false
 
     const collect = node => {
-      if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer)) {
+      if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)) {
         const callName = ts.isIdentifier(node.initializer.expression) ? node.initializer.expression.text : ""
-        const [stateElement, setterElement] = node.name.elements
-        if (callName === "useState" && stateElement && setterElement && ts.isBindingElement(stateElement) && ts.isBindingElement(setterElement) && ts.isIdentifier(stateElement.name) && ts.isIdentifier(setterElement.name)) {
+        if (callName === "useReducer") {
+          if (!ts.isArrayBindingPattern(node.name)) throw sourceNodeError(node.name, sourceFile, "useReducer() must use [state, dispatch] identifier destructuring")
+          const [stateElement, dispatchElement] = node.name.elements
+          if (node.name.elements.length !== 2 || !stateElement || !dispatchElement || !ts.isBindingElement(stateElement) || !ts.isBindingElement(dispatchElement) || !ts.isIdentifier(stateElement.name) || !ts.isIdentifier(dispatchElement.name)) throw sourceNodeError(node.name, sourceFile, "useReducer() must use [state, dispatch] identifier destructuring")
+          if (node.initializer.arguments.length !== 2) throw sourceNodeError(node.initializer, sourceFile, "useReducer() requires exactly a reducer and initial value")
+          const reducer = node.initializer.arguments[0]
+          if (!ts.isIdentifier(reducer) || !importBindings.has(reducer.text) || importBindings.get(reducer.text).kind === "namespace") throw sourceNodeError(reducer, sourceFile, "useReducer() reducers must be default or named imports from relative TypeScript modules")
+          const reducerImport = importBindings.get(reducer.text)
+          let reducerDeclaration
+          try {
+            reducerDeclaration = resolveComponentExport(reducerImport.target, reducerImport.kind === "default" ? "default" : reducerImport.imported, importedSource, sourceFiles)
+          } catch {
+            throw sourceNodeError(reducer, sourceFile, "useReducer() imports must resolve to a statically analyzable reducer function")
+          }
+          if (reducerDeclaration.parameters.length !== 2 || reducerDeclaration.asteriskToken || reducerDeclaration.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) throw sourceNodeError(reducer, sourceFile, "useReducer() reducers must be synchronous functions with exactly state and action parameters")
           const owner = nearestFunction(node)
-          if (owner) {
-            const setters = settersByFunction.get(owner) ?? new Map()
-            setters.set(setterElement.name.text, stateElement.name.text)
-            settersByFunction.set(owner, setters)
+          if (!owner) throw sourceNodeError(node, sourceFile, "useReducer() cannot be used outside a Kudzu component")
+          const setters = settersByFunction.get(owner) ?? new Map()
+          setters.set(dispatchElement.name.text, stateElement.name.text)
+          settersByFunction.set(owner, setters)
+          const reducers = reducersByFunction.get(owner) ?? new Map()
+          reducers.set(dispatchElement.name.text, { state: stateElement.name.text, reducer: reducer.text, import: reducerImport })
+          reducersByFunction.set(owner, reducers)
+        }
+        if (ts.isArrayBindingPattern(node.name)) {
+          const [stateElement, setterElement] = node.name.elements
+          if (callName === "useState" && stateElement && setterElement && ts.isBindingElement(stateElement) && ts.isBindingElement(setterElement) && ts.isIdentifier(stateElement.name) && ts.isIdentifier(setterElement.name)) {
+            const owner = nearestFunction(node)
+            if (owner) {
+              const setters = settersByFunction.get(owner) ?? new Map()
+              setters.set(setterElement.name.text, stateElement.name.text)
+              settersByFunction.set(owner, setters)
+            }
           }
         }
       }
@@ -1931,7 +1958,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         } else {
           compiledCallback = rewriteEffectWorkers(callback, callbackFile, callbackSource, sourceFiles, workerReferences, factory, context)
         }
-        const descriptor = compileNativeCallback(compiledCallback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
+        const descriptor = compileNativeCallback(compiledCallback, setters, reducersForNode(node, reducersByFunction), factory, effectHandlers, listEffect?.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
@@ -1948,7 +1975,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.arguments.length === 1) {
+      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.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, [
@@ -2030,7 +2057,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
 
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && /^on[A-Z]/.test(node.name.text)) {
         const setters = settersForNode(node, settersByFunction)
-        const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl, listEventItems.get(node), importBindings, clientImports)
+        const event = compileEvent(node.initializer.expression, setters, reducersForNode(node, reducersByFunction), functions, factory, nativeHandlers, handlerUrl, listEventItems.get(node), importBindings, clientImports)
         if (event) {
           usesBehavior = true
           return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, event))
@@ -2656,15 +2683,15 @@ function factoryNull() {
   return ts.factory.createNull()
 }
 
-function compileEvent(expression, setters, functions, factory, nativeHandlers, handlerUrl, listItem, importBindings, clientImports) {
+function compileEvent(expression, setters, reducers, functions, factory, nativeHandlers, handlerUrl, listItem, importBindings, clientImports) {
   if (ts.isIdentifier(expression)) expression = functions.get(expression.text)
   if (!expression || (!ts.isArrowFunction(expression) && !ts.isFunctionExpression(expression) && !ts.isFunctionDeclaration(expression))) return undefined
 
-  const optimized = compileOptimizedEvent(expression, setters, factory)
+  const optimized = referencedReducerDispatches(expression.body, reducers, expression).size ? undefined : compileOptimizedEvent(expression, setters, factory)
   if (optimized) return optimized
 
   rejectWorkerConstructions(expression, expression.getSourceFile(), "Relative TypeScript Worker construction is only supported directly inside an inline useEffect() callback")
-  const descriptor = compileNativeCallback(expression, setters, factory, nativeHandlers, importBindings, clientImports, "handler", listItem)
+  const descriptor = compileNativeCallback(expression, setters, reducers, factory, nativeHandlers, importBindings, clientImports, "handler", listItem)
   return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
     factory.createStringLiteral(handlerUrl),
     factory.createStringLiteral(descriptor.exportName),
@@ -2673,14 +2700,16 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   ])
 }
 
-function compileNativeCallback(expression, setters, factory, entries, importBindings, clientImports, prefix, listItem, deferValues = false, snapshotNested = false) {
+function compileNativeCallback(expression, setters, reducers, factory, entries, importBindings, clientImports, prefix, listItem, deferValues = false, snapshotNested = false) {
   const allCaptures = nativeCaptureNames(expression, setters)
+  const usedReducers = referencedReducerDispatches(expression.body, reducers, expression)
   const imports = [...referencedImportedBindings(expression, importBindings)].map(name => importBindings.get(name))
+  imports.push(...[...usedReducers].map(name => reducers.get(name).import))
   const captures = new Set([...allCaptures].filter(name => !importBindings.has(name)))
   for (const entry of imports) clientImports.add(entry.target)
   const usedStates = nativeStateNames(expression, setters)
   const exportName = `${prefix}${entries.length}`
-  entries.push({ exportName, expression, captures, imports, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), snapshotNested })
+  entries.push({ exportName, expression, captures, imports, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested })
   const value = name => deferValues
     ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createIdentifier(name))
     : factory.createIdentifier(name)
@@ -2697,6 +2726,16 @@ function compileNativeCallback(expression, setters, factory, entries, importBind
   }
 }
 
+function referencedReducerDispatches(root, reducers, scopeRoot = root) {
+  const used = new Set()
+  const visit = node => {
+    if (ts.isIdentifier(node) && reducers.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, scopeRoot)) used.add(node.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return used
+}
+
 function nativeStateNames(expression, setters) {
   return referencedStateNames(expression.body, setters, expression)
 }
@@ -2945,6 +2984,15 @@ function settersForNode(node, settersByFunction) {
   return new Map()
 }
 
+function reducersForNode(node, reducersByFunction) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (!ts.isFunctionDeclaration(current) && !ts.isFunctionExpression(current) && !ts.isArrowFunction(current)) continue
+    const reducers = reducersByFunction.get(current)
+    if (reducers) return reducers
+  }
+  return new Map()
+}
+
 function clientImportBindings(sourceFile, file, sourceFiles) {
   const bindings = new Map()
   for (const node of sourceFile.statements) {
@@ -3242,7 +3290,7 @@ function relativeModulePath(from, to) {
   return path.startsWith(".") ? path : `./${path}`
 }
 
-function printNativeHandler({ exportName, expression, captures, setters, snapshotNested }) {
+function printNativeHandler({ exportName, expression, captures, setters, reducers = new Map(), snapshotNested }) {
   const factory = ts.factory
   const stateNames = new Set(setters.values())
   const snapshotNames = snapshotNested ? nestedStateNames(expression, setters) : new Set()
@@ -3251,6 +3299,16 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
   const captureSnapshots = new Map([...captureSnapshotNames].map(name => [name, factory.createUniqueName("__kEffectCapture")]))
   const transformer = context => root => {
     const visitor = node => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && reducers.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
+        if (node.arguments.length !== 1) throw sourceNodeError(node, expression.getSourceFile(), "Reducer dispatches require exactly one action")
+        return reducerDispatch(factory, reducers.get(node.expression.text), ts.visitNode(node.arguments[0], visitor))
+      }
+      if (ts.isShorthandPropertyAssignment(node) && reducers.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        return factory.createPropertyAssignment(node.name, reducerReference(factory, reducers.get(node.name.text)))
+      }
+      if (ts.isIdentifier(node) && reducers.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
+        return reducerReference(factory, reducers.get(node.text))
+      }
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
         return factory.createCallExpression(
           factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"),
@@ -3357,6 +3415,17 @@ function setterReference(factory, stateName) {
   )
 }
 
+function reducerReference(factory, reducer) {
+  const action = factory.createUniqueName("__kAction")
+  return factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, action)], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), reducerDispatch(factory, reducer, action))
+}
+
+function reducerDispatch(factory, reducer, action) {
+  const previous = factory.createUniqueName("__kPrevious")
+  const update = factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, previous)], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createCallExpression(factory.createIdentifier(reducer.reducer), undefined, [previous, action]))
+  return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"), undefined, [factory.createStringLiteral(reducer.state), update])
+}
+
 function printReactiveBinding({ exportName, expression, captures, states }) {
   const factory = ts.factory
   const transformer = context => root => {

package/framework/core.d.ts

@@ -1,8 +1,11 @@
 export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
+export type Reducer<State, Action> = (state: State, action: Action) => State
+export type Dispatch<Action> = (action: Action) => void
 export type EffectCleanup = () => void | Promise<void>
 export type EffectDependency = string | number | boolean | null
 
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
+export function useReducer<State, Action>(reducer: Reducer<State, Action>, initialValue: State): [State, Dispatch<Action>]
 export function useEffect(effect: () => void | EffectCleanup | Promise<void>, dependencies: readonly EffectDependency[]): void
 export function useParams<Params extends Record<string, string> = Record<string, string>>(): Readonly<Params>
 

package/framework/core.mjs

@@ -2,6 +2,7 @@ import { serializeStyle } from "./style.js"
 
 const signalMarker = Symbol("kudzu.signal")
 const setterMarker = Symbol("kudzu.setter")
+const reducerDispatchMarker = Symbol("kudzu.reducerDispatch")
 const behaviorMarker = Symbol("kudzu.behavior")
 const nativeBehaviorMarker = Symbol("kudzu.nativeBehavior")
 const bindingMarker = Symbol("kudzu.binding")
@@ -35,6 +36,16 @@ export function useState(initialValue, name) {
   return [signal, setter]
 }
 
+export function useReducer(reducer, initialValue, name) {
+  if (typeof reducer !== "function") throw new Error("useReducer() requires a reducer function")
+  const [state] = useState(initialValue, name)
+  const dispatch = () => {
+    throw new Error("Reducer dispatches are compiled into browser handlers")
+  }
+  Object.defineProperty(dispatch, reducerDispatchMarker, { value: state.id })
+  return [state, dispatch]
+}
+
 export function useParams() {
   if (renderContext?.renderScope === "layout") throw new Error("useParams() is only supported in route scope")
   if (!renderContext?.runtimeParamNames?.length) throw new Error("useParams() requires export const runtimeParams = true on a bracket page")
@@ -268,6 +279,7 @@ function serializeCapture(name, value, seen) {
   if (value?.[listItemMarker]) return { type: "list-item" }
   if (value?.[refMarker]) return { type: "ref", id: value.id }
   if (value?.[signalMarker]) return { type: "state", id: value.id }
+  if (typeof value === "function" && value[reducerDispatchMarker]) throw new Error(`Native capture "${name}" cannot contain a reducer dispatch`)
   if (typeof value === "function" && value[setterMarker]) return { type: "setter", id: value[setterMarker] }
   if (value === null || typeof value === "string" || typeof value === "boolean") return value
   if (typeof value === "number") {

package/package.json

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