@kudzujs/core 0.1.0 → 0.2.3

package/README.md

@@ -10,10 +10,22 @@ Brand assets, favicons, manifest icons, and the 1200×630 social preview live in
 
 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.
+> Experimental `0.2.x`: the compiler API and supported TSX surface may change.
+
+Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
 ## Install
 
+Create a new project:
+
+```bash
+npm create kudzu@latest my-app
+cd my-app
+npm run dev
+```
+
+Or add Kudzu to an existing project:
+
 ```bash
 npm install @kudzujs/core
 ```
@@ -86,6 +98,18 @@ function increaseTwice() {
 
 The handler above increments by two and patches its bound DOM once. Inspect the generated plan at `.kudzu/kudzu-plan.json`.
 
+## Reactive Attributes
+
+`className`, `disabled`, and controlled `value` accept normal state-dependent TSX expressions:
+
+```tsx
+<div className={active ? "active" : "idle"} />
+<button disabled={loading}>Save</button>
+<input value={name} onInput={event => setName(event.currentTarget.value)} />
+```
+
+Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property.
+
 ## 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.
@@ -139,10 +163,10 @@ Supported:
 - Synchronous and async event handlers
 - Serializable component-local captures
 - Direct text DOM patches
+- Reactive `className`, `disabled`, and controlled `value` 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
@@ -150,7 +174,7 @@ Not implemented yet:
 
 ## Benchmarks
 
-Measurements below were produced on the same machine from production builds. They compare build artifacts, not ecosystem maturity or full application performance.
+Measurements below were produced on the same machine from production builds. Each framework received one warm-up followed by seven clean builds in rotating order; the table reports the median. Initial JavaScript includes inline scripts, root script references, and their static import graph, compressed file-by-file with gzip level 9. Total output is the raw size of every deploy artifact.
 
 ### Interactive Counter
 
@@ -158,30 +182,31 @@ 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 |
+| Kudzu | Yes | 563 B | 1.7 KB | **384 ms** |
+| Astro | Yes | **158 B** | **365 B** | 911 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 |
+| Qwik CSR | No | 20.6 KB | 57.8 KB | 627 ms |
+| Vue CSR | No | 24.0 KB | 60.3 KB | 814 ms |
+| React CSR | No | 59.2 KB | 189.0 KB | 1052 ms |
+| Next.js | Yes | 182.1 KB | 652.2 KB | 2985 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:
+Same content and CSS across every fixture:
 
 | 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.
+| Kudzu | Yes | **0 B** | 3.2 KB | **478 ms** |
+| Astro | Yes | **0 B** | **3.0 KB** | 1253 ms |
+| Svelte CSR | No | 10.2 KB | 27.2 KB | 1018 ms |
+| Qwik CSR | No | 20.2 KB | 59.6 KB | 784 ms |
+| Vue CSR | No | 24.2 KB | 62.3 KB | 960 ms |
+| React CSR | No | 59.8 KB | 192.3 KB | 1253 ms |
+| Next.js | Yes | 182.6 KB | 663.6 KB | 3880 ms |
+
+Benchmark snapshot collected on July 21, 2026 with Node 24.14.0 on an Intel i5-9500. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
 
 ## Development
 

package/framework/README.md

@@ -3,10 +3,13 @@
 - `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.
+- `runtime.js`: command-only runtime for direct state-to-text patches.
+- `shared-runtime.js`: command runtime with binding commit hooks, emitted only when needed.
+- `binding-runtime.js`: optional reactive `className`, `disabled`, and `value` patches.
+- `serialization.js`: capture deserialization shared by binding and native handlers.
 - `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/`.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes add `binding-runtime.js`; native handlers add `native-runtime.js`. Generated evaluators live under `dist/assets/handlers/`.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/binding-runtime.js

@@ -0,0 +1,85 @@
+import { browserState, registerCommitter } from "./shared-runtime.js"
+import { deserialize } from "./serialization.js"
+
+const bindingTargets = new Map()
+
+export function patchBinding(node, target, value) {
+  if (target === "disabled") {
+    node.toggleAttribute("disabled", Boolean(value))
+  } else if (target === "value") {
+    const next = value == null ? "" : String(value)
+    if (node.value !== next) node.value = next
+  } else if (value == null || value === false) {
+    node.removeAttribute("class")
+  } else {
+    node.setAttribute("class", String(value))
+  }
+}
+
+function commitBindings(id) {
+  for (const binding of bindingTargets.get(id) ?? []) patchBinding(binding.node, binding.target, binding.read())
+}
+
+registerCommitter(commitBindings)
+
+if (typeof document !== "undefined") {
+  const imports = new Map()
+  const registrations = []
+  for (const target of ["class", "disabled", "value"]) {
+    for (const node of document.querySelectorAll(`[data-k-bind-${target}]`)) {
+      const descriptor = JSON.parse(node.dataset[`kBind${capitalize(target)}`])
+      if (descriptor.state) {
+        registerBinding(descriptor.state, { node, target, read: () => browserState.get(descriptor.state) })
+        continue
+      }
+      let modulePromise = imports.get(descriptor.module)
+      if (!modulePromise) {
+        modulePromise = import(descriptor.module)
+        imports.set(descriptor.module, modulePromise)
+      }
+      registrations.push(modulePromise.then(async module => {
+        const context = await createBindingContext(descriptor, imports)
+        const binding = { node, target, read: () => module[descriptor.handler](context) }
+        for (const id of bindingStateIds(descriptor)) registerBinding(id, binding)
+        patchBinding(node, target, binding.read())
+      }))
+    }
+  }
+  Promise.all(registrations).catch(error => console.error(error))
+}
+
+function registerBinding(id, binding) {
+  const bindings = bindingTargets.get(id) ?? []
+  bindings.push(binding)
+  bindingTargets.set(id, bindings)
+}
+
+async function createBindingContext(descriptor, imports) {
+  const scope = Object.fromEntries(Object.entries(descriptor.scope).map(([name, value]) => [name, deserialize(value)]))
+  const nested = {}
+  await Promise.all(Object.entries(descriptor.scopeBindings).map(async ([name, binding]) => {
+    let modulePromise = imports.get(binding.module)
+    if (!modulePromise) {
+      modulePromise = import(binding.module)
+      imports.set(binding.module, modulePromise)
+    }
+    const [module, context] = await Promise.all([modulePromise, createBindingContext(binding, imports)])
+    nested[name] = () => module[binding.handler](context)
+  }))
+  return {
+    get: name => browserState.get(descriptor.states[name]),
+    scope: name => name in descriptor.scopeStates ? browserState.get(descriptor.scopeStates[name]) : name in nested ? nested[name]() : scope[name]
+  }
+}
+
+function bindingStateIds(descriptor) {
+  return new Set([
+    ...Object.values(descriptor.states),
+    ...Object.values(descriptor.scopeStates),
+    ...Object.values(descriptor.scopeBindings).flatMap(binding => [...bindingStateIds(binding)])
+  ])
+}
+
+function capitalize(value) {
+  return value[0].toUpperCase() + value.slice(1)
+}

package/framework/build.mjs

@@ -30,6 +30,8 @@ export async function build({ quiet = false } = {}) {
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
 
   let behaviorCount = 0
+  let bindingCount = 0
+  let stateSeedCount = 0
   const plans = []
   const hasStyles = await exists(join(sourceDirectory, "style.css"))
 
@@ -48,14 +50,32 @@ export async function build({ quiet = false } = {}) {
     await writeFile(join(routeDirectory, "index.html"), result.html)
     plans.push({ route: `/${route}`, ...result.plan })
     if (result.hasBehaviors) behaviorCount++
+    if (result.hasBindings) bindingCount++
+    if (result.hasStateSeed) stateSeedCount++
   }
 
   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)
+  const commandEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.commands).map(event => event.event)))].sort()
+  const nativeEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.native).map(event => event.event)))].sort()
+  if (behaviorCount) {
+    const runtimeFile = bindingCount ? "./shared-runtime.js" : "./runtime.js"
+    const runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, stateSeedCount > 0)
+    await writeFile(join(assetsDirectory, "kudzu.js"), runtime)
+  }
+  const hasNativeHandlers = handlerModules.some(module => module.hasNativeHandlers)
+  if (bindingCount || hasNativeHandlers) await cp(new URL("./serialization.js", import.meta.url), join(assetsDirectory, "kudzu-serialization.js"))
+  if (bindingCount) {
+    const bindingRuntime = (await readFile(new URL("./binding-runtime.js", import.meta.url), "utf8"))
+      .replace('"./shared-runtime.js"', '"./kudzu.js"')
+      .replace('"./serialization.js"', '"./kudzu-serialization.js"')
+    await writeFile(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime)
+  }
+  if (hasNativeHandlers) {
+    const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"))
+      .replace('"./runtime.js"', '"./kudzu.js"')
+      .replace('"./serialization.js"', '"./kudzu-serialization.js"')
+    await writeFile(join(assetsDirectory, "kudzu-native.js"), specializeEvents(nativeRuntime, nativeEvents))
   }
   for (const handlerModule of handlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
@@ -69,6 +89,18 @@ export async function build({ quiet = false } = {}) {
   if (!quiet) console.log(`Built ${pageFiles.length} page(s), ${behaviorCount} interactive page(s) into dist/`)
 }
 
+function specializeEvents(source, events) {
+  return source.replace(/const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`)
+}
+
+function specializeRuntime(source, events, hasStateSeed) {
+  const specialized = specializeEvents(source, events)
+  if (hasStateSeed) return specialized
+  return specialized
+    .replace("  const initialState = document.body.dataset.kState\n", "")
+    .replace("  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)\n", "")
+}
+
 export async function dev() {
   await build()
 
@@ -110,6 +142,7 @@ export async function dev() {
 async function compile(file) {
   const source = await readFile(file, "utf8")
   const nativeHandlers = []
+  const reactiveBindings = []
   const handlerPath = `handlers/${relative(sourceDirectory, file).replaceAll(sep, "/").replace(/\.(?:ts|tsx)$/, ".js")}`
   const result = ts.transpileModule(source, {
     fileName: file,
@@ -119,7 +152,7 @@ async function compile(file) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, `/assets/${handlerPath}`)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, `/assets/${handlerPath}`)] },
     reportDiagnostics: true
   })
 
@@ -132,21 +165,24 @@ async function compile(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")
+  if (!nativeHandlers.length && !reactiveBindings.length) return undefined
+  const moduleSource = [
+    ...nativeHandlers.map(handler => printNativeHandler(handler)),
+    ...reactiveBindings.map(entry => printReactiveBinding(entry))
+  ].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 }
+  return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0 }
 }
 
-function createKudzuTransformer(nativeHandlers, handlerUrl) {
+function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
   return context => sourceFile => {
     const factory = context.factory
-    const setters = new Map()
+    const settersByFunction = new Map()
     const functions = new Map()
     let usesBehavior = false
 
@@ -155,7 +191,12 @@ function createKudzuTransformer(nativeHandlers, handlerUrl) {
         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)
+          const owner = nearestFunction(node)
+          if (owner) {
+            const setters = settersByFunction.get(owner) ?? new Map()
+            setters.set(setterElement.name.text, stateElement.name.text)
+            settersByFunction.set(owner, setters)
+          }
         }
       }
       if (ts.isFunctionDeclaration(node) && node.name) functions.set(node.name.text, node)
@@ -185,7 +226,20 @@ function createKudzuTransformer(nativeHandlers, handlerUrl) {
         return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, initializer)
       }
 
+      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && ["className", "disabled", "value"].includes(node.name.getText())) {
+        const expression = node.initializer.expression
+        const setters = settersForNode(node, settersByFunction)
+        const usedStates = referencedStateNames(expression, setters)
+        const captures = captureNames(expression, expression, setters)
+        if ((usedStates.size || captures.size) && !ts.isIdentifier(expression)) {
+          usesBehavior = true
+          const compiled = compileReactiveBinding(expression, setters, factory, context, reactiveBindings, handlerUrl)
+          return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, compiled))
+        }
+      }
+
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && /^on[A-Z]/.test(node.name.getText())) {
+        const setters = settersForNode(node, settersByFunction)
         const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl)
         if (event) {
           usesBehavior = true
@@ -203,6 +257,8 @@ function createKudzuTransformer(nativeHandlers, handlerUrl) {
 
     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")))
+    if (reactiveBindings.length) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("binding"), factory.createIdentifier("__kBinding")))
+    if (reactiveBindings.length) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
       undefined,
       factory.createImportClause(false, undefined, factory.createNamedImports(behaviorImports)),
@@ -212,6 +268,44 @@ function createKudzuTransformer(nativeHandlers, handlerUrl) {
   }
 }
 
+function compileReactiveBinding(expression, setters, factory, context, reactiveBindings, handlerUrl) {
+  const usedStates = referencedStateNames(expression, setters)
+  const captures = captureNames(expression, expression, setters)
+  const exportName = `binding${reactiveBindings.length}`
+  reactiveBindings.push({ exportName, expression, captures, states: usedStates })
+  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)
+  ]))
+  const stateNames = new Set(usedStates)
+  const rewriteInitial = node => {
+    if (ts.isShorthandPropertyAssignment(node) && stateNames.has(node.name.text)) {
+      return factory.createPropertyAssignment(node.name, factory.createPropertyAccessExpression(node.name, "value"))
+    }
+    if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression)) {
+      return factory.createPropertyAccessExpression(node, "value")
+    }
+    if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text)) {
+      return factory.createPropertyAssignment(node.name, factory.createCallExpression(factory.createIdentifier("__kBindingValue"), undefined, [node.name]))
+    }
+    if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node)) {
+      return factory.createCallExpression(factory.createIdentifier("__kBindingValue"), undefined, [node])
+    }
+    return ts.visitEachChild(node, rewriteInitial, context)
+  }
+  return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, [
+    ts.visitNode(expression, rewriteInitial),
+    factory.createStringLiteral(handlerUrl),
+    factory.createStringLiteral(exportName),
+    factory.createArrayLiteralExpression(states),
+    factory.createArrayLiteralExpression(scope)
+  ])
+}
+
 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
@@ -240,14 +334,18 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
 }
 
 function nativeStateNames(expression, setters) {
+  return referencedStateNames(expression.body, setters, expression)
+}
+
+function referencedStateNames(root, setters, scopeRoot = root) {
   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)
+    if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, scopeRoot)) used.add(node.text)
     ts.forEachChild(node, visit)
   }
-  visit(expression.body)
+  visit(root)
   return used
 }
 
@@ -267,6 +365,10 @@ const nativeGlobals = new Set([
 ])
 
 function nativeCaptureNames(expression, setters) {
+  return captureNames(expression, expression.body, setters)
+}
+
+function captureNames(declarationRoot, referenceRoot, setters) {
   const local = new Set()
   const collectDeclarations = node => {
     if (ts.isVariableDeclaration(node)) for (const name of bindingNames(node.name)) local.add(name)
@@ -274,7 +376,7 @@ function nativeCaptureNames(expression, setters) {
     if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) local.add(node.name.text)
     ts.forEachChild(node, collectDeclarations)
   }
-  collectDeclarations(expression)
+  collectDeclarations(declarationRoot)
 
   const stateNames = new Set(setters.values())
   const captures = new Set()
@@ -285,7 +387,7 @@ function nativeCaptureNames(expression, setters) {
     }
     ts.forEachChild(node, visit)
   }
-  visit(expression.body)
+  visit(referenceRoot)
   return captures
 }
 
@@ -308,6 +410,30 @@ function isReferenceIdentifier(node) {
   return true
 }
 
+function nearestFunction(node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (ts.isFunctionDeclaration(current) || ts.isFunctionExpression(current) || ts.isArrowFunction(current)) return current
+  }
+  return undefined
+}
+
+function isShadowedByParameter(node, scopeRoot) {
+  for (let current = node.parent; current; current = current.parent) {
+    if ((ts.isFunctionDeclaration(current) || ts.isFunctionExpression(current) || ts.isArrowFunction(current)) && current.parameters.some(parameter => bindingNames(parameter.name).includes(node.text))) return true
+    if (current === scopeRoot) break
+  }
+  return false
+}
+
+function settersForNode(node, settersByFunction) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (!ts.isFunctionDeclaration(current) && !ts.isFunctionExpression(current) && !ts.isArrowFunction(current)) continue
+    const setters = settersByFunction.get(current)
+    if (setters) return setters
+  }
+  return new Map()
+}
+
 function printNativeHandler({ exportName, expression, captures, setters }) {
   const factory = ts.factory
   const stateNames = new Set(setters.values())
@@ -320,7 +446,7 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
           [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)) {
+      if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression)) {
         return factory.createCallExpression(
           factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"),
           undefined,
@@ -359,6 +485,54 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
   }
 }
 
+function printReactiveBinding({ exportName, expression, captures, states }) {
+  const factory = ts.factory
+  const transformer = context => root => {
+    const visitor = node => {
+      if (ts.isShorthandPropertyAssignment(node) && states.has(node.name.text)) {
+        return factory.createPropertyAssignment(
+          node.name,
+          factory.createCallExpression(
+            factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"),
+            undefined,
+            [factory.createStringLiteral(node.name.text)]
+          )
+        )
+      }
+      if (ts.isIdentifier(node) && states.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression)) {
+        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, [transformer])
+  try {
+    const declaration = factory.createFunctionDeclaration(
+      [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+      undefined,
+      exportName,
+      undefined,
+      [factory.createParameterDeclaration(undefined, undefined, "__k")],
+      undefined,
+      factory.createBlock([factory.createReturnStatement(transformed.transformed[0])], true)
+    )
+    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"),

package/framework/core.d.ts

@@ -4,6 +4,8 @@ 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 binding(value: unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
+export function bindingValue(value: unknown): unknown
 
 export function renderPage(
   component: (props: Record<string, never>) => unknown | Promise<unknown>,
@@ -28,6 +30,8 @@ export function renderPage(
 ): Promise<{
   html: string
   hasBehaviors: boolean
+  hasBindings: boolean
+  hasStateSeed: boolean
   plan: {
     states: Array<{ id: string; name: string; initialValue: unknown }>
     events: Array<{
@@ -35,5 +39,15 @@ export function renderPage(
       commands?: Array<[string, string, unknown]>
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
+    bindings: Array<{
+      target: "class" | "disabled" | "value"
+      state?: string
+      module?: string
+      handler?: string
+      states?: Record<string, string>
+      scope?: Record<string, unknown>
+      scopeStates?: Record<string, string>
+      scopeBindings?: Record<string, unknown>
+    }>
   }
 }>

package/framework/core.mjs

@@ -1,6 +1,7 @@
 const signalMarker = Symbol("kudzu.signal")
 const behaviorMarker = Symbol("kudzu.behavior")
 const nativeBehaviorMarker = Symbol("kudzu.nativeBehavior")
+const bindingMarker = Symbol("kudzu.binding")
 
 let renderContext
 
@@ -51,6 +52,38 @@ export function nativeBehavior(module, handler, states, scope) {
   }
 }
 
+export function binding(value, module, handler, states, scope) {
+  const scopeStates = {}
+  const serializedScope = {}
+  const scopeBindings = {}
+  for (const [name, entry] of scope) {
+    if (entry?.[signalMarker]) scopeStates[name] = entry.id
+    else if (entry?.[bindingMarker]) scopeBindings[name] = bindingDescriptor(entry)
+    else serializedScope[name] = serializeCapture(name, entry, new Set())
+  }
+  return {
+    [bindingMarker]: true,
+    value,
+    module,
+    handler,
+    states: Object.fromEntries(states.map(([name, signal]) => {
+      if (!signal?.[signalMarker]) throw new Error("A reactive binding must target framework state")
+      return [name, signal.id]
+    })),
+    scope: serializedScope,
+    scopeStates,
+    scopeBindings
+  }
+}
+
+export function bindingValue(value) {
+  return value?.[signalMarker] || value?.[bindingMarker] ? value.value : value
+}
+
+function bindingDescriptor(value) {
+  return { module: value.module, handler: value.handler, states: value.states, scope: value.scope, scopeStates: value.scopeStates, scopeBindings: value.scopeBindings }
+}
+
 function serializeCapture(name, value, seen) {
   if (value === null || typeof value === "string" || typeof value === "boolean") return value
   if (typeof value === "number") {
@@ -83,7 +116,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}) {
-  renderContext = { nextState: 0, states: {}, events: [], hasBehaviors: false, hasNativeBehaviors: false }
+  renderContext = { nextState: 0, states: {}, textStates: new Set(), events: [], bindings: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false }
 
   try {
     const body = await renderNode({ type: component, props: {} })
@@ -98,13 +131,25 @@ export async function renderPage(component, metadata = {}) {
     const nativeRuntime = renderContext.hasNativeBehaviors
       ? '<script type="module" src="/assets/kudzu-native.js"></script>'
       : ""
+    const bindingRuntime = renderContext.hasBindings
+      ? '<script type="module" src="/assets/kudzu-binding.js"></script>'
+      : ""
+    const initialState = renderContext.hasBehaviors
+      ? Object.entries(renderContext.states).filter(([id]) => !renderContext.textStates.has(id)).map(([id, entry]) => [id, entry.initialValue])
+      : []
+    const state = initialState.length
+      ? ` data-k-state="${escapeAttribute(JSON.stringify(initialState))}"`
+      : ""
 
     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`,
+      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${state}>\n${body}\n${runtime}\n${bindingRuntime}\n${nativeRuntime}\n</body>\n</html>\n`,
       hasBehaviors: renderContext.hasBehaviors,
+      hasBindings: renderContext.hasBindings,
+      hasStateSeed: initialState.length > 0,
       plan: {
         states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
-        events: renderContext.events
+        events: renderContext.events,
+        bindings: renderContext.bindings
       }
     }
   } finally {
@@ -153,6 +198,7 @@ async function renderNode(node) {
     return html
   }
   if (node?.[signalMarker]) {
+    renderContext.textStates.add(node.id)
     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") {
@@ -171,7 +217,7 @@ async function renderNode(node) {
   let attributes = ""
 
   for (const [rawName, value] of Object.entries(props)) {
-    if (rawName === "children" || rawName === "key" || value == null || value === false) continue
+    if (rawName === "children" || rawName === "key") continue
 
     if (/^on[A-Z]/.test(rawName)) {
       const event = rawName.slice(2).toLowerCase()
@@ -192,6 +238,26 @@ async function renderNode(node) {
     }
 
     const name = rawName === "className" ? "class" : rawName === "htmlFor" ? "for" : rawName
+    const target = name === "class" || name === "disabled" || name === "value" ? name : undefined
+    if (target && (value?.[signalMarker] || value?.[bindingMarker])) {
+      const initialValue = value[signalMarker] ? value.value : value.value
+      const reactive = value[signalMarker] || Object.keys(value.states).length > 0 || Object.keys(value.scopeStates).length > 0 || Object.keys(value.scopeBindings).length > 0
+      if (!reactive) {
+        attributes += renderAttribute(name, initialValue)
+        continue
+      }
+      const descriptor = value[signalMarker]
+        ? { state: value.id }
+        : bindingDescriptor(value)
+      attributes += renderAttribute(name, initialValue)
+      attributes += ` data-k-bind-${target}="${escapeAttribute(JSON.stringify(descriptor))}"`
+      renderContext.bindings.push({ target, ...descriptor })
+      renderContext.hasBehaviors = true
+      renderContext.hasBindings = true
+      continue
+    }
+
+    if (value == null || value === false) continue
     if (value === true) {
       attributes += ` ${name}`
     } else if (name === "style" && typeof value === "object") {
@@ -207,6 +273,13 @@ async function renderNode(node) {
   return `<${tag}${attributes}>${await renderNode(props.children)}</${tag}>`
 }
 
+function renderAttribute(name, value) {
+  if (name === "disabled") return value ? " disabled" : ""
+  if (name === "value") return value == null ? "" : ` value="${escapeAttribute(value)}"`
+  if (value == null || value === false) return ""
+  return ` ${name}="${escapeAttribute(value)}"`
+}
+
 function escapeHtml(value) {
   return String(value)
     .replaceAll("&", "&amp;")

package/framework/native-runtime.js

@@ -1,4 +1,5 @@
 import { browserState, commitDom } from "./runtime.js"
+import { deserialize } from "./serialization.js"
 
 export function createNativeContext(state, stateIds, commit, serializedScope = {}) {
   const changed = new Set()
@@ -35,7 +36,8 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
 if (typeof document !== "undefined") {
   const modules = new Map()
 
-  for (const eventName of ["click", "input", "change", "submit", "keydown", "keyup"]) {
+  const eventNames = ["click", "input", "change", "submit", "keydown", "keyup"]
+  for (const eventName of eventNames) {
     document.addEventListener(eventName, event => {
       const target = event.target.closest(`[data-k-native-${eventName}]`)
       if (!target) return
@@ -53,19 +55,6 @@ if (typeof document !== "undefined") {
   }
 }
 
-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) {

package/framework/runtime.js

@@ -17,18 +17,16 @@ export function applyCommands(state, commands, commit, log = console.log) {
 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)
-  }
+  for (const node of document.querySelectorAll(`[data-k-text="${id}"]`)) node.textContent = value
 }
 
 if (typeof document !== "undefined") {
-  for (const node of document.querySelectorAll("[data-k-text]")) {
-    browserState.set(node.dataset.kText, JSON.parse(node.dataset.kValue))
-  }
+  const initialState = document.body.dataset.kState
+  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)
+  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"]) {
+  const eventNames = ["click", "input", "change"]
+  for (const eventName of eventNames) {
     document.addEventListener(eventName, event => {
       const target = event.target.closest(`[data-k-on-${eventName}]`)
       if (!target) return

package/framework/serialization.js

@@ -0,0 +1,12 @@
+export 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
+}

package/framework/shared-runtime.js

@@ -0,0 +1,47 @@
+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()
+const committers = []
+
+export function registerCommitter(commit) {
+  committers.push(commit)
+}
+
+export function commitDom(id, value) {
+  for (const node of document.querySelectorAll(`[data-k-text="${id}"]`)) node.textContent = value
+  for (const commit of committers) commit(id)
+}
+
+if (typeof document !== "undefined") {
+  const initialState = document.body.dataset.kState
+  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)
+  for (const node of document.querySelectorAll("[data-k-text]")) browserState.set(node.dataset.kText, JSON.parse(node.dataset.kValue))
+
+  const eventNames = ["click", "input", "change"]
+  for (const eventName of eventNames) {
+    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

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "bin": {
-    "kudzu": "./bin/kudzu.mjs"
+    "kudzu": "bin/kudzu.mjs"
   },
   "exports": {
     ".": {
@@ -48,9 +48,14 @@
     "dev": "node ./bin/kudzu.mjs dev",
     "check": "tsc --noEmit && node ./bin/kudzu.mjs build",
     "test": "node --test",
-    "prepublishOnly": "npm run check && npm test"
+    "prepublishOnly": "npm run check && npm test",
+    "deploy": "wrangler deploy",
+    "preview": "wrangler dev"
   },
   "dependencies": {
     "typescript": "^5.9.2"
+  },
+  "devDependencies": {
+    "wrangler": "^4.112.0"
   }
 }