@lotics/cli 0.54.0 → 0.55.0

package/dist/dev/server.js

@@ -86,7 +86,10 @@ export async function startDevServer(args) {
     // ── HTTP server ────────────────────────────────────────────────────────
     const server = http.createServer(async (req, res) => {
         const url = req.url ?? "/";
-        if (req.method === "GET" && (url === "/" || url === "/index.html")) {
+        // Route by pathname — `useUrlState` writes a query string onto the wrapper
+        // URL, so a refresh / shared link requests `/?…`; the page must still serve.
+        const pathname = url.split("?")[0];
+        if (req.method === "GET" && (pathname === "/" || pathname === "/index.html")) {
             res.writeHead(200, {
                 "Content-Type": "text/html; charset=utf-8",
                 "Cache-Control": "no-cache, no-store, must-revalidate",

package/dist/dev/wrapper_page.d.ts

@@ -24,6 +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" }.
+ *   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,6 +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" }.
+ *   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;
@@ -165,6 +168,54 @@ export function buildWrapperPage(args) {
         return undefined;
       }
 
+      // urlState.get/set — useUrlState keeps app view-state (filters, search) in
+      // THIS wrapper page's address bar so it survives refresh and is shareable,
+      // mirroring the production host. Handled locally (the URL is the store; no
+      // API hop). The wrapper page is its own top-level page, so its query string
+      // is entirely the app's. Repeated keys become arrays. Parse/merge MUST
+      // match @lotics/app-sdk parseSearch/serializeMerge and the production host
+      // (inline JS here — no module system to share the trivial copy).
+      function readUrlParams() {
+        const sp = new URLSearchParams(window.location.search);
+        const out = {};
+        sp.forEach(function (_value, key) {
+          if (key in out) return;
+          const all = sp.getAll(key);
+          out[key] = all.length > 1 ? all : all[0];
+        });
+        return out;
+      }
+      var lastPushAt = 0;
+      function handleUrlStateSet(payload) {
+        const params = (payload && payload.params) || {};
+        const sp = new URLSearchParams(window.location.search);
+        Object.keys(params).forEach(function (key) {
+          sp.delete(key);
+          const value = params[key];
+          if (value === undefined || value === null) return;
+          if (Array.isArray(value)) value.forEach(function (item) { sp.append(key, item); });
+          else sp.append(key, value);
+        });
+        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);
+        return undefined;
+      }
+
       // Streaming agent runs (op "agentRun"): the response is a stream, so it
       // can't use rpc()'s single JSON round-trip. POST /_agent_run, read the SSE
       // body, and forward chunks to the iframe as the SDK's bridged streaming
@@ -226,6 +277,12 @@ export function buildWrapperPage(args) {
             ? await handleUpload(msg.payload)
             : msg.op === "openExternal"
             ? handleOpenExternal(msg.payload)
+            : msg.op === "urlState.get"
+            ? 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);
@@ -242,6 +299,16 @@ 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.
+      window.addEventListener("popstate", function () {
+        iframe.contentWindow.postMessage(
+          { type: "url-state", params: readUrlParams() },
+          VITE_ORIGIN
+        );
+      });
     })();
   </script>
 </body>

package/dist/src/cli.js

@@ -30241,8 +30241,8 @@ import { spawn as spawn2 } from "node:child_process";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
-var STARTER_FALLBACK_UI_VERSION = "2.3.0";
-var STARTER_FALLBACK_SDK_VERSION = "0.11.0";
+var STARTER_FALLBACK_UI_VERSION = "6.1.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",
@@ -30409,8 +30412,18 @@ export default defineConfig({
     // otherwise serves them without a synthesized default export ("does not
     // provide an export named 'default'"), blanking the iframe. (Production/rollup
     // resolves the interop already, so this is dev-only.)
+    //
+    // \`react-markdown\` (@lotics/ui's Markdown renderer, reached by AgentRun and
+    // any markdown surface) pulls a transitive CJS dep, \`style-to-js\`, whose
+    // default export the dev optimizer won't synthesize unbundled ("does not
+    // provide an export named 'default'") \u2014 blanking the iframe the moment a
+    // markdown component mounts. Pre-bundling react-markdown folds the whole
+    // subtree (incl. style-to-js) into one interop'd chunk; remark-gfm (imported
+    // alongside it) is pre-bundled for the same consistency. Both are regular
+    // deps of @lotics/ui (hoisted), so they need no package.json entry here.
     include: [
       "react-native-svg",
+      "react-markdown", "remark-gfm",
       "react-native-web", "@react-native/normalize-colors",
       "inline-style-prefixer/lib/createPrefixer",
       "inline-style-prefixer/lib/plugins/crossFade",
@@ -30487,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"],
@@ -30533,73 +30550,132 @@ export default defineConfig({
       content: `import "@lotics/ui/index.css";
 import "@lotics/ui/fonts.css";
 import { PortalHost } from "@lotics/ui/portal";
+import { LoticsLocaleProvider, vi } from "@lotics/ui/locale";
 import { mount } from "@lotics/app-sdk";
 import App from "./App";
 
 // PortalHost is the render target for @lotics/ui overlays (Popover, Tooltip,
 // Dialog). Without it, Portal renders nothing \u2014 keep it wrapping the app.
+//
+// LoticsLocaleProvider supplies the kit's own strings (Pagination, sort
+// headers, select-all, the Drawer's record nav\u2026) in one language \u2014 Vietnamese
+// by default, since Lotics apps are Vietnamese. Swap to \`en\` (or your own
+// LoticsLocale pack) for another language; remove it to fall back to English.
 mount(
-  <PortalHost>
-    <App />
-  </PortalHost>,
+  <LoticsLocaleProvider locale={vi}>
+    <PortalHost>
+      <App />
+    </PortalHost>
+  </LoticsLocaleProvider>,
 );
 `
     },
     {
       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, 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 \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} />;
+}
 `
     },
     {
@@ -30678,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");
   });
 });
 `
@@ -30764,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.
 `
     }
@@ -31060,6 +31146,54 @@ function buildWrapperPage(args) {
         return undefined;
       }
 
+      // urlState.get/set \u2014 useUrlState keeps app view-state (filters, search) in
+      // THIS wrapper page's address bar so it survives refresh and is shareable,
+      // mirroring the production host. Handled locally (the URL is the store; no
+      // API hop). The wrapper page is its own top-level page, so its query string
+      // is entirely the app's. Repeated keys become arrays. Parse/merge MUST
+      // match @lotics/app-sdk parseSearch/serializeMerge and the production host
+      // (inline JS here \u2014 no module system to share the trivial copy).
+      function readUrlParams() {
+        const sp = new URLSearchParams(window.location.search);
+        const out = {};
+        sp.forEach(function (_value, key) {
+          if (key in out) return;
+          const all = sp.getAll(key);
+          out[key] = all.length > 1 ? all : all[0];
+        });
+        return out;
+      }
+      var lastPushAt = 0;
+      function handleUrlStateSet(payload) {
+        const params = (payload && payload.params) || {};
+        const sp = new URLSearchParams(window.location.search);
+        Object.keys(params).forEach(function (key) {
+          sp.delete(key);
+          const value = params[key];
+          if (value === undefined || value === null) return;
+          if (Array.isArray(value)) value.forEach(function (item) { sp.append(key, item); });
+          else sp.append(key, value);
+        });
+        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);
+        return undefined;
+      }
+
       // Streaming agent runs (op "agentRun"): the response is a stream, so it
       // can't use rpc()'s single JSON round-trip. POST /_agent_run, read the SSE
       // body, and forward chunks to the iframe as the SDK's bridged streaming
@@ -31121,6 +31255,12 @@ function buildWrapperPage(args) {
             ? await handleUpload(msg.payload)
             : msg.op === "openExternal"
             ? handleOpenExternal(msg.payload)
+            : msg.op === "urlState.get"
+            ? 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);
@@ -31137,6 +31277,16 @@ 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.
+      window.addEventListener("popstate", function () {
+        iframe.contentWindow.postMessage(
+          { type: "url-state", params: readUrlParams() },
+          VITE_ORIGIN
+        );
+      });
     })();
   </script>
 </body>
@@ -31195,7 +31345,8 @@ async function startDevServer(args) {
   process.once("exit", killViteOnExit);
   const server = http.createServer(async (req, res) => {
     const url = req.url ?? "/";
-    if (req.method === "GET" && (url === "/" || url === "/index.html")) {
+    const pathname = url.split("?")[0];
+    if (req.method === "GET" && (pathname === "/" || pathname === "/index.html")) {
       res.writeHead(200, {
         "Content-Type": "text/html; charset=utf-8",
         "Cache-Control": "no-cache, no-store, must-revalidate"

package/dist/starter_template.d.ts

@@ -11,8 +11,10 @@
  * Conventions (locked decisions):
  *   - Vite + React + TypeScript (strict mode).
  *   - Entry: src/App.tsx with `export default`. main.tsx wires
- *     `mount(<PortalHost><App/></PortalHost>)` — PortalHost is the render
- *     target @lotics/ui overlays (Popover/Tooltip/Dialog) need — and imports
+ *     `mount(<LoticsLocaleProvider locale={vi}><PortalHost><App/></PortalHost></LoticsLocaleProvider>)` —
+ *     LoticsLocaleProvider sets the kit's strings to Vietnamese (Lotics apps are
+ *     Vietnamese; swap to `en` for English); PortalHost is the render target
+ *     @lotics/ui overlays (Popover/Tooltip/Dialog) need — and imports
  *     @lotics/ui/index.css (base style reset) + @lotics/ui/fonts.css
  *     (path-independent Inter @font-face bundle — Text renders unstyled without it).
  *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
@@ -39,8 +41,8 @@ export interface StarterFile {
  * scaffolds resolve the live version via `fetchLatestNpmVersion` and only
  * fall back here when the lookup fails.
  */
-export declare const STARTER_FALLBACK_UI_VERSION = "2.3.0";
-export declare const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
+export declare const STARTER_FALLBACK_UI_VERSION = "6.1.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

@@ -11,8 +11,10 @@
  * Conventions (locked decisions):
  *   - Vite + React + TypeScript (strict mode).
  *   - Entry: src/App.tsx with `export default`. main.tsx wires
- *     `mount(<PortalHost><App/></PortalHost>)` — PortalHost is the render
- *     target @lotics/ui overlays (Popover/Tooltip/Dialog) need — and imports
+ *     `mount(<LoticsLocaleProvider locale={vi}><PortalHost><App/></PortalHost></LoticsLocaleProvider>)` —
+ *     LoticsLocaleProvider sets the kit's strings to Vietnamese (Lotics apps are
+ *     Vietnamese; swap to `en` for English); PortalHost is the render target
+ *     @lotics/ui overlays (Popover/Tooltip/Dialog) need — and imports
  *     @lotics/ui/index.css (base style reset) + @lotics/ui/fonts.css
  *     (path-independent Inter @font-face bundle — Text renders unstyled without it).
  *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
@@ -35,8 +37,11 @@
  * scaffolds resolve the live version via `fetchLatestNpmVersion` and only
  * fall back here when the lookup fails.
  */
-export const STARTER_FALLBACK_UI_VERSION = "2.3.0";
-export const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
+export const STARTER_FALLBACK_UI_VERSION = "6.1.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
@@ -92,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",
@@ -209,8 +217,18 @@ export default defineConfig({
     // otherwise serves them without a synthesized default export ("does not
     // provide an export named 'default'"), blanking the iframe. (Production/rollup
     // resolves the interop already, so this is dev-only.)
+    //
+    // \`react-markdown\` (@lotics/ui's Markdown renderer, reached by AgentRun and
+    // any markdown surface) pulls a transitive CJS dep, \`style-to-js\`, whose
+    // default export the dev optimizer won't synthesize unbundled ("does not
+    // provide an export named 'default'") — blanking the iframe the moment a
+    // markdown component mounts. Pre-bundling react-markdown folds the whole
+    // subtree (incl. style-to-js) into one interop'd chunk; remark-gfm (imported
+    // alongside it) is pre-bundled for the same consistency. Both are regular
+    // deps of @lotics/ui (hoisted), so they need no package.json entry here.
     include: [
       "react-native-svg",
+      "react-markdown", "remark-gfm",
       "react-native-web", "@react-native/normalize-colors",
       "inline-style-prefixer/lib/createPrefixer",
       "inline-style-prefixer/lib/plugins/crossFade",
@@ -287,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"],
@@ -333,73 +355,132 @@ export default defineConfig({
             content: `import "@lotics/ui/index.css";
 import "@lotics/ui/fonts.css";
 import { PortalHost } from "@lotics/ui/portal";
+import { LoticsLocaleProvider, vi } from "@lotics/ui/locale";
 import { mount } from "@lotics/app-sdk";
 import App from "./App";
 
 // PortalHost is the render target for @lotics/ui overlays (Popover, Tooltip,
 // Dialog). Without it, Portal renders nothing — keep it wrapping the app.
+//
+// LoticsLocaleProvider supplies the kit's own strings (Pagination, sort
+// headers, select-all, the Drawer's record nav…) in one language — Vietnamese
+// by default, since Lotics apps are Vietnamese. Swap to \`en\` (or your own
+// LoticsLocale pack) for another language; remove it to fall back to English.
 mount(
-  <PortalHost>
-    <App />
-  </PortalHost>,
+  <LoticsLocaleProvider locale={vi}>
+    <PortalHost>
+      <App />
+    </PortalHost>
+  </LoticsLocaleProvider>,
 );
 `,
         },
         {
             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,
-        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 — 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} />;
+}
 `,
         },
         {
@@ -478,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");
   });
 });
 `,
@@ -564,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.0",
+  "version": "0.55.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {