@colixsystems/widget-sdk 0.101.0 → 0.102.0

package/README.md

@@ -24,6 +24,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
+| **CORE** | `useWidgetRoute(initial)` | `[state, setState]` | `ctx.widgetRoute` — no scope. Where YOUR WIDGET is, persisted by the host so it survives a reload and travels in a shared link (the `w_<instanceId>` query key on web, the screen's route params natively): the folder a browser has opened, a wizard step, a selected tab, a list's sort and search. `useState` semantics over an object — writes MERGE, `null` clears a key back to its `initial`, and `initial` is read once. Values are scalars or flat arrays of scalars, size- and length-capped; anything else is not stored. NOT history (Back still leaves the page, on both platforms). Degrades to component state on the Studio canvas. |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
@@ -837,6 +838,10 @@ The "split-implementation + vetted package list" pivot.
 - **`useDatastoreRecord(tableId, recordId)` is wired.** Returns `{ data, loading, error, refetch }` for a single record fetched through the host's `records(table).get(id)`. Sister to `useDatastoreQuery`; mirrors its ref discipline so `refetch` stays a stable callback identity. A 404 surfaces as `DatastoreError.code === "NOT_FOUND"`. Additive.
 - **`useAsset(fileId)` is wired** + new `WidgetContext.assets` slice. Returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL the widget can drop straight into `<Image source>`. Backed by a new `files.get(fileId)` host facade (web: `widgetHostFiles` through `api/client`; native: `hostFiles` in the export's `widgetHost.js`). Additive.
 
+### What's new in 0.102.0
+
+- **`useWidgetRoute(initial)` persists your widget's own internal position.** A widget's internal navigation lived in bare `useState`, so it was neither linkable nor durable: a reload dropped the visitor back at the opening view. Use the hook exactly like `useState` with an object — `const [view, setView] = useWidgetRoute({ path: [], sort: 'name' })` — and the host persists the bag: the view survives a reload and a copied link opens the widget where the sender was. Writes MERGE, `null` clears a key back to the `initial` you declared (which is what keeps the address clean), and `initial` is read once like `useState`'s argument. Values are scalars or flat arrays of scalars — a path, a list of visited steps — and are size- and length-capped; nothing else is stored. Scoped to the PLACEMENT, so the same widget placed twice on a page keeps two independent views. Three rules worth reading twice: it is **not history** (Back still leaves the page on both platforms, because native has no equivalent stack to mirror an in-widget one onto), it is **opt-in per key** (transient UI — an open dropdown, a half-typed form — stays in ordinary `useState`), and for a **text input** you should keep the box in `useState` and push it in on a short debounce rather than rewriting the address once per keystroke. Degrades to plain component state on the Studio canvas, so it is always safe to call. Additive (v0.102.0).
+
 ### What's new in 0.11.0
 
 - **`useNavigation()` is wired.** Returns the host-provided navigation surface `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page-to-page navigation. Missing methods degrade to no-ops on the Studio canvas preview. Additive.
@@ -915,7 +920,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useWidgetRoute`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/contract.cjs

@@ -688,6 +688,20 @@ const HOOKS = [
     requiredContextSlice: ["pageContext"],
     scopes: null,
   },
+  {
+    name: "useWidgetRoute",
+    signature: "useWidgetRoute(initial)",
+    returnShape: {
+      "[0]":
+        "the widget INSTANCE's own internal position, merged over the initial object you declared — the folder a browser is in, a wizard step, a list's sort/search. Survives a reload and travels in a shared link.",
+      "[1]":
+        "setState(patchOrUpdater) — merges like a class setState. A null value clears that key back to its initial. Scalars only (string, finite number, boolean); anything else is dropped.",
+    },
+    description:
+      "The widget's OWN internal position, persisted by the host so it survives a reload and travels in a shared link — the folder a file browser is in, a wizard step, a list's sort and search. Use it like useState with an object: writes MERGE, null clears a key back to its initial, and initial is read once. Values are scalars or flat arrays of scalars (a path, a list of visited steps). Only for state a visitor would link to or expect to survive a reload; transient UI stays in plain useState. It is NOT history — Back still leaves the page, on both platforms.",
+    requiredContextSlice: ["widgetRoute"],
+    scopes: null,
+  },
   {
     name: "useDatastoreRecord",
     signature: "useDatastoreRecord(tableId, recordId)",
@@ -1938,6 +1952,15 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { params: "object", records: "object" },
   },
+  widgetRoute: {
+    description:
+      "sc-5717 — the widget INSTANCE's own persisted internal position. " +
+      "{ params: { <key>: scalar }, set(bag) }. " +
+      "params is what the host read back for THIS placement (the w_<instanceId> query key on web, the screen's route params on native); set writes the changed-from-initial bag back. " +
+      "Absent on a host with nowhere to persist (the Studio canvas), where useWidgetRoute() degrades to component state. Backs useWidgetRoute().",
+    required: false,
+    fields: { params: "object", set: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -2565,6 +2588,21 @@ function normaliseCurrencyCode(value) {
  * A non-finite amount renders as zero rather than "NaN": a price whose data has
  * not loaded should read as an amount, never as a broken string in a checkout.
  */
+/**
+ * sc-5717 — value equality for a stored widget-route value: is this key still
+ * at the default its widget declared?
+ *
+ * Structural for arrays, because two equal arrays are never Object.is-equal —
+ * identity alone would report an array key as permanently moved-from-default,
+ * so its key could never be cleared from the address again. Lives here rather
+ * than beside the codec so hooks.js and widget-route.js share ONE rule.
+ */
+function sameWidgetRouteValue(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => Object.is(item, b[i]));
+  }
+  return Object.is(a, b);
+}
 function formatMoneyIn(currency, minorUnits) {
   const code = normaliseCurrencyCode(currency);
   const fmt = CURRENCY_FORMATS[code] || {
@@ -3221,7 +3259,7 @@ const CONTRACT = deepFreeze({
   //    are compressed to WebP by default; `compress: false` stores the file
   //    byte-for-byte. Existing callers are unaffected — the field is only sent
   //    when the opt-out is chosen.
-  version: "1.75.0",
+  version: "1.76.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3521,6 +3559,7 @@ module.exports = {
   normaliseComponentGradient,
   formatMoneyIn,
   normaliseCurrencyCode,
+  sameWidgetRouteValue,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/contract.js

@@ -688,6 +688,20 @@ const HOOKS = [
     requiredContextSlice: ["pageContext"],
     scopes: null,
   },
+  {
+    name: "useWidgetRoute",
+    signature: "useWidgetRoute(initial)",
+    returnShape: {
+      "[0]":
+        "the widget INSTANCE's own internal position, merged over the initial object you declared — the folder a browser is in, a wizard step, a list's sort/search. Survives a reload and travels in a shared link.",
+      "[1]":
+        "setState(patchOrUpdater) — merges like a class setState. A null value clears that key back to its initial. Scalars only (string, finite number, boolean); anything else is dropped.",
+    },
+    description:
+      "The widget's OWN internal position, persisted by the host so it survives a reload and travels in a shared link — the folder a file browser is in, a wizard step, a list's sort and search. Use it like useState with an object: writes MERGE, null clears a key back to its initial, and initial is read once. Values are scalars or flat arrays of scalars (a path, a list of visited steps). Only for state a visitor would link to or expect to survive a reload; transient UI stays in plain useState. It is NOT history — Back still leaves the page, on both platforms.",
+    requiredContextSlice: ["widgetRoute"],
+    scopes: null,
+  },
   {
     name: "useDatastoreRecord",
     signature: "useDatastoreRecord(tableId, recordId)",
@@ -1938,6 +1952,15 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { params: "object", records: "object" },
   },
+  widgetRoute: {
+    description:
+      "sc-5717 — the widget INSTANCE's own persisted internal position. " +
+      "{ params: { <key>: scalar }, set(bag) }. " +
+      "params is what the host read back for THIS placement (the w_<instanceId> query key on web, the screen's route params on native); set writes the changed-from-initial bag back. " +
+      "Absent on a host with nowhere to persist (the Studio canvas), where useWidgetRoute() degrades to component state. Backs useWidgetRoute().",
+    required: false,
+    fields: { params: "object", set: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -2565,6 +2588,21 @@ function normaliseCurrencyCode(value) {
  * A non-finite amount renders as zero rather than "NaN": a price whose data has
  * not loaded should read as an amount, never as a broken string in a checkout.
  */
+/**
+ * sc-5717 — value equality for a stored widget-route value: is this key still
+ * at the default its widget declared?
+ *
+ * Structural for arrays, because two equal arrays are never Object.is-equal —
+ * identity alone would report an array key as permanently moved-from-default,
+ * so its key could never be cleared from the address again. Lives here rather
+ * than beside the codec so hooks.js and widget-route.js share ONE rule.
+ */
+function sameWidgetRouteValue(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => Object.is(item, b[i]));
+  }
+  return Object.is(a, b);
+}
 function formatMoneyIn(currency, minorUnits) {
   const code = normaliseCurrencyCode(currency);
   const fmt = CURRENCY_FORMATS[code] || {
@@ -3221,7 +3259,7 @@ const CONTRACT = deepFreeze({
   //    are compressed to WebP by default; `compress: false` stores the file
   //    byte-for-byte. Existing callers are unaffected — the field is only sent
   //    when the opt-out is chosen.
-  version: "1.75.0",
+  version: "1.76.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3521,6 +3559,7 @@ export {
   normaliseComponentGradient,
   formatMoneyIn,
   normaliseCurrencyCode,
+  sameWidgetRouteValue,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/hooks.js

@@ -43,6 +43,9 @@ import {
   isSharedTranslationKey,
   formatMoneyIn,
   normaliseCurrencyCode,
+  // sc-5717 — "is this key still at its declared default", shared with the
+  // host codec so the hook and the encoder can never disagree about it.
+  sameWidgetRouteValue,
 } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
@@ -479,6 +482,103 @@ export function usePageContext() {
   };
 }
 
+const EMPTY_WIDGET_ROUTE = Object.freeze({ params: EMPTY_PARAMS, set: null });
+
+/**
+ * sc-5717 — `[state, setState]` for the widget's OWN internal position, which
+ * the host persists so it survives a reload and travels in a shared link.
+ *
+ * Use it exactly like `useState` with an object, for the state that answers
+ * "where is this widget right now": the folder a browser is in, a wizard's
+ * step, a list's sort and search.
+ *
+ *   const [view, setView] = useWidgetRoute({ folder: null, sort: "name" });
+ *   setView({ folder: row.id });          // merges, like a class setState
+ *   setView((v) => ({ sort: flip(v.sort) }));
+ *
+ * Semantics worth knowing:
+ *
+ * - **Merging, not replacing.** A partial write leaves the other keys alone.
+ * - **Values are scalars** — string, finite number, boolean. `null` clears a key
+ *   back to the initial value you declared, which is also what keeps the URL
+ *   clean rather than carrying `{"folder":null}` forever.
+ * - **`initial` is read once**, like `useState`'s initial argument. Re-rendering
+ *   with a different literal does not reset anything.
+ * - **It is not history.** Persisting the position is not the same as making
+ *   Back step through it: pressing Back leaves the page on both platforms, the
+ *   same way it did before. Native has no URL to step through and no
+ *   host-neutral way to intercept its back gesture per widget, so an
+ *   in-widget back stack would behave one way on the web Player and another in
+ *   the exported app — the divergence CLAUDE.md §8 exists to prevent.
+ * - **Opt in per key.** Only put state here that a visitor would reasonably
+ *   link to or expect to survive a reload. Transient UI — an open dropdown, a
+ *   half-typed form — belongs in ordinary `useState`.
+ *
+ * On a host with nowhere to persist (the Studio canvas preview) it degrades to
+ * plain component state, so a widget behaves the same in every surface.
+ */
+export function useWidgetRoute(initial) {
+  const ctx = useWidgetContextOrThrow("useWidgetRoute");
+  const slice = ctx.widgetRoute || EMPTY_WIDGET_ROUTE;
+  const stored = slice.params || EMPTY_PARAMS;
+
+  // `initial` is the DECLARED default, captured once — a caller passing an
+  // object literal re-creates it every render, and re-resolving from the newest
+  // one would let an unrelated re-render silently redefine "cleared".
+  const initialRef = useRef(null);
+  if (initialRef.current === null) {
+    initialRef.current =
+      initial && typeof initial === "object" && !Array.isArray(initial)
+        ? { ...initial }
+        : {};
+  }
+
+  // The canvas has no host store; fall back to component state so the widget
+  // still works, just without persistence.
+  const [local, setLocal] = useState(initialRef.current);
+  const persisted = typeof slice.set === "function";
+
+  const state = useMemo(
+    () => (persisted ? { ...initialRef.current, ...stored } : local),
+    [persisted, stored, local],
+  );
+
+  // `state` is read inside, so the callback must see the current one; a ref
+  // keeps `setState` referentially stable for widgets that pass it to a memoised
+  // child or list an effect dependency on it.
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const setRef = useRef(slice.set);
+  setRef.current = slice.set;
+
+  const setState = useCallback((patch) => {
+    const current = stateRef.current;
+    const next = typeof patch === "function" ? patch(current) : patch;
+    if (!next || typeof next !== "object" || Array.isArray(next)) return;
+    const merged = { ...current, ...next };
+    const write = setRef.current;
+    if (typeof write !== "function") {
+      setLocal(merged);
+      return;
+    }
+    // Only the DIFFERENCE from the declared initial is handed to the host. A key
+    // sitting at its default is restored from `initial` anyway, so storing it
+    // would spend URL budget to say nothing — and returning a widget to its
+    // opening view leaves a clean address rather than a bag full of defaults.
+    const defaults = initialRef.current;
+    const changed = {};
+    for (const key of Object.keys(merged)) {
+      if (key in defaults && sameWidgetRouteValue(merged[key], defaults[key])) {
+        continue;
+      }
+      changed[key] = merged[key];
+    }
+    write(changed);
+  }, []);
+
+  return [state, setState];
+}
+
 /**
  * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
  * the host's translation table and falls back to `fallback ?? key` when

package/dist/host.d.ts

@@ -182,3 +182,43 @@ export interface FooterTokens {
  * renders exactly as it did before the block existed.
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
+
+/** A value a widget may persist: a scalar, or a flat array of them. */
+export type WidgetRouteScalar = string | number | boolean;
+export type WidgetRouteValue = WidgetRouteScalar | WidgetRouteScalar[];
+
+/** How many entries one array value may carry. */
+export const WIDGET_ROUTE_MAX_ITEMS: number;
+
+/** Value equality for "is this key still at its declared default" — structural
+ *  for arrays, so an array key can be cleared from the address. */
+export function sameWidgetRouteValue(a: unknown, b: unknown): boolean;
+
+/** Query-string / route-param key prefix for a widget's stored position. */
+export const WIDGET_ROUTE_PREFIX: string;
+
+/** Cap on ONE instance's encoded bag, so a single widget cannot spend the
+ *  whole URL budget. An over-cap write is dropped, never truncated. */
+export const WIDGET_ROUTE_MAX_CHARS: number;
+
+/** The key one placed widget instance stores its route bag under. */
+export function widgetRouteKey(instanceId: string): string;
+
+/** Whether a raw query-string key belongs to a widget rather than the page. */
+export function isWidgetRouteKey(key: unknown): boolean;
+
+/** Encode a bag for the address. Returns "" when there is nothing to store or
+ *  the bag exceeds `WIDGET_ROUTE_MAX_CHARS` — the caller removes the key. */
+export function encodeWidgetRoute(
+  bag: Record<string, unknown> | null | undefined,
+): string;
+
+/** Decode what the address carried. Total: any malformed input yields `{}`. */
+export function decodeWidgetRoute(
+  raw: unknown,
+): Record<string, WidgetRouteValue>;
+
+/** Every widget's stored bag out of a raw query-string map, keyed by instance id. */
+export function collectWidgetRoutes(
+  rawParams: Record<string, string> | null | undefined,
+): Record<string, Record<string, WidgetRouteValue>>;

package/dist/host.js

@@ -55,3 +55,21 @@ export {
   quickBarCap,
   resolveFooterTokens,
 } from "./navigation.js";
+
+// sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal
+// position is written into the address the host carries (the query string on
+// web, the screen's route params on native). Host-only by necessity as well as
+// by taste: a widget may not touch the URL at all, so the encoding cannot live
+// on the author side. Both hosts import THIS module, so a widget's stored
+// position can never mean one thing in the Player and another in the export.
+export {
+  WIDGET_ROUTE_PREFIX,
+  WIDGET_ROUTE_MAX_CHARS,
+  WIDGET_ROUTE_MAX_ITEMS,
+  widgetRouteKey,
+  isWidgetRouteKey,
+  encodeWidgetRoute,
+  decodeWidgetRoute,
+  collectWidgetRoutes,
+  sameWidgetRouteValue,
+} from "./widget-route.js";

package/dist/index.d.ts

@@ -1278,6 +1278,28 @@ export function usePageContext(): {
   records: Record<string, Record<string, unknown> | null>;
 };
 
+/** A value `useWidgetRoute` can persist: a scalar, or a flat array of them. */
+export type WidgetRouteScalar = string | number | boolean;
+export type WidgetRouteValue = WidgetRouteScalar | WidgetRouteScalar[];
+
+/**
+ * sc-5717 — `[state, setState]` for the widget's OWN internal position, which
+ * the host persists so it survives a reload and travels in a shared link: the
+ * folder a browser is in, a wizard's step, a list's sort and search.
+ *
+ * Use it like `useState` with an object. Writes MERGE, `null` clears a key back
+ * to the value you declared in `initial`, and `initial` itself is read once.
+ * Only put state here that a visitor would reasonably link to or expect to
+ * survive a reload — transient UI belongs in ordinary `useState`.
+ *
+ * It is not history: pressing Back leaves the page, on both platforms.
+ */
+export function useWidgetRoute<
+  T extends Record<string, WidgetRouteValue | null>,
+>(
+  initial: T,
+): [T, (patch: Partial<T> | ((current: T) => Partial<T>)) => void];
+
 /**
  * Static API for external URLs. `openURL(url)` opens a URL with the OS
  * handler (web: react-native-web maps to `window.open` / `location.href`;

package/dist/index.js

@@ -55,6 +55,7 @@ export {
   useNavigation,
   useRouteParams,
   usePageContext,
+  useWidgetRoute,
   useChildRenderer,
   useRefresh,
   useSectionEmpty,

package/dist/index.native.js

@@ -55,6 +55,7 @@ export {
   useNavigation,
   useRouteParams,
   usePageContext,
+  useWidgetRoute,
   useChildRenderer,
   useRefresh,
   useSectionEmpty,

package/dist/widget-route.js

@@ -0,0 +1,151 @@
+// sc-5717 — the codec for a widget's own internal navigation state.
+//
+// A widget's internal position (the folder a file browser is in, a list's sort
+// and search) lived in bare `useState`, so it was neither linkable nor durable:
+// a reload dropped the visitor back at the widget's initial view. `useWidgetRoute`
+// gives that state a home the host persists — the URL on web, the screen's route
+// params on native.
+//
+// Everything here is HOST plumbing. A widget never sees a key or an encoded
+// string: it reads and writes a plain object, and the host decides how that
+// object is carried. Widgets cannot touch the URL at all (`window.location` is
+// in CONTRACT.bannedApis), which is exactly why the codec lives on this side.
+//
+// One implementation for both hosts. The web Player imports it from
+// `@colixsystems/widget-sdk/host`; the generated Expo app imports the SAME
+// module from the SAME entry point, so there is no mirrored copy to drift
+// (CLAUDE.md §3/§8).
+
+/** Query-string / route-param key prefix. */
+export const WIDGET_ROUTE_PREFIX = "w_";
+
+/**
+ * Cap on ONE instance's encoded bag.
+ *
+ * Browsers stop being reliable somewhere around 2000 characters of URL, and a
+ * page may hold several widgets that each store state. Capping per instance
+ * keeps one widget from spending the whole budget; an over-cap write is dropped
+ * rather than truncated, because half a JSON document decodes to nothing and
+ * would silently reset the widget instead of just failing to persist.
+ */
+export const WIDGET_ROUTE_MAX_CHARS = 512;
+
+/** The key one placed widget instance stores its route bag under. */
+export function widgetRouteKey(instanceId) {
+  return `${WIDGET_ROUTE_PREFIX}${instanceId}`;
+}
+
+/** Whether a raw query-string key belongs to a widget rather than the page. */
+export function isWidgetRouteKey(key) {
+  return typeof key === "string" && key.startsWith(WIDGET_ROUTE_PREFIX);
+}
+
+/**
+ * How many entries one array value may carry. Paths and step lists are short;
+ * the length cap rejects an abusive value before the character cap has to.
+ */
+export const WIDGET_ROUTE_MAX_ITEMS = 64;
+
+function isScalar(value) {
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return true;
+  return type === "number" && Number.isFinite(value);
+}
+
+/**
+ * A scalar, or a flat array of them.
+ *
+ * Not a general serializer on purpose. The bag round-trips through a URL a
+ * visitor can edit, so the shape is bounded to what the host can validate
+ * cheaply and completely. Arrays earn their place because the common
+ * "where am I" state IS a path — a file browser's open folders, a wizard's
+ * visited steps — and modelling that as a scalar would push widgets into
+ * encoding their own delimited strings, which is the codec this module exists
+ * to be.
+ */
+function isStorableValue(value) {
+  if (Array.isArray(value)) {
+    return value.length <= WIDGET_ROUTE_MAX_ITEMS && value.every(isScalar);
+  }
+  return isScalar(value);
+}
+
+// Value equality for "is this key still at its declared default" lives in
+// contract.js, so the hook and this codec share one rule; re-exported here so a
+// host has the whole route surface from one import.
+export { sameWidgetRouteValue } from "./contract.js";
+
+/**
+ * Encode a widget's route bag for the URL.
+ *
+ * `null` / `undefined` values are DROPPED rather than stored. That is what makes
+ * "back to the initial view" produce a clean URL instead of `?w_…={"folder":null}`
+ * — the hook resolves an absent key to the widget's declared initial value, so
+ * absence and default are the same state by construction.
+ *
+ * @returns {string} the encoded bag, or "" when there is nothing to store (the
+ *   caller removes the key) or the bag exceeds WIDGET_ROUTE_MAX_CHARS.
+ */
+export function encodeWidgetRoute(bag) {
+  if (!bag || typeof bag !== "object" || Array.isArray(bag)) return "";
+  const storable = {};
+  let count = 0;
+  for (const key of Object.keys(bag).sort()) {
+    const value = bag[key];
+    if (value === undefined || value === null) continue;
+    if (!isStorableValue(value)) continue;
+    storable[key] = value;
+    count += 1;
+  }
+  if (count === 0) return "";
+  // Keys are sorted above so an unchanged bag always encodes to the same string
+  // — the host compares encodings to decide whether the URL needs rewriting,
+  // and key order must not make an identical state look like a change.
+  const encoded = JSON.stringify(storable);
+  return encoded.length > WIDGET_ROUTE_MAX_CHARS ? "" : encoded;
+}
+
+/**
+ * Decode what the URL carried back into a bag.
+ *
+ * Deliberately total: the input is whatever a visitor left in the address bar,
+ * so every malformed shape — bad JSON, an array, a nested object, a NaN —
+ * resolves to "no stored state" and the widget renders its initial view. It
+ * never throws, and it never yields a value a widget could not have written.
+ */
+export function decodeWidgetRoute(raw) {
+  if (typeof raw !== "string" || raw === "") return {};
+  if (raw.length > WIDGET_ROUTE_MAX_CHARS) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+  const out = {};
+  for (const key of Object.keys(parsed)) {
+    const value = parsed[key];
+    if (!isStorableValue(value)) continue;
+    // A copy, so a widget mutating the array it read cannot reach back into
+    // whatever the host is holding.
+    out[key] = Array.isArray(value) ? value.slice() : value;
+  }
+  return out;
+}
+
+/**
+ * Collect every widget's stored bag out of a raw query-string map, keyed by
+ * instance id. The host calls this once per navigation and hands each widget
+ * only its own slice.
+ */
+export function collectWidgetRoutes(rawParams) {
+  const out = {};
+  if (!rawParams || typeof rawParams !== "object") return out;
+  for (const key of Object.keys(rawParams)) {
+    if (!isWidgetRouteKey(key)) continue;
+    const instanceId = key.slice(WIDGET_ROUTE_PREFIX.length);
+    if (instanceId) out[instanceId] = decodeWidgetRoute(rawParams[key]);
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.101.0",
+  "version": "0.102.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js"
   },
   "engines": {
     "node": ">=18"