@kudzujs/core 0.7.1 → 0.7.2

package/README.md

@@ -10,7 +10,7 @@ Kudzu is designed so ordinary common React-shaped TSX can migrate with minimal s
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**0.7.1:** Vite-style landing assets. Common CSS, CSS Module, image, SVG, font, and `?url` imports now compile to static output without React, a VDOM, or hydration. See [release notes](./RELEASES.md#071---vite-style-landing-assets).
+**0.7.2:** React hook normalization. Aliased hooks, direct members such as `React.useState`, and inline `useCallback` now compile to existing Kudzu capabilities without React, a VDOM, or hydration. See [release notes](./RELEASES.md#072---react-hook-normalization).
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -74,7 +74,7 @@ export default function Header() {
 }
 ```
 
-Kudzu rewrites supported React imports to its compile-time APIs before evaluating the module; neither the React package nor a compatibility runtime enters the deploy output. Named `useState`, `useReducer`, `useEffect`, `useRef`, `createContext`, and `useContext` imports must retain those names. Default and namespace React imports currently support `Fragment`; named `Fragment` also works. Aliased hooks, `React.useState`, `memo`, `useMemo`, `useCallback`, React classes, and side-effect or dynamic React imports remain unsupported. A static route using these import forms still emits zero JavaScript.
+Kudzu rewrites supported React imports to its compile-time APIs before evaluating the module; neither the React package nor a compatibility runtime enters the deploy output. Named or aliased `useState`, `useReducer`, `useEffect`, `useRef`, `createContext`, and `useContext` imports compile to their canonical forms. Default and namespace imports may call those APIs as direct members such as `React.useState`, and default, namespace, or named `Fragment` also works. Inline `useCallback(function, literalDependencies)` is erased to its function because Kudzu does not retain or rerender a browser component. `memo`, `useMemo`, React classes, and side-effect or dynamic React imports remain unsupported. A static route using these import forms still emits zero JavaScript.
 
 Create `src/pages/index.tsx`:
 
@@ -225,7 +225,7 @@ const add = (title: string) => dispatch({ type: "add", title })
 return <Input onSubmit={add} />
 ```
 
-Kudzu substitutes the callback into the child's compiled event handler at build time. This is not general function-prop serialization: only one nested specialized callback boundary is supported, and `useCallback`, further forwarding, effects, component roots, and callback use outside event handlers are rejected.
+Kudzu substitutes the callback into the child's compiled event handler at build time. An inline React `useCallback` wrapper is erased before this analysis. This is not general function-prop serialization: only one nested specialized callback boundary is supported, and further forwarding, effects, component roots, and callback use outside event handlers are rejected.
 
 Reducer dispatch and callback components may use destructured string, finite-number, boolean, or `null` defaults. A missing prop is replaced during specialization; object, array, computed, and function-call defaults remain unsupported:
 

package/RELEASES.md

@@ -1,5 +1,29 @@
 # Kudzu Releases
 
+## 0.7.2 - React hook normalization
+
+Kudzu 0.7.2 accepts more ordinary React/Vite hook syntax while compiling through the existing static HTML and direct DOM capability paths.
+
+### New in 0.7.2
+
+- Supported hooks imported from `react` may retain aliases such as `useState as useMenuState` and `useEffect as runEffect`.
+- Default and namespace imports may use direct supported members such as `React.useState(...)`.
+- Inline React `useCallback` wrappers with literal inert dependencies are erased to their callback before Kudzu specialization.
+- Captured local state must appear in the callback dependency array, preserving an actionable boundary around stale React closures.
+- Unsupported members, indirect hook references, computed React members, and effectful dependency expressions fail with source locations.
+- Type-only React namespaces remain available to TypeScript and do not trigger runtime migration diagnostics.
+- A React/Vite-shaped app fixture verifies CSS, SVG assets, a non-root base, aliased state/effects, member state, repeated callback updates, browser interaction, and a zero-JavaScript static route.
+
+### Boundary
+
+`useCallback` requires an inline function and a literal array containing only identifiers or primitive literals. `memo`, `useMemo`, React classes, indirect hook references, side-effect React imports, and dynamic React imports remain unsupported. React, a VDOM, hydration, and a retained browser component tree are never emitted.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.2
+```
+
 ## 0.7.1 - Vite-style landing assets
 
 Kudzu 0.7.1 lets ordinary React/Vite landing-page source retain its common local stylesheet and static asset imports while preserving static HTML output and capability-only JavaScript.

package/framework/README.md

@@ -2,7 +2,7 @@
 
 Kudzu specializes ordinary common React-shaped TSX so migrations need minimal source restructuring. Declarative components, collection pipelines, conditions, hooks, and handlers should be lowered at build time rather than replaced with application-owned imperative DOM code. This principle applies across migrations and is not Stay-specific; it does not imply a React package, VDOM, hydration, or ecosystem runtime.
 
-Migration source may retain conventional `react` imports for unaliased supported named hooks and default, namespace, or named `Fragment`. `build.mjs` rewrites those module references to `@kudzujs/core` before build-time evaluation. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports. Member hook calls and aliased hooks are deliberately not inferred yet.
+Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, inline `useCallback`, and default, namespace, or named `Fragment`. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. `useCallback` is erased to its function because no browser component rerender occurs. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
 
 - `build.mjs`: TSX compilation, static, `getStaticPaths`, and runtime-fallback routes, base paths, CSS collection, post-build hooks, behavior extraction, static HTML output, and the development server.
 - `core.mjs`: server-side JSX rendering, state slots, context providers, behavior metadata, and serializable capture validation.

package/framework/build.mjs

@@ -1744,10 +1744,133 @@ function hasReactModuleReference(source, file) {
   return found
 }
 
+function normalizeReactMigrationSyntax(sourceFile, factory, context) {
+  const supported = new Set(["createContext", "useContext", "useEffect", "useReducer", "useRef", "useState"])
+  const aliases = new Map()
+  const reactObjects = new Set()
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "react") continue
+    if (statement.importClause?.name) reactObjects.add(statement.importClause.name.text)
+    const bindings = statement.importClause?.namedBindings
+    if (bindings && ts.isNamespaceImport(bindings)) reactObjects.add(bindings.name.text)
+    if (bindings && ts.isNamedImports(bindings)) for (const entry of bindings.elements) {
+      const imported = (entry.propertyName ?? entry.name).text
+      if (!entry.isTypeOnly && (supported.has(imported) || imported === "useCallback")) aliases.set(entry.name.text, imported)
+      else if (!entry.isTypeOnly && (imported === "memo" || /^use[A-Z]/.test(imported))) throw sourceNodeError(entry, sourceFile, `React ${imported} is not supported by Kudzu migration input`)
+    }
+  }
+  if (!aliases.size && !reactObjects.size) return sourceFile
+
+  const migrationCallName = call => {
+    if (ts.isIdentifier(call.expression) && aliases.has(call.expression.text) && !isShadowedIdentifier(call.expression, sourceFile)) return aliases.get(call.expression.text)
+    if (ts.isPropertyAccessExpression(call.expression) && ts.isIdentifier(call.expression.expression) && reactObjects.has(call.expression.expression.text) && !isShadowedIdentifier(call.expression.expression, sourceFile)) return call.expression.name.text
+    return undefined
+  }
+  const ownerStateNames = owner => {
+    const names = new Set()
+    const collect = node => {
+      if (node !== owner && isFunctionLike(node)) return
+      if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ["useReducer", "useState"].includes(migrationCallName(node.initializer))) {
+        const state = node.name.elements[0]
+        if (state && ts.isBindingElement(state) && ts.isIdentifier(state.name)) names.add(state.name.text)
+      }
+      ts.forEachChild(node, collect)
+    }
+    collect(owner)
+    return names
+  }
+
+  const validate = node => {
+    if (ts.isTypeNode(node)) return
+    if (ts.isIdentifier(node) && aliases.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile) && !(ts.isCallExpression(node.parent) && node.parent.expression === node)) throw sourceNodeError(node, sourceFile, `Aliased React ${aliases.get(node.text)} must be called directly`)
+    if (ts.isIdentifier(node) && reactObjects.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.expression === node)) throw sourceNodeError(node, sourceFile, "React default or namespace imports may only be used for direct supported members or React.Fragment")
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && reactObjects.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+      const name = node.name.text
+      if (name !== "Fragment" && !(ts.isCallExpression(node.parent) && node.parent.expression === node && (supported.has(name) || name === "useCallback"))) throw sourceNodeError(node, sourceFile, `React.${name} is not supported; use a directly supported hook call or React.Fragment`)
+    }
+    ts.forEachChild(node, validate)
+  }
+  validate(sourceFile)
+
+  const required = new Set()
+  const imported = new Set()
+  const visitor = node => {
+    if (ts.isCallExpression(node)) {
+      const name = migrationCallName(node)
+      if (name === "useCallback") {
+        if (node.arguments.length !== 2 || !ts.isArrayLiteralExpression(node.arguments[1]) || !(ts.isArrowFunction(node.arguments[0]) || ts.isFunctionExpression(node.arguments[0]))) throw sourceNodeError(node, sourceFile, "React useCallback() requires an inline function and a literal dependency array")
+        const dependency = node.arguments[1].elements.find(entry => !isReactCallbackDependency(entry))
+        if (dependency) throw sourceNodeError(dependency, sourceFile, "React useCallback() dependencies must be identifiers or primitive literals")
+        const dependencies = new Set(node.arguments[1].elements.map(unwrapExpression).filter(ts.isIdentifier).map(entry => entry.text))
+        const owner = nearestFunction(node)
+        const stale = owner && [...ownerStateNames(owner)].find(state => referenceIdentifiers(node.arguments[0], state).length && !dependencies.has(state))
+        if (stale) throw sourceNodeError(node.arguments[1], sourceFile, `React useCallback() must list captured state ${JSON.stringify(stale)} as a dependency`)
+        return ts.visitNode(node.arguments[0], visitor)
+      }
+      if (name && supported.has(name)) {
+        required.add(name)
+        return factory.updateCallExpression(node, factory.createIdentifier(name), node.typeArguments, ts.visitNodes(node.arguments, visitor))
+      }
+    }
+    if (ts.isImportDeclaration(node) && !node.importClause?.isTypeOnly && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react") {
+      const clause = node.importClause
+      if (!clause) return node
+      let bindings = clause.namedBindings
+      if (bindings && ts.isNamedImports(bindings)) {
+        const entries = []
+        for (const entry of bindings.elements) {
+          const name = (entry.propertyName ?? entry.name).text
+          if (!entry.isTypeOnly && name === "useCallback") continue
+          if (!entry.isTypeOnly && supported.has(name)) {
+            if (imported.has(name)) continue
+            imported.add(name)
+            required.add(name)
+            entries.push(factory.createImportSpecifier(false, undefined, factory.createIdentifier(name)))
+          } else {
+            entries.push(entry)
+          }
+        }
+        bindings = entries.length ? factory.updateNamedImports(bindings, entries) : undefined
+      }
+      if (!clause.name && !bindings) return undefined
+      return factory.updateImportDeclaration(node, node.modifiers, factory.updateImportClause(clause, clause.isTypeOnly, clause.name, bindings), node.moduleSpecifier, node.attributes)
+    }
+    return ts.visitEachChild(node, visitor, context)
+  }
+  let normalized = ts.visitNode(sourceFile, visitor)
+  const missing = [...required].filter(name => !imported.has(name)).sort()
+  if (!missing.length) return normalized
+  for (const name of missing) {
+    const collision = sourceFile.statements.some(statement => statementDeclaresName(statement, name) || ts.isImportDeclaration(statement) && importDeclarationNames(statement).includes(name) && statement.moduleSpecifier.text !== "react")
+    if (collision) throw sourceNodeError(sourceFile, sourceFile, `React.${name} cannot be normalized because ${JSON.stringify(name)} is already declared`)
+  }
+  const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports(missing.map(name => factory.createImportSpecifier(false, undefined, factory.createIdentifier(name))))), factory.createStringLiteral("react"))
+  const statements = [...normalized.statements]
+  const lastImport = statements.findLastIndex(statement => ts.isImportDeclaration(statement))
+  statements.splice(lastImport + 1, 0, declaration)
+  normalized = factory.updateSourceFile(normalized, statements)
+  return normalized
+}
+
+function importDeclarationNames(statement) {
+  const names = []
+  if (statement.importClause?.name) names.push(statement.importClause.name.text)
+  const bindings = statement.importClause?.namedBindings
+  if (bindings && ts.isNamespaceImport(bindings)) names.push(bindings.name.text)
+  if (bindings && ts.isNamedImports(bindings)) for (const entry of bindings.elements) names.push(entry.name.text)
+  return names
+}
+
+function isReactCallbackDependency(node) {
+  node = unwrapExpression(node)
+  return ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node) || node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword || node.kind === ts.SyntaxKind.NullKeyword
+}
+
 function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base, clientImports, workerReferences) {
   return context => sourceFile => {
     const factory = context.factory
     const hasLinkElements = /<link/i.test(sourceFile.text)
+    sourceFile = normalizeReactMigrationSyntax(sourceFile, factory, context)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
     rejectOrdinaryWorkerImports(sourceFile, file, sourceFiles)
@@ -1757,7 +1880,8 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     const importedSource = target => {
       let imported = importedSources.get(target)
       if (!imported) {
-        imported = normalizeRenderControlFlow(parseSourceFile(target, sourceIndex.get(target)), factory, context)
+        imported = normalizeReactMigrationSyntax(parseSourceFile(target, sourceIndex.get(target)), factory, context)
+        imported = normalizeRenderControlFlow(imported, factory, context)
         ts.setParentRecursive(imported, false)
         importedSources.set(target, imported)
       }
@@ -3616,6 +3740,7 @@ function isShadowedIdentifier(node, scopeRoot) {
   if (isFunctionLike(scopeRoot) && functionVarDeclaresName(scopeRoot, node.text)) return true
   for (let current = node.parent; current; current = current.parent) {
     if (current === scopeRoot) break
+    if (ts.isFunctionExpression(current) && current.name?.text === node.text) return true
     if (ts.isBlock(current) && current.statements.some(statement => statementDeclaresName(statement, node.text))) return true
     if (ts.isCaseBlock(current) && current.clauses.some(clause => clause.statements.some(statement => statementDeclaresName(statement, node.text)))) return true
     if (ts.isCatchClause(current) && current.variableDeclaration && bindingNames(current.variableDeclaration.name).includes(node.text)) return true

package/package.json

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