@lotics/app-sdk 0.55.3 → 0.56.1

package/AGENTS.md

@@ -20,7 +20,7 @@ signature; open the file.**
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, preview pairing, filter operators, the server-side delivery bounds. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen. |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 

package/dist/src/rpc.js

@@ -1,4 +1,3 @@
-import { promptForPassword } from "./password_gate.js";
 import { runUploadPipeline } from "./upload/pipeline.js";
 import { parseSearch, serializeMerge, } from "./url_params.js";
 /**
@@ -346,44 +345,23 @@ let sessionToken = null;
  * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
  */
 export const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
-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;
+/**
+ * The cookie the app-host Worker sets after the visitor clears the password
+ * gate. Readable by design — the SDK forwards its value as the session header
+ * on every data call. Same exposure as the `localStorage` token it replaced,
+ * minus the password prompt the SDK no longer owns.
+ */
+const SESSION_COOKIE = "lotics_app_session";
+function readSessionCookie() {
+    for (const part of document.cookie.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() === SESSION_COOKIE) {
+            return decodeURIComponent(part.slice(eq + 1).trim()) || 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));
-    }
-    catch {
-        // ignore
     }
+    return null;
 }
 /**
  * Resolve the app's identity + analytics config from its own subdomain. Shared
@@ -412,13 +390,12 @@ async function boot() {
     const attempt = (async () => {
         const info = await resolveAppInfo();
         if (info.requires_password) {
-            const stored = readStoredSession(info.app_id);
-            if (stored) {
-                sessionToken = stored;
-            }
-            else {
-                await acquireSessionToken(info.app_id);
-            }
+            // The visitor already passed the gate — the app-host Worker refuses to
+            // serve a single byte of this bundle otherwise — and handed us the session
+            // in a cookie on this origin. The SDK does not prompt: a password screen
+            // is the serving layer's job, which is why it can be one styled, localized
+            // page for every public app instead of hand-rolled DOM in a data library.
+            sessionToken = readSessionCookie();
         }
         return info;
     })();
@@ -429,23 +406,6 @@ async function boot() {
     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 };
-            }
-        },
-    });
-}
 /**
  * A user-facing message for a transport/gateway failure — derived from the HTTP
  * status, never from the response body. A 524 (Cloudflare edge timeout on a long
@@ -528,15 +488,21 @@ async function apiCall(method, path, body, opts) {
     }
     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.
+        // The session went stale — the owner rotated or cleared the password, so the
+        // token's fingerprint no longer matches. Reloading is the whole recovery:
+        // the app-host Worker re-checks its own cookie and, if that is stale too,
+        // serves the gate. The SDK deliberately owns no re-prompt — the gate is a
+        // page at the serving layer, not a modal inside the data layer.
         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 });
+            // `/__gate`, not a plain reload: the edge cookie outlives the API session
+            // (rotation kills the session immediately, the cookie only on expiry), so
+            // reloading would be served the bundle again and loop forever. This route
+            // clears both cookies and re-presents the gate.
+            window.location.assign("/__gate");
+            // Never resolves — navigation replaces the document. Returning would let
+            // callers render an error state during teardown.
+            return new Promise(() => { });
         }
         // Never surface a non-JSON body (a gateway HTML error page) or a 5xx body as
         // the message — emit a body-free, status-derived message instead.

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

@@ -1,10 +1,11 @@
 /**
  * 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.
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) and no document needs
+ * megapixels. Resize to ≤1568px on the long edge — the vision model's own
+ * working resolution, above which the provider downsamples anyway — and
+ * re-encode as JPEG at q=0.9, which keeps small glyphs (container numbers,
+ * invoice lines) legible to a reader and to an extraction agent.
  *
  * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
  * pass through unchanged. Falls through gracefully on any browser API gap

package/dist/src/upload/optimize.js

@@ -1,10 +1,11 @@
 /**
  * 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.
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) and no document needs
+ * megapixels. Resize to ≤1568px on the long edge — the vision model's own
+ * working resolution, above which the provider downsamples anyway — and
+ * re-encode as JPEG at q=0.9, which keeps small glyphs (container numbers,
+ * invoice lines) legible to a reader and to an extraction agent.
  *
  * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
  * pass through unchanged. Falls through gracefully on any browser API gap
@@ -15,8 +16,10 @@
  * 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;
+// MIRRORS `@lotics/shared/image_policy` — the SDK ships dependency-free so it
+// cannot import it. Change both together.
+const MAX_IMAGE_DIMENSION_PX = 1568;
+const JPEG_QUALITY = 0.9;
 const CONVERTIBLE_EXTENSION_PATTERN = /\.(heic|heif|png|webp)$/i;
 export async function optimizeImageForUpload(file) {
     const format = getOptimizableFormat(file);

package/docs/ai.md

@@ -20,7 +20,7 @@ A declaration carries:
 | Field | Meaning |
 |---|---|
 | `instructions` | System instructions — the task the agent performs per run |
-| `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. **This is the capability boundary** — the run can use nothing else. May be empty for a pure-reasoning agent |
+| `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. **This is the capability boundary** — the run can use nothing else. May be empty — including for an agent that reads documents, since a [`file` input carries its own content](#file-inputs--what-the-agent-can-actually-see) |
 | `model_id` | The chat model the agent runs on |
 | `effort_level` | Optional reasoning depth for adaptive-thinking models |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it |
@@ -181,9 +181,21 @@ On recovery, `output` adopts the row's output **only when it is an object** (a s
 
 Sessions are scoped to the authenticated member who ran them: two members using the same `sessionId` string share nothing, and a member can never read or extend another member's thread.
 
-### File inputs → vision
+### File inputs — what the agent can actually see
 
-A declared `file` input (single or `multi`) is materialized into the model's native perception when the type supports it: **`image/*` becomes a vision part, `application/pdf` a document part** — the agent literally sees the file, no OCR tooling needed. Any other type (docx, xlsx, csv, …) is passed as a `file_id` reference instead; the agent can only open it if a file-reading tool is in its declared `tool_names`. Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
+**A `file` input carries its own content. You do not declare a tool to read it.**
+
+| Tier | Types | How the agent gets it |
+|---|---|---|
+| **Perceived natively** | `image/*`, `application/pdf` | A vision / document part — the agent literally sees it |
+| **Materialized** | Word (`.docx`/`.doc`), Excel (`.xlsx`/`.xls`), CSV, and text (`.txt`, `.md`, `.json`, `.eml`, `.html`, `.xml`, `.yaml`) | Read server-side by the same engines `view_files` uses and inlined into the run's message, truncated at 40,000 characters with the agent told when that happened |
+| **Unreadable** | Archives, audio, video | The run fails immediately, naming the file — a fact about the upload, not a gap in your configuration |
+
+Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
+
+**Why no tool:** the content ends up in the agent's context either way, so making it fetch what the server already holds costs a model round-trip and buys nothing. It also keeps the capability boundary tight — an agent that reads its own input never gains the ability to read *other* files in the workspace.
+
+**When to add a tool anyway.** Only to reach *past* what was inlined. A spreadsheet is materialized at 100 rows × 50 columns per sheet and a Word file at 1,000 elements; overflow is reported, never silent. If the agent must read row 4,000 of a large sheet, add `excel_get_range` / `excel_find_cells` (or `view_files` for an ad-hoc second look at a different file).
 
 ### Auth, quota, and bounds
 

package/docs/runtime.md

@@ -129,20 +129,16 @@ fails. Dev apps are always bridged; standalone mode exists only on the deployed
 On first data call the SDK resolves the app's identity from its own subdomain
 (one shared `GET /v1/apps/by-subdomain/{slug}` fetch — concurrent first calls
 coalesce; a transient failure isn't cached, the next call retries). If the app
-is password-protected, the SDK renders its own full-screen password overlay
-(plain DOM, so it works before React data arrives), exchanges the password for a
-session token, and stores it in `localStorage` under
-`lotics_app_session:<app_id>` with its expiry. The token rides on subsequent
-calls in its own `X-Lotics-App-Session` header — deliberately not
-`Authorization`, which carries API keys and OAuth bearers: this token
-authenticates nobody, it proves the visitor knows the shared password, and
-sharing the credential header made the auth layer reject it before the password
-gate could read it. A `401` with error code `PASSWORD_REQUIRED` (the
-owner rotated or cleared the password) drops the stored token, re-prompts, and
-retries the original call once. There is no cancel button — the visitor enters
-the password or leaves. When `localStorage` is unavailable (private browsing,
-quota) the token lives in memory for the page's lifetime and the next reload
-re-prompts. What the password does and doesn't protect: [security](./security.md).
+is password-protected, the visitor never reaches the app at all until they
+clear the gate: `<slug>.lotics.app` is served by the app-host Worker, which
+withholds every byte of the bundle and serves a password page instead. On
+success it sets `lotics_app_session` on the app's origin; the SDK reads that
+cookie and forwards it as `X-Lotics-App-Session` on data calls. The SDK owns no
+password UI — a gate is a property of *serving* an app, not of fetching data,
+so it lives at the serving layer where one styled, localized page covers every
+public app. A `401` with error code `PASSWORD_REQUIRED` (the owner rotated or
+cleared the password) reloads the page, which puts the visitor back through the
+gate. What the password does and doesn't protect: [security](./security.md).
 
 ### Transport error semantics
 

package/package.json

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

package/dist/src/password_gate.d.ts

@@ -1,29 +0,0 @@
-/**
- * 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

@@ -1,142 +0,0 @@
-/**
- * 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;
-}