grist-widget-sdk 0.2.0

package/dist/inline-CRwQQ-GW.d.cts

@@ -0,0 +1,311 @@
+import { c as GristCursorPos, y as GristWidgetInteraction, w as GristWidgetColumnMap, j as GristReplicaColumn, p as GristRowRecord, m as GristReplicaSelection, x as GristWidgetConfiguration, i as GristReadyOptions, f as GristFetchSelectedOptions, s as GristTableOperations } from './types-Fb2wplkv.cjs';
+
+/**
+ * Tiny pub-sub used to broadcast every emulator state change to:
+ *   - the transports (which translate events into protocol messages),
+ *   - the React DevTools inspector (timeline view),
+ *   - the testing harness (assertions on emitted events).
+ */
+
+type EmulatorEvent = {
+    type: "data-change";
+    tableId: string;
+} | {
+    type: "cursor-change";
+    tableId: string;
+    rowId: number | "new" | null;
+    cursor?: GristCursorPos;
+} | {
+    type: "options-change";
+    options: Record<string, unknown>;
+    interaction: GristWidgetInteraction;
+} | {
+    type: "theme-change";
+    message: Record<string, unknown>;
+} | {
+    type: "ready";
+    configuration: unknown;
+} | {
+    type: "user-action";
+    action: unknown[];
+} | {
+    type: "mappings-change";
+    mappings: GristWidgetColumnMap | null;
+};
+type EmulatorEventListener = (event: EmulatorEvent) => void;
+type EventBus = {
+    emit: (event: EmulatorEvent) => void;
+    on: (listener: EmulatorEventListener) => () => void;
+    history: () => readonly EmulatorEvent[];
+    clear: () => void;
+};
+
+/**
+ * Core types for the in-memory Grist emulator document model.
+ *
+ * The emulator is a faithful, in-process re-implementation of Grist's
+ * server-side contract — it owns a typed document and derives every event
+ * the widget receives (`onRecord`, `onRecords`, `onOptions`, `onNewRecord`)
+ * from mutations applied to that document.
+ *
+ * No DOM, no `window`, no React in this layer.
+ */
+
+type EmulatorRowId = number;
+/**
+ * Column metadata for the emulator: {@link GristReplicaColumn} plus in-process
+ * `formulaFn` (never serialized in replica JSON).
+ *
+ * - **`formula`** — original Grist formula text from the replica (when present).
+ * - **`inferredFormula`** — emulator-only companion string: explicit value, else mirrors
+ *   `formula`, else a stable placeholder when only `formulaFn` is provided.
+ */
+type EmulatorColumn = GristReplicaColumn & {
+    formulaFn?: (row: GristRowRecord, ctx: EmulatorFormulaContext) => unknown;
+    /** Emulator-only; not part of {@link GristReplicaColumn} JSON. See type JSDoc above. */
+    inferredFormula?: string;
+};
+type EmulatorFormulaContext = {
+    table: EmulatorTable;
+    document: EmulatorDocumentState;
+};
+type EmulatorTable = {
+    tableId: string;
+    /** Optional human-readable label (used by the inspector). */
+    label?: string;
+    columns: Record<string, EmulatorColumn>;
+    rows: GristRowRecord[];
+};
+type EmulatorDocumentState = {
+    /** Logical doc name returned by `getDocName()`. */
+    docName: string;
+    /**
+     * `tableId` → `EmulatorTable`. The order of insertion is preserved for
+     * `listTables()` (Grist's behaviour).
+     */
+    tables: Map<string, EmulatorTable>;
+    /** Current widget selection (which table, which row). */
+    selection: GristReplicaSelection;
+    /** Persisted widget options, exposed via `WidgetAPI.{get,set}Option`. */
+    widgetOptions: Record<string, unknown>;
+    /**
+     * Widget interaction info passed alongside `onOptions`. Lets tests assert
+     * `access_level`, theme, etc.
+     */
+    widgetInteraction: GristWidgetInteraction;
+    /** Last `ready()` payload received from the widget. */
+    configuration: GristWidgetConfiguration | null;
+    /**
+     * Mock REST access token returned by `getAccessToken()`. Set to `null` to
+     * simulate unauthenticated widgets (the call will reject).
+     */
+    accessToken: {
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    } | null;
+};
+
+/**
+ * Type-only signatures of the Grist plugin interfaces that the emulator
+ * exposes to the widget (under both inline and iframe transports).
+ *
+ * These mirror the upstream `grist-plugin-api` contracts. We re-declare them
+ * here instead of `import`ing the upstream types because:
+ *   - we don't depend on `grist-plugin-api` runtime,
+ *   - the emulator is the single source of truth for what's testable.
+ */
+type GristViewImpl = {
+    /**
+     * Always returns Grist's **columnar** wire shape. The `format` option is
+     * accepted for protocol fidelity (the production `grist-plugin-api.js`
+     * always forwards it) but the host stub MUST ignore it: the wrapper inside
+     * the plugin script is the one that does the rows transposition. See
+     * `api/grist-view.ts` and `transports/inline.ts` for the consumer side.
+     */
+    fetchSelectedTable: (options?: {
+        keepEncoded?: boolean;
+        format?: "rows" | "columns";
+    }) => Promise<Record<string, unknown[]>>;
+    fetchSelectedRecord: (rowId: number, options?: {
+        keepEncoded?: boolean;
+    }) => Promise<Record<string, unknown>>;
+    allowSelectBy: () => Promise<boolean>;
+    setSelectedRows: (rowIds: number[] | null) => Promise<void>;
+    setCursorPos: (cursor: {
+        rowId?: number;
+        field?: string;
+        sectionId?: number;
+    }) => Promise<void>;
+};
+type GristDocApiImpl = {
+    getDocName: () => Promise<string>;
+    listTables: () => Promise<string[]>;
+    fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
+    applyUserActions: (actions: unknown[][], options?: {
+        desc?: string;
+    }) => Promise<{
+        retValues: unknown[];
+    }>;
+    getAccessToken: (options?: {
+        readOnly?: boolean;
+    }) => Promise<{
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    }>;
+};
+type WidgetApiImpl = {
+    getOption: (key: string) => Promise<unknown>;
+    setOption: (key: string, value: unknown) => Promise<void>;
+    getOptions: () => Promise<Record<string, unknown> | null>;
+    setOptions: (options: Record<string, unknown>) => Promise<void>;
+    clearOptions: () => Promise<void>;
+};
+type CustomSectionApiImpl = {
+    configure: (settings: Record<string, unknown>) => Promise<void>;
+    mappings: () => Promise<Record<string, string | string[] | undefined> | null>;
+};
+/**
+ * Top-level Grist plugin RPC (the `_grist_api` interface). Used by the
+ * widget to subscribe to events such as "onMessage" relays. Keeps a minimal
+ * surface in v1 — extend as widget needs grow.
+ */
+type GristApiImpl = {
+    /** No-op echo helpful for protocol-level health checks. */
+    ping: () => Promise<"pong">;
+};
+type CommandApiImpl = {
+    /** Runs a registered command by name. The emulator currently no-ops. */
+    run: (name: string) => Promise<void>;
+};
+
+/**
+ * Bundles the six host-side Grist API implementations into one record so
+ * transports (iframe, inline) can wire them up uniformly.
+ */
+
+type EmulatorApiBundle = {
+    GristView: GristViewImpl;
+    GristDocAPI: GristDocApiImpl;
+    WidgetAPI: WidgetApiImpl;
+    CustomSectionAPI: CustomSectionApiImpl;
+    GristAPI: GristApiImpl;
+    CommandAPI: CommandApiImpl;
+};
+
+type EmulatorTransport = {
+    /** Tear the transport down. Idempotent. */
+    dispose: () => void;
+    /** Push a "data refreshed" hint to the widget. */
+    fireDataChange: (tableId?: string) => void;
+    /** Push a cursor change to the widget (number rowId, "new", or null). */
+    fireCursor: (rowId?: number | "new" | null) => void;
+    /** Push the current options + interaction to the widget. */
+    fireOptions: () => void;
+    /** Push a host theme message (`grist.on("message")` / `msg.theme`). */
+    fireTheme: (message: Record<string, unknown>) => void;
+    /** Replays the post-ready bootstrap (options + cursor + data) as if the widget had just connected. */
+    emitInitialState: () => void;
+};
+type TransportContext = {
+    state: EmulatorDocumentState;
+    bus: EventBus;
+    api: EmulatorApiBundle;
+    /** Initial document theme replayed on widget ready (host message channel). */
+    initialTheme?: "light" | "dark";
+    /**
+     * Information piggybacked on `onOptions`. Same as `state.widgetInteraction`
+     * by default but transports may augment it (e.g. `access_level` derived
+     * from `state.configuration.requiredAccess`).
+     */
+    buildInteraction?: () => GristWidgetInteraction;
+    /**
+     * Cursor sentinel sent on initial connection. Defaults to the current
+     * `state.selection.rowId` (which can be `null`, `"new"`, or a numeric id).
+     */
+    initialCursor?: () => number | "new" | null;
+    /** Optional cursor sent alongside `onRecord` payloads. */
+    cursor?: () => GristCursorPos | undefined;
+};
+
+/**
+ * Inline transport — synthesises a `window.grist` global wired directly to
+ * the emulator state. No iframe, no postMessage, no serialization.
+ *
+ * Used for:
+ *   - SDK unit tests in jsdom (`renderWithGrist(...)`),
+ *   - IDE-style live previews where widget code lives in the same window
+ *     as the emulator host.
+ *
+ * The synthesised `grist` object exposes the **same** typed surface as the
+ * production `grist-plugin-api.js` (see `hooks/grist-global.d.ts`). Hooks
+ * call `grist.docApi.fetchTable(...)` etc. and get the answer directly from
+ * the action engine.
+ */
+
+/**
+ * Shape of the synthesised global. Matches `globalThis.grist` from
+ * `grist-global.d.ts`.
+ */
+type InlineGristGlobal = {
+    ready: (options?: GristReadyOptions) => Promise<void>;
+    onRecord: (cb: (record: Record<string, unknown> | null, mappings?: GristWidgetColumnMap | null) => void, options?: GristFetchSelectedOptions) => void;
+    onRecords: (cb: (records: Record<string, unknown>[], mappings?: GristWidgetColumnMap | null) => void, options?: GristFetchSelectedOptions) => void;
+    onOptions: (cb: (options: Record<string, unknown> | null, interaction: GristWidgetInteraction) => void) => void;
+    onNewRecord: (cb: (mappings: GristWidgetColumnMap | null) => void) => void;
+    mapColumnNames: (data: Record<string, unknown>) => Record<string, unknown> | null;
+    mapColumnNamesBack: (data: Record<string, unknown>) => Record<string, unknown>;
+    getOptions: () => Promise<Record<string, unknown> | null>;
+    getOption: (key: string) => Promise<unknown>;
+    setOption: (key: string, value: unknown) => Promise<void>;
+    setOptions: (options: Record<string, unknown>) => Promise<void>;
+    clearOptions: () => Promise<void>;
+    setCursorPos: (pos: GristCursorPos) => Promise<void>;
+    setSelectedRows: (rowIds: number[] | null) => Promise<void>;
+    fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
+    fetchSelectedRecord: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+    docApi: {
+        getDocName: () => Promise<string>;
+        listTables: () => Promise<string[]>;
+        fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
+        applyUserActions: (actions: unknown[][], options?: {
+            desc?: string;
+        }) => Promise<{
+            retValues: unknown[];
+        }>;
+        getAccessToken?: (options?: {
+            readOnly?: boolean;
+        }) => Promise<{
+            token: string;
+            baseUrl: string;
+        }>;
+        fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
+        fetchSelectedRecord: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+    };
+    selectedTable: GristTableOperations;
+    getTable: (tableId?: string) => GristTableOperations;
+    sectionApi: {
+        configure: (settings: GristReadyOptions) => Promise<void>;
+        mappings: () => Promise<GristWidgetColumnMap | null>;
+    };
+    on: (eventName: string, listener: (...args: unknown[]) => void) => () => void;
+};
+type InlineTransportOptions = TransportContext & {
+    /**
+     * Where to mount the synthesised `grist` global.
+     * Defaults to the current window. Pass a different target (e.g. an iframe's
+     * `contentWindow`) to install it in another realm.
+     */
+    target?: Window & typeof globalThis;
+};
+/**
+ * Returns an {@link EmulatorTransport} **and** the synthesised `grist`
+ * object. `target.grist = global` is set as a side-effect for parity with
+ * the production runtime.
+ */
+declare function createInlineTransport(options: InlineTransportOptions): EmulatorTransport & {
+    grist: InlineGristGlobal;
+};
+
+export { type EmulatorApiBundle as E, type InlineGristGlobal as I, type TransportContext as T, type EmulatorColumn as a, type EmulatorDocumentState as b, type EmulatorEvent as c, type EmulatorRowId as d, type EmulatorTable as e, type EmulatorTransport as f, type EventBus as g, type InlineTransportOptions as h, createInlineTransport as i };

package/dist/inline-QitZwXKP.d.ts

@@ -0,0 +1,311 @@
+import { c as GristCursorPos, y as GristWidgetInteraction, w as GristWidgetColumnMap, j as GristReplicaColumn, p as GristRowRecord, m as GristReplicaSelection, x as GristWidgetConfiguration, i as GristReadyOptions, f as GristFetchSelectedOptions, s as GristTableOperations } from './types-Fb2wplkv.js';
+
+/**
+ * Tiny pub-sub used to broadcast every emulator state change to:
+ *   - the transports (which translate events into protocol messages),
+ *   - the React DevTools inspector (timeline view),
+ *   - the testing harness (assertions on emitted events).
+ */
+
+type EmulatorEvent = {
+    type: "data-change";
+    tableId: string;
+} | {
+    type: "cursor-change";
+    tableId: string;
+    rowId: number | "new" | null;
+    cursor?: GristCursorPos;
+} | {
+    type: "options-change";
+    options: Record<string, unknown>;
+    interaction: GristWidgetInteraction;
+} | {
+    type: "theme-change";
+    message: Record<string, unknown>;
+} | {
+    type: "ready";
+    configuration: unknown;
+} | {
+    type: "user-action";
+    action: unknown[];
+} | {
+    type: "mappings-change";
+    mappings: GristWidgetColumnMap | null;
+};
+type EmulatorEventListener = (event: EmulatorEvent) => void;
+type EventBus = {
+    emit: (event: EmulatorEvent) => void;
+    on: (listener: EmulatorEventListener) => () => void;
+    history: () => readonly EmulatorEvent[];
+    clear: () => void;
+};
+
+/**
+ * Core types for the in-memory Grist emulator document model.
+ *
+ * The emulator is a faithful, in-process re-implementation of Grist's
+ * server-side contract — it owns a typed document and derives every event
+ * the widget receives (`onRecord`, `onRecords`, `onOptions`, `onNewRecord`)
+ * from mutations applied to that document.
+ *
+ * No DOM, no `window`, no React in this layer.
+ */
+
+type EmulatorRowId = number;
+/**
+ * Column metadata for the emulator: {@link GristReplicaColumn} plus in-process
+ * `formulaFn` (never serialized in replica JSON).
+ *
+ * - **`formula`** — original Grist formula text from the replica (when present).
+ * - **`inferredFormula`** — emulator-only companion string: explicit value, else mirrors
+ *   `formula`, else a stable placeholder when only `formulaFn` is provided.
+ */
+type EmulatorColumn = GristReplicaColumn & {
+    formulaFn?: (row: GristRowRecord, ctx: EmulatorFormulaContext) => unknown;
+    /** Emulator-only; not part of {@link GristReplicaColumn} JSON. See type JSDoc above. */
+    inferredFormula?: string;
+};
+type EmulatorFormulaContext = {
+    table: EmulatorTable;
+    document: EmulatorDocumentState;
+};
+type EmulatorTable = {
+    tableId: string;
+    /** Optional human-readable label (used by the inspector). */
+    label?: string;
+    columns: Record<string, EmulatorColumn>;
+    rows: GristRowRecord[];
+};
+type EmulatorDocumentState = {
+    /** Logical doc name returned by `getDocName()`. */
+    docName: string;
+    /**
+     * `tableId` → `EmulatorTable`. The order of insertion is preserved for
+     * `listTables()` (Grist's behaviour).
+     */
+    tables: Map<string, EmulatorTable>;
+    /** Current widget selection (which table, which row). */
+    selection: GristReplicaSelection;
+    /** Persisted widget options, exposed via `WidgetAPI.{get,set}Option`. */
+    widgetOptions: Record<string, unknown>;
+    /**
+     * Widget interaction info passed alongside `onOptions`. Lets tests assert
+     * `access_level`, theme, etc.
+     */
+    widgetInteraction: GristWidgetInteraction;
+    /** Last `ready()` payload received from the widget. */
+    configuration: GristWidgetConfiguration | null;
+    /**
+     * Mock REST access token returned by `getAccessToken()`. Set to `null` to
+     * simulate unauthenticated widgets (the call will reject).
+     */
+    accessToken: {
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    } | null;
+};
+
+/**
+ * Type-only signatures of the Grist plugin interfaces that the emulator
+ * exposes to the widget (under both inline and iframe transports).
+ *
+ * These mirror the upstream `grist-plugin-api` contracts. We re-declare them
+ * here instead of `import`ing the upstream types because:
+ *   - we don't depend on `grist-plugin-api` runtime,
+ *   - the emulator is the single source of truth for what's testable.
+ */
+type GristViewImpl = {
+    /**
+     * Always returns Grist's **columnar** wire shape. The `format` option is
+     * accepted for protocol fidelity (the production `grist-plugin-api.js`
+     * always forwards it) but the host stub MUST ignore it: the wrapper inside
+     * the plugin script is the one that does the rows transposition. See
+     * `api/grist-view.ts` and `transports/inline.ts` for the consumer side.
+     */
+    fetchSelectedTable: (options?: {
+        keepEncoded?: boolean;
+        format?: "rows" | "columns";
+    }) => Promise<Record<string, unknown[]>>;
+    fetchSelectedRecord: (rowId: number, options?: {
+        keepEncoded?: boolean;
+    }) => Promise<Record<string, unknown>>;
+    allowSelectBy: () => Promise<boolean>;
+    setSelectedRows: (rowIds: number[] | null) => Promise<void>;
+    setCursorPos: (cursor: {
+        rowId?: number;
+        field?: string;
+        sectionId?: number;
+    }) => Promise<void>;
+};
+type GristDocApiImpl = {
+    getDocName: () => Promise<string>;
+    listTables: () => Promise<string[]>;
+    fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
+    applyUserActions: (actions: unknown[][], options?: {
+        desc?: string;
+    }) => Promise<{
+        retValues: unknown[];
+    }>;
+    getAccessToken: (options?: {
+        readOnly?: boolean;
+    }) => Promise<{
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    }>;
+};
+type WidgetApiImpl = {
+    getOption: (key: string) => Promise<unknown>;
+    setOption: (key: string, value: unknown) => Promise<void>;
+    getOptions: () => Promise<Record<string, unknown> | null>;
+    setOptions: (options: Record<string, unknown>) => Promise<void>;
+    clearOptions: () => Promise<void>;
+};
+type CustomSectionApiImpl = {
+    configure: (settings: Record<string, unknown>) => Promise<void>;
+    mappings: () => Promise<Record<string, string | string[] | undefined> | null>;
+};
+/**
+ * Top-level Grist plugin RPC (the `_grist_api` interface). Used by the
+ * widget to subscribe to events such as "onMessage" relays. Keeps a minimal
+ * surface in v1 — extend as widget needs grow.
+ */
+type GristApiImpl = {
+    /** No-op echo helpful for protocol-level health checks. */
+    ping: () => Promise<"pong">;
+};
+type CommandApiImpl = {
+    /** Runs a registered command by name. The emulator currently no-ops. */
+    run: (name: string) => Promise<void>;
+};
+
+/**
+ * Bundles the six host-side Grist API implementations into one record so
+ * transports (iframe, inline) can wire them up uniformly.
+ */
+
+type EmulatorApiBundle = {
+    GristView: GristViewImpl;
+    GristDocAPI: GristDocApiImpl;
+    WidgetAPI: WidgetApiImpl;
+    CustomSectionAPI: CustomSectionApiImpl;
+    GristAPI: GristApiImpl;
+    CommandAPI: CommandApiImpl;
+};
+
+type EmulatorTransport = {
+    /** Tear the transport down. Idempotent. */
+    dispose: () => void;
+    /** Push a "data refreshed" hint to the widget. */
+    fireDataChange: (tableId?: string) => void;
+    /** Push a cursor change to the widget (number rowId, "new", or null). */
+    fireCursor: (rowId?: number | "new" | null) => void;
+    /** Push the current options + interaction to the widget. */
+    fireOptions: () => void;
+    /** Push a host theme message (`grist.on("message")` / `msg.theme`). */
+    fireTheme: (message: Record<string, unknown>) => void;
+    /** Replays the post-ready bootstrap (options + cursor + data) as if the widget had just connected. */
+    emitInitialState: () => void;
+};
+type TransportContext = {
+    state: EmulatorDocumentState;
+    bus: EventBus;
+    api: EmulatorApiBundle;
+    /** Initial document theme replayed on widget ready (host message channel). */
+    initialTheme?: "light" | "dark";
+    /**
+     * Information piggybacked on `onOptions`. Same as `state.widgetInteraction`
+     * by default but transports may augment it (e.g. `access_level` derived
+     * from `state.configuration.requiredAccess`).
+     */
+    buildInteraction?: () => GristWidgetInteraction;
+    /**
+     * Cursor sentinel sent on initial connection. Defaults to the current
+     * `state.selection.rowId` (which can be `null`, `"new"`, or a numeric id).
+     */
+    initialCursor?: () => number | "new" | null;
+    /** Optional cursor sent alongside `onRecord` payloads. */
+    cursor?: () => GristCursorPos | undefined;
+};
+
+/**
+ * Inline transport — synthesises a `window.grist` global wired directly to
+ * the emulator state. No iframe, no postMessage, no serialization.
+ *
+ * Used for:
+ *   - SDK unit tests in jsdom (`renderWithGrist(...)`),
+ *   - IDE-style live previews where widget code lives in the same window
+ *     as the emulator host.
+ *
+ * The synthesised `grist` object exposes the **same** typed surface as the
+ * production `grist-plugin-api.js` (see `hooks/grist-global.d.ts`). Hooks
+ * call `grist.docApi.fetchTable(...)` etc. and get the answer directly from
+ * the action engine.
+ */
+
+/**
+ * Shape of the synthesised global. Matches `globalThis.grist` from
+ * `grist-global.d.ts`.
+ */
+type InlineGristGlobal = {
+    ready: (options?: GristReadyOptions) => Promise<void>;
+    onRecord: (cb: (record: Record<string, unknown> | null, mappings?: GristWidgetColumnMap | null) => void, options?: GristFetchSelectedOptions) => void;
+    onRecords: (cb: (records: Record<string, unknown>[], mappings?: GristWidgetColumnMap | null) => void, options?: GristFetchSelectedOptions) => void;
+    onOptions: (cb: (options: Record<string, unknown> | null, interaction: GristWidgetInteraction) => void) => void;
+    onNewRecord: (cb: (mappings: GristWidgetColumnMap | null) => void) => void;
+    mapColumnNames: (data: Record<string, unknown>) => Record<string, unknown> | null;
+    mapColumnNamesBack: (data: Record<string, unknown>) => Record<string, unknown>;
+    getOptions: () => Promise<Record<string, unknown> | null>;
+    getOption: (key: string) => Promise<unknown>;
+    setOption: (key: string, value: unknown) => Promise<void>;
+    setOptions: (options: Record<string, unknown>) => Promise<void>;
+    clearOptions: () => Promise<void>;
+    setCursorPos: (pos: GristCursorPos) => Promise<void>;
+    setSelectedRows: (rowIds: number[] | null) => Promise<void>;
+    fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
+    fetchSelectedRecord: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+    docApi: {
+        getDocName: () => Promise<string>;
+        listTables: () => Promise<string[]>;
+        fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
+        applyUserActions: (actions: unknown[][], options?: {
+            desc?: string;
+        }) => Promise<{
+            retValues: unknown[];
+        }>;
+        getAccessToken?: (options?: {
+            readOnly?: boolean;
+        }) => Promise<{
+            token: string;
+            baseUrl: string;
+        }>;
+        fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
+        fetchSelectedRecord: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+    };
+    selectedTable: GristTableOperations;
+    getTable: (tableId?: string) => GristTableOperations;
+    sectionApi: {
+        configure: (settings: GristReadyOptions) => Promise<void>;
+        mappings: () => Promise<GristWidgetColumnMap | null>;
+    };
+    on: (eventName: string, listener: (...args: unknown[]) => void) => () => void;
+};
+type InlineTransportOptions = TransportContext & {
+    /**
+     * Where to mount the synthesised `grist` global.
+     * Defaults to the current window. Pass a different target (e.g. an iframe's
+     * `contentWindow`) to install it in another realm.
+     */
+    target?: Window & typeof globalThis;
+};
+/**
+ * Returns an {@link EmulatorTransport} **and** the synthesised `grist`
+ * object. `target.grist = global` is set as a side-effect for parity with
+ * the production runtime.
+ */
+declare function createInlineTransport(options: InlineTransportOptions): EmulatorTransport & {
+    grist: InlineGristGlobal;
+};
+
+export { type EmulatorApiBundle as E, type InlineGristGlobal as I, type TransportContext as T, type EmulatorColumn as a, type EmulatorDocumentState as b, type EmulatorEvent as c, type EmulatorRowId as d, type EmulatorTable as e, type EmulatorTransport as f, type EventBus as g, type InlineTransportOptions as h, createInlineTransport as i };

package/dist/templates-BC7FoSdW.d.ts

@@ -0,0 +1,24 @@
+import { k as GristReplicaDocument } from './types-Fb2wplkv.js';
+
+/**
+ * Document templates exposed at the top of the emulator API.
+ *
+ * Templates return plain data — they don't allocate state, the caller passes
+ * the returned value into `createGristEmulator(...)` which performs the allocation.
+ */
+
+/**
+ * Useful templates for quick demos and tests.
+ */
+declare const presets: {
+    /**
+     * Default starter fixture for demos / sandboxes that need a neutral document
+     * without choosing a domain-specific preset.
+     */
+    defaultTemplate(): GristReplicaDocument;
+    blank(): GristReplicaDocument;
+    todoList(): GristReplicaDocument;
+    contacts(): GristReplicaDocument;
+};
+
+export { presets as p };

package/dist/templates-DBq719O_.d.cts

@@ -0,0 +1,24 @@
+import { k as GristReplicaDocument } from './types-Fb2wplkv.cjs';
+
+/**
+ * Document templates exposed at the top of the emulator API.
+ *
+ * Templates return plain data — they don't allocate state, the caller passes
+ * the returned value into `createGristEmulator(...)` which performs the allocation.
+ */
+
+/**
+ * Useful templates for quick demos and tests.
+ */
+declare const presets: {
+    /**
+     * Default starter fixture for demos / sandboxes that need a neutral document
+     * without choosing a domain-specific preset.
+     */
+    defaultTemplate(): GristReplicaDocument;
+    blank(): GristReplicaDocument;
+    todoList(): GristReplicaDocument;
+    contacts(): GristReplicaDocument;
+};
+
+export { presets as p };