@kudzujs/core 0.4.0 → 0.4.3

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
 
@@ -150,16 +150,25 @@ Map local array state directly to one keyed JSX element per item:
 
 ```tsx
 const [items, setItems] = useState([
-  { id: 1, name: "Oak" },
-  { id: 2, name: "Pine" }
+  { id: 1, name: "Oak", done: false },
+  { id: 2, name: "Pine", done: true }
 ])
 
-<ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
+<ul>{items.map(item =>
+  <li
+    key={item.id}
+    className={item.done ? "done" : "active"}
+    aria-label={`${item.name} item`}
+  >
+    {item.name.toUpperCase()}
+    <button onClick={() => setItems(items.filter(entry => entry.id !== item.id))}>Remove</button>
+  </li>
+)}</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. Each item must be a plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, plain objects, and primitive values.
+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.
 
-The MVP requires a direct local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. Item data may appear only as direct `item.<field>` text or attributes. Item-derived expressions, item-local handlers, nested conditions or lists, component tags, and fragments are rejected at build time. 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, fragments, and reactive `style`, `ref`, or `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 ## Normal JavaScript
 
@@ -181,6 +190,8 @@ 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.
+
 ## Rendering
 
 ```text

package/framework/README.md

@@ -6,11 +6,12 @@
 - `runtime.js`: command-only runtime for direct state-to-text patches.
 - `shared-runtime.js`: command runtime with capability commit and DOM lifecycle hooks, emitted only when needed.
 - `binding-runtime.js`: optional generic attributes, form properties, and conditional range patches.
-- `list-runtime.js`: optional keyed list validation, updates, moves, and cleanup.
+- `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 })
@@ -108,48 +112,149 @@ 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 = []
   const reactiveBindings = []
+  const listExpressions = []
   const handlerPath = `handlers/${relative(sourceDirectory, file).replaceAll(sep, "/").replace(/\.(?:ts|tsx)$/, ".js")}`
   const result = ts.transpileModule(source, {
     fileName: file,
@@ -159,7 +264,7 @@ async function compile(file) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, `/assets/${handlerPath}`)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, `/assets/${handlerPath}`)] },
     reportDiagnostics: true
   })
 
@@ -172,10 +277,11 @@ async function compile(file) {
   await mkdir(resolve(output, ".."), { recursive: true })
   await writeFile(output, result.outputText)
 
-  if (!nativeHandlers.length && !reactiveBindings.length) return undefined
+  if (!nativeHandlers.length && !reactiveBindings.length && !listExpressions.length) return undefined
   const moduleSource = [
     ...nativeHandlers.map(handler => printNativeHandler(handler)),
-    ...reactiveBindings.map(entry => printReactiveBinding(entry))
+    ...reactiveBindings.map(entry => printReactiveBinding(entry)),
+    ...listExpressions.map(entry => printListExpression(entry))
   ].join("\n")
   const moduleResult = ts.transpileModule(moduleSource, {
     compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext },
@@ -186,12 +292,13 @@ async function compile(file) {
   return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0 }
 }
 
-function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
+function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, handlerUrl) {
   return context => sourceFile => {
     const factory = context.factory
     const settersByFunction = new Map()
     const functions = new Map()
-    const listFieldExpressions = new WeakSet()
+    const listValues = new WeakMap()
+    const listEventItems = new WeakMap()
     let usesBehavior = false
     let usesBinding = false
     let usesConditional = false
@@ -237,13 +344,20 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
         return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, initializer)
       }
 
+      if (ts.isJsxExpression(node) && node.expression && listValues.has(node.expression)) {
+        return factory.updateJsxExpression(node, compileListValue(node.expression, listValues.get(node.expression), factory, listExpressions, handlerUrl))
+      }
+
+      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && listValues.has(node.initializer.expression)) {
+        return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, compileListValue(node.initializer.expression, listValues.get(node.initializer.expression), factory, listExpressions, handlerUrl)))
+      }
+
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
         const listParts = keyedListParts(node.expression, settersForNode(node, settersByFunction))
         if (listParts) {
           if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
-          validateKeyedList(listParts, sourceFile, listFieldExpressions)
+          validateKeyedList(listParts, sourceFile, settersForNode(node, settersByFunction), listValues, listEventItems)
           usesBehavior = true
-          usesBinding = true
           usesList = true
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
             listParts.state,
@@ -269,7 +383,6 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
 
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && !/^on/i.test(node.name.getText()) && !["style", "key", "ref", "dangerouslysetinnerhtml"].includes(node.name.getText().toLowerCase())) {
         const expression = node.initializer.expression
-        if (listFieldExpressions.has(expression)) return node
         const setters = settersForNode(node, settersByFunction)
         const usedStates = referencedStateNames(expression, setters)
         const captures = captureNames(expression, expression, setters)
@@ -283,7 +396,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
 
       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)
+        const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl, listEventItems.get(node))
         if (event) {
           usesBehavior = true
           return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, event))
@@ -302,7 +415,12 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
     if (nativeHandlers.length) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("nativeBehavior"), factory.createIdentifier("__kNativeBehavior")))
     if (usesBinding) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("binding"), factory.createIdentifier("__kBinding")))
     if (usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("conditional"), factory.createIdentifier("__kConditional")))
-    if (usesList) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("list"), factory.createIdentifier("__kList")))
+    if (usesList) {
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("list"), factory.createIdentifier("__kList")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listExpression"), factory.createIdentifier("__kListExpression")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listField"), factory.createIdentifier("__kListField")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listItem"), factory.createIdentifier("__kListItem")))
+    }
     if (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
       undefined,
@@ -331,7 +449,7 @@ function keyedListParts(expression, setters) {
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
 }
 
-function validateKeyedList(parts, sourceFile, listFieldExpressions) {
+function validateKeyedList(parts, sourceFile, setters, listValues, listEventItems) {
   const fail = (node, message) => {
     const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
@@ -341,27 +459,112 @@ function validateKeyedList(parts, sourceFile, listFieldExpressions) {
     if (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(node, "Keyed list items must use intrinsic JSX elements")
   }
   const visit = node => {
+    if (ts.isJsxFragment(node)) fail(node, "Fragments are not supported in keyed lists")
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) validateElement(node)
-    if (node !== parts.root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map") fail(node, "Nested keyed lists are not supported")
+    if (node !== parts.root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, "Nested keyed lists are not supported")
     if (ts.isJsxSpreadAttribute(node) && referencesIdentifier(node.expression, parts.item)) fail(node, "Keyed list item spreads are not supported")
-    if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.getText())) fail(node, "Item-local handlers are not supported in keyed lists")
+    if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.getText())) {
+      listEventItems.set(node, parts.item)
+      return
+    }
     if (ts.isJsxExpression(node) && node.expression) {
       const expression = unwrapExpression(node.expression)
+      if (conditionalParts(expression) && containsJsx(expression)) fail(node, "Nested reactive conditions are not supported in keyed lists")
       const field = directProperty(expression, parts.item)
-      const isRootKey = node.parent?.parent === parts.root && ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "key"
+      const isRootKey = ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "key"
+      if (field && ["__proto__", "constructor", "prototype"].includes(field)) fail(node, `Keyed list item property "${field}" is not supported`)
       if (field && ts.isJsxAttribute(node.parent) && ["style", "ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
-      if (isRootKey || field) {
-        if (field) listFieldExpressions.add(node.expression)
+      if (isRootKey) return
+      if (field) {
+        listValues.set(node.expression, { field })
+        return
+      }
+      if (referencesIdentifier(expression, parts.item)) {
+        validateListExpression(expression, parts.item, node, fail)
+        if (ts.isJsxAttribute(node.parent) && ["style", "ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
+        listValues.set(node.expression, { item: parts.item })
         return
       }
-      if (conditionalParts(expression)) fail(node, "Nested reactive conditions are not supported in keyed lists")
-      if (referencesIdentifier(expression, parts.item)) fail(node, `Keyed list item expressions must be direct ${parts.item}.<field> reads`)
     }
     ts.forEachChild(node, visit)
   }
   visit(parts.root)
 }
 
+const pureListMethods = new Set(["at", "charAt", "charCodeAt", "concat", "endsWith", "includes", "indexOf", "join", "lastIndexOf", "padEnd", "padStart", "repeat", "replace", "replaceAll", "slice", "startsWith", "substring", "toLowerCase", "toUpperCase", "trim", "trimEnd", "trimStart"])
+const mutatingListMethods = new Set(["copyWithin", "fill", "pop", "push", "reverse", "shift", "sort", "splice", "unshift"])
+const pureMathMethods = new Set(["abs", "ceil", "floor", "max", "min", "pow", "round", "sign", "sqrt", "trunc"])
+const pureListGlobals = new Set(["Boolean", "Infinity", "Math", "NaN", "Number", "String", "undefined"])
+const assignmentOperators = new Set([
+  ts.SyntaxKind.EqualsToken, ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.MinusEqualsToken,
+  ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskAsteriskEqualsToken, ts.SyntaxKind.SlashEqualsToken,
+  ts.SyntaxKind.PercentEqualsToken, ts.SyntaxKind.LessThanLessThanEqualsToken, ts.SyntaxKind.GreaterThanGreaterThanEqualsToken,
+  ts.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken, ts.SyntaxKind.AmpersandEqualsToken, ts.SyntaxKind.BarEqualsToken,
+  ts.SyntaxKind.CaretEqualsToken, ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.AmpersandAmpersandEqualsToken,
+  ts.SyntaxKind.QuestionQuestionEqualsToken
+])
+
+function validateListExpression(expression, item, source, fail) {
+  const visit = node => {
+    if (ts.isElementAccessExpression(node) && referencesIdentifier(node.expression, item)) {
+      const key = node.argumentExpression
+      if (!ts.isStringLiteral(key) && !ts.isNumericLiteral(key)) fail(source, "Derived keyed list item computed properties require a direct string or numeric literal key")
+      if (ts.isStringLiteral(key) && ["__proto__", "constructor", "prototype"].includes(key.text)) fail(source, `Derived keyed list item property "${key.text}" is not supported`)
+    }
+    if (ts.isPropertyAccessExpression(node) && ["__proto__", "constructor", "prototype"].includes(node.name.text) || ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) && ["__proto__", "constructor", "prototype"].includes(node.argumentExpression.text)) {
+      fail(source, "Derived keyed list item expressions cannot read __proto__, prototype, or constructor")
+    }
+    if (ts.isBinaryExpression(node) && assignmentOperators.has(node.operatorToken.kind) || ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)) {
+      fail(source, "Derived keyed list item expressions must be pure; assignments and updates are not supported")
+    }
+    if (ts.isDeleteExpression(node) || ts.isAwaitExpression(node) || ts.isNewExpression(node) || ts.isYieldExpression(node)) {
+      fail(source, "Derived keyed list item expressions must be synchronous and side-effect free; delete, await, yield, and new are not supported")
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isTaggedTemplateExpression(node)) {
+      fail(source, "Derived keyed list item expressions cannot create or invoke arbitrary functions")
+    }
+    if (ts.isCallExpression(node)) {
+      if (ts.isPropertyAccessExpression(node.expression)) {
+        const method = node.expression.name.text
+        if (mutatingListMethods.has(method)) fail(source, `Derived keyed list item expressions cannot call mutating method "${method}"`)
+        const receiver = node.expression.expression
+        const mathCall = ts.isIdentifier(receiver) && receiver.text === "Math" && pureMathMethods.has(method)
+        if (!mathCall && !pureListMethods.has(method)) fail(source, `Derived keyed list item expressions cannot call arbitrary method "${method}"`)
+      } else if (!ts.isIdentifier(node.expression) || !["Boolean", "Number", "String"].includes(node.expression.text)) {
+        fail(source, "Derived keyed list item expressions cannot call arbitrary functions")
+      }
+    }
+    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && node.text !== item && !pureListGlobals.has(node.text)) {
+      fail(source, `Derived keyed list item expression identifier "${node.text}" is not allowed`)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(expression)
+}
+
+function containsJsx(root) {
+  let found = false
+  const visit = node => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) found = true
+    if (!found) ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return found
+}
+
+function compileListExpression(read, expression, item, factory, listExpressions, handlerUrl) {
+  const exportName = `listExpression${listExpressions.length}`
+  listExpressions.push({ exportName, expression, item })
+  return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)])
+}
+
+function compileListValue(expression, entry, factory, listExpressions, handlerUrl) {
+  const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), expression)
+  return entry.field
+    ? factory.createCallExpression(factory.createIdentifier("__kListField"), undefined, [read, factory.createStringLiteral(entry.field)])
+    : compileListExpression(read, expression, entry.item, factory, listExpressions, handlerUrl)
+}
+
 function directProperty(expression, objectName) {
   const value = unwrapExpression(expression)
   if (!ts.isPropertyAccessExpression(value) || !ts.isIdentifier(value.expression)) return undefined
@@ -454,10 +657,11 @@ function factoryNull() {
   return ts.factory.createNull()
 }
 
-function compileEvent(expression, setters, functions, factory, nativeHandlers, handlerUrl) {
+function compileEvent(expression, setters, functions, factory, nativeHandlers, handlerUrl, listItem) {
   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
 
@@ -469,18 +673,45 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
     factory.createStringLiteral(name),
     factory.createIdentifier(name)
   ]))
-  const scope = [...captures].map(name => factory.createArrayLiteralExpression([
-    factory.createStringLiteral(name),
-    factory.createIdentifier(name)
-  ]))
   return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
     factory.createStringLiteral(handlerUrl),
     factory.createStringLiteral(exportName),
     factory.createArrayLiteralExpression(states),
-    factory.createArrayLiteralExpression(scope)
+    factory.createArrayLiteralExpression([...captures].map(name => factory.createArrayLiteralExpression([
+      factory.createStringLiteral(name),
+      name === listItem ? factory.createCallExpression(factory.createIdentifier("__kListItem"), undefined, []) : factory.createIdentifier(name)
+    ])))
   ])
 }
 
+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)
 }
@@ -681,6 +912,19 @@ function printReactiveBinding({ exportName, expression, captures, states }) {
   }
 }
 
+function printListExpression({ exportName, expression, item }) {
+  const declaration = ts.factory.createFunctionDeclaration(
+    [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    undefined,
+    exportName,
+    undefined,
+    [ts.factory.createParameterDeclaration(undefined, undefined, item)],
+    undefined,
+    ts.factory.createBlock([ts.factory.createReturnStatement(expression)], true)
+  )
+  return ts.createPrinter().printNode(ts.EmitHint.Unspecified, declaration, expression.getSourceFile())
+}
+
 function scopeRead(factory, name) {
   return factory.createCallExpression(
     factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "scope"),

package/framework/core.d.ts

@@ -8,6 +8,9 @@ export function binding(value: unknown, module: string, handler: string, states:
 export function bindingValue(value: unknown): unknown
 export function conditional(kind: "and" | "ternary", value: unknown, truthy: () => unknown, falsy: () => unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
 export function list(items: unknown, keyField: string, render: (item: unknown) => unknown): unknown
+export function listField(read: () => unknown, field: string): unknown
+export function listExpression(read: () => unknown, module: string, handler: string): unknown
+export function listItem(): unknown
 
 export function renderPage(
   component: (props: Record<string, never>) => unknown | Promise<unknown>,

package/framework/core.mjs

@@ -5,6 +5,8 @@ const bindingMarker = Symbol("kudzu.binding")
 const conditionalMarker = Symbol("kudzu.conditional")
 const listMarker = Symbol("kudzu.list")
 const listFieldMarker = Symbol("kudzu.listField")
+const listExpressionMarker = Symbol("kudzu.listExpression")
+const listItemMarker = Symbol("kudzu.listItem")
 const noSelectValue = Symbol("kudzu.no-select-value")
 
 let renderContext
@@ -79,13 +81,27 @@ export function list(items, keyField, render) {
   return { [listMarker]: true, items, keyField, render }
 }
 
+export function listField(read, field) {
+  return { [listFieldMarker]: true, field, value: renderContext?.listTemplate ? undefined : read() }
+}
+
+export function listExpression(read, module, handler) {
+  const value = renderContext?.listTemplate ? undefined : read()
+  if (value && typeof value.then === "function") throw new Error("Derived keyed list item expressions must return synchronous values")
+  return { [listExpressionMarker]: true, module, handler, value }
+}
+
+export function listItem() {
+  return { [listItemMarker]: true }
+}
+
 function validListKey(key) {
   return typeof key === "string" || typeof key === "number" && Number.isFinite(key)
 }
 
 function assertListItem(item) {
   const prototype = item && typeof item === "object" ? Object.getPrototypeOf(item) : undefined
-  if (!item || Array.isArray(item) || prototype !== Object.prototype && prototype !== null) throw new Error("Keyed list items must be plain objects")
+  if (!item || Array.isArray(item) || prototype !== Object.prototype) throw new Error("Keyed list items must be ordinary plain objects")
 }
 
 function assertListValue(value, seen) {
@@ -93,7 +109,7 @@ function assertListValue(value, seen) {
   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 && prototype !== null) throw new Error("Keyed list items must contain only arrays and plain objects")
+  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")
   seen.add(value)
   const descriptors = Object.getOwnPropertyDescriptors(value)
@@ -139,6 +155,7 @@ function bindingDescriptor(value) {
 }
 
 function serializeCapture(name, value, seen) {
+  if (value?.[listItemMarker]) return { type: "list-item" }
   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) }
@@ -170,7 +187,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, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false }
+  renderContext = { nextState: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, 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: {} })
@@ -290,6 +307,10 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node?.[listFieldMarker]) {
     return `<template data-k-list-text="${escapeAttribute(node.field)}"></template>${escapeHtml(node.value ?? "")}<template data-k-list-text-end></template>`
   }
+  if (node?.[listExpressionMarker]) {
+    const descriptor = { module: node.module, handler: node.handler }
+    return `<template data-k-list-expression='${escapeJsonAttribute(descriptor)}'></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
+  }
   if (!node || typeof node !== "object" || !("type" in node)) {
     throw new Error(`Cannot render ${String(node)}`)
   }
@@ -308,6 +329,8 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   let attributes = ""
   const attributeBindings = []
   const listAttributes = []
+  const listExpressionAttributes = []
+  const listEvents = []
 
   if (renderContext.listRoot) {
     const root = renderContext.listRoot
@@ -327,15 +350,17 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     }
 
     if (/^on[A-Z]/.test(rawName)) {
-      const event = rawName.slice(2).toLowerCase()
+        const event = rawName.slice(2).toLowerCase()
       if (value?.[behaviorMarker]) {
         const commands = JSON.stringify(value.commands)
         attributes += ` data-k-on-${event}='${escapeJsonAttribute(value.commands)}'`
         renderContext.events.push({ event, commands: value.commands })
       } else if (value?.[nativeBehaviorMarker]) {
-        const native = { module: value.module, handler: value.handler, states: value.states, scope: value.scope }
+        const template = { module: value.module, handler: value.handler, states: value.states, scope: value.scope }
+        const native = template
         attributes += ` data-k-native-${event}='${escapeJsonAttribute(native)}'`
         renderContext.events.push({ event, native })
+        if (renderContext.listDepth && Object.values(template.scope).some(entry => entry?.type === "list-item")) listEvents.push([event, template])
         renderContext.hasNativeBehaviors = true
       } else {
         throw new Error(`${rawName} must reference a compilable event handler`)
@@ -351,6 +376,11 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
       listAttributes.push([name, value.field])
       continue
     }
+    if (value?.[listExpressionMarker]) {
+      attributes += renderAttribute(name, value.value)
+      listExpressionAttributes.push([name, value.module, value.handler])
+      continue
+    }
     if (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
@@ -382,6 +412,8 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
 
   if (attributeBindings.length) attributes += ` data-k-bind-attrs='${escapeJsonAttribute(attributeBindings)}'`
   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 (tag === "option" && selectValue !== noSelectValue && String(optionValue(props)) === (selectValue == null ? "" : String(selectValue))) attributes += " selected"
 
@@ -394,17 +426,16 @@ async function renderList(node, namespace, selectValue) {
   if (namespace) throw new Error(`Reactive keyed lists are not supported inside ${namespace}`)
   const id = `l${renderContext.nextList++}`
   const descriptor = { id, state: node.items.id, key: node.keyField }
-  const itemProxy = value => new Proxy({}, {
-    get: (_, field) => ({ [listFieldMarker]: true, field: String(field), value: value?.[field] })
-  })
   renderContext.listDepth++
   try {
+    renderContext.listTemplate = true
     renderContext.listRoot = { id, template: true }
-    const template = await renderNode(node.render(itemProxy(undefined)), namespace, selectValue)
+    const template = await renderNode(node.render({}), namespace, selectValue)
     let current = ""
+    renderContext.listTemplate = false
     for (const item of node.items.value) {
       renderContext.listRoot = { id, key: item[node.keyField], template: false }
-      current += await renderNode(node.render(itemProxy(item)), namespace, selectValue)
+      current += await renderNode(node.render(item), namespace, selectValue)
     }
     renderContext.lists.push(descriptor)
     renderContext.hasBehaviors = true
@@ -412,6 +443,7 @@ async function renderList(node, namespace, selectValue) {
     return `<template data-k-list='${escapeJsonAttribute(descriptor)}'>${template}</template>${current}<template data-k-list-end="${id}"></template>`
   } finally {
     renderContext.listRoot = undefined
+    renderContext.listTemplate = false
     renderContext.listDepth--
   }
 }

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

@@ -3,6 +3,8 @@ import { browserState, mountDom, registerCommitter, registerMountHook, registerU
 const listTargets = new Map()
 const listRegistrations = new WeakMap()
 const mountedLists = new WeakSet()
+const imports = new Map()
+const revisions = new WeakMap()
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -97,20 +99,62 @@ function updateList(list) {
 }
 
 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 value = item?.[marker.dataset.kListText]
-    let end = marker.nextSibling
-    while (end && !(end.nodeType === Node.ELEMENT_NODE && end.matches("template[data-k-list-text-end]"))) end = end.nextSibling
-    if (!end) throw new Error("Keyed list text marker has no end")
-    const range = marker.ownerDocument.createRange()
-    range.setStartAfter(marker)
-    range.setEndBefore(end)
-    range.deleteContents()
-    end.before(marker.ownerDocument.createTextNode(value == null ? "" : String(value)))
+    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 of matching(root, "[data-k-list-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 => {
+      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)) {
+      evaluate({ module, handler }, item).then(value => {
+        if (revisions.get(root) === revision && root.isConnected) patchBinding(node, target, value)
+      }).catch(error => console.error(error))
+    }
+  }
+}
+
+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 range = marker.ownerDocument.createRange()
+  range.setStartAfter(marker)
+  range.setEndBefore(end)
+  range.deleteContents()
+  end.before(marker.ownerDocument.createTextNode(value == null ? "" : String(value)))
+}
+
+function evaluate(descriptor, item) {
+  let module = imports.get(descriptor.module)
+  if (!module) {
+    module = import(descriptor.module)
+    imports.set(descriptor.module, module)
+  }
+  return module.then(exports => {
+    const value = exports[descriptor.handler](item)
+    if (value && typeof value.then === "function") throw new Error("Derived keyed list item expressions must return synchronous values")
+    return value
+  })
+}
+
+function serializeItem(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") return value
+  if (Array.isArray(value)) return { type: "array", value: value.map(serializeItem) }
+  return { type: "object", nullPrototype: false, value: Object.entries(value).map(([key, entry]) => [key, serializeItem(entry)]) }
 }
 
 function patchBinding(node, target, value) {
@@ -142,7 +186,7 @@ function validListKey(key) {
 
 function assertListItem(item) {
   const prototype = item && typeof item === "object" ? Object.getPrototypeOf(item) : undefined
-  if (!item || Array.isArray(item) || prototype !== Object.prototype && prototype !== null) throw new Error("Keyed list items must be plain objects")
+  if (!item || Array.isArray(item) || prototype !== Object.prototype) throw new Error("Keyed list items must be ordinary plain objects")
 }
 
 function assertListValue(value, seen) {
@@ -150,7 +194,7 @@ function assertListValue(value, seen) {
   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 && prototype !== null) throw new Error("Keyed list items must contain only arrays and plain objects")
+  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")
   seen.add(value)
   const descriptors = Object.getOwnPropertyDescriptors(value)
@@ -183,3 +227,7 @@ function matching(root, selector) {
 function isStringBooleanAttribute(name) {
   return name.startsWith("aria-") || name.startsWith("data-")
 }
+
+function capitalize(value) {
+  return value[0].toUpperCase() + value.slice(1)
+}

package/framework/native-runtime.js

@@ -39,19 +39,38 @@ if (typeof document !== "undefined") {
   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
-
-      const native = JSON.parse(target.dataset[`kNative${capitalize(eventName)}`])
-      let modulePromise = modules.get(native.module)
-      if (!modulePromise) {
-        modulePromise = import(native.module)
-        modules.set(native.module, modulePromise)
+      try {
+        dispatchNative(event, snapshotNativeTargets(event, eventName), modules).catch(error => console.error(error))
+      } catch (error) {
+        console.error(error)
       }
-      modulePromise
-        .then(module => module[native.handler](createNativeContext(browserState, native.states, commitDom, native.scope), delegatedEvent(event, target)))
-        .catch(error => console.error(error))
-    }, true)
+    })
+  }
+}
+
+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)}`]) })
+  }
+  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)
+    }
   }
 }
 

package/package.json

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