@kudzujs/core 0.8.19 → 0.8.21

package/framework/compiler/descriptor-session.mjs

@@ -2,7 +2,7 @@ import ts from "typescript"
 import { createComponentAnalysis } from "./analysis/component-analysis.mjs"
 import { bindingNames, isFunctionLike, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, unwrapExpression } from "./ast-helpers.mjs"
 import { generateCommandBehavior } from "./codegen/command-codegen.mjs"
-import { createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerModuleHandler } from "./ir/module-ir.mjs"
+import { createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerEffect, registerKeyedBlock, registerModuleHandler } from "./ir/module-ir.mjs"
 
 export function createSemanticArtifact(file) {
   return { componentAnalysis: createComponentAnalysis(file), moduleIR: createModuleIR(file) }
@@ -16,9 +16,9 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
   const listExpressions = []
   const clientModules = new Set()
 
-  function compileListExpression(read, expression, item, index, states = new Set()) {
+  function compileListExpression(read, expression, item, index, states = new Set(), keyedBlock) {
     const exportName = `listExpression${listExpressions.length}`
-    listExpressions.push({ exportName, expression, item, index, states, role: "list-expression" })
+    listExpressions.push({ exportName, expression, item, index, states, role: "list-expression", keyedBlock })
     const arguments_ = [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)]
     if (states.size) arguments_.push(factory.createArrayLiteralExpression([...states].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
     return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, arguments_)
@@ -26,7 +26,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   function compileListConditional(entry) {
     const exportName = `listExpression${listExpressions.length}`
-    listExpressions.push({ exportName, expression: entry.condition, item: entry.item, index: entry.index, role: "list-conditional" })
+    listExpressions.push({ exportName, expression: entry.condition, item: entry.item, index: entry.index, role: "list-conditional", keyedBlock: entry.keyedBlock })
     const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), entry.condition)
     const thunk = branch => factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), branch)
     return factory.createCallExpression(factory.createIdentifier("__kListConditional"), undefined, [
@@ -44,16 +44,16 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), initial)
     return entry.field
       ? factory.createCallExpression(factory.createIdentifier("__kListField"), undefined, [read, factory.createStringLiteral(entry.field)])
-      : compileListExpression(read, expression, entry.item, entry.index, entry.states)
+      : compileListExpression(read, expression, entry.item, entry.index, entry.states, entry.keyedBlock)
   }
 
-  function compileReactiveBinding(expression, { setters, importBindings = new Map() }) {
+  function compileReactiveBinding(expression, { setters, importBindings = new Map(), keyedBlock }) {
     const parts = conditionalParts(expression)
     const state = parts && directStateIdentifier(parts.condition, setters)
     if (state && isPrimitiveLiteral(parts.truthy) && isPrimitiveLiteral(parts.falsy)) {
       return factory.createCallExpression(factory.createIdentifier("__kSelect"), undefined, [state, parts.truthy, parts.falsy])
     }
-    return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, importBindings))
+    return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, importBindings, keyedBlock))
   }
 
   function compileConditional(kind, expression, truthy, falsy, setters) {
@@ -64,14 +64,14 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return factory.createCallExpression(factory.createIdentifier("__kConditional"), undefined, [factory.createStringLiteral(kind), initial, thunk(truthy), thunk(falsy), ...descriptor])
   }
 
-  function compileReactiveExpression(expression, setters, importBindings = new Map()) {
+  function compileReactiveExpression(expression, setters, importBindings = new Map(), keyedBlock) {
     const usedStates = referencedStateNames(expression, setters)
     const importedNames = referencedImportedBindings(expression, importBindings)
     const imports = [...importedNames].map(name => importBindings.get(name))
     registerClientImports(imports)
     const captures = new Set([...captureNames(expression, expression, setters)].filter(name => !importedNames.has(name)))
     const exportName = `binding${reactiveBindings.length}`
-    reactiveBindings.push({ exportName, expression, captures, states: usedStates, imports, role: "binding" })
+    reactiveBindings.push({ exportName, expression, captures, states: usedStates, imports, role: "binding", keyedBlock })
     const states = [...usedStates].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))
     const scope = [...captures].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))
     const stateNames = new Set(usedStates)
@@ -91,13 +91,13 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     ]
   }
 
-  function compileEvent(expression, { owner = "module", stateOwners = new Map(), setters, reducers, functions, listItem, importBindings }) {
+  function compileEvent(expression, { owner = "module", stateOwners = new Map(), setters, reducers, functions, listItem, keyedBlock, importBindings }) {
     if (ts.isIdentifier(expression)) expression = functions.get(expression.text)
     if (!expression || (!ts.isArrowFunction(expression) && !ts.isFunctionExpression(expression) && !ts.isFunctionDeclaration(expression))) return undefined
-    const optimized = referencedReducerDispatches(expression.body, reducers, expression).size ? undefined : compileOptimizedEvent(expression, setters, stateOwners, owner)
+    const optimized = referencedReducerDispatches(expression.body, reducers, expression).size ? undefined : compileOptimizedEvent(expression, setters, stateOwners, owner, keyedBlock)
     if (optimized) return optimized
     rejectWorkerConstructions(expression)
-    const descriptor = compileNativeCallback(expression, { setters, reducers, entries: nativeHandlers, importBindings, prefix: "handler", role: "native", listItem })
+    const descriptor = compileNativeCallback(expression, { setters, reducers, entries: nativeHandlers, importBindings, prefix: "handler", role: "native", listItem, keyedBlock })
     return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
       factory.createStringLiteral(handlerUrl), factory.createStringLiteral(descriptor.exportName), descriptor.states, descriptor.scope
     ])
@@ -107,7 +107,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return compileNativeCallback(expression, { ...options, entries: effectHandlers, prefix: "effect", role: "effect" })
   }
 
-  function compileNativeCallback(expression, { setters, reducers, entries, importBindings, prefix, role, listItem, deferValues = false, snapshotNested = false, liveStates = new Set() }) {
+  function compileNativeCallback(expression, { setters, reducers, entries, importBindings, prefix, role, listItem, keyedBlock, deferValues = false, snapshotNested = false, liveStates = new Set() }) {
     const allCaptures = nativeCaptureNames(expression, setters)
     const usedReducers = referencedReducerDispatches(expression.body, reducers, expression)
     const imports = [...referencedImportedBindings(expression, importBindings)].map(name => importBindings.get(name))
@@ -120,7 +120,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       if (reducer.contextAction) for (const state of referencedStateNames(reducer.contextAction.body, reducer.states, reducer.contextAction)) usedStates.add(state)
     }
     const exportName = `${prefix}${entries.length}`
-    entries.push({ exportName, expression, captures, deferValues, imports, listItem, liveStates, role, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested, usedStates })
+    entries.push({ exportName, expression, captures, deferValues, imports, listItem, keyedBlock, liveStates, role, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested, usedStates })
     const value = name => deferValues
       ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createIdentifier(name))
       : factory.createIdentifier(name)
@@ -136,13 +136,14 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     }
   }
 
-  function compileOptimizedEvent(expression, setters, stateOwners, owner) {
+  function compileOptimizedEvent(expression, setters, stateOwners, owner, keyedBlock) {
     const statements = ts.isBlock(expression.body) ? expression.body.statements : [factory.createExpressionStatement(expression.body)]
     const commands = statements.map(statement => ts.isExpressionStatement(statement) ? compileEventCommand(statement.expression, setters) : undefined)
     if (!commands.length || commands.some(command => !command)) return undefined
     const original = ts.getOriginalNode(expression)
     const source = original.pos >= 0 && original.end >= 0 ? { file: sourceName(original.getSourceFile()), start: original.getStart(), end: original.end } : undefined
     const handler = registerCommandHandler(moduleIR, commands.map(command => ({ ...command, owner: stateOwners.get(command.state) ?? owner })), source, owner)
+    if (keyedBlock !== undefined) handler.keyedBlock = keyedBlock
     return generateCommandBehavior(moduleIR, handler, factory)
   }
 
@@ -155,6 +156,14 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return registerDerived(moduleIR, { kind, [kind]: normalized, states: [...states], ...(source(node) ? { source: source(node) } : {}) })
   }
 
+  function registerKeyedBlockResult(descriptor) {
+    return registerKeyedBlock(moduleIR, descriptor)
+  }
+
+  function registerEffectResult(handler, descriptor) {
+    return registerEffect(moduleIR, { ...descriptor, setup: { exportName: handler.exportName } })
+  }
+
   function finalize() {
     const callbacks = [...nativeHandlers, ...effectHandlers]
     for (const entry of callbacks) {
@@ -162,6 +171,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       const setters = Map.groupBy(entry.setters, ([, state]) => state)
       registerModuleHandler(moduleIR, {
         role: entry.role,
+        ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
         exportName: entry.exportName,
         async: Boolean(entry.expression.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)),
         generator: Boolean(entry.expression.asteriskToken),
@@ -184,6 +194,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     }
     for (const entry of reactiveBindings) registerBinding(moduleIR, {
       role: entry.role,
+      ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
       exportName: entry.exportName,
       parameters: ["__k"],
       states: [...entry.states],
@@ -194,6 +205,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     })
     for (const entry of listExpressions) registerBinding(moduleIR, {
       role: entry.role,
+      ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
       exportName: entry.exportName,
       parameters: [entry.item, entry.index ?? "__kIndex", "__k"],
       states: [...(entry.states ?? [])],
@@ -202,6 +214,11 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       code: handlerLowering.lowerListExpression(entry),
       ...(source(entry.expression) ? { source: source(entry.expression) } : {})
     })
+    for (const effect of moduleIR.effects) {
+      const handler = moduleIR.handlers.find(candidate => candidate.kind === "module-export" && candidate.role === "effect" && candidate.exportName === effect.setup.exportName)
+      if (!handler) throw new Error(`Effect handler ${JSON.stringify(effect.setup.exportName)} was not finalized`)
+      effect.setup = { handler: handler.slot }
+    }
     const imports = [...callbacks, ...reactiveBindings].flatMap(entry => entry.imports ?? []).map(importRecord)
     moduleIR.imports = [...new Map(imports.map(entry => [`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`, entry])).values()]
     moduleIR.clientModules = [...clientModules]
@@ -215,7 +232,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   const importRecord = entry => ({ target: entry.target, kind: entry.kind, local: entry.local, ...(entry.imported ? { imported: entry.imported } : {}), package: Boolean(entry.package) })
 
-  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult }
+  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult, registerEffect: registerEffectResult, registerKeyedBlock: registerKeyedBlockResult }
 }
 
 function directStateIdentifier(expression, setters) {

package/framework/compiler/effect-analysis.mjs

@@ -0,0 +1,89 @@
+import ts from "typescript"
+import { nearestFunction, referencesIdentifier, unwrapExpression } from "./ast-helpers.mjs"
+import { collectionExpression } from "./collection-analysis.mjs"
+import { referencedStateNames } from "./descriptor-session.mjs"
+
+export function analyzeEffectDependencies({ dependencies, node, listEffect, keyedItem, setters, localDeclarations, factory, fail }) {
+  const itemDependencies = []
+  const ordinaryDependencies = []
+  let dependencyItem = listEffect ? keyedItem : undefined
+  for (const dependency of dependencies.elements) {
+    const value = unwrapExpression(dependency)
+    if (!dependencyItem && ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression) && isDestructuredParameter(value.expression, nearestFunction(node))) dependencyItem = value.expression.text
+    const field = dependencyItem && directProperty(dependency, dependencyItem)
+    if (field) {
+      if (["__proto__", "constructor", "prototype"].includes(field)) fail(dependency, `useEffect() keyed item property "${field}" is not supported`)
+      itemDependencies.push(field)
+    } else if (dependencyItem && referencesIdentifier(dependency, dependencyItem)) {
+      fail(dependency, "useEffect() keyed item dependencies must be direct item.<field> properties")
+    } else {
+      ordinaryDependencies.push(dependency)
+    }
+  }
+  const invalidDependency = ordinaryDependencies.find(dependency => !ts.isIdentifier(dependency))
+  if (invalidDependency) fail(invalidDependency, "useEffect() dependencies must be direct state or runtime parameter identifiers")
+
+  const entries = []
+  const dependencyStates = new Map()
+  const substitutions = new Map()
+  const subscriptions = []
+  let hasDerived = false
+  const stateNames = new Set(setters.values())
+  for (const dependency of ordinaryDependencies) {
+    const declarations = localDeclarations?.get(dependency.text)
+    const initializer = declarations?.length === 1 ? declarations[0].initializer : undefined
+    const directAlias = initializer && ts.isIdentifier(unwrapExpression(initializer)) && stateNames.has(unwrapExpression(initializer).text)
+    const derivedStates = initializer && !directAlias ? referencedStateNames(initializer, setters) : new Set()
+    if (derivedStates.size) {
+      const usedStates = new Set()
+      const expression = collectionExpression(initializer, { fail, stateNames, selectorStates: usedStates })
+      if (!usedStates.size) fail(dependency, `useEffect() derived dependency "${dependency.text}" must read direct primitive state`)
+      entries.push({ kind: "derived", name: dependency.text, expression, states: usedStates, source: initializer })
+      for (const name of usedStates) {
+        subscriptions.push(factory.createIdentifier(name))
+        dependencyStates.set(name, factory.createIdentifier(name))
+      }
+      substitutions.set(dependency.text, initializer)
+      hasDerived = true
+    } else {
+      subscriptions.push(dependency)
+      entries.push({ kind: "signal", name: dependency.text })
+      dependencyStates.set(dependency.text, dependency)
+    }
+  }
+  if (!hasDerived) dependencyStates.clear()
+  return { dependencyItem, itemDependencies, ordinaryDependencies, entries, dependencyStates, substitutions, subscriptions, hasDerived }
+}
+
+export function validateEffectOwnedBrowserResources(callback, returns, fail) {
+  const observers = []
+  const frameAssignments = []
+  const cancellations = new Set()
+  const disconnected = new Set()
+  const insideCleanup = node => returns.cleanups.some(cleanup => {
+    for (let current = node; current; current = current.parent) if (current === cleanup) return true
+    return false
+  })
+  const visit = node => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isNewExpression(unwrapExpression(node.initializer)) && ts.isIdentifier(unwrapExpression(node.initializer).expression) && unwrapExpression(node.initializer).expression.text === "IntersectionObserver") observers.push(node)
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(unwrapExpression(node.left)) && ts.isCallExpression(unwrapExpression(node.right)) && ts.isIdentifier(unwrapExpression(node.right).expression) && unwrapExpression(node.right).expression.text === "requestAnimationFrame") frameAssignments.push(node)
+    if (insideCleanup(node) && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "cancelAnimationFrame" && node.arguments.length === 1 && ts.isIdentifier(unwrapExpression(node.arguments[0]))) cancellations.add(unwrapExpression(node.arguments[0]).text)
+    if (insideCleanup(node) && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.name.text === "disconnect" && node.arguments.length === 0) disconnected.add(node.expression.expression.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(callback.body)
+  for (const observer of observers) if (!disconnected.has(observer.name.text)) fail(observer, `IntersectionObserver effects must disconnect ${JSON.stringify(observer.name.text)} in cleanup`)
+  for (const assignment of frameAssignments) {
+    const name = unwrapExpression(assignment.left).text
+    if (!cancellations.has(name)) fail(assignment, `Animation loop effects must cancel ${JSON.stringify(name)} in cleanup`)
+  }
+}
+
+function isDestructuredParameter(identifier, fn) {
+  return fn?.parameters.some(parameter => ts.isObjectBindingPattern(parameter.name) && parameter.name.elements.some(element => ts.isIdentifier(element.name) && element.name.text === identifier.text)) ?? false
+}
+
+function directProperty(expression, objectName) {
+  const value = unwrapExpression(expression)
+  return ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression) && value.expression.text === objectName ? value.name.text : undefined
+}

package/framework/compiler/ir/module-ir.mjs

@@ -1,5 +1,5 @@
 export function createModuleIR(file) {
-  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], imports: [], clientModules: [] }
+  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
 }
 
 export function registerCommandHandler(moduleIR, commands, source, scope = "module") {
@@ -39,3 +39,15 @@ export function registerDerived(moduleIR, descriptor) {
   moduleIR.derived.push(derived)
   return derived
 }
+
+export function registerEffect(moduleIR, descriptor) {
+  const effect = { slot: moduleIR.effects.length, ...descriptor }
+  moduleIR.effects.push(effect)
+  return effect
+}
+
+export function registerKeyedBlock(moduleIR, descriptor) {
+  const block = { slot: moduleIR.keyedBlocks.length, ...descriptor }
+  moduleIR.keyedBlocks.push(block)
+  return block
+}

package/framework/compiler/worker-compiler.mjs

@@ -44,7 +44,8 @@ export function createWorkerCompiler({
     return { worker, url, specifier: specifierNode.text, options }
   }
 
-  const rewriteEffect = (callback, file, sourceFile, sourceFiles, workerReferences, factory, context) => {
+  const rewriteEffect = (callback, file, sourceFile, sourceFiles, factory, context) => {
+    const workers = []
     const visit = node => {
       const value = candidate(node, sourceFile)
       if (value) {
@@ -56,12 +57,17 @@ export function createWorkerCompiler({
         if (!sourceFiles.has(target)) throw sourceNodeError(url.arguments[0], sourceFile, `Relative TypeScript Worker ${JSON.stringify(specifier)} must resolve to an existing .worker.ts file under src/`)
         const identity = `${sourceRelative.replaceAll(sep, "/")}:${ts.getOriginalNode(node).getStart(sourceFile)}`
         const placeholder = `/__kudzu_worker_${createHash("sha256").update(identity).digest("hex").slice(0, 16)}__.js`
-        workerReferences.push({ root: target, placeholder })
+        const original = ts.getOriginalNode(node)
+        workers.push({
+          root: sourceRelative.replaceAll(sep, "/"),
+          placeholder,
+          source: { file: relative(root, sourceFile.fileName).replaceAll(sep, "/"), start: original.getStart(sourceFile), end: original.end }
+        })
         return factory.updateNewExpression(worker, worker.expression, worker.typeArguments, [factory.createStringLiteral(placeholder), options])
       }
       return ts.visitEachChild(node, visit, context)
     }
-    return ts.visitEachChild(callback, visit, context)
+    return { callback: ts.visitEachChild(callback, visit, context), workers }
   }
 
   const rejectConstructions = (expression, sourceFile, message) => {
@@ -124,7 +130,7 @@ export function createWorkerCompiler({
   }
 
   const emit = async (references, sourceFiles, assetsDirectory, base, minify) => {
-    const roots = [...new Set(references.map(reference => reference.root))].sort()
+    const roots = [...new Set(references.map(reference => resolve(sourceDirectory, reference.root)))].sort()
     if (!roots.length) return new Map()
     await validateGraphs(roots, sourceFiles)
     const workerDirectory = resolve(assetsDirectory, "workers")
@@ -150,12 +156,12 @@ export function createWorkerCompiler({
     for (const [output, metadata] of Object.entries(result.metafile.outputs)) {
       if (!metadata.entryPoint) continue
       const entry = resolve(root, metadata.entryPoint)
-      const rootReferences = references.filter(reference => reference.root === entry)
+      const rootReferences = references.filter(reference => resolve(sourceDirectory, reference.root) === entry)
       const outputFile = resolve(root, output)
       const url = assetPath(base, relative(outputDirectory, outputFile).replaceAll(sep, "/"))
       for (const reference of rootReferences) emitted.set(reference.placeholder, url)
     }
-    for (const reference of references) if (!emitted.has(reference.placeholder)) throw new Error(`Worker entry was not emitted: ${relative(root, reference.root)}`)
+    for (const reference of references) if (!emitted.has(reference.placeholder)) throw new Error(`Worker entry was not emitted: ${reference.root}`)
     return emitted
   }
 

package/framework/core.d.ts

@@ -80,6 +80,57 @@ export type MetadataContext<Props = Record<string, unknown>> = {
   props: Props
 }
 
+export type ListSourceDescriptor =
+  | { state: string; truthy?: unknown; falsy?: unknown }
+  | {
+      module: string
+      handler: string
+      states: Record<string, string>
+      scope: Record<string, unknown>
+      scopeStates: Record<string, string>
+      scopeBindings: Record<string, unknown>
+    }
+
+export type ChildListDescriptor = {
+  id: string
+  field: string
+  key: string | null
+  selector?: unknown[]
+}
+
+export type ListDescriptor = {
+  id: string
+  state: string
+  key: string | null
+  keys: Array<string | number>
+  svg?: true
+  static?: true
+  source?: ListSourceDescriptor
+  ownerField?: string
+  selector?: unknown[]
+  selectorStates?: Record<string, string>
+  indexed?: true
+  reducer?: true
+  children?: ChildListDescriptor[]
+  mount?: true
+  nested?: true
+  effects?: true
+  conditions?: true
+  conditionHandlers?: true
+  textRanges?: true
+  attributes?: true
+  events?: true
+  expressions?: true
+  expressionAttributes?: true
+  expressionStates?: string[]
+  rowStates?: Array<{ id: string; initialValue: unknown }>
+  rowConditions?: string[]
+  rowRefs?: string[]
+  fastRelease?: true
+  seed?: Record<string, string | number | boolean | null>
+  valueSeed?: Record<string, string | number | boolean | null>
+}
+
 export function renderPage<Props = Record<string, never>>(
   component: (props: Props) => unknown | Promise<unknown>,
   metadata?: PageMetadata,
@@ -105,7 +156,21 @@ export function renderPage<Props = Record<string, never>>(
       commands?: Array<[string, string, unknown]>
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
-    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown>; lifetime?: "layout" | "route"; dependencies?: string[]; itemDependencies?: string[]; listState?: string; cleanup?: true; owner?: string; list?: true }>
+    effects: Array<{
+      module: string
+      handler: string
+      states: Record<string, string>
+      scope: Record<string, unknown>
+      lifetime?: "layout" | "route"
+      dependencies?: string[]
+      dependencyExpressions?: unknown[]
+      dependencyStates?: Record<string, string>
+      itemDependencies?: string[]
+      listState?: string
+      cleanup?: true
+      owner?: string
+      list?: true
+    }>
     bindings: Array<{
       target: string
       state?: string
@@ -117,6 +182,6 @@ export function renderPage<Props = Record<string, never>>(
       scopeBindings?: Record<string, unknown>
     }>
     conditions: Array<Record<string, unknown>>
-    lists: Array<Record<string, unknown>>
+    lists: ListDescriptor[]
   }
 }>

package/package.json

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