@kudzujs/core 0.7.24 → 0.7.25

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.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).
+**Latest release: 0.7.25 - Router-shaped native navigation.** Supported React Router `useNavigate()` calls now lower to base-aware native document navigation through `location.assign()` or `location.replace()`, with no router runtime. Read the [release notes](./RELEASES.md#0725---router-shaped-native-navigation) or open the [release page](https://kudzujs.cloud/releases/0.7.25).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)
@@ -85,6 +85,7 @@ ordinary React-shaped TSX
 - 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.
+- A named or aliased React Router `useNavigate()` top-level binding lowers direct nested-callback calls with safe static root-relative destinations to native `location.assign()` or `location.replace()` navigation.
 - 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,31 @@
 # Kudzu Releases
 
+## 0.7.25 - Router-shaped native navigation
+
+Kudzu 0.7.25 accepts a narrow React Router `useNavigate()` source shape and lowers safe static destinations to native full-document navigation without shipping React Router or adding an SPA runtime.
+
+### New in 0.7.25
+
+- A named or aliased `useNavigate` import may initialize one top-level `const` identifier in a component.
+- Direct calls from nested browser callbacks with one safe static root-relative destination lower to `globalThis.location.assign()`.
+- Exactly `{ replace: true }` lowers to `globalThis.location.replace()`.
+- Configured `base` is applied while query strings and fragments are preserved.
+- The React Router import and navigate binding are erased from emitted component code.
+- Dynamic or relative destinations, render-time calls, passed aliases, optional calls, and other navigation options fail with source diagnostics.
+- Native document navigation remains deliberate even when enhanced navigation is configured.
+- Unaffected destination routes remain complete static documents with zero JavaScript.
+- The complete suite passes 117/117 tests with Chrome coverage for base-aware full-document navigation.
+
+### Boundary
+
+The supported migration shape is one top-level `const navigate = useNavigate()` and direct calls from nested browser callbacks. Destinations must be safe static root-relative strings. Only the absent options argument and exactly `{ replace: true }` are supported; dynamic values, relative paths, deltas, state, relative routing, scroll options, aliases, and render-time calls remain unsupported. No SPA router is included.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.25
+```
+
 ## 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.

package/framework/README.md

@@ -10,6 +10,8 @@ A named or aliased React Router `useParams` import may also be called directly w
 
 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.
 
+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.
+
 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

@@ -1788,15 +1788,16 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
   const links = new Set()
   const params = new Set()
   const searchHooks = new Set()
+  const navigateHooks = 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 named Link, useParams, or useSearchParams imports")
+      if (clause.name) throw sourceNodeError(clause.name, sourceFile, "React Router default imports are not supported; use named Link, useParams, 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, or useSearchParams imports")
+      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")
       for (const entry of bindings.elements) {
         if (entry.isTypeOnly) continue
         const imported = (entry.propertyName ?? entry.name).text
@@ -1804,11 +1805,12 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
         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`)
+        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`)
       }
     }
   }
-  if (!links.size && !params.size && !searchHooks.size) return sourceFile
+  if (!links.size && !params.size && !searchHooks.size && !navigateHooks.size) return sourceFile
 
   let searchHelper = "__kUseSearchParam"
   while (sourceFile.text.includes(searchHelper)) searchHelper += "_"
@@ -1831,7 +1833,7 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
     ts.forEachChild(node, collectSearchHooks)
   }
   collectSearchHooks(sourceFile)
-  const searchObjectShadowed = (node, entry) => {
+  const localBindingShadowed = (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
@@ -1843,7 +1845,7 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
   }
   for (const entry of searchObjects) {
     const collectReads = node => {
-      if (ts.isIdentifier(node) && node.text === entry.name && isReferenceIdentifier(node) && !searchObjectShadowed(node, entry)) {
+      if (ts.isIdentifier(node) && node.text === entry.name && isReferenceIdentifier(node) && !localBindingShadowed(node, entry)) {
         const property = node.parent
         const call = property?.parent
         const declaration = call?.parent
@@ -1862,6 +1864,55 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
     collectReads(entry.owner.body)
   }
 
+  const navigateDeclarations = new Set()
+  const navigateCalls = new Map()
+  const navigateFunctions = []
+  const collectNavigateHooks = node => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && navigateHooks.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.arguments.length || node.typeArguments?.length || !ts.isVariableDeclaration(declaration) || declaration.initializer !== node || !ts.isIdentifier(declaration.name) || !isLocalConst(declaration) || !owner || statement?.parent !== owner.body) {
+        throw sourceNodeError(node, sourceFile, "React Router useNavigate must initialize one top-level const identifier in a component")
+      }
+      const entry = { name: declaration.name.text, declaration, statement, owner }
+      navigateDeclarations.add(declaration)
+      navigateFunctions.push(entry)
+    }
+    ts.forEachChild(node, collectNavigateHooks)
+  }
+  collectNavigateHooks(sourceFile)
+  for (const entry of navigateFunctions) {
+    const collectCalls = node => {
+      if (ts.isIdentifier(node) && node.text === entry.name && isReferenceIdentifier(node) && !localBindingShadowed(node, entry)) {
+        const call = node.parent
+        if (!ts.isCallExpression(call) || call.expression !== node || call.questionDotToken || call.typeArguments?.length || nearestFunction(call) === entry.owner) {
+          throw sourceNodeError(node, sourceFile, "React Router navigate bindings may only be called directly from a nested browser callback")
+        }
+        if (call.arguments.length < 1 || call.arguments.length > 2 || !ts.isStringLiteral(call.arguments[0])) {
+          throw sourceNodeError(call, sourceFile, 'React Router useNavigate requires a static root-relative navigate("/path") destination')
+        }
+        const destination = call.arguments[0].text
+        const pathname = destination.match(/^[^?#]*/)[0]
+        let decoded
+        try { decoded = decodeURIComponent(pathname) } catch { throw sourceNodeError(call.arguments[0], sourceFile, 'React Router useNavigate requires a safe static root-relative navigate("/path") destination') }
+        if (!destination.startsWith("/") || destination.startsWith("//") || /%(?:2f|5c)/i.test(pathname) || /[\\\0]/.test(decoded) || decoded.split("/").includes("..") || [...decoded].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127 && character.charCodeAt(0) <= 159)) throw sourceNodeError(call.arguments[0], sourceFile, 'React Router useNavigate requires a safe static root-relative navigate("/path") destination')
+        let method = "assign"
+        if (call.arguments.length === 2) {
+          const options = unwrapExpression(call.arguments[1])
+          const property = ts.isObjectLiteralExpression(options) && options.properties.length === 1 ? options.properties[0] : undefined
+          const name = property && ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined
+          if (name !== "replace" || property.initializer.kind !== ts.SyntaxKind.TrueKeyword) throw sourceNodeError(call.arguments[1], sourceFile, 'React Router useNavigate only supports exactly { replace: true } as a second argument')
+          method = "replace"
+        }
+        navigateCalls.set(call, { method, destination: withBase(base, destination) })
+        return
+      }
+      ts.forEachChild(node, collectCalls)
+    }
+    collectCalls(entry.owner.body)
+  }
+
   const routerProps = new Set(["discover", "end", "prefetch", "preventScrollReset", "relative", "reloadDocument", "replace", "state", "viewTransition"])
   const attributes = attributesNode => {
     const output = []
@@ -1889,12 +1940,16 @@ 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 (ts.isVariableStatement(node) && node.declarationList.declarations.some(declaration => searchDeclarations.has(declaration) || navigateDeclarations.has(declaration))) {
+      const declarations = node.declarationList.declarations.filter(declaration => !searchDeclarations.has(declaration) && !navigateDeclarations.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.isCallExpression(node) && navigateCalls.has(node)) {
+      const { method, destination } = navigateCalls.get(node)
+      return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createPropertyAccessExpression(factory.createIdentifier("globalThis"), "location"), method), undefined, [factory.createStringLiteral(destination)])
+    }
     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"))
@@ -1908,12 +1963,13 @@ function normalizeReactRouterSyntax(sourceFile, factory, context, base) {
     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.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") {
       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 || !["Link", "useParams", "useSearchParams"].includes((entry.propertyName ?? entry.name).text))
+      const elements = bindings.elements.filter(entry => entry.isTypeOnly || !["Link", "useParams", "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)
     }

package/package.json

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