@kudzujs/core 0.4.14 → 0.5.1

package/README.md

@@ -79,6 +79,43 @@ npm run dev
 
 Pages live in `src/pages`; `index.tsx` maps to `/`. `npm run dev` serves locally on `127.0.0.1`, reloads the browser after successful rebuilds, and shows build failures in an error overlay. Across that full-page reload, compatible Kudzu logical state is briefly preserved by route-unique state variable name for the current pathname, query, and hash, including controlled properties, conditions, and keyed-list arrays. Renamed, removed, and duplicate-named state is skipped. Uncontrolled DOM state, focus, selection, and imperative DOM mutations are not preserved. Set `PORT` to change the default port of `3000`. The development client and state snapshot are dev-only; production output in `dist/` is unaffected.
 
+Dynamic static pages use bracket parameters and `getStaticPaths()`:
+
+```tsx
+// src/pages/posts/[slug].tsx
+export async function getStaticPaths() {
+  return [
+    { params: { slug: "oak" }, props: { title: "Oak" } },
+    { params: { slug: "pine" }, props: { title: "Pine" } }
+  ]
+}
+
+export default function Post({ title }: { title: string }) {
+  return <h1>{title}</h1>
+}
+```
+
+This emits `/posts/oak` and `/posts/pine`. Parameter values must be safe single path segments; missing, unsafe, and duplicate routes fail the build.
+
+Static trusted HTML can be rendered without a transform layer:
+
+```tsx
+<article dangerouslySetInnerHTML={{ __html: renderedNotionHtml }} />
+```
+
+The HTML is intentionally not sanitized. Use only trusted or previously sanitized build-time content. Reactive raw HTML, children on the same element, void elements, and keyed-list raw HTML are rejected.
+
+Every CSS file under `src` is copied to the same relative path under `dist/assets` and linked in deterministic order. Project-page deployments and post-build artifacts use `kudzu.config.mjs`:
+
+```js
+export default {
+  base: "/newsletter",
+  async afterBuild({ outDir, routes, plans, base }) {
+    // Write RSS, sitemap, search indexes, or other static artifacts.
+  }
+}
+```
+
 ## State Semantics
 
 Kudzu intentionally differs from React's state snapshot behavior:
@@ -106,6 +143,8 @@ const [weather, setWeather] = useState({ temperature: 28, label: "Warm" })
 return <p>{weather.temperature}° {weather.label}</p>
 ```
 
+Derived text uses comment-bounded text nodes rather than wrapper elements, so table cells, options, SVG text, layout, and element selectors keep their authored structure.
+
 ## Reactive Attributes
 
 `className`, `disabled`, controlled `value`, and controlled `checked` accept normal state-dependent TSX expressions. The same `value` binding works for inputs and selects:
@@ -225,9 +264,19 @@ const rows = items.map(item =>
 return <ul>{rows}</ul>
 ```
 
+The root may also be a same-file row component that directly returns one intrinsic element and receives the whole item through one prop:
+
+```tsx
+function ItemRow({ item }: { item: Item }) {
+  return <li>{item.name}</li>
+}
+
+const rows = items.map(item => <ItemRow key={item.id} item={item} />)
+```
+
 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, and `key={item.<field>}`. 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, locals, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Nested item conditions or lists, item spreads, 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 same-file row component, and `key={item.<field>}`. A row component must directly destructure the whole item prop, directly return one intrinsic element, and be used only by that list. 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, locals, imported helpers, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Nested item conditions, lists, or component tags, item spreads, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 ## Normal JavaScript
 
@@ -294,6 +343,9 @@ Supported:
 - Function components, props, children, fragments, and TSX
 - File-based static routes
 - Build-time async components
+- Dynamic static routes with build-time props
+- Static trusted `dangerouslySetInnerHTML`
+- Base-path deployments, multiple CSS files, and `afterBuild`
 - Primitive `useState` bindings
 - Synchronous and async event handlers
 - Relative imported helpers in native handlers
@@ -346,6 +398,28 @@ The same native counter calculation was measured inline and through one relative
 
 Bundling removes the helper file boundary, leaving 26 raw bytes and 18 gzip bytes for the function definition and calls. The measured call adds 0.69 µs per state update. The smaller 393 B command-only counter above uses a different optimized runtime path and is not the helper overhead baseline.
 
+#### Wrapper-Free Derived Text
+
+The same object-state counter was built with the v0.4.14 span target and the comment-bounded text range. Browser medians use five 20,000-update batches in each of seven fresh Chrome sessions.
+
+| Text target | Files | JS gzip | Total output | Clean build | Update |
+|---|---:|---:|---:|---:|---:|
+| Span v0.4.14 | 7 | **4,453 B** | **10,065 B** | **404 ms** | **4.83 µs** |
+| Comment range | 7 | 4,763 B | 10,922 B | 426 ms | 5.03 µs |
+
+The range costs 310 B gzip only on pages using derived reactive text. It removes wrapper elements and preserves authored structure across table cells, options, SVG text, selectors, and conditional remounts; ordinary attribute and condition pages tree-shake the range code entirely.
+
+### 123-Page Newsletter Build
+
+The migration fixture emits the same 123 static detail pages, two stylesheets, base-prefixed URLs, and post-build feed with no browser JavaScript. Seven clean builds compare generated page files with one dynamic page module.
+
+| Build model | TSX source files | Pages | JS gzip | Total output | Clean build |
+|---|---:|---:|---:|---:|---:|
+| Generated TSX workaround | 123 | 123 | 0 B | 52.0 KB | 882 ms |
+| `getStaticPaths` | **1** | 123 | 0 B | 52.0 KB | **454 ms** |
+
+`getStaticPaths` removes 122 generated source files and cuts clean build time by 48.5% without changing deploy output or runtime cost.
+
 ### Static Journal Page
 
 Same content and CSS across every fixture:
@@ -374,6 +448,8 @@ The list starts with 1,000 keyed items, then updates every label, reverses the o
 | Svelte CSR | No | 12.9 KB | 33.1 KB | 828 ms | 5.8 ms | 38.9 ms | 4.0 ms | 5.9 ms | 54.6 ms |
 | Qwik CSR | No | 22.2 KB | 64.1 KB | 594 ms | 9.1 ms | 22.2 ms | 30.8 ms | 19.0 ms | 81.1 ms |
 
+An intrinsic-root versus row-component A/B build produced byte-for-byte identical `dist` output: 5,175 B JS gzip and 61,731 B total. Seven interleaved clean builds measured 444 ms and 441 ms. Browser operation medians totaled 23.8 ms and 25.4 ms respectively; because the deployed HTML and JavaScript are identical, that 1.6 ms difference is measurement variance rather than component runtime overhead.
+
 Astro is the hand-authored native DOM baseline in the interactive fixtures. React, Vue, Svelte, and Qwik used client-rendered fixtures, while Kudzu and Astro emitted initial HTML; Qwik therefore did not exercise its SSR resumability advantage. Kudzu's keyed-list operations total 23.2 ms, 10.7 ms behind the hand-authored Astro baseline and 7.1 ms ahead of React across all four operations.
 
 Benchmark snapshot collected on July 22, 2026 with Node 24.14.0 on an Intel i5-9500. These results compare the selected one-page fixtures, not ecosystem maturity, browser interaction speed beyond the listed operations, or each framework's full rendering options. Build times vary with machine load and filesystem cache.

package/framework/README.md

@@ -1,11 +1,11 @@
 # Framework Internals
 
-- `build.mjs`: TSX compilation, file routes, behavior extraction, static HTML output, and the development server.
+- `build.mjs`: TSX compilation, static and `getStaticPaths` routes, base paths, CSS collection, post-build hooks, behavior extraction, static HTML output, and the development server.
 - `core.mjs`: server-side JSX rendering, state slots, context providers, behavior metadata, and serializable capture validation.
 - `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.
 - `runtime.js`: command-only runtime for direct state-to-text patches.
 - `shared-runtime.js`: command runtime with capability commit and DOM lifecycle hooks, emitted only when needed.
-- `binding-runtime.js`: optional generic attributes, form properties, and conditional range patches.
+- `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.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.

package/framework/binding-runtime.js

@@ -9,13 +9,13 @@ const mountedBindings = new WeakSet()
 const mountedConditions = new WeakSet()
 const bindingRegistrations = new WeakMap()
 const conditionRegistrations = new WeakMap()
-const bindingTypes = ["text", "class", "disabled", "value", "checked", "style"]
+const textDescriptors = globalThis.__KUDZU_TEXT_BINDINGS__ && typeof document !== "undefined" ? JSON.parse(document.body.dataset.kTextBindings ?? "[]") : []
+const bindingTypes = ["class", "disabled", "value", "checked", "style"]
 const bindingSelector = [...bindingTypes.map(target => `[data-k-bind-${target}]`), "[data-k-bind-attrs]"].join(",")
 
 export function patchBinding(node, target, value) {
-  if (target === "text") {
-    const next = value == null ? "" : String(value)
-    if (node.textContent !== next) node.textContent = next
+  if (globalThis.__KUDZU_TEXT_BINDINGS__ && target === "text") {
+    patchText(node, value)
   } else if (target === "disabled") {
     node.toggleAttribute("disabled", Boolean(value))
   } else if (target === "checked") {
@@ -94,6 +94,25 @@ function mountBindings(root) {
       }).catch(error => console.error(error))
     }
   }
+  if (globalThis.__KUDZU_TEXT_BINDINGS__) {
+    for (const node of textBindingStarts(root)) {
+      if (mountedBindings.has(node)) continue
+      const descriptor = textDescriptors[Number(node.data.slice("k-text:".length))]
+      if (!descriptor) continue
+      mountedBindings.add(node)
+      const registrations = []
+      bindingRegistrations.set(node, registrations)
+      loadEvaluator(descriptor).then(evaluator => {
+        if (!node.isConnected) return
+        const binding = { node, target: "text", read: evaluator.read }
+        for (const id of evaluator.stateIds) {
+          register(bindingTargets, id, binding)
+          registrations.push([id, binding])
+        }
+        patchBinding(node, "text", binding.read())
+      }).catch(error => console.error(error))
+    }
+  }
 }
 
 function mountConditions(root) {
@@ -146,6 +165,13 @@ function unmountBindings(root) {
     bindingRegistrations.delete(node)
     mountedBindings.delete(node)
   }
+  if (globalThis.__KUDZU_TEXT_BINDINGS__) {
+    for (const node of textBindingStarts(root)) {
+      for (const [id, binding] of bindingRegistrations.get(node) ?? []) bindingTargets.get(id)?.delete(binding)
+      bindingRegistrations.delete(node)
+      mountedBindings.delete(node)
+    }
+  }
 }
 
 function unmountConditions(root) {
@@ -227,6 +253,28 @@ function matching(root, selector) {
   return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
 }
 
+function textBindingStarts(root) {
+  const nodes = root.nodeType === 8 && root.data.startsWith("k-text:") ? [root] : []
+  const walker = (root.ownerDocument ?? root).createTreeWalker?.(root, 128)
+  while (walker?.nextNode()) if (walker.currentNode.data.startsWith("k-text:")) nodes.push(walker.currentNode)
+  return nodes
+}
+
+function patchText(start, value) {
+  const next = value == null ? "" : String(value)
+  const current = start.nextSibling
+  const text = current?.nodeType === 3 ? current : undefined
+  const end = text ? text.nextSibling : current
+  if (end?.nodeType !== 8 || end.data !== "k-text-end") throw new Error("Reactive text marker has no end")
+  if (text) {
+    if (next) {
+      if (text.data !== next) text.data = next
+    } else text.remove()
+    return
+  }
+  if (next) end.before(start.ownerDocument.createTextNode(next))
+}
+
 function capitalize(value) {
   return value[0].toUpperCase() + value.slice(1)
 }

package/framework/build.mjs

@@ -17,18 +17,22 @@ const outputDirectory = join(root, "dist")
 const devClient = (session, revision, schema) => `<script>(()=>{const show=event=>{let box=document.getElementById("__kudzu_error");if(!box){box=document.createElement("div");box.id="__kudzu_error";box.setAttribute("role","alert");box.setAttribute("aria-live","assertive");box.style.cssText="position:fixed;inset:0;z-index:2147483647;overflow:auto;padding:2rem;background:#200;color:#fff;font:16px/1.5 ui-monospace,monospace";const title=document.createElement("strong"),text=document.createElement("pre");title.textContent="Kudzu build error";text.style.whiteSpace="pre-wrap";box.append(title,text);document.body.append(box)}box.querySelector("pre").textContent=event.data};const schema=${inlineJson(schema)},route=location.pathname+location.search+location.hash,urls=[...document.querySelectorAll('script[type="module"][src]')].map(node=>node.src).filter(url=>/\\/assets\\/kudzu(?:-(?:binding|list|native))?\\.js$/.test(new URL(url).pathname));const devImport=import("/__kudzu_dev.js"),runtimeImports=Promise.allSettled(urls.map(url=>import(url)));const ready=(async()=>{const dev=await devImport,modules=await runtimeImports,runtime=modules.find(result=>result.status==="fulfilled"&&result.value.browserState instanceof Map&&typeof result.value.commitDom==="function")?.value;try{dev.restoreState(sessionStorage,route,runtime?.browserState,schema,runtime?.commitDom)}catch{}return{dev,runtime}})().catch(()=>({}));const events=new EventSource("/__kudzu_reload?session=${session}&revision=${revision}");let reloading=false;events.addEventListener("reload",async()=>{if(reloading)return;reloading=true;try{const{dev,runtime}=await ready;dev?.snapshotState(sessionStorage,route,runtime?.browserState,schema)}catch{}location.reload()});events.addEventListener("build-error",show)})()</script>`
 
 export async function build({ quiet = false, minify = true } = {}) {
+  const config = await loadConfig()
+  const base = normalizeBase(config.base)
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
   await mkdir(workDirectory, { recursive: true })
   await mkdir(outputDirectory, { recursive: true })
 
-  const sourceFiles = (await walk(sourceDirectory)).filter(file => /\.(?:ts|tsx)$/.test(file)).sort()
+  const projectFiles = await walk(sourceDirectory)
+  const sourceFiles = projectFiles.filter(file => /\.(?:ts|tsx)$/.test(file)).sort()
+  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 handlerModules = []
   for (const file of sourceFiles) {
-    const handlerModule = await compile(file, sourceFileSet)
+    const handlerModule = await compile(file, sourceFileSet, base)
     if (handlerModule) handlerModules.push(handlerModule)
   }
 
@@ -41,35 +45,44 @@ export async function build({ quiet = false, minify = true } = {}) {
   let listStyleCount = 0
   let stateSeedCount = 0
   const plans = []
-  const hasStyles = await exists(join(sourceDirectory, "style.css"))
+  const emittedRoutes = new Set()
+  const styleUrls = cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`))
 
   for (const pageFile of pageFiles) {
     const compiledFile = compiledPath(pageFile)
     const module = await import(`${pathToFileURL(compiledFile).href}?v=${Date.now()}`)
     if (typeof module.default !== "function") throw new Error(`${relative(root, pageFile)} must export a default component`)
 
-    const result = await renderPage(module.default, {
-      ...(module.metadata ?? {}),
-      styles: hasStyles
-    })
-    const route = routeFromPage(pageFile)
-    const routeDirectory = join(outputDirectory, route)
-    await mkdir(routeDirectory, { recursive: true })
-    await writeFile(join(routeDirectory, "index.html"), result.html)
-    plans.push({ route: `/${route}`, ...result.plan })
-    if (result.hasBehaviors) behaviorCount++
-    if (result.hasBindings) bindingCount++
-    if (result.hasLists) listCount++
-    if (result.hasListStyles) listStyleCount++
-    if (result.hasStateSeed) stateSeedCount++
+    const entries = await staticPathEntries(module, pageFile)
+    for (const { params, props } of entries) {
+      const route = routeFromPage(pageFile, params)
+      const routePath = withBase(base, `/${route}`)
+      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
+      }, 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.hasBehaviors) behaviorCount++
+      if (result.hasBindings) bindingCount++
+      if (result.hasLists) listCount++
+      if (result.hasListStyles) listStyleCount++
+      if (result.hasStateSeed) stateSeedCount++
+    }
   }
 
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
   const commandEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.commands).map(event => event.event)))].sort()
   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 nativeModules = handlerModules.filter(module => module.hasNativeHandlers).map(module => `/assets/${module.path}`)
+  const nativeModules = handlerModules.filter(module => module.hasNativeHandlers).map(module => assetPath(base, `assets/${module.path}`))
   const hasNativeHandlers = nativeModules.length > 0
   if (behaviorCount) {
     const runtimeFile = bindingCount || listCount || hasNativeHandlers ? "./shared-runtime.js" : "./runtime.js"
@@ -83,7 +96,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       .replace('"./shared-runtime.js"', '"./kudzu.js"')
       .replace('"./serialization.js"', '"./kudzu-serialization.js"')
       .replace('"./style.js"', '"./kudzu-style.js"')
-    await writeJavaScript(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime, minify)
+    await writeBundledJavaScript(join(assetsDirectory, "kudzu-binding.js"), bindingRuntime, minify, { "globalThis.__KUDZU_TEXT_BINDINGS__": String(hasTextBindings) })
   }
   if (listCount) {
     let listRuntime = (await readFile(new URL("./list-runtime.js", import.meta.url), "utf8"))
@@ -134,10 +147,18 @@ export async function build({ quiet = false, minify = true } = {}) {
     await rm(join(assetsDirectory, "modules"), { recursive: true, force: true })
   }
   await writeFile(join(workDirectory, "kudzu-plan.json"), JSON.stringify({ routes: plans }, null, 2))
-  if (hasStyles) await cp(join(sourceDirectory, "style.css"), join(assetsDirectory, "style.css"))
+  for (const file of cssFiles) {
+    const output = join(assetsDirectory, relative(sourceDirectory, file))
+    await mkdir(dirname(output), { recursive: true })
+    await cp(file, output)
+  }
   if (await exists(join(root, "public"))) await cp(join(root, "public"), outputDirectory, { recursive: true })
+  if (config.afterBuild !== undefined) {
+    if (typeof config.afterBuild !== "function") throw new Error("kudzu.config afterBuild must be a function")
+    await config.afterBuild({ root, outDir: outputDirectory, sourceDir: sourceDirectory, base, routes: plans.map(plan => plan.route), plans })
+  }
 
-  if (!quiet) console.log(`Built ${pageFiles.length} page(s), ${behaviorCount} interactive page(s) into dist/`)
+  if (!quiet) console.log(`Built ${plans.length} page(s), ${behaviorCount} interactive page(s) into dist/`)
 }
 
 function specializeEvents(source, events) {
@@ -168,7 +189,7 @@ async function writeBundledJavaScript(file, source, minify, define) {
     stdin: { contents: source, resolveDir: dirname(file), sourcefile: file },
     bundle: true,
     write: false,
-    external: ["./kudzu.js", "./kudzu-style.js"],
+    external: ["./kudzu.js", "./kudzu-serialization.js", "./kudzu-style.js"],
     define,
     format: "esm",
     target: "es2022",
@@ -189,6 +210,7 @@ export function parseDevPort(value) {
 
 export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
   if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid dev server port: ${port}`)
+  const base = normalizeBase((await loadConfig()).base)
 
   let buildError
   let revision = 0
@@ -226,7 +248,7 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
         return
       }
 
-      const relativePath = pathname.replace(/^\/+/, "")
+      const relativePath = stripBase(pathname, base).replace(/^\/+/, "")
       let file = resolve(outputDirectory, relativePath)
       if (!file.startsWith(`${outputDirectory}${sep}`) && file !== outputDirectory) throw new Error("Invalid path")
 
@@ -287,6 +309,12 @@ function injectDevClient(html, session, revision, schema) {
   return `${html}${devClient(session, revision, schema)}`
 }
 
+function stripBase(path, base) {
+  if (!base) return path
+  if (path === base) return "/"
+  return path.startsWith(`${base}/`) ? path.slice(base.length) : path
+}
+
 async function devSchema(pathname) {
   try {
     const plan = JSON.parse(await readFile(join(workDirectory, "kudzu-plan.json"), "utf8"))
@@ -317,7 +345,7 @@ function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
 }
 
-async function compile(file, sourceFiles) {
+async function compile(file, sourceFiles, base) {
   const source = await readFile(file, "utf8")
   const nativeHandlers = []
   const reactiveBindings = []
@@ -332,7 +360,7 @@ async function compile(file, sourceFiles) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, `/assets/${handlerPath}`, file, sourceFiles, clientImports)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, clientImports)] },
     reportDiagnostics: true
   })
 
@@ -438,6 +466,19 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
         if (uses.length) listLocalUses.set(uses[0], parts)
       }
     }
+    const renderedLists = new WeakMap()
+    const collectRenderedLists = node => {
+      if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
+        const parts = listLocalUses.get(node) ?? keyedListParts(node.expression, settersForNode(node, settersByFunction))
+        if (parts) {
+          if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
+          validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, functions)
+          renderedLists.set(node, parts)
+        }
+      }
+      ts.forEachChild(node, collectRenderedLists)
+    }
+    collectRenderedLists(sourceFile)
 
     const visitor = node => {
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
@@ -495,10 +536,8 @@ function createKudzuTransformer(nativeHandlers, reactiveBindings, listExpression
       }
 
       if (ts.isJsxExpression(node) && node.initializer === undefined && node.expression && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
-        const listParts = listLocalUses.get(node) ?? keyedListParts(node.expression, settersForNode(node, settersByFunction))
+        const listParts = renderedLists.get(node)
         if (listParts) {
-          if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
-          validateKeyedList(listParts, sourceFile, settersForNode(node, settersByFunction), listValues, listEventItems, listConditions)
           usesBehavior = true
           usesList = true
           return factory.updateJsxExpression(node, factory.createCallExpression(factory.createIdentifier("__kList"), undefined, [
@@ -600,11 +639,35 @@ function keyedListParts(expression, setters) {
   return { state, callback, root, item: callback.parameters[0].name.text, keyField: field }
 }
 
-function validateKeyedList(parts, sourceFile, setters, listValues, listEventItems, listConditions) {
+function validateKeyedList(parts, sourceFile, listValues, listEventItems, listConditions, functions) {
   const fail = (node, message) => {
     const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     throw new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
   }
+  let root = parts.root
+  let item = parts.item
+  const rootTag = ts.isJsxElement(root) ? root.openingElement.tagName : root.tagName
+  if (ts.isIdentifier(rootTag) && rootTag.text[0] === rootTag.text[0].toUpperCase()) {
+    const component = functions.get(rootTag.text)
+    if (!component) fail(root, `Keyed list component ${rootTag.text} must be declared in the same file`)
+    const uses = jsxTagUses(sourceFile, rootTag.text)
+    if (uses.length !== 1 || uses[0] !== root) fail(root, `Keyed list component ${rootTag.text} may only be used as this list root`)
+    const attributes = ts.isJsxElement(root) ? root.openingElement.attributes : root.attributes
+    let itemProp
+    for (const attribute of attributes.properties) {
+      if (ts.isJsxSpreadAttribute(attribute)) {
+        if (referencesIdentifier(attribute.expression, item)) fail(attribute, "Keyed list item spreads are not supported")
+        continue
+      }
+      if (attribute.name.getText() === "key" || !attribute.initializer || !ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression || !referencesIdentifier(attribute.initializer.expression, item)) continue
+      if (!ts.isIdentifier(attribute.initializer.expression) || attribute.initializer.expression.text !== item || itemProp) fail(attribute, `Keyed list component ${rootTag.text} must receive the whole item through one direct prop`)
+      itemProp = attribute.name.getText()
+    }
+    if (ts.isJsxElement(root) && root.children.some(child => referencesIdentifier(child, item))) fail(root, `Keyed list component ${rootTag.text} must receive the whole item through one direct prop`)
+    if (!itemProp) fail(root, `Keyed list component ${rootTag.text} must receive the whole item through one direct prop`)
+    item = componentItemParameter(component, itemProp, node => fail(node, `Keyed list component ${rootTag.text} must destructure its item prop`))
+    root = componentJsxRoot(component, node => fail(node, `Keyed list component ${rootTag.text} must return one JSX element`))
+  }
   const validateElement = node => {
     const tag = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName
     if (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(node, "Keyed list items must use intrinsic JSX elements")
@@ -613,10 +676,10 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
   const visit = node => {
     if (ts.isJsxFragment(node)) fail(node, "Fragments are not supported in keyed lists")
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) validateElement(node)
-    if (node !== parts.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, parts.item)) fail(node, "Keyed list item spreads are not supported")
+    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())) {
-      listEventItems.set(node, parts.item)
+      listEventItems.set(node, item)
       return
     }
     if (ts.isJsxExpression(node) && node.expression) {
@@ -624,16 +687,16 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
       const condition = conditionalParts(expression)
       if (condition && containsJsx(expression)) {
         if (conditionDepth) fail(node, "Nested item conditions are not supported in keyed lists")
-        if (!referencesIdentifier(condition.condition, parts.item)) fail(node, "Keyed list item conditions must read the item")
-        validateListExpression(condition.condition, parts.item, node, fail)
-        listConditions.set(node.expression, { ...condition, item: parts.item })
+        if (!referencesIdentifier(condition.condition, item)) fail(node, "Keyed list item conditions must read the item")
+        validateListExpression(condition.condition, item, node, fail)
+        listConditions.set(node.expression, { ...condition, item })
         conditionDepth++
         visit(condition.truthy)
         visit(condition.falsy)
         conditionDepth--
         return
       }
-      const field = directProperty(expression, parts.item)
+      const field = directProperty(expression, item)
       const isRootKey = ts.isJsxAttribute(node.parent) && node.parent.name.getText() === "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`)
@@ -642,16 +705,47 @@ function validateKeyedList(parts, sourceFile, setters, listValues, listEventItem
         listValues.set(node.expression, { field })
         return
       }
-      if (referencesIdentifier(expression, parts.item)) {
-        validateListExpression(expression, parts.item, node, fail)
+      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`)
-        listValues.set(node.expression, { item: parts.item })
+        listValues.set(node.expression, { item })
         return
       }
     }
     ts.forEachChild(node, visit)
   }
-  visit(parts.root)
+  visit(root)
+}
+
+function componentItemParameter(component, prop, fail) {
+  if (component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name)) fail(component)
+  const element = component.parameters[0].name.elements.find(entry => !entry.dotDotDotToken && !entry.initializer && (entry.propertyName ?? entry.name).getText() === prop)
+  if (!element || !ts.isIdentifier(element.name)) fail(component.parameters[0])
+  return element.name.text
+}
+
+function componentJsxRoot(component, fail) {
+  if (!ts.isBlock(component.body)) {
+    const root = unwrapExpression(component.body)
+    if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) fail(component.body)
+    return root
+  }
+  if (component.body.statements.length !== 1 || !ts.isReturnStatement(component.body.statements[0]) || !component.body.statements[0].expression) fail(component.body)
+  const statement = component.body.statements[0]
+  const root = unwrapExpression(statement.expression)
+  if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) fail(statement)
+  return root
+}
+
+function jsxTagUses(root, name) {
+  const uses = []
+  const visit = node => {
+    const tag = ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : undefined
+    if (tag && ts.isIdentifier(tag) && tag.text === name) uses.push(node)
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return uses
 }
 
 const pureListMethods = new Set(["at", "charAt", "charCodeAt", "concat", "endsWith", "includes", "indexOf", "join", "lastIndexOf", "padEnd", "padStart", "repeat", "replace", "replaceAll", "slice", "startsWith", "substring", "toLowerCase", "toUpperCase", "trim", "trimEnd", "trimStart"])
@@ -1289,9 +1383,59 @@ function compiledPath(file) {
   return join(workDirectory, relative(sourceDirectory, file)).replace(/\.(?:ts|tsx)$/, ".mjs")
 }
 
-function routeFromPage(file) {
+async function loadConfig() {
+  for (const name of ["kudzu.config.mjs", "kudzu.config.js"]) {
+    const file = join(root, name)
+    if (!(await exists(file))) continue
+    const config = (await import(`${pathToFileURL(file).href}?v=${Date.now()}-${randomUUID()}`)).default ?? {}
+    if (!isPlainRecord(config)) throw new Error(`${name} must export a default object`)
+    return config
+  }
+  return {}
+}
+
+function normalizeBase(value) {
+  if (value == null || value === "" || value === "/") return ""
+  if (typeof value !== "string" || !value.startsWith("/") || /[?#\0]/.test(value) || value.split("/").includes("..")) throw new Error("kudzu.config base must be a root-relative path")
+  return value.replace(/\/+$/, "")
+}
+
+function assetPath(base, path) {
+  return `${base}/${path}`
+}
+
+function withBase(base, path) {
+  return base ? `${base}${path}` : path
+}
+
+async function staticPathEntries(module, file) {
+  if (typeof module.getStaticPaths !== "function") return [{ params: {}, props: {} }]
+  const entries = await module.getStaticPaths()
+  if (!Array.isArray(entries)) throw new Error(`${relative(root, file)} getStaticPaths() must return an array`)
+  return entries.map((entry, index) => {
+    if (!isPlainRecord(entry)) throw new Error(`${relative(root, file)} getStaticPaths()[${index}] must be an object`)
+    const params = entry.params ?? {}
+    const props = entry.props ?? {}
+    if (!isPlainRecord(params)) throw new Error(`${relative(root, file)} getStaticPaths()[${index}].params must be an object`)
+    if (!isPlainRecord(props)) throw new Error(`${relative(root, file)} getStaticPaths()[${index}].props must be an object`)
+    return { params, props }
+  })
+}
+
+function routeFromPage(file, params = {}) {
   const page = relative(pagesDirectory, file).replace(/\\/g, "/").replace(/\.tsx$/, "")
-  return page === "index" ? "" : page.replace(/\/index$/, "")
+  if (page.includes("[...")) throw new Error(`Catch-all routes are not supported: ${page}`)
+  const filled = page.replace(/\[([^\]]+)\]/g, (_, name) => {
+    if (!Object.hasOwn(params, name)) throw new Error(`Missing param "${name}" for route ${page}`)
+    const value = String(params[name])
+    if (!value || value === "." || value === ".." || /[\\/\0?#]/.test(value)) throw new Error(`Invalid param "${name}" for route ${page}`)
+    return value
+  })
+  return filled === "index" ? "" : filled.replace(/\/index$/, "")
+}
+
+function isPlainRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
 }
 
 async function walk(directory) {

package/framework/core.d.ts

@@ -26,8 +26,8 @@ export function listExpression(read: () => unknown, module: string, handler: str
 export function listItem(): unknown
 export function listConditional(kind: "and" | "ternary", read: () => unknown, truthy: () => unknown, falsy: () => unknown, module: string, handler: string): unknown
 
-export function renderPage(
-  component: (props: Record<string, never>) => unknown | Promise<unknown>,
+export function renderPage<Props = Record<string, never>>(
+  component: (props: Props) => unknown | Promise<unknown>,
   metadata?: {
     title?: string
     description?: string
@@ -44,8 +44,10 @@ export function renderPage(
     icon?: string
     appleTouchIcon?: string
     manifest?: string
-    styles?: boolean
-  }
+    styles?: boolean | string[]
+    base?: string
+  },
+  props?: Props
 ): Promise<{
   html: string
   hasBehaviors: boolean

package/framework/core.mjs

@@ -220,27 +220,27 @@ function serializeCapture(name, value, seen) {
   }
 }
 
-export async function renderPage(component, metadata = {}) {
-  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: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasBindings: false, hasLists: false, hasListStyles: false }
+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 }
 
   try {
-    const body = await renderNode({ type: component, props: {} })
+    const body = await renderNode({ type: component, props })
     const title = escapeHtml(metadata.title ?? "Kudzu")
     const head = renderMetadata(metadata)
     const styles = metadata.styles === false
       ? ""
-      : '<link rel="stylesheet" href="/assets/style.css">'
+      : (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="/assets/kudzu.js"></script>'
+      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu.js")}"></script>`
       : ""
     const nativeRuntime = renderContext.hasNativeBehaviors
-      ? '<script type="module" src="/assets/kudzu-native.js"></script>'
+      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-native.js")}"></script>`
       : ""
     const bindingRuntime = renderContext.hasBindings
-      ? '<script type="module" src="/assets/kudzu-binding.js"></script>'
+      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-binding.js")}"></script>`
       : ""
     const listRuntime = renderContext.hasLists
-      ? '<script type="module" src="/assets/kudzu-list.js"></script>'
+      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-list.js")}"></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))
@@ -253,9 +253,12 @@ export async function renderPage(component, metadata = {}) {
     const state = initialState.length
       ? ` data-k-state='${escapeJsonAttribute(initialState)}'`
       : ""
+    const textBindings = renderContext.textBindings.length
+      ? ` data-k-text-bindings='${escapeJsonAttribute(renderContext.textBindings)}'`
+      : ""
 
     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}>${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}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasBindings: renderContext.hasBindings,
       hasLists: renderContext.hasLists,
@@ -283,9 +286,9 @@ function renderMetadata(metadata) {
   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(metadata.icon)}">`)
-  if (metadata.appleTouchIcon) tags.push(`<link rel="apple-touch-icon" href="${escapeAttribute(metadata.appleTouchIcon)}">`)
-  if (metadata.manifest) tags.push(`<link rel="manifest" href="${escapeAttribute(metadata.manifest)}">`)
+  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))}">`)
 
   meta("og:title", metadata.title, true)
   meta("og:description", metadata.description, true)
@@ -307,6 +310,14 @@ function renderMetadata(metadata) {
   return tags.join("")
 }
 
+function assetPath(base, path) {
+  return `${base ?? ""}/${path}`
+}
+
+function baseUrl(base, value) {
+  return value.startsWith("/") ? `${base ?? ""}${value}` : value
+}
+
 async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node == null || node === false || node === true) return ""
   if (Array.isArray(node)) {
@@ -370,7 +381,9 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     if (renderContext.conditionDepth || renderContext.listDepth) for (const stateId of reactiveStateIds(descriptor)) renderContext.conditionStates.add(stateId)
     renderContext.hasBehaviors = true
     renderContext.hasBindings = true
-    return `<span data-k-bind-text='${escapeJsonAttribute(descriptor)}'>${escapeHtml(node.value ?? "")}</span>`
+    const id = renderContext.textBindings.length
+    renderContext.textBindings.push(descriptor)
+    return `<!--k-text:${id}-->${escapeHtml(node.value ?? "")}<!--k-text-end-->`
   }
   if (node?.[listConditionalMarker]) {
     const descriptor = { kind: node.kind, module: node.module, handler: node.handler }
@@ -412,6 +425,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   const listAttributes = []
   const listExpressionAttributes = []
   const listEvents = []
+  let rawHtml
 
   if (renderContext.listRoot) {
     const root = renderContext.listRoot
@@ -433,6 +447,14 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     if (["ref", "dangerouslysetinnerhtml"].includes(rawName.toLowerCase()) && (value?.[signalMarker] || value?.[bindingMarker])) {
       throw new Error(`Reactive ${rawName} is not supported`)
     }
+    if (rawName === "dangerouslySetInnerHTML") {
+      if (renderContext.listDepth) throw new Error("dangerouslySetInnerHTML is not supported in keyed lists")
+      if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, "__html")) throw new Error("dangerouslySetInnerHTML requires { __html }")
+      if (value.__html?.[signalMarker] || value.__html?.[bindingMarker]) throw new Error("Reactive dangerouslySetInnerHTML is not supported")
+      if (props.children != null) throw new Error("dangerouslySetInnerHTML cannot be used with children")
+      rawHtml = value.__html == null ? "" : String(value.__html)
+      continue
+    }
 
     if (/^on[A-Z]/.test(rawName)) {
         const event = rawName.slice(2).toLowerCase()
@@ -504,8 +526,11 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (tag === "option" && selectValue !== noSelectValue && String(optionValue(props)) === (selectValue == null ? "" : String(selectValue))) attributes += " selected"
 
   const voidElements = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"])
-  if (voidElements.has(tag)) return `<${tag}${attributes}>`
-  const children = directListText ? escapeHtml(directListText.value ?? "") : await renderNode(props.children, childNamespace, childSelectValue)
+  if (voidElements.has(tag)) {
+    if (rawHtml !== undefined) throw new Error(`dangerouslySetInnerHTML cannot be used on <${tag}>`)
+    return `<${tag}${attributes}>`
+  }
+  const children = rawHtml ?? (directListText ? escapeHtml(directListText.value ?? "") : await renderNode(props.children, childNamespace, childSelectValue))
   return `<${tag}${attributes}>${children}</${tag}>`
 }
 

package/package.json

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