@lotics/app-sdk 0.100.0 → 0.101.0

package/dist/row.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure, never-throwing decoders of `useQuery` cells: a select is a
+ * `{ key, label }[]`, a date/datetime a timezone-less `YYYY-MM-DD[THH:mm…]`
+ * wall-clock string, a number or boolean itself.
+ */
+/** The column a predicted row carries, so no surface opens a row the server has not answered for. */
+export declare const PENDING = "__pending";
+/** Select → first option key; `readSelect` for every option. */
+declare function opt(v: unknown): string | null;
+/** Numbers stringified; anything else non-string is "". */
+declare function text(v: unknown): string;
+/** `null` for an empty or non-finite cell — empty is not 0; write `?? 0` where it is. */
+declare function num(v: unknown): number | null;
+/**
+ * `null` for an unanswered cell, which is not a "no". Write `=== true` where
+ * only yes acts, `?? false` where false is the safe reading.
+ */
+declare function bool(v: unknown): boolean | null;
+/**
+ * The stored day at local midnight, so placement never shifts across zones. A
+ * reduced-precision value ("2026-05") decodes to its period start.
+ */
+declare function date(v: unknown): Date | null;
+/**
+ * A local Date keeping the stored wall-clock time verbatim, with no UTC
+ * conversion; a missing month/day is 1 and a missing time midnight.
+ */
+declare function datetime(v: unknown): Date | null;
+export interface ResolvedLink {
+    /** A `rec_…` id, to correlate or filter. */
+    id: string;
+    /** The primary-field value, to render. */
+    display: string;
+}
+/** The first linked record, or null; `readLinks` for all. */
+declare function link(v: unknown): ResolvedLink | null;
+/**
+ * Every linked record. A lookup of a link arrives one level deeper (one link
+ * cell per linked row); it is flattened here, in order, each id once.
+ */
+export declare function readLinks(v: unknown): ResolvedLink[];
+/** A files cell entry; `url`/`thumbnail_url` are presigned (24h) and load from the sandboxed frame. */
+export interface AppFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url: string;
+    thumbnail_url?: string;
+    /** Bytes; absent on older files — sort by the raw number, format at display. */
+    size?: number | null;
+    /** ISO upload timestamp. */
+    created_at?: string;
+    /** The document template the file was generated from (`dtl_…`); absent on a file a person brought. */
+    document_template_id?: string;
+}
+/**
+ * The presigned files, skipping any without a `url`; `toDisplayFile`
+ * (`@lotics/ui/file_thumbnail`) converts one for the kit. A lookup arrives one
+ * level deeper, flattened as in {@link readLinks}.
+ */
+export declare function readFiles(v: unknown): AppFile[];
+/**
+ * Whether the row's record is locked (`__source_locked`), so edits must go
+ * through `request_locked_field_change`. Pass the whole row; absent is unlocked.
+ */
+export declare function readLocked(rowValue: unknown): boolean;
+/** `__created_at` of the row's record; null on a grouped row. Pass the whole row. */
+export declare function readCreatedAt(rowValue: unknown): Date | null;
+/** `__updated_at`, as {@link readCreatedAt}. */
+export declare function readUpdatedAt(rowValue: unknown): Date | null;
+export declare const row: {
+    opt: typeof opt;
+    text: typeof text;
+    num: typeof num;
+    bool: typeof bool;
+    date: typeof date;
+    datetime: typeof datetime;
+    link: typeof link;
+};
+/**
+ * Rows counted per value of one column — what the query RPC's `count_by`
+ * answers, over rows already in hand. A cell holding several values (a
+ * multi-select) is counted under each, a cell holding none under nothing: the
+ * same rows a `has_any_of` on each value keeps.
+ */
+export declare function countsOf(rows: ReadonlyArray<Record<string, unknown>>, by: string): Record<string, number>;
+export {};

package/dist/rpc.d.ts

@@ -0,0 +1,114 @@
+import type { AskUserChoiceOutput } from "./agent_stream.js";
+import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
+/**
+ * The app's RPC bridge. Bridged (`?lotics_host=` present): ops go over
+ * postMessage and the host, holding the member's session, calls the API.
+ * Standalone: the public `/v1/apps/{id}/*` endpoints are called directly, with
+ * no credentials. The bridged wire must match `app_iframe_host.tsx`:
+ *   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" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
+export interface AgentRunPayload {
+    alias: string;
+    session_id: string;
+    input: Record<string, unknown>;
+}
+export interface AgentRunHandle {
+    done: Promise<void>;
+    abort: () => void;
+}
+/** Passed through unresolved; the member's chat agent acts on it only under their IAM. */
+export interface AiContextRecordRef {
+    table_id: string;
+    record_id: string;
+}
+/** What the app rendered on the current screen, pushed to the member's chat agent. */
+export interface AiContextValue {
+    /** Enters the agent prompt as data. Host-capped to 1000 chars. */
+    description: string;
+    /** Host-capped to 20. */
+    records?: AiContextRecordRef[];
+    /** Dropped past the host's size cap, keeping the description. */
+    data?: unknown;
+}
+/** An error the app did not handle; `reportAppError` builds it. */
+export interface AppErrorReport {
+    type: "report_error";
+    kind: "uncaught" | "rejection" | "spec";
+    /** `spec` when the page carries a JSON app's inlined spec, so the hosted runtime drew it. */
+    served: "spec" | "bundle";
+    /** The error's class, or the `typeof` of a non-Error throw. */
+    name: string;
+    message: string;
+    /** The first frame, with no origin, query or fragment. */
+    stack_top: string | null;
+}
+/** One-way, app → host: no id, no reply. */
+export type HostNotification = {
+    type: "aiContext";
+    slot: string;
+    context: AiContextValue | null;
+} | AppErrorReport;
+/** The app's identity: the host's context when bridged, `/by-subdomain` (no member) standalone. */
+export interface AppContext {
+    member_id: string | null;
+    /** The app declared `comments`; `useComments` also needs a signed-in member. */
+    comments_enabled: boolean;
+    /** The IANA zone every instant is dated in; absent from an older host, which
+     *  reads in the viewer's zone. */
+    timezone?: string;
+    /** The ISO 4217 code uncoded money is counted in; absent from an older host,
+     *  which refuses such money rather than guess a currency. */
+    default_currency?: string;
+    /** True only from a host with `recording.*`, for a signed-in member, on an
+     *  instance that transcribes; absent reads as false. */
+    recording_enabled?: boolean;
+    /** This app's recordings the host still tracks, by alias. */
+    recordings?: Record<string, unknown>;
+}
+/** Whether a Lotics host embeds the app, rather than it standing alone on its own origin. */
+export declare function isEmbedded(): boolean;
+export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;
+export declare function getUrlParams(): Promise<UrlParams>;
+/** A key set to `undefined` is cleared; every other param is kept, and no history entry added. */
+export declare function setUrlParams(patch: UrlParamsPatch): Promise<void>;
+/** Synchronous first-paint snapshot; `{}` when embedded, which hydrates on mount. */
+export declare function peekUrlParams(): UrlParams;
+/** Back/forward and edited URLs: the host's `url-state` embedded, `popstate` standalone. */
+export declare function subscribeUrlParams(cb: (params: UrlParams) => void): () => void;
+/** No-ops standalone. */
+export declare function postHostNotification(message: HostNotification): void;
+/**
+ * The host's `queriesChanged` push, naming the aliases whose tables moved. The
+ * host owns the realtime socket because the frame holds no credentials; inert
+ * standalone.
+ */
+export declare function subscribeQueriesChanged(cb: (aliases: string[]) => void): () => void;
+export declare function registerQueryAlias(alias: string): () => void;
+/**
+ * Re-read after this app's own write — the realtime push is too slow for it.
+ * `reads` names the queries the write changed, where the caller knows them;
+ * absent, every mounted query, since a hand-written app cannot know which
+ * tables a workflow touched.
+ */
+export declare function notifyLocalWrite(reads?: readonly string[]): void;
+/** Hands each raw SSE chunk to `onText`; `done` settles when the stream ends. */
+export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void, onRunId?: (runId: string) => void): AgentRunHandle;
+export interface AgentRunContinuePayload {
+    run_id: string;
+    tool_call_id: string;
+    output: AskUserChoiceOutput;
+}
+/** Continue a parked run with the answer to its `ask_user_choice`, streamed like `rpcAgentRun`. */
+export declare function rpcAgentRunContinue(payload: AgentRunContinuePayload, onText: (chunk: string) => void): AgentRunHandle;
+/**
+ * Not `Authorization`: the token proves the shared link password, not an
+ * identity, and the auth middleware would reject it as an unknown bearer
+ * before the password gate runs. Mirrored server-side.
+ */
+export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
+/** Mirrored server-side. */
+export declare const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
+/** A stream refused before its first byte: the body's `message`, never its raw text. */
+export declare function streamStartError(res: Response): Promise<Error>;

package/dist/select.d.ts

@@ -0,0 +1,24 @@
+/** The server resolves each `select` cell to `ResolvedOption[]` before the app sees it. */
+export interface ResolvedOption {
+    key: string;
+    /** The key, for an option deleted after the cell was written. */
+    label: string;
+    /**
+     * A palette token (`"blue"`), from `useFieldOptions` only — a cell carries
+     * key and label. `@lotics/ui` `Status` takes the option whole.
+     */
+    color?: string;
+    /** A brand or icon mark, from `useFieldOptions` only; `Status` draws it in the dot's place. */
+    mark?: {
+        kind: "brand";
+        name: string;
+    } | {
+        kind: "icon";
+        name: string;
+    };
+}
+/**
+ * `[]` for an empty or malformed cell; a bare string (options unresolved
+ * server-side) becomes `{ key, label: key }`; malformed entries are dropped.
+ */
+export declare function readSelect(value: unknown): ResolvedOption[];

package/dist/shared_types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `@lotics/shared` types this SDK's declarations name — generated by
+ * `scripts/build_sdk.mjs`, because that package is private and ships in no
+ * tarball. Written at every build, never edited.
+ */
+export type QueryAggregate = { by?: readonly string[]; day?: string; sum?: string; };
+export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
+export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;

package/dist/store.d.ts

@@ -0,0 +1,43 @@
+/** How a key is read: from when the request was sent and the answer it holds now (a feed grows from it). */
+export type Fetcher<T> = (askedAt: number, current: T | undefined) => Promise<T>;
+/** The read clock: every request stamps when it was sent, so an answer is known to carry what settled before it. */
+export declare function tick(): number;
+/** Ask again every key reading one of `aliases` — every query key where none is named; an unmounted one on its next mount. */
+export declare function refetchReads(aliases: readonly string[] | undefined): void;
+export interface Held<T> {
+    /** The answer shown: each staged value over it, else the answer; the last key's while a new key is first asked. */
+    data: T | undefined;
+    /** When the answer shown was asked; 0 for a staged value or none. */
+    askedAt: number;
+    error: Error | null;
+    /** A first answer is awaited, and none is shown. */
+    loading: boolean;
+    /** A request for this key is in flight. */
+    validating: boolean;
+    refetch: () => void;
+}
+export interface KeyOptions<T> {
+    /** `false` asks nothing on focus or a reconnect. Default `true`. */
+    focus?: boolean;
+    /** `false` asks nothing when a key already answered is mounted again. Default `true`. */
+    arrival?: boolean;
+    /** The query aliases the key reads. */
+    aliases?: readonly string[];
+    /** An answer known without asking — a design-time fixture's — shown from the first render. */
+    known?: (askedAt: number) => T | undefined;
+}
+/** Whether a screen reads a key now. */
+export declare function mountedKey(key: string): boolean;
+/** A key's answer, asked on mount; `null` asks nothing and shows nothing. */
+export declare function useKey<T>(key: string | null, fetcher: Fetcher<T>, opts?: KeyOptions<T>): Held<T>;
+/**
+ * Show `next` over a key while `write` runs. A failed write drops it and throws; a successful one keeps it
+ * until the read it asks for next — asked after the write — answers with what the server stored.
+ */
+export declare function stageKey<T>(key: string, next: (current: T | undefined) => T, write: () => Promise<unknown>): Promise<void>;
+/** A key's answer outside a render: the one held, else the request in flight, else a new one — so a key read here and on screen is asked once. */
+export declare function readKey<T>(key: string, fetcher: Fetcher<T>): Promise<T>;
+/** Replace a key's answer with what the app knows it now is, asking nothing. */
+export declare function setKey(key: string, answer: unknown): void;
+/** Test seam: forget every answer. */
+export declare function resetStore(): void;

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Codegen augments these empty interfaces per app, so an undeclared alias is a
+ * compile error. `AppWorkflows`: alias → input shape (`Record<string, never>`
+ * for none).
+ *
+ * ```ts
+ * // .lotics/app_workflows.d.ts (generated)
+ * import "@lotics/app-sdk";
+ * declare module "@lotics/app-sdk" {
+ *   interface AppWorkflows {
+ *     "issueInvoiceStorageDrop": { record_id: string };
+ *     "issueInvoiceReuseLift": Record<string, never>;
+ *   }
+ * }
+ * ```
+ */
+export interface AppWorkflows {
+}
+/** Alias → its `return({ data })` type from declared `outputs`; absent ⇒ `unknown`. */
+export interface AppWorkflowResults {
+}
+/** Alias → param shape (`Record<string, never>` for none). */
+export interface AppQueries {
+}
+/**
+ * Alias → the union of its projected column names; absent where the AST names
+ * none (a bare `from_table`), whose keys stay `string`.
+ */
+export interface AppQueryColumns {
+}
+/** Agent alias → input shape. */
+export interface AppAgents {
+}
+/** Agent alias → its declared `outputs`; absent ⇒ `unknown`. */
+export interface AppAgentResults {
+}

package/dist/upload/optimize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser-side image downscaling to JPEG before upload, per fidelity; any
+ * other file, or any browser API gap, passes the original through.
+ */
+/** An ordinal scale, so a caller knows what it costs; `@lotics/shared/image_policy` carries the reasoning. */
+export type ImageFidelity = "original" | "high" | "standard";
+/**
+ * Mirrors `@lotics/shared/image_policy`, which the published declarations may
+ * not name; a test fails on drift. `high`, since most unconsidered uploads carry text.
+ */
+export declare const DEFAULT_IMAGE_FIDELITY: ImageFidelity;
+export interface ImagePolicy {
+    maxDimensionPx: number;
+    jpegQuality: number;
+}
+/** For the drift test only. */
+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" | "skipped_canvas_no_data";
+export interface OptimizationResult {
+    file: File;
+    optimized: boolean;
+    reason: OptimizationReason;
+    originalSizeBytes: number;
+    optimizedSizeBytes: number;
+    width: number;
+    height: number;
+    targetWidth: number;
+    targetHeight: number;
+}
+export declare function optimizeImageForUpload(file: File, fidelity?: ImageFidelity): Promise<OptimizationResult>;

package/dist/upload/pipeline.d.ts

@@ -0,0 +1,36 @@
+/** Upload: optimize (images) → presigned URL → PUT with retry → complete. */
+import { type ImageFidelity } from "./optimize.js";
+interface UploadInitResponse {
+    upload_url: string;
+    file_id: string;
+    file_storage_key: string;
+}
+interface CompleteResponseFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+    preview_url?: string;
+}
+/** Injected, so the pipeline stays free of the SDK's auth and bootstrap. */
+export interface UploadRpc {
+    initUpload(input: {
+        filename: string;
+        mime_type: string;
+        file_size: number;
+    }): Promise<UploadInitResponse>;
+    completeUpload(input: {
+        file_id: string;
+        file_storage_key: string;
+        filename: string;
+    }): Promise<{
+        file: CompleteResponseFile;
+    }>;
+}
+export interface RunUploadPipelineOptions {
+    signal?: AbortSignal;
+    fidelity?: ImageFidelity;
+}
+export declare function runUploadPipeline(file: File, rpc: UploadRpc, options?: RunUploadPipelineOptions): Promise<CompleteResponseFile>;
+export {};

package/dist/upload/transport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Upload transport: a per-request timeout, since a bare `fetch` can hang
+ * forever, and exponential-backoff retry for the storage PUT, the most
+ * failure-prone step on mobile.
+ */
+export declare const UPLOAD_TIMEOUT_MS: number;
+export declare class UploadTimeoutError extends Error {
+    readonly url: string;
+    readonly timeoutMs: number;
+    readonly name = "UploadTimeoutError";
+    constructor(url: string, timeoutMs: number);
+}
+export declare class UploadAbortedError extends Error {
+    readonly name = "UploadAbortedError";
+    constructor();
+}
+export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response>;
+/** Retries network errors, timeouts and 5xx; a 4xx is returned as is, and an abort propagates. */
+export declare function putToStorageWithRetry(uploadUrl: string, file: File, signal: AbortSignal | undefined): Promise<Response>;

package/dist/url_params.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed query-string codecs behind `useUrlState`. A `.withDefault(d)` value
+ * equal to its default is omitted from the URL; only declared keys are read or
+ * written, and every other param is preserved on merge.
+ */
+/** An array for a repeated key (`?tag=a&tag=b`). */
+export type UrlParamValue = string | string[];
+export type UrlParams = Record<string, UrlParamValue>;
+/** `undefined` clears a key; keys not present are preserved. */
+export type UrlParamsPatch = Record<string, UrlParamValue | undefined>;
+/** Methods, not function properties, so `UrlParamCodec<string>` stays assignable to `UrlParamCodec<unknown>`. */
+export interface UrlParamCodec<T> {
+    decode(raw: UrlParamValue | undefined): T;
+    /** `undefined` omits the key. */
+    encode(value: T): UrlParamValue | undefined;
+}
+export interface OptionalUrlParamCodec<T> extends UrlParamCodec<T | undefined> {
+    /** An absent key decodes to `fallback`; a value equal to it is omitted. */
+    withDefault(fallback: T): UrlParamCodec<T>;
+}
+declare function enumCodec<const V extends readonly string[]>(values: V): OptionalUrlParamCodec<V[number]>;
+declare function arrayOf<T>(inner: UrlParamCodec<T | undefined>): OptionalUrlParamCodec<T[]>;
+/**
+ * Each builder is optional; `.withDefault(v)` makes it required.
+ *
+ *   useUrlState({
+ *     q:      urlParam.string.withDefault(""),
+ *     status: urlParam.enum(["open", "won", "lost"]),       // optional
+ *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
+ *     from:   urlParam.isoDate,                              // optional Date
+ *     page:   urlParam.number.withDefault(1),
+ *   })
+ */
+export declare const urlParam: {
+    readonly string: OptionalUrlParamCodec<string>;
+    readonly number: OptionalUrlParamCodec<number>;
+    readonly boolean: OptionalUrlParamCodec<boolean>;
+    readonly isoDate: OptionalUrlParamCodec<Date>;
+    readonly enum: typeof enumCodec;
+    readonly arrayOf: typeof arrayOf;
+};
+export declare function decodeAll<D extends Record<string, UrlParamCodec<unknown>>>(defs: D, params: UrlParams): {
+    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
+};
+/** Only the keys present in `values` are emitted, so the write merges. */
+export declare function encodePatch<D extends Record<string, UrlParamCodec<unknown>>>(defs: D, values: Partial<{
+    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
+}>): UrlParamsPatch;
+export declare function parseSearch(search: string): UrlParams;
+/** The merged query string, without the leading `?`. */
+export declare function serializeMerge(search: string, patch: UrlParamsPatch): string;
+export declare function applyPatch(params: UrlParams, patch: UrlParamsPatch): UrlParams;
+/** Drops an echo of the app's own write. */
+export declare function paramsEqual(a: UrlParams, b: UrlParams): boolean;
+export {};

package/dist/use_recents.d.ts

@@ -0,0 +1,15 @@
+export interface RecentsApi<T> {
+    /** Deduped by `keyOf`, capped at `max`. */
+    recents: T[];
+    /** Call on select. */
+    remember: (item: T) => void;
+    forget: (item: T) => void;
+    clear: () => void;
+}
+export interface RecentsOptions<T> {
+    /** Default `JSON.stringify`; pass an id for objects you recreate. */
+    keyOf?: (item: T) => string;
+    /** Default 5. */
+    max?: number;
+}
+export declare function useRecents<T>(key: string, options?: RecentsOptions<T>): RecentsApi<T>;

package/dist/{src/use_url_state.d.ts → use_url_state.d.ts}

@@ -1,7 +1,5 @@
 import { type UrlParamCodec } from "./url_params.js";
-/** A `useUrlState` shape: a map of param key → codec. */
 export type UrlStateShape = Record<string, UrlParamCodec<unknown>>;
-/** The decoded, typed values for a shape. */
 export type UrlStateValues<D extends UrlStateShape> = {
     [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
 };

package/dist/viewer.d.ts

@@ -0,0 +1,41 @@
+import { type AppContext } from "./rpc.js";
+/** The store key the host's context is held under, read by every screen and by the write model alike. */
+export declare const APP_CONTEXT_KEY = "app-context";
+export declare function readContext(): Promise<AppContext>;
+/**
+ * The host's context, read once and shared. `settled` once it answered or
+ * failed; on `failure` every fact is unknown, so draw the failure rather than
+ * guess.
+ */
+export declare function useAppContext(): {
+    memberId: string | null;
+    commentsEnabled: boolean;
+    recordingEnabled: boolean;
+    timezone: string | undefined;
+    currency: string | undefined;
+    resolved: boolean;
+    settled: boolean;
+    failure: {
+        message: string;
+        retry: () => void;
+    } | null;
+};
+/**
+ * The IANA zone an instant (`__created_at`, a comment's time) is dated in; a
+ * date cell is a wall clock and needs none. `undefined` until resolved.
+ */
+export declare function useWorkspaceTimezone(): string | undefined;
+/**
+ * The ISO 4217 code for money whose field states none — pass it as `currency`,
+ * or the kit prints its home market. `undefined` until resolved.
+ */
+export declare function useWorkspaceCurrency(): string | undefined;
+/**
+ * The viewing member — the view-as target under "View as" — or `null` for a
+ * public visitor, while `loading`, or on failure. Row scoping needs no viewer:
+ * use an `is_current_member` query filter.
+ */
+export declare function useViewer(): {
+    memberId: string | null;
+    loading: boolean;
+};

package/dist/written.d.ts

@@ -0,0 +1,77 @@
+import { type BodyTable } from "./shared_types.js";
+import type { TableField } from "./shared_types.js";
+import { type QueryWriteShape } from "./shared_types.js";
+export type Row = Record<string, unknown>;
+/** A predicted write in the shape rows store it: an option as `["opt_…"]`, a link as `[{ id, display }]`. */
+export type Staged = {
+    kind: "update" | "create";
+    table_id: string;
+    record_id: string;
+    cells: Record<string, unknown>;
+    unknown: readonly string[];
+} | {
+    kind: "remove";
+    table_id: string;
+    record_id: string;
+};
+/** The org's members as the roster answers them: a face for a member no read has drawn yet. */
+export declare function noteMembers(roster: readonly {
+    id: string;
+}[]): void;
+/** A record as a write leaves it: its stored cells, then each staged write over it, in order. */
+export declare function recordAfter(recordId: string, staged: readonly Staged[]): {
+    cells: Map<string, unknown>;
+    unknown: Set<string>;
+    gone: boolean;
+};
+/** A write staged before its run answers, and the ids minted for the rows it makes — the run is sent them. */
+export interface StagedWrite {
+    token: number;
+    minted: readonly string[];
+}
+/**
+ * Stage what `workflow` will write with `inputs`, before its run is sent. Null where nothing can be said: no
+ * model yet, a workflow that writes no record, or a guard the client can read refusing it.
+ */
+export declare function stageWrite(workflow: string, inputs: Readonly<Record<string, unknown>>): Promise<StagedWrite | null>;
+export declare function dropWrite(token: number): void;
+/** The server kept the write: every read asked from now on carries it. */
+export declare function settleWrite(token: number): void;
+/** Whether a run of `workflow` writes records — every run while the model is unread. */
+export declare function writesRecords(workflow: string): boolean;
+/**
+ * Note a read's answer: its rows as stored, and when it was asked — or, for a key holding pages asked at
+ * different times, when its oldest was (`since`).
+ */
+export declare function noteAnswer(key: string, alias: string, askedAt: number, rows: readonly Row[], since?: number): void;
+/**
+ * The queries a successful run of `workflow` re-reads: those over a table its body names. Undefined — every
+ * mounted query — until the model is read, or where a write names a table only at run time.
+ */
+export declare function readsAfter(workflow: string, token: number | null): string[] | undefined;
+/** What overlaying one read needs: the model, what this app has read, and the writes live over that read. */
+export interface Over {
+    field: (tableId: string, key: string) => TableField | undefined;
+    table: (tableId: string) => BodyTable | undefined;
+    held: (recordId: string) => Map<string, unknown> | undefined;
+    member: (id: string) => unknown;
+    memberId: string | null;
+    timezone: string | undefined;
+    staged: readonly Staged[];
+    /** The rows of writes the server has kept, which open as any other. */
+    kept: ReadonlySet<string>;
+    /** A write over these tables is in flight, or wrote rows of one its prediction could not name. */
+    pending: boolean;
+}
+/** A query the model describes, with every table its answer depends on. */
+export declare function shapeOf(alias: string): {
+    shape: QueryWriteShape;
+    tables: ReadonlySet<string>;
+} | undefined;
+/** The writes live over a read asked at `askedAt` of `tables` — asked before each settled — or null where none touches it. */
+export declare function writesOver(tables: ReadonlySet<string>, askedAt: number): Over | null;
+/** Whether a write in flight touches what an alias reads. */
+export declare function pendingRead(alias: string): boolean;
+export declare function useWrittenVersion(): number;
+/** Test seam: forget everything read and staged. */
+export declare function resetWritten(): void;