@kudzujs/core 0.8.20 → 0.8.22

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, registerKeyedBlock, 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) }
@@ -160,6 +160,10 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     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) {
@@ -210,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]
@@ -223,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, registerKeyedBlock: registerKeyedBlockResult }
+  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: [], keyedBlocks: [], imports: [], clientModules: [] }
+  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
 }
 
 export function registerCommandHandler(moduleIR, commands, source, scope = "module") {
@@ -40,6 +40,12 @@ export function registerDerived(moduleIR, descriptor) {
   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)

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

@@ -0,0 +1,95 @@
+import { assertCapabilityIR } from "./route-capability-planner.mjs"
+
+export function generateListRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  const { lists, effects } = capabilityIR
+  let runtime = replaceRequired(source, '"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import")
+  runtime = lists.calculated
+    ? replaceRequired(runtime, '"./binding-runtime.js"', '"./kudzu-binding.js"', "binding runtime import")
+    : replaceRequired(runtime, /^const loadListEvaluator[^\n]+\n/m, "", "list evaluator loader")
+  runtime = lists.selectors
+    ? replaceRequired(runtime, '"./collection-selector.js"', '"./kudzu-collection-selector.js"', "collection selector import")
+    : replaceRequired(runtime, /^import \{ selectCollection \}[^\n]+\n/m, "", "collection selector import")
+  if (!lists.indexes) {
+    runtime = replaceSequenceRequired(runtime, [
+      ["for (const [index, item] of items.entries()) {", "for (const item of items) {", "item iteration"],
+      ["const key = list.descriptor.key === null ? index : item?.[list.descriptor.key]", "const key = item?.[list.descriptor.key]", "index key"],
+      ["entries.push({ item, index, key, token, value:", "entries.push({ item, key, token, value:", "indexed entry"],
+      ["for (const { item, index, key, token, value } of entries) {", "for (const { item, key, token, value } of entries) {", "indexed entry loop"],
+      ["fillListItem(node, item, list.descriptor.nested, index)", "fillListItem(node, item, list.descriptor.nested)", "indexed item fill", true],
+      ["fillListItem(node, item, list.descriptor.nested, index, mapListItemParts", "fillListItem(node, item, list.descriptor.nested, 0, mapListItemParts", "mapped item fill"],
+      ["function addListRoot(list, { item, index = list.roots.size, key, token, value })", "function addListRoot(list, { item, key, token, value })", "indexed list root"],
+      ["fillListParts(root, listItemParts(root), listItems.get(owner), 0, __KUDZU_LIST_INDEXES__ ? listIndexes.get(owner) ?? 0 : 0)", "fillListParts(root, listItemParts(root), listItems.get(owner), 0)", "indexed root parts"],
+      ["fillListParts(root, parts, item, revision, index, previous)", "fillListParts(root, parts, item, revision, previous)", "indexed fill call"],
+      ["function fillListParts(root, parts, item, revision, index = 0, previous)", "function fillListParts(root, parts, item, revision, previous)", "indexed parts signature"],
+      ["fillListExpressions(root, parts, item, revision, index)", "fillListExpressions(root, parts, item, revision)", "indexed expressions"],
+      ['value?.type === "list-item" ? serializeItem(item) : value?.type === "list-index" ? index : value', 'value?.type === "list-item" ? serializeItem(item) : value', "index capture", true],
+      ["evaluate(descriptor, item, index)", "evaluate(descriptor, item)", "indexed evaluator", true],
+      ["updateListCondition(marker, descriptor.kind, value, item, index)", "updateListCondition(marker, descriptor.kind, value, item)", "indexed condition"],
+      ["function updateListCondition(marker, kind, value, item, index)", "function updateListCondition(marker, kind, value, item)", "indexed condition signature"],
+      ["fillListParts(marker, listItemParts(fragment), item, revision, index)", "fillListParts(marker, listItemParts(fragment), item, revision)", "indexed condition parts"],
+      ["exports[descriptor.handler](item, index, {", "exports[descriptor.handler](item, undefined, {", "indexed state handler call"]
+    ])
+  }
+  if (!lists.selectors) runtime = replaceRequired(runtime, " && !list.descriptor.selector", "", "selector guards", true)
+  if (!lists.indexes) runtime = replaceSequenceRequired(runtime, [
+    [" && !list.descriptor.indexed", "", "indexed guards", true],
+    [" && list.descriptor.key !== null", "", "key guards", true],
+    ["(referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value) || list.descriptor.indexed || list.descriptor.key === null", "referenceOnly ? listItems.get(node) !== item : list.values.get(token) !== value", "indexed value comparison"]
+  ])
+  if (lists.rowHooks && !lists.generalRowHooks) runtime = replaceSequenceRequired(replaceRequired(runtime, /\/\* general-row-hooks \*\/[\s\S]*?\/\* general-row-hooks-end \*\/\n/, "", "general row hooks"), [
+    ["initializeGeneralRowHooks", "initializeRowStates", "general row initializer", true],
+    ["if (__KUDZU_LIST_ROW_HOOKS__) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index], roots[index], nested?.owner)", "if (__KUDZU_LIST_ROW_HOOKS__ && descriptor.rowStates) for (let index = 0; index < roots.length; index++) initializeRowStates(descriptor, descriptor.keys[index])", "flat row initialization"],
+    ["if (__KUDZU_LIST_ROW_HOOKS__) initializeRowStates(list.descriptor, key, node, list.owner)", "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"],
+    ["  if (!replacements) return\n", "", "row replacement guard"]
+  ])
+  if (!effects.itemDependencies) runtime = replaceRequired(runtime, ", notifyListItem", "", "item notification import")
+  if (!lists.stableFastPaths) runtime = replaceRequired(runtime, /\/\* stable-list-fast-path \*\/[\s\S]*?\/\* stable-list-fast-path-end \*\/\n/, "", "stable list fast path")
+  const stylePatch = `  if (target === "style") {
+    const style = serializeStyle(value)
+    if (style) node.setAttribute("style", style)
+    else node.removeAttribute("style")
+    return
+  }`
+  runtime = replaceRequired(runtime, "  /* list-style */", lists.styleCount ? stylePatch : "", "list style")
+  if (lists.styleCount) runtime = `import { serializeStyle } from "./kudzu-style.js"\n${runtime}`
+  return {
+    source: runtime,
+    define: {
+      __KUDZU_LIST_CONDITIONS__: String(lists.conditions),
+      __KUDZU_DEEP_LIST_CONDITIONS__: String(lists.deepConditions),
+      __KUDZU_LIST_TEXT_RANGES__: String(lists.textRanges),
+      __KUDZU_LIST_ATTRIBUTES__: String(lists.attributes),
+      __KUDZU_LIST_EVENTS__: String(lists.events),
+      __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_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_LIST_ROW_REFS__: String(lists.rowRefs),
+      __KUDZU_COMPLEX_LIST_ROW_STATE__: String(lists.complexRowState),
+      __KUDZU_NESTED_LISTS__: String(lists.nested),
+      __KUDZU_COLLECTION_SELECTORS__: String(lists.selectors),
+      __KUDZU_STATIC_COLLECTIONS__: String(lists.static),
+      __KUDZU_LIST_INDEXES__: String(lists.indexes),
+      __KUDZU_LIST_STABLE_FAST_PATHS__: String(lists.stableFastPaths),
+      __KUDZU_SVG_LISTS__: String(lists.svg)
+    }
+  }
+}
+
+function replaceRequired(source, search, replacement, label, all = false) {
+  const output = all ? source.replaceAll(search, replacement) : source.replace(search, replacement)
+  if (output === source) throw new Error(`${label} specialization did not match list-runtime.js`)
+  return output
+}
+
+function replaceSequenceRequired(source, replacements) {
+  return replacements.reduce((output, [search, replacement, label, all]) => replaceRequired(output, search, replacement, label, all), source)
+}

package/framework/compiler/param-codegen.mjs

@@ -0,0 +1,72 @@
+import { join } from "node:path"
+
+export function createParamCodegen({ browserPath, inlineJson, relativeModulePath }) {
+  return function printParamEntry(schema, params, searchParams, searchParamsWritable, output, assetsDirectory, base, runtimeName, navigable) {
+    const hasSearch = searchParams.length || searchParamsWritable
+    const signature = hasSearch ? "pathname, search" : "pathname"
+    const prefix = navigable ? `export function initializeParams(${signature}) {\n${searchParamsWritable ? "globalThis.__kSetSearchParams = setSearchParams\n" : ""}` : `${schema ? "let pathname = location.pathname\n" : ""}${hasSearch ? "let search = location.search\n" : ""}`
+    const suffix = navigable ? "\n}" : ""
+    const pathname = schema ? `const base = ${inlineJson(browserPath(base).slice(1).split("/").filter(Boolean).map(segment => decodeURIComponent(segment)))}
+const schema = ${inlineJson(schema.segments)}
+const params = ${inlineJson(params)}
+let path = pathname
+if (base.length) {
+  const pathSegments = path.slice(1).split("/")
+  if (pathSegments.length < base.length || base.some((segment, index) => decodeSegment(pathSegments[index], false) !== segment)) throw new Error("Runtime route is outside the configured base")
+  path = "/" + pathSegments.slice(base.length).join("/")
+}
+if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
+const segments = path.slice(1).split("/")
+if (segments.length !== schema.length) throw new Error("Runtime route does not match its fallback pattern")
+const values = Object.create(null)
+for (let index = 0; index < schema.length; index++) {
+  const segment = schema[index]
+  const value = decodeSegment(segments[index], Boolean(segment.param))
+  if (segment.literal !== undefined && value !== segment.literal) throw new Error("Runtime route literal does not match")
+  if (segment.param) values[segment.param] = value
+}
+for (const param of params) {
+  const value = values[param.name]
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+function decodeSegment(raw, param) {
+  if (param && /%(?:2f|5c)/i.test(raw)) throw new Error("Runtime route parameter contains an encoded separator")
+  let value
+  try { value = decodeURIComponent(raw) } catch { throw new Error("Runtime route parameter has malformed encoding") }
+  const decodedDots = value.replace(/%2e/gi, ".")
+  if (param && (!value || value === "." || value === ".." || decodedDots === "." || decodedDots === ".." || /[\\/?#]/.test(value) || [...value].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159) || /%(?:2f|5c)/i.test(value))) throw new Error("Runtime route parameter is invalid")
+  return value
+}
+` : ""
+    const searchInitializer = searchParamsWritable && searchParams.length ? `function initializeSearch(search) {
+const query = new URLSearchParams(search)
+for (const param of ${inlineJson(searchParams)}) {
+  const value = query.get(param.name)
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+}
+` : ""
+    const query = searchParams.length ? searchParamsWritable ? "initializeSearch(search)\n" : `const query = new URLSearchParams(search)
+for (const param of ${inlineJson(searchParams)}) {
+  const value = query.get(param.name)
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+` : ""
+    const writer = searchParamsWritable ? `
+function setSearchParams(update, replace) {
+  const next = update(new URLSearchParams(location.search))
+  if (!(next instanceof URLSearchParams)) throw new Error("React Router search parameter updater must return URLSearchParams")
+  const url = new URL(location.href)
+  url.search = next.toString()
+  history[replace ? "replaceState" : "pushState"](null, "", url)
+  ${searchParams.length ? "initializeSearch(location.search)" : ""}
+}
+${navigable ? "" : `globalThis.__kSetSearchParams = setSearchParams
+addEventListener("popstate", () => ${searchParams.length ? "initializeSearch(location.search)" : "undefined"})`}` : ""
+    return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
+${searchInitializer}${prefix}${pathname}${query}${suffix}${writer}`
+  }
+}

package/framework/compiler/route-capability-planner.mjs

@@ -1,9 +1,11 @@
 export function usesRouteDependencyRuntime({ plan, navigable, hasBindings, hasLists }) {
+  assertRouteIR(plan)
   const hasDependencies = plan.effects.some(effect => effect.dependencies?.length)
   return !navigable && hasDependencies && !plan.effects.some(effect => effect.owner) && !hasBindings && !hasLists && !plan.events.some(event => event.native)
 }
 
 export function planRouteCapabilities(plans, { routes = new Map(), navigationRouteCount = 0 } = {}) {
+  for (const plan of plans) assertRouteIR(plan)
   const commandEvents = new Set()
   const nativeEvents = new Set()
   const bindings = { count: 0, text: false, svgConditions: false }
@@ -90,6 +92,7 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
   lists.mounts ||= lists.conditions || lists.nested
 
   return {
+    version: 1,
     routes: routeCounts,
     events: { command: [...commandEvents].sort(), native: [...nativeEvents].sort(), hasNativeHandlers: nativeEvents.size > 0 },
     bindings,
@@ -103,6 +106,38 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
   }
 }
 
+function assertRouteIR(plan) {
+  if (plan?.version !== 1) throw new Error(`Unsupported RouteIR version: ${JSON.stringify(plan?.version)}`)
+  if (!["states", "params", "searchParams", "events", "effects", "bindings", "conditions", "lists"].every(name => Array.isArray(plan[name])) || typeof plan.searchParamsWritable !== "boolean") throw new Error("Invalid RouteIR v1 structure")
+  if (plan.states.some((state, slot) => state?.slot !== slot || typeof state.id !== "string" || typeof state.name !== "string" || !Object.hasOwn(state, "initialValue") || state.lifetime !== undefined && !["layout", "route"].includes(state.lifetime) || state.internal !== undefined && state.internal !== true)) throw new Error("Invalid RouteIR v1 state")
+  if ([...plan.params, ...plan.searchParams].some(param => !isRecord(param) || typeof param.name !== "string" || typeof param.id !== "string")) throw new Error("Invalid RouteIR v1 parameter")
+  if (plan.events.some(event => !isRecord(event) || typeof event.event !== "string" || event.commands !== undefined && (!Array.isArray(event.commands) || event.commands.some(command => !Array.isArray(command))) || event.native !== undefined && (!isRecord(event.native) || typeof event.native.module !== "string" || typeof event.native.handler !== "string" || !isRecord(event.native.states) || !isRecord(event.native.scope)))) throw new Error("Invalid RouteIR v1 event")
+  if (plan.effects.some(effect => !isRecord(effect) || typeof effect.module !== "string" || typeof effect.handler !== "string" || !isRecord(effect.states) || !isRecord(effect.scope))) throw new Error("Invalid RouteIR v1 effect")
+  if (plan.bindings.some(binding => !isRecord(binding) || typeof binding.target !== "string") || plan.conditions.some(condition => !isRecord(condition) || condition.svg !== undefined && typeof condition.svg !== "boolean") || plan.lists.some(list => !isRouteList(list))) throw new Error("Invalid RouteIR v1 binding, condition, or list")
+}
+
+export function assertCapabilityIR(capabilityIR) {
+  if (capabilityIR?.version !== 1) throw new Error(`Unsupported CapabilityIR version: ${JSON.stringify(capabilityIR?.version)}`)
+  const sections = ["routes", "events", "bindings", "lists", "effects", "captures", "runtime"]
+  if (!sections.every(name => isRecord(capabilityIR[name]))) throw new Error("Invalid CapabilityIR v1 structure")
+  if (!["behaviors", "regularBehaviors", "regularStateSeeds", "dependencyStateSeeds"].every(name => isCount(capabilityIR.routes[name]))) throw new Error("Invalid CapabilityIR v1 route counts")
+  if (!["command", "native"].every(name => Array.isArray(capabilityIR.events[name]) && capabilityIR.events[name].every(event => typeof event === "string")) || typeof capabilityIR.events.hasNativeHandlers !== "boolean") throw new Error("Invalid CapabilityIR v1 events")
+  if (!isCount(capabilityIR.bindings.count) || !["text", "svgConditions"].every(name => typeof capabilityIR.bindings[name] === "boolean")) throw new Error("Invalid CapabilityIR v1 bindings")
+  const listFlags = ["conditions", "svg", "deepConditions", "textRanges", "attributes", "events", "expressions", "expressionAttributes", "seeds", "effects", "rowHooks", "rowRefs", "complexRowState", "nested", "selectors", "calculated", "static", "indexes", "stableFastPaths", "generalRowHooks", "asyncParts", "mounts"]
+  if (!isCount(capabilityIR.lists.count) || !isCount(capabilityIR.lists.styleCount) || !listFlags.every(name => typeof capabilityIR.lists[name] === "boolean")) throw new Error("Invalid CapabilityIR v1 lists")
+  if (!["any", "derivedDependencies", "itemDependencies", "captures", "navigable", "navigableOwners"].every(name => typeof capabilityIR.effects[name] === "boolean") || !["nestedState", "setter"].every(name => typeof capabilityIR.captures[name] === "boolean") || !["shared", "dependency"].every(name => typeof capabilityIR.runtime[name] === "boolean")) throw new Error("Invalid CapabilityIR v1 effect, capture, or runtime flags")
+}
+
+const isRecord = value => value !== null && typeof value === "object" && !Array.isArray(value)
+const isCount = value => Number.isSafeInteger(value) && value >= 0
+const isRouteList = list => isRecord(list)
+  && typeof list.id === "string"
+  && typeof list.state === "string"
+  && (typeof list.key === "string" || list.key === null)
+  && Array.isArray(list.keys)
+  && ["svg", "static", "indexed", "reducer", "mount", "nested", "effects", "conditions", "conditionHandlers", "textRanges", "attributes", "events", "expressions", "expressionAttributes", "fastRelease"].every(name => list[name] === undefined || list[name] === true)
+  && ["selector", "children", "expressionStates", "rowStates", "rowConditions", "rowRefs"].every(name => list[name] === undefined || Array.isArray(list[name]))
+
 function hasCaptureType(value, type) {
   if (!value || typeof value !== "object") return false
   if (value.type === type) return true

package/framework/compiler/runtime-codegen.mjs

@@ -0,0 +1,146 @@
+import { assertCapabilityIR } from "./route-capability-planner.mjs"
+
+export function generateCoreRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  const { effects, events, routes } = capabilityIR
+  let runtime = specializeRuntime(source, events.command, routes.regularStateSeeds > 0)
+  if (!effects.itemDependencies && capabilityIR.runtime.shared) runtime = replaceRequired(runtime, /\/\* list-item-hooks \*\/[\s\S]*?\/\* list-item-hooks-end \*\/\n/, "", "list item hooks", "shared-runtime.js")
+  if (effects.navigable) runtime = replaceRequired(runtime, "export function registerCommitter(commit) {\n  committers.push(commit)\n}", "export function registerCommitter(commit) {\n  committers.push(commit)\n  return () => {\n    const index = committers.indexOf(commit)\n    if (index !== -1) committers.splice(index, 1)\n  }\n}", "navigable committer", "shared-runtime.js")
+  if (effects.navigableOwners) runtime = replaceSequenceRequired(runtime, [
+    ["export function registerMountHook(mount) {\n  mountHooks.push(mount)\n}", "export function registerMountHook(mount) {\n  mountHooks.push(mount)\n  return () => {\n    const index = mountHooks.indexOf(mount)\n    if (index !== -1) mountHooks.splice(index, 1)\n  }\n}", "navigable mount hook"],
+    ["export function registerUnmountHook(unmount) {\n  unmountHooks.push(unmount)\n}", "export function registerUnmountHook(unmount) {\n  unmountHooks.push(unmount)\n  return () => {\n    const index = unmountHooks.indexOf(unmount)\n    if (index !== -1) unmountHooks.splice(index, 1)\n  }\n}", "navigable unmount hook"]
+  ], "shared-runtime.js")
+  return runtime
+}
+
+export function generateEffectRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  const { captures, effects } = capabilityIR
+  return {
+    source: effects.captures ? replaceRequired(source, '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "effect-runtime.js") : replaceRequired(source, /^import[^\n]+\n/, "", "serialization import", "effect-runtime.js"),
+    define: {
+      "globalThis.__KUDZU_CAPTURE_SETTER__": String(captures.setter),
+      "globalThis.__KUDZU_EFFECT_CAPTURES__": String(effects.captures)
+    }
+  }
+}
+
+export function generateBindingRuntime(source, capabilityIR, navigable) {
+  assertCapabilityIR(capabilityIR)
+  let runtime = replaceRequired(source, '"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import", "binding-runtime.js")
+  runtime = replaceRequired(runtime, '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "binding-runtime.js")
+  runtime = replaceRequired(runtime, '"./style.js"', '"./kudzu-style.js"', "style import", "binding-runtime.js")
+  if (navigable) runtime = specializeNavigationTextDescriptors(runtime)
+  return {
+    source: runtime,
+    define: {
+      "globalThis.__KUDZU_TEXT_BINDINGS__": String(capabilityIR.bindings.text),
+      "globalThis.__KUDZU_SVG_CONDITIONS__": String(capabilityIR.bindings.svgConditions),
+      "globalThis.__KUDZU_CAPTURE_STATE__": String(capabilityIR.captures.nestedState)
+    }
+  }
+}
+
+export function generateNativeRuntime(source, capabilityIR) {
+  assertCapabilityIR(capabilityIR)
+  return {
+    source: specializeEvents(replaceRequired(replaceRequired(source, '"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import", "native-runtime.js"), '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "native-runtime.js"), capabilityIR.events.native),
+    define: { "globalThis.__KUDZU_CAPTURE_SETTER__": String(capabilityIR.captures.setter) }
+  }
+}
+
+export function generateNavigationRuntime(source, group) {
+  let runtime = replaceSequenceRequired(source, [
+    ["__KUDZU_NAVIGATION_ROUTES__", JSON.stringify(group.records).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029"), "route records"],
+    ["__KUDZU_APPLICATION_ID__", JSON.stringify(group.applicationId), "application ID"],
+    ["__KUDZU_LAYOUT_ID__", JSON.stringify(group.layoutId), "layout ID"],
+    ['"./shared-runtime.js"', '"./kudzu.js"', "shared runtime import"]
+  ], "navigation-runtime.js")
+  runtime = specializeNavigationPatterns(runtime, group.records.some(record => record.segments))
+  return specializeNavigationEffects(runtime, group.hasEffects || group.hasParams)
+}
+
+export function specializeRuntime(source, events, hasStateSeed) {
+  const specialized = specializeEvents(source, events)
+  if (hasStateSeed) return specialized
+  return replaceSequenceRequired(specialized, [
+    ["  const initialState = document.body.dataset.kState\n", "", "initial state read"],
+    [/^  if \(initialState\).*\n/m, "", "initial state parse"]
+  ], "runtime source")
+}
+
+function specializeEvents(source, events) {
+  return replaceRequired(source, /const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`, "event names", "runtime source")
+}
+
+function replaceRequired(source, search, replacement, label, file) {
+  const output = source.replace(search, replacement)
+  if (output === source) throw new Error(`${label} specialization did not match ${file}`)
+  return output
+}
+
+function replaceSequenceRequired(source, replacements, file) {
+  return replacements.reduce((output, [search, replacement, label]) => replaceRequired(output, search, replacement, label, file), source)
+}
+
+function specializeNavigationEffects(source, enabled) {
+  if (enabled) return source
+  return replaceSequenceRequired(source, [
+    ["const noDispose = async () => {}\nlet routeDispose = noDispose\nlet layoutDispose = noDispose\nconst ready = mountInitial()\n", "", "initial effect lifecycle"],
+    [`addEventListener("pagehide", event => {
+  if (event.persisted) return
+  ++revision
+  request?.abort()
+  void (async () => {
+    await routeDispose()
+    await layoutDispose()
+  })()
+})
+`, "", "pagehide effect lifecycle"],
+    [`
+async function mountInitial() {
+  try {
+    const record = matchRoute(location.pathname)
+    if (!record) throw new Error("Initial navigation route does not match")
+    const capabilities = await loadCapabilities(validate(document, record))
+    capabilities.params?.(location.pathname, location.search)
+    layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
+    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
+  } catch (error) {
+    console.error(error)
+  }
+}
+`, "", "initial effect mount"],
+    ["  await ready\n", "", "initial effect readiness"],
+    ["    const { incoming, parsed, capabilities } = documentResult\n", "    const { incoming, parsed } = documentResult\n", "navigation capability result"],
+    ["    await routeDispose()\n    if (current !== revision) return\n", "", "route effect disposal"],
+    ["    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)\n", "    commit(incoming, parsed.nodes)\n", "navigation capability commit"],
+    ["    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "", "route effect mount"],
+    ["  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", "navigation capability load"],
+    [`
+async function loadCapabilities(parsed) {
+  const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
+  const params = modules.filter(module => typeof module.initializeParams === "function")
+  const effects = modules.filter(module => typeof module.mountRouteEffects === "function")
+  if (params.length > 1 || effects.length > 1) throw new Error("Navigation document has duplicate route capabilities")
+  return { params: params[0]?.initializeParams, effects: effects[0] }
+}
+`, "", "capability loader"]
+  ], "navigation-runtime.js")
+}
+
+function specializeNavigationPatterns(source, enabled) {
+  if (enabled) return source
+  return replaceRequired(source, /function matchRoute\(pathname\) \{[\s\S]+?\n\}\n\nfunction fallback/, `function matchRoute(pathname) {
+  return routes.find(record => record.path === pathname)
+}
+
+function fallback`, "exact route matcher", "navigation-runtime.js")
+}
+
+function specializeNavigationTextDescriptors(source) {
+  return replaceSequenceRequired(source, [
+    ["const textDescriptors = globalThis.__KUDZU_TEXT_BINDINGS__ && typeof document !== \"undefined\" ? JSON.parse(document.body.dataset.kTextBindings ?? \"[]\") : []", "const textDescriptors = () => globalThis.__KUDZU_TEXT_BINDINGS__ ? JSON.parse(document.body.dataset.kTextBindings ?? \"[]\") : []", "text descriptor reader"],
+    ["const descriptor = textDescriptors[Number(node.data.slice(\"k-text:\".length))]", "const descriptor = textDescriptors()[Number(node.data.slice(\"k-text:\".length))]", "text descriptor lookup"]
+  ], "binding-runtime.js")
+}

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
   }