@kudzujs/core 0.7.0 → 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.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).
+**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`:
 
@@ -146,7 +146,7 @@ Static trusted HTML can be rendered without a transform layer:
 
 The HTML is intentionally not sanitized. Use only trusted or previously sanitized build-time content. Reactive raw HTML, children on the same element, void elements, and keyed-list raw HTML are rejected.
 
-Every CSS file under `src` is copied to the same relative path under `dist/assets` and linked in deterministic order. Configured root-relative URLs receive `base`; absolute HTTP URLs are preserved. A source style entry reads CSS, optionally transforms it, writes its declared output, and links it without an `afterBuild` file pipeline. `publicDir` defaults to `public` and may point elsewhere. Global or page `metadata` may be an object or a function of `{ route, params, props }`, so route props can set document language and head resources before rendering:
+Every CSS file under `src` is emitted to the same relative path under `dist/assets` and linked in deterministic order. Relative side-effect CSS imports are erased after validation. Default `.module.css` imports become deterministic scoped class maps at build time, while default imports of `.avif`, `.gif`, `.ico`, `.jpeg`, `.jpg`, `.otf`, `.png`, `.svg`, `.ttf`, `.webp`, `.woff`, or `.woff2` become base-prefixed asset URL strings; the same files accept `?url`. Relative CSS `url(...)` references are rewritten to base-prefixed URLs, preserve query/hash suffixes, and copy the referenced bytes under their source-relative `dist/assets` path. Data, fragment, root-relative, protocol-relative, and absolute CSS URLs remain unchanged. Other import queries, import hashes, attributes, named/namespace asset imports, and CSS Module `composes` are rejected. Configured root-relative URLs receive `base`; absolute HTTP URLs are preserved. A source style entry reads CSS, optionally transforms it, writes its declared output, and links it without an `afterBuild` file pipeline. `publicDir` defaults to `public` and may point elsewhere. Global or page `metadata` may be an object or a function of `{ route, params, props }`, so route props can set document language and head resources before rendering:
 
 ```js
 export default {
@@ -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,54 @@
 # 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.
+
+### New in 0.7.1
+
+- Relative side-effect CSS imports are validated and erased before server module evaluation.
+- Default CSS Module imports compile to deterministic scoped class maps with no client runtime.
+- Relative image, SVG, and font imports compile to base-aware URL strings; supported assets also accept `?url`.
+- Relative CSS `url(...)` references are rewritten to base-aware emitted URLs, preserving query and hash suffixes.
+- Referenced asset bytes are copied under deterministic source-relative `dist/assets` paths.
+- Static assets and CSS Modules work inside specialized relative keyed-row components.
+- Declaration files under `src` remain available to TypeScript but are excluded from executable module compilation.
+- The migration fixture verifies a non-root base, byte-identical assets, scoped classes, browser interaction, and zero JavaScript on its static route.
+
+### Boundary
+
+CSS Module `composes`, arbitrary import queries, import hashes/attributes, and named or namespace asset bindings fail at build time with source locations. React, a VDOM, hydration, and a retained browser component tree remain absent.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.1
+```
+
 ## 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.

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

@@ -1,7 +1,7 @@
 import { createServer } from "node:http"
 import { createHash, randomUUID } from "node:crypto"
-import { cp, mkdir, readFile, readdir, rm, stat, watch, writeFile } from "node:fs/promises"
-import { dirname, extname, join, relative, resolve, sep } from "node:path"
+import { cp, mkdir, readFile, readdir, realpath, rm, stat, watch, writeFile } from "node:fs/promises"
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
 import { build as bundle, transform } from "esbuild"
 import ts from "typescript"
@@ -13,6 +13,7 @@ const sourceDirectory = join(root, "src")
 const pagesDirectory = join(sourceDirectory, "pages")
 const workDirectory = join(root, ".kudzu")
 const outputDirectory = join(root, "dist")
+const staticAssetExtensions = new Set([".avif", ".gif", ".ico", ".jpeg", ".jpg", ".otf", ".png", ".svg", ".ttf", ".webp", ".woff", ".woff2"])
 
 const devClient = (session, revision, schema) => `<script>(()=>{const show=event=>{let box=document.getElementById("__kudzu_error");if(!box){box=document.createElement("div");box.id="__kudzu_error";box.setAttribute("role","alert");box.setAttribute("aria-live","assertive");box.style.cssText="position:fixed;inset:0;z-index:2147483647;overflow:auto;padding:2rem;background:#200;color:#fff;font:16px/1.5 ui-monospace,monospace";const title=document.createElement("strong"),text=document.createElement("pre");title.textContent="Kudzu build error";text.style.whiteSpace="pre-wrap";box.append(title,text);document.body.append(box)}box.querySelector("pre").textContent=event.data};const schema=${inlineJson(schema)},route=location.pathname+location.search+location.hash,urls=[...document.querySelectorAll('script[type="module"][src]')].map(node=>node.src).filter(url=>/\\/assets\\/kudzu(?:-(?:binding|list|native))?\\.js$/.test(new URL(url).pathname));const devImport=import("/__kudzu_dev.js"),runtimeImports=Promise.allSettled(urls.map(url=>import(url)));const ready=(async()=>{const dev=await devImport,modules=await runtimeImports,runtime=modules.find(result=>result.status==="fulfilled"&&result.value.browserState instanceof Map&&typeof result.value.commitDom==="function")?.value;try{dev.restoreState(sessionStorage,route,runtime?.browserState,schema,runtime?.commitDom)}catch{}return{dev,runtime}})().catch(()=>({}));const events=new EventSource("/__kudzu_reload?session=${session}&revision=${revision}");let reloading=false;events.addEventListener("reload",async()=>{if(reloading)return;reloading=true;try{const{dev,runtime}=await ready;dev?.snapshotState(sessionStorage,route,runtime?.browserState,schema)}catch{}location.reload()});events.addEventListener("build-error",show)})()</script>`
 
@@ -39,18 +40,22 @@ export async function build({ quiet = false, minify = true } = {}) {
   await mkdir(outputDirectory, { recursive: true })
 
   const projectFiles = await walk(sourceDirectory)
-  const sourceFiles = projectFiles.filter(file => /\.(?:ts|tsx)$/.test(file)).sort()
+  const sourceFiles = projectFiles.filter(file => /\.(?:ts|tsx)$/.test(file) && !file.endsWith(".d.ts")).sort()
   const configuredStyleSources = new Set(configuredStyles.sources.map(style => style.source))
-  const cssFiles = projectFiles.filter(file => file.endsWith(".css") && !configuredStyleSources.has(file)).sort()
+  const discoveredCssFiles = projectFiles.filter(file => file.toLowerCase().endsWith(".css") && !configuredStyleSources.has(file)).sort()
   if (!sourceFiles.length) throw new Error("No TypeScript files found in src/")
   const sourceFileSet = new Set(sourceFiles)
   const sourceIndex = new Map(await Promise.all(sourceFiles.map(async file => [file, await readFile(file, "utf8")])))
+  const staticFiles = await safeStaticFiles(projectFiles)
+  const cssFiles = orderSourceStyles(discoveredCssFiles, sourceFiles, sourceIndex, staticFiles)
+  const importedAssets = new Set()
+  const { cssModules, cssOutputs } = await prepareSourceStyles(cssFiles, staticFiles, importedAssets, base)
 
   const handlerModules = []
   const workerReferences = []
   for (const file of sourceFiles) {
     if (file.endsWith(".worker.ts")) continue
-    const handlerModule = await compile(file, sourceFileSet, sourceIndex, base, workerReferences)
+    const handlerModule = await compile(file, sourceFileSet, sourceIndex, staticFiles, importedAssets, cssModules, base, workerReferences)
     if (handlerModule) handlerModules.push(handlerModule)
   }
 
@@ -387,7 +392,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   for (const file of clientModules) {
     const output = join(assetsDirectory, clientModulePath(file))
     await mkdir(resolve(output, ".."), { recursive: true })
-    await writeJavaScript(output, await compileClientModule(file, sourceFileSet), minify)
+    await writeJavaScript(output, await compileClientModule(file, sourceFileSet, staticFiles, importedAssets, cssModules, base), minify)
   }
   if (clientModules.length) {
     await bundle({
@@ -409,10 +414,20 @@ export async function build({ quiet = false, minify = true } = {}) {
   }
   const sortedRewrites = rewrites.sort((left, right) => runtimeSpecificity(right) - runtimeSpecificity(left) || left.pattern.localeCompare(right.pattern))
   await writeFile(join(workDirectory, "kudzu-plan.json"), JSON.stringify({ routes: plans, rewrites: sortedRewrites }, null, 2))
+  for (const file of new Set([...cssFiles, ...importedAssets])) {
+    const collision = join(publicDirectory, "assets", relative(sourceDirectory, file))
+    if (await exists(collision)) throw new Error(`${relative(root, collision)} collides with emitted source asset ${relative(root, file)}`)
+  }
   for (const file of cssFiles) {
     const output = join(assetsDirectory, relative(sourceDirectory, file))
     await mkdir(dirname(output), { recursive: true })
-    await cp(file, output)
+    await writeFile(output, cssOutputs.get(file))
+  }
+  for (const file of [...importedAssets].sort()) {
+    if (cssOutputs.has(file)) continue
+    const output = join(assetsDirectory, relative(sourceDirectory, file))
+    await mkdir(dirname(output), { recursive: true })
+    await writeFile(output, await readFile(file))
   }
   for (const style of configuredStyles.sources) {
     let css = await readFile(style.source, "utf8")
@@ -1670,7 +1685,7 @@ function escapeAttribute(value) {
   return escapeHtml(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;")
 }
 
-async function compile(file, sourceFiles, sourceIndex, base, workerReferences) {
+async function compile(file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base, workerReferences) {
   const source = sourceIndex.get(file)
   const nativeHandlers = []
   const effectHandlers = []
@@ -1686,7 +1701,7 @@ async function compile(file, sourceFiles, sourceIndex, base, workerReferences) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, clientImports, workerReferences)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, staticFiles, importedAssets, cssModules, base, clientImports, workerReferences)] },
     reportDiagnostics: true
   })
 
@@ -1729,10 +1744,133 @@ function hasReactModuleReference(source, file) {
   return found
 }
 
-function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports, workerReferences) {
+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)
@@ -1742,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)
       }
@@ -1901,10 +2040,23 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       usesRowState ||= specialization.rowStates.length > 0
       usesRowRef ||= specialization.rowRefs.length > 0
     }
-    const mergeSpecializedImports = (root, componentSource, call) => {
+    const mergeSpecializedImports = (root, componentSource, call, effects = []) => {
       const componentImports = clientImportBindings(componentSource, componentSource.fileName, sourceFiles)
       for (const name of runtimeImportNames(componentSource, false)) if (referenceIdentifiers(root, name).length) fail(call, "Imported specialized component handlers may only use relative TypeScript runtime imports")
       const substitutions = new Map()
+      for (const statement of componentSource.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !isStaticImport(statement.moduleSpecifier.text)) continue
+        const entry = staticImportEntry(statement, componentSource, componentSource.fileName, staticFiles, importedAssets, cssModules, base, factory)
+        if (!entry?.name) continue
+        if (referenceIdentifiers(root, entry.name).length) substitutions.set(entry.name, entry.value)
+        for (const effect of effects) {
+          if (effect.source.getSourceFile() !== componentSource) continue
+          if (!referenceIdentifiers(effect.call, entry.name).length) continue
+          ts.setParentRecursive(effect.call, false)
+          effect.call = substituteClone(effect.call, new Map([[entry.name, entry.value]]), factory, context)
+          synthesizeTree(effect.call)
+        }
+      }
       for (const [name, entry] of componentImports) {
         const references = referenceIdentifiers(root, name)
         if (!references.length) continue
@@ -1939,7 +2091,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         for (const nestedCall of nestedCalls) {
           const nested = specializeComponentCall(nestedCall, nestedComponent, sourceFile, factory, context, fail, "Reducer-callback")
           if (nested.effects.length) fail(nestedCall, "Reducer-callback components cannot declare effects")
-          nested.root = mergeSpecializedImports(nested.root, nestedComponent.getSourceFile(), nestedCall)
+          nested.root = mergeSpecializedImports(nested.root, nestedComponent.getSourceFile(), nestedCall, nested.effects)
           synthesizeTree(nested.root)
           replacements.set(nestedCall, nested.root)
           count++
@@ -2022,7 +2174,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         const specialization = specializeComponentCall(call, component, sourceFile, factory, context, fail, "Reducer-dispatch")
         registerRowHooks(call, specialization)
         specialization.root = expandReducerCallbacks(specialization.root, componentSource, call)
-        specialization.root = mergeSpecializedImports(specialization.root, componentSource, call)
+        specialization.root = mergeSpecializedImports(specialization.root, componentSource, call, specialization.effects)
         synthesizeTree(specialization.root)
         componentSpecializations.set(call, specialization)
         reducerComponentCalls.add(call)
@@ -2119,7 +2271,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           const specialization = specializeComponentCall(node, component, sourceFile, factory, context, fail, "Keyed list", true)
           registerRowHooks(node, specialization)
           specialization.root = expandKeyedComponents(specialization.root, component.getSourceFile(), [...trail, component], specialization)
-          if (imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, component.getSourceFile(), node))
+          if (imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, component.getSourceFile(), node, specialization.effects))
           expandedRowSpecializations.set(specialization.root, specialization)
           if (currentAggregate) {
             currentAggregate.effects.push(...specialization.effects)
@@ -2164,7 +2316,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       const specialization = componentSpecializations.get(originalParts.root) ?? { root: originalParts.root, calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [] }
       const componentSource = specialization.componentSource ?? sourceFile
       specialization.root = expandKeyedComponents(specialization.root, componentSource, specialization.component ? [specialization.component] : [], specialization)
-      if (specialization.imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, componentSource, originalParts.root))
+      if (specialization.imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, componentSource, originalParts.root, specialization.effects))
       if (specialization.root !== originalParts.root) componentSpecializations.set(originalParts.root, specialization)
       const root = specialization.root
       let callback = root === originalParts.root ? originalParts.callback : factory.updateArrowFunction(
@@ -2228,6 +2380,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       }
 
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
+        if (isStaticImport(node.moduleSpecifier.text)) return staticImportEntry(node, sourceFile, file, staticFiles, importedAssets, cssModules, base, factory)?.replacement
         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)
       }
@@ -2757,7 +2910,7 @@ function jsxCallHasReducerCallbackProp(call, reducers) {
 function runtimeImportNames(sourceFile, relative) {
   const names = new Set()
   for (const statement of sourceFile.statements) {
-    if (!ts.isImportDeclaration(statement) || !statement.importClause || statement.importClause.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text.startsWith(".") !== relative) continue
+    if (!ts.isImportDeclaration(statement) || !statement.importClause || statement.importClause.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text.startsWith(".") !== relative || isStaticImport(statement.moduleSpecifier.text)) continue
     const clause = statement.importClause
     if (clause.name) names.add(clause.name.text)
     if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) names.add(clause.namedBindings.name.text)
@@ -3587,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
@@ -3662,7 +3816,7 @@ function reducersForNode(node, reducersByFunction) {
 function clientImportBindings(sourceFile, file, sourceFiles) {
   const bindings = new Map()
   for (const node of sourceFile.statements) {
-    if (!ts.isImportDeclaration(node) || !node.importClause || node.importClause.isTypeOnly || !ts.isStringLiteral(node.moduleSpecifier) || !node.moduleSpecifier.text.startsWith(".")) continue
+    if (!ts.isImportDeclaration(node) || !node.importClause || node.importClause.isTypeOnly || !ts.isStringLiteral(node.moduleSpecifier) || !node.moduleSpecifier.text.startsWith(".") || isStaticImport(node.moduleSpecifier.text)) continue
     let target
     try {
       target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
@@ -3857,6 +4011,7 @@ async function collectClientModules(entries, sourceFiles) {
     for (const node of sourceFile.statements) {
       if ((!ts.isImportDeclaration(node) && !ts.isExportDeclaration(node)) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier) || !runtimeModuleReference(node)) continue
       if (!node.moduleSpecifier.text.startsWith(".")) throw new Error(`${relative(root, file)} Imported client helpers may only use relative runtime imports`)
+      if (isStaticImport(node.moduleSpecifier.text)) continue
       queue.push(resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles))
     }
   }
@@ -3869,12 +4024,13 @@ async function collectClientModules(entries, sourceFiles) {
   return [...modules].sort()
 }
 
-async function compileClientModule(file, sourceFiles) {
+async function compileClientModule(file, sourceFiles, staticFiles, importedAssets, cssModules, base) {
   const source = await readFile(file, "utf8")
   const transformer = context => sourceFile => {
     const factory = context.factory
     const visitor = node => {
       if (ts.isImportDeclaration(node) && runtimeModuleReference(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
+        if (isStaticImport(node.moduleSpecifier.text)) return staticImportEntry(node, sourceFile, file, staticFiles, importedAssets, cssModules, base, factory)?.replacement
         const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
         return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(relativeModulePath(clientModulePath(file), clientModulePath(target))), node.attributes)
       }
@@ -3909,6 +4065,225 @@ function resolveSourceImport(importer, specifier, sourceFiles) {
   return matches[0]
 }
 
+function staticImportExtension(specifier) {
+  return extname(specifier.split(/[?#]/, 1)[0]).toLowerCase()
+}
+
+function isStaticImport(specifier) {
+  const extension = staticImportExtension(specifier)
+  return extension === ".css" || staticAssetExtensions.has(extension)
+}
+
+function resolveStaticImport(importer, specifier, staticFiles) {
+  const target = resolve(dirname(importer), specifier.split(/[?#]/, 1)[0])
+  if (!staticFiles.has(target)) throw new Error(`${relative(root, importer)} Relative asset import ${JSON.stringify(specifier)} must resolve to an existing regular file under src/`)
+  return target
+}
+
+async function safeStaticFiles(files) {
+  const sourceRoot = await realpath(sourceDirectory)
+  const entries = await Promise.all(files.map(async file => {
+    try {
+      const target = await realpath(file)
+      const path = relative(sourceRoot, target)
+      if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path) || !(await stat(target)).isFile()) return undefined
+      return file
+    } catch {
+      return undefined
+    }
+  }))
+  return new Set(entries.filter(Boolean))
+}
+
+function orderSourceStyles(cssFiles, sourceFiles, sourceIndex, staticFiles) {
+  const ordered = []
+  const seenStyles = new Set()
+  const seenSources = new Set()
+  const sourceSet = new Set(sourceFiles)
+  const visit = file => {
+    if (seenSources.has(file)) return
+    seenSources.add(file)
+    const sourceFile = parseSourceFile(file, sourceIndex.get(file))
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.moduleSpecifier.text.startsWith(".")) continue
+      const specifier = statement.moduleSpecifier.text
+      if (staticImportExtension(specifier) === ".css") {
+        let target
+        try { target = resolveStaticImport(file, specifier, staticFiles) } catch { continue }
+        if (!seenStyles.has(target)) {
+          seenStyles.add(target)
+          ordered.push(target)
+        }
+        continue
+      }
+      if (isStaticImport(specifier)) continue
+      try { visit(resolveSourceImport(file, specifier, sourceSet)) } catch {}
+    }
+  }
+  for (const file of sourceFiles.filter(file => file.startsWith(`${pagesDirectory}${sep}`) && file.endsWith(".tsx"))) visit(file)
+  for (const file of sourceFiles) visit(file)
+  return [...ordered, ...cssFiles.filter(file => !seenStyles.has(file))]
+}
+
+async function prepareSourceStyles(cssFiles, staticFiles, importedAssets, base) {
+  const cssModules = new Map()
+  const cssOutputs = new Map()
+  for (const file of cssFiles) {
+    let css = rewriteCssUrls(await readFile(file, "utf8"), file, staticFiles, importedAssets, base)
+    if (file.toLowerCase().endsWith(".module.css")) {
+      if (/\bcomposes\s*:/i.test(maskCssCommentsAndStrings(css))) throw new Error(`${relative(root, file)} CSS Modules composes is not supported`)
+      const prefix = `k${createHash("sha256").update(relative(sourceDirectory, file).replaceAll(sep, "/")).digest("hex").slice(0, 8)}`
+      css = (await transform(css, { loader: "local-css", sourcefile: `${prefix}.css`, target: "es2022" })).code
+      const classes = {}
+      for (const match of css.matchAll(new RegExp(`\\.${prefix}_([_a-zA-Z][_a-zA-Z0-9-]*)`, "g"))) classes[match[1]] = match[0].slice(1)
+      cssModules.set(file, classes)
+    }
+    cssOutputs.set(file, css)
+  }
+  return { cssModules, cssOutputs }
+}
+
+function rewriteCssUrls(css, file, staticFiles, importedAssets, base) {
+  let output = ""
+  let cursor = 0
+  let index = 0
+  while (index < css.length) {
+    if (css.startsWith("/*", index)) {
+      index = css.indexOf("*/", index + 2)
+      index = index === -1 ? css.length : index + 2
+      continue
+    }
+    if (css[index] === '"' || css[index] === "'") {
+      index = cssStringEnd(css, index)
+      continue
+    }
+    if (css.slice(index, index + 3).toLowerCase() !== "url" || /[-_a-z\d]/i.test(css[index - 1] ?? "")) {
+      index++
+      continue
+    }
+    let open = index + 3
+    while (/\s/.test(css[open] ?? "")) open++
+    if (css[open] !== "(") {
+      index++
+      continue
+    }
+    let start = open + 1
+    while (/\s/.test(css[start] ?? "")) start++
+    const quote = css[start] === '"' || css[start] === "'" ? css[start] : ""
+    const valueStart = quote ? start + 1 : start
+    let end = valueStart
+    if (quote) {
+      end = cssStringEnd(css, start) - 1
+      if (css[end] !== quote) {
+        index = open + 1
+        continue
+      }
+    } else {
+      while (end < css.length && css[end] !== ")") end += css[end] === "\\" ? 2 : 1
+    }
+    let close = quote ? end + 1 : end
+    while (/\s/.test(css[close] ?? "")) close++
+    if (css[close] !== ")") {
+      index = open + 1
+      continue
+    }
+    const value = css.slice(valueStart, end).trim()
+    const replacement = rewriteCssUrl(value, quote, file, staticFiles, importedAssets, base)
+    output += css.slice(cursor, index) + (replacement ?? css.slice(index, close + 1))
+    cursor = close + 1
+    index = close + 1
+  }
+  return output + css.slice(cursor)
+}
+
+function rewriteCssUrl(value, quote, file, staticFiles, importedAssets, base) {
+  if (!value || value.startsWith("/") || value.startsWith("#") || value.startsWith("//") || /^[a-z][a-z\d+.-]*:/i.test(value)) return undefined
+  const split = value.search(/[?#]/)
+  const pathname = split === -1 ? value : value.slice(0, split)
+  const suffix = split === -1 ? "" : value.slice(split)
+  const target = resolve(dirname(file), pathname)
+  if (!staticFiles.has(target)) throw new Error(`${relative(root, file)} CSS URL ${JSON.stringify(value)} must resolve to an existing regular file under src/`)
+  importedAssets.add(target)
+  const url = assetPath(base, `assets/${relative(sourceDirectory, target).replaceAll(sep, "/")}`)
+  return `url(${quote || '"'}${url}${suffix}${quote || '"'})`
+}
+
+function cssStringEnd(css, start) {
+  const quote = css[start]
+  let index = start + 1
+  while (index < css.length) {
+    if (css[index] === "\\") index += 2
+    else if (css[index++] === quote) break
+    else if (css[index - 1] === "\n") break
+  }
+  return index
+}
+
+function maskCssCommentsAndStrings(css) {
+  const masked = [...css]
+  let index = 0
+  while (index < css.length) {
+    let end
+    if (css.startsWith("/*", index)) {
+      const close = css.indexOf("*/", index + 2)
+      end = close === -1 ? css.length : close + 2
+    } else if (css[index] === '"' || css[index] === "'") {
+      end = cssStringEnd(css, index)
+    } else {
+      index++
+      continue
+    }
+    for (; index < end; index++) if (masked[index] !== "\n") masked[index] = " "
+  }
+  return masked.join("")
+}
+
+function staticImportEntry(node, sourceFile, file, staticFiles, importedAssets, cssModules, base, factory) {
+  const specifier = node.moduleSpecifier.text
+  if (specifier.includes("\\") || specifier.includes("#")) throw sourceNodeError(node.moduleSpecifier, sourceFile, "Static asset imports require forward-slash paths without hash suffixes")
+  const queryIndex = specifier.indexOf("?")
+  const query = queryIndex === -1 ? "" : specifier.slice(queryIndex + 1)
+  if (query && query !== "url") throw sourceNodeError(node.moduleSpecifier, sourceFile, "Static asset imports support only the ?url query")
+  let target
+  try {
+    target = resolveStaticImport(file, specifier, staticFiles)
+  } catch (error) {
+    throw sourceNodeError(node.moduleSpecifier, sourceFile, error.message)
+  }
+  if (node.attributes) throw sourceNodeError(node.attributes, sourceFile, "Static asset import attributes are not supported")
+  const extension = staticImportExtension(specifier)
+  if (query === "url") {
+    if (!node.importClause?.name || node.importClause.isTypeOnly || node.importClause.namedBindings) throw sourceNodeError(node, sourceFile, "Static assets require one default import")
+    if (extension !== ".css") importedAssets.add(target)
+    const value = factory.createStringLiteral(assetPath(base, `assets/${relative(sourceDirectory, target).replaceAll(sep, "/")}`))
+    return staticImportReplacement(node.importClause.name.text, value, factory)
+  }
+  if (extension === ".css") {
+    const classes = cssModules.get(target)
+    if (!node.importClause) return undefined
+    if (!classes || !node.importClause.name || node.importClause.isTypeOnly || node.importClause.namedBindings) {
+      const message = classes ? "CSS Modules require one default import" : "CSS imports must be side-effect imports"
+      throw sourceNodeError(node.importClause, sourceFile, message)
+    }
+    const value = factory.createObjectLiteralExpression(Object.entries(classes).sort(([left], [right]) => left.localeCompare(right)).map(([name, scoped]) => factory.createPropertyAssignment(factory.createStringLiteral(name), factory.createStringLiteral(scoped))))
+    return staticImportReplacement(node.importClause.name.text, value, factory)
+  }
+  if (!node.importClause?.name || node.importClause.isTypeOnly || node.importClause.namedBindings) throw sourceNodeError(node, sourceFile, "Static assets require one default import")
+  importedAssets.add(target)
+  const value = factory.createStringLiteral(assetPath(base, `assets/${relative(sourceDirectory, target).replaceAll(sep, "/")}`))
+  return staticImportReplacement(node.importClause.name.text, value, factory)
+}
+
+function staticImportReplacement(name, value, factory) {
+  return {
+    name,
+    value,
+    replacement: factory.createVariableStatement(undefined, factory.createVariableDeclarationList([
+      factory.createVariableDeclaration(name, undefined, undefined, value)
+    ], ts.NodeFlags.Const))
+  }
+}
+
 function runtimeModuleReference(node) {
   if (ts.isExportDeclaration(node)) return !node.isTypeOnly && (!node.exportClause || !ts.isNamedExports(node.exportClause) || node.exportClause.elements.some(entry => !entry.isTypeOnly))
   const clause = node.importClause

package/package.json

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