@kudzujs/core 0.8.62 → 0.9.1

package/framework/compiler/effect-analysis.mjs

@@ -1,14 +1,15 @@
 import ts from "typescript"
-import { nearestFunction, referencesIdentifier, unwrapExpression } from "./ast-helpers.mjs"
+import { isNodeWithin, 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, bindingIndex }) {
+export function analyzeEffectDependencies({ dependencies, node, listEffect, keyedItem, setters, localDeclarations, factory, fail, bindingIndex, resolveCalculation }) {
   const itemDependencies = []
   const ordinaryDependencies = []
   let dependencyItem = listEffect ? keyedItem : undefined
   for (const dependency of dependencies.elements) {
     const value = unwrapExpression(dependency)
+    if (ts.isElementAccessExpression(value) && ts.isIdentifier(unwrapExpression(value.expression)) && isDestructuredParameter(unwrapExpression(value.expression), nearestFunction(node)) && !ts.isStringLiteral(value.argumentExpression) && !ts.isNumericLiteral(value.argumentExpression)) fail(dependency, "useEffect() object property dependencies require a direct static property path")
     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) {
@@ -29,7 +30,19 @@ export function analyzeEffectDependencies({ dependencies, node, listEffect, keye
   let hasDerived = false
   const stateNames = new Set(setters.values())
   for (const dependency of ordinaryDependencies) {
+    const calculation = resolveCalculation?.(dependency)
+    if (calculation) {
+      entries.push({ kind: "calculation", ...calculation })
+      for (const name of calculation.states) {
+        subscriptions.push(factory.createIdentifier(name))
+        dependencyStates.set(name, factory.createIdentifier(name))
+      }
+      substitutions.set(calculation.name, calculation.call)
+      hasDerived = true
+      continue
+    }
     const direct = ts.isIdentifier(dependency)
+    if (!direct && dynamicStatePropertyDependency(dependency, stateNames)) fail(dependency, "useEffect() object property dependencies require a direct static property path")
     if (!direct && !statePropertyDependency(dependency, stateNames)) fail(dependency, "useEffect() dependencies must be direct state or runtime parameter identifiers or property reads")
     const declarations = direct ? localDeclarations?.get(dependency.text) : undefined
     const initializer = declarations?.length === 1 ? declarations[0].initializer : undefined
@@ -42,7 +55,7 @@ export function analyzeEffectDependencies({ dependencies, node, listEffect, keye
       const usedStates = new Set()
       const expression = collectionExpression(expressionSource, { fail, stateNames, selectorStates: usedStates })
       if (!usedStates.size) fail(dependency, `useEffect() derived dependency must read direct state`)
-      entries.push({ kind: "derived", name: direct ? dependency.text : dependency.getText(), expression, states: usedStates, source: expressionSource })
+      entries.push({ kind: "derived", name: direct ? dependency.text : "derived", expression, states: usedStates, source: expressionSource })
       for (const name of usedStates) {
         subscriptions.push(factory.createIdentifier(name))
         dependencyStates.set(name, factory.createIdentifier(name))
@@ -56,7 +69,7 @@ export function analyzeEffectDependencies({ dependencies, node, listEffect, keye
       dependencyStates.set(dependency.text, dependency)
     }
   }
-  const derivedSourceNames = new Set(entries.filter(entry => entry.kind === "derived").flatMap(entry => [...entry.states]))
+  const derivedSourceNames = new Set(entries.filter(entry => entry.kind !== "signal").flatMap(entry => [...entry.states]))
   const ambiguous = entries.find(entry => entry.kind === "signal" && derivedSourceNames.has(entry.name))
   if (ambiguous) fail(ordinaryDependencies[entries.indexOf(ambiguous)], `useEffect() cannot mix whole-object and property dependencies for state ${JSON.stringify(ambiguous.name)}`)
   if (!hasDerived) dependencyStates.clear()
@@ -69,10 +82,7 @@ export function validateEffectOwnedBrowserResources(callback, returns, fail, bin
   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 insideCleanup = node => returns.cleanups.some(cleanup => isNodeWithin(node, cleanup))
   const isGlobal = (identifier, name) => identifier.text === name && (!bindingIndex || bindingIndex.resolveReference(identifier, callback)?.kind === "global")
   const resource = identifier => bindingIndex?.resolveReference(identifier, callback)?.declaration ?? identifier.text
   const visit = node => {
@@ -109,3 +119,13 @@ function statePropertyDependency(expression, stateNames) {
   }
   return property && ts.isIdentifier(value) && stateNames.has(value.text)
 }
+
+function dynamicStatePropertyDependency(expression, stateNames) {
+  let value = unwrapExpression(expression)
+  let dynamic = false
+  while (ts.isPropertyAccessExpression(value) || ts.isElementAccessExpression(value)) {
+    if (ts.isElementAccessExpression(value) && !ts.isStringLiteral(value.argumentExpression) && !ts.isNumericLiteral(value.argumentExpression)) dynamic = true
+    value = unwrapExpression(value.expression)
+  }
+  return dynamic && ts.isIdentifier(value) && stateNames.has(value.text)
+}

package/framework/compiler/effect-codegen.mjs

@@ -6,6 +6,7 @@ function printEffectEntry(effects, output, handlerModules, assetsDirectory, runt
   const hasDependencies = effects.some(effect => effect.dependencies?.length || effect.itemDependencies?.length)
   const hasOwners = effects.some(effect => effect.owner)
   const hasDependencyExpressions = effects.some(effect => effect.dependencyExpressions?.length)
+  const hasDependencyEvaluators = effects.some(effect => effect.dependencyEvaluators?.length)
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
     const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
@@ -34,7 +35,7 @@ const dispose = root => {
   for (const record of records) invokeCleanup(record)
 }
 
-if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose, "effects")
 addEventListener("pagehide", event => {
   if (event.persisted) return
   if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
@@ -101,7 +102,7 @@ async function flush() {
   }
 }
 function readDependencies(record) {
-${hasDependencyExpressions ? printDerivedDependencyRead("browserState") : ""}
+${hasDependencyExpressions || hasDependencyEvaluators ? printDerivedDependencyRead("browserState", hasDependencyExpressions, hasDependencyEvaluators) : ""}
   return (record.effect.dependencies ?? []).map(id => {
     const value = browserState.get(id)
     if (!Array.isArray(value) && value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive or array")
@@ -170,7 +171,7 @@ const dispose = root => {
   }
   cleanups.length = 0
 }
-if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose, "effects")
 addEventListener("pagehide", event => {
   if (event.persisted) return
   if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
@@ -180,6 +181,7 @@ addEventListener("pagehide", event => {
 
 function printNavigableEffectEntry(effects, output, handlerModules, assetsDirectory, runtimeDirectory, base) {
   const hasDependencyExpressions = effects.some(effect => effect.dependencyExpressions?.length)
+  const hasDependencyEvaluators = effects.some(effect => effect.dependencyEvaluators?.length)
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
     const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
@@ -257,7 +259,7 @@ function mount(lifetime) {
     }
   }
   function readDependencies(record) {
-${hasDependencyExpressions ? printDerivedDependencyRead("__kRuntime.browserState") : ""}
+${hasDependencyExpressions || hasDependencyEvaluators ? printDerivedDependencyRead("__kRuntime.browserState", hasDependencyExpressions, hasDependencyEvaluators) : ""}
     return (record.effect.dependencies ?? []).map(id => {
       const value = __kRuntime.browserState.get(id)
       if (!Array.isArray(value) && value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive or array")
@@ -303,6 +305,7 @@ ${hasDependencyExpressions ? printDerivedDependencyRead("__kRuntime.browserState
 function printOwnedNavigableEffectEntry(effects, output, handlerModules, assetsDirectory, runtimeDirectory, base) {
   const hasItemDependencies = effects.some(effect => effect.itemDependencies?.length)
   const hasDependencyExpressions = effects.some(effect => effect.dependencyExpressions?.length)
+  const hasDependencyEvaluators = effects.some(effect => effect.dependencyEvaluators?.length)
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
     const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
@@ -346,8 +349,8 @@ function mount(lifetime) {
     for (const record of dependencies.get(id) ?? []) if (record.mounted) pending.add(record)
     schedule()
   }) : undefined
-  const unsubscribeMount = __kRuntime.registerMountHook(mountOwned)
-  const unsubscribeUnmount = __kRuntime.registerUnmountHook(unmountOwned)
+  const unsubscribeMount = __kRuntime.registerMountHook(mountOwned, "effects")
+  const unsubscribeUnmount = __kRuntime.registerUnmountHook(unmountOwned, "effects")
   ${hasItemDependencies ? `const unsubscribeItems = [...new Set(selectedEffects.filter(({ effect }) => effect.itemDependencies?.length).map(({ effect }) => effect.listState))].map(listState => __kRuntime.registerListItemHook(listState, root => {
     if (!active) return
     for (const record of registrations.get(root) ?? []) if (record.mounted && record.effect.itemDependencies) pending.add(record)
@@ -481,7 +484,7 @@ function mount(lifetime) {
     }
   }
   function readDependencies(record) {
-${hasDependencyExpressions ? printDerivedDependencyRead("__kRuntime.browserState") : ""}
+${hasDependencyExpressions || hasDependencyEvaluators ? printDerivedDependencyRead("__kRuntime.browserState", hasDependencyExpressions, hasDependencyEvaluators) : ""}
     const values = (record.effect.dependencies ?? []).map(id => {
       const value = __kRuntime.browserState.get(id)
       if (!Array.isArray(value) && value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive or array")
@@ -554,19 +557,28 @@ ${hasDependencyExpressions ? printDerivedDependencyRead("__kRuntime.browserState
 }`
 }
 
-function printDerivedDependencyRead(state) {
-  return `    if (record.effect.dependencyExpressions) return record.effect.dependencyExpressions.map(expression => {
+function printDerivedDependencyRead(state, hasExpressions, hasEvaluators) {
+  return `${hasEvaluators ? `    if (record.effect.dependencyEvaluators) return record.effect.dependencyEvaluators.map(evaluator => {
+      const result = modules.get(evaluator.module)[evaluator.handler](createEffectContext(${state}, evaluator.states, () => {}, evaluator.scope))
+      const value = result[evaluator.field]
+      if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() calculated dependency must remain a JSON-safe primitive")
+      return value
+    })
+` : ""}${hasExpressions ? `    if (record.effect.dependencyExpressions) return record.effect.dependencyExpressions.map(expression => {
       const value = __kEvaluateDependency(expression, undefined, undefined, name => ${state}.get(record.effect.dependencyStates[name]))
-      if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() derived dependency must remain a JSON-safe primitive")
+      if (value !== null && !Array.isArray(value) && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() derived dependency must remain a JSON-safe primitive or array")
       return value
-    })`
+    })` : ""}`
 }
 
 function printOwnedEffectEntry(imports, effects, entries) {
   const hasItemDependencies = effects.some(effect => effect.itemDependencies?.length)
   const hasOrdinaryDependencies = effects.some(effect => effect.dependencies?.length)
   const hasDependencyExpressions = effects.some(effect => effect.dependencyExpressions?.length)
-  const hasRowState = effects.some(effect => JSON.stringify([effect.dependencies, effect.dependencyStates, effect.states, effect.scope]).includes("$k"))
+  const hasDependencyEvaluators = effects.some(effect => effect.dependencyEvaluators?.length)
+  const hasRowState = effects.some(effect => JSON.stringify([effect.dependencies, effect.dependencyStates, effect.states]).includes("$k") || Object.values(effect.scope).some(hasRowStateCapture))
+  const hasRowRef = effects.some(effect => Object.values(effect.scope).some(hasRowRefCapture))
+  const initialDependencyCheck = [hasOrdinaryDependencies && "record.effect.dependencies?.length", hasItemDependencies && "record.effect.itemDependencies?.length", hasDependencyExpressions && "record.effect.dependencyExpressions?.length", hasDependencyEvaluators && "record.effect.dependencyEvaluators?.length"].filter(Boolean).join(" || ")
   return `${imports.join("\n")}
 const effects = ${inlineJson(effects)}
 const modules = new Map([${entries}])
@@ -574,6 +586,7 @@ ${hasItemDependencies ? "let order = 0\n" : ""}const records = effects.map((effe
 const listTemplates = new Map(effects.map((effect, index) => effect.list ? [effect.owner, { effect, index }] : undefined).filter(Boolean))
 const owners = new Map(records.filter(record => record.effect.owner).map(record => [record.effect.owner, record]))
 const listRegistrations = new WeakMap()
+const listOwnerSets = new Map()
 const mountedRecords = new Set(records.filter(record => record.mounted))
 const dependencies = new Map()
 const pending = new Set()
@@ -585,7 +598,7 @@ function createRecord(effect, index${hasRowState ? ", marker" : ""}) {
   return { effect: ${hasRowState ? "marker ? specializeRowEffect(effect, marker) : effect" : "effect"}, index, ${hasItemDependencies ? "order: order++, " : ""}mounted: !effect.owner, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined, token: undefined }
 }
 ${hasRowState ? `function specializeRowEffect(effect, marker) {
-  const path = marker.dataset.kRowPath
+  const path = __kRuntime.listRowPaths.get(marker)
   const id = value => typeof value === "string" ? value.replace("$k", path) : value
   const capture = value => value?.type === "state" || value?.type === "setter" || value?.type === "ref" ? { ...value, id: id(value.id) } : value?.type === "array" ? { ...value, value: value.value.map(capture) } : value?.type === "object" ? { ...value, value: value.value.map(([key, entry]) => [key, capture(entry)]) } : value
   return { ...effect, dependencies: effect.dependencies?.map(id), dependencyStates: effect.dependencyStates && Object.fromEntries(Object.entries(effect.dependencyStates).map(([name, value]) => [name, id(value)])), states: Object.fromEntries(Object.entries(effect.states).map(([name, value]) => [name, id(value)])), scope: Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, capture(value)])) }
@@ -620,12 +633,18 @@ ${hasItemDependencies ? `for (const listState of new Set(effects.filter(effect =
   for (const marker of matching(root)) {
     if (marker.dataset.kEffects) {
       if (listRegistrations.has(marker)) continue
-      const rowRecords = JSON.parse(marker.dataset.kEffects).map(owner => {
+       const encoded = marker.dataset.kEffects
+       let effectOwners = listOwnerSets.get(encoded)
+       if (!effectOwners) {
+         effectOwners = JSON.parse(encoded)
+         listOwnerSets.set(encoded, effectOwners)
+       }
+       const rowRecords = effectOwners.map(owner => {
         const template = listTemplates.get(owner)
         if (!template) throw new Error("Keyed row effect template was not emitted")
         const record = createRecord(template.effect, template.index${hasRowState ? ", marker" : ""})
-        registerDependencies(record)
-        mount(record, marker)
+        if (record.effect.dependencies?.length) registerDependencies(record)
+        mount(record, marker, true)
         return record
       })
       listRegistrations.set(marker, rowRecords)
@@ -634,7 +653,7 @@ ${hasItemDependencies ? `for (const listState of new Set(effects.filter(effect =
     const record = owners.get(marker.dataset.kEffect)
     if (!record?.mounted) mount(record, marker)
   }
-})
+}, "effects")
 __kRuntime.registerUnmountHook(root => {
   if (root === document) {
     if (!active) return
@@ -653,7 +672,7 @@ __kRuntime.registerUnmountHook(root => {
     const record = owners.get(marker.dataset.kEffect)
     if (record?.marker === marker) unmount(record)
   }
-})
+}, "effects")
 for (const record of records) if (record.mounted) start(record)
 __kRuntime.mountDom(document)
 addEventListener("pagehide", event => {
@@ -663,17 +682,16 @@ function matching(root) {
   const selector = "template[data-k-effect],[data-k-effects]"
   return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
 }
-function mount(record, marker) {
+function mount(record, marker, fresh = false) {
   record.mounted = true
   record.marker = marker
   mountedRecords.add(record)
   const version = ++record.version
-  const begin = () => {
+  if (record.disposal) record.disposal.then(() => {
     if (!active || !record.mounted || record.version !== version || !marker.isConnected) return
     start(record)
-  }
-  if (record.disposal) record.disposal.then(begin)
-  else begin()
+  })
+  else if (fresh || active && marker.isConnected) start(record)
 }
 function unmount(record, dynamic = false) {
   if (!record.mounted) return
@@ -687,7 +705,7 @@ function unmount(record, dynamic = false) {
 }
 function start(record) {
   try {
-    record.values = readDependencies(record)
+    ${initialDependencyCheck ? `if (${initialDependencyCheck}) record.values = readDependencies(record)` : ""}
     invoke(record)
   } catch (error) {
     console.error(error)
@@ -730,7 +748,7 @@ async function flush() {
   }
 }
 function readDependencies(record) {
-${hasDependencyExpressions ? printDerivedDependencyRead("browserState") : ""}
+${hasDependencyExpressions || hasDependencyEvaluators ? printDerivedDependencyRead("browserState", hasDependencyExpressions, hasDependencyEvaluators) : ""}
   const values = (record.effect.dependencies ?? []).map(id => {
     const value = browserState.get(id)
     if (!Array.isArray(value) && value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive or array")
@@ -752,9 +770,16 @@ function invoke(record) {
   try {
     const effect = record.effect
     const scope = effect.list
-      ? Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, value?.type === "list-item" ? JSON.parse(record.marker.dataset.kEffectItem) : value]))
+      ? Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, value?.type === "list-item" ? __kRuntime.listItems.get(record.marker) : value]))
       : effect.scope
-    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope, () => active && token.active && record.token === token))
+    const marker = record.marker
+    ${hasRowRef ? "const rowPath = effect.list ? __kRuntime.listRowPaths.get(marker) : undefined" : ""}
+    const resolveRef = id => {
+      if (!marker?.isConnected) return null
+      const resolved = ${hasRowRef ? 'id.replace("$k", rowPath)' : "id"}
+      return marker.dataset.kRef === resolved ? marker : [...marker.querySelectorAll("[data-k-ref]")].find(node => node.dataset.kRef === resolved) ?? null
+    }
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope, () => active && token.active && record.token === token, effect.list ? resolveRef : undefined))
     if (effect.cleanup && typeof result === "function") record.cleanup = result
     else if (result && typeof result.then === "function") result.catch(error => console.error(error))
   } catch (error) {
@@ -767,14 +792,16 @@ function invokeCleanup(record) {
   if (record.disposal) return record.disposal
   const cleanup = record.cleanup
   record.cleanup = undefined
-  if (!cleanup) return Promise.resolve()
-  const disposal = (async () => {
-    try {
-      await cleanup()
-    } catch (error) {
-      console.error(error)
-    }
-  })()
+  if (!cleanup) return
+  let result
+  try {
+    result = cleanup()
+  } catch (error) {
+    console.error(error)
+    return
+  }
+  if (!result || typeof result.then !== "function") return
+  const disposal = Promise.resolve(result).catch(error => console.error(error))
   record.disposal = disposal
   disposal.finally(() => {
     if (record.disposal === disposal) record.disposal = undefined
@@ -783,6 +810,22 @@ function invokeCleanup(record) {
 }`
 }
 
+function hasRowStateCapture(value) {
+  if (!value || typeof value !== "object") return false
+  if ((value.type === "state" || value.type === "setter") && value.id.includes("$k")) return true
+  if (value.type === "array") return value.value.some(hasRowStateCapture)
+  if (value.type === "object") return value.value.some(([, entry]) => hasRowStateCapture(entry))
+  return false
+}
+
+function hasRowRefCapture(value) {
+  if (!value || typeof value !== "object") return false
+  if (value.type === "ref" && value.id.includes("$k")) return true
+  if (value.type === "array") return value.value.some(hasRowRefCapture)
+  if (value.type === "object") return value.value.some(([, entry]) => hasRowRefCapture(entry))
+  return false
+}
+
 function printSingleDependencyEffect(imports, effect, hasCleanup) {
   const disposal = hasCleanup ? `
 const dispose = root => {
@@ -791,7 +834,7 @@ const dispose = root => {
   pending = false
   invokeCleanup()
 }
-if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose, "effects")
 addEventListener("pagehide", event => {
   if (event.persisted) return
   if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)

package/framework/compiler/effect-private-ref-pass.mjs

@@ -1,5 +1,5 @@
 import ts from "typescript"
-import { effectReturns, importDeclarationNames, isShadowedIdentifier, nearestFunction, referenceIdentifiers, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
+import { effectReturns, importDeclarationNames, isNodeWithin, isShadowedIdentifier, nearestFunction, referenceIdentifiers, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
 
 export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
     const frameCall = (node, name) => ts.isCallExpression(node) && (
@@ -11,10 +11,6 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
       return name && !isShadowedIdentifier(name, owner) && !sourceFile.statements.some(statement => statementDeclaresName(statement, name.text) || ts.isImportDeclaration(statement) && importDeclarationNames(statement).includes(name.text))
     }
     const currentAccess = (node, name) => ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name && node.name.text === "current"
-    const inside = (node, root) => {
-      for (let current = node; current; current = current.parent) if (current === root) return true
-      return false
-    }
     const directOrGuarded = (statement, body, name, negated) => {
       if (statement.parent === body) return true
       let branch = statement
@@ -58,13 +54,13 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
       const effectCalls = owner.body.statements.flatMap(statement => hasUseEffectImport && ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression) && ts.isIdentifier(statement.expression.expression) && statement.expression.expression.text === "useEffect" && !isShadowedIdentifier(statement.expression.expression, sourceFile) ? [statement.expression] : [])
       const effects = effectCalls.filter(effect => {
         const callback = effect.arguments[0]
-        return callback && accesses.every(access => inside(access, callback))
+        return callback && accesses.every(access => isNodeWithin(access, callback))
       })
       if (!frameAssignments.length) {
         const callback = effects.length === 1 ? effects[0].arguments[0] : undefined
         if (callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) && ts.isBlock(callback.body)) {
           const cleanups = effectReturns(callback).cleanups
-          const cleanupWrites = cleanups.length === 1 && accesses.some(access => inside(access, cleanups[0]) && ts.isBinaryExpression(access.parent) && unwrapExpression(access.parent.left) === access && access.parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && access.parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+          const cleanupWrites = cleanups.length === 1 && accesses.some(access => isNodeWithin(access, cleanups[0]) && ts.isBinaryExpression(access.parent) && unwrapExpression(access.parent.left) === access && access.parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && access.parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
           if (!cleanupWrites) throw sourceNodeError(node, sourceFile, "Effect-private refs require one cleanup that directly resets or invalidates ref.current")
           registerPrivateRef(node, callback)
         }
@@ -77,7 +73,7 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
       const effect = effects[0]
       const callback = effect.arguments[0]
       if (!(ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) || !ts.isBlock(callback.body)) throw sourceNodeError(callback, sourceFile, "Animation frame refs require one inline block-bodied effect")
-      if (accesses.some(access => !inside(access, callback))) throw sourceNodeError(node, sourceFile, "Animation frame refs may only be used inside their owning effect")
+      if (accesses.some(access => !isNodeWithin(access, callback))) throw sourceNodeError(node, sourceFile, "Animation frame refs may only be used inside their owning effect")
       const callbacks = new Map()
       for (const statement of callback.body.statements) {
         if (ts.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) {

package/framework/compiler/handler-lowering.mjs

@@ -15,23 +15,22 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
       const visitor = node => {
         if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && reducers.has(node.expression.text) && matchesExternalReference(node.expression, expression, bindingIndex)) {
           const reducer = reducers.get(node.expression.text)
-          if (reducer.contextAction) {
-            const action = synthesizeTree(cloneAst(reducer.contextAction, factory, context))
-            const call = factory.createCallExpression(action, undefined, node.arguments)
+          if (reducer.directImplementation) {
+            const call = factory.createCallExpression(synthesizeTree(cloneAst(reducer.directImplementation, factory, context)), undefined, node.arguments.map(argument => ts.visitNode(argument, visitor)))
             ts.setParentRecursive(call, false)
             return ts.visitNode(call, visitor)
           }
-          if (reducer.sharedAction) return sharedActionDispatch(factory, reducer, node.arguments.map(argument => ts.visitNode(argument, visitor)))
+          if (reducer.sharedAction) return sharedActionDispatch(factory, reducer, node.arguments.map(argument => ts.visitNode(argument, visitor)), visitor, context)
           if (node.arguments.length !== 1) throw sourceNodeError(node, expression.getSourceFile(), "Reducer dispatches require exactly one action")
           return reducerDispatch(factory, reducer, ts.visitNode(node.arguments[0], visitor))
         }
         if (ts.isShorthandPropertyAssignment(node) && reducers.has(node.name.text) && matchesExternalReference(node.name, expression, bindingIndex)) {
-          if (reducers.get(node.name.text).contextAction) throw sourceNodeError(node, expression.getSourceFile(), "Context actions must be called directly inside an event handler")
+          if (reducers.get(node.name.text).directImplementation) throw sourceNodeError(node, expression.getSourceFile(), `${reducers.get(node.name.text).sourceKind} actions must be called directly inside an event handler`)
           if (reducers.get(node.name.text).sharedAction) throw sourceNodeError(node, expression.getSourceFile(), `${reducers.get(node.name.text).sourceKind} actions must be called directly inside an event handler`)
           return factory.createPropertyAssignment(node.name, reducerReference(factory, reducers.get(node.name.text)))
         }
         if (ts.isIdentifier(node) && reducers.has(node.text) && isReferenceIdentifier(node) && matchesExternalReference(node, expression, bindingIndex)) {
-          if (reducers.get(node.text).contextAction) throw sourceNodeError(node, expression.getSourceFile(), "Context actions must be called directly inside an event handler")
+          if (reducers.get(node.text).directImplementation) throw sourceNodeError(node, expression.getSourceFile(), `${reducers.get(node.text).sourceKind} actions must be called directly inside an event handler`)
           if (reducers.get(node.text).sharedAction) throw sourceNodeError(node, expression.getSourceFile(), `${reducers.get(node.text).sourceKind} actions must be called directly inside an event handler`)
           return reducerReference(factory, reducers.get(node.text))
         }
@@ -162,7 +161,13 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
     return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"), undefined, [factory.createStringLiteral(reducer.state), update])
   }
 
-  function sharedActionDispatch(factory, reducer, args) {
+  function sharedActionDispatch(factory, reducer, args, visitor, context) {
+    const direct = reducer.sharedAction.directImplementation
+    if (direct) {
+      const call = factory.createCallExpression(synthesizeTree(cloneAst(direct, factory, context)), undefined, args)
+      ts.setParentRecursive(call, false)
+      return ts.visitNode(call, visitor)
+    }
     const previous = factory.createUniqueName("__kPrevious")
     const current = factory.createUniqueName("__kStore")
     const updateValue = factory.createUniqueName("__kUpdate")

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

@@ -40,7 +40,13 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
       indexed(`Component specialization ${specialization.slot} ref`, specialization.refs)
       indexed(`Component specialization ${specialization.slot} ID`, specialization.ids)
       if (specialization.owner !== undefined) ownerRef(specialization.owner, `Component specialization ${specialization.slot} owner`)
-      for (const prop of specialization.props ?? []) for (const signal of prop.signals ?? []) slot(moduleIR.signals, signal, `Component specialization ${specialization.slot} prop ${JSON.stringify(prop.name)}`, "SignalIR")
+      for (const prop of specialization.props ?? []) {
+        for (const signal of prop.signals ?? []) slot(moduleIR.signals, signal, `Component specialization ${specialization.slot} prop ${JSON.stringify(prop.name)}`, "SignalIR")
+        for (const property of prop.properties ?? []) {
+          slot(moduleIR.signals, property.signal, `Component specialization ${specialization.slot} prop ${JSON.stringify(prop.name)} property`, "SignalIR")
+          if (!(prop.signals ?? []).includes(property.signal) || !Array.isArray(property.path) || property.path.length !== 1 || property.path.some(segment => typeof segment !== "string" || !segment || ["__proto__", "constructor", "prototype"].includes(segment)) || !Array.isArray(property.consumers) || !property.consumers.length || property.consumers.some(consumer => !["binding", "effect", "list"].includes(consumer)) || property.equality !== "object-is") throw new Error(`Component specialization ${specialization.slot} prop ${JSON.stringify(prop.name)} has an invalid property link`)
+        }
+      }
     }
   }
   function moduleSymbol(symbol, label) {
@@ -86,17 +92,32 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
     for (const [index, signal] of (binding.signals ?? []).entries()) slot(moduleIR.signals, signal, `BindingIR ${binding.slot} signal ${index}`, "SignalIR")
     for (const [index, imported] of (binding.imports ?? []).entries()) slot(moduleIR.imports, imported, `BindingIR ${binding.slot} import ${index}`, "ImportIR")
     for (const [index, capture] of (binding.captures ?? []).entries()) if (capture.symbol !== undefined) slot(moduleIR.symbols, capture.symbol, `BindingIR ${binding.slot} capture ${index}`, "SymbolRef")
+    if (binding.derived) {
+      const derived = slot(moduleIR.derived, binding.derived.derived, `BindingIR ${binding.slot} derived value`, "DerivedIR")
+      if (derived.kind !== "calculation" || !Array.isArray(binding.derived.fields) || !binding.derived.fields.length || binding.derived.fields.some(field => !derived.calculation.fields.includes(field))) throw new Error(`BindingIR ${binding.slot} has invalid calculation fields`)
+    }
     if (binding.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, binding.keyedBlock, `BindingIR ${binding.slot} keyed block`, "KeyedBlockIR")
   }
-  for (const derived of moduleIR.derived) for (const [index, signal] of (derived.signals ?? []).entries()) slot(moduleIR.signals, signal, `DerivedIR ${derived.slot} signal ${index}`, "SignalIR")
+  for (const derived of moduleIR.derived) {
+    for (const [index, signal] of (derived.signals ?? []).entries()) slot(moduleIR.signals, signal, `DerivedIR ${derived.slot} signal ${index}`, "SignalIR")
+    if (derived.kind === "calculation") {
+      const binding = slot(moduleIR.bindings, derived.calculation?.binding, `DerivedIR ${derived.slot} calculation`, "BindingIR")
+      if (binding.kind !== "module-export") throw new Error(`DerivedIR ${derived.slot} calculation must use a module-export BindingIR`)
+      if (!Array.isArray(derived.calculation?.fields) || !derived.calculation.fields.length || derived.calculation.fields.some(field => typeof field !== "string" || !field || ["__proto__", "constructor", "prototype"].includes(field))) throw new Error(`DerivedIR ${derived.slot} calculation has invalid fields`)
+    }
+  }
   for (const effect of moduleIR.effects) {
     const handler = slot(moduleIR.handlers, effect.setup?.handler, `EffectIR ${effect.slot} setup`, "HandlerIR")
     if (handler.kind !== "module-export" || handler.role !== "effect") throw new Error(`EffectIR ${effect.slot} setup HandlerIR ${handler.slot} must have role "effect"`)
     for (const [index, dependency] of (effect.dependencies ?? []).entries()) {
       if (dependency.kind === "signal") slot(moduleIR.signals, dependency.signal, `EffectIR ${effect.slot} dependency ${index}`, "SignalIR")
       else if (dependency.kind === "derived") {
-        slot(moduleIR.derived, dependency.derived, `EffectIR ${effect.slot} dependency ${index}`, "DerivedIR")
+        const derived = slot(moduleIR.derived, dependency.derived, `EffectIR ${effect.slot} dependency ${index}`, "DerivedIR")
         for (const [sourceIndex, signal] of (dependency.sources ?? []).entries()) slot(moduleIR.signals, signal, `EffectIR ${effect.slot} dependency ${index} source ${sourceIndex}`, "SignalIR")
+        if (dependency.evaluator !== undefined || dependency.field !== undefined) {
+          if (derived.kind !== "calculation" || dependency.evaluator !== derived.calculation.binding) throw new Error(`EffectIR ${effect.slot} dependency ${index} must use its calculation evaluator`)
+          if (!derived.calculation.fields.includes(dependency.field)) throw new Error(`EffectIR ${effect.slot} dependency ${index} references unknown calculation field ${JSON.stringify(dependency.field)}`)
+        }
       } else throw new Error(`EffectIR ${effect.slot} dependency ${index} has invalid kind ${JSON.stringify(dependency.kind)}`)
     }
     for (const [index, signal] of (effect.subscriptions ?? []).entries()) slot(moduleIR.signals, signal, `EffectIR ${effect.slot} subscription ${index}`, "SignalIR")
@@ -172,11 +193,12 @@ export function registerSharedAction(moduleIR, descriptor) {
   return action
 }
 
-export function registerCommandHandler(moduleIR, commands, source) {
+export function registerCommandHandler(moduleIR, commands, source, actions = []) {
   const handler = {
     slot: moduleIR.handlers.length,
     kind: "commands",
     commands: commands.map(({ operation, reference, state, value, syntax }) => ({ operation, signal: registerSignal(moduleIR, reference, state).slot, value, ...(syntax ? { syntax } : {}) })),
+    ...(actions.length ? { actions } : {}),
     ...(source ? { source } : {})
   }
   moduleIR.handlers.push(handler)

package/framework/compiler/list-runtime-codegen.mjs

@@ -43,7 +43,8 @@ export function generateListRuntime(source, capabilityIR) {
     ["if (__KUDZU_LIST_ROW_HOOKS__) initializeRowStates(list.descriptor, key, node, list.owner, item)", "if (__KUDZU_LIST_ROW_HOOKS__ && list.descriptor.rowStates) initializeRowStates(list.descriptor, key, node)", "flat row add", true],
     ["for (const node of registration.list.roots.values()) deleteRowStates(registration.list.descriptor, ownershipPaths.get(node))", "for (const token of registration.list.roots.keys()) deleteFlatRowStates(registration.list.descriptor, token)", "flat registration cleanup"],
     ["deleteRowStates(list.descriptor, ownershipPaths.get(node))", "deleteFlatRowStates(list.descriptor, token)", "flat row cleanup", true],
-    ["  if (__KUDZU_LIST_ROW_HOOKS__) replaceRowIds(root, rowReplacements.get(root))\n", "", "row ID replacement"],
+    ["const directRowReplacements = __KUDZU_LIST_ROW_HOOKS__ ? new WeakSet() : undefined\n", "", "direct row replacement storage"],
+    ["  if (__KUDZU_LIST_ROW_HOOKS__) replaceOwnedRowIds(root)\n", "", "row ID replacement"],
     ["  if (!replacements) return\n", "", "row replacement guard"]
   ])
   if (!effects.itemDependencies) runtime = replaceRequired(runtime, ", notifyListItem", "", "item notification import")
@@ -67,11 +68,12 @@ export function generateListRuntime(source, capabilityIR) {
       __KUDZU_LIST_EXPRESSIONS__: String(lists.expressions),
       __KUDZU_LIST_EXPRESSION_ATTRIBUTES__: String(lists.expressionAttributes),
       __KUDZU_LIST_SEEDS__: String(lists.seeds),
-      __KUDZU_LIST_EFFECTS__: String(lists.effects),
+      __KUDZU_LIST_EFFECTS__: String(effects.itemDependencies),
       __KUDZU_LIST_ASYNC_PARTS__: String(lists.asyncParts),
       __KUDZU_LIST_MOUNTS__: String(lists.mounts),
       __KUDZU_LIST_ITEM_HOOKS__: String(effects.itemDependencies),
       __KUDZU_LIST_ROW_HOOKS__: String(lists.rowHooks),
+      __KUDZU_GENERAL_ROW_HOOKS__: String(lists.generalRowHooks),
       __KUDZU_LIST_ROW_REFS__: String(lists.rowRefs),
       __KUDZU_COMPLEX_LIST_ROW_STATE__: String(lists.complexRowState),
       __KUDZU_NESTED_LISTS__: String(lists.nested),

package/framework/compiler/optimize/command-specialization.mjs

@@ -1,5 +1,5 @@
 import ts from "typescript"
-import { sourceNodeError } from "../ast-helpers.mjs"
+import { isNodeWithin, sourceNodeError } from "../ast-helpers.mjs"
 
 export function createCommandSpecializer({ isPrimitiveLiteral }) {
   const specialize = (expression, setters) => {
@@ -12,6 +12,8 @@ export function createCommandSpecializer({ isPrimitiveLiteral }) {
     const value = expression.arguments[0]
     if (ts.isBinaryExpression(value) && ts.isIdentifier(value.left) && value.left.text === state) return addCommand(state, value)
     if (ts.isArrowFunction(value) && value.parameters.length === 1 && ts.isIdentifier(value.parameters[0].name) && ts.isBinaryExpression(value.body) && ts.isIdentifier(value.body.left) && value.body.left.text === value.parameters[0].name.text) return addCommand(state, value.body)
+    if (ts.isPrefixUnaryExpression(value) && value.operator === ts.SyntaxKind.ExclamationToken && ts.isIdentifier(value.operand) && value.operand.text === state) return { operation: "toggle", state, value: false }
+    if (ts.isArrowFunction(value) && value.parameters.length === 1 && ts.isIdentifier(value.parameters[0].name) && ts.isPrefixUnaryExpression(value.body) && value.body.operator === ts.SyntaxKind.ExclamationToken && ts.isIdentifier(value.body.operand) && value.body.operand.text === value.parameters[0].name.text) return { operation: "toggle", state, value: false }
     if (isPrimitiveLiteral(value)) {
       const literal = primitiveValue(value)
       return literal ? { operation: "set", state, ...literal } : undefined
@@ -95,7 +97,7 @@ function rejectUnsafe(statements, boundary, setters, bindingIndex) {
     const helper = helperDeclaration(statement, boundary, setters, bindingIndex)
     if (!helper) continue
     const uses = refs(boundary, helper.name, boundary, bindingIndex)
-    if (uses.some(reference => inside(reference, helper.body))) fail(helper.name, "Semantic state helpers cannot be recursive")
+    if (uses.some(reference => isNodeWithin(reference, helper.body))) fail(helper.name, "Semantic state helpers cannot be recursive")
     if (helper.mutable || uses.some(mutated)) fail(helper.name, "Semantic state helpers must remain immutable")
     if (uses.some(dynamic)) fail(uses.find(dynamic), "Semantic state helpers do not support dynamic dispatch")
     if (uses.length !== 1 || !directIdentifierCall(uses[0])) fail(uses.find(reference => !directIdentifierCall(reference)) ?? helper.name, "Semantic state helpers must be called exactly once and cannot escape")
@@ -191,11 +193,6 @@ function mutated(identifier) {
   return ts.isPrefixUnaryExpression(parent) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(parent.operator) || ts.isPostfixUnaryExpression(parent) || ts.isBinaryExpression(parent) && parent.left === identifier && parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment
 }
 
-function inside(node, root) {
-  for (let current = node; current; current = current.parent) if (current === root) return true
-  return false
-}
-
 function fail(node, message) {
   throw sourceNodeError(node, node.getSourceFile(), message)
 }

package/framework/compiler/route-artifact-report.mjs

@@ -18,7 +18,8 @@ export function createRouteArtifactReport(records, {
   if (!runtimeFamilies || !runtimeFamilyByRecord) ({ families: runtimeFamilies, familyByRecord: runtimeFamilyByRecord } = planRuntimeFamilies(records))
   const handlerGraph = handlerMetafile ? outputGraph(handlerMetafile, outputDirectory, base) : new Map()
   const routes = records.map(record => {
-    const capability = planRouteCapabilities([record], { navigationRouteCount: Number(record.capabilities.navigable) })
+    const family = runtimeFamilyByRecord.get(record)
+    const capability = family && !family.navigation ? family.capability : planRouteCapabilities([record], { navigationRouteCount: Number(record.capabilities.navigable) })
     const handlerEntries = [...new Set(record.artifacts.handlers.map(reference => reference.module))].sort()
     const handlerOutputs = closure(handlerEntries, handlerGraph, Boolean(handlerMetafile))
     const workers = workerReferences
@@ -35,7 +36,7 @@ export function createRouteArtifactReport(records, {
         signature: capabilitySignature(capability),
         manifest: capability
       },
-      runtime: routeRuntimeEdges(record, capability, runtimeFamilyByRecord.get(record), base, navigationAssets.get(record.route)),
+      runtime: routeRuntimeEdges(record, capability, family, base, navigationAssets.get(record.route)),
       handlers: {
         entries: handlerEntries,
         chunks: handlerOutputs.filter(output => !handlerEntries.includes(output))
@@ -58,7 +59,7 @@ export function createRouteArtifactReport(records, {
       id: family.id,
       signature: family.signature,
       navigation: family.navigation,
-      routes: records.filter(record => runtimeFamilyByRecord.get(record)?.id === family.id).map(record => record.route).sort(),
+      routes: family.records.map(record => record.route).sort(),
       manifest: family.capability,
       requirements: familyRuntimeRequirements(family, base)
     })),