@kudzujs/core 0.9.2 → 0.10.0

package/docs/next-architecture/goal-d-routing-compatibility-decisions.md

@@ -12,6 +12,7 @@ Supported React Router-shaped migration remains narrow:
 
 - static root-relative `Link` lowers to a base-prefixed native `<a>`;
 - bracket runtime routes may lower direct `useParams()` to the pathname reader;
+- route-owned exact static root-relative `useMatch()` bindings fold case-insensitively from the build-known application route;
 - top-level direct `useSearchParams()` reads/writes lower to URL signals and native history;
 - direct nested `useNavigate()` calls lower to native `location.assign()` or `location.replace()`;
 - no React Router package executes in build output or the browser.

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records. The active `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md); that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -62,15 +62,24 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 - A planned patch may ship under a different actual version only if this table and release-facing documentation are updated before release.
 - Release notes describe completed facts; this file continues to describe future work.
 - Internal decomposition alone does not require `0.9.0`; use a minor only for a public compiler/tooling or compatibility boundary.
+- From `0.10.0` onward, each application-capability section owns one minor and each independently accepted evidence packet owns one patch as defined by the active application-capability release plan.
 
 ## Generator Versions
 
-`create-kudzu@0.1.103` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.9.0`.
+`create-kudzu@0.1.104` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.10.0`.
 
 ## Release Boundary
 
 Every patch is independently revertible before publication. After npm publication, never repoint its tag; forward-fix with the next patch. Require the exact commit to pass CI, package smoke installation, registry verification, and the performance gates before starting the next ownership seam.
 
+From `0.10.0` onward every completed patch packet is a full release transaction:
+version and lockfile updates, release records, an accepted `Release Kudzu X.Y.Z`
+commit, commit push and CI, an immutable `vX.Y.Z` tag push, a published GitHub
+release, npm publication through `.github/workflows/publish.yml`, registry
+verification, and fresh-install verification. Incomplete work sessions retain
+the same target version and do not create commits, tags, or npm releases merely
+because the session ended.
+
 ## Per-Patch Continuation Checklist
 
 - [ ] Confirm all earlier planned patches are complete or explicitly replanned.

package/framework/README.md

@@ -10,7 +10,7 @@ Native platform work remains ordinary source. A direct async handler or directly
 
 Imperative canvas migrations use the same effect ownership rather than a component or canvas runtime. One `null`-initialized canvas DOM ref may feed an inline effect whose local variables persist across a recursive animation-frame callback, an `IntersectionObserver`, and native canvas/window listeners; the returned cleanup must cancel the latest frame, disconnect the observer, and remove every listener. Bare `IntersectionObserver` and `performance` identifiers remain browser globals in emitted effect ESM. Component-level mutable value refs and callbacks shared across effects or JSX handlers remain unsupported; move resource-private state and listeners into the owning effect.
 
-Localized static migrations do not need a package router. `getStaticPaths()` emits each build-known locale, a small relative Link replacement prefixes native hrefs from the locale prop, and an optional `/` mount effect may choose a stored locale or inspect `navigator.languages` before calling `location.replace()` with the original query and hash. This preserves automatic browser-language entry and locale-prefixed navigation; request-time `Accept-Language` negotiation still requires host or edge configuration. Build-known MDX becomes static `dangerouslySetInnerHTML`, while copy controls, tabs, and other supported interactive components remain ordinary state and handler capabilities beside that HTML.
+Localized static migrations do not need a package router. `getStaticPaths()` emits each build-known locale, a small relative Link replacement prefixes native hrefs from the locale prop, and an optional `/` mount effect may choose a stored locale or inspect `navigator.languages` before calling `location.replace()` with the original query and hash. Runtime-resource `react-i18next` `useTranslation()` calls receive a source diagnostic directing this migration instead of silently selecting one language or retaining i18next. This preserves automatic browser-language entry and locale-prefixed navigation; request-time `Accept-Language` negotiation still requires host or edge configuration. Build-known MDX becomes static `dangerouslySetInnerHTML`, while copy controls, tabs, and other supported interactive components remain ordinary state and handler capabilities beside that HTML.
 
 A top-level component local shaped exactly as `const supported = "literal" in navigator` may control one direct `supported && <Branch />` JSX site. Kudzu emits the branch as false static fallback, evaluates the browser capability once through an existing mount effect, and uses existing state-conditional ownership to mount its DOM and handlers only when supported. The value cannot escape or feed aliases, composed expressions, ternaries, dynamic properties, `canShare()`, or other browser globals.
 
@@ -20,10 +20,16 @@ A named or aliased `Link` import from `react-router-dom` may render directly wit
 
 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 React Router `useSearchParams` import may initialize one top-level `const [params]` or `const [params, setParams]` binding. Each top-level `const value = params.get("literal")` lowers to one cached nullable `useSearchParam()` signal. New Kudzu source may call that same literal reader directly; binding nullable query values to hidden input `value` and `disabled` attributes initializes native GET form carry without a generic mount effect. Direct setter calls inside nested browser callbacks accept one synchronous inline updater over native `URLSearchParams`; no options pushes history and exactly `{ replace: true }` replaces it. The route parameter asset recommits changed query signals and follows `popstate`. Missing keys remain `null`, direct text renders blank, and nullable attributes are removed. Dynamic names, direct-value setters, other methods on the outer params object, aliases, wrapped reads, and layout ownership are rejected. Routes without query reads or writes do not emit this branch or a parameter asset.
+A named or aliased React Router `useMatch` import may directly initialize one top-level `const` from an exact static root-relative string such as `useMatch("/")` in route scope. The compiler compares it case-insensitively with the build-known application route and returns the conventional match object or `null` during rendering, then erases the router import. Reused relative components receive the route of each page invocation. Layout use, runtime-parameter pages, params, wildcards, query/hash patterns, trailing slashes, dynamic patterns, indirect calls, and pattern objects are rejected. No route matcher ships to the browser.
+
+A named or aliased React Router `useSearchParams` import may initialize one top-level `const [params]` or `const [params, setParams]` binding. Each top-level `const value = params.get("literal")` lowers to one cached nullable `useSearchParam()` signal. The exact top-level pagination form `const page = Number(params.get("literal")) || finiteNumber` and string form `const order = params.get("literal") || importedImmutableArray[staticIndex]` separate that raw signal into a compiler-owned local and reuse the existing primitive binding evaluator. The string fallback must be a static numeric element of a named relative JSON-safe immutable array. New Kudzu source may call the literal reader directly; binding nullable query values to hidden input `value` and `disabled` attributes initializes native GET form carry without a generic mount effect. Direct setter calls inside nested browser callbacks accept one synchronous inline updater over native `URLSearchParams`; no options pushes history and exactly `{ replace: true }` replaces it. The route parameter asset recommits changed query signals and follows `popstate`, including read-only routes. Missing keys remain `null`, direct text renders blank, and nullable attributes are removed. Dynamic names or indexes, direct-value setters, other methods on the outer params object, aliases, indirect reads, broader wrappers, and layout ownership are rejected. Routes without query reads or writes do not emit this branch or a parameter asset.
 
 A named or aliased React Router `useNavigate` import may initialize one top-level `const` identifier. A direct call from a nested browser callback with one safe static root-relative string lowers to `location.assign()` after applying `base`; exactly `{ replace: true }` lowers to `location.replace()`. This deliberately performs native document navigation even when enhanced navigation is configured. Dynamic or relative destinations, render-time calls, aliases passed as values, and options such as `state`, `relative`, or `preventScrollReset` are rejected. Routes without an actual navigation handler emit no browser JavaScript.
 
+Named or aliased React Bootstrap `Row` and `Col` imports may be used as direct JSX elements with children and at most one static `className`. The React migration normalization pass erases those package imports and emits native `<div>` elements. `Row` emits `row`; a `Col` without spans emits `col`, while numeric literal `xs`, `sm`, `md`, `lg`, `xl`, and `xxl` values from 1 through 12 emit Bootstrap span classes in deterministic largest-to-smallest breakpoint order. The application must keep Bootstrap CSS reachable. Boolean, object, dynamic, offset, and order grid props, dynamic classes, spreads, default/subpath/namespace imports, non-JSX references, and other React Bootstrap components are rejected or remain unsupported. This shape emits no browser JavaScript.
+
+Browser-only package-query migrations use one inline dependency effect with native `fetch()` and application-owned loading, error, and data state. Apache Answer-shaped page/order search signals may derive both effect dependencies and endpoint values; dependency replacement prevents a superseded response from writing state, while existing keyed-list ownership handles nested result rows. SWR, axios, `qs`, query clients, caches, Providers, retries, and background schedulers are not retained. Build-known reads should remain async page/component work instead.
+
 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. Reactive text and attributes may reference recursively chained top-level immutable locals derived through supported pure primitive expressions from direct state; the compiler substitutes those expressions into the existing binding evaluator and subscribes every source state. Fixed-locale `new Intl.NumberFormat("literal").format(Math.round(expression))` display chains reuse that binding ESM, while dynamic locales and options remain unsupported. 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.
@@ -47,7 +53,7 @@ Reduced Zustand migration stores lower through package-neutral `SharedStateIR` a
 - `compiler/handler-lowering.mjs`: source-local native/effect callback, reducer, Context, package-neutral shared-action, reactive-binding, and list-evaluator AST lowering before IR finalization.
 - `compiler/handler-codegen.mjs`: AST-free ordered import rendering and finalized handler/binding export-source assembly.
 - `compiler/render-control-pass.mjs`: render-function early-return and exhaustive adjacent-assignment normalization.
-- `compiler/router-pass.mjs`: React Router import validation and native Link, pathname parameter, search parameter, and imperative navigation lowering.
+- `compiler/router-pass.mjs`: React Router import validation and native Link, build-time exact match, pathname parameter, search parameter, and imperative navigation lowering.
 - `compiler/route-capability-planner.mjs`: RouteIR v1 validation and pure CapabilityIR v1 projection into runtime and artifact requirements.
 - `compiler/runtime-family-planner.mjs`: deterministic standalone capability deduplication and enhanced-navigation group unioning at the ESM singleton boundary.
 - `compiler/route-artifact-report.mjs`: deterministic per-route capability signatures and runtime requirements plus handler, Worker, stylesheet, and transitive esbuild chunk closure reporting.

package/framework/build.mjs

@@ -246,6 +246,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
         styles: styleUrls.length ? styleUrls : false,
         managedStyles: navigable ? sourceStyleUrls : [],
         base,
+        applicationRoute,
         runtimeAsset: runtimePlaceholder,
         bindingAsset: bindingPlaceholder,
         listAsset: listPlaceholder,

package/framework/compiler/param-codegen.mjs

@@ -39,7 +39,7 @@ function decodeSegment(raw, param) {
   return value
 }
 ` : ""
-    const searchInitializer = searchParamsWritable && searchParams.length ? `function initializeSearch(search) {
+    const searchInitializer = searchParams.length ? `function initializeSearch(search) {
 const query = new URLSearchParams(search)
 for (const param of ${inlineJson(searchParams)}) {
   const value = query.get(param.name)
@@ -48,13 +48,7 @@ for (const param of ${inlineJson(searchParams)}) {
 }
 }
 ` : ""
-    const query = searchParams.length ? searchParamsWritable ? "initializeSearch(search)\n" : `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)
-}
-` : ""
+    const query = searchParams.length ? "initializeSearch(search)\n" : ""
     const writer = searchParamsWritable ? `
 function setSearchParams(update, replace) {
   const next = update(new URLSearchParams(location.search))
@@ -66,7 +60,8 @@ function setSearchParams(update, replace) {
 }
 ${navigable ? "" : `globalThis.__kSetSearchParams = setSearchParams
 addEventListener("popstate", () => ${searchParams.length ? "initializeSearch(location.search)" : "undefined"})`}` : ""
+    const reader = !navigable && !searchParamsWritable && searchParams.length ? '\naddEventListener("popstate", () => initializeSearch(location.search))' : ""
     return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(runtimeDirectory, runtimeName)))}
-${searchInitializer}${prefix}${pathname}${query}${suffix}${writer}`
+${searchInitializer}${prefix}${pathname}${query}${suffix}${writer}${reader}`
   }
 }

package/framework/compiler/react-migration-pass.mjs

@@ -3,6 +3,68 @@ import { bindingNames, importDeclarationNames, isFunctionLike, isLocalConst, isR
 import { analyzeCollectionPipeline, isArrayFromCall } from "./collection-analysis.mjs"
 
 export function createReactMigrationPass({ cloneAst, jsxTagName }) {
+  function normalizeReactBootstrapLayout(sourceFile, factory, context) {
+    const layouts = new Map()
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "react-bootstrap") continue
+      const clause = statement.importClause
+      if (!clause || clause.name || !clause.namedBindings || ts.isNamespaceImport(clause.namedBindings)) throw sourceNodeError(statement, sourceFile, "React Bootstrap layout migration requires named Row or Col imports")
+      for (const entry of clause.namedBindings.elements) {
+        const imported = (entry.propertyName ?? entry.name).text
+        if (!entry.isTypeOnly && ["Row", "Col"].includes(imported)) layouts.set(entry.name.text, imported.toLowerCase())
+      }
+    }
+    if (!layouts.size) return sourceFile
+
+    const layout = tag => ts.isIdentifier(tag) && layouts.has(tag.text) && !isShadowedIdentifier(tag, sourceFile) ? layouts.get(tag.text) : undefined
+    const attributes = node => {
+      let authored
+      const spans = new Map()
+      const kind = layout(node.parent.tagName)
+      const breakpoints = ["xxl", "xl", "lg", "md", "sm", "xs"]
+      for (const property of node.properties) {
+        if (ts.isJsxSpreadAttribute(property)) throw sourceNodeError(property, sourceFile, "React Bootstrap Row and Col do not support spread props during native layout lowering")
+        const name = property.name.text
+        const initializer = property.initializer
+        const value = ts.isStringLiteral(initializer) ? initializer : initializer && ts.isJsxExpression(initializer) ? unwrapExpression(initializer.expression) : undefined
+        if (name === "className") {
+          if (authored !== undefined) throw sourceNodeError(property, sourceFile, "React Bootstrap Row and Col accept className only once")
+          if (!value || !ts.isStringLiteral(value) && !ts.isNoSubstitutionTemplateLiteral(value)) throw sourceNodeError(property, sourceFile, "React Bootstrap Row and Col className must be a static string")
+          authored = value.text
+          continue
+        }
+        if (kind === "col" && breakpoints.includes(name)) {
+          const span = value && ts.isNumericLiteral(value) ? Number(value.text) : NaN
+          if (!Number.isInteger(span) || span < 1 || span > 12) throw sourceNodeError(property, sourceFile, `React Bootstrap Col breakpoint ${JSON.stringify(name)} must be an integer literal from 1 through 12`)
+          spans.set(name, span)
+          continue
+        }
+        throw sourceNodeError(property, sourceFile, `React Bootstrap Row and Col only support a static className or numeric Col breakpoint prop; found ${JSON.stringify(name)}`)
+      }
+      const generated = kind === "row" ? ["row"] : spans.size ? breakpoints.filter(name => spans.has(name)).map(name => name === "xs" ? `col-${spans.get(name)}` : `col-${name}-${spans.get(name)}`) : ["col"]
+      return factory.createJsxAttributes([factory.createJsxAttribute(factory.createIdentifier("className"), factory.createStringLiteral([...generated, authored].filter(Boolean).join(" ")))])
+    }
+    const visitor = node => {
+      if (ts.isJsxElement(node) && layout(node.openingElement.tagName)) {
+        const opening = factory.updateJsxOpeningElement(node.openingElement, factory.createIdentifier("div"), node.openingElement.typeArguments, attributes(node.openingElement.attributes))
+        const closing = factory.updateJsxClosingElement(node.closingElement, factory.createIdentifier("div"))
+        return factory.updateJsxElement(node, opening, ts.visitNodes(node.children, visitor), closing)
+      }
+      if (ts.isJsxSelfClosingElement(node) && layout(node.tagName)) return factory.updateJsxSelfClosingElement(node, factory.createIdentifier("div"), node.typeArguments, attributes(node.attributes))
+      if (ts.isIdentifier(node) && layouts.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Bootstrap Row and Col imports may only be used as direct JSX elements")
+      if (ts.isImportDeclaration(node) && !node.importClause?.isTypeOnly && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react-bootstrap") {
+        const clause = node.importClause
+        const bindings = clause?.namedBindings
+        if (!clause || !bindings || !ts.isNamedImports(bindings)) return node
+        const elements = bindings.elements.filter(entry => entry.isTypeOnly || !["Row", "Col"].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)
+  }
+
   function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCollections = new Set()) {
     const supported = new Set(["createContext", "useContext", "useEffect", "useId", "useReducer", "useRef", "useState"])
     const erased = new Set(["createRef", "forwardRef", "memo", "useCallback", "useMemo"])
@@ -19,7 +81,7 @@ export function createReactMigrationPass({ cloneAst, jsxTagName }) {
         else if (!entry.isTypeOnly && /^use[A-Z]/.test(imported)) throw sourceNodeError(entry, sourceFile, `React ${imported} is not supported by Kudzu migration input`)
       }
     }
-    if (!aliases.size && !reactObjects.size) return sourceFile
+    if (!aliases.size && !reactObjects.size) return normalizeReactBootstrapLayout(sourceFile, factory, context)
 
     const migrationCallName = call => {
       if (ts.isIdentifier(call.expression) && aliases.has(call.expression.text) && !isShadowedIdentifier(call.expression, sourceFile)) return aliases.get(call.expression.text)
@@ -193,7 +255,7 @@ export function createReactMigrationPass({ cloneAst, jsxTagName }) {
     }
     let normalized = ts.visitNode(sourceFile, visitor)
     const missing = [...required].filter(name => !imported.has(name)).sort()
-    if (!missing.length) return normalized
+    if (!missing.length) return normalizeReactBootstrapLayout(normalized, factory, context)
     for (const name of missing) {
       const collision = sourceFile.statements.some(statement => statementDeclaresName(statement, name) || ts.isImportDeclaration(statement) && importDeclarationNames(statement).includes(name) && statement.moduleSpecifier.text !== "react")
       if (collision) throw sourceNodeError(sourceFile, sourceFile, `React.${name} cannot be normalized because ${JSON.stringify(name)} is already declared`)
@@ -203,7 +265,7 @@ export function createReactMigrationPass({ cloneAst, jsxTagName }) {
     const lastImport = statements.findLastIndex(statement => ts.isImportDeclaration(statement))
     statements.splice(lastImport + 1, 0, declaration)
     normalized = factory.updateSourceFile(normalized, statements)
-    return normalized
+    return normalizeReactBootstrapLayout(normalized, factory, context)
   }
 
   function lowerReactForwardRef(call, sourceFile, factory) {

package/framework/compiler/router-pass.mjs

@@ -2,9 +2,10 @@ import ts from "typescript"
 import { bindingNames, functionVarDeclaresName, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedIdentifier, loopDeclaresName, nearestFunction, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
 
 export function createRouterPass({ withBase }) {
-  return function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
+  return function normalizeReactRouterSyntax(sourceFile, factory, context, base, importedCollections = new Map()) {
     const links = new Set()
     const params = new Set()
+    const matchHooks = new Set()
     const searchHooks = new Set()
     const navigateHooks = new Set()
     for (const statement of sourceFile.statements) {
@@ -13,22 +14,62 @@ export function createRouterPass({ withBase }) {
         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 named Link, useParams, useSearchParams, or useNavigate imports")
+        if (clause.name) throw sourceNodeError(clause.name, sourceFile, "React Router default imports are not supported; use named Link, useParams, useMatch, useSearchParams, or useNavigate imports")
         const bindings = clause.namedBindings
-        if (!bindings || ts.isNamespaceImport(bindings)) throw sourceNodeError(bindings ?? statement, sourceFile, "React Router namespace imports are not supported; use named Link, useParams, useSearchParams, or useNavigate imports")
+        if (!bindings || ts.isNamespaceImport(bindings)) throw sourceNodeError(bindings ?? statement, sourceFile, "React Router namespace imports are not supported; use named Link, useParams, useMatch, useSearchParams, or useNavigate 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") links.add(entry.name.text)
           else if (imported === "useParams") params.add(entry.name.text)
+          else if (imported === "useMatch") matchHooks.add(entry.name.text)
           else if (imported === "useSearchParams") searchHooks.add(entry.name.text)
           else if (imported === "useNavigate") navigateHooks.add(entry.name.text)
-          else throw sourceNodeError(entry, sourceFile, `React Router ${imported} is not supported; only named Link, useParams, useSearchParams, and useNavigate imports can be lowered`)
+          else throw sourceNodeError(entry, sourceFile, `React Router ${imported} is not supported; only named Link, useParams, useMatch, useSearchParams, and useNavigate imports can be lowered`)
         }
       }
     }
-    if (!links.size && !params.size && !searchHooks.size && !navigateHooks.size) return sourceFile
+    if (!links.size && !params.size && !matchHooks.size && !searchHooks.size && !navigateHooks.size) return sourceFile
+
+    let matchHelper = "__kUseRouteMatch"
+    while (sourceFile.text.includes(matchHelper)) matchHelper += "_"
+    const matchCalls = new Map()
+    const topLevelFunction = owner => owner.parent === sourceFile || ts.isExportAssignment(owner.parent) && owner.parent.parent === sourceFile || (ts.isArrowFunction(owner) || ts.isFunctionExpression(owner)) && ts.isVariableDeclaration(owner.parent) && owner.parent.parent?.parent?.parent === sourceFile
+    const componentFunction = owner => {
+      if (!topLevelFunction(owner)) return false
+      if (ts.isExportAssignment(owner.parent)) return true
+      if (ts.isFunctionDeclaration(owner) && owner.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) return true
+      const name = ts.isFunctionDeclaration(owner) ? owner.name?.text : ts.isVariableDeclaration(owner.parent) && ts.isIdentifier(owner.parent.name) ? owner.parent.name.text : undefined
+      if (!name || !/^[A-Z]/.test(name)) return false
+      let eventHandlerUse = false
+      const inspect = node => {
+        if (eventHandlerUse) return
+        if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) {
+          for (let current = node.parent; current && current !== sourceFile; current = current.parent) {
+            if (ts.isJsxAttribute(current) && /^on[A-Z]/.test(current.name.text)) eventHandlerUse = true
+          }
+        }
+        ts.forEachChild(node, inspect)
+      }
+      inspect(sourceFile)
+      return !eventHandlerUse
+    }
+    const collectMatchHooks = node => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && matchHooks.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
+        const declaration = node.parent
+        const statement = declaration?.parent?.parent
+        const owner = nearestFunction(node)
+        if (node.questionDotToken || node.typeArguments?.length || node.arguments.length !== 1 || !ts.isStringLiteral(node.arguments[0]) || !ts.isVariableDeclaration(declaration) || declaration.initializer !== node || !ts.isIdentifier(declaration.name) || !isLocalConst(declaration) || !owner || !componentFunction(owner) || statement?.parent !== owner.body) {
+          throw sourceNodeError(node, sourceFile, 'React Router useMatch must directly initialize one top-level const from one static root-relative pattern such as useMatch("/")')
+        }
+        const pattern = node.arguments[0].text
+        if (!pattern.startsWith("/") || pattern.startsWith("//") || pattern !== "/" && pattern.endsWith("/") || /[:*?#\\\0]/.test(pattern)) throw sourceNodeError(node.arguments[0], sourceFile, 'React Router useMatch only supports an exact static root-relative pattern without params, wildcards, query, hash, or a trailing slash')
+        matchCalls.set(node, pattern)
+      }
+      ts.forEachChild(node, collectMatchHooks)
+    }
+    collectMatchHooks(sourceFile)
 
     let searchHelper = "__kUseSearchParam"
     while (sourceFile.text.includes(searchHelper)) searchHelper += "_"
@@ -36,8 +77,18 @@ export function createRouterPass({ withBase }) {
     while (sourceFile.text.includes(searchWriterHelper)) searchWriterHelper += "_"
     const searchDeclarations = new Set()
     const searchReads = new Map()
+    const searchFallbackValues = new Map()
+    const composedSearchDeclarations = new Map()
+    const composedSearchCalls = new Map()
     const searchWrites = new Map()
     const searchObjects = []
+    let composedSearchIndex = 0
+    const composedSearchName = () => {
+      let name
+      do name = `__kRouterSearchParam${composedSearchIndex++ || ""}`
+      while (sourceFile.text.includes(name) || [...composedSearchCalls.values()].includes(name))
+      return name
+    }
     const collectSearchHooks = node => {
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && searchHooks.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) {
         const declaration = node.parent
@@ -71,15 +122,38 @@ export function createRouterPass({ withBase }) {
           if (entry.setter && ts.isCallExpression(node.parent) && node.parent.arguments.includes(node) && ts.isIdentifier(node.parent.expression) && node.parent.expression.text === entry.setter) return
           const property = node.parent
           const call = property?.parent
-          const declaration = call?.parent
+          const directDeclaration = call?.parent
+          const numberCall = directDeclaration && ts.isCallExpression(directDeclaration) && ts.isIdentifier(directDeclaration.expression) && directDeclaration.expression.text === "Number" && !isShadowedIdentifier(directDeclaration.expression, sourceFile) && directDeclaration.arguments.length === 1 && directDeclaration.arguments[0] === call && !directDeclaration.questionDotToken && !directDeclaration.typeArguments?.length ? directDeclaration : undefined
+          const binary = numberCall?.parent ?? directDeclaration
+          const numericRight = binary?.right
+          const numericValue = numericRight && ts.isNumericLiteral(numericRight) ? Number(numericRight.text) : numericRight && ts.isPrefixUnaryExpression(numericRight) && [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(numericRight.operator) && ts.isNumericLiteral(numericRight.operand) ? Number(numericRight.getText(sourceFile)) : NaN
+          const numericFallback = numberCall && ts.isBinaryExpression(binary) && binary.left === numberCall && binary.operatorToken.kind === ts.SyntaxKind.BarBarToken && Number.isFinite(numericValue) ? binary : undefined
+          const importedValue = !numberCall && ts.isBinaryExpression(binary) && binary.left === call && binary.operatorToken.kind === ts.SyntaxKind.BarBarToken ? binary.right : undefined
+          const importedCollection = importedValue && ts.isElementAccessExpression(importedValue) && !importedValue.questionDotToken && ts.isIdentifier(importedValue.expression) && ts.isNumericLiteral(importedValue.argumentExpression) ? importedCollections.get(importedValue.expression.text) : undefined
+          const importedIndex = importedValue && ts.isElementAccessExpression(importedValue) && ts.isNumericLiteral(importedValue.argumentExpression) ? Number(importedValue.argumentExpression.text) : undefined
+          const importedElement = importedCollection && Number.isSafeInteger(importedIndex) ? importedCollection.elements[importedIndex] : undefined
+          const importedString = importedElement && unwrapExpression(importedElement)
+          const importedFallback = importedString && (ts.isStringLiteral(importedString) || ts.isNoSubstitutionTemplateLiteral(importedString)) ? binary : undefined
+          const fallback = numericFallback ?? importedFallback
+          let composedInitializer = fallback
+          while (composedInitializer?.parent && (ts.isParenthesizedExpression(composedInitializer.parent) || ts.isAsExpression(composedInitializer.parent) || ts.isTypeAssertionExpression(composedInitializer.parent) || ts.isSatisfiesExpression(composedInitializer.parent) || ts.isNonNullExpression(composedInitializer.parent)) && composedInitializer.parent.expression === composedInitializer) composedInitializer = composedInitializer.parent
+          const composedDeclaration = composedInitializer?.parent
+          const declaration = directDeclaration && ts.isVariableDeclaration(directDeclaration) ? directDeclaration : composedDeclaration && ts.isVariableDeclaration(composedDeclaration) ? composedDeclaration : undefined
           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")
+          if (!declaration || declaration.initializer !== call && declaration.initializer !== composedInitializer || !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, appear as Number(params.get("name")) || finiteNumber, or use params.get("name") || importedArray[staticIndex]')
           }
+          if (fallback && declaration.parent.declarations.length !== 1) throw sourceNodeError(declaration, sourceFile, "React Router composed search parameter reads require their own top-level const statement")
           searchReads.set(call, call.arguments[0])
+          if (importedValue && importedFallback) searchFallbackValues.set(importedValue, importedString.text)
+          if (fallback) {
+            const name = composedSearchName()
+            composedSearchDeclarations.set(declaration, { call, name })
+            composedSearchCalls.set(call, name)
+          }
           return
         }
         ts.forEachChild(node, collectReads)
@@ -185,6 +259,17 @@ export function createRouterPass({ withBase }) {
     }
     const importedLink = tag => ts.isIdentifier(tag) && links.has(tag.text) && !isShadowedIdentifier(tag, sourceFile)
     const visitor = node => {
+      if (searchFallbackValues.has(node)) return factory.createStringLiteral(searchFallbackValues.get(node))
+      if (ts.isVariableStatement(node) && node.declarationList.declarations.length === 1) {
+        const declaration = node.declarationList.declarations[0]
+        const composed = composedSearchDeclarations.get(declaration)
+        if (composed) {
+          const raw = factory.createVariableStatement(undefined, factory.createVariableDeclarationList([
+            factory.createVariableDeclaration(composed.name, undefined, undefined, factory.createCallExpression(factory.createIdentifier(searchHelper), undefined, [searchReads.get(composed.call)]))
+          ], ts.NodeFlags.Const))
+          return [raw, ts.visitEachChild(node, visitor, context)]
+        }
+      }
       if (ts.isVariableStatement(node) && node.declarationList.declarations.some(declaration => searchDeclarations.has(declaration) || navigateDeclarations.has(declaration))) {
         const declarations = node.declarationList.declarations.flatMap(declaration => {
           if (navigateDeclarations.has(declaration)) return []
@@ -196,7 +281,7 @@ export function createRouterPass({ withBase }) {
         if (!declarations.length) return undefined
         return factory.updateVariableStatement(node, node.modifiers, factory.updateVariableDeclarationList(node.declarationList, declarations))
       }
-      if (ts.isCallExpression(node) && searchReads.has(node)) return factory.createCallExpression(factory.createIdentifier(searchHelper), undefined, [searchReads.get(node)])
+      if (ts.isCallExpression(node) && searchReads.has(node)) return composedSearchCalls.has(node) ? factory.createIdentifier(composedSearchCalls.get(node)) : factory.createCallExpression(factory.createIdentifier(searchHelper), undefined, [searchReads.get(node)])
       if (ts.isCallExpression(node) && searchWrites.has(node)) {
         const { updater, replace } = searchWrites.get(node)
         return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("globalThis"), "__kSetSearchParams"), undefined, [ts.visitNode(updater, visitor), replace ? factory.createTrue() : factory.createFalse()])
@@ -205,6 +290,7 @@ export function createRouterPass({ withBase }) {
         const { method, destination } = navigateCalls.get(node)
         return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createPropertyAccessExpression(factory.createIdentifier("globalThis"), "location"), method), undefined, [factory.createStringLiteral(destination)])
       }
+      if (ts.isCallExpression(node) && matchCalls.has(node)) return factory.createCallExpression(factory.createIdentifier(matchHelper), undefined, [factory.createStringLiteral(matchCalls.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"))
@@ -217,6 +303,7 @@ export function createRouterPass({ withBase }) {
       }
       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) && matchHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useMatch imports may only initialize the supported top-level const binding")
       if (ts.isIdentifier(node) && searchHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useSearchParams imports may only initialize the supported top-level tuple binding")
       if (ts.isIdentifier(node) && navigateHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useNavigate imports may only initialize the supported top-level navigate binding")
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react-router-dom") {
@@ -224,16 +311,17 @@ export function createRouterPass({ withBase }) {
         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 || !["Link", "useParams", "useSearchParams", "useNavigate"].includes((entry.propertyName ?? entry.name).text))
+        const elements = bindings.elements.filter(entry => entry.isTypeOnly || !["Link", "useParams", "useMatch", "useSearchParams", "useNavigate"].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)
     }
     const normalized = ts.visitNode(sourceFile, visitor)
-    if (!params.size && !searchHooks.size) return normalized
+    if (!params.size && !matchHooks.size && !searchHooks.size) return normalized
     const imports = [
       ...[...params].map(name => factory.createImportSpecifier(false, name === "useParams" ? undefined : factory.createIdentifier("useParams"), factory.createIdentifier(name))),
+      ...(matchHooks.size ? [factory.createImportSpecifier(false, matchHelper === "__kUseRouteMatch" ? undefined : factory.createIdentifier("__kUseRouteMatch"), factory.createIdentifier(matchHelper))] : []),
       ...(searchReads.size ? [factory.createImportSpecifier(false, factory.createIdentifier("useSearchParam"), factory.createIdentifier(searchHelper))] : []),
       ...(searchObjects.some(entry => entry.setter) ? [factory.createImportSpecifier(false, factory.createIdentifier("useSearchParamsWriter"), factory.createIdentifier(searchWriterHelper))] : [])
     ]

package/framework/compiler/source-compiler.mjs

@@ -315,12 +315,12 @@ function normalizeParameterizedDebounceHooks(sourceFile, factory, context) {
   return ts.visitNode(sourceFile, visitor)
 }
 
-function normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedStaticCollections, sourceFiles, sourceIndex }) {
+function normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedFallbackCollections, importedStaticCollections, sourceFiles, sourceIndex }) {
   const factory = context.factory
   let customHookTimerStates = new Set()
   sourceFile = applyNormalizationPasses(sourceFile, [
     ...(importedStaticCollections ? [source => normalizeImportedStaticCollections(source, importedStaticCollections, factory, context)] : []),
-    source => normalizeReactRouterSyntax(source, factory, context, base),
+    source => normalizeReactRouterSyntax(source, factory, context, base, importedFallbackCollections),
     source => normalizeClsxSyntax(source, factory, context),
     source => normalizeMediaQueryExternalStores(source, factory, context),
     source => normalizeReactMigrationSyntax(source, factory, context, importedCollections ?? importedSerializableCollectionNames(source, file, sourceFiles, sourceIndex)),
@@ -354,7 +354,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const hasLinkElements = /<link/i.test(sourceFile.text)
     const importedStaticCollections = importedSerializableCollections(sourceFile, file, sourceFiles, sourceIndex, true)
     const importedCollections = new Set(importedStaticCollections.keys())
-    const normalized = normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedStaticCollections, sourceFiles, sourceIndex })
+    const importedFallbackCollections = importedSerializableCollections(sourceFile, file, sourceFiles, sourceIndex)
+    const normalized = normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedFallbackCollections, importedStaticCollections, sourceFiles, sourceIndex })
     sourceFile = normalized.sourceFile
     const { customHookTimerStates } = normalized
     const bindingIndex = createBindingIndex(sourceFile)
@@ -398,9 +399,10 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     })
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
     const packageBindings = packageImportBindings(sourceFile)
-    for (const [name] of packageBindings) {
+    for (const [name, binding] of packageBindings) {
       const references = referenceIdentifiers(sourceFile, name)
       const invalid = references.find(reference => !insideJsxEventHandler(reference, sourceFile) && !insideOwnedEffectCallback(reference, sourceFile))
+      if (invalid && binding.target === "react-i18next" && binding.imported === "useTranslation") throw sourceNodeError(invalid, sourceFile, "React i18next useTranslation() depends on runtime locale resources; migrate build-known locales through getStaticPaths() and props, or browser-only locale reads through an owned effect")
       if (invalid) throw sourceNodeError(invalid, sourceFile, `Package import ${JSON.stringify(name)} may only be referenced directly inside JSX event handlers or owned effect setup/cleanup callbacks`)
     }
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
@@ -661,6 +663,15 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const collect = node => {
       if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)) {
         const callName = ts.isIdentifier(node.initializer.expression) ? node.initializer.expression.text : ""
+        if (ts.isIdentifier(node.name) && /^__kRouterSearchParam\d*$/.test(node.name.text) && /^__kUseSearchParam_*$/.test(callName)) {
+          const owner = nearestFunction(node)
+          if (!owner || !isLocalConst(node) || node.parent?.parent?.parent !== owner.body) throw sourceNodeError(node, sourceFile, "Compiler-owned search parameter signals must be top-level component const declarations")
+          const setters = settersByFunction.get(owner) ?? new Map()
+          const setter = `__kSet${node.name.text}`
+          setters.set(setter, node.name.text)
+          registerState(owner, node.name.text, setter, "search-param", node)
+          settersByFunction.set(owner, setters)
+        }
         const customHookImport = callName && /^use[A-Z]/.test(callName) && importBindings.has(callName) && importBindings.get(callName).kind !== "namespace" && !resolvedSharedState(importBindings.get(callName))
         const debounce = customHookImport && ts.isIdentifier(node.name) ? resolveParameterizedDebounceHook(importBindings.get(callName)) : undefined
         if (debounce) {
@@ -1110,6 +1121,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       const declarations = jsxLocalDeclarations.get(owner)
       if (!declarations) return expression
       const substitutions = new Map()
+      const stateNames = new Set(setters.values())
       const resolving = []
       const resolve = (name, reference) => {
         if (substitutions.has(name)) return
@@ -1122,7 +1134,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         resolving.push(name)
         const initializer = entries[0].initializer
         const visit = node => {
-          if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isShadowedByParameter(node, initializer) && declarations.has(node.text)) resolve(node.text, node)
+          if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isShadowedByParameter(node, initializer) && declarations.has(node.text) && !stateNames.has(node.text)) resolve(node.text, node)
           ts.forEachChild(node, visit)
         }
         visit(initializer)
@@ -1130,7 +1142,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         resolving.pop()
       }
       const visit = node => {
-        if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression) && declarations.has(node.text)) resolve(node.text, node)
+        if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isShadowedByParameter(node, expression) && declarations.has(node.text) && !stateNames.has(node.text)) resolve(node.text, node)
         ts.forEachChild(node, visit)
       }
       visit(expression)
@@ -1632,7 +1644,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           const entries = jsxLocalDeclarations.get(nearestFunction(node))?.get(value.expression.text)
           if (!entries?.length) return undefined
           const initializer = entries.length === 1 ? unwrapExpression(entries[0].initializer) : undefined
-          if (!initializer || !ts.isCallExpression(initializer) || !ts.isIdentifier(initializer.expression) || !importBindings.has(initializer.expression.text)) return undefined
+          if (!initializer || !ts.isCallExpression(initializer) || !ts.isIdentifier(initializer.expression) || !importBindings.has(initializer.expression.text) || resolvedSharedState(importBindings.get(initializer.expression.text))) return undefined
           if (entries[0].node.parent?.parent?.parent !== nearestFunction(entries[0].node)?.body) fail(value.expression, `Calculated collection result "${value.expression.text}" must be one top-level immutable local`)
           validateImportedCalculation(initializer, value.name.text)
           const expanded = resolveReactiveJsxExpression(value, nearestFunction(node), setters)
@@ -1974,11 +1986,13 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         if (callback.parameters.length) effectFail(callback, "useEffect() callback cannot declare parameters")
         if (!ts.isArrayLiteralExpression(dependencies)) effectFail(dependencies, "useEffect() dependencies must be a literal array")
         const setters = settersForNode(node, settersByFunction)
+        const effectStateNames = new Set(setters.values())
         const resolveCalculation = dependency => {
           if (specializedEffect) return undefined
           const value = unwrapExpression(dependency)
           const result = ts.isIdentifier(value) ? value : ts.isPropertyAccessExpression(value) || ts.isElementAccessExpression(value) ? unwrapExpression(value.expression) : undefined
           if (!result || !ts.isIdentifier(result)) return undefined
+          if (effectStateNames.has(result.text)) return undefined
           const entries = jsxLocalDeclarations.get(effectOwner)?.get(result.text)
           const initializer = entries?.length === 1 && entries[0].node.parent?.parent?.parent === effectOwner?.body ? unwrapExpression(entries[0].initializer) : undefined
           if (!initializer || !ts.isCallExpression(initializer) || !ts.isIdentifier(initializer.expression) || !importBindings.has(initializer.expression.text)) return undefined

package/framework/core.mjs

@@ -123,6 +123,19 @@ export function useParams() {
   return renderContext.params
 }
 
+export function __kUseRouteMatch(pattern) {
+  if (!renderContext) throw new Error("React Router useMatch can only run while rendering a Kudzu component")
+  if (renderContext.renderScope === "layout") throw new Error("React Router useMatch is only supported in route scope")
+  if (renderContext.runtimeParamNames?.length) throw new Error("React Router useMatch requires a build-known route and cannot run on a runtimeParams bracket page")
+  const pathname = renderContext.applicationRoute
+  let decodedPathname = pathname
+  try {
+    decodedPathname = pathname.split("/").map(segment => decodeURIComponent(segment).replaceAll("/", "%2F")).join("/")
+  } catch {}
+  const matches = new RegExp(`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "i").test(decodedPathname)
+  return matches ? { params: {}, pathname: decodedPathname, pathnameBase: decodedPathname, pattern: { path: pattern, caseSensitive: false, end: true } } : null
+}
+
 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")
@@ -471,7 +484,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: [], captureCache: new WeakMap(), sharedStates: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", applicationRoute: metadata.applicationRoute, 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: [], captureCache: new WeakMap(), sharedStates: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }

package/package.json

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