@kudzujs/core 0.4.10 → 0.4.12

package/README.md

@@ -139,6 +139,26 @@ return <>
 
 Kudzu resolves `current` when the handler reads it, so removed conditional elements return `null` without a component runtime. Refs must initialize with `null`; callback refs, mutable value refs, and refs inside keyed lists are not supported.
 
+## Context
+
+Create a context to pass static or reactive values through component layers without prop drilling:
+
+```tsx
+const ThemeContext = createContext("light")
+
+function Toolbar() {
+  const theme = useContext(ThemeContext)
+  return <button className={`theme-${theme}`}>{theme}</button>
+}
+
+function App() {
+  const [theme] = useState("dark")
+  return <ThemeContext.Provider value={theme}><Toolbar /></ThemeContext.Provider>
+}
+```
+
+The default value applies outside a Provider, nested Providers override their parent, and native handlers read the latest direct state value. Static Provider values must be serializable. Reactive Provider values must be a direct `useState` value; setters and objects containing reactive values are not supported.
+
 ## Conditional DOM
 
 Inline child `&&` and ternary expressions insert and remove bounded DOM ranges directly. A menu bar needs only state setters:
@@ -181,7 +201,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"}
@@ -191,12 +211,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
 
@@ -259,6 +281,7 @@ Supported:
 - Reactive standard, `aria-*`, and `data-*` attributes
 - Reactive object `style` attributes
 - Object DOM refs in native event handlers
+- Default, nested, and reactive context providers
 - Controlled `value` and `checked` form properties
 - Conditional child `&&` and ternary DOM patches
 - Top-level immutable JSX locals
@@ -266,7 +289,7 @@ Supported:
 
 Not implemented yet:
 
-- Block-scoped JSX 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
@@ -281,13 +304,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 | **383 ms** |
-| Astro | Yes | **158 B** | **365 B** | 914 ms |
-| Svelte CSR | No | 10.5 KB | 26.9 KB | 892 ms |
-| Qwik CSR | No | 20.6 KB | 57.8 KB | 606 ms |
-| Vue CSR | No | 24.0 KB | 60.3 KB | 815 ms |
-| React CSR | No | 59.2 KB | 189.0 KB | 1044 ms |
-| Next.js | Yes | 182.1 KB | 652.2 KB | 3030 ms |
+| Kudzu | Yes | 393 B | 1.1 KB | **409 ms** |
+| Astro | Yes | **158 B** | **365 B** | 893 ms |
+| Svelte CSR | No | 10.5 KB | 26.9 KB | 867 ms |
+| Qwik CSR | No | 20.6 KB | 57.8 KB | 600 ms |
+| Vue CSR | No | 24.0 KB | 60.3 KB | 785 ms |
+| React CSR | No | 59.2 KB | 189.0 KB | 1032 ms |
+| Next.js | Yes | 182.1 KB | 652.2 KB | 3082 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.
 
@@ -297,29 +320,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 | **409 ms** |
-| Astro | Yes | **0 B** | **3.0 KB** | 1053 ms |
-| Svelte CSR | No | 10.2 KB | 27.2 KB | 863 ms |
-| Qwik CSR | No | 20.2 KB | 59.6 KB | 611 ms |
-| Vue CSR | No | 24.2 KB | 62.3 KB | 782 ms |
-| React CSR | No | 59.8 KB | 192.3 KB | 1062 ms |
-| Next.js | Yes | 182.6 KB | 663.6 KB | 3118 ms |
+| Kudzu | Yes | **0 B** | 3.2 KB | **422 ms** |
+| Astro | Yes | **0 B** | **3.0 KB** | 1081 ms |
+| Svelte CSR | No | 10.2 KB | 27.2 KB | 902 ms |
+| Qwik CSR | No | 20.2 KB | 59.6 KB | 633 ms |
+| Vue CSR | No | 24.2 KB | 62.3 KB | 810 ms |
+| React CSR | No | 59.8 KB | 192.3 KB | 1110 ms |
+| Next.js | Yes | 182.6 KB | 663.6 KB | 3126 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** | 862 ms | **3.5 ms** | 24.8 ms | **8.4 ms** | **17.9 ms** | **54.6 ms** |
-| Kudzu | Yes | 5.0 KB | 60.3 KB | **435 ms** | 6.1 ms | 29.0 ms | 12.8 ms | 19.5 ms | 67.4 ms |
-| Vue CSR | No | 24.3 KB | 61.3 KB | 789 ms | 9.3 ms | 32.1 ms | 10.6 ms | 18.6 ms | 70.6 ms |
-| React CSR | No | 59.3 KB | 189.4 KB | 1049 ms | 8.8 ms | 34.7 ms | 13.5 ms | 18.2 ms | 75.2 ms |
-| Next.js | Yes | 182.2 KB | 695.2 KB | 3029 ms | 7.0 ms | 37.2 ms | 12.9 ms | 21.9 ms | 79.0 ms |
-| Qwik CSR | No | 22.2 KB | 64.1 KB | 623 ms | 13.4 ms | **21.7 ms** | 33.6 ms | 28.9 ms | 97.6 ms |
-| Svelte CSR | No | 12.9 KB | 33.1 KB | 870 ms | 5.6 ms | 61.3 ms | 15.6 ms | 18.3 ms | 100.8 ms |
-
-Astro is the hand-authored native DOM baseline in the interactive fixtures. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. In this run Kudzu's keyed-list operations total 67.4 ms, 12.8 ms behind Astro and 7.8 ms ahead of React across all four operations.
+| Astro | Yes | **324 B** | **43.6 KB** | 826 ms | **4.1 ms** | **3.7 ms** | **1.4 ms** | **3.3 ms** | **12.5 ms** |
+| Kudzu | Yes | 5.0 KB | 60.3 KB | **452 ms** | 7.1 ms | 7.5 ms | 1.9 ms | 7.0 ms | 23.5 ms |
+| Next.js | Yes | 182.2 KB | 695.2 KB | 3002 ms | 7.5 ms | 12.3 ms | 4.1 ms | 7.8 ms | 31.7 ms |
+| Vue CSR | No | 24.3 KB | 61.3 KB | 765 ms | 11.4 ms | 9.8 ms | 4.4 ms | 7.0 ms | 32.6 ms |
+| React CSR | No | 59.3 KB | 189.4 KB | 1039 ms | 9.9 ms | 13.4 ms | 4.7 ms | 6.1 ms | 34.1 ms |
+| Svelte CSR | No | 12.9 KB | 33.1 KB | 845 ms | 6.2 ms | 42.9 ms | 4.6 ms | 6.2 ms | 59.9 ms |
+| Qwik CSR | No | 22.2 KB | 64.1 KB | 630 ms | 10.7 ms | 27.5 ms | 39.2 ms | 22.2 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 23.5 ms, 11.0 ms behind the hand-authored Astro baseline and 10.6 ms ahead of React across all four operations.
 
 Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
 

package/framework/README.md

@@ -1,7 +1,7 @@
 # Framework Internals
 
 - `build.mjs`: TSX compilation, file routes, behavior extraction, static HTML output, and the development server.
-- `core.mjs`: server-side JSX rendering, state slots, behavior metadata, and serializable capture validation.
+- `core.mjs`: server-side JSX rendering, state slots, context providers, 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 capability commit and DOM lifecycle hooks, emitted only when needed.

package/framework/build.mjs

@@ -324,6 +324,8 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
     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
@@ -351,7 +353,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       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)
+        declarations.set(node.name.text, { node, initializer: node.initializer })
         jsxLocalDeclarations.set(owner, declarations)
       }
       ts.forEachChild(node, collect)
@@ -362,7 +364,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       let changed = true
       while (changed) {
         changed = false
-        for (const [name, initializer] of declarations) {
+        for (const [name, { initializer }] of declarations) {
           if (!names.has(name) && isJsxLocalValue(initializer, names)) {
             names.add(name)
             changed = true
@@ -371,6 +373,25 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       }
       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(".")) {
@@ -391,6 +412,10 @@ 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) {
@@ -415,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)
@@ -651,6 +676,16 @@ 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
 }

package/framework/core.d.ts

@@ -8,6 +8,13 @@ export interface RefObject<T> {
 
 export function useRef<T>(initialValue: null): RefObject<T>
 
+export interface Context<T> {
+  Provider: (props: { value: T; children?: unknown }) => unknown
+}
+
+export function createContext<T>(defaultValue: T): Context<T>
+export function useContext<T>(context: Context<T>): T
+
 export function behavior(commands: Array<["add" | "set" | "log", unknown, unknown]>): unknown
 export function nativeBehavior(module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
 export function binding(value: unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown

package/framework/core.mjs

@@ -10,6 +10,8 @@ const listFieldMarker = Symbol("kudzu.listField")
 const listExpressionMarker = Symbol("kudzu.listExpression")
 const listItemMarker = Symbol("kudzu.listItem")
 const refMarker = Symbol("kudzu.ref")
+const contextMarker = Symbol("kudzu.context")
+const contextProviderMarker = Symbol("kudzu.contextProvider")
 const noSelectValue = Symbol("kudzu.no-select-value")
 
 let renderContext
@@ -44,6 +46,23 @@ export function useRef(initialValue) {
   return { [refMarker]: true, id: `r${renderContext.nextRef++}`, current: null }
 }
 
+export function createContext(defaultValue) {
+  const context = { [contextMarker]: true, defaultValue }
+  context.Provider = function Provider({ value, children }) {
+    return { [contextProviderMarker]: true, context, value, children }
+  }
+  return context
+}
+
+export function useContext(context) {
+  if (!renderContext) throw new Error("useContext() can only run while rendering a Kudzu component")
+  if (!context?.[contextMarker]) throw new Error("useContext() requires a Kudzu context")
+  for (let index = renderContext.contexts.length - 1; index >= 0; index--) {
+    if (renderContext.contexts[index][0] === context) return renderContext.contexts[index][1]
+  }
+  return context.defaultValue
+}
+
 export function behavior(commands) {
   return {
     [behaviorMarker]: true,
@@ -63,7 +82,7 @@ export function nativeBehavior(module, handler, states, scope) {
       if (!signal?.[signalMarker]) throw new Error("A native behavior must target framework state")
       return [name, signal.id]
     })),
-    scope: Object.fromEntries(scope.map(([name, value]) => [name, serializeCapture(name, value, new Set())]))
+    scope: Object.fromEntries(scope.map(([name, value]) => [name, value?.[signalMarker] ? { type: "state", id: value.id } : serializeCapture(name, value, new Set())]))
   }
 }
 
@@ -197,7 +216,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}) {
-  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listFields: undefined, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listFields: undefined, contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const body = await renderNode({ type: component, props: {} })
@@ -299,6 +318,14 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     return escapeHtml(node)
   }
   if (node instanceof Promise) return renderNode(await node, namespace, selectValue)
+  if (node?.[contextProviderMarker]) {
+    renderContext.contexts.push([node.context, node.value])
+    try {
+      return await renderNode(node.children, namespace, selectValue)
+    } finally {
+      renderContext.contexts.pop()
+    }
+  }
   if (node?.[conditionalMarker]) {
     const descriptor = bindingDescriptor(node)
     const stateIds = reactiveStateIds(descriptor)

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/framework/native-runtime.js

@@ -20,7 +20,7 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
       return state.get(stateIds[name])
     },
     scope(name) {
-      return scope[name]
+      return serializedScope[name]?.type === "state" ? state.get(serializedScope[name].id) : scope[name]
     },
     set(name, value) {
       const id = stateIds[name]

package/package.json

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