@kudzujs/core 0.7.9 → 0.7.10

package/README.md

@@ -10,7 +10,7 @@ Kudzu is designed so ordinary common React-shaped TSX can migrate with minimal s
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**0.7.9:** Keyed-row prop defaults. Same-file and relative keyed row components retain destructured primitive literal defaults, with missing props substituted at compile time and no new browser runtime. See [release notes](./RELEASES.md#079---keyed-row-prop-defaults).
+**0.7.10:** Component composition. Existing specialized collection wrappers and keyed rows now retain direct analyzable prop spreads and forwarded JSX children without adding a browser component runtime. See [release notes](./RELEASES.md#0710---component-composition).
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -465,7 +465,7 @@ Initial child rows remain complete HTML. Kudzu stores one child row prototype, i
 
 In the matched 100-parent/1,000-child fixture, Kudzu measured 1.3/0.4/5.0/0.7 ms for child update and condition change, child reverse, parent reverse, and parent removal. Hand-written Astro/native measured 0.5/0.4/3.9/0.2 ms, Svelte 2.7/1.2/6.7/1.3 ms, Vue 4.9/2.5/6.1/2.2 ms, and React 11.8/5.0/8.2/4.4 ms. Kudzu and Astro emit initial rows while the CSR targets do not, so artifact sizes are not architecture-equivalent.
 
-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. Collections must remain anchored to local array state or a supported static named import; inline callbacks accept one or two identifier parameters, and row roots must be intrinsic JSX or supported same-file/relative components with `key={item.<field>}` or `key={index}`. Specialized keyed row components accept missing destructured string, finite-number, boolean, or `null` props with literal defaults. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` effect dependencies are rejected. A collection alias may only be rendered once and cannot be read by other JavaScript. Collection callbacks and derived expressions must be pure and synchronous: supported reads, operators, templates, approved read-only methods, deterministic `Math`, and primitive conversion compile; imported callbacks, browser globals, promises, mutation, arbitrary calls, and prototype-sensitive properties fail. Lazy or dynamic keyed-row state initializers, non-`null` refs, callback refs, package/namespace/star row imports, same-file exported rows, reusable aliases, prop spreads/rest, non-primitive defaults, children, fragments, 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. Collections must remain anchored to local array state or a supported static named import; inline callbacks accept one or two identifier parameters, and row roots must be intrinsic JSX or supported same-file/relative components with `key={item.<field>}` or `key={index}`. Specialized wrappers and keyed rows accept forwarded JSX children and source-ordered prop spreads from inline object literals or one direct `const` object literal declared in the calling component. Specialized keyed row components accept missing destructured string, finite-number, boolean, or `null` props with literal defaults. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` effect dependencies are rejected. A collection alias may only be rendered once and cannot be read by other JavaScript. Collection callbacks and derived expressions must be pure and synchronous: supported reads, operators, templates, approved read-only methods, deterministic `Math`, and primitive conversion compile; imported callbacks, browser globals, promises, mutation, arbitrary calls, and prototype-sensitive properties fail. Lazy or dynamic keyed-row state initializers, non-`null` refs, callback refs, package/namespace/star row imports, same-file exported rows, reusable aliases, dynamic/computed prop spreads, rest props, non-primitive defaults, fragments, 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.
 
@@ -676,7 +676,7 @@ Supported:
 
 Selected current migration limits:
 
-- Common prop spreads/rest, wrapper `children` forwarding, `forwardRef`, and `useId` still need fixture-driven component specialization.
+- Non-primitive prop defaults/rest, exported reusable specialized rows, `forwardRef`, and `useId` still need fixture-driven component specialization. Direct analyzable prop spreads and forwarded JSX children are supported across existing specialized collection boundaries.
 - Hookful non-keyed imported components and pure lazy state/reducer initializers remain narrower than ordinary React.
 - Reusable collection aliases, computed child collections, imported pure transforms, and common immutable pagination/sorting forms need failing fixtures before expansion.
 - Effect dependencies remain limited to directly analyzable primitive signals and supported keyed-item properties.

package/RELEASES.md

@@ -1,5 +1,28 @@
 # Kudzu Releases
 
+## 0.7.10 - Component composition
+
+Kudzu 0.7.10 preserves common component composition across existing compiler-specialized collection boundaries.
+
+### New in 0.7.10
+
+- State-backed collection wrappers, keyed rows, and reducer specializations accept prop spreads from direct inline object literals or one direct `const` object literal declared in the calling component.
+- Spread and explicit props apply in source order, preserving ordinary override behavior.
+- Specialized components accept forwarded JSX children, including mixed text and element children, while still lowering to intrinsic DOM.
+- Non-self-closing specialized component tags are counted as one JSX use instead of treating the closing tag as another reference.
+- A conventional React-shaped landing fixture proves imported layout children, component spreads, keyed row children, interaction output, and a zero-JavaScript static route.
+- Dynamic, computed, circular, prototype-sensitive, and method/accessor spread shapes fail with source-located diagnostics.
+
+### Boundary
+
+Spread sources must be inline object literals or one direct `const` object literal declared in the calling component. State collections still cross the specialization boundary as direct props. Rest bindings, non-primitive defaults, exported reusable specialized rows, `forwardRef`, and `useId` remain fixture-driven work.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.10
+```
+
 ## 0.7.9 - Keyed-row prop defaults
 
 Kudzu 0.7.9 lets ordinary keyed row components retain destructured primitive literal prop defaults instead of restructuring every call site.

package/framework/README.md

@@ -33,7 +33,7 @@ Inline SVG rendering normalizes an explicit set of common React presentation ali
 
 Same-file and relative-imported component chains receiving a direct local-state array or keyed item are recursively specialized to intrinsic JSX before keyed-list analysis, so their component functions are not retained in the browser. Missing destructured string, finite-number, boolean, or `null` props use their literal defaults during specialization. Rows may own multiple direct-property child maps recursively, nested conditions, latest-item handlers, multiple directly serializable state slots, effects, and `null`-initialized object refs. Structural list sites and ancestor key paths scope hooks across updates and reorder and release them on removal. Handler modules are emitted only when a rendered descriptor references them. Direct JSON-safe primitive keyed-item dependencies subscribe each row record to its owning list commit and compare selected fields after `list-runtime.js` synchronously refreshes the row marker. Only changed rows rerun with the complete latest item; reorder compares equal and unrelated fields do nothing. Builds without item dependencies emit no item reader or list-state subscription code.
 
-Rendered collection selectors compile one-use aliases and inline `(item)` or `(item, index)` pipelines over local array state or supported static named imports. Supported selectors are pure `filter` with direct local-state reads, direct-property `flatMap`, and `Array.from` before a final keyed `map`; dependency commits re-evaluate the selector against the immutable build-time collection while field keys retain item identity and `key={index}` retains positional identity. Compiler-owned static filters over structural keyed rows validate source references and keys once, retain removed rows as detached prototypes, clone fresh restoration nodes, and insert only new runs without moving retained DOM. This route-specific path is compiled out elsewhere. Compiler-owned collection state is excluded from development snapshot restoration. Arbitrary callbacks, mutation, asynchronous selectors, imported callback functions, prototype-sensitive reads, lazy/dynamic row state initializers, non-`null` or callback refs, and recursive component cycles fail during compilation.
+Rendered collection selectors compile one-use aliases and inline `(item)` or `(item, index)` pipelines over local array state or supported static named imports. Supported selectors are pure `filter` with direct local-state reads, direct-property `flatMap`, and `Array.from` before a final keyed `map`; dependency commits re-evaluate the selector against the immutable build-time collection while field keys retain item identity and `key={index}` retains positional identity. Compiler-owned static filters over structural keyed rows validate source references and keys once, retain removed rows as detached prototypes, clone fresh restoration nodes, and insert only new runs without moving retained DOM. Specialized collection wrappers and keyed rows inline direct object-literal or calling-component `const` object prop spreads in source order and forward JSX children into intrinsic output. This route-specific path is compiled out elsewhere. Compiler-owned collection state is excluded from development snapshot restoration. Dynamic/computed prop spreads, arbitrary callbacks, mutation, asynchronous selectors, imported callback functions, prototype-sensitive reads, lazy/dynamic row state initializers, non-`null` or callback refs, and recursive component cycles fail during compilation.
 
 The reduced `useReducer` form reuses ordinary state slots and React's pure reducer contract. A direct dispatch in a compiled handler becomes a functional `set` whose reducer is bundled from a relative TypeScript module into that handler graph. Pure reducer-owned keyed lists reuse unchanged item identities for reorder, one removal, and append fast paths; ordinary `useState` lists retain full validation. One direct dispatch prop into a same-file or relative-imported synchronous component, including a direct keyed row, is specialized to intrinsic JSX at the call site, so its handler retains the parent reducer scope and no dispatch capture or child handler asset is emitted. A reducer row reads the latest item through the existing list scope and uses the same multiple serializable state, effect, condition, and object-ref specialization as other keyed rows. Relative TypeScript imports referenced inside that child handler receive collision-free call-site aliases and join the parent handler graph. One nested relative-imported intrinsic child may receive an inline or simple `const` callback containing dispatch; the compiler recursively substitutes that callback once and omits the nested child handler asset. Missing primitive literal defaults in these reducer specializations are substituted at the same call site. Reducer-free routes and shared runtimes are unchanged; no reducer runtime or browser component instance exists.
 

package/framework/build.mjs

@@ -3358,17 +3358,113 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
   visit(root)
 }
 
+function directConstObjectLiteral(expression, call, sourceFile) {
+  expression = unwrapExpression(expression)
+  if (ts.isObjectLiteralExpression(expression)) return expression
+  if (!ts.isIdentifier(expression)) return
+  const owner = nearestFunction(call)
+  const scope = owner?.body ?? sourceFile
+  if (!scope || !ts.isBlock(scope) && !ts.isSourceFile(scope)) return
+  const declarations = []
+  for (const statement of scope.statements) {
+    if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === expression.text && declaration.initializer && declaration.end < call.pos) declarations.push(declaration)
+    }
+  }
+  if (declarations.length !== 1) return
+  const initializer = unwrapExpression(declarations[0].initializer)
+  if (ts.isObjectLiteralExpression(initializer)) return initializer
+}
+
+function specializedSpreadEntries(expression, call, sourceFile, fail, label, seen = new Set()) {
+  const object = directConstObjectLiteral(expression, call, sourceFile)
+  if (!object) fail(expression, `${label} component prop spreads must use an inline object literal or one direct const object literal declared in the calling component`)
+  if (seen.has(object)) fail(expression, `${label} component prop spreads cannot be circular`)
+  seen.add(object)
+  const entries = []
+  for (const property of object.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      entries.push(...specializedSpreadEntries(property.expression, call, sourceFile, fail, label, seen))
+      continue
+    }
+    if (ts.isShorthandPropertyAssignment(property)) {
+      entries.push([property.name.text, property.name, property])
+      continue
+    }
+    if (!ts.isPropertyAssignment(property) || ts.isComputedPropertyName(property.name) || !ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name) && !ts.isNumericLiteral(property.name)) {
+      fail(property, `${label} component prop spreads must contain only direct properties`)
+    }
+    entries.push([property.name.text, property.initializer, property])
+  }
+  seen.delete(object)
+  return entries
+}
+
+function specializedCallChildren(call, factory) {
+  if (!ts.isJsxElement(call)) return []
+  return call.children.flatMap(child => {
+    if (ts.isJsxText(child)) {
+      const lines = child.text.split(/\r\n|\n|\r/)
+      const text = lines.length === 1
+        ? child.text
+        : lines.map((line, index) => {
+            let text = line.replace(/\t/g, " ")
+            if (index) text = text.trimStart()
+            if (index < lines.length - 1) text = text.trimEnd()
+            return text
+          }).filter(Boolean).join(" ")
+      return text ? [factory.createStringLiteral(text)] : []
+    }
+    if (ts.isJsxExpression(child)) return child.expression ? [child.expression] : []
+    return [child]
+  })
+}
+
+function flattenForwardedComponentChildren(root, factory, context) {
+  const forwarded = expression => {
+    const value = unwrapExpression(expression)
+    if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value)) return [value]
+    if (ts.isJsxFragment(value)) return [...value.children]
+    if (ts.isArrayLiteralExpression(value) && !value.elements.some(ts.isSpreadElement)) {
+      return value.elements.flatMap(element => {
+        if (ts.isJsxFragment(element)) return [...element.children]
+        if (ts.isJsxElement(element) || ts.isJsxSelfClosingElement(element)) return [element]
+        return [factory.createJsxExpression(undefined, element)]
+      })
+    }
+  }
+  const visit = node => {
+    if (ts.isJsxElement(node)) {
+      const children = node.children.flatMap(child => {
+        const values = ts.isJsxExpression(child) && child.expression ? forwarded(child.expression) : undefined
+        return (values ?? [child]).map(entry => ts.visitNode(entry, visit))
+      })
+      return factory.updateJsxElement(node, ts.visitNode(node.openingElement, visit), children, ts.visitNode(node.closingElement, visit))
+    }
+    return ts.visitEachChild(node, visit, context)
+  }
+  return ts.visitNode(root, visit)
+}
+
 function specializeComponentCall(call, component, sourceFile, factory, context, fail, label = "Keyed list", allowComponentRoot = false) {
   if (component.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || component.asteriskToken) fail(component, `${label} components must be synchronous`)
   if (component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name)) fail(component, `${label} components must use one destructured props parameter`)
-  if (ts.isJsxElement(call) && call.children.some(child => !ts.isJsxText(child) || child.text.trim())) fail(call, `${label} component children are not supported`)
   const callAttributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
   const props = new Map()
+  const directProps = new Set()
   let key
   for (const attribute of callAttributes.properties) {
-    if (ts.isJsxSpreadAttribute(attribute)) fail(attribute, `${label} component prop spreads are not supported`)
+    if (ts.isJsxSpreadAttribute(attribute)) {
+      for (const [name, value, property] of specializedSpreadEntries(attribute.expression, call, sourceFile, fail, label)) {
+        if (["__proto__", "constructor", "prototype"].includes(name)) fail(property, `${label} component prop spread property ${JSON.stringify(name)} is not supported`)
+        if (name === "key") fail(property, `${label} component prop spreads cannot declare key`)
+        props.set(name, value)
+      }
+      continue
+    }
     const name = attribute.name.text
-    if (props.has(name) || name === "key" && key) fail(attribute, `Duplicate ${label.toLowerCase()} component prop "${name}"`)
+    if (directProps.has(name) || name === "key" && key) fail(attribute, `Duplicate ${label.toLowerCase()} component prop "${name}"`)
     const value = !attribute.initializer
       ? factory.createTrue()
       : ts.isStringLiteral(attribute.initializer)
@@ -3377,7 +3473,15 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
           ? attribute.initializer.expression
           : factory.createIdentifier("undefined")
     if (name === "key") key = attribute
-    else props.set(name, value)
+    else {
+      props.set(name, value)
+      directProps.add(name)
+    }
+  }
+  const children = specializedCallChildren(call, factory)
+  if (children.length) {
+    if (directProps.has("children")) fail(call, `Duplicate ${label.toLowerCase()} component prop "children"`)
+    props.set("children", children.length === 1 ? children[0] : factory.createArrayLiteralExpression(children))
   }
   const substitutions = new Map()
   const acceptedProps = new Set()
@@ -3454,7 +3558,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   findUnsupportedHook(returned)
   for (const calculation of calculations) findUnsupportedHook(calculation.expression)
   if (unsupportedHook) throw sourceNodeError(unsupportedHook, component.getSourceFile(), `Keyed row ${unsupportedHook.expression.text}() must be one top-level const declaration`)
-  let root = unwrapExpression(substituteClone(returned, substitutions, factory, context))
+  let root = unwrapExpression(flattenForwardedComponentChildren(substituteClone(returned, substitutions, factory, context), factory, context))
   if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) fail(returned, `${label} component must return one JSX element`)
   const tag = jsxTagName(root)
   if (!ts.isIdentifier(tag) || !allowComponentRoot && tag.text[0] !== tag.text[0].toLowerCase()) fail(returned, `${label} component must directly return an intrinsic JSX element`)
@@ -3663,7 +3767,7 @@ function validateListExpression(expression, item, source, fail, index) {
         fail(source, "Derived keyed list item expressions cannot call arbitrary functions")
       }
     }
-    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && node.text !== item && node.text !== index && !pureListGlobals.has(node.text)) {
+    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isJsxSyntaxIdentifier(node) && node.text !== item && node.text !== index && !pureListGlobals.has(node.text)) {
       fail(source, `Derived keyed list item expression identifier "${node.text}" is not allowed`)
     }
     ts.forEachChild(node, visit)
@@ -3731,7 +3835,7 @@ function referencesIdentifier(root, name) {
 function identifierReferenceCount(root, name) {
   let count = 0
   const visit = node => {
-    if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node)) count++
+    if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node) && !ts.isJsxClosingElement(node.parent)) count++
     ts.forEachChild(node, visit)
   }
   visit(root)

package/package.json

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