@kudzujs/core 0.6.28 → 0.7.0

package/README.md

@@ -8,7 +8,9 @@ HTML-first TSX framework with synchronous state semantics and no virtual DOM.
 
 Kudzu is designed so ordinary common React-shaped TSX can migrate with minimal source restructuring. It keeps familiar function components, props, children, collection rendering, conditions, event handlers, `useState`, reduced `useReducer`, refs, and effects, preferring compiler specialization over imperative DOM rewrites. This is a general migration model, not compatibility for one application. Static components compile to HTML; interactions compile to direct DOM capabilities and external ESM only where used.
 
-> Experimental `0.6.x`: the compiler API and supported TSX surface may change.
+> Experimental `0.7.x`: the compiler API and supported TSX surface may change.
+
+**0.7.0:** React-source migration preview. Supported conventional `react` imports now compile to static HTML and capability-specific ESM without React, a VDOM, or hydration. See [release notes](./RELEASES.md#070---react-source-migration-preview).
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -58,6 +60,22 @@ Configure TypeScript:
 
 Make sure application TSX files are included by this `tsconfig.json`. Files outside its `include` may fall into an editor-inferred React project and incorrectly report a missing `react/jsx-runtime` or React event-type errors.
 
+Existing React migration source may retain conventional imports while components are moved under `src`:
+
+```tsx
+import React, { useState } from "react"
+
+export default function Header() {
+  const [open, setOpen] = useState(false)
+  return <React.Fragment>
+    <button onClick={() => setOpen(!open)}>{open ? "Close" : "Menu"}</button>
+    {open && <nav>Navigation</nav>}
+  </React.Fragment>
+}
+```
+
+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.
+
 Create `src/pages/index.tsx`:
 
 ```tsx

package/RELEASES.md

@@ -0,0 +1,44 @@
+# Kudzu Releases
+
+## 0.7.0 - React-source migration preview
+
+Kudzu 0.7.0 begins the migration track for ordinary React-shaped landing pages. Existing source may retain conventional supported imports from `react`; Kudzu rewrites those imports to compile-time APIs, pre-renders complete HTML, and emits only the route capabilities that are actually used. React, a virtual DOM, hydration, and a browser component tree are never emitted or executed.
+
+```tsx
+import React, { useState } from "react"
+
+export default function Header() {
+  const [open, setOpen] = useState(false)
+
+  return <React.Fragment>
+    <button onClick={() => setOpen(!open)}>{open ? "Close" : "Menu"}</button>
+    {open && <nav>Navigation</nav>}
+  </React.Fragment>
+}
+```
+
+### New in 0.7.0
+
+- Conventional unaliased named imports of supported hooks from `react` compile through Kudzu without loading React.
+- Default, namespace, and named `Fragment` imports are accepted for migration source.
+- Relative function components, props, children, conditions, attributes, text, and event handlers keep their familiar TSX shape.
+- Static routes using the accepted React import forms still ship zero JavaScript.
+- Interactive routes ship direct DOM capabilities only; the landing-page acceptance fixture adds state, text, attribute, condition, and menu-handler capabilities.
+- Emitted modules are checked for surviving runtime React references, and side-effect React imports fail with a source location.
+- Keyed collections now support analyzable `filter`, direct-property `flatMap`, `Array.from`, positional keys, recursively deep sibling child maps, nested conditions, latest-item handlers, multiple serializable row states, effects, and `null` object refs.
+
+### Current boundary
+
+This is source migration support, not a React compatibility runtime. Aliased hooks, member hook calls such as `React.useState`, `memo`, `useMemo`, `useCallback`, React classes, React Router, Next-specific components, React UI packages, side-effect imports, and dynamic React imports remain unsupported. Migrate a real route, reduce the first unsupported pattern to a fixture, and extend the compiler one proven blocker at a time.
+
+### Measured fixture
+
+The two-route landing fixture retains React imports across relative components. Its static route has no script, while its interactive mobile-menu route emits 10,245 B raw / 5,030 B aggregate gzip JavaScript across seven capability files. Seven clean builds after one warm-up measured a 310.0 ms median on the development machine described in `MIGRATION_ROADMAP.md`.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.0
+```
+
+New Kudzu source should continue importing APIs from `@kudzujs/core`. Retaining `react` imports is intended for migration input where minimizing source edits matters.

package/framework/README.md

@@ -2,6 +2,8 @@
 
 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.
+
 - `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.
 - `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.

package/framework/build.mjs

@@ -1694,6 +1694,7 @@ async function compile(file, sourceFiles, sourceIndex, base, workerReferences) {
   if (errors.length) {
     throw new Error(errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
   }
+  if (hasReactModuleReference(result.outputText, file)) throw new Error(`${relative(root, file)} Runtime React module references are not supported`)
 
   const output = compiledPath(file)
   await mkdir(resolve(output, ".."), { recursive: true })
@@ -1716,6 +1717,18 @@ async function compile(file, sourceFiles, sourceIndex, base, workerReferences) {
   return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0, hasEffects: effectHandlers.length > 0, clientImports: [...clientImports] }
 }
 
+function hasReactModuleReference(source, file) {
+  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS)
+  let found = false
+  const visit = node => {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react") found = true
+    if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require") && ts.isStringLiteral(node.arguments[0]) && node.arguments[0].text === "react") found = true
+    if (!found) ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return found
+}
+
 function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports, workerReferences) {
   return context => sourceFile => {
     const factory = context.factory
@@ -1724,7 +1737,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     ts.setParentRecursive(sourceFile, false)
     rejectOrdinaryWorkerImports(sourceFile, file, sourceFiles)
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
-    const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && statement.moduleSpecifier.text === "@kudzujs/core" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
+    const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
     const importedSources = new Map()
     const importedSource = target => {
       let imported = importedSources.get(target)
@@ -2208,6 +2221,12 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         fail(node, "Stylesheets must be placed under src/ or declared in kudzu.config styles so Kudzu can emit them in <head>")
       }
 
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react") {
+        if (!node.importClause) fail(node, "Side-effect React imports are not supported because Kudzu does not load the React runtime")
+        if (node.importClause.isTypeOnly) return node
+        return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral("@kudzujs/core"), node.attributes)
+      }
+
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
         const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
         return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(relativeModulePath(compiledPath(file), compiledPath(target))), node.attributes)

package/framework/core.d.ts

@@ -3,6 +3,7 @@ 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 const Fragment: unique symbol
 
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
 export function useReducer<State, Action>(reducer: Reducer<State, Action>, initialValue: State): [State, Dispatch<Action>]
@@ -22,6 +23,9 @@ export interface Context<T> {
 export function createContext<T>(defaultValue: T): Context<T>
 export function useContext<T>(context: Context<T>): T
 
+declare const React: { Fragment: typeof Fragment }
+export default React
+
 export function behavior(commands: Array<["add" | "set" | "log", unknown, unknown]>): unknown
 export function nativeBehavior(module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
 export function binding(value: unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown

package/framework/core.mjs

@@ -20,6 +20,7 @@ const contextMarker = Symbol("kudzu.context")
 const contextProviderMarker = Symbol("kudzu.contextProvider")
 const routeScopeMarker = Symbol("kudzu.routeScope")
 const noSelectValue = Symbol("kudzu.no-select-value")
+export const Fragment = Symbol.for("kudzu.fragment")
 const svgAttributeAliases = {
   clipRule: "clip-rule",
   colorInterpolation: "color-interpolation",
@@ -170,6 +171,8 @@ export function useContext(context) {
   return context.defaultValue
 }
 
+export default { Fragment }
+
 export function behavior(commands) {
   return {
     [behaviorMarker]: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.6.28",
+  "version": "0.7.0",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "framework/",
     "GOAL_A.md",
     "GOAL_B.md",
+    "RELEASES.md",
     "README.md",
     "LICENSE"
   ],