@kudzujs/core 0.5.6 → 0.5.7

package/README.md

@@ -97,6 +97,27 @@ export default function Post({ title }: { title: string }) {
 
 This emits `/posts/oak` and `/posts/pine`. Parameter values must be safe single path segments; missing, unsafe, and duplicate routes fail the build.
 
+When a bracket value exists only in the request URL, opt into one static fallback document and read it with `useParams()`:
+
+```tsx
+// src/pages/items/[id].tsx
+import { useEffect, useParams } from "@kudzujs/core"
+
+export const runtimeParams = true
+
+export default function ItemPage() {
+  const { id } = useParams<{ id: string }>()
+
+  useEffect(() => {
+    fetch(`/api/items/${encodeURIComponent(id)}`)
+  }, [])
+
+  return <h1>Item {id}</h1>
+}
+```
+
+This emits `dist/items/[id]/index.html` and a route-specific pathname matcher. `getStaticPaths()` and `runtimeParams` are mutually exclusive. Runtime parameters occupy complete path segments, decode once, and reject empty, malformed, separator, control, and traversal-like values. The development server resolves deep links automatically. Production static hosts must try exact files first, then internally rewrite matching paths to the fallback file while preserving the browser URL; `.kudzu/kudzu-plan.json` and `afterBuild()` expose ordered `rewrites` for host adapters. Navigation remains ordinary `<a>` document navigation, not an SPA router.
+
 Static trusted HTML can be rendered without a transform layer:
 
 ```tsx
@@ -110,8 +131,8 @@ Every CSS file under `src` is copied to the same relative path under `dist/asset
 ```js
 export default {
   base: "/newsletter",
-  async afterBuild({ outDir, routes, plans, base }) {
-    // Write RSS, sitemap, search indexes, or other static artifacts.
+  async afterBuild({ outDir, routes, plans, rewrites, base }) {
+    // Write host rewrites, RSS, sitemap, or other static artifacts.
   }
 }
 ```
@@ -395,6 +416,7 @@ Supported:
 - File-based static routes
 - Build-time async components
 - Dynamic static routes with build-time props
+- Runtime bracket parameters with static fallback documents and host rewrite metadata
 - Static trusted `dangerouslySetInnerHTML`
 - Base-path deployments, multiple CSS files, and `afterBuild`
 - Primitive `useState` bindings

package/framework/README.md

@@ -1,6 +1,6 @@
 # Framework Internals
 
-- `build.mjs`: TSX compilation, static and `getStaticPaths` routes, base paths, CSS collection, post-build hooks, behavior extraction, static HTML output, and the development server.
+- `build.mjs`: TSX compilation, static, `getStaticPaths`, and runtime-fallback 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.
@@ -13,6 +13,6 @@
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; mount effects add `effect-runtime.js` and one route-specific entry. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; runtime bracket pages using `useParams()` add one route-specific pathname matcher; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; mount effects add `effect-runtime.js` and one route-specific entry. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. Runtime fallback rewrites are ordered by specificity in `.kudzu/kudzu-plan.json` and passed to `afterBuild()`; exact static files take precedence in development. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/build.mjs

@@ -47,6 +47,8 @@ export async function build({ quiet = false, minify = true } = {}) {
   let stateSeedCount = 0
   const plans = []
   const effectEntries = []
+  const paramEntries = []
+  const rewrites = []
   const emittedRoutes = new Set()
   const styleUrls = cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`))
 
@@ -55,24 +57,40 @@ export async function build({ quiet = false, minify = true } = {}) {
     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 entries = await staticPathEntries(module, pageFile)
+    const runtimeSchema = runtimeRouteSchema(module, pageFile)
+    if (runtimeSchema) {
+      const conflicting = rewrites.find(rewrite => sameRuntimePrecedence(rewrite, runtimeSchema))
+      if (conflicting) throw new Error(`Ambiguous runtime routes: ${conflicting.route} and ${runtimeSchema.route}`)
+      rewrites.push({
+        route: runtimeSchema.route,
+        pattern: withBase(base, `/${runtimeSchema.route}`),
+        file: `${runtimeSchema.route}/index.html`,
+        params: runtimeSchema.params,
+        segments: runtimeSchema.segments
+      })
+    }
+    const entries = runtimeSchema ? [{ params: {}, props: {} }] : await staticPathEntries(module, pageFile)
     for (const { params, props } of entries) {
-      const route = routeFromPage(pageFile, params)
+      const route = runtimeSchema?.route ?? routeFromPage(pageFile, params)
       const routePath = withBase(base, `/${route}`)
       const effectPath = `effects/${route ? `${route}/index` : "index"}.js`
+      const paramPath = `params/${route}/index.js`
       if (emittedRoutes.has(routePath)) throw new Error(`Duplicate route: ${routePath}`)
       emittedRoutes.add(routePath)
       const result = await renderPage(module.default, {
         ...(module.metadata ?? {}),
         styles: styleUrls.length ? styleUrls : false,
         base,
-        effectAsset: assetPath(base, `assets/${effectPath}`)
+        effectAsset: assetPath(base, `assets/${effectPath}`),
+        paramAsset: assetPath(base, `assets/${paramPath}`),
+        runtimeParams: runtimeSchema?.params
       }, props)
       const routeDirectory = join(outputDirectory, route)
       await mkdir(routeDirectory, { recursive: true })
       await writeFile(join(routeDirectory, "index.html"), result.html)
       plans.push({ route: routePath, ...result.plan })
-      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: result.plan.effects })
+      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params })
+      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: result.plan.effects, paramPath: result.hasParams ? paramPath : undefined })
       if (result.hasBehaviors) behaviorCount++
       if (result.hasBindings) bindingCount++
       if (result.hasLists) listCount++
@@ -165,10 +183,15 @@ export async function build({ quiet = false, minify = true } = {}) {
     await mkdir(resolve(output, ".."), { recursive: true })
     await writeJavaScript(output, handlerModule.code, minify)
   }
+  for (const entry of paramEntries) {
+    const output = join(assetsDirectory, entry.path)
+    await mkdir(dirname(output), { recursive: true })
+    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base), minify)
+  }
   for (const entry of effectEntries) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
-    await writeJavaScript(output, printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base), minify)
+    await writeJavaScript(output, printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath), minify)
   }
   const clientModules = await collectClientModules(handlerModules.flatMap(module => module.clientImports), sourceFileSet)
   for (const file of clientModules) {
@@ -194,7 +217,8 @@ 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))
+  const sortedRewrites = rewrites.sort((left, right) => runtimeSpecificity(right) - runtimeSpecificity(left) || left.pattern.localeCompare(right.pattern))
+  await writeFile(join(workDirectory, "kudzu-plan.json"), JSON.stringify({ routes: plans, rewrites: sortedRewrites }, null, 2))
   for (const file of cssFiles) {
     const output = join(assetsDirectory, relative(sourceDirectory, file))
     await mkdir(dirname(output), { recursive: true })
@@ -203,7 +227,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   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 })
+    await config.afterBuild({ root, outDir: outputDirectory, sourceDir: sourceDirectory, base, routes: plans.map(plan => plan.route), plans, rewrites: sortedRewrites })
   }
 
   if (!quiet) console.log(`Built ${plans.length} page(s), ${behaviorCount} interactive page(s) into dist/`)
@@ -219,7 +243,7 @@ function specializeNativeRuntime(source, events, modules) {
   return `${imports}\n${specializeEvents(source, events).replace(/const modules = new Map\(\[[^\n]*\]\)/, `const modules = new Map([${entries}])`)}`
 }
 
-function printEffectEntry(effects, output, handlerModules, assetsDirectory, base) {
+function printEffectEntry(effects, output, handlerModules, assetsDirectory, base, paramPath) {
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
     const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
@@ -229,6 +253,7 @@ function printEffectEntry(effects, output, handlerModules, assetsDirectory, base
   const imports = [
     `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}`,
     `import { createEffectContext } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu-effect.js")))}`,
+    ...(paramPath ? [`import ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, paramPath)))}`] : []),
     ...modules.map((module, index) => `import * as __kEffectModule${index} from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, module.path)))}`)
   ]
   const entries = moduleUrls.map((url, index) => `[${JSON.stringify(url)}, __kEffectModule${index}]`).join(",")
@@ -245,6 +270,42 @@ for (const effect of effects) {
 }`
 }
 
+function printParamEntry(schema, params, output, assetsDirectory, base) {
+  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}
+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 = location.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
+}`
+}
+
 function hasCaptureType(value, type) {
   if (!value || typeof value !== "object") return false
   if (value.type === type) return true
@@ -316,7 +377,8 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
   const server = createServer(async (request, response) => {
     try {
       const url = new URL(request.url, "http://localhost")
-      const pathname = decodeURIComponent(url.pathname)
+      const rawPathname = url.pathname
+      const pathname = decodeURIComponent(rawPathname)
       if (pathname === "/__kudzu_reload") {
         response.writeHead(200, {
           "content-type": "text/event-stream; charset=utf-8",
@@ -336,15 +398,24 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
         return
       }
 
-      const relativePath = stripBase(pathname, base).replace(/^\/+/, "")
+      const relativePath = stripBaseStrict(pathname, decodeURIComponent(base)).replace(/^\/+/, "")
       let file = resolve(outputDirectory, relativePath)
       if (!file.startsWith(`${outputDirectory}${sep}`) && file !== outputDirectory) throw new Error("Invalid path")
 
       if ((await exists(file)) && (await stat(file)).isDirectory()) file = join(file, "index.html")
       if (!(await exists(file)) && !extname(file)) file = join(file, "index.html")
+      let matchedRoute
+      if (!(await exists(file)) && !buildError) {
+        const plan = JSON.parse(await readFile(join(workDirectory, "kudzu-plan.json"), "utf8"))
+        const rewrite = plan.rewrites?.find(entry => runtimePathValues(rawPathname, entry, browserPath(base)))
+        if (rewrite) {
+          file = resolve(outputDirectory, rewrite.file)
+          matchedRoute = rewrite.pattern
+        }
+      }
       const isHtml = extname(file) === ".html"
       const content = isHtml
-        ? injectDevClient(buildError ? errorPage(buildError) : await readFile(file, "utf8"), session, revision, buildError ? [] : await devSchema(pathname))
+        ? injectDevClient(buildError ? errorPage(buildError) : await readFile(file, "utf8"), session, revision, buildError ? [] : await devSchema(withBase(base, stripBaseStrict(pathname, decodeURIComponent(base))), matchedRoute))
         : await readFile(file)
       response.writeHead(200, {
         "content-type": contentType(file),
@@ -397,22 +468,58 @@ function injectDevClient(html, session, revision, schema) {
   return `${html}${devClient(session, revision, schema)}`
 }
 
-function stripBase(path, base) {
+function stripBaseStrict(path, base) {
   if (!base) return path
   if (path === base) return "/"
-  return path.startsWith(`${base}/`) ? path.slice(base.length) : path
+  if (path.startsWith(`${base}/`)) return path.slice(base.length)
+  throw new Error("Path is outside the configured base")
 }
 
-async function devSchema(pathname) {
+async function devSchema(pathname, matchedRoute) {
   try {
     const plan = JSON.parse(await readFile(join(workDirectory, "kudzu-plan.json"), "utf8"))
-    const route = pathname.replace(/\/(?:index\.html)?$/, "") || "/"
+    const route = matchedRoute ?? (pathname.replace(/\/(?:index\.html)?$/, "") || "/")
     return stateSchema(plan.routes.find(entry => entry.route === route)?.states ?? [])
   } catch {
     return []
   }
 }
 
+function runtimePathValues(pathname, rewrite, base) {
+  try {
+    let path = stripBrowserBase(pathname, base)
+    if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
+    const rawSegments = path.slice(1).split("/")
+    if (rawSegments.length !== rewrite.segments.length) return undefined
+    const values = Object.create(null)
+    for (let index = 0; index < rewrite.segments.length; index++) {
+      const segment = rewrite.segments[index]
+      const value = decodeRuntimeSegment(rawSegments[index], Boolean(segment.param))
+      if (segment.literal !== undefined && value !== segment.literal) return undefined
+      if (segment.param) values[segment.param] = value
+    }
+    return values
+  } catch {
+    return undefined
+  }
+}
+
+function stripBrowserBase(path, base) {
+  if (!base) return path
+  const pathSegments = path.slice(1).split("/")
+  const baseSegments = base.slice(1).split("/").map(segment => decodeURIComponent(segment))
+  if (pathSegments.length < baseSegments.length || baseSegments.some((segment, index) => decodeRuntimeSegment(pathSegments[index], false) !== segment)) throw new Error("Path is outside the configured base")
+  return `/${pathSegments.slice(baseSegments.length).join("/")}`
+}
+
+function decodeRuntimeSegment(raw, param) {
+  if (param && /%(?:2f|5c)/i.test(raw)) throw new Error("Encoded separator")
+  const value = decodeURIComponent(raw)
+  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("Invalid runtime parameter")
+  return value
+}
+
 function inlineJson(value) {
   return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029")
 }
@@ -1960,10 +2067,17 @@ async function loadConfig() {
 
 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")
+  if (typeof value !== "string" || !value.startsWith("/") || /[?#\0]/.test(value) || /%(?:2f|5c)/i.test(value)) throw new Error("kudzu.config base must be a root-relative path")
+  let decoded
+  try { decoded = decodeURIComponent(value) } catch { throw new Error("kudzu.config base must be a root-relative path") }
+  if (/[\\?#\0]/.test(decoded) || decoded.split("/").includes("..") || [...decoded].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159)) throw new Error("kudzu.config base must be a root-relative path")
   return value.replace(/\/+$/, "")
 }
 
+function browserPath(path) {
+  return path ? new URL(path, "http://kudzu.local").pathname : ""
+}
+
 function assetPath(base, path) {
   return `${base}/${path}`
 }
@@ -1986,6 +2100,43 @@ async function staticPathEntries(module, file) {
   })
 }
 
+function runtimeRouteSchema(module, file) {
+  if (!Object.hasOwn(module, "runtimeParams")) return undefined
+  if (module.runtimeParams !== true) throw new Error(`${relative(root, file)} runtimeParams must be exactly true`)
+  if (typeof module.getStaticPaths === "function") throw new Error(`${relative(root, file)} runtimeParams cannot be combined with getStaticPaths()`)
+  const route = pageRoutePattern(file)
+  if (route.includes("[...")) throw new Error(`Catch-all routes are not supported: ${route}`)
+  const names = new Set()
+  const segments = route.split("/").map(segment => {
+    const match = segment.match(/^\[([^\]]+)\]$/)
+    if (!match) {
+      if (/[\[\]]/.test(segment)) throw new Error(`${relative(root, file)} runtime parameters must occupy a complete path segment`)
+      return { literal: segment }
+    }
+    const name = match[1]
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) || ["__proto__", "constructor", "prototype"].includes(name)) throw new Error(`${relative(root, file)} invalid runtime parameter name ${JSON.stringify(name)}`)
+    if (names.has(name)) throw new Error(`${relative(root, file)} duplicate runtime parameter ${JSON.stringify(name)}`)
+    names.add(name)
+    return { param: name }
+  })
+  if (!names.size) throw new Error(`${relative(root, file)} runtimeParams requires a bracket page`)
+  return { route, segments, params: [...names] }
+}
+
+function pageRoutePattern(file) {
+  const page = relative(pagesDirectory, file).replace(/\\/g, "/").replace(/\.tsx$/, "")
+  return page === "index" ? "" : page.replace(/\/index$/, "")
+}
+
+function runtimeSpecificity(schema) {
+  return schema.segments.filter(segment => segment.literal !== undefined).length
+}
+
+function sameRuntimePrecedence(left, right) {
+  if (left.segments.length !== right.segments.length || runtimeSpecificity(left) !== runtimeSpecificity(right)) return false
+  return left.segments.every((segment, index) => segment.literal === undefined || right.segments[index].literal === undefined || segment.literal === right.segments[index].literal)
+}
+
 function routeFromPage(file, params = {}) {
   const page = relative(pagesDirectory, file).replace(/\\/g, "/").replace(/\.tsx$/, "")
   if (page.includes("[...")) throw new Error(`Catch-all routes are not supported: ${page}`)

package/framework/core.d.ts

@@ -2,6 +2,7 @@ export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
 
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
 export function useEffect(effect: () => void | Promise<void>, dependencies: readonly []): void
+export function useParams<Params extends Record<string, string> = Record<string, string>>(): Readonly<Params>
 
 export interface RefObject<T> {
   readonly current: T | null
@@ -48,18 +49,22 @@ export function renderPage<Props = Record<string, never>>(
     styles?: boolean | string[]
     base?: string
     effectAsset?: string
+    paramAsset?: string
+    runtimeParams?: string[]
   },
   props?: Props
 ): Promise<{
   html: string
   hasBehaviors: boolean
   hasEffects: boolean
+  hasParams: boolean
   hasBindings: boolean
   hasLists: boolean
   hasListStyles: boolean
   hasStateSeed: boolean
   plan: {
     states: Array<{ id: string; name: string; initialValue: unknown }>
+    params: Array<{ name: string; id: string }>
     events: Array<{
       event: string
       commands?: Array<[string, string, unknown]>

package/framework/core.mjs

@@ -24,10 +24,37 @@ export function useState(initialValue, name) {
   }
 
   const id = `s${renderContext.nextState++}`
-  const signal = {
+  const signal = createSignal(id, initialValue)
+
+  const setter = () => {
+    throw new Error("State setters are compiled into ordered browser behaviors")
+  }
+  Object.defineProperty(setter, setterMarker, { value: id })
+  renderContext.states[id] = { name: name ?? id, initialValue }
+  return [signal, setter]
+}
+
+export function useParams() {
+  if (!renderContext?.runtimeParamNames?.length) throw new Error("useParams() requires export const runtimeParams = true on a bracket page")
+  if (!renderContext.params) {
+    const params = Object.create(null)
+    renderContext.paramEntries = renderContext.runtimeParamNames.map((name, index) => {
+      const id = `p${index}`
+      params[name] = createSignal(id, "")
+      return { name, id }
+    })
+    renderContext.params = Object.freeze(params)
+    renderContext.hasBehaviors = true
+    renderContext.hasParams = true
+  }
+  return renderContext.params
+}
+
+function createSignal(id, value) {
+  return {
     [signalMarker]: true,
     id,
-    value: initialValue,
+    value,
     valueOf() {
       return this.value
     },
@@ -35,13 +62,6 @@ export function useState(initialValue, name) {
       return String(this.value)
     }
   }
-
-  const setter = () => {
-    throw new Error("State setters are compiled into ordered browser behaviors")
-  }
-  Object.defineProperty(setter, setterMarker, { value: id })
-  renderContext.states[id] = { name: name ?? id, initialValue }
-  return [signal, setter]
 }
 
 export function useEffect(callback, dependencies, module, handler, states, scope, source) {
@@ -242,7 +262,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}) {
-  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, contexts: [], states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const body = await renderNode({ type: component, props })
@@ -268,6 +288,9 @@ export async function renderPage(component, metadata = {}, props = {}) {
     const nativeRuntime = renderContext.hasNativeBehaviors
       ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-native.js")}"></script>`
       : ""
+    const paramRuntime = renderContext.hasParams
+      ? `<script type="module" src="${escapeAttribute(metadata.paramAsset)}"></script>`
+      : ""
     const bindingRuntime = renderContext.hasBindings
       ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-binding.js")}"></script>`
       : ""
@@ -293,15 +316,17 @@ export async function renderPage(component, metadata = {}, props = {}) {
       : ""
 
     return {
-      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}</head><body${state}${textBindings}>${body}${runtime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}</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}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasEffects: renderContext.hasEffects,
+      hasParams: renderContext.hasParams,
       hasBindings: renderContext.hasBindings,
       hasLists: renderContext.hasLists,
       hasListStyles: renderContext.hasListStyles,
       hasStateSeed: initialState.length > 0,
       plan: {
         states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
+        params: renderContext.paramEntries,
         events: renderContext.events,
         effects: renderContext.effects,
         bindings: renderContext.bindings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "build": "node ./bin/kudzu.mjs build",
     "dev": "node ./bin/kudzu.mjs dev",
     "check": "tsc --noEmit && tsc -p test/fixtures/tsconfig.json --noEmit && node ./bin/kudzu.mjs build",
-    "test": "node --test",
+    "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run check && npm test",
     "deploy": "wrangler deploy",
     "preview": "wrangler dev"