@kudzujs/core 0.5.8 → 0.6.0

package/framework/build.mjs

@@ -1,5 +1,5 @@
 import { createServer } from "node:http"
-import { randomUUID } from "node:crypto"
+import { createHash, randomUUID } from "node:crypto"
 import { cp, mkdir, readFile, readdir, rm, stat, watch, writeFile } from "node:fs/promises"
 import { dirname, extname, join, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
@@ -19,6 +19,15 @@ const devClient = (session, revision, schema) => `<script>(()=>{const show=event
 export async function build({ quiet = false, minify = true } = {}) {
   const config = await loadConfig()
   const base = normalizeBase(config.base)
+  const configuredStyles = normalizeStyles(config.styles, base)
+  const navigationRoutes = normalizeNavigation(config.navigation)
+  const navigationSet = new Set(navigationRoutes)
+  const browserNavigationRoutes = navigationRoutes.map(route => withBase(base, route))
+  const navigationAsset = assetPath(base, "assets/kudzu-navigation.js")
+  const navigationId = navigationRoutes.length ? createHash("sha256").update(JSON.stringify([...navigationRoutes].sort())).digest("hex").slice(0, 16) : undefined
+  const applicationId = navigationId ? `a-${navigationId}` : undefined
+  const layoutId = navigationId ? `l-${navigationId}` : undefined
+  let navigationLayout
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
   await mkdir(workDirectory, { recursive: true })
@@ -41,21 +50,30 @@ export async function build({ quiet = false, minify = true } = {}) {
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
 
   let behaviorCount = 0
+  let regularBehaviorCount = 0
   let bindingCount = 0
   let listCount = 0
   let listStyleCount = 0
-  let stateSeedCount = 0
+  let regularStateSeedCount = 0
+  let dependencyStateSeedCount = 0
   const plans = []
+  const pageEntries = []
   const effectEntries = []
   const paramEntries = []
   const rewrites = []
   const emittedRoutes = new Set()
-  const styleUrls = cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`))
+  const emittedApplicationRoutes = new Set()
+  const styleUrls = [...new Set([
+    ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
+    ...configuredStyles
+  ])]
+  const runtimePlaceholder = `/__kudzu_runtime_${randomUUID()}.js`
 
   for (const pageFile of pageFiles) {
     const compiledFile = compiledPath(pageFile)
     const module = await import(`${pathToFileURL(compiledFile).href}?v=${Date.now()}`)
     if (typeof module.default !== "function") throw new Error(`${relative(root, pageFile)} must export a default component`)
+    if (Object.hasOwn(module, "layout") && typeof module.layout !== "function") throw layoutExportError(pageFile, sourceIndex.get(pageFile))
 
     const runtimeSchema = runtimeRouteSchema(module, pageFile)
     if (runtimeSchema) {
@@ -72,33 +90,52 @@ export async function build({ quiet = false, minify = true } = {}) {
     const entries = runtimeSchema ? [{ params: {}, props: {} }] : await staticPathEntries(module, pageFile)
     for (const { params, props } of entries) {
       const route = runtimeSchema?.route ?? routeFromPage(pageFile, params)
+      const applicationRoute = `/${route}`
       const routePath = withBase(base, `/${route}`)
+      const navigable = navigationSet.has(applicationRoute)
       const effectPath = `effects/${route ? `${route}/index` : "index"}.js`
       const paramPath = `params/${route}/index.js`
       if (emittedRoutes.has(routePath)) throw new Error(`Duplicate route: ${routePath}`)
       emittedRoutes.add(routePath)
+      emittedApplicationRoutes.add(applicationRoute)
+      if (navigable) {
+        if (runtimeSchema) throw new Error(`kudzu.config navigation route ${JSON.stringify(routePath)} must be an exact static route; runtime bracket routes are not supported`)
+        if (typeof module.layout !== "function") throw new Error(`kudzu.config navigation route ${JSON.stringify(routePath)} must export a layout function so Kudzu can emit route markers`)
+        if (navigationLayout && navigationLayout !== module.layout) throw new Error("kudzu.config navigation routes must export the same layout function identity")
+        navigationLayout = module.layout
+      }
       const result = await renderPage(module.default, {
         ...(module.metadata ?? {}),
         styles: styleUrls.length ? styleUrls : false,
         base,
+        runtimeAsset: runtimePlaceholder,
         effectAsset: assetPath(base, `assets/${effectPath}`),
         paramAsset: assetPath(base, `assets/${paramPath}`),
-        runtimeParams: runtimeSchema?.params
-      }, props)
-      const routeDirectory = join(outputDirectory, route)
-      await mkdir(routeDirectory, { recursive: true })
-      await writeFile(join(routeDirectory, "index.html"), result.html)
+        runtimeParams: runtimeSchema?.params,
+        ...(navigable ? { navigationAsset, applicationId, layoutId } : {})
+      }, props, module.layout)
+      const hasDependencies = result.plan.effects.some(effect => effect.dependencies?.length)
+      const usesDependencyRuntime = !navigable && hasDependencies && !result.plan.effects.some(effect => effect.owner) && !result.hasBindings && !result.hasLists && !result.plan.events.some(event => event.native)
+      pageEntries.push({ route, html: result.html, usesDependencyRuntime })
       plans.push({ route: routePath, ...result.plan })
-      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params })
-      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: result.plan.effects, paramPath: result.hasParams ? paramPath : undefined })
-      if (result.hasBehaviors) behaviorCount++
+      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, usesDependencyRuntime })
+      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: runtimeEffects(result.plan.effects, navigable), paramPath: result.hasParams ? paramPath : undefined, usesDependencyRuntime, navigable })
+      if (result.hasBehaviors) {
+        behaviorCount++
+        if (!usesDependencyRuntime) regularBehaviorCount++
+      }
       if (result.hasBindings) bindingCount++
       if (result.hasLists) listCount++
       if (result.hasListStyles) listStyleCount++
-      if (result.hasStateSeed) stateSeedCount++
+      if (result.hasStateSeed) {
+        if (usesDependencyRuntime) dependencyStateSeedCount++
+        else regularStateSeedCount++
+      }
     }
   }
 
+  for (const route of navigationRoutes) if (!emittedApplicationRoutes.has(route)) throw new Error(`kudzu.config navigation route ${JSON.stringify(route)} is not an exact emitted route`)
+
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
   const commandEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.commands).map(event => event.event)))].sort()
@@ -111,6 +148,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   const hasListExpressions = plans.some(plan => plan.lists.some(list => list.expressions))
   const hasListExpressionAttributes = plans.some(plan => plan.lists.some(list => list.expressionAttributes))
   const hasListSeeds = plans.some(plan => plan.lists.some(list => list.seed))
+  const hasListEffects = plans.some(plan => plan.lists.some(list => list.effects))
   const hasListAsyncParts = hasListExpressions || hasListExpressionAttributes || hasListConditions
   const hasListMounts = hasListConditions || plans.some(plan => plan.lists.some(list => list.mount))
   const hasNestedStateCaptures = hasNestedCaptureState(plans)
@@ -119,11 +157,26 @@ export async function build({ quiet = false, minify = true } = {}) {
   const nativeModules = handlerModules.filter(module => module.hasNativeHandlers).map(module => assetPath(base, `assets/${module.path}`))
   const hasNativeHandlers = nativeModules.length > 0
   const hasEffects = effectEntries.length > 0
-  if (behaviorCount) {
-    const runtimeFile = bindingCount || listCount || hasNativeHandlers ? "./shared-runtime.js" : "./runtime.js"
-    const runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, stateSeedCount > 0)
+  const hasNavigableEffects = effectEntries.some(entry => entry.navigable)
+  const hasSharedRuntime = bindingCount || listCount || hasNativeHandlers || navigationRoutes.length
+  const hasDependencyRuntime = pageEntries.some(entry => entry.usesDependencyRuntime)
+  const runtimeName = usesDependencyRuntime => usesDependencyRuntime ? "kudzu-deps.js" : "kudzu.js"
+  for (const entry of pageEntries) {
+    const routeDirectory = join(outputDirectory, entry.route)
+    await mkdir(routeDirectory, { recursive: true })
+    const html = entry.html.replace(runtimePlaceholder, escapeAttribute(assetPath(base, `assets/${runtimeName(entry.usesDependencyRuntime)}`)))
+    await writeFile(join(routeDirectory, "index.html"), html)
+  }
+  if (navigationRoutes.length || behaviorCount && (hasSharedRuntime || regularBehaviorCount)) {
+    const runtimeFile = hasSharedRuntime ? "./shared-runtime.js" : "./runtime.js"
+    let runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, regularStateSeedCount > 0)
+    if (hasNavigableEffects) runtime = runtime.replace("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}")
     await writeJavaScript(join(assetsDirectory, "kudzu.js"), runtime, minify)
   }
+  if (hasDependencyRuntime) {
+    const runtime = specializeRuntime(await readFile(new URL("./dependency-runtime.js", import.meta.url), "utf8"), commandEvents, dependencyStateSeedCount > 0)
+    await writeJavaScript(join(assetsDirectory, "kudzu-deps.js"), runtime, minify)
+  }
   if (bindingCount || hasNativeHandlers || hasEffectCaptures) await writeJavaScript(join(assetsDirectory, "kudzu-serialization.js"), await readFile(new URL("./serialization.js", import.meta.url), "utf8"), minify, {
     "globalThis.__KUDZU_CAPTURE_STATE__": String(hasNestedStateCaptures),
     "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
@@ -138,10 +191,11 @@ export async function build({ quiet = false, minify = true } = {}) {
   }
   if (bindingCount || listStyleCount) await writeJavaScript(join(assetsDirectory, "kudzu-style.js"), await readFile(new URL("./style.js", import.meta.url), "utf8"), minify)
   if (bindingCount) {
-    const bindingRuntime = (await readFile(new URL("./binding-runtime.js", import.meta.url), "utf8"))
+    let bindingRuntime = (await readFile(new URL("./binding-runtime.js", import.meta.url), "utf8"))
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
       .replace('"./serialization.js"', '"./kudzu-serialization.js"')
       .replace('"./style.js"', '"./kudzu-style.js"')
+    if (navigationRoutes.length) bindingRuntime = specializeNavigationTextDescriptors(bindingRuntime)
     await writeBundledJavaScript(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime, minify, {
       "globalThis.__KUDZU_TEXT_BINDINGS__": String(hasTextBindings),
       "globalThis.__KUDZU_CAPTURE_STATE__": String(hasNestedStateCaptures)
@@ -166,6 +220,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       __KUDZU_LIST_EXPRESSIONS__: String(hasListExpressions),
       __KUDZU_LIST_EXPRESSION_ATTRIBUTES__: String(hasListExpressionAttributes),
       __KUDZU_LIST_SEEDS__: String(hasListSeeds),
+      __KUDZU_LIST_EFFECTS__: String(hasListEffects),
       __KUDZU_LIST_ASYNC_PARTS__: String(hasListAsyncParts),
       __KUDZU_LIST_MOUNTS__: String(hasListMounts)
     })
@@ -178,6 +233,14 @@ export async function build({ quiet = false, minify = true } = {}) {
       "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
     })
   }
+  if (navigationRoutes.length) {
+    const navigationRuntime = (await readFile(new URL("./navigation-runtime.js", import.meta.url), "utf8"))
+      .replace("__KUDZU_NAVIGATION_ROUTES__", inlineJson(browserNavigationRoutes))
+      .replace("__KUDZU_APPLICATION_ID__", JSON.stringify(applicationId))
+      .replace("__KUDZU_LAYOUT_ID__", JSON.stringify(layoutId))
+      .replace('"./shared-runtime.js"', '"./kudzu.js"')
+    await writeJavaScript(join(assetsDirectory, "kudzu-navigation.js"), specializeNavigationEffects(navigationRuntime, hasNavigableEffects), minify)
+  }
   for (const handlerModule of handlerModules) {
     const output = join(assetsDirectory, handlerModule.path)
     await mkdir(resolve(output, ".."), { recursive: true })
@@ -186,12 +249,14 @@ export async function build({ quiet = false, minify = true } = {}) {
   for (const entry of paramEntries) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
-    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base), minify)
+    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base, runtimeName(entry.usesDependencyRuntime)), minify)
   }
   for (const entry of effectEntries) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
-    await writeJavaScript(output, printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath), minify)
+    await writeJavaScript(output, entry.navigable
+      ? printNavigableEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base)
+      : printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath, runtimeName(entry.usesDependencyRuntime)), minify)
   }
   const clientModules = await collectClientModules(handlerModules.flatMap(module => module.clientImports), sourceFileSet)
   for (const file of clientModules) {
@@ -237,14 +302,53 @@ function specializeEvents(source, events) {
   return source.replace(/const eventNames = \[[^\n]+\]/, `const eventNames = ${JSON.stringify(events)}`)
 }
 
+function specializeNavigationEffects(source, enabled) {
+  if (enabled) return source
+  return source
+    .replace("const noDispose = async () => {}\nlet routeDispose = noDispose\nlet layoutDispose = noDispose\nconst ready = mountInitial()\n", "")
+    .replace(`addEventListener("pagehide", event => {
+  if (event.persisted) return
+  ++revision
+  request?.abort()
+  void (async () => {
+    await routeDispose()
+    await layoutDispose()
+  })()
+})
+`, "")
+    .replace(`
+async function mountInitial() {
+  try {
+    const effects = await loadCapabilities(validate(document))
+    layoutDispose = await effects?.mountLayoutEffects?.() ?? noDispose
+    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose
+  } catch (error) {
+    console.error(error)
+  }
+}
+`, "")
+    .replace("  await ready\n", "")
+    .replace("    const effects = await loadCapabilities(parsed)\n", "    await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n")
+    .replace("    await routeDispose()\n    if (current !== revision) return\n", "")
+    .replace("    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose\n", "")
+    .replace(`
+async function loadCapabilities(parsed) {
+  const modules = await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))
+  return modules.find(module => typeof module.mountRouteEffects === "function")
+}
+`, "")
+}
+
 function specializeNativeRuntime(source, events, modules) {
   const imports = modules.map((module, index) => `import * as __kNativeModule${index} from ${JSON.stringify(module)}`).join("\n")
   const entries = modules.map((module, index) => `[${JSON.stringify(module)}, __kNativeModule${index}]`).join(",")
   return `${imports}\n${specializeEvents(source, events).replace(/const modules = new Map\(\[[^\n]*\]\)/, `const modules = new Map([${entries}])`)}`
 }
 
-function printEffectEntry(effects, output, handlerModules, assetsDirectory, base, paramPath) {
+function printEffectEntry(effects, output, handlerModules, assetsDirectory, base, paramPath, runtimeName) {
   const hasCleanup = effects.some(effect => effect.cleanup)
+  const hasDependencies = effects.some(effect => effect.dependencies?.length)
+  const hasOwners = effects.some(effect => effect.owner)
   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)
@@ -252,14 +356,119 @@ function printEffectEntry(effects, output, handlerModules, assetsDirectory, base
     return module
   })
   const imports = [
-    hasCleanup
-      ? `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}\nconst { browserState, commitDom } = __kRuntime`
-      : `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}`,
+    hasCleanup || hasDependencies || hasOwners
+      ? `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}\nconst { browserState, commitDom } = __kRuntime`
+      : `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}`,
     `import { createEffectContext } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu-effect.js")))}`,
     ...(paramPath ? [`import ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, paramPath)))}`] : []),
     ...modules.map((module, index) => `import * as __kEffectModule${index} from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, module.path)))}`)
   ]
   const entries = moduleUrls.map((url, index) => `[${JSON.stringify(url)}, __kEffectModule${index}]`).join(",")
+  if (hasOwners) return printOwnedEffectEntry(imports, effects, entries)
+  if (effects.length === 1 && effects[0].dependencies?.length === 1) return printSingleDependencyEffect(imports, effects[0], hasCleanup)
+  const disposal = hasCleanup ? `
+let disposed = false
+const dispose = root => {
+  if (root !== document || disposed) return
+  disposed = true
+  active = false
+  pending.clear()
+  for (const record of records) invokeCleanup(record)
+}
+
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+addEventListener("pagehide", event => {
+  if (event.persisted) return
+  if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
+  else dispose(document)
+})` : ""
+  if (hasDependencies) return `${imports.join("\n")}
+const effects = ${inlineJson(effects)}
+const modules = new Map([${entries}])
+const records = effects.map((effect, index) => ({ effect, index, values: undefined, cleanup: undefined }))
+const dependencies = new Map()
+const pending = new Set()
+let scheduled = false
+let flushing = false
+let active = true
+for (const record of records) {
+  for (const id of record.effect.dependencies ?? []) {
+    const subscribers = dependencies.get(id) ?? new Set()
+    subscribers.add(record)
+    dependencies.set(id, subscribers)
+  }
+}
+__kRuntime.registerCommitter(id => {
+  if (!active) return
+  for (const record of dependencies.get(id) ?? []) pending.add(record)
+  schedule()
+})
+for (const record of records) {
+  try {
+    record.values = readDependencies(record)
+    invoke(record)
+  } catch (error) {
+    console.error(error)
+  }
+}
+function schedule() {
+  if (!pending.size || scheduled || flushing) return
+  scheduled = true
+  queueMicrotask(flush)
+}
+async function flush() {
+  scheduled = false
+  if (!active) return pending.clear()
+  flushing = true
+  try {
+    const selected = [...pending].sort((left, right) => left.index - right.index)
+    pending.clear()
+    const changed = []
+    for (const record of selected) {
+      try {
+        const values = readDependencies(record)
+        if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
+          record.values = values
+          changed.push(record)
+        }
+      } catch (error) {
+        console.error(error)
+      }
+    }
+    for (const record of changed) await invokeCleanup(record)
+    if (active) for (const record of changed) invoke(record)
+  } finally {
+    flushing = false
+    if (active) schedule()
+  }
+}
+function readDependencies(record) {
+  return (record.effect.dependencies ?? []).map(id => {
+    const value = browserState.get(id)
+    if (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")
+    return value
+  })
+}
+function invoke(record) {
+  try {
+    const effect = record.effect
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, effect.scope))
+    if (effect.cleanup && typeof result === "function") record.cleanup = result
+    else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}
+async function invokeCleanup(record) {
+  const cleanup = record.cleanup
+  record.cleanup = undefined
+  if (!cleanup) return
+  try {
+    await cleanup()
+  } catch (error) {
+    console.error(error)
+  }
+}${disposal}`
   if (!hasCleanup) return `${imports.join("\n")}
 const effects = ${inlineJson(effects)}
 const modules = new Map([${entries}])
@@ -306,8 +515,415 @@ addEventListener("pagehide", event => {
 })`
 }
 
-function printParamEntry(schema, params, output, assetsDirectory, base) {
-  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}
+function printNavigableEffectEntry(effects, output, handlerModules, assetsDirectory, base) {
+  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)
+    if (!module) throw new Error(`Effect handler module was not emitted: ${url}`)
+    return module
+  })
+  const imports = [
+    `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}`,
+    `import { createEffectContext } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu-effect.js")))}`,
+    ...modules.map((module, index) => `import * as __kEffectModule${index} from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, module.path)))}`)
+  ]
+  const entries = moduleUrls.map((url, index) => `[${JSON.stringify(url)}, __kEffectModule${index}]`).join(",")
+  return `${imports.join("\n")}
+const effects = ${inlineJson(effects)}
+const modules = new Map([${entries}])
+export const mountLayoutEffects = () => mount("layout")
+export const mountRouteEffects = () => mount("route")
+function mount(lifetime) {
+  let active = true
+  let flushing
+  const records = effects.filter(effect => effect.lifetime === lifetime).map((effect, index) => ({ effect, index, values: undefined, cleanup: undefined, token: undefined }))
+  const dependencies = new Map()
+  const pending = new Set()
+  let scheduled = false
+  for (const record of records) for (const id of record.effect.dependencies ?? []) {
+    const subscribers = dependencies.get(id) ?? new Set()
+    subscribers.add(record)
+    dependencies.set(id, subscribers)
+  }
+  const unsubscribe = dependencies.size ? __kRuntime.registerCommitter(id => {
+    if (!active) return
+    for (const record of dependencies.get(id) ?? []) pending.add(record)
+    if (pending.size && !scheduled && !flushing) {
+      scheduled = true
+      queueMicrotask(flush)
+    }
+  }) : undefined
+  for (const record of records) {
+    try {
+      record.values = readDependencies(record)
+      invoke(record)
+    } catch (error) {
+      console.error(error)
+    }
+  }
+  async function flush() {
+    scheduled = false
+    if (!active) return pending.clear()
+    const operation = (async () => {
+      const selected = [...pending].sort((left, right) => left.index - right.index)
+      pending.clear()
+      const changed = []
+      for (const record of selected) {
+        try {
+          const values = readDependencies(record)
+          if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
+            record.values = values
+            changed.push(record)
+          }
+        } catch (error) {
+          console.error(error)
+        }
+      }
+      for (const record of changed) await cleanup(record)
+      if (active) for (const record of changed) invoke(record)
+    })()
+    flushing = operation
+    try { await operation } finally {
+      if (flushing === operation) flushing = undefined
+      if (active && pending.size && !scheduled) {
+        scheduled = true
+        queueMicrotask(flush)
+      }
+    }
+  }
+  function readDependencies(record) {
+    return (record.effect.dependencies ?? []).map(id => {
+      const value = __kRuntime.browserState.get(id)
+      if (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")
+      return value
+    })
+  }
+  function invoke(record) {
+    const token = { active: true }
+    record.token = token
+    try {
+      const effect = record.effect
+      const result = modules.get(effect.module)[effect.handler](createEffectContext(__kRuntime.browserState, effect.states, __kRuntime.commitDom, effect.scope, () => active && token.active && record.token === token))
+      if (effect.cleanup && typeof result === "function") record.cleanup = result
+      else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+    } catch (error) {
+      console.error(error)
+    }
+  }
+  async function cleanup(record) {
+    if (record.token) record.token.active = false
+    record.token = undefined
+    const current = record.cleanup
+    record.cleanup = undefined
+    if (!current) return
+    try { await current() } catch (error) { console.error(error) }
+  }
+  let disposal
+  return async function dispose() {
+    if (disposal) return disposal
+    disposal = (async () => {
+      active = false
+      unsubscribe?.()
+      pending.clear()
+      for (const record of records) if (record.token) record.token.active = false
+      if (flushing) await flushing
+      for (const record of records) await cleanup(record)
+    })()
+    return disposal
+  }
+}`
+}
+
+function runtimeEffects(effects, lifetimes = false) {
+  return effects.map(effect => ({
+    module: effect.module,
+    handler: effect.handler,
+    ...(effect.dependencies ? { dependencies: effect.dependencies } : {}),
+    ...(effect.cleanup ? { cleanup: true } : {}),
+    ...(effect.owner ? { owner: effect.owner } : {}),
+    ...(effect.list ? { list: true } : {}),
+    ...(lifetimes && effect.lifetime ? { lifetime: effect.lifetime } : {}),
+    states: effect.states,
+    scope: effect.scope
+  }))
+}
+
+function printOwnedEffectEntry(imports, effects, entries) {
+  return `${imports.join("\n")}
+const effects = ${inlineJson(effects)}
+const modules = new Map([${entries}])
+const records = effects.map((effect, index) => effect.list ? undefined : createRecord(effect, index)).filter(Boolean)
+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 mountedRecords = new Set(records.filter(record => record.mounted))
+const dependencies = new Map()
+const pending = new Set()
+let scheduled = false
+let flushing = false
+let active = true
+for (const record of records) registerDependencies(record)
+function createRecord(effect, index) {
+  return { effect, index, mounted: !effect.owner, marker: undefined, version: 0, values: undefined, cleanup: undefined, disposal: undefined }
+}
+function registerDependencies(record) {
+  for (const id of record.effect.dependencies ?? []) {
+  const subscribers = dependencies.get(id) ?? new Set()
+  subscribers.add(record)
+  dependencies.set(id, subscribers)
+  }
+}
+function unregisterDependencies(record) {
+  for (const id of record.effect.dependencies ?? []) {
+    const subscribers = dependencies.get(id)
+    subscribers?.delete(record)
+    if (!subscribers?.size) dependencies.delete(id)
+  }
+}
+__kRuntime.registerCommitter(id => {
+  if (!active) return
+  for (const record of dependencies.get(id) ?? []) if (record.mounted) pending.add(record)
+  schedule()
+})
+__kRuntime.registerMountHook(root => {
+  if (!active) return
+  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 template = listTemplates.get(owner)
+        if (!template) throw new Error("Keyed row effect template was not emitted")
+        const record = createRecord(template.effect, template.index)
+        registerDependencies(record)
+        mount(record, marker)
+        return record
+      })
+      listRegistrations.set(marker, rowRecords)
+      continue
+    }
+    const record = owners.get(marker.dataset.kEffect)
+    if (!record?.mounted) mount(record, marker)
+  }
+})
+__kRuntime.registerUnmountHook(root => {
+  if (root === document) {
+    if (!active) return
+    active = false
+    pending.clear()
+    for (const record of [...mountedRecords]) unmount(record, record.effect.list)
+    return
+  }
+  for (const marker of matching(root)) {
+    const rowRecords = listRegistrations.get(marker)
+    if (rowRecords) {
+      for (const record of rowRecords) unmount(record, true)
+      listRegistrations.delete(marker)
+      continue
+    }
+    const record = owners.get(marker.dataset.kEffect)
+    if (record?.marker === marker) unmount(record)
+  }
+})
+for (const record of records) if (record.mounted) start(record)
+__kRuntime.mountDom(document)
+addEventListener("pagehide", event => {
+  if (!event.persisted) __kRuntime.unmountDom(document)
+})
+function matching(root) {
+  const selector = "template[data-k-effect],[data-k-effects]"
+  return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
+}
+function mount(record, marker) {
+  record.mounted = true
+  record.marker = marker
+  mountedRecords.add(record)
+  const version = ++record.version
+  const begin = () => {
+    if (!active || !record.mounted || record.version !== version || !marker.isConnected) return
+    start(record)
+  }
+  if (record.disposal) record.disposal.then(begin)
+  else begin()
+}
+function unmount(record, dynamic = false) {
+  if (!record.mounted) return
+  record.mounted = false
+  record.marker = undefined
+  mountedRecords.delete(record)
+  if (dynamic) unregisterDependencies(record)
+  record.version++
+  pending.delete(record)
+  invokeCleanup(record)
+}
+function start(record) {
+  try {
+    record.values = readDependencies(record)
+    invoke(record)
+  } catch (error) {
+    console.error(error)
+  }
+}
+function schedule() {
+  if (!pending.size || scheduled || flushing) return
+  scheduled = true
+  queueMicrotask(flush)
+}
+async function flush() {
+  scheduled = false
+  if (!active) return pending.clear()
+  flushing = true
+  try {
+    const selected = [...pending].filter(record => record.mounted).sort((left, right) => left.index - right.index)
+    pending.clear()
+    const changed = []
+    for (const record of selected) {
+      try {
+        const values = readDependencies(record)
+        if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
+          record.values = values
+          changed.push([record, record.version])
+        }
+      } catch (error) {
+        console.error(error)
+      }
+    }
+    for (const [record] of changed) await invokeCleanup(record)
+    if (active) for (const [record, version] of changed) if (record.mounted && record.version === version) invoke(record)
+  } finally {
+    flushing = false
+    if (active) schedule()
+  }
+}
+function readDependencies(record) {
+  return (record.effect.dependencies ?? []).map(id => {
+    const value = browserState.get(id)
+    if (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")
+    return value
+  })
+}
+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]))
+      : effect.scope
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope))
+    if (effect.cleanup && typeof result === "function") record.cleanup = result
+    else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}
+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)
+    }
+  })()
+  record.disposal = disposal
+  disposal.finally(() => {
+    if (record.disposal === disposal) record.disposal = undefined
+  })
+  return disposal
+}`
+}
+
+function printSingleDependencyEffect(imports, effect, hasCleanup) {
+  const disposal = hasCleanup ? `
+const dispose = root => {
+  if (root !== document || !active) return
+  active = false
+  pending = false
+  invokeCleanup()
+}
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+addEventListener("pagehide", event => {
+  if (event.persisted) return
+  if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
+  else dispose(document)
+})` : ""
+  return `${imports.join("\n")}
+const effect = ${inlineJson(effect)}
+const dependency = effect.dependencies[0]
+let value
+let cleanup
+let active = true
+let pending = false
+let scheduled = false
+let running = false
+__kRuntime.registerCommitter(id => {
+  if (active && id === dependency) {
+    pending = true
+    schedule()
+  }
+})
+try {
+  value = readDependency()
+  invoke()
+} catch (error) {
+  console.error(error)
+}
+function schedule() {
+  if (!pending || scheduled || running) return
+  scheduled = true
+  queueMicrotask(flush)
+}
+async function flush() {
+  scheduled = false
+  if (!active) return
+  let next
+  try {
+    next = readDependency()
+  } catch (error) {
+    console.error(error)
+    return
+  }
+  pending = false
+  if (Object.is(next, value)) return
+  value = next
+  running = true
+  try {
+    await invokeCleanup()
+    if (active) invoke()
+  } finally {
+    running = false
+    if (active) schedule()
+  }
+}
+function readDependency() {
+  const next = browserState.get(dependency)
+  if (next !== null && typeof next !== "string" && typeof next !== "boolean" && !(typeof next === "number" && Number.isFinite(next) && !Object.is(next, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive")
+  return next
+}
+function invoke() {
+  try {
+    const result = __kEffectModule0[effect.handler](createEffectContext(browserState, effect.states, commitDom, effect.scope))
+    if (effect.cleanup && typeof result === "function") cleanup = result
+    else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}
+async function invokeCleanup() {
+  const current = cleanup
+  cleanup = undefined
+  if (!current) return
+  try {
+    await current()
+  } catch (error) {
+    console.error(error)
+  }
+}${disposal}`
+}
+
+function printParamEntry(schema, params, output, assetsDirectory, base, runtimeName) {
+  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
 const base = ${inlineJson(browserPath(base).slice(1).split("/").filter(Boolean).map(segment => decodeURIComponent(segment)))}
 const schema = ${inlineJson(schema.segments)}
 const params = ${inlineJson(params)}
@@ -501,7 +1117,7 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
 }
 
 function injectDevClient(html, session, revision, schema) {
-  return `${html}${devClient(session, revision, schema)}`
+  return `${html}${devClient(session, revision, schema).replace("binding|list|native", "binding|deps|list|native")}`
 }
 
 function stripBaseStrict(path, base) {
@@ -576,6 +1192,10 @@ function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
 }
 
+function escapeAttribute(value) {
+  return escapeHtml(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;")
+}
+
 async function compile(file, sourceFiles, sourceIndex, base) {
   const source = sourceIndex.get(file)
   const nativeHandlers = []
@@ -625,6 +1245,7 @@ async function compile(file, sourceFiles, sourceIndex, base) {
 function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports) {
   return context => sourceFile => {
     const factory = context.factory
+    const hasLinkElements = /<link/i.test(sourceFile.text)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
@@ -650,10 +1271,12 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     const listValues = new WeakMap()
     const listEventItems = new WeakMap()
     const listConditions = new WeakMap()
+    const listEffectEntries = new WeakMap()
     let usesBehavior = false
     let usesBinding = false
     let usesConditional = false
     let usesList = false
+    let usesListEffects = false
 
     const collect = node => {
       if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer)) {
@@ -758,6 +1381,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     }))
     const componentSpecializations = new WeakMap()
     const specializedDeclarations = new WeakSet()
+    const keyedComponentCalls = new Set(rawRenderedLists.map(({ parts }) => parts.root))
     for (const name of listComponentNames) {
       let component = components.get(name)
       const local = Boolean(component)
@@ -770,7 +1394,11 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       if (local && isExportedDeclaration(component.declaration)) fail(component.declaration, `Keyed list component ${name} cannot be exported`)
       const calls = jsxTagUses(sourceFile, name)
       if (local && identifierReferenceCount(sourceFile, name) !== calls.length) fail(component.declaration, `Keyed list component ${name} may only be referenced as JSX`)
-      for (const call of calls) componentSpecializations.set(call, specializeComponentCall(call, component.function, sourceFile, factory, context, fail))
+      for (const call of calls) {
+        const specialization = specializeComponentCall(call, component.function, sourceFile, factory, context, fail)
+        if (specialization.effects.length && !keyedComponentCalls.has(call)) fail(call, "Effectful keyed row components may only be used directly as keyed map rows")
+        componentSpecializations.set(call, specialization)
+      }
       if (local) specializedDeclarations.add(component.declaration)
     }
     const renderedLists = new WeakMap()
@@ -778,7 +1406,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
       const specialization = componentSpecializations.get(originalParts.root)
       const root = specialization?.root ?? originalParts.root
-      const callback = root === originalParts.root ? originalParts.callback : factory.updateArrowFunction(
+      let callback = root === originalParts.root ? originalParts.callback : factory.updateArrowFunction(
         originalParts.callback,
         originalParts.callback.modifiers,
         originalParts.callback.typeParameters,
@@ -798,6 +1426,20 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         validateListExpression(calculation, parts.item, originalParts.root, fail)
       }
       validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions)
+      if (specialization?.effects.length) {
+        usesListEffects = true
+        const statements = specialization.effects.map(entry => {
+          const call = factory.updateCallExpression(entry.call, factory.createIdentifier("__kListUseEffect"), entry.call.typeArguments, entry.call.arguments)
+          synthesizeTree(call)
+          const effectSource = entry.source.getSourceFile()
+          listEffectEntries.set(call, { item: parts.item, source: entry.source, sourceFile: effectSource, imports: clientImportBindings(effectSource, effectSource.fileName, sourceFiles) })
+          return factory.createExpressionStatement(call)
+        })
+        callback = factory.updateArrowFunction(callback, callback.modifiers, callback.typeParameters, callback.parameters, callback.type, callback.equalsGreaterThanToken, factory.createBlock([...statements, factory.createReturnStatement(root)], true))
+        ts.setParentRecursive(callback, false)
+        callback.parent = originalParts.callback.parent
+        parts.callback = callback
+      }
       renderedLists.set(node, parts)
     }
 
@@ -827,6 +1469,10 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       if (specializedDeclarations.has(node)) return node
       if (componentSpecializations.has(node)) return ts.visitNode(componentSpecializations.get(node).root, visitor)
 
+      if (hasLinkElements && (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) && isStylesheetLink(node)) {
+        fail(node, "Stylesheets must be placed under src/ or declared in kudzu.config styles so Kudzu can emit them in <head>")
+      }
+
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
         const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
         return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(relativeModulePath(compiledPath(file), compiledPath(target))), node.attributes)
@@ -837,23 +1483,33 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         return factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, factory.createStringLiteral(relativeModulePath(compiledPath(file), compiledPath(target))), node.attributes)
       }
 
-      if (hasUseEffectImport && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "useEffect") {
-        if (node.arguments.length !== 2) fail(node, "useEffect() requires exactly a callback and literal empty dependency array")
+      const listEffect = ts.isCallExpression(node) ? listEffectEntries.get(node) : undefined
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (hasUseEffectImport && node.expression.text === "useEffect" || listEffect)) {
+        const effectFail = (target, message) => {
+          if (listEffect) throw sourceNodeError(listEffect.source, listEffect.sourceFile, message)
+          fail(target, message)
+        }
+        if (node.arguments.length !== 2) effectFail(node, "useEffect() requires exactly a callback and literal dependency array")
         const [callback, dependencies] = node.arguments
-        if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) fail(callback, "useEffect() callback must be an inline function")
-        if (ts.isFunctionExpression(callback) && callback.name) fail(callback, "useEffect() callback function must be anonymous")
-        if (callback.asteriskToken) fail(callback, "useEffect() callback cannot be a generator")
-        if (callback.parameters.length) fail(callback, "useEffect() callback cannot declare parameters")
-        if (!ts.isArrayLiteralExpression(dependencies) || dependencies.elements.length) fail(dependencies, "useEffect() dependencies must be a literal empty array")
+        if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) effectFail(callback, "useEffect() callback must be an inline function")
+        if (ts.isFunctionExpression(callback) && callback.name) effectFail(callback, "useEffect() callback function must be anonymous")
+        if (callback.asteriskToken) effectFail(callback, "useEffect() callback cannot be a generator")
+        if (callback.parameters.length) effectFail(callback, "useEffect() callback cannot declare parameters")
+        if (!ts.isArrayLiteralExpression(dependencies)) effectFail(dependencies, "useEffect() dependencies must be a literal array")
+        if (listEffect && dependencies.elements.some(dependency => referencesIdentifier(dependency, listEffect.item))) {
+          effectFail(dependencies, "useEffect() item-property dependencies are not supported in keyed lists; use [] or primitive Kudzu state identifiers")
+        }
+        const invalidDependency = dependencies.elements.find(dependency => !ts.isIdentifier(dependency))
+        if (invalidDependency) effectFail(invalidDependency, "useEffect() dependencies must be direct state or runtime parameter identifiers")
         if (!nearestFunction(node)) fail(node, "useEffect() cannot be used outside a Kudzu component")
-        if (!ts.isBlock(callback.body)) fail(callback, "useEffect() callback must use a block body")
+        if (!ts.isBlock(callback.body)) effectFail(callback, "useEffect() callback must use a block body")
         const returns = effectReturns(callback)
-        if (returns.invalid) fail(returns.invalid, "useEffect() return values must be inline cleanup functions")
+        if (returns.invalid) effectFail(returns.invalid, "useEffect() return values must be inline cleanup functions")
         const invalidCleanup = returns.cleanups.find(cleanup => cleanup.parameters.length || cleanup.asteriskToken)
-        if (invalidCleanup) fail(invalidCleanup, "useEffect() cleanup functions cannot declare parameters or be generators")
-        if (returns.cleanup && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) fail(callback, "useEffect() async callbacks cannot return cleanup functions")
+        if (invalidCleanup) effectFail(invalidCleanup, "useEffect() cleanup functions cannot declare parameters or be generators")
+        if (returns.cleanup && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) effectFail(callback, "useEffect() async callbacks cannot return cleanup functions")
         const setters = settersForNode(node, settersByFunction)
-        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, importBindings, clientImports, "effect", undefined, true, returns.cleanup)
+        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", listEffect?.item, true, returns.cleanup)
         usesBehavior = true
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [
           callback,
@@ -862,7 +1518,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           factory.createStringLiteral(descriptor.exportName),
           descriptor.states,
           descriptor.scope,
-          factory.createStringLiteral(sourceLocation(node, sourceFile)),
+          factory.createStringLiteral(listEffect ? sourceLocation(listEffect.source, listEffect.sourceFile) : sourceLocation(node, sourceFile)),
           returns.cleanup ? factory.createTrue() : factory.createFalse()
         ])
       }
@@ -976,6 +1632,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listItem"), factory.createIdentifier("__kListItem")))
       behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("listConditional"), factory.createIdentifier("__kListConditional")))
     }
+    if (usesListEffects) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useEffect"), factory.createIdentifier("__kListUseEffect")))
     if (usesBinding || usesConditional) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("bindingValue"), factory.createIdentifier("__kBindingValue")))
     const behaviorImport = factory.createImportDeclaration(
       undefined,
@@ -1198,6 +1855,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
 
   let returned
   const calculations = []
+  const effectCalls = []
   if (!ts.isBlock(component.body)) {
     returned = component.body
   } else {
@@ -1205,6 +1863,10 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
     const last = statements.pop()
     if (!last || !ts.isReturnStatement(last) || !last.expression) fail(component.body, "Keyed list component must end with one JSX return")
     for (const statement of statements) {
+      if (ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression) && ts.isIdentifier(statement.expression.expression) && statement.expression.expression.text === "useEffect") {
+        effectCalls.push(statement.expression)
+        continue
+      }
       if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0 || statement.declarationList.declarations.length !== 1) fail(statement, "Keyed list component locals must be single const declarations")
       const declaration = statement.declarationList.declarations[0]
       if (!ts.isIdentifier(declaration.name) || !declaration.initializer) fail(declaration, "Keyed list component locals must be initialized identifiers")
@@ -1223,7 +1885,8 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   if (key) root = addJsxAttribute(root, cloneAst(key, factory, context), factory)
   ts.setParentRecursive(root, false)
   root.parent = call.parent
-  return { root, calculations }
+  const effects = effectCalls.map(source => ({ source, call: substituteClone(source, substitutions, factory, context) }))
+  return { root, calculations, effects }
 }
 
 function substituteClone(root, substitutions, factory, context) {
@@ -1256,6 +1919,16 @@ function cloneAst(root, factory, context) {
   return visit(root)
 }
 
+function synthesizeTree(root) {
+  const visit = node => {
+    ts.setTextRange(node, { pos: -1, end: -1 })
+    ts.setOriginalNode(node, undefined)
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return root
+}
+
 function addJsxAttribute(root, attribute, factory) {
   if (ts.isJsxSelfClosingElement(root)) {
     return factory.updateJsxSelfClosingElement(root, root.tagName, root.typeArguments, factory.updateJsxAttributes(root.attributes, [attribute, ...root.attributes.properties]))
@@ -1268,6 +1941,19 @@ function jsxTagName(node) {
   return ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : undefined
 }
 
+function isStylesheetLink(node) {
+  const element = ts.isJsxElement(node) ? node.openingElement : node
+  if (!ts.isIdentifier(element.tagName) || element.tagName.text.toLowerCase() !== "link") return false
+  const attribute = element.attributes.properties.find(property => ts.isJsxAttribute(property) && property.name.getText().toLowerCase() === "rel")
+  if (!attribute?.initializer) return false
+  const value = ts.isStringLiteral(attribute.initializer)
+    ? attribute.initializer.text
+    : ts.isJsxExpression(attribute.initializer) && attribute.initializer.expression && (ts.isStringLiteral(attribute.initializer.expression) || ts.isNoSubstitutionTemplateLiteral(attribute.initializer.expression))
+      ? attribute.initializer.expression.text
+      : undefined
+  return value?.toLowerCase().split(/\s+/).includes("stylesheet") ?? false
+}
+
 function isContextProviderValue(node, contexts) {
   if (node.name.getText() !== "value") return false
   const element = node.parent?.parent
@@ -1898,6 +2584,22 @@ function parseSourceFile(file, source) {
   return ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true, file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
 }
 
+function layoutExportError(file, source) {
+  const sourceFile = parseSourceFile(file, source)
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+      const specifier = statement.exportClause.elements.find(entry => entry.name.text === "layout")
+      if (specifier) return sourceNodeError(specifier, sourceFile, "layout export must be a function")
+    }
+    if (ts.isVariableStatement(statement) && statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+      const declaration = statement.declarationList.declarations.find(entry => ts.isIdentifier(entry.name) && entry.name.text === "layout")
+      if (declaration) return sourceNodeError(declaration, sourceFile, "layout export must be a function")
+    }
+    if (ts.isFunctionDeclaration(statement) && statement.name?.text === "layout") return sourceNodeError(statement, sourceFile, "layout export must be a function")
+  }
+  return new Error(`${relative(root, file)} layout export must be a function`)
+}
+
 function clientModulePath(file) {
   return `modules/${relative(sourceDirectory, file).replaceAll(sep, "/").replace(/\.(?:ts|tsx)$/, ".js")}`
 }
@@ -1912,6 +2614,8 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
   const stateNames = new Set(setters.values())
   const snapshotNames = snapshotNested ? nestedStateNames(expression, setters) : new Set()
   const snapshots = new Map([...snapshotNames].map(name => [name, factory.createUniqueName("__kEffectState")]))
+  const captureSnapshotNames = snapshotNested ? nestedCaptureNames(expression, captures) : new Set()
+  const captureSnapshots = new Map([...captureSnapshotNames].map(name => [name, factory.createUniqueName("__kEffectCapture")]))
   const transformer = context => root => {
     const visitor = node => {
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
@@ -1940,9 +2644,11 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
         )
       }
       if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        if (captureSnapshots.has(node.name.text) && insideNestedFunction(node, expression)) return factory.createPropertyAssignment(node.name, captureSnapshots.get(node.name.text))
         return factory.createPropertyAssignment(node.name, scopeRead(factory, node.name.text))
       }
       if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
+        if (captureSnapshots.has(node.text) && insideNestedFunction(node, expression)) return captureSnapshots.get(node.text)
         return scopeRead(factory, node.text)
       }
       return ts.visitEachChild(node, visitor, context)
@@ -1954,8 +2660,12 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
     let body = ts.isBlock(expression.body)
       ? transformed.transformed[0]
       : factory.createBlock([factory.createReturnStatement(transformed.transformed[0])], true)
-    if (snapshots.size) body = factory.updateBlock(body, [
-      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([...snapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(name)]))), ts.NodeFlags.Const)),
+    const snapshotDeclarations = [
+      ...[...snapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(name)]))),
+      ...[...captureSnapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "scope"), undefined, [factory.createStringLiteral(name)])))
+    ]
+    if (snapshotDeclarations.length) body = factory.updateBlock(body, [
+      factory.createVariableStatement(undefined, factory.createVariableDeclarationList(snapshotDeclarations, ts.NodeFlags.Const)),
       ...body.statements
     ])
     const modifiers = [factory.createModifier(ts.SyntaxKind.ExportKeyword)]
@@ -1975,6 +2685,16 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
   }
 }
 
+function nestedCaptureNames(expression, captures) {
+  const names = new Set()
+  const visit = node => {
+    if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node) && insideNestedFunction(node, expression) && !isShadowedIdentifier(node, expression)) names.add(node.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body)
+  return names
+}
+
 function nestedStateNames(expression, setters) {
   const states = new Set(setters.values())
   const names = new Set()
@@ -2124,6 +2844,43 @@ async function loadConfig() {
   return {}
 }
 
+function normalizeStyles(value, base) {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) throw new Error("kudzu.config styles must be an array of URLs")
+  return value.map((style, index) => {
+    if (typeof style !== "string" || !style) throw new Error(`kudzu.config styles[${index}] must be a non-empty URL`)
+    if (style.startsWith("//")) throw new Error(`kudzu.config styles[${index}] must be root-relative or an absolute HTTP URL`)
+    if (style.startsWith("/")) return withBase(base, style)
+    if (!/^https?:\/\//i.test(style)) throw new Error(`kudzu.config styles[${index}] must be root-relative or an absolute HTTP URL`)
+    try { new URL(style) } catch { throw new Error(`kudzu.config styles[${index}] must be root-relative or an absolute HTTP URL`) }
+    return style
+  })
+}
+
+export function normalizeNavigation(value) {
+  if (value === undefined) return []
+  if (!isPlainRecord(value)) throw new Error("kudzu.config navigation must be a plain object")
+  if (Object.keys(value).some(key => key !== "routes")) throw new Error("kudzu.config navigation only supports routes")
+  if (!Array.isArray(value.routes) || !value.routes.length) throw new Error("kudzu.config navigation.routes must be a nonempty array")
+  const routes = value.routes.map((route, index) => {
+    if (typeof route !== "string" || !route.startsWith("/") || route.startsWith("//") || /[?#\\\0]/.test(route) || /%(?:2f|5c)/i.test(route)) throw new Error(`kudzu.config navigation.routes[${index}] must be a root-relative path without query, hash, or traversal`)
+    let decoded
+    try { decoded = decodeURIComponent(route) } catch { throw new Error(`kudzu.config navigation.routes[${index}] must be a root-relative path without query, hash, or traversal`) }
+    if (decoded.split("/").includes("..") || /[?#\\\0]/.test(decoded)) throw new Error(`kudzu.config navigation.routes[${index}] must be a root-relative path without query, hash, or traversal`)
+    return route
+  })
+  if (new Set(routes).size !== routes.length) throw new Error("kudzu.config navigation.routes must contain unique paths")
+  return routes
+}
+
+function specializeNavigationTextDescriptors(source) {
+  const dynamic = source
+    .replace("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 ?? \"[]\") : []")
+    .replace("const descriptor = textDescriptors[Number(node.data.slice(\"k-text:\".length))]", "const descriptor = textDescriptors()[Number(node.data.slice(\"k-text:\".length))]")
+  if (dynamic === source) throw new Error("Navigation text descriptor specialization did not match binding-runtime.js")
+  return dynamic
+}
+
 function normalizeBase(value) {
   if (value == null || value === "" || value === "/") return ""
   if (typeof value !== "string" || !value.startsWith("/") || /[?#\0]/.test(value) || /%(?:2f|5c)/i.test(value)) throw new Error("kudzu.config base must be a root-relative path")