@kudzujs/core 0.5.0 → 0.5.2

package/README.md

@@ -264,9 +264,32 @@ const rows = items.map(item =>
 return <ul>{rows}</ul>
 ```
 
-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.
+The root may also be a top-level same-file row component. Kudzu specializes each call at build time, so projected props, callback props, and simple local calculations compile to the same intrinsic list template:
 
-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>`.
+```tsx
+function ItemRow({ name, done, onRemove }: {
+  name: string
+  done: boolean
+  onRemove: () => void
+}) {
+  const className = done ? "done" : "active"
+  return <li className={className}>
+    {name}
+    <button onClick={() => onRemove()}>Remove</button>
+  </li>
+}
+
+const rows = items.map(item => <ItemRow
+  key={item.id}
+  name={item.name}
+  done={item.done}
+  onRemove={() => setItems(items.filter(entry => entry.id !== item.id))}
+/>)
+```
+
+The original component remains reusable across multiple lists and ordinary JSX. 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 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 or top-level same-file row component, and `key={item.<field>}`. Row components accept destructured projected props and top-level single-`const` calculations before one intrinsic return. 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, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Exported or imported row components, 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>`.
 
 ## Normal JavaScript
 
@@ -438,6 +461,8 @@ The list starts with 1,000 keyed items, then updates every label, reverses the o
 | Svelte CSR | No | 12.9 KB | 33.1 KB | 828 ms | 5.8 ms | 38.9 ms | 4.0 ms | 5.9 ms | 54.6 ms |
 | Qwik CSR | No | 22.2 KB | 64.1 KB | 594 ms | 9.1 ms | 22.2 ms | 30.8 ms | 19.0 ms | 81.1 ms |
 
+An intrinsic-root versus projected-prop row-component A/B build produced byte-for-byte identical `dist` output: 5,175 B JS gzip and 61,731 B total. Seven interleaved clean builds measured 467 ms and 455 ms. Browser operation medians totaled 23.7 ms and 23.9 ms respectively; because the deployed HTML and JavaScript are identical, the 0.2 ms difference is measurement variance rather than component runtime overhead.
+
 Astro is the hand-authored native DOM baseline in the interactive fixtures. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. Kudzu's keyed-list operations total 23.2 ms, 10.7 ms behind the hand-authored Astro baseline and 7.1 ms ahead of React across all four operations.
 
 Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.

package/framework/build.mjs

@@ -395,6 +395,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
     const settersByFunction = new Map()
     const functions = new Map()
+    const components = new Map()
     const jsxLocalDeclarations = new Map()
     const jsxLocalsByFunction = new Map()
     const listLocalDeclarations = new WeakSet()
@@ -420,9 +421,13 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
           }
         }
       }
-      if (ts.isFunctionDeclaration(node) && node.name) functions.set(node.name.text, node)
+      if (ts.isFunctionDeclaration(node) && node.name) {
+        functions.set(node.name.text, node)
+        if (node.parent === sourceFile) components.set(node.name.text, { function: node, declaration: node })
+      }
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
         functions.set(node.name.text, node.initializer)
+        if (node.parent?.parent?.parent === sourceFile) components.set(node.name.text, { function: node.initializer, declaration: node })
       }
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && isTopLevelConst(node)) {
         const owner = nearestFunction(node)
@@ -466,8 +471,66 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         if (uses.length) listLocalUses.set(uses[0], parts)
       }
     }
+    const rawRenderedLists = []
+    const collectRenderedLists = node => {
+      if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
+        const parts = listLocalUses.get(node) ?? keyedListParts(node.expression, settersForNode(node, settersByFunction))
+        if (parts) rawRenderedLists.push({ node, parts })
+      }
+      ts.forEachChild(node, collectRenderedLists)
+    }
+    collectRenderedLists(sourceFile)
+    const fail = (node, message) => {
+      const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
+      throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
+    }
+    const listComponentNames = new Set(rawRenderedLists.flatMap(({ parts }) => {
+      const tag = jsxTagName(parts.root)
+      return tag && ts.isIdentifier(tag) && tag.text[0] === tag.text[0].toUpperCase() ? [tag.text] : []
+    }))
+    const componentSpecializations = new WeakMap()
+    const specializedDeclarations = new WeakSet()
+    for (const name of listComponentNames) {
+      const component = components.get(name)
+      if (!component) fail(sourceFile, `Keyed list component ${name} must be declared at the top level in the same file`)
+      if (isExportedDeclaration(component.declaration)) fail(component.declaration, `Keyed list component ${name} cannot be exported`)
+      const calls = jsxTagUses(sourceFile, name)
+      if (identifierReferenceCount(sourceFile, name) !== calls.length) fail(component.declaration, `Keyed list component ${name} may only be referenced as JSX`)
+      for (const call of calls) componentSpecializations.set(call, specializeComponentCall(call, component.function, sourceFile, factory, context, fail))
+      specializedDeclarations.add(component.declaration)
+    }
+    const renderedLists = new WeakMap()
+    for (const { node, parts: originalParts } of rawRenderedLists) {
+      if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
+      const specialization = componentSpecializations.get(originalParts.root)
+      const root = specialization?.root ?? originalParts.root
+      const callback = root === originalParts.root ? originalParts.callback : factory.updateArrowFunction(
+        originalParts.callback,
+        originalParts.callback.modifiers,
+        originalParts.callback.typeParameters,
+        originalParts.callback.parameters,
+        originalParts.callback.type,
+        originalParts.callback.equalsGreaterThanToken,
+        root
+      )
+      if (callback !== originalParts.callback) {
+        ts.setParentRecursive(callback, false)
+        callback.parent = originalParts.callback.parent
+      }
+      const parts = { ...originalParts, root, callback }
+      for (const calculation of specialization?.calculations ?? []) {
+        ts.setParentRecursive(calculation, false)
+        calculation.parent = callback
+        validateListExpression(calculation, parts.item, originalParts.root, fail)
+      }
+      validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions)
+      renderedLists.set(node, parts)
+    }
 
     const visitor = node => {
+      if (specializedDeclarations.has(node)) return node
+      if (componentSpecializations.has(node)) return ts.visitNode(componentSpecializations.get(node).root, visitor)
+
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
         return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(modulePath(node.moduleSpecifier.text)), node.attributes)
       }
@@ -523,10 +586,8 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       }
 
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
-        const listParts = listLocalUses.get(node) ?? keyedListParts(node.expression, settersForNode(node, settersByFunction))
+        const listParts = renderedLists.get(node)
         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, listConditions)
           usesBehavior = true
           usesList = true
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
@@ -628,11 +689,13 @@ function keyedListParts(expression, setters) {
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
 }
 
-function validateKeyedList(parts, sourceFile, setters, listValues, listEventItems, listConditions) {
+function validateKeyedList(parts, sourceFile, 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}`)
   }
+  const root = parts.root
+  const item = parts.item
   const validateElement = node => {
     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")
@@ -641,10 +704,10 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
   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 !== parts.root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, "Nested keyed lists are not supported")
-    if (ts.isJsxSpreadAttribute(node) && referencesIdentifier(node.expression, parts.item)) fail(node, "Keyed list item spreads are not supported")
+    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 (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.getText())) {
-      listEventItems.set(node, parts.item)
+      listEventItems.set(node, item)
       return
     }
     if (ts.isJsxExpression(node) && node.expression) {
@@ -652,16 +715,16 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
       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 })
+        if (!referencesIdentifier(condition.condition, item)) fail(node, "Keyed list item conditions must read the item")
+        validateListExpression(condition.condition, item, node, fail)
+        listConditions.set(node.expression, { ...condition, item })
         conditionDepth++
         visit(condition.truthy)
         visit(condition.falsy)
         conditionDepth--
         return
       }
-      const field = directProperty(expression, parts.item)
+      const field = directProperty(expression, 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`)
       if (field && ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
@@ -670,16 +733,143 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
         listValues.set(node.expression, { field })
         return
       }
-      if (referencesIdentifier(expression, parts.item)) {
-        validateListExpression(expression, parts.item, node, fail)
+      if (referencesIdentifier(expression, item)) {
+        validateListExpression(expression, item, node, fail)
         if (ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
-        listValues.set(node.expression, { item: parts.item })
+        listValues.set(node.expression, { item })
         return
       }
     }
     ts.forEachChild(node, visit)
   }
-  visit(parts.root)
+  visit(root)
+}
+
+function specializeComponentCall(call, component, sourceFile, factory, context, fail) {
+  if (component.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || component.asteriskToken) fail(component, "Keyed list components must be synchronous")
+  if (component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name)) fail(component, "Keyed list components must use one destructured props parameter")
+  if (ts.isJsxElement(call) && call.children.some(child => !ts.isJsxText(child) || child.text.trim())) fail(call, "Keyed list component children are not supported")
+  const callAttributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
+  const props = new Map()
+  let key
+  for (const attribute of callAttributes.properties) {
+    if (ts.isJsxSpreadAttribute(attribute)) fail(attribute, "Keyed list component prop spreads are not supported")
+    const name = attribute.name.getText()
+    if (props.has(name) || name === "key" && key) fail(attribute, `Duplicate keyed list component prop "${name}"`)
+    const value = !attribute.initializer
+      ? factory.createTrue()
+      : ts.isStringLiteral(attribute.initializer)
+        ? factory.createStringLiteral(attribute.initializer.text)
+        : ts.isJsxExpression(attribute.initializer) && attribute.initializer.expression
+          ? attribute.initializer.expression
+          : factory.createIdentifier("undefined")
+    if (name === "key") key = attribute
+    else props.set(name, value)
+  }
+  const substitutions = new Map()
+  const acceptedProps = new Set()
+  for (const element of component.parameters[0].name.elements) {
+    if (element.dotDotDotToken || element.initializer || !ts.isIdentifier(element.name)) fail(element, "Keyed list component props cannot use rest, defaults, or nested destructuring")
+    const prop = (element.propertyName ?? element.name).getText()
+    acceptedProps.add(prop)
+    substitutions.set(element.name.text, props.get(prop) ?? factory.createIdentifier("undefined"))
+  }
+  for (const prop of props.keys()) if (!acceptedProps.has(prop)) fail(call, `Unknown keyed list component prop "${prop}"`)
+
+  let returned
+  const calculations = []
+  if (!ts.isBlock(component.body)) {
+    returned = component.body
+  } else {
+    const statements = [...component.body.statements]
+    const last = statements.pop()
+    if (!last || !ts.isReturnStatement(last) || !last.expression) fail(component.body, "Keyed list component must end with one JSX return")
+    for (const statement of statements) {
+      if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0 || statement.declarationList.declarations.length !== 1) fail(statement, "Keyed list component locals must be single const declarations")
+      const declaration = statement.declarationList.declarations[0]
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) fail(declaration, "Keyed list component locals must be initialized identifiers")
+      const calculation = substituteClone(declaration.initializer, substitutions, factory, context)
+      calculations.push(calculation)
+      substitutions.set(declaration.name.text, calculation)
+    }
+    returned = last.expression
+  }
+  let root = unwrapExpression(substituteClone(returned, substitutions, factory, context))
+  if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) fail(returned, "Keyed list component must return one JSX element")
+  const tag = jsxTagName(root)
+  if (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(returned, "Keyed list component must directly return an intrinsic JSX element")
+  const rootAttributes = ts.isJsxElement(root) ? root.openingElement.attributes : root.attributes
+  if (rootAttributes.properties.some(attribute => ts.isJsxAttribute(attribute) && attribute.name.text === "key")) fail(root, "Keyed list component intrinsic root cannot declare key")
+  if (key) root = addJsxAttribute(root, cloneAst(key, factory, context), factory)
+  ts.setParentRecursive(root, false)
+  root.parent = call.parent
+  return { root, calculations }
+}
+
+function substituteClone(root, substitutions, factory, context) {
+  const visit = (node, shadowed = new Set()) => {
+    if (ts.isShorthandPropertyAssignment(node) && substitutions.has(node.name.text) && !shadowed.has(node.name.text)) {
+      return factory.createPropertyAssignment(cloneAst(node.name, factory, context), cloneAst(substitutions.get(node.name.text), factory, context))
+    }
+    if (ts.isIdentifier(node) && substitutions.has(node.text) && !shadowed.has(node.text) && isReferenceIdentifier(node) && !isJsxSyntaxIdentifier(node)) {
+      return cloneAst(substitutions.get(node.text), factory, context)
+    }
+    const nextShadowed = isFunctionLike(node)
+      ? new Set([...shadowed, ...node.parameters.flatMap(parameter => bindingNames(parameter.name))])
+      : shadowed
+    const clone = factory.cloneNode(node)
+    ts.setTextRange(clone, node)
+    ts.setOriginalNode(clone, node)
+    return ts.visitEachChild(clone, child => visit(child, nextShadowed), context)
+  }
+  return visit(root)
+}
+
+function cloneAst(root, factory, context) {
+  const visit = node => {
+    const clone = factory.cloneNode(node)
+    ts.setTextRange(clone, node)
+    ts.setOriginalNode(clone, node)
+    return ts.visitEachChild(clone, visit, context)
+  }
+  return visit(root)
+}
+
+function addJsxAttribute(root, attribute, factory) {
+  if (ts.isJsxSelfClosingElement(root)) {
+    return factory.updateJsxSelfClosingElement(root, root.tagName, root.typeArguments, factory.updateJsxAttributes(root.attributes, [attribute, ...root.attributes.properties]))
+  }
+  const opening = factory.updateJsxOpeningElement(root.openingElement, root.openingElement.tagName, root.openingElement.typeArguments, factory.updateJsxAttributes(root.openingElement.attributes, [attribute, ...root.openingElement.attributes.properties]))
+  return factory.updateJsxElement(root, opening, root.children, root.closingElement)
+}
+
+function jsxTagName(node) {
+  return ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : undefined
+}
+
+function isJsxSyntaxIdentifier(node) {
+  const parent = node.parent
+  return (ts.isJsxOpeningElement(parent) || ts.isJsxClosingElement(parent) || ts.isJsxSelfClosingElement(parent)) && parent.tagName === node || ts.isJsxAttribute(parent) && parent.name === node
+}
+
+function isFunctionLike(node) {
+  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)
+}
+
+function isExportedDeclaration(node) {
+  const statement = ts.isVariableDeclaration(node) ? node.parent?.parent : node
+  return statement?.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword || modifier.kind === ts.SyntaxKind.DefaultKeyword) ?? false
+}
+
+function jsxTagUses(root, name) {
+  const uses = []
+  const visit = node => {
+    const tag = ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : undefined
+    if (tag && ts.isIdentifier(tag) && tag.text === name) uses.push(node)
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return uses
 }
 
 const pureListMethods = new Set(["at", "charAt", "charCodeAt", "concat", "endsWith", "includes", "indexOf", "join", "lastIndexOf", "padEnd", "padStart", "repeat", "replace", "replaceAll", "slice", "startsWith", "substring", "toLowerCase", "toUpperCase", "trim", "trimEnd", "trimStart"])

package/package.json

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