@kudzujs/core 0.7.6 → 0.7.9

package/RELEASES.md

@@ -1,5 +1,78 @@
 # Kudzu Releases
 
+## 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.
+
+### New in 0.7.9
+
+- Same-file and relative-imported keyed row components accept string, finite-number, boolean, and `null` defaults.
+- Missing props receive their default literals during existing component specialization.
+- The component call lowers to intrinsic keyed JSX; React imports and the component call do not enter browser output.
+- Rest and nested destructuring remain source-diagnosed, while object, array, computed, and call defaults remain rejected.
+- No browser runtime branch or shared asset bytes are added.
+- The product documents now define commerce and realtime dashboards as validation fixtures under one general React migration roadmap, not separate product verticals.
+
+### Boundary
+
+This release supports primitive literal defaults on compiler-specialized keyed rows. General prop spreads, rest bindings, non-primitive defaults, specialized `children`, `forwardRef`, and `useId` remain fixture-driven composition work.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.9
+```
+
+## 0.7.8 - Static collection fast paths
+
+Kudzu 0.7.8 specializes compiler-owned static `filter` collections so repeated category changes avoid general keyed-list validation and reconciliation.
+
+### New in 0.7.8
+
+- Static source items, unique keys, source positions, and reference entries validate and cache once when the list mounts.
+- Structural rows removed by a filter become detached prototypes; restoration clones fresh DOM, preserving remount semantics without moving retained keys.
+- Interleaved additions insert only new contiguous runs instead of attaching additions and then reordering the complete list.
+- General local-state lists, dynamic selectors, indexed rows, handlers, effects, refs, and row state retain their existing reconciliation paths.
+- The capability is route-specific and compiles out when no compiler-owned static collection is rendered.
+- The matched route adds 648 B gzip compared with 0.7.7's initial implementation while reducing 500-row restoration from 13.2 ms to 3.6 ms.
+
+### Benchmark
+
+The matched fixture imports 1,000 alternating products, filters to 500, then restores all 1,000 while checking retained and remounted DOM identity. Thirty-one rotating fresh Chrome 150 profiles on an Apple M3 used 4x CPU throttling. Median visible/filter/restore times were Kudzu 37.8/8.4/3.6 ms, React 86.3/12.9/6.2 ms, Vue 54.1/8.4/4.3 ms, and Svelte 61.4/11.7/8.3 ms. React, Vue, and Svelte used Vite CSR shells while Kudzu emitted initial HTML, so visible-row and artifact comparisons are architecture-dependent.
+
+### Boundary
+
+The fast path requires a compiler-owned static source, field keys, filter-only selection, and structural rows without handlers, effects, refs, row state, or index dependencies. It is intended for ordinary catalog-sized collections, not direct rendering of 100,000 or 1,000,000 DOM rows; use pagination or windowing for those workloads.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.8
+```
+
+## 0.7.7 - Imported memo collections
+
+Kudzu 0.7.7 lets ordinary React migration source filter an imported static catalog through state-dependent `useMemo` while reusing existing keyed-list reconciliation.
+
+### New in 0.7.7
+
+- Named relative imports of exported JSON-safe `const` arrays can anchor analyzable collection pipelines.
+- Direct local-state reads in collection selectors invalidate the list when their declared state dependencies change.
+- Existing keys retain DOM identity through filtering and restoration; removed keys remount when restored.
+- Compiler-owned static collection state is excluded from development snapshot restoration.
+- Static routes remain JavaScript-free, and interactive routes ship no React runtime or browser memo cache.
+- Focused fixtures verify dependency diagnostics, static output, generated selectors, and browser DOM identity.
+
+### Boundary
+
+Static collections must be named relative imports of exported JSON-safe `const` arrays. Package, namespace, default, dynamic, mutable, and non-serializable collection sources remain unsupported, as do arbitrary callbacks and general-purpose memo caching.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.7
+```
+
 ## 0.7.6 - Zustand-shaped shared stores
 
 Kudzu 0.7.6 lets reduced React migration source retain a Zustand `create(set => ...)` store across an explicitly configured shared-layout navigation group.

package/framework/README.md

@@ -2,7 +2,7 @@
 
 Kudzu specializes ordinary common React-shaped TSX so migrations need minimal source restructuring. Declarative components, collection pipelines, conditions, hooks, and handlers should be lowered at build time rather than replaced with application-owned imperative DOM code. This principle applies across migrations and is not Stay-specific; it does not imply a React package, VDOM, hydration, or ecosystem runtime.
 
-Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, same-file `memo`, inline `useCallback`, direct-state expression or analyzable collection-pipeline `useMemo`, and default, namespace, or named `Fragment`. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. Memo wrappers are erased or inlined into existing bindings and keyed-list selectors because no browser component rerender or memo cache exists. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
+Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, same-file `memo`, inline `useCallback`, direct-state expression or analyzable collection-pipeline `useMemo`, and default, namespace, or named `Fragment`. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array and may read direct local state declared in their dependency array. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. Memo wrappers are erased or inlined into existing bindings and keyed-list selectors because no browser component rerender or memo cache exists. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
 
 Direct `clsx` calls over literal strings, numbers, arrays, object conditions, and conditional expressions are similarly lowered to ordinary concatenation and conditional expressions. The package import is erased, and dynamic classes continue through the existing binding compiler without serializing or shipping the `clsx` function.
 
@@ -31,9 +31,9 @@ Page `metadata` can emit description, canonical, favicon, manifest, Open Graph,
 
 Inline SVG rendering normalizes an explicit set of common React presentation aliases before static serialization and binding descriptor creation. Reactive aliases therefore use the existing generic `setAttribute` path; static SVG adds no JavaScript and reactive SVG adds no SVG-specific runtime.
 
-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. 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.
+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. Supported selectors are pure `filter`, direct-property `flatMap`, and `Array.from` before a final keyed `map`; field keys retain item identity while `key={index}` retains positional identity. 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. 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.
 
 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

@@ -213,6 +213,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasComplexListRowState = plans.some(plan => plan.lists.some(list => list.rowStates?.some(state => state.initialValue !== null && typeof state.initialValue === "object")))
   const hasNestedLists = plans.some(plan => plan.lists.some(list => list.ownerField))
   const hasCollectionSelectors = plans.some(plan => plan.lists.some(list => list.selector))
+  const hasStaticCollections = plans.some(plan => plan.lists.some(list => list.static))
   const hasListIndexes = plans.some(plan => plan.lists.some(list => list.indexed))
   const hasListStableFastPaths = plans.some(plan => plan.lists.some(list => !list.children && !list.ownerField && list.key !== null && !list.indexed && !list.reducer && !list.selector))
   const hasGeneralListRowHooks = hasListRowRefs || hasComplexListRowState || plans.some(plan => plan.lists.some(list => list.ownerField && (list.rowStates?.length || list.rowRefs?.length)))
@@ -343,6 +344,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       __KUDZU_COMPLEX_LIST_ROW_STATE__: String(hasComplexListRowState),
       __KUDZU_NESTED_LISTS__: String(hasNestedLists),
       __KUDZU_COLLECTION_SELECTORS__: String(hasCollectionSelectors),
+      __KUDZU_STATIC_COLLECTIONS__: String(hasStaticCollections),
       __KUDZU_LIST_INDEXES__: String(hasListIndexes),
       __KUDZU_LIST_STABLE_FAST_PATHS__: String(hasListStableFastPaths)
     })
@@ -1879,7 +1881,7 @@ function normalizeZustandMigrationSyntax(sourceFile, factory, context) {
   return factory.updateSourceFile(normalized, statements)
 }
 
-function normalizeReactMigrationSyntax(sourceFile, factory, context) {
+function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCollections = new Set()) {
   const supported = new Set(["createContext", "useContext", "useEffect", "useReducer", "useRef", "useState"])
   const erased = new Set(["memo", "useCallback", "useMemo"])
   const aliases = new Map()
@@ -2013,14 +2015,15 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context) {
         const dependencies = new Set(node.arguments[1].elements.map(unwrapExpression).filter(ts.isIdentifier).map(entry => entry.text))
         const owner = nearestFunction(node)
         const states = owner ? ownerStateNames(owner) : new Set()
-        const collectionState = expression && reactMemoCollectionState(expression, states, sourceFile)
-        if (!expression || !collectionState && !isPureReactMemoExpression(expression)) throw sourceNodeError(callback.body, sourceFile, "React useMemo() callback must return one pure expression or analyzable collection pipeline")
-        if (!collectionState) {
+        const collection = expression && reactMemoCollection(expression, states, importedCollections, sourceFile)
+        if (!expression || !collection && !isPureReactMemoExpression(expression)) throw sourceNodeError(callback.body, sourceFile, "React useMemo() callback must return one pure expression or analyzable collection pipeline")
+        if (!collection) {
           const unsupported = [...reactMemoReferenceNames(expression)].find(reference => !states.has(reference))
           if (unsupported) throw sourceNodeError(expression, sourceFile, `React useMemo() pure expressions may only reference direct local state; found ${JSON.stringify(unsupported)}`)
         }
-        const stale = collectionState
-          ? !dependencies.has(collectionState) ? collectionState : undefined
+        const collectionDependencies = collection ? new Set([...collection.selectorStates, ...(collection.static ? [] : [collection.state.text])]) : undefined
+        const stale = collection
+          ? [...collectionDependencies].find(state => !dependencies.has(state))
           : [...states].find(state => referenceIdentifiers(expression, state).length && !dependencies.has(state))
         if (stale) throw sourceNodeError(node.arguments[1], sourceFile, `React useMemo() must list captured state ${JSON.stringify(stale)} as a dependency`)
         return ts.visitNode(expression, visitor)
@@ -2106,10 +2109,10 @@ function lowerReactMemoCollectionExpression(expression, factory) {
   return visit(expression)
 }
 
-function reactMemoCollectionState(expression, states, sourceFile) {
+function reactMemoCollection(expression, states, importedCollections, sourceFile) {
   const setters = new Map([...states].map(state => [state, state]))
   const fail = (node, message) => { throw sourceNodeError(node, sourceFile, message) }
-  return renderedCollectionSource(expression, setters, undefined, fail, new Set())?.state?.text
+  return renderedCollectionSource(expression, setters, undefined, fail, new Set(), importedCollections, states)
 }
 
 function reactMemoComponentExpression(identifier, sourceFile, factory, context) {
@@ -2150,9 +2153,10 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
   return context => sourceFile => {
     const factory = context.factory
     const hasLinkElements = /<link/i.test(sourceFile.text)
+    const importedCollections = importedSerializableCollectionNames(sourceFile, file, sourceFiles, sourceIndex)
     sourceFile = normalizeClsxSyntax(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
-    sourceFile = normalizeReactMigrationSyntax(sourceFile, factory, context)
+    sourceFile = normalizeReactMigrationSyntax(sourceFile, factory, context, importedCollections)
     ts.setParentRecursive(sourceFile, false)
     sourceFile = normalizeZustandMigrationSyntax(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
@@ -2167,7 +2171,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       if (!imported) {
         imported = normalizeClsxSyntax(parseSourceFile(target, sourceIndex.get(target)), factory, context)
         ts.setParentRecursive(imported, false)
-        imported = normalizeReactMigrationSyntax(imported, factory, context)
+        imported = normalizeReactMigrationSyntax(imported, factory, context, importedSerializableCollectionNames(imported, target, sourceFiles, sourceIndex))
         ts.setParentRecursive(imported, false)
         imported = normalizeZustandMigrationSyntax(imported, factory, context)
         ts.setParentRecursive(imported, false)
@@ -2314,7 +2318,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       const setters = settersByFunction.get(owner) ?? new Map()
       for (const [name, entries] of declarations) {
         for (const declaration of entries) {
-          const parts = keyedListParts(declaration.initializer, setters, declarations, (target, message) => { throw sourceNodeError(target, sourceFile, message) })
+          const parts = keyedListParts(declaration.initializer, setters, declarations, (target, message) => { throw sourceNodeError(target, sourceFile, message) }, new Set(), importedCollections)
           if (!parts) continue
           const uses = []
           const collectUses = node => {
@@ -2508,7 +2512,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         return
       }
       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), jsxLocalDeclarations.get(nearestFunction(node)), fail)
+        const parts = listLocalUses.get(node) ?? keyedListParts(node.expression, settersForNode(node, settersByFunction), jsxLocalDeclarations.get(nearestFunction(node)), fail, new Set(), importedCollections)
         if (parts) {
           for (const declaration of parts.aliasDeclarations ?? []) listLocalDeclarations.add(declaration)
           rawRenderedLists.push({ node, parts })
@@ -2824,14 +2828,16 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         if (listParts) {
           usesBehavior = true
           usesList = true
-          return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
+          const arguments_ = [
             listParts.state,
             listParts.keyField === null ? factory.createNull() : factory.createStringLiteral(listParts.keyField),
             ts.visitNode(listParts.callback, visitor),
             factory.createStringLiteral(listParts.ownerField ?? ""),
             jsonExpression(listParts.selector ?? [], factory),
             listParts.indexed ? factory.createTrue() : factory.createFalse()
-          ]))
+          ]
+          if (listParts.selectorStates?.size) arguments_.push(factory.createArrayLiteralExpression([...listParts.selectorStates].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
+          return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, arguments_))
         }
         const conditional = conditionalParts(node.expression)
         if (conditional) {
@@ -3017,11 +3023,11 @@ function containsRenderControl(root, knownLocals) {
   return found
 }
 
-function keyedListParts(expression, setters, declarations, fail, aliases = new Set()) {
+function keyedListParts(expression, setters, declarations, fail, aliases = new Set(), importedCollections = new Set()) {
   const value = unwrapExpression(expression)
   const directFrom = isArrayFromCall(value) && value.arguments.length === 2 && containsJsx(value.arguments[1])
   if (!directFrom && (!ts.isCallExpression(value) || value.arguments.length !== 1 || !ts.isPropertyAccessExpression(value.expression) || value.expression.name.text !== "map")) return undefined
-  const collection = renderedCollectionSource(directFrom ? value.arguments[0] : value.expression.expression, setters, declarations, fail, aliases)
+  const collection = renderedCollectionSource(directFrom ? value.arguments[0] : value.expression.expression, setters, declarations, fail, aliases, importedCollections, new Set(setters.values()))
   if (!collection?.state) return undefined
   if (directFrom) collection.selector.push(["from", undefined])
   const callback = directFrom ? value.arguments[1] : value.arguments[0]
@@ -3055,16 +3061,17 @@ function nestedKeyedListParts(expression, parentItem, fail) {
   return { ...collection, callback, root, item: parameters.item, index: parameters.index, indexed: Boolean(parameters.index), keyField: positional ? null : keyField }
 }
 
-function renderedCollectionSource(expression, setters, declarations, fail, aliases) {
+function renderedCollectionSource(expression, setters, declarations, fail, aliases, importedCollections = new Set(), stateNames = new Set()) {
   const value = unwrapExpression(expression)
   if (ts.isIdentifier(value)) {
-    if ([...setters.values()].includes(value.text)) return { state: value, selector: [] }
+    if ([...setters.values()].includes(value.text)) return { state: value, selector: [], selectorStates: new Set() }
+    if (importedCollections.has(value.text)) return { state: value, static: true, selector: [], selectorStates: new Set() }
     const entries = declarations?.get(value.text)
     if (!entries) return undefined
     if (entries.length !== 1 || aliases.has(value.text) || entries[0].node.parent?.parent?.parent !== nearestFunction(entries[0].node)?.body) fail(value, `Rendered collection alias "${value.text}" must be one top-level immutable local`)
     if (identifierReferenceCount(nearestFunction(entries[0].node).body, value.text) !== 1) fail(value, `Rendered collection alias "${value.text}" may only be rendered once`)
     aliases.add(value.text)
-    const source = renderedCollectionSource(entries[0].initializer, setters, declarations, fail, aliases)
+    const source = renderedCollectionSource(entries[0].initializer, setters, declarations, fail, aliases, importedCollections, stateNames)
     aliases.delete(value.text)
     return source && { ...source, aliasDeclarations: [...(source.aliasDeclarations ?? []), entries[0].node] }
   }
@@ -3073,14 +3080,15 @@ function renderedCollectionSource(expression, setters, declarations, fail, alias
     const method = value.expression.name.text
     if (method === "filter") {
       if (value.arguments.length !== 1) fail(value, "Rendered collection filter() requires one inline predicate")
-      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases)
+      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames)
       if (!source) return undefined
       const parameters = collectionParameters(value.arguments[0], "Rendered collection filter()", fail)
-      return { ...source, selector: [...source.selector, ["filter", collectionExpression(unwrapExpression(value.arguments[0].body), parameters, fail)]] }
+      const selectorStates = new Set(source.selectorStates)
+      return { ...source, selector: [...source.selector, ["filter", collectionExpression(unwrapExpression(value.arguments[0].body), parameters, fail, stateNames, selectorStates)]], selectorStates }
     }
     if (method === "flatMap") {
       if (value.arguments.length !== 1) fail(value, "Rendered collection flatMap() requires one inline projector")
-      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases)
+      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames)
       if (!source) return undefined
       const parameters = collectionParameters(value.arguments[0], "Rendered collection flatMap()", fail)
       const field = directProperty(value.arguments[0].body, parameters.item)
@@ -3091,12 +3099,14 @@ function renderedCollectionSource(expression, setters, declarations, fail, alias
   }
   if (isArrayFromCall(value)) {
     if (value.arguments.length < 1 || value.arguments.length > 2) fail(value, "Rendered Array.from() requires an anchor and optional inline mapper")
-    const source = renderedCollectionSource(value.arguments[0], setters, declarations, fail, aliases)
+    const source = renderedCollectionSource(value.arguments[0], setters, declarations, fail, aliases, importedCollections, stateNames)
     if (!source) return undefined
     let mapper
     if (value.arguments[1]) {
       const parameters = collectionParameters(value.arguments[1], "Rendered Array.from() mapper", fail)
-      mapper = collectionExpression(unwrapExpression(value.arguments[1].body), parameters, fail)
+      const selectorStates = new Set(source.selectorStates)
+      mapper = collectionExpression(unwrapExpression(value.arguments[1].body), parameters, fail, stateNames, selectorStates)
+      source.selectorStates = selectorStates
     }
     return { ...source, selector: [...source.selector, ["from", mapper]] }
   }
@@ -3111,7 +3121,7 @@ function collectionParameters(callback, label, fail) {
   return { item: callback.parameters[0].name.text, index: callback.parameters[1]?.name.text }
 }
 
-function collectionExpression(expression, parameters, fail) {
+function collectionExpression(expression, parameters, fail, stateNames = new Set(), selectorStates = new Set()) {
   const encode = node => {
     node = unwrapExpression(node)
     if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node)) return ["value", ts.isNumericLiteral(node) ? Number(node.text) : node.text]
@@ -3122,6 +3132,10 @@ function collectionExpression(expression, parameters, fail) {
       if (node.text === parameters.item) return ["item"]
       if (node.text === parameters.index) return ["index"]
       if (node.text === "undefined") return ["undefined"]
+      if (stateNames.has(node.text)) {
+        selectorStates.add(node.text)
+        return ["state", node.text]
+      }
       fail(node, `Rendered collection expression identifier "${node.text}" is not allowed`)
     }
     if (ts.isPropertyAccessExpression(node)) {
@@ -3368,7 +3382,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   const substitutions = new Map()
   const acceptedProps = new Set()
   for (const element of component.parameters[0].name.elements) {
-    if (element.dotDotDotToken || !ts.isIdentifier(element.name) || (element.initializer && label === "Keyed list")) fail(element, `${label} component props cannot use rest, defaults, or nested destructuring`)
+    if (element.dotDotDotToken || !ts.isIdentifier(element.name)) fail(element, `${label} component props cannot use rest or nested destructuring`)
     if (element.initializer && !isPrimitiveDefaultLiteral(element.initializer)) fail(element.initializer, `${label} component prop defaults must be primitive literals`)
     const prop = (element.propertyName ?? element.name).text
     acceptedProps.add(prop)
@@ -4160,6 +4174,20 @@ function clientImportBindings(sourceFile, file, sourceFiles) {
   return bindings
 }
 
+function importedSerializableCollectionNames(sourceFile, file, sourceFiles, sourceIndex) {
+  const names = new Set()
+  for (const [name, binding] of clientImportBindings(sourceFile, file, sourceFiles)) {
+    if (binding.kind !== "named") continue
+    const imported = parseSourceFile(binding.target, sourceIndex.get(binding.target))
+    for (const statement of imported.statements) {
+      if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const) || !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue
+      const declaration = statement.declarationList.declarations.find(entry => ts.isIdentifier(entry.name) && entry.name.text === binding.imported)
+      if (declaration?.initializer && ts.isArrayLiteralExpression(unwrapExpression(declaration.initializer)) && isSerializableStateLiteral(declaration.initializer)) names.add(name)
+    }
+  }
+  return names
+}
+
 function resolveComponentExport(file, exportName, getSource, sourceFiles, trail = []) {
   const key = `${file}:${exportName}`
   if (trail.includes(key)) throw new Error(`Imported keyed list component re-export cycle: ${[...trail, key].map(entry => relative(root, entry.slice(0, entry.lastIndexOf(":")))).join(" -> ")}`)

package/framework/collection-selector.js

@@ -1,10 +1,10 @@
-export function selectCollection(anchor, selector = []) {
+export function selectCollection(anchor, selector = [], readState) {
   let values = anchor == null ? [] : anchor
   for (const operation of selector) {
-    if (operation[0] === "from") values = Array.from(values, operation[1] ? (item, index) => evaluateCollectionExpression(operation[1], item, index) : undefined)
+    if (operation[0] === "from") values = Array.from(values, operation[1] ? (item, index) => evaluateCollectionExpression(operation[1], item, index, readState) : undefined)
     else {
       if (!Array.isArray(values)) throw new Error("Rendered collection source must remain an array")
-      if (operation[0] === "filter") values = values.filter((item, index) => evaluateCollectionExpression(operation[1], item, index))
+      if (operation[0] === "filter") values = values.filter((item, index) => evaluateCollectionExpression(operation[1], item, index, readState))
       else if (operation[0] === "flatMap") values = values.flatMap(item => item?.[operation[1]] ?? [])
     }
   }
@@ -12,29 +12,33 @@ export function selectCollection(anchor, selector = []) {
   return values
 }
 
-function evaluateCollectionExpression(expression, item, index) {
+function evaluateCollectionExpression(expression, item, index, readState) {
   const [kind, ...parts] = expression
   if (kind === "value") return parts[0]
   if (kind === "undefined") return undefined
   if (kind === "item") return item
   if (kind === "index") return index
+  if (kind === "state") {
+    if (!readState) throw new Error(`Rendered collection state ${JSON.stringify(parts[0])} is not available`)
+    return readState(parts[0])
+  }
   if (kind === "get") {
-    const object = evaluateCollectionExpression(parts[0], item, index)
+    const object = evaluateCollectionExpression(parts[0], item, index, readState)
     return object == null && parts[2] ? undefined : object[parts[1]]
   }
   if (kind === "unary") {
-    const value = evaluateCollectionExpression(parts[1], item, index)
+    const value = evaluateCollectionExpression(parts[1], item, index, readState)
     if (parts[0] === "!") return !value
     if (parts[0] === "+") return +value
     if (parts[0] === "-") return -value
     if (parts[0] === "typeof") return typeof value
   }
   if (kind === "binary") {
-    const left = evaluateCollectionExpression(parts[1], item, index)
-    if (parts[0] === "&&") return left && evaluateCollectionExpression(parts[2], item, index)
-    if (parts[0] === "||") return left || evaluateCollectionExpression(parts[2], item, index)
-    if (parts[0] === "??") return left ?? evaluateCollectionExpression(parts[2], item, index)
-    const right = evaluateCollectionExpression(parts[2], item, index)
+    const left = evaluateCollectionExpression(parts[1], item, index, readState)
+    if (parts[0] === "&&") return left && evaluateCollectionExpression(parts[2], item, index, readState)
+    if (parts[0] === "||") return left || evaluateCollectionExpression(parts[2], item, index, readState)
+    if (parts[0] === "??") return left ?? evaluateCollectionExpression(parts[2], item, index, readState)
+    const right = evaluateCollectionExpression(parts[2], item, index, readState)
     if (parts[0] === "===") return left === right
     if (parts[0] === "!==") return left !== right
     if (parts[0] === "==") return left == right
@@ -49,15 +53,15 @@ function evaluateCollectionExpression(expression, item, index) {
     if (parts[0] === "/") return left / right
     if (parts[0] === "%") return left % right
   }
-  if (kind === "conditional") return evaluateCollectionExpression(parts[0], item, index) ? evaluateCollectionExpression(parts[1], item, index) : evaluateCollectionExpression(parts[2], item, index)
-  if (kind === "array") return parts.map(value => evaluateCollectionExpression(value, item, index))
-  if (kind === "object") return Object.fromEntries(parts.map(([key, value]) => [key, evaluateCollectionExpression(value, item, index)]))
-  if (kind === "template") return parts[0].map((text, offset) => text + (offset < parts[1].length ? evaluateCollectionExpression(parts[1][offset], item, index) : "")).join("")
+  if (kind === "conditional") return evaluateCollectionExpression(parts[0], item, index, readState) ? evaluateCollectionExpression(parts[1], item, index, readState) : evaluateCollectionExpression(parts[2], item, index, readState)
+  if (kind === "array") return parts.map(value => evaluateCollectionExpression(value, item, index, readState))
+  if (kind === "object") return Object.fromEntries(parts.map(([key, value]) => [key, evaluateCollectionExpression(value, item, index, readState)]))
+  if (kind === "template") return parts[0].map((text, offset) => text + (offset < parts[1].length ? evaluateCollectionExpression(parts[1][offset], item, index, readState) : "")).join("")
   if (kind === "call") {
-    const receiver = evaluateCollectionExpression(parts[0], item, index)
-    return receiver[parts[1]](...parts.slice(2).map(value => evaluateCollectionExpression(value, item, index)))
+    const receiver = evaluateCollectionExpression(parts[0], item, index, readState)
+    return receiver[parts[1]](...parts.slice(2).map(value => evaluateCollectionExpression(value, item, index, readState)))
   }
-  if (kind === "global") return globalThis[parts[0]](...parts.slice(1).map(value => evaluateCollectionExpression(value, item, index)))
-  if (kind === "math") return Math[parts[0]](...parts.slice(1).map(value => evaluateCollectionExpression(value, item, index)))
+  if (kind === "global") return globalThis[parts[0]](...parts.slice(1).map(value => evaluateCollectionExpression(value, item, index, readState)))
+  if (kind === "math") return Math[parts[0]](...parts.slice(1).map(value => evaluateCollectionExpression(value, item, index, readState)))
   throw new Error(`Unsupported rendered collection expression: ${String(kind)}`)
 }

package/framework/core.d.ts

@@ -31,7 +31,7 @@ export function nativeBehavior(module: string, handler: string, states: Array<[s
 export function binding(value: unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
 export function bindingValue(value: unknown): unknown
 export function conditional(kind: "and" | "ternary", value: unknown, truthy: () => unknown, falsy: () => unknown, module: string, handler: string, states: Array<[string, unknown]>, scope: Array<[string, unknown]>): unknown
-export function list(items: unknown, keyField: string | null, render: (item: unknown, index: number) => unknown, ownerField?: string, selector?: unknown[], indexed?: boolean): unknown
+export function list(items: unknown, keyField: string | null, render: (item: unknown, index: number) => unknown, ownerField?: string, selector?: unknown[], indexed?: boolean, selectorStates?: Array<[string, unknown]>): unknown
 export function listField(read: () => unknown, field: string): unknown
 export function listExpression(read: () => unknown, module: string, handler: string): unknown
 export function listItem(): unknown
@@ -89,7 +89,7 @@ export function renderPage<Props = Record<string, never>>(
   hasStateSeed: boolean
   handlerModules: string[]
   plan: {
-    states: Array<{ id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route" }>
+    states: Array<{ id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route"; internal?: true }>
     params: Array<{ name: string; id: string }>
     events: Array<{
       event: string

package/framework/core.mjs

@@ -2,6 +2,7 @@ import { serializeStyle } from "./style.js"
 import { selectCollection } from "./collection-selector.js"
 
 const signalMarker = Symbol("kudzu.signal")
+const internalStateMarker = Symbol("kudzu.internal-state")
 const setterMarker = Symbol("kudzu.setter")
 const reducerDispatchMarker = Symbol("kudzu.reducerDispatch")
 const reducerStateMarker = Symbol("kudzu.reducerState")
@@ -130,6 +131,14 @@ function createSignal(id, value) {
   }
 }
 
+function createInternalState(initialValue) {
+  const id = nextRenderId("s")
+  const signal = createSignal(id, initialValue)
+  signal[internalStateMarker] = true
+  renderContext.states[id] = { name: id, initialValue, internal: true, ...(renderContext.scoped ? { lifetime: renderContext.renderScope } : {}) }
+  return signal
+}
+
 export function useEffect(callback, dependencies, module, handler, states, scope, source, cleanup, itemDependencies = []) {
   if (!renderContext) throw new Error("useEffect() can only run while rendering a Kudzu component")
   if (typeof callback !== "function" || !Array.isArray(dependencies) || !module || !handler) throw new Error("useEffect() must be compiled with a literal dependency array")
@@ -247,8 +256,11 @@ export function stateConditional(kind, state, truthy, falsy) {
   return { [conditionalMarker]: true, kind, value: state.value, truthy, falsy, state: state.id }
 }
 
-export function list(items, keyField, render, ownerField, selector = [], indexed = false) {
-  if (!items?.[signalMarker] || !Array.isArray(items.value)) throw new Error("A keyed list must use local array state")
+export function list(items, keyField, render, ownerField, selector = [], indexed = false, selectorStates = []) {
+  if (Array.isArray(items)) items = createInternalState(items)
+  if (!items?.[signalMarker] || !Array.isArray(items.value)) throw new Error("A keyed list must use local array state or a supported imported static array")
+  const selectorStateMap = new Map(selectorStates)
+  for (const [name, state] of selectorStateMap) if (!state?.[signalMarker]) throw new Error(`Rendered collection selector state ${JSON.stringify(name)} must be framework state`)
   let values = items.value
   if (ownerField) {
     const owner = renderContext?.listRoot ?? renderContext?.listRowRoot
@@ -257,7 +269,7 @@ export function list(items, keyField, render, ownerField, selector = [], indexed
     values = renderContext.listTemplate ? [] : owner.item?.[ownerField]
     if (!Array.isArray(values) && values != null) throw new Error(`Nested keyed list property "${ownerField}" must remain an array`)
   }
-  values = selectCollection(values, selector)
+  values = selectCollection(values, selector, name => selectorStateMap.get(name)?.value)
   const keys = new Set()
   for (const [index, item] of values.entries()) {
     const key = keyField === null ? index : item?.[keyField]
@@ -268,7 +280,7 @@ export function list(items, keyField, render, ownerField, selector = [], indexed
     if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
     keys.add(token)
   }
-  return { [listMarker]: true, items, values, keyField, render, ownerField, selector, indexed }
+  return { [listMarker]: true, items, values, keyField, render, ownerField, selector, indexed, selectorStates }
 }
 
 export function listField(read, field) {
@@ -801,7 +813,7 @@ async function renderList(node, namespace, selectValue) {
   const ownerTemplate = Boolean(node.ownerField && renderContext.listTemplate)
   const rowList = node.ownerField ? nextRowList() : undefined
   const id = rowList?.id ?? nextRenderId("l")
-  const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.values.map((item, index) => node.keyField === null ? index : item[node.keyField]), ...(node.ownerField ? { ownerField: node.ownerField } : {}), ...(node.selector.length ? { selector: node.selector } : {}), ...(node.indexed ? { indexed: true } : {}), ...(!node.selector.length && node.keyField !== null && node.items[reducerStateMarker] ? { reducer: true } : {}) }
+  const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.values.map((item, index) => node.keyField === null ? index : item[node.keyField]), ...(node.items[internalStateMarker] ? { static: true } : {}), ...(node.ownerField ? { ownerField: node.ownerField } : {}), ...(node.selector.length ? { selector: node.selector } : {}), ...(node.selectorStates.length ? { selectorStates: Object.fromEntries(node.selectorStates.map(([name, state]) => [name, state.id])) } : {}), ...(node.indexed ? { indexed: true } : {}), ...(!node.selector.length && node.keyField !== null && node.items[reducerStateMarker] ? { reducer: true } : {}) }
   if (ownerTemplate) {
     ownerRoot.descriptor.children ??= []
     ownerRoot.descriptor.children.push({ id, field: node.ownerField, key: node.keyField, ...(node.selector.length ? { selector: node.selector } : {}) })

package/framework/dev-state.js

@@ -2,9 +2,9 @@ const maxAge = 10000
 
 export function stateSchema(states) {
   const occurrences = new Map()
-  for (const { name } of states) if (typeof name === "string") occurrences.set(name, (occurrences.get(name) ?? 0) + 1)
-  return states.flatMap(({ id, name }) => {
-    return typeof id === "string" && occurrences.get(name) === 1 ? [[id, name]] : []
+  for (const { name, internal } of states) if (!internal && typeof name === "string") occurrences.set(name, (occurrences.get(name) ?? 0) + 1)
+  return states.flatMap(({ id, name, internal }) => {
+    return !internal && typeof id === "string" && occurrences.get(name) === 1 ? [[id, name]] : []
   })
 }