@kudzujs/core 0.4.11 → 0.4.13

package/README.md

@@ -98,6 +98,14 @@ function increaseTwice() {
 
 The handler above increments by two and patches its bound DOM once. Inspect the generated plan at `.kudzu/kudzu-plan.json`.
 
+State may also hold serializable plain objects. Property expressions in JSX text update directly:
+
+```tsx
+const [weather, setWeather] = useState({ temperature: 28, label: "Warm" })
+
+return <p>{weather.temperature}° {weather.label}</p>
+```
+
 ## Reactive Attributes
 
 `className`, `disabled`, controlled `value`, and controlled `checked` accept normal state-dependent TSX expressions. The same `value` binding works for inputs and selects:
@@ -139,6 +147,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:
@@ -189,6 +217,7 @@ const rows = items.map(item =>
     style={{ opacity: item.done ? 0.5 : 1 }}
   >
     {item.name.toUpperCase()}
+    {item.done ? <strong>Complete</strong> : <span>Pending</span>}
     <button onClick={() => setItems(items.filter(entry => entry.id !== item.id))}>Remove</button>
   </li>
 )
@@ -196,9 +225,9 @@ const rows = items.map(item =>
 return <ul>{rows}</ul>
 ```
 
-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.
+Kudzu emits initial items as static HTML, then adds, removes, updates, styles, conditional branches, 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. Single-level item-local `&&` and ternary JSX conditions patch only their bounded branch and mount or unmount its handlers. 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 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>`.
+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 item 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
 
@@ -261,6 +290,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
@@ -283,13 +313,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 | **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 |
+| 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.
 
@@ -299,13 +329,13 @@ Same content and CSS across every fixture:
 
 | Framework | Initial content | Initial JS gzip | Total output | Clean build |
 |---|---:|---:|---:|---:|
-| 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 |
+| 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
 
@@ -313,15 +343,15 @@ The list starts with 1,000 keyed items, then updates every label, reverses the o
 
 | Framework | Initial content | Initial JS gzip | Total output | Build | Update | Reverse | Remove | Add | Operations total |
 |---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
-| 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.
+| 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.4 KB | 61.6 KB | **448 ms** | 8.6 ms | 8.3 ms | 2.4 ms | 8.6 ms | 27.9 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 27.9 ms, 15.4 ms behind the hand-authored Astro baseline and 6.2 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,12 +1,12 @@
 # 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.
 - `binding-runtime.js`: optional generic attributes, form properties, and conditional range patches.
-- `list-runtime.js`: optional keyed list validation, external item-expression evaluation, dynamic styles and item-handler scopes, moves, and cleanup.
+- `list-runtime.js`: optional keyed list validation, external item-expression evaluation, item-local conditional ranges, dynamic styles and 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.

package/framework/binding-runtime.js

@@ -9,11 +9,14 @@ const mountedBindings = new WeakSet()
 const mountedConditions = new WeakSet()
 const bindingRegistrations = new WeakMap()
 const conditionRegistrations = new WeakMap()
-const bindingTypes = ["class", "disabled", "value", "checked", "style"]
+const bindingTypes = ["text", "class", "disabled", "value", "checked", "style"]
 const bindingSelector = [...bindingTypes.map(target => `[data-k-bind-${target}]`), "[data-k-bind-attrs]"].join(",")
 
 export function patchBinding(node, target, value) {
-  if (target === "disabled") {
+  if (target === "text") {
+    const next = value == null ? "" : String(value)
+    if (node.textContent !== next) node.textContent = next
+  } else if (target === "disabled") {
     node.toggleAttribute("disabled", Boolean(value))
   } else if (target === "checked") {
     node.checked = Boolean(value)

package/framework/build.mjs

@@ -328,6 +328,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
     const listLocalUses = new WeakMap()
     const listValues = new WeakMap()
     const listEventItems = new WeakMap()
+    const listConditions = new WeakMap()
     let usesBehavior = false
     let usesBinding = false
     let usesConditional = false
@@ -431,6 +432,15 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         }
       }
 
+      if (ts.isJsxExpression(node) && node.expression && listConditions.has(node.expression)) {
+        const entry = listConditions.get(node.expression)
+        return factory.updateJsxExpression(node, compileListConditional({
+          ...entry,
+          truthy: ts.visitNode(entry.truthy, visitor),
+          falsy: ts.visitNode(entry.falsy, visitor)
+        }, factory, listExpressions, handlerUrl))
+      }
+
       if (ts.isJsxExpression(node) && node.expression && listValues.has(node.expression)) {
         return factory.updateJsxExpression(node, compileListValue(node.expression, listValues.get(node.expression), factory, listExpressions, handlerUrl))
       }
@@ -443,7 +453,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         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)
+          validateKeyedList(listParts, sourceFile, settersForNode(node, settersByFunction), listValues, listEventItems, listConditions)
           usesBehavior = true
           usesList = true
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
@@ -466,6 +476,14 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
             return factory.updateJsxExpression(node, compiled)
           }
         }
+        const setters = settersForNode(node, settersByFunction)
+        const usedStates = referencedStateNames(node.expression, setters)
+        const captures = captureNames(node.expression, node.expression, setters)
+        if ((usedStates.size || captures.size) && !ts.isIdentifier(node.expression) && !containsJsx(node.expression)) {
+          usesBehavior = true
+          usesBinding = true
+          return factory.updateJsxExpression(node, compileReactiveBinding(node.expression, setters, factory, context, reactiveBindings, handlerUrl))
+        }
       }
 
       if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && !/^on/i.test(node.name.getText()) && !["key", "ref", "dangerouslysetinnerhtml"].includes(node.name.getText().toLowerCase())) {
@@ -507,6 +525,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       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")))
+      behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listConditional"), factory.createIdentifier("__kListConditional")))
     }
     if (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
@@ -536,7 +555,7 @@ function keyedListParts(expression, setters) {
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
 }
 
-function validateKeyedList(parts, sourceFile, setters, listValues, listEventItems) {
+function validateKeyedList(parts, sourceFile, setters, listValues, listEventItems, listConditions) {
   const fail = (node, message) => {
     const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
@@ -545,6 +564,7 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
     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")
   }
+  let conditionDepth = 0
   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)
@@ -556,7 +576,18 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
     }
     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 condition = conditionalParts(expression)
+      if (condition && containsJsx(expression)) {
+        if (conditionDepth) fail(node, "Nested item conditions are not supported in keyed lists")
+        if (!referencesIdentifier(condition.condition, parts.item)) fail(node, "Keyed list item conditions must read the item")
+        validateListExpression(condition.condition, parts.item, node, fail)
+        listConditions.set(node.expression, { ...condition, item: parts.item })
+        conditionDepth++
+        visit(condition.truthy)
+        visit(condition.falsy)
+        conditionDepth--
+        return
+      }
       const field = directProperty(expression, parts.item)
       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`)
@@ -645,6 +676,16 @@ function compileListExpression(read, expression, item, factory, listExpressions,
   return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)])
 }
 
+function compileListConditional(entry, factory, listExpressions, handlerUrl) {
+  const exportName = `listExpression${listExpressions.length}`
+  listExpressions.push({ exportName, expression: entry.condition, item: entry.item })
+  const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), entry.condition)
+  const thunk = branch => factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), branch)
+  return factory.createCallExpression(factory.createIdentifier("__kListConditional"), undefined, [
+    factory.createStringLiteral(entry.kind), read, thunk(entry.truthy), thunk(entry.falsy), 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

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
@@ -17,6 +24,7 @@ export function list(items: unknown, keyField: string, render: (item: 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 listConditional(kind: "and" | "ternary", read: () => unknown, truthy: () => unknown, falsy: () => unknown, module: string, handler: string): unknown
 
 export function renderPage(
   component: (props: Record<string, never>) => unknown | Promise<unknown>,

package/framework/core.mjs

@@ -9,7 +9,10 @@ const listMarker = Symbol("kudzu.list")
 const listFieldMarker = Symbol("kudzu.listField")
 const listExpressionMarker = Symbol("kudzu.listExpression")
 const listItemMarker = Symbol("kudzu.listItem")
+const listConditionalMarker = Symbol("kudzu.listConditional")
 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 +47,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 +83,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())]))
   }
 }
 
@@ -104,6 +124,10 @@ export function listItem() {
   return { [listItemMarker]: true }
 }
 
+export function listConditional(kind, read, truthy, falsy, module, handler) {
+  return { [listConditionalMarker]: true, kind, value: renderContext?.listTemplate ? undefined : read(), truthy, falsy, module, handler }
+}
+
 function validListKey(key) {
   return typeof key === "string" || typeof key === "number" && Number.isFinite(key)
 }
@@ -197,7 +221,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, listInitialMarkers: false, listConditionalBranch: 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 +323,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)
@@ -321,15 +353,44 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
   if (node?.[listMarker]) return renderList(node, namespace, selectValue)
   if (node?.[listFieldMarker]) {
-    if (renderContext.listTemplate) renderContext.listFields?.add(node.field)
-    const marker = renderContext.listTemplate ? ` data-k-list-text="${escapeAttribute(node.field)}"` : ""
+    if (renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) renderContext.listFields?.add(node.field)
+    const marker = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch ? ` data-k-list-text="${escapeAttribute(node.field)}"` : ""
     return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-text-end></template>`
   }
   if (node?.[listExpressionMarker]) {
     const descriptor = { module: node.module, handler: node.handler }
-    const marker = renderContext.listTemplate ? ` data-k-list-expression='${escapeJsonAttribute(descriptor)}'` : ""
+    const marker = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch ? ` data-k-list-expression='${escapeJsonAttribute(descriptor)}'` : ""
     return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
   }
+  if (node?.[bindingMarker]) {
+    const descriptor = bindingDescriptor(node)
+    const reactive = Object.keys(node.states).length > 0 || Object.keys(node.scopeStates).length > 0 || Object.keys(node.scopeBindings).length > 0
+    if (!reactive) return renderNode(node.value, namespace, selectValue)
+    renderContext.bindings.push({ target: "text", ...descriptor })
+    if (renderContext.conditionDepth || renderContext.listDepth) for (const stateId of reactiveStateIds(descriptor)) renderContext.conditionStates.add(stateId)
+    renderContext.hasBehaviors = true
+    renderContext.hasBindings = true
+    return `<span data-k-bind-text='${escapeJsonAttribute(descriptor)}'>${escapeHtml(node.value ?? "")}</span>`
+  }
+  if (node?.[listConditionalMarker]) {
+    const descriptor = { kind: node.kind, module: node.module, handler: node.handler }
+    const previousBranch = renderContext.listConditionalBranch
+    renderContext.listConditionalBranch = true
+    let truthy
+    let falsy
+    try {
+      truthy = await renderNode(node.truthy(), namespace, selectValue)
+      falsy = await renderNode(node.falsy(), namespace, selectValue)
+    } finally {
+      renderContext.listConditionalBranch = previousBranch
+    }
+    const key = conditionKey(node.kind, node.value)
+    const current = renderContext.listTemplate
+      ? ""
+      : node.kind === "and" && !node.value ? escapeHtml(renderFalsy(node.value)) : node.value ? truthy : falsy
+    const initial = renderContext.listTemplate ? "" : ` data-k-list-current="${escapeAttribute(key)}"`
+    return `<template data-k-list-condition='${escapeJsonAttribute(descriptor)}'${initial}><template data-k-list-true>${truthy}</template><template data-k-list-false>${falsy}</template></template>${current}<template data-k-list-condition-end></template>`
+  }
   if (!node || typeof node !== "object" || !("type" in node)) {
     throw new Error(`Cannot render ${String(node)}`)
   }
@@ -432,10 +493,10 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
 
   if (attributeBindings.length) attributes += ` data-k-bind-attrs='${escapeJsonAttribute(attributeBindings)}'`
-  if (renderContext.listTemplate && listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
-  if (renderContext.listTemplate && listExpressionAttributes.length) attributes += ` data-k-list-expression-attrs='${escapeJsonAttribute(listExpressionAttributes)}'`
-  if (renderContext.listTemplate && listEvents.length) attributes += ` data-k-list-events='${escapeJsonAttribute(listEvents)}'`
-  if (renderContext.listTemplate && directListText) {
+  if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
+  if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listExpressionAttributes.length) attributes += ` data-k-list-expression-attrs='${escapeJsonAttribute(listExpressionAttributes)}'`
+  if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && listEvents.length) attributes += ` data-k-list-events='${escapeJsonAttribute(listEvents)}'`
+  if ((renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) && directListText) {
     renderContext.listFields?.add(directListText.field)
     attributes += ` data-k-list-text="${escapeAttribute(directListText.field)}"`
   }
@@ -460,10 +521,12 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listRoot = { id, template: true }
     const template = await renderNode(node.render({}), namespace, selectValue)
     if (template.includes("data-k-native-")) descriptor.mount = true
+    if (template.includes("data-k-list-condition")) descriptor.conditions = true
     const seed = listSeed(node.items.value, renderContext.listFields)
     if (seed) descriptor.seed = seed
     let current = ""
     renderContext.listTemplate = false
+    renderContext.listInitialMarkers = Boolean(descriptor.conditions)
     for (const item of node.items.value) {
       renderContext.listRoot = { id, key: item[node.keyField], template: false }
       current += await renderNode(node.render(item), namespace, selectValue)
@@ -475,6 +538,7 @@ async function renderList(node, namespace, selectValue) {
   } finally {
     renderContext.listRoot = undefined
     renderContext.listTemplate = false
+    renderContext.listInitialMarkers = false
     renderContext.listFields = previousListFields
     renderContext.listDepth--
   }
@@ -485,6 +549,14 @@ function optionValue(props) {
   return Array.isArray(props.children) ? props.children.join("") : props.children ?? ""
 }
 
+function conditionKey(kind, value) {
+  return value ? "true" : kind === "and" ? `false:${renderFalsy(value)}` : "false"
+}
+
+function renderFalsy(value) {
+  return value === false || value == null || value === true ? "" : String(value)
+}
+
 function reactiveStateIds(descriptor) {
   if (descriptor.state) return new Set([descriptor.state])
   return new Set([

package/framework/list-runtime.js

@@ -6,7 +6,8 @@ const mountedLists = new WeakSet()
 const imports = new Map()
 const revisions = new WeakMap()
 const itemParts = new WeakMap()
-const itemPartsSelector = "[data-k-list-text],[data-k-list-attrs],[data-k-list-events],[data-k-list-expression],[data-k-list-expression-attrs]"
+const conditionOwners = new WeakMap()
+const itemPartsSelector = "[data-k-list-text],[data-k-list-attrs],[data-k-list-events],[data-k-list-expression],[data-k-list-expression-attrs],[data-k-list-condition]"
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -32,7 +33,7 @@ function mountLists(root) {
     const roots = listRoots(start, end)
     const templateRoot = start.content.firstElementChild
     const parts = listItemPartPlan(templateRoot)
-    for (const root of roots) mapListItemParts(parts, root)
+    for (const root of roots) descriptor.conditions ? listItemParts(root) : mapListItemParts(parts, root)
     if (descriptor.seed && !browserState.has(descriptor.state)) browserState.set(descriptor.state, roots.map((root, index) => seedListItem(root, descriptor, index)))
     const items = browserState.get(descriptor.state)
     const list = {
@@ -144,6 +145,10 @@ function fillListItem(root, item) {
   const revision = (revisions.get(root) ?? 0) + 1
   revisions.set(root, revision)
   const parts = listItemParts(root)
+  fillListParts(root, parts, item, revision)
+}
+
+function fillListParts(root, parts, item, revision) {
   for (const [node, field] of parts.directTexts) {
     const text = item?.[field]
     const value = text == null ? "" : String(text)
@@ -178,18 +183,27 @@ function fillListItem(root, item) {
       }).catch(error => console.error(error))
     }
   }
+  for (const [marker, descriptor] of parts.conditions) {
+    evaluate(descriptor, item).then(value => {
+      if (revisions.get(root) === revision && root.isConnected) updateListCondition(marker, descriptor.kind, value, item)
+    }).catch(error => console.error(error))
+  }
 }
 
 function listItemParts(root) {
   let parts = itemParts.get(root)
   if (parts) return parts
-  parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [] }
+  parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [], conditions: [] }
   for (const node of matching(root, itemPartsSelector)) {
     if (node.hasAttribute("data-k-list-text")) (node.tagName === "TEMPLATE" ? parts.texts : parts.directTexts).push([node, node.dataset.kListText])
     if (node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
     if (node.hasAttribute("data-k-list-events")) parts.events.push([node, node.dataset.kListEvents])
     if (node.hasAttribute("data-k-list-expression")) parts.expressions.push([node, JSON.parse(node.dataset.kListExpression)])
     if (node.hasAttribute("data-k-list-expression-attrs")) parts.expressionAttributes.push([node, JSON.parse(node.dataset.kListExpressionAttrs)])
+    if (node.hasAttribute("data-k-list-condition")) {
+      parts.conditions.push([node, JSON.parse(node.dataset.kListCondition)])
+      conditionOwners.set(node, root)
+    }
   }
   itemParts.set(root, parts)
   return parts
@@ -205,7 +219,8 @@ function listItemPartPlan(template) {
     attributes: parts.attributes.map(([node, attributes]) => [indexes.get(node), attributes]),
     events: parts.events.map(([node, events]) => [indexes.get(node), events]),
     expressions: parts.expressions.map(([node, descriptor]) => [indexes.get(node), descriptor]),
-    expressionAttributes: parts.expressionAttributes.map(([node, attributes]) => [indexes.get(node), attributes])
+    expressionAttributes: parts.expressionAttributes.map(([node, attributes]) => [indexes.get(node), attributes]),
+    conditions: parts.conditions.map(([node, descriptor]) => [indexes.get(node), descriptor])
   }
 }
 
@@ -217,10 +232,50 @@ function mapListItemParts(parts, root) {
     attributes: parts.attributes.map(([index, attributes]) => [target[index], attributes]),
     events: parts.events.map(([index, events]) => [target[index], events]),
     expressions: parts.expressions.map(([index, descriptor]) => [target[index], descriptor]),
-    expressionAttributes: parts.expressionAttributes.map(([index, attributes]) => [target[index], attributes])
+    expressionAttributes: parts.expressionAttributes.map(([index, attributes]) => [target[index], attributes]),
+    conditions: parts.conditions.map(([index, descriptor]) => {
+      conditionOwners.set(target[index], root)
+      return [target[index], descriptor]
+    })
   })
 }
 
+function updateListCondition(marker, kind, value, item) {
+  const current = listConditionKey(kind, value)
+  if (marker.dataset.kListCurrent === current) return
+  let end = marker.nextSibling
+  while (end && !(end.nodeType === Node.ELEMENT_NODE && end.matches("template[data-k-list-condition-end]"))) end = end.nextSibling
+  if (!end) throw new Error("Keyed list condition marker has no end")
+  for (let node = marker.nextSibling; node && node !== end;) {
+    const next = node.nextSibling
+    unmountDom(node)
+    node.remove()
+    node = next
+  }
+  const falseText = kind === "and" && !value ? renderFalsy(value) : ""
+  const fragment = falseText
+    ? marker.ownerDocument.createDocumentFragment()
+    : marker.content.querySelector(value ? "template[data-k-list-true]" : "template[data-k-list-false]").content.cloneNode(true)
+  if (falseText) fragment.append(marker.ownerDocument.createTextNode(falseText))
+  const nodes = [...fragment.childNodes]
+  const revision = (revisions.get(marker) ?? 0) + 1
+  revisions.set(marker, revision)
+  fillListParts(marker, listItemParts(fragment), item, revision)
+  end.parentNode.insertBefore(fragment, end)
+  marker.dataset.kListCurrent = current
+  const owner = conditionOwners.get(marker)
+  if (owner) itemParts.delete(owner)
+  for (const node of nodes) mountDom(node)
+}
+
+function listConditionKey(kind, value) {
+  return value ? "true" : kind === "and" ? `false:${renderFalsy(value)}` : "false"
+}
+
+function renderFalsy(value) {
+  return value === false || value == null || value === true ? "" : String(value)
+}
+
 function listRoots(start, end) {
   const roots = []
   for (let node = start.nextSibling; node && node !== end; node = node.nextSibling) {

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.11",
+  "version": "0.4.13",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",