@kudzujs/core 0.4.9 → 0.4.11

package/README.md

@@ -160,6 +160,17 @@ 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.
 
+Top-level immutable JSX locals can hold static or state-dependent branches:
+
+```tsx
+const menu = open ? <MenuBar /> : <p>Menu dormant</p>
+const content = open && menu
+
+return <main>{content}</main>
+```
+
+Kudzu compiles the local initializer to the same bounded DOM ranges as an inline condition. Reassigned, block-scoped, and keyed-list alias locals remain unsupported.
+
 ## Keyed Lists
 
 Map local array state directly to one keyed JSX element per item:
@@ -170,7 +181,7 @@ const [items, setItems] = useState([
   { id: 2, name: "Pine", done: true }
 ])
 
-<ul>{items.map(item =>
+const rows = items.map(item =>
   <li
     key={item.id}
     className={item.done ? "done" : "active"}
@@ -180,12 +191,14 @@ const [items, setItems] = useState([
     {item.name.toUpperCase()}
     <button onClick={() => setItems(items.filter(entry => entry.id !== item.id))}>Remove</button>
   </li>
-)}</ul>
+)
+
+return <ul>{rows}</ul>
 ```
 
-Kudzu emits initial items as static HTML, then adds, removes, updates, styles, and moves keyed elements directly. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Item-local handlers use direct DOM listeners and receive the latest JSON-safe item for their key, including after updates, additions, and reorders. The item remains stored once in shared list state; handler descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
+Kudzu emits initial items as static HTML, then adds, removes, updates, styles, and moves keyed elements directly. The map may appear directly in JSX or in one top-level immutable `const` rendered once as a JSX child. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Item-local handlers use direct DOM listeners and receive the latest JSON-safe item for their key, including after updates, additions, and reorders. The item remains stored once in shared list state; handler descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
 
-Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a direct local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, locals, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Nested conditions or lists, item spreads, component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a local-state `.map`, one identifier callback parameter, one intrinsic JSX root, and `key={item.<field>}`. A list alias may only be rendered once and cannot be read by other JavaScript. 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, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 ## Normal JavaScript
 
@@ -250,11 +263,12 @@ Supported:
 - Object DOM refs in native event handlers
 - Controlled `value` and `checked` form properties
 - Conditional child `&&` and ternary DOM patches
+- Top-level immutable JSX locals
 - Direct keyed local-state lists
 
 Not implemented yet:
 
-- Generalized JSX-valued locals and non-direct list item expressions
+- Block-scoped JSX locals and reusable keyed-list aliases
 - Server actions and request-time SSR
 - Imported client helpers and React package islands
 - HMR and framework DevTools
@@ -269,13 +283,13 @@ Same counter with initial value `7` and increment/decrement buttons:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| Kudzu | Yes | 393 B | 1.1 KB | **431 ms** |
-| Astro | Yes | **158 B** | **365 B** | 974 ms |
-| Svelte CSR | No | 10.5 KB | 26.9 KB | 961 ms |
-| Qwik CSR | No | 20.6 KB | 57.8 KB | 660 ms |
-| Vue CSR | No | 24.0 KB | 60.3 KB | 859 ms |
-| React CSR | No | 59.2 KB | 189.0 KB | 1133 ms |
-| Next.js | Yes | 182.1 KB | 652.2 KB | 3269 ms |
+| Kudzu | Yes | 393 B | 1.1 KB | **429 ms** |
+| Astro | Yes | **158 B** | **365 B** | 942 ms |
+| Svelte CSR | No | 10.5 KB | 26.9 KB | 850 ms |
+| Qwik CSR | No | 20.6 KB | 57.8 KB | 686 ms |
+| Vue CSR | No | 24.0 KB | 60.3 KB | 875 ms |
+| React CSR | No | 59.2 KB | 189.0 KB | 1150 ms |
+| Next.js | Yes | 182.1 KB | 652.2 KB | 3203 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.
 
@@ -285,29 +299,29 @@ Same content and CSS across every fixture:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| Kudzu | Yes | **0 B** | 3.2 KB | **385 ms** |
-| Astro | Yes | **0 B** | **3.0 KB** | 970 ms |
-| Svelte CSR | No | 10.2 KB | 27.2 KB | 829 ms |
-| Qwik CSR | No | 20.2 KB | 59.6 KB | 634 ms |
-| Vue CSR | No | 24.2 KB | 62.3 KB | 767 ms |
-| React CSR | No | 59.8 KB | 192.3 KB | 1098 ms |
-| Next.js | Yes | 182.6 KB | 663.6 KB | 3217 ms |
+| Kudzu | Yes | **0 B** | 3.2 KB | **395 ms** |
+| Astro | Yes | **0 B** | **3.0 KB** | 1048 ms |
+| Svelte CSR | No | 10.2 KB | 27.2 KB | 897 ms |
+| Qwik CSR | No | 20.2 KB | 59.6 KB | 608 ms |
+| Vue CSR | No | 24.2 KB | 62.3 KB | 801 ms |
+| React CSR | No | 59.8 KB | 192.3 KB | 1097 ms |
+| Next.js | Yes | 182.6 KB | 663.6 KB | 3085 ms |
 
 ### 1,000-item Keyed List
 
-The list starts with 1,000 keyed items, then updates every label, reverses the order, removes odd IDs, and adds 500 items. Browser timings are medians from seven fresh headless Chrome runs.
+The list starts with 1,000 keyed items, then updates every label, reverses the order, removes odd IDs, and adds 500 items. Browser timings are medians from seven fresh headless Chrome runs, measured when a DOM observer sees each expected result rather than at the next animation frame.
 
 | Framework | Initial content | Initial JS gzip | Total output | Build | Update | Reverse | Remove | Add | Operations total |
 |---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
-| Astro | Yes | **324 B** | **43.6 KB** | 889 ms | **3.9 ms** | 27.6 ms | 7.9 ms | **18.1 ms** | **57.5 ms** |
-| Kudzu | Yes | 5.0 KB | 60.3 KB | **447 ms** | 6.3 ms | 31.0 ms | **7.3 ms** | 20.7 ms | 65.3 ms |
-| Vue CSR | No | 24.3 KB | 61.3 KB | 805 ms | 10.9 ms | 36.4 ms | 12.2 ms | 21.0 ms | 80.5 ms |
-| Next.js | Yes | 182.2 KB | 695.2 KB | 3081 ms | 7.9 ms | 40.2 ms | 9.4 ms | 23.5 ms | 81.0 ms |
-| React CSR | No | 59.3 KB | 189.4 KB | 1075 ms | 10.8 ms | 40.6 ms | 11.0 ms | 21.0 ms | 83.4 ms |
-| Qwik CSR | No | 22.2 KB | 64.1 KB | 655 ms | 11.9 ms | **25.1 ms** | 40.7 ms | 22.6 ms | 100.3 ms |
-| Svelte CSR | No | 12.9 KB | 33.1 KB | 895 ms | 6.1 ms | 69.9 ms | 11.2 ms | 20.8 ms | 108.0 ms |
-
-Astro is the hand-authored native DOM baseline in the interactive fixtures. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. In this run Kudzu's keyed-list operations total 65.3 ms, 7.8 ms behind Astro and 18.1 ms ahead of React across all four operations.
+| Astro | Yes | **324 B** | **43.6 KB** | 843 ms | **4.7 ms** | **4.4 ms** | **1.6 ms** | **3.6 ms** | **14.3 ms** |
+| Kudzu | Yes | 5.0 KB | 60.3 KB | **432 ms** | 8.0 ms | 8.0 ms | 2.1 ms | 7.8 ms | 25.9 ms |
+| Vue CSR | No | 24.3 KB | 61.3 KB | 776 ms | 12.0 ms | 10.8 ms | 4.6 ms | 7.4 ms | 34.8 ms |
+| React CSR | No | 59.3 KB | 189.4 KB | 1032 ms | 11.9 ms | 14.5 ms | 4.7 ms | 6.5 ms | 37.6 ms |
+| Next.js | Yes | 182.2 KB | 695.2 KB | 2988 ms | 8.6 ms | 15.8 ms | 5.1 ms | 8.5 ms | 38.0 ms |
+| Svelte CSR | No | 12.9 KB | 33.1 KB | 858 ms | 6.6 ms | 48.5 ms | 5.2 ms | 7.3 ms | 67.6 ms |
+| Qwik CSR | No | 22.2 KB | 64.1 KB | 618 ms | 11.4 ms | 27.5 ms | 37.9 ms | 22.8 ms | 99.6 ms |
+
+Astro is the hand-authored native DOM baseline in the interactive fixtures. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. Kudzu's keyed-list operations total 25.9 ms, 11.6 ms behind the hand-authored Astro baseline and 11.7 ms ahead of React across all four operations.
 
 Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
 

package/framework/build.mjs

@@ -322,6 +322,10 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
     const factory = context.factory
     const settersByFunction = new Map()
     const functions = new Map()
+    const jsxLocalDeclarations = new Map()
+    const jsxLocalsByFunction = new Map()
+    const listLocalDeclarations = new WeakSet()
+    const listLocalUses = new WeakMap()
     const listValues = new WeakMap()
     const listEventItems = new WeakMap()
     let usesBehavior = false
@@ -346,9 +350,48 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
         functions.set(node.name.text, node.initializer)
       }
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && isTopLevelConst(node)) {
+        const owner = nearestFunction(node)
+        const declarations = jsxLocalDeclarations.get(owner) ?? new Map()
+        declarations.set(node.name.text, { node, initializer: node.initializer })
+        jsxLocalDeclarations.set(owner, declarations)
+      }
       ts.forEachChild(node, collect)
     }
     collect(sourceFile)
+    for (const [owner, declarations] of jsxLocalDeclarations) {
+      const names = new Set()
+      let changed = true
+      while (changed) {
+        changed = false
+        for (const [name, { initializer }] of declarations) {
+          if (!names.has(name) && isJsxLocalValue(initializer, names)) {
+            names.add(name)
+            changed = true
+          }
+        }
+      }
+      jsxLocalsByFunction.set(owner, names)
+    }
+    for (const [owner, declarations] of jsxLocalDeclarations) {
+      const setters = settersByFunction.get(owner) ?? new Map()
+      for (const [name, declaration] of declarations) {
+        const parts = keyedListParts(declaration.initializer, setters)
+        if (!parts) continue
+        const uses = []
+        const collectUses = node => {
+          if (ts.isJsxExpression(node) && node.initializer === undefined && ts.isIdentifier(node.expression) && node.expression.text === name && nearestFunction(node) === owner) uses.push(node)
+          ts.forEachChild(node, collectUses)
+        }
+        collectUses(owner.body)
+        const references = identifierReferenceCount(owner.body, name)
+        const position = sourceFile.getLineAndCharacterOfPosition(declaration.node.getStart(sourceFile))
+        if (uses.length > 1) throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} Keyed list local "${name}" must be rendered exactly once`)
+        if (references !== uses.length) throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} Keyed list local "${name}" may only be used as a JSX child`)
+        listLocalDeclarations.add(declaration.node)
+        if (uses.length) listLocalUses.set(uses[0], parts)
+      }
+    }
 
     const visitor = node => {
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
@@ -369,6 +412,25 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, initializer)
       }
 
+      if (ts.isVariableDeclaration(node) && listLocalDeclarations.has(node)) {
+        return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, factory.createIdentifier("undefined"))
+      }
+
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && jsxLocalsByFunction.get(nearestFunction(node))?.has(node.name.text) && referencesIdentifier(nearestFunction(node).body, node.name.text)) {
+        const parts = conditionalParts(node.initializer)
+        if (parts) {
+          const setters = settersForNode(node, settersByFunction)
+          const usedStates = referencedStateNames(parts.condition, setters)
+          const captures = captureNames(parts.condition, parts.condition, setters)
+          if (usedStates.size || captures.size) {
+            usesBehavior = true
+            usesConditional = true
+            const compiled = compileConditional(parts.kind, parts.condition, ts.visitNode(parts.truthy, visitor), ts.visitNode(parts.falsy, visitor), setters, factory, context, reactiveBindings, handlerUrl)
+            return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, compiled)
+          }
+        }
+      }
+
       if (ts.isJsxExpression(node) && node.expression && listValues.has(node.expression)) {
         return factory.updateJsxExpression(node, compileListValue(node.expression, listValues.get(node.expression), factory, listExpressions, handlerUrl))
       }
@@ -378,7 +440,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       }
 
       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))
+        const listParts = listLocalUses.get(node) ?? 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, settersForNode(node, settersByFunction), listValues, listEventItems)
@@ -614,10 +676,35 @@ function referencesIdentifier(root, name) {
   return found
 }
 
+function identifierReferenceCount(root, name) {
+  let count = 0
+  const visit = node => {
+    if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node)) count++
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return count
+}
+
 function unwrapExpression(node) {
   return ts.isParenthesizedExpression(node) ? unwrapExpression(node.expression) : node
 }
 
+function isTopLevelConst(node) {
+  const list = node.parent
+  const statement = list?.parent
+  const owner = nearestFunction(node)
+  return ts.isVariableDeclarationList(list) && (list.flags & ts.NodeFlags.Const) !== 0 && ts.isVariableStatement(statement) && statement.parent === owner?.body
+}
+
+function isJsxLocalValue(expression, known) {
+  const value = unwrapExpression(expression)
+  if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value) || ts.isJsxFragment(value)) return true
+  if (ts.isIdentifier(value)) return known.has(value.text)
+  const parts = conditionalParts(value)
+  return Boolean(parts && (isJsxLocalValue(parts.truthy, known) || isJsxLocalValue(parts.falsy, known)))
+}
+
 function compileReactiveBinding(expression, setters, factory, context, reactiveBindings, handlerUrl) {
   return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, factory, context, reactiveBindings, handlerUrl))
 }

package/framework/list-runtime.js

@@ -105,15 +105,12 @@ function updateList(list) {
     next.push([token, node])
     values.set(token, value)
   }
-  const removals = parent.ownerDocument.createDocumentFragment()
   for (const [token, node] of list.roots) {
     if (keys.has(token)) continue
     if (list.descriptor.mount) {
       unmountDom(node)
       node.remove()
-    } else {
-      removals.append(node)
-    }
+    } else node.remove()
   }
   if (added) {
     if (list.descriptor.mount) mountDom(additions)

package/package.json

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