@kudzujs/core 0.4.14 → 0.5.0

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:
@@ -294,6 +333,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 +388,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:

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
   })
 
@@ -1289,9 +1317,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.0",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",