@kudzujs/core 0.5.4 → 0.5.6

package/README.md

@@ -6,7 +6,7 @@
 
 HTML-first TSX framework with synchronous state semantics and no virtual DOM.
 
-Kudzu keeps the familiar function-component, props, children, event-handler, and `useState` shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers compile to external ESM.
+Kudzu keeps the familiar function-component, props, children, event-handler, `useState`, and mount-effect shape. Static components compile to HTML. Simple interactions compile to small behavior commands, while normal sync or async JavaScript handlers and mount effects compile to external ESM.
 
 > Experimental `0.4.x`: the compiler API and supported TSX surface may change.
 
@@ -281,7 +281,7 @@ const rows = items.map(item =>
 return <ul>{rows}</ul>
 ```
 
-The root may also be a top-level same-file row component. Kudzu specializes each call at build time, so projected props, callback props, and simple local calculations compile to the same intrinsic list template:
+The root may also be a top-level row component declared in the same file or imported from a relative TypeScript module. Default, named, aliased, and named re-export imports are resolved at build time. Kudzu specializes each call, so projected props, callback props, and simple local calculations compile to the same intrinsic list template:
 
 ```tsx
 function ItemRow({ name, done, onRemove }: {
@@ -306,7 +306,28 @@ const rows = items.map(item => <ItemRow
 
 The original component remains reusable across multiple lists and ordinary JSX. No component function or component runtime is shipped to the browser. Kudzu emits initial items as static HTML, then adds, removes, updates, styles, conditional branches, and moves keyed elements directly. The map may appear directly in JSX or in one top-level immutable `const` rendered once as a JSX child. Existing keys move without remounting, preserving uncontrolled descendant state. Direct `item.<field>` reads use compact markers; derived item expressions compile to external ESM evaluators. Single-level item-local `&&` and ternary JSX conditions patch only their bounded branch and mount or unmount its handlers. Item-local handlers use direct DOM listeners and receive the latest JSON-safe item for their key, including after updates, additions, and reorders. The item remains stored once in shared list state; handler descriptors carry a placeholder that the list runtime fills when mounting or updating the keyed root.
 
-Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level same-file row component, and `key={item.<field>}`. Row components accept destructured projected props and top-level single-`const` calculations before one intrinsic return. A list alias may only be rendered once and cannot be read by other JavaScript. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Exported or imported row components, prop spreads/defaults/rest, children, nested item conditions, lists, or component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level local or relative-imported row component, and `key={item.<field>}`. Row components accept destructured projected props and top-level single-`const` calculations before one intrinsic return. A list alias may only be rendered once and cannot be read by other JavaScript. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions, lists, or component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+
+## Mount Effects
+
+Browser-only initial work uses the familiar empty-dependency effect shape:
+
+```tsx
+import { useEffect, useState } from "@kudzujs/core"
+
+const [items, setItems] = useState([])
+
+useEffect(async () => {
+  const response = await fetch("/api/items")
+  setItems(await response.json())
+}, [])
+```
+
+Kudzu does not execute the effect during static rendering and does not ship the component. It emits one route-specific effect entry that invokes the compiled callback against existing logical state and direct DOM commit capabilities. Effects may update reactive text, attributes, conditions, and keyed lists. Multiple effects start independently in source order, and one synchronous or asynchronous failure is reported without suppressing later effects.
+
+Only inline block-bodied callbacks with a literal empty dependency array are supported. Dependencies, cleanup or other return values, callback parameters, and non-serializable captures are rejected at build time. Pages without effects receive no effect entry and retain their existing output.
+
+A matched mount-fetch benchmark renders a title and two keyed rows from local JSON. With one warm-up and seven rotating clean builds, Kudzu shipped initial HTML, 3.4 KB initial JS gzip, 8.1 KB total output, and built in 374 ms. React CSR shipped no initial content, 59.3 KB initial JS gzip, 189.2 KB total output, and built in 992 ms. Hand-written ESM shipped 534 B initial JS gzip, 1.2 KB total output, and built in 210 ms. Fresh-profile Chrome medians to loaded data were 157.9 ms, 166.5 ms, and 153.4 ms respectively.
 
 ## Normal JavaScript
 
@@ -377,6 +398,7 @@ Supported:
 - Static trusted `dangerouslySetInnerHTML`
 - Base-path deployments, multiple CSS files, and `afterBuild`
 - Primitive `useState` bindings
+- Mount-only `useEffect(fn, [])` compiled to route-specific ESM
 - Synchronous and async event handlers
 - Relative imported helpers in native handlers
 - Serializable component-local captures

package/framework/README.md

@@ -8,10 +8,11 @@
 - `binding-runtime.js`: optional generic attributes, form properties, comment-bounded text patches, and conditional range patches.
 - `list-runtime.js`: optional keyed list validation, external item-expression evaluation, item-local conditional ranges, dynamic styles and item-handler scopes, moves, and cleanup.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
+- `effect-runtime.js`: optional state and capture context for route-specific mount-effect entries.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; mount effects add `effect-runtime.js` and one route-specific entry. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/build.mjs

@@ -29,10 +29,11 @@ export async function build({ quiet = false, minify = true } = {}) {
   const cssFiles = projectFiles.filter(file => file.endsWith(".css")).sort()
   if (!sourceFiles.length) throw new Error("No TypeScript files found in src/")
   const sourceFileSet = new Set(sourceFiles)
+  const sourceIndex = new Map(await Promise.all(sourceFiles.map(async file => [file, await readFile(file, "utf8")])))
 
   const handlerModules = []
   for (const file of sourceFiles) {
-    const handlerModule = await compile(file, sourceFileSet, base)
+    const handlerModule = await compile(file, sourceFileSet, sourceIndex, base)
     if (handlerModule) handlerModules.push(handlerModule)
   }
 
@@ -45,6 +46,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   let listStyleCount = 0
   let stateSeedCount = 0
   const plans = []
+  const effectEntries = []
   const emittedRoutes = new Set()
   const styleUrls = cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`))
 
@@ -57,17 +59,20 @@ export async function build({ quiet = false, minify = true } = {}) {
     for (const { params, props } of entries) {
       const route = routeFromPage(pageFile, params)
       const routePath = withBase(base, `/${route}`)
+      const effectPath = `effects/${route ? `${route}/index` : "index"}.js`
       if (emittedRoutes.has(routePath)) throw new Error(`Duplicate route: ${routePath}`)
       emittedRoutes.add(routePath)
       const result = await renderPage(module.default, {
         ...(module.metadata ?? {}),
         styles: styleUrls.length ? styleUrls : false,
-        base
+        base,
+        effectAsset: assetPath(base, `assets/${effectPath}`)
       }, props)
       const routeDirectory = join(outputDirectory, route)
       await mkdir(routeDirectory, { recursive: true })
       await writeFile(join(routeDirectory, "index.html"), result.html)
       plans.push({ route: routePath, ...result.plan })
+      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: result.plan.effects })
       if (result.hasBehaviors) behaviorCount++
       if (result.hasBindings) bindingCount++
       if (result.hasLists) listCount++
@@ -82,19 +87,37 @@ export async function build({ quiet = false, minify = true } = {}) {
   const nativeEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.native).map(event => event.event)))].sort()
   const hasTextBindings = plans.some(plan => plan.bindings.some(binding => binding.target === "text"))
   const hasListConditions = plans.some(plan => plan.lists.some(list => list.conditions))
+  const hasListTextRanges = plans.some(plan => plan.lists.some(list => list.textRanges))
+  const hasListAttributes = plans.some(plan => plan.lists.some(list => list.attributes))
+  const hasListEvents = plans.some(plan => plan.lists.some(list => list.events))
+  const hasListExpressions = plans.some(plan => plan.lists.some(list => list.expressions))
+  const hasListExpressionAttributes = plans.some(plan => plan.lists.some(list => list.expressionAttributes))
+  const hasListSeeds = plans.some(plan => plan.lists.some(list => list.seed))
+  const hasListAsyncParts = hasListExpressions || hasListExpressionAttributes || hasListConditions
+  const hasListMounts = hasListConditions || plans.some(plan => plan.lists.some(list => list.mount))
   const hasNestedStateCaptures = hasNestedCaptureState(plans)
   const hasSetterCaptures = hasCaptureType(plans, "setter")
+  const hasEffectCaptures = plans.some(plan => plan.effects.some(effect => Object.keys(effect.scope).length))
   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)
     await writeJavaScript(join(assetsDirectory, "kudzu.js"), runtime, minify)
   }
-  if (bindingCount || hasNativeHandlers) await writeJavaScript(join(assetsDirectory, "kudzu-serialization.js"), await readFile(new URL("./serialization.js", import.meta.url), "utf8"), 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)
   })
+  if (hasEffects) {
+    let effectRuntime = await readFile(new URL("./effect-runtime.js", import.meta.url), "utf8")
+    effectRuntime = hasEffectCaptures ? effectRuntime.replace('"./serialization.js"', '"./kudzu-serialization.js"') : effectRuntime.replace(/^import[^\n]+\n/, "")
+    await writeBundledJavaScript(join(assetsDirectory, "kudzu-effect.js"), effectRuntime, minify, {
+      "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures),
+      "globalThis.__KUDZU_EFFECT_CAPTURES__": String(hasEffectCaptures)
+    })
+  }
   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"))
@@ -117,7 +140,17 @@ export async function build({ quiet = false, minify = true } = {}) {
   }`
     listRuntime = listRuntime.replace("  /* list-style */", listStyleCount ? stylePatch : "")
     if (listStyleCount) listRuntime = `import { serializeStyle } from "./kudzu-style.js"\n${listRuntime}`
-    await writeBundledJavaScript(join(assetsDirectory, "kudzu-list.js"), listRuntime, minify, { __KUDZU_LIST_CONDITIONS__: String(hasListConditions) })
+    await writeBundledJavaScript(join(assetsDirectory, "kudzu-list.js"), listRuntime, minify, {
+      __KUDZU_LIST_CONDITIONS__: String(hasListConditions),
+      __KUDZU_LIST_TEXT_RANGES__: String(hasListTextRanges),
+      __KUDZU_LIST_ATTRIBUTES__: String(hasListAttributes),
+      __KUDZU_LIST_EVENTS__: String(hasListEvents),
+      __KUDZU_LIST_EXPRESSIONS__: String(hasListExpressions),
+      __KUDZU_LIST_EXPRESSION_ATTRIBUTES__: String(hasListExpressionAttributes),
+      __KUDZU_LIST_SEEDS__: String(hasListSeeds),
+      __KUDZU_LIST_ASYNC_PARTS__: String(hasListAsyncParts),
+      __KUDZU_LIST_MOUNTS__: String(hasListMounts)
+    })
   }
   if (hasNativeHandlers) {
     const nativeRuntime = (await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"))
@@ -132,6 +165,11 @@ export async function build({ quiet = false, minify = true } = {}) {
     await mkdir(resolve(output, ".."), { recursive: true })
     await writeJavaScript(output, handlerModule.code, 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), minify)
+  }
   const clientModules = await collectClientModules(handlerModules.flatMap(module => module.clientImports), sourceFileSet)
   for (const file of clientModules) {
     const output = join(assetsDirectory, clientModulePath(file))
@@ -181,6 +219,32 @@ function specializeNativeRuntime(source, events, modules) {
   return `${imports}\n${specializeEvents(source, events).replace(/const modules = new Map\(\[[^\n]*\]\)/, `const modules = new Map([${entries}])`)}`
 }
 
+function printEffectEntry(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 { browserState, commitDom } 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}])
+for (const effect of effects) {
+  try {
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, effect.scope))
+    if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}`
+}
+
 function hasCaptureType(value, type) {
   if (!value || typeof value !== "object") return false
   if (value.type === type) return true
@@ -369,9 +433,10 @@ function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
 }
 
-async function compile(file, sourceFiles, base) {
-  const source = await readFile(file, "utf8")
+async function compile(file, sourceFiles, sourceIndex, base) {
+  const source = sourceIndex.get(file)
   const nativeHandlers = []
+  const effectHandlers = []
   const reactiveBindings = []
   const listExpressions = []
   const clientImports = new Set()
@@ -384,7 +449,7 @@ async function compile(file, sourceFiles, base) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, clientImports)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, clientImports)] },
     reportDiagnostics: true
   })
 
@@ -397,10 +462,11 @@ async function compile(file, sourceFiles, base) {
   await mkdir(resolve(output, ".."), { recursive: true })
   await writeFile(output, result.outputText)
 
-  if (!nativeHandlers.length && !reactiveBindings.length && !listExpressions.length) return undefined
+  if (!nativeHandlers.length && !effectHandlers.length && !reactiveBindings.length && !listExpressions.length) return undefined
+  const callbacks = [...nativeHandlers, ...effectHandlers]
   const moduleSource = [
-    printClientImports(nativeHandlers.flatMap(handler => handler.imports), handlerPath),
-    ...nativeHandlers.map(handler => printNativeHandler(handler)),
+    printClientImports(callbacks.flatMap(handler => handler.imports), handlerPath),
+    ...callbacks.map(handler => printNativeHandler(handler)),
     ...reactiveBindings.map(entry => printReactiveBinding(entry)),
     ...listExpressions.map(entry => printListExpression(entry))
   ].join("\n")
@@ -410,15 +476,26 @@ async function compile(file, sourceFiles, base) {
   })
   const moduleErrors = moduleResult.diagnostics?.filter(diagnostic => diagnostic.category === ts.DiagnosticCategory.Error) ?? []
   if (moduleErrors.length) throw new Error(moduleErrors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
-  return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0, clientImports: [...clientImports] }
+  return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0, hasEffects: effectHandlers.length > 0, clientImports: [...clientImports] }
 }
 
-function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, clientImports) {
+function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports) {
   return context => sourceFile => {
     const factory = context.factory
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
+    const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && statement.moduleSpecifier.text === "@kudzujs/core" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
+    const importedSources = new Map()
+    const importedSource = target => {
+      let imported = importedSources.get(target)
+      if (!imported) {
+        imported = normalizeRenderControlFlow(parseSourceFile(target, sourceIndex.get(target)), factory, context)
+        ts.setParentRecursive(imported, false)
+        importedSources.set(target, imported)
+      }
+      return imported
+    }
     const settersByFunction = new Map()
     const functions = new Map()
     const components = new Map()
@@ -520,8 +597,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
     }
     collectRenderedLists(sourceFile)
     const fail = (node, message) => {
-      const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
-      throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
+      throw sourceNodeError(node, sourceFile, message)
     }
     const rejectUnsupportedRenderControl = node => {
       if (ts.isIfStatement(node) && containsRenderControl(node, jsxLocalsByFunction.get(nearestFunction(node)) ?? new Set())) {
@@ -540,13 +616,19 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
     const componentSpecializations = new WeakMap()
     const specializedDeclarations = new WeakSet()
     for (const name of listComponentNames) {
-      const component = components.get(name)
-      if (!component) fail(sourceFile, `Keyed list component ${name} must be declared at the top level in the same file`)
-      if (isExportedDeclaration(component.declaration)) fail(component.declaration, `Keyed list component ${name} cannot be exported`)
+      let component = components.get(name)
+      const local = Boolean(component)
+      if (!component) {
+        const binding = importBindings.get(name)
+        if (!binding || binding.kind === "namespace") fail(sourceFile, `Keyed list component ${name} must be declared locally or imported from a relative TypeScript module`)
+        const imported = binding.kind === "default" ? "default" : binding.imported
+        component = { function: resolveComponentExport(binding.target, imported, importedSource, sourceFiles), declaration: undefined }
+      }
+      if (local && isExportedDeclaration(component.declaration)) fail(component.declaration, `Keyed list component ${name} cannot be exported`)
       const calls = jsxTagUses(sourceFile, name)
-      if (identifierReferenceCount(sourceFile, name) !== calls.length) fail(component.declaration, `Keyed list component ${name} may only be referenced as JSX`)
+      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))
-      specializedDeclarations.add(component.declaration)
+      if (local) specializedDeclarations.add(component.declaration)
     }
     const renderedLists = new WeakMap()
     for (const { node, parts: originalParts } of rawRenderedLists) {
@@ -603,11 +685,38 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       if (componentSpecializations.has(node)) return ts.visitNode(componentSpecializations.get(node).root, visitor)
 
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
-        return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(modulePath(node.moduleSpecifier.text)), node.attributes)
+        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)
       }
 
       if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
-        return factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, factory.createStringLiteral(modulePath(node.moduleSpecifier.text)), node.attributes)
+        const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
+        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 [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.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 (!nearestFunction(node)) fail(node, "useEffect() cannot be used outside a Kudzu component")
+        if (returnsCleanup(callback)) fail(callback, "useEffect() cleanup functions are not supported")
+        if (!ts.isBlock(callback.body)) fail(callback, "useEffect() callback must use a block body")
+        if (returnsEffectValue(callback)) fail(callback, "useEffect() return values are not supported")
+        const setters = settersForNode(node, settersByFunction)
+        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, importBindings, clientImports, "effect", undefined, true)
+        usesBehavior = true
+        return factory.updateCallExpression(node, node.expression, node.typeArguments, [
+          callback,
+          dependencies,
+          factory.createStringLiteral(handlerUrl),
+          factory.createStringLiteral(descriptor.exportName),
+          descriptor.states,
+          descriptor.scope,
+          factory.createStringLiteral(sourceLocation(node, sourceFile))
+        ])
       }
 
       if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression) && node.initializer.expression.text === "useState" && node.initializer.arguments.length === 1) {
@@ -677,7 +786,7 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         }
       }
 
-      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && !isContextProviderValue(node, contexts) && !/^on/i.test(node.name.getText()) && !["key", "ref", "dangerouslysetinnerhtml"].includes(node.name.getText().toLowerCase())) {
+      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && !isContextProviderValue(node, contexts) && !/^on/i.test(node.name.text) && !["key", "ref", "dangerouslysetinnerhtml"].includes(node.name.text.toLowerCase())) {
         const expression = node.initializer.expression
         const setters = settersForNode(node, settersByFunction)
         const usedStates = referencedStateNames(expression, setters)
@@ -690,15 +799,16 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         }
       }
 
-      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && /^on[A-Z]/.test(node.name.getText())) {
+      if (ts.isJsxAttribute(node) && node.initializer && ts.isJsxExpression(node.initializer) && node.initializer.expression && /^on[A-Z]/.test(node.name.text)) {
         const setters = settersForNode(node, settersByFunction)
         const event = compileEvent(node.initializer.expression, setters, functions, factory, nativeHandlers, handlerUrl, listEventItems.get(node), importBindings, clientImports)
         if (event) {
           usesBehavior = true
           return factory.updateJsxAttribute(node, node.name, factory.createJsxExpression(undefined, event))
         }
+        if (ts.isIdentifier(node.initializer.expression) && isDestructuredParameter(node.initializer.expression, nearestFunction(node))) return node
         const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
-        throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${node.name.getText()} must reference a function`)
+        throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${node.name.text} must reference a function`)
       }
 
       return ts.visitEachChild(node, visitor, context)
@@ -854,8 +964,7 @@ function keyedListParts(expression, setters) {
 
 function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions) {
   const fail = (node, message) => {
-    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
-    throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
+    throw sourceNodeError(node, sourceFile, message)
   }
   const root = parts.root
   const item = parts.item
@@ -869,7 +978,7 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) validateElement(node)
     if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, "Nested keyed lists are not supported")
     if (ts.isJsxSpreadAttribute(node) && referencesIdentifier(node.expression, item)) fail(node, "Keyed list item spreads are not supported")
-    if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.getText())) {
+    if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.text)) {
       listEventItems.set(node, item)
       return
     }
@@ -888,9 +997,9 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
         return
       }
       const field = directProperty(expression, item)
-      const isRootKey = ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "key"
+      const isRootKey = ts.isJsxAttribute(node.parent) && node.parent.name.text === "key"
       if (field && ["__proto__", "constructor", "prototype"].includes(field)) fail(node, `Keyed list item property "${field}" is not supported`)
-      if (field && ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
+      if (field && ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.text.toLowerCase())) fail(node, `Keyed list item ${node.parent.name.text} is not supported`)
       if (isRootKey) return
       if (field) {
         listValues.set(node.expression, { field })
@@ -898,7 +1007,7 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
       }
       if (referencesIdentifier(expression, item)) {
         validateListExpression(expression, item, node, fail)
-        if (ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.getText().toLowerCase())) fail(node, `Keyed list item ${node.parent.name.getText()} is not supported`)
+        if (ts.isJsxAttribute(node.parent) && ["ref", "dangerouslysetinnerhtml"].includes(node.parent.name.text.toLowerCase())) fail(node, `Keyed list item ${node.parent.name.text} is not supported`)
         listValues.set(node.expression, { item })
         return
       }
@@ -971,6 +1080,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
 
 function substituteClone(root, substitutions, factory, context) {
   const visit = (node, shadowed = new Set()) => {
+    if (ts.isTypeNode(node)) return cloneAst(node, factory, context)
     if (ts.isShorthandPropertyAssignment(node) && substitutions.has(node.name.text) && !shadowed.has(node.name.text)) {
       return factory.createPropertyAssignment(cloneAst(node.name, factory, context), cloneAst(substitutions.get(node.name.text), factory, context))
     }
@@ -1026,6 +1136,10 @@ function isFunctionLike(node) {
   return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)
 }
 
+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 isExportedDeclaration(node) {
   const statement = ts.isVariableDeclaration(node) ? node.parent?.parent : node
   return statement?.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword || modifier.kind === ts.SyntaxKind.DefaultKeyword) ?? false
@@ -1057,6 +1171,7 @@ const assignmentOperators = new Set([
 
 function validateListExpression(expression, item, source, fail) {
   const visit = node => {
+    if (ts.isTypeNode(node)) return
     if (ts.isElementAccessExpression(node) && referencesIdentifier(node.expression, item)) {
       const key = node.argumentExpression
       if (!ts.isStringLiteral(key) && !ts.isNumericLiteral(key)) fail(source, "Derived keyed list item computed properties require a direct string or numeric literal key")
@@ -1249,26 +1364,37 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   const optimized = compileOptimizedEvent(expression, setters, factory)
   if (optimized) return optimized
 
+  const descriptor = compileNativeCallback(expression, setters, factory, nativeHandlers, importBindings, clientImports, "handler", listItem)
+  return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
+    factory.createStringLiteral(handlerUrl),
+    factory.createStringLiteral(descriptor.exportName),
+    descriptor.states,
+    descriptor.scope
+  ])
+}
+
+function compileNativeCallback(expression, setters, factory, entries, importBindings, clientImports, prefix, listItem, deferValues = false) {
   const allCaptures = nativeCaptureNames(expression, setters)
   const imports = [...referencedImportedBindings(expression, importBindings)].map(name => importBindings.get(name))
   const captures = new Set([...allCaptures].filter(name => !importBindings.has(name)))
   for (const entry of imports) clientImports.add(entry.target)
   const usedStates = nativeStateNames(expression, setters)
-  const exportName = `handler${nativeHandlers.length}`
-  nativeHandlers.push({ exportName, expression, captures, imports, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))) })
-  const states = [...usedStates].map(name => factory.createArrayLiteralExpression([
-    factory.createStringLiteral(name),
-    factory.createIdentifier(name)
-  ]))
-  return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
-    factory.createStringLiteral(handlerUrl),
-    factory.createStringLiteral(exportName),
-    factory.createArrayLiteralExpression(states),
-    factory.createArrayLiteralExpression([...captures].map(name => factory.createArrayLiteralExpression([
+  const exportName = `${prefix}${entries.length}`
+  entries.push({ exportName, expression, captures, imports, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))) })
+  const value = name => deferValues
+    ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createIdentifier(name))
+    : factory.createIdentifier(name)
+  return {
+    exportName,
+    states: factory.createArrayLiteralExpression([...usedStates].map(name => factory.createArrayLiteralExpression([
+      factory.createStringLiteral(name),
+      value(name)
+    ]))),
+    scope: factory.createArrayLiteralExpression([...captures].map(name => factory.createArrayLiteralExpression([
       factory.createStringLiteral(name),
-      name === listItem ? factory.createCallExpression(factory.createIdentifier("__kListItem"), undefined, []) : factory.createIdentifier(name)
+      name === listItem ? factory.createCallExpression(factory.createIdentifier("__kListItem"), undefined, []) : value(name)
     ])))
-  ])
+  }
 }
 
 function nativeStateNames(expression, setters) {
@@ -1279,7 +1405,8 @@ function referencedStateNames(root, setters, scopeRoot = root) {
   const stateNames = new Set(setters.values())
   const used = new Set()
   const visit = node => {
-    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text)) used.add(setters.get(node.expression.text))
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && !isShadowedIdentifier(node.expression, scopeRoot)) used.add(setters.get(node.expression.text))
+    if (ts.isIdentifier(node) && setters.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, scopeRoot)) used.add(setters.get(node.text))
     if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, scopeRoot)) used.add(node.text)
     ts.forEachChild(node, visit)
   }
@@ -1318,20 +1445,22 @@ function referencedImportedBindings(expression, imports) {
 
 function captureNames(declarationRoot, referenceRoot, setters) {
   const local = new Set()
-  const collectDeclarations = node => {
-    if (ts.isVariableDeclaration(node)) for (const name of bindingNames(node.name)) local.add(name)
-    if (ts.isParameter(node)) for (const name of bindingNames(node.name)) local.add(name)
-    if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) local.add(node.name.text)
-    ts.forEachChild(node, collectDeclarations)
+  if (!isFunctionLike(declarationRoot)) {
+    const collectDeclarations = node => {
+      if (ts.isVariableDeclaration(node)) for (const name of bindingNames(node.name)) local.add(name)
+      if (ts.isParameter(node)) for (const name of bindingNames(node.name)) local.add(name)
+      if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) local.add(node.name.text)
+      ts.forEachChild(node, collectDeclarations)
+    }
+    collectDeclarations(declarationRoot)
   }
-  collectDeclarations(declarationRoot)
-
   const stateNames = new Set(setters.values())
   const captures = new Set()
   const visit = node => {
     if (ts.isTypeNode(node)) return
-    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !local.has(node.text) && !setters.has(node.text) && !stateNames.has(node.text) && !nativeGlobals.has(node.text)) {
-      captures.add(node.text)
+    if (ts.isIdentifier(node)) {
+      const declared = isFunctionLike(declarationRoot) ? isShadowedIdentifier(node, declarationRoot) : local.has(node.text)
+      if (isReferenceIdentifier(node) && !declared && !setters.has(node.text) && !stateNames.has(node.text) && !nativeGlobals.has(node.text)) captures.add(node.text)
     }
     ts.forEachChild(node, visit)
   }
@@ -1353,7 +1482,7 @@ function isReferenceIdentifier(node) {
       (ts.isVariableDeclaration(parent) && parent.name === node) ||
       (ts.isParameter(parent) && parent.name === node) ||
       (ts.isFunctionDeclaration(parent) && parent.name === node) ||
-      (ts.isBindingElement(parent) && parent.name === node) ||
+      (ts.isBindingElement(parent) && (parent.name === node || parent.propertyName === node)) ||
       ts.isImportSpecifier(parent) || ts.isImportClause(parent)) return false
   return true
 }
@@ -1373,6 +1502,43 @@ function isShadowedByParameter(node, scopeRoot) {
   return false
 }
 
+function isShadowedIdentifier(node, scopeRoot) {
+  if (isShadowedByParameter(node, scopeRoot)) return true
+  if (node === scopeRoot) return false
+  if (isFunctionLike(scopeRoot) && scopeRoot.name?.text === node.text) return true
+  if (isFunctionLike(scopeRoot) && functionVarDeclaresName(scopeRoot, node.text)) return true
+  for (let current = node.parent; current; current = current.parent) {
+    if (current === scopeRoot) break
+    if (ts.isBlock(current) && current.statements.some(statement => statementDeclaresName(statement, node.text))) return true
+    if (ts.isCaseBlock(current) && current.clauses.some(clause => clause.statements.some(statement => statementDeclaresName(statement, node.text)))) return true
+    if (ts.isCatchClause(current) && current.variableDeclaration && bindingNames(current.variableDeclaration.name).includes(node.text)) return true
+    if ((ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current)) && loopDeclaresName(current, node.text)) return true
+    if (isFunctionLike(current) && functionVarDeclaresName(current, node.text)) return true
+  }
+  return false
+}
+
+function statementDeclaresName(statement, name) {
+  if (ts.isVariableStatement(statement)) return statement.declarationList.declarations.some(declaration => bindingNames(declaration.name).includes(name))
+  return (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name?.text === name
+}
+
+function loopDeclaresName(loop, name) {
+  const declaration = ts.isForStatement(loop) ? loop.initializer : loop.initializer
+  return declaration && ts.isVariableDeclarationList(declaration) && declaration.declarations.some(entry => bindingNames(entry.name).includes(name))
+}
+
+function functionVarDeclaresName(fn, name) {
+  let found = false
+  const visit = node => {
+    if (found || node !== fn.body && isFunctionLike(node)) return
+    if (ts.isVariableDeclarationList(node) && (node.flags & ts.NodeFlags.BlockScoped) === 0 && node.declarations.some(entry => bindingNames(entry.name).includes(name))) found = true
+    if (!found) ts.forEachChild(node, visit)
+  }
+  if (fn.body) visit(fn.body)
+  return found
+}
+
 function settersForNode(node, settersByFunction) {
   for (let current = node.parent; current; current = current.parent) {
     if (!ts.isFunctionDeclaration(current) && !ts.isFunctionExpression(current) && !ts.isArrowFunction(current)) continue
@@ -1399,6 +1565,96 @@ function clientImportBindings(sourceFile, file, sourceFiles) {
   return bindings
 }
 
+function resolveComponentExport(file, exportName, getSource, sourceFiles, trail = []) {
+  const key = `${file}:${exportName}`
+  if (trail.includes(key)) throw new Error(`Imported keyed list component re-export cycle: ${[...trail, key].map(entry => relative(root, entry.slice(0, entry.lastIndexOf(":")))).join(" -> ")}`)
+  const sourceFile = getSource(file)
+  const nextTrail = [...trail, key]
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(statement)) {
+      const isDefault = statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)
+      const isExported = statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)
+      if (exportName === "default" && isDefault || exportName !== "default" && isExported && statement.name?.text === exportName) return statement
+    }
+    if (ts.isVariableStatement(statement) && statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword) && exportName !== "default") {
+      const declaration = statement.declarationList.declarations.find(entry => ts.isIdentifier(entry.name) && entry.name.text === exportName)
+      if (declaration?.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) return declaration.initializer
+    }
+    if (exportName === "default" && ts.isExportAssignment(statement) && !statement.isExportEquals && ts.isIdentifier(statement.expression)) {
+      const component = localComponentDeclaration(sourceFile, statement.expression.text)
+      if (component) return component
+    }
+    if (ts.isExportDeclaration(statement) && ts.isNamedExports(statement.exportClause)) {
+      const entry = statement.exportClause.elements.find(element => !element.isTypeOnly && element.name.text === exportName)
+      if (!entry) continue
+      const imported = (entry.propertyName ?? entry.name).text
+      if (statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+        if (!statement.moduleSpecifier.text.startsWith(".")) throw sourceNodeError(statement, sourceFile, "Imported keyed list components must use relative TypeScript re-exports")
+        const target = resolveSourceImport(file, statement.moduleSpecifier.text, sourceFiles)
+        return resolveComponentExport(target, imported, getSource, sourceFiles, nextTrail)
+      }
+      const component = localComponentDeclaration(sourceFile, imported)
+      if (component) return component
+    }
+  }
+  throw new Error(`${relative(root, file)} does not export a statically analyzable keyed list component named ${JSON.stringify(exportName)}`)
+}
+
+function localComponentDeclaration(sourceFile, name) {
+  for (const statement of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name?.text === name) return statement
+    if (ts.isVariableStatement(statement)) {
+      const declaration = statement.declarationList.declarations.find(entry => ts.isIdentifier(entry.name) && entry.name.text === name)
+      if (declaration?.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) return declaration.initializer
+    }
+  }
+  return undefined
+}
+
+function sourceNodeError(node, fallbackSource, message) {
+  const original = ts.getOriginalNode(node)
+  const sourceFile = original.getSourceFile?.()?.fileName ? original.getSourceFile() : fallbackSource
+  const position = sourceFile.getLineAndCharacterOfPosition(original.getStart(sourceFile))
+  return new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
+}
+
+function sourceLocation(node, fallbackSource) {
+  const original = ts.getOriginalNode(node)
+  const sourceFile = original.getSourceFile?.()?.fileName ? original.getSourceFile() : fallbackSource
+  const position = sourceFile.getLineAndCharacterOfPosition(original.getStart(sourceFile))
+  return `${sourceFile.fileName}:${position.line + 1}:${position.character + 1}`
+}
+
+function returnsCleanup(callback) {
+  if (ts.isArrowFunction(callback) && !ts.isBlock(callback.body)) {
+    const body = unwrapExpression(callback.body)
+    return ts.isArrowFunction(body) || ts.isFunctionExpression(body)
+  }
+  let found = false
+  const visit = node => {
+    if (found || node !== callback.body && isFunctionLike(node)) return
+    if (ts.isReturnStatement(node) && node.expression) {
+      const expression = unwrapExpression(node.expression)
+      if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) found = true
+    }
+    if (!found) ts.forEachChild(node, visit)
+  }
+  visit(callback.body)
+  return found
+}
+
+function returnsEffectValue(callback) {
+  let found = false
+  const visit = node => {
+    if (found || node !== callback.body && isFunctionLike(node)) return
+    if (ts.isReturnStatement(node) && node.expression) found = true
+    if (!found) ts.forEachChild(node, visit)
+  }
+  visit(callback.body)
+  return found
+}
+
 function printClientImports(entries, handlerPath) {
   const unique = new Map(entries.map(entry => [`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`, entry]))
   const groups = Map.groupBy(unique.values(), entry => entry.target)
@@ -1474,7 +1730,7 @@ function resolveSourceImport(importer, specifier, sourceFiles) {
   const stem = /\.(?:js|jsx|ts|tsx)$/.test(extension) ? base.slice(0, -extension.length) : base
   const candidates = extension === ".ts" || extension === ".tsx"
     ? [base]
-    : [`${stem}.ts`, `${stem}.tsx`]
+    : [`${stem}.ts`, `${stem}.tsx`, join(stem, "index.ts"), join(stem, "index.tsx")]
   const matches = candidates.filter(candidate => sourceFiles.has(candidate))
   if (matches.length !== 1) throw new Error(`${relative(root, importer)} Relative import ${JSON.stringify(specifier)} must resolve to one TypeScript file in src/`)
   return matches[0]
@@ -1516,24 +1772,33 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
   const stateNames = new Set(setters.values())
   const transformer = context => root => {
     const visitor = node => {
-      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text)) {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
         return factory.createCallExpression(
           factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"),
           undefined,
           [factory.createStringLiteral(setters.get(node.expression.text)), ...node.arguments.map(argument => ts.visitNode(argument, visitor))]
         )
       }
-      if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression)) {
+      if (ts.isShorthandPropertyAssignment(node) && setters.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        return factory.createPropertyAssignment(node.name, setterReference(factory, setters.get(node.name.text)))
+      }
+      if (ts.isIdentifier(node) && setters.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
+        return setterReference(factory, setters.get(node.text))
+      }
+      if (ts.isShorthandPropertyAssignment(node) && stateNames.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        return factory.createPropertyAssignment(node.name, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(node.name.text)]))
+      }
+      if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
         return factory.createCallExpression(
           factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"),
           undefined,
           [factory.createStringLiteral(node.text)]
         )
       }
-      if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text)) {
+      if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
         return factory.createPropertyAssignment(node.name, scopeRead(factory, node.name.text))
       }
-      if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node)) {
+      if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
         return scopeRead(factory, node.text)
       }
       return ts.visitEachChild(node, visitor, context)
@@ -1562,6 +1827,17 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
   }
 }
 
+function setterReference(factory, stateName) {
+  return factory.createArrowFunction(
+    undefined,
+    undefined,
+    [factory.createParameterDeclaration(undefined, undefined, "value")],
+    undefined,
+    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+    factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"), undefined, [factory.createStringLiteral(stateName), factory.createIdentifier("value")])
+  )
+}
+
 function printReactiveBinding({ exportName, expression, captures, states }) {
   const factory = ts.factory
   const transformer = context => root => {
@@ -1667,11 +1943,6 @@ function numericExpression(factory, value, negative) {
   return negative ? factory.createPrefixUnaryExpression(ts.SyntaxKind.MinusToken, literal) : literal
 }
 
-function modulePath(value) {
-  if (/\.(?:ts|tsx|js|jsx)$/.test(value)) return value.replace(/\.(?:ts|tsx|js|jsx)$/, ".mjs")
-  return `${value}.mjs`
-}
-
 function compiledPath(file) {
   return join(workDirectory, relative(sourceDirectory, file)).replace(/\.(?:ts|tsx)$/, ".mjs")
 }

package/framework/core.d.ts

@@ -1,6 +1,7 @@
 export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
 
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
+export function useEffect(effect: () => void | Promise<void>, dependencies: readonly []): void
 
 export interface RefObject<T> {
   readonly current: T | null
@@ -46,11 +47,13 @@ export function renderPage<Props = Record<string, never>>(
     manifest?: string
     styles?: boolean | string[]
     base?: string
+    effectAsset?: string
   },
   props?: Props
 ): Promise<{
   html: string
   hasBehaviors: boolean
+  hasEffects: boolean
   hasBindings: boolean
   hasLists: boolean
   hasListStyles: boolean
@@ -62,6 +65,7 @@ export function renderPage<Props = Record<string, never>>(
       commands?: Array<[string, string, unknown]>
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
+    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }>
     bindings: Array<{
       target: string
       state?: string

package/framework/core.mjs

@@ -44,6 +44,16 @@ export function useState(initialValue, name) {
   return [signal, setter]
 }
 
+export function useEffect(callback, dependencies, module, handler, states, scope, source) {
+  if (!renderContext) throw new Error("useEffect() can only run while rendering a Kudzu component")
+  if (typeof callback !== "function" || !Array.isArray(dependencies) || dependencies.length || !module || !handler) {
+    throw new Error("useEffect() must be compiled with a literal empty dependency array")
+  }
+  renderContext.effects.push({ module, handler, states, scope, source })
+  renderContext.hasBehaviors = true
+  renderContext.hasEffects = true
+}
+
 export function useRef(initialValue) {
   if (!renderContext) throw new Error("useRef() can only run while rendering a Kudzu component")
   if (initialValue !== null) throw new Error("Kudzu DOM refs must initialize with null")
@@ -82,8 +92,14 @@ export function nativeBehavior(module, handler, states, scope) {
     [nativeBehaviorMarker]: true,
     module,
     handler,
+    ...nativeDescriptor(states, scope)
+  }
+}
+
+function nativeDescriptor(states, scope) {
+  return {
     states: Object.fromEntries(states.map(([name, signal]) => {
-      if (!signal?.[signalMarker]) throw new Error("A native behavior must target framework state")
+      if (!signal?.[signalMarker]) throw new Error("A native callback must target framework state")
       return [name, signal.id]
     })),
     scope: Object.fromEntries(scope.map(([name, value]) => [name, value?.[signalMarker] ? { type: "state", id: value.id } : serializeCapture(name, value, new Set())]))
@@ -226,10 +242,21 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}) {
-  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], bindings: [], textBindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const body = await renderNode({ type: component, props })
+    renderContext.effects = renderContext.effects.map(effect => {
+      try {
+        return {
+          module: effect.module,
+          handler: effect.handler,
+          ...nativeDescriptor(effect.states.map(([name, read]) => [name, read()]), effect.scope.map(([name, read]) => [name, read()]))
+        }
+      } catch (error) {
+        throw new Error(`${effect.source} ${error.message}`)
+      }
+    })
     const title = escapeHtml(metadata.title ?? "Kudzu")
     const head = renderMetadata(metadata)
     const styles = metadata.styles === false
@@ -247,6 +274,9 @@ export async function renderPage(component, metadata = {}, props = {}) {
     const listRuntime = renderContext.hasLists
       ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-list.js")}"></script>`
       : ""
+    const effectRuntime = renderContext.hasEffects
+      ? `<script type="module" src="${escapeAttribute(metadata.effectAsset)}"></script>`
+      : ""
     const listStates = new Set(renderContext.lists.map(list => list.state))
     const seededListStates = new Set(renderContext.lists.filter(list => list.seed && !renderContext.textStates.has(list.state) && !renderContext.conditionStates.has(list.state)).map(list => list.state))
     const initialState = renderContext.hasBehaviors
@@ -263,8 +293,9 @@ export async function renderPage(component, metadata = {}, props = {}) {
       : ""
 
     return {
-      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}</head><body${state}${textBindings}>${body}${runtime}${bindingRuntime}${listRuntime}${nativeRuntime}</body></html>`,
+      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}</head><body${state}${textBindings}>${body}${runtime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
+      hasEffects: renderContext.hasEffects,
       hasBindings: renderContext.hasBindings,
       hasLists: renderContext.hasLists,
       hasListStyles: renderContext.hasListStyles,
@@ -272,6 +303,7 @@ export async function renderPage(component, metadata = {}, props = {}) {
       plan: {
         states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
         events: renderContext.events,
+        effects: renderContext.effects,
         bindings: renderContext.bindings,
         conditions: renderContext.conditions,
         lists: renderContext.lists
@@ -552,6 +584,11 @@ async function renderList(node, namespace, selectValue) {
     const template = await renderNode(node.render({}), namespace, selectValue)
     if (template.includes("data-k-native-")) descriptor.mount = true
     if (template.includes("data-k-list-condition")) descriptor.conditions = true
+    if (template.includes("data-k-list-text-end")) descriptor.textRanges = true
+    if (template.includes("data-k-list-attrs")) descriptor.attributes = true
+    if (template.includes("data-k-list-events")) descriptor.events = true
+    if (template.includes("data-k-list-expression=")) descriptor.expressions = true
+    if (template.includes("data-k-list-expression-attrs")) descriptor.expressionAttributes = true
     const seed = listSeed(node.items.value, renderContext.listFields)
     if (seed) descriptor.seed = seed
     let current = ""

package/framework/effect-runtime.js

@@ -0,0 +1,39 @@
+import { deserialize } from "./serialization.js"
+
+export function createEffectContext(state, stateIds, commit, serializedScope = {}) {
+  const changed = new Set()
+  let scheduled = false
+
+  const flush = () => {
+    scheduled = false
+    const ids = [...changed]
+    changed.clear()
+    for (const id of ids) commit(id, state.get(id))
+  }
+
+  const setId = (id, value) => {
+    const current = state.get(id)
+    state.set(id, typeof value === "function" ? value(current) : value)
+    changed.add(id)
+    if (!scheduled) {
+      scheduled = true
+      queueMicrotask(flush)
+    }
+  }
+
+  const scope = globalThis.__KUDZU_EFFECT_CAPTURES__
+    ? Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value, id => state.get(id), globalThis.__KUDZU_CAPTURE_SETTER__ ? setId : undefined)]))
+    : undefined
+
+  return {
+    get(name) {
+      return state.get(stateIds[name])
+    },
+    scope(name) {
+      return globalThis.__KUDZU_EFFECT_CAPTURES__ ? serializedScope[name]?.type === "state" ? state.get(serializedScope[name].id) : scope[name] : undefined
+    },
+    set(name, value) {
+      setId(stateIds[name], value)
+    }
+  }
+}

package/framework/list-runtime.js

@@ -3,11 +3,11 @@ import { browserState, mountDom, registerCommitter, registerMountHook, registerU
 const listTargets = new Map()
 const listRegistrations = new WeakMap()
 const mountedLists = new WeakSet()
-const imports = new Map()
-const revisions = new WeakMap()
+const imports = __KUDZU_LIST_ASYNC_PARTS__ ? new Map() : undefined
+const revisions = __KUDZU_LIST_ASYNC_PARTS__ ? new WeakMap() : undefined
 const itemParts = new WeakMap()
-const conditionOwners = new WeakMap()
-const itemPartsSelector = `[data-k-list-text],[data-k-list-attrs],[data-k-list-events],[data-k-list-expression],[data-k-list-expression-attrs]${__KUDZU_LIST_CONDITIONS__ ? ",[data-k-list-condition]" : ""}`
+const conditionOwners = __KUDZU_LIST_CONDITIONS__ ? new WeakMap() : undefined
+const itemPartsSelector = `[data-k-list-text]${__KUDZU_LIST_ATTRIBUTES__ ? ",[data-k-list-attrs]" : ""}${__KUDZU_LIST_EVENTS__ ? ",[data-k-list-events]" : ""}${__KUDZU_LIST_EXPRESSIONS__ ? ",[data-k-list-expression]" : ""}${__KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? ",[data-k-list-expression-attrs]" : ""}${__KUDZU_LIST_CONDITIONS__ ? ",[data-k-list-condition]" : ""}`
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -34,13 +34,13 @@ function mountLists(root) {
     const templateRoot = start.content.firstElementChild
     const parts = listItemPartPlan(templateRoot)
     for (const root of roots) __KUDZU_LIST_CONDITIONS__ && descriptor.conditions ? listItemParts(root) : mapListItemParts(parts, root)
-    if (descriptor.seed && !browserState.has(descriptor.state)) browserState.set(descriptor.state, roots.map((root, index) => seedListItem(root, descriptor, index)))
+    if (__KUDZU_LIST_SEEDS__ && descriptor.seed && !browserState.has(descriptor.state)) browserState.set(descriptor.state, roots.map((root, index) => seedListItem(root, descriptor, index)))
     const items = browserState.get(descriptor.state)
     const list = {
       start,
       descriptor,
       parts,
-      seedFields: descriptor.seed && Object.keys(descriptor.seed),
+      seedFields: __KUDZU_LIST_SEEDS__ && descriptor.seed && Object.keys(descriptor.seed),
       roots: new Map(roots.map((node, index) => [keyToken(descriptor.keys[index]), node])),
       values: new Map(),
       container: roots[0]?.parentNode,
@@ -77,7 +77,7 @@ function updateList(list) {
     const key = item?.[list.descriptor.key]
     if (!validListKey(key)) throw new Error(`Keyed list key "${list.descriptor.key}" must be a string or finite number`)
     assertListItem(item)
-    const seededValue = list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed)
+    const seededValue = __KUDZU_LIST_SEEDS__ ? list.seedFields && seededListValue(item, list.seedFields, list.descriptor.seed) : undefined
     if (seededValue === undefined) assertListValue(item, seen, true)
     const token = keyToken(key)
     if (keys.has(token)) throw new Error(`Duplicate keyed list key: ${String(key)}`)
@@ -108,13 +108,13 @@ function updateList(list) {
   }
   for (const [token, node] of list.roots) {
     if (keys.has(token)) continue
-    if (list.descriptor.mount) {
+    if (__KUDZU_LIST_MOUNTS__ && list.descriptor.mount) {
       unmountDom(node)
       node.remove()
     } else node.remove()
   }
   if (added) {
-    if (list.descriptor.mount) mountDom(additions)
+    if (__KUDZU_LIST_MOUNTS__ && list.descriptor.mount) mountDom(additions)
     parent.insertBefore(additions, list.boundary)
     list.container ??= parent
   }
@@ -142,8 +142,8 @@ function updateList(list) {
 }
 
 function fillListItem(root, item) {
-  const revision = (revisions.get(root) ?? 0) + 1
-  revisions.set(root, revision)
+  const revision = __KUDZU_LIST_ASYNC_PARTS__ ? (revisions.get(root) ?? 0) + 1 : 0
+  if (__KUDZU_LIST_ASYNC_PARTS__) revisions.set(root, revision)
   const parts = listItemParts(root)
   fillListParts(root, parts, item, revision)
 }
@@ -159,30 +159,38 @@ function fillListParts(root, parts, item, revision) {
       node.textContent = value
     }
   }
-  for (const [marker, field] of parts.texts) {
-    patchListText(marker, "template[data-k-list-text-end]", item?.[field])
+  if (__KUDZU_LIST_TEXT_RANGES__) {
+    for (const [marker, field] of parts.texts) patchListText(marker, "template[data-k-list-text-end]", item?.[field])
   }
-  for (const [node, attributes] of parts.attributes) {
-    for (const [target, field] of attributes) patchBinding(node, target, item?.[field])
-  }
-  for (const [node, events] of parts.events) {
-    for (const [event, native] of JSON.parse(events)) {
-      native.scope = Object.fromEntries(Object.entries(native.scope).map(([name, value]) => [name, value?.type === "list-item" ? serializeItem(item) : value]))
-      node.dataset[`kNative${capitalize(event)}`] = JSON.stringify(native)
+  if (__KUDZU_LIST_ATTRIBUTES__) {
+    for (const [node, attributes] of parts.attributes) {
+      for (const [target, field] of attributes) patchBinding(node, target, item?.[field])
     }
   }
-  for (const [marker, descriptor] of parts.expressions) {
-    evaluate(descriptor, item).then(value => {
-      if (revisions.get(root) === revision && root.isConnected) patchListText(marker, "template[data-k-list-expression-end]", value)
-    }).catch(error => console.error(error))
+  if (__KUDZU_LIST_EVENTS__) {
+    for (const [node, events] of parts.events) {
+      for (const [event, native] of JSON.parse(events)) {
+        native.scope = Object.fromEntries(Object.entries(native.scope).map(([name, value]) => [name, value?.type === "list-item" ? serializeItem(item) : value]))
+        node.dataset[`kNative${capitalize(event)}`] = JSON.stringify(native)
+      }
+    }
   }
-  for (const [node, attributes] of parts.expressionAttributes) {
-    for (const [target, module, handler] of attributes) {
-      evaluate({ module, handler }, item).then(value => {
-        if (revisions.get(root) === revision && root.isConnected) patchBinding(node, target, value)
+  if (__KUDZU_LIST_EXPRESSIONS__) {
+    for (const [marker, descriptor] of parts.expressions) {
+      evaluate(descriptor, item).then(value => {
+        if (revisions.get(root) === revision && root.isConnected) patchListText(marker, "template[data-k-list-expression-end]", value)
       }).catch(error => console.error(error))
     }
   }
+  if (__KUDZU_LIST_EXPRESSION_ATTRIBUTES__) {
+    for (const [node, attributes] of parts.expressionAttributes) {
+      for (const [target, module, handler] of attributes) {
+        evaluate({ module, handler }, item).then(value => {
+          if (revisions.get(root) === revision && root.isConnected) patchBinding(node, target, value)
+        }).catch(error => console.error(error))
+      }
+    }
+  }
   if (__KUDZU_LIST_CONDITIONS__) {
     for (const [marker, descriptor] of parts.conditions) {
       evaluate(descriptor, item).then(value => {
@@ -198,10 +206,10 @@ function listItemParts(root) {
   parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [], conditions: [] }
   for (const node of matching(root, itemPartsSelector)) {
     if (node.hasAttribute("data-k-list-text")) (node.tagName === "TEMPLATE" ? parts.texts : parts.directTexts).push([node, node.dataset.kListText])
-    if (node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
-    if (node.hasAttribute("data-k-list-events")) parts.events.push([node, node.dataset.kListEvents])
-    if (node.hasAttribute("data-k-list-expression")) parts.expressions.push([node, JSON.parse(node.dataset.kListExpression)])
-    if (node.hasAttribute("data-k-list-expression-attrs")) parts.expressionAttributes.push([node, JSON.parse(node.dataset.kListExpressionAttrs)])
+    if (__KUDZU_LIST_ATTRIBUTES__ && node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
+    if (__KUDZU_LIST_EVENTS__ && node.hasAttribute("data-k-list-events")) parts.events.push([node, node.dataset.kListEvents])
+    if (__KUDZU_LIST_EXPRESSIONS__ && node.hasAttribute("data-k-list-expression")) parts.expressions.push([node, JSON.parse(node.dataset.kListExpression)])
+    if (__KUDZU_LIST_EXPRESSION_ATTRIBUTES__ && node.hasAttribute("data-k-list-expression-attrs")) parts.expressionAttributes.push([node, JSON.parse(node.dataset.kListExpressionAttrs)])
     if (__KUDZU_LIST_CONDITIONS__ && node.hasAttribute("data-k-list-condition")) {
       parts.conditions.push([node, JSON.parse(node.dataset.kListCondition)])
       conditionOwners.set(node, root)
@@ -217,11 +225,11 @@ function listItemPartPlan(template) {
   const parts = listItemParts(template)
   return {
     directTexts: parts.directTexts.map(([node, field]) => [indexes.get(node), field]),
-    texts: parts.texts.map(([node, field]) => [indexes.get(node), field]),
-    attributes: parts.attributes.map(([node, attributes]) => [indexes.get(node), attributes]),
-    events: parts.events.map(([node, events]) => [indexes.get(node), events]),
-    expressions: parts.expressions.map(([node, descriptor]) => [indexes.get(node), descriptor]),
-    expressionAttributes: parts.expressionAttributes.map(([node, attributes]) => [indexes.get(node), attributes]),
+    texts: __KUDZU_LIST_TEXT_RANGES__ ? parts.texts.map(([node, field]) => [indexes.get(node), field]) : [],
+    attributes: __KUDZU_LIST_ATTRIBUTES__ ? parts.attributes.map(([node, attributes]) => [indexes.get(node), attributes]) : [],
+    events: __KUDZU_LIST_EVENTS__ ? parts.events.map(([node, events]) => [indexes.get(node), events]) : [],
+    expressions: __KUDZU_LIST_EXPRESSIONS__ ? parts.expressions.map(([node, descriptor]) => [indexes.get(node), descriptor]) : [],
+    expressionAttributes: __KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? parts.expressionAttributes.map(([node, attributes]) => [indexes.get(node), attributes]) : [],
     conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([node, descriptor]) => [indexes.get(node), descriptor]) : []
   }
 }
@@ -230,11 +238,11 @@ function mapListItemParts(parts, root) {
   const target = [root, ...root.querySelectorAll("*")]
   itemParts.set(root, {
     directTexts: parts.directTexts.map(([index, field]) => [target[index], field]),
-    texts: parts.texts.map(([index, field]) => [target[index], field]),
-    attributes: parts.attributes.map(([index, attributes]) => [target[index], attributes]),
-    events: parts.events.map(([index, events]) => [target[index], events]),
-    expressions: parts.expressions.map(([index, descriptor]) => [target[index], descriptor]),
-    expressionAttributes: parts.expressionAttributes.map(([index, attributes]) => [target[index], attributes]),
+    texts: __KUDZU_LIST_TEXT_RANGES__ ? parts.texts.map(([index, field]) => [target[index], field]) : [],
+    attributes: __KUDZU_LIST_ATTRIBUTES__ ? parts.attributes.map(([index, attributes]) => [target[index], attributes]) : [],
+    events: __KUDZU_LIST_EVENTS__ ? parts.events.map(([index, events]) => [target[index], events]) : [],
+    expressions: __KUDZU_LIST_EXPRESSIONS__ ? parts.expressions.map(([index, descriptor]) => [target[index], descriptor]) : [],
+    expressionAttributes: __KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? parts.expressionAttributes.map(([index, attributes]) => [target[index], attributes]) : [],
     conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([index, descriptor]) => {
       conditionOwners.set(target[index], root)
       return [target[index], descriptor]

package/package.json

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