@kudzujs/core 0.4.5 → 0.4.6

package/README.md

@@ -279,15 +279,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** | 867 ms | **3.5 ms** | **25.4 ms** | 10.7 ms | **18.0 ms** | **57.6 ms** |
-| Kudzu | Yes | 5.7 KB | 180.8 KB | **417 ms** | 8.3 ms | 28.5 ms | **10.2 ms** | 20.5 ms | **67.5 ms** |
-| Vue CSR | No | 24.3 KB | 61.3 KB | 771 ms | 9.7 ms | 31.3 ms | 9.4 ms | 18.1 ms | 68.5 ms |
-| React CSR | No | 59.3 KB | 189.4 KB | 1024 ms | 8.7 ms | 32.3 ms | 12.4 ms | 18.1 ms | 71.5 ms |
-| Next.js | Yes | 182.2 KB | 695.2 KB | 3049 ms | 6.7 ms | 35.0 ms | 16.3 ms | 19.4 ms | 77.4 ms |
-| Qwik CSR | No | 22.2 KB | 64.1 KB | 602 ms | 14.5 ms | 19.9 ms | 31.3 ms | 18.9 ms | 84.6 ms |
-| Svelte CSR | No | 12.9 KB | 33.1 KB | 859 ms | 5.2 ms | 65.4 ms | 10.7 ms | 19.9 ms | 101.2 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 67.5 ms, ahead of the React fixture's 71.5 ms and within 9.9 ms of Astro across all four operations.
+| Astro | Yes | **324 B** | **43.6 KB** | 852 ms | **3.5 ms** | 25.8 ms | 15.8 ms | **17.9 ms** | **63.0 ms** |
+| Kudzu | Yes | 6.3 KB | 69.3 KB | **406 ms** | 6.0 ms | 28.5 ms | 14.7 ms | 19.1 ms | **68.3 ms** |
+| Next.js | Yes | 182.2 KB | 695.2 KB | 2950 ms | 6.8 ms | 34.1 ms | **9.0 ms** | 19.3 ms | 69.2 ms |
+| React CSR | No | 59.3 KB | 189.4 KB | 1028 ms | 9.5 ms | 35.3 ms | 10.1 ms | **17.8 ms** | 72.7 ms |
+| Vue CSR | No | 24.3 KB | 61.3 KB | 759 ms | 10.2 ms | 33.9 ms | 9.3 ms | 19.7 ms | 73.1 ms |
+| Qwik CSR | No | 22.2 KB | 64.1 KB | 604 ms | 15.6 ms | **20.0 ms** | 30.4 ms | 18.1 ms | 84.1 ms |
+| Svelte CSR | No | 12.9 KB | 33.1 KB | 845 ms | 5.4 ms | 64.4 ms | 11.2 ms | 19.1 ms | 100.1 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 68.3 ms, ahead of the React fixture's 72.7 ms and within 5.3 ms of Astro across all four operations.
 
 Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.
 

package/framework/build.mjs

@@ -116,7 +116,7 @@ function specializeRuntime(source, events, hasStateSeed) {
   if (hasStateSeed) return specialized
   return specialized
     .replace("  const initialState = document.body.dataset.kState\n", "")
-    .replace("  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)\n", "")
+    .replace("  if (initialState) for (const [id, value, compact] of JSON.parse(initialState)) browserState.set(id, compact ? value[1].map(row => Object.fromEntries(value[0].map((field, index) => [field, row[index]]))) : value)\n", "")
 }
 
 export function parseDevPort(value) {

package/framework/core.mjs

@@ -187,7 +187,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}) {
-  renderContext = { nextState: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false }
+  renderContext = { nextState: 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 }
 
   try {
     const body = await renderNode({ type: component, props: {} })
@@ -208,8 +208,13 @@ export async function renderPage(component, metadata = {}) {
     const listRuntime = renderContext.hasLists
       ? '<script type="module" src="/assets/kudzu-list.js"></script>'
       : ""
+    const listStates = new Set(renderContext.lists.map(list => list.state))
+    const seededListStates = new Set(renderContext.lists.filter(list => list.seed && !renderContext.textStates.has(list.state) && !renderContext.conditionStates.has(list.state)).map(list => list.state))
     const initialState = renderContext.hasBehaviors
-      ? Object.entries(renderContext.states).filter(([id]) => !renderContext.textStates.has(id) || renderContext.conditionStates.has(id)).map(([id, entry]) => [id, entry.initialValue])
+      ? Object.entries(renderContext.states).filter(([id]) => (!renderContext.textStates.has(id) || renderContext.conditionStates.has(id)) && !seededListStates.has(id)).map(([id, entry]) => {
+        const compact = listStates.has(id) && compactListState(entry.initialValue)
+        return compact ? [id, compact, 1] : [id, entry.initialValue]
+      })
       : []
     const state = initialState.length
       ? ` data-k-state='${escapeJsonAttribute(initialState)}'`
@@ -305,11 +310,14 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
   if (node?.[listMarker]) return renderList(node, namespace, selectValue)
   if (node?.[listFieldMarker]) {
-    return `<template data-k-list-text="${escapeAttribute(node.field)}"></template>${escapeHtml(node.value ?? "")}<template data-k-list-text-end></template>`
+    if (renderContext.listTemplate) renderContext.listFields?.add(node.field)
+    const marker = renderContext.listTemplate ? ` 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 }
-    return `<template data-k-list-expression='${escapeJsonAttribute(descriptor)}'></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
+    const marker = renderContext.listTemplate ? ` data-k-list-expression='${escapeJsonAttribute(descriptor)}'` : ""
+    return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
   }
   if (!node || typeof node !== "object" || !("type" in node)) {
     throw new Error(`Cannot render ${String(node)}`)
@@ -336,9 +344,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (renderContext.listRoot) {
     const root = renderContext.listRoot
     renderContext.listRoot = undefined
-    attributes += root.template
-      ? ` data-k-list-root="${root.id}"`
-      : ` data-k-list-item='${escapeJsonAttribute([root.id, root.key])}'`
+    if (root.template) attributes += ` data-k-list-root="${root.id}"`
   }
 
   for (const [rawName, value] of Object.entries(props)) {
@@ -412,10 +418,13 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
 
   if (attributeBindings.length) attributes += ` data-k-bind-attrs='${escapeJsonAttribute(attributeBindings)}'`
-  if (listAttributes.length) attributes += ` data-k-list-attrs='${escapeJsonAttribute(listAttributes)}'`
-  if (listExpressionAttributes.length) attributes += ` data-k-list-expression-attrs='${escapeJsonAttribute(listExpressionAttributes)}'`
-  if (listEvents.length) attributes += ` data-k-list-events='${escapeJsonAttribute(listEvents)}'`
-  if (directListText) attributes += ` data-k-list-text="${escapeAttribute(directListText.field)}"`
+  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) {
+    renderContext.listFields?.add(directListText.field)
+    attributes += ` data-k-list-text="${escapeAttribute(directListText.field)}"`
+  }
 
   if (tag === "option" && selectValue !== noSelectValue && String(optionValue(props)) === (selectValue == null ? "" : String(selectValue))) attributes += " selected"
 
@@ -428,12 +437,17 @@ 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 = `l${renderContext.nextList++}`
-  const descriptor = { id, state: node.items.id, key: node.keyField }
+  const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.items.value.map(item => item[node.keyField]) }
   renderContext.listDepth++
+  const previousListFields = renderContext.listFields
   try {
     renderContext.listTemplate = true
+    renderContext.listFields = new Set([node.keyField])
     renderContext.listRoot = { id, template: true }
     const template = await renderNode(node.render({}), namespace, selectValue)
+    if (template.includes("data-k-native-")) descriptor.mount = true
+    const seed = listSeed(node.items.value, renderContext.listFields)
+    if (seed) descriptor.seed = seed
     let current = ""
     renderContext.listTemplate = false
     for (const item of node.items.value) {
@@ -447,6 +461,7 @@ async function renderList(node, namespace, selectValue) {
   } finally {
     renderContext.listRoot = undefined
     renderContext.listTemplate = false
+    renderContext.listFields = previousListFields
     renderContext.listDepth--
   }
 }
@@ -493,6 +508,24 @@ function escapeJsonAttribute(value) {
   return JSON.stringify(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll("'", "&#39;")
 }
 
+function compactListState(value) {
+  if (!Array.isArray(value) || !value.length) return undefined
+  const fields = Object.keys(value[0])
+  if (!fields.length || !value.every(item => Object.keys(item).length === fields.length && fields.every(field => Object.hasOwn(item, field)))) return undefined
+  return [fields, value.map(item => fields.map(field => item[field]))]
+}
+
+function listSeed(items, fields) {
+  if (!items.length || !items.every(item => Object.keys(item).length === fields.size && Object.keys(item).every(field => fields.has(field)))) return undefined
+  const seed = {}
+  for (const field of fields) {
+    const types = new Set(items.map(item => item[field] === null ? "null" : typeof item[field]))
+    if (types.size !== 1 || !["string", "number", "boolean", "null"].includes([...types][0])) return undefined
+    seed[field] = [...types][0]
+  }
+  return seed
+}
+
 function toKebabCase(value) {
   return value.replace(/[A-Z]/g, character => `-${character.toLowerCase()}`)
 }

package/framework/list-runtime.js

@@ -28,16 +28,22 @@ function mountLists(root) {
     if (mountedLists.has(start)) continue
     mountedLists.add(start)
     const descriptor = JSON.parse(start.dataset.kList)
-    const roots = [...start.ownerDocument.querySelectorAll("[data-k-list-item]")].filter(node => JSON.parse(node.dataset.kListItem)[0] === descriptor.id)
+    const end = findEnd(start, descriptor.id)
+    const roots = listRoots(start, end)
+    const templateRoot = start.content.firstElementChild
+    const parts = listItemPartPlan(templateRoot)
+    for (const root of roots) 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)
-    for (const root of roots) listItemParts(root)
     const list = {
       start,
       descriptor,
-      roots: new Map(roots.map(node => [keyToken(JSON.parse(node.dataset.kListItem)[1]), node])),
-      values: new Map(items.map(item => [keyToken(item[descriptor.key]), JSON.stringify(item)])),
+      parts,
+      seedFields: descriptor.seed && Object.keys(descriptor.seed),
+      roots: new Map(roots.map((node, index) => [keyToken(descriptor.keys[index]), node])),
+      values: new Map(),
       container: roots[0]?.parentNode,
-      boundary: roots.length ? roots.at(-1).nextSibling : findEnd(start, descriptor.id)
+      boundary: end
     }
     register(listTargets, descriptor.state, list)
     listRegistrations.set(start, { state: descriptor.state, list })
@@ -70,11 +76,12 @@ function updateList(list) {
     const key = item?.[list.descriptor.key]
     if (!validListKey(key)) throw new Error(`Keyed list key "${list.descriptor.key}" must be a string or finite number`)
     assertListItem(item)
-    assertListValue(item, seen, true)
+    const seededValue = list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed)
+    if (seededValue === undefined) assertListValue(item, seen, true)
     const token = keyToken(key)
     if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
     keys.add(token)
-    entries.push({ item, key, token, value: JSON.stringify(item) })
+    entries.push({ item, key, token, value: seededValue ?? JSON.stringify(item) })
   }
   const next = []
   const values = new Map()
@@ -88,7 +95,7 @@ function updateList(list) {
       if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
       if (!node) throw new Error("Keyed list template has no root element")
       node.removeAttribute("data-k-list-root")
-      node.dataset.kListItem = JSON.stringify([list.descriptor.id, key])
+      mapListItemParts(list.parts, node)
       fillListItem(node, item)
       additions.append(node)
       added = true
@@ -98,13 +105,18 @@ 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
-    unmountDom(node)
-    node.remove()
+    if (list.descriptor.mount) {
+      unmountDom(node)
+      node.remove()
+    } else {
+      removals.append(node)
+    }
   }
   if (added) {
-    mountDom(additions)
+    if (list.descriptor.mount) mountDom(additions)
     parent.insertBefore(additions, list.boundary)
     list.container ??= parent
   }
@@ -135,8 +147,8 @@ function fillListItem(root, item) {
   const revision = (revisions.get(root) ?? 0) + 1
   revisions.set(root, revision)
   const parts = listItemParts(root)
-  for (const node of parts.directTexts) {
-    const text = item?.[node.dataset.kListText]
+  for (const [node, field] of parts.directTexts) {
+    const text = item?.[field]
     const value = text == null ? "" : String(text)
     const current = node.firstChild
     if (current?.nodeType === Node.TEXT_NODE && !current.nextSibling) {
@@ -145,14 +157,14 @@ function fillListItem(root, item) {
       node.textContent = value
     }
   }
-  for (const marker of parts.texts) {
-    patchListText(marker, "template[data-k-list-text-end]", item?.[marker.dataset.kListText])
+  for (const [marker, field] of parts.texts) {
+    patchListText(marker, "template[data-k-list-text-end]", item?.[field])
   }
   for (const [node, attributes] of parts.attributes) {
     for (const [target, field] of attributes) patchBinding(node, target, item?.[field])
   }
-  for (const node of parts.events) {
-    for (const [event, native] of JSON.parse(node.dataset.kListEvents)) {
+  for (const [node, events] of parts.events) {
+    for (const [event, native] of JSON.parse(events)) {
       native.scope = Object.fromEntries(Object.entries(native.scope).map(([name, value]) => [name, value?.type === "list-item" ? serializeItem(item) : value]))
       node.dataset[`kNative${capitalize(event)}`] = JSON.stringify(native)
     }
@@ -176,9 +188,9 @@ function listItemParts(root) {
   if (parts) return parts
   parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [] }
   for (const node of matching(root, itemPartsSelector)) {
-    if (node.hasAttribute("data-k-list-text")) (node.tagName === "TEMPLATE" ? parts.texts : parts.directTexts).push(node)
+    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)
+    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)])
   }
@@ -186,6 +198,61 @@ function listItemParts(root) {
   return parts
 }
 
+function listItemPartPlan(template) {
+  const source = [template, ...template.querySelectorAll("*")]
+  const indexes = new Map(source.map((node, index) => [node, index]))
+  const parts = listItemParts(template)
+  return {
+    directTexts: parts.directTexts.map(([node, field]) => [indexes.get(node), field]),
+    texts: parts.texts.map(([node, field]) => [indexes.get(node), field]),
+    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])
+  }
+}
+
+function mapListItemParts(parts, root) {
+  const target = [root, ...root.querySelectorAll("*")]
+  itemParts.set(root, {
+    directTexts: parts.directTexts.map(([index, field]) => [target[index], field]),
+    texts: parts.texts.map(([index, field]) => [target[index], field]),
+    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])
+  })
+}
+
+function listRoots(start, end) {
+  const roots = []
+  for (let node = start.nextSibling; node && node !== end; node = node.nextSibling) {
+    if (node.nodeType === Node.ELEMENT_NODE) roots.push(node)
+  }
+  return roots
+}
+
+function seedListItem(root, descriptor, index) {
+  const item = { [descriptor.key]: descriptor.keys[index] }
+  const parts = itemParts.get(root)
+  for (const [node, field] of parts.directTexts) item[field] = seedValue(node.textContent, descriptor.seed[field])
+  for (const [marker, field] of parts.texts) item[field] = seedValue(rangeText(marker, "template[data-k-list-text-end]"), descriptor.seed[field])
+  return item
+}
+
+function seedValue(value, type) {
+  if (type === "number") return Number(value)
+  if (type === "boolean") return value === "true"
+  if (type === "null") return null
+  return value
+}
+
+function rangeText(marker, endSelector) {
+  let value = ""
+  for (let node = marker.nextSibling; node && !(node.nodeType === Node.ELEMENT_NODE && node.matches(endSelector)); node = node.nextSibling) value += node.textContent
+  return value
+}
+
 function patchListText(marker, endSelector, value) {
   let end = marker.nextSibling
   while (end && !(end.nodeType === Node.ELEMENT_NODE && end.matches(endSelector))) end = end.nextSibling
@@ -254,6 +321,22 @@ function assertListItem(item) {
   if (!item || Array.isArray(item) || prototype !== Object.prototype) throw new Error("Keyed list items must be ordinary plain objects")
 }
 
+function seededListValue(item, fields, seed) {
+  const keys = Reflect.ownKeys(item)
+  if (keys.length !== fields.length || keys.some(key => typeof key !== "string" || !fields.includes(key))) return undefined
+  const values = []
+  for (const field of fields) {
+    const descriptor = Object.getOwnPropertyDescriptor(item, field)
+    if (!descriptor.enumerable) throw new Error("Keyed list items must not contain non-enumerable properties")
+    if (!("value" in descriptor)) throw new Error("Keyed list items must not contain accessors")
+    const value = descriptor.value
+    const type = value === null ? "null" : typeof value
+    if (type !== seed[field] || type === "number" && (!Number.isFinite(value) || Object.is(value, -0))) return undefined
+    values.push(value)
+  }
+  return JSON.stringify(values)
+}
+
 function assertListValue(value, seen, root = false) {
   if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0)) return
   if (!value || typeof value !== "object") throw new Error("Keyed list items must contain only JSON-safe values")

package/framework/shared-runtime.js

@@ -55,7 +55,7 @@ export function unmountDom(root) {
 
 if (typeof document !== "undefined") {
   const initialState = document.body.dataset.kState
-  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)
+  if (initialState) for (const [id, value, compact] of JSON.parse(initialState)) browserState.set(id, compact ? value[1].map(row => Object.fromEntries(value[0].map((field, index) => [field, row[index]]))) : value)
   mountText(document)
 
   const eventNames = ["click", "input", "change"]

package/package.json

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