@kudzujs/core 0.6.20 → 0.6.21

package/README.md

@@ -388,7 +388,18 @@ return <ItemList items={items} />
 
 The original row component remains reusable across multiple lists and ordinary JSX. State-backed list wrappers and row components are specialized to intrinsic JSX at build time; no component function or component runtime is shipped to the browser. 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, in one top-level immutable `const` rendered once as a JSX child, or in one synchronous wrapper receiving the state identifier as a direct prop. 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 and effects receive the latest JSON-safe item for their key. Effects mount after a row is connected and clean up when it is removed. A direct primitive item dependency such as `[item.name]`, optionally mixed with state as `[version, item.name]`, reruns only rows whose selected value changed; the replacement setup receives the complete latest item. Unrelated fields and reorder do not rerun it, while a key change removes and mounts the row. The item remains stored once in shared list state; runtime 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 or top-level local or relative-imported row component, and `key={item.<field>}`. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Same-file wrappers must be unexported and state-backed at every call; relative default, named/aliased, and direct named re-export wrappers are specialized per qualifying call. Row components accept destructured projected props, top-level single-`const` calculations and inline effects before one intrinsic return. Effect dependencies inside a row may be empty, direct primitive Kudzu state identifiers, or direct `item.<field>` properties whose selected values remain JSON-safe primitives. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` dependencies are rejected. 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, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package, namespace, and star-export list wrappers, package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions, lists, or component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+One nested keyed map may read a direct array property of its parent item. This supports category/item data populated after mount while preserving both parent and child DOM identity across updates and reorder:
+
+```tsx
+{categories.map(category => <section key={category.id}>
+  <h2>{category.title}</h2>
+  <ul>{category.items.map(item => <li key={item.id}>{item.title}</li>)}</ul>
+</section>)}
+```
+
+The nested collection must be `parent.<field>`, the child row must have one intrinsic root, and child handlers may capture the child item. A second child list, third nesting level, computed collection, parent-item capture from the child row, child conditions, child effects, child components, and child row-local state remain unsupported.
+
+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 or top-level local or relative-imported row component, and `key={item.<field>}`. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Same-file wrappers must be unexported and state-backed at every call; relative default, named/aliased, and direct named re-export wrappers are specialized per qualifying call. Row components accept destructured projected props, top-level single-`const` calculations and inline effects before one intrinsic return. Effect dependencies inside a row may be empty, direct primitive Kudzu state identifiers, or direct `item.<field>` properties whose selected values remain JSON-safe primitives. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` dependencies are rejected. 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, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package, namespace, and star-export list wrappers, package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions beyond the direct one-level form above, component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 The focused wrapper fixture emits 1,393 B raw / 500 B gzip HTML and 10,719 B raw / 4,665 B gzip JavaScript across its route capabilities. After one warm-up, seven clean builds measured 314.1, 325.3, 322.3, 327.2, 336.1, 322.4, and 315.0 ms, with a 322.4 ms median.
 

package/framework/build.mjs

@@ -197,9 +197,10 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasListSeeds = plans.some(plan => plan.lists.some(list => list.seed))
   const hasListEffects = plans.some(plan => plan.lists.some(list => list.effects))
   const hasListRowStates = plans.some(plan => plan.lists.some(list => list.rowStates))
+  const hasNestedLists = plans.some(plan => plan.lists.some(list => list.ownerField))
   const hasItemDependencies = plans.some(plan => plan.effects.some(effect => effect.itemDependencies?.length))
   const hasListAsyncParts = hasListExpressions || hasListExpressionAttributes || hasListConditions
-  const hasListMounts = hasListConditions || plans.some(plan => plan.lists.some(list => list.mount))
+  const hasListMounts = hasListConditions || hasNestedLists || plans.some(plan => plan.lists.some(list => list.mount))
   const hasNestedStateCaptures = hasNestedCaptureState(plans)
   const hasSetterCaptures = hasCaptureType(plans, "setter")
   const hasEffectCaptures = plans.some(plan => plan.effects.some(effect => Object.keys(effect.scope).length))
@@ -278,7 +279,8 @@ export async function build({ quiet = false, minify = true } = {}) {
       __KUDZU_LIST_ASYNC_PARTS__: String(hasListAsyncParts),
       __KUDZU_LIST_MOUNTS__: String(hasListMounts),
       __KUDZU_LIST_ITEM_HOOKS__: String(hasItemDependencies),
-      __KUDZU_LIST_ROW_STATES__: String(hasListRowStates)
+      __KUDZU_LIST_ROW_STATES__: String(hasListRowStates),
+      __KUDZU_NESTED_LISTS__: String(hasNestedLists)
     })
   }
   if (hasNativeHandlers) {
@@ -1666,6 +1668,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     const listValues = new WeakMap()
     const listEventItems = new WeakMap()
     const listConditions = new WeakMap()
+    const nestedLists = new WeakMap()
     const listEffectEntries = new WeakMap()
     let usesBehavior = false
     let usesBinding = false
@@ -2018,7 +2021,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         calculation.parent = callback
         validateListExpression(calculation, parts.item, originalParts.root, fail)
       }
-      validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, settersForNode(originalParts.root, settersByFunction), specialization?.rowState)
+      validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, settersForNode(originalParts.root, settersByFunction), specialization?.rowState, nestedLists)
       if (specialization?.effects.length) {
         usesListEffects = true
         const statements = specialization.effects.map(entry => {
@@ -2185,14 +2188,16 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       }
 
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
-        const listParts = renderedLists.get(node)
+        const nestedParts = nestedLists.get(unwrapExpression(node.expression))
+        const listParts = renderedLists.get(node) ?? nestedParts
         if (listParts) {
           usesBehavior = true
           usesList = true
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
             listParts.state,
             factory.createStringLiteral(listParts.keyField),
-            ts.visitNode(listParts.callback, visitor)
+            ts.visitNode(listParts.callback, visitor),
+            ...(nestedParts ? [factory.createStringLiteral(listParts.ownerField)] : [])
           ]))
         }
         const conditional = conditionalParts(node.expression)
@@ -2395,6 +2400,25 @@ function keyedListParts(expression, setters) {
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
 }
 
+function nestedKeyedListParts(expression, parentItem) {
+  const value = unwrapExpression(expression)
+  if (!ts.isCallExpression(value) || value.arguments.length !== 1 || !ts.isPropertyAccessExpression(value.expression) || value.expression.name.text !== "map") return undefined
+  const collection = value.expression.expression
+  if (!ts.isPropertyAccessExpression(collection) || !ts.isIdentifier(collection.expression) || collection.expression.text !== parentItem) return undefined
+  const callback = value.arguments[0]
+  if (!ts.isArrowFunction(callback) || callback.parameters.length !== 1 || !ts.isIdentifier(callback.parameters[0].name)) {
+    throw new Error("Nested 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("Nested 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) && ts.isIdentifier(attribute.name) && attribute.name.text === "key")
+  const item = callback.parameters[0].name.text
+  const keyField = key && ts.isJsxAttribute(key) && key.initializer && ts.isJsxExpression(key.initializer) && key.initializer.expression && directProperty(key.initializer.expression, item)
+  if (!keyField) throw new Error(`Nested keyed list root must have key={${item}.<field>}`)
+  return { callback, root, item, keyField, ownerField: collection.name.text }
+}
+
 function isStateBackedListComponentCall(call, component, setters) {
   if (component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name)) return false
   const attributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
@@ -2479,7 +2503,7 @@ function insideJsxEventHandler(node, root) {
   return false
 }
 
-function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, setters, rowState) {
+function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, setters, rowState, nestedLists) {
   const fail = (node, message) => {
     throw sourceNodeError(node, sourceFile, message)
   }
@@ -2490,10 +2514,11 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
     if (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(node, "Keyed list items must use intrinsic JSX elements")
   }
   let conditionDepth = 0
+  let nestedList
   const visit = node => {
     if (ts.isJsxFragment(node)) fail(node, "Fragments are not supported in keyed lists")
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) validateElement(node)
-    if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, "Nested keyed lists are not supported")
+    if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, parts.nested ? "Keyed lists support at most one nested level" : "Nested keyed list collections must be a direct property of the parent item")
     if (ts.isJsxSpreadAttribute(node) && referencesIdentifier(node.expression, item)) fail(node, "Keyed list item spreads are not supported")
     if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.text)) {
       listEventItems.set(node, item)
@@ -2501,8 +2526,21 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
     }
     if (ts.isJsxExpression(node) && node.expression) {
       const expression = unwrapExpression(node.expression)
+      if (containsJsx(expression) && ts.isCallExpression(expression) && ts.isPropertyAccessExpression(expression.expression) && expression.expression.name.text === "map") {
+        const nested = nestedKeyedListParts(expression, item)
+        if (!nested) fail(expression, parts.nested ? "Keyed lists support at most one nested level" : "Nested keyed list collections must be a direct property of the parent item")
+        if (parts.nested) fail(expression, "Keyed lists support at most one nested level")
+        if (nestedList) fail(expression, "Keyed list rows support one nested keyed list")
+        if (referenceIdentifiers(nested.callback, item).length) fail(nested.root, "Nested keyed list rows cannot capture the parent item")
+        nestedList = nested
+        const nestedParts = { ...nested, state: parts.state, nested: true }
+        nestedLists.set(expression, nestedParts)
+        validateKeyedList(nestedParts, sourceFile, listValues, listEventItems, listConditions, setters, undefined, nestedLists)
+        return
+      }
       const condition = conditionalParts(expression)
       if (condition && containsJsx(expression)) {
+        if (parts.nested) fail(node, "Nested keyed list item conditions are not supported")
         if (conditionDepth) fail(node, "Nested item conditions are not supported in keyed lists")
         if (rowState && referencedStateNames(condition.condition, setters).has(rowState.state)) {
           conditionDepth++

package/framework/core.d.ts

@@ -27,7 +27,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 list(items: unknown, keyField: string, render: (item: unknown) => unknown, ownerField?: string): unknown
 export function listField(read: () => unknown, field: string): unknown
 export function listExpression(read: () => unknown, module: string, handler: string): unknown
 export function listItem(): unknown

package/framework/core.mjs

@@ -214,10 +214,18 @@ export function stateConditional(kind, state, truthy, falsy) {
   return { [conditionalMarker]: true, kind, value: state.value, truthy, falsy, state: state.id }
 }
 
-export function list(items, keyField, render) {
+export function list(items, keyField, render, ownerField) {
   if (!items?.[signalMarker] || !Array.isArray(items.value)) throw new Error("A keyed list must use local array state")
+  let values = items.value
+  if (ownerField) {
+    const owner = renderContext?.listRoot ?? renderContext?.listRowRoot
+    if (!owner) throw new Error("A nested keyed list must be rendered inside a keyed row")
+    renderContext.listFields?.add(ownerField)
+    values = renderContext.listTemplate ? [] : owner.item?.[ownerField]
+    if (!Array.isArray(values)) throw new Error(`Nested keyed list property "${ownerField}" must remain an array`)
+  }
   const keys = new Set()
-  for (const item of items.value) {
+  for (const item of values) {
     const key = item?.[keyField]
     if (!validListKey(key)) throw new Error(`Keyed list key "${keyField}" must be a string or finite number`)
     assertListItem(item)
@@ -226,7 +234,7 @@ export function list(items, keyField, render) {
     if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
     keys.add(token)
   }
-  return { [listMarker]: true, items, keyField, render }
+  return { [listMarker]: true, items, values, keyField, render, ownerField }
 }
 
 export function listField(read, field) {
@@ -347,7 +355,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}, layout) {
-  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowConditions: [], effectOwners: [], contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }
@@ -735,23 +743,33 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
 
 async function renderList(node, namespace, selectValue) {
   if (namespace) throw new Error(`Reactive keyed lists are not supported inside ${namespace}`)
-  const id = nextRenderId("l")
-  const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.items.value.map(item => item[node.keyField]), ...(node.items[reducerStateMarker] ? { reducer: true } : {}) }
+  const ownerRoot = node.ownerField ? renderContext.listRoot ?? renderContext.listRowRoot : undefined
+  const ownerTemplate = Boolean(node.ownerField && renderContext.listTemplate)
+  const id = node.ownerField ? nextRowListId() : nextRenderId("l")
+  const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.values.map(item => item[node.keyField]), ...(node.ownerField ? { ownerField: node.ownerField } : {}), ...(node.items[reducerStateMarker] ? { reducer: true } : {}) }
+  if (ownerTemplate) Object.assign(ownerRoot.descriptor, { child: { field: node.ownerField, key: node.keyField }, mount: true, nested: true })
   renderContext.listDepth++
+  const previousListRoot = renderContext.listRoot
+  const previousListRowRoot = renderContext.listRowRoot
+  const previousListTemplate = renderContext.listTemplate
+  const previousListInitialMarkers = renderContext.listInitialMarkers
   const previousListFields = renderContext.listFields
   const previousListEffectOwners = renderContext.listEffectOwners
   const previousListRowStates = renderContext.listRowStates
   const previousListRowConditions = renderContext.listRowConditions
+  const previousListRowLists = renderContext.listRowLists
   try {
     renderContext.listTemplate = true
     renderContext.listEffectOwners = []
     renderContext.listRowStates = []
     renderContext.listRowConditions = []
+    renderContext.listRowLists = []
     renderContext.listFields = new Set([node.keyField])
-    renderContext.listRoot = { id, state: node.items.id, template: true, effects: [], item: {}, rowIndexes: { s: 0, c: 0 } }
+    renderContext.listRoot = { id, state: node.items.id, descriptor, template: true, effects: [], item: {}, rowIndexes: { s: 0, c: 0, l: 0 } }
     renderContext.listRowRoot = renderContext.listRoot
     const template = await renderNode(node.render({}), namespace, selectValue)
-    if (template.includes("data-k-native-") || template.includes("data-k-effects=")) descriptor.mount = true
+    if (template.includes("data-k-native-") || template.includes("data-k-effects=") || template.includes("data-k-list=")) descriptor.mount = true
+    if (template.includes("data-k-list=")) descriptor.nested = true
     if (template.includes("data-k-effects=")) descriptor.effects = true
     if (template.includes("data-k-list-condition")) descriptor.conditions = true
     if (template.includes("data-k-list-text-end")) descriptor.textRanges = true
@@ -764,33 +782,47 @@ async function renderList(node, namespace, selectValue) {
       if (renderContext.listRowConditions.length) descriptor.rowConditions = renderContext.listRowConditions.map(({ id }) => id)
       descriptor.mount = true
     }
-    const seed = listSeed(node.items.value, renderContext.listFields)
+    const seed = node.ownerField ? undefined : listSeed(node.values, 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, state: node.items.id, key: item[node.keyField], template: false, effects: [], item, rowIndexes: { s: 0, c: 0 } }
+    for (const item of node.values) {
+      renderContext.listRoot = { id, state: node.items.id, descriptor, key: item[node.keyField], template: false, effects: [], item, rowIndexes: { s: 0, c: 0, l: 0 } }
       renderContext.listRowRoot = renderContext.listRoot
       current += await renderNode(node.render(item), namespace, selectValue)
     }
-    renderContext.lists.push(descriptor)
+    if (!node.ownerField || ownerTemplate) 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.listRowRoot = undefined
-    renderContext.listTemplate = false
-    renderContext.listInitialMarkers = false
+    renderContext.listRoot = previousListRoot
+    renderContext.listRowRoot = previousListRowRoot
+    renderContext.listTemplate = previousListTemplate
+    renderContext.listInitialMarkers = previousListInitialMarkers
     renderContext.listFields = previousListFields
     renderContext.listEffectOwners = previousListEffectOwners
     renderContext.listRowStates = previousListRowStates
     renderContext.listRowConditions = previousListRowConditions
+    renderContext.listRowLists = previousListRowLists
     renderContext.listDepth--
   }
 }
 
+function nextRowListId() {
+  const root = renderContext.listRoot ?? renderContext.listRowRoot
+  const index = root.rowIndexes.l++
+  if (renderContext.listTemplate) {
+    const id = nextRenderId("l")
+    renderContext.listRowLists[index] = { id }
+    return id
+  }
+  const entry = renderContext.listRowLists[index]
+  if (!entry) throw new Error("Nested keyed lists must have the same order for every parent item")
+  return entry.id
+}
+
 function nextRenderId(kind) {
   if (renderContext.scoped) return `${renderContext.renderScope === "layout" ? "l" : "r"}${kind}${renderContext.counters[renderContext.renderScope][kind]++}`
   const counters = { s: "nextState", r: "nextRef", c: "nextCondition", l: "nextList", e: "nextEffect", p: "nextParam" }

package/framework/list-runtime.js

@@ -7,6 +7,7 @@ const imports = __KUDZU_LIST_ASYNC_PARTS__ ? new Map() : undefined
 const revisions = __KUDZU_LIST_ASYNC_PARTS__ ? new WeakMap() : undefined
 const itemParts = new WeakMap()
 const listItems = new WeakMap()
+const ownedLists = __KUDZU_NESTED_LISTS__ ? new WeakMap() : undefined
 const conditionOwners = __KUDZU_LIST_CONDITIONS__ ? new WeakMap() : undefined
 const itemPartsSelector = `[data-k-list-text]${__KUDZU_LIST_ATTRIBUTES__ ? ",[data-k-list-attrs]" : ""}${__KUDZU_LIST_EVENTS__ ? ",[data-k-list-events]" : ""}${__KUDZU_LIST_EXPRESSIONS__ ? ",[data-k-list-expression]" : ""}${__KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? ",[data-k-list-expression-attrs]" : ""}${__KUDZU_LIST_CONDITIONS__ ? ",[data-k-list-condition]" : ""}${__KUDZU_LIST_EFFECTS__ ? ",[data-k-effects]" : ""}`
 
@@ -37,8 +38,8 @@ function mountLists(root) {
     const roots = listRoots(start, end)
     if (__KUDZU_LIST_ROW_STATES__ && descriptor.rowStates) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index])
     const templateRoot = start.content.firstElementChild
-    const parts = listItemPartPlan(templateRoot)
-    for (const root of roots) __KUDZU_LIST_CONDITIONS__ && descriptor.conditions ? listItemParts(root) : mapListItemParts(parts, root)
+    const parts = listItemPartPlan(templateRoot, descriptor.nested)
+    for (const root of roots) __KUDZU_LIST_CONDITIONS__ && descriptor.conditions ? listItemParts(root, descriptor.nested) : mapListItemParts(parts, root, descriptor.nested)
     if (__KUDZU_LIST_SEEDS__ && 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 = {
@@ -50,10 +51,18 @@ function mountLists(root) {
       values: new Map(),
       items: undefined,
       container: roots[0]?.parentNode,
-      boundary: end
+      boundary: end,
+      ...(__KUDZU_NESTED_LISTS__ && descriptor.ownerField ? { owner: listOwner(start) } : {})
+    }
+    if (__KUDZU_NESTED_LISTS__ && descriptor.ownerField) {
+      if (!list.owner) throw new Error("Nested keyed list has no parent row")
+      if (ownedLists.has(list.owner)) throw new Error("Keyed list rows support one nested keyed list")
+      ownedLists.set(list.owner, list)
+      listRegistrations.set(start, { list, owner: list.owner })
+    } else {
+      register(listTargets, descriptor.state, list)
+      listRegistrations.set(start, { state: descriptor.state, list })
     }
-    register(listTargets, descriptor.state, list)
-    listRegistrations.set(start, { state: descriptor.state, list })
     updateList(list)
   }
 }
@@ -65,9 +74,13 @@ function unmountLists(root) {
 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)
+    if (__KUDZU_NESTED_LISTS__ && registration.owner) {
+      if (ownedLists.get(registration.owner) === registration.list) ownedLists.delete(registration.owner)
+    } else {
+      const lists = listTargets.get(registration.state)
+      lists?.delete(registration.list)
+      if (!lists?.size) listTargets.delete(registration.state)
+    }
     if (__KUDZU_LIST_ROW_STATES__ && registration.list.descriptor.rowStates) for (const token of registration.list.roots.keys()) deleteRowStates(registration.list.descriptor, token)
   }
   listRegistrations.delete(start)
@@ -75,8 +88,12 @@ function unregisterList(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 items = __KUDZU_NESTED_LISTS__ && list.descriptor.ownerField
+    ? listItems.get(list.owner)?.[list.descriptor.ownerField]
+    : browserState.get(list.descriptor.state)
+  if (!Array.isArray(items)) throw new Error(list.descriptor.ownerField ? `Nested keyed list property "${list.descriptor.ownerField}" must remain an array` : "Keyed list state must remain an array")
+  if (__KUDZU_NESTED_LISTS__ && (list.descriptor.child || list.descriptor.ownerField) && list.items && updateNestedList(list, items)) return
+  if (__KUDZU_NESTED_LISTS__ && list.descriptor.child) validateChildLists(items, list.descriptor.child)
   if (list.descriptor.reducer && list.items && updateReducerList(list, items)) return
   const entries = []
   const keys = new Set()
@@ -132,15 +149,14 @@ function updateList(list) {
       if (!node) throw new Error("Keyed list template has no root element")
       node.removeAttribute("data-k-list-root")
       if (__KUDZU_LIST_ROW_STATES__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)
-      mapListItemParts(list.parts, node)
-      fillListItem(node, item)
+      mapListItemParts(list.parts, node, list.descriptor.nested)
+      fillListItem(node, item, list.descriptor.nested)
       additions.append(node)
       added = true
     } else if (list.values.get(token) !== value) {
-      fillListItem(node, item)
+      fillListItem(node, item, list.descriptor.nested)
       if (__KUDZU_LIST_ITEM_HOOKS__) notifyListItem(list.descriptor.state, node)
     }
-    listItems.set(node, item)
     next.push([token, node])
     values.set(token, value)
   }
@@ -184,6 +200,75 @@ function updateList(list) {
   list.items = items
 }
 
+function updateNestedList(list, items) {
+  const previous = list.items
+  if (items === previous) return false
+  if (items.length === previous.length && items.every((item, index) => item === previous[index])) {
+    list.items = items
+    return true
+  }
+  if (items.length === previous.length && items.every((item, index) => item === previous[previous.length - index - 1])) {
+    const tokens = [...list.roots.keys()].reverse()
+    const parent = list.container ?? list.start.parentNode
+    const reordered = parent.ownerDocument.createDocumentFragment()
+    reordered.append(...tokens.map(token => list.roots.get(token)))
+    parent.insertBefore(reordered, list.boundary)
+    list.roots = new Map(tokens.map(token => [token, list.roots.get(token)]))
+    list.items = items
+    list.container ??= parent
+    return true
+  }
+  if (items.length === previous.length - 1) {
+    let removed = 0
+    while (removed < items.length && items[removed] === previous[removed]) removed++
+    if (items.every((item, index) => item === previous[index >= removed ? index + 1 : index])) {
+      removeListRoot(list, keyToken(previous[removed]?.[list.descriptor.key]))
+      list.roots = new Map(items.map(item => {
+        const token = keyToken(item[list.descriptor.key])
+        return [token, list.roots.get(token)]
+      }))
+      list.items = items
+      return true
+    }
+  }
+  if (items.length === previous.length + 1 && previous.every((item, index) => item === items[index])) {
+    const entry = nestedListEntry(list, items.at(-1))
+    if (list.roots.has(entry.token)) throw new Error(`Duplicate keyed list key: ${String(entry.key)}`)
+    addListRoot(list, entry)
+    list.items = items
+    return true
+  }
+  if (items.length !== previous.length) return false
+  let changed = -1
+  for (let index = 0; index < items.length; index++) {
+    if (items[index] === previous[index]) continue
+    if (changed !== -1) return false
+    changed = index
+  }
+  if (changed === -1) return false
+  const item = items[changed]
+  if (item?.[list.descriptor.key] !== previous[changed]?.[list.descriptor.key]) return false
+  const entry = nestedListEntry(list, item)
+  const node = list.roots.get(entry.token)
+  if (!node) return false
+  if (list.values.get(entry.token) !== entry.value) {
+    fillListItem(node, item, list.descriptor.nested)
+    if (__KUDZU_LIST_ITEM_HOOKS__) notifyListItem(list.descriptor.state, node)
+    list.values.set(entry.token, entry.value)
+  }
+  list.items = items
+  return true
+}
+
+function nestedListEntry(list, item) {
+  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)
+  if (list.descriptor.child) validateChildLists([item], list.descriptor.child)
+  assertListValue(item, new Set(), true)
+  return { item, key, token: keyToken(key), value: JSON.stringify(item) }
+}
+
 function updateReducerList(list, items) {
   const previous = list.items
   if (items.length === previous.length && items.every((item, index) => item === previous[index])) {
@@ -237,9 +322,8 @@ function addListRoot(list, { item, key, token, value }) {
   if (!node) throw new Error("Keyed list template has no root element")
   node.removeAttribute("data-k-list-root")
   if (__KUDZU_LIST_ROW_STATES__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)
-  mapListItemParts(list.parts, node)
-  fillListItem(node, item)
-  listItems.set(node, item)
+  mapListItemParts(list.parts, node, list.descriptor.nested)
+  fillListItem(node, item, list.descriptor.nested)
   const parent = list.container ?? list.start.parentNode
   parent.insertBefore(node, list.boundary)
   if (__KUDZU_LIST_MOUNTS__ && list.descriptor.mount) mountDom(node)
@@ -257,11 +341,16 @@ function removeListRoot(list, token) {
   list.values.delete(token)
 }
 
-function fillListItem(root, item) {
+function fillListItem(root, item, nested = false) {
+  listItems.set(root, item)
   const revision = __KUDZU_LIST_ASYNC_PARTS__ ? (revisions.get(root) ?? 0) + 1 : 0
   if (__KUDZU_LIST_ASYNC_PARTS__) revisions.set(root, revision)
-  const parts = listItemParts(root)
+  const parts = listItemParts(root, nested)
   fillListParts(root, parts, item, revision)
+  if (__KUDZU_NESTED_LISTS__) {
+    const child = ownedLists.get(root)
+    if (child) updateList(child)
+  }
 }
 
 function fillListParts(root, parts, item, revision) {
@@ -317,11 +406,11 @@ function fillListParts(root, parts, item, revision) {
   }
 }
 
-function listItemParts(root) {
+function listItemParts(root, nested = false) {
   let parts = itemParts.get(root)
   if (parts) return parts
   parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [], conditions: [], effects: [] }
-  for (const node of matching(root, itemPartsSelector)) {
+  for (const node of nested ? ownedElements(root).filter(node => node.matches(itemPartsSelector)) : matching(root, itemPartsSelector)) {
     if (node.hasAttribute("data-k-list-text")) (node.tagName === "TEMPLATE" ? parts.texts : parts.directTexts).push([node, node.dataset.kListText])
     if (__KUDZU_LIST_ATTRIBUTES__ && node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
     if (__KUDZU_LIST_EVENTS__ && node.hasAttribute("data-k-list-events")) parts.events.push([node, node.dataset.kListEvents])
@@ -337,8 +426,8 @@ function listItemParts(root) {
   return parts
 }
 
-function listItemPartPlan(template) {
-  const source = [template, ...template.querySelectorAll("*")]
+function listItemPartPlan(template, nested = false) {
+  const source = nested ? ownedElements(template) : [template, ...template.querySelectorAll("*")]
   const indexes = new Map(source.map((node, index) => [node, index]))
   const parts = listItemParts(template)
   return {
@@ -353,8 +442,8 @@ function listItemPartPlan(template) {
   }
 }
 
-function mapListItemParts(parts, root) {
-  const target = [root, ...root.querySelectorAll("*")]
+function mapListItemParts(parts, root, nested = false) {
+  const target = nested ? ownedElements(root) : [root, ...root.querySelectorAll("*")]
   itemParts.set(root, {
     directTexts: parts.directTexts.map(([index, field]) => [target[index], field]),
     texts: __KUDZU_LIST_TEXT_RANGES__ ? parts.texts.map(([index, field]) => [target[index], field]) : [],
@@ -406,6 +495,49 @@ function renderFalsy(value) {
   return value === false || value == null || value === true ? "" : String(value)
 }
 
+function validateChildLists(items, child) {
+  for (const item of items) {
+    const children = item?.[child.field]
+    if (!Array.isArray(children)) throw new Error(`Nested keyed list property "${child.field}" must remain an array`)
+    const keys = new Set()
+    for (const entry of children) {
+      const key = entry?.[child.key]
+      if (!validListKey(key)) throw new Error(`Keyed list key "${child.key}" must be a string or finite number`)
+      assertListItem(entry)
+      assertListValue(entry, new Set(), true)
+      const token = keyToken(key)
+      if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
+      keys.add(token)
+    }
+  }
+}
+
+function listOwner(start) {
+  let owner = start.parentElement
+  while (owner && !listItems.has(owner)) owner = owner.parentElement
+  return owner
+}
+
+function ownedElements(root) {
+  const elements = []
+  const visit = node => {
+    elements.push(node)
+    for (let child = node.firstElementChild; child;) {
+      if (child.matches("template[data-k-list]")) {
+        const end = findEnd(child, JSON.parse(child.dataset.kList).id)
+        elements.push(child, end)
+        child = end.nextElementSibling
+      } else {
+        const next = child.nextElementSibling
+        visit(child)
+        child = next
+      }
+    }
+  }
+  visit(root)
+  return elements
+}
+
 function listRoots(start, end) {
   const roots = []
   for (let node = start.nextSibling; node && node !== end; node = node.nextSibling) {
@@ -585,8 +717,10 @@ function assertListValue(value, seen, root = false) {
 }
 
 function findEnd(start, id) {
-  return [...start.ownerDocument.querySelectorAll("template[data-k-list-end]")]
-    .find(node => node.dataset.kListEnd === id)
+  for (let node = start.nextElementSibling; node; node = node.nextElementSibling) {
+    if (node.matches("template[data-k-list-end]") && node.dataset.kListEnd === id) return node
+  }
+  throw new Error("Keyed list marker has no end")
 }
 
 function register(targets, id, entry) {

package/package.json

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