@lotics/cli 0.54.2 → 0.55.0

package/dist/dev/wrapper_page.d.ts

@@ -24,9 +24,9 @@
  *   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" }.
- *   url-state (useUrlState): the iframe reads/writes the wrapper's address bar
- *     via the urlState.get/set ops; the wrapper pushes { type: "url-state",
- *     params } (no id) on back/forward.
+ *   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.
  */
 export interface WrapperPageArgs {
     app_name: string;

package/dist/dev/wrapper_page.js

@@ -24,9 +24,9 @@
  *   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" }.
- *   url-state (useUrlState): the iframe reads/writes the wrapper's address bar
- *     via the urlState.get/set ops; the wrapper pushes { type: "url-state",
- *     params } (no id) on back/forward.
+ *   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.
  */
 export function buildWrapperPage(args) {
     const { app_name, app_id, workspace_id, vite_url, api_url } = args;
@@ -185,6 +185,7 @@ export function buildWrapperPage(args) {
         });
         return out;
       }
+      var lastPushAt = 0;
       function handleUrlStateSet(payload) {
         const params = (payload && payload.params) || {};
         const sp = new URLSearchParams(window.location.search);
@@ -197,10 +198,21 @@ export function buildWrapperPage(args) {
         });
         const qs = sp.toString();
         const url = window.location.pathname + (qs ? "?" + qs : "") + window.location.hash;
-        // pushState/replaceState don't fire popstate, so no echo — the app
-        // updated itself optimistically on write.
-        if (payload && payload.push) window.history.pushState(null, "", url);
-        else window.history.replaceState(null, "", url);
+        // 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);
         return undefined;
       }
 
@@ -269,6 +281,8 @@ 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);
@@ -286,9 +300,9 @@ export function buildWrapperPage(args) {
         }
       });
 
-      // Push the URL back into the app on back/forward so useUrlState
-      // re-hydrates (the app's own writes use replace/pushState — no popstate —
-      // so there's no echo). Matches the production host.
+      // 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.
       window.addEventListener("popstate", function () {
         iframe.contentWindow.postMessage(
           { type: "url-state", params: readUrlParams() },

package/dist/src/cli.js

@@ -30242,7 +30242,7 @@ import { tmpdir } from "node:os";
 
 // src/starter_template.ts
 var STARTER_FALLBACK_UI_VERSION = "6.1.0";
-var STARTER_FALLBACK_SDK_VERSION = "0.11.0";
+var STARTER_FALLBACK_SDK_VERSION = "0.40.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 function buildStarterTemplate(args) {
   const uiVersion = args.ui_version ?? `^${STARTER_FALLBACK_UI_VERSION}`;
@@ -30284,7 +30284,10 @@ function buildStarterTemplate(args) {
             "react-dom": "^19.0.0",
             "react-native": STARTER_REACT_NATIVE_VERSION,
             "react-native-svg": "^15.0.0",
-            "react-native-web": "^0.21.0"
+            "react-native-web": "^0.21.0",
+            // In-app routing for the scaffolded list→detail example. The app owns
+            // its routing; the SDK's `isEmbedded()` picks memory vs browser history.
+            "react-router-dom": "^7.0.0"
           },
           devDependencies: {
             "@testing-library/react": "^16.1.0",
@@ -30497,6 +30500,10 @@ export default defineConfig({
             // the hooks dispatcher the instant a hook (useAgentRun / useQuery)
             // runs in a rendered App tree.
             "@lotics/app-sdk",
+            // react-router-dom (App's router) also ships compiled dist JS \u2014 pin it
+            // into the shared chunk so its hooks don't split the react instance
+            // ("Invalid hook call") when a test renders the routed App tree.
+            "react-router-dom",
           ],
           esbuildOptions: {
             resolveExtensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".json"],
@@ -30565,59 +30572,110 @@ mount(
     },
     {
       path: "src/App.tsx",
-      // Welcome screen demonstrates the full-container layout pattern that
-      // real apps (dashboards, tables, full-page surfaces) rely on:
-      //   - Outer <View flex:1> claims the full iframe height (works because
-      //     index.html sets html/body/#root to 100% + #root is a flex column).
-      //   - Inner View is content-sized + centered for a card layout.
-      //
-      // We deliberately do NOT use @lotics/ui/stack for the outer chain.
-      // Stack wraps each child in an unstyled <View>, which breaks `flex: 1`
-      // propagation to children that need to claim flexible height (e.g., a
-      // scrollable table or list that fills the remaining space below a
-      // header + search).
-      // Use plain <View> with `flexDirection` + `gap` for any outer layout
-      // that hosts a flex-filling child; Stack is fine for content-sized
-      // groupings inside such a chain.
-      content: `import { View } from "react-native";
+      // 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 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
+      //     plain — @lotics/ui/stack wraps children in an unstyled <View> that
+      //     breaks `flex: 1` propagation to a fill-remaining-space child.
+      // A single-screen app can delete the router and render one Screen directly.
+      content: `import type { ReactNode } from "react";
+import { View } from "react-native";
+import { useNavigate, useParams } from "react-router-dom";
+import { AppRouter } from "@lotics/app-sdk/router";
 import { Card } from "@lotics/ui/card";
 import { Text } from "@lotics/ui/text";
 import { Button } from "@lotics/ui/button";
 
-// Outer <View flex:1> claims the full iframe height \u2014 works because
-// index.html sets html/body/#root to 100% and #root is a flex column.
-// For real layouts with a fill-remaining-space child (a scrollable
-// table/list etc.), keep this flex chain plain \u2014 @lotics/ui/stack wraps
-// each child in an unstyled <View> that breaks \`flex: 1\` propagation.
-export default function App() {
+// 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).
+//   - Standalone at <slug>.lotics.app: a normal browser router with real path URLs.
+
+const ITEMS = [
+  { id: "1", name: "First item" },
+  { id: "2", name: "Second item" },
+  { id: "3", name: "Third item" },
+];
+
+// Outer <View flex:1> claims the full iframe height \u2014 works because index.html
+// sets html/body/#root to 100% and #root is a flex column. Keep this flex chain
+// plain (not @lotics/ui/stack) so a fill-remaining-space child can claim height.
+function Screen({ children }: { children: ReactNode }) {
   return (
-    <View
-      style={{
-        flex: 1,
-        padding: 24,
-        justifyContent: "center",
-        alignItems: "center",
-      }}
-    >
-      <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>
-        <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
-        <Card>
-          <View style={{ padding: 16, gap: 8 }}>
-            <Text>This is your new Lotics app.</Text>
-            <Text color="muted">
-              Edit <Text weight="medium">src/App.tsx</Text> and run{" "}
-              <Text weight="medium">lotics app deploy</Text> to publish.
-            </Text>
+    <View style={{ flex: 1, padding: 24, alignItems: "center" }}>
+      <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>{children}</View>
+    </View>
+  );
+}
+
+function ListScreen() {
+  const navigate = useNavigate();
+  return (
+    <Screen>
+      <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
+      <Text color="muted">
+        Tap an item to open its detail screen \u2014 the app routes itself. Edit{" "}
+        <Text weight="medium">src/App.tsx</Text> and run{" "}
+        <Text weight="medium">lotics app deploy</Text> to publish.
+      </Text>
+      {ITEMS.map((item) => (
+        <Card key={item.id}>
+          <View
+            style={{
+              padding: 16,
+              flexDirection: "row",
+              alignItems: "center",
+              justifyContent: "space-between",
+              gap: 12,
+            }}
+          >
+            <Text weight="medium">{item.name}</Text>
+            <Button title="Open" color="primary" onPress={() => navigate("/item/" + item.id)} />
           </View>
         </Card>
-        <Text color="muted" size="sm">
-          Hooks from @lotics/app-sdk: useQuery, useWorkflow.
-        </Text>
-        <Button title="Get started" onPress={() => {}} color="primary" />
+      ))}
+    </Screen>
+  );
+}
+
+function ItemDetailScreen() {
+  const { id } = useParams();
+  const navigate = useNavigate();
+  const item = ITEMS.find((i) => i.id === id);
+  return (
+    <Screen>
+      {/* An in-app Back control; navigate(-1) walks the history (the browser Back
+          button walks app screens too). */}
+      <View style={{ alignItems: "flex-start" }}>
+        <Button title="Back" onPress={() => navigate(-1)} />
       </View>
-    </View>
+      <Text size="xl" weight="semibold">{item ? item.name : "Not found"}</Text>
+      <Card>
+        <View style={{ padding: 16, gap: 8 }}>
+          <Text>Detail for item {id}.</Text>
+          <Text color="muted">Reached via in-app navigation, not a host route.</Text>
+        </View>
+      </Card>
+    </Screen>
   );
 }
+
+const routes = [
+  { path: "/", element: <ListScreen /> },
+  { path: "/item/:id", element: <ItemDetailScreen /> },
+];
+
+export default function App() {
+  return <AppRouter routes={routes} />;
+}
 `
     },
     {
@@ -30696,9 +30754,9 @@ import { render } from "@testing-library/react";
 import App from "./App";
 
 describe("App", () => {
-  test("renders without crashing", () => {
+  test("renders the default route", () => {
     const { container } = render(<App />);
-    expect(container).not.toBeNull();
+    expect(container.textContent).toContain("First item");
   });
 });
 `
@@ -30782,6 +30840,16 @@ import { Text } from "@lotics/ui/text";
 in this Vite app (the alias is preconfigured in \`vite.config.ts\`). See
 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
+normal browser router with real path URLs. A single-screen app can drop the
+router and render one screen directly.
+
 See https://lotics.ai/docs/app-sdk for the SDK reference.
 `
     }
@@ -31095,6 +31163,7 @@ function buildWrapperPage(args) {
         });
         return out;
       }
+      var lastPushAt = 0;
       function handleUrlStateSet(payload) {
         const params = (payload && payload.params) || {};
         const sp = new URLSearchParams(window.location.search);
@@ -31107,10 +31176,21 @@ function buildWrapperPage(args) {
         });
         const qs = sp.toString();
         const url = window.location.pathname + (qs ? "?" + qs : "") + window.location.hash;
-        // pushState/replaceState don't fire popstate, so no echo \u2014 the app
-        // updated itself optimistically on write.
-        if (payload && payload.push) window.history.pushState(null, "", url);
-        else window.history.replaceState(null, "", url);
+        // 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);
         return undefined;
       }
 
@@ -31179,6 +31259,8 @@ 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);
@@ -31196,9 +31278,9 @@ function buildWrapperPage(args) {
         }
       });
 
-      // Push the URL back into the app on back/forward so useUrlState
-      // re-hydrates (the app's own writes use replace/pushState \u2014 no popstate \u2014
-      // so there's no echo). Matches the production host.
+      // 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.
       window.addEventListener("popstate", function () {
         iframe.contentWindow.postMessage(
           { type: "url-state", params: readUrlParams() },

package/dist/starter_template.d.ts

@@ -42,7 +42,7 @@ export interface StarterFile {
  * fall back here when the lookup fails.
  */
 export declare const STARTER_FALLBACK_UI_VERSION = "6.1.0";
-export declare const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
+export declare const STARTER_FALLBACK_SDK_VERSION = "0.40.0";
 /**
  * react-native pin for scaffolded apps. Matches the monorepo frontend's pin so
  * an app deep-typechecks `@lotics/ui`'s `.tsx` source against the SAME RN types

package/dist/starter_template.js

@@ -38,7 +38,10 @@
  * fall back here when the lookup fails.
  */
 export const STARTER_FALLBACK_UI_VERSION = "6.1.0";
-export const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
+// Must be ≥ the release that added `@lotics/app-sdk/router` (`AppRouter`, used by
+// the scaffolded App.tsx) — an older offline pin won't resolve the subpath and
+// the scaffold won't typecheck.
+export const STARTER_FALLBACK_SDK_VERSION = "0.40.0";
 /**
  * react-native pin for scaffolded apps. Matches the monorepo frontend's pin so
  * an app deep-typechecks `@lotics/ui`'s `.tsx` source against the SAME RN types
@@ -94,6 +97,9 @@ export function buildStarterTemplate(args) {
                     "react-native": STARTER_REACT_NATIVE_VERSION,
                     "react-native-svg": "^15.0.0",
                     "react-native-web": "^0.21.0",
+                    // In-app routing for the scaffolded list→detail example. The app owns
+                    // its routing; the SDK's `isEmbedded()` picks memory vs browser history.
+                    "react-router-dom": "^7.0.0",
                 },
                 devDependencies: {
                     "@testing-library/react": "^16.1.0",
@@ -299,6 +305,10 @@ export default defineConfig({
             // the hooks dispatcher the instant a hook (useAgentRun / useQuery)
             // runs in a rendered App tree.
             "@lotics/app-sdk",
+            // react-router-dom (App's router) also ships compiled dist JS — pin it
+            // into the shared chunk so its hooks don't split the react instance
+            // ("Invalid hook call") when a test renders the routed App tree.
+            "react-router-dom",
           ],
           esbuildOptions: {
             resolveExtensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".json"],
@@ -367,59 +377,110 @@ mount(
         },
         {
             path: "src/App.tsx",
-            // Welcome screen demonstrates the full-container layout pattern that
-            // real apps (dashboards, tables, full-page surfaces) rely on:
-            //   - Outer <View flex:1> claims the full iframe height (works because
-            //     index.html sets html/body/#root to 100% + #root is a flex column).
-            //   - Inner View is content-sized + centered for a card layout.
-            //
-            // We deliberately do NOT use @lotics/ui/stack for the outer chain.
-            // Stack wraps each child in an unstyled <View>, which breaks `flex: 1`
-            // propagation to children that need to claim flexible height (e.g., a
-            // scrollable table or list that fills the remaining space below a
-            // header + search).
-            // Use plain <View> with `flexDirection` + `gap` for any outer layout
-            // that hosts a flex-filling child; Stack is fine for content-sized
-            // groupings inside such a chain.
-            content: `import { View } from "react-native";
+            // 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 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
+            //     plain — @lotics/ui/stack wraps children in an unstyled <View> that
+            //     breaks `flex: 1` propagation to a fill-remaining-space child.
+            // A single-screen app can delete the router and render one Screen directly.
+            content: `import type { ReactNode } from "react";
+import { View } from "react-native";
+import { useNavigate, useParams } from "react-router-dom";
+import { AppRouter } from "@lotics/app-sdk/router";
 import { Card } from "@lotics/ui/card";
 import { Text } from "@lotics/ui/text";
 import { Button } from "@lotics/ui/button";
 
-// Outer <View flex:1> claims the full iframe height — works because
-// index.html sets html/body/#root to 100% and #root is a flex column.
-// For real layouts with a fill-remaining-space child (a scrollable
-// table/list etc.), keep this flex chain plain — @lotics/ui/stack wraps
-// each child in an unstyled <View> that breaks \`flex: 1\` propagation.
-export default function App() {
+// 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).
+//   - Standalone at <slug>.lotics.app: a normal browser router with real path URLs.
+
+const ITEMS = [
+  { id: "1", name: "First item" },
+  { id: "2", name: "Second item" },
+  { id: "3", name: "Third item" },
+];
+
+// Outer <View flex:1> claims the full iframe height — works because index.html
+// sets html/body/#root to 100% and #root is a flex column. Keep this flex chain
+// plain (not @lotics/ui/stack) so a fill-remaining-space child can claim height.
+function Screen({ children }: { children: ReactNode }) {
+  return (
+    <View style={{ flex: 1, padding: 24, alignItems: "center" }}>
+      <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>{children}</View>
+    </View>
+  );
+}
+
+function ListScreen() {
+  const navigate = useNavigate();
   return (
-    <View
-      style={{
-        flex: 1,
-        padding: 24,
-        justifyContent: "center",
-        alignItems: "center",
-      }}
-    >
-      <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>
-        <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
-        <Card>
-          <View style={{ padding: 16, gap: 8 }}>
-            <Text>This is your new Lotics app.</Text>
-            <Text color="muted">
-              Edit <Text weight="medium">src/App.tsx</Text> and run{" "}
-              <Text weight="medium">lotics app deploy</Text> to publish.
-            </Text>
+    <Screen>
+      <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
+      <Text color="muted">
+        Tap an item to open its detail screen — the app routes itself. Edit{" "}
+        <Text weight="medium">src/App.tsx</Text> and run{" "}
+        <Text weight="medium">lotics app deploy</Text> to publish.
+      </Text>
+      {ITEMS.map((item) => (
+        <Card key={item.id}>
+          <View
+            style={{
+              padding: 16,
+              flexDirection: "row",
+              alignItems: "center",
+              justifyContent: "space-between",
+              gap: 12,
+            }}
+          >
+            <Text weight="medium">{item.name}</Text>
+            <Button title="Open" color="primary" onPress={() => navigate("/item/" + item.id)} />
           </View>
         </Card>
-        <Text color="muted" size="sm">
-          Hooks from @lotics/app-sdk: useQuery, useWorkflow.
-        </Text>
-        <Button title="Get started" onPress={() => {}} color="primary" />
+      ))}
+    </Screen>
+  );
+}
+
+function ItemDetailScreen() {
+  const { id } = useParams();
+  const navigate = useNavigate();
+  const item = ITEMS.find((i) => i.id === id);
+  return (
+    <Screen>
+      {/* An in-app Back control; navigate(-1) walks the history (the browser Back
+          button walks app screens too). */}
+      <View style={{ alignItems: "flex-start" }}>
+        <Button title="Back" onPress={() => navigate(-1)} />
       </View>
-    </View>
+      <Text size="xl" weight="semibold">{item ? item.name : "Not found"}</Text>
+      <Card>
+        <View style={{ padding: 16, gap: 8 }}>
+          <Text>Detail for item {id}.</Text>
+          <Text color="muted">Reached via in-app navigation, not a host route.</Text>
+        </View>
+      </Card>
+    </Screen>
   );
 }
+
+const routes = [
+  { path: "/", element: <ListScreen /> },
+  { path: "/item/:id", element: <ItemDetailScreen /> },
+];
+
+export default function App() {
+  return <AppRouter routes={routes} />;
+}
 `,
         },
         {
@@ -498,9 +559,9 @@ import { render } from "@testing-library/react";
 import App from "./App";
 
 describe("App", () => {
-  test("renders without crashing", () => {
+  test("renders the default route", () => {
     const { container } = render(<App />);
-    expect(container).not.toBeNull();
+    expect(container.textContent).toContain("First item");
   });
 });
 `,
@@ -584,6 +645,16 @@ import { Text } from "@lotics/ui/text";
 in this Vite app (the alias is preconfigured in \`vite.config.ts\`). See
 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
+normal browser router with real path URLs. A single-screen app can drop the
+router and render one screen directly.
+
 See https://lotics.ai/docs/app-sdk for the SDK reference.
 `,
         },

package/dist/starter_template.test.js

@@ -77,4 +77,24 @@ describe("buildStarterTemplate", () => {
         expect(pkg.dependencies["@lotics/ui"]).toBe(`^${STARTER_FALLBACK_UI_VERSION}`);
         expect(pkg.dependencies["@lotics/app-sdk"]).toBe(`^${STARTER_FALLBACK_SDK_VERSION}`);
     });
+    test("package.json includes react-router-dom for the in-app router example", () => {
+        const pkg = JSON.parse(fileNamed(buildStarterTemplate(baseArgs), "package.json"));
+        expect(pkg.dependencies["react-router-dom"]).toBeDefined();
+    });
+    test("App.tsx routes via the SDK's AppRouter (real addressable URLs, both modes)", () => {
+        // The scaffold demonstrates the recommended shape: the app uses react-router
+        // through `AppRouter`, which makes screens addressable URLs in both modes.
+        // Guards against the wiring being dropped back to a single screen.
+        const app = fileNamed(buildStarterTemplate(baseArgs), "src/App.tsx");
+        expect(app).toContain('from "react-router-dom"');
+        expect(app).toContain('from "@lotics/app-sdk/router"');
+        expect(app).toContain("<AppRouter routes={routes}");
+    });
+    test("vite.config.ts pins react-router-dom into the vitest web optimizer (else the routed App test splits the react instance)", () => {
+        // react-router-dom ships compiled dist JS; un-pinned, its hooks load a second
+        // react instance under vitest and the scaffold's App.test fails with "Invalid
+        // hook call" the moment it renders RouterProvider.
+        const config = fileNamed(buildStarterTemplate(baseArgs), "vite.config.ts");
+        expect(config).toMatch(/include:\s*\[[\s\S]*"react-router-dom"/);
+    });
 });

package/package.json

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