@kudzujs/core 0.5.10 → 0.6.0

package/framework/core.d.ts

@@ -54,8 +54,12 @@ export function renderPage<Props = Record<string, never>>(
     effectAsset?: string
     paramAsset?: string
     runtimeParams?: string[]
+    navigationAsset?: string
+    applicationId?: string
+    layoutId?: string
   },
-  props?: Props
+  props?: Props,
+  layout?: (props: { children: unknown }) => unknown | Promise<unknown>
 ): Promise<{
   html: string
   hasBehaviors: boolean
@@ -66,14 +70,14 @@ export function renderPage<Props = Record<string, never>>(
   hasListStyles: boolean
   hasStateSeed: boolean
   plan: {
-    states: Array<{ id: string; name: string; initialValue: unknown }>
+    states: Array<{ id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route" }>
     params: Array<{ name: string; id: string }>
     events: Array<{
       event: string
       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>; dependencies?: string[]; cleanup?: true }>
+    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown>; lifetime?: "layout" | "route"; dependencies?: string[]; cleanup?: true; owner?: string; list?: true }>
     bindings: Array<{
       target: string
       state?: string

package/framework/core.mjs

@@ -14,6 +14,7 @@ const listConditionalMarker = Symbol("kudzu.listConditional")
 const refMarker = Symbol("kudzu.ref")
 const contextMarker = Symbol("kudzu.context")
 const contextProviderMarker = Symbol("kudzu.contextProvider")
+const routeScopeMarker = Symbol("kudzu.routeScope")
 const noSelectValue = Symbol("kudzu.no-select-value")
 
 let renderContext
@@ -23,23 +24,24 @@ export function useState(initialValue, name) {
     throw new Error("useState() can only run while rendering a Kudzu component")
   }
 
-  const id = `s${renderContext.nextState++}`
+  const id = nextRenderId("s")
   const signal = createSignal(id, initialValue)
 
   const setter = () => {
     throw new Error("State setters are compiled into ordered browser behaviors")
   }
   Object.defineProperty(setter, setterMarker, { value: id })
-  renderContext.states[id] = { name: name ?? id, initialValue }
+  renderContext.states[id] = { name: name ?? id, initialValue, ...(renderContext.scoped ? { lifetime: renderContext.renderScope } : {}) }
   return [signal, setter]
 }
 
 export function useParams() {
+  if (renderContext?.renderScope === "layout") throw new Error("useParams() is only supported in route scope")
   if (!renderContext?.runtimeParamNames?.length) throw new Error("useParams() requires export const runtimeParams = true on a bracket page")
   if (!renderContext.params) {
     const params = Object.create(null)
-    renderContext.paramEntries = renderContext.runtimeParamNames.map((name, index) => {
-      const id = `p${index}`
+    renderContext.paramEntries = renderContext.runtimeParamNames.map(name => {
+      const id = nextRenderId("p")
       params[name] = createSignal(id, "")
       return { name, id }
     })
@@ -71,7 +73,28 @@ export function useEffect(callback, dependencies, module, handler, states, scope
     if (!dependency?.[signalMarker] || !validEffectDependency(dependency.value)) throw new Error(`${source} useEffect() dependencies must be primitive Kudzu state or runtime parameter identifiers`)
     return dependency.id
   })
-  renderContext.effects.push({ module, handler, states, scope, source, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(cleanup ? { cleanup: true } : {}) })
+  let owner
+  let list = false
+  if (renderContext.listDepth) {
+    const effects = renderContext.listRoot?.effects
+    if (!effects) throw new Error(`${source} useEffect() inside keyed lists must belong to the direct row component`)
+    const index = effects.length
+    if (renderContext.listTemplate) {
+      owner = nextRenderId("e")
+      renderContext.listEffectOwners.push(owner)
+      list = true
+    } else {
+      owner = renderContext.listEffectOwners[index]
+      if (!owner) throw new Error(`${source} Keyed row effects must have the same hook order for every item`)
+    }
+    effects.push(owner)
+  } else if (renderContext.conditionDepth) {
+    const owners = renderContext.effectOwners.at(-1)
+    if (!owners) throw new Error(`${source} useEffect() inside conditional DOM must belong to a rendered function component`)
+    owner = nextRenderId("e")
+    owners.push(owner)
+  }
+  if (!renderContext.listDepth || list) renderContext.effects.push({ module, handler, states, scope, source, renderScope: renderContext.renderScope, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(cleanup ? { cleanup: true } : {}), ...(owner ? { owner } : {}), ...(list ? { list: true } : {}) })
   renderContext.hasBehaviors = true
   renderContext.hasEffects = true
 }
@@ -83,7 +106,7 @@ function validEffectDependency(value) {
 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")
-  return { [refMarker]: true, id: `r${renderContext.nextRef++}`, current: null }
+  return { [refMarker]: true, id: nextRenderId("r"), current: null }
 }
 
 export function createContext(defaultValue) {
@@ -267,19 +290,26 @@ 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: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+export async function renderPage(component, metadata = {}, props = {}, layout) {
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], effectOwners: [], contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
-    const body = await renderNode({ type: component, props })
+    const page = { [routeScopeMarker]: true, component, props }
+    const body = await renderNode(layout ? { type: layout, props: { children: page } } : { type: component, props })
     renderContext.effects = renderContext.effects.map(effect => {
       try {
+        if (metadata.navigationAsset && effect.owner) throw new Error("useEffect() inside conditional or keyed DOM is not supported in a configured navigation group yet; move the effect to the layout or route component body, or remove the route from navigation")
+        const descriptor = nativeDescriptor(effect.states.map(([name, read]) => [name, read()]), effect.scope.map(([name, read]) => [name, typeof read === "function" ? read() : read]))
         return {
           module: effect.module,
           handler: effect.handler,
           ...(effect.dependencies ? { dependencies: effect.dependencies } : {}),
           ...(effect.cleanup ? { cleanup: true } : {}),
-          ...nativeDescriptor(effect.states.map(([name, read]) => [name, read()]), effect.scope.map(([name, read]) => [name, read()]))
+          ...(effect.owner ? { owner: effect.owner } : {}),
+          ...(effect.list ? { list: true } : {}),
+          ...(renderContext.scoped ? { lifetime: effect.renderScope } : {}),
+          states: descriptor.states,
+          scope: descriptor.scope
         }
       } catch (error) {
         throw new Error(`${effect.source} ${error.message}`)
@@ -287,26 +317,30 @@ export async function renderPage(component, metadata = {}, props = {}) {
     })
     const title = escapeHtml(metadata.title ?? "Kudzu")
     const head = renderMetadata(metadata)
+    const capability = metadata.navigationAsset ? " data-k-capability" : ""
     const styles = metadata.styles === false
       ? ""
       : (Array.isArray(metadata.styles) ? metadata.styles : [assetPath(metadata.base, "assets/style.css")]).map(href => `<link rel="stylesheet" href="${escapeAttribute(href)}">`).join("")
     const runtime = renderContext.hasBehaviors
-      ? `<script type="module" src="${escapeAttribute(metadata.runtimeAsset ?? assetPath(metadata.base, "assets/kudzu.js"))}"></script>`
+      ? `<script type="module"${capability} src="${escapeAttribute(metadata.runtimeAsset ?? assetPath(metadata.base, "assets/kudzu.js"))}"></script>`
       : ""
     const nativeRuntime = renderContext.hasNativeBehaviors
-      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-native.js")}"></script>`
+      ? `<script type="module"${capability} src="${assetPath(metadata.base, "assets/kudzu-native.js")}"></script>`
       : ""
     const paramRuntime = renderContext.hasParams
-      ? `<script type="module" src="${escapeAttribute(metadata.paramAsset)}"></script>`
+      ? `<script type="module"${capability} src="${escapeAttribute(metadata.paramAsset)}"></script>`
       : ""
     const bindingRuntime = renderContext.hasBindings
-      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-binding.js")}"></script>`
+      ? `<script type="module"${capability} src="${assetPath(metadata.base, "assets/kudzu-binding.js")}"></script>`
       : ""
     const listRuntime = renderContext.hasLists
-      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-list.js")}"></script>`
+      ? `<script type="module"${capability} src="${assetPath(metadata.base, "assets/kudzu-list.js")}"></script>`
       : ""
     const effectRuntime = renderContext.hasEffects
-      ? `<script type="module" src="${escapeAttribute(metadata.effectAsset)}"></script>`
+      ? `<script type="module"${capability} src="${escapeAttribute(metadata.effectAsset)}"></script>`
+      : ""
+    const navigationRuntime = metadata.navigationAsset
+      ? `<script type="module" data-k-capability src="${escapeAttribute(metadata.navigationAsset)}"></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))
@@ -324,7 +358,7 @@ 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}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}</head><body${state}${textBindings}>${body}</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}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}${navigationRuntime}</head><body${state}${textBindings}${metadata.applicationId ? ` data-k-application="${escapeAttribute(metadata.applicationId)}" data-k-layout="${escapeAttribute(metadata.layoutId)}"` : ""}>${body}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasEffects: renderContext.hasEffects,
       hasParams: renderContext.hasParams,
@@ -349,16 +383,17 @@ export async function renderPage(component, metadata = {}, props = {}) {
 
 function renderMetadata(metadata) {
   const tags = []
+  const owned = metadata.navigationAsset ? " data-k-head" : ""
   const meta = (name, content, property = false) => {
-    if (content) tags.push(`<meta ${property ? "property" : "name"}="${escapeAttribute(name)}" content="${escapeAttribute(content)}">`)
+    if (content) tags.push(`<meta${owned} ${property ? "property" : "name"}="${escapeAttribute(name)}" content="${escapeAttribute(content)}">`)
   }
 
   if (metadata.description) meta("description", metadata.description)
   if (metadata.themeColor) meta("theme-color", metadata.themeColor)
-  if (metadata.url) tags.push(`<link rel="canonical" href="${escapeAttribute(metadata.url)}">`)
-  if (metadata.icon) tags.push(`<link rel="icon" href="${escapeAttribute(baseUrl(metadata.base, metadata.icon))}">`)
-  if (metadata.appleTouchIcon) tags.push(`<link rel="apple-touch-icon" href="${escapeAttribute(baseUrl(metadata.base, metadata.appleTouchIcon))}">`)
-  if (metadata.manifest) tags.push(`<link rel="manifest" href="${escapeAttribute(baseUrl(metadata.base, metadata.manifest))}">`)
+  if (metadata.url) tags.push(`<link${owned} rel="canonical" href="${escapeAttribute(metadata.url)}">`)
+  if (metadata.icon) tags.push(`<link${owned} rel="icon" href="${escapeAttribute(baseUrl(metadata.base, metadata.icon))}">`)
+  if (metadata.appleTouchIcon) tags.push(`<link${owned} rel="apple-touch-icon" href="${escapeAttribute(baseUrl(metadata.base, metadata.appleTouchIcon))}">`)
+  if (metadata.manifest) tags.push(`<link${owned} rel="manifest" href="${escapeAttribute(baseUrl(metadata.base, metadata.manifest))}">`)
 
   meta("og:title", metadata.title, true)
   meta("og:description", metadata.description, true)
@@ -404,6 +439,16 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     return escapeHtml(node)
   }
   if (node instanceof Promise) return renderNode(await node, namespace, selectValue)
+  if (node?.[routeScopeMarker]) {
+    const previousScope = renderContext.renderScope
+    renderContext.renderScope = "route"
+    try {
+      const html = await renderNode({ type: node.component, props: node.props }, namespace, selectValue)
+      return `<template data-k-route-start></template>${html}<template data-k-route-end></template>`
+    } finally {
+      renderContext.renderScope = previousScope
+    }
+  }
   if (node?.[contextProviderMarker]) {
     renderContext.contexts.push([node.context, node.value])
     try {
@@ -418,7 +463,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     if (!stateIds.size) return renderNode(node.value ? node.truthy() : node.falsy(), namespace, selectValue)
     if (namespace) throw new Error(`Reactive conditional DOM is not supported inside ${namespace}`)
 
-    const id = `c${renderContext.nextCondition++}`
+    const id = nextRenderId("c")
     renderContext.conditionDepth++
     const truthy = await renderNode(node.truthy(), namespace, selectValue)
     const falsy = await renderNode(node.falsy(), namespace, selectValue)
@@ -479,7 +524,19 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
 
   if (node.type === Symbol.for("kudzu.fragment")) return renderNode(node.props.children, namespace, selectValue)
-  if (typeof node.type === "function") return renderNode(await node.type(node.props), namespace, selectValue)
+  if (typeof node.type === "function") {
+    if (!renderContext.conditionDepth) return renderNode(await node.type(node.props), namespace, selectValue)
+    const owners = []
+    renderContext.effectOwners.push(owners)
+    let result
+    try {
+      result = await node.type(node.props)
+    } finally {
+      renderContext.effectOwners.pop()
+    }
+    const html = await renderNode(result, namespace, selectValue)
+    return owners.map(owner => `<template data-k-effect="${owner}"></template>`).join("") + html
+  }
 
   const tag = node.type
   const props = node.props ?? {}
@@ -508,6 +565,10 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     const root = renderContext.listRoot
     renderContext.listRoot = undefined
     if (root.template) attributes += ` data-k-list-root="${root.id}"`
+    if (root.effects.length) {
+      attributes += ` data-k-effects='${escapeJsonAttribute(root.effects)}'`
+      if (!root.template) attributes += ` data-k-effect-item='${escapeJsonAttribute(root.item)}'`
+    }
   }
 
   for (const [rawName, value] of Object.entries(props)) {
@@ -520,7 +581,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     }
     if (rawName === "selected" && selectValue !== noSelectValue) continue
     if (/^on/i.test(rawName) && !/^on[A-Z]/.test(rawName)) throw new Error(`${rawName} must use a camelCase event handler`)
-    if (rawName.toLowerCase().startsWith("data-k-")) throw new Error(`${rawName} uses Kudzu's reserved data-k-* prefix`)
+    if (rawName.toLowerCase().startsWith("data-k-") && rawName.toLowerCase() !== "data-k-native") throw new Error(`${rawName} uses Kudzu's reserved data-k-* prefix`)
     if (["ref", "dangerouslysetinnerhtml"].includes(rawName.toLowerCase()) && (value?.[signalMarker] || value?.[bindingMarker])) {
       throw new Error(`Reactive ${rawName} is not supported`)
     }
@@ -613,16 +674,19 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
 
 async function renderList(node, namespace, selectValue) {
   if (namespace) throw new Error(`Reactive keyed lists are not supported inside ${namespace}`)
-  const id = `l${renderContext.nextList++}`
+  const id = nextRenderId("l")
   const descriptor = { id, state: node.items.id, key: node.keyField, keys: node.items.value.map(item => item[node.keyField]) }
   renderContext.listDepth++
   const previousListFields = renderContext.listFields
+  const previousListEffectOwners = renderContext.listEffectOwners
   try {
     renderContext.listTemplate = true
+    renderContext.listEffectOwners = []
     renderContext.listFields = new Set([node.keyField])
-    renderContext.listRoot = { id, template: true }
+    renderContext.listRoot = { id, template: true, effects: [], item: {} }
     const template = await renderNode(node.render({}), namespace, selectValue)
-    if (template.includes("data-k-native-")) descriptor.mount = true
+    if (template.includes("data-k-native-") || template.includes("data-k-effects=")) descriptor.mount = true
+    if (template.includes("data-k-effects=")) descriptor.effects = 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
@@ -635,7 +699,7 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listTemplate = false
     renderContext.listInitialMarkers = Boolean(descriptor.conditions)
     for (const item of node.items.value) {
-      renderContext.listRoot = { id, key: item[node.keyField], template: false }
+      renderContext.listRoot = { id, key: item[node.keyField], template: false, effects: [], item }
       current += await renderNode(node.render(item), namespace, selectValue)
     }
     renderContext.lists.push(descriptor)
@@ -647,10 +711,17 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listTemplate = false
     renderContext.listInitialMarkers = false
     renderContext.listFields = previousListFields
+    renderContext.listEffectOwners = previousListEffectOwners
     renderContext.listDepth--
   }
 }
 
+function nextRenderId(kind) {
+  if (renderContext.scoped) return `${renderContext.renderScope === "layout" ? "l" : "r"}${kind}${renderContext.counters[renderContext.renderScope][kind]++}`
+  const counters = { s: "nextState", r: "nextRef", c: "nextCondition", l: "nextList", e: "nextEffect", p: "nextParam" }
+  return `${kind}${renderContext[counters[kind]]++}`
+}
+
 function optionValue(props) {
   if (props.value != null) return bindingValue(props.value)
   return Array.isArray(props.children) ? props.children.join("") : props.children ?? ""

package/framework/effect-runtime.js

@@ -1,17 +1,19 @@
 import { deserialize } from "./serialization.js"
 
-export function createEffectContext(state, stateIds, commit, serializedScope = {}) {
+export function createEffectContext(state, stateIds, commit, serializedScope = {}, active = () => true) {
   const changed = new Set()
   let scheduled = false
 
   const flush = () => {
     scheduled = false
+    if (!active()) return changed.clear()
     const ids = [...changed]
     changed.clear()
     for (const id of ids) commit(id, state.get(id))
   }
 
   const setId = (id, value) => {
+    if (!active()) return
     const current = state.get(id)
     state.set(id, typeof value === "function" ? value(current) : value)
     changed.add(id)

package/framework/list-runtime.js

@@ -7,7 +7,7 @@ const imports = __KUDZU_LIST_ASYNC_PARTS__ ? new Map() : undefined
 const revisions = __KUDZU_LIST_ASYNC_PARTS__ ? new WeakMap() : undefined
 const itemParts = new WeakMap()
 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]" : ""}`
+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]" : ""}${__KUDZU_LIST_EFFECTS__ ? ",[data-k-effects]" : ""}`
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -114,8 +114,11 @@ function updateList(list) {
     } else node.remove()
   }
   if (added) {
-    if (__KUDZU_LIST_MOUNTS__ && list.descriptor.mount) mountDom(additions)
-    parent.insertBefore(additions, list.boundary)
+    if (__KUDZU_LIST_MOUNTS__ && list.descriptor.mount) {
+      const addedNodes = [...additions.childNodes]
+      parent.insertBefore(additions, list.boundary)
+      for (const node of addedNodes) mountDom(node)
+    } else parent.insertBefore(additions, list.boundary)
     list.container ??= parent
   }
   let anchor = list.boundary
@@ -149,6 +152,7 @@ function fillListItem(root, item) {
 }
 
 function fillListParts(root, parts, item, revision) {
+  if (__KUDZU_LIST_EFFECTS__) for (const node of parts.effects) node.dataset.kEffectItem = JSON.stringify(item)
   for (const [node, field] of parts.directTexts) {
     const text = item?.[field]
     const value = text == null ? "" : String(text)
@@ -203,7 +207,7 @@ function fillListParts(root, parts, item, revision) {
 function listItemParts(root) {
   let parts = itemParts.get(root)
   if (parts) return parts
-  parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [], conditions: [] }
+  parts = { directTexts: [], texts: [], attributes: [], events: [], expressions: [], expressionAttributes: [], conditions: [], effects: [] }
   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 (__KUDZU_LIST_ATTRIBUTES__ && node.hasAttribute("data-k-list-attrs")) parts.attributes.push([node, JSON.parse(node.dataset.kListAttrs)])
@@ -214,6 +218,7 @@ function listItemParts(root) {
       parts.conditions.push([node, JSON.parse(node.dataset.kListCondition)])
       conditionOwners.set(node, root)
     }
+    if (__KUDZU_LIST_EFFECTS__ && node.hasAttribute("data-k-effects")) parts.effects.push(node)
   }
   itemParts.set(root, parts)
   return parts
@@ -230,7 +235,8 @@ function listItemPartPlan(template) {
     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]) : []
+    conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([node, descriptor]) => [indexes.get(node), descriptor]) : [],
+    effects: __KUDZU_LIST_EFFECTS__ ? parts.effects.map(node => indexes.get(node)) : []
   }
 }
 
@@ -246,7 +252,8 @@ function mapListItemParts(parts, root) {
     conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([index, descriptor]) => {
       conditionOwners.set(target[index], root)
       return [target[index], descriptor]
-    }) : []
+    }) : [],
+    effects: __KUDZU_LIST_EFFECTS__ ? parts.effects.map(index => target[index]) : []
   })
 }
 

package/framework/navigation-runtime.js

@@ -0,0 +1,220 @@
+import { browserState, mountDom, unmountDom } from "./shared-runtime.js"
+
+const routes = new Set(__KUDZU_NAVIGATION_ROUTES__)
+const applicationId = __KUDZU_APPLICATION_ID__
+const layoutId = __KUDZU_LAYOUT_ID__
+const navigationAsset = new URL(import.meta.url).pathname
+const status = document.createElement("div")
+status.dataset.kNavigationStatus = ""
+status.setAttribute("role", "status")
+status.setAttribute("aria-live", "polite")
+status.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;padding:0;margin:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0"
+document.body.append(status)
+
+let request
+let revision = 0
+const documents = new Map()
+let observer
+let idle
+let idleAnchors
+const noDispose = async () => {}
+let routeDispose = noDispose
+let layoutDispose = noDispose
+const ready = mountInitial()
+
+document.addEventListener("click", event => {
+  const anchor = event.target.closest?.("a[href]")
+  if (!eligibleClick(event, anchor)) return
+  const url = new URL(anchor.href)
+  event.preventDefault()
+  navigate(url, true)
+})
+document.addEventListener("pointerover", event => prefetchAnchor(event.target.closest?.("a[href]")))
+document.addEventListener("focusin", event => prefetchAnchor(event.target.closest?.("a[href]")))
+
+addEventListener("popstate", () => navigate(new URL(location.href), false))
+addEventListener("pagehide", event => {
+  if (event.persisted) return
+  ++revision
+  request?.abort()
+  void (async () => {
+    await routeDispose()
+    await layoutDispose()
+  })()
+})
+discover()
+
+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)
+  }
+}
+
+function eligibleClick(event, anchor) {
+  if (!anchor || event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false
+  return eligibleAnchor(anchor)
+}
+
+function eligibleAnchor(anchor) {
+  if (anchor.hasAttribute("download") || anchor.hasAttribute("data-k-native") || !["", "_self"].includes(anchor.target)) return false
+  if (anchor.relList?.contains("external")) return false
+  const url = new URL(anchor.href)
+  if (url.hash && url.pathname === location.pathname && url.search === location.search) return false
+  return url.origin === location.origin && routes.has(url.pathname)
+}
+
+function discover() {
+  const anchors = [...document.querySelectorAll("a[href]")].filter(eligibleAnchor)
+  idleAnchors = anchors
+  prune(anchors)
+  observer?.disconnect()
+  if ("IntersectionObserver" in globalThis) {
+    observer ??= new IntersectionObserver(entries => {
+      for (const entry of entries) if (entry.isIntersecting) {
+        observer.unobserve(entry.target)
+        prefetchAnchor(entry.target)
+      }
+    }, { rootMargin: "200px" })
+    for (const anchor of anchors) observer.observe(anchor)
+  } else if (idle === undefined) {
+    const schedule = globalThis.requestIdleCallback ?? (callback => setTimeout(callback, 0))
+    idle = schedule(() => {
+      idle = undefined
+      for (const anchor of idleAnchors) prefetchAnchor(anchor)
+    })
+  }
+}
+
+function prefetchAnchor(anchor) {
+  if (!eligibleAnchor(anchor)) return
+  const url = new URL(anchor.href)
+  prune([...document.querySelectorAll("a[href]")].filter(eligibleAnchor))
+  if (documents.has(url.href)) return
+  const pending = fetchDocument(url)
+  documents.set(url.href, pending)
+  pending.catch(() => {
+    if (documents.get(url.href) === pending) documents.delete(url.href)
+  })
+}
+
+function prune(anchors) {
+  const retained = new Set([location.href, ...anchors.map(anchor => anchor.href)])
+  for (const key of documents.keys()) if (!retained.has(key)) documents.delete(key)
+}
+
+async function navigate(url, push) {
+  await ready
+  const current = ++revision
+  request?.abort()
+  request = new AbortController()
+  let committed = false
+  try {
+    let documentResult
+    const cached = documents.get(url.href)
+    if (cached) {
+      try { documentResult = await cached }
+      catch { documentResult = await fetchDocument(url, request.signal) }
+    } else documentResult = await fetchDocument(url, request.signal)
+    documents.set(url.href, Promise.resolve(documentResult))
+    const { incoming, parsed } = documentResult
+    const effects = await loadCapabilities(parsed)
+    if (current !== revision) return
+    await routeDispose()
+    if (current !== revision) return
+    commit(incoming, parsed.nodes)
+    routeDispose = await effects?.mountRouteEffects?.() ?? noDispose
+    committed = true
+    if (push) history.pushState(null, "", url)
+    updateHead(incoming)
+    focusAndScroll(url)
+    status.textContent = `Navigated to ${document.title}`
+    discover()
+  } catch (error) {
+    if (current !== revision || error.name === "AbortError") return
+    if (push) location.assign(url.href)
+    else location.reload()
+    if (committed) return
+  }
+}
+
+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")
+}
+
+async function fetchDocument(url, signal) {
+  const response = await fetch(url, { signal, redirect: "manual", headers: { accept: "text/html" } })
+  if (!response.ok || response.redirected || response.type === "opaqueredirect" || !response.headers.get("content-type")?.toLowerCase().includes("text/html")) throw new Error("Navigation response is not successful nonredirected HTML")
+  const incoming = new DOMParser().parseFromString(await response.text(), "text/html")
+  return { incoming, parsed: validate(incoming) }
+}
+
+function validate(incoming) {
+  if (incoming.body.dataset.kApplication !== applicationId || incoming.body.dataset.kLayout !== layoutId) throw new Error("Navigation document identity does not match")
+  const starts = incoming.querySelectorAll("template[data-k-route-start]")
+  const ends = incoming.querySelectorAll("template[data-k-route-end]")
+  if (starts.length !== 1 || ends.length !== 1) throw new Error("Navigation document must contain exactly one route marker pair")
+  const nodes = between(starts[0], ends[0])
+  const assets = [...incoming.querySelectorAll("script[data-k-capability][src]")].map(script => {
+    const url = new URL(script.src)
+    if (url.origin !== location.origin) throw new Error("Navigation capability asset must be same-origin")
+    return url.pathname
+  })
+  if (!assets.includes(navigationAsset)) throw new Error("Navigation capability asset is missing")
+  return { nodes, assets: [...new Set(assets)] }
+}
+
+function commit(incoming, incomingNodes) {
+  const start = document.querySelector("template[data-k-route-start]")
+  const end = document.querySelector("template[data-k-route-end]")
+  if (!start || !end || document.querySelectorAll("template[data-k-route-start],template[data-k-route-end]").length !== 2) throw new Error("Current route markers are invalid")
+  const outgoing = between(start, end)
+  for (const node of outgoing) unmountDom(node)
+  for (const node of outgoing) node.remove()
+  for (const id of [...browserState.keys()]) if (id.startsWith("r")) browserState.delete(id)
+  for (const [id, value, compact] of JSON.parse(incoming.body.dataset.kState ?? "[]")) if (id.startsWith("r")) browserState.set(id, compact ? value[1].map(row => Object.fromEntries(value[0].map((field, index) => [field, row[index]]))) : value)
+  if (incoming.body.dataset.kTextBindings === undefined) delete document.body.dataset.kTextBindings
+  else document.body.dataset.kTextBindings = incoming.body.dataset.kTextBindings
+  const nodes = incomingNodes.map(node => document.importNode(node, true))
+  end.before(...nodes)
+  for (const node of nodes) mountDom(node)
+}
+
+function between(start, end) {
+  if (start.parentNode !== end.parentNode) throw new Error("Route markers must share a parent")
+  const nodes = []
+  for (let node = start.nextSibling; node && node !== end; node = node.nextSibling) nodes.push(node)
+  if (!nodes.length && start.nextSibling !== end) throw new Error("Route marker pair is invalid")
+  return nodes
+}
+
+function updateHead(incoming) {
+  document.title = incoming.title
+  document.head.querySelectorAll("[data-k-head]").forEach(node => node.remove())
+  document.head.append(...[...incoming.head.querySelectorAll("[data-k-head]")].map(node => document.importNode(node, true)))
+}
+
+function focusAndScroll(url) {
+  const hashTarget = url.hash && document.getElementById(decodeURIComponent(url.hash.slice(1)))
+  const target = hashTarget ?? routeElement("h1") ?? routeElement("main")
+  if (target) {
+    if (!target.hasAttribute("tabindex")) target.setAttribute("tabindex", "-1")
+    target.focus({ preventScroll: true })
+  }
+  if (hashTarget) hashTarget.scrollIntoView()
+  else scrollTo(0, 0)
+}
+
+function routeElement(selector) {
+  const start = document.querySelector("template[data-k-route-start]")
+  const end = document.querySelector("template[data-k-route-end]")
+  for (const node of between(start, end)) {
+    if (node.matches?.(selector)) return node
+    const match = node.querySelector?.(selector)
+    if (match) return match
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.5.10",
+  "version": "0.6.0",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
   "files": [
     "bin/",
     "framework/",
+    "GOAL_A.md",
     "README.md",
     "LICENSE"
   ],