@lotics/app-sdk 0.56.0 → 0.57.0

package/AGENTS.md

@@ -17,10 +17,10 @@ signature; open the file.**
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
 | [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, data discipline, the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`. |
-| [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/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. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [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/hooks.d.ts

@@ -1,3 +1,4 @@
+import { type ImageFidelity } from "./upload/optimize.js";
 import { type AiContextValue } from "./rpc.js";
 import { type AgentUIPart, type PendingChoice } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppQueries, AppAgents, AppAgentResults } from "./types.js";
@@ -302,8 +303,17 @@ interface FileUploadState {
      * Upload one file. Resolves to the stored file; pass `UploadedFile.id` into
      * a `useWorkflow` call to attach it to a record. Rejects on failure — the
      * file is never partially stored.
+     *
+     * `fidelity` says how much of the image must survive storage; it defaults to
+     * `"high"`, which keeps the text of a photographed document legible. Only
+     * photographs are affected — a PDF, Word or Excel file is stored untouched at
+     * every step. Pass `"standard"` for bulk visual capture (a forty-photo survey,
+     * where the volume is what costs you), or `"original"` when the pixels
+     * themselves are the evidence.
      */
-    upload: (file: File) => Promise<UploadedFile>;
+    upload: (file: File, options?: {
+        fidelity?: ImageFidelity;
+    }) => Promise<UploadedFile>;
     /** True while any upload from this hook is in flight. */
     uploading: boolean;
     /** Message of the most recent failed upload, cleared when a new one starts. */
@@ -341,7 +351,9 @@ interface AttachmentsState {
     /** Add picked/pasted/dropped files — each shows its local preview at once and
      *  uploads in the background. Picking is the app's choice: wire a button to
      *  `@lotics/ui` `pickFiles`, or a paste/drop handler, then call this. */
-    add: (files: File[]) => void;
+    add: (files: File[], options?: {
+        fidelity?: ImageFidelity;
+    }) => void;
     /** Remove one attachment and revoke its preview URL. */
     remove: (id: string) => void;
     /** Remove all attachments and revoke their preview URLs. */

package/dist/src/hooks.js

@@ -16,6 +16,7 @@
  * `useState` — they have nothing to share.
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
@@ -242,12 +243,13 @@ export function usePaginatedQuery(alias, params, opts) {
 export function useFileUpload() {
     const [inFlight, setInFlight] = useState(0);
     const [error, setError] = useState(null);
-    const upload = useCallback(async (file) => {
+    const upload = useCallback(async (file, options) => {
+        const fidelity = options?.fidelity ?? DEFAULT_IMAGE_FIDELITY;
         setInFlight((n) => n + 1);
         setError(null);
         try {
-            const uploaded = await rpc("upload", { file });
-            captureAppEvent("app_file_uploaded", { mime_type: file.type });
+            const uploaded = await rpc("upload", { file, fidelity });
+            captureAppEvent("app_file_uploaded", { mime_type: file.type, fidelity });
             return uploaded;
         }
         catch (err) {
@@ -287,7 +289,7 @@ let attachSeq = 0;
 export function useAttachments() {
     const { upload } = useFileUpload();
     const [files, setFiles] = useState([]);
-    const add = useCallback((incoming) => {
+    const add = useCallback((incoming, options) => {
         for (const file of incoming) {
             const id = `att_${(attachSeq += 1)}`;
             const previewUrl = URL.createObjectURL(file);
@@ -295,7 +297,7 @@ export function useAttachments() {
                 ...prev,
                 { id, filename: file.name, mime_type: file.type, preview_url: previewUrl, status: "uploading" },
             ]);
-            upload(file)
+            upload(file, options)
                 .then((uploaded) => setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "ready", file_id: uploaded.id } : f))))
                 .catch(() => setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "error" } : f))));
         }

package/dist/src/rpc.js

@@ -525,7 +525,7 @@ function rpcStandalone(op, payload) {
         case "agentRun.cancel":
             return standaloneAgentRunCancel(payload);
         case "upload":
-            return standaloneUpload(payload.file);
+            return standaloneUpload(payload.file, payload.fidelity);
         case "members":
             return standaloneMembers(payload);
         case "context":
@@ -705,7 +705,7 @@ async function standaloneAgentRunCancel(p) {
     });
     return { ok: true };
 }
-async function standaloneUpload(file) {
+async function standaloneUpload(file, fidelity) {
     if (!(file instanceof File)) {
         throw new Error("upload payload must include a File");
     }
@@ -713,6 +713,6 @@ async function standaloneUpload(file) {
     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 }),
-    });
+    }, { fidelity });
     return uploaded;
 }

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

@@ -1,10 +1,12 @@
 /**
  * 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 ≤2000px on the long edge — above the standard vision
+ * tier's 1568px so a high-resolution reader keeps real detail, but under the
+ * limit that rejects requests carrying more than 20 images — 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
@@ -12,10 +14,32 @@
  *
  * 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
+ * dependency-free (no logger, no ImageFidelity 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";
+/**
+ * How faithful the STORED image must be — a closed ordinal scale, not a taxonomy
+ * of subjects, so a caller can read the value and know what it costs.
+ * `@lotics/shared/image_policy` carries the same scale and the reasoning.
+ */
+export type ImageFidelity = "original" | "high" | "standard";
+/**
+ * What an upload defaults to when the caller says nothing. MIRRORS
+ * `@lotics/shared/image_policy` — this package ships dependency-free and cannot
+ * import it — and a test fails when the two drift.
+ *
+ * `high` because the surfaces that do not think about this mostly carry text; a
+ * caller collecting in volume declares `"standard"` and pays a fraction as much.
+ */
+export declare const DEFAULT_IMAGE_FIDELITY: ImageFidelity;
+export interface ImagePolicy {
+    maxDimensionPx: number;
+    jpegQuality: number;
+}
+/** The mirror, exposed so the drift guard can compare it with the shared
+ *  source of truth. Not part of the package's public surface. */
+export declare const IMAGE_POLICIES_FOR_TEST: Record<"high" | "standard", ImagePolicy>;
+export type OptimizationReason = "optimized" | "skipped_original" | "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;
@@ -27,4 +51,4 @@ export interface OptimizationResult {
     targetWidth: number;
     targetHeight: number;
 }
-export declare function optimizeImageForUpload(file: File): Promise<OptimizationResult>;
+export declare function optimizeImageForUpload(file: File, fidelity?: ImageFidelity): Promise<OptimizationResult>;

package/dist/src/upload/optimize.js

@@ -1,10 +1,12 @@
 /**
  * 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 ≤2000px on the long edge — above the standard vision
+ * tier's 1568px so a high-resolution reader keeps real detail, but under the
+ * limit that rejects requests carrying more than 20 images — 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
@@ -12,13 +14,36 @@
  *
  * 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
+ * dependency-free (no logger, no ImageFidelity abstraction) so the SDK ships
  * as a single drop-in.
  */
-const MAX_IMAGE_DIMENSION_PX = 1280;
-const JPEG_QUALITY = 0.75;
+/**
+ * What an upload defaults to when the caller says nothing. MIRRORS
+ * `@lotics/shared/image_policy` — this package ships dependency-free and cannot
+ * import it — and a test fails when the two drift.
+ *
+ * `high` because the surfaces that do not think about this mostly carry text; a
+ * caller collecting in volume declares `"standard"` and pays a fraction as much.
+ */
+export const DEFAULT_IMAGE_FIDELITY = "high";
+// MIRRORS `@lotics/shared/image_policy` — the SDK ships dependency-free so it
+// cannot import it. Change both together.
+//  · standard — bulk visual evidence, NEVER read by a model, so tokens do not
+//    enter it: sized purely for upload time and storage across dozens of files.
+//  · high     — read by a model or a person. Token cost depends on DIMENSION
+//    alone, so this buys quality (free in tokens) and keeps the dimension modest.
+const IMAGE_POLICIES = {
+    standard: { maxDimensionPx: 1280, jpegQuality: 0.8 },
+    high: { maxDimensionPx: 1568, jpegQuality: 0.95 },
+};
+/** The mirror, exposed so the drift guard can compare it with the shared
+ *  source of truth. Not part of the package's public surface. */
+export const IMAGE_POLICIES_FOR_TEST = IMAGE_POLICIES;
 const CONVERTIBLE_EXTENSION_PATTERN = /\.(heic|heif|png|webp)$/i;
-export async function optimizeImageForUpload(file) {
+export async function optimizeImageForUpload(file, fidelity = DEFAULT_IMAGE_FIDELITY) {
+    if (fidelity === "original")
+        return unchanged(file, "skipped_original");
+    const policy = IMAGE_POLICIES[fidelity];
     const format = getOptimizableFormat(file);
     const mimeType = format?.outputMimeType;
     const unsupportedReason = getUnsupportedReason(file, mimeType);
@@ -34,11 +59,11 @@ export async function optimizeImageForUpload(file) {
         closeSource(source);
         return unchanged(file, "skipped_invalid_dimensions");
     }
-    if (Math.max(width, height) <= MAX_IMAGE_DIMENSION_PX) {
+    if (Math.max(width, height) <= policy.maxDimensionPx) {
         closeSource(source);
         return unchanged(file, "skipped_small_dimensions", width, height);
     }
-    const { width: targetWidth, height: targetHeight } = scale(width, height);
+    const { width: targetWidth, height: targetHeight } = scale(width, height, policy.maxDimensionPx);
     const canvas = document.createElement("canvas");
     canvas.width = targetWidth;
     canvas.height = targetHeight;
@@ -51,7 +76,7 @@ export async function optimizeImageForUpload(file) {
     ctx.imageSmoothingQuality = "high";
     ctx.drawImage(source, 0, 0, targetWidth, targetHeight);
     closeSource(source);
-    const blob = await canvasToBlob(canvas, mimeType);
+    const blob = await canvasToBlob(canvas, mimeType, policy.jpegQuality);
     if (blob.type !== mimeType) {
         return unchanged(file, "skipped_canvas_type_mismatch", width, height, targetWidth, targetHeight);
     }
@@ -128,11 +153,11 @@ function closeSource(source) {
     if ("close" in source && typeof source.close === "function")
         source.close();
 }
-function scale(width, height) {
+function scale(width, height, maxDimensionPx) {
     const largest = Math.max(width, height);
-    if (largest <= MAX_IMAGE_DIMENSION_PX)
+    if (largest <= maxDimensionPx)
         return { width, height };
-    const factor = MAX_IMAGE_DIMENSION_PX / largest;
+    const factor = maxDimensionPx / largest;
     return {
         width: Math.max(1, Math.round(width * factor)),
         height: Math.max(1, Math.round(height * factor)),
@@ -169,7 +194,7 @@ async function loadImage(file) {
         image.src = objectUrl;
     });
 }
-async function canvasToBlob(canvas, mimeType) {
+async function canvasToBlob(canvas, mimeType, jpegQuality) {
     return new Promise((resolve, reject) => {
         canvas.toBlob((blob) => {
             if (!blob) {
@@ -177,6 +202,6 @@ async function canvasToBlob(canvas, mimeType) {
                 return;
             }
             resolve(blob);
-        }, mimeType, JPEG_QUALITY);
+        }, mimeType, jpegQuality);
     });
 }

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

@@ -13,6 +13,7 @@
  * timeouts use platform-internal defaults — same conventions as the
  * in-Lotics direct-upload pipeline.
  */
+import { type ImageFidelity } from "./optimize.js";
 interface UploadInitResponse {
     upload_url: string;
     file_id: string;
@@ -47,6 +48,8 @@ export interface UploadRpc {
 }
 export interface RunUploadPipelineOptions {
     signal?: AbortSignal;
+    /** What the surface is collecting — selects the stored image resolution. */
+    fidelity?: ImageFidelity;
 }
 export declare function runUploadPipeline(file: File, rpc: UploadRpc, options?: RunUploadPipelineOptions): Promise<CompleteResponseFile>;
 export {};

package/dist/src/upload/pipeline.js

@@ -13,16 +13,16 @@
  * timeouts use platform-internal defaults — same conventions as the
  * in-Lotics direct-upload pipeline.
  */
-import { optimizeImageForUpload } from "./optimize.js";
+import { optimizeImageForUpload, DEFAULT_IMAGE_FIDELITY } from "./optimize.js";
 import { putToStorageWithRetry } from "./transport.js";
 export async function runUploadPipeline(file, rpc, options = {}) {
-    const { signal } = options;
+    const { signal, fidelity = DEFAULT_IMAGE_FIDELITY } = 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);
+        const optimized = await optimizeImageForUpload(file, fidelity);
         candidate = optimized.file;
     }
     catch {

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/files.md

@@ -14,6 +14,8 @@ discipline in [data fetching](./data_fetching.md).
 |---|---|---|
 | Collect bytes from the visitor | `useFileUpload().upload(file)` | `UploadedFile` — a stored, **unattached** file id + presigned serving URLs |
 | Collect several with live previews | `useAttachments()` | `AttachedFile[]` with instant local previews; `fileIds` when done |
+
+`useAttachments().add(files, { fidelity })` takes the same `fidelity` as `upload`.
 | Attach to a record | a declared workflow with a `{ type: "file" }` input | the workflow writes the id(s) into a `files` field — the **only** write path |
 | Read back from records | `useQuery` + `readFiles(cell)` | `AppFile[]` — presigned `url`/`thumbnail_url` (24 h) + `size`/`created_at` |
 | Receive a generated document | `useWorkflow` → `WorkflowResult.files` | presigned files auto-extracted from the run |
@@ -30,17 +32,40 @@ declared workflow (see [mutations](./mutations.md)).
 const { upload, uploading, error } = useFileUpload();
 const submit = useWorkflow("submitOrder");
 
-const photo = await upload(file);            // File → UploadedFile
-await submit({ ...fields, photo_file_id: photo.id });
+const invoiceShot = await upload(file);                       // high (default)
+const surveyPhoto = await upload(file, { fidelity: "standard" }); // bulk capture
+await submit({ ...fields, invoice_file_id: invoiceShot.id });
 ```
 
 Signature: `dist/src/hooks.d.ts`. Returns `{ upload, uploading, error }`:
 
-- `upload(file: File): Promise<UploadedFile>` — resolves to the stored file; rejects on failure
+- `upload(file: File, options?: { fidelity }): Promise<UploadedFile>` — resolves to the stored file; rejects on failure
   (the file is never partially stored). `UploadedFile` is
   `{ id, filename, mime_type, url?, thumbnail_url? }` — `url`/`thumbnail_url` are presigned
   (24 h) and load directly in the sandboxed iframe, so a just-uploaded image previews without a
   round-trip.
+- `fidelity` — **how faithful the stored image must be.** An ordinal scale, so the value tells
+  you what it costs without looking up a mapping. The platform owns the pixels behind each step
+  and re-tunes them centrally as model tiers change.
+
+  Defaults to `"high"` — enough to resolve the text of a photographed document. Drop to
+  `"standard"` when collecting in volume.
+
+  **This only affects photographs.** A PDF, Word, Excel or CSV file is stored untouched at every
+  step, so `"original"` is not what keeps a document intact — it already is. Reach for it when
+  the PIXELS are the evidence. Note too that HEIC (what an iPhone camera produces) is transcoded
+  to JPEG server-side whatever you choose, because no browser can render it.
+
+  | `fidelity` | Use it when | Stored at |
+  |---|---|---|
+  | `"standard"` | The image is only looked AT and archived — site and container surveys, the forty-image drop. Never read by a model, so it is sized purely for upload speed and storage. | 1280 px, q 0.80 |
+  | `"high"` *(default)* | The image is READ — invoices, release orders, screenshots of dense tables — by a model or a person. Near-lossless, because a model's token cost depends on dimension alone, so quality is free accuracy. | 1568 px, q 0.95 |
+  | `"original"` | The bytes themselves matter: evidence of record, or anything that may be re-read at a higher fidelity later. | unchanged |
+
+  Getting it wrong is never fatal — too low stores fewer pixels than the reader wanted, it never
+  produces a wrong answer. Rule of thumb: **if text on the image has to be legible, or a person
+  may zoom, use `"high"`.** Reach for `"original"` only when the file IS the record rather than
+  a picture of it — it is the one step whose meaning survives a change to these numbers.
 - `uploading` — true while **any** upload from this hook is in flight.
 - `error` — message of the most recent failed upload; cleared when a new one starts.
 

package/package.json

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