@lotics/app-sdk 0.37.0 → 0.38.1

package/AGENTS.md

@@ -53,7 +53,11 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   data→UI adapter; the SDK never imports `@lotics/ui`) for
   `<FileThumbnail file={{ id, filename, mimeType, url }} uploading={f.status === "uploading"} />`;
   `sendDisabled` gates on `uploading` and the send payload is `fileIds`. Don't hand-roll
-  `createObjectURL`/upload/revoke per app.
+  `createObjectURL`/upload/revoke per app. For a full add-files SCREEN (not the composer pill), map
+  each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file }`, else
+  `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `@lotics/ui`
+  `FileGrid`'s `uploads` — it renders the uploading/error/retry tiles itself (see the kit AGENTS.md
+  Attachments recipe).
 - **List members** — **`useMembers(opts?)`** → `{ members: {id,name,email,image}[], loading, error }`
   — the candidate set for an assign/picker. Gated: the app must declare a `member`-typed input
   (`opts.group` restricts to a declared group). Render with `@lotics/ui` `MemberSelect` / `MemberChip`.
@@ -70,6 +74,10 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   client-side advisory — pass `coords` to a workflow to record where an action happened.
 - **Recents** — **`useRecents(key, max)`** → most-recent-first, deduped, capped, `localStorage`-backed
   (web-only, which is why it's here, not in `@lotics/ui`). Feeds a `Combobox`'s `recentOptions`.
+- **Shareable view-state (filters in the URL)** — **`useUrlState(shape)`** → `[values, setValues]`,
+  keeping a declared slice of state (filters, search, sort, the active tab) in the **address bar** so a
+  view survives refresh and is shareable/bookmarkable; `setValues(patch, { push })` makes it
+  back/forward-navigable. Build `shape` from **`urlParam`** codecs. See *Shareable filters in the URL*.
 - **Optimistic mutation glue** — **`useOptimistic()`** → reconcile a workflow mutation against the
   query cache for an interactive (calendar/kanban/grid) app. See the data-bound recipe.
 - **Infra** — **`mount(opts?)`** boots the app + analytics (call once at entry; PostHog is automatic,
@@ -140,8 +148,13 @@ compose these, don't hand-roll search:
 - **`useRecents`** — persist the picked option; pass its list as `recentOptions`.
 
 Fetch detail on select with a SECOND parameterized query (a unique-code `equals`, or a link
-`has_any_of [record_id]`) — never a bare full-table load. Filtering a record by its *own* id isn't a
-compilable AST shape; filter by a unique field value.
+`has_any_of [record_id]`) — never a bare full-table load. To fetch a record by its **own id**, use the
+field-less **`record_id` system condition** (a sibling of `locked`/`current_member`, NOT a `field_key`):
+`useQuery(alias, {}, { filter: { node_type: "condition", type: "record_id", operator: "is_any_of", value:
+[id] } })` (`is_none_of` excludes). Works on any row-level query; a *grouped* query collapses rows so it's
+rejected there. A link `has_any_of [record_id]` matches a *related* record; `record_id` matches the row's
+own id — the only way, since a record has no field holding its own id. **Prefer a link/join when an actual
+relationship exists**; reach for `record_id` only when your starting point is a bare id (e.g. a drill row).
 
 ## Browse + sort + filter (the record picker)
 
@@ -183,15 +196,24 @@ Two of the most common cells render the platform way with zero hand-rolling; han
 ## Previewing files
 
 Render any uploaded file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`; never
-hand-roll per-type rendering.
-
-- **`FileGalleryModal`** (full-screen viewer) delegates to **`FilePreview`** (single-file), dispatching
-  by MIME; the frontend gallery uses the same renderer.
+hand-roll per-type rendering, and don't fall back to `openExternal` for a preview (that's "download /
+open elsewhere", not viewing).
+
+- **`FileGalleryModal`** (full-screen viewer: toolbar = filename · counter · ⋯actions · close-✕, plus
+  prev/next + ESC) delegates to **`FilePreview`** (single-file), dispatching by MIME; the frontend
+  gallery uses the same renderer. Wire `onFilePress` → a `number|null` `activeIndex`.
+- **PDF renders INLINE** — bytes fetched and painted to a canvas (with a selectable text layer) via
+  `pdfjs-dist`, NOT a native `<iframe>` viewer: a nested PDF browsing context is blocked inside the
+  sandboxed, cross-origin app iframe; a canvas isn't, so preview works. `pdfjs-dist` ships in the app
+  starter (lazy-loaded — non-PDF apps pay no bundle cost).
 - File cells already carry presigned URLs — decode with **`readFiles`** → `AppFile[]`, map to
   `DisplayFile` (`mime_type`→`mimeType`, `thumbnail_url`→`thumbnailUrl`). No round-trip, no URL
   derivation, no server-side doc→PDF (rendering is client-side).
-- Word/Excel preview lazy-imports `@lotics/docx` + `@lotics/xlsx` (optional peer deps) — an image/PDF
-  app installs neither. `@lotics/ui` is i18n/analytics-free: pass `labels` + an `onError`.
+- PDF (`pdfjs-dist`), Word (`@lotics/docx`), and Excel/CSV (`@lotics/xlsx`) all ship in the app starter,
+  lazy-imported — an app that never previews a type pays no bundle cost. Excel renders to a canvas with
+  live formula recalc; Word renders OOXML to the DOM. `@lotics/ui` is i18n/analytics-free: pass `labels`
+  + an `onError`. The toolbar's "open in new tab" can't pop a window in the sandbox — pass `onOpenExternal`
+  wired to the SDK's `openExternal` (omit it and the action hides).
 
 ## Composable optional filters (one query, many scopes)
 
@@ -228,6 +250,36 @@ stops constraining instead of erroring (no-op for all-required queries).
 independently. Keep a scope that must always apply `required` (a missing required param 400s). Typos
 can't widen — deploy rejects a `{{params.x}}` with no declared param.
 
+## Shareable filters in the URL (`useUrlState`)
+
+The filters above are the query's *server* params; **`useUrlState`** is their *client* home — keep them in
+the address bar and a filtered view survives refresh, is shareable/bookmarkable as a link, and (with
+`{ push: true }`) is back/forward-navigable. The hook drives the host's URL over the bridge; the app
+can't touch the cross-origin host URL itself. Standalone apps drive their own URL — same code.
+
+```tsx
+const [filters, setFilters] = useUrlState({
+  q:      urlParam.string.withDefault(""),
+  status: urlParam.enum(["open", "won", "lost"]),         // optional → omitted when unset
+  tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
+  page:   urlParam.number.withDefault(1),
+});
+// filters → { q: string; status?: "open"|"won"|"lost"; tags: string[]; page: number }
+const { rows } = usePaginatedQuery("search", { keyword: filters.q, status: filters.status }, { pageSize: 50 });
+setFilters({ status: "won" });                  // merge, replace history → URL ?status=won
+setFilters({ page: 2 }, { push: true });        // back-able navigation
+```
+
+- **`urlParam`** codecs: `string` / `number` / `boolean` / `isoDate` / `enum([...])` / `arrayOf(inner)`,
+  each `.withDefault(v)` to make it required. **Defaults are omitted from the URL** (`page=1` never
+  appears) — links carry only what changed.
+- **The URL is the only store** — `filters` is decoded fresh each render; don't mirror it into `useState`.
+- **Declared keys only.** The app touches just the keys in `shape`; every other param (a second
+  `useUrlState`, the framework's own) is preserved on write — no namespace rule to remember.
+- **Search box:** keep the live input in local `useState` and commit to `setFilters` on a **debounce** —
+  in an embedded app each `setFilters` is a cross-frame write. Default is *replace* (no history entry);
+  reserve `{ push: true }` for committed navigations (open a detail, switch a major tab).
+
 ---
 
 ## Recipes (app actions beyond the hooks)

package/dist/src/hooks.d.ts

@@ -414,7 +414,12 @@ export interface UseAgentRun<TInput, TOutput> {
      *  structured output (undefined for a free-text or failed run). Calling again
      *  aborts any run still in flight. */
     run: (input: TInput, opts: AgentRunOptions) => Promise<TOutput | undefined>;
+    /** Stop listening locally (no server effect) — the run keeps executing
+     *  server-side and its result lands in the session history. Used on unmount. */
     abort: () => void;
+    /** Explicitly stop the run server-side (saves tokens) AND locally. Wire a
+     *  user-facing "Stop" button to this, not `abort`. */
+    cancel: () => void;
     status: "idle" | "streaming" | "completed" | "error";
     /** The agent's streamed reasoning / answer text, accumulating live. */
     text: string;

package/dist/src/hooks.js

@@ -351,6 +351,10 @@ export function useMembers(opts) {
 export function useAgentRun(alias) {
     const [state, setState] = useState(null);
     const handleRef = useRef(null);
+    // The run id of the in-flight run (reported by the transport off the response
+    // header). Lets the hook poll the run to completion if the stream connection
+    // drops, and cancel it server-side on an explicit stop.
+    const runIdRef = useRef(null);
     // Guards setState after unmount and aborts any in-flight run on unmount, so a
     // stream never keeps writing to a dead component (or leaks the transport).
     const mountedRef = useRef(true);
@@ -367,6 +371,7 @@ export function useAgentRun(alias) {
     }, []);
     const run = useCallback((input, opts) => {
         handleRef.current?.abort();
+        runIdRef.current = null;
         let acc = initialAgentRunState();
         let buffer = "";
         let aborted = false;
@@ -382,6 +387,8 @@ export function useAgentRun(alias) {
             for (const c of chunks)
                 acc = reduceAgentChunk(acc, c);
             safeSetState({ ...acc });
+        }, (runId) => {
+            runIdRef.current = runId;
         });
         // Wrap abort so a stop (user or unmount) marks the run cancelled and clears
         // the partial state back to idle — `done` resolves cleanly, never an error.
@@ -406,9 +413,27 @@ export function useAgentRun(alias) {
             captureAppEvent("app_agent_run", { alias, ok: acc.status !== "error" });
             return acc.output;
         })
-            .catch((err) => {
+            .catch(async (err) => {
             if (aborted)
                 return undefined;
+            // The stream connection dropped, but the run is decoupled from it and
+            // keeps executing server-side. Poll the persisted run to completion and
+            // surface its result instead of a network error — work is never lost.
+            const runId = runIdRef.current;
+            if (runId) {
+                const settled = await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current);
+                if (settled && !aborted) {
+                    acc =
+                        settled.status === "completed"
+                            ? { ...acc, status: "completed", output: settled.output ?? acc.output }
+                            : { ...acc, status: "error", error: settled.error_message ?? "The run was stopped." };
+                    safeSetState(acc);
+                    captureAppEvent("app_agent_run", { alias, ok: settled.status === "completed" });
+                    return acc.output;
+                }
+                if (aborted)
+                    return undefined;
+            }
             acc = { ...acc, status: "error", error: err.message };
             safeSetState(acc);
             captureAppEvent("app_agent_run", { alias, ok: false });
@@ -416,9 +441,17 @@ export function useAgentRun(alias) {
         });
     }, [alias, safeSetState]);
     const abort = useCallback(() => handleRef.current?.abort(), []);
+    const cancel = useCallback(() => {
+        // Stop server-side too (saves tokens on an unwanted run), then locally.
+        const runId = runIdRef.current;
+        if (runId)
+            void rpc("agentRun.cancel", { run_id: runId }).catch(() => { });
+        handleRef.current?.abort();
+    }, []);
     return {
         run,
         abort,
+        cancel,
         status: state?.status ?? "idle",
         text: state?.text ?? "",
         steps: state?.steps ?? [],
@@ -426,6 +459,29 @@ export function useAgentRun(alias) {
         error: state?.error,
     };
 }
+/**
+ * Poll a single run until it leaves `running` — the resume path when a run's
+ * stream connection drops mid-flight. Bounded just past the server-side max-run
+ * cap so a hung run can never poll forever, and bails the moment the caller
+ * aborts or unmounts. Returns the settled run, or null if it never settled.
+ */
+async function pollAgentRunToSettle(runId, cancelled) {
+    const deadline = Date.now() + 11 * 60_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 2500));
+        if (cancelled())
+            return null;
+        try {
+            const { run } = await rpc("agentRun.get", { run_id: runId });
+            if (run.status !== "running")
+                return run;
+        }
+        catch {
+            // transient read failure — keep polling until the deadline
+        }
+    }
+    return null;
+}
 /**
  * The run history of a session, oldest-first — the persisted outputs the app
  * renders as a session log (NOT a chat: a flat list of past runs). Refetch

package/dist/src/index.d.ts

@@ -39,3 +39,7 @@ export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";
 export type { RecentsApi, RecentsOptions } from "./use_recents.js";
+export { useUrlState } from "./use_url_state.js";
+export type { UrlStateShape, UrlStateValues, SetUrlStateOptions } from "./use_url_state.js";
+export { urlParam } from "./url_params.js";
+export type { UrlParamCodec, OptionalUrlParamCodec, UrlParams, UrlParamValue, } from "./url_params.js";

package/dist/src/index.js

@@ -27,3 +27,5 @@ export { readSelect } from "./select.js";
 export { row, readLinks, readFiles, readLocked } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";
+export { useUrlState } from "./use_url_state.js";
+export { urlParam } from "./url_params.js";

package/dist/src/rpc.d.ts

@@ -1,3 +1,4 @@
+import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
 /**
  * RPC bridge for a custom-code app's data operations.
  *
@@ -18,7 +19,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;
@@ -58,10 +59,24 @@ export interface AppContext {
     comments_enabled: boolean;
 }
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;
+/** Read the current app-owned query params — bridged: ask the host; standalone:
+ *  the page's own query string. */
+export declare function getUrlParams(): Promise<UrlParams>;
+/** Merge `patch` into the query string (each key set, or cleared when its value
+ *  is `undefined`). `push` adds a history entry (back-able); otherwise it
+ *  replaces in place — the default, so filter churn doesn't flood history. */
+export declare function setUrlParams(patch: UrlParamsPatch, push: boolean): Promise<void>;
+/** Synchronous best-effort snapshot for first paint. Standalone reads its own
+ *  URL (no flash); bridged can't read the cross-origin host URL synchronously,
+ *  so it returns `{}` and the hook hydrates via `getUrlParams()` on mount. */
+export declare function peekUrlParams(): UrlParams;
+/** Subscribe to external query changes — back/forward, or an edited URL.
+ *  Bridged: the host's `url-state` broadcast; standalone: `popstate`. */
+export declare function subscribeUrlParams(cb: (params: UrlParams) => void): () => void;
 /**
  * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
  * (the caller parses it via `agent_stream`); `done` settles when the stream
  * ends. Bridged: the host opens the SSE with its session and forwards chunks;
  * standalone: the SDK reads the public endpoint's body directly.
  */
-export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void): AgentRunHandle;
+export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void, onRunId?: (runId: string) => void): AgentRunHandle;

package/dist/src/rpc.js

@@ -1,5 +1,6 @@
 import { promptForPassword } from "./password_gate.js";
 import { runUploadPipeline } from "./upload/pipeline.js";
+import { parseSearch, serializeMerge, } from "./url_params.js";
 /**
  * The embedding Lotics host's origin — present iff the app is bridged.
  *
@@ -23,8 +24,49 @@ export function rpc(op, payload) {
         ? rpcBridged(op, payload, hostOrigin)
         : rpcStandalone(op, payload);
 }
+// ── URL state (the address bar as shareable view-state) ─────────────────────
+//
+// `useUrlState` keeps a declared slice of app state in the host's address bar so
+// a filtered view survives refresh and is shareable/bookmarkable. An embedded
+// app can't read or write the cross-origin host URL directly, so reads/writes
+// flow over the bridge (the host drives its own router); a standalone app owns
+// its top-level URL and the same ops resolve against `window.location`.
+/** Read the current app-owned query params — bridged: ask the host; standalone:
+ *  the page's own query string. */
+export function getUrlParams() {
+    return rpc("urlState.get", {});
+}
+/** Merge `patch` into the query string (each key set, or cleared when its value
+ *  is `undefined`). `push` adds a history entry (back-able); otherwise it
+ *  replaces in place — the default, so filter churn doesn't flood history. */
+export function setUrlParams(patch, push) {
+    return rpc("urlState.set", { params: patch, push });
+}
+/** Synchronous best-effort snapshot for first paint. Standalone reads its own
+ *  URL (no flash); bridged can't read the cross-origin host URL synchronously,
+ *  so it returns `{}` and the hook hydrates via `getUrlParams()` on mount. */
+export function peekUrlParams() {
+    return getHostOrigin() ? {} : parseSearch(window.location.search);
+}
+/** Subscribe to external query changes — back/forward, or an edited URL.
+ *  Bridged: the host's `url-state` broadcast; standalone: `popstate`. */
+export function subscribeUrlParams(cb) {
+    if (getHostOrigin()) {
+        ensureListener();
+        urlStateSubscribers.add(cb);
+        return () => {
+            urlStateSubscribers.delete(cb);
+        };
+    }
+    const handler = () => cb(parseSearch(window.location.search));
+    window.addEventListener("popstate", handler);
+    return () => window.removeEventListener("popstate", handler);
+}
 const pending = new Map();
 const streaming = new Map();
+/** `useUrlState` subscribers (bridged transport) — notified when the host pushes
+ *  a `url-state` broadcast after an external navigation. */
+const urlStateSubscribers = new Set();
 let nextRpcId = 0;
 let listenerInstalled = false;
 function ensureListener() {
@@ -36,7 +78,16 @@ function ensureListener() {
         if (event.source !== window.parent || event.origin !== getHostOrigin())
             return;
         const msg = event.data;
-        if (!msg || typeof msg.id !== "number")
+        if (!msg)
+            return;
+        // Broadcast (no id): the host pushes the new query params after an external
+        // navigation (back/forward, an edited URL) so `useUrlState` re-hydrates.
+        if (msg.type === "url-state" && msg.params && typeof msg.params === "object") {
+            for (const cb of urlStateSubscribers)
+                cb(msg.params);
+            return;
+        }
+        if (typeof msg.id !== "number")
             return;
         // Single-response ops.
         const handler = pending.get(msg.id);
@@ -48,11 +99,15 @@ function ensureListener() {
                 handler.reject(new Error(msg.message ?? "RPC failed"));
             return;
         }
-        // Streaming op (agentRun): chunk* → end | error.
+        // Streaming op (agentRun): run-id? chunk* → end | error.
         const stream = streaming.get(msg.id);
         if (!stream)
             return;
-        if (msg.type === "stream-chunk") {
+        if (msg.type === "run-id") {
+            if (typeof msg.runId === "string")
+                stream.onRunId?.(msg.runId);
+        }
+        else if (msg.type === "stream-chunk") {
             if (typeof msg.chunk === "string")
                 stream.onText(msg.chunk);
         }
@@ -81,17 +136,19 @@ function rpcBridged(op, payload, host) {
  * ends. Bridged: the host opens the SSE with its session and forwards chunks;
  * standalone: the SDK reads the public endpoint's body directly.
  */
-export function rpcAgentRun(payload, onText) {
+export function rpcAgentRun(payload, onText, onRunId) {
     const hostOrigin = getHostOrigin();
-    return hostOrigin ? agentRunBridged(payload, onText, hostOrigin) : agentRunStandalone(payload, onText);
+    return hostOrigin
+        ? agentRunBridged(payload, onText, hostOrigin, onRunId)
+        : agentRunStandalone(payload, onText, onRunId);
 }
-function agentRunBridged(payload, onText, host) {
+function agentRunBridged(payload, onText, host, onRunId) {
     ensureListener();
     const id = nextRpcId++;
     let settleDone = () => { };
     const done = new Promise((resolve, reject) => {
         settleDone = resolve;
-        streaming.set(id, { onText, resolve, reject });
+        streaming.set(id, { onText, onRunId, resolve, reject });
         window.parent.postMessage({ id, op: "agentRun", payload }, host);
     });
     return {
@@ -107,7 +164,7 @@ function agentRunBridged(payload, onText, host) {
         },
     };
 }
-function agentRunStandalone(payload, onText) {
+function agentRunStandalone(payload, onText, onRunId) {
     const controller = new AbortController();
     const done = (async () => {
         const { app_id } = await boot();
@@ -124,6 +181,9 @@ function agentRunStandalone(payload, onText) {
             const text = await res.text().catch(() => "");
             throw new Error(text || `HTTP ${res.status}`);
         }
+        const runId = res.headers.get("x-app-agent-run-id");
+        if (runId)
+            onRunId?.(runId);
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         try {
@@ -307,6 +367,10 @@ function rpcStandalone(op, payload) {
             return standaloneWorkflow(payload);
         case "agentRuns":
             return standaloneAgentRuns(payload);
+        case "agentRun.get":
+            return standaloneAgentRunGet(payload);
+        case "agentRun.cancel":
+            return standaloneAgentRunCancel(payload);
         case "upload":
             return standaloneUpload(payload.file);
         case "members":
@@ -315,6 +379,11 @@ function rpcStandalone(op, payload) {
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
+        case "urlState.get":
+            // Standalone is a top-level page — its own query string IS the store.
+            return Promise.resolve(parseSearch(window.location.search));
+        case "urlState.set":
+            return standaloneUrlStateSet(payload);
         case "comments.list":
         case "comments.create":
         case "comments.update":
@@ -363,6 +432,16 @@ function openValidatedUrl(url) {
 async function standaloneOpenExternal(p) {
     openValidatedUrl(p.url);
 }
+async function standaloneUrlStateSet(p) {
+    const search = serializeMerge(window.location.search, p.params ?? {});
+    const url = window.location.pathname + (search ? `?${search}` : "") + window.location.hash;
+    // pushState/replaceState don't fire popstate, so subscribers aren't notified
+    // here — the hook updates its own state optimistically on write.
+    if (p.push)
+        window.history.pushState(null, "", url);
+    else
+        window.history.replaceState(null, "", url);
+}
 async function standaloneContext() {
     const info = await resolveAppInfo();
     return {
@@ -402,6 +481,24 @@ async function standaloneAgentRuns(p) {
     }));
     return { runs: r.runs ?? [] };
 }
+/** Poll read for a single run — follows a run to completion after its stream
+ *  connection drops. The caller types the run shape via `rpc<T>`. */
+async function standaloneAgentRunGet(p) {
+    const { app_id } = await boot();
+    const r = (await apiCall("GET", `/v1/apps/${app_id}/agent-runs/${encodeURIComponent(p.run_id)}`, undefined, {
+        appId: app_id,
+    }));
+    return { run: r.run };
+}
+/** Request server-side cancellation of an in-flight run (an explicit user stop,
+ *  distinct from merely closing the stream). */
+async function standaloneAgentRunCancel(p) {
+    const { app_id } = await boot();
+    await apiCall("POST", `/v1/apps/${app_id}/agent-runs/${encodeURIComponent(p.run_id)}/cancel`, {}, {
+        appId: app_id,
+    });
+    return { ok: true };
+}
 async function standaloneUpload(file) {
     if (!(file instanceof File)) {
         throw new Error("upload payload must include a File");

package/dist/src/url_params.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Typed codecs that map URL query-string values (always strings, or string
+ * arrays for repeated keys) to and from the typed view-state an app keeps in
+ * the address bar — the engine behind `useUrlState`.
+ *
+ * Two properties make the URLs clean and the round-trip lossless:
+ *
+ *  - **Default-omission.** A codec built with `.withDefault(d)` encodes the
+ *    default value to `undefined` — i.e. the key is dropped from the URL. So a
+ *    filter at its default (`page=1`, `q=""`) never appears, and the shared
+ *    link carries only what the user actually changed.
+ *  - **Declared keys only.** `decodeAll`/`encodePatch` touch exactly the keys the
+ *    app declared. Every other query param (`lotics_host`, `__mock`, a param a
+ *    second `useUrlState` owns, a future host param) is read past and preserved
+ *    on write — the merge is the namespace boundary, so no reserved-prefix rule
+ *    is needed.
+ *
+ * Self-contained on purpose: the SDK publishes to npm as a bundle-free `dist/`,
+ * so it carries no workspace deps (no `@lotics/shared`). These are plain pure
+ * functions — a frontend that later wants the same value⇄query codec can import
+ * them from here rather than growing a second copy.
+ */
+/** A query value as it appears in the URL: a single string, or an array for a
+ *  repeated key (`?tag=a&tag=b`). Absent keys are simply missing from the map. */
+export type UrlParamValue = string | string[];
+/** The current query string decoded to a map (present keys only). */
+export type UrlParams = Record<string, UrlParamValue>;
+/** A write: each key set to its encoded value, or `undefined` to clear it. Only
+ *  the keys present are touched; others in the URL are preserved (a merge). */
+export type UrlParamsPatch = Record<string, UrlParamValue | undefined>;
+/**
+ * A reversible mapping between a typed value `T` and its URL representation.
+ * Methods (not function-typed properties) so a concrete `UrlParamCodec<string>`
+ * stays assignable to `UrlParamCodec<unknown>` for the `useUrlState` codec map.
+ */
+export interface UrlParamCodec<T> {
+    /** Raw query value (or `undefined` when the key is absent) → typed value. */
+    decode(raw: UrlParamValue | undefined): T;
+    /** Typed value → raw query value, or `undefined` to omit the key. */
+    encode(value: T): UrlParamValue | undefined;
+}
+/** A codec whose value is optional (absent key → `undefined`), refinable to a
+ *  required codec with a fallback via `.withDefault`. */
+export interface OptionalUrlParamCodec<T> extends UrlParamCodec<T | undefined> {
+    /** Make the value required: an absent key decodes to `fallback`, and a value
+     *  equal to `fallback` encodes to nothing (kept out of the URL). */
+    withDefault(fallback: T): UrlParamCodec<T>;
+}
+declare function enumCodec<const V extends readonly string[]>(values: V): OptionalUrlParamCodec<V[number]>;
+declare function arrayOf<T>(inner: UrlParamCodec<T | undefined>): OptionalUrlParamCodec<T[]>;
+/**
+ * The codec builders an app composes into a `useUrlState` shape. Each base
+ * builder yields an optional codec (absent key → `undefined`); add
+ * `.withDefault(v)` to make it required and keep the default out of the URL.
+ *
+ *   useUrlState({
+ *     q:      urlParam.string.withDefault(""),
+ *     status: urlParam.enum(["open", "won", "lost"]),       // optional
+ *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
+ *     from:   urlParam.isoDate,                              // optional Date
+ *     page:   urlParam.number.withDefault(1),
+ *   })
+ */
+export declare const urlParam: {
+    readonly string: OptionalUrlParamCodec<string>;
+    readonly number: OptionalUrlParamCodec<number>;
+    readonly boolean: OptionalUrlParamCodec<boolean>;
+    readonly isoDate: OptionalUrlParamCodec<Date>;
+    readonly enum: typeof enumCodec;
+    readonly arrayOf: typeof arrayOf;
+};
+/** Decode the declared keys out of a params map into typed values. */
+export declare function decodeAll<D extends Record<string, UrlParamCodec<unknown>>>(defs: D, params: UrlParams): {
+    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
+};
+/** Encode a partial set of declared values into a patch (each key → value or
+ *  `undefined` to clear). Only the keys present in `values` are emitted, so the
+ *  write merges and leaves every other query param untouched. */
+export declare function encodePatch<D extends Record<string, UrlParamCodec<unknown>>>(defs: D, values: Partial<{
+    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
+}>): UrlParamsPatch;
+/** Parse a `location.search` string into a params map (repeated keys → array). */
+export declare function parseSearch(search: string): UrlParams;
+/** Apply a patch to a `location.search` string and return the new query string
+ *  (no leading `?`). Each patch key is replaced; `undefined` clears it; every
+ *  other existing param is preserved. */
+export declare function serializeMerge(search: string, patch: UrlParamsPatch): string;
+/** Apply a patch to an in-memory params map (the optimistic local mirror). */
+export declare function applyPatch(params: UrlParams, patch: UrlParamsPatch): UrlParams;
+/** Shallow value-equality over two params maps — used to drop echoed updates so
+ *  an app's own write doesn't re-render it a second time. */
+export declare function paramsEqual(a: UrlParams, b: UrlParams): boolean;
+export {};

package/dist/src/url_params.js

@@ -0,0 +1,215 @@
+/**
+ * Typed codecs that map URL query-string values (always strings, or string
+ * arrays for repeated keys) to and from the typed view-state an app keeps in
+ * the address bar — the engine behind `useUrlState`.
+ *
+ * Two properties make the URLs clean and the round-trip lossless:
+ *
+ *  - **Default-omission.** A codec built with `.withDefault(d)` encodes the
+ *    default value to `undefined` — i.e. the key is dropped from the URL. So a
+ *    filter at its default (`page=1`, `q=""`) never appears, and the shared
+ *    link carries only what the user actually changed.
+ *  - **Declared keys only.** `decodeAll`/`encodePatch` touch exactly the keys the
+ *    app declared. Every other query param (`lotics_host`, `__mock`, a param a
+ *    second `useUrlState` owns, a future host param) is read past and preserved
+ *    on write — the merge is the namespace boundary, so no reserved-prefix rule
+ *    is needed.
+ *
+ * Self-contained on purpose: the SDK publishes to npm as a bundle-free `dist/`,
+ * so it carries no workspace deps (no `@lotics/shared`). These are plain pure
+ * functions — a frontend that later wants the same value⇄query codec can import
+ * them from here rather than growing a second copy.
+ */
+function first(raw) {
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+function valueEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => valueEqual(x, b[i]));
+    }
+    return false;
+}
+/** Wrap an optional base codec with `.withDefault`. */
+function optional(base) {
+    return {
+        decode: base.decode,
+        encode: base.encode,
+        withDefault(fallback) {
+            return {
+                decode: (raw) => {
+                    const v = base.decode(raw);
+                    return v === undefined ? fallback : v;
+                },
+                encode: (value) => (valueEqual(value, fallback) ? undefined : base.encode(value)),
+            };
+        },
+    };
+}
+const stringCodec = optional({
+    decode: (raw) => (raw === undefined ? undefined : first(raw)),
+    encode: (v) => v,
+});
+const numberCodec = optional({
+    decode: (raw) => {
+        const s = first(raw);
+        if (s === undefined || s === "")
+            return undefined;
+        const n = Number(s);
+        return Number.isFinite(n) ? n : undefined;
+    },
+    encode: (v) => (v === undefined ? undefined : String(v)),
+});
+const booleanCodec = optional({
+    decode: (raw) => {
+        const s = first(raw);
+        return s === "true" ? true : s === "false" ? false : undefined;
+    },
+    encode: (v) => (v === undefined ? undefined : v ? "true" : "false"),
+});
+const isoDateCodec = optional({
+    decode: (raw) => {
+        const s = first(raw);
+        if (s === undefined || !/^\d{4}-\d{2}-\d{2}$/.test(s))
+            return undefined;
+        const d = new Date(`${s}T00:00:00.000Z`);
+        return Number.isNaN(d.getTime()) ? undefined : d;
+    },
+    encode: (v) => (v === undefined ? undefined : v.toISOString().slice(0, 10)),
+});
+function enumCodec(values) {
+    return optional({
+        decode: (raw) => {
+            const s = first(raw);
+            return s === undefined ? undefined : values.find((v) => v === s);
+        },
+        encode: (v) => v,
+    });
+}
+function arrayOf(inner) {
+    return optional({
+        decode: (raw) => {
+            if (raw === undefined)
+                return undefined;
+            const items = Array.isArray(raw) ? raw : [raw];
+            return items.map((x) => inner.decode(x)).filter((x) => x !== undefined);
+        },
+        encode: (value) => {
+            if (value === undefined || value.length === 0)
+                return undefined;
+            const out = value
+                .map((x) => inner.encode(x))
+                .filter((x) => typeof x === "string");
+            return out.length > 0 ? out : undefined;
+        },
+    });
+}
+/**
+ * The codec builders an app composes into a `useUrlState` shape. Each base
+ * builder yields an optional codec (absent key → `undefined`); add
+ * `.withDefault(v)` to make it required and keep the default out of the URL.
+ *
+ *   useUrlState({
+ *     q:      urlParam.string.withDefault(""),
+ *     status: urlParam.enum(["open", "won", "lost"]),       // optional
+ *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
+ *     from:   urlParam.isoDate,                              // optional Date
+ *     page:   urlParam.number.withDefault(1),
+ *   })
+ */
+export const urlParam = {
+    string: stringCodec,
+    number: numberCodec,
+    boolean: booleanCodec,
+    isoDate: isoDateCodec,
+    enum: enumCodec,
+    arrayOf,
+};
+/** Decode the declared keys out of a params map into typed values. */
+export function decodeAll(defs, params) {
+    const out = {};
+    for (const key of Object.keys(defs)) {
+        out[key] = defs[key].decode(params[key]);
+    }
+    // Boundary: a per-key loop can't be expressed as the mapped result type.
+    return out;
+}
+/** Encode a partial set of declared values into a patch (each key → value or
+ *  `undefined` to clear). Only the keys present in `values` are emitted, so the
+ *  write merges and leaves every other query param untouched. */
+export function encodePatch(defs, values) {
+    const out = {};
+    for (const key of Object.keys(values)) {
+        const codec = defs[key];
+        if (codec)
+            out[key] = codec.encode(values[key]);
+    }
+    return out;
+}
+/** Parse a `location.search` string into a params map (repeated keys → array). */
+export function parseSearch(search) {
+    const sp = new URLSearchParams(search);
+    const out = {};
+    for (const key of sp.keys()) {
+        if (key in out)
+            continue;
+        const all = sp.getAll(key);
+        out[key] = all.length > 1 ? all : all[0];
+    }
+    return out;
+}
+/** Apply a patch to a `location.search` string and return the new query string
+ *  (no leading `?`). Each patch key is replaced; `undefined` clears it; every
+ *  other existing param is preserved. */
+export function serializeMerge(search, patch) {
+    const sp = new URLSearchParams(search);
+    for (const [key, value] of Object.entries(patch)) {
+        sp.delete(key);
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                sp.append(key, item);
+        }
+        else {
+            sp.append(key, value);
+        }
+    }
+    return sp.toString();
+}
+/** Apply a patch to an in-memory params map (the optimistic local mirror). */
+export function applyPatch(params, patch) {
+    const next = { ...params };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            delete next[key];
+        else
+            next[key] = value;
+    }
+    return next;
+}
+/** Shallow value-equality over two params maps — used to drop echoed updates so
+ *  an app's own write doesn't re-render it a second time. */
+export function paramsEqual(a, b) {
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    for (const key of ak) {
+        const av = a[key];
+        const bv = b[key];
+        if (Array.isArray(av) || Array.isArray(bv)) {
+            if (!Array.isArray(av) || !Array.isArray(bv))
+                return false;
+            if (av.length !== bv.length || !av.every((x, i) => x === bv[i]))
+                return false;
+        }
+        else if (av !== bv) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/src/use_url_state.d.ts

@@ -0,0 +1,16 @@
+import { type UrlParamCodec } from "./url_params.js";
+/** A `useUrlState` shape: a map of param key → codec. */
+export type UrlStateShape = Record<string, UrlParamCodec<unknown>>;
+/** The decoded, typed values for a shape. */
+export type UrlStateValues<D extends UrlStateShape> = {
+    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
+};
+export interface SetUrlStateOptions {
+    /** Add a browser history entry (back/forward navigable). Default `false` —
+     *  replace in place, so high-frequency filter changes don't flood history. */
+    push?: boolean;
+}
+export declare function useUrlState<D extends UrlStateShape>(defs: D): readonly [
+    UrlStateValues<D>,
+    (patch: Partial<UrlStateValues<D>>, options?: SetUrlStateOptions) => void
+];

package/dist/src/use_url_state.js

@@ -0,0 +1,74 @@
+/**
+ * Keep a declared slice of an app's view-state — filters, search, sort, the
+ * active tab — in the browser's address bar, with two-way sync. The result is
+ * real browser behaviour for an otherwise opaque cross-origin app: a filtered
+ * view survives refresh, is shareable/bookmarkable as a link, and (with
+ * `{ push: true }`) is back/forward-navigable.
+ *
+ *   const [filters, setFilters] = useUrlState({
+ *     q:      urlParam.string.withDefault(""),
+ *     status: urlParam.enum(["open", "won", "lost"]),        // optional
+ *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
+ *     page:   urlParam.number.withDefault(1),
+ *   });
+ *   // filters → { q: string; status?: "open"|"won"|"lost"; tags: string[]; page: number }
+ *   setFilters({ q: "acme" });                  // merge, replace history
+ *   setFilters({ status: "won" }, { push: true });  // back-able navigation
+ *
+ * The app declares only the keys it owns; every other query param (a param a
+ * second `useUrlState` owns, the framework's `lotics_host`/`__mock`, a future
+ * host param) is read past and preserved on write. For a search box, keep the
+ * live input in local state and commit to `setFilters` on a debounce — each
+ * call is a cross-frame write in an embedded app.
+ *
+ * The address bar is the only store: nothing is persisted server-side. Values
+ * are decoded fresh from the current params each render; standalone reads the
+ * URL directly, while an embedded app keeps a local mirror the SDK syncs from
+ * the host (initial `urlState.get`, the app's own writes, and back/forward
+ * broadcasts) — so there's no independently-mutable second copy to drift.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { getUrlParams, peekUrlParams, setUrlParams, subscribeUrlParams } from "./rpc.js";
+import { applyPatch, decodeAll, encodePatch, paramsEqual, } from "./url_params.js";
+export function useUrlState(defs) {
+    // `defs` is expected stable (declared inline once); read through a ref so the
+    // decoded values and `setValues` stay referentially stable across renders.
+    const defsRef = useRef(defs);
+    defsRef.current = defs;
+    const [params, setParams] = useState(peekUrlParams);
+    // Once the user edits, a late initial hydration (bridged `getUrlParams`
+    // resolves a tick after mount) must not clobber their write.
+    const editedRef = useRef(false);
+    useEffect(() => {
+        let active = true;
+        const apply = (next) => {
+            if (active)
+                setParams((prev) => (paramsEqual(prev, next) ? prev : next));
+        };
+        void getUrlParams().then((p) => {
+            if (active && !editedRef.current)
+                apply(p);
+        });
+        const unsubscribe = subscribeUrlParams(apply);
+        return () => {
+            active = false;
+            unsubscribe();
+        };
+    }, []);
+    const values = useMemo(() => decodeAll(defsRef.current, params), [params]);
+    const setValues = useCallback((patch, options) => {
+        editedRef.current = true;
+        const encoded = encodePatch(defsRef.current, patch);
+        // Optimistic local mirror so the UI is responsive even before the write
+        // round-trips (and the only update path in standalone, where the history
+        // write fires no event).
+        setParams((prev) => applyPatch(prev, encoded));
+        // The optimistic mirror already reflects the change, so a failed write
+        // only loses cross-refresh persistence, never the session — keep the
+        // optimistic state, but surface the failure instead of swallowing it.
+        void setUrlParams(encoded, options?.push ?? false).catch((err) => {
+            console.error("useUrlState: failed to write state to the address bar", err);
+        });
+    }, []);
+    return [values, setValues];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {