@kudzujs/core 0.7.22 → 0.7.24

package/README.md

@@ -10,7 +10,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.7.22 - SVG structures and native links.** Reactive SVG conditionals and flat keyed lists preserve their namespace, while supported React Router `Link` authoring erases to base-aware native anchors with zero router runtime. Read the [release notes](./RELEASES.md#0722---svg-structures-and-native-links) or open the [release page](https://kudzujs.cloud/releases/0.7.22).
+**Latest release: 0.7.24 - Router-shaped query reads.** Read-only React Router `useSearchParams()` authoring now lowers direct static `get()` reads to nullable route signals initialized by a minimal native query reader. Read the [release notes](./RELEASES.md#0724---router-shaped-query-reads) or open the [release page](https://kudzujs.cloud/releases/0.7.24).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)
@@ -83,6 +83,8 @@ ordinary React-shaped TSX
 - Build-known data and routes become complete HTML through async components and `getStaticPaths()`.
 - Native document navigation is the default; static routes do not load a client runtime.
 - A named or aliased React Router `Link` with a static root-relative `to` erases to a base-aware native anchor; no router package or runtime is emitted.
+- A direct named or aliased React Router `useParams()` call on a `runtimeParams` bracket route reuses Kudzu's route-specific pathname reader.
+- Read-only React Router `useSearchParams()` with direct static `get("name")` locals lowers to nullable signals initialized by a minimal route-specific query reader.
 - Unsupported nearby patterns fail during the build with a source location and actionable boundary.
 
 Migration input may retain supported imports from `react`; Kudzu erases those references and never emits or executes React. New Kudzu source should import framework APIs from `@kudzujs/core`.

package/RELEASES.md

@@ -1,5 +1,54 @@
 # Kudzu Releases
 
+## 0.7.24 - Router-shaped query reads
+
+Kudzu 0.7.24 accepts a narrow read-only React Router `useSearchParams()` shape and lowers each static query read to a nullable route signal backed by native `URLSearchParams`, without adding a router runtime.
+
+### New in 0.7.24
+
+- A named or aliased `useSearchParams` import may initialize one top-level `const [params]` tuple without a setter.
+- Direct top-level `const value = params.get("literal")` reads lower to cached nullable query signals.
+- The route-specific parameter module uses native `URLSearchParams.get()` semantics for missing, empty, duplicate, plus-encoded, Unicode, and percent-encoded values.
+- Static fallback HTML renders missing query text as blank and omits nullable attributes; browser values initialize before route effects mount.
+- Query signals compose with direct text and attributes, effect dependencies, native handlers, React Router Link lowering, and configured same-document navigation.
+- Routes without query reads emit no parameter module or query branch.
+- Setter tuples, dynamic names, other methods, aliases, wrapped expressions, and indirect reads fail with source diagnostics.
+- The complete suite passes 115/115 tests with Chrome coverage for standalone and navigation-group query initialization.
+
+### Boundary
+
+The supported migration shape is one top-level `const [params] = useSearchParams()` and one or more top-level direct `const value = params.get("literal")` reads. Query setters, `getAll`, `has`, iteration, dynamic names, aliases, inline JSX calls, fallback wrappers, layout ownership, and general URLSearchParams semantics remain unsupported. Native document navigation remains the default; no SPA router is included.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.24
+```
+
+## 0.7.23 - Router-shaped runtime params
+
+Kudzu 0.7.23 accepts the conventional React Router `useParams()` source shape on runtime bracket routes and redirects it to the existing capability-specific pathname reader without shipping React Router.
+
+### New in 0.7.23
+
+- Named or aliased `useParams` imports from `react-router-dom` may be called directly on bracket pages exporting `runtimeParams = true`.
+- One optional TypeScript type argument is preserved through normalization while the runtime call remains argument-free.
+- The React Router binding is redirected to `@kudzujs/core`; no `react-router-dom` module reference survives emitted code.
+- Mixed `Link` and `useParams` imports lower together: Link becomes a base-aware native anchor and params reuse the pathname reader.
+- Runtime parameter values retain existing secure decoding, direct DOM bindings, effects, handlers, and navigation-group lifecycle behavior.
+- Indirect references, runtime arguments, default/namespace imports, and unsupported router hooks fail with source diagnostics.
+- The complete suite passes 112/112 tests with browser coverage for multi-parameter paths and mixed Link/params migration input.
+
+### Boundary
+
+React Router `useParams()` lowering requires a direct named or aliased zero-argument call on a bracket route exporting `runtimeParams = true`. Build-known `getStaticPaths()` routes continue to receive params through page props. Catch-all routes, optional segments, indirect calls, runtime arguments, and other router hooks remain unsupported. No SPA router or shared router runtime is added.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.23
+```
+
 ## 0.7.22 - SVG structures and native links
 
 Kudzu 0.7.22 extends ordinary React-shaped structural authoring into SVG and erases the common React Router `Link` form to native navigation without adding an SVG renderer or router runtime.

package/framework/README.md

@@ -6,6 +6,10 @@ Migration source may retain conventional `react` imports for supported named or
 
 A named or aliased `Link` import from `react-router-dom` may render directly with one static root-relative `to` plus native anchor props. The compiler prefixes the configured `base`, changes the element to `<a href>`, and erases the import, so native navigation remains the default and configured navigation groups see an ordinary eligible anchor. Dynamic or relative destinations, `NavLink`, router-only props, spreads, default/namespace imports, and non-JSX uses fail with source diagnostics. No React Router package code or router runtime is emitted.
 
+A named or aliased React Router `useParams` import may also be called directly without runtime arguments on a bracket route exporting `runtimeParams = true`. The compiler redirects that local binding to `@kudzujs/core`, preserving one optional TypeScript type argument, and reuses the existing route-specific pathname matcher. Indirect calls and other router hooks remain unsupported. Build-known `getStaticPaths()` routes use page props instead because no browser pathname capability is needed.
+
+A named or aliased read-only React Router `useSearchParams` import may initialize one top-level `const [params]` binding. Each top-level `const value = params.get("literal")` lowers to one cached nullable `useSearchParam()` signal. The existing parameter asset initializes those signals with native `URLSearchParams.get()` semantics before route effects mount, including during configured same-document navigation. Missing keys remain `null`, direct text renders blank, and nullable attributes are removed. Setter destructuring, dynamic names, other methods, aliases, wrapped reads, and layout ownership are rejected. Routes without query reads do not emit this branch or a parameter asset.
+
 Direct `clsx` calls over literal strings, numbers, arrays, object conditions, and conditional expressions are similarly lowered to ordinary concatenation and conditional expressions. The package import is erased, and dynamic classes continue through the existing binding compiler without serializing or shipping the `clsx` function.
 
 Repeated ordinary same-file and relative-imported child components execute independently at build time, so each `useState` call receives a distinct concrete state ID while shared native handler modules retain per-element state maps and captures. A direct JSON-safe primitive parent state passed to a destructured child prop remains the same signal for child DOM bindings and effect dependencies; repeated calls own independent effect records, and conditional removal cleans up before remount recreates the effect. Multiple direct primitive dependencies share the existing commit batching path: every value is compared with `Object.is`, and one or more same-turn changes cause one cleanup and rerun. A top-level immutable local derived through a supported pure primitive expression from direct state may also be an effect dependency: source state commits schedule evaluation, the derived result is compared with `Object.is`, and the expression is substituted into setup and cleanup handlers. Effect setup and directly returned cleanup callbacks may each resolve one top-level simple `const` function in the same component; those functions are substituted into the existing handler graph rather than retained in a browser registry. Reactive conditional descriptors own state created by their direct branch: initial visible output reuses the rendered template IDs, removal deletes those slots, and remount recreates them from serialized initial values. Static sibling routes and branches without local state add no ownership metadata, component function, hook dispatcher, or rerender loop.

package/framework/build.mjs

@@ -115,7 +115,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       const navigable = Boolean(navigationGroup)
       const effectPath = `effects/${route ? `${route}/index` : "index"}.js`
       const nativePath = `native/${route ? `${route}/index` : "index"}.js`
-      const paramPath = `params/${route}/index.js`
+      const paramPath = `params/${route ? `${route}/index` : "index"}.js`
       if (emittedRoutes.has(routePath)) throw new Error(`Duplicate route: ${routePath}`)
       emittedRoutes.add(routePath)
       emittedApplicationRoutes.add(applicationRoute)
@@ -153,7 +153,7 @@ export async function build({ quiet = false, minify = true } = {}) {
       const usesDependencyRuntime = !navigable && hasDependencies && !result.plan.effects.some(effect => effect.owner) && !result.hasBindings && !result.hasLists && !result.plan.events.some(event => event.native)
       pageEntries.push({ route, html: result.html, usesDependencyRuntime })
       plans.push({ route: routePath, ...result.plan })
-      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, usesDependencyRuntime, navigable })
+      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, searchParams: result.plan.searchParams, usesDependencyRuntime, navigable })
       if (result.hasEffects) effectEntries.push({ path: effectPath, effects: runtimeEffects(result.plan.effects, navigable), paramPath: result.hasParams ? paramPath : undefined, usesDependencyRuntime, navigable })
       if (result.plan.events.some(event => event.native)) nativeEntries.push({
         path: nativePath,
@@ -386,7 +386,7 @@ export async function build({ quiet = false, minify = true } = {}) {
   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, runtimeName(entry.usesDependencyRuntime), entry.navigable), minify)
+    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, entry.searchParams, output, assetsDirectory, base, runtimeName(entry.usesDependencyRuntime), entry.navigable), minify)
   }
   for (const entry of effectEntries) {
     const output = join(assetsDirectory, entry.path)
@@ -482,7 +482,7 @@ async function mountInitial() {
     const record = matchRoute(location.pathname)
     if (!record) throw new Error("Initial navigation route does not match")
     const capabilities = await loadCapabilities(validate(document, record))
-    capabilities.params?.(location.pathname)
+    capabilities.params?.(location.pathname, location.search)
     layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
     routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
   } catch (error) {
@@ -493,7 +493,7 @@ async function mountInitial() {
     .replace("  await ready\n", "")
     .replace("    const capabilities = await loadCapabilities(parsed)\n", "    await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n")
     .replace("    await routeDispose()\n    if (current !== revision) return\n", "")
-    .replace("    commit(incoming, parsed.nodes, capabilities.params, url.pathname)\n", "    commit(incoming, parsed.nodes)\n")
+    .replace("    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)\n", "    commit(incoming, parsed.nodes)\n")
     .replace("    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "")
     .replace(`
 async function loadCapabilities(parsed) {
@@ -1406,14 +1406,14 @@ async function invokeCleanup() {
 }${disposal}`
 }
 
-function printParamEntry(schema, params, output, assetsDirectory, base, runtimeName, navigable) {
-  const prefix = navigable ? "export function initializeParams(pathname) {\n" : "let pathname = location.pathname\n"
+function printParamEntry(schema, params, searchParams, output, assetsDirectory, base, runtimeName, navigable) {
+  const signature = searchParams.length ? "pathname, search" : "pathname"
+  const prefix = navigable ? `export function initializeParams(${signature}) {\n` : `${schema ? "let pathname = location.pathname\n" : ""}${searchParams.length ? "let search = location.search\n" : ""}`
   const suffix = navigable ? "\n}" : ""
-  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
-const base = ${inlineJson(browserPath(base).slice(1).split("/").filter(Boolean).map(segment => decodeURIComponent(segment)))}
+  const pathname = schema ? `const base = ${inlineJson(browserPath(base).slice(1).split("/").filter(Boolean).map(segment => decodeURIComponent(segment)))}
 const schema = ${inlineJson(schema.segments)}
 const params = ${inlineJson(params)}
-${prefix}let path = pathname
+let path = pathname
 if (base.length) {
   const pathSegments = path.slice(1).split("/")
   if (pathSegments.length < base.length || base.some((segment, index) => decodeSegment(pathSegments[index], false) !== segment)) throw new Error("Runtime route is outside the configured base")
@@ -1441,7 +1441,17 @@ function decodeSegment(raw, param) {
   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
-}${suffix}`
+}
+` : ""
+  const query = searchParams.length ? `const query = new URLSearchParams(search)
+for (const param of ${inlineJson(searchParams)}) {
+  const value = query.get(param.name)
+  browserState.set(param.id, value)
+  commitDom(param.id, value)
+}
+` : ""
+  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
+${prefix}${pathname}${query}${suffix}`
 }
 
 function hasCaptureType(value, type) {
@@ -1776,25 +1786,81 @@ function emittedPackageReference(source, file, packages) {
 
 function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
   const links = new Set()
+  const params = new Set()
+  const searchHooks = new Set()
   for (const statement of sourceFile.statements) {
     if ((ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement)) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react-router-dom") {
       if (ts.isExportDeclaration(statement)) throw sourceNodeError(statement, sourceFile, "React Router exports are not supported; import Link directly where it renders")
       const clause = statement.importClause
       if (clause?.isTypeOnly) continue
       if (!clause) throw sourceNodeError(statement, sourceFile, "Side-effect React Router imports are not supported")
-      if (clause.name) throw sourceNodeError(clause.name, sourceFile, "React Router default imports are not supported; use a named Link import")
+      if (clause.name) throw sourceNodeError(clause.name, sourceFile, "React Router default imports are not supported; use named Link, useParams, or useSearchParams imports")
       const bindings = clause.namedBindings
-      if (!bindings || ts.isNamespaceImport(bindings)) throw sourceNodeError(bindings ?? statement, sourceFile, "React Router namespace imports are not supported; use a named Link import")
+      if (!bindings || ts.isNamespaceImport(bindings)) throw sourceNodeError(bindings ?? statement, sourceFile, "React Router namespace imports are not supported; use named Link, useParams, or useSearchParams imports")
       for (const entry of bindings.elements) {
         if (entry.isTypeOnly) continue
         const imported = (entry.propertyName ?? entry.name).text
         if (imported === "NavLink") throw sourceNodeError(entry, sourceFile, "React Router NavLink active-route semantics cannot be erased to a native anchor")
-        if (imported !== "Link") throw sourceNodeError(entry, sourceFile, `React Router ${imported} is not supported; only named Link imports can be erased to native anchors`)
-        links.add(entry.name.text)
+        if (imported === "Link") links.add(entry.name.text)
+        else if (imported === "useParams") params.add(entry.name.text)
+        else if (imported === "useSearchParams") searchHooks.add(entry.name.text)
+        else throw sourceNodeError(entry, sourceFile, `React Router ${imported} is not supported; only named Link, useParams, and useSearchParams imports can be lowered`)
       }
     }
   }
-  if (!links.size) return sourceFile
+  if (!links.size && !params.size && !searchHooks.size) return sourceFile
+
+  let searchHelper = "__kUseSearchParam"
+  while (sourceFile.text.includes(searchHelper)) searchHelper += "_"
+  const searchDeclarations = new Set()
+  const searchReads = new Map()
+  const searchObjects = []
+  const collectSearchHooks = node => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && searchHooks.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+      const declaration = node.parent
+      const statement = declaration?.parent?.parent
+      const owner = nearestFunction(node)
+      const first = ts.isVariableDeclaration(declaration) && ts.isArrayBindingPattern(declaration.name) ? declaration.name.elements[0] : undefined
+      if (node.questionDotToken || node.arguments.length || node.typeArguments?.length || !ts.isVariableDeclaration(declaration) || declaration.initializer !== node || !isLocalConst(declaration) || !owner || statement?.parent !== owner.body || !ts.isBindingElement(first) || !ts.isIdentifier(first.name) || declaration.name.elements.length !== 1) {
+        throw sourceNodeError(node, sourceFile, "React Router useSearchParams must use one top-level const [params] = useSearchParams() without a setter")
+      }
+      const entry = { name: first.name.text, declaration, statement, owner }
+      searchDeclarations.add(declaration)
+      searchObjects.push(entry)
+    }
+    ts.forEachChild(node, collectSearchHooks)
+  }
+  collectSearchHooks(sourceFile)
+  const searchObjectShadowed = (node, entry) => {
+    for (let current = node.parent; current && current !== entry.owner; current = current.parent) {
+      if (isFunctionLike(current) && (current.parameters.some(parameter => bindingNames(parameter.name).includes(entry.name)) || functionVarDeclaresName(current, entry.name))) return true
+      if (ts.isBlock(current) && current.statements.some(statement => statement !== entry.statement && statementDeclaresName(statement, entry.name))) return true
+      if (ts.isCaseBlock(current) && current.clauses.some(clause => clause.statements.some(statement => statement !== entry.statement && statementDeclaresName(statement, entry.name)))) return true
+      if (ts.isCatchClause(current) && current.variableDeclaration && bindingNames(current.variableDeclaration.name).includes(entry.name)) return true
+      if ((ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current)) && loopDeclaresName(current, entry.name)) return true
+    }
+    return false
+  }
+  for (const entry of searchObjects) {
+    const collectReads = node => {
+      if (ts.isIdentifier(node) && node.text === entry.name && isReferenceIdentifier(node) && !searchObjectShadowed(node, entry)) {
+        const property = node.parent
+        const call = property?.parent
+        const declaration = call?.parent
+        const statement = declaration?.parent?.parent
+        if (!ts.isPropertyAccessExpression(property) || property.expression !== node || property.name.text !== "get" || !ts.isCallExpression(call) || call.expression !== property || call.questionDotToken || call.typeArguments?.length || call.arguments.length !== 1 || !ts.isStringLiteral(call.arguments[0])) {
+          throw sourceNodeError(node, sourceFile, 'React Router search parameters only support direct get("static-name") reads')
+        }
+        if (!ts.isVariableDeclaration(declaration) || declaration.initializer !== call || !ts.isIdentifier(declaration.name) || !isLocalConst(declaration) || statement?.parent !== entry.owner.body) {
+          throw sourceNodeError(call, sourceFile, "React Router search parameter get() must directly initialize one top-level const identifier")
+        }
+        searchReads.set(call, call.arguments[0])
+        return
+      }
+      ts.forEachChild(node, collectReads)
+    }
+    collectReads(entry.owner.body)
+  }
 
   const routerProps = new Set(["discover", "end", "prefetch", "preventScrollReset", "relative", "reloadDocument", "replace", "state", "viewTransition"])
   const attributes = attributesNode => {
@@ -1823,25 +1889,46 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
   }
   const importedLink = tag => ts.isIdentifier(tag) && links.has(tag.text) && !isShadowedIdentifier(tag, sourceFile)
   const visitor = node => {
+    if (ts.isVariableStatement(node) && node.declarationList.declarations.some(declaration => searchDeclarations.has(declaration))) {
+      const declarations = node.declarationList.declarations.filter(declaration => !searchDeclarations.has(declaration))
+      if (!declarations.length) return undefined
+      return factory.updateVariableStatement(node, node.modifiers, factory.updateVariableDeclarationList(node.declarationList, declarations.map(declaration => ts.visitEachChild(declaration, visitor, context))))
+    }
+    if (ts.isCallExpression(node) && searchReads.has(node)) return factory.createCallExpression(factory.createIdentifier(searchHelper), undefined, [searchReads.get(node)])
     if (ts.isJsxElement(node) && importedLink(node.openingElement.tagName)) {
       const opening = factory.updateJsxOpeningElement(node.openingElement, factory.createIdentifier("a"), node.openingElement.typeArguments, attributes(node.openingElement.attributes))
       const closing = factory.updateJsxClosingElement(node.closingElement, factory.createIdentifier("a"))
       return factory.updateJsxElement(node, opening, ts.visitNodes(node.children, visitor), closing)
     }
     if (ts.isJsxSelfClosingElement(node) && importedLink(node.tagName)) return factory.updateJsxSelfClosingElement(node, factory.createIdentifier("a"), node.typeArguments, attributes(node.attributes))
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && params.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+      if (node.questionDotToken || node.arguments.length || (node.typeArguments?.length ?? 0) > 1) throw sourceNodeError(node, sourceFile, "React Router useParams must be called directly without runtime arguments and with at most one type argument")
+      return node
+    }
     if (ts.isIdentifier(node) && links.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router Link imports may only be used as direct JSX elements")
+    if (ts.isIdentifier(node) && params.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useParams imports may only be called directly")
+    if (ts.isIdentifier(node) && searchHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useSearchParams imports may only be used by the supported read-only pattern")
     if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react-router-dom") {
       const clause = node.importClause
       if (!clause || clause.isTypeOnly) return node
       const bindings = clause.namedBindings
       if (!bindings || !ts.isNamedImports(bindings)) return node
-      const elements = bindings.elements.filter(entry => entry.isTypeOnly || (entry.propertyName ?? entry.name).text !== "Link")
+      const elements = bindings.elements.filter(entry => entry.isTypeOnly || !["Link", "useParams", "useSearchParams"].includes((entry.propertyName ?? entry.name).text))
       if (!elements.length) return undefined
       return factory.updateImportDeclaration(node, node.modifiers, factory.updateImportClause(clause, clause.isTypeOnly, undefined, factory.updateNamedImports(bindings, elements)), node.moduleSpecifier, node.attributes)
     }
     return ts.visitEachChild(node, visitor, context)
   }
-  return ts.visitNode(sourceFile, visitor)
+  const normalized = ts.visitNode(sourceFile, visitor)
+  if (!params.size && !searchHooks.size) return normalized
+  const imports = [
+    ...[...params].map(name => factory.createImportSpecifier(false, name === "useParams" ? undefined : factory.createIdentifier("useParams"), factory.createIdentifier(name))),
+    ...(searchHooks.size ? [factory.createImportSpecifier(false, factory.createIdentifier("useSearchParam"), factory.createIdentifier(searchHelper))] : [])
+  ]
+  const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports(imports)), factory.createStringLiteral("@kudzujs/core"))
+  const statements = [...normalized.statements]
+  statements.splice(statements.findLastIndex(statement => ts.isImportDeclaration(statement)) + 1, 0, declaration)
+  return factory.updateSourceFile(normalized, statements)
 }
 
 function normalizeClsxSyntax(sourceFile, factory, context) {

package/framework/core.d.ts

@@ -12,6 +12,7 @@ export function useReducer<State, Action, InitialArg>(reducer: Reducer<State, Ac
 export function useReducer<State, Action>(reducer: Reducer<State, Action>, initialValue: State): [State, Dispatch<Action>]
 export function useEffect(effect: () => void | EffectCleanup | Promise<void>, dependencies: readonly EffectDependency[]): void
 export function useParams<Params extends Record<string, string> = Record<string, string>>(): Readonly<Params>
+export function useSearchParam(name: string): string | null
 
 export interface RefObject<T> {
   readonly current: T | null
@@ -94,6 +95,7 @@ export function renderPage<Props = Record<string, never>>(
   plan: {
     states: Array<{ id: string; name: string; initialValue: unknown; lifetime?: "layout" | "route"; internal?: true }>
     params: Array<{ name: string; id: string }>
+    searchParams: Array<{ name: string; id: string }>
     events: Array<{
       event: string
       commands?: Array<[string, string, unknown]>

package/framework/core.mjs

@@ -123,6 +123,22 @@ export function useParams() {
   return renderContext.params
 }
 
+export function useSearchParam(name) {
+  if (!renderContext) throw new Error("useSearchParam() can only run while rendering a Kudzu component")
+  if (renderContext?.renderScope === "layout") throw new Error("useSearchParam() is only supported in route scope")
+  if (typeof name !== "string") throw new Error("useSearchParam() requires a string name")
+  let signal = renderContext.searchParams.get(name)
+  if (!signal) {
+    const id = nextRenderId("p")
+    signal = createSignal(id, null)
+    renderContext.searchParams.set(name, signal)
+    renderContext.searchParamEntries.push({ name, id })
+  }
+  renderContext.hasBehaviors = true
+  renderContext.hasParams = true
+  return signal
+}
+
 function createSignal(id, value) {
   return {
     [signalMarker]: true,
@@ -416,7 +432,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}, layout) {
-  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }
@@ -496,6 +512,7 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
       plan: {
         states: Object.entries(renderContext.states).map(([id, state]) => ({ id, ...state })),
         params: renderContext.paramEntries,
+        searchParams: renderContext.searchParamEntries,
         events: renderContext.events,
         effects: renderContext.effects,
         bindings: renderContext.bindings,
@@ -560,7 +577,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node?.[signalMarker]) {
     renderContext.textStates.add(node.id)
     if (renderContext.conditionDepth || renderContext.listDepth) renderContext.conditionStates.add(node.id)
-    return `<span data-k-text="${node.id}" data-k-value='${escapeJsonAttribute(node.value)}'>${escapeHtml(node.value)}</span>`
+    return `<span data-k-text="${node.id}" data-k-value='${escapeJsonAttribute(node.value)}'>${escapeHtml(node.value ?? "")}</span>`
   }
   if (typeof node === "string" || typeof node === "number" || typeof node === "bigint") {
     return escapeHtml(node)

package/framework/navigation-runtime.js

@@ -49,7 +49,7 @@ async function mountInitial() {
     const record = matchRoute(location.pathname)
     if (!record) throw new Error("Initial navigation route does not match")
     const capabilities = await loadCapabilities(validate(document, record))
-    capabilities.params?.(location.pathname)
+    capabilities.params?.(location.pathname, location.search)
     layoutDispose = await capabilities.effects?.mountLayoutEffects?.() ?? noDispose
     routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
   } catch (error) {
@@ -130,7 +130,7 @@ async function navigate(url, push) {
     if (current !== revision) return
     await routeDispose()
     if (current !== revision) return
-    commit(incoming, parsed.nodes, capabilities.params, url.pathname)
+    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)
     committed = true
     routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
     if (push) history.pushState(null, "", url)
@@ -175,7 +175,7 @@ function validate(incoming, record) {
   return { nodes, assets: [...new Set(assets)] }
 }
 
-function commit(incoming, incomingNodes, initializeParams, pathname) {
+function commit(incoming, incomingNodes, initializeParams, pathname, search) {
   const start = document.querySelector("template[data-k-route-start]")
   const end = document.querySelector("template[data-k-route-end]")
   if (!start || !end || document.querySelectorAll("template[data-k-route-start],template[data-k-route-end]").length !== 2) throw new Error("Current route markers are invalid")
@@ -189,7 +189,7 @@ function commit(incoming, incomingNodes, initializeParams, pathname) {
   document.body.dataset.kRoute = incoming.body.dataset.kRoute
   const nodes = incomingNodes.map(node => document.importNode(node, true))
   end.before(...nodes)
-  initializeParams?.(pathname)
+  initializeParams?.(pathname, search)
   for (const node of nodes) mountDom(node)
 }
 

package/package.json

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