@kudzujs/core 0.8.21 → 0.8.23

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

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

package/framework/compiler/param-codegen.mjs

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

package/framework/compiler/path-helpers.mjs

@@ -0,0 +1,18 @@
+import { dirname, relative } from "node:path"
+
+export function relativeModulePath(from, to) {
+  const path = relative(dirname(from), to).replaceAll("\\", "/")
+  return path.startsWith(".") ? path : `./${path}`
+}
+
+export function browserPath(path) {
+  return path ? new URL(path, "http://kudzu.local").pathname : ""
+}
+
+export function assetPath(base, path) {
+  return `${base}/${path}`
+}
+
+export function withBase(base, path) {
+  return base ? `${base}${path}` : path
+}

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

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

package/framework/compiler/runtime-codegen.mjs

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