@kudzujs/core 0.5.6 → 0.5.8

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.
   }
 }
 ```
@@ -325,10 +346,23 @@ useEffect(async () => {
 
 Kudzu does not execute the effect during static rendering and does not ship the component. It emits one route-specific effect entry that invokes the compiled callback against existing logical state and direct DOM commit capabilities. Effects may update reactive text, attributes, conditions, and keyed lists. Multiple effects start independently in source order, and one synchronous or asynchronous failure is reported without suppressing later effects.
 
-Only inline block-bodied callbacks with a literal empty dependency array are supported. Dependencies, cleanup or other return values, callback parameters, and non-serializable captures are rejected at build time. Pages without effects receive no effect entry and retain their existing output.
+An effect may directly return an inline cleanup function:
+
+```tsx
+useEffect(() => {
+  const onResize = () => console.log(window.innerWidth)
+  window.addEventListener("resize", onResize)
+
+  return () => window.removeEventListener("resize", onResize)
+}, [])
+```
+
+Cleanup runs once when the document leaves outside the browser back-forward cache. Effect-local resources and component state read by nested cleanup closures retain their mount-time values. Cleanup failures are isolated so later cleanups still run. Only inline block-bodied callbacks with a literal empty dependency array are supported. Dependencies, named or dynamically obtained cleanup functions, cleanup parameters or generators, other return values, callback parameters, and non-serializable captures are rejected at build time. Async effects cannot return cleanup functions; the cleanup itself may be async. Pages without effects receive no effect entry, and effects without cleanup retain their smaller runtime output.
 
 A matched mount-fetch benchmark renders a title and two keyed rows from local JSON. With one warm-up and seven rotating clean builds, Kudzu shipped initial HTML, 3.4 KB initial JS gzip, 8.1 KB total output, and built in 374 ms. React CSR shipped no initial content, 59.3 KB initial JS gzip, 189.2 KB total output, and built in 992 ms. Hand-written ESM shipped 534 B initial JS gzip, 1.2 KB total output, and built in 210 ms. Fresh-profile Chrome medians to loaded data were 157.9 ms, 166.5 ms, and 153.4 ms respectively.
 
+A matched resize-listener cleanup fixture, measured with the same warm-up and seven rotating clean builds, shipped 1.2 KB JavaScript gzip and built in 402 ms with Kudzu. Svelte shipped 10.1 KB and built in 861 ms, Vue shipped 23.6 KB and built in 768 ms, and React shipped 59.1 KB and built in 1,058 ms. Kudzu and the 127 B hand-written Astro baseline emitted initial HTML; the CSR fixtures did not.
+
 ## Normal JavaScript
 
 Command-only setters use the smallest optimized path. Conditions, local variables, browser globals, events, and `async`/`await` compile to external ESM without `eval`, `new Function`, or inline executable code.
@@ -395,6 +429,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. Effect cleanup integrates with shared unmount hooks when present and otherwise disposes directly on non-persisted `pagehide`; unrelated routes and effects retain their existing runtime. 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,8 @@ 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 hasCleanup = effects.some(effect => effect.cleanup)
   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)
@@ -227,12 +252,15 @@ function printEffectEntry(effects, output, handlerModules, assetsDirectory, base
     return module
   })
   const imports = [
-    `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}`,
+    hasCleanup
+      ? `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}\nconst { browserState, commitDom } = __kRuntime`
+      : `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(",")
-  return `${imports.join("\n")}
+  if (!hasCleanup) return `${imports.join("\n")}
 const effects = ${inlineJson(effects)}
 const modules = new Map([${entries}])
 for (const effect of effects) {
@@ -242,6 +270,75 @@ for (const effect of effects) {
   } catch (error) {
     console.error(error)
   }
+}`
+  return `${imports.join("\n")}
+const effects = ${inlineJson(effects)}
+const modules = new Map([${entries}])
+const cleanups = []
+for (const effect of effects) {
+  try {
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, effect.scope))
+    if (effect.cleanup && typeof result === "function") cleanups.push(result)
+    else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}
+let cleaned = false
+const dispose = root => {
+  if (root !== document || cleaned) return
+  cleaned = true
+  for (const cleanup of cleanups) {
+    try {
+      const result = cleanup()
+      if (result && typeof result.then === "function") result.catch(error => console.error(error))
+    } catch (error) {
+      console.error(error)
+    }
+  }
+  cleanups.length = 0
+}
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+addEventListener("pagehide", event => {
+  if (event.persisted) return
+  if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
+  else dispose(document)
+})`
+}
+
+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
 }`
 }
 
@@ -316,7 +413,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 +434,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 +504,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")
 }
@@ -699,14 +842,18 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         const [callback, dependencies] = node.arguments
         if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) fail(callback, "useEffect() callback must be an inline function")
         if (ts.isFunctionExpression(callback) && callback.name) fail(callback, "useEffect() callback function must be anonymous")
+        if (callback.asteriskToken) fail(callback, "useEffect() callback cannot be a generator")
         if (callback.parameters.length) fail(callback, "useEffect() callback cannot declare parameters")
         if (!ts.isArrayLiteralExpression(dependencies) || dependencies.elements.length) fail(dependencies, "useEffect() dependencies must be a literal empty array")
         if (!nearestFunction(node)) fail(node, "useEffect() cannot be used outside a Kudzu component")
-        if (returnsCleanup(callback)) fail(callback, "useEffect() cleanup functions are not supported")
         if (!ts.isBlock(callback.body)) fail(callback, "useEffect() callback must use a block body")
-        if (returnsEffectValue(callback)) fail(callback, "useEffect() return values are not supported")
+        const returns = effectReturns(callback)
+        if (returns.invalid) fail(returns.invalid, "useEffect() return values must be inline cleanup functions")
+        const invalidCleanup = returns.cleanups.find(cleanup => cleanup.parameters.length || cleanup.asteriskToken)
+        if (invalidCleanup) fail(invalidCleanup, "useEffect() cleanup functions cannot declare parameters or be generators")
+        if (returns.cleanup && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) fail(callback, "useEffect() async callbacks cannot return cleanup functions")
         const setters = settersForNode(node, settersByFunction)
-        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, importBindings, clientImports, "effect", undefined, true)
+        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, importBindings, clientImports, "effect", undefined, true, returns.cleanup)
         usesBehavior = true
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [
           callback,
@@ -715,7 +862,8 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
           factory.createStringLiteral(descriptor.exportName),
           descriptor.states,
           descriptor.scope,
-          factory.createStringLiteral(sourceLocation(node, sourceFile))
+          factory.createStringLiteral(sourceLocation(node, sourceFile)),
+          returns.cleanup ? factory.createTrue() : factory.createFalse()
         ])
       }
 
@@ -1133,7 +1281,7 @@ function isJsxSyntaxIdentifier(node) {
 }
 
 function isFunctionLike(node) {
-  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)
+  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node)
 }
 
 function isDestructuredParameter(identifier, fn) {
@@ -1373,14 +1521,14 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   ])
 }
 
-function compileNativeCallback(expression, setters, factory, entries, importBindings, clientImports, prefix, listItem, deferValues = false) {
+function compileNativeCallback(expression, setters, factory, entries, importBindings, clientImports, prefix, listItem, deferValues = false, snapshotNested = false) {
   const allCaptures = nativeCaptureNames(expression, setters)
   const imports = [...referencedImportedBindings(expression, importBindings)].map(name => importBindings.get(name))
   const captures = new Set([...allCaptures].filter(name => !importBindings.has(name)))
   for (const entry of imports) clientImports.add(entry.target)
   const usedStates = nativeStateNames(expression, setters)
   const exportName = `${prefix}${entries.length}`
-  entries.push({ exportName, expression, captures, imports, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))) })
+  entries.push({ exportName, expression, captures, imports, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), snapshotNested })
   const value = name => deferValues
     ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createIdentifier(name))
     : factory.createIdentifier(name)
@@ -1479,6 +1627,7 @@ function isReferenceIdentifier(node) {
   if ((ts.isPropertyAccessExpression(parent) && parent.name === node) ||
       (ts.isPropertyAssignment(parent) && parent.name === node) ||
       (ts.isMethodDeclaration(parent) && parent.name === node) ||
+      ((ts.isGetAccessorDeclaration(parent) || ts.isSetAccessorDeclaration(parent)) && parent.name === node) ||
       (ts.isVariableDeclaration(parent) && parent.name === node) ||
       (ts.isParameter(parent) && parent.name === node) ||
       (ts.isFunctionDeclaration(parent) && parent.name === node) ||
@@ -1496,7 +1645,7 @@ function nearestFunction(node) {
 
 function isShadowedByParameter(node, scopeRoot) {
   for (let current = node.parent; current; current = current.parent) {
-    if ((ts.isFunctionDeclaration(current) || ts.isFunctionExpression(current) || ts.isArrowFunction(current)) && current.parameters.some(parameter => bindingNames(parameter.name).includes(node.text))) return true
+    if (isFunctionLike(current) && current.parameters.some(parameter => bindingNames(parameter.name).includes(node.text))) return true
     if (current === scopeRoot) break
   }
   return false
@@ -1626,33 +1775,24 @@ function sourceLocation(node, fallbackSource) {
   return `${sourceFile.fileName}:${position.line + 1}:${position.character + 1}`
 }
 
-function returnsCleanup(callback) {
-  if (ts.isArrowFunction(callback) && !ts.isBlock(callback.body)) {
-    const body = unwrapExpression(callback.body)
-    return ts.isArrowFunction(body) || ts.isFunctionExpression(body)
-  }
-  let found = false
+function effectReturns(callback) {
+  let cleanup = false
+  let invalid
+  const cleanups = []
   const visit = node => {
-    if (found || node !== callback.body && isFunctionLike(node)) return
+    if (invalid || node !== callback.body && isFunctionLike(node)) return
     if (ts.isReturnStatement(node) && node.expression) {
       const expression = unwrapExpression(node.expression)
-      if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) found = true
+      if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
+        cleanup = true
+        cleanups.push(expression)
+      }
+      else invalid = node
     }
-    if (!found) ts.forEachChild(node, visit)
-  }
-  visit(callback.body)
-  return found
-}
-
-function returnsEffectValue(callback) {
-  let found = false
-  const visit = node => {
-    if (found || node !== callback.body && isFunctionLike(node)) return
-    if (ts.isReturnStatement(node) && node.expression) found = true
-    if (!found) ts.forEachChild(node, visit)
+    if (!invalid) ts.forEachChild(node, visit)
   }
   visit(callback.body)
-  return found
+  return { cleanup, cleanups, invalid }
 }
 
 function printClientImports(entries, handlerPath) {
@@ -1767,9 +1907,11 @@ function relativeModulePath(from, to) {
   return path.startsWith(".") ? path : `./${path}`
 }
 
-function printNativeHandler({ exportName, expression, captures, setters }) {
+function printNativeHandler({ exportName, expression, captures, setters, snapshotNested }) {
   const factory = ts.factory
   const stateNames = new Set(setters.values())
+  const snapshotNames = snapshotNested ? nestedStateNames(expression, setters) : new Set()
+  const snapshots = new Map([...snapshotNames].map(name => [name, factory.createUniqueName("__kEffectState")]))
   const transformer = context => root => {
     const visitor = node => {
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
@@ -1786,9 +1928,11 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
         return setterReference(factory, setters.get(node.text))
       }
       if (ts.isShorthandPropertyAssignment(node) && stateNames.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        if (snapshots.has(node.name.text) && insideNestedFunction(node, expression)) return factory.createPropertyAssignment(node.name, snapshots.get(node.name.text))
         return factory.createPropertyAssignment(node.name, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(node.name.text)]))
       }
       if (ts.isIdentifier(node) && stateNames.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
+        if (snapshots.has(node.text) && insideNestedFunction(node, expression)) return snapshots.get(node.text)
         return factory.createCallExpression(
           factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"),
           undefined,
@@ -1807,9 +1951,13 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
   }
   const transformed = ts.transform(expression.body, [transformer])
   try {
-    const body = ts.isBlock(expression.body)
+    let body = ts.isBlock(expression.body)
       ? transformed.transformed[0]
       : factory.createBlock([factory.createReturnStatement(transformed.transformed[0])], true)
+    if (snapshots.size) body = factory.updateBlock(body, [
+      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([...snapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(name)]))), ts.NodeFlags.Const)),
+      ...body.statements
+    ])
     const modifiers = [factory.createModifier(ts.SyntaxKind.ExportKeyword)]
     if (expression.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) modifiers.push(factory.createModifier(ts.SyntaxKind.AsyncKeyword))
     const declaration = factory.createFunctionDeclaration(
@@ -1827,6 +1975,24 @@ function printNativeHandler({ exportName, expression, captures, setters }) {
   }
 }
 
+function nestedStateNames(expression, setters) {
+  const states = new Set(setters.values())
+  const names = new Set()
+  const visit = node => {
+    if (ts.isIdentifier(node) && states.has(node.text) && isReferenceIdentifier(node) && insideNestedFunction(node, expression) && !isShadowedIdentifier(node, expression)) names.add(node.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body)
+  return names
+}
+
+function insideNestedFunction(node, root) {
+  for (let current = node.parent; current && current !== root; current = current.parent) {
+    if (isFunctionLike(current)) return true
+  }
+  return false
+}
+
 function setterReference(factory, stateName) {
   return factory.createArrowFunction(
     undefined,
@@ -1960,10 +2126,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 +2159,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

@@ -1,7 +1,9 @@
 export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
+export type EffectCleanup = () => void | Promise<void>
 
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
-export function useEffect(effect: () => void | Promise<void>, dependencies: readonly []): void
+export function useEffect(effect: () => void | EffectCleanup | 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,24 +50,28 @@ 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]>
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
-    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }>
+    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown>; cleanup?: true }>
     bindings: Array<{
       target: string
       state?: string

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,21 +62,14 @@ 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) {
+export function useEffect(callback, dependencies, module, handler, states, scope, source, cleanup) {
   if (!renderContext) throw new Error("useEffect() can only run while rendering a Kudzu component")
   if (typeof callback !== "function" || !Array.isArray(dependencies) || dependencies.length || !module || !handler) {
     throw new Error("useEffect() must be compiled with a literal empty dependency array")
   }
-  renderContext.effects.push({ module, handler, states, scope, source })
+  renderContext.effects.push({ module, handler, states, scope, source, ...(cleanup ? { cleanup: true } : {}) })
   renderContext.hasBehaviors = true
   renderContext.hasEffects = true
 }
@@ -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 })
@@ -251,6 +271,7 @@ export async function renderPage(component, metadata = {}, props = {}) {
         return {
           module: effect.module,
           handler: effect.handler,
+          ...(effect.cleanup ? { cleanup: true } : {}),
           ...nativeDescriptor(effect.states.map(([name, read]) => [name, read()]), effect.scope.map(([name, read]) => [name, read()]))
         }
       } catch (error) {
@@ -268,6 +289,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 +317,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.8",
   "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"