@lotics/app-sdk 0.98.5 → 0.100.1

package/AGENTS.md

@@ -17,8 +17,8 @@ signature; open the file.**
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [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 four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate at 10,000 — `useQuery` says so with `truncated`), the ROW type (`RowOf` — the alias's projected columns and nothing else, values `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys AND the `useFieldOptions` map keyed against that same projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*` — `row.num` and `row.bool` answer `null` for an EMPTY cell, so none is distinguishable from zero and an unanswered checkbox from a "no" — `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, and `readCreatedAt`/`readUpdatedAt` for the record timestamps every row-level result carries), caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), 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 (`field_errors` locates a refusal on the control it belongs to, where `message` can only say it at the dialog's scope), typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
-| [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + explicit `linked()` descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
+| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract (`field_errors` locates a refusal on the control it belongs to, where `message` can only say it at the dialog's scope), typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write), `useRecording` (the HOST records the member — mic, system sound, screen — and files the transcribed recording through a receiving workflow exactly once; `available` gates the control, `state` follows the recording). |
+| [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + explicit `linked()` descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the `recording` input a workflow declares to receive a recording, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments` (**the add-queue, and which lifecycle it keeps**: a composer clears, a record passes `landed` and each entry leaves as the stored pile takes it over), `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted; and a LOOKUP of a files field is one list per linked row, which the reader opens itself), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), 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` (keyed by the alias's OWN columns, every key optional), `useViewer`, `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), 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`. |

package/dist/src/hooks.d.ts

@@ -386,7 +386,7 @@ export interface FieldOptions {
     /** The source field's display name — e.g. a picker/section label. */
     label: string;
     /**
-     * Every option of the field — `{ key, label, color }`. Includes options not
+     * Every option of the field — `{ key, label, color, mark? }`. Includes options not
      * present in any current row, so a freshly-added option appears in a picker
      * without an app change, and a removed one drops out.
      */

package/dist/src/index.d.ts

@@ -21,6 +21,9 @@ export type { AttachedFile, AttachmentsOptions, AttachmentsState } from "./attac
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";
+export { useRecording } from "./recording.js";
+export type { UseRecording } from "./recording.js";
+export type { RecordingState, RecordingInputs } from "./recording_state.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
 export { rpc, isEmbedded } from "./rpc.js";

package/dist/src/index.js

@@ -17,6 +17,7 @@ export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
+export { useRecording } from "./recording.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export { rpc, isEmbedded } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/dist/src/mock.d.ts

@@ -35,10 +35,14 @@
  * a static row array cannot, so a master/detail drawer under `?__mock=1` would
  * otherwise show every parent's children under every parent.
  *
+ * `recordings` hands `useRecording` a canned state per alias, so each state a
+ * recording act passes through can be drawn without a host that records.
+ *
  * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
  * different shape from a request/response pair, and nothing has needed it.
  */
 import type { WorkflowResult } from "./hooks.js";
+import type { RecordingState } from "./recording_state.js";
 /**
  * What a mocked workflow answers with: a fixed result, or a function of the
  * inputs it was called with. Return a promise from the function to hold the
@@ -72,6 +76,10 @@ export interface AppFixture {
     /** Map of workflow alias → the result it resolves with when mock mode is on.
      *  The workflow never executes, so nothing it would have written is written. */
     workflows?: Record<string, MockWorkflow>;
+    /** Map of workflow alias → the state `useRecording(alias)` reports when mock
+     *  mode is on. It reads as available, and `start`/`stop` resolve without
+     *  recording anything or changing the state. */
+    recordings?: Record<string, RecordingState>;
 }
 /**
  * Called by `mount({ fixture })`. Module-level state because the SDK has no
@@ -105,3 +113,6 @@ export declare function getMockRows(alias: string, call: MockQueryCall): Array<R
  * app that never calls the workflow pays nothing.
  */
 export declare function getMockWorkflow(alias: string): MockWorkflow | null;
+/** The canned recording states when mock mode is active and the fixture names
+ *  any; otherwise null, and `useRecording` reads the host. */
+export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/src/mock.js

@@ -35,6 +35,9 @@
  * a static row array cannot, so a master/detail drawer under `?__mock=1` would
  * otherwise show every parent's children under every parent.
  *
+ * `recordings` hands `useRecording` a canned state per alias, so each state a
+ * recording act passes through can be drawn without a host that records.
+ *
  * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
  * different shape from a request/response pair, and nothing has needed it.
  */
@@ -112,3 +115,10 @@ export function getMockWorkflow(alias) {
         return null;
     return registeredFixture?.workflows?.[alias] ?? null;
 }
+/** The canned recording states when mock mode is active and the fixture names
+ *  any; otherwise null, and `useRecording` reads the host. */
+export function getMockRecordings() {
+    if (!isMockMode())
+        return null;
+    return registeredFixture?.recordings ?? null;
+}

package/dist/src/recording.d.ts

@@ -0,0 +1,59 @@
+import { type RecordingState } from "./recording_state.js";
+import type { AppWorkflows } from "./types.js";
+/** The platform fills a receiving workflow's `recording` input; the app passes
+ *  the rest of what the workflow declares. */
+type ActInputsOf<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? Omit<AppWorkflows[K], "recording"> : Record<string, unknown>;
+export interface UseRecording<I> {
+    /**
+     * Whether this surface can record. False standalone, in a host that
+     * predates recording, on an instance without transcription, and until the
+     * host's context has answered. A control that starts a recording is drawn
+     * only when this is true.
+     */
+    available: boolean;
+    /** The most recent recording this app started through this alias. */
+    state: RecordingState;
+    /** Whether a recording this app started is live, through any alias. The
+     *  host records one at a time, so a start while this is true is refused. */
+    busy: boolean;
+    /**
+     * Ask the host to record. The host opens its own capture dialog, and nothing
+     * records until the member presses Start there. Resolves `{ started: true }`
+     * once capture runs, `{ started: false }` when the member closed the dialog;
+     * rejects, with the reason, when the host refuses (another recording is
+     * running, the inputs fail the workflow's contract, recording is unavailable).
+     * When the recording is transcribed, the host runs the alias's workflow with
+     * these inputs plus `recording`.
+     */
+    start: {} extends I ? (inputs?: I) => Promise<{
+        started: boolean;
+    }> : (inputs: I) => Promise<{
+        started: boolean;
+    }>;
+    /** Stop this alias's live recording. Resolves whether or not one was live. */
+    stop: () => Promise<void>;
+}
+/**
+ * Record a call, a visit, a meeting — and file it through a workflow.
+ *
+ * `alias` names a workflow that declares the platform's `recording` input; the
+ * host records as the signed-in member and, once the transcript is ready, runs
+ * that workflow once with the app's inputs and the recording. Its write reaches
+ * the screen like any workflow's.
+ *
+ * ```tsx
+ * const visit = useRecording("log_visit");
+ * if (!visit.available) return null;
+ * if (visit.state.phase === "live" && visit.state.inputs.site === siteId) {
+ *   return <Button onPress={() => visit.stop()}>Stop</Button>;
+ * }
+ * return (
+ *   <Button disabled={visit.busy} onPress={() => visit.start({ site: siteId })}>
+ *     Record the visit
+ *   </Button>
+ * );
+ * ```
+ */
+export declare function useRecording<K extends keyof AppWorkflows & string>(alias: K): UseRecording<ActInputsOf<K>>;
+export declare function useRecording(alias: string): UseRecording<Record<string, unknown>>;
+export {};

package/dist/src/recording.js

@@ -0,0 +1,30 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { rpc } from "./rpc.js";
+import { getMockRecordings } from "./mock.js";
+import { useAppContext } from "./viewer.js";
+import { anyRecordingLive, recordingStateOf, subscribeRecordings, } from "./recording_state.js";
+const NO_MOCKS = {};
+export function useRecording(alias) {
+    const { recordingEnabled } = useAppContext();
+    const mocks = getMockRecordings() ?? NO_MOCKS;
+    const mocked = mocks[alias];
+    const hostState = useSyncExternalStore(subscribeRecordings, () => recordingStateOf(alias));
+    const hostBusy = useSyncExternalStore(subscribeRecordings, anyRecordingLive);
+    const start = useCallback(async (inputs) => {
+        if (getMockRecordings()?.[alias])
+            return { started: true };
+        return rpc("recording.start", { alias, inputs: inputs ?? {} });
+    }, [alias]);
+    const stop = useCallback(async () => {
+        if (getMockRecordings()?.[alias])
+            return;
+        await rpc("recording.stop", { alias });
+    }, [alias]);
+    return {
+        available: mocked !== undefined || recordingEnabled,
+        state: mocked ?? hostState,
+        busy: hostBusy || Object.values(mocks).some((state) => state.phase === "live"),
+        start,
+        stop,
+    };
+}

package/dist/src/recording_state.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What the host says about the recordings THIS app started, one per workflow
+ * alias: the most recently started recording through that alias.
+ *
+ * A leaf module, because two sides write it and one reads it: the bridge
+ * listener in `rpc.ts` applies the host's `recordingChanged` push, the context
+ * fetch in `viewer.ts` applies the snapshot a newly loaded frame starts from,
+ * and `useRecording` reads it. Both writes arrive on the one postMessage channel
+ * in the order the host sent them, so the later arrival is always the newer
+ * state.
+ */
+/** The act's own inputs the recording was started with — what `start` was
+ *  passed, echoed back so a screen drawing one act per row can tell which row
+ *  the recording is about. */
+export type RecordingInputs = Record<string, unknown>;
+/**
+ * One recording, from the host's side. `idle`: nothing of this alias's is
+ * running or waiting. `live`: capturing. `interrupted`: the tab closed mid-call
+ * and the member has not yet resumed or finished it from the recording bar.
+ * `processing`: stopped, the transcript is on its way. `filed`: the workflow
+ * ran and succeeded. `failed`: transcription failed, the platform refused to
+ * file (the member lost access, the alias or its declaration changed), or the
+ * run failed; the recording is kept, and the member retries from the recording
+ * bar.
+ */
+export type RecordingState = {
+    phase: "idle";
+} | {
+    phase: "live";
+    elapsed_seconds: number;
+    inputs: RecordingInputs;
+} | {
+    phase: "interrupted";
+    elapsed_seconds: number;
+    inputs: RecordingInputs;
+} | {
+    phase: "processing";
+    inputs: RecordingInputs;
+} | {
+    phase: "filed";
+    execution_id: string;
+    inputs: RecordingInputs;
+} | {
+    phase: "failed";
+    message: string;
+    inputs: RecordingInputs;
+};
+export declare const IDLE_RECORDING: RecordingState;
+export declare function subscribeRecordings(listener: () => void): () => void;
+export declare function recordingStateOf(alias: string): RecordingState;
+export declare function anyRecordingLive(): boolean;
+/** The host's push for one alias. */
+export declare function applyRecordingChange(alias: string, state: RecordingState): void;
+/** The snapshot `context` carries: every alias it omits is idle. */
+export declare function replaceRecordings(snapshot: Record<string, RecordingState>): void;
+/** A host message's `state`, or null when it is not one. */
+export declare function readRecordingState(raw: unknown): RecordingState | null;
+/** A context's `recordings`, keeping each well-formed entry. */
+export declare function readRecordingSnapshot(raw: unknown): Record<string, RecordingState>;

package/dist/src/recording_state.js

@@ -0,0 +1,94 @@
+/**
+ * What the host says about the recordings THIS app started, one per workflow
+ * alias: the most recently started recording through that alias.
+ *
+ * A leaf module, because two sides write it and one reads it: the bridge
+ * listener in `rpc.ts` applies the host's `recordingChanged` push, the context
+ * fetch in `viewer.ts` applies the snapshot a newly loaded frame starts from,
+ * and `useRecording` reads it. Both writes arrive on the one postMessage channel
+ * in the order the host sent them, so the later arrival is always the newer
+ * state.
+ */
+export const IDLE_RECORDING = { phase: "idle" };
+const states = new Map();
+const listeners = new Set();
+function emit() {
+    for (const listener of listeners)
+        listener();
+}
+export function subscribeRecordings(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function recordingStateOf(alias) {
+    return states.get(alias) ?? IDLE_RECORDING;
+}
+export function anyRecordingLive() {
+    for (const state of states.values())
+        if (state.phase === "live")
+            return true;
+    return false;
+}
+/** The host's push for one alias. */
+export function applyRecordingChange(alias, state) {
+    if (state.phase === "idle")
+        states.delete(alias);
+    else
+        states.set(alias, state);
+    emit();
+}
+/** The snapshot `context` carries: every alias it omits is idle. */
+export function replaceRecordings(snapshot) {
+    states.clear();
+    for (const [alias, state] of Object.entries(snapshot)) {
+        if (state.phase !== "idle")
+            states.set(alias, state);
+    }
+    emit();
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** A host message's `state`, or null when it is not one. */
+export function readRecordingState(raw) {
+    if (!isRecord(raw))
+        return null;
+    if (raw.phase === "idle")
+        return IDLE_RECORDING;
+    const inputs = raw.inputs;
+    if (!isRecord(inputs))
+        return null;
+    switch (raw.phase) {
+        case "live":
+        case "interrupted":
+            return typeof raw.elapsed_seconds === "number"
+                ? { phase: raw.phase, elapsed_seconds: raw.elapsed_seconds, inputs }
+                : null;
+        case "processing":
+            return { phase: "processing", inputs };
+        case "filed":
+            return typeof raw.execution_id === "string"
+                ? { phase: "filed", execution_id: raw.execution_id, inputs }
+                : null;
+        case "failed":
+            return typeof raw.message === "string" ? { phase: "failed", message: raw.message, inputs } : null;
+        default:
+            return null;
+    }
+}
+/** A context's `recordings`, keeping each well-formed entry. */
+export function readRecordingSnapshot(raw) {
+    if (!isRecord(raw))
+        return {};
+    const entries = Object.entries(raw).flatMap(([alias, value]) => {
+        const state = readRecordingState(value);
+        if (state === null) {
+            console.error(`The host's context carried a malformed recording for "${alias}"; it reads as idle.`, value);
+            return [];
+        }
+        return [[alias, state]];
+    });
+    return Object.fromEntries(entries);
+}

package/dist/src/rpc.d.ts

@@ -21,7 +21,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;
@@ -82,6 +82,15 @@ export interface AppContext {
      * app that didn't opt in, and (vacuously) for standalone visitors.
      */
     comments_enabled: boolean;
+    /**
+     * Whether this host records for the app: true only from a host that has the
+     * `recording.*` ops, for a signed-in member, on an instance that transcribes.
+     * A host that predates recording omits it, which reads as false.
+     */
+    recording_enabled?: boolean;
+    /** The recordings this app started that the host still tracks, by alias —
+     *  the state a newly loaded frame starts from. */
+    recordings?: Record<string, unknown>;
 }
 /**
  * Whether the app is running embedded in a Lotics host (vs. standalone at its

package/dist/src/rpc.js

@@ -1,4 +1,5 @@
 import { runUploadPipeline } from "./upload/pipeline.js";
+import { applyRecordingChange, readRecordingState, recordingStateOf } from "./recording_state.js";
 import { parseSearch, serializeMerge, } from "./url_params.js";
 /**
  * The embedding Lotics host's origin — present iff the app is bridged.
@@ -192,6 +193,24 @@ function ensureListener() {
                 cb(aliases);
             return;
         }
+        // Broadcast (no id): a recording THIS app started moved — the host sends
+        // no other app's and not the chat's.
+        if (msg.type === "recordingChanged") {
+            const state = readRecordingState(msg.state);
+            if (typeof msg.alias !== "string" || state === null) {
+                console.error("The host sent a malformed recordingChanged push; it is ignored.", msg);
+                return;
+            }
+            const before = recordingStateOf(msg.alias);
+            applyRecordingChange(msg.alias, state);
+            // A filed recording is this app's own successful write, so the screen
+            // re-reads now, as after any workflow, not on the realtime push.
+            const newlyFiled = state.phase === "filed" &&
+                !(before.phase === "filed" && before.execution_id === state.execution_id);
+            if (newlyFiled)
+                notifyLocalWrite();
+            return;
+        }
         if (typeof msg.id !== "number")
             return;
         // Single-response ops.
@@ -738,6 +757,11 @@ function rpcStandalone(op, payload) {
         case "comments.delete":
         case "comments.counts":
             return rejectCommentsStandalone();
+        case "recording.start":
+        case "recording.stop":
+            // The host records, as the signed-in member; a standalone visitor is
+            // anonymous and has no host to capture in.
+            return Promise.reject(new Error("Recording needs the Lotics host and a signed-in member. Gate the control on useRecording's `available`."));
     }
 }
 /**
@@ -794,6 +818,7 @@ async function standaloneContext() {
         // comments are unavailable regardless of the capability flag.
         member_id: null,
         comments_enabled: info.comments_enabled,
+        recording_enabled: false,
     };
 }
 /**

package/dist/src/select.d.ts

@@ -22,6 +22,20 @@ export interface ResolvedOption {
      * degrades a missing/unknown token to a neutral badge.
      */
     color?: string;
+    /**
+     * The option's own mark, where its field gives one to every option — the
+     * channel it IS (`brand`, a `BrandMark` name) or a glyph (`icon`, a kit icon
+     * name). Populated by `useFieldOptions` like `color`, absent on a cell. Pass
+     * the option to `@lotics/ui`'s `Status`, which draws it in the dot's place and
+     * degrades a name its build does not draw to the dot.
+     */
+    mark?: {
+        kind: "brand";
+        name: string;
+    } | {
+        kind: "icon";
+        name: string;
+    };
 }
 /**
  * Parse a `useQuery` cell value into `ResolvedOption[]`. Returns `[]` for

package/dist/src/viewer.d.ts

@@ -6,6 +6,7 @@
 export declare function useAppContext(): {
     memberId: string | null;
     commentsEnabled: boolean;
+    recordingEnabled: boolean;
     resolved: boolean;
 };
 /**

package/dist/src/viewer.js

@@ -1,12 +1,23 @@
 import useSWR from "swr";
 import { rpc } from "./rpc.js";
+import { readRecordingSnapshot, replaceRecordings } from "./recording_state.js";
+/**
+ * The context, with its recording snapshot applied in the same task the
+ * answer arrived in — before any later host push is handled, so the snapshot
+ * can never overwrite a newer push.
+ */
+async function fetchContext() {
+    const context = await rpc("context", {});
+    replaceRecordings(readRecordingSnapshot(context.recordings));
+    return context;
+}
 /**
  * Read the app's context once, shared across every hook via a stable SWR key.
  * The host (the product iframe, or `lotics app dev`) supplies the signed-in
  * member and the app's declared capabilities.
  */
 export function useAppContext() {
-    const { data } = useSWR("app-context", () => rpc("context", {}), {
+    const { data } = useSWR("app-context", fetchContext, {
         revalidateOnFocus: false,
         revalidateIfStale: false,
         revalidateOnReconnect: false,
@@ -15,6 +26,7 @@ export function useAppContext() {
     return {
         memberId: data?.member_id ?? null,
         commentsEnabled: data?.comments_enabled ?? false,
+        recordingEnabled: data?.recording_enabled === true,
         resolved: data !== undefined,
     };
 }

package/docs/members_and_options.md

@@ -77,7 +77,7 @@ rendering with no options; and every key is optional, so the read is through `?.
 | Property | Meaning |
 | --- | --- |
 | `label` | The source field's display name — a ready picker/section label |
-| `options` | Every option of the field — `{ key, label, color }` — in field-config order, **including options not present in any current row** |
+| `options` | Every option of the field — `{ key, label, color, mark? }` (the option's own brand or glyph, where the field marks every option) — in field-config order, **including options not present in any current row** |
 | `byKey(key)` | Resolve one option by key; `undefined` for an unknown key (option removed after the cell was written) |
 
 - `color` is a named palette token (e.g. `"blue"`, `"emerald"`). Pass the option straight to

package/docs/mutations.md

@@ -4,8 +4,8 @@ Everything about writing data from an app: `useWorkflow` (the only write path),
 `WorkflowResult` contract and its resolve-never-throw failure model, declaring typed workflow
 inputs (file/member/optional inputs), returning structured data with `return({ data })`,
 the automatic re-read a successful write triggers, the diff-before-update discipline, locked records
-(`readLocked` + `request_locked_record_change`), and optimistic reconciliation
-(`useOptimistic`). Read this before building any screen that creates, updates, or deletes
+(`readLocked` + `request_locked_record_change`), optimistic reconciliation
+(`useOptimistic`), and `useRecording` — a recording the host files through a workflow. Read this before building any screen that creates, updates, or deletes
 records. What may be written **inside** the workflow body — the JS subset, steps, helpers,
 traps — is [workflows](./workflows.md). Reading data is [queries](./queries.md) +
 [data_fetching](./data_fetching.md); uploads are [files](./files.md); who a write runs as is
@@ -686,3 +686,71 @@ workflow cannot be used to clobber another record by guessing its id.
 
 Use `newRecordId()` directly if you need the id outside a hook (routing to the surface before
 mounting it, say). It mints the same `rec_*` shape the server validates.
+
+## Recording into a workflow: `useRecording`
+
+A recording act — record a site visit, a call, a meeting, and file it on the row it is about —
+is a workflow whose run waits for the transcript. Exact signature: `dist/src/recording.d.ts`.
+
+```tsx
+import { useRecording } from "@lotics/app-sdk";
+
+const visit = useRecording("log_visit");
+if (!visit.available) return null;                     // draw nothing that cannot record
+const mine = visit.state.phase !== "idle" && visit.state.inputs.site === siteId;
+
+const { started } = await visit.start({ site: siteId }); // false: the member closed the dialog
+await visit.stop();
+```
+
+- **The alias names a receiving workflow** — one that declares the platform's `recording` input
+  ([workflows](./workflows.md#a-workflow-that-receives-a-recording)). `start` takes the rest of
+  its declared inputs, typed from the declaration without `recording`; passing `recording` is a
+  `tsc` error and a refusal. Such a workflow runs only from a recording: `useWorkflow` on its
+  alias is refused, because the platform alone fills `recording`.
+- **The host records, never the app.** `start` asks the Lotics host, which opens its own capture
+  dialog — microphone, and where the browser supports it system sound and the screen — named
+  with the app's name. Nothing records until the member presses Start there. The app touches no
+  media device and needs no permission. The recording belongs to the tab, not the frame: the
+  member may leave the app, and a bar in the product carries the recording until it is filed.
+- **`start` resolves `{ started: true }`** once capture runs and **`{ started: false }`** when the
+  member closed the dialog. It **rejects with the host's reason** when refused: a recording is
+  already running (one per tab, across every app and the chat), the member has three recordings
+  still open, the inputs fail the workflow's declaration (a deleted record is refused before
+  anything is recorded, not after), or recording is unavailable. Show the reason.
+- **`stop`** stops this alias's live recording, and resolves whether or not one was live. The
+  member can also stop from the product's bar.
+- **Filing.** Once transcribed, the host runs the workflow **once** with `{ ...inputs,
+  recording }`, under the app owner's authority with the recording member as
+  `runtime.triggered_by_member_id` ([security](./security.md)). A silent recording files with
+  `transcript: ""`. Filing is re-checked at run time: the member still holds the app, the alias
+  is still bound, and its declaration still receives recordings. A refused or failed filing is
+  never retried by itself and the recording is never lost: the member retries from the
+  product's bar, and a failed run also sends the app's owner the failed-run notice.
+- **`available`** is what the host states — false standalone, in `lotics app dev`, in a host
+  that predates recording, on an instance without transcription, and until the context has
+  answered. A standalone app has no member to record as; both calls reject there.
+
+`state` is the most recent recording this app started through the alias (a second recording
+replaces the first's state):
+
+| `phase` | Carries | Means |
+|---|---|---|
+| `idle` | — | nothing through this alias is running or waiting |
+| `live` | `elapsed_seconds`, `inputs` | capturing; the host updates it each second |
+| `interrupted` | `elapsed_seconds`, `inputs` | the tab closed mid-recording; the member resumes or finishes it from the product's bar |
+| `processing` | `inputs` | stopped; the transcript is on its way |
+| `filed` | `execution_id`, `inputs` | the workflow ran and succeeded |
+| `failed` | `message`, `inputs` | transcription failed, or filing was refused or its run failed |
+
+`inputs` is what `start` was passed, so a screen with one act per row can tell which row the
+recording is about. **`busy`** is true while any recording this app started is live, through
+any alias: stand the other acts down, since the host would refuse them. A recording in another
+app or the chat is invisible to this app, so `start` can still be refused while `busy` is false.
+
+**Filed means written.** When `state` becomes `filed`, every mounted query re-reads, exactly as
+after a successful `useWorkflow` call ([refetch](#refetch-after-a-mutation)). Draw the filed row's
+files and transcript with `@lotics/ui/recording`.
+
+A mock fixture's `recordings` map (alias → `state`) draws each phase without a host
+([runtime](./runtime.md#the-mock-harness-optionsfixture--__mock1)).

package/docs/runtime.md

@@ -66,7 +66,7 @@ Activation is a **two-step gate** — both must hold, so demo data shipping in t
 bundle never leaks into normal traffic:
 
 1. A fixture is registered via `mount({ fixture })` (`AppFixture` type:
-   `dist/src/mock.d.ts` — `{ queries?, workflows? }`).
+   `dist/src/mock.d.ts` — `{ queries?, workflows?, recordings? }`).
 2. The page URL carries `?__mock=1` (exactly `1`). Without the flag the fixture
    is completely inert.
 
@@ -99,6 +99,10 @@ transport. Calling `mount` again (HMR) replaces the registration last-write-wins
   whose only AI surface is a workflow calling `agent(...)` otherwise has no
   non-billing path to its own thinking / done / error screens, which is how
   those three ship unreviewed.
+- **A mocked recording is a canned state.** `recordings: { log_visit: { phase:
+  "live", elapsed_seconds: 754, inputs: { site: "rec_1" } } }` makes
+  `useRecording("log_visit")` available with that `state`; `start` and `stop`
+  resolve without recording anything or moving the state.
 - **Not mocked:** uploads, `useFieldOptions`, members, comments, agent runs. In
   mock mode those still hit the real transport.
 - **Analytics is disabled** whenever `?__mock=1` is present, fixture or not — a
@@ -202,6 +206,7 @@ surfaces:
 | `agentRuns` (session history) | **no** — the product host doesn't implement it either (`"Unknown RPC op: agentRuns"`) | **no** | yes |
 | `askAi` | yes | **no** — `"Unknown RPC op: askAi"` | rejects — `"askAi is only available when the app runs inside Lotics"` |
 | `openApp` | yes — routes to the sibling in the same tab | yes — opens the sibling on the web app in a new tab (one app is served locally) | rejects — `"openApp needs the Lotics host …"` |
+| `recording.start`, `recording.stop` | yes, when the context states `recording_enabled` | **no** — `"Unknown RPC op: …"`; the context omits `recording_enabled` | rejects — `"Recording needs the Lotics host and a signed-in member …"` |
 
 **Limitation:** Don't build a session-log UI on `useAgentRuns`; keep the log in app
 state from live `useAgentRun` results (see [ai](./ai.md)). Server-side *cancel*
@@ -250,13 +255,15 @@ semantics are documented:
 | `agentRun.cancel` | `{ run_id }` | `{ ok: true }` | [ai](./ai.md) |
 | `urlState.get` / `urlState.set` | — / `{ params }` | `UrlParams` / `void` | [navigation & state](./navigation_and_state.md) |
 | `comments.list/create/update/delete/counts` | comment ops | comment payloads | [members & options](./members_and_options.md) |
+| `recording.start` / `recording.stop` | `{ alias, inputs }` / `{ alias }` | `{ started }` / `void` | [mutations](./mutations.md#recording-into-a-workflow-userecording) |
 
 The **streaming** agent-run op is *not* reachable through `rpc()` — its
 response is a chunk stream, not a single value; it's internal to `useAgentRun`.
 
-`rpc("context", {})` resolves the viewer: `{ member_id, comments_enabled }`.
-`member_id` is the signed-in member when embedded, `null` standalone — read it
-through `useViewer()` rather than this op. **Limitation:** the context type is
+`rpc("context", {})` resolves the viewer: `{ member_id, comments_enabled,
+recording_enabled?, recordings? }`. `member_id` is the signed-in member when
+embedded, `null` standalone — read it through `useViewer()` rather than this op;
+the recording fields are `useRecording`'s. **Limitation:** the context type is
 not exported from the package root, so type the result yourself via the `rpc<T>`
 generic.
 

package/docs/workflows.md

@@ -861,6 +861,52 @@ refuses, up front, exactly the lists a live run refuses (over 10 000 items). The
 is the one `live_reads: true` makes reachable: a loop body that reads issues one real query per
 iteration.
 
+## A workflow that receives a recording
+
+A workflow that files a recording ([mutations](./mutations.md#recording-into-a-workflow-userecording))
+declares the platform's `recording` input in exactly this shape, beside its own inputs:
+
+```jsonc
+// package.json#lotics.workflows.log_visit
+"inputs": {
+  "site": { "type": "record_link", "table_id": "tbl_sites" },
+  "recording": { "type": "object", "fields": {
+    "session_id":       { "type": "text" },
+    "audio":            { "type": "file" },
+    "video":            { "type": "file", "required": false },
+    "transcript":       { "type": "text" },
+    "duration_seconds": { "type": "number" },
+    "recorded_at":      { "type": "datetime" }
+  } }
+}
+```
+
+A declaration that differs in any field, type or `required` is not a receiver: the host refuses
+to start a recording for it, naming the first difference. The platform alone fills `recording`,
+so a call through `useWorkflow` is refused.
+
+- `audio` and `video` are file ids in the workspace. `video` is absent when the screen was not
+  recorded or its video failed to assemble. Both carry the same sound, so file **one**: the
+  video when present, else the audio.
+- `transcript` is the verbatim text, one `Speaker A: …` line per turn, and `""` for a silent
+  recording. A text field holds it whole, with no length limit: three hours is about 200,000
+  characters.
+- `recorded_at` is when capture started; `duration_seconds` is how long it ran.
+
+```js
+const i = trigger.app_workflow.inputs;
+const r = i.recording;
+await create_records({
+  table_id: "tbl_visits",
+  records: [{
+    fld_site: [i.site],
+    fld_recording: [r.video ?? r.audio],
+    fld_transcript: r.transcript,
+    fld_visited_at: r.recorded_at,
+  }],
+});
+```
+
 ## A worked body
 
 An app action that creates an order after checking for a duplicate, then returns the new id.

package/package.json

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