@book.dev/sdk 3.7.0 → 3.9.0

package/dist/tableSnapshot.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Table STRUCTURE ops over a stored page snapshot (API-3).
+ *
+ * The editor owns the live-document versions of these ops (`packages/ui/src/
+ * blockeditor/model.ts` — `tableInsertRow`, `tableMoveColumn`, …), which mutate a
+ * Y.Doc inside one transaction. This module is their SERVER-SIDE twin: the same
+ * seven structural ops (plus cell text and row/column tints) applied to the
+ * `blockdoc` JSON projection, for the paths that have no live editor — the MCP
+ * write tools, and the agent bridge's stored-page fallback.
+ *
+ * ── THE `col:` / `ord` DECISION ──────────────────────────────────────────────
+ * A keyed table carries FRACTIONAL ORDER KEYS: `table.props['col:<colId>']` per
+ * column and `row.props.ord` per row (see the model's table contract). Render
+ * order is those keys sorted — never array order. A table built by
+ * `append_blocks` has NO keys (an MCP client can't invent them), so it is a
+ * "legacy" table that renders in array order until something migrates it.
+ *
+ * These ops MIGRATE EAGERLY: every op runs {@link ensureSnapshotTableOrder}
+ * first — a line-for-line mirror of the editor's `ensureTableOrderInTx`, using
+ * the SAME shared key algebra (`./orderKeys`, which the editor now imports from
+ * here) and the SAME deterministic column ids (`c0…cN-1`) and
+ * `keysBetween(null, null, n)` spread. So a table migrated by an MCP op and the
+ * same table migrated by the editor end up with IDENTICAL keys.
+ *
+ * We do NOT take the alternative — "stay positional and let
+ * `ensureTableOrderInTx` migrate later" — because three of the ops
+ * (`move_row`, `move_column`, and every insert) are DEFINED as order-key edits.
+ * A positional-only snapshot op would have to reorder the arrays instead, which
+ * (a) gives a different result than the editor for an already-keyed table, and
+ * (b) rewrites nodes a concurrent peer is editing, losing the ops' convergence
+ * property. Migrating first costs one deterministic pass and makes the editor,
+ * agent-proposal and snapshot paths produce the same grid — which is exactly
+ * what the cross-path invariant test asserts.
+ *
+ * Ops here mutate a DEEP COPY of the snapshot's blocks and drop the stale CRDT
+ * `update` (like every other snapshot writer), so the next reader rebuilds from
+ * the projection.
+ */
+import type { PageSnapshot } from './types';
+/** Prefix of the column-registry entries in a table block's props. */
+export declare const TABLE_COL_PREFIX = "col:";
+/** Prefix of the per-column colour entries (`colbg:<colId>` → palette token). */
+export declare const TABLE_COLBG_PREFIX = "colbg:";
+/**
+ * The table order-contract PRIVATE keys (TBL-1): `row.props.ord`,
+ * `cell.props.col`, the `col:<id>` column registry, and the `colbg:<id>`
+ * column tints. They encode a table's cell order/identity — writing them
+ * through a generic props tool corrupts or hides cells, so EVERY
+ * update_block_props surface (MCP server AND the in-app agent) refuses them
+ * with {@link tableOrderContractRefusal} and points at the sanctioned table
+ * structure tools. Returns the offending key, or null when `props` touches
+ * none.
+ */
+export declare function tableOrderContractKey(props: Record<string, unknown>): string | null;
+/** The shared refusal message for a {@link tableOrderContractKey} hit — the
+ *  SAME wording on both write surfaces, naming the table tools that own the
+ *  keys. */
+export declare const tableOrderContractRefusal: (key: string) => string;
+/** One block of the `blockdoc` JSON projection, as these ops mutate it. */
+export interface SnapshotBlock {
+    id?: string;
+    type?: string;
+    text?: Array<{
+        t: string;
+        a?: Record<string, unknown>;
+    }>;
+    props?: Record<string, unknown>;
+    children?: SnapshotBlock[];
+}
+/**
+ * The structural table ops, named exactly as the agent proposal kinds and the
+ * MCP tool names — one vocabulary across the editor bridge, the agent, and MCP.
+ */
+export type TableOpKind = 'table_insert_row' | 'table_delete_row' | 'table_duplicate_row' | 'table_insert_column' | 'table_delete_column' | 'table_move_row' | 'table_move_column' | 'table_set_cell' | 'table_set_row_color' | 'table_set_column_color';
+/** Every {@link TableOpKind}, for schema/description generation. */
+export declare const TABLE_OP_KINDS: readonly TableOpKind[];
+/**
+ * A table op with its coordinates already RESOLVED to SORTED (render-order)
+ * indices — the same coordinate space as the editor's `cellPosition`. Id-based
+ * addressing (a cell id, a row id, a column id) is resolved to these indices by
+ * {@link resolveTableOp} before validation, so bounds errors read the same
+ * whichever way the caller addressed the table.
+ */
+export interface TableOpRequest {
+    kind: TableOpKind;
+    /** Sorted row index (row-axis ops, and `table_set_cell`). */
+    rowIndex?: number;
+    /** Sorted column index (column-axis ops, and `table_set_cell`). */
+    colIndex?: number;
+    /** Move target, a sorted index counted with the moved row/column REMOVED. */
+    toIndex?: number;
+    /** New plain text (`table_set_cell`). */
+    text?: string;
+    /** Palette token, or null to clear (`table_set_row_color` / `..._column_color`). */
+    color?: string | null;
+}
+/** The dimensions an op is validated against (from the SORTED grid). */
+export interface TableShape {
+    rows: number;
+    cols: number;
+    /** The table's `header` prop — sorted row 0 renders as the header row. */
+    header: boolean;
+}
+/**
+ * Validate a resolved op against the table's shape — the ONE definition of the
+ * table ops' server-side invariants, shared by the agent bridge and the MCP
+ * tools so both refuse exactly the same requests with exactly the same words.
+ * Returns an actionable message, or null when the op is legal.
+ *
+ * Mirrors the editor's context-menu guards (`BlockEditor.tsx`,
+ * `TableCellMenuContent`):
+ *  · insert-row-above is HIDDEN on the header row, because rendering is
+ *    positional — the blank new row would become the header and silently demote
+ *    the real one. Here that is a refusal, not a silent clamp.
+ *  · move up/down and move left/right are DISABLED at the extremes, which is the
+ *    same thing as a target index outside `0…n-1`.
+ *  · row 0 is otherwise an ordinary row: it can be deleted, duplicated, tinted,
+ *    and another row may be MOVED into position 0 (that promotes it to header —
+ *    the documented behaviour of contract note 5).
+ * Unlike the editor's ops (which CLAMP indices and no-op on a miss), these
+ * refuse: a remote caller that mis-addresses a table should hear about it rather
+ * than have the edit land somewhere else.
+ */
+export declare function tableOpError(shape: TableShape, op: TableOpRequest): string | null;
+/** True for the two ops whose "last one" case removes the whole table block. */
+export declare function tableOpRemovesTable(shape: TableShape, op: TableOpRequest): boolean;
+/** The table's column registry, sorted into render order (key, then id). */
+export declare function snapshotTableColumns(table: SnapshotBlock): Array<{
+    id: string;
+    key: string;
+}>;
+/** The sorted grid view of a snapshot table — mirrors the model's `TableGrid`. */
+export interface SnapshotTableGrid {
+    keyed: boolean;
+    rows: SnapshotBlock[];
+    colIds: string[];
+    /** `cells[r][c]`, null for a merge gap (exactly like the model's grid). */
+    cells: (SnapshotBlock | null)[][];
+    width: number;
+}
+export declare function snapshotTableGrid(table: SnapshotBlock): SnapshotTableGrid;
+/**
+ * Lazy migration + backfill of a snapshot table's order keys — the mirror of the
+ * editor's `ensureTableOrderInTx`, deterministic in exactly the same way so a
+ * migration performed here and one performed in the editor converge. Idempotent.
+ */
+export declare function ensureSnapshotTableOrder(table: SnapshotBlock): void;
+/** A read-only projection of a table for inspection + op resolution. */
+export interface SnapshotTableView {
+    tableId: string;
+    header: boolean;
+    rows: number;
+    cols: number;
+    /** Row block ids in SORTED order. */
+    rowIds: string[];
+    /** Column ids in SORTED order (empty for a not-yet-migrated legacy table). */
+    colIds: string[];
+    /** Cell block ids in SORTED order; null for a merge gap. */
+    cellIds: (string | null)[][];
+    /** Cell plain text in SORTED order; '' for a merge gap. */
+    cells: string[][];
+}
+/**
+ * Read a table by id from a page snapshot, in SORTED render order. Read-only —
+ * it never migrates (like the model's `cellPosition`), so `colIds` is empty for
+ * a legacy table even though `cols` already reports its rendered width. Returns
+ * null when `tableId` isn't a `table` block on the page.
+ */
+export declare function snapshotTableView(data: PageSnapshot | null | undefined, tableId: string): SnapshotTableView | null;
+/** Grid coordinates of a cell id — the snapshot mirror of `cellPosition`. */
+export declare function snapshotCellPosition(data: PageSnapshot | null | undefined, cellId: string): {
+    tableId: string;
+    row: number;
+    col: number;
+    rows: number;
+    cols: number;
+} | null;
+/** The id of the table that contains `blockId` (a table, row, or cell id). */
+export declare function snapshotTableIdFor(data: PageSnapshot | null | undefined, blockId: string): string | null;
+/** How a caller addressed a table op: sorted indices and/or block ids. */
+export interface TableOpAddress {
+    rowIndex?: number;
+    colIndex?: number;
+    toIndex?: number;
+    /** A cell id — resolves BOTH `rowIndex` and `colIndex`. */
+    cellId?: string;
+    /** A row block id — resolves `rowIndex`. */
+    rowId?: string;
+    /** A column id (from `col:<id>` / a cell's `col` prop) — resolves `colIndex`. */
+    colId?: string;
+    text?: string;
+    color?: string | null;
+}
+/**
+ * Resolve id-based addressing to SORTED indices against a table view. An id that
+ * isn't in this table is an error, never a silent fallback.
+ *
+ * Precedence: for ops that TARGET AN EXISTING NODE, an id wins over the matching
+ * index — the id is that node's identity, so a caller who sent both meant the
+ * node. For the two INSERT ops the index is a POSITION, not a node, so an id
+ * there only serves to name the table and never overrides the position (a
+ * `cellId` on `table_insert_row` means "the table this cell is in", not "insert
+ * at this cell's row").
+ */
+export declare function resolveTableOp(view: SnapshotTableView, kind: TableOpKind, address: TableOpAddress): {
+    op: TableOpRequest;
+} | {
+    error: string;
+};
+/** The shape an op is validated against, from a read view. */
+export declare const tableShapeOf: (view: SnapshotTableView) => TableShape;
+/**
+ * Apply ONE resolved table op to a page snapshot, returning the new snapshot.
+ * Coordinates are SORTED indices ({@link resolveTableOp} turns ids into them);
+ * validate with {@link tableOpError} first — this function assumes a legal op
+ * and clamps like the editor rather than reporting.
+ *
+ * Returns null when `tableId` isn't a table on the page. `removedTable` is true
+ * when the op deleted the LAST row or column, which removes the whole table
+ * block — the editor's behaviour (`tableDeleteRow` / `tableDeleteColumn`), kept
+ * identical here so the three paths can't diverge.
+ */
+export declare function applyTableOpToSnapshot(data: PageSnapshot, tableId: string, op: TableOpRequest): {
+    data: PageSnapshot;
+    removedTable: boolean;
+} | null;
+/** Every `table` block on a page, in document order (for `list_tables`). */
+export declare function snapshotTables(data: PageSnapshot | null | undefined): Array<{
+    id: string;
+    rows: number;
+    cols: number;
+    header: boolean;
+}>;