@close-by/clay 0.2.15 → 0.2.16

package/docs/browser-apis.md

@@ -68,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`, `setUrlSearch`, `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/protocol.md

@@ -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,7 @@ 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`
 
@@ -169,7 +177,7 @@ Client sets `location.hash` via `history.replaceState` (`hash` has no leading `#
 { "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`. Prefer `ui.setUrlSearch` / `ui.updateUrlSearch` / `ui.getUrlSearch`. See [URL search](./url-search.md).
+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

@@ -61,12 +61,18 @@ tweaks so Back is not flooded.
 
 ## Protocol
 
-**Client → server** (`hello`):
+**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
@@ -74,7 +80,8 @@ tweaks so Back is not flooded.
 ```
 
 Client writes `pathname + ?search + hash` via `history.replaceState` / `pushState`.
-Hash is preserved (same as `setUrlHash` preserves search).
+Hash is preserved (same as `setUrlHash` preserves search). Same-path `popstate`
+sends `urlchange` so `ui.urlState` re-hydrates in place.
 
 ## Path vs query
 
@@ -84,14 +91,7 @@ Hash is preserved (same as `setUrlHash` preserves search).
 | Active tab, filters, sort, page | **Query string** (`ui.urlState`) |
 | In-page focus / trace id | Hash (`ui.setUrlHash`) when you already use it |
 
-## Limits / follow-ups
-
-- Hydration runs on each `hello` (connect, reconnect, SPA path change). Pure
-  Back/Forward that only changes the query does **not** remount yet — same
-  limitation as hash today. A future `urlchange` client event (or popstate →
-  hello) would close that gap and re-hydrate `urlState` in place.
-
 ## Related
 
 - [Browser APIs](./browser-apis.md)
-- [WebSocket protocol](./protocol.md) — `hello.search`, `setUrlSearch`
+- [WebSocket protocol](./protocol.md) — `hello.search`, `urlchange`, `setUrlSearch`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.15",
+  "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.15",
-    "@close-by/clay-core": "0.2.15",
-    "@close-by/clay-components": "0.2.15",
-    "@close-by/clay-server": "0.2.15",
+    "@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"
   }