@kudzujs/core 0.4.7 → 0.4.8

package/README.md

@@ -122,7 +122,22 @@ Regular attributes use the same expressions without an allowlist:
 />
 ```
 
-Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property. `aria-*` and `data-*` boolean values serialize as `"true"` or `"false"`; ordinary false values remove the attribute. Object `style` values use React-shaped camelCase properties, add `px` to nonzero dimensional numbers, and preserve unitless properties and CSS custom properties. Reactive `ref` and `dangerouslySetInnerHTML` remain unsupported.
+Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property. `aria-*` and `data-*` boolean values serialize as `"true"` or `"false"`; ordinary false values remove the attribute. Object `style` values use React-shaped camelCase properties, add `px` to nonzero dimensional numbers, and preserve unitless properties and CSS custom properties. Reactive `dangerouslySetInnerHTML` remains unsupported.
+
+## DOM Refs
+
+Use an object ref to access an element from a normal event handler:
+
+```tsx
+const inputRef = useRef<HTMLInputElement>(null)
+
+return <>
+  <input ref={inputRef} />
+  <button onClick={() => inputRef.current?.focus()}>Focus</button>
+</>
+```
+
+Kudzu resolves `current` when the handler reads it, so removed conditional elements return `null` without a component runtime. Refs must initialize with `null`; callback refs, mutable value refs, and refs inside keyed lists are not supported.
 
 ## Conditional DOM
 
@@ -169,7 +184,7 @@ const [items, setItems] = useState([
 
 Kudzu emits initial items as static HTML, then adds, removes, updates, and moves keyed elements directly. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Item-local handlers use direct DOM listeners and receive the latest JSON-safe item for their key, including after updates, additions, and reorders. The item remains stored once in shared list state; handler descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
 
-Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a direct local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, locals, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Nested conditions or lists, item spreads, component tags, fragments, and reactive `style`, `ref`, or `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a direct local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, locals, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Nested conditions or lists, item spreads, component tags, dynamic styles, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 ## Normal JavaScript
 
@@ -206,6 +221,7 @@ TSX
 
 - Static pages ship no client JavaScript.
 - Interactive pages receive only the runtime capabilities they use.
+- Production JavaScript is minified; development output stays readable.
 - Components are authoring units; no component tree is retained in the browser.
 - There is no VDOM, hydration pass, router, or client application runtime.
 
@@ -230,6 +246,7 @@ Supported:
 - Direct text DOM patches
 - Reactive standard, `aria-*`, and `data-*` attributes
 - Reactive object `style` attributes
+- Object DOM refs in native event handlers
 - Controlled `value` and `checked` form properties
 - Conditional child `&&` and ternary DOM patches
 - Direct keyed local-state lists
@@ -251,13 +268,13 @@ Same counter with initial value `7` and increment/decrement buttons:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| Kudzu | Yes | 487 B | 1.4 KB | **363 ms** |
-| Astro | Yes | **158 B** | **365 B** | 851 ms |
-| Svelte CSR | No | 10.5 KB | 26.9 KB | 827 ms |
-| Qwik CSR | No | 20.6 KB | 57.8 KB | 598 ms |
-| Vue CSR | No | 24.0 KB | 60.3 KB | 762 ms |
-| React CSR | No | 59.2 KB | 189.0 KB | 1018 ms |
-| Next.js | Yes | 182.1 KB | 652.2 KB | 2989 ms |
+| Kudzu | Yes | 393 B | 1.1 KB | **431 ms** |
+| Astro | Yes | **158 B** | **365 B** | 974 ms |
+| Svelte CSR | No | 10.5 KB | 26.9 KB | 961 ms |
+| Qwik CSR | No | 20.6 KB | 57.8 KB | 660 ms |
+| Vue CSR | No | 24.0 KB | 60.3 KB | 859 ms |
+| React CSR | No | 59.2 KB | 189.0 KB | 1133 ms |
+| Next.js | Yes | 182.1 KB | 652.2 KB | 3269 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.
 
@@ -267,13 +284,13 @@ Same content and CSS across every fixture:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| Kudzu | Yes | **0 B** | 3.2 KB | **380 ms** |
-| Astro | Yes | **0 B** | **3.0 KB** | 965 ms |
-| Svelte CSR | No | 10.2 KB | 27.2 KB | 824 ms |
-| Qwik CSR | No | 20.2 KB | 59.6 KB | 594 ms |
-| Vue CSR | No | 24.2 KB | 62.3 KB | 755 ms |
-| React CSR | No | 59.8 KB | 192.3 KB | 1041 ms |
-| Next.js | Yes | 182.6 KB | 663.6 KB | 2975 ms |
+| Kudzu | Yes | **0 B** | 3.2 KB | **385 ms** |
+| Astro | Yes | **0 B** | **3.0 KB** | 970 ms |
+| Svelte CSR | No | 10.2 KB | 27.2 KB | 829 ms |
+| Qwik CSR | No | 20.2 KB | 59.6 KB | 634 ms |
+| Vue CSR | No | 24.2 KB | 62.3 KB | 767 ms |
+| React CSR | No | 59.8 KB | 192.3 KB | 1098 ms |
+| Next.js | Yes | 182.6 KB | 663.6 KB | 3217 ms |
 
 ### 1,000-item Keyed List
 
@@ -281,15 +298,15 @@ The list starts with 1,000 keyed items, then updates every label, reverses the o
 
 | Framework | Initial content | Initial JS gzip | Total output | Build | Update | Reverse | Remove | Add | Operations total |
 |---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
-| Astro | Yes | **324 B** | **43.6 KB** | 852 ms | **3.5 ms** | 25.8 ms | 15.8 ms | **17.9 ms** | **63.0 ms** |
-| Kudzu | Yes | 6.3 KB | 69.3 KB | **406 ms** | 6.0 ms | 28.5 ms | 14.7 ms | 19.1 ms | **68.3 ms** |
-| Next.js | Yes | 182.2 KB | 695.2 KB | 2950 ms | 6.8 ms | 34.1 ms | **9.0 ms** | 19.3 ms | 69.2 ms |
-| React CSR | No | 59.3 KB | 189.4 KB | 1028 ms | 9.5 ms | 35.3 ms | 10.1 ms | **17.8 ms** | 72.7 ms |
-| Vue CSR | No | 24.3 KB | 61.3 KB | 759 ms | 10.2 ms | 33.9 ms | 9.3 ms | 19.7 ms | 73.1 ms |
-| Qwik CSR | No | 22.2 KB | 64.1 KB | 604 ms | 15.6 ms | **20.0 ms** | 30.4 ms | 18.1 ms | 84.1 ms |
-| Svelte CSR | No | 12.9 KB | 33.1 KB | 845 ms | 5.4 ms | 64.4 ms | 11.2 ms | 19.1 ms | 100.1 ms |
-
-Astro is the hand-authored native DOM baseline in the interactive fixtures. 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. Kudzu's keyed-list operations total 68.3 ms, ahead of the React fixture's 72.7 ms and within 5.3 ms of Astro across all four operations.
+| Astro | Yes | **324 B** | **43.6 KB** | 869 ms | **3.9 ms** | 29.4 ms | 13.9 ms | **18.3 ms** | **65.5 ms** |
+| Kudzu | Yes | 5.0 KB | 60.3 KB | **437 ms** | 7.0 ms | 31.7 ms | **6.7 ms** | 22.0 ms | 67.4 ms |
+| Vue CSR | No | 24.3 KB | 61.3 KB | 813 ms | 11.3 ms | 37.5 ms | 10.1 ms | 21.4 ms | 80.3 ms |
+| Next.js | Yes | 182.2 KB | 695.2 KB | 3069 ms | 7.8 ms | 40.6 ms | 9.8 ms | 22.2 ms | 80.4 ms |
+| React CSR | No | 59.3 KB | 189.4 KB | 1073 ms | 10.5 ms | 40.2 ms | 9.9 ms | 21.4 ms | 82.0 ms |
+| Qwik CSR | No | 22.2 KB | 64.1 KB | 625 ms | 13.3 ms | **25.4 ms** | 37.1 ms | 24.4 ms | 100.2 ms |
+| Svelte CSR | No | 12.9 KB | 33.1 KB | 905 ms | 6.5 ms | 72.3 ms | 9.2 ms | 22.3 ms | 110.3 ms |
+
+Astro is the hand-authored native DOM baseline in the interactive fixtures. 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. In this run Kudzu's keyed-list operations total 67.4 ms, 1.9 ms behind Astro and 14.6 ms ahead of React across all four operations.
 
 Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
 

package/framework/build.mjs

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto"
 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 { transform } from "esbuild"
 import ts from "typescript"
 import { renderPage } from "./core.mjs"
 import { stateSchema } from "./dev-state.js"
@@ -15,7 +16,7 @@ const outputDirectory = join(root, "dist")
 
 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>`
 
-export async function build({ quiet = false } = {}) {
+export async function build({ quiet = false, minify = true } = {}) {
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
   await mkdir(workDirectory, { recursive: true })
@@ -69,32 +70,32 @@ export async function build({ quiet = false } = {}) {
   if (behaviorCount) {
     const runtimeFile = bindingCount || listCount || hasNativeHandlers ? "./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)
+    await writeJavaScript(join(assetsDirectory, "kudzu.js"), runtime, minify)
   }
-  if (bindingCount || hasNativeHandlers) await cp(new URL("./serialization.js", import.meta.url), join(assetsDirectory, "kudzu-serialization.js"))
+  if (bindingCount || hasNativeHandlers) await writeJavaScript(join(assetsDirectory, "kudzu-serialization.js"), await readFile(new URL("./serialization.js", import.meta.url), "utf8"), minify)
   if (bindingCount) {
-    await cp(new URL("./style.js", import.meta.url), join(assetsDirectory, "kudzu-style.js"))
+    await writeJavaScript(join(assetsDirectory, "kudzu-style.js"), await readFile(new URL("./style.js", import.meta.url), "utf8"), minify)
     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"')
       .replace('"./style.js"', '"./kudzu-style.js"')
-    await writeFile(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime)
+    await writeJavaScript(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime, minify)
   }
   if (listCount) {
     const listRuntime = (await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"))
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
-    await writeFile(join(assetsDirectory, "kudzu-list.js"), listRuntime)
+    await writeJavaScript(join(assetsDirectory, "kudzu-list.js"), listRuntime, minify)
   }
   if (hasNativeHandlers) {
     const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"))
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
       .replace('"./serialization.js"', '"./kudzu-serialization.js"')
-    await writeFile(join(assetsDirectory, "kudzu-native.js"), specializeNativeRuntime(nativeRuntime, nativeEvents, nativeModules))
+    await writeJavaScript(join(assetsDirectory, "kudzu-native.js"), specializeNativeRuntime(nativeRuntime, nativeEvents, nativeModules), minify)
   }
   for (const handlerModule of handlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
     await mkdir(resolve(output, ".."), { recursive: true })
-    await writeFile(output, handlerModule.code)
+    await writeJavaScript(output, handlerModule.code, minify)
   }
   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"))
@@ -113,12 +114,17 @@ function specializeNativeRuntime(source, events, modules) {
   return `${imports}\n${specializeEvents(source, events).replace(/const modules = new Map\(\[[^\n]*\]\)/, `const modules = new Map([${entries}])`)}`
 }
 
-function specializeRuntime(source, events, hasStateSeed) {
+export 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, compact] of JSON.parse(initialState)) browserState.set(id, compact ? value[1].map(row => Object.fromEntries(value[0].map((field, index) => [field, row[index]]))) : value)\n", "")
+    .replace(/^  if \(initialState\).*\n/m, "")
+}
+
+async function writeJavaScript(file, source, minify) {
+  const code = minify ? (await transform(source, { format: "esm", legalComments: "none", minify: true, target: "es2022" })).code : source
+  await writeFile(file, code)
 }
 
 export function parseDevPort(value) {
@@ -136,7 +142,7 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
   let revision = 0
   const session = randomUUID()
   try {
-    await build()
+    await build({ minify: false })
     revision++
   } catch (error) {
     buildError = errorText(error)
@@ -204,7 +210,7 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
     do {
       pending = false
       try {
-        await build({ quiet: true })
+        await build({ quiet: true, minify: false })
         buildError = undefined
         revision++
         console.log(`Rebuilt after ${changedFile ?? "source change"}`)

package/framework/core.d.ts

@@ -2,6 +2,12 @@ export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
 
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
 
+export interface RefObject<T> {
+  readonly current: T | null
+}
+
+export function useRef<T>(initialValue: null): RefObject<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

package/framework/core.mjs

@@ -9,6 +9,7 @@ const listMarker = Symbol("kudzu.list")
 const listFieldMarker = Symbol("kudzu.listField")
 const listExpressionMarker = Symbol("kudzu.listExpression")
 const listItemMarker = Symbol("kudzu.listItem")
+const refMarker = Symbol("kudzu.ref")
 const noSelectValue = Symbol("kudzu.no-select-value")
 
 let renderContext
@@ -37,6 +38,12 @@ export function useState(initialValue, name) {
   }]
 }
 
+export function useRef(initialValue) {
+  if (!renderContext) throw new Error("useRef() can only run while rendering a Kudzu component")
+  if (initialValue !== null) throw new Error("Kudzu DOM refs must initialize with null")
+  return { [refMarker]: true, id: `r${renderContext.nextRef++}`, current: null }
+}
+
 export function behavior(commands) {
   return {
     [behaviorMarker]: true,
@@ -158,6 +165,7 @@ function bindingDescriptor(value) {
 
 function serializeCapture(name, value, seen) {
   if (value?.[listItemMarker]) return { type: "list-item" }
+  if (value?.[refMarker]) return { type: "ref", id: value.id }
   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) }
@@ -189,7 +197,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}) {
-  renderContext = { nextState: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listFields: undefined, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false }
+  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listFields: undefined, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false }
 
   try {
     const body = await renderNode({ type: component, props: {} })
@@ -351,6 +359,12 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
 
   for (const [rawName, value] of Object.entries(props)) {
     if (rawName === "children" || rawName === "key") continue
+    if (rawName === "ref") {
+      if (!value?.[refMarker]) throw new Error("ref must be created by useRef(null)")
+      if (renderContext.listDepth) throw new Error("Refs are not supported in keyed lists")
+      attributes += ` data-k-ref="${value.id}"`
+      continue
+    }
     if (rawName === "selected" && selectValue !== noSelectValue) continue
     if (/^on/i.test(rawName) && !/^on[A-Z]/.test(rawName)) throw new Error(`${rawName} must use a camelCase event handler`)
     if (rawName.toLowerCase().startsWith("data-k-")) throw new Error(`${rawName} uses Kudzu's reserved data-k-* prefix`)

package/framework/serialization.js

@@ -2,6 +2,7 @@ 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 === "ref") return { get current() { return typeof document === "undefined" ? null : document.querySelector(`[data-k-ref="${value.id}"]`) } }
   if (value.type === "array") return value.value.map(deserialize)
   if (value.type === "object") {
     const object = value.nullPrototype ? Object.create(null) : {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "preview": "wrangler dev"
   },
   "dependencies": {
+    "esbuild": "^0.28.1",
     "typescript": "^5.9.2"
   },
   "devDependencies": {