@lotics/cli 0.53.0 → 0.54.2

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" }.
+ *   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.
  */
 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" }.
+ *   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.
  */
 export function buildWrapperPage(args) {
     const { app_name, app_id, workspace_id, vite_url, api_url } = args;
@@ -165,6 +168,42 @@ 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;
+      }
+      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;
+        // 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);
+        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 +265,10 @@ 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)
             : await rpc(msg.op, msg.payload);
           const ms = Math.round(performance.now() - startedAt);
           console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
@@ -242,6 +285,16 @@ 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.
+      window.addEventListener("popstate", function () {
+        iframe.contentWindow.postMessage(
+          { type: "url-state", params: readUrlParams() },
+          VITE_ORIGIN
+        );
+      });
     })();
   </script>
 </body>

package/dist/src/cli.js

@@ -30241,7 +30241,7 @@ 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_UI_VERSION = "6.1.0";
 var STARTER_FALLBACK_SDK_VERSION = "0.11.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 function buildStarterTemplate(args) {
@@ -30268,11 +30268,18 @@ function buildStarterTemplate(args) {
           },
           dependencies: {
             "@lotics/app-sdk": sdkVersion,
+            // Document preview engines for @lotics/ui FilePreview/FileGalleryModal
+            // (Word, Excel/CSV). Lazy-loaded — an app that never previews them
+            // pays no bundle cost; only node_modules size grows.
+            "@lotics/docx": "^0.1.0",
             "@lotics/ui": uiVersion,
+            "@lotics/xlsx": "^0.1.0",
             "@react-native-picker/picker": "^2.7.0",
             "expo-image": "~3.0.9",
             "lucide-react": "^0.562.0",
             "lucide-react-native": "^0.562.0",
+            // PDF preview engine for FilePreview/FileGalleryModal — also lazy-loaded.
+            "pdfjs-dist": "^6.0.0",
             react: "^19.0.0",
             "react-dom": "^19.0.0",
             "react-native": STARTER_REACT_NATIVE_VERSION,
@@ -30402,8 +30409,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",
@@ -30526,15 +30543,23 @@ 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>,
 );
 `
     },
@@ -31053,6 +31078,42 @@ 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;
+      }
+      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;
+        // 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);
+        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
@@ -31114,6 +31175,10 @@ 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)
             : await rpc(msg.op, msg.payload);
           const ms = Math.round(performance.now() - startedAt);
           console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
@@ -31130,6 +31195,16 @@ 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.
+      window.addEventListener("popstate", function () {
+        iframe.contentWindow.postMessage(
+          { type: "url-state", params: readUrlParams() },
+          VITE_ORIGIN
+        );
+      });
     })();
   </script>
 </body>
@@ -31188,7 +31263,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,7 +41,7 @@ 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_UI_VERSION = "6.1.0";
 export declare const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
 /**
  * react-native pin for scaffolded apps. Matches the monorepo frontend's pin so

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,7 +37,7 @@
  * 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_UI_VERSION = "6.1.0";
 export const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
 /**
  * react-native pin for scaffolded apps. Matches the monorepo frontend's pin so
@@ -75,11 +77,18 @@ export function buildStarterTemplate(args) {
                 },
                 dependencies: {
                     "@lotics/app-sdk": sdkVersion,
+                    // Document preview engines for @lotics/ui FilePreview/FileGalleryModal
+                    // (Word, Excel/CSV). Lazy-loaded — an app that never previews them
+                    // pays no bundle cost; only node_modules size grows.
+                    "@lotics/docx": "^0.1.0",
                     "@lotics/ui": uiVersion,
+                    "@lotics/xlsx": "^0.1.0",
                     "@react-native-picker/picker": "^2.7.0",
                     "expo-image": "~3.0.9",
                     "lucide-react": "^0.562.0",
                     "lucide-react-native": "^0.562.0",
+                    // PDF preview engine for FilePreview/FileGalleryModal — also lazy-loaded.
+                    "pdfjs-dist": "^6.0.0",
                     react: "^19.0.0",
                     "react-dom": "^19.0.0",
                     "react-native": STARTER_REACT_NATIVE_VERSION,
@@ -202,8 +211,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",
@@ -326,15 +345,23 @@ 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>,
 );
 `,
         },

package/package.json

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