@kudzujs/core 0.8.1 → 0.8.2

package/RELEASES.md

@@ -1,5 +1,30 @@
 # Kudzu Releases
 
+## 0.8.2 - Calculated keyed collections
+
+Kudzu 0.8.2 lets one direct array field from a synchronous relative calculation result drive an intrinsic keyed list, preserving static HTML and existing DOM ownership while improving list and navigation hot paths.
+
+### New in 0.8.2
+
+- A top-level `const result = calculate(state)` may feed `result.items.map(...)` when the relative synchronous helper returns a JSON-safe array field.
+- Route-specific evaluator ESM refreshes a compiler-owned array anchor after source-state commits; the existing keyed reconciler retains keys, current handlers, and SVG namespaces.
+- Initial structural rows hydrate list bookkeeping without repeating DOM writes, retained direct attributes skip redundant DOM reads, and stable-list fallback avoids duplicate validation.
+- Immutable local filter sources with unused ordinary `useState` setters use the existing static-filter restoration path while indirect custom-hook and reducer mutation paths remain dynamic.
+- Required route modules emit `modulepreload` hints, and navigation prefetch resolves validated destination capabilities before commit while preserving complete-document fallback and cleanup ordering.
+- Navigation prefetch safely ignores focus and pointer targets outside anchors.
+- Calculated collection fixtures verify insert, reorder, removal, retained identity, latest handlers, scalar bindings, SVG namespace, and zero JavaScript on unaffected static routes.
+- The complete suite passes 133/133 tests, and the FIRE migration retains all chart nodes and acceptance behavior.
+
+### Boundary
+
+The calculation must be one top-level immutable result from a synchronous relative TypeScript function, and the consumed field must remain a JSON-safe array. Indirect result aliases, dynamic fields, nested calculated SVG lists, package calculations, and asynchronous helpers remain unsupported. Static-filter specialization applies only when an ordinary local setter is provably unused; lifecycle-bearing and indirectly mutable collections retain the general path.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.2
+```
+
 ## 0.8.1 - Custom-hook reset actions
 
 Kudzu 0.8.1 compiles direct multi-state reset callbacks returned by relative custom hooks into one existing behavior command, keeping conventional hook ownership without adding a callback runtime.

package/framework/README.md

@@ -4,7 +4,7 @@ Kudzu specializes ordinary common React-shaped TSX so migrations need minimal so
 
 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`, direct intrinsic `forwardRef`, top-level `const` identifiers initialized by `useId()`, and default, namespace, or named `Fragment`. A named or default zero-argument custom hook imported from a relative TypeScript module may return direct shorthand state/setter pairs and callbacks that capture those states, including a callback that resets multiple states to direct primitive literals; callers use one top-level `const` object destructuring without aliases, defaults, or rest. Kudzu's JSX declarations accept ReactNode-shaped component returns and contextually type common intrinsic DOM events, so strict React component props do not need migration-only `unknown` or explicit event annotations. `forwardRef()` accepts one inline synchronous `(props, ref)` function and requires the object ref exactly once on its direct intrinsic root; the compiler removes `ref` from props/rest and erases the wrapper. `useId()` becomes a deterministic build-time HTML ID and emits no browser capability; keyed rows reject it because cloned row templates cannot safely duplicate HTML IDs. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array, including type-only `as const` and `satisfies` wrappers, 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.
 
-Compilation begins from page entries and follows relative runtime imports, re-exports, and validated Worker references; unreachable TypeScript migration files are not transformed. Direct maps over imported immutable JSON-safe arrays fold to literals for zero-JavaScript static rows. Synchronous relative calculation functions may return objects whose direct static fields feed reactive JSX bindings; build rendering uses current signal values and route-specific binding ESM reevaluates the same helper after state commits. Package imports have a separate narrow boundary: direct references inside intrinsic JSX event callbacks are erased from build modules and bundled into route handler ESM, while render-time, effect, helper-indirect, and mixed package use fails.
+Compilation begins from page entries and follows relative runtime imports, re-exports, and validated Worker references; unreachable TypeScript migration files are not transformed. Direct maps over imported immutable JSON-safe arrays fold to literals for zero-JavaScript static rows. Synchronous relative calculation functions may return objects whose direct static fields feed reactive JSX bindings; build rendering uses current signal values and route-specific binding ESM reevaluates the same helper after state commits. One direct array field may instead feed a keyed intrinsic map: its evaluator refreshes a compiler-owned array anchor before the existing list reconciler runs, preserving keyed DOM and SVG identity without a calculation runtime. That field must remain a JSON-safe array after every source-state commit. Package imports have a separate narrow boundary: direct references inside intrinsic JSX event callbacks are erased from build modules and bundled into route handler ESM, while render-time, effect, helper-indirect, and mixed package use fails.
 
 A named or aliased `Link` import from `react-router-dom` may render directly with one static root-relative `to` plus native anchor props. The compiler prefixes the configured `base`, changes the element to `<a href>`, and erases the import, so native navigation remains the default and configured navigation groups see an ordinary eligible anchor. Dynamic or relative destinations, `NavLink`, router-only props, spreads, default/namespace imports, and non-JSX uses fail with source diagnostics. No React Router package code or router runtime is emitted.
 

package/framework/binding-runtime.js

@@ -268,7 +268,7 @@ function register(targets, id, entry) {
   targets.set(id, entries)
 }
 
-async function loadEvaluator(descriptor) {
+export async function loadEvaluator(descriptor) {
   let modulePromise = imports.get(descriptor.module)
   if (!modulePromise) {
     modulePromise = import(descriptor.module)

package/framework/build.mjs

@@ -209,13 +209,14 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasListEvents = plans.some(plan => plan.lists.some(list => list.events))
   const hasListExpressions = plans.some(plan => plan.lists.some(list => list.expressions))
   const hasListExpressionAttributes = plans.some(plan => plan.lists.some(list => list.expressionAttributes))
-  const hasListSeeds = plans.some(plan => plan.lists.some(list => list.seed))
+  const hasListSeeds = plans.some(plan => plan.lists.some(list => list.seed || list.valueSeed))
   const hasListEffects = plans.some(plan => plan.lists.some(list => list.effects))
   const hasListRowHooks = plans.some(plan => plan.lists.some(list => list.rowStates?.length || list.rowRefs?.length))
   const hasListRowRefs = plans.some(plan => plan.lists.some(list => list.rowRefs?.length))
   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 hasCalculatedCollections = plans.some(plan => plan.lists.some(list => list.source))
   const hasDerivedEffectDependencies = plans.some(plan => plan.effects.some(effect => effect.dependencyExpressions?.length))
   const hasStaticCollections = plans.some(plan => plan.lists.some(list => list.static))
   const hasListIndexes = plans.some(plan => plan.lists.some(list => list.indexed))
@@ -237,7 +238,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   for (const entry of pageEntries) {
     const routeDirectory = join(outputDirectory, entry.route)
     await mkdir(routeDirectory, { recursive: true })
-    const html = entry.html.replace(runtimePlaceholder, escapeAttribute(assetPath(base, `assets/${runtimeName(entry.usesDependencyRuntime)}`)))
+    const html = preloadModules(entry.html.replace(runtimePlaceholder, escapeAttribute(assetPath(base, `assets/${runtimeName(entry.usesDependencyRuntime)}`))))
     await writeFile(join(routeDirectory, "index.html"), html)
   }
   if (navigationRoutes.length || behaviorCount && (hasSharedRuntime || regularBehaviorCount)) {
@@ -284,6 +285,9 @@ export async function build({ quiet = false, minify = true } = {}) {
     if (hasCollectionSelectors && !hasDerivedEffectDependencies) await writeJavaScript(join(assetsDirectory, "kudzu-collection-selector.js"), await readFile(new URL("./collection-selector.js", import.meta.url), "utf8"), minify)
     let listRuntime = (await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"))
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
+    listRuntime = hasCalculatedCollections
+      ? listRuntime.replace('"./binding-runtime.js"', '"./kudzu-binding.js"')
+      : listRuntime.replace(/^const loadListEvaluator[^\n]+\n/m, "")
     listRuntime = hasCollectionSelectors
       ? listRuntime.replace('"./collection-selector.js"', '"./kudzu-collection-selector.js"')
       : listRuntime.replace(/^import \{ selectCollection \}[^\n]+\n/m, "")
@@ -297,8 +301,8 @@ export async function build({ quiet = false, minify = true } = {}) {
       .replace("function addListRoot(list, { item, index = list.roots.size, key, token, value })", "function addListRoot(list, { item, key, token, value })")
       .replace("fillListParts(root, listItemParts(root), listItems.get(owner), 0, __KUDZU_LIST_INDEXES__ ? listIndexes.get(owner) ?? 0 : 0)", "fillListParts(root, listItemParts(root), listItems.get(owner), 0)")
       .replace("function fillListItem(root, item, nested = false, index = 0)", "function fillListItem(root, item, nested = false)")
-      .replace("fillListParts(root, parts, item, revision, index)", "fillListParts(root, parts, item, revision)")
-      .replace("function fillListParts(root, parts, item, revision, index = 0)", "function fillListParts(root, parts, item, revision)")
+      .replace("fillListParts(root, parts, item, revision, index, previous)", "fillListParts(root, parts, item, revision, previous)")
+      .replace("function fillListParts(root, parts, item, revision, index = 0, previous)", "function fillListParts(root, parts, item, revision, previous)")
       .replaceAll('value?.type === "list-item" ? serializeItem(item) : value?.type === "list-index" ? index : value', 'value?.type === "list-item" ? serializeItem(item) : value')
       .replaceAll("evaluate(descriptor, item, index)", "evaluate(descriptor, item)")
       .replaceAll("evaluate({ module, handler }, item, index)", "evaluate({ module, handler }, item)")
@@ -459,6 +463,13 @@ export async function build({ quiet = false, minify = true } = {}) {
   if (!quiet) console.log(`Built ${plans.length} page(s), ${behaviorCount} interactive page(s) into dist/`)
 }
 
+function preloadModules(html) {
+  const scripts = [...html.matchAll(/<script type="module"[^>]* src="([^"]+)"[^>]*><\/script>/g)]
+  if (!scripts.length) return html
+  const links = [...new Set(scripts.map(match => match[1]))].map(href => `<link rel="modulepreload" href="${href}">`).join("")
+  return html.replace(scripts[0][0], `${links}${scripts[0][0]}`)
+}
+
 function specializeEvents(source, events) {
   return source.replace(/const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`)
 }
@@ -492,10 +503,11 @@ async function mountInitial() {
 }
 `, "")
     .replace("  await ready\n", "")
-    .replace("    const capabilities = await loadCapabilities(parsed)\n", "    await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n")
+    .replace("    const { incoming, parsed, capabilities } = documentResult\n", "    const { incoming, parsed } = documentResult\n")
     .replace("    await routeDispose()\n    if (current !== revision) return\n", "")
     .replace("    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)\n", "    commit(incoming, parsed.nodes)\n")
     .replace("    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "")
+    .replace("  return { incoming, parsed, capabilities: await loadCapabilities(parsed), record }\n", "  await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n  return { incoming, parsed, record }\n")
     .replace(`
 async function loadCapabilities(parsed) {
   const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
@@ -1508,7 +1520,7 @@ async function writeBundledJavaScript(file, source, minify, define) {
     stdin: { contents: source, resolveDir: dirname(file), sourcefile: file },
     bundle: true,
     write: false,
-    external: ["./kudzu.js", "./kudzu-serialization.js", "./kudzu-style.js"],
+    external: ["./kudzu.js", "./kudzu-binding.js", "./kudzu-serialization.js", "./kudzu-style.js"],
     define,
     format: "esm",
     target: "es2022",
@@ -2655,6 +2667,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       } catch {}
     }
     const settersByFunction = new Map()
+    const localStateSettersByFunction = new Map()
     const reducersByFunction = new Map()
     const zustandStores = new Map()
     const resolvedZustandStore = entry => {
@@ -2813,6 +2826,9 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
               const setters = settersByFunction.get(owner) ?? new Map()
               setters.set(setterElement.name.text, stateElement.name.text)
               settersByFunction.set(owner, setters)
+              const localSetters = localStateSettersByFunction.get(owner) ?? new Set()
+              localSetters.add(setterElement.name.text)
+              localStateSettersByFunction.set(owner, localSetters)
             }
           }
         }
@@ -3327,7 +3343,23 @@ 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, new Set(), importedCollections, factory, context, importedCollectionTransforms)
+        const owner = nearestFunction(node)
+        const setters = settersForNode(node, settersByFunction)
+        const staticCollection = state => [...(localStateSettersByFunction.get(owner) ?? [])].some(setter => setters.get(setter) === state && !referenceIdentifiers(owner.body, setter).length)
+        const calculatedCollection = expression => {
+          const value = unwrapExpression(expression)
+          if (!ts.isPropertyAccessExpression(value) || !ts.isIdentifier(value.expression)) return undefined
+          const entries = jsxLocalDeclarations.get(nearestFunction(node))?.get(value.expression.text)
+          if (!entries?.length) return undefined
+          const initializer = entries.length === 1 ? unwrapExpression(entries[0].initializer) : undefined
+          if (!initializer || !ts.isCallExpression(initializer) || !ts.isIdentifier(initializer.expression) || !importBindings.has(initializer.expression.text)) return undefined
+          if (entries[0].node.parent?.parent?.parent !== nearestFunction(entries[0].node)?.body) fail(value.expression, `Calculated collection result "${value.expression.text}" must be one top-level immutable local`)
+          validateImportedCalculation(initializer, value.name.text)
+          const expanded = resolveReactiveJsxExpression(value, nearestFunction(node), setters)
+          if (expanded === value || !referencedStateNames(expanded, setters).size) fail(value, "Calculated collection fields must directly depend on local state")
+          return expanded
+        }
+        const parts = listLocalUses.get(node) ?? keyedListParts(node.expression, setters, jsxLocalDeclarations.get(owner), fail, new Set(), importedCollections, factory, context, importedCollectionTransforms, calculatedCollection, staticCollection)
         if (parts) {
           for (const declaration of parts.aliasDeclarations ?? []) listLocalDeclarations.add(declaration)
           rawRenderedLists.push({ node, parts })
@@ -3731,15 +3763,21 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         if (listParts) {
           usesBehavior = true
           usesList = true
+          let listSource = listParts.state
+          if (listParts.calculation) {
+            usesBinding = true
+            listSource = compileReactiveBinding(listParts.calculation, settersForNode(node, settersByFunction), factory, context, reactiveBindings, handlerUrl, importBindings, clientImports)
+          }
           const arguments_ = [
-            listParts.state,
+            listSource,
             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)]))))
+          if (listParts.selectorStates?.size || listParts.static) arguments_.push(factory.createArrayLiteralExpression([...(listParts.selectorStates ?? [])].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
+          if (listParts.static) arguments_.push(factory.createTrue())
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, arguments_))
         }
         const conditional = conditionalParts(node.expression)
@@ -3932,12 +3970,12 @@ function containsRenderControl(root, knownLocals) {
   return found
 }
 
-function keyedListParts(expression, setters, declarations, fail, aliases = new Set(), importedCollections = new Set(), factory = ts.factory, context, importedCollectionTransforms = new Map()) {
+function keyedListParts(expression, setters, declarations, fail, aliases = new Set(), importedCollections = new Set(), factory = ts.factory, context, importedCollectionTransforms = new Map(), calculatedCollection, staticCollection) {
   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, importedCollections, new Set(setters.values()), importedCollectionTransforms, factory, context)
-  if (!collection?.state) return undefined
+  const collection = renderedCollectionSource(directFrom ? value.arguments[0] : value.expression.expression, setters, declarations, fail, aliases, importedCollections, new Set(setters.values()), importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
+  if (!collection?.state && !collection?.calculation) return undefined
   if (directFrom) collection.selector.push(["from", undefined])
   let callback = directFrom ? value.arguments[1] : value.arguments[0]
   const parameters = collectionParameters(callback, "Keyed list map", fail)
@@ -3962,7 +4000,7 @@ function keyedListParts(expression, setters, declarations, fail, aliases = new S
   const field = keyExpression && directProperty(keyExpression, parameters.item)
   const positional = Boolean(keyExpression && parameters.index && ts.isIdentifier(unwrapExpression(keyExpression)) && unwrapExpression(keyExpression).text === parameters.index)
   if (!field && !positional) fail(key ?? root, `Keyed list root must have key={${parameters.item}.<field>} or key={${parameters.index ?? "index"}}`)
-  return { ...collection, callback, root, item: parameters.item, index: parameters.index, indexed: Boolean(parameters.index), keyField: positional ? null : field }
+  return { ...collection, static: collection.static && (!collection.localStatic || collection.selector.length > 0), callback, root, item: parameters.item, index: parameters.index, indexed: Boolean(parameters.index), keyField: positional ? null : field }
 }
 
 function nestedKeyedListParts(expression, parentItem, fail) {
@@ -3983,20 +4021,27 @@ 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, importedCollections = new Set(), stateNames = new Set(), importedCollectionTransforms = new Map(), factory = ts.factory, context) {
+function renderedCollectionSource(expression, setters, declarations, fail, aliases, importedCollections = new Set(), stateNames = new Set(), importedCollectionTransforms = new Map(), factory = ts.factory, context, calculatedCollection, staticCollection) {
   const value = unwrapExpression(expression)
   if (ts.isIdentifier(value)) {
-    if ([...setters.values()].includes(value.text)) return { state: value, selector: [], selectorStates: new Set() }
+    if ([...setters.values()].includes(value.text)) {
+      const localStatic = staticCollection?.(value.text)
+      return { state: value, static: localStatic, localStatic, 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`)
     aliases.add(value.text)
-    const source = renderedCollectionSource(entries[0].initializer, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+    const source = renderedCollectionSource(entries[0].initializer, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
     aliases.delete(value.text)
     return source && { ...source, aliasDeclarations: [...(source.aliasDeclarations ?? []), entries[0].node], aliasUses: [...(source.aliasUses ?? []), value] }
   }
-  if (ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression)) return { state: undefined, ownerField: value.name.text, selector: [], parentItem: value.expression.text }
+  if (ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression)) {
+    const calculation = calculatedCollection?.(value)
+    if (calculation) return { calculation, selector: [], selectorStates: new Set() }
+    return { state: undefined, ownerField: value.name.text, selector: [], parentItem: value.expression.text }
+  }
   if (ts.isCallExpression(value) && ts.isIdentifier(value.expression) && importedCollectionTransforms.has(value.expression.text)) {
     const transform = importedCollectionTransforms.get(value.expression.text)
     const parameter = transform.parameters[0]
@@ -4007,7 +4052,7 @@ function renderedCollectionSource(expression, setters, declarations, fail, alias
     if (!returned) fail(value, `Imported collection transform "${value.expression.text}" must contain only one returned collection expression`)
     const transformSource = renderedCollectionSource(returned, new Map([[parameter.name.text, parameter.name.text]]), undefined, fail, new Set(), new Set(), new Set([parameter.name.text]))
     if (!transformSource?.state || transformSource.state.text !== parameter.name.text || transformSource.selectorStates.size) fail(value, `Imported collection transform "${value.expression.text}" must return a supported pure pipeline rooted only in its parameter`)
-    const source = renderedCollectionSource(value.arguments[0], setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+    const source = renderedCollectionSource(value.arguments[0], setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
     if (!source) fail(value.arguments[0], `Imported collection transform "${value.expression.text}" requires a supported collection argument`)
     return { ...source, selector: [...source.selector, ...transformSource.selector] }
   }
@@ -4015,7 +4060,7 @@ 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, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
       if (!source) return undefined
       const parameters = collectionParameters(value.arguments[0], "Rendered collection filter()", fail)
       const selectorStates = new Set(source.selectorStates)
@@ -4023,7 +4068,7 @@ function renderedCollectionSource(expression, setters, declarations, fail, alias
     }
     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, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
       if (!source) return undefined
       const parameters = collectionParameters(value.arguments[0], "Rendered collection flatMap()", fail)
       const field = directProperty(value.arguments[0].body, parameters.item)
@@ -4033,7 +4078,7 @@ function renderedCollectionSource(expression, setters, declarations, fail, alias
     }
     if (method === "slice") {
       if (value.arguments.length < 1 || value.arguments.length > 2) fail(value, "Rendered collection slice() requires a start and optional end")
-      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
       if (!source) return undefined
       const selectorStates = new Set(source.selectorStates)
       const start = collectionExpression(value.arguments[0], {}, fail, stateNames, selectorStates)
@@ -4042,7 +4087,7 @@ function renderedCollectionSource(expression, setters, declarations, fail, alias
     }
     if (method === "toSorted") {
       if (value.arguments.length !== 1) fail(value, "Rendered collection toSorted() requires one inline comparator")
-      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+      const source = renderedCollectionSource(value.expression.expression, setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
       if (!source) return undefined
       const comparator = value.arguments[0]
       const parameters = collectionParameters(comparator, "Rendered collection toSorted()", fail)
@@ -4055,7 +4100,7 @@ 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, importedCollections, stateNames, importedCollectionTransforms, factory, context)
+    const source = renderedCollectionSource(value.arguments[0], setters, declarations, fail, aliases, importedCollections, stateNames, importedCollectionTransforms, factory, context, calculatedCollection, staticCollection)
     if (!source) return undefined
     let mapper
     if (value.arguments[1]) {

package/framework/core.d.ts

@@ -36,7 +36,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, selectorStates?: Array<[string, unknown]>): 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]>, staticCollection?: boolean): unknown
 export function listField(read: () => unknown, field: string): unknown
 export function listExpression(read: () => unknown, module: string, handler: string): unknown
 export function listItem(): unknown

package/framework/core.mjs

@@ -291,7 +291,9 @@ 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, selectorStates = []) {
+export function list(items, keyField, render, ownerField, selector = [], indexed = false, selectorStates = [], staticCollection = false) {
+  const source = items?.[bindingMarker] ? bindingDescriptor(items) : undefined
+  if (source) items = createInternalState(items.value)
   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)
@@ -315,7 +317,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, selectorStates }
+  return { [listMarker]: true, items, values, keyField, render, ownerField, selector, indexed, static: staticCollection, selectorStates, source }
 }
 
 export function listField(read, field) {
@@ -870,7 +872,8 @@ 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]), ...(namespace === "svg" ? { svg: true } : {}), ...(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 } : {}) }
+  const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.values.map((item, index) => node.keyField === null ? index : item[node.keyField]), ...(namespace === "svg" ? { svg: true } : {}), ...(node.static || node.items[internalStateMarker] && !node.source ? { static: true } : {}), ...(node.source ? { source: node.source } : {}), ...(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 (node.source) renderContext.hasBindings = true
   if (ownerTemplate) {
     ownerRoot.descriptor.children ??= []
     ownerRoot.descriptor.children.push({ id, field: node.ownerField, key: node.keyField, ...(node.selector.length ? { selector: node.selector } : {}) })
@@ -919,8 +922,10 @@ async function renderList(node, namespace, selectValue) {
       descriptor.mount = true
     }
     if (descriptor.rowStates && !descriptor.effects && !descriptor.nested && !template.includes("data-k-text")) descriptor.fastRelease = true
-    const seed = node.ownerField || node.selector.length || node.keyField === null ? undefined : listSeed(node.values, renderContext.listFields)
+    const valueSeed = node.ownerField || node.keyField === null ? undefined : listSeed(node.values, renderContext.listFields)
+    const seed = node.selector.length ? undefined : valueSeed
     if (seed) descriptor.seed = seed
+    else if (valueSeed) descriptor.valueSeed = valueSeed
     let current = ""
     renderContext.listTemplate = false
     renderContext.listInitialMarkers = Boolean(descriptor.conditions)

package/framework/list-runtime.js

@@ -1,8 +1,10 @@
 import { browserState, mountDom, notifyListItem, registerCommitter, registerMountHook, registerUnmountHook, releaseState, unmountDom } from "./shared-runtime.js"
 import { selectCollection } from "./collection-selector.js"
+const loadListEvaluator = descriptor => import("./binding-runtime.js").then(module => module.loadEvaluator(descriptor))
 
 const listTargets = new Map()
 const listRegistrations = new WeakMap()
+const listLoads = new WeakMap()
 const mountedLists = new WeakSet()
 const imports = __KUDZU_LIST_ASYNC_PARTS__ ? new Map() : undefined
 const revisions = __KUDZU_LIST_ASYNC_PARTS__ ? new WeakMap() : undefined
@@ -68,7 +70,8 @@ function mountLists(root) {
       parts,
       ...(__KUDZU_STATIC_COLLECTIONS__ && staticRows ? { staticRows } : {}),
       ...(__KUDZU_STATIC_COLLECTIONS__ && staticEntries ? { staticEntries, staticPositions: staticEntries.positions } : {}),
-      seedFields: __KUDZU_LIST_SEEDS__ && descriptor.seed && Object.keys(descriptor.seed),
+      seedFields: __KUDZU_LIST_SEEDS__ && (descriptor.seed || descriptor.valueSeed) && Object.keys(descriptor.seed ?? descriptor.valueSeed),
+      valueSeed: __KUDZU_LIST_SEEDS__ && (descriptor.seed ?? descriptor.valueSeed),
       roots: new Map(roots.map((node, index) => [keyToken(descriptor.keys[index]), node])),
       ...(__KUDZU_LIST_STABLE_FAST_PATHS__ ? { orderedRoots: roots } : {}),
       values: new Map(),
@@ -84,6 +87,17 @@ function mountLists(root) {
       lists.set(descriptor.id, list)
       ownedLists.set(list.owner, lists)
       listRegistrations.set(start, { list, owner: list.owner })
+    } else if (descriptor.source) {
+      const load = {}
+      listLoads.set(start, load)
+      loadListEvaluator(descriptor.source).then(evaluator => {
+        if (listLoads.get(start) !== load || !start.isConnected) return
+        list.sourceEvaluator = evaluator
+        const states = [...new Set([...evaluator.stateIds, ...(__KUDZU_COLLECTION_SELECTORS__ ? Object.values(descriptor.selectorStates ?? {}) : [])])]
+        for (const state of states) register(listTargets, state, list)
+        listRegistrations.set(start, { states, list })
+        updateList(list)
+      }).catch(error => console.error(error))
     } else {
       if (__KUDZU_COLLECTION_SELECTORS__ && descriptor.selectorStates) {
         const states = [...new Set([descriptor.state, ...Object.values(descriptor.selectorStates)])]
@@ -94,7 +108,7 @@ function mountLists(root) {
         listRegistrations.set(start, { state: descriptor.state, list })
       }
     }
-    updateList(list)
+    if (!descriptor.source) updateList(list)
   }
 }
 
@@ -103,6 +117,7 @@ function unmountLists(root) {
 }
 
 function unregisterList(start) {
+  listLoads.delete(start)
   const registration = listRegistrations.get(start)
   if (registration) {
     if (__KUDZU_NESTED_LISTS__ && registration.owner) {
@@ -110,7 +125,7 @@ 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 {
-      if (__KUDZU_COLLECTION_SELECTORS__ && registration.states) {
+      if ((__KUDZU_COLLECTION_SELECTORS__ || registration.list.descriptor.source) && registration.states) {
         for (const state of registration.states) {
           const lists = listTargets.get(state)
           lists?.delete(registration.list)
@@ -129,6 +144,7 @@ function unregisterList(start) {
 }
 
 function updateList(list) {
+  if (list.sourceEvaluator) browserState.set(list.descriptor.state, list.sourceEvaluator.read())
   let items = __KUDZU_NESTED_LISTS__ && list.descriptor.ownerField
     ? listItems.get(list.owner)?.[list.descriptor.ownerField]
     : browserState.get(list.descriptor.state)
@@ -148,13 +164,26 @@ function updateList(list) {
     const key = list.descriptor.key === null ? index : item?.[list.descriptor.key]
     if (!validListKey(key)) throw new Error(`Keyed list key "${list.descriptor.key}" must be a string or finite number`)
     assertListItem(item)
-    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed, !referenceOnly) : undefined
+    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.valueSeed, !referenceOnly) : undefined
     if (seededValue === undefined) assertListValue(item, seen, true)
     const token = keyToken(key)
     if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
     keys.add(token)
     entries.push({ item, index, key, token, value: referenceOnly ? item : seededValue === undefined ? JSON.stringify(item) : seededValue })
   }
+  if (list.items === undefined && list.parts.directFill && entries.length === list.roots.size) {
+    const roots = __KUDZU_LIST_STABLE_FAST_PATHS__ ? list.orderedRoots : [...list.roots.values()]
+    if (entries.every((entry, index) => list.roots.get(entry.token) === roots[index])) {
+      for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index]
+        listItems.set(roots[index], entry.item)
+        if (__KUDZU_LIST_INDEXES__) listIndexes.set(roots[index], index)
+        if (!referenceOnly) list.values.set(entry.token, entry.value)
+      }
+      list.items = items
+      return
+    }
+  }
   if (list.descriptor.key !== null && !list.descriptor.indexed && !list.descriptor.selector && (referenceOnly || list.values.size) && entries.every(entry => {
     const root = list.roots.get(entry.token)
     return !root || (referenceOnly ? listItems.get(root) === entry.item : list.values.get(entry.token) === entry.value)
@@ -349,19 +378,18 @@ function updateStableList(list, items) {
   const seen = new Set()
   const keyField = list.descriptor.key
   const fragment = list.start.ownerDocument.createDocumentFragment()
-  let stable = true
   for (let index = 0; index < items.length; index++) {
     const item = items[index]
     assertListItem(item)
-    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed, !referenceOnly) : undefined
+    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.valueSeed, !referenceOnly) : undefined
     if (seededValue === undefined) assertListValue(item, seen, true)
     const key = item[keyField]
     if (!validListKey(key)) throw new Error(`Keyed list key "${keyField}" 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)
-    if (index < previous.length && (key !== previous[index][keyField] || appending && item !== previous[index])) stable = false
-    if (!stable || items.length === previous.length + 1 || index < previous.length) continue
+    if (index < previous.length && (key !== previous[index][keyField] || appending && item !== previous[index])) return false
+    if (items.length === previous.length + 1 || index < previous.length) continue
     let node = list.templateRoot?.cloneNode(true)
     if (node?.dataset.kListRoot !== list.descriptor.id) node = undefined
     if (!node) throw new Error("Keyed list template has no root element")
@@ -371,13 +399,12 @@ function updateStableList(list, items) {
     else fillListItem(node, item, list.descriptor.nested, index, mapListItemParts(list.parts, node, list.descriptor.nested))
     fragment.append(node)
   }
-  if (!stable) return false
   if (appending) {
     if (items.length === previous.length + 1) {
       const item = items.at(-1)
       const key = item[keyField]
       const token = keyToken(key)
-      const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed, !referenceOnly) : undefined
+      const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.valueSeed, !referenceOnly) : undefined
       addListRoot(list, { item, index: previous.length, key, token, value: referenceOnly ? item : seededValue === undefined ? JSON.stringify(item) : seededValue })
       if (referenceOnly) list.values.clear()
       list.items = items
@@ -391,7 +418,7 @@ function updateStableList(list, items) {
       list.roots.set(token, node)
       list.orderedRoots.push(node)
       if (!referenceOnly) {
-        const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed) : undefined
+        const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.valueSeed) : undefined
         list.values.set(token, seededValue === undefined ? JSON.stringify(item) : seededValue)
       }
       node = node.nextSibling
@@ -414,7 +441,7 @@ function updateStableList(list, items) {
       const item = items[index]
       if (item === previous[index]) continue
       const token = keyToken(item[keyField])
-      const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed) : undefined
+      const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.valueSeed) : undefined
       const value = seededValue === undefined ? JSON.stringify(item) : seededValue
       if (list.values.get(token) !== value) {
         const node = list.orderedRoots[index]
@@ -535,7 +562,7 @@ function updateReducerList(list, items) {
     if (!validListKey(key)) throw new Error(`Keyed list key "${list.descriptor.key}" must be a string or finite number`)
     assertListItem(item)
     const seen = new Set()
-    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed) : undefined
+    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.valueSeed) : undefined
     if (seededValue === undefined) assertListValue(item, seen, true)
     const token = keyToken(key)
     if (list.roots.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
@@ -574,11 +601,12 @@ function removeListRoot(list, token) {
 }
 
 function fillListItem(root, item, nested = false, index = 0, parts = listItemParts(root, nested)) {
+  const previous = listItems.get(root)
   listItems.set(root, item)
   if (__KUDZU_LIST_INDEXES__) listIndexes.set(root, index)
   const revision = __KUDZU_LIST_ASYNC_PARTS__ ? (revisions.get(root) ?? 0) + 1 : 0
   if (__KUDZU_LIST_ASYNC_PARTS__) revisions.set(root, revision)
-  fillListParts(root, parts, item, revision, index)
+  fillListParts(root, parts, item, revision, index, previous)
   if (__KUDZU_NESTED_LISTS__) {
     const children = ownedLists.get(root)
     if (children) for (const child of children.values()) updateList(child)
@@ -586,7 +614,7 @@ function fillListItem(root, item, nested = false, index = 0, parts = listItemPar
   if (__KUDZU_LIST_ROW_HOOKS__) replaceRowIds(root, rowReplacements.get(root))
 }
 
-function fillListParts(root, parts, item, revision, index = 0) {
+function fillListParts(root, parts, item, revision, index = 0, previous) {
   if (__KUDZU_LIST_EFFECTS__) for (const node of parts.effects) node.dataset.kEffectItem = JSON.stringify(item)
   for (const [node, field] of parts.directTexts) {
     const text = item?.[field]
@@ -603,7 +631,10 @@ function fillListParts(root, parts, item, revision, index = 0) {
   }
   if (__KUDZU_LIST_ATTRIBUTES__) {
     for (const [node, attributes] of parts.attributes) {
-      for (const [target, field] of attributes) patchBinding(node, target, item?.[field])
+      for (const [target, field] of attributes) {
+        if (previous && Object.is(previous[field], item?.[field])) continue
+        patchBinding(node, target, item?.[field], true)
+      }
     }
   }
   if (__KUDZU_LIST_EVENTS__) {
@@ -978,7 +1009,7 @@ function serializeItem(value) {
   return { type: "object", nullPrototype: false, value: Object.entries(value).map(([key, entry]) => [key, serializeItem(entry)]) }
 }
 
-function patchBinding(node, target, value) {
+function patchBinding(node, target, value, write = false) {
   /* list-style */
   if (target === "disabled") {
     node.toggleAttribute("disabled", Boolean(value))
@@ -995,7 +1026,7 @@ function patchBinding(node, target, value) {
     node.removeAttribute(target)
   } else {
     const next = value === true && !isStringBooleanAttribute(target) ? "" : String(value)
-    if (node.getAttribute(target) !== next) node.setAttribute(target, next)
+    if (write || node.getAttribute(target) !== next) node.setAttribute(target, next)
   }
 }
 

package/framework/navigation-runtime.js

@@ -63,6 +63,7 @@ function eligibleClick(event, anchor) {
 }
 
 function eligibleAnchor(anchor) {
+  if (!anchor) return false
   if (anchor.hasAttribute("download") || anchor.hasAttribute("data-k-native") || !["", "_self"].includes(anchor.target)) return false
   if (anchor.relList?.contains("external")) return false
   const url = new URL(anchor.href)
@@ -125,8 +126,7 @@ async function navigate(url, push) {
       catch { documentResult = await fetchDocument(url, record, request.signal) }
     } else documentResult = await fetchDocument(url, record, request.signal)
     documents.set(url.href, Promise.resolve(documentResult))
-    const { incoming, parsed } = documentResult
-    const capabilities = await loadCapabilities(parsed)
+    const { incoming, parsed, capabilities } = documentResult
     if (current !== revision) return
     await routeDispose()
     if (current !== revision) return
@@ -157,7 +157,8 @@ async function fetchDocument(url, record, signal) {
   const response = await fetch(url, { signal, redirect: "manual", headers: { accept: "text/html" } })
   if (!response.ok || response.redirected || response.type === "opaqueredirect" || !response.headers.get("content-type")?.toLowerCase().includes("text/html")) throw new Error("Navigation response is not successful nonredirected HTML")
   const incoming = new DOMParser().parseFromString(await response.text(), "text/html")
-  return { incoming, parsed: validate(incoming, record), record }
+  const parsed = validate(incoming, record)
+  return { incoming, parsed, capabilities: await loadCapabilities(parsed), record }
 }
 
 function validate(incoming, record) {

package/package.json

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