@close-by/clay 0.2.14 → 0.2.16

package/SKILL.md

@@ -62,6 +62,7 @@ ui.label(() => `Count: ${s.count}`);
 | API | Use when |
 |-----|----------|
 | `ui.state(initial)` | Reactive object; writes trigger tracked rebuilds |
+| `ui.urlState(defaults, opts?)` | Like `state`, hydrated from / synced to the query string |
 | `ui.auto(fn)` | Rebuild a UI block when tracked state changes |
 | `ui.label(() => …)` / `bindText` | Patch text only (stable tree) |
 | `bindValue` | Two-way inputs |
@@ -94,7 +95,7 @@ ui.page('/dashboard', () => {
 ## Do not
 
 - Import React, write JSX, or add client components for screens.
-- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Assume `let` is shared across tabs or users.
 - Use `ui.ai.*` as an LLM runtime — it is visual primitives only.
 

package/docs/README.md

@@ -15,7 +15,8 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 | [Tailwind](./tailwind.md) | Zero-config utilities from page modules; optional tokens |
 | [Sample app](./tutorial.md) | Step-by-step tasks list, then two pages + shell |
 | [Concepts](./concepts.md) | Mental model: sessions, elements, patches; **canonical `state`/`auto`/`timer` recipe**; reactive `let` alternative |
-| [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / `openExternal` — never `window` in page code |
+| [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / search / `openExternal` — never `window` in page code |
+| [URL search](./url-search.md) | `ui.urlState` + query helpers for shareable filters |
 | [Production & security](./production.md) | Auth, server exposure, rate limits, boot parity |
 | [Ops patterns](./ops-patterns.md) | Dense consoles: chips, master–detail, feeds, sensitive logs, auth nav |
 | [API reference](./api.md) | `ui.*`, `Element` methods, `reactive`, helpers |

package/docs/SKILL.md

@@ -62,6 +62,7 @@ ui.label(() => `Count: ${s.count}`);
 | API | Use when |
 |-----|----------|
 | `ui.state(initial)` | Reactive object; writes trigger tracked rebuilds |
+| `ui.urlState(defaults, opts?)` | Like `state`, hydrated from / synced to the query string |
 | `ui.auto(fn)` | Rebuild a UI block when tracked state changes |
 | `ui.label(() => …)` / `bindText` | Patch text only (stable tree) |
 | `bindValue` | Two-way inputs |
@@ -94,7 +95,7 @@ ui.page('/dashboard', () => {
 ## Do not
 
 - Import React, write JSX, or add client components for screens.
-- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Assume `let` is shared across tabs or users.
 - Use `ui.ai.*` as an LLM runtime — it is visual primitives only.
 

package/docs/api.md

@@ -1793,6 +1793,11 @@ onClick: async () => {
 | `ui.clipboard(content)` | `void` | Write text to clipboard (prefer over `navigator.clipboard`) |
 | `ui.getUrlHash()` | `string` | Current hash without `#` (from hello / last set) |
 | `ui.setUrlHash(hash)` | `void` | Set `location.hash` on the client |
+| `ui.getUrlSearch()` | `string` | Current search without `?` (from hello / last set) |
+| `ui.getUrlSearchParams()` | `URLSearchParams` | Mutable parse of `getUrlSearch()` |
+| `ui.setUrlSearch(search, opts?)` | `void` | Set `location.search` (`opts.mode`: `replace` \| `push`) |
+| `ui.updateUrlSearch(patch, opts?)` | `void` | Merge query keys; `null`/`''` deletes |
+| `ui.urlState(defaults, opts?)` | reactive object | `ui.state` + hydrate/sync query string (prefer this) |
 | `ui.openExternal(url)` | `void` | `window.open` in a new tab (`noopener`) |
 | `ui.theme.set(mode)` | `void` | Push `light` \| `dark` \| `system` to this client |
 | `ui.theme.get()` | `ThemeMode \| null` | Last value set on this session |

package/docs/browser-apis.md

@@ -8,6 +8,7 @@ Page builders and event handlers run on the **server** (Bun), not in the browser
 |------|-----|
 | Copy text | `ui.clipboard(text)` |
 | Read / set URL hash | `ui.getUrlHash()` / `ui.setUrlHash(hash)` |
+| Read / set URL search (query) | `ui.urlState(defaults)` (prefer) or `ui.getUrlSearch` / `ui.updateUrlSearch` |
 | Open a URL in a new tab | `ui.openExternal(url)` |
 | In-app route change | `ui.navigate(path)` |
 | Scroll | `ui.scroll.to` / `ui.scroll.intoView` |
@@ -23,17 +24,23 @@ ui.button('Copy id', {
 
 const focus = ui.getUrlHash(); // from last hello / setUrlHash
 ui.setUrlHash(traceId);
+
+const partner = ui.getUrlSearchParams().get('partner');
+ui.updateUrlSearch({ partner: 'UBER', page: null }); // omit empty defaults
 ui.openExternal('https://signoz.example/trace/' + traceId);
 ```
 
 `getUrlHash` returns the hash **without** a leading `#`. It is hydrated from the client on each `hello` (connect, reconnect, SPA navigate) and updated when you call `setUrlHash`.
 
+`getUrlSearch` returns the query string **without** a leading `?` (same hydration / write path). Prefer **`ui.urlState`** for filter objects; use `ui.updateUrlSearch` for one-off merges. See [URL search](./url-search.md).
+
 ## Don’t
 
 ```ts
 // Wrong — server has no clipboard / location
 await navigator.clipboard.writeText(value);
 window.location.hash = traceId;
+window.location.search = '?partner=UBER';
 window.open(url, '_blank');
 ```
 
@@ -61,5 +68,5 @@ With **`clay --reactive-let`**, transformed files that import known-fragile CJS
 ## Related
 
 - Helpers table: [API — dialogs and feedback](./api.md#dialogs-and-feedback)
-- Protocol: `clipboard`, `setUrlHash`, `openExternal` in [WebSocket protocol](./protocol.md)
+- Protocol: `clipboard`, `setUrlHash`, `setUrlSearch`, `urlchange`, `openExternal` in [WebSocket protocol](./protocol.md)
 - Phase 1 reactivity (preferred over DOM hacks): [reactive-let](./reactive-let.md)

package/docs/llms.txt

@@ -9,7 +9,7 @@ Notes for agents:
 - Public API and wire protocol are camelCase (`onClick`, `bindValue`, `setText`).
 - Page builders run once per WebSocket session (per browser tab). `let` is per-tab, not shared.
 - Update existing nodes with `setText` / `setValue` / bindings. Prefer `ui.state` + `ui.auto` (+ `ui.timer`) for async/live UIs; `ui.refreshable` for simple one-shot rebuilds. Shared or persisted state: `ui.storage` (`tab` / `user` / `app`).
-- Never use `window` / `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Never use `window` / `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Runtime is Bun. In this repo: `bun run build:client`, then `bun run demo` (http://localhost:4000) or `bun run clay hello.ts`.
 - `ui.ai.*` is visual primitives only — no model or streaming runtime.
 - Agent skill (Cursor / compatible tools): `@close-by/clay/SKILL.md` — copy to `.cursor/skills/clay/SKILL.md` or read from `node_modules` when installed.

package/docs/protocol.md

@@ -19,7 +19,7 @@ On unexpected socket close, the client reconnects with exponential backoff (500m
 { "op": "hello", "path": "/examples/counter", "userId": "optional-stable-id", "hash": "optional-hash-without-hash-sign", "browserStorage": {}, "clientStorage": {}, "tabStorage": {} }
 ```
 
-Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`.
+Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `search` (no leading `?`) hydrates `ui.getUrlSearch()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`.
 
 Sent on connect and after client-side navigation. The React client keeps matching `app` shell chrome mounted across remounts; only inset content is replaced.
 
@@ -35,6 +35,14 @@ Sent on connect and after client-side navigation. The React client keeps matchin
 | `type` | `string` | Event name (`click`, `input`, `change`, …) |
 | `value` | `unknown` | Optional payload (string, number, boolean, …) |
 
+### `urlchange`
+
+```json
+{ "op": "urlchange", "search": "tab=orders&partner=UBER", "hash": "" }
+```
+
+Browser Back/Forward (or other `popstate`) changed the query and/or hash **without** a path change. Server updates `session.urlSearch` / `session.urlHash` and notifies `ui.urlState` listeners — **no remount**. Path changes still use `hello`. Prefer this over reading `window` in page code. See [URL search](./url-search.md).
+
 ## Server → client
 
 ### `mount`
@@ -161,7 +169,15 @@ Client writes `content` with `navigator.clipboard.writeText` (shows an error toa
 { "op": "setUrlHash", "hash": "trace-abc" }
 ```
 
-Client sets `location.hash` via `history.replaceState` (`hash` has no leading `#`; empty string clears). Hydrated the other way on `hello.hash`. Prefer `ui.setUrlHash` / `ui.getUrlHash`.
+Client sets `location.hash` via `history.replaceState` (`hash` has no leading `#`; empty string clears). Hydrated the other way on `hello.hash` and re-synced in place on `urlchange`. Prefer `ui.setUrlHash` / `ui.getUrlHash`.
+
+### `setUrlSearch`
+
+```json
+{ "op": "setUrlSearch", "search": "tab=orders&partner=UBER", "mode": "replace" }
+```
+
+Client sets `location.search` via `history.replaceState` or `pushState` (`mode`, default `replace`). `search` has no leading `?`; empty string clears. Pathname and hash are preserved. Hydrated the other way on `hello.search` and re-synced in place on `urlchange`. Prefer `ui.setUrlSearch` / `ui.updateUrlSearch` / `ui.getUrlSearch`. See [URL search](./url-search.md).
 
 ### `openExternal`
 

package/docs/url-search.md

@@ -0,0 +1,97 @@
+# URL search (query string) helpers
+
+Ops consoles often need **shareable filter state** in the address bar
+(`?tab=orders&partner=UBER&from=2026-01-01`). Page builders run on the server, so
+they must not read `window.location`. Clay mirrors the existing hash helpers.
+
+## Prefer `ui.urlState`
+
+Like `ui.state`, but hydrated from the query string and write-through synced:
+
+```ts
+import { ui } from '@close-by/clay';
+
+ui.page('/lastmile', () => {
+  const filters = ui.urlState({
+    tab: 'dashboard',
+    partner: '',
+    from: '',
+    page: 1,
+  });
+
+  // ?partner=UBER&page=2 — defaults (dashboard / '' / 1) are omitted
+  filters.partner = 'UBER';
+  filters.page = 2;
+
+  ui.select({
+    label: 'Partner',
+    value: filters.partner || '__all__',
+    options: [
+      { value: '__all__', label: 'All' },
+      { value: 'UBER', label: 'Uber Eats' },
+    ],
+    onChange: (v) => {
+      filters.partner = v === '__all__' ? '' : v;
+    },
+  });
+});
+```
+
+| Option | Default | Role |
+|--------|---------|------|
+| `omitDefaults` | `true` | Drop keys whose value equals the default |
+| `mode` | `'replace'` | History write (`'push'` when Back should undo) |
+| `keys` | identity | Remap state keys → query names (`{ page: 'p' }`) |
+
+Works with `ui.auto` / `bindValue` the same way as `ui.state`.
+
+## Low-level helpers
+
+Escape hatches when you need a one-off read/write without a reactive object:
+
+| Helper | Role |
+|--------|------|
+| `ui.getUrlSearch()` | Current search **without** leading `?` (from `hello` / last set) |
+| `ui.getUrlSearchParams()` | Mutable `URLSearchParams` copy of that string |
+| `ui.setUrlSearch(search, opts?)` | Replace the whole query string (empty clears) |
+| `ui.updateUrlSearch(patch, opts?)` | Merge keys; `null` / `undefined` / `''` deletes |
+
+`opts.mode` is `'replace'` (default) or `'push'`. Prefer **replace** for filter
+tweaks so Back is not flooded.
+
+## Protocol
+
+**Client → server** (`hello` on connect / path change):
+
+```json
+{ "op": "hello", "path": "/lastmile", "hash": "", "search": "tab=orders&partner=UBER" }
+```
+
+**Client → server** (Back/Forward, same path — no remount):
+
+```json
+{ "op": "urlchange", "search": "partner=GLOVO", "hash": "" }
+```
+
+**Server → client**:
+
+```json
+{ "op": "setUrlSearch", "search": "tab=orders&partner=UBER", "mode": "replace" }
+```
+
+Client writes `pathname + ?search + hash` via `history.replaceState` / `pushState`.
+Hash is preserved (same as `setUrlHash` preserves search). Same-path `popstate`
+sends `urlchange` so `ui.urlState` re-hydrates in place.
+
+## Path vs query
+
+| Concern | Prefer |
+|---------|--------|
+| Resource identity | Path (`/orders/:id`) via `ui.page` / `ui.navigate` |
+| Active tab, filters, sort, page | **Query string** (`ui.urlState`) |
+| In-page focus / trace id | Hash (`ui.setUrlHash`) when you already use it |
+
+## Related
+
+- [Browser APIs](./browser-apis.md)
+- [WebSocket protocol](./protocol.md) — `hello.search`, `urlchange`, `setUrlSearch`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.14",
-    "@close-by/clay-core": "0.2.14",
-    "@close-by/clay-components": "0.2.14",
-    "@close-by/clay-server": "0.2.14",
+    "@close-by/clay-compiler": "0.2.16",
+    "@close-by/clay-core": "0.2.16",
+    "@close-by/clay-components": "0.2.16",
+    "@close-by/clay-server": "0.2.16",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -443,6 +443,10 @@ import {
   runJavaScript as runJavaScriptCore,
   getUrlHash as getUrlHashCore,
   setUrlHash as setUrlHashCore,
+  getUrlSearch as getUrlSearchCore,
+  getUrlSearchParams as getUrlSearchParamsCore,
+  setUrlSearch as setUrlSearchCore,
+  updateUrlSearch as updateUrlSearchCore,
   openExternal as openExternalCore,
   scroll as scrollCore,
   timer as timerCore,
@@ -451,6 +455,7 @@ import {
   reactive as reactiveCore,
   state as stateCore,
   subscribe as subscribeCore,
+  urlState as urlStateCore,
   auto as autoCore,
   draft as draftCore,
   validate as validateCore,
@@ -468,6 +473,8 @@ import {
   type ThemeMode,
   type DraftStorage,
   type DraftOptions,
+  type UrlStateOptions,
+  type UrlStateValue,
 } from '@close-by/clay-core';
 import {
   ClayServer,
@@ -1593,6 +1600,35 @@ export function setUrlHash(hash: string): void {
   setUrlHashCore(hash);
 }
 
+/** URL search without `?` (from hello / last `setUrlSearch`). Prefer over `window.location`. */
+export function getUrlSearch(): string {
+  return getUrlSearchCore();
+}
+
+/** Parse {@link getUrlSearch} as `URLSearchParams` (mutable copy). */
+export function getUrlSearchParams(): URLSearchParams {
+  return getUrlSearchParamsCore();
+}
+
+/** Set the browser query string. Prefer over `window.history` / `location.search`. */
+export function setUrlSearch(
+  search: string,
+  opts?: { mode?: 'replace' | 'push' },
+): void {
+  setUrlSearchCore(search, opts);
+}
+
+/**
+ * Merge keys into the current query string.
+ * `null` / `undefined` / `''` deletes the key.
+ */
+export function updateUrlSearch(
+  patch: Record<string, string | number | boolean | null | undefined>,
+  opts?: { mode?: 'replace' | 'push' },
+): void {
+  updateUrlSearchCore(patch, opts);
+}
+
 /** Open a URL in a new tab. Prefer over `runJavaScript('window.open…')`. */
 export function openExternal(url: string): void {
   openExternalCore(url);
@@ -1630,6 +1666,18 @@ export const reactive = reactiveCore;
 /** Alias for `reactive` — NiceGUI-ish mutable page state. Prefer `ui.state`. */
 export const state = stateCore;
 
+/**
+ * Like `ui.state`, but hydrated from the query string and write-through synced
+ * via `ui.updateUrlSearch`. Prefer for shareable filters / tabs.
+ * See {@link UrlStateOptions}.
+ */
+export function urlState<T extends Record<string, UrlStateValue>>(
+  defaults: T,
+  opts?: UrlStateOptions<T>,
+): T {
+  return urlStateCore(defaults, opts);
+}
+
 /** Listen for a reactive property change. Prefer this over importing from `@close-by/clay-core`. */
 export const subscribe = subscribeCore;
 
@@ -1915,6 +1963,10 @@ export const ui = {
   clipboard,
   getUrlHash,
   setUrlHash,
+  getUrlSearch,
+  getUrlSearchParams,
+  setUrlSearch,
+  updateUrlSearch,
   openExternal,
   runJavaScript,
   scroll,
@@ -1923,6 +1975,7 @@ export const ui = {
   theme,
   reactive,
   state,
+  urlState,
   subscribe,
   draft,
   validate,