@lotics/app-sdk 0.38.1 → 0.41.0

package/AGENTS.md

@@ -76,8 +76,12 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   (web-only, which is why it's here, not in `@lotics/ui`). Feeds a `Combobox`'s `recentOptions`.
 - **Shareable view-state (filters in the URL)** — **`useUrlState(shape)`** → `[values, setValues]`,
   keeping a declared slice of state (filters, search, sort, the active tab) in the **address bar** so a
-  view survives refresh and is shareable/bookmarkable; `setValues(patch, { push })` makes it
-  back/forward-navigable. Build `shape` from **`urlParam`** codecs. See *Shareable filters in the URL*.
+  view survives refresh and is shareable/bookmarkable. `setValues` replaces in place. Build `shape` from
+  **`urlParam`** codecs. See *Save view-state to the URL*.
+- **In-app routing** — **`AppRouter`** (from `@lotics/app-sdk/router`) → wrap a react-router route config;
+  the app owns its own url (embedded, that's the iframe's own url — never the host's), so navigation never
+  reloads the app, browser back/forward walk app screens, and screens stay shareable + refresh-survivable.
+  See *In-app navigation*.
 - **Optimistic mutation glue** — **`useOptimistic()`** → reconcile a workflow mutation against the
   query cache for an interactive (calendar/kanban/grid) app. See the data-bound recipe.
 - **Infra** — **`mount(opts?)`** boots the app + analytics (call once at entry; PostHog is automatic,
@@ -250,12 +254,13 @@ stops constraining instead of erroring (no-op for all-required queries).
 independently. Keep a scope that must always apply `required` (a missing required param 400s). Typos
 can't widen — deploy rejects a `{{params.x}}` with no declared param.
 
-## Shareable filters in the URL (`useUrlState`)
+## Save view-state to the URL (`useUrlState`)
 
-The filters above are the query's *server* params; **`useUrlState`** is their *client* home — keep them in
-the address bar and a filtered view survives refresh, is shareable/bookmarkable as a link, and (with
-`{ push: true }`) is back/forward-navigable. The hook drives the host's URL over the bridge; the app
-can't touch the cross-origin host URL itself. Standalone apps drive their own URL — same code.
+The filters above are the query's *server* params; **`useUrlState`** is their *client* home — save them to
+the host's address bar and a filtered view survives refresh and is shareable/bookmarkable as a link. Writes
+always **replace** in place (filter changes shouldn't add history entries); screen-to-screen navigation and
+history are the router's job (next section). The hook drives the host's URL over the bridge; the app can't
+touch the cross-origin host URL itself. Standalone apps drive their own URL — same code.
 
 ```tsx
 const [filters, setFilters] = useUrlState({
@@ -266,8 +271,8 @@ const [filters, setFilters] = useUrlState({
 });
 // filters → { q: string; status?: "open"|"won"|"lost"; tags: string[]; page: number }
 const { rows } = usePaginatedQuery("search", { keyword: filters.q, status: filters.status }, { pageSize: 50 });
-setFilters({ status: "won" });                  // merge, replace history → URL ?status=won
-setFilters({ page: 2 }, { push: true });        // back-able navigation
+setFilters({ status: "won" });                  // merge into the address bar → ?status=won
+setFilters({ page: 2 });                        // merge (replace; no history entry)
 ```
 
 - **`urlParam`** codecs: `string` / `number` / `boolean` / `isoDate` / `enum([...])` / `arrayOf(inner)`,
@@ -277,8 +282,38 @@ setFilters({ page: 2 }, { push: true });        // back-able navigation
 - **Declared keys only.** The app touches just the keys in `shape`; every other param (a second
   `useUrlState`, the framework's own) is preserved on write — no namespace rule to remember.
 - **Search box:** keep the live input in local `useState` and commit to `setFilters` on a **debounce** —
-  in an embedded app each `setFilters` is a cross-frame write. Default is *replace* (no history entry);
-  reserve `{ push: true }` for committed navigations (open a detail, switch a major tab).
+  in an embedded app each `setFilters` is a cross-frame write.
+
+## In-app navigation (`AppRouter`)
+
+For a multi-screen app, write plain react-router and wrap your routes in **`AppRouter`** (from
+`@lotics/app-sdk/router`) — it makes screens real, addressable URLs in both modes, with no per-mode code:
+
+```tsx
+import { AppRouter } from "@lotics/app-sdk/router";
+
+export default function App() {
+  return <AppRouter routes={[
+    { path: "/", element: <List /> },
+    { path: "/item/:id", element: <Detail /> },
+  ]} />;
+}
+```
+
+Inside, use react-router normally — `useNavigate`, `useParams`, `<Link>`.
+
+- **Embedded** (in the Lotics host): the app drives the **iframe's own url** (same-origin to itself) via
+  `pushState`. The user sees the host's address bar, never the iframe's, so the screen url is invisible — and
+  the host never sees it, so navigation never reloads the app. The iframe's history participates in the
+  session history, so the **browser Back/Forward buttons walk app screens** (then leave the app). `AppRouter`
+  also mirrors the current screen into the host url (a non-remounting write) and the host bakes it back into
+  the iframe src on load, so a screen is **shareable and survives a full refresh** — no reload, no extra code.
+- **Standalone** (`<slug>.lotics.app`): a normal browser router — real path URLs, native browser back/forward,
+  refresh-survivable.
+
+`useUrlState` is the complement: in-app *routing* (screens) is automatic via `AppRouter`; reach for
+`useUrlState` for *filters/search* you want as first-class, typed, shareable query keys. `react-router-dom` is
+an optional peer — only apps that import `@lotics/app-sdk/router` pull it in.
 
 ---
 

package/dist/src/index.d.ts

@@ -23,7 +23,7 @@ export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, Commen
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
-export { rpc } from "./rpc.js";
+export { rpc, isEmbedded } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { downloadFile } from "./download.js";
@@ -40,6 +40,6 @@ export type { OptimisticApi } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";
 export type { RecentsApi, RecentsOptions } from "./use_recents.js";
 export { useUrlState } from "./use_url_state.js";
-export type { UrlStateShape, UrlStateValues, SetUrlStateOptions } from "./use_url_state.js";
+export type { UrlStateShape, UrlStateValues } from "./use_url_state.js";
 export { urlParam } from "./url_params.js";
 export type { UrlParamCodec, OptionalUrlParamCodec, UrlParams, UrlParamValue, } from "./url_params.js";

package/dist/src/index.js

@@ -19,7 +19,7 @@ export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOpt
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
-export { rpc } from "./rpc.js";
+export { rpc, isEmbedded } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";

package/dist/src/router.d.ts

@@ -0,0 +1,4 @@
+import { type RouteObject } from "react-router-dom";
+export declare function AppRouter({ routes }: {
+    routes: RouteObject[];
+}): import("react/jsx-runtime").JSX.Element;

package/dist/src/router.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * In-app routing for custom-code apps — `AppRouter` lets an app use react-router
+ * normally (`useNavigate`, `useParams`, `<Link>`) while its screens become real,
+ * addressable URLs. The app owns its OWN url (a plain browser history) in both
+ * modes; the host url only ever *mirrors* the screen, it never drives the router:
+ *
+ *  - **Standalone** (`<slug>.lotics.app`): the page's own browser history — real
+ *    path URLs, native browser back/forward, deep-link/refresh via the app host's
+ *    SPA fallback.
+ *  - **Embedded** (inside the Lotics host): the app drives the IFRAME's own url
+ *    (the iframe is same-origin to itself) via `pushState`. The user sees the
+ *    host's address bar, never the iframe's, and the host never sees the iframe's
+ *    url — so it never navigates and never remounts the iframe. (Reflecting the
+ *    screen into the host url with a *navigation* is what used to remount the app
+ *    iframe and reload the whole app on every in-app navigation.) The iframe's
+ *    history still participates in the session history, so browser Back/Forward
+ *    walk app screens (then leave the app).
+ *
+ *    To stay shareable + refresh-survivable, `AppRouter` *mirrors* the current
+ *    screen into the host url under `_loc` via `setUrlParams` — a non-remounting
+ *    `history.replaceState` on the host, never a navigation. The READ half is the
+ *    host's job: on (re)load it bakes `_loc` into the iframe src, so the app boots
+ *    *directly* at the saved screen. There's deliberately no async seed here —
+ *    that would race the app's own first navigation; the iframe's initial url is
+ *    the source of truth, set synchronously by the host.
+ *
+ * Shipped as a separate entry (`@lotics/app-sdk/router`) so apps that don't route
+ * never pull react-router into their bundle:
+ *
+ *   import { AppRouter } from "@lotics/app-sdk/router";
+ *   export default function App() {
+ *     return <AppRouter routes={[
+ *       { path: "/", element: <List /> },
+ *       { path: "/item/:id", element: <Detail /> },
+ *     ]} />;
+ *   }
+ */
+import { useEffect } from "react";
+import { BrowserRouter, useLocation, useRoutes, } from "react-router-dom";
+import { isEmbedded, setUrlParams } from "./rpc.js";
+/** Host query key carrying the app's current screen, so it's shareable and the
+ *  host can restore it on refresh. */
+const LOC_KEY = "_loc";
+/** The host handshake param the host puts on the iframe src — present on the
+ *  initial url only, never part of a route, so it's stripped from the mirror. */
+const HOST_KEY = "lotics_host";
+function screenHref(loc) {
+    const search = new URLSearchParams(loc.search);
+    search.delete(HOST_KEY);
+    const qs = search.toString();
+    return loc.pathname + (qs ? `?${qs}` : "") + loc.hash;
+}
+/**
+ * Embedded only: mirror the current screen into the host url under `_loc` — a
+ * non-remounting `setUrlParams` → `history.replaceState`, never a navigation, so
+ * it never reloads the app. Write-only by design: the host reads `_loc` back and
+ * bakes it into the iframe src on (re)load, so the app already boots at the saved
+ * screen — no async read here, hence no seed-vs-navigation race. Standalone needs
+ * none of this — the app's own url already IS the screen.
+ */
+function HostScreenMirror() {
+    const location = useLocation();
+    const href = screenHref(location);
+    useEffect(() => {
+        void setUrlParams({ [LOC_KEY]: href });
+    }, [href]);
+    return null;
+}
+function RoutedRoutes({ routes }) {
+    return useRoutes(routes);
+}
+export function AppRouter({ routes }) {
+    // `isEmbedded()` reads the `?lotics_host=` the host puts on the iframe src, so
+    // it's known synchronously at first render.
+    const embedded = isEmbedded();
+    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: routes })
+        ] }));
+}

package/dist/src/rpc.d.ts

@@ -58,20 +58,26 @@ export interface AppContext {
      */
     comments_enabled: boolean;
 }
+/**
+ * Whether the app is running embedded in a Lotics host (vs. standalone at its
+ * own `<slug>.lotics.app`). `rpc()`, `useUrlState`, and `AppRouter` use this to
+ * pick the transport / behaviour; an app rarely needs it directly.
+ */
+export declare function isEmbedded(): boolean;
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;
 /** Read the current app-owned query params — bridged: ask the host; standalone:
  *  the page's own query string. */
 export declare function getUrlParams(): Promise<UrlParams>;
-/** Merge `patch` into the query string (each key set, or cleared when its value
- *  is `undefined`). `push` adds a history entry (back-able); otherwise it
- *  replaces in place — the default, so filter churn doesn't flood history. */
-export declare function setUrlParams(patch: UrlParamsPatch, push: boolean): Promise<void>;
+/** Merge `patch` into the host's address bar (each key set, or cleared when its
+ *  value is `undefined`), preserving every other param. The host writes in place
+ *  (`history.replaceState`) — view-state changes don't add history entries. */
+export declare function setUrlParams(patch: UrlParamsPatch): Promise<void>;
 /** Synchronous best-effort snapshot for first paint. Standalone reads its own
  *  URL (no flash); bridged can't read the cross-origin host URL synchronously,
  *  so it returns `{}` and the hook hydrates via `getUrlParams()` on mount. */
 export declare function peekUrlParams(): UrlParams;
-/** Subscribe to external query changes — back/forward, or an edited URL.
- *  Bridged: the host's `url-state` broadcast; standalone: `popstate`. */
+/** Subscribe to external query changes — browser back/forward and edited URLs.
+ *  Embedded: the host's `url-state` broadcast; standalone: `popstate`. */
 export declare function subscribeUrlParams(cb: (params: UrlParams) => void): () => void;
 /**
  * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`

package/dist/src/rpc.js

@@ -18,40 +18,56 @@ function getHostOrigin() {
     }
     return hostOriginCache;
 }
+/**
+ * Whether the app is running embedded in a Lotics host (vs. standalone at its
+ * own `<slug>.lotics.app`). `rpc()`, `useUrlState`, and `AppRouter` use this to
+ * pick the transport / behaviour; an app rarely needs it directly.
+ */
+export function isEmbedded() {
+    // Truthiness, not `!== null`: a present-but-empty `?lotics_host=` yields "",
+    // which is no usable host origin — so it's standalone, matching how `rpc()`
+    // branches transports below.
+    return Boolean(getHostOrigin());
+}
 export function rpc(op, payload) {
     const hostOrigin = getHostOrigin();
     return hostOrigin
         ? rpcBridged(op, payload, hostOrigin)
         : rpcStandalone(op, payload);
 }
-// ── URL state (the address bar as shareable view-state) ─────────────────────
+// ── URL state (the host address bar as shareable app view-state + screen) ────
 //
-// `useUrlState` keeps a declared slice of app state in the host's address bar so
-// a filtered view survives refresh and is shareable/bookmarkable. An embedded
-// app can't read or write the cross-origin host URL directly, so reads/writes
-// flow over the bridge (the host drives its own router); a standalone app owns
-// its top-level URL and the same ops resolve against `window.location`.
+// Two consumers: `useUrlState` (a declared, typed slice of filters/search) and
+// `AppRouter`'s screen mirror (the current screen under `_loc`). Both keep app
+// state in the host's address bar so it survives refresh and is shareable. An
+// embedded app can't touch the cross-origin host URL directly, so reads/writes
+// flow over the bridge: the host writes the params in place (a non-remounting
+// `history.replaceState` — never a navigation, which would reload the iframe) and
+// pushes external changes (browser back/forward) back via the `url-state`
+// broadcast. A standalone app owns its top-level URL and the same ops resolve
+// against `window.location`. (In-app *routing* is not here — the app owns its own
+// url via `@lotics/app-sdk/router`; see that module.)
 /** Read the current app-owned query params — bridged: ask the host; standalone:
  *  the page's own query string. */
 export function getUrlParams() {
     return rpc("urlState.get", {});
 }
-/** Merge `patch` into the query string (each key set, or cleared when its value
- *  is `undefined`). `push` adds a history entry (back-able); otherwise it
- *  replaces in place — the default, so filter churn doesn't flood history. */
-export function setUrlParams(patch, push) {
-    return rpc("urlState.set", { params: patch, push });
+/** Merge `patch` into the host's address bar (each key set, or cleared when its
+ *  value is `undefined`), preserving every other param. The host writes in place
+ *  (`history.replaceState`) — view-state changes don't add history entries. */
+export function setUrlParams(patch) {
+    return rpc("urlState.set", { params: patch });
 }
 /** Synchronous best-effort snapshot for first paint. Standalone reads its own
  *  URL (no flash); bridged can't read the cross-origin host URL synchronously,
  *  so it returns `{}` and the hook hydrates via `getUrlParams()` on mount. */
 export function peekUrlParams() {
-    return getHostOrigin() ? {} : parseSearch(window.location.search);
+    return isEmbedded() ? {} : parseSearch(window.location.search);
 }
-/** Subscribe to external query changes — back/forward, or an edited URL.
- *  Bridged: the host's `url-state` broadcast; standalone: `popstate`. */
+/** Subscribe to external query changes — browser back/forward and edited URLs.
+ *  Embedded: the host's `url-state` broadcast; standalone: `popstate`. */
 export function subscribeUrlParams(cb) {
-    if (getHostOrigin()) {
+    if (isEmbedded()) {
         ensureListener();
         urlStateSubscribers.add(cb);
         return () => {
@@ -64,8 +80,8 @@ export function subscribeUrlParams(cb) {
 }
 const pending = new Map();
 const streaming = new Map();
-/** `useUrlState` subscribers (bridged transport) — notified when the host pushes
- *  a `url-state` broadcast after an external navigation. */
+/** `useUrlState` subscribers — notified when the host broadcasts new params
+ *  after browser back/forward. */
 const urlStateSubscribers = new Set();
 let nextRpcId = 0;
 let listenerInstalled = false;
@@ -80,8 +96,8 @@ function ensureListener() {
         const msg = event.data;
         if (!msg)
             return;
-        // Broadcast (no id): the host pushes the new query params after an external
-        // navigation (back/forward, an edited URL) so `useUrlState` re-hydrates.
+        // Broadcast (no id): the host pushes new params after browser back/forward
+        // so `useUrlState` subscribers re-hydrate.
         if (msg.type === "url-state" && msg.params && typeof msg.params === "object") {
             for (const cb of urlStateSubscribers)
                 cb(msg.params);
@@ -435,12 +451,9 @@ async function standaloneOpenExternal(p) {
 async function standaloneUrlStateSet(p) {
     const search = serializeMerge(window.location.search, p.params ?? {});
     const url = window.location.pathname + (search ? `?${search}` : "") + window.location.hash;
-    // pushState/replaceState don't fire popstate, so subscribers aren't notified
-    // here — the hook updates its own state optimistically on write.
-    if (p.push)
-        window.history.pushState(null, "", url);
-    else
-        window.history.replaceState(null, "", url);
+    // View-state writes never add a history entry; replaceState doesn't fire
+    // popstate, so there's no echo — the caller already updated optimistically.
+    window.history.replaceState(null, "", url);
 }
 async function standaloneContext() {
     const info = await resolveAppInfo();

package/dist/src/use_url_state.d.ts

@@ -5,12 +5,4 @@ export type UrlStateShape = Record<string, UrlParamCodec<unknown>>;
 export type UrlStateValues<D extends UrlStateShape> = {
     [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
 };
-export interface SetUrlStateOptions {
-    /** Add a browser history entry (back/forward navigable). Default `false` —
-     *  replace in place, so high-frequency filter changes don't flood history. */
-    push?: boolean;
-}
-export declare function useUrlState<D extends UrlStateShape>(defs: D): readonly [
-    UrlStateValues<D>,
-    (patch: Partial<UrlStateValues<D>>, options?: SetUrlStateOptions) => void
-];
+export declare function useUrlState<D extends UrlStateShape>(defs: D): readonly [UrlStateValues<D>, (patch: Partial<UrlStateValues<D>>) => void];

package/dist/src/use_url_state.js

@@ -1,9 +1,9 @@
 /**
- * Keep a declared slice of an app's view-state — filters, search, sort, the
- * active tab — in the browser's address bar, with two-way sync. The result is
- * real browser behaviour for an otherwise opaque cross-origin app: a filtered
- * view survives refresh, is shareable/bookmarkable as a link, and (with
- * `{ push: true }`) is back/forward-navigable.
+ * Save a declared slice of an app's view-state — filters, search, sort, the
+ * active tab — into the host's address bar, so a filtered view survives refresh
+ * and is shareable/bookmarkable as a link. Writes always *replace* in place: the
+ * host owns no in-app history, and in-app navigation (and the browser back
+ * button) belong to the app's own router, not to this hook.
  *
  *   const [filters, setFilters] = useUrlState({
  *     q:      urlParam.string.withDefault(""),
@@ -12,8 +12,7 @@
  *     page:   urlParam.number.withDefault(1),
  *   });
  *   // filters → { q: string; status?: "open"|"won"|"lost"; tags: string[]; page: number }
- *   setFilters({ q: "acme" });                  // merge, replace history
- *   setFilters({ status: "won" }, { push: true });  // back-able navigation
+ *   setFilters({ q: "acme" });                  // merge into the address bar (replace)
  *
  * The app declares only the keys it owns; every other query param (a param a
  * second `useUrlState` owns, the framework's `lotics_host`/`__mock`, a future
@@ -23,9 +22,9 @@
  *
  * The address bar is the only store: nothing is persisted server-side. Values
  * are decoded fresh from the current params each render; standalone reads the
- * URL directly, while an embedded app keeps a local mirror the SDK syncs from
- * the host (initial `urlState.get`, the app's own writes, and back/forward
- * broadcasts) — so there's no independently-mutable second copy to drift.
+ * URL directly, while an embedded app keeps a local mirror seeded from the host
+ * (`urlState.get` on mount) and updated optimistically on its own writes — so
+ * there's no independently-mutable second copy to drift.
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { getUrlParams, peekUrlParams, setUrlParams, subscribeUrlParams } from "./rpc.js";
@@ -56,7 +55,7 @@ export function useUrlState(defs) {
         };
     }, []);
     const values = useMemo(() => decodeAll(defsRef.current, params), [params]);
-    const setValues = useCallback((patch, options) => {
+    const setValues = useCallback((patch) => {
         editedRef.current = true;
         const encoded = encodePatch(defsRef.current, patch);
         // Optimistic local mirror so the UI is responsive even before the write
@@ -66,7 +65,7 @@ export function useUrlState(defs) {
         // The optimistic mirror already reflects the change, so a failed write
         // only loses cross-refresh persistence, never the session — keep the
         // optimistic state, but surface the failure instead of swallowing it.
-        void setUrlParams(encoded, options?.push ?? false).catch((err) => {
+        void setUrlParams(encoded).catch((err) => {
             console.error("useUrlState: failed to write state to the address bar", err);
         });
     }, []);

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.38.1",
+  "version": "0.41.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
-    ".": "./dist/src/index.js"
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./router": {
+      "types": "./dist/src/router.d.ts",
+      "default": "./dist/src/router.js"
+    }
   },
   "types": "./dist/src/index.d.ts",
   "files": [
@@ -23,13 +30,20 @@
   },
   "peerDependencies": {
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.0.0"
   },
   "keywords": [
     "lotics",