@lotics/cli 0.19.0 → 0.21.0

package/dist/src/app_commands.d.ts

@@ -43,3 +43,21 @@ export declare function appDeploy(client: LoticsClient, args: {
     projectDir?: string;
     message?: string;
 }): Promise<void>;
+/**
+ * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
+ *
+ * Local dev mode for iframe apps. Spawns Vite + a postMessage RPC forwarder
+ * that bridges the iframe's hooks (useQuery, useMutate, useAction,
+ * useWorkflow) to api.lotics.ai using the CLI's stored API key. Wrapper
+ * iframe matches the production sandbox attributes exactly — null origin,
+ * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
+ *
+ * Lifecycle: Vite as a child process (HMR over WebSocket), HTTP server on a
+ * sibling port serving the wrapper HTML + the /_rpc dispatcher. SIGINT kills
+ * both cleanly.
+ */
+export declare function appDev(client: LoticsClient, args: {
+    projectDir?: string;
+    port?: number;
+    vitePort?: number;
+}): Promise<void>;

package/dist/src/app_commands.js

@@ -16,6 +16,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { buildStarterTemplate } from "./starter_template.js";
+import { startDevServer, openBrowser } from "./dev/server.js";
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
 function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
@@ -244,3 +245,56 @@ export async function appDeploy(client, args) {
             fs.unlinkSync(tmpDist);
     }
 }
+/**
+ * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
+ *
+ * Local dev mode for iframe apps. Spawns Vite + a postMessage RPC forwarder
+ * that bridges the iframe's hooks (useQuery, useMutate, useAction,
+ * useWorkflow) to api.lotics.ai using the CLI's stored API key. Wrapper
+ * iframe matches the production sandbox attributes exactly — null origin,
+ * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
+ *
+ * Lifecycle: Vite as a child process (HMR over WebSocket), HTTP server on a
+ * sibling port serving the wrapper HTML + the /_rpc dispatcher. SIGINT kills
+ * both cleanly.
+ */
+export async function appDev(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const meta = readAppMeta(projectDir);
+    // Sanity: confirm the app exists in the workspace the CLI is auth'd into.
+    // Surfaces a clear error if the project's app_id has been deleted or the
+    // CLI is pointed at the wrong workspace.
+    const app = await client.getApp(meta.app_id);
+    const handle = await startDevServer({
+        projectDir,
+        app_id: meta.app_id,
+        app_name: app.name,
+        workspace_id: meta.workspace_id,
+        api_url: client.baseUrl,
+        port: args.port,
+        vitePort: args.vitePort,
+        client,
+    });
+    await handle.ready;
+    const url = `http://localhost:${handle.port}`;
+    console.error(`\n  lotics app dev`);
+    console.error(`  app:       ${app.name} (${meta.app_id})`);
+    console.error(`  workspace: ${meta.workspace_id}`);
+    console.error(`  vite:      http://localhost:${handle.vitePort}/`);
+    console.error(`  open:      ${url}`);
+    console.error(`  rpc:       ${client.baseUrl} (via Bearer API key)\n`);
+    console.error(`  Ctrl-C to stop.\n`);
+    openBrowser(url);
+    // Block until SIGINT.
+    await new Promise((resolve) => {
+        const onSig = () => {
+            process.off("SIGINT", onSig);
+            process.off("SIGTERM", onSig);
+            resolve();
+        };
+        process.on("SIGINT", onSig);
+        process.on("SIGTERM", onSig);
+    });
+    console.error("\nStopping…");
+    await handle.stop();
+}

package/dist/src/cli.js

@@ -5,7 +5,7 @@ import readline from "node:readline";
 import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveAuth, loadConfig, saveConfig, deleteConfig, checkForUpdate } from "./config.js";
 import { VERSION } from "./version.js";
-import { appCreate, appPull, appDeploy } from "./app_commands.js";
+import { appCreate, appPull, appDeploy, appDev } from "./app_commands.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
@@ -47,6 +47,7 @@ COMMANDS
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
   lotics app deploy [-m <message>]     Build + upload current dir as a new version
+  lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -403,6 +404,7 @@ async function main() {
         console.error("  lotics app create <name> [path]      Scaffold a new app locally");
         console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
         console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+        console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
         process.exit(1);
     }
     if (command === "run" && !subcommand) {
@@ -522,6 +524,23 @@ async function main() {
             await appDeploy(client, { message });
             return;
         }
+        if (subcommand === "dev") {
+            // First positional is an optional project path (defaults to cwd).
+            // --port and --vite-port can override the wrapper / Vite ports.
+            const projectDir = toolArgs;
+            let port;
+            let vitePort;
+            for (const a of restArgs) {
+                const portMatch = /^--port=(\d+)$/.exec(a);
+                const vitePortMatch = /^--vite-port=(\d+)$/.exec(a);
+                if (portMatch)
+                    port = Number(portMatch[1]);
+                else if (vitePortMatch)
+                    vitePort = Number(vitePortMatch[1]);
+            }
+            await appDev(client, { projectDir, port, vitePort });
+            return;
+        }
         console.error(`Unknown app subcommand: ${subcommand}`);
         console.error("Run 'lotics app' for usage.");
         process.exit(1);

package/dist/src/client.d.ts

@@ -35,7 +35,10 @@ export declare const API_BASE_URL: string;
 export declare class LoticsClient {
     private apiKey;
     private workspaceId;
-    private baseUrl;
+    /** API URL the client is configured against. Read-only after construction.
+     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
+     *  shows it in the banner). */
+    readonly baseUrl: string;
     constructor(options: LoticsClientOptions);
     private throwResponseError;
     private buildHeaders;
@@ -92,6 +95,28 @@ export declare class LoticsClient {
         build_status: string;
     }>;
     getAppVersionSourceUrl(app_id: string, version_id: string): Promise<string>;
+    /**
+     * Run a query AST scoped to an app's IAM principal.
+     * Mirrors POST /v1/apps/{app_id}/query.
+     */
+    appQuery(app_id: string, ast: unknown): Promise<{
+        rows: unknown[];
+    }>;
+    /**
+     * Update records in a workspace table scoped to an app's IAM principal.
+     * Mirrors PATCH /v1/apps/{app_id}/tables/{table_id}/records.
+     */
+    appMutate(app_id: string, table_id: string, records: unknown): Promise<unknown>;
+    /**
+     * Execute an app-declared action.
+     * Mirrors POST /v1/apps/{app_id}/actions/{action_id}.
+     */
+    appAction(app_id: string, action_id: string, inputs: unknown): Promise<unknown>;
+    /**
+     * Execute a workflow by alias declared in package.json#lotics.workflows.
+     * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
+     */
+    appWorkflow(app_id: string, alias: string, inputs: unknown): Promise<unknown>;
     deployAppVersion(args: {
         app_id: string;
         source_archive: Buffer;

package/dist/src/client.js

@@ -49,6 +49,9 @@ export const API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai
 export class LoticsClient {
     apiKey;
     workspaceId;
+    /** API URL the client is configured against. Read-only after construction.
+     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
+     *  shows it in the banner). */
     baseUrl;
     constructor(options) {
         this.apiKey = options.apiKey;
@@ -153,6 +156,39 @@ export class LoticsClient {
         const result = await this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}/source`);
         return result.url;
     }
+    // ── App iframe RPC endpoints ──────────────────────────────────────────────
+    // These mirror the four ops handled by frontend/features/app_ui/app_iframe_host.tsx.
+    // The deployed iframe sends postMessage to the parent frontend, which calls
+    // these same endpoints via the user's session cookie. `lotics app dev`
+    // forwards the iframe's postMessage to these methods using the CLI's API key.
+    /**
+     * Run a query AST scoped to an app's IAM principal.
+     * Mirrors POST /v1/apps/{app_id}/query.
+     */
+    async appQuery(app_id, ast) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/query`, { ast });
+    }
+    /**
+     * Update records in a workspace table scoped to an app's IAM principal.
+     * Mirrors PATCH /v1/apps/{app_id}/tables/{table_id}/records.
+     */
+    async appMutate(app_id, table_id, records) {
+        return this.request("PATCH", `/v1/apps/${encodeURIComponent(app_id)}/tables/${encodeURIComponent(table_id)}/records`, { records });
+    }
+    /**
+     * Execute an app-declared action.
+     * Mirrors POST /v1/apps/{app_id}/actions/{action_id}.
+     */
+    async appAction(app_id, action_id, inputs) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/actions/${encodeURIComponent(action_id)}`, { inputs });
+    }
+    /**
+     * Execute a workflow by alias declared in package.json#lotics.workflows.
+     * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
+     */
+    async appWorkflow(app_id, alias, inputs) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
+    }
     async deployAppVersion(args) {
         const formData = new FormData();
         // Wrap Buffers as Uint8Array views so the Blob constructor accepts them

package/dist/src/dev/rpc_handler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stateless dispatcher: takes a parsed RPC envelope from the wrapper page
+ * and routes to the matching LoticsClient method.
+ *
+ * Errors are thrown — the HTTP server caller serializes them to a 500 with
+ * { message }. Same shape as the production iframe-host's error path.
+ */
+import { LoticsClient } from "../client.js";
+export type RpcOp = "query" | "mutate" | "action" | "workflow";
+export interface RpcRequest {
+    app_id: string;
+    op: RpcOp;
+    payload: unknown;
+}
+export declare function dispatchRpc(client: LoticsClient, body: RpcRequest): Promise<unknown>;

package/dist/src/dev/rpc_handler.js

@@ -0,0 +1,51 @@
+/**
+ * Stateless dispatcher: takes a parsed RPC envelope from the wrapper page
+ * and routes to the matching LoticsClient method.
+ *
+ * Errors are thrown — the HTTP server caller serializes them to a 500 with
+ * { message }. Same shape as the production iframe-host's error path.
+ */
+const SUPPORTED_OPS = new Set(["query", "mutate", "action", "workflow"]);
+export async function dispatchRpc(client, body) {
+    if (!body || typeof body.app_id !== "string" || typeof body.op !== "string") {
+        throw new Error("RPC envelope must include app_id and op");
+    }
+    if (!SUPPORTED_OPS.has(body.op)) {
+        throw new Error(`Unknown RPC op: ${body.op}`);
+    }
+    switch (body.op) {
+        case "query": {
+            const p = body.payload;
+            const ast = p?.ast;
+            if (ast === undefined) {
+                throw new Error("query payload must include `ast`");
+            }
+            return client.appQuery(body.app_id, ast);
+        }
+        case "mutate": {
+            const p = body.payload;
+            if (!p || typeof p.table_id !== "string") {
+                throw new Error("mutate payload must include `table_id`");
+            }
+            return client.appMutate(body.app_id, p.table_id, p.records);
+        }
+        case "action": {
+            const p = body.payload;
+            if (!p || typeof p.action_id !== "string") {
+                throw new Error("action payload must include `action_id`");
+            }
+            return client.appAction(body.app_id, p.action_id, p.inputs);
+        }
+        case "workflow": {
+            const p = body.payload;
+            if (!p || typeof p.alias !== "string") {
+                throw new Error("workflow payload must include `alias`");
+            }
+            return client.appWorkflow(body.app_id, p.alias, p.inputs);
+        }
+        default: {
+            // Unreachable — SUPPORTED_OPS gates above.
+            throw new Error(`Unhandled RPC op: ${body.op}`);
+        }
+    }
+}

package/dist/src/dev/server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `lotics app dev` orchestrator.
+ *
+ * Two child processes managed in one Node lifecycle:
+ *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
+ *      stdio inherited so Vite's own logging surfaces to the developer.
+ *   2. node:http server on <port> serving:
+ *        GET  /        → wrapper HTML (cached: no)
+ *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
+ *        *             → 404
+ *
+ * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ */
+import { type ChildProcess } from "node:child_process";
+import { LoticsClient } from "../client.js";
+export interface DevServerArgs {
+    projectDir: string;
+    app_id: string;
+    app_name: string;
+    workspace_id: string;
+    /** API URL the CLI is configured against — shown in the header banner. */
+    api_url: string;
+    /** Preferred wrapper port. If taken, auto-picks a free one. */
+    port?: number;
+    /** Preferred Vite port. If taken, auto-picks a free one. */
+    vitePort?: number;
+    client: LoticsClient;
+}
+export interface DevServerHandle {
+    port: number;
+    vitePort: number;
+    /** Resolves when both Vite + HTTP server are listening. */
+    ready: Promise<void>;
+    /** Stops Vite + HTTP server. Safe to call multiple times. */
+    stop: () => Promise<void>;
+}
+export declare function startDevServer(args: DevServerArgs): Promise<DevServerHandle>;
+/** Used by the CLI command for cross-platform `open <url>`. Best-effort —
+ *  if the platform opener isn't installed (common in WSL, headless CI, some
+ *  Linux minimal images), we log a note and keep the dev server running so
+ *  the developer can copy/paste the URL manually. */
+export declare function openBrowser(url: string): void;
+declare global {
+    type _UnusedChildProcess = ChildProcess;
+}

package/dist/src/dev/server.js

@@ -0,0 +1,198 @@
+/**
+ * `lotics app dev` orchestrator.
+ *
+ * Two child processes managed in one Node lifecycle:
+ *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
+ *      stdio inherited so Vite's own logging surfaces to the developer.
+ *   2. node:http server on <port> serving:
+ *        GET  /        → wrapper HTML (cached: no)
+ *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
+ *        *             → 404
+ *
+ * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ */
+import http from "node:http";
+import net from "node:net";
+import { spawn } from "node:child_process";
+import { dispatchRpc } from "./rpc_handler.js";
+import { buildWrapperPage } from "./wrapper_page.js";
+const DEFAULT_PORT = 5174;
+const DEFAULT_VITE_PORT = 5173;
+export async function startDevServer(args) {
+    const wrapperPort = await pickPort(args.port ?? DEFAULT_PORT);
+    const vitePort = await pickPort(args.vitePort ?? DEFAULT_VITE_PORT, wrapperPort);
+    const viteUrl = `http://localhost:${vitePort}/`;
+    const html = buildWrapperPage({
+        app_name: args.app_name,
+        app_id: args.app_id,
+        workspace_id: args.workspace_id,
+        vite_url: viteUrl,
+        api_url: args.api_url,
+    });
+    // ── Vite child ──────────────────────────────────────────────────────────
+    // `npx vite` resolves to the project's installed Vite (devDependency in
+    // the starter). Inherit stdio so the dev sees Vite's own banner + HMR logs.
+    const viteChild = spawn("npx", ["vite", "--port", String(vitePort), "--strictPort"], {
+        cwd: args.projectDir,
+        stdio: "inherit",
+        env: { ...process.env, FORCE_COLOR: "1" },
+    });
+    let stopped = false;
+    let stoppingResolve = null;
+    const stoppingPromise = new Promise((resolve) => {
+        stoppingResolve = resolve;
+    });
+    viteChild.on("exit", (code, signal) => {
+        if (!stopped) {
+            console.error(`Vite exited unexpectedly (code=${code} signal=${signal})`);
+            void stopAll();
+        }
+    });
+    // Belt and suspenders: kill Vite if the parent dies for any reason.
+    // process.on('exit') runs synchronously on every termination path
+    // (including uncaught exceptions). spawn() returns immediately so we
+    // can grab the pid before any failure mode.
+    const killViteOnExit = () => {
+        if (!viteChild.killed && viteChild.pid) {
+            try {
+                process.kill(viteChild.pid, "SIGTERM");
+            }
+            catch {
+                // process already gone — fine
+            }
+        }
+    };
+    process.once("exit", killViteOnExit);
+    // ── HTTP server ────────────────────────────────────────────────────────
+    const server = http.createServer(async (req, res) => {
+        const url = req.url ?? "/";
+        if (req.method === "GET" && (url === "/" || url === "/index.html")) {
+            res.writeHead(200, {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "no-cache, no-store, must-revalidate",
+            });
+            res.end(html);
+            return;
+        }
+        if (req.method === "POST" && url === "/_rpc") {
+            try {
+                const body = await readJson(req);
+                const startedAt = Date.now();
+                const result = await dispatchRpc(args.client, {
+                    app_id: body.app_id,
+                    op: body.op,
+                    payload: body.payload,
+                });
+                const ms = Date.now() - startedAt;
+                process.stderr.write(`[rpc] ${body.op} ${ms}ms\n`);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(result));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[rpc] ERROR ${message}\n`);
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ message }));
+            }
+            return;
+        }
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(wrapperPort, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    // ── Lifecycle ───────────────────────────────────────────────────────────
+    async function stopAll() {
+        if (stopped)
+            return;
+        stopped = true;
+        if (!viteChild.killed) {
+            viteChild.kill("SIGINT");
+        }
+        await new Promise((resolve) => server.close(() => resolve()));
+        stoppingResolve?.();
+    }
+    // Vite startup is async — we don't get a "ready" signal cleanly across
+    // versions, so we wait for a fixed grace period before resolving `ready`.
+    // The wrapper page handles iframe load failures (Vite still warming up =
+    // the iframe shows a brief refused-connection until Vite responds).
+    const ready = new Promise((resolve) => {
+        setTimeout(resolve, 800);
+    });
+    // Expose stoppingPromise on stop() so callers can await it cleanly.
+    return {
+        port: wrapperPort,
+        vitePort,
+        ready,
+        stop: async () => {
+            await stopAll();
+            await stoppingPromise;
+        },
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+async function pickPort(preferred, ...avoid) {
+    // Try preferred first. If it's taken or in `avoid`, ask the OS for any
+    // free port via listen(0).
+    if (!avoid.includes(preferred) && (await isPortFree(preferred))) {
+        return preferred;
+    }
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once("error", reject);
+        srv.listen(0, () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error("Failed to pick port"))));
+        });
+    });
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once("error", () => resolve(false));
+        srv.listen(port, () => {
+            srv.close(() => resolve(true));
+        });
+    });
+}
+async function readJson(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8");
+    if (!raw)
+        throw new Error("empty request body");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.app_id !== "string" || typeof parsed.op !== "string") {
+        throw new Error("body must include app_id and op");
+    }
+    return parsed;
+}
+/** Used by the CLI command for cross-platform `open <url>`. Best-effort —
+ *  if the platform opener isn't installed (common in WSL, headless CI, some
+ *  Linux minimal images), we log a note and keep the dev server running so
+ *  the developer can copy/paste the URL manually. */
+export function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    const child = spawn(cmd, [url], { stdio: "ignore", detached: true });
+    child.on("error", (err) => {
+        if (err.code === "ENOENT") {
+            process.stderr.write(`Note: ${cmd} not available — open ${url} manually.\n`);
+        }
+        else {
+            process.stderr.write(`Note: could not auto-open browser (${err.message}).\n`);
+        }
+    });
+    child.unref();
+}

package/dist/src/dev/wrapper_page.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Builds the wrapper HTML for `lotics app dev`.
+ *
+ * The wrapper page is served at http://localhost:<port>/ and embeds the
+ * project's Vite dev server in a sandboxed iframe with the same
+ * sandbox="allow-scripts" attribute production uses. The iframe sends
+ * postMessage RPCs to this wrapper, which forwards them to the local
+ * /_rpc endpoint, which dispatches to api.lotics.ai with the CLI's API
+ * key.
+ *
+ * Protocol matches `frontend/features/app_ui/app_iframe_host.tsx` exactly:
+ *   iframe → wrapper: { id: number, op: string, payload: unknown }
+ *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
+ */
+export interface WrapperPageArgs {
+    app_name: string;
+    app_id: string;
+    workspace_id: string;
+    vite_url: string;
+    api_url: string;
+}
+export declare function buildWrapperPage(args: WrapperPageArgs): string;

package/dist/src/dev/wrapper_page.js

@@ -0,0 +1,106 @@
+/**
+ * Builds the wrapper HTML for `lotics app dev`.
+ *
+ * The wrapper page is served at http://localhost:<port>/ and embeds the
+ * project's Vite dev server in a sandboxed iframe with the same
+ * sandbox="allow-scripts" attribute production uses. The iframe sends
+ * postMessage RPCs to this wrapper, which forwards them to the local
+ * /_rpc endpoint, which dispatches to api.lotics.ai with the CLI's API
+ * key.
+ *
+ * Protocol matches `frontend/features/app_ui/app_iframe_host.tsx` exactly:
+ *   iframe → wrapper: { id: number, op: string, payload: unknown }
+ *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
+ */
+export function buildWrapperPage(args) {
+    const { app_name, app_id, workspace_id, vite_url, api_url } = args;
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeHtml(app_name)} — lotics app dev</title>
+  <style>
+    html, body { margin: 0; height: 100%; }
+    body {
+      display: flex; flex-direction: column;
+      font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+      background: #f4f4f5;
+    }
+    header {
+      padding: 8px 14px;
+      background: #18181b;
+      color: #fafafa;
+      font-size: 12px;
+      display: flex; align-items: center; gap: 12px;
+      flex-shrink: 0;
+    }
+    header strong { font-size: 13px; }
+    header code {
+      font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+      font-size: 11px;
+      background: rgba(255,255,255,0.08);
+      padding: 1px 6px; border-radius: 3px;
+    }
+    header span { color: #a1a1aa; }
+    iframe { border: 0; flex: 1; width: 100%; background: #fff; }
+  </style>
+</head>
+<body>
+  <header>
+    <strong>${escapeHtml(app_name)}</strong>
+    <span>app_id <code>${escapeHtml(app_id)}</code></span>
+    <span>workspace <code>${escapeHtml(workspace_id)}</code></span>
+    <span>RPC → <code>${escapeHtml(api_url)}</code></span>
+  </header>
+  <iframe id="app" sandbox="allow-scripts" src="${escapeAttr(vite_url)}"></iframe>
+  <script>
+    (function () {
+      const APP_ID = ${JSON.stringify(app_id)};
+      const iframe = document.getElementById("app");
+
+      window.addEventListener("message", async function (event) {
+        if (event.source !== iframe.contentWindow) return;
+        const msg = event.data;
+        if (!msg || typeof msg.id !== "number" || typeof msg.op !== "string") return;
+        const startedAt = performance.now();
+        try {
+          const res = await fetch("/_rpc", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ app_id: APP_ID, op: msg.op, payload: msg.payload }),
+          });
+          const text = await res.text();
+          if (!res.ok) {
+            let detail = text;
+            try { detail = JSON.parse(text).message ?? text; } catch (_) {}
+            throw new Error(detail || ("HTTP " + res.status));
+          }
+          const data = JSON.parse(text);
+          const ms = Math.round(performance.now() - startedAt);
+          console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
+          iframe.contentWindow.postMessage({ id: msg.id, type: "result", data: data }, "*");
+        } catch (err) {
+          const message = err && err.message ? err.message : String(err);
+          console.error("[lotics-dev] " + msg.op + " failed:", message);
+          iframe.contentWindow.postMessage(
+            { id: msg.id, type: "error", message: message },
+            "*"
+          );
+        }
+      });
+    })();
+  </script>
+</body>
+</html>
+`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function escapeAttr(s) {
+    return escapeHtml(s).replace(/"/g, "&quot;");
+}

package/dist/src/starter_template.d.ts

@@ -10,11 +10,15 @@
  *
  * Conventions (locked decisions):
  *   - Vite + React + TypeScript (strict mode).
- *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`.
+ *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`
+ *     and imports @lotics/ui/index.css for the base style reset.
  *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
  *     endpoint rewrites root-relative paths to `/v1/apps/{id}/asset/...`.
  *     Don't switch to `base: "./"` without updating `rewriteAssetPaths`.
- *   - `@lotics/app-sdk` peer-supplied; user installs it via npm.
+ *   - react-native aliased to react-native-web so @lotics/ui's RN primitives
+ *     render in a pure-web environment. `.web.tsx` is prioritized in the
+ *     resolve.extensions list.
+ *   - @lotics/app-sdk + @lotics/ui peer-supplied; user installs both via npm.
  *   - oxlint + vitest + tsc out of the box, plus a GitHub Actions CI
  *     workflow that runs all three on every PR.
  */

package/dist/src/starter_template.js

@@ -10,11 +10,15 @@
  *
  * Conventions (locked decisions):
  *   - Vite + React + TypeScript (strict mode).
- *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`.
+ *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`
+ *     and imports @lotics/ui/index.css for the base style reset.
  *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
  *     endpoint rewrites root-relative paths to `/v1/apps/{id}/asset/...`.
  *     Don't switch to `base: "./"` without updating `rewriteAssetPaths`.
- *   - `@lotics/app-sdk` peer-supplied; user installs it via npm.
+ *   - react-native aliased to react-native-web so @lotics/ui's RN primitives
+ *     render in a pure-web environment. `.web.tsx` is prioritized in the
+ *     resolve.extensions list.
+ *   - @lotics/app-sdk + @lotics/ui peer-supplied; user installs both via npm.
  *   - oxlint + vitest + tsc out of the box, plus a GitHub Actions CI
  *     workflow that runs all three on every PR.
  */
@@ -43,9 +47,17 @@ export function buildStarterTemplate(args) {
                     test: "vitest run",
                 },
                 dependencies: {
-                    "@lotics/app-sdk": "^0.1.0",
+                    "@lotics/app-sdk": "^0.2.0",
+                    "@lotics/ui": "^0.2.0",
+                    "@react-native-picker/picker": "^2.7.0",
+                    "expo-image": "~3.0.9",
+                    "lucide-react": "^0.562.0",
+                    "lucide-react-native": "^0.562.0",
                     react: "^19.0.0",
                     "react-dom": "^19.0.0",
+                    "react-native": "0.81.0",
+                    "react-native-svg": "^15.0.0",
+                    "react-native-web": "^0.21.0",
                 },
                 devDependencies: {
                     "@testing-library/react": "^16.1.0",
@@ -99,8 +111,19 @@ import react from "@vitejs/plugin-react";
 // render endpoint rewrites those to /v1/apps/{id}/asset/... so the bundle
 // loads via the platform's asset proxy. Don't change \`base\` unless you
 // also adjust the rewrite logic in backend/api/apps.ts:rewriteAssetPaths.
+//
+// react-native → react-native-web alias lets @lotics/ui's RN primitives
+// (View, Text, Pressable, StyleSheet, etc.) render in a pure-web environment.
+// .web.tsx is prioritized in resolve.extensions so per-target variants
+// (avatar.web.tsx, wave_avatar.web.tsx) win over the native .tsx file.
 export default defineConfig({
   plugins: [react()],
+  resolve: {
+    alias: {
+      "react-native": "react-native-web",
+    },
+    extensions: [".web.tsx", ".web.ts", ".tsx", ".ts", ".jsx", ".js"],
+  },
   build: {
     outDir: "dist",
     sourcemap: true,
@@ -129,7 +152,8 @@ export default defineConfig({
         },
         {
             path: "src/main.tsx",
-            content: `import { mount } from "@lotics/app-sdk";
+            content: `import "@lotics/ui/index.css";
+import { mount } from "@lotics/app-sdk";
 import App from "./App";
 
 mount(<App />);
@@ -137,22 +161,35 @@ mount(<App />);
         },
         {
             path: "src/App.tsx",
-            // Static welcome screen — no useTable call so the freshly-deployed v1
-            // renders cleanly without needing a real table id. The user's first
-            // edit is to replace this with their actual app.
-            content: `export default function App() {
+            // Static welcome screen using @lotics/ui primitives — no useTable call
+            // so the freshly-deployed v1 renders cleanly without needing a real
+            // table id. The user's first edit is to replace this with their app.
+            content: `import { View } from "react-native";
+import { Stack } from "@lotics/ui/stack";
+import { Card } from "@lotics/ui/card";
+import { Text } from "@lotics/ui/text";
+import { Button } from "@lotics/ui/button";
+
+export default function App() {
   return (
-    <main style={{ fontFamily: "system-ui, sans-serif", padding: 24, maxWidth: 640, margin: "0 auto" }}>
-      <h1 style={{ marginBottom: 8 }}>${escapeHtml(args.app_name)}</h1>
-      <p style={{ color: "#52525b", marginBottom: 16 }}>
-        This is your new Lotics app. Edit <code>src/App.tsx</code> and run{" "}
-        <code>lotics app deploy</code> to publish.
-      </p>
-      <p style={{ color: "#52525b" }}>
-        Available hooks from <code>@lotics/app-sdk</code>:{" "}
-        <code>useTable</code>, <code>useMutate</code>, <code>useAction</code>, <code>useQuery</code>.
-      </p>
-    </main>
+    <View style={{ padding: 24, maxWidth: 640, marginHorizontal: "auto" }}>
+      <Stack gap={16}>
+        <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
+        <Card>
+          <Stack gap={8} style={{ padding: 16 }}>
+            <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>
+          </Stack>
+        </Card>
+        <Text color="muted" size="sm">
+          Hooks from @lotics/app-sdk: useTable, useMutate, useAction, useQuery, useWorkflow.
+        </Text>
+        <Button title="Get started" onPress={() => {}} color="primary" />
+      </Stack>
+    </View>
   );
 }
 `,
@@ -164,9 +201,9 @@ import { render } from "@testing-library/react";
 import App from "./App";
 
 describe("App", () => {
-  test("renders a heading", () => {
-    const { getByRole } = render(<App />);
-    expect(getByRole("heading", { level: 1 })).not.toBeNull();
+  test("renders without crashing", () => {
+    const { container } = render(<App />);
+    expect(container).not.toBeNull();
   });
 });
 `,
@@ -235,13 +272,22 @@ lotics app deploy              # build + upload as a new version
 lotics app deploy -m "what"    # with a commit-message-style note
 \`\`\`
 
-## SDK
+## SDK + UI components
 
 \`\`\`tsx
-import { mount, useTable, useMutate, useAction, useQuery } from "@lotics/app-sdk";
+import { mount, useTable, useMutate, useAction, useQuery, useWorkflow } from "@lotics/app-sdk";
+import { Stack } from "@lotics/ui/stack";
+import { Card } from "@lotics/ui/card";
+import { Button } from "@lotics/ui/button";
+import { Text } from "@lotics/ui/text";
+// ... and Grid, Dialog, DatePicker, FormPicker, BarChart, LineChart, PieChart, Metric, ProgressBar, etc.
 \`\`\`
 
-See https://lotics.ai/docs/app-sdk for the full reference.
+@lotics/ui ships React Native primitives that render via react-native-web
+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.
+
+See https://lotics.ai/docs/app-sdk for the SDK reference.
 `,
         },
     ];

package/package.json

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