@barefootjs/client 0.15.2 → 0.17.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-export { createSignal, createEffect, createDisposableEffect, createMemo, createRoot, onCleanup, onMount, untrack, batch, setProfilerSink, beginTurn, endTurn, __bfReportOutput, searchParams, __bfSetServerEnvReader, type Reactive, type Signal, type Memo, type CleanupFn, type EffectFn, type ProfilerEventSink, type SubscriberKind, } from '@barefootjs/client/reactive';
+export { createSignal, createEffect, createDisposableEffect, createMemo, createRoot, onCleanup, onMount, untrack, batch, setProfilerSink, beginTurn, endTurn, __bfReportOutput, createSearchParams, type SearchParamsInit, __bfSetServerEnvReader, type Reactive, type Signal, type Memo, type CleanupFn, type EffectFn, type ProfilerEventSink, type SubscriberKind, } from '@barefootjs/client/reactive';
 export { createRecordingSink, type ProfilerEvent, type ProfilerEventType, type RecordingSink, } from './profiler-events.ts';
 export { splitProps } from './split-props.ts';
 export { __slot, type SlotMarker } from './slot.ts';
 export { forwardProps } from './forward-props.ts';
 export { unwrap } from './unwrap.ts';
+export { queryHref, type QueryParams, type QueryParamValue } from './query-href.ts';
 export { createContext, type Context } from './context.ts';
 export { useContext, provideContext, createPortal, isSSRPortal, findSiblingSlot, cleanupPortalPlaceholder, type Portal, type PortalChildren, type PortalOptions, type Renderable, } from './shims.ts';
 export { Async, Region, type AsyncProps, type RegionProps, } from './builtins.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACtB,UAAU,EACV,UAAU,EACV,SAAS,EACT,OAAO,EACP,OAAO,EACP,KAAK,EACL,eAAe,EACf,SAAS,EACT,OAAO,EACP,gBAAgB,EAKhB,YAAY,EACZ,sBAAsB,EACtB,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,EACL,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAA;AAKnB,OAAO,EACL,KAAK,EACL,MAAM,EACN,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACtB,UAAU,EACV,UAAU,EACV,SAAS,EACT,OAAO,EACP,OAAO,EACP,KAAK,EACL,eAAe,EACf,SAAS,EACT,OAAO,EACP,gBAAgB,EAMhB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEnF,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,EACL,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAA;AAKnB,OAAO,EACL,KAAK,EACL,MAAM,EACN,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   beginTurn,
   endTurn,
   __bfReportOutput,
-  searchParams,
+  createSearchParams,
   __bfSetServerEnvReader
 } from "@barefootjs/client/reactive";
 
@@ -146,6 +146,21 @@ function forwardProps(source, overrides, excludeKeys) {
 function unwrap(prop) {
   return typeof prop === "function" ? prop() : prop;
 }
+// src/query-href.ts
+function queryHref(base, params) {
+  const u = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const member of value)
+        if (member)
+          u.append(key, member);
+    } else if (value) {
+      u.set(key, value);
+    }
+  }
+  const qs = u.toString();
+  return qs ? `${base}?${qs}` : base;
+}
 // src/context.ts
 function createContext(defaultValue) {
   return {
@@ -194,7 +209,7 @@ export {
   untrack,
   splitProps,
   setProfilerSink,
-  searchParams,
+  queryHref,
   provideContext,
   onMount,
   onCleanup,
@@ -203,6 +218,7 @@ export {
   findSiblingSlot,
   endTurn,
   createSignal,
+  createSearchParams,
   createRoot,
   createRecordingSink,
   createPortal,

package/dist/query-href.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `queryHref` — build a URL from a base path plus query params, omitting falsy
+ * values. The functional counterpart to `searchParams()` (the reactive *reader*):
+ * instead of imperatively mutating a `URLSearchParams`, pass a params object.
+ *
+ * ```tsx
+ * const href = queryHref(base, {
+ *   sort: sort !== 'date' ? sort : undefined, // conditional include via the value
+ *   tag,                                        // included only when truthy
+ * })
+ * ```
+ *
+ * Each entry is included iff its value is a **non-empty string** — `''` /
+ * `undefined` / `null` are omitted — so a conditional include folds into the
+ * value as `cond ? value : undefined`. Returns the bare `base` when no params
+ * survive. Values are encoded with `URLSearchParams` (form-encoding, spaces →
+ * `+`).
+ *
+ * A value may also be a **`string[]`**, which appends one entry per non-empty
+ * member (`{ tag: ['a', 'b'] }` → `?tag=a&tag=b`), i.e. `URLSearchParams.append`
+ * rather than `set`. Empty / falsy members are skipped (same truthy-omit as a
+ * scalar), so an empty array — or one whose members are all empty — contributes
+ * nothing.
+ *
+ * Values are **strings** (`QueryParamValue`). Number / boolean aren't accepted:
+ * JS truthiness would omit `0` / `false`, which the SSR adapters' string guard
+ * can't model without per-value type info — so keeping values string-only
+ * guarantees the server-rendered URL matches this client output byte-for-byte.
+ * Stringify other types at the call site (`String(n)`), choosing the omit rule
+ * explicitly (`n > 0 ? String(n) : undefined`).
+ *
+ * This is a pure function with no reactivity. The SSR adapters lower a
+ * `queryHref(base, { … })` call to their query helper (go-template: `bf_query`),
+ * which is why the params object must be a plain object literal at the call site.
+ */
+export type QueryParamValue = string | string[] | null | undefined;
+export type QueryParams = Record<string, QueryParamValue>;
+export declare function queryHref(base: string, params: QueryParams): string;
+//# sourceMappingURL=query-href.d.ts.map

package/dist/query-href.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-href.d.ts","sourceRoot":"","sources":["../src/query-href.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAAA;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;AAEzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAWnE"}

package/dist/reactive.d.ts

@@ -235,23 +235,12 @@ export declare function createMemo<T>(fn: () => T, __bfId?: string): Memo<T>;
  * resolves per-request.
  */
 export declare function __bfSetServerEnvReader(reader: ((key: string) => string | undefined) | null): void;
-/**
- * Reactive read of the current query string as `URLSearchParams`.
- *
- * ```tsx
- * const sort = createMemo(() => searchParams().get('sort') ?? 'recent')
- * ```
- *
- * A same-route, query-only navigation (`/list?sort=price`) driven by
- * `@barefootjs/router` updates this signal and the URL **without a swap or
- * re-hydration**. On the server it reflects the current request's query.
- *
- * Reactivity is **router-driven**: the signal is seeded once on first read and
- * thereafter updated only through the `window.__bf_pushSearch` seam, which
- * `startRouter()` drives (including on `popstate`). Without the router running
- * — or after a non-router `history` change — the value is read-once; the seam
- * name is shared with `@barefootjs/router` via `BF_SEAM_PUSH_SEARCH`, so the
- * installer (here) and the pusher agree by construction.
- */
-export declare const searchParams: Reactive<() => URLSearchParams>;
+/** Accepted inputs for `setSearchParams` — a raw query string (with or without
+ *  a leading `?`), a `URLSearchParams`, or a plain record (array = multi-value,
+ *  form-encoded like the client `queryHref`, cf. #2048). */
+export type SearchParamsInit = string | URLSearchParams | Record<string, string | readonly string[]>;
+export declare function createSearchParams(): readonly [
+    Reactive<() => URLSearchParams>,
+    (next: SearchParamsInit) => void
+];
 //# sourceMappingURL=reactive.d.ts.map

package/dist/reactive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"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"}

package/dist/reactive.js

@@ -1,5 +1,6 @@
 // ../shared/src/markers.ts
 var BF_SEAM_PUSH_SEARCH = "__bf_pushSearch";
+var BF_SEAM_NAV_SEARCH = "__bf_navSearch";
 // ../shared/src/dom-prop.ts
 var BOOLEAN_ATTRS = new Set([
   "checked",
@@ -374,7 +375,7 @@ function resolveServerEnv(key) {
   const seam = globalThis.__bf_serverEnvReader;
   return typeof seam === "function" ? seam(key) : undefined;
 }
-function createEnvSignal(key, readClient, parse, pushSeam) {
+function createEnvSignal(key, readClient, parse, pushSeam, navSeam) {
   let getRaw = null;
   function ensureClientSignal() {
     if (!getRaw) {
@@ -387,22 +388,59 @@ function createEnvSignal(key, readClient, parse, pushSeam) {
     }
     return getRaw();
   }
-  return () => {
+  const getter = () => {
     if (typeof window === "undefined") {
       return parse(resolveServerEnv(key) ?? "");
     }
     return parse(ensureClientSignal());
   };
+  const setter = (nextRaw) => {
+    if (typeof window === "undefined")
+      return;
+    const w = window;
+    const nav = w[navSeam];
+    if (typeof nav === "function") {
+      nav(nextRaw);
+      return;
+    }
+    window.location.search = nextRaw;
+  };
+  return [getter, setter];
+}
+function toSearchString(next) {
+  let usp;
+  if (next instanceof URLSearchParams) {
+    usp = next;
+  } else if (typeof next === "string") {
+    usp = new URLSearchParams(next.startsWith("?") ? next.slice(1) : next);
+  } else {
+    usp = new URLSearchParams;
+    for (const [k, v] of Object.entries(next)) {
+      if (Array.isArray(v)) {
+        for (const item of v)
+          usp.append(k, item);
+      } else {
+        usp.append(k, v);
+      }
+    }
+  }
+  const s = usp.toString();
+  return s ? `?${s}` : "";
+}
+var [searchParamsGetter, setSearchParamsRaw] = createEnvSignal("search", () => window.location.search, (raw) => new URLSearchParams(raw), BF_SEAM_PUSH_SEARCH, BF_SEAM_NAV_SEARCH);
+var setSearchParams = (next) => setSearchParamsRaw(toSearchString(next));
+var searchParamsTuple = [searchParamsGetter, setSearchParams];
+function createSearchParams() {
+  return searchParamsTuple;
 }
-var searchParams = createEnvSignal("search", () => window.location.search, (raw) => new URLSearchParams(raw), BF_SEAM_PUSH_SEARCH);
 export {
   untrack,
   setProfilerSink,
-  searchParams,
   onMount,
   onCleanup,
   endTurn,
   createSignal,
+  createSearchParams,
   createRoot,
   createMemo,
   createEffect,

package/dist/runtime/index.d.ts

@@ -1,9 +1,10 @@
-export { createSignal, createEffect, createDisposableEffect, createMemo, createRoot, onCleanup, onMount, untrack, batch, setProfilerSink, beginTurn, endTurn, __bfReportOutput, searchParams, __bfSetServerEnvReader, type Reactive, type Signal, type Memo, type CleanupFn, type EffectFn, type ProfilerEventSink, type SubscriberKind, } from '@barefootjs/client/reactive';
+export { createSignal, createEffect, createDisposableEffect, createMemo, createRoot, onCleanup, onMount, untrack, batch, setProfilerSink, beginTurn, endTurn, __bfReportOutput, createSearchParams, type SearchParamsInit, __bfSetServerEnvReader, type Reactive, type Signal, type Memo, type CleanupFn, type EffectFn, type ProfilerEventSink, type SubscriberKind, } from '@barefootjs/client/reactive';
 export { createRecordingSink, type ProfilerEvent, type ProfilerEventType, type RecordingSink, } from '../profiler-events.ts';
 export { splitProps } from '../split-props.ts';
 export { __slot, type SlotMarker } from '../slot.ts';
 export { forwardProps } from '../forward-props.ts';
 export { unwrap } from '../unwrap.ts';
+export { queryHref, type QueryParams, type QueryParamValue } from '../query-href.ts';
 export { createContext, useContext, provideContext, setCurrentScope, type Context, } from './context.ts';
 export { createPortal, isSSRPortal, findSiblingSlot, cleanupPortalPlaceholder, type Portal, type PortalOptions, type Renderable, type PortalChildren, } from './portal.ts';
 export { reconcileList, type RenderItemFn } from './list.ts';

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}

package/dist/runtime/index.js

@@ -13,7 +13,7 @@ import {
   beginTurn,
   endTurn,
   __bfReportOutput as __bfReportOutput2,
-  searchParams,
+  createSearchParams,
   __bfSetServerEnvReader
 } from "@barefootjs/client/reactive";
 
@@ -146,6 +146,21 @@ function forwardProps(source, overrides, excludeKeys) {
 function unwrap(prop) {
   return typeof prop === "function" ? prop() : prop;
 }
+// src/query-href.ts
+function queryHref(base, params) {
+  const u = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const member of value)
+        if (member)
+          u.append(key, member);
+    } else if (value) {
+      u.set(key, value);
+    }
+  }
+  const qs = u.toString();
+  return qs ? `${base}?${qs}` : base;
+}
 // ../shared/src/markers.ts
 var BF_SCOPE = "bf-s";
 var BF_SLOT = "bf";
@@ -2556,7 +2571,6 @@ export {
   setupStreaming,
   setProfilerSink,
   setCurrentScope,
-  searchParams,
   renderChild,
   render,
   rehydrateScope,
@@ -2565,6 +2579,7 @@ export {
   registerComponent,
   reconcileList,
   reconcileElements,
+  queryHref,
   qsaItem,
   qsaChildScopes,
   qsaChildScope,
@@ -2599,6 +2614,7 @@ export {
   disposeScope,
   cssEscape,
   createSignal2 as createSignal,
+  createSearchParams,
   createRoot3 as createRoot,
   createRecordingSink,
   createPortal,

package/dist/runtime/standalone.js

@@ -31,6 +31,7 @@ var BF_SEAM_HYDRATE = "__bf_hydrate";
 var BF_SEAM_HYDRATE_WITHIN = "__bf_hydrate_within";
 var BF_SEAM_DISPOSE_WITHIN = "__bf_dispose_within";
 var BF_SEAM_PUSH_SEARCH = "__bf_pushSearch";
+var BF_SEAM_NAV_SEARCH = "__bf_navSearch";
 // ../shared/src/dom-prop.ts
 var BOOLEAN_ATTRS = new Set([
   "checked",
@@ -473,7 +474,7 @@ function resolveServerEnv(key) {
   const seam = globalThis.__bf_serverEnvReader;
   return typeof seam === "function" ? seam(key) : undefined;
 }
-function createEnvSignal(key, readClient, parse, pushSeam) {
+function createEnvSignal(key, readClient, parse, pushSeam, navSeam) {
   let getRaw = null;
   function ensureClientSignal() {
     if (!getRaw) {
@@ -486,14 +487,51 @@ function createEnvSignal(key, readClient, parse, pushSeam) {
     }
     return getRaw();
   }
-  return () => {
+  const getter = () => {
     if (typeof window === "undefined") {
       return parse(resolveServerEnv(key) ?? "");
     }
     return parse(ensureClientSignal());
   };
+  const setter = (nextRaw) => {
+    if (typeof window === "undefined")
+      return;
+    const w = window;
+    const nav = w[navSeam];
+    if (typeof nav === "function") {
+      nav(nextRaw);
+      return;
+    }
+    window.location.search = nextRaw;
+  };
+  return [getter, setter];
+}
+function toSearchString(next) {
+  let usp;
+  if (next instanceof URLSearchParams) {
+    usp = next;
+  } else if (typeof next === "string") {
+    usp = new URLSearchParams(next.startsWith("?") ? next.slice(1) : next);
+  } else {
+    usp = new URLSearchParams;
+    for (const [k, v] of Object.entries(next)) {
+      if (Array.isArray(v)) {
+        for (const item of v)
+          usp.append(k, item);
+      } else {
+        usp.append(k, v);
+      }
+    }
+  }
+  const s = usp.toString();
+  return s ? `?${s}` : "";
+}
+var [searchParamsGetter, setSearchParamsRaw] = createEnvSignal("search", () => window.location.search, (raw) => new URLSearchParams(raw), BF_SEAM_PUSH_SEARCH, BF_SEAM_NAV_SEARCH);
+var setSearchParams = (next) => setSearchParamsRaw(toSearchString(next));
+var searchParamsTuple = [searchParamsGetter, setSearchParams];
+function createSearchParams() {
+  return searchParamsTuple;
 }
-var searchParams = createEnvSignal("search", () => window.location.search, (raw) => new URLSearchParams(raw), BF_SEAM_PUSH_SEARCH);
 // src/profiler-events.ts
 function createRecordingSink() {
   const events = [];
@@ -623,6 +661,21 @@ function forwardProps(source, overrides, excludeKeys) {
 function unwrap(prop) {
   return typeof prop === "function" ? prop() : prop;
 }
+// src/query-href.ts
+function queryHref(base, params) {
+  const u = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const member of value)
+        if (member)
+          u.append(key, member);
+    } else if (value) {
+      u.set(key, value);
+    }
+  }
+  const qs = u.toString();
+  return qs ? `${base}?${qs}` : base;
+}
 // src/context.ts
 function createContext(defaultValue) {
   return {
@@ -2841,7 +2894,6 @@ export {
   setupStreaming,
   setProfilerSink,
   setCurrentScope,
-  searchParams,
   renderChild,
   render,
   rehydrateScope,
@@ -2850,6 +2902,7 @@ export {
   registerComponent,
   reconcileList,
   reconcileElements,
+  queryHref,
   qsaItem,
   qsaChildScopes,
   qsaChildScope,
@@ -2884,6 +2937,7 @@ export {
   disposeScope,
   cssEscape,
   createSignal,
+  createSearchParams,
   createRoot,
   createRecordingSink,
   createPortal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/client",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "description": "BarefootJS client package: reactive primitives (SSR-safe) plus browser runtime under the `/runtime` subpath (compiler target)",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "directory": "packages/client"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.15.2"
+    "@barefootjs/shared": "0.17.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"

package/src/index.ts

@@ -16,10 +16,12 @@ export {
   endTurn,
   __bfReportOutput,
   // Request-scoped reactive environment signals (spec/router.md "The wedge").
-  // `searchParams` lives in the shared reactive module too, so this entry and
-  // the `/runtime` entry resolve to ONE signal instance. `createEnvSignal` stays
-  // internal; `__bfSetServerEnvReader` is the keyed adapter/host hook for SSR.
-  searchParams,
+  // `createSearchParams` lives in the shared reactive module too, so this entry
+  // and the `/runtime` entry resolve to ONE signal instance. `createEnvSignal`
+  // stays internal; `__bfSetServerEnvReader` is the keyed adapter/host hook for
+  // SSR.
+  createSearchParams,
+  type SearchParamsInit,
   __bfSetServerEnvReader,
   type Reactive,
   type Signal,
@@ -45,6 +47,8 @@ export { forwardProps } from './forward-props.ts'
 
 export { unwrap } from './unwrap.ts'
 
+export { queryHref, type QueryParams, type QueryParamValue } from './query-href.ts'
+
 export { createContext, type Context } from './context.ts'
 
 export {

package/src/query-href.ts

@@ -0,0 +1,50 @@
+/**
+ * `queryHref` — build a URL from a base path plus query params, omitting falsy
+ * values. The functional counterpart to `searchParams()` (the reactive *reader*):
+ * instead of imperatively mutating a `URLSearchParams`, pass a params object.
+ *
+ * ```tsx
+ * const href = queryHref(base, {
+ *   sort: sort !== 'date' ? sort : undefined, // conditional include via the value
+ *   tag,                                        // included only when truthy
+ * })
+ * ```
+ *
+ * Each entry is included iff its value is a **non-empty string** — `''` /
+ * `undefined` / `null` are omitted — so a conditional include folds into the
+ * value as `cond ? value : undefined`. Returns the bare `base` when no params
+ * survive. Values are encoded with `URLSearchParams` (form-encoding, spaces →
+ * `+`).
+ *
+ * A value may also be a **`string[]`**, which appends one entry per non-empty
+ * member (`{ tag: ['a', 'b'] }` → `?tag=a&tag=b`), i.e. `URLSearchParams.append`
+ * rather than `set`. Empty / falsy members are skipped (same truthy-omit as a
+ * scalar), so an empty array — or one whose members are all empty — contributes
+ * nothing.
+ *
+ * Values are **strings** (`QueryParamValue`). Number / boolean aren't accepted:
+ * JS truthiness would omit `0` / `false`, which the SSR adapters' string guard
+ * can't model without per-value type info — so keeping values string-only
+ * guarantees the server-rendered URL matches this client output byte-for-byte.
+ * Stringify other types at the call site (`String(n)`), choosing the omit rule
+ * explicitly (`n > 0 ? String(n) : undefined`).
+ *
+ * This is a pure function with no reactivity. The SSR adapters lower a
+ * `queryHref(base, { … })` call to their query helper (go-template: `bf_query`),
+ * which is why the params object must be a plain object literal at the call site.
+ */
+export type QueryParamValue = string | string[] | null | undefined
+export type QueryParams = Record<string, QueryParamValue>
+
+export function queryHref(base: string, params: QueryParams): string {
+  const u = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const member of value) if (member) u.append(key, member)
+    } else if (value) {
+      u.set(key, value)
+    }
+  }
+  const qs = u.toString()
+  return qs ? `${base}?${qs}` : base
+}

package/src/reactive.ts

@@ -5,7 +5,7 @@
  * Inspired by SolidJS signals.
  */
 
-import { BF_SEAM_PUSH_SEARCH } from '@barefootjs/shared'
+import { BF_SEAM_NAV_SEARCH, BF_SEAM_PUSH_SEARCH } from '@barefootjs/shared'
 
 /**
  * Phantom brand for compile-time reactivity detection.
@@ -665,15 +665,22 @@ function resolveServerEnv(key: string): string | undefined {
 
 /**
  * Build a request-scoped reactive environment signal, keyed by `key` — the env
- * id the SSR reader resolves (`'search'`, …). Internal: only concrete instances
- * (`searchParams`, …) are exported.
+ * id the SSR reader resolves (`'search'`, …) — as a `createSignal`-shaped
+ * `[getter, setter]` tuple. Internal: only concrete factories
+ * (`createSearchParams`, …) are exported.
+ *
+ * The tuple shape is deliberate (#2057): the compiler recognises the getter
+ * *structurally* — the same path as `createSignal` — so it needs no env-signal
+ * name allow-list, and the getter is pure-within-render for the block fold. The
+ * setter is the single imperative navigation path.
  */
 function createEnvSignal<T>(
   key: string,
   readClient: () => string,
   parse: (raw: string) => T,
   pushSeam: string,
-): Reactive<() => T> {
+  navSeam: string,
+): readonly [Reactive<() => T>, (nextRaw: string) => void] {
   let getRaw: (() => string) | null = null
 
   function ensureClientSignal(): string {
@@ -693,7 +700,7 @@ function createEnvSignal<T>(
     return getRaw()
   }
 
-  return (() => {
+  const getter = (() => {
     if (typeof window === 'undefined') {
       // SSR: resolve per-call inside the host's request context. Never cache a
       // module-level signal — it would be a process-wide global that races.
@@ -701,29 +708,100 @@ function createEnvSignal<T>(
     }
     return parse(ensureClientSignal())
   }) as Reactive<() => T>
+
+  // Imperative navigation. The setter writes the new raw value through the
+  // router's nav seam (soft, same-route query navigation) when a router has
+  // installed it; otherwise it hard-navigates — "never worse than an MPA" — so
+  // the write is correct standalone. The getter is then updated by the router
+  // through `pushSeam`, keeping read reactivity in one place. On the server a
+  // setter call is a no-op (there is nothing to navigate).
+  const setter = (nextRaw: string) => {
+    if (typeof window === 'undefined') return
+    const w = window as unknown as Record<string, ((next: string) => void) | undefined>
+    const nav = w[navSeam]
+    if (typeof nav === 'function') {
+      nav(nextRaw)
+      return
+    }
+    window.location.search = nextRaw
+  }
+
+  return [getter, setter] as const
 }
 
+/** Accepted inputs for `setSearchParams` — a raw query string (with or without
+ *  a leading `?`), a `URLSearchParams`, or a plain record (array = multi-value,
+ *  form-encoded like the client `queryHref`, cf. #2048). */
+export type SearchParamsInit =
+  | string
+  | URLSearchParams
+  | Record<string, string | readonly string[]>
+
+function toSearchString(next: SearchParamsInit): string {
+  let usp: URLSearchParams
+  if (next instanceof URLSearchParams) {
+    usp = next
+  } else if (typeof next === 'string') {
+    usp = new URLSearchParams(next.startsWith('?') ? next.slice(1) : next)
+  } else {
+    usp = new URLSearchParams()
+    for (const [k, v] of Object.entries(next)) {
+      if (Array.isArray(v)) {
+        for (const item of v) usp.append(k, item)
+      } else {
+        usp.append(k, v as string)
+      }
+    }
+  }
+  const s = usp.toString()
+  return s ? `?${s}` : ''
+}
+
+const [searchParamsGetter, setSearchParamsRaw] = createEnvSignal(
+  'search',
+  () => window.location.search,
+  (raw) => new URLSearchParams(raw),
+  BF_SEAM_PUSH_SEARCH,
+  BF_SEAM_NAV_SEARCH,
+)
+
 /**
- * Reactive read of the current query string as `URLSearchParams`.
+ * `createSearchParams()` — the request-scoped query-string env signal, returned
+ * as a `createSignal`-shaped `[getter, setter]` tuple (#2057):
  *
  * ```tsx
+ * const [searchParams, setSearchParams] = createSearchParams()
  * const sort = createMemo(() => searchParams().get('sort') ?? 'recent')
+ * // …
+ * setSearchParams({ sort: 'price' })   // imperative, same-route navigation
  * ```
  *
- * A same-route, query-only navigation (`/list?sort=price`) driven by
+ * **Read** (`searchParams()`): the current query as `URLSearchParams`. A
+ * same-route, query-only navigation (`/list?sort=price`) driven by
  * `@barefootjs/router` updates this signal and the URL **without a swap or
  * re-hydration**. On the server it reflects the current request's query.
- *
  * Reactivity is **router-driven**: the signal is seeded once on first read and
  * thereafter updated only through the `window.__bf_pushSearch` seam, which
- * `startRouter()` drives (including on `popstate`). Without the router running
- * — or after a non-router `history` change — the value is read-once; the seam
- * name is shared with `@barefootjs/router` via `BF_SEAM_PUSH_SEARCH`, so the
- * installer (here) and the pusher agree by construction.
+ * `startRouter()` drives (including on `popstate`).
+ *
+ * **Write** (`setSearchParams(next)`): the single imperative navigation path —
+ * a soft same-route navigation when a router is running, a hard navigation
+ * otherwise. This replaces mutating a live `URLSearchParams` reader (which only
+ * ever changed a throwaway copy), so there is exactly one way to change the
+ * query.
+ *
+ * Every call returns the same request-scoped getter/setter — there is one query
+ * per document, so the tuple is a stable view, not per-call state.
  */
-export const searchParams = createEnvSignal(
-  'search',
-  () => window.location.search,
-  (raw) => new URLSearchParams(raw),
-  BF_SEAM_PUSH_SEARCH,
-)
+const setSearchParams = (next: SearchParamsInit): void => setSearchParamsRaw(toSearchString(next))
+const searchParamsTuple: readonly [
+  Reactive<() => URLSearchParams>,
+  (next: SearchParamsInit) => void,
+] = [searchParamsGetter, setSearchParams]
+
+export function createSearchParams(): readonly [
+  Reactive<() => URLSearchParams>,
+  (next: SearchParamsInit) => void,
+] {
+  return searchParamsTuple
+}

package/src/runtime/index.ts

@@ -23,11 +23,13 @@ export {
   endTurn,
   __bfReportOutput,
   // Request-scoped env signal (router v0.5). The compiler emits island client JS
-  // that imports `searchParams` from `@barefootjs/client/runtime`; re-exporting
-  // it from the shared reactive module (same as the signal primitives above)
-  // means this entry and the main `@barefootjs/client` entry resolve to ONE
-  // signal instance — no second copy to disconnect from router pushes.
-  searchParams,
+  // that imports `createSearchParams` from `@barefootjs/client/runtime`;
+  // re-exporting it from the shared reactive module (same as the signal
+  // primitives above) means this entry and the main `@barefootjs/client` entry
+  // resolve to ONE signal instance — no second copy to disconnect from router
+  // pushes.
+  createSearchParams,
+  type SearchParamsInit,
   __bfSetServerEnvReader,
   type Reactive,
   type Signal,
@@ -49,6 +51,7 @@ export { splitProps } from '../split-props.ts'
 export { __slot, type SlotMarker } from '../slot.ts'
 export { forwardProps } from '../forward-props.ts'
 export { unwrap } from '../unwrap.ts'
+export { queryHref, type QueryParams, type QueryParamValue } from '../query-href.ts'
 
 // Context API (real DOM-bound implementations; `createContext` is the
 // same pure function re-exported from `../context`).