grist-widget-sdk 0.2.0

package/dist/advanced.d.ts

@@ -0,0 +1,790 @@
+import { C as GristTerminationReason, i as GristGeneration, p as GristMappingSource, U as UseGristCoreOptions, E as GristWidgetSnapshot, I as GristWidgetStatus, b as GristCapabilities, D as GristUserActionTuple, G as GristAccessToken, f as GristColumnarTable } from './use-grist-widget-options-from-context-BFhQBGRY.js';
+export { a as GristAuthz, d as GristColumnInfo, g as GristConfig, h as GristCurrentTableState, j as GristLifecycle, k as GristLifecyclePhase, l as GristLink, m as GristLinkState, n as GristMappingComplete, o as GristMappingIncomplete, q as GristMappingState, z as GristStreamFreshness, A as GristSync, L as ListColumnsOptions, J as ListTablesOptions, O as UseGristWidgetOptionsFromContextConfig, P as UseGristWidgetOptionsFromContextResult, aq as useGristWidgetOptionsFromContext } from './use-grist-widget-options-from-context-BFhQBGRY.js';
+import { o as GristRequiredAccess, b as GristColumnsToMap, w as GristWidgetColumnMap, i as GristReadyOptions, d as GristDocApi, G as GristApplyUserActionsOptions, q as GristTableNewRecord, r as GristTableOpOptions, h as GristMinimalRecord, t as GristTableUpdateRecord, v as GristTableUpsertRecord, u as GristTableUpsertOptions, p as GristRowRecord, f as GristFetchSelectedOptions } from './types-Fb2wplkv.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import 'zod';
+
+/**
+ * Action union for the handshake state machine.
+ *
+ * Every action that can mutate the snapshot is listed here as a discriminated
+ * union — exhaustiveness checks in the reducer rely on it.
+ *
+ * Actions either:
+ *   - target a single axis (e.g. `RPC_SUCCESS` → link), OR
+ *   - target multiple axes via a single transition (e.g. `NEGOTIATE_SUCCESS`
+ *     advances lifecycle AND authz at once).
+ *
+ * Generation-carrying actions can be **dropped** by the reducer if their
+ * `generation` is older than the snapshot's current generation; this is the
+ * primary defence against stale events arriving after a reload/restart.
+ */
+
+type GristLifecycleAction = {
+    type: "DETECT_START";
+    atMs: number;
+} | {
+    type: "DETECT_TICK";
+    attempts: number;
+    atMs: number;
+} | {
+    type: "DETECT_AVAILABLE";
+    atMs: number;
+} | {
+    type: "DETECT_TIMEOUT";
+    attempts: number;
+    atMs: number;
+} | {
+    type: "NOT_EMBEDDED";
+    atMs: number;
+} | {
+    type: "NEGOTIATE_START";
+    access: GristRequiredAccess;
+    atMs: number;
+} | {
+    type: "NEGOTIATE_SUCCESS";
+    access: GristRequiredAccess;
+    grantedLevel: GristRequiredAccess;
+    atMs: number;
+} | {
+    type: "NEGOTIATE_FAIL";
+    reason: GristTerminationReason;
+    atMs: number;
+} | {
+    type: "TERMINATE";
+    reason: GristTerminationReason;
+    atMs: number;
+};
+type GristLinkAction = {
+    type: "RPC_SUCCESS";
+    atMs: number;
+} | {
+    type: "RPC_FAILURE";
+    atMs: number;
+    kind: "timeout" | "rejected" | "other";
+} | {
+    type: "HEARTBEAT_OK";
+    atMs: number;
+} | {
+    type: "HEARTBEAT_FAIL";
+    atMs: number;
+};
+type GristAuthzAction = {
+    type: "AUTHZ_REPORT";
+    /** Effective access level reported by Grist (`onOptions` / `interaction.access_level`). */
+    level: GristRequiredAccess;
+    atMs: number;
+    generation: GristGeneration;
+};
+type GristGenerationAction = {
+    type: "BUMP_GENERATION";
+    atMs: number;
+    reason: "reload" | "restart" | "link_recovery" | "widening";
+};
+type GristMappingAction = {
+    type: "MAPPING_DECLARE";
+    declared: GristColumnsToMap;
+    atMs: number;
+    generation: GristGeneration;
+} | {
+    type: "MAPPING_REPORT";
+    source: GristMappingSource;
+    payload: GristWidgetColumnMap | null;
+    atMs: number;
+    generation: GristGeneration;
+} | {
+    type: "MAPPING_INVALIDATE";
+    atMs: number;
+    generation: GristGeneration;
+} | {
+    type: "MAPPING_INVALIDATION_RESOLVE";
+    atMs: number;
+    generation: GristGeneration;
+} | {
+    type: "MAPPING_TIMEOUT";
+    atMs: number;
+    generation: GristGeneration;
+};
+type GristSyncStream = "record" | "records" | "options" | "newRecord";
+type GristSyncAction = {
+    type: "STREAM_RECEIVED";
+    stream: GristSyncStream;
+    payloadHash: string;
+    atMs: number;
+    generation: GristGeneration;
+} | {
+    type: "STREAM_WARMING";
+    stream: GristSyncStream;
+    atMs: number;
+} | {
+    type: "STREAM_STALE";
+    stream: GristSyncStream;
+    atMs: number;
+    reason: "link_lost" | "tab_hidden" | "host_quiet";
+} | {
+    type: "CURRENT_TABLE_KNOWN";
+    tableId: string;
+    atMs: number;
+} | {
+    type: "CURRENT_TABLE_REFRESH_START";
+    atMs: number;
+} | {
+    type: "CURRENT_TABLE_ERROR";
+    message: string;
+    atMs: number;
+};
+type GristAction = GristLifecycleAction | GristLinkAction | GristAuthzAction | GristGenerationAction | GristMappingAction | GristSyncAction;
+
+/**
+ * Pure reducer for the handshake state machine.
+ *
+ * Contract
+ * --------
+ *   - **Pure**: `(snapshot, action, ctx) => nextSnapshot`. No I/O, no globals,
+ *     no Date.now() — callers pass timestamps via `action.atMs` and (optionally)
+ *     a context object for the {@link MappingResolver}.
+ *   - **Total**: every (snapshot.lifecycle.phase × action.type) pair returns
+ *     either an updated snapshot or the identity snapshot.
+ *   - **Idempotent for replays**: same generation-stamped action applied twice
+ *     leaves the snapshot unchanged (`payloadHash` short-circuit on streams,
+ *     resolver hash short-circuit on mappings).
+ *   - **Generation-safe**: any action carrying a `generation` lower than the
+ *     current snapshot generation is dropped silently — this is what makes
+ *     the SDK robust to late events after reload/restart.
+ *
+ * The reducer never throws. Invariant violations are surfaced via
+ * `./invariants.ts` if the caller opts in.
+ */
+
+/**
+ * Tuning knobs. Pass `Partial<ReducerConfig>` to override defaults; values
+ * are read by the reducer at each step.
+ */
+type ReducerConfig = {
+    /** Stale-pings threshold before link transitions to `stale`. */
+    staleAfterMissed: number;
+    /** Stale-pings threshold before link transitions to `lost`. */
+    lostAfterMissed: number;
+};
+
+/**
+ * Environment abstraction for the handshake effects layer.
+ *
+ * Why an abstraction
+ * ------------------
+ * The detect / negotiate / heartbeat effects need access to:
+ *   - the `grist` global (or absence thereof),
+ *   - `window.self !== window.top` to detect iframe embedding,
+ *   - timers (`setTimeout`, `clearTimeout`),
+ *   - the wall clock (`performance.now()` or `Date.now()`),
+ *   - `navigator.connection?.effectiveType` for adaptive policy.
+ *
+ * Putting these behind a small interface lets us test the manager and effects
+ * **without touching `window`**, using deterministic fake timers and stubbed
+ * detectors / negotiators.
+ *
+ * Production code calls {@link createBrowserEnvironment()} which returns an
+ * adapter against `globalThis`. Tests pass {@link createTestEnvironment} or a
+ * hand-rolled stub.
+ */
+
+type GristEnvironment = {
+    /** Wall-clock ms (monotonic preferred but not required). */
+    now(): number;
+    /** Schedule a callback. */
+    setTimeout(cb: () => void, ms: number): TimerHandle;
+    /** Cancel a timer. */
+    clearTimeout(handle: TimerHandle): void;
+    /**
+     * Probe whether the `grist` global is present in this realm.
+     * Returns `{ embedded }` when the global exists; `null` otherwise.
+     */
+    probeGrist(): {
+        embedded: boolean;
+    } | null;
+    /**
+     * Snapshot of the `grist` global. Effects use this once detection has
+     * succeeded; callers must NOT cache the result across `restart()`.
+     */
+    getGrist(): GristLike | null;
+    /** Adaptive detection budget hint (ms). `null` if unknown. */
+    effectiveTypeHint(): EffectiveTypeHint | null;
+    /** Add a listener for `visibilitychange` / `online` / `focus`. Returns cleanup. */
+    onVisibilityChange?(listener: (visible: boolean) => void): () => void;
+    onOnline?(listener: () => void): () => void;
+};
+type TimerHandle = ReturnType<typeof setTimeout> | number | {
+    __opaque: true;
+};
+type EffectiveTypeHint = "slow-2g" | "2g" | "3g" | "4g" | "5g";
+/**
+ * Subset of `window.grist` actually used by handshake effects. Mirrors the
+ * declared shape in `grist-global.d.ts` but only the pieces we need.
+ */
+type GristLike = {
+    ready: (options?: GristReadyOptions) => Promise<void> | void;
+    docApi: GristDocApi | null | undefined;
+    onRecord?: (cb: (record: Record<string, unknown> | null, mappings?: GristWidgetColumnMap | null) => void, options?: {
+        keepEncoded?: boolean;
+    }) => void;
+    onRecords?: (cb: (records: Record<string, unknown>[], mappings?: GristWidgetColumnMap | null) => void, options?: {
+        keepEncoded?: boolean;
+        format?: string;
+    }) => void;
+    onOptions?: (cb: (options: Record<string, unknown> | null, interaction: unknown) => void) => void;
+    onNewRecord?: (cb: (mappings: GristWidgetColumnMap | null) => void) => void;
+    sectionApi?: {
+        mappings: () => Promise<GristWidgetColumnMap | null>;
+    };
+};
+
+/**
+ * Detect effect — poll for `window.grist` with exponential backoff inside a
+ * finite, optionally adaptive budget.
+ *
+ * Outputs (dispatched to the manager):
+ *   - DETECT_START      (once, at start)
+ *   - DETECT_TICK       (each unsuccessful poll, with attempts count)
+ *   - DETECT_AVAILABLE  (grist global present AND embedded)
+ *   - NOT_EMBEDDED      (grist global present but `self === top`)
+ *   - DETECT_TIMEOUT    (budget consumed without detection)
+ *
+ * The effect aborts on `signal.aborted` and clears its pending timer.
+ *
+ * Pure of `window`: relies on the {@link GristEnvironment} adapter so the
+ * effect is fully unit-testable with a virtual clock.
+ */
+
+type DetectOptions = {
+    /** Custom poll sequence in ms. Index past end uses last value. */
+    pollSequenceMs?: readonly number[];
+    /** Total wall-clock budget across all polls. */
+    budgetMs?: number;
+};
+
+/**
+ * Negotiate effect — issue `grist.ready(payload)` race-d against a timeout
+ * and an external `AbortSignal`.
+ *
+ * Dispatches:
+ *   - NEGOTIATE_START
+ *   - NEGOTIATE_SUCCESS   (grist.ready resolved AND `docApi` is present)
+ *   - NEGOTIATE_FAIL      (reason: ready_failed | ready_timeout | manual_terminate)
+ *
+ * The effect never throws to the caller. Aborts before resolution silently
+ * stop dispatching.
+ */
+
+type NegotiateOptions = {
+    /** Max ms to wait for `grist.ready` to resolve. */
+    timeoutMs?: number;
+    /**
+     * Custom implementation of `grist.ready(payload)`. Defaults to calling
+     * `grist.ready` directly via the env. Production callers (the provider)
+     * inject a wrapper that routes through `ensureGristReady()` so the
+     * page-level singleton dedupes concurrent ready calls.
+     */
+    readyImpl?: (payload: GristReadyOptions) => Promise<void> | void;
+};
+
+/**
+ * Subscriptions effect — bind Grist event streams once and feed the handshake
+ * machine with generation-stamped, hash-deduplicated dispatches.
+ *
+ * Why a dedicated effect
+ * ----------------------
+ * The SDK already has a {@link "../../subscriptions"} module that owns the
+ * one-time binding to `grist.on*` and the BehaviorSubject-style cache. We do
+ * NOT re-bind here — instead, we install a single listener per stream that
+ * forwards into the handshake reducer.
+ *
+ * Generation discipline: every dispatched action carries the CURRENT manager
+ * generation read at the moment the event arrives. The reducer enforces
+ * `action.generation >= snapshot.generation`, so events arriving after a
+ * `reload()` / `restart()` that bumped generation are dropped automatically.
+ *
+ * Hash: payloads are reduced to a compact, deterministic string so duplicates
+ * (e.g. emulator triple-replay of initial state) become no-ops at the reducer.
+ */
+
+type SubscriptionsHandle = {
+    cancel(): void;
+};
+/**
+ * Pluggable binder type. The default {@link defaultSubscriptionsBinder}
+ * subscribes to the SDK's singleton {@link GristEvent} instances. Tests can
+ * supply a stub that never touches the real `grist` global.
+ */
+type SubscriptionsBinder = (ctx: SubscriptionsContext) => SubscriptionsHandle;
+type SubscriptionsContext = {
+    dispatch: (action: GristAction) => void;
+    /**
+     * Snapshot generation provider. Must be read lazily (inside the callback)
+     * because `generation` is monotone but mutates over the lifetime of the
+     * subscription.
+     */
+    getGeneration: () => GristGeneration;
+    /** Hook for the mapping effect: receive payloads in arrival order. */
+    onRecordPayload?: (mappings: Record<string, unknown> | null | undefined) => void;
+    onRecordsPayload?: (mappings: Record<string, unknown> | null | undefined) => void;
+    onOptionsPayload?: (options: Record<string, unknown> | null) => void;
+    onNewRecordPayload?: (mappings: Record<string, unknown> | null | undefined) => void;
+};
+
+/**
+ * Mappings effect — feed column-mapping payloads into the reducer from the
+ * three Grist sources (`sectionApi.mappings()`, `onRecord`, `onRecords`,
+ * `onNewRecord`) and trigger the mapping timeout if nothing arrives in time.
+ *
+ * Inputs:
+ *   - `declared`  — `columns` from the provider options.
+ *   - `getGeneration()` — current snapshot generation (for stale-drop).
+ *   - `getGrist()` — environment accessor to `grist.sectionApi.mappings()`.
+ *
+ * Outputs:
+ *   - `MAPPING_DECLARE` (once at start when `declared.length > 0`)
+ *   - `MAPPING_REPORT`  (one per source payload received)
+ *   - `MAPPING_TIMEOUT` (if no payload after `timeoutMs`)
+ *
+ * The effect does NOT subscribe to grist events directly — it consumes them
+ * via the {@link SubscriptionsContext} payload callbacks. This keeps the
+ * single-binding contract of `subscriptions.ts` intact (one `grist.onRecord`
+ * binding per page).
+ */
+
+type MappingsOptions = {
+    /**
+     * Time after `MAPPING_DECLARE` before falling back to `unreported` state.
+     * Default 5 000 ms.
+     */
+    timeoutMs?: number;
+    /**
+     * If true, dispatch `MAPPING_INVALIDATE` whenever a payload differs from
+     * the last applied mappings. Default false — graceful invalidation requires
+     * a `mappingsChange: true` envelope flag the SDK doesn't currently surface,
+     * so we leave it opt-in for tests.
+     */
+    invalidateOnDiff?: boolean;
+};
+
+/**
+ * Heartbeat effect — periodically verify the RPC channel is alive.
+ *
+ * Strategy
+ * --------
+ *   1. Schedule a ping every `intervalMs` (default 30 s).
+ *   2. The ping calls a cheap RPC (default `grist.docApi.getDocName()`).
+ *   3. Success → `HEARTBEAT_OK`. Failure / timeout → `HEARTBEAT_FAIL`.
+ *   4. Any externally-observed RPC success (the caller invokes
+ *      {@link HeartbeatHandle.recordRpcSuccess}) coalesces with the heartbeat
+ *      and reschedules the next ping — we don't burn a request when natural
+ *      traffic already proves the link.
+ *   5. Tab hidden? Pause via `env.onVisibilityChange`. Resume on `visible`.
+ *
+ * The effect is **purely an observer**: it never mutates application state
+ * directly — it only dispatches actions the reducer consumes.
+ */
+
+type HeartbeatOptions = {
+    /** How often to issue a probe when no natural RPC traffic occurred. */
+    intervalMs?: number;
+    /** Max time to wait for the probe before counting it as a failure. */
+    pingTimeoutMs?: number;
+    /** If true, pause the heartbeat when the document becomes hidden. */
+    pauseWhenHidden?: boolean;
+    /**
+     * Probe used when the interval elapses. Defaults to
+     * `() => env.getGrist().docApi.getDocName()`. Tests pass a controlled stub.
+     */
+    probe?: () => Promise<unknown>;
+};
+
+/**
+ * GristHandshakeManager — single owner of the handshake snapshot.
+ *
+ * Responsibilities
+ * ----------------
+ * 1. Hold the snapshot and the {@link GristReducerContext}.
+ * 2. Run effects (detect → negotiate → subscriptions + mappings) in order.
+ * 3. Bump generation on `reload()` / `restart()` and propagate cancellation
+ *    through a per-generation {@link AbortController}.
+ * 4. Notify subscribers on each snapshot change (interface compatible with
+ *    React's `useSyncExternalStore`).
+ *
+ * The manager is a **class**, not a hook. React hooks subscribe to it via the
+ * standard `subscribe` / `getSnapshot` pair so unit tests can drive the
+ * manager directly with a virtual clock — no React needed.
+ */
+
+type ManagerOptions = GristReadyOptions & {
+    detect?: DetectOptions;
+    negotiate?: NegotiateOptions;
+    mappings?: MappingsOptions;
+    heartbeat?: HeartbeatOptions | false;
+    reducerConfig?: Partial<ReducerConfig>;
+    /**
+     * Where to read `grist`, timers, and platform hints from. Defaults to a
+     * browser adapter. Tests pass {@link createTestEnvironment}.
+     */
+    env?: GristEnvironment;
+    /**
+     * Binder for grist event streams. Defaults to
+     * {@link defaultSubscriptionsBinder} which wires the SDK's singleton
+     * {@link "../../subscriptions"} module. Tests can pass `noopSubscriptionsBinder`
+     * to avoid touching the real `grist` global.
+     */
+    subscriptionsBinder?: SubscriptionsBinder;
+    /**
+     * Called when the manager catches an unexpected internal error.
+     * Telemetry hook — does not affect reducer state.
+     */
+    onError?: (err: unknown, where: string) => void;
+    /**
+     * Called from inside {@link ManagerControls.reload} BEFORE generation bump.
+     * Production callers route `resetGristReadySingleton()` through here so
+     * the page-level ready singleton is cleared and the next negotiate effect
+     * issues a fresh `grist.ready` instead of re-using the cached promise.
+     */
+    onBeforeReload?: () => void;
+};
+
+type UseGristAvailabilityOptions = Pick<UseGristCoreOptions, "availabilityMaxAttempts" | "availabilityIntervalMs" | "logWhenNotEmbedded">;
+/**
+ * Handshake-backed availability — projects `isAvailable` from the FSM.
+ */
+declare function useGristAvailability(options?: UseGristAvailabilityOptions): boolean | null;
+
+type UseGristReadyOptions = GristReadyOptions & {
+    availabilityMaxAttempts?: number;
+    availabilityIntervalMs?: number;
+    logWhenNotEmbedded?: boolean;
+};
+type UseGristReadyResult = {
+    isAvailable: boolean | null;
+    docApi: GristDocApi | null;
+    error: string | null;
+    reload: () => Promise<void>;
+};
+/**
+ * Handshake-backed `grist.ready` — delegates to {@link useGristCore} (FSM).
+ *
+ * Prefer `<GristWidgetProvider>` + `useGrist()` for full widget state; use this
+ * hook when you only need `docApi` and connection status.
+ */
+declare function useGristReady(options?: UseGristReadyOptions): UseGristReadyResult;
+
+/**
+ * `useGristHandshake()` — React adapter over {@link GristHandshakeManager}.
+ *
+ * Exposes the full {@link GristWidgetSnapshot} plus derived
+ * {@link GristCapabilities}, plus `reload()` / `restart()` controls.
+ *
+ * Identity stability
+ * ------------------
+ * The snapshot reference changes whenever the reducer produces a new
+ * snapshot. Capabilities are memoized by snapshot identity, so consumers
+ * branching on a single capability (e.g. `canWriteRecords`) avoid extra
+ * re-renders unless that boolean actually flips.
+ *
+ * SSR-safe: `getServerSnapshot` returns the initial snapshot deterministically.
+ */
+
+type UseGristHandshakeOptions = ManagerOptions;
+type UseGristHandshakeResult = {
+    snapshot: GristWidgetSnapshot;
+    status: GristWidgetStatus;
+    error: string | null;
+    capabilities: GristCapabilities;
+    reload: () => void;
+    restart: () => void;
+};
+/**
+ * Mount a handshake manager local to the component subtree. Multiple
+ * widgets in the same page should NOT call this in parallel — instead,
+ * mount a single `<GristWidgetProvider>` at the app root.
+ *
+ * In tests, pass `options.env` (see `createTestEnvironment`) to drive the
+ * machine with a virtual clock.
+ */
+declare function useGristHandshake(options?: UseGristHandshakeOptions): UseGristHandshakeResult;
+/**
+ * Convenience hook — equivalent to `useGristHandshake().capabilities` but
+ * skips returning the full snapshot. Intended for leaf components that only
+ * need to gate UI on `canRender` / `canWriteRecords` / etc.
+ */
+declare function useGristCapabilities(options?: UseGristHandshakeOptions): GristCapabilities;
+
+type GristHandshakeContextValue = {
+    snapshot: GristWidgetSnapshot;
+    status: GristWidgetStatus;
+    error: string | null;
+    capabilities: GristCapabilities;
+    reload: () => void;
+    restart: () => void;
+    recordRpcSuccess: () => void;
+    recordRpcFailure: () => void;
+};
+type GristHandshakeProviderProps = {
+    options?: ManagerOptions;
+    children: ReactNode;
+};
+/**
+ * Mount a single {@link GristHandshakeManager} for the React subtree and
+ * expose its snapshot via context.
+ *
+ * The manager is created **once** on first mount; the `options` prop is
+ * captured at that time. To re-create the manager with new options, unmount
+ * and re-mount the provider (e.g. via a `key`).
+ */
+declare function GristHandshakeProvider({ options, children }: GristHandshakeProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Read the handshake context. Throws if no `<GristHandshakeProvider>` is
+ * mounted in the tree.
+ *
+ * Use {@link useGristHandshakeContextOptional} when the provider is optional
+ * (e.g. when the same component is sometimes used standalone).
+ */
+declare function useGristHandshakeContext(): GristHandshakeContextValue;
+/** Non-throwing variant. */
+declare function useGristHandshakeContextOptional(): GristHandshakeContextValue | null;
+
+type UseGristRecordSubscriptionResult = {
+    loading: boolean;
+    error: string | null;
+    /** Latest mappings from `grist.onRecord` (logical name → real column id, or `string[]` for `allowMultiple`). */
+    mappings: GristWidgetColumnMap | null;
+};
+/**
+ * Subscribes to the currently-selected row in the widget's section.
+ *
+ * The Grist event is shared across all hook instances (no leak).
+ */
+declare function useGristRecord(cb: (record: Record<string, unknown> | null, mappings: GristWidgetColumnMap | null) => void, options?: GristReadyOptions): UseGristRecordSubscriptionResult;
+
+/**
+ * Subscribes to the full row set visible in the widget's section
+ * (filters, sorts, and linked rows applied).
+ */
+declare function useGristRecords(cb: (records: Record<string, unknown>[], mappings: GristWidgetColumnMap | null) => void, options?: GristReadyOptions): UseGristRecordSubscriptionResult;
+
+type UseGristNewRecordResult = {
+    /** True when the user has selected the blank "new row" placeholder. */
+    isNewRecord: boolean;
+    /** Mappings reported by Grist alongside the new-record event. */
+    mappings: GristWidgetColumnMap | null;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Subscribes to `grist.onNewRecord` — fires when the user selects the blank
+ * row in the linked section. Useful for form-style widgets that need to
+ * switch into "create" mode.
+ *
+ * `isNewRecord` is reset to `false` whenever a real `onRecord` payload arrives,
+ * so callers don't need to manage that themselves.
+ */
+declare function useGristNewRecord(options?: GristReadyOptions): UseGristNewRecordResult;
+
+type GristActionsStatus = "idle" | "running" | "error";
+type UseGristActionsOptions = Pick<GristReadyOptions, "requiredAccess" | "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+type UseGristActionsResult = {
+    status: GristActionsStatus;
+    error: string | null;
+    /** Apply raw user actions. `applyOptions.desc` is shown in the document undo stack. */
+    apply: (actions: GristUserActionTuple[], applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+    updateRecord: (tableId: string, recordId: number, patch: Record<string, unknown>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+    addRecord: (tableId: string, values: Record<string, unknown>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+    removeRecord: (tableId: string, recordId: number, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+    bulkAddRecord: (tableId: string, values: Record<string, unknown[]>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+    bulkUpdateRecord: (tableId: string, rowIds: number[], columnarPatch: Record<string, unknown[]>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+    bulkRemoveRecord: (tableId: string, rowIds: number[], applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
+};
+declare function useGristActions(options?: UseGristActionsOptions): UseGristActionsResult;
+
+type UseGristMappedRecordResult<T> = {
+    rawRecord: Record<string, unknown> | null;
+    mappedRecord: T | null;
+    /** Current column mappings reported by Grist. */
+    mappings: GristWidgetColumnMap | null;
+    loading: boolean;
+    error: string | null;
+    /**
+     * Reverse-map a logical patch (`{ logicalName: value }`) into a real-column
+     * patch (`{ realColId: value }`) ready for `applyUserActions` /
+     * `useGristTableOps.update`.
+     * Falls back to `grist.mapColumnNamesBack` when present, otherwise resolves
+     * names manually from `mappings` (single-mapped columns only).
+     */
+    mapBack: (patch: Partial<T>) => Record<string, unknown>;
+    /** Resolve a single logical name to its current real column id. */
+    resolveColumnId: (logicalName: keyof T & string) => string | undefined;
+};
+/**
+ * Subscribes to the selected row, applies `grist.mapColumnNames` so widget code
+ * sees logical column names, and exposes `mapBack` for safe writes.
+ */
+declare function useGristMappedRecord<T = Record<string, unknown>>(options?: GristReadyOptions): UseGristMappedRecordResult<T>;
+
+type GristTableOpsStatus = "idle" | "running" | "error";
+type UseGristTableOpsOptions = {
+    /**
+     * Table to operate on:
+     * - `"selected"` (default): use `grist.selectedTable` (the widget's current table).
+     * - any other string: use `grist.getTable(tableId)`.
+     */
+    tableId?: "selected" | string;
+    /** Defaults to `"full"` since these operations write to the document. */
+    requiredAccess?: GristReadyOptions["requiredAccess"];
+} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+type UseGristTableOpsResult = {
+    status: GristTableOpsStatus;
+    error: string | null;
+    /** Resolves the runtime tableId (only meaningful when `tableId` is `"selected"`). */
+    getTableId: () => Promise<string>;
+    create: (records: GristTableNewRecord | GristTableNewRecord[], opOptions?: GristTableOpOptions) => Promise<GristMinimalRecord | GristMinimalRecord[]>;
+    update: (records: GristTableUpdateRecord | GristTableUpdateRecord[], opOptions?: GristTableOpOptions) => Promise<void>;
+    upsert: (records: GristTableUpsertRecord | GristTableUpsertRecord[], opOptions?: GristTableUpsertOptions) => Promise<void>;
+    destroy: (recordIds: number | number[]) => Promise<void>;
+};
+/**
+ * Strongly-typed CRUD wrapper around Grist's `TableOperations` (`grist.selectedTable`
+ * or `grist.getTable(tableId)`). Prefer this over hand-rolled `applyUserActions`.
+ *
+ * @see https://support.getgrist.com/code/interfaces/TableOperations.TableOperations/
+ */
+declare function useGristTableOps(options?: UseGristTableOpsOptions): UseGristTableOpsResult;
+
+type UseGristRowsFromTableOptions<T> = {
+    tableId: string;
+    /** Re-fetch on a fixed cadence (ms). Default: disabled. */
+    pollIntervalMs?: number;
+    /** Map raw rows to a domain shape (e.g. `decodeGristValue` your columns). */
+    transform?: (row: GristRowRecord) => GristRowRecord<T>;
+    requiredAccess?: GristReadyOptions["requiredAccess"];
+} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+type UseGristRowsFromTableResult<T> = {
+    rows: GristRowRecord<T>[] | null;
+    loading: boolean;
+    error: string | null;
+    /** Force a re-fetch (call after writes that should be reflected immediately). */
+    refresh: () => Promise<void>;
+};
+/**
+ * Subscribes to a full table's rows via `docApi.fetchTable`.
+ *
+ * Unlike `useGristRecords` (which is bound to the widget's selected section),
+ * this hook works against any table id and **doesn't auto-update on Grist
+ * writes from elsewhere** — call `refresh()` after your own writes, or set
+ * `pollIntervalMs` for polling.
+ */
+declare function useGristRowsFromTable<T = Record<string, unknown>>(options: UseGristRowsFromTableOptions<T>): UseGristRowsFromTableResult<T>;
+
+type UseGristAccessTokenOptions = {
+    /** Default for all token requests issued by this hook. */
+    readOnly?: boolean;
+    /** Pre-fetch a token on mount so `token` is non-null when widgets render. */
+    prefetch?: boolean;
+    /** Defaults to `"full"` since tokens are used for REST calls. */
+    requiredAccess?: GristReadyOptions["requiredAccess"];
+} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+type UseGristAccessTokenResult = {
+    token: GristAccessToken | null;
+    loading: boolean;
+    error: string | null;
+    /** Request a fresh token (Grist tokens are short-lived; do not cache aggressively). */
+    refresh: (overrides?: {
+        readOnly?: boolean;
+    }) => Promise<GristAccessToken>;
+    /** `fetch()` against Grist's REST API with auth attached. */
+    fetch: (path: string, init?: RequestInit & {
+        readOnly?: boolean;
+    }) => Promise<Response>;
+};
+/**
+ * Exposes `docApi.getAccessToken` plus a ready-to-use `fetch` for calling
+ * Grist's REST API (e.g. attachments, records, sql) from a widget.
+ */
+declare function useGristAccessToken(options?: UseGristAccessTokenOptions): UseGristAccessTokenResult;
+
+type UseGristSectionResult = {
+    /** Current widget ↔ section column mappings, refreshed on demand. */
+    mappings: GristWidgetColumnMap | null;
+    loading: boolean;
+    error: string | null;
+    /** Re-read mappings from `sectionApi`. */
+    refresh: () => Promise<void>;
+    /**
+     * Update the widget's declared `ColumnsToMap` (and other ready options) after
+     * mount. Use this to dynamically request more columns once the user has
+     * configured the widget.
+     */
+    configure: (options: GristReadyOptions) => Promise<void>;
+};
+/**
+ * Wraps Grist's `sectionApi` (`mappings()` + `configure()`) so widgets can
+ * inspect/refresh the column mapping and re-declare requirements without
+ * touching `grist` directly.
+ */
+declare function useGristSection(options?: GristReadyOptions): UseGristSectionResult;
+
+type UseGristWidgetOptionsConfig<T> = {
+    /** Default values returned before Grist responds and merged with stored options. */
+    defaults: T;
+    /** Debounce window for `setOptions` writes (ms). Default: 250. */
+    debounceMs?: number;
+    /**
+     * Optional namespace inside `grist.setOptions`. When set, this hook reads/writes
+     * `grist.setOption(namespace, value)` instead of the whole options blob — useful
+     * to share the options bag with `hasCustomOptions` / unrelated widget state.
+     */
+    namespace?: string;
+    requiredAccess?: GristReadyOptions["requiredAccess"];
+} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+type UseGristWidgetOptionsResult<T> = {
+    options: T;
+    /** True until Grist has responded with the initial `onOptions` payload. */
+    loading: boolean;
+    error: string | null;
+    /** Replace the options object (debounced write to Grist). */
+    setOptions: (next: T) => void;
+    /** Patch a subset of keys (debounced write to Grist). */
+    patchOptions: (patch: Partial<T>) => void;
+    /** Reset to `defaults` (immediate write to Grist). */
+    reset: () => Promise<void>;
+};
+/**
+ * Persist a typed object of widget settings via `grist.onOptions` / `setOptions`.
+ *
+ * - Defaults are returned immediately (no flicker before Grist responds).
+ * - Writes are debounced and batched.
+ * - `hasCustomOptions` defaults to `true` so Grist exposes the gear icon — pass
+ *   `hasCustomOptions: false` to opt out.
+ */
+declare function useGristWidgetOptions<T extends Record<string, unknown>>(config: UseGristWidgetOptionsConfig<T>): UseGristWidgetOptionsResult<T>;
+
+type UseGristTableOptions = {
+    requiredAccess?: GristRequiredAccess;
+    /**
+     * `'current'` (default): follow the widget’s selected table.
+     * Any other string: fixed table id (no `grist.selectedTable` polling).
+     */
+    tableId?: "current" | string;
+} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+type UseGristTableResult = {
+    tableId: string | null;
+    loading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+    fetchTable: (targetTableId: string) => Promise<GristColumnarTable>;
+    listTables: () => Promise<string[]>;
+    getDocName: () => Promise<string>;
+    fetchSelectedTable: (fetchOptions?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
+    fetchSelectedRecord: (rowId: number, fetchOptions?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+};
+/**
+ * Selected or fixed table id plus document reads — no raw `docApi` on the result.
+ */
+declare function useGristTable(options?: UseGristTableOptions): UseGristTableResult;
+
+export { type GristActionsStatus, GristCapabilities, GristGeneration, type GristHandshakeContextValue, GristHandshakeProvider, type GristHandshakeProviderProps, GristMappingSource, type GristTableOpsStatus, GristTerminationReason, GristWidgetSnapshot, type UseGristAccessTokenOptions, type UseGristAccessTokenResult, type UseGristActionsOptions, type UseGristActionsResult, type UseGristHandshakeOptions, type UseGristHandshakeResult, type UseGristMappedRecordResult, type UseGristNewRecordResult, type UseGristReadyOptions, type UseGristReadyResult, type UseGristRecordSubscriptionResult, type UseGristRowsFromTableOptions, type UseGristRowsFromTableResult, type UseGristSectionResult, type UseGristTableOpsOptions, type UseGristTableOpsResult, type UseGristTableOptions, type UseGristTableResult, type UseGristWidgetOptionsConfig, type UseGristWidgetOptionsResult, useGristAccessToken, useGristActions, useGristAvailability, useGristCapabilities, useGristHandshake, useGristHandshakeContext, useGristHandshakeContextOptional, useGristMappedRecord, useGristNewRecord, useGristReady, useGristRecord, useGristRecords, useGristRowsFromTable, useGristSection, useGristTable, useGristTableOps, useGristWidgetOptions };