@kudzujs/core 0.3.0 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@ HTML-first TSX framework with synchronous state semantics and no virtual DOM.
 
 Kudzu keeps the familiar function-component, props, children, event-handler, and `useState` shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers compile to external ESM.
 
-> Experimental `0.3.x`: the compiler API and supported TSX surface may change.
+> Experimental `0.4.x`: the compiler API and supported TSX surface may change.
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -100,15 +100,28 @@ The handler above increments by two and patches its bound DOM once. Inspect the
 
 ## Reactive Attributes
 
-`className`, `disabled`, and controlled `value` accept normal state-dependent TSX expressions:
+`className`, `disabled`, controlled `value`, and controlled `checked` accept normal state-dependent TSX expressions. The same `value` binding works for inputs and selects:
 
 ```tsx
 <div className={active ? "active" : "idle"} />
 <button disabled={loading}>Save</button>
 <input value={name} onInput={event => setName(event.currentTarget.value)} />
+<input type="checkbox" checked={subscribed} onChange={event => setSubscribed(event.currentTarget.checked)} />
+<select value={theme} onChange={event => setTheme(event.currentTarget.value)} />
 ```
 
-Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property.
+Regular attributes use the same expressions without an allowlist:
+
+```tsx
+<button
+  aria-expanded={open}
+  data-state={open ? "open" : "closed"}
+  hidden={!visible}
+  title={open ? "Close menu" : "Open menu"}
+/>
+```
+
+Kudzu compiles derived expressions to external ESM and patches only the bound DOM attribute or property. `aria-*` and `data-*` boolean values serialize as `"true"` or `"false"`; ordinary false values remove the attribute. Reactive `style`, `ref`, and `dangerouslySetInnerHTML` remain unsupported.
 
 ## Conditional DOM
 
@@ -131,6 +144,23 @@ Logical state persists across branch switches, while uncontrolled DOM state rese
 
 Reactive conditional DOM currently targets the HTML namespace and is rejected inside SVG or MathML.
 
+## Keyed Lists
+
+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" }
+])
+
+<ul>{items.map(item => <li key={item.id}>{item.name}</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.
+
+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>`.
+
 ## Normal JavaScript
 
 Command-only setters use the smallest optimized path. Conditions, local variables, browser globals, events, and `async`/`await` compile to external ESM without `eval`, `new Function`, or inline executable code.
@@ -158,6 +188,7 @@ TSX
 ├─ static component      → HTML
 ├─ ordered state setter  → behavior command
 ├─ conditional child     → bounded DOM range
+├─ keyed state map       → keyed DOM moves
 └─ normal JS handler     → external ESM
 ```
 
@@ -185,12 +216,14 @@ Supported:
 - Synchronous and async event handlers
 - Serializable component-local captures
 - Direct text DOM patches
-- Reactive `className`, `disabled`, and controlled `value` patches
+- Reactive standard, `aria-*`, and `data-*` attributes
+- Controlled `value` and `checked` form properties
 - Conditional child `&&` and ternary DOM patches
+- Direct keyed local-state lists
 
 Not implemented yet:
 
-- Keyed lists and generalized JSX-valued locals
+- Generalized JSX-valued locals and non-direct list item expressions
 - Server actions and request-time SSR
 - Imported client helpers and React package islands
 - HMR and framework DevTools
@@ -205,13 +238,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 | **385 ms** |
-| Astro | Yes | **158 B** | **365 B** | 948 ms |
-| Svelte CSR | No | 10.5 KB | 26.9 KB | 885 ms |
-| Qwik CSR | No | 20.6 KB | 57.8 KB | 622 ms |
-| Vue CSR | No | 24.0 KB | 60.3 KB | 822 ms |
-| React CSR | No | 59.2 KB | 189.0 KB | 1084 ms |
-| Next.js | Yes | 182.1 KB | 652.2 KB | 3074 ms |
+| 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 |
 
 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.
 

package/framework/README.md

@@ -4,12 +4,13 @@
 - `core.mjs`: server-side JSX rendering, state slots, behavior metadata, and serializable capture validation.
 - `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.
 - `runtime.js`: command-only runtime for direct state-to-text patches.
-- `shared-runtime.js`: command runtime with binding commit hooks, emitted only when needed.
-- `binding-runtime.js`: optional reactive attributes and conditional DOM range 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.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes add `binding-runtime.js`; native handlers add `native-runtime.js`. Generated evaluators live under `dist/assets/handlers/`.
+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/`.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/binding-runtime.js

@@ -1,4 +1,4 @@
-import { browserState, mountText, registerCommitter } from "./shared-runtime.js"
+import { browserState, mountDom, registerCommitter, registerMountHook, registerUnmountHook, unmountDom } from "./shared-runtime.js"
 import { deserialize } from "./serialization.js"
 
 const imports = new Map()
@@ -8,17 +8,25 @@ const mountedBindings = new WeakSet()
 const mountedConditions = new WeakSet()
 const bindingRegistrations = new WeakMap()
 const conditionRegistrations = new WeakMap()
+const bindingTypes = ["class", "disabled", "value", "checked"]
+const bindingSelector = [...bindingTypes.map(target => `[data-k-bind-${target}]`), "[data-k-bind-attrs]"].join(",")
 
 export function patchBinding(node, target, value) {
   if (target === "disabled") {
     node.toggleAttribute("disabled", Boolean(value))
+  } else if (target === "checked") {
+    node.checked = Boolean(value)
   } else if (target === "value") {
     const next = value == null ? "" : String(value)
     if (node.value !== next) node.value = next
-  } else if (value == null || value === false) {
+  } else if (target === "class" && (value == null || value === false)) {
     node.removeAttribute("class")
-  } else {
+  } else if (target === "class") {
     node.setAttribute("class", String(value))
+  } else if (value == null || (value === false && !isStringBooleanAttribute(target))) {
+    node.removeAttribute(target)
+  } else {
+    node.setAttribute(target, value === true && !isStringBooleanAttribute(target) ? "" : String(value))
   }
 }
 
@@ -42,37 +50,38 @@ function commitConditions(id) {
 
 registerCommitter(commitBindings)
 registerCommitter(commitConditions)
+registerMountHook(mountBindings)
+registerMountHook(mountConditions)
+registerUnmountHook(unmountBindings)
+registerUnmountHook(unmountConditions)
 
 if (typeof document !== "undefined") mountDom(document)
 
-function mountDom(root) {
-  mountText(root)
-  mountBindings(root)
-  mountConditions(root)
-}
-
 function mountBindings(root) {
-  for (const target of ["class", "disabled", "value"]) {
-    for (const node of matching(root, `[data-k-bind-${target}]`)) {
-      if (mountedBindings.has(node)) continue
-      mountedBindings.add(node)
-      const descriptor = JSON.parse(node.dataset[`kBind${capitalize(target)}`])
+  for (const node of matching(root, bindingSelector)) {
+    if (mountedBindings.has(node)) continue
+    mountedBindings.add(node)
+    const registrations = []
+    bindingRegistrations.set(node, registrations)
+    const descriptors = bindingTypes.flatMap(target => node.hasAttribute(`data-k-bind-${target}`)
+      ? [[target, JSON.parse(node.dataset[`kBind${capitalize(target)}`])]]
+      : [])
+    if (node.dataset.kBindAttrs) descriptors.push(...JSON.parse(node.dataset.kBindAttrs).map(({ target, ...descriptor }) => [target, descriptor]))
+    for (const [target, descriptor] of descriptors) {
       if (descriptor.state) {
         const binding = { node, target, read: () => browserState.get(descriptor.state) }
         register(bindingTargets, descriptor.state, binding)
-        bindingRegistrations.set(node, [[descriptor.state, binding]])
+        registrations.push([descriptor.state, binding])
         patchBinding(node, target, binding.read())
         continue
       }
       loadEvaluator(descriptor).then(evaluator => {
         if (!node.isConnected) return
         const binding = { node, target, read: evaluator.read }
-        const registrations = []
         for (const id of evaluator.stateIds) {
           register(bindingTargets, id, binding)
           registrations.push([id, binding])
         }
-        bindingRegistrations.set(node, registrations)
         patchBinding(node, target, binding.read())
       }).catch(error => console.error(error))
     }
@@ -117,14 +126,21 @@ function updateCondition(condition) {
   condition.end.parentNode.insertBefore(fragment, condition.end)
   condition.current = next
   for (const node of nodes) mountDom(node)
+  const select = condition.start.closest("select[data-k-bind-value]")
+  for (const binding of new Set((bindingRegistrations.get(select) ?? []).map(([, entry]) => entry))) {
+    patchBinding(binding.node, binding.target, binding.read())
+  }
 }
 
-function unmountDom(root) {
-  for (const node of matching(root, "[data-k-bind-class],[data-k-bind-disabled],[data-k-bind-value]")) {
+function unmountBindings(root) {
+  for (const node of matching(root, bindingSelector)) {
     for (const [id, binding] of bindingRegistrations.get(node) ?? []) bindingTargets.get(id)?.delete(binding)
     bindingRegistrations.delete(node)
     mountedBindings.delete(node)
   }
+}
+
+function unmountConditions(root) {
   for (const start of matching(root, "template[data-k-if]")) {
     const registration = conditionRegistrations.get(start)
     for (const [id, condition] of registration?.registrations ?? []) conditionTargets.get(id)?.delete(condition)
@@ -138,9 +154,8 @@ function removeConditionRange(start, end) {
   range.setStartAfter(start)
   range.setEndBefore(end)
   const root = range.commonAncestorContainer
-  for (const node of matching(root, "[data-k-bind-class],[data-k-bind-disabled],[data-k-bind-value],template[data-k-if]")) {
-    if (range.comparePoint(node, 0) === 0) unmountDom(node)
-  }
+  const nodes = matching(root, "*").filter(node => range.comparePoint(node, 0) === 0)
+  for (const node of nodes) if (!nodes.some(parent => parent !== node && parent.contains(node))) unmountDom(node)
   range.deleteContents()
 }
 
@@ -207,3 +222,7 @@ function matching(root, selector) {
 function capitalize(value) {
   return value[0].toUpperCase() + value.slice(1)
 }
+
+function isStringBooleanAttribute(name) {
+  return name.startsWith("aria-") || name.startsWith("data-")
+}

package/framework/build.mjs

@@ -31,6 +31,7 @@ export async function build({ quiet = false } = {}) {
 
   let behaviorCount = 0
   let bindingCount = 0
+  let listCount = 0
   let stateSeedCount = 0
   const plans = []
   const hasStyles = await exists(join(sourceDirectory, "style.css"))
@@ -51,6 +52,7 @@ export async function build({ quiet = false } = {}) {
     plans.push({ route: `/${route}`, ...result.plan })
     if (result.hasBehaviors) behaviorCount++
     if (result.hasBindings) bindingCount++
+    if (result.hasLists) listCount++
     if (result.hasStateSeed) stateSeedCount++
   }
 
@@ -59,7 +61,7 @@ export async function build({ quiet = false } = {}) {
   const commandEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.commands).map(event => event.event)))].sort()
   const nativeEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.native).map(event => event.event)))].sort()
   if (behaviorCount) {
-    const runtimeFile = bindingCount ? "./shared-runtime.js" : "./runtime.js"
+    const runtimeFile = bindingCount || listCount ? "./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)
   }
@@ -71,6 +73,11 @@ export async function build({ quiet = false } = {}) {
       .replace('"./serialization.js"', '"./kudzu-serialization.js"')
     await writeFile(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime)
   }
+  if (listCount) {
+    const listRuntime = (await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"))
+      .replace('"./shared-runtime.js"', '"./kudzu.js"')
+    await writeFile(join(assetsDirectory, "kudzu-list.js"), listRuntime)
+  }
   if (hasNativeHandlers) {
     const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"))
       .replace('"./runtime.js"', '"./kudzu.js"')
@@ -184,9 +191,11 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
     const factory = context.factory
     const settersByFunction = new Map()
     const functions = new Map()
+    const listFieldExpressions = new WeakSet()
     let usesBehavior = false
     let usesBinding = false
     let usesConditional = false
+    let usesList = false
 
     const collect = node => {
       if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer)) {
@@ -229,6 +238,19 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, 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)
+          usesBehavior = true
+          usesBinding = true
+          usesList = true
+          return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
+            listParts.state,
+            factory.createStringLiteral(listParts.keyField),
+            ts.visitNode(listParts.callback, visitor)
+          ]))
+        }
         const parts = conditionalParts(node.expression)
         if (parts) {
           const setters = settersForNode(node, settersByFunction)
@@ -245,8 +267,9 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
         }
       }
 
-      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && ["className", "disabled", "value"].includes(node.name.getText())) {
+      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)
@@ -279,6 +302,7 @@ 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 (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
       undefined,
@@ -289,6 +313,83 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, handlerUrl) {
   }
 }
 
+function keyedListParts(expression, setters) {
+  const value = unwrapExpression(expression)
+  if (!ts.isCallExpression(value) || value.arguments.length !== 1 || !ts.isPropertyAccessExpression(value.expression) || value.expression.name.text !== "map" || !ts.isIdentifier(value.expression.expression)) return undefined
+  const state = value.expression.expression
+  if (![...setters.values()].includes(state.text)) return undefined
+  const callback = value.arguments[0]
+  if (!ts.isArrowFunction(callback) || callback.parameters.length !== 1 || !ts.isIdentifier(callback.parameters[0].name)) {
+    throw new Error("Keyed list map callback must be an arrow function with one identifier parameter")
+  }
+  const root = unwrapExpression(callback.body)
+  if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) throw new Error("Keyed list map callback must return one JSX element")
+  const attributes = ts.isJsxElement(root) ? root.openingElement.attributes : root.attributes
+  const key = attributes.properties.find(attribute => ts.isJsxAttribute(attribute) && attribute.name.getText() === "key")
+  const field = key && ts.isJsxAttribute(key) && key.initializer && ts.isJsxExpression(key.initializer) && key.initializer.expression && directProperty(key.initializer.expression, callback.parameters[0].name.text)
+  if (!field) throw new Error(`Keyed list root must have key={${callback.parameters[0].name.text}.<field>}`)
+  return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
+}
+
+function validateKeyedList(parts, sourceFile, listFieldExpressions) {
+  const fail = (node, message) => {
+    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
+    throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
+  }
+  const validateElement = node => {
+    const tag = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName
+    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.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 (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.isJsxExpression(node) && node.expression) {
+      const expression = unwrapExpression(node.expression)
+      const field = directProperty(expression, parts.item)
+      const isRootKey = node.parent?.parent === parts.root && ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "key"
+      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)
+        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)
+}
+
+function directProperty(expression, objectName) {
+  const value = unwrapExpression(expression)
+  if (!ts.isPropertyAccessExpression(value) || !ts.isIdentifier(value.expression)) return undefined
+  if (objectName !== undefined && value.expression.text !== objectName) return undefined
+  return value.name.text
+}
+
+function keyedListParentTag(node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (ts.isJsxElement(current)) return current.openingElement.tagName.getText().toLowerCase()
+  }
+  return undefined
+}
+
+function referencesIdentifier(root, name) {
+  let found = false
+  const visit = node => {
+    if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node)) found = true
+    if (!found) ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return found
+}
+
+function unwrapExpression(node) {
+  return ts.isParenthesizedExpression(node) ? unwrapExpression(node.expression) : node
+}
+
 function compileReactiveBinding(expression, setters, factory, context, reactiveBindings, handlerUrl) {
   return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, factory, context, reactiveBindings, handlerUrl))
 }

package/framework/core.d.ts

@@ -7,6 +7,7 @@ export function nativeBehavior(module: string, handler: string, states: Array<[s
 export function binding(value: unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
 export function bindingValue(value: unknown): unknown
 export function 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 renderPage(
   component: (props: Record<string, never>) => unknown | Promise<unknown>,
@@ -32,6 +33,7 @@ export function renderPage(
   html: string
   hasBehaviors: boolean
   hasBindings: boolean
+  hasLists: boolean
   hasStateSeed: boolean
   plan: {
     states: Array<{ id: string; name: string; initialValue: unknown }>
@@ -41,7 +43,7 @@ export function renderPage(
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
     bindings: Array<{
-      target: "class" | "disabled" | "value"
+      target: string
       state?: string
       module?: string
       handler?: string
@@ -51,5 +53,6 @@ export function renderPage(
       scopeBindings?: Record<string, unknown>
     }>
     conditions: Array<Record<string, unknown>>
+    lists: Array<Record<string, unknown>>
   }
 }>

package/framework/core.mjs

@@ -3,6 +3,9 @@ const behaviorMarker = Symbol("kudzu.behavior")
 const nativeBehaviorMarker = Symbol("kudzu.nativeBehavior")
 const bindingMarker = Symbol("kudzu.binding")
 const conditionalMarker = Symbol("kudzu.conditional")
+const listMarker = Symbol("kudzu.list")
+const listFieldMarker = Symbol("kudzu.listField")
+const noSelectValue = Symbol("kudzu.no-select-value")
 
 let renderContext
 
@@ -61,6 +64,50 @@ export function conditional(kind, value, truthy, falsy, module, handler, states,
   return { [conditionalMarker]: true, kind, value, truthy, falsy, ...reactiveDescriptor(module, handler, states, scope) }
 }
 
+export function list(items, keyField, render) {
+  if (!items?.[signalMarker] || !Array.isArray(items.value)) throw new Error("A keyed list must use local array state")
+  const keys = new Set()
+  for (const item of items.value) {
+    const key = item?.[keyField]
+    if (!validListKey(key)) throw new Error(`Keyed list key "${keyField}" must be a string or finite number`)
+    assertListItem(item)
+    assertListValue(item, new Set())
+    const token = `${typeof key}:${key}`
+    if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
+    keys.add(token)
+  }
+  return { [listMarker]: true, items, keyField, render }
+}
+
+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")
+}
+
+function assertListValue(value, seen) {
+  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 && prototype !== null) throw new Error("Keyed list items must contain only arrays and 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)
+  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")
+  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)) {
+    if (Array.isArray(value) && key === "length") continue
+    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)
+  }
+  seen.delete(value)
+}
+
 function reactiveDescriptor(module, handler, states, scope) {
   const scopeStates = {}
   const serializedScope = {}
@@ -123,7 +170,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}) {
-  renderContext = { nextState: 0, nextCondition: 0, conditionDepth: 0, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false }
+  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 }
 
   try {
     const body = await renderNode({ type: component, props: {} })
@@ -141,6 +188,9 @@ export async function renderPage(component, metadata = {}) {
     const bindingRuntime = renderContext.hasBindings
       ? '<script type="module" src="/assets/kudzu-binding.js"></script>'
       : ""
+    const listRuntime = renderContext.hasLists
+      ? '<script type="module" src="/assets/kudzu-list.js"></script>'
+      : ""
     const initialState = renderContext.hasBehaviors
       ? Object.entries(renderContext.states).filter(([id]) => !renderContext.textStates.has(id) || renderContext.conditionStates.has(id)).map(([id, entry]) => [id, entry.initialValue])
       : []
@@ -149,15 +199,17 @@ export async function renderPage(component, metadata = {}) {
       : ""
 
     return {
-      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}</head><body${state}>${body}${runtime}${bindingRuntime}${nativeRuntime}</body></html>`,
+      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}</head><body${state}>${body}${runtime}${bindingRuntime}${listRuntime}${nativeRuntime}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasBindings: renderContext.hasBindings,
+      hasLists: renderContext.hasLists,
       hasStateSeed: initialState.length > 0,
       plan: {
         states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
         events: renderContext.events,
         bindings: renderContext.bindings,
-        conditions: renderContext.conditions
+        conditions: renderContext.conditions,
+        lists: renderContext.lists
       }
     }
   } finally {
@@ -198,32 +250,32 @@ function renderMetadata(metadata) {
   return tags.join("")
 }
 
-async function renderNode(node, namespace) {
+async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node == null || node === false || node === true) return ""
   if (Array.isArray(node)) {
     let html = ""
-    for (const child of node) html += await renderNode(child, namespace)
+    for (const child of node) html += await renderNode(child, namespace, selectValue)
     return html
   }
   if (node?.[signalMarker]) {
     renderContext.textStates.add(node.id)
-    if (renderContext.conditionDepth) renderContext.conditionStates.add(node.id)
+    if (renderContext.conditionDepth || renderContext.listDepth) renderContext.conditionStates.add(node.id)
     return `<span data-k-text="${node.id}" data-k-value='${escapeJsonAttribute(node.value)}'>${escapeHtml(node.value)}</span>`
   }
   if (typeof node === "string" || typeof node === "number" || typeof node === "bigint") {
     return escapeHtml(node)
   }
-  if (node instanceof Promise) return renderNode(await node, namespace)
+  if (node instanceof Promise) return renderNode(await node, namespace, selectValue)
   if (node?.[conditionalMarker]) {
     const descriptor = bindingDescriptor(node)
     const stateIds = reactiveStateIds(descriptor)
-    if (!stateIds.size) return renderNode(node.value ? node.truthy() : node.falsy(), namespace)
+    if (!stateIds.size) return renderNode(node.value ? node.truthy() : node.falsy(), namespace, selectValue)
     if (namespace) throw new Error(`Reactive conditional DOM is not supported inside ${namespace}`)
 
     const id = `c${renderContext.nextCondition++}`
     renderContext.conditionDepth++
-    const truthy = await renderNode(node.truthy())
-    const falsy = await renderNode(node.falsy())
+    const truthy = await renderNode(node.truthy(), namespace, selectValue)
+    const falsy = await renderNode(node.falsy(), namespace, selectValue)
     renderContext.conditionDepth--
     const metadata = { id, kind: node.kind, initial: node.value, ...descriptor }
     for (const stateId of stateIds) renderContext.conditionStates.add(stateId)
@@ -231,25 +283,48 @@ async function renderNode(node, namespace) {
     renderContext.hasBehaviors = true
     renderContext.hasBindings = true
     const encoded = escapeJsonAttribute(metadata)
-    const current = node.value ? truthy : node.kind === "and" ? await renderNode(node.value) : falsy
+    const current = node.value ? truthy : node.kind === "and" ? await renderNode(node.value, namespace, selectValue) : falsy
     return `<template data-k-if='${encoded}'><template data-k-true>${truthy}</template><template data-k-false>${falsy}</template></template>${current}<template data-k-if-end="${id}"></template>`
   }
+  if (node?.[listMarker]) return renderList(node, namespace, selectValue)
+  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 || typeof node !== "object" || !("type" in node)) {
     throw new Error(`Cannot render ${String(node)}`)
   }
 
-  if (node.type === Symbol.for("kudzu.fragment")) return renderNode(node.props.children, namespace)
-  if (typeof node.type === "function") return renderNode(await node.type(node.props), namespace)
+  if (node.type === Symbol.for("kudzu.fragment")) return renderNode(node.props.children, namespace, selectValue)
+  if (typeof node.type === "function") return renderNode(await node.type(node.props), namespace, selectValue)
 
   const tag = node.type
   const props = node.props ?? {}
+  const childSelectValue = tag === "select"
+    ? Object.hasOwn(props, "value") ? bindingValue(props.value) : noSelectValue
+    : selectValue
   const childNamespace = tag === "svg" || tag === "math"
     ? tag
     : namespace === "svg" && tag === "foreignObject" ? undefined : namespace
   let attributes = ""
+  const attributeBindings = []
+  const listAttributes = []
+
+  if (renderContext.listRoot) {
+    const root = renderContext.listRoot
+    renderContext.listRoot = undefined
+    attributes += root.template
+      ? ` data-k-list-root="${root.id}"`
+      : ` data-k-list-item='${escapeJsonAttribute([root.id, root.key])}'`
+  }
 
   for (const [rawName, value] of Object.entries(props)) {
     if (rawName === "children" || rawName === "key") continue
+    if (rawName === "selected" && selectValue !== noSelectValue) continue
+    if (/^on/i.test(rawName) && !/^on[A-Z]/.test(rawName)) throw new Error(`${rawName} must use a camelCase event handler`)
+    if (rawName.toLowerCase().startsWith("data-k-")) throw new Error(`${rawName} uses Kudzu's reserved data-k-* prefix`)
+    if (["style", "ref", "dangerouslysetinnerhtml"].includes(rawName.toLowerCase()) && (value?.[signalMarker] || value?.[bindingMarker])) {
+      throw new Error(`Reactive ${rawName} is not supported`)
+    }
 
     if (/^on[A-Z]/.test(rawName)) {
       const event = rawName.slice(2).toLowerCase()
@@ -270,40 +345,80 @@ async function renderNode(node, namespace) {
     }
 
     const name = rawName === "className" ? "class" : rawName === "htmlFor" ? "for" : rawName
-    const target = name === "class" || name === "disabled" || name === "value" ? name : undefined
-    if (target && (value?.[signalMarker] || value?.[bindingMarker])) {
+    const propertyTarget = name === "class" || name === "disabled" || name === "value" || name === "checked"
+    if (value?.[listFieldMarker]) {
+      attributes += renderAttribute(name, value.value)
+      listAttributes.push([name, value.field])
+      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
       if (!reactive) {
-        attributes += renderAttribute(name, initialValue)
+        if (tag !== "select" || name !== "value") attributes += renderAttribute(name, initialValue)
         continue
       }
       const descriptor = value[signalMarker]
         ? { state: value.id }
         : bindingDescriptor(value)
-      attributes += renderAttribute(name, initialValue)
-      attributes += ` data-k-bind-${target}='${escapeJsonAttribute(descriptor)}'`
-      renderContext.bindings.push({ target, ...descriptor })
-      if (renderContext.conditionDepth) for (const stateId of reactiveStateIds(descriptor)) renderContext.conditionStates.add(stateId)
+      if (tag !== "select" || name !== "value") attributes += renderAttribute(name, initialValue)
+      if (propertyTarget) attributes += ` data-k-bind-${name}='${escapeJsonAttribute(descriptor)}'`
+      else attributeBindings.push({ target: name, ...descriptor })
+      renderContext.bindings.push({ target: name, ...descriptor })
+      if (renderContext.conditionDepth || renderContext.listDepth) for (const stateId of reactiveStateIds(descriptor)) renderContext.conditionStates.add(stateId)
       renderContext.hasBehaviors = true
       renderContext.hasBindings = true
       continue
     }
 
-    if (value == null || value === false) continue
-    if (value === true) {
-      attributes += ` ${name}`
-    } else if (name === "style" && typeof value === "object") {
+    if (tag === "select" && name === "value") continue
+    if (name === "style" && value && typeof value === "object") {
       const style = Object.entries(value).map(([property, entry]) => `${toKebabCase(property)}:${entry}`).join(";")
       attributes += ` style="${escapeAttribute(style)}"`
     } else {
-      attributes += ` ${name}="${escapeAttribute(value)}"`
+      attributes += renderAttribute(name, value)
     }
   }
 
+  if (attributeBindings.length) attributes += ` data-k-bind-attrs='${escapeJsonAttribute(attributeBindings)}'`
+  if (listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
+
+  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)}</${tag}>`
+  return `<${tag}${attributes}>${await renderNode(props.children, childNamespace, childSelectValue)}</${tag}>`
+}
+
+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.listRoot = { id, template: true }
+    const template = await renderNode(node.render(itemProxy(undefined)), namespace, selectValue)
+    let current = ""
+    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)
+    }
+    renderContext.lists.push(descriptor)
+    renderContext.hasBehaviors = true
+    renderContext.hasLists = true
+    return `<template data-k-list='${escapeJsonAttribute(descriptor)}'>${template}</template>${current}<template data-k-list-end="${id}"></template>`
+  } finally {
+    renderContext.listRoot = undefined
+    renderContext.listDepth--
+  }
+}
+
+function optionValue(props) {
+  if (props.value != null) return bindingValue(props.value)
+  return Array.isArray(props.children) ? props.children.join("") : props.children ?? ""
 }
 
 function reactiveStateIds(descriptor) {
@@ -316,12 +431,17 @@ function reactiveStateIds(descriptor) {
 }
 
 function renderAttribute(name, value) {
-  if (name === "disabled") return value ? " disabled" : ""
+  if (name === "disabled" || name === "checked") return value ? ` ${name}` : ""
   if (name === "value") return value == null ? "" : ` value="${escapeAttribute(value)}"`
-  if (value == null || value === false) return ""
+  if (value == null || (value === false && !isStringBooleanAttribute(name))) return ""
+  if (value === true && !isStringBooleanAttribute(name)) return ` ${name}`
   return ` ${name}="${escapeAttribute(value)}"`
 }
 
+function isStringBooleanAttribute(name) {
+  return name.startsWith("aria-") || name.startsWith("data-")
+}
+
 function escapeHtml(value) {
   return String(value)
     .replaceAll("&", "&amp;")

package/framework/list-runtime.js

@@ -0,0 +1,185 @@
+import { browserState, mountDom, registerCommitter, registerMountHook, registerUnmountHook, unmountDom } from "./shared-runtime.js"
+
+const listTargets = new Map()
+const listRegistrations = new WeakMap()
+const mountedLists = new WeakSet()
+
+function commitLists(id) {
+  const lists = listTargets.get(id)
+  if (!lists) return
+  for (const list of lists) {
+    if (!list.start.isConnected) unregisterList(list.start)
+    else updateList(list)
+  }
+}
+
+registerCommitter(commitLists)
+registerMountHook(mountLists)
+registerUnmountHook(unmountLists)
+
+if (typeof document !== "undefined") mountDom(document)
+
+function mountLists(root) {
+  for (const start of matching(root, "template[data-k-list]")) {
+    if (mountedLists.has(start)) continue
+    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 list = {
+      start,
+      descriptor,
+      roots: new Map(roots.map(node => [keyToken(JSON.parse(node.dataset.kListItem)[1]), node])),
+      container: roots[0]?.parentNode,
+      boundary: roots.length ? roots.at(-1).nextSibling : findEnd(start, descriptor.id)
+    }
+    register(listTargets, descriptor.state, list)
+    listRegistrations.set(start, { state: descriptor.state, list })
+    updateList(list)
+  }
+}
+
+function unmountLists(root) {
+  for (const start of matching(root, "template[data-k-list]")) unregisterList(start)
+}
+
+function unregisterList(start) {
+  const registration = listRegistrations.get(start)
+  if (registration) {
+    const lists = listTargets.get(registration.state)
+    lists?.delete(registration.list)
+    if (!lists?.size) listTargets.delete(registration.state)
+  }
+  listRegistrations.delete(start)
+  mountedLists.delete(start)
+}
+
+function updateList(list) {
+  const items = browserState.get(list.descriptor.state)
+  if (!Array.isArray(items)) throw new Error("Keyed list state must remain an array")
+  const entries = []
+  const keys = 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())
+    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 })
+  }
+  const next = []
+  for (const { item, key, token } 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}"]`)
+      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 {
+      fillListItem(node, item)
+    }
+    next.push([token, node])
+  }
+  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)
+  list.roots = new Map(next)
+}
+
+function fillListItem(root, item) {
+  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)))
+  }
+  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])
+  }
+}
+
+function patchBinding(node, target, value) {
+  if (target === "disabled") {
+    node.toggleAttribute("disabled", Boolean(value))
+  } else if (target === "checked") {
+    node.checked = Boolean(value)
+  } else if (target === "value") {
+    const next = value == null ? "" : String(value)
+    if (node.value !== next) node.value = next
+  } else if (target === "class" && (value == null || value === false)) {
+    node.removeAttribute("class")
+  } else if (target === "class") {
+    node.setAttribute("class", String(value))
+  } else if (value == null || (value === false && !isStringBooleanAttribute(target))) {
+    node.removeAttribute(target)
+  } else {
+    node.setAttribute(target, value === true && !isStringBooleanAttribute(target) ? "" : String(value))
+  }
+}
+
+function keyToken(key) {
+  return `${typeof key}:${key}`
+}
+
+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")
+}
+
+function assertListValue(value, seen) {
+  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 && prototype !== null) throw new Error("Keyed list items must contain only arrays and 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)
+  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")
+  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)) {
+    if (Array.isArray(value) && key === "length") continue
+    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)
+  }
+  seen.delete(value)
+}
+
+function findEnd(start, id) {
+  return [...start.ownerDocument.querySelectorAll("template[data-k-list-end]")]
+    .find(node => node.dataset.kListEnd === id)
+}
+
+function register(targets, id, entry) {
+  const entries = targets.get(id) ?? new Set()
+  entries.add(entry)
+  targets.set(id, entries)
+}
+
+function matching(root, selector) {
+  return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
+}
+
+function isStringBooleanAttribute(name) {
+  return name.startsWith("aria-") || name.startsWith("data-")
+}

package/framework/shared-runtime.js

@@ -16,11 +16,21 @@ export function applyCommands(state, commands, commit, log = console.log) {
 
 export const browserState = new Map()
 const committers = []
+const mountHooks = []
+const unmountHooks = []
 
 export function registerCommitter(commit) {
   committers.push(commit)
 }
 
+export function registerMountHook(mount) {
+  mountHooks.push(mount)
+}
+
+export function registerUnmountHook(unmount) {
+  unmountHooks.push(unmount)
+}
+
 export function commitDom(id, value) {
   for (const node of document.querySelectorAll(`[data-k-text="${id}"]`)) node.textContent = value
   for (const commit of committers) commit(id)
@@ -34,6 +44,15 @@ export function mountText(root) {
   }
 }
 
+export function mountDom(root) {
+  mountText(root)
+  for (const mount of mountHooks) mount(root)
+}
+
+export function unmountDom(root) {
+  for (const unmount of unmountHooks) unmount(root)
+}
+
 if (typeof document !== "undefined") {
   const initialState = document.body.dataset.kState
   if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)

package/package.json

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