feat(composables): useSearchParams mutators take { replace } (#1825)

Every mutator committed through pushState, so the composable could express
"remove this param from the URL" but not "remove this param so it's gone"
— which is the reason the API gets reached for. Consuming a one-shot
value (an OAuth callback result, ?checkout=success, a flash token) leaves
the pre-delete URL, still carrying the param, as the previous history
entry: Back replays the callback and re-runs whatever consuming it
triggered.

set, delete and setAll now take an optional { replace?: boolean } that
switches the commit to replaceState. Default is unchanged, so nothing
that works today changes. Spelled to match navigate(), which already
takes { replace } — before this the two halves of the routing API
disagreed on whether replacing was expressible at all.

All three surfaces move together, because they have drifted before:
the client runtime (signals.ts), the module export
(composables/use-router.ts, including its own non-delegating
implementation), and the ambient declaration (stx.d.ts).

The guard is `!!(options && typeof options === 'object' && options.replace)`
in both implementations, deliberately, and NOT a plain truthy read of the
property. A truthy read asks whether the value HAS a replace property, and
every string carries String.prototype.replace — delete(key, 'push') would
have replaced, the exact opposite of what it reads as. Optional chaining
alone was worse: it diverged BETWEEN the two implementations on the empty
string, which short-circuits in one and reaches String.prototype.replace
in the other. Same call, two entry points, opposite history semantics.

Verified in Chrome against the rebuilt dist, arriving at /login?code=abc123
and consuming the param:

  default             Back -> ?code=abc123   (replayed)
  { replace: true }   Back -> (none)         (not replayed)
  'push'              Back -> ?code=abc123   (pushes, as it reads)
  true                Back -> ?code=abc123   (ignored; the contract is an
                                              options object)

Tests extend the existing parity suite, which already runs every case
against all three implementations: the fake history gained replaceState
so a test can tell "the URL changed" from "the URL changed AND the old one
is still reachable with Back", plus a truth table over the odd argument
shapes above. 67 pass; the replace-specific ones fail without this change.

Docs updated where they now teach the wrong thing: the agent guide's
canonical RIGHT example was the exact #1825 scenario and prescribed
setAll({ project: undefined }), which pushes AND writes the string
"undefined" rather than deleting; the PROHIBITED_DOM_PATTERNS row mapping
history.replaceState to useSearchParams silently converted a replace into
a push; API.md, api/router.md and api/composables-ref.md documented only
get/set/setAll with "(pushes history)" and no opt-out, and referred to a
type name, SearchParamsHandle, that exists nowhere in the code.

Full suite 10754 pass, 1 fail — pre-existing (crosswind-arbitrary-values),
confirmed identical before the change. A downstream app is green.

Author: glennmichael123

docs/API.md

@@ -5367,15 +5367,43 @@ const search = useSearchParams()
 
 // Read a param
 const page = search.get('page')  // '2'
+search.has('page')               // true
 
-// Set a single param (pushes to history)
+// Set a single param (pushes a history entry)
 search.set('page', '3')
 
 // Set multiple params at once
 search.setAll({ page: '1', sort: 'name', order: 'asc' })
+
+// Remove one
+search.delete('page')
 </script>
 ```
 
+#### Consuming a one-shot param
+
+Every mutator takes an optional `{ replace: true }` that swaps the `pushState`
+for a `replaceState`. Reach for it whenever the param is a **one-shot value** —
+an OAuth callback result, `?checkout=success`, a flash token:
+
+```html
+<script client>
+const search = useSearchParams()
+
+onMount(() => {
+  const code = search.get('code')
+  if (!code) return
+  exchangeForSession(code)
+  // Without { replace: true } the URL that still carries `code` stays in
+  // history, so pressing Back replays the callback and re-runs the exchange.
+  search.delete('code', { replace: true })
+})
+</script>
+```
+
+`{ replace }` is spelled the same way [`navigate()`](#navigateurl) spells it, and
+the default is unchanged: a mutation pushes unless you say otherwise.
+
 ---
 
 ## Event Listener Composable

docs/api/composables-ref.md

@@ -289,7 +289,7 @@ const route = useRoute()
 ### useSearchParams
 
 ```typescript
-useSearchParams(): SearchParamsHandle
+useSearchParams(): SearchParamsRef
 ```
 
 Reactive URL search parameters. Syncs with `popstate` and `stx:navigate` events.
@@ -307,14 +307,20 @@ search.setAll({ page: '1', sort: 'name' })
 </script>
 ```
 
-**SearchParamsHandle:**
+**SearchParamsRef:**
 
 | Property/Method | Type | Description |
 |-----------------|------|-------------|
 | `data` | `Signal<Record<string, string>>` | Reactive params signal |
 | `get(key)` | `(key: string) => string \| undefined` | Read a param |
-| `set(key, value)` | `(key: string, value: string) => void` | Set a param (pushes history) |
-| `setAll(obj)` | `(obj: Record<string, string>) => void` | Set multiple params |
+| `has(key)` | `(key: string) => boolean` | Whether the param is present |
+| `set(key, value, options?)` | `(key, value, options?: { replace?: boolean }) => void` | Set a param. Pushes a history entry unless `replace` |
+| `delete(key, options?)` | `(key, options?: { replace?: boolean }) => void` | Remove a param. Pushes unless `replace` |
+| `setAll(obj, options?)` | `(obj, options?: { replace?: boolean }) => void` | Set several params. Pushes unless `replace` |
+
+Consuming a **one-shot** param — an OAuth callback result, `?checkout=success`,
+a flash token — needs `{ replace: true }`. Under the default push, the URL still
+carrying the param stays in history, so Back replays the callback.
 
 ## DOM
 

docs/api/router.md

@@ -446,14 +446,26 @@ route.params    // {} (from stxRouter if available)
 
 ### useSearchParams()
 
-Reactive URL search parameters with get/set methods. Automatically syncs with `popstate` and `stx:navigate` events.
+Reactive URL search parameters. Automatically syncs with `popstate` and `stx:navigate` events.
 
 ```ts
 const search = useSearchParams()
 
 search.get('page')              // '2'
-search.set('page', '3')         // Updates URL and pushes history
+search.has('page')              // true
+search.set('page', '3')         // Updates the URL, pushes a history entry
 search.setAll({ page: '1', sort: 'name' })  // Set multiple params
+search.delete('page')           // Remove one
+```
+
+Every mutator takes an optional `{ replace: true }`, which replaces the current
+history entry instead of pushing a new one:
+
+```ts
+// Consuming a one-shot param — an OAuth callback, ?checkout=success, a flash
+// token. Without `replace` the URL still carrying `code` stays in history, so
+// Back replays the callback.
+search.delete('code', { replace: true })
 ```
 
 ## Next Steps

docs/guide/agent-guide.md

@@ -3941,7 +3941,7 @@ Today that exits 1 and prints `violating blocks: 20`. Gotcha: the line numbers i
 | `el.setAttribute(k, v)` | `:k="v"` | `signals.js:1784-1800` | `index.stx:137,144`, `register.stx:188` |
 | `addEventListener` / `on*=` attr | `@click` / `@change` / `@input`, or `useEventListener()` | `signals.js:1830-1840`, `signals.js:3645-3652` | `dashboard.stx:429`, `StartMenu.stx:52` |
 | `window.location.*`, `location.assign/replace/href=` | `navigate(url)` / `navigate(url, true)` | `signals.js:941-952` | 29 sites across 8 files |
-| `window.history.replaceState` | `useSearchParams().set/setAll` | `signals.js:1004-1016` | `dashboard.stx:593` |
+| `window.history.replaceState` | `useSearchParams().set/delete/setAll` **with `{ replace: true }`** — the default pushes | `signals.js:1004-1016` | `dashboard.stx:593` |
 | `setTimeout` / `setInterval` | `useTimeout()` / `useInterval()` | `signals.js:3271-3300`, `3229-3268` | `settings.stx:203,406,512`, `issue/[id].stx:354`, `AutofixPanel.stx:189` |
 | self-rescheduling poll | `useQuery(url, { refetchInterval })` or `useInterval` | `signals.js:1110-1113` | `AutofixPanel.stx:189` |
 | `document.cookie = …` | `useCookie(name, opts)` | `signals.js:3568-3599` | 21 sites across 8 files |
@@ -4198,17 +4198,25 @@ if (qs.get('project')) {
 }
 ```
 
-**RIGHT (c):** `useSearchParams()` owns history rewriting (`signals.js:1004-1016`) and resyncs its signal after every write:
+**RIGHT (c):** `useSearchParams()` owns history rewriting and resyncs its signal after every write:
 
 ```js
 const params = useSearchParams()
 const activeProject = useCookie('bughq_project', { maxAge: 31536000, sameSite: 'Lax' })
 if (params.get('project')) {
   activeProject.set(params.get('project'))
-  params.setAll({ project: undefined })   // rewrites the URL, then syncFromUrl()
+  // { replace: true } is load-bearing, not tidiness. This is a ONE-SHOT param:
+  // it has been consumed into the cookie, so it must not survive a Back press.
+  // The default is pushState, which leaves the URL still carrying ?project= as
+  // the previous history entry — Back would replay the consumption (#1825).
+  params.delete('project', { replace: true })
 }
 ```
 
+The mirror of the WRONG snippet above is exact: that code reached for
+`history.replaceState` precisely because replace is the correct semantic here,
+and `{ replace: true }` is how the composable expresses it.
+
 **External URLs are not an exception.** `resources/views/pricing.stx:26` does `location.assign(data.url)` to reach Stripe. Write `navigate(data.url, true)` — same document load, one declared API, one fewer strict violation.
 
 **CHECK:** `grep -rnE 'window\.location|window\.history|location\.(href\s*=|assign|replace)' resources/ --include='*.stx'` → must match only the sites declared under rule 8.11. Today: 29 `window.location`, 11 `location.replace`, 7 `location.assign`, 1 `location.href=`, 1 `window.history`.
@@ -4619,7 +4627,7 @@ grep -rn '<StxLink[^>]*\bprefetch\b' resources/   # must return nothing
 
 ### 9.7 MUST — programmatic navigation is `navigate()`, never `location.*` or `history.*`
 
-**RULE.** In any `<script>` block, use the auto-imported `navigate(url)`. Use `navigate(url, true)` when you genuinely need a document load. Use `goBack()` / `goForward()` for history. Use `useSearchParams().set()` to rewrite the query string. Never write `window.location`, `location.href =`, `location.assign()`, `location.replace()` or `history.replaceState()`.
+**RULE.** In any `<script>` block, use the auto-imported `navigate(url)`. Use `navigate(url, true)` when you genuinely need a document load. Use `goBack()` / `goForward()` for history. Use `useSearchParams().set()` to rewrite the query string, and pass `{ replace: true }` when the URL change must not become a Back destination — consuming a one-shot param such as an OAuth `?code=` needs it, or Back replays the callback (#1825). Never write `window.location`, `location.href =`, `location.assign()`, `location.replace()` or `history.replaceState()`.
 
 **WHY.** `navigate` is defined at `signals.js:940-951` and published as a global at `signals.js:4635` (also `window.stx.navigate`, `signals.js:4148`). It delegates to `window.stxRouter.navigate` when the router is live (`signals.js:946-947`) and falls back to `location.href` only when it is not — strictly safer than the hand-written form. `goBack`/`goForward`: `signals.js:953-954`. `useSearchParams()` owns history rewriting: `signals.js:1004-1024`.
 

packages/stx/src/composables/index.ts

@@ -375,7 +375,9 @@ export {
   goForward,
   useRoute,
   useSearchParams,
+  type NavigateOptions,
   type RouteInfo,
+  type SearchParamsCommitOptions,
   type SearchParamsRef,
 } from './use-router'
 

packages/stx/src/composables/use-router.ts

@@ -21,19 +21,43 @@ export interface RouteInfo {
   params: Record<string, string>
 }
 
+/**
+ * How a search-param mutation is written to session history.
+ *
+ * Spelled `{ replace }` to match `navigate()`, which already takes it — before
+ * this the two halves of the routing API disagreed on whether replacing was
+ * expressible at all.
+ */
+export interface SearchParamsCommitOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean
+}
+
 export interface SearchParamsRef {
   /** Reactive signal containing current search params */
   data: { (): Record<string, string>, set: (v: Record<string, string>) => void }
   /** Get a single param value. `undefined` when absent. */
   get: (key: string) => string | undefined
   /** Whether the param is present. */
   has: (key: string) => boolean
-  /** Set a single param and push to history */
-  set: (key: string, value: string) => void
-  /** Remove a param and push to history */
-  delete: (key: string) => void
-  /** Set multiple params and push to history */
-  setAll: (obj: Record<string, string>) => void
+  /**
+   * Set a single param. Pushes a history entry unless `replace` is passed.
+   *
+   * Pass `{ replace: true }` when the URL change should not be a place the user
+   * can go Back to — see `delete` for the case that makes this necessary.
+   */
+  set: (key: string, value: string, options?: SearchParamsCommitOptions) => void
+  /**
+   * Remove a param. Pushes a history entry unless `replace` is passed.
+   *
+   * CONSUMING a one-shot param — an OAuth callback result, `?checkout=success`,
+   * a flash token — needs `{ replace: true }`. With the default push, the URL
+   * that still carries the param becomes the previous history entry, so Back
+   * replays the callback and re-runs whatever consuming it triggered (#1825).
+   */
+  delete: (key: string, options?: SearchParamsCommitOptions) => void
+  /** Set multiple params. Pushes a history entry unless `replace` is passed. */
+  setAll: (obj: Record<string, string>, options?: SearchParamsCommitOptions) => void
 }
 
 export interface NavigateOptions {
@@ -178,8 +202,17 @@ export function useSearchParams(): SearchParamsRef {
   window.addEventListener('popstate', sync)
   window.addEventListener('stx:navigate', sync)
 
-  const commit = (url: URL) => {
-    window.history.pushState({}, '', url)
+  const commit = (url: URL, options?: SearchParamsCommitOptions) => {
+    // Deliberately the same test as the client runtime's commit
+    // (signals.ts) — `options?.replace` alone diverges from it on '',
+    // because optional chaining only short-circuits on null/undefined and
+    // String.prototype.replace is truthy. Same call, two entry points, opposite
+    // history semantics is exactly what this composable must not have.
+    const replace = !!(options && typeof options === 'object' && options.replace)
+    if (replace)
+      window.history.replaceState({}, '', url)
+    else
+      window.history.pushState({}, '', url)
     sync()
   }
   // Own-property reads only: the backing object would otherwise inherit
@@ -190,20 +223,20 @@ export function useSearchParams(): SearchParamsRef {
     data: data as any,
     get: key => (has(key) ? data()[key] : undefined),
     has,
-    set: (key, value) => {
+    set: (key, value, options) => {
       const url = new URL(window.location.href)
       url.searchParams.set(key, value)
-      commit(url)
+      commit(url, options)
     },
-    delete: (key) => {
+    delete: (key, options) => {
       const url = new URL(window.location.href)
       url.searchParams.delete(key)
-      commit(url)
+      commit(url, options)
     },
-    setAll: (obj) => {
+    setAll: (obj, options) => {
       const url = new URL(window.location.href)
       for (const [k, v] of Object.entries(obj)) url.searchParams.set(k, v)
-      commit(url)
+      commit(url, options)
     },
   }
 }

packages/stx/src/signals.ts

@@ -1125,31 +1125,58 @@ else if (immediate) {
       var current = params();
       return Object.prototype.hasOwnProperty.call(current, key);
     };
-    var commit = function(url) {
-      window.history.pushState({}, '', url);
+    // pushState by default; replaceState when the caller asks for it (#1825).
+    //
+    // The canonical reason to delete a param is to CONSUME a one-shot value —
+    // an OAuth callback result, ?checkout=success, a flash token — and the
+    // point of consuming it is that it must not survive a Back press. Under
+    // pushState the pre-delete URL, the one still carrying the param, becomes
+    // the previous entry, so Back replays the callback and whatever consuming
+    // it triggered runs again.
+    //
+    // Default stays pushState so nothing that works today changes, and the
+    // option is spelled { replace } to match navigate(), which already takes it.
+    var commit = function(url, options) {
+      // A plain truthy read of the replace property looks equivalent and is
+      // not: it asks whether the value HAS a replace property, and every string
+      // has String.prototype.replace — so delete(key, 'push') would have
+      // replaced, the exact opposite of what it reads as. Requiring an object
+      // also keeps this identical to the module implementation in
+      // composables/use-router.ts; with optional chaining alone the two
+      // disagreed on the empty string, which short-circuits in one and hits
+      // String.prototype.replace in the other.
+      //
+      // NB: no backticks anywhere in this block. This runtime is assembled as a
+      // template literal, so a backtick in a COMMENT ends the string and the
+      // rest of the runtime is parsed as code.
+      var replace = !!(options && typeof options === 'object' && options.replace);
+      if (replace)
+        window.history.replaceState({}, '', url);
+      else
+        window.history.pushState({}, '', url);
       syncFromUrl();
     };
     return {
       data: params,
       get: function(key) { return own(key) ? params()[key] : undefined; },
       has: own,
-      set: function(key, value) {
+      set: function(key, value, options) {
         var url = new URL(window.location.href);
         url.searchParams.set(key, value);
-        commit(url);
+        commit(url, options);
       },
       // delete and has were DECLARED but absent, so the compiler endorsed calls
       // that threw in the browser; setAll and data were present but undeclared
       // (#1806). Deleting writes history the same way set does, for consistency.
-      'delete': function(key) {
+      'delete': function(key, options) {
         var url = new URL(window.location.href);
         url.searchParams['delete'](key);
-        commit(url);
+        commit(url, options);
       },
-      setAll: function(obj) {
+      setAll: function(obj, options) {
         var url = new URL(window.location.href);
         Object.keys(obj).forEach(function(k) { url.searchParams.set(k, obj[k]); });
-        commit(url);
+        commit(url, options);
       }
     };
   }

packages/stx/stx.d.ts

@@ -134,6 +134,12 @@ declare function useRoute(): {
   hash: string
 }
 declare function setRouteParams(_params: Record<string, string>): void
+/** How a search-param mutation is written to session history (#1825). */
+interface StxSearchParamsCommitOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean
+}
+
 /**
  * Reactive access to the URL query string.
  *
@@ -148,9 +154,19 @@ declare function useSearchParams(): {
   data: StxSignal<Record<string, string>>
   get: (_key: string) => string | undefined
   has: (_key: string) => boolean
-  set: (_key: string, _value: string) => void
-  delete: (_key: string) => void
-  setAll: (_values: Record<string, string>) => void
+  /** Set a param. Pushes a history entry unless `{ replace: true }` is passed. */
+  set: (_key: string, _value: string, _options?: StxSearchParamsCommitOptions) => void
+  /**
+   * Remove a param. Pushes a history entry unless `{ replace: true }` is passed.
+   *
+   * CONSUMING a one-shot param — an OAuth callback result, `?checkout=success`,
+   * a flash token — needs `{ replace: true }`. Under the default push, the URL
+   * that still carries the param becomes the previous history entry, so Back
+   * replays the callback and re-runs whatever consuming it triggered (#1825).
+   */
+  delete: (_key: string, _options?: StxSearchParamsCommitOptions) => void
+  /** Set several params. Pushes a history entry unless `{ replace: true }` is passed. */
+  setAll: (_values: Record<string, string>, _options?: StxSearchParamsCommitOptions) => void
 }
 
 // ============================================================================