@lotics/cli 0.55.0 → 0.56.0

package/dist/dev/wrapper_page.d.ts

@@ -24,9 +24,11 @@
  *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
  *   streaming (op "agentRun"): { id, type: "stream-chunk", chunk } * → { id, type: "stream-end" };
  *     the iframe aborts with { id, type: "abort" }.
- *   urlState (useUrlState + router adapter): the iframe reads/writes the wrapper's
- *     address bar via urlState.get/set/go; set push/replace and go drive history,
- *     and back/forward broadcast { type: "url-state", params } back to the iframe.
+ *   urlState (useUrlState): the iframe reads/writes the wrapper's address bar via
+ *     urlState.get/set; set writes in place (replaceState), and browser
+ *     back/forward broadcast { type: "url-state", params } back to the iframe.
+ *     (In-app routing isn't here — the app owns the iframe's own url; see
+ *     @lotics/app-sdk/router.)
  */
 export interface WrapperPageArgs {
     app_name: string;

package/dist/dev/wrapper_page.js

@@ -24,9 +24,11 @@
  *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
  *   streaming (op "agentRun"): { id, type: "stream-chunk", chunk } * → { id, type: "stream-end" };
  *     the iframe aborts with { id, type: "abort" }.
- *   urlState (useUrlState + router adapter): the iframe reads/writes the wrapper's
- *     address bar via urlState.get/set/go; set push/replace and go drive history,
- *     and back/forward broadcast { type: "url-state", params } back to the iframe.
+ *   urlState (useUrlState): the iframe reads/writes the wrapper's address bar via
+ *     urlState.get/set; set writes in place (replaceState), and browser
+ *     back/forward broadcast { type: "url-state", params } back to the iframe.
+ *     (In-app routing isn't here — the app owns the iframe's own url; see
+ *     @lotics/app-sdk/router.)
  */
 export function buildWrapperPage(args) {
     const { app_name, app_id, workspace_id, vite_url, api_url } = args;
@@ -78,9 +80,28 @@ export function buildWrapperPage(args) {
       const iframe = document.getElementById("app");
 
       // Pass the wrapper's own origin to the app via ?lotics_host= so the app
-      // SDK can origin-lock its postMessage bridge.
-      iframe.src = VITE_URL + (VITE_URL.indexOf("?") >= 0 ? "&" : "?")
-        + "lotics_host=" + encodeURIComponent(window.location.origin);
+      // SDK can origin-lock its postMessage bridge, and bake the saved screen
+      // (the wrapper url's _loc, kept current by AppRouter's mirror) into the src
+      // path so a refresh boots the app at that screen — mirrors the production
+      // host. _loc is honoured only when it resolves same-origin to the Vite
+      // server (a url param flowing into an iframe src is a redirect vector);
+      // anything else falls back to the app root.
+      const appSrc = new URL(VITE_URL);
+      const savedLoc = new URLSearchParams(window.location.search).get("_loc");
+      if (savedLoc) {
+        try {
+          const resolved = new URL(savedLoc, VITE_ORIGIN);
+          if (resolved.origin === VITE_ORIGIN) {
+            appSrc.pathname = resolved.pathname;
+            appSrc.search = resolved.search;
+            appSrc.hash = resolved.hash;
+          }
+        } catch (e) {
+          // malformed _loc -> app root
+        }
+      }
+      appSrc.searchParams.set("lotics_host", window.location.origin);
+      iframe.src = appSrc.toString();
 
       async function rpc(op, payload) {
         const res = await fetch("/_rpc", {
@@ -185,7 +206,6 @@ export function buildWrapperPage(args) {
         });
         return out;
       }
-      var lastPushAt = 0;
       function handleUrlStateSet(payload) {
         const params = (payload && payload.params) || {};
         const sp = new URLSearchParams(window.location.search);
@@ -198,21 +218,9 @@ export function buildWrapperPage(args) {
         });
         const qs = sp.toString();
         const url = window.location.pathname + (qs ? "?" + qs : "") + window.location.hash;
-        // push adds a back-able entry (the router adapter); replace for filter
-        // churn. Flood guard: coerce sub-100ms pushes to replace. pushState/
-        // replaceState don't fire popstate, so no echo. Mirrors the production host.
-        const now = Date.now();
-        if (payload && payload.push && now - lastPushAt > 100) {
-          lastPushAt = now;
-          window.history.pushState(null, "", url);
-        } else {
-          window.history.replaceState(null, "", url);
-        }
-        return undefined;
-      }
-      function handleUrlStateGo(payload) {
-        const delta = payload && payload.delta;
-        if (typeof delta === "number") window.history.go(delta);
+        // View-state writes in place — never a history entry. replaceState doesn't
+        // fire popstate, so no echo. Mirrors the production host.
+        window.history.replaceState(null, "", url);
         return undefined;
       }
 
@@ -281,8 +289,6 @@ export function buildWrapperPage(args) {
             ? readUrlParams()
             : msg.op === "urlState.set"
             ? handleUrlStateSet(msg.payload)
-            : msg.op === "urlState.go"
-            ? handleUrlStateGo(msg.payload)
             : await rpc(msg.op, msg.payload);
           const ms = Math.round(performance.now() - startedAt);
           console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
@@ -300,9 +306,9 @@ export function buildWrapperPage(args) {
         }
       });
 
-      // Browser/adapter back/forward → broadcast the new params so useUrlState and
-      // the router adapter re-hydrate (the app's own set writes use push/replace
-      // State — no popstate — so there's no echo). Mirrors the production host.
+      // Browser back/forward → broadcast the new params so useUrlState re-hydrates
+      // (the app's own set writes use replaceState — no popstate — so there's no
+      // echo). Mirrors the production host.
       window.addEventListener("popstate", function () {
         iframe.contentWindow.postMessage(
           { type: "url-state", params: readUrlParams() },

package/dist/src/cli.js

@@ -30574,10 +30574,10 @@ mount(
       path: "src/App.tsx",
       // Default scaffold = a minimal in-app router example (a list screen and a
       // detail screen), so a new app starts with the recommended routing shape:
-      //   - The app uses react-router via `AppRouter` (from @lotics/app-sdk/router),
-      //     which makes screens real addressable URLs — embedded, they live in the
-      //     host address bar (?_loc=…) and the browser Back/Forward walk screens;
-      //     standalone, real path URLs.
+      //   - The app uses react-router via `AppRouter` (from @lotics/app-sdk/router).
+      //     The app owns its own url — embedded, that's the iframe's own url (the
+      //     host never sees it, so navigation never reloads the app); standalone,
+      //     real path URLs. Browser Back/Forward walk app screens in both.
       //   - The full-container layout pattern is preserved in `Screen`: an outer
       //     <View flex:1> claims the iframe height (index.html sets
       //     html/body/#root to 100% + #root is a flex column). Keep that chain
@@ -30592,11 +30592,13 @@ import { Card } from "@lotics/ui/card";
 import { Text } from "@lotics/ui/text";
 import { Button } from "@lotics/ui/button";
 
-// AppRouter makes the app's screens real, addressable URLs \u2014 write plain
-// react-router (useNavigate / useParams / <Link>) and it handles both modes:
-//   - Embedded in the Lotics host: the current screen lives in the host address
-//     bar (?_loc=\u2026) \u2014 shareable + refresh-survivable \u2014 and the browser Back /
-//     Forward buttons walk app screens (then leave the app).
+// AppRouter makes the app's screens real URLs \u2014 write plain react-router
+// (useNavigate / useParams / <Link>) and it handles both modes. The app owns its
+// own url, so navigation never reloads the app:
+//   - Embedded in the Lotics host: the app drives the iframe's OWN url (invisible
+//     to the user, never seen by the host). Browser Back / Forward walk app
+//     screens; the screen is also mirrored to the host url, so it's shareable and
+//     survives a full refresh (handled by AppRouter \u2014 no extra code).
 //   - Standalone at <slug>.lotics.app: a normal browser router with real path URLs.
 
 const ITEMS = [
@@ -30843,10 +30845,11 @@ the full export list at https://www.npmjs.com/package/@lotics/ui.
 ## Routing
 
 \`src/App.tsx\` ships a minimal in-app router. Write plain react-router and wrap
-your routes in \`AppRouter\` from \`@lotics/app-sdk/router\` \u2014 it makes screens real,
-addressable URLs in both modes: embedded in the Lotics host the current screen
-lives in the host address bar (\`?_loc=\u2026\`, shareable + refresh-survivable) and the
-browser Back/Forward walk app screens; standalone (\`<slug>.lotics.app\`) it's a
+your routes in \`AppRouter\` from \`@lotics/app-sdk/router\` \u2014 the app owns its own
+url, so navigation never reloads the app. Embedded in the Lotics host it drives
+the iframe's own url (invisible to the user, never seen by the host); browser
+Back/Forward walk app screens, and the screen is mirrored to the host url so it's
+shareable and survives a full refresh. Standalone (\`<slug>.lotics.app\`) it's a
 normal browser router with real path URLs. A single-screen app can drop the
 router and render one screen directly.
 
@@ -31056,9 +31059,28 @@ function buildWrapperPage(args) {
       const iframe = document.getElementById("app");
 
       // Pass the wrapper's own origin to the app via ?lotics_host= so the app
-      // SDK can origin-lock its postMessage bridge.
-      iframe.src = VITE_URL + (VITE_URL.indexOf("?") >= 0 ? "&" : "?")
-        + "lotics_host=" + encodeURIComponent(window.location.origin);
+      // SDK can origin-lock its postMessage bridge, and bake the saved screen
+      // (the wrapper url's _loc, kept current by AppRouter's mirror) into the src
+      // path so a refresh boots the app at that screen \u2014 mirrors the production
+      // host. _loc is honoured only when it resolves same-origin to the Vite
+      // server (a url param flowing into an iframe src is a redirect vector);
+      // anything else falls back to the app root.
+      const appSrc = new URL(VITE_URL);
+      const savedLoc = new URLSearchParams(window.location.search).get("_loc");
+      if (savedLoc) {
+        try {
+          const resolved = new URL(savedLoc, VITE_ORIGIN);
+          if (resolved.origin === VITE_ORIGIN) {
+            appSrc.pathname = resolved.pathname;
+            appSrc.search = resolved.search;
+            appSrc.hash = resolved.hash;
+          }
+        } catch (e) {
+          // malformed _loc -> app root
+        }
+      }
+      appSrc.searchParams.set("lotics_host", window.location.origin);
+      iframe.src = appSrc.toString();
 
       async function rpc(op, payload) {
         const res = await fetch("/_rpc", {
@@ -31163,7 +31185,6 @@ function buildWrapperPage(args) {
         });
         return out;
       }
-      var lastPushAt = 0;
       function handleUrlStateSet(payload) {
         const params = (payload && payload.params) || {};
         const sp = new URLSearchParams(window.location.search);
@@ -31176,21 +31197,9 @@ function buildWrapperPage(args) {
         });
         const qs = sp.toString();
         const url = window.location.pathname + (qs ? "?" + qs : "") + window.location.hash;
-        // push adds a back-able entry (the router adapter); replace for filter
-        // churn. Flood guard: coerce sub-100ms pushes to replace. pushState/
-        // replaceState don't fire popstate, so no echo. Mirrors the production host.
-        const now = Date.now();
-        if (payload && payload.push && now - lastPushAt > 100) {
-          lastPushAt = now;
-          window.history.pushState(null, "", url);
-        } else {
-          window.history.replaceState(null, "", url);
-        }
-        return undefined;
-      }
-      function handleUrlStateGo(payload) {
-        const delta = payload && payload.delta;
-        if (typeof delta === "number") window.history.go(delta);
+        // View-state writes in place \u2014 never a history entry. replaceState doesn't
+        // fire popstate, so no echo. Mirrors the production host.
+        window.history.replaceState(null, "", url);
         return undefined;
       }
 
@@ -31259,8 +31268,6 @@ function buildWrapperPage(args) {
             ? readUrlParams()
             : msg.op === "urlState.set"
             ? handleUrlStateSet(msg.payload)
-            : msg.op === "urlState.go"
-            ? handleUrlStateGo(msg.payload)
             : await rpc(msg.op, msg.payload);
           const ms = Math.round(performance.now() - startedAt);
           console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
@@ -31278,9 +31285,9 @@ function buildWrapperPage(args) {
         }
       });
 
-      // Browser/adapter back/forward \u2192 broadcast the new params so useUrlState and
-      // the router adapter re-hydrate (the app's own set writes use push/replace
-      // State \u2014 no popstate \u2014 so there's no echo). Mirrors the production host.
+      // Browser back/forward \u2192 broadcast the new params so useUrlState re-hydrates
+      // (the app's own set writes use replaceState \u2014 no popstate \u2014 so there's no
+      // echo). Mirrors the production host.
       window.addEventListener("popstate", function () {
         iframe.contentWindow.postMessage(
           { type: "url-state", params: readUrlParams() },

package/dist/starter_template.js

@@ -379,10 +379,10 @@ mount(
             path: "src/App.tsx",
             // Default scaffold = a minimal in-app router example (a list screen and a
             // detail screen), so a new app starts with the recommended routing shape:
-            //   - The app uses react-router via `AppRouter` (from @lotics/app-sdk/router),
-            //     which makes screens real addressable URLs — embedded, they live in the
-            //     host address bar (?_loc=…) and the browser Back/Forward walk screens;
-            //     standalone, real path URLs.
+            //   - The app uses react-router via `AppRouter` (from @lotics/app-sdk/router).
+            //     The app owns its own url — embedded, that's the iframe's own url (the
+            //     host never sees it, so navigation never reloads the app); standalone,
+            //     real path URLs. Browser Back/Forward walk app screens in both.
             //   - The full-container layout pattern is preserved in `Screen`: an outer
             //     <View flex:1> claims the iframe height (index.html sets
             //     html/body/#root to 100% + #root is a flex column). Keep that chain
@@ -397,11 +397,13 @@ import { Card } from "@lotics/ui/card";
 import { Text } from "@lotics/ui/text";
 import { Button } from "@lotics/ui/button";
 
-// AppRouter makes the app's screens real, addressable URLs — write plain
-// react-router (useNavigate / useParams / <Link>) and it handles both modes:
-//   - 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).
+// AppRouter makes the app's screens real URLs — write plain react-router
+// (useNavigate / useParams / <Link>) and it handles both modes. The app owns its
+// own url, so navigation never reloads the app:
+//   - Embedded in the Lotics host: the app drives the iframe's OWN url (invisible
+//     to the user, never seen by the host). Browser Back / Forward walk app
+//     screens; the screen is also mirrored to the host url, so it's shareable and
+//     survives a full refresh (handled by AppRouter — no extra code).
 //   - Standalone at <slug>.lotics.app: a normal browser router with real path URLs.
 
 const ITEMS = [
@@ -648,10 +650,11 @@ the full export list at https://www.npmjs.com/package/@lotics/ui.
 ## Routing
 
 \`src/App.tsx\` ships a minimal in-app router. Write plain react-router and wrap
-your routes in \`AppRouter\` from \`@lotics/app-sdk/router\` — it makes screens real,
-addressable URLs in both modes: embedded in the Lotics host the current screen
-lives in the host address bar (\`?_loc=…\`, shareable + refresh-survivable) and the
-browser Back/Forward walk app screens; standalone (\`<slug>.lotics.app\`) it's a
+your routes in \`AppRouter\` from \`@lotics/app-sdk/router\` — the app owns its own
+url, so navigation never reloads the app. Embedded in the Lotics host it drives
+the iframe's own url (invisible to the user, never seen by the host); browser
+Back/Forward walk app screens, and the screen is mirrored to the host url so it's
+shareable and survives a full refresh. Standalone (\`<slug>.lotics.app\`) it's a
 normal browser router with real path URLs. A single-screen app can drop the
 router and render one screen directly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {