@kudzujs/core 0.6.7 → 0.6.9

package/README.md

@@ -330,7 +330,7 @@ const rows = items.map(item => <ItemRow
 />)
 ```
 
-The map may also stay inside one same-file component that receives the local state array directly:
+The map may also stay inside a component that receives the local state array directly. The component may be declared in the page or imported by default or name from a relative TypeScript module; direct named re-exports are resolved at build time:
 
 ```tsx
 function ItemList({ items }: { items: Item[] }) {
@@ -340,12 +340,14 @@ function ItemList({ items }: { items: Item[] }) {
 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 same-file 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.
+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 must be unexported same-file components with one destructured props parameter, an intrinsic return root, no effects, and direct local-state props at every 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. Imported 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>`.
+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>`.
 
 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.
 
+The three-wrapper relative-import fixture emits 2,279 B raw / 629 B gzip HTML and 11,370 B raw / 4,828 B gzip JavaScript, including one imported-wrapper item expression; its unused component handler module is not emitted. After one warm-up, seven clean builds measured 340.2, 349.4, 352.8, 335.0, 354.1, 364.3, and 349.5 ms, with a 349.5 ms median.
+
 ## Effects
 
 Browser-only initial work uses the familiar empty-dependency effect shape:

package/framework/README.md

@@ -21,7 +21,7 @@ Exact relative `.worker.ts` constructors in inline effects are validated and bun
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime. Source CSS and global `kudzu.config` styles are emitted in document heads before `afterBuild()` runs; static stylesheet links in component JSX fail compilation instead of loading from the body.
 
-Same-file components receiving a direct local-state array prop are specialized to intrinsic JSX before keyed-list analysis, so their component function is not retained in the browser. 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, unrelated fields do nothing, and key changes remain remove plus mount. Builds without item dependencies emit no item reader or list-state subscription code.
+Same-file and relative-imported components receiving a direct local-state array prop are specialized to intrinsic JSX before keyed-list analysis, so their component function is not retained in the browser. Handler modules are emitted only when a rendered descriptor references them, preventing specialized imported components from adding dead browser assets. 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, unrelated fields do nothing, and key changes remain remove plus mount. Builds without item dependencies emit no item reader or list-state subscription code.
 
 `kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Direct primitive state, runtime parameter, and keyed-item property dependencies and cleanup are supported. Fragment payloads and coordinated View Transitions are not implemented.
 

package/framework/build.mjs

@@ -70,6 +70,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const emittedRoutes = new Set()
   const emittedApplicationRoutes = new Set()
   const emittedNavigationRecords = []
+  const renderedHandlerUrls = new Set()
   const styleUrls = [...new Set([
     ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
     ...configuredStyles
@@ -129,6 +130,7 @@ export async function build({ quiet = false, minify = true } = {}) {
         runtimeParams: runtimeSchema?.params,
         ...(navigable ? { navigationAsset: navigationGroup.assetPath, applicationId: navigationGroup.applicationId, layoutId: navigationGroup.layoutId, routeId: applicationRoute } : {})
       }, props, module.layout)
+      for (const url of result.handlerModules) renderedHandlerUrls.add(url)
       if (navigationGroup) {
         navigationGroup.hasEffects ||= result.hasEffects
         navigationGroup.hasParams ||= result.hasParams
@@ -163,11 +165,12 @@ export async function build({ quiet = false, minify = true } = {}) {
 
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
+  const emittedHandlerModules = handlerModules.filter(module => renderedHandlerUrls.has(assetPath(base, `assets/${module.path}`)))
   const renderedEffects = new Set(plans.flatMap(plan => plan.effects.map(effect => `${effect.module}:${effect.handler}`)))
   const renderedWorkerReferences = workerReferences.filter(reference => renderedEffects.has(`${reference.module}:${reference.handler}`))
   if (renderedWorkerReferences.length && await exists(join(root, "public", "assets", "workers"))) throw new Error("public/assets/workers collides with Kudzu's generated Worker asset namespace")
   const workerAssets = await emitWorkers(renderedWorkerReferences, sourceFileSet, assetsDirectory, base, minify)
-  for (const module of handlerModules) {
+  for (const module of emittedHandlerModules) {
     for (const reference of workerReferences) {
       if (reference.module !== assetPath(base, `assets/${module.path}`)) continue
       const url = workerAssets.get(reference.placeholder) ?? "about:blank"
@@ -192,7 +195,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasNestedStateCaptures = hasNestedCaptureState(plans)
   const hasSetterCaptures = hasCaptureType(plans, "setter")
   const hasEffectCaptures = plans.some(plan => plan.effects.some(effect => Object.keys(effect.scope).length))
-  const nativeModules = handlerModules.filter(module => module.hasNativeHandlers).map(module => assetPath(base, `assets/${module.path}`))
+  const nativeModules = emittedHandlerModules.filter(module => module.hasNativeHandlers).map(module => assetPath(base, `assets/${module.path}`))
   const hasNativeHandlers = nativeModules.length > 0
   const hasEffects = effectEntries.length > 0
   const hasNavigableEffects = effectEntries.some(entry => entry.navigable)
@@ -290,7 +293,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       await writeJavaScript(join(assetsDirectory, group.assetName), specializeNavigationEffects(navigationRuntime, group.hasEffects || group.hasParams), minify)
     }
   }
-  for (const handlerModule of handlerModules) {
+  for (const handlerModule of emittedHandlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
     await mkdir(resolve(output, ".."), { recursive: true })
     await writeJavaScript(output, handlerModule.code, minify)
@@ -305,11 +308,11 @@ export async function build({ quiet = false, minify = true } = {}) {
     await mkdir(dirname(output), { recursive: true })
     await writeJavaScript(output, entry.navigable
       ? entry.effects.some(effect => effect.owner)
-        ? printOwnedNavigableEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base)
-        : printNavigableEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base)
-      : printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath, runtimeName(entry.usesDependencyRuntime)), minify)
+        ? printOwnedNavigableEffectEntry(entry.effects, output, emittedHandlerModules, assetsDirectory, base)
+        : printNavigableEffectEntry(entry.effects, output, emittedHandlerModules, assetsDirectory, base)
+      : printEffectEntry(entry.effects, output, emittedHandlerModules, assetsDirectory, base, entry.paramPath, runtimeName(entry.usesDependencyRuntime)), minify)
   }
-  const clientModules = await collectClientModules(handlerModules.flatMap(module => module.clientImports), sourceFileSet)
+  const clientModules = await collectClientModules(emittedHandlerModules.flatMap(module => module.clientImports), sourceFileSet)
   for (const file of clientModules) {
     const output = join(assetsDirectory, clientModulePath(file))
     await mkdir(resolve(output, ".."), { recursive: true })
@@ -317,7 +320,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   }
   if (clientModules.length) {
     await bundle({
-      entryPoints: handlerModules.map(module => join(assetsDirectory, module.path)),
+      entryPoints: emittedHandlerModules.map(module => join(assetsDirectory, module.path)),
       outbase: join(assetsDirectory, "handlers"),
       outdir: join(assetsDirectory, "handlers"),
       entryNames: "[dir]/[name]",
@@ -1724,6 +1727,26 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       specializedDeclarations.add(component.declaration)
       stateBackedComponentFunctions.add(component.function)
     }
+    for (const [name, binding] of importBindings) {
+      if (binding.kind === "namespace") continue
+      const calls = jsxTagUses(sourceFile, name)
+      if (!calls.some(call => jsxCallHasDirectStateProp(call, settersByFunction.get(nearestFunction(call)) ?? new Map()))) continue
+      const imported = binding.kind === "default" ? "default" : binding.imported
+      let component
+      try {
+        component = resolveComponentExport(binding.target, imported, importedSource, sourceFiles)
+      } catch (error) {
+        if (error.message.includes("does not export a statically analyzable keyed list component")) continue
+        throw error
+      }
+      const stateBackedCalls = calls.filter(call => isStateBackedListComponentCall(call, component, settersByFunction.get(nearestFunction(call)) ?? new Map()))
+      for (const call of stateBackedCalls) {
+        const specialization = specializeComponentCall(call, component, sourceFile, factory, context, fail)
+        if (specialization.effects.length) fail(call, "State-backed list components cannot declare effects")
+        componentSpecializations.set(call, specialization)
+        stateBackedComponentRoots.push(specialization.root)
+      }
+    }
     const rawRenderedLists = []
     const collectRenderedLists = node => {
       const specialization = componentSpecializations.get(node)
@@ -2164,7 +2187,7 @@ function keyedListParts(expression, setters) {
   const root = unwrapExpression(callback.body)
   if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) throw new Error("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) && attribute.name.getText() === "key")
+  const key = attributes.properties.find(attribute => ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name) && attribute.name.text === "key")
   const field = key && ts.isJsxAttribute(key) && key.initializer && ts.isJsxExpression(key.initializer) && key.initializer.expression && directProperty(key.initializer.expression, callback.parameters[0].name.text)
   if (!field) throw new Error(`Keyed list root must have key={${callback.parameters[0].name.text}.<field>}`)
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
@@ -2200,6 +2223,15 @@ function isStateBackedListComponentCall(call, component, setters) {
   return found
 }
 
+function jsxCallHasDirectStateProp(call, setters) {
+  const attributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
+  const stateNames = new Set(setters.values())
+  return attributes.properties.some(attribute => {
+    const value = ts.isJsxAttribute(attribute) && attribute.initializer && ts.isJsxExpression(attribute.initializer) ? unwrapExpression(attribute.initializer.expression) : undefined
+    return value && ts.isIdentifier(value) && stateNames.has(value.text)
+  })
+}
+
 function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions) {
   const fail = (node, message) => {
     throw sourceNodeError(node, sourceFile, message)

package/framework/core.d.ts

@@ -70,6 +70,7 @@ export function renderPage<Props = Record<string, never>>(
   hasLists: boolean
   hasListStyles: boolean
   hasStateSeed: boolean
+  handlerModules: string[]
   plan: {
     states: Array<{ id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route" }>
     params: Array<{ name: string; id: string }>

package/framework/core.mjs

@@ -99,6 +99,7 @@ export function useEffect(callback, dependencies, module, handler, states, scope
     owners.push(owner)
   }
   if (!renderContext.listDepth || list) renderContext.effects.push({ module, handler, states, scope, source, renderScope: renderContext.renderScope, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(itemDependencies.length ? { itemDependencies, listState: renderContext.listRoot.state } : {}), ...(cleanup ? { cleanup: true } : {}), ...(owner ? { owner } : {}), ...(list ? { list: true } : {}) })
+  renderContext.handlerModules.add(module)
   renderContext.hasBehaviors = true
   renderContext.hasEffects = true
 }
@@ -141,6 +142,7 @@ export function behavior(commands) {
 }
 
 export function nativeBehavior(module, handler, states, scope) {
+  renderContext?.handlerModules.add(module)
   return {
     [nativeBehaviorMarker]: true,
     module,
@@ -187,6 +189,7 @@ export function listField(read, field) {
 }
 
 export function listExpression(read, module, handler) {
+  renderContext?.handlerModules.add(module)
   const value = renderContext?.listTemplate ? undefined : read()
   if (value && typeof value.then === "function") throw new Error("Derived keyed list item expressions must return synchronous values")
   return { [listExpressionMarker]: true, module, handler, value }
@@ -197,6 +200,7 @@ export function listItem() {
 }
 
 export function listConditional(kind, read, truthy, falsy, module, handler) {
+  renderContext?.handlerModules.add(module)
   return { [listConditionalMarker]: true, kind, value: renderContext?.listTemplate ? undefined : read(), truthy, falsy, module, handler }
 }
 
@@ -230,6 +234,7 @@ function assertListValue(value, seen) {
 }
 
 function reactiveDescriptor(module, handler, states, scope) {
+  renderContext?.handlerModules.add(module)
   const scopeStates = {}
   const serializedScope = {}
   const scopeBindings = {}
@@ -295,7 +300,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, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], effectOwners: [], contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], 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, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], 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 }
@@ -370,6 +375,7 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
       hasLists: renderContext.hasLists,
       hasListStyles: renderContext.hasListStyles,
       hasStateSeed: initialState.length > 0,
+      handlerModules: [...renderContext.handlerModules],
       plan: {
         states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
         params: renderContext.paramEntries,

package/package.json

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