@lotics/app-sdk 0.7.0 → 0.9.0

package/dist/src/hooks.js

@@ -15,6 +15,7 @@
  */
 import { useCallback, useEffect, useState } from "react";
 import { rpc } from "./rpc.js";
+import { getMockRows } from "./mock.js";
 export function useWorkflow(alias) {
     return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
 }
@@ -26,12 +27,25 @@ export function useQuery(alias, params) {
     // refetch callback mutates only this counter; state transitions still
     // happen inside the effect so loading / error / rows flow consistently.
     const [refetchToken, setRefetchToken] = useState(0);
-    const [state, setState] = useState({
-        rows: [],
-        loading: true,
-        error: null,
+    // Initialize from the fixture when mock mode is on and the app registered
+    // rows for this alias — avoids a flash of `loading: true` on first paint.
+    // Computed lazily so subsequent renders don't re-read `window.location`.
+    const [state, setState] = useState(() => {
+        const mockRows = getMockRows(alias);
+        if (mockRows)
+            return { rows: mockRows, loading: false, error: null };
+        return { rows: [], loading: true, error: null };
     });
     useEffect(() => {
+        // Re-check on every effect run so HMR updates to the fixture (mount-time
+        // re-registration) propagate without a hard reload. When the fixture has
+        // an entry we short-circuit the RPC — partial mocking still works because
+        // aliases without fixture entries fall through to the live path below.
+        const mockRows = getMockRows(alias);
+        if (mockRows) {
+            setState({ rows: mockRows, loading: false, error: null });
+            return;
+        }
         let cancelled = false;
         setState((s) => ({ rows: s.rows, loading: true, error: null }));
         rpc("query", { alias, params: params ?? {} })

package/dist/src/index.d.ts

@@ -10,8 +10,10 @@
  * depending on packages/ui's React Native Web setup.
  */
 export { mount } from "./mount.js";
+export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export type { UploadedFile } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
+export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";

package/dist/src/mock.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Demo / design-time fixture support for `useQuery`.
+ *
+ * Activation contract:
+ *
+ *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
+ *      is a `{ queries: { alias: Row[] } }` map keyed by the same aliases the
+ *      app declared in `package.json#lotics.queries`.
+ *   2. At runtime, the user (or a screenshot script) loads the app with the
+ *      `?__mock=1` URL search param. Without that param the SDK ignores the
+ *      fixture entirely and `useQuery` flows through the RPC bridge as usual.
+ *
+ * The two-step gate keeps demo data shipping in the bundle from leaking into
+ * normal traffic — the param namespace (`__mock` prefix) is reserved and
+ * unlikely to collide with app-side query state. Apps that don't pass a
+ * fixture pay nothing: `getMockRows` returns `null` for every alias and the
+ * hook path is unchanged.
+ *
+ * What's deliberately *not* mocked yet:
+ *   - `useWorkflow` — mutations have side effects (notifications, audit
+ *     trail). A workflow mock would have to also produce realistic followup
+ *     state, which is more design than this iteration warrants.
+ *   - `useFileUpload` — same reason.
+ *
+ * If those become needed, extend `AppFixture` with `workflows`/`uploads` and
+ * route from each hook.
+ */
+export interface AppFixture {
+    /** Map of query alias → rows the hook should return when mock mode is on. */
+    queries?: Record<string, Array<Record<string, unknown>>>;
+}
+/**
+ * Called by `mount({ fixture })`. Module-level state because the SDK has no
+ * React context boundary around the iframe — every hook resolves against the
+ * same registration. Calling twice replaces (last-write-wins) which is fine
+ * for HMR.
+ */
+export declare function registerMockFixture(fixture: AppFixture | undefined): void;
+/**
+ * Returns the fixture rows for an alias when mock mode is active *and* the
+ * fixture has an entry for that alias. Otherwise null — the hook falls
+ * through to the real RPC path. The distinction matters: an app may mock
+ * only some queries and let the rest flow through to real data.
+ */
+export declare function getMockRows(alias: string): Array<Record<string, unknown>> | null;

package/dist/src/mock.js

@@ -0,0 +1,65 @@
+/**
+ * Demo / design-time fixture support for `useQuery`.
+ *
+ * Activation contract:
+ *
+ *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
+ *      is a `{ queries: { alias: Row[] } }` map keyed by the same aliases the
+ *      app declared in `package.json#lotics.queries`.
+ *   2. At runtime, the user (or a screenshot script) loads the app with the
+ *      `?__mock=1` URL search param. Without that param the SDK ignores the
+ *      fixture entirely and `useQuery` flows through the RPC bridge as usual.
+ *
+ * The two-step gate keeps demo data shipping in the bundle from leaking into
+ * normal traffic — the param namespace (`__mock` prefix) is reserved and
+ * unlikely to collide with app-side query state. Apps that don't pass a
+ * fixture pay nothing: `getMockRows` returns `null` for every alias and the
+ * hook path is unchanged.
+ *
+ * What's deliberately *not* mocked yet:
+ *   - `useWorkflow` — mutations have side effects (notifications, audit
+ *     trail). A workflow mock would have to also produce realistic followup
+ *     state, which is more design than this iteration warrants.
+ *   - `useFileUpload` — same reason.
+ *
+ * If those become needed, extend `AppFixture` with `workflows`/`uploads` and
+ * route from each hook.
+ */
+let registeredFixture;
+/**
+ * Called by `mount({ fixture })`. Module-level state because the SDK has no
+ * React context boundary around the iframe — every hook resolves against the
+ * same registration. Calling twice replaces (last-write-wins) which is fine
+ * for HMR.
+ */
+export function registerMockFixture(fixture) {
+    registeredFixture = fixture;
+}
+/**
+ * True iff the iframe URL carries the `__mock=1` activation flag AND a
+ * fixture was registered. Safe to call before mount — returns false when no
+ * fixture exists. Throws never; a malformed URL or missing `window` (SSR /
+ * jsdom without location) silently returns false.
+ */
+function isMockMode() {
+    if (!registeredFixture)
+        return false;
+    try {
+        return new URLSearchParams(window.location.search).get("__mock") === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the fixture rows for an alias when mock mode is active *and* the
+ * fixture has an entry for that alias. Otherwise null — the hook falls
+ * through to the real RPC path. The distinction matters: an app may mock
+ * only some queries and let the rest flow through to real data.
+ */
+export function getMockRows(alias) {
+    if (!isMockMode())
+        return null;
+    const rows = registeredFixture?.queries?.[alias];
+    return rows ?? null;
+}

package/dist/src/mount.d.ts

@@ -10,9 +10,23 @@
  * mount(<App />);
  * ```
  *
+ * Optional second argument registers a demo/design-time fixture. When the
+ * iframe is loaded with `?__mock=1`, `useQuery` returns rows from the
+ * fixture instead of hitting the RPC bridge. Without the URL flag the
+ * fixture is inert — useful for taking screenshots or iterating on
+ * dashboard layouts before real data exists.
+ *
+ * ```tsx
+ * mount(<App />, {
+ *   fixture: {
+ *     queries: { customers: MOCK_CUSTOMERS, deals: MOCK_DEALS },
+ *   },
+ * });
+ * ```
+ *
  * `mount` wires up React 19's createRoot against `#root` in the iframe shell,
  * sets up window.onerror/unhandledrejection forwarding so runtime crashes
- * surface in the parent's debug pane (PR 2 of the debug-loop phase), and
+ * surface in the parent's debug pane, registers the fixture (if any), and
  * renders the user's tree.
  *
  * If the bundler doesn't ship #root in the user's `index.html`, we create it
@@ -20,4 +34,14 @@
  * mount resilient.
  */
 import type { ReactNode } from "react";
-export declare function mount(element: ReactNode): void;
+import { type AppFixture } from "./mock.js";
+export interface MountOptions {
+    /**
+     * Optional demo fixture. When the iframe URL contains `?__mock=1`,
+     * `useQuery(alias)` returns `fixture.queries[alias]` instead of calling
+     * the RPC bridge. Aliases not present in the fixture still flow through
+     * the real path — partial mocking is supported.
+     */
+    fixture?: AppFixture;
+}
+export declare function mount(element: ReactNode, options?: MountOptions): void;

package/dist/src/mount.js

@@ -1,5 +1,7 @@
 import { createRoot } from "react-dom/client";
-export function mount(element) {
+import { registerMockFixture } from "./mock.js";
+export function mount(element, options = {}) {
+    registerMockFixture(options.fixture);
     let container = document.getElementById("root");
     if (!container) {
         container = document.createElement("div");

package/dist/src/password_gate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vanilla DOM password overlay for password-protected public apps.
+ *
+ * The SDK can't assume the host app's React tree has mounted yet (this fires
+ * before any data call resolves), so the overlay is built with plain DOM
+ * APIs and self-contained inline styles. It rejects the boot promise only
+ * on `cancel()` — which is currently never wired to a button; the visitor
+ * either enters the correct password or leaves the page.
+ *
+ * One overlay at a time. Concurrent calls reuse the in-flight promise so a
+ * burst of failing API calls produces a single modal, not several stacked.
+ */
+interface OverlayController {
+    showError(message: string): void;
+    setSubmitting(submitting: boolean): void;
+}
+export interface PasswordPromptArgs {
+    /**
+     * Validates the entered password. Resolve to keep the overlay open on a
+     * wrong password (the SDK calls `controller.showError(...)` afterwards),
+     * or `accept()` to dismiss the overlay and resolve the prompt with the
+     * password the visitor typed.
+     */
+    authenticate: (password: string, controller: OverlayController) => Promise<{
+        ok: boolean;
+    }>;
+}
+export declare function promptForPassword(args: PasswordPromptArgs): Promise<string>;
+export {};

package/dist/src/password_gate.js

@@ -0,0 +1,142 @@
+/**
+ * Vanilla DOM password overlay for password-protected public apps.
+ *
+ * The SDK can't assume the host app's React tree has mounted yet (this fires
+ * before any data call resolves), so the overlay is built with plain DOM
+ * APIs and self-contained inline styles. It rejects the boot promise only
+ * on `cancel()` — which is currently never wired to a button; the visitor
+ * either enters the correct password or leaves the page.
+ *
+ * One overlay at a time. Concurrent calls reuse the in-flight promise so a
+ * burst of failing API calls produces a single modal, not several stacked.
+ */
+let activePrompt = null;
+export function promptForPassword(args) {
+    if (activePrompt)
+        return activePrompt;
+    activePrompt = new Promise((resolve) => {
+        const root = document.createElement("div");
+        root.dataset.loticsAppPasswordGate = "true";
+        root.style.cssText = [
+            "position:fixed",
+            "inset:0",
+            "z-index:2147483647",
+            "background:rgba(15,23,42,0.55)",
+            "backdrop-filter:blur(8px)",
+            "-webkit-backdrop-filter:blur(8px)",
+            "display:flex",
+            "align-items:center",
+            "justify-content:center",
+            "padding:24px",
+            "font:14px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Inter,sans-serif",
+            "color:#0f172a",
+        ].join(";");
+        const card = document.createElement("form");
+        card.setAttribute("role", "dialog");
+        card.setAttribute("aria-modal", "true");
+        card.setAttribute("aria-labelledby", "lotics-app-password-title");
+        card.style.cssText = [
+            "background:#fff",
+            "border-radius:14px",
+            "padding:28px",
+            "max-width:380px",
+            "width:100%",
+            "box-shadow:0 25px 50px -12px rgba(0,0,0,0.25)",
+            "display:flex",
+            "flex-direction:column",
+            "gap:16px",
+        ].join(";");
+        const title = document.createElement("h2");
+        title.id = "lotics-app-password-title";
+        title.textContent = "Password required";
+        title.style.cssText = "margin:0;font-size:18px;font-weight:600;letter-spacing:-0.01em;";
+        const subtitle = document.createElement("p");
+        subtitle.textContent = "Enter the password to access this app.";
+        subtitle.style.cssText = "margin:0;color:#475569;font-size:13.5px;";
+        const input = document.createElement("input");
+        input.type = "password";
+        input.autocomplete = "current-password";
+        input.required = true;
+        input.placeholder = "Password";
+        input.setAttribute("aria-label", "Password");
+        input.style.cssText = [
+            "width:100%",
+            "box-sizing:border-box",
+            "padding:10px 12px",
+            "border:1px solid #cbd5e1",
+            "border-radius:8px",
+            "font-size:14px",
+            "outline:none",
+            "transition:border-color 0.15s,box-shadow 0.15s",
+        ].join(";");
+        input.addEventListener("focus", () => {
+            input.style.borderColor = "#2563eb";
+            input.style.boxShadow = "0 0 0 3px rgba(37,99,235,0.18)";
+        });
+        input.addEventListener("blur", () => {
+            input.style.borderColor = "#cbd5e1";
+            input.style.boxShadow = "none";
+        });
+        const error = document.createElement("div");
+        error.setAttribute("role", "alert");
+        error.style.cssText = "color:#dc2626;font-size:13px;min-height:18px;";
+        const submit = document.createElement("button");
+        submit.type = "submit";
+        submit.textContent = "Continue";
+        submit.style.cssText = [
+            "padding:10px 12px",
+            "background:#0f172a",
+            "color:#fff",
+            "border:none",
+            "border-radius:8px",
+            "font-size:14px",
+            "font-weight:500",
+            "cursor:pointer",
+            "transition:background 0.15s,opacity 0.15s",
+        ].join(";");
+        const setSubmitting = (s) => {
+            submit.disabled = s;
+            input.disabled = s;
+            submit.textContent = s ? "Checking…" : "Continue";
+            submit.style.opacity = s ? "0.7" : "1";
+            submit.style.cursor = s ? "wait" : "pointer";
+        };
+        const showError = (message) => {
+            error.textContent = message;
+        };
+        card.append(title, subtitle, input, error, submit);
+        root.append(card);
+        document.body.append(root);
+        // Defer focus until the element is in layout — some browsers ignore focus
+        // on freshly-attached inputs without a microtask break.
+        queueMicrotask(() => input.focus());
+        card.addEventListener("submit", (e) => {
+            e.preventDefault();
+            const value = input.value;
+            if (!value) {
+                showError("Enter a password.");
+                return;
+            }
+            showError("");
+            setSubmitting(true);
+            args
+                .authenticate(value, { showError, setSubmitting })
+                .then((res) => {
+                if (res.ok) {
+                    root.remove();
+                    activePrompt = null;
+                    resolve(value);
+                }
+                else {
+                    setSubmitting(false);
+                    input.select();
+                }
+            })
+                .catch((err) => {
+                setSubmitting(false);
+                showError(err instanceof Error ? err.message : "Something went wrong.");
+            });
+        });
+    });
+    return activePrompt;
+}

package/dist/src/rpc.js

@@ -1,23 +1,5 @@
-/**
- * RPC bridge for a custom-code app's data operations.
- *
- * An app reaches the Lotics API one of two ways, chosen automatically:
- *
- *  - **Bridged** — the app is embedded by a Lotics host (the authenticated
- *    product, or `lotics app dev`), which passes its origin via the
- *    `?lotics_host=` query param. The host holds the session; the app posts
- *    ops over postMessage and the host makes the API call. Used by internal
- *    apps — the member's credentials must never reach the app.
- *
- *  - **Standalone** — the app is served on its own at `<slug>.lotics.app`
- *    with no host. It calls the public `/v1/apps/{id}/*` endpoints directly;
- *    those are anonymous-accessible for a publicly-shared app. The app holds
- *    no credentials, so there is nothing to protect.
- *
- * Wire protocol (bridged — must match `app_iframe_host.tsx`):
- *   app  → host: { id, op, payload }
- *   host → app:  { id, type: "result", data } | { id, type: "error", message }
- */
+import { promptForPassword } from "./password_gate.js";
+import { runUploadPipeline } from "./upload/pipeline.js";
 /** The embedding Lotics host's origin — present iff the app is bridged. */
 const hostOrigin = new URLSearchParams(window.location.search).get("lotics_host");
 export function rpc(op, payload) {
@@ -63,41 +45,134 @@ function rpcBridged(op, payload, host) {
 // Standalone apps run only at `<slug>.lotics.app` (production); dev apps are
 // always bridged by the `lotics app dev` wrapper.
 const API_BASE = "https://api.lotics.ai";
-/** Resolved once — the app_id this standalone app's data calls are keyed by. */
-let appIdPromise = null;
-function resolveAppId() {
-    if (!appIdPromise) {
-        const slug = window.location.hostname.split(".")[0];
-        const attempt = apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`).then((r) => r.app_id);
-        // Don't cache a rejection — a transient failure on first load would
-        // otherwise brick every later data call for the session. Clear the slot
-        // so the next call retries.
-        attempt.catch(() => {
-            if (appIdPromise === attempt)
-                appIdPromise = null;
-        });
-        appIdPromise = attempt;
+const PASSWORD_REQUIRED_CODE = "PASSWORD_REQUIRED";
+/**
+ * Boot-time resolution result. Promise is shared so concurrent first calls
+ * (e.g. two `useQuery` hooks rendering simultaneously) coalesce into one
+ * `/by-subdomain` fetch and at most one password prompt.
+ */
+let bootPromise = null;
+let sessionToken = null;
+function sessionStorageKey(appId) {
+    return `lotics_app_session:${appId}`;
+}
+function readStoredSession(appId) {
+    try {
+        const raw = window.localStorage.getItem(sessionStorageKey(appId));
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed.token || !parsed.expires_at)
+            return null;
+        if (Date.parse(parsed.expires_at) <= Date.now()) {
+            window.localStorage.removeItem(sessionStorageKey(appId));
+            return null;
+        }
+        return parsed.token;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStoredSession(appId, token, expiresAt) {
+    try {
+        window.localStorage.setItem(sessionStorageKey(appId), JSON.stringify({ token, expires_at: expiresAt }));
+    }
+    catch {
+        // localStorage unavailable (Safari private mode, quota): the token still
+        // lives in memory for this page lifetime — that's good enough for a single
+        // session, the next reload simply re-prompts.
+    }
+}
+function clearStoredSession(appId) {
+    try {
+        window.localStorage.removeItem(sessionStorageKey(appId));
     }
-    return appIdPromise;
+    catch {
+        // ignore
+    }
+}
+async function boot() {
+    if (bootPromise)
+        return bootPromise;
+    const slug = window.location.hostname.split(".")[0];
+    const attempt = (async () => {
+        const info = (await apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`));
+        if (info.requires_password) {
+            const stored = readStoredSession(info.app_id);
+            if (stored) {
+                sessionToken = stored;
+            }
+            else {
+                await acquireSessionToken(info.app_id);
+            }
+        }
+        return info;
+    })();
+    // Don't cache a rejection — a transient failure on first load would brick
+    // every later data call. Clear the slot so the next call retries.
+    attempt.catch(() => {
+        if (bootPromise === attempt)
+            bootPromise = null;
+    });
+    bootPromise = attempt;
+    return attempt;
+}
+async function acquireSessionToken(appId) {
+    await promptForPassword({
+        authenticate: async (password, controller) => {
+            try {
+                const res = (await apiCall("POST", `/v1/apps/${appId}/public/authenticate`, { password }, { skipAuth: true }));
+                sessionToken = res.session_token;
+                writeStoredSession(appId, res.session_token, res.expires_at);
+                return { ok: true };
+            }
+            catch (err) {
+                const message = err instanceof Error && err.message ? err.message : "Incorrect password.";
+                controller.showError(message);
+                return { ok: false };
+            }
+        },
+    });
 }
-async function apiCall(method, path, body) {
+async function apiCall(method, path, body, opts) {
+    const headers = {};
+    if (body)
+        headers["content-type"] = "application/json";
+    if (sessionToken && !opts?.skipAuth) {
+        headers["authorization"] = `Bearer ${sessionToken}`;
+    }
     const res = await fetch(`${API_BASE}${path}`, {
         method,
-        headers: body ? { "content-type": "application/json" } : undefined,
+        headers,
         body: body ? JSON.stringify(body) : undefined,
     });
     const text = await res.text();
-    if (!res.ok) {
-        let message = text;
+    let parsed = null;
+    if (text) {
         try {
-            message = JSON.parse(text).message ?? text;
+            parsed = JSON.parse(text);
         }
         catch {
-            // response body is not JSON — use it verbatim
+            // not JSON — body left as raw text
+        }
+    }
+    if (!res.ok) {
+        const errorBody = parsed;
+        // Password gate (re-)prompt: the stored token went stale because the owner
+        // rotated or cleared the password, or it was never present. Drop the
+        // current token, ask the visitor again, and retry the original call once.
+        if (res.status === 401 && errorBody?.error_code === PASSWORD_REQUIRED_CODE && !opts?.skipAuth) {
+            const appId = opts?.appId ?? (await boot()).app_id;
+            sessionToken = null;
+            clearStoredSession(appId);
+            await acquireSessionToken(appId);
+            return apiCall(method, path, body, { ...opts, appId });
         }
+        const message = errorBody?.message ?? text;
         throw new Error(message || `HTTP ${res.status}`);
     }
-    return text ? JSON.parse(text) : {};
+    return parsed ?? (text ? text : {});
 }
 function rpcStandalone(op, payload) {
     switch (op) {
@@ -110,39 +185,22 @@ function rpcStandalone(op, payload) {
     }
 }
 async function standaloneQuery(p) {
-    const appId = await resolveAppId();
-    const r = (await apiCall("POST", `/v1/apps/${appId}/query`, {
-        alias: p.alias,
-        params: p.params,
-    }));
+    const { app_id } = await boot();
+    const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params }, { appId: app_id }));
     return { rows: r.rows ?? [] };
 }
 async function standaloneWorkflow(p) {
-    const appId = await resolveAppId();
-    return apiCall("POST", `/v1/apps/${appId}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs });
+    const { app_id } = await boot();
+    return apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });
 }
 async function standaloneUpload(file) {
     if (!(file instanceof File)) {
         throw new Error("upload payload must include a File");
     }
-    const appId = await resolveAppId();
-    const init = (await apiCall("POST", `/v1/apps/${appId}/files/upload-url`, {
-        filename: file.name,
-        mime_type: file.type,
-        file_size: file.size,
-    }));
-    const put = await fetch(init.upload_url, {
-        method: "PUT",
-        body: file,
-        headers: { "Content-Type": file.type },
+    const { app_id } = await boot();
+    const uploaded = await runUploadPipeline(file, {
+        initUpload: (input) => apiCall("POST", `/v1/apps/${app_id}/files/upload-url`, input, { appId: app_id }),
+        completeUpload: (input) => apiCall("POST", `/v1/apps/${app_id}/files/complete`, input, { appId: app_id }),
     });
-    if (!put.ok) {
-        throw new Error(`Storage upload failed (${put.status})`);
-    }
-    const done = (await apiCall("POST", `/v1/apps/${appId}/files/complete`, {
-        file_id: init.file_id,
-        file_storage_key: init.file_storage_key,
-        filename: file.name,
-    }));
-    return done.file;
+    return uploaded;
 }

package/dist/src/upload/optimize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser-side image compression for app uploads.
+ *
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) but documents only need
+ * legible bytes, not megapixel ones. Resize to ≤1280px on the long edge and
+ * re-encode as JPEG at q=0.75 before uploading — typically 10–20× smaller
+ * with no visible quality loss for the doc-scan use case.
+ *
+ * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
+ * pass through unchanged. Falls through gracefully on any browser API gap
+ * — the original file is always returned as a usable upload candidate.
+ *
+ * Ported from `frontend/lib/upload_file_optimization.ts` so public-app forms
+ * get the same mobile-friendly upload behavior as the in-Lotics UI. Kept
+ * dependency-free (no logger, no UploadIntent abstraction) so the SDK ships
+ * as a single drop-in.
+ */
+export type OptimizationReason = "optimized" | "skipped_unsupported_format" | "skipped_environment_unsupported" | "skipped_decode_unavailable" | "skipped_invalid_dimensions" | "skipped_small_dimensions" | "skipped_canvas_unavailable" | "skipped_canvas_type_mismatch";
+export interface OptimizationResult {
+    file: File;
+    optimized: boolean;
+    reason: OptimizationReason;
+    originalSizeBytes: number;
+    optimizedSizeBytes: number;
+    width: number;
+    height: number;
+    targetWidth: number;
+    targetHeight: number;
+}
+export declare function optimizeImageForUpload(file: File): Promise<OptimizationResult>;

package/dist/src/upload/optimize.js

@@ -0,0 +1,182 @@
+/**
+ * Browser-side image compression for app uploads.
+ *
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) but documents only need
+ * legible bytes, not megapixel ones. Resize to ≤1280px on the long edge and
+ * re-encode as JPEG at q=0.75 before uploading — typically 10–20× smaller
+ * with no visible quality loss for the doc-scan use case.
+ *
+ * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
+ * pass through unchanged. Falls through gracefully on any browser API gap
+ * — the original file is always returned as a usable upload candidate.
+ *
+ * Ported from `frontend/lib/upload_file_optimization.ts` so public-app forms
+ * get the same mobile-friendly upload behavior as the in-Lotics UI. Kept
+ * dependency-free (no logger, no UploadIntent abstraction) so the SDK ships
+ * as a single drop-in.
+ */
+const MAX_IMAGE_DIMENSION_PX = 1280;
+const JPEG_QUALITY = 0.75;
+const CONVERTIBLE_EXTENSION_PATTERN = /\.(heic|heif|png|webp)$/i;
+export async function optimizeImageForUpload(file) {
+    const format = getOptimizableFormat(file);
+    const mimeType = format?.outputMimeType;
+    const unsupportedReason = getUnsupportedReason(file, mimeType);
+    if (unsupportedReason)
+        return unchanged(file, unsupportedReason);
+    if (!mimeType || !format)
+        return unchanged(file, "skipped_unsupported_format");
+    const loaded = await loadImage(file);
+    if (loaded.status === "decode_unavailable")
+        return unchanged(file, "skipped_decode_unavailable");
+    const { source, width, height } = loaded;
+    if (width <= 0 || height <= 0) {
+        closeSource(source);
+        return unchanged(file, "skipped_invalid_dimensions");
+    }
+    if (Math.max(width, height) <= MAX_IMAGE_DIMENSION_PX) {
+        closeSource(source);
+        return unchanged(file, "skipped_small_dimensions", width, height);
+    }
+    const { width: targetWidth, height: targetHeight } = scale(width, height);
+    const canvas = document.createElement("canvas");
+    canvas.width = targetWidth;
+    canvas.height = targetHeight;
+    const ctx = canvas.getContext("2d");
+    if (!ctx || typeof canvas.toBlob !== "function") {
+        closeSource(source);
+        return unchanged(file, "skipped_canvas_unavailable", width, height);
+    }
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = "high";
+    ctx.drawImage(source, 0, 0, targetWidth, targetHeight);
+    closeSource(source);
+    const blob = await canvasToBlob(canvas, mimeType);
+    if (blob.type !== mimeType) {
+        return unchanged(file, "skipped_canvas_type_mismatch", width, height, targetWidth, targetHeight);
+    }
+    return {
+        file: new File([blob], format.outputFilename, {
+            type: mimeType,
+            lastModified: file.lastModified,
+        }),
+        optimized: true,
+        reason: "optimized",
+        originalSizeBytes: file.size,
+        optimizedSizeBytes: blob.size,
+        width,
+        height,
+        targetWidth,
+        targetHeight,
+    };
+}
+function getUnsupportedReason(file, mimeType) {
+    void file;
+    if (mimeType === undefined)
+        return "skipped_unsupported_format";
+    if (typeof window === "undefined" ||
+        typeof document === "undefined" ||
+        typeof document.createElement !== "function" ||
+        typeof URL.createObjectURL !== "function" ||
+        typeof URL.revokeObjectURL !== "function" ||
+        typeof Image === "undefined") {
+        return "skipped_environment_unsupported";
+    }
+    return undefined;
+}
+function getOptimizableFormat(file) {
+    const mimeType = normalizeMimeType(file.type);
+    if (!mimeType)
+        return undefined;
+    if (mimeType === "image/jpeg") {
+        return { outputMimeType: "image/jpeg", outputFilename: file.name };
+    }
+    // PNG / WebP / HEIC / HEIF → JPEG (transparency lost on PNG; acceptable
+    // for document uploads where we explicitly opt into lossy compression).
+    return { outputMimeType: "image/jpeg", outputFilename: replaceExtensionWithJpeg(file.name) };
+}
+function normalizeMimeType(mimeType) {
+    const m = mimeType.toLowerCase();
+    if (m === "image/jpeg" || m === "image/jpg")
+        return "image/jpeg";
+    if (m === "image/heic" || m === "image/heif")
+        return m;
+    if (m === "image/png" || m === "image/webp")
+        return m;
+    return undefined;
+}
+function replaceExtensionWithJpeg(filename) {
+    if (CONVERTIBLE_EXTENSION_PATTERN.test(filename)) {
+        return filename.replace(CONVERTIBLE_EXTENSION_PATTERN, ".jpg");
+    }
+    return `${filename}.jpg`;
+}
+function unchanged(file, reason, width = 0, height = 0, targetWidth = width, targetHeight = height) {
+    return {
+        file,
+        optimized: false,
+        reason,
+        originalSizeBytes: file.size,
+        optimizedSizeBytes: file.size,
+        width,
+        height,
+        targetWidth,
+        targetHeight,
+    };
+}
+function closeSource(source) {
+    if ("close" in source && typeof source.close === "function")
+        source.close();
+}
+function scale(width, height) {
+    const largest = Math.max(width, height);
+    if (largest <= MAX_IMAGE_DIMENSION_PX)
+        return { width, height };
+    const factor = MAX_IMAGE_DIMENSION_PX / largest;
+    return {
+        width: Math.max(1, Math.round(width * factor)),
+        height: Math.max(1, Math.round(height * factor)),
+    };
+}
+async function loadImage(file) {
+    // Prefer createImageBitmap — off-main-thread decode, more reliable on
+    // mobile under memory pressure where Image() silently fails.
+    if (typeof createImageBitmap === "function") {
+        try {
+            const bitmap = await createImageBitmap(file);
+            return { status: "decoded", source: bitmap, width: bitmap.width, height: bitmap.height };
+        }
+        catch {
+            // unsupported format / corrupt — fall back to Image()
+        }
+    }
+    const objectUrl = URL.createObjectURL(file);
+    return new Promise((resolve) => {
+        const image = new Image();
+        const cleanup = () => {
+            image.onload = null;
+            image.onerror = null;
+            URL.revokeObjectURL(objectUrl);
+        };
+        image.onload = () => {
+            cleanup();
+            resolve({ status: "decoded", source: image, width: image.naturalWidth, height: image.naturalHeight });
+        };
+        image.onerror = () => {
+            cleanup();
+            resolve({ status: "decode_unavailable" });
+        };
+        image.src = objectUrl;
+    });
+}
+async function canvasToBlob(canvas, mimeType) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (!blob) {
+                reject(new Error("Canvas export returned no data during upload optimization"));
+                return;
+            }
+            resolve(blob);
+        }, mimeType, JPEG_QUALITY);
+    });
+}

package/dist/src/upload/pipeline.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Orchestrator for the app-upload pipeline.
+ *
+ *   File → optimize (image only) → request presigned URL →
+ *     PUT to storage (with retry) → complete → ProcessedFile
+ *
+ * Each step is a focused module (see `optimize.ts`, `transport.ts`); this
+ * file just wires them together so `useFileUpload` callers get one robust
+ * "uploaded" promise instead of a bare-fetch happy path.
+ *
+ * Surface is intentionally minimal: the only knob is an optional
+ * `AbortSignal` for caller cancellation. Optimization, retries, and
+ * timeouts use platform-internal defaults — same conventions as the
+ * in-Lotics direct-upload pipeline.
+ */
+interface UploadInitResponse {
+    upload_url: string;
+    file_id: string;
+    file_storage_key: string;
+}
+interface CompleteResponseFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+    preview_url?: string;
+}
+/**
+ * Caller injects the RPC primitives so this module stays decoupled from the
+ * SDK's auth / bootstrap layer. The pipeline targets a specific app's upload
+ * endpoints via the supplied `initUpload` and `completeUpload`.
+ */
+export interface UploadRpc {
+    initUpload(input: {
+        filename: string;
+        mime_type: string;
+        file_size: number;
+    }): Promise<UploadInitResponse>;
+    completeUpload(input: {
+        file_id: string;
+        file_storage_key: string;
+        filename: string;
+    }): Promise<{
+        file: CompleteResponseFile;
+    }>;
+}
+export interface RunUploadPipelineOptions {
+    signal?: AbortSignal;
+}
+export declare function runUploadPipeline(file: File, rpc: UploadRpc, options?: RunUploadPipelineOptions): Promise<CompleteResponseFile>;
+export {};

package/dist/src/upload/pipeline.js

@@ -0,0 +1,52 @@
+/**
+ * Orchestrator for the app-upload pipeline.
+ *
+ *   File → optimize (image only) → request presigned URL →
+ *     PUT to storage (with retry) → complete → ProcessedFile
+ *
+ * Each step is a focused module (see `optimize.ts`, `transport.ts`); this
+ * file just wires them together so `useFileUpload` callers get one robust
+ * "uploaded" promise instead of a bare-fetch happy path.
+ *
+ * Surface is intentionally minimal: the only knob is an optional
+ * `AbortSignal` for caller cancellation. Optimization, retries, and
+ * timeouts use platform-internal defaults — same conventions as the
+ * in-Lotics direct-upload pipeline.
+ */
+import { optimizeImageForUpload } from "./optimize.js";
+import { putToStorageWithRetry } from "./transport.js";
+export async function runUploadPipeline(file, rpc, options = {}) {
+    const { signal } = options;
+    // 1. Compress images. Non-image files return unchanged. Failures here are
+    //    intentionally swallowed — the user shouldn't see an upload error
+    //    because canvas threw; we just upload the original bytes.
+    let candidate = file;
+    try {
+        const optimized = await optimizeImageForUpload(file);
+        candidate = optimized.file;
+    }
+    catch {
+        // fall through with original file
+    }
+    if (signal?.aborted)
+        throw new Error("Upload aborted");
+    // 2. Ask the backend for a presigned upload URL.
+    const init = await rpc.initUpload({
+        filename: candidate.name,
+        mime_type: candidate.type,
+        file_size: candidate.size,
+    });
+    // 3. PUT the bytes with timeout + retry. This is the mobile-network
+    //    failure point.
+    const putResponse = await putToStorageWithRetry(init.upload_url, candidate, signal);
+    if (!putResponse.ok) {
+        throw new Error(`Storage upload failed (${putResponse.status}). Please check your connection and try again.`);
+    }
+    // 4. Finalize — the server validates the object and creates the file row.
+    const { file: uploaded } = await rpc.completeUpload({
+        file_id: init.file_id,
+        file_storage_key: init.file_storage_key,
+        filename: candidate.name,
+    });
+    return uploaded;
+}

package/dist/src/upload/transport.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Transport-layer helpers for the SDK upload pipeline.
+ *
+ * Two concerns this module owns:
+ *
+ * 1. **Per-request timeout.** A bare `fetch` hangs forever if the network is
+ *    unreachable; we wrap it in an `AbortController` so a stuck request fails
+ *    after `UPLOAD_TIMEOUT_MS` instead of leaving the user staring at a
+ *    spinner.
+ *
+ * 2. **Retry with exponential backoff** for the presigned `PUT` to object
+ *    storage — the single most failure-prone step on mobile networks. We
+ *    retry on network errors / 5xx / timeouts up to `UPLOAD_PUT_MAX_ATTEMPTS`
+ *    with 1s → 2s → 4s waits between attempts. We do NOT retry on 4xx
+ *    (client error, retrying won't help) or on caller-initiated aborts.
+ *
+ * Mirrors the conventions in `frontend/lib/api_utils.ts` and
+ * `frontend/lib/file_upload.ts`, simplified for the SDK (no logger, no
+ * correlation headers).
+ */
+export declare const UPLOAD_TIMEOUT_MS: number;
+export declare class UploadTimeoutError extends Error {
+    readonly url: string;
+    readonly timeoutMs: number;
+    readonly name = "UploadTimeoutError";
+    constructor(url: string, timeoutMs: number);
+}
+export declare class UploadAbortedError extends Error {
+    readonly name = "UploadAbortedError";
+    constructor();
+}
+/** `fetch` with timeout + optional external `AbortSignal`. */
+export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response>;
+/**
+ * Presigned-PUT to object storage with retry + backoff.
+ *
+ * Retries network errors, timeouts, and 5xx responses up to
+ * `UPLOAD_PUT_MAX_ATTEMPTS` times. A 4xx response is returned to the caller
+ * unchanged (retrying a 403/400 won't help; the caller decides). Aborts
+ * propagate immediately without retry.
+ */
+export declare function putToStorageWithRetry(uploadUrl: string, file: File, signal: AbortSignal | undefined): Promise<Response>;

package/dist/src/upload/transport.js

@@ -0,0 +1,128 @@
+/**
+ * Transport-layer helpers for the SDK upload pipeline.
+ *
+ * Two concerns this module owns:
+ *
+ * 1. **Per-request timeout.** A bare `fetch` hangs forever if the network is
+ *    unreachable; we wrap it in an `AbortController` so a stuck request fails
+ *    after `UPLOAD_TIMEOUT_MS` instead of leaving the user staring at a
+ *    spinner.
+ *
+ * 2. **Retry with exponential backoff** for the presigned `PUT` to object
+ *    storage — the single most failure-prone step on mobile networks. We
+ *    retry on network errors / 5xx / timeouts up to `UPLOAD_PUT_MAX_ATTEMPTS`
+ *    with 1s → 2s → 4s waits between attempts. We do NOT retry on 4xx
+ *    (client error, retrying won't help) or on caller-initiated aborts.
+ *
+ * Mirrors the conventions in `frontend/lib/api_utils.ts` and
+ * `frontend/lib/file_upload.ts`, simplified for the SDK (no logger, no
+ * correlation headers).
+ */
+export const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+const UPLOAD_PUT_MAX_ATTEMPTS = 3;
+const UPLOAD_PUT_BACKOFF_BASE_MS = 1000;
+export class UploadTimeoutError extends Error {
+    url;
+    timeoutMs;
+    name = "UploadTimeoutError";
+    constructor(url, timeoutMs) {
+        super(`Upload request to ${url} timed out after ${timeoutMs}ms`);
+        this.url = url;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class UploadAbortedError extends Error {
+    name = "UploadAbortedError";
+    constructor() {
+        super("Upload aborted");
+    }
+}
+/** `fetch` with timeout + optional external `AbortSignal`. */
+export async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    let didTimeout = false;
+    const timeoutId = setTimeout(() => {
+        didTimeout = true;
+        controller.abort();
+    }, timeoutMs);
+    if (init.signal) {
+        if (init.signal.aborted) {
+            clearTimeout(timeoutId);
+            throw new UploadAbortedError();
+        }
+        init.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (err) {
+        if (didTimeout)
+            throw new UploadTimeoutError(url, timeoutMs);
+        if (init.signal?.aborted)
+            throw new UploadAbortedError();
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Presigned-PUT to object storage with retry + backoff.
+ *
+ * Retries network errors, timeouts, and 5xx responses up to
+ * `UPLOAD_PUT_MAX_ATTEMPTS` times. A 4xx response is returned to the caller
+ * unchanged (retrying a 403/400 won't help; the caller decides). Aborts
+ * propagate immediately without retry.
+ */
+export async function putToStorageWithRetry(uploadUrl, file, signal) {
+    let lastError;
+    for (let attempt = 1; attempt <= UPLOAD_PUT_MAX_ATTEMPTS; attempt += 1) {
+        try {
+            const response = await fetchWithTimeout(uploadUrl, {
+                method: "PUT",
+                headers: { "Content-Type": file.type },
+                body: file,
+                signal,
+            }, UPLOAD_TIMEOUT_MS);
+            if (response.ok)
+                return response;
+            // 4xx is terminal — retrying a malformed/expired URL is pointless.
+            if (response.status >= 400 && response.status < 500)
+                return response;
+            // 5xx — fall through to retry.
+            lastError = new Error(`Storage PUT returned ${response.status}`);
+        }
+        catch (err) {
+            // Caller-initiated abort: stop immediately.
+            if (err instanceof UploadAbortedError)
+                throw err;
+            lastError = err;
+        }
+        if (attempt < UPLOAD_PUT_MAX_ATTEMPTS) {
+            const delayMs = UPLOAD_PUT_BACKOFF_BASE_MS * 2 ** (attempt - 1);
+            await sleep(delayMs, signal);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Storage PUT failed");
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new UploadAbortedError());
+            return;
+        }
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const cleanup = () => {
+            clearTimeout(timeoutId);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new UploadAbortedError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/package.json

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