@kudzujs/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kudzujs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kudzujs/kudzu/main/public/icon-128.png" width="96" alt="Kudzu logo">
+</p>
+
+# Kudzu
+
+HTML-first TSX framework with synchronous state semantics and no virtual DOM.
+
+Brand assets, favicons, manifest icons, and the 1200×630 social preview live in [`public/`](./public).
+
+Kudzu keeps the familiar function-component, props, children, event-handler, and `useState` shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers compile to external ESM.
+
+> Experimental `0.1.x`: the compiler API and supported TSX surface may change.
+
+## Install
+
+```bash
+npm install @kudzujs/core
+```
+
+Add scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "kudzu dev",
+    "build": "kudzu build"
+  }
+}
+```
+
+Configure TypeScript:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "@kudzujs/core",
+    "strict": true
+  }
+}
+```
+
+Create `src/pages/index.tsx`:
+
+```tsx
+import { useState } from "@kudzujs/core"
+
+export default function HomePage() {
+  const [count, setCount] = useState(0)
+
+  function increaseTwice() {
+    setCount(count + 1)
+    setCount(count + 1)
+  }
+
+  return <button onClick={increaseTwice}>Count: {count}</button>
+}
+```
+
+```bash
+npm run dev
+```
+
+Pages live in `src/pages`; `index.tsx` maps to `/`. Production output is written to `dist/`.
+
+## State Semantics
+
+Kudzu intentionally differs from React's state snapshot behavior:
+
+```tsx
+function increaseTwice() {
+  setCount(count + 1)
+  setCount(count + 1)
+}
+```
+
+- A setter updates logical state immediately.
+- The next statement reads the latest logical state.
+- Setters execute in source order.
+- DOM writes batch at synchronous-turn boundaries.
+- The same input produces the same execution plan.
+
+The handler above increments by two and patches its bound DOM once. Inspect the generated plan at `.kudzu/kudzu-plan.json`.
+
+## Normal JavaScript
+
+Command-only setters use the smallest optimized path. Conditions, local variables, browser globals, events, and `async`/`await` compile to external ESM without `eval`, `new Function`, or inline executable code.
+
+```tsx
+async function load() {
+  setStatus("loading")
+
+  try {
+    const response = await fetch("/api/status")
+    const result = await response.json()
+    setStatus(result.status)
+  } catch {
+    setStatus("failed")
+  }
+}
+```
+
+Primitive values, arrays, plain objects, and destructured props can be captured by client handlers. Functions, symbols, bigints, cycles, class instances, and imported helper functions are not yet supported as captures.
+
+## Rendering
+
+```text
+TSX
+├─ static component      → HTML
+├─ ordered state setter  → behavior command
+└─ normal JS handler     → route handler ESM
+```
+
+- Static pages ship no client JavaScript.
+- Interactive pages receive only the runtime capabilities they use.
+- Components are authoring units; no component tree is retained in the browser.
+- There is no VDOM, hydration pass, router, or client application runtime.
+
+Example Nginx configuration:
+
+```nginx
+location / {
+    try_files $uri $uri/ $uri/index.html =404;
+}
+```
+
+## Current Scope
+
+Supported:
+
+- Function components, props, children, fragments, and TSX
+- File-based static routes
+- Build-time async components
+- Primitive `useState` bindings
+- Synchronous and async event handlers
+- Serializable component-local captures
+- Direct text DOM patches
+
+Not implemented yet:
+
+- Reactive attributes, classes, and controlled inputs
+- Conditional DOM patches and keyed lists
+- Server actions and request-time SSR
+- Imported client helpers and React package islands
+- HMR and framework DevTools
+
+## Benchmarks
+
+Measurements below were produced on the same machine from production builds. They compare build artifacts, not ecosystem maturity or full application performance.
+
+### Interactive Counter
+
+Same counter with initial value `7` and increment/decrement buttons:
+
+| Framework | Initial content | Initial JS gzip | Total output | Clean build |
+|---|---:|---:|---:|---:|
+| Kudzu | Yes | **581 B** | 1.7 KB | **371 ms** |
+| Astro | Yes | 158 B | **365 B** | 953 ms |
+| Svelte CSR | No | 10.5 KB | 26.9 KB | 910 ms |
+| Qwik CSR | No | 20.6 KB | 57.8 KB | 633 ms |
+| React CSR | No | 59.2 KB | 189.0 KB | 1010 ms |
+| Next.js | Yes | 182.1 KB | 652.2 KB | 3074 ms |
+
+Astro produces the smallest hand-authored counter. Kudzu's advantage in this fixture is React-shaped state code with a sub-1 KB runtime, not the smallest possible JavaScript.
+
+### Static Journal Page
+
+Same content and CSS across every fixture; build is the median of three clean runs:
+
+| Framework | Initial content | Initial JS gzip | Total output | Clean build |
+|---|---:|---:|---:|---:|
+| Kudzu | Yes | **0 B** | 3.1 KB | **383 ms** |
+| Astro | Yes | **0 B** | **3.0 KB** | 1022 ms |
+| Svelte CSR | No | 10.2 KB | 27.2 KB | 907 ms |
+| Qwik CSR | No | 20.2 KB | 59.6 KB | 619 ms |
+| Vue CSR | No | 24.2 KB | 62.3 KB | 719 ms |
+| React CSR | No | 59.8 KB | 192.3 KB | 1053 ms |
+| Next.js | Yes | 182.6 KB | 663.6 KB | 3054 ms |
+
+Benchmark snapshot collected on July 20, 2026 from equivalent production fixtures on the same machine. Qwik used a client entry and therefore did not exercise its SSR resumability advantage. Build times vary by hardware and filesystem cache.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+```
+
+License: MIT

package/bin/kudzu.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { build, dev } from "../framework/build.mjs"
+
+const command = process.argv[2] ?? "dev"
+
+if (command === "build") {
+  await build()
+} else if (command === "dev") {
+  await dev()
+} else {
+  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev>`)
+  process.exitCode = 1
+}

package/framework/README.md

@@ -0,0 +1,12 @@
+# Framework Internals
+
+- `build.mjs`: TSX compilation, file routes, behavior extraction, static HTML output, and the development server.
+- `core.mjs`: server-side JSX rendering, state slots, behavior metadata, and serializable capture validation.
+- `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.
+- `runtime.js`: command-only browser runtime for direct state-to-text patches.
+- `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
+- `*.d.ts`: public TypeScript and JSX declarations.
+
+Static routes do not receive either browser runtime. Command-only routes receive `runtime.js`; native handlers add `native-runtime.js` and generated modules under `dist/assets/handlers/`.
+
+Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/build.mjs

@@ -0,0 +1,446 @@
+import { createServer } from "node:http"
+import { cp, mkdir, readFile, readdir, rm, stat, watch, writeFile } from "node:fs/promises"
+import { extname, join, relative, resolve, sep } from "node:path"
+import { pathToFileURL } from "node:url"
+import ts from "typescript"
+import { renderPage } from "./core.mjs"
+
+const root = process.cwd()
+const sourceDirectory = join(root, "src")
+const pagesDirectory = join(sourceDirectory, "pages")
+const workDirectory = join(root, ".kudzu")
+const outputDirectory = join(root, "dist")
+
+export async function build({ quiet = false } = {}) {
+  await rm(workDirectory, { recursive: true, force: true })
+  await rm(outputDirectory, { recursive: true, force: true })
+  await mkdir(workDirectory, { recursive: true })
+  await mkdir(outputDirectory, { recursive: true })
+
+  const sourceFiles = (await walk(sourceDirectory)).filter(file => /\.(?:ts|tsx)$/.test(file)).sort()
+  if (!sourceFiles.length) throw new Error("No TypeScript files found in src/")
+
+  const handlerModules = []
+  for (const file of sourceFiles) {
+    const handlerModule = await compile(file)
+    if (handlerModule) handlerModules.push(handlerModule)
+  }
+
+  const pageFiles = sourceFiles.filter(file => file.startsWith(`${pagesDirectory}${sep}`) && file.endsWith(".tsx"))
+  if (!pageFiles.length) throw new Error("No pages found in src/pages/")
+
+  let behaviorCount = 0
+  const plans = []
+  const hasStyles = await exists(join(sourceDirectory, "style.css"))
+
+  for (const pageFile of pageFiles) {
+    const compiledFile = compiledPath(pageFile)
+    const module = await import(`${pathToFileURL(compiledFile).href}?v=${Date.now()}`)
+    if (typeof module.default !== "function") throw new Error(`${relative(root, pageFile)} must export a default component`)
+
+    const result = await renderPage(module.default, {
+      ...(module.metadata ?? {}),
+      styles: hasStyles
+    })
+    const route = routeFromPage(pageFile)
+    const routeDirectory = join(outputDirectory, route)
+    await mkdir(routeDirectory, { recursive: true })
+    await writeFile(join(routeDirectory, "index.html"), result.html)
+    plans.push({ route: `/${route}`, ...result.plan })
+    if (result.hasBehaviors) behaviorCount++
+  }
+
+  const assetsDirectory = join(outputDirectory, "assets")
+  await mkdir(assetsDirectory, { recursive: true })
+  if (behaviorCount) await cp(new URL("./runtime.js", import.meta.url), join(assetsDirectory, "kudzu.js"))
+  if (handlerModules.length) {
+    const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8")).replace('"./runtime.js"', '"./kudzu.js"')
+    await writeFile(join(assetsDirectory, "kudzu-native.js"), nativeRuntime)
+  }
+  for (const handlerModule of handlerModules) {
+    const output = join(assetsDirectory, handlerModule.path)
+    await mkdir(resolve(output, ".."), { recursive: true })
+    await writeFile(output, handlerModule.code)
+  }
+  await writeFile(join(workDirectory, "kudzu-plan.json"), JSON.stringify({ routes: plans }, null, 2))
+  if (hasStyles) await cp(join(sourceDirectory, "style.css"), join(assetsDirectory, "style.css"))
+  if (await exists(join(root, "public"))) await cp(join(root, "public"), outputDirectory, { recursive: true })
+
+  if (!quiet) console.log(`Built ${pageFiles.length} page(s), ${behaviorCount} interactive page(s) into dist/`)
+}
+
+export async function dev() {
+  await build()
+
+  const server = createServer(async (request, response) => {
+    try {
+      const pathname = decodeURIComponent(new URL(request.url, "http://localhost").pathname)
+      const relativePath = pathname.replace(/^\/+/, "")
+      let file = resolve(outputDirectory, relativePath)
+      if (!file.startsWith(`${outputDirectory}${sep}`) && file !== outputDirectory) throw new Error("Invalid path")
+
+      if ((await exists(file)) && (await stat(file)).isDirectory()) file = join(file, "index.html")
+      if (!(await exists(file)) && !extname(file)) file = join(file, "index.html")
+      const content = await readFile(file)
+      response.writeHead(200, { "content-type": contentType(file) })
+      response.end(content)
+    } catch {
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" })
+      response.end("Not found")
+    }
+  })
+
+  server.listen(3000, () => console.log("Kudzu dev server: http://localhost:3000"))
+
+  let timer
+  const watcher = watch(sourceDirectory, { recursive: true })
+  for await (const event of watcher) {
+    clearTimeout(timer)
+    timer = setTimeout(async () => {
+      try {
+        await build({ quiet: true })
+        console.log(`Rebuilt after ${event.filename ?? "source change"}`)
+      } catch (error) {
+        console.error(error)
+      }
+    }, 80)
+  }
+}
+
+async function compile(file) {
+  const source = await readFile(file, "utf8")
+  const nativeHandlers = []
+  const handlerPath = `handlers/${relative(sourceDirectory, file).replaceAll(sep, "/").replace(/\.(?:ts|tsx)$/, ".js")}`
+  const result = ts.transpileModule(source, {
+    fileName: file,
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      jsx: ts.JsxEmit.ReactJSX,
+      jsxImportSource: "@kudzujs/core"
+    },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, `/assets/${handlerPath}`)] },
+    reportDiagnostics: true
+  })
+
+  const errors = result.diagnostics?.filter(diagnostic => diagnostic.category === ts.DiagnosticCategory.Error) ?? []
+  if (errors.length) {
+    throw new Error(errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
+  }
+
+  const output = compiledPath(file)
+  await mkdir(resolve(output, ".."), { recursive: true })
+  await writeFile(output, result.outputText)
+
+  if (!nativeHandlers.length) return undefined
+  const moduleSource = nativeHandlers.map(handler => printNativeHandler(handler)).join("\n")
+  const moduleResult = ts.transpileModule(moduleSource, {
+    compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext },
+    reportDiagnostics: true
+  })
+  const moduleErrors = moduleResult.diagnostics?.filter(diagnostic => diagnostic.category === ts.DiagnosticCategory.Error) ?? []
+  if (moduleErrors.length) throw new Error(moduleErrors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
+  return { path: handlerPath, code: moduleResult.outputText }
+}
+
+function createKudzuTransformer(nativeHandlers, handlerUrl) {
+  return context => sourceFile => {
+    const factory = context.factory
+    const setters = new Map()
+    const functions = new Map()
+    let usesBehavior = false
+
+    const collect = node => {
+      if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && 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)) {
+          setters.set(setterElement.name.text, stateElement.name.text)
+        }
+      }
+      if (ts.isFunctionDeclaration(node) && node.name) functions.set(node.name.text, node)
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+        functions.set(node.name.text, node.initializer)
+      }
+      ts.forEachChild(node, collect)
+    }
+    collect(sourceFile)
+
+    const visitor = node => {
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
+        return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(modulePath(node.moduleSpecifier.text)), node.attributes)
+      }
+
+      if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
+        return factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, factory.createStringLiteral(modulePath(node.moduleSpecifier.text)), node.attributes)
+      }
+
+      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) {
+        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, [
+          ...node.initializer.arguments,
+          factory.createStringLiteral(stateElement.name.text)
+        ])
+        return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, initializer)
+      }
+
+      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && /^on[A-Z]/.test(node.name.getText())) {
+        const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl)
+        if (event) {
+          usesBehavior = true
+          return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, event))
+        }
+        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
+        throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${node.name.getText()} must reference a function`)
+      }
+
+      return ts.visitEachChild(node, visitor, context)
+    }
+
+    const transformed = ts.visitNode(sourceFile, visitor)
+    if (!usesBehavior) return transformed
+
+    const behaviorImports = [factory.createImportSpecifier(false, factory.createIdentifier("behavior"), factory.createIdentifier("__kBehavior"))]
+    if (nativeHandlers.length) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("nativeBehavior"), factory.createIdentifier("__kNativeBehavior")))
+    const behaviorImport = factory.createImportDeclaration(
+      undefined,
+      factory.createImportClause(false, undefined, factory.createNamedImports(behaviorImports)),
+      factory.createStringLiteral("@kudzujs/core")
+    )
+    return factory.updateSourceFile(transformed, [behaviorImport, ...transformed.statements])
+  }
+}
+
+function compileEvent(expression, setters, functions, factory, nativeHandlers, handlerUrl) {
+  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)
+  if (optimized) return optimized
+
+  const captures = nativeCaptureNames(expression, setters)
+  const usedStates = nativeStateNames(expression, setters)
+  const exportName = `handler${nativeHandlers.length}`
+  nativeHandlers.push({ exportName, expression, captures, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))) })
+  const states = [...usedStates].map(name => factory.createArrayLiteralExpression([
+    factory.createStringLiteral(name),
+    factory.createIdentifier(name)
+  ]))
+  const scope = [...captures].map(name => factory.createArrayLiteralExpression([
+    factory.createStringLiteral(name),
+    factory.createIdentifier(name)
+  ]))
+  return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
+    factory.createStringLiteral(handlerUrl),
+    factory.createStringLiteral(exportName),
+    factory.createArrayLiteralExpression(states),
+    factory.createArrayLiteralExpression(scope)
+  ])
+}
+
+function nativeStateNames(expression, setters) {
+  const stateNames = new Set(setters.values())
+  const used = new Set()
+  const visit = node => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text)) used.add(setters.get(node.expression.text))
+    if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node)) used.add(node.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body)
+  return used
+}
+
+function compileOptimizedEvent(expression, setters, factory) {
+  const statements = ts.isBlock(expression.body) ? expression.body.statements : [factory.createExpressionStatement(expression.body)]
+  const commands = statements.map(statement => {
+    if (!ts.isExpressionStatement(statement)) return undefined
+    return compileEventCommand(statement.expression, setters, factory)
+  })
+  if (!commands.length || commands.some(command => !command)) return undefined
+
+  return factory.createCallExpression(factory.createIdentifier("__kBehavior"), undefined, [factory.createArrayLiteralExpression(commands)])
+}
+
+const nativeGlobals = new Set([
+  "Array", "ArrayBuffer", "BigInt", "Boolean", "Date", "Error", "Event", "FormData", "Infinity", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "atob", "btoa", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "location", "navigator", "parseFloat", "parseInt", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
+])
+
+function nativeCaptureNames(expression, setters) {
+  const local = new Set()
+  const collectDeclarations = node => {
+    if (ts.isVariableDeclaration(node)) for (const name of bindingNames(node.name)) local.add(name)
+    if (ts.isParameter(node)) for (const name of bindingNames(node.name)) local.add(name)
+    if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) local.add(node.name.text)
+    ts.forEachChild(node, collectDeclarations)
+  }
+  collectDeclarations(expression)
+
+  const stateNames = new Set(setters.values())
+  const captures = new Set()
+  const visit = node => {
+    if (ts.isTypeNode(node)) return
+    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !local.has(node.text) && !setters.has(node.text) && !stateNames.has(node.text) && !nativeGlobals.has(node.text)) {
+      captures.add(node.text)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body)
+  return captures
+}
+
+function bindingNames(name) {
+  if (ts.isIdentifier(name)) return [name.text]
+  return name.elements.flatMap(element => ts.isBindingElement(element) ? bindingNames(element.name) : [])
+}
+
+function isReferenceIdentifier(node) {
+  const parent = node.parent
+  if (!parent) return true
+  if ((ts.isPropertyAccessExpression(parent) && parent.name === node) ||
+      (ts.isPropertyAssignment(parent) && parent.name === node) ||
+      (ts.isMethodDeclaration(parent) && parent.name === node) ||
+      (ts.isVariableDeclaration(parent) && parent.name === node) ||
+      (ts.isParameter(parent) && parent.name === node) ||
+      (ts.isFunctionDeclaration(parent) && parent.name === node) ||
+      (ts.isBindingElement(parent) && parent.name === node) ||
+      ts.isImportSpecifier(parent) || ts.isImportClause(parent)) return false
+  return true
+}
+
+function printNativeHandler({ exportName, expression, captures, setters }) {
+  const factory = ts.factory
+  const stateNames = new Set(setters.values())
+  const transformer = context => root => {
+    const visitor = node => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text)) {
+        return factory.createCallExpression(
+          factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"),
+          undefined,
+          [factory.createStringLiteral(setters.get(node.expression.text)), ...node.arguments.map(argument => ts.visitNode(argument, visitor))]
+        )
+      }
+      if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node)) {
+        return factory.createCallExpression(
+          factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"),
+          undefined,
+          [factory.createStringLiteral(node.text)]
+        )
+      }
+      if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text)) {
+        return factory.createPropertyAssignment(node.name, scopeRead(factory, node.name.text))
+      }
+      if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node)) {
+        return scopeRead(factory, node.text)
+      }
+      return ts.visitEachChild(node, visitor, context)
+    }
+    return ts.visitNode(root, visitor)
+  }
+  const transformed = ts.transform(expression.body, [transformer])
+  try {
+    const body = ts.isBlock(expression.body)
+      ? transformed.transformed[0]
+      : factory.createBlock([factory.createReturnStatement(transformed.transformed[0])], true)
+    const modifiers = [factory.createModifier(ts.SyntaxKind.ExportKeyword)]
+    if (expression.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) modifiers.push(factory.createModifier(ts.SyntaxKind.AsyncKeyword))
+    const declaration = factory.createFunctionDeclaration(
+      modifiers,
+      expression.asteriskToken,
+      exportName,
+      undefined,
+      [factory.createParameterDeclaration(undefined, undefined, "__k"), ...expression.parameters],
+      undefined,
+      body
+    )
+    return ts.createPrinter().printNode(ts.EmitHint.Unspecified, declaration, expression.getSourceFile())
+  } finally {
+    transformed.dispose()
+  }
+}
+
+function scopeRead(factory, name) {
+  return factory.createCallExpression(
+    factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "scope"),
+    undefined,
+    [factory.createStringLiteral(name)]
+  )
+}
+
+function compileEventCommand(expression, setters, factory) {
+  if (ts.isCallExpression(expression) && ts.isPropertyAccessExpression(expression.expression) && ts.isIdentifier(expression.expression.expression) && expression.expression.expression.text === "console" && expression.expression.name.text === "log" && expression.arguments.length === 2 && ts.isStringLiteral(expression.arguments[0]) && ts.isIdentifier(expression.arguments[1]) && [...setters.values()].includes(expression.arguments[1].text)) {
+    return command(factory, "log", expression.arguments[1], expression.arguments[0])
+  }
+
+  if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression) || expression.arguments.length !== 1) return undefined
+  const stateName = setters.get(expression.expression.text)
+  if (!stateName) return undefined
+
+  const state = factory.createIdentifier(stateName)
+  const value = expression.arguments[0]
+  if (ts.isBinaryExpression(value) && ts.isIdentifier(value.left) && value.left.text === stateName && ts.isNumericLiteral(value.right)) {
+    if (value.operatorToken.kind !== ts.SyntaxKind.PlusToken && value.operatorToken.kind !== ts.SyntaxKind.MinusToken) return undefined
+    return command(factory, "add", state, numericExpression(factory, Number(value.right.text), value.operatorToken.kind === ts.SyntaxKind.MinusToken))
+  }
+  if (ts.isArrowFunction(value) && value.parameters.length === 1 && ts.isIdentifier(value.parameters[0].name) && ts.isBinaryExpression(value.body) && ts.isIdentifier(value.body.left) && value.body.left.text === value.parameters[0].name.text && ts.isNumericLiteral(value.body.right)) {
+    if (value.body.operatorToken.kind !== ts.SyntaxKind.PlusToken && value.body.operatorToken.kind !== ts.SyntaxKind.MinusToken) return undefined
+    return command(factory, "add", state, numericExpression(factory, Number(value.body.right.text), value.body.operatorToken.kind === ts.SyntaxKind.MinusToken))
+  }
+  if (isPrimitiveLiteral(value)) return command(factory, "set", state, value)
+  return undefined
+}
+
+function command(factory, operation, state, value) {
+  return factory.createArrayLiteralExpression([factory.createStringLiteral(operation), state, value])
+}
+
+function isPrimitiveLiteral(node) {
+  return ts.isStringLiteral(node) || ts.isNumericLiteral(node) || node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword
+}
+
+function numericExpression(factory, value, negative) {
+  const literal = factory.createNumericLiteral(value)
+  return negative ? factory.createPrefixUnaryExpression(ts.SyntaxKind.MinusToken, literal) : literal
+}
+
+function modulePath(value) {
+  if (/\.(?:ts|tsx|js|jsx)$/.test(value)) return value.replace(/\.(?:ts|tsx|js|jsx)$/, ".mjs")
+  return `${value}.mjs`
+}
+
+function compiledPath(file) {
+  return join(workDirectory, relative(sourceDirectory, file)).replace(/\.(?:ts|tsx)$/, ".mjs")
+}
+
+function routeFromPage(file) {
+  const page = relative(pagesDirectory, file).replace(/\\/g, "/").replace(/\.tsx$/, "")
+  return page === "index" ? "" : page.replace(/\/index$/, "")
+}
+
+async function walk(directory) {
+  const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))
+  const files = await Promise.all(entries.map(entry => {
+    const path = join(directory, entry.name)
+    return entry.isDirectory() ? walk(path) : path
+  }))
+  return files.flat()
+}
+
+async function exists(path) {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function contentType(file) {
+  return {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml"
+  }[extname(file)] ?? "application/octet-stream"
+}

package/framework/core.d.ts

@@ -0,0 +1,39 @@
+export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
+
+export function useState<T>(initialValue: T): [T, StateSetter<T>]
+
+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 renderPage(
+  component: (props: Record<string, never>) => unknown | Promise<unknown>,
+  metadata?: {
+    title?: string
+    description?: string
+    lang?: string
+    locale?: string
+    siteName?: string
+    type?: string
+    url?: string
+    image?: string
+    imageAlt?: string
+    twitterCard?: string
+    twitterImage?: string
+    themeColor?: string
+    icon?: string
+    appleTouchIcon?: string
+    manifest?: string
+    styles?: boolean
+  }
+): Promise<{
+  html: string
+  hasBehaviors: boolean
+  plan: {
+    states: Array<{ id: string; name: string; initialValue: unknown }>
+    events: Array<{
+      event: string
+      commands?: Array<[string, string, unknown]>
+      native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
+    }>
+  }
+}>

package/framework/core.mjs

@@ -0,0 +1,224 @@
+const signalMarker = Symbol("kudzu.signal")
+const behaviorMarker = Symbol("kudzu.behavior")
+const nativeBehaviorMarker = Symbol("kudzu.nativeBehavior")
+
+let renderContext
+
+export function useState(initialValue, name) {
+  if (!renderContext) {
+    throw new Error("useState() can only run while rendering a Kudzu component")
+  }
+
+  const id = `s${renderContext.nextState++}`
+  const signal = {
+    [signalMarker]: true,
+    id,
+    value: initialValue,
+    valueOf() {
+      return this.value
+    },
+    toString() {
+      return String(this.value)
+    }
+  }
+
+  renderContext.states[id] = { name: name ?? id, initialValue }
+  return [signal, () => {
+    throw new Error("State setters are compiled into ordered browser behaviors")
+  }]
+}
+
+export function behavior(commands) {
+  return {
+    [behaviorMarker]: true,
+    commands: commands.map(([operation, signal, value]) => {
+      if (!signal?.[signalMarker]) throw new Error("A compiled behavior must target framework state")
+      return [operation, signal.id, value]
+    })
+  }
+}
+
+export function nativeBehavior(module, handler, states, scope) {
+  return {
+    [nativeBehaviorMarker]: true,
+    module,
+    handler,
+    states: Object.fromEntries(states.map(([name, signal]) => {
+      if (!signal?.[signalMarker]) throw new Error("A native behavior must target framework state")
+      return [name, signal.id]
+    })),
+    scope: Object.fromEntries(scope.map(([name, value]) => [name, serializeCapture(name, value, new Set())]))
+  }
+}
+
+function serializeCapture(name, value, seen) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value
+  if (typeof value === "number") {
+    return Number.isFinite(value) && !Object.is(value, -0) ? value : { type: "number", value: String(value) }
+  }
+  if (value === undefined) return { type: "undefined" }
+  if (typeof value !== "object") throw new Error(`Native capture "${name}" is not serializable: ${typeof value}`)
+  if (seen.has(value)) throw new Error(`Native capture "${name}" is not serializable: cycle`)
+
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) {
+      return { type: "array", value: Array.from(value, entry => serializeCapture(name, entry, seen)) }
+    }
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error(`Native capture "${name}" is not serializable: ${value.constructor?.name ?? "non-plain object"}`)
+    }
+    if (Object.getOwnPropertySymbols(value).length) throw new Error(`Native capture "${name}" is not serializable: symbol`)
+    const entries = []
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+      if (!descriptor.enumerable) continue
+      if (!("value" in descriptor)) throw new Error(`Native capture "${name}" is not serializable: accessor`)
+      entries.push([key, serializeCapture(name, descriptor.value, seen)])
+    }
+    return { type: "object", nullPrototype: prototype === null, value: entries }
+  } finally {
+    seen.delete(value)
+  }
+}
+
+export async function renderPage(component, metadata = {}) {
+  renderContext = { nextState: 0, states: {}, events: [], hasBehaviors: false, hasNativeBehaviors: false }
+
+  try {
+    const body = await renderNode({ type: component, props: {} })
+    const title = escapeHtml(metadata.title ?? "Kudzu")
+    const head = renderMetadata(metadata)
+    const styles = metadata.styles === false
+      ? ""
+      : '<link rel="stylesheet" href="/assets/style.css">'
+    const runtime = renderContext.hasBehaviors
+      ? '<script type="module" src="/assets/kudzu.js"></script>'
+      : ""
+    const nativeRuntime = renderContext.hasNativeBehaviors
+      ? '<script type="module" src="/assets/kudzu-native.js"></script>'
+      : ""
+
+    return {
+      html: `<!doctype html>\n<html lang="${escapeAttribute(metadata.lang ?? "en")}">\n<head>\n<meta charset="utf-8">\n<meta name="viewport" content="width=device-width, initial-scale=1">\n<title>${title}</title>\n${head}${styles}\n</head>\n<body>\n${body}\n${runtime}\n${nativeRuntime}\n</body>\n</html>\n`,
+      hasBehaviors: renderContext.hasBehaviors,
+      plan: {
+        states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
+        events: renderContext.events
+      }
+    }
+  } finally {
+    renderContext = undefined
+  }
+}
+
+function renderMetadata(metadata) {
+  const tags = []
+  const meta = (name, content, property = false) => {
+    if (content) tags.push(`<meta ${property ? "property" : "name"}="${escapeAttribute(name)}" content="${escapeAttribute(content)}">`)
+  }
+
+  if (metadata.description) meta("description", metadata.description)
+  if (metadata.themeColor) meta("theme-color", metadata.themeColor)
+  if (metadata.url) tags.push(`<link rel="canonical" href="${escapeAttribute(metadata.url)}">`)
+  if (metadata.icon) tags.push(`<link rel="icon" href="${escapeAttribute(metadata.icon)}">`)
+  if (metadata.appleTouchIcon) tags.push(`<link rel="apple-touch-icon" href="${escapeAttribute(metadata.appleTouchIcon)}">`)
+  if (metadata.manifest) tags.push(`<link rel="manifest" href="${escapeAttribute(metadata.manifest)}">`)
+
+  meta("og:title", metadata.title, true)
+  meta("og:description", metadata.description, true)
+  meta("og:type", metadata.type ?? "website", true)
+  meta("og:url", metadata.url, true)
+  meta("og:image", metadata.image, true)
+  if (metadata.image) {
+    meta("og:image:width", "1200", true)
+    meta("og:image:height", "630", true)
+    meta("og:image:alt", metadata.imageAlt ?? metadata.title, true)
+  }
+  meta("og:site_name", metadata.siteName, true)
+  meta("og:locale", metadata.locale, true)
+  meta("twitter:card", metadata.twitterCard ?? (metadata.image ? "summary_large_image" : undefined))
+  meta("twitter:title", metadata.title)
+  meta("twitter:description", metadata.description)
+  meta("twitter:image", metadata.twitterImage ?? metadata.image)
+
+  return tags.length ? `${tags.join("\n")}\n` : ""
+}
+
+async function renderNode(node) {
+  if (node == null || node === false || node === true) return ""
+  if (Array.isArray(node)) {
+    let html = ""
+    for (const child of node) html += await renderNode(child)
+    return html
+  }
+  if (node?.[signalMarker]) {
+    return `<span data-k-text="${node.id}" data-k-value="${escapeAttribute(JSON.stringify(node.value))}">${escapeHtml(node.value)}</span>`
+  }
+  if (typeof node === "string" || typeof node === "number" || typeof node === "bigint") {
+    return escapeHtml(node)
+  }
+  if (node instanceof Promise) return renderNode(await node)
+  if (!node || typeof node !== "object" || !("type" in node)) {
+    throw new Error(`Cannot render ${String(node)}`)
+  }
+
+  if (node.type === Symbol.for("kudzu.fragment")) return renderNode(node.props.children)
+  if (typeof node.type === "function") return renderNode(await node.type(node.props))
+
+  const tag = node.type
+  const props = node.props ?? {}
+  let attributes = ""
+
+  for (const [rawName, value] of Object.entries(props)) {
+    if (rawName === "children" || rawName === "key" || value == null || value === false) continue
+
+    if (/^on[A-Z]/.test(rawName)) {
+      const event = rawName.slice(2).toLowerCase()
+      if (value?.[behaviorMarker]) {
+        const commands = JSON.stringify(value.commands)
+        attributes += ` data-k-on-${event}="${escapeAttribute(commands)}"`
+        renderContext.events.push({ event, commands: value.commands })
+      } else if (value?.[nativeBehaviorMarker]) {
+        const native = { module: value.module, handler: value.handler, states: value.states, scope: value.scope }
+        attributes += ` data-k-native-${event}="${escapeAttribute(JSON.stringify(native))}"`
+        renderContext.events.push({ event, native })
+        renderContext.hasNativeBehaviors = true
+      } else {
+        throw new Error(`${rawName} must reference a compilable event handler`)
+      }
+      renderContext.hasBehaviors = true
+      continue
+    }
+
+    const name = rawName === "className" ? "class" : rawName === "htmlFor" ? "for" : rawName
+    if (value === true) {
+      attributes += ` ${name}`
+    } else if (name === "style" && typeof value === "object") {
+      const style = Object.entries(value).map(([property, entry]) => `${toKebabCase(property)}:${entry}`).join(";")
+      attributes += ` style="${escapeAttribute(style)}"`
+    } else {
+      attributes += ` ${name}="${escapeAttribute(value)}"`
+    }
+  }
+
+  const voidElements = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"])
+  if (voidElements.has(tag)) return `<${tag}${attributes}>`
+  return `<${tag}${attributes}>${await renderNode(props.children)}</${tag}>`
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+}
+
+function escapeAttribute(value) {
+  return escapeHtml(value).replaceAll("'", "&#39;")
+}
+
+function toKebabCase(value) {
+  return value.replace(/[A-Z]/g, character => `-${character.toLowerCase()}`)
+}

package/framework/jsx-runtime.d.ts

@@ -0,0 +1,17 @@
+export namespace JSX {
+  type Element = unknown
+  type Children = unknown
+
+  interface IntrinsicAttributes {
+    key?: string | number
+  }
+
+  interface IntrinsicElements {
+    [elementName: string]: Record<string, unknown>
+  }
+}
+
+export const Fragment: unique symbol
+export function jsx(type: unknown, props: unknown, key?: string): JSX.Element
+export const jsxs: typeof jsx
+export const jsxDEV: typeof jsx

package/framework/jsx-runtime.mjs

@@ -0,0 +1,8 @@
+export const Fragment = Symbol.for("kudzu.fragment")
+
+export function jsx(type, props, key) {
+  return { type, props: key == null ? props : { ...props, key } }
+}
+
+export const jsxs = jsx
+export const jsxDEV = jsx

package/framework/native-runtime.js

@@ -0,0 +1,81 @@
+import { browserState, commitDom } from "./runtime.js"
+
+export function createNativeContext(state, stateIds, commit, serializedScope = {}) {
+  const changed = new Set()
+  let scheduled = false
+  const scope = Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value)]))
+
+  const flush = () => {
+    scheduled = false
+    const ids = [...changed]
+    changed.clear()
+    for (const id of ids) commit(id, state.get(id))
+  }
+
+  return {
+    get(name) {
+      return state.get(stateIds[name])
+    },
+    scope(name) {
+      return scope[name]
+    },
+    set(name, value) {
+      const id = stateIds[name]
+      const current = state.get(id)
+      state.set(id, typeof value === "function" ? value(current) : value)
+      changed.add(id)
+      if (!scheduled) {
+        scheduled = true
+        queueMicrotask(flush)
+      }
+    }
+  }
+}
+
+if (typeof document !== "undefined") {
+  const modules = new Map()
+
+  for (const eventName of ["click", "input", "change", "submit", "keydown", "keyup"]) {
+    document.addEventListener(eventName, event => {
+      const target = event.target.closest(`[data-k-native-${eventName}]`)
+      if (!target) return
+
+      const native = JSON.parse(target.dataset[`kNative${capitalize(eventName)}`])
+      let modulePromise = modules.get(native.module)
+      if (!modulePromise) {
+        modulePromise = import(native.module)
+        modules.set(native.module, modulePromise)
+      }
+      modulePromise
+        .then(module => module[native.handler](createNativeContext(browserState, native.states, commitDom, native.scope), delegatedEvent(event, target)))
+        .catch(error => console.error(error))
+    }, true)
+  }
+}
+
+function deserialize(value) {
+  if (!value || typeof value !== "object") return value
+  if (value.type === "undefined") return undefined
+  if (value.type === "number") return value.value === "NaN" ? NaN : value.value === "Infinity" ? Infinity : value.value === "-Infinity" ? -Infinity : -0
+  if (value.type === "array") return value.value.map(deserialize)
+  if (value.type === "object") {
+    const object = value.nullPrototype ? Object.create(null) : {}
+    for (const [key, entry] of value.value) Object.defineProperty(object, key, { value: deserialize(entry), enumerable: true, writable: true, configurable: true })
+    return object
+  }
+  return value
+}
+
+function delegatedEvent(event, currentTarget) {
+  return new Proxy(event, {
+    get(source, property) {
+      if (property === "currentTarget") return currentTarget
+      const value = Reflect.get(source, property, source)
+      return typeof value === "function" ? value.bind(source) : value
+    }
+  })
+}
+
+function capitalize(value) {
+  return value[0].toUpperCase() + value.slice(1)
+}

package/framework/runtime.js

@@ -0,0 +1,43 @@
+export function applyCommands(state, commands, commit, log = console.log) {
+  const changed = new Set()
+
+  for (const [operation, id, operand] of commands) {
+    const current = state.get(id)
+    if (operation === "log") {
+      log(operand, current)
+      continue
+    }
+    state.set(id, operation === "add" ? current + operand : operand)
+    changed.add(id)
+  }
+
+  for (const id of changed) commit(id, state.get(id))
+}
+
+export const browserState = new Map()
+
+export function commitDom(id, value) {
+  for (const node of document.querySelectorAll(`[data-k-text="${id}"]`)) {
+    node.textContent = value
+    node.dataset.kValue = JSON.stringify(value)
+  }
+}
+
+if (typeof document !== "undefined") {
+  for (const node of document.querySelectorAll("[data-k-text]")) {
+    browserState.set(node.dataset.kText, JSON.parse(node.dataset.kValue))
+  }
+
+  for (const eventName of ["click", "input", "change"]) {
+    document.addEventListener(eventName, event => {
+      const target = event.target.closest(`[data-k-on-${eventName}]`)
+      if (!target) return
+      const commands = target.dataset[`kOn${capitalize(eventName)}`]
+      applyCommands(browserState, JSON.parse(commands), commitDom)
+    })
+  }
+}
+
+function capitalize(value) {
+  return value[0].toUpperCase() + value.slice(1)
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kudzujs/core",
+  "version": "0.1.0",
+  "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kudzujs/kudzu.git"
+  },
+  "homepage": "https://github.com/kudzujs/kudzu#readme",
+  "bugs": "https://github.com/kudzujs/kudzu/issues",
+  "keywords": [
+    "tsx",
+    "framework",
+    "html-first",
+    "compiler",
+    "ssg",
+    "no-vdom"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin/",
+    "framework/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kudzu": "./bin/kudzu.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./framework/core.d.ts",
+      "default": "./framework/core.mjs"
+    },
+    "./jsx-runtime": {
+      "types": "./framework/jsx-runtime.d.ts",
+      "default": "./framework/jsx-runtime.mjs"
+    }
+  },
+  "scripts": {
+    "build": "node ./bin/kudzu.mjs build",
+    "dev": "node ./bin/kudzu.mjs dev",
+    "check": "tsc --noEmit && node ./bin/kudzu.mjs build",
+    "test": "node --test",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "dependencies": {
+    "typescript": "^5.9.2"
+  }
+}