@kudzujs/core 0.4.1 → 0.4.5

package/README.md

@@ -77,7 +77,7 @@ export default function HomePage() {
 npm run dev
 ```
 
-Pages live in `src/pages`; `index.tsx` maps to `/`. Production output is written to `dist/`.
+Pages live in `src/pages`; `index.tsx` maps to `/`. `npm run dev` serves locally on `127.0.0.1`, reloads the browser after successful rebuilds, and shows build failures in an error overlay. Across that full-page reload, compatible Kudzu logical state is briefly preserved by route-unique state variable name for the current pathname, query, and hash, including controlled properties, conditions, and keyed-list arrays. Renamed, removed, and duplicate-named state is skipped. Uncontrolled DOM state, focus, selection, and imperative DOM mutations are not preserved. Set `PORT` to change the default port of `3000`. The development client and state snapshot are dev-only; production output in `dist/` is unaffected.
 
 ## State Semantics
 
@@ -166,7 +166,7 @@ const [items, setItems] = useState([
 )}</ul>
 ```
 
-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 delegated events 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.
+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>`.
 
@@ -190,7 +190,7 @@ async function load() {
 
 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.
 
-Native handlers are delegated after normal event bubbling and run from the target toward matching Kudzu ancestors in deterministic order. Delegated handlers cannot call or reference `preventDefault`, `stopPropagation`, or `stopImmediatePropagation`; the compiler rejects those methods because external ESM cannot apply them with correct synchronous DOM semantics.
+Native handlers use direct DOM listeners with normal `currentTarget`, bubbling, default-action, and propagation semantics. Handler modules load before listener registration, so `preventDefault`, `stopPropagation`, and `stopImmediatePropagation` work synchronously as expected.
 
 ## Rendering
 
@@ -249,13 +249,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 | **373 ms** |
-| Astro | Yes | **158 B** | **365 B** | 877 ms |
-| Svelte CSR | No | 10.5 KB | 26.9 KB | 837 ms |
-| Qwik CSR | No | 20.6 KB | 57.8 KB | 626 ms |
-| Vue CSR | No | 24.0 KB | 60.3 KB | 778 ms |
-| React CSR | No | 59.2 KB | 189.0 KB | 1049 ms |
-| Next.js | Yes | 182.1 KB | 652.2 KB | 3099 ms |
+| 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 |
 
 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.
 
@@ -265,15 +265,31 @@ Same content and CSS across every fixture:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| 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.
+| 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 |
+
+### 1,000-item Keyed List
+
+The list starts with 1,000 keyed items, then updates every label, reverses the order, removes odd IDs, and adds 500 items. Browser timings are medians from seven fresh headless Chrome runs.
+
+| Framework | Initial content | Initial JS gzip | Total output | Build | Update | Reverse | Remove | Add | Operations total |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| Astro | Yes | **324 B** | **43.6 KB** | 867 ms | **3.5 ms** | **25.4 ms** | 10.7 ms | **18.0 ms** | **57.6 ms** |
+| Kudzu | Yes | 5.7 KB | 180.8 KB | **417 ms** | 8.3 ms | 28.5 ms | **10.2 ms** | 20.5 ms | **67.5 ms** |
+| Vue CSR | No | 24.3 KB | 61.3 KB | 771 ms | 9.7 ms | 31.3 ms | 9.4 ms | 18.1 ms | 68.5 ms |
+| React CSR | No | 59.3 KB | 189.4 KB | 1024 ms | 8.7 ms | 32.3 ms | 12.4 ms | 18.1 ms | 71.5 ms |
+| Next.js | Yes | 182.2 KB | 695.2 KB | 3049 ms | 6.7 ms | 35.0 ms | 16.3 ms | 19.4 ms | 77.4 ms |
+| Qwik CSR | No | 22.2 KB | 64.1 KB | 602 ms | 14.5 ms | 19.9 ms | 31.3 ms | 18.9 ms | 84.6 ms |
+| Svelte CSR | No | 12.9 KB | 33.1 KB | 859 ms | 5.2 ms | 65.4 ms | 10.7 ms | 19.9 ms | 101.2 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 67.5 ms, ahead of the React fixture's 71.5 ms and within 9.9 ms of Astro 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.
 
 ## Development
 

package/framework/README.md

@@ -9,8 +9,9 @@
 - `list-runtime.js`: optional keyed list validation, external item-expression evaluation, dynamic item-handler scopes, moves, and cleanup.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
+- `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators live under `dist/assets/handlers/`.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators live under `dist/assets/handlers/`. The dev server derives stable state identities from route-unique variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/build.mjs

@@ -1,9 +1,11 @@
 import { createServer } from "node:http"
+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 ts from "typescript"
 import { renderPage } from "./core.mjs"
+import { stateSchema } from "./dev-state.js"
 
 const root = process.cwd()
 const sourceDirectory = join(root, "src")
@@ -11,6 +13,8 @@ const pagesDirectory = join(sourceDirectory, "pages")
 const workDirectory = join(root, ".kudzu")
 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 } = {}) {
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
@@ -60,12 +64,13 @@ export async function build({ quiet = false } = {}) {
   await mkdir(assetsDirectory, { recursive: true })
   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()
+  const nativeModules = handlerModules.filter(module => module.hasNativeHandlers).map(module => `/assets/${module.path}`)
+  const hasNativeHandlers = nativeModules.length > 0
   if (behaviorCount) {
-    const runtimeFile = bindingCount || listCount ? "./shared-runtime.js" : "./runtime.js"
+    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)
   }
-  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"))
@@ -80,9 +85,9 @@ export async function build({ quiet = false } = {}) {
   }
   if (hasNativeHandlers) {
     const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"))
-      .replace('"./runtime.js"', '"./kudzu.js"')
+      .replace('"./shared-runtime.js"', '"./kudzu.js"')
       .replace('"./serialization.js"', '"./kudzu-serialization.js"')
-    await writeFile(join(assetsDirectory, "kudzu-native.js"), specializeEvents(nativeRuntime, nativeEvents))
+    await writeFile(join(assetsDirectory, "kudzu-native.js"), specializeNativeRuntime(nativeRuntime, nativeEvents, nativeModules))
   }
   for (const handlerModule of handlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
@@ -100,6 +105,12 @@ function specializeEvents(source, events) {
   return source.replace(/const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`)
 }
 
+function specializeNativeRuntime(source, events, modules) {
+  const imports = modules.map((module, index) => `import * as __kNativeModule${index} from ${JSON.stringify(module)}`).join("\n")
+  const entries = modules.map((module, index) => `[${JSON.stringify(module)}, __kNativeModule${index}]`).join(",")
+  return `${imports}\n${specializeEvents(source, events).replace(/const modules = new Map\(\[[^\n]*\]\)/, `const modules = new Map([${entries}])`)}`
+}
+
 function specializeRuntime(source, events, hasStateSeed) {
   const specialized = specializeEvents(source, events)
   if (hasStateSeed) return specialized
@@ -108,44 +119,144 @@ function specializeRuntime(source, events, hasStateSeed) {
     .replace("  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)\n", "")
 }
 
-export async function dev() {
-  await build()
+export function parseDevPort(value) {
+  if (value === undefined || value.trim() === "") return 3000
+  if (!/^\d+$/.test(value)) throw new Error(`Invalid dev server port: ${value}`)
+  const port = Number(value)
+  if (port > 65535) throw new Error(`Invalid dev server port: ${value}`)
+  return port
+}
+
+export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid dev server port: ${port}`)
+
+  let buildError
+  let revision = 0
+  const session = randomUUID()
+  try {
+    await build()
+    revision++
+  } catch (error) {
+    buildError = errorText(error)
+    console.error(error)
+  }
+
+  const clients = new Set()
 
   const server = createServer(async (request, response) => {
     try {
-      const pathname = decodeURIComponent(new URL(request.url, "http://localhost").pathname)
+      const url = new URL(request.url, "http://localhost")
+      const pathname = decodeURIComponent(url.pathname)
+      if (pathname === "/__kudzu_reload") {
+        response.writeHead(200, {
+          "content-type": "text/event-stream; charset=utf-8",
+          "cache-control": "no-cache, no-transform",
+          connection: "keep-alive"
+        })
+        response.write(": connected\n\n")
+        clients.add(response)
+        request.on("close", () => clients.delete(response))
+        if (buildError) sendEvent(response, "build-error", buildError)
+        else if (url.searchParams.get("session") !== session || url.searchParams.get("revision") !== String(revision)) sendEvent(response, "reload")
+        return
+      }
+      if (pathname === "/__kudzu_dev.js") {
+        response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" })
+        response.end(await readFile(new URL("./dev-state.js", import.meta.url)))
+        return
+      }
+
       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) })
+      const isHtml = extname(file) === ".html"
+      const content = isHtml
+        ? injectDevClient(buildError ? errorPage(buildError) : await readFile(file, "utf8"), session, revision, buildError ? [] : await devSchema(pathname))
+        : await readFile(file)
+      response.writeHead(200, {
+        "content-type": contentType(file),
+        "cache-control": "no-store"
+      })
       response.end(content)
     } catch {
-      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" })
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" })
       response.end("Not found")
     }
   })
 
-  server.listen(3000, () => console.log("Kudzu dev server: http://localhost:3000"))
+  server.listen(port, "127.0.0.1", () => console.log(`Kudzu dev server: http://127.0.0.1:${server.address().port}`))
 
   let timer
-  const watcher = watch(sourceDirectory, { recursive: true })
-  for await (const event of watcher) {
-    clearTimeout(timer)
-    timer = setTimeout(async () => {
+  let rebuilding = false
+  let pending = false
+  let changedFile
+  const rebuild = async () => {
+    if (rebuilding) {
+      pending = true
+      return
+    }
+    rebuilding = true
+    do {
+      pending = false
       try {
         await build({ quiet: true })
-        console.log(`Rebuilt after ${event.filename ?? "source change"}`)
+        buildError = undefined
+        revision++
+        console.log(`Rebuilt after ${changedFile ?? "source change"}`)
+        for (const client of clients) sendEvent(client, "reload")
       } catch (error) {
+        buildError = errorText(error)
         console.error(error)
+        for (const client of clients) sendEvent(client, "build-error", buildError)
       }
-    }, 80)
+    } while (pending)
+    rebuilding = false
+  }
+  const watcher = watch(sourceDirectory, { recursive: true })
+  for await (const event of watcher) {
+    changedFile = event.filename
+    clearTimeout(timer)
+    timer = setTimeout(rebuild, 80)
+  }
+}
+
+function injectDevClient(html, session, revision, schema) {
+  return `${html}${devClient(session, revision, schema)}`
+}
+
+async function devSchema(pathname) {
+  try {
+    const plan = JSON.parse(await readFile(join(workDirectory, "kudzu-plan.json"), "utf8"))
+    const route = pathname.replace(/\/(?:index\.html)?$/, "") || "/"
+    return stateSchema(plan.routes.find(entry => entry.route === route)?.states ?? [])
+  } catch {
+    return []
   }
 }
 
+function inlineJson(value) {
+  return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029")
+}
+
+function errorPage(error) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Kudzu build error</title></head><body><div id="__kudzu_error" role="alert" aria-live="assertive" style="position:fixed;inset:0;overflow:auto;padding:2rem;background:#200;color:#fff;font:16px/1.5 ui-monospace,monospace"><strong>Kudzu build error</strong><pre style="white-space:pre-wrap">${escapeHtml(error)}</pre></div></body></html>`
+}
+
+function errorText(error) {
+  return String(error?.message ?? error)
+}
+
+function sendEvent(response, event, data = "") {
+  response.write(`event: ${event}\n${String(data).replaceAll("\r", "").split("\n").map(line => `data: ${line}\n`).join("")}\n`)
+}
+
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+}
+
 async function compile(file) {
   const source = await readFile(file, "utf8")
   const nativeHandlers = []
@@ -557,7 +668,6 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   if (ts.isIdentifier(expression)) expression = functions.get(expression.text)
   if (!expression || (!ts.isArrowFunction(expression) && !ts.isFunctionExpression(expression) && !ts.isFunctionDeclaration(expression))) return undefined
 
-  rejectNativeEventControls(expression)
   const optimized = compileOptimizedEvent(expression, setters, factory)
   if (optimized) return optimized
 
@@ -580,34 +690,6 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   ])
 }
 
-function rejectNativeEventControls(expression) {
-  const controls = new Set(["preventDefault", "stopPropagation", "stopImmediatePropagation"])
-  const found = new Set()
-  const eventAliases = new Set()
-  const parameter = expression.parameters[0]?.name
-  if (parameter && ts.isIdentifier(parameter)) eventAliases.add(parameter.text)
-  const visit = node => {
-    if (ts.isIdentifier(node) && controls.has(node.text)) found.add(node.text)
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isIdentifier(unwrapEventAlias(node.initializer)) && eventAliases.has(unwrapEventAlias(node.initializer).text)) {
-      eventAliases.add(node.name.text)
-    }
-    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(node.left) && ts.isIdentifier(unwrapEventAlias(node.right)) && eventAliases.has(unwrapEventAlias(node.right).text)) eventAliases.add(node.left.text)
-    if (ts.isElementAccessExpression(node) && ts.isIdentifier(unwrapEventAlias(node.expression)) && eventAliases.has(unwrapEventAlias(node.expression).text)) {
-      if (ts.isStringLiteral(node.argumentExpression) && controls.has(node.argumentExpression.text)) found.add(node.argumentExpression.text)
-      else if (!ts.isStringLiteral(node.argumentExpression)) for (const control of controls) found.add(control)
-    }
-    ts.forEachChild(node, visit)
-  }
-  for (const parameter of expression.parameters) visit(parameter)
-  visit(expression.body)
-  if (found.size) throw new Error(`Delegated native handlers do not support event control methods: ${[...found].sort().join(", ")}`)
-}
-
-function unwrapEventAlias(node) {
-  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node)) return unwrapEventAlias(node.expression)
-  return node
-}
-
 function nativeStateNames(expression, setters) {
   return referencedStateNames(expression.body, setters, expression)
 }

package/framework/core.mjs

@@ -320,6 +320,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
 
   const tag = node.type
   const props = node.props ?? {}
+  const directListText = props.children?.[listFieldMarker] ? props.children : undefined
   const childSelectValue = tag === "select"
     ? Object.hasOwn(props, "value") ? bindingValue(props.value) : noSelectValue
     : selectValue
@@ -414,12 +415,14 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
   if (listExpressionAttributes.length) attributes += ` data-k-list-expression-attrs='${escapeJsonAttribute(listExpressionAttributes)}'`
   if (listEvents.length) attributes += ` data-k-list-events='${escapeJsonAttribute(listEvents)}'`
+  if (directListText) attributes += ` data-k-list-text="${escapeAttribute(directListText.field)}"`
 
   if (tag === "option" && selectValue !== noSelectValue && String(optionValue(props)) === (selectValue == null ? "" : String(selectValue))) attributes += " selected"
 
   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, childNamespace, childSelectValue)}</${tag}>`
+  const children = directListText ? escapeHtml(directListText.value ?? "") : await renderNode(props.children, childNamespace, childSelectValue)
+  return `<${tag}${attributes}>${children}</${tag}>`
 }
 
 async function renderList(node, namespace, selectValue) {

package/framework/dev-state.js

@@ -0,0 +1,98 @@
+const maxAge = 10000
+
+export function stateSchema(states) {
+  const occurrences = new Map()
+  for (const { name } of states) if (typeof name === "string") occurrences.set(name, (occurrences.get(name) ?? 0) + 1)
+  return states.flatMap(({ id, name }) => {
+    return typeof id === "string" && occurrences.get(name) === 1 ? [[id, name]] : []
+  })
+}
+
+export function snapshotState(storage, route, state, schema, now = Date.now()) {
+  try {
+    storage.removeItem(storageKey(route))
+  } catch {
+    return false
+  }
+  try {
+    const identities = new Map(schema)
+    const values = [...state].flatMap(([id, value]) => {
+      const identity = identities.get(id)
+      return typeof identity === "string" && jsonSafe(value) ? [[identity, value]] : []
+    })
+    if (values.length) storage.setItem(storageKey(route), JSON.stringify({ time: now, values }))
+    return values.length > 0
+  } catch {
+    return false
+  }
+}
+
+export function restoreState(storage, route, state, schema, commit, now = Date.now()) {
+  let snapshot
+  try {
+    const raw = storage.getItem(storageKey(route))
+    if (raw === null) return []
+    storage.removeItem(storageKey(route))
+    snapshot = JSON.parse(raw)
+  } catch {
+    return []
+  }
+
+  if (!(state instanceof Map) || !Array.isArray(schema) || typeof commit !== "function") return []
+  if (!snapshot || !Number.isFinite(snapshot.time) || now < snapshot.time || now - snapshot.time > maxAge || !Array.isArray(snapshot.values)) return []
+  const ids = new Map(schema.flatMap(entry => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && typeof entry[1] === "string" ? [[entry[1], entry[0]]] : []))
+  const changes = []
+  const seen = new Set()
+  for (const entry of snapshot.values) {
+    if (!Array.isArray(entry) || entry.length !== 2) continue
+    const [identity, value] = entry
+    const id = ids.get(identity)
+    if (typeof identity !== "string" || seen.has(identity) || !state.has(id) || !jsonSafe(value) || shape(value) !== shape(state.get(id))) continue
+    seen.add(identity)
+    changes.push({ id, value, original: state.get(id) })
+  }
+  for (const { id, value } of changes) state.set(id, value)
+  try {
+    for (const { id } of changes) commit(id, state.get(id))
+  } catch {
+    for (const { id, original } of changes) state.set(id, original)
+    for (const { id } of changes) {
+      try { commit(id, state.get(id)) } catch {}
+    }
+    return []
+  }
+  return changes.map(({ id }) => id)
+}
+
+function storageKey(route) {
+  return `__kudzu_state:${route}`
+}
+
+function shape(value) {
+  if (Array.isArray(value)) return "array"
+  if (value === null) return "null"
+  return typeof value === "object" ? "object" : typeof value
+}
+
+function jsonSafe(value, seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true
+  if (typeof value === "number") return Number.isFinite(value) && !Object.is(value, -0)
+  if (!value || typeof value !== "object" || seen.has(value) || Object.getOwnPropertySymbols(value).length) return false
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) return false
+
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  if (Array.isArray(value)) {
+    if (Object.keys(descriptors).some(key => key !== "length" && !/^(0|[1-9]\d*)$/.test(key))) return false
+    if (Object.keys(value).length !== value.length) return false
+  }
+  seen.add(value)
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (Array.isArray(value) && key === "length") continue
+    if (!descriptor.enumerable || !("value" in descriptor) || !jsonSafe(descriptor.value, seen)) {
+      seen.delete(value)
+      return false
+    }
+  }
+  seen.delete(value)
+  return true
+}

package/framework/list-runtime.js

@@ -5,6 +5,8 @@ const listRegistrations = new WeakMap()
 const mountedLists = new WeakSet()
 const imports = new Map()
 const revisions = new WeakMap()
+const itemParts = new WeakMap()
+const itemPartsSelector = "[data-k-list-text],[data-k-list-attrs],[data-k-list-events],[data-k-list-expression],[data-k-list-expression-attrs]"
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -27,10 +29,13 @@ function mountLists(root) {
     mountedLists.add(start)
     const descriptor = JSON.parse(start.dataset.kList)
     const roots = [...start.ownerDocument.querySelectorAll("[data-k-list-item]")].filter(node => JSON.parse(node.dataset.kListItem)[0] === descriptor.id)
+    const items = browserState.get(descriptor.state)
+    for (const root of roots) listItemParts(root)
     const list = {
       start,
       descriptor,
       roots: new Map(roots.map(node => [keyToken(JSON.parse(node.dataset.kListItem)[1]), node])),
+      values: new Map(items.map(item => [keyToken(item[descriptor.key]), JSON.stringify(item)])),
       container: roots[0]?.parentNode,
       boundary: roots.length ? roots.at(-1).nextSibling : findEnd(start, descriptor.id)
     }
@@ -60,66 +65,105 @@ function updateList(list) {
   if (!Array.isArray(items)) throw new Error("Keyed list state must remain an array")
   const entries = []
   const keys = new Set()
+  const seen = new Set()
   for (const item of items) {
     const key = item?.[list.descriptor.key]
     if (!validListKey(key)) throw new Error(`Keyed list key "${list.descriptor.key}" must be a string or finite number`)
     assertListItem(item)
-    assertListValue(item, new Set())
+    assertListValue(item, seen, true)
     const token = keyToken(key)
     if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
     keys.add(token)
-    entries.push({ item, key, token })
+    entries.push({ item, key, token, value: JSON.stringify(item) })
   }
   const next = []
-  for (const { item, key, token } of entries) {
+  const values = new Map()
+  const parent = list.container ?? list.start.parentNode
+  const additions = parent.ownerDocument.createDocumentFragment()
+  let added = false
+  for (const { item, key, token, value } of entries) {
     let node = list.roots.get(token)
     if (!node) {
-      const fragment = list.start.content.cloneNode(true)
-      node = fragment.querySelector(`[data-k-list-root="${list.descriptor.id}"]`)
+      node = list.start.content.firstElementChild?.cloneNode(true)
+      if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
       if (!node) throw new Error("Keyed list template has no root element")
       node.removeAttribute("data-k-list-root")
       node.dataset.kListItem = JSON.stringify([list.descriptor.id, key])
       fillListItem(node, item)
-      ;(list.container ?? list.start.parentNode).insertBefore(fragment, list.boundary)
-      list.container ??= node.parentNode
-      mountDom(node)
-    } else {
+      additions.append(node)
+      added = true
+    } else if (list.values.get(token) !== value) {
       fillListItem(node, item)
     }
     next.push([token, node])
+    values.set(token, value)
   }
   for (const [token, node] of list.roots) {
     if (keys.has(token)) continue
     unmountDom(node)
     node.remove()
   }
-  const parent = list.container ?? list.start.parentNode
-  for (const [, node] of next) parent.insertBefore(node, list.boundary)
+  if (added) {
+    mountDom(additions)
+    parent.insertBefore(additions, list.boundary)
+    list.container ??= parent
+  }
+  let anchor = list.boundary
+  let misplaced = 0
+  for (let index = next.length - 1; index >= 0; index--) {
+    const node = next[index][1]
+    if (node.nextSibling !== anchor) misplaced++
+    anchor = node
+  }
+  if (misplaced > next.length / 2) {
+    const reordered = parent.ownerDocument.createDocumentFragment()
+    reordered.append(...next.map(([, node]) => node))
+    parent.insertBefore(reordered, list.boundary)
+  } else if (misplaced) {
+    anchor = list.boundary
+    for (let index = next.length - 1; index >= 0; index--) {
+      const node = next[index][1]
+      if (node.nextSibling !== anchor) parent.insertBefore(node, anchor)
+      anchor = node
+    }
+  }
   list.roots = new Map(next)
+  list.values = values
 }
 
 function fillListItem(root, item) {
   const revision = (revisions.get(root) ?? 0) + 1
   revisions.set(root, revision)
-  for (const marker of matching(root, "template[data-k-list-text]")) {
+  const parts = listItemParts(root)
+  for (const node of parts.directTexts) {
+    const text = item?.[node.dataset.kListText]
+    const value = text == null ? "" : String(text)
+    const current = node.firstChild
+    if (current?.nodeType === Node.TEXT_NODE && !current.nextSibling) {
+      if (current.data !== value) current.data = value
+    } else {
+      node.textContent = value
+    }
+  }
+  for (const marker of parts.texts) {
     patchListText(marker, "template[data-k-list-text-end]", item?.[marker.dataset.kListText])
   }
-  for (const node of matching(root, "[data-k-list-attrs]")) {
-    for (const [target, field] of JSON.parse(node.dataset.kListAttrs)) patchBinding(node, target, item?.[field])
+  for (const [node, attributes] of parts.attributes) {
+    for (const [target, field] of attributes) patchBinding(node, target, item?.[field])
   }
-  for (const node of matching(root, "[data-k-list-events]")) {
+  for (const node of parts.events) {
     for (const [event, native] of JSON.parse(node.dataset.kListEvents)) {
       native.scope = Object.fromEntries(Object.entries(native.scope).map(([name, value]) => [name, value?.type === "list-item" ? serializeItem(item) : value]))
       node.dataset[`kNative${capitalize(event)}`] = JSON.stringify(native)
     }
   }
-  for (const marker of matching(root, "template[data-k-list-expression]")) {
-    evaluate(JSON.parse(marker.dataset.kListExpression), item).then(value => {
+  for (const [marker, descriptor] of parts.expressions) {
+    evaluate(descriptor, item).then(value => {
       if (revisions.get(root) === revision && root.isConnected) patchListText(marker, "template[data-k-list-expression-end]", value)
     }).catch(error => console.error(error))
   }
-  for (const node of matching(root, "[data-k-list-expression-attrs]")) {
-    for (const [target, module, handler] of JSON.parse(node.dataset.kListExpressionAttrs)) {
+  for (const [node, attributes] of parts.expressionAttributes) {
+    for (const [target, module, handler] of attributes) {
       evaluate({ module, handler }, item).then(value => {
         if (revisions.get(root) === revision && root.isConnected) patchBinding(node, target, value)
       }).catch(error => console.error(error))
@@ -127,15 +171,36 @@ function fillListItem(root, item) {
   }
 }
 
+function listItemParts(root) {
+  let parts = itemParts.get(root)
+  if (parts) return parts
+  parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [] }
+  for (const node of matching(root, itemPartsSelector)) {
+    if (node.hasAttribute("data-k-list-text")) (node.tagName === "TEMPLATE" ? parts.texts : parts.directTexts).push(node)
+    if (node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
+    if (node.hasAttribute("data-k-list-events")) parts.events.push(node)
+    if (node.hasAttribute("data-k-list-expression")) parts.expressions.push([node, JSON.parse(node.dataset.kListExpression)])
+    if (node.hasAttribute("data-k-list-expression-attrs")) parts.expressionAttributes.push([node, JSON.parse(node.dataset.kListExpressionAttrs)])
+  }
+  itemParts.set(root, parts)
+  return parts
+}
+
 function patchListText(marker, endSelector, value) {
   let end = marker.nextSibling
   while (end && !(end.nodeType === Node.ELEMENT_NODE && end.matches(endSelector))) end = end.nextSibling
   if (!end) throw new Error("Keyed list text marker has no end")
+  const text = value == null ? "" : String(value)
+  const current = marker.nextSibling
+  if (current?.nodeType === Node.TEXT_NODE && current.nextSibling === end) {
+    if (current.data !== text) current.data = text
+    return
+  }
   const range = marker.ownerDocument.createRange()
   range.setStartAfter(marker)
   range.setEndBefore(end)
   range.deleteContents()
-  end.before(marker.ownerDocument.createTextNode(value == null ? "" : String(value)))
+  end.before(marker.ownerDocument.createTextNode(text))
 }
 
 function evaluate(descriptor, item) {
@@ -189,19 +254,19 @@ function assertListItem(item) {
   if (!item || Array.isArray(item) || prototype !== Object.prototype) throw new Error("Keyed list items must be ordinary plain objects")
 }
 
-function assertListValue(value, seen) {
+function assertListValue(value, seen, root = false) {
   if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0)) return
   if (!value || typeof value !== "object") throw new Error("Keyed list items must contain only JSON-safe values")
   if (seen.has(value)) throw new Error("Keyed list items must not contain cycles")
-  const prototype = Object.getPrototypeOf(value)
-  if (!Array.isArray(value) && prototype !== Object.prototype) throw new Error("Keyed list items must contain only arrays and ordinary plain objects")
-  if (Object.getOwnPropertySymbols(value).length) throw new Error("Keyed list items must not contain symbols")
+  if (!root && !Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) throw new Error("Keyed list items must contain only arrays and ordinary plain objects")
   seen.add(value)
-  const descriptors = Object.getOwnPropertyDescriptors(value)
-  if (Array.isArray(value) && Object.keys(descriptors).some(key => key !== "length" && !/^(0|[1-9]\d*)$/.test(key))) throw new Error("Keyed list arrays must not contain custom properties")
+  const keys = Reflect.ownKeys(value)
+  if (keys.some(key => typeof key === "symbol")) throw new Error("Keyed list items must not contain symbols")
+  if (Array.isArray(value) && keys.some(key => key !== "length" && !/^(0|[1-9]\d*)$/.test(key))) throw new Error("Keyed list arrays must not contain custom properties")
   if (Array.isArray(value) && Object.keys(value).length !== value.length) throw new Error("Keyed list arrays must not contain holes")
-  for (const [key, descriptor] of Object.entries(descriptors)) {
+  for (const key of keys) {
     if (Array.isArray(value) && key === "length") continue
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
     if (!descriptor.enumerable) throw new Error("Keyed list items must not contain non-enumerable properties")
     if (!("value" in descriptor)) throw new Error("Keyed list items must not contain accessors")
     assertListValue(descriptor.value, seen)

package/framework/native-runtime.js

@@ -1,6 +1,8 @@
-import { browserState, commitDom } from "./runtime.js"
+import { browserState, commitDom, registerMountHook, registerUnmountHook } from "./shared-runtime.js"
 import { deserialize } from "./serialization.js"
 
+const registrations = new WeakMap()
+
 export function createNativeContext(state, stateIds, commit, serializedScope = {}) {
   const changed = new Set()
   let scheduled = false
@@ -34,54 +36,44 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
 }
 
 if (typeof document !== "undefined") {
-  const modules = new Map()
-
   const eventNames = ["click", "input", "change", "submit", "keydown", "keyup"]
-  for (const eventName of eventNames) {
-    document.addEventListener(eventName, event => {
-      try {
-        dispatchNative(event, snapshotNativeTargets(event, eventName), modules).catch(error => console.error(error))
-      } catch (error) {
-        console.error(error)
-      }
-    })
-  }
+  const modules = new Map([])
+  const mount = root => mountNative(root, eventNames, modules)
+  registerMountHook(mount)
+  registerUnmountHook(unmountNative)
+  mount(document)
 }
 
-function snapshotNativeTargets(event, eventName) {
-  const selector = `[data-k-native-${eventName}]`
-  const targets = []
-  for (let target = event.target.closest(selector); target; target = target.parentElement?.closest(selector)) {
-    targets.push({ target, native: JSON.parse(target.dataset[`kNative${capitalize(eventName)}`]) })
+function mountNative(root, eventNames, modules) {
+  for (const eventName of eventNames) {
+    for (const node of matching(root, `[data-k-native-${eventName}]`)) {
+      const listeners = registrations.get(node) ?? new Map()
+      if (listeners.has(eventName)) continue
+      const listener = event => {
+        try {
+          const native = JSON.parse(node.dataset[`kNative${capitalize(eventName)}`])
+          const result = modules.get(native.module)[native.handler](createNativeContext(browserState, native.states, commitDom, native.scope), event)
+          if (result && typeof result.then === "function") result.catch(error => console.error(error))
+        } catch (error) {
+          console.error(error)
+        }
+      }
+      node.addEventListener(eventName, listener)
+      listeners.set(eventName, listener)
+      registrations.set(node, listeners)
+    }
   }
-  return targets
 }
 
-async function dispatchNative(event, targets, modules) {
-  for (const { target, native } of targets) {
-    let modulePromise = modules.get(native.module)
-    if (!modulePromise) {
-      modulePromise = import(native.module)
-      modules.set(native.module, modulePromise)
-    }
-    try {
-      const module = await modulePromise
-      const result = module[native.handler](createNativeContext(browserState, native.states, commitDom, native.scope), delegatedEvent(event, target))
-      if (result && typeof result.then === "function") result.catch(error => console.error(error))
-    } catch (error) {
-      console.error(error)
-    }
+function unmountNative(root) {
+  for (const node of matching(root, "*")) {
+    for (const [eventName, listener] of registrations.get(node) ?? []) node.removeEventListener(eventName, listener)
+    registrations.delete(node)
   }
 }
 
-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 matching(root, selector) {
+  return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
 }
 
 function capitalize(value) {

package/package.json

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