@lotics/app-sdk 0.40.0 → 0.41.0

package/AGENTS.md

@@ -78,8 +78,9 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   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` 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 so
-  screens become real, addressable URLs in both modes (browser back/forward walk app screens embedded).
+- **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.
@@ -301,14 +302,18 @@ export default function App() {
 
 Inside, use react-router normally — `useNavigate`, `useParams`, `<Link>`.
 
-- **Embedded** (in the Lotics host): the current screen lives in the host address bar (`?_loc=…`) —
-  shareable + refresh-survivable — and the **browser Back/Forward buttons walk app screens** (then leave the
-  app). The host owns the single history stack; the adapter proxies push/replace/go over the bridge.
-- **Standalone** (`<slug>.lotics.app`): a normal browser router — real path URLs, native browser back/forward.
-
-`useUrlState` is the complement for *filters/search* you want as first-class, typed query keys; it composes
-with the router (different keys; the host merge preserves both). `react-router-dom` is an optional peer — only
-apps that import `@lotics/app-sdk/router` pull it in.
+- **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/router.js

@@ -1,17 +1,29 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+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 in both modes:
+ * 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`): a normal 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 can't touch the cross-origin
- *    host URL, so a custom history proxies every push/replace/go to the host over
- *    the bridge. The host owns the single history stack, so the screen lives in
- *    its address bar (`?_loc=…`) — shareable + refresh-survivable — and the
- *    browser Back/Forward buttons walk app screens (then leave the app).
+ *  - **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:
@@ -24,103 +36,44 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *     ]} />;
  *   }
  */
-import { useState } from "react";
-import { NavigationType, UNSAFE_createBrowserHistory, unstable_HistoryRouter as HistoryRouter, useRoutes, } from "react-router-dom";
-import { getUrlParams, goUrlHistory, isEmbedded, setUrlParams, subscribeUrlParams } from "./rpc.js";
-/** Host query key carrying the app's current screen when embedded, so it's
- *  shareable and survives refresh. */
+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";
-function hrefOf(to) {
-    if (typeof to === "string")
-        return to || "/";
-    return (to.pathname ?? "/") + (to.search ?? "") + (to.hash ?? "");
-}
-let locKey = 0;
-function toLocation(href) {
-    const u = new URL(href || "/", "http://x");
-    return { pathname: u.pathname, search: u.search, hash: u.hash, state: null, key: String(++locKey) };
+/** 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 history: the host owns the single history stack.
- *  - `push`/`replace` optimistically update the local location and tell the host
- *    (pushState/replaceState don't fire popstate, so no echo back).
- *  - `go` (and the browser Back/Forward buttons) move the host history; the
- *    resulting location arrives via the `url-state` broadcast as an action POP.
+ * 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 createBridgedHistory() {
-    const listeners = new Set();
-    let location = toLocation("/");
-    let action = NavigationType.Pop;
-    // Once the location has been driven — by the app (push/replace) or the host
-    // (a back/forward broadcast) — a late boot-seed must not clobber it; the
-    // bridged read of the host URL resolves a tick after mount.
-    let seeded = false;
-    // `delta` is history metadata (scroll restoration / blockers), not used for
-    // rendering — best-effort per action, since the host doesn't report the exact
-    // index change on a broadcast.
-    function set(href, act, delta) {
-        seeded = true;
-        location = toLocation(href);
-        action = act;
-        for (const l of listeners)
-            l({ action, location, delta });
-    }
-    // Host back/forward (browser Back or our own `go`) → re-render to the broadcast
-    // location. Guarded so an already-current location doesn't re-fire.
-    subscribeUrlParams((params) => {
-        const raw = params[LOC_KEY];
-        const href = typeof raw === "string" ? raw : "/";
-        if (href !== hrefOf(location))
-            set(href, NavigationType.Pop, -1);
-    });
-    // Boot: seed from the host URL (resolves a tick after mount — first paint is
-    // "/"). Skip if the location was already driven, so a navigation that races the
-    // bridge read isn't clobbered.
-    void getUrlParams().then((params) => {
-        if (seeded)
-            return;
-        const raw = params[LOC_KEY];
-        if (typeof raw === "string" && raw !== hrefOf(location))
-            set(raw, NavigationType.Pop, 0);
-    });
-    return {
-        get action() {
-            return action;
-        },
-        get location() {
-            return location;
-        },
-        createHref: (to) => hrefOf(to),
-        createURL: (to) => new URL(hrefOf(to), window.location.origin),
-        encodeLocation: (to) => {
-            const u = new URL(hrefOf(to), "http://x");
-            return { pathname: u.pathname, search: u.search, hash: u.hash };
-        },
-        push: (to) => {
-            const href = hrefOf(to);
-            set(href, NavigationType.Push, 1);
-            void setUrlParams({ [LOC_KEY]: href }, true);
-        },
-        replace: (to) => {
-            const href = hrefOf(to);
-            set(href, NavigationType.Replace, 0);
-            void setUrlParams({ [LOC_KEY]: href }, false);
-        },
-        go: (delta) => {
-            void goUrlHistory(delta);
-        },
-        listen: (listener) => {
-            listeners.add(listener);
-            return () => listeners.delete(listener);
-        },
-    };
+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 }) {
-    // Created once (a lazy state initializer survives StrictMode's double render,
-    // so the bridge subscription isn't installed twice).
-    const [history] = useState(() => isEmbedded() ? createBridgedHistory() : UNSAFE_createBrowserHistory());
-    return (_jsx(HistoryRouter, { history: history, children: _jsx(RoutedRoutes, { routes: 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

@@ -19,7 +19,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "urlState.get" | "urlState.set" | "urlState.go" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;
@@ -60,8 +60,8 @@ export interface AppContext {
 }
 /**
  * Whether the app is running embedded in a Lotics host (vs. standalone at its
- * own `<slug>.lotics.app`). The router adapter (`@lotics/app-sdk/router`) uses
- * this to pick its history backend; an app rarely needs it directly.
+ * 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>;
@@ -69,20 +69,15 @@ export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T
  *  the page's own query string. */
 export declare function getUrlParams(): Promise<UrlParams>;
 /** Merge `patch` into the host's address bar (each key set, or cleared when its
- *  value is `undefined`), preserving every other param. `push` adds a back-able
- *  history entry — the router adapter uses it per in-app navigation; the default
- *  replaces in place (filter changes shouldn't flood history). */
-export declare function setUrlParams(patch: UrlParamsPatch, push?: boolean): Promise<void>;
-/** Move the host's history by `delta` (the router adapter's back/forward). The
- *  resulting location arrives via the `url-state` broadcast, not the return. */
-export declare function goUrlHistory(delta: number): Promise<void>;
+ *  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 (browser or the adapter's
- *  `go`) and edited URLs. Embedded: 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

@@ -20,8 +20,8 @@ function getHostOrigin() {
 }
 /**
  * Whether the app is running embedded in a Lotics host (vs. standalone at its
- * own `<slug>.lotics.app`). The router adapter (`@lotics/app-sdk/router`) uses
- * this to pick its history backend; an app rarely needs it directly.
+ * 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 "",
@@ -35,31 +35,28 @@ export function rpc(op, payload) {
         ? rpcBridged(op, payload, hostOrigin)
         : rpcStandalone(op, payload);
 }
-// ── URL state (the address bar as app view-state + route) ───────────────────
+// ── URL state (the host address bar as shareable app view-state + screen) ────
 //
-// Two consumers share these ops: `useUrlState` (a declared, typed slice of
-// filters/search) and the router adapter (`@lotics/app-sdk/router`, the app's
-// current screen under `_loc`). An embedded app can't touch the cross-origin
-// host URL directly, so reads/writes/back-forward flow over the bridge: the host
-// drives its own history (`set` with `push`, `go` for back/forward) and pushes
-// the resulting params back via the `url-state` broadcast. 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 host's address bar (each key set, or cleared when its
- *  value is `undefined`), preserving every other param. `push` adds a back-able
- *  history entry — the router adapter uses it per in-app navigation; the default
- *  replaces in place (filter changes shouldn't flood history). */
-export function setUrlParams(patch, push = false) {
-    return rpc("urlState.set", { params: patch, push });
-}
-/** Move the host's history by `delta` (the router adapter's back/forward). The
- *  resulting location arrives via the `url-state` broadcast, not the return. */
-export function goUrlHistory(delta) {
-    return rpc("urlState.go", { delta });
+ *  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,
@@ -67,9 +64,8 @@ export function goUrlHistory(delta) {
 export function peekUrlParams() {
     return isEmbedded() ? {} : parseSearch(window.location.search);
 }
-/** Subscribe to external query changes — back/forward (browser or the adapter's
- *  `go`) and edited URLs. Embedded: 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 (isEmbedded()) {
         ensureListener();
@@ -84,8 +80,8 @@ export function subscribeUrlParams(cb) {
 }
 const pending = new Map();
 const streaming = new Map();
-/** `useUrlState` + the router adapter — notified when the host broadcasts new
- *  params after browser/adapter back/forward. */
+/** `useUrlState` subscribers — notified when the host broadcasts new params
+ *  after browser back/forward. */
 const urlStateSubscribers = new Set();
 let nextRpcId = 0;
 let listenerInstalled = false;
@@ -100,8 +96,8 @@ function ensureListener() {
         const msg = event.data;
         if (!msg)
             return;
-        // Broadcast (no id): the host pushes new params after browser/adapter
-        // back/forward so subscribers (`useUrlState`, the router adapter) re-hydrate.
+        // 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);
@@ -404,12 +400,6 @@ function rpcStandalone(op, payload) {
             return Promise.resolve(parseSearch(window.location.search));
         case "urlState.set":
             return standaloneUrlStateSet(payload);
-        case "urlState.go": {
-            // Standalone owns its own history — move it; popstate re-hydrates subscribers.
-            const { delta } = payload;
-            window.history.go(delta);
-            return Promise.resolve();
-        }
         case "comments.list":
         case "comments.create":
         case "comments.update":
@@ -461,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 no echo — the caller updated
-    // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {