@kudzujs/core 0.7.6 → 0.7.8

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.6:** Zustand-shaped shared stores. Reduced `create(set => ...)` stores compile to persistent application-layout state and direct handler updates without shipping React or Zustand. See [release notes](./RELEASES.md#076---zustand-shaped-shared-stores).
+**0.7.8:** Static collection fast paths. Compiler-owned static filters reuse validated item metadata and detached row prototypes, making 1,000-row filtering match Vue and restoring filtered rows faster than React, Vue, and Svelte in the matched benchmark. See [release notes](./RELEASES.md#078---static-collection-fast-paths).
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
@@ -74,7 +74,7 @@ export default function Header() {
 }
 ```
 
-Kudzu rewrites supported React imports to its compile-time APIs before evaluating the module; neither the React package nor a compatibility runtime enters the deploy output. Named or aliased `useState`, `useReducer`, `useEffect`, `useRef`, `createContext`, and `useContext` imports compile to their canonical forms. Default and namespace imports may call those APIs as direct members such as `React.useState`, and default, namespace, or named `Fragment` also works. `memo(Component)` is erased to a same-file component. Inline `useCallback(function, literalDependencies)` is erased to its function, while inline synchronous `useMemo` callbacks may return one expression over primitive literals/direct local state or an analyzable `filter`, `map`, `flatMap`, and `Array.from` collection pipeline. Scalar expressions inline into existing bindings; collection pipelines lower to existing keyed-list selectors and preserve row identity. Both hooks require inert literal dependency arrays and complete captured-state dependencies; memo locals cannot be duplicated or captured by nested functions. React classes and side-effect or dynamic React imports remain unsupported. A static route using these forms still emits zero JavaScript.
+Kudzu rewrites supported React imports to its compile-time APIs before evaluating the module; neither the React package nor a compatibility runtime enters the deploy output. Named or aliased `useState`, `useReducer`, `useEffect`, `useRef`, `createContext`, and `useContext` imports compile to their canonical forms. Default and namespace imports may call those APIs as direct members such as `React.useState`, and default, namespace, or named `Fragment` also works. `memo(Component)` is erased to a same-file component. Inline `useCallback(function, literalDependencies)` is erased to its function, while inline synchronous `useMemo` callbacks may return one expression over primitive literals/direct local state or an analyzable `filter`, `map`, `flatMap`, and `Array.from` collection pipeline. Collection pipelines may start from local array state or a named relative import whose source is an exported JSON-safe `const` array; imported static collections may be filtered by direct local state listed in the dependency array. Scalar expressions inline into existing bindings; collection pipelines lower to existing keyed-list selectors and preserve row identity. Both hooks require inert literal dependency arrays and complete captured-state dependencies; memo locals cannot be duplicated or captured by nested functions. React classes and side-effect or dynamic React imports remain unsupported. A static route using these forms still emits zero JavaScript.
 
 Direct default or named `clsx` imports compile away for string/number literals, literal arrays, literal object conditions, and conditional expressions. Kudzu lowers those calls to ordinary class expressions, so reactive classes reuse existing bindings without shipping `clsx`; spreads, computed object keys, arbitrary calls, and indirect references remain unsupported.
 
@@ -418,7 +418,9 @@ 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 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. Nested item-local `&&` and ternary conditions patch bounded branches and mount or unmount their 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 row or page state, reruns only rows whose selected values changed; unrelated fields and reorder do not rerun it, while removal cleans it up. 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.
 
-Rendered collections may use one-use top-level aliases and analyzable pipelines over local array state. Inline arrow callbacks accept `(item)` or `(item, index)`; `filter()` supports pure synchronous expressions, `flatMap()` projects one direct array property, `Array.from()` accepts an optional pure mapper, and the final `map()` may use `key={item.field}` or positional `key={index}`. Field keys preserve the matching DOM node through filtering and reorder. Positional keys deliberately preserve the DOM node at each position while its item changes, matching React key semantics.
+Rendered collections may use one-use top-level aliases and analyzable pipelines over local array state or named relative imports of exported JSON-safe `const` arrays. Inline arrow callbacks accept `(item)` or `(item, index)`; `filter()` supports pure synchronous expressions and direct local-state reads, `flatMap()` projects one direct array property, `Array.from()` accepts an optional pure mapper, and the final `map()` may use `key={item.field}` or positional `key={index}`. Field keys preserve the matching DOM node through filtering and reorder. Positional keys deliberately preserve the DOM node at each position while its item changes, matching React key semantics.
+
+Compiler-owned static `filter` collections with structural keyed rows validate source items and key tokens once. Removed rows become detached prototypes; restoration clones fresh nodes and inserts only new runs, so retained keys keep identity while restored keys remount. In a 31-fresh-profile, 4x CPU-throttled Chrome benchmark over 1,000 alternating products, Kudzu measured 37.8 ms to visible rows, 8.4 ms to filter to 500, and 3.6 ms to restore 1,000. React measured 86.3/12.9/6.2 ms, Vue 54.1/8.4/4.3 ms, and Svelte 61.4/11.7/8.3 ms. This is a focused static-filter result, not a claim that rendering 100,000 or 1,000,000 DOM rows is appropriate; paginate or window large datasets so only the visible result set enters the document.
 
 A keyed row may contain multiple keyed maps over direct array properties of its item at any nesting depth. This supports recursively nested data populated after mount while preserving keyed DOM identity across updates and reorder:
 
@@ -463,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; 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}`. 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/defaults/rest, 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}`. 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/defaults/rest, children, 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.
 

package/RELEASES.md

@@ -1,5 +1,55 @@
 # Kudzu Releases
 
+## 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.
 
@@ -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. 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)) {
@@ -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]] : []
   })
 }
 

package/framework/list-runtime.js

@@ -47,6 +47,7 @@ function mountLists(root) {
     const templateRoot = __KUDZU_NESTED_LISTS__ ? nested.templateRoot : start.content.firstElementChild
     if (__KUDZU_LIST_ROW_HOOKS__) for (let index = 0; index < roots.length; index++) initializeGeneralRowHooks(descriptor, descriptor.keys[index], roots[index], nested?.owner)
     const parts = listItemPartPlan(templateRoot, descriptor.nested)
+    const staticRows = __KUDZU_STATIC_COLLECTIONS__ && descriptor.static && parts.directFill ? new Map() : undefined
     for (const root of roots) {
       if (__KUDZU_LIST_CONDITIONS__ && descriptor.conditions) {
         if (__KUDZU_NESTED_LISTS__ && descriptor.ownerField) itemPartPlans.set(root, parts)
@@ -56,11 +57,16 @@ function mountLists(root) {
     }
     if (__KUDZU_LIST_SEEDS__ && descriptor.seed && !browserState.has(descriptor.state)) browserState.set(descriptor.state, roots.map((root, index) => seedListItem(root, descriptor, index)))
     const items = browserState.get(descriptor.state)
+    const staticEntries = __KUDZU_STATIC_COLLECTIONS__ && descriptor.static && descriptor.key !== null && !descriptor.indexed && descriptor.selector?.every(operation => operation[0] === "filter") && parts.directFill
+      ? cacheStaticListEntries(descriptor, items)
+      : undefined
     const list = {
       start,
       descriptor,
       ...(__KUDZU_NESTED_LISTS__ ? { templateRoot, ...(nested.childPrototypes?.size ? { childPrototypes: nested.childPrototypes } : {}) } : {}),
       parts,
+      ...(__KUDZU_STATIC_COLLECTIONS__ && staticRows ? { staticRows } : {}),
+      ...(__KUDZU_STATIC_COLLECTIONS__ && staticEntries ? { staticEntries, staticPositions: staticEntries.positions } : {}),
       seedFields: __KUDZU_LIST_SEEDS__ && descriptor.seed && Object.keys(descriptor.seed),
       roots: new Map(roots.map((node, index) => [keyToken(descriptor.keys[index]), node])),
       ...(__KUDZU_LIST_STABLE_FAST_PATHS__ ? { orderedRoots: roots } : {}),
@@ -78,8 +84,14 @@ function mountLists(root) {
       ownedLists.set(list.owner, lists)
       listRegistrations.set(start, { list, owner: list.owner })
     } else {
-      register(listTargets, descriptor.state, list)
-      listRegistrations.set(start, { state: descriptor.state, list })
+      if (__KUDZU_COLLECTION_SELECTORS__ && descriptor.selectorStates) {
+        const states = [...new Set([descriptor.state, ...Object.values(descriptor.selectorStates)])]
+        for (const state of states) register(listTargets, state, list)
+        listRegistrations.set(start, { states, list })
+      } else {
+        register(listTargets, descriptor.state, list)
+        listRegistrations.set(start, { state: descriptor.state, list })
+      }
     }
     updateList(list)
   }
@@ -97,9 +109,17 @@ function unregisterList(start) {
       if (lists?.get(registration.list.descriptor.id) === registration.list) lists.delete(registration.list.descriptor.id)
       if (!lists?.size) ownedLists.delete(registration.owner)
     } else {
-      const lists = listTargets.get(registration.state)
-      lists?.delete(registration.list)
-      if (!lists?.size) listTargets.delete(registration.state)
+      if (__KUDZU_COLLECTION_SELECTORS__ && registration.states) {
+        for (const state of registration.states) {
+          const lists = listTargets.get(state)
+          lists?.delete(registration.list)
+          if (!lists?.size) listTargets.delete(state)
+        }
+      } else {
+        const lists = listTargets.get(registration.state)
+        lists?.delete(registration.list)
+        if (!lists?.size) listTargets.delete(registration.state)
+      }
     }
     if (__KUDZU_LIST_ROW_HOOKS__ && registration.list.descriptor.rowStates) for (const node of registration.list.roots.values()) deleteRowStates(registration.list.descriptor, ownershipPaths.get(node))
   }
@@ -112,12 +132,13 @@ function updateList(list) {
     ? listItems.get(list.owner)?.[list.descriptor.ownerField]
     : browserState.get(list.descriptor.state)
   if (__KUDZU_NESTED_LISTS__ && list.descriptor.ownerField && items == null) items = []
-  if (__KUDZU_COLLECTION_SELECTORS__) items = selectCollection(items, list.descriptor.selector)
+  if (__KUDZU_COLLECTION_SELECTORS__) items = selectCollection(items, list.descriptor.selector, name => browserState.get(list.descriptor.selectorStates?.[name]))
   if (!Array.isArray(items)) throw new Error(list.descriptor.ownerField ? `Nested keyed list property "${list.descriptor.ownerField}" must remain an array` : "Keyed list state must remain an array")
   if (__KUDZU_NESTED_LISTS__ && (list.descriptor.children || list.descriptor.ownerField) && !list.descriptor.indexed && !list.descriptor.selector && list.descriptor.key !== null && list.items && updateNestedList(list, items)) return
   if (__KUDZU_NESTED_LISTS__ && list.descriptor.children) validateChildLists(items, list.descriptor.children)
   if (list.descriptor.reducer && !list.descriptor.selector && list.descriptor.key !== null && list.items && updateReducerList(list, items)) return
   if (__KUDZU_LIST_STABLE_FAST_PATHS__ && list.descriptor.key !== null && !list.descriptor.indexed && !list.descriptor.selector && !list.descriptor.reducer && !list.descriptor.children && !list.descriptor.ownerField && list.items && updateStableList(list, items)) return
+  if (__KUDZU_STATIC_COLLECTIONS__ && list.staticEntries && updateStaticFilterList(list, items)) return
   const entries = []
   const keys = new Set()
   const seen = new Set()
@@ -174,14 +195,18 @@ function updateList(list) {
   for (const { item, index, key, token, value } of entries) {
     let node = list.roots.get(token)
     if (!node) {
-      node = (__KUDZU_NESTED_LISTS__ ? list.templateRoot : list.start.content.firstElementChild)?.cloneNode(true)
-      if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
+      const staticRoot = __KUDZU_STATIC_COLLECTIONS__ && list.staticRows?.get(token)?.cloneNode(true)
+      node = staticRoot ?? (__KUDZU_NESTED_LISTS__ ? list.templateRoot : list.start.content.firstElementChild)?.cloneNode(true)
+      if (!staticRoot && node?.dataset.kListRoot !== list.descriptor.id) node = undefined
       if (!node) throw new Error("Keyed list template has no root element")
       node.removeAttribute("data-k-list-root")
       if (__KUDZU_NESTED_LISTS__ && list.childPrototypes) childPrototypes.set(node, list.childPrototypes)
       if (__KUDZU_LIST_ROW_HOOKS__) initializeGeneralRowHooks(list.descriptor, key, node, list.owner)
-      mapListItemParts(list.parts, node, list.descriptor.nested)
-      fillListItem(node, item, list.descriptor.nested, index)
+      if (staticRoot) listItems.set(node, item)
+      else if (list.parts.directFill) {
+        listItems.set(node, item)
+        fillStructuralListParts(list.parts, node, item)
+      } else fillListItem(node, item, list.descriptor.nested, index, mapListItemParts(list.parts, node, list.descriptor.nested))
       additions.append(node)
       added = true
     } else if ((referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value) || list.descriptor.indexed || list.descriptor.key === null) {
@@ -199,20 +224,38 @@ function updateList(list) {
     } else node.remove()
     if (__KUDZU_LIST_ROW_HOOKS__ && list.descriptor.rowStates) deleteRowStates(list.descriptor, ownershipPaths.get(node))
   }
+  let ordered = false
   if (added) {
-    if (__KUDZU_LIST_MOUNTS__ && list.descriptor.mount) {
-      const addedNodes = [...additions.childNodes]
-      parent.insertBefore(additions, list.boundary)
-      for (const node of addedNodes) mountDom(node)
+    const addedNodes = __KUDZU_LIST_MOUNTS__ && list.descriptor.mount ? [...additions.childNodes] : undefined
+    let seenAddition = false
+    let interleaved = false
+    for (const [, node] of next) {
+      if (node.parentNode === additions) seenAddition = true
+      else if (seenAddition) {
+        interleaved = true
+        break
+      }
+    }
+    if (interleaved) {
+      const run = parent.ownerDocument.createDocumentFragment()
+      for (const [, node] of next) {
+        if (node.parentNode === additions) run.append(node)
+        else if (run.firstChild) parent.insertBefore(run, node)
+      }
+      if (run.firstChild) parent.insertBefore(run, list.boundary)
+      ordered = true
     } else parent.insertBefore(additions, list.boundary)
+    if (addedNodes) for (const node of addedNodes) mountDom(node)
     list.container ??= parent
   }
   let anchor = list.boundary
   let misplaced = 0
-  for (let index = next.length - 1; index >= 0; index--) {
-    const node = next[index][1]
-    if (node.nextSibling !== anchor) misplaced++
-    anchor = node
+  if (!ordered) {
+    for (let index = next.length - 1; index >= 0; index--) {
+      const node = next[index][1]
+      if (node.nextSibling !== anchor) misplaced++
+      anchor = node
+    }
   }
   if (misplaced > next.length / 2) {
     const reordered = parent.ownerDocument.createDocumentFragment()
@@ -232,6 +275,68 @@ function updateList(list) {
   list.items = items
 }
 
+function updateStaticFilterList(list, items) {
+  const entries = new Array(items.length)
+  for (let index = 0; index < items.length; index++) {
+    const entry = list.staticEntries.get(items[index])
+    if (!entry || !list.roots.has(entry.token) && !list.staticRows.has(entry.token)) return false
+    entries[index] = entry
+  }
+  let selectedIndex = 0
+  for (const [token, node] of list.roots) {
+    const position = list.staticPositions.get(token)
+    while (entries[selectedIndex]?.position < position) selectedIndex++
+    if (entries[selectedIndex]?.token === token) {
+      selectedIndex++
+      continue
+    }
+    list.staticRows.set(token, node)
+    node.remove()
+  }
+  const parent = list.container ?? list.start.parentNode
+  const run = parent.ownerDocument.createDocumentFragment()
+  const next = new Array(entries.length)
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index]
+    let node = list.roots.get(entry.token)
+    if (!node) {
+      node = list.staticRows.get(entry.token).cloneNode(true)
+      listItems.set(node, entry.item)
+      run.append(node)
+    } else if (run.firstChild) parent.insertBefore(run, node)
+    next[index] = [entry.token, node]
+  }
+  if (run.firstChild) parent.insertBefore(run, list.boundary)
+  list.roots = new Map(next)
+  if (__KUDZU_LIST_STABLE_FAST_PATHS__) list.orderedRoots = next.map(([, node]) => node)
+  list.values.clear()
+  list.items = items
+  list.container ??= parent
+  return true
+}
+
+function cacheStaticListEntries(descriptor, items) {
+  if (!Array.isArray(items)) return undefined
+  const entries = new WeakMap()
+  const positions = new Map()
+  const keys = new Set()
+  const seen = new Set()
+  for (let position = 0; position < items.length; position++) {
+    const item = items[position]
+    assertListItem(item)
+    assertListValue(item, seen, true)
+    const key = item[descriptor.key]
+    if (!validListKey(key)) throw new Error(`Keyed list key "${descriptor.key}" must be a string or finite number`)
+    const token = keyToken(key)
+    if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
+    keys.add(token)
+    entries.set(item, { item, key, token, value: item, position })
+    positions.set(token, position)
+  }
+  entries.positions = positions
+  return entries
+}
+
 /* stable-list-fast-path */
 function updateStableList(list, items) {
   const previous = list.items

package/package.json

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