docblocks-react-ui 0.0.0-stage → 0.1.0

package/dist/index-D6_ysSmQ.d.mts

@@ -0,0 +1,1075 @@
+import { n as BlockRendererMap } from "./index-YJcgf8Hh.mjs";
+import { ComponentType, ReactNode } from "react";
+import { Block, BlockContent, BlockId, BlockType, CanvasTextAttrs, Change, ConnectorAttrs, DatabaseFilterPayload, Doc, DocMeta, Geometry, PresenceState, Selection, SelectionView, ShapeAttrs, SyncEmbedRef, SyncProvider } from "docblocks-core";
+import { StoreApi } from "zustand/vanilla";
+//#region src/blob-store.d.ts
+/**
+ * The blob bridge: the library does not own storage.
+ *
+ * The bytes live where the consumer stored them (S3, disk, a CDN — the
+ * package does not know and does not care). The document holds only an
+ * opaque key, and the consumer's callbacks are the only path key →
+ * displayable url and file → key. Both directions carry the metadata:
+ * `upload` accepts a `meta` (the consumer decides the subtype), and
+ * `resolve` returns the key's url plus the authoritative metadata — the
+ * UI renders from `meta.subtype` and never guesses (an image blob stands
+ * an `<img>`, a pdf an iframe viewer, a file a download card).
+ *
+ * The legacy `blobResolver` prop (synchronous key → src string) wraps as
+ * a store: view-only (no upload), subtype "image".
+ */
+/** The blob's media class; the consumer decides, extends additively. */
+type BlobSubtype = "image" | "pdf" | "file";
+/** The blob's display metadata (the consumer is the source of truth). */
+interface BlobMeta {
+  subtype: BlobSubtype;
+  /** The file name (the file card's caption). */
+  name?: string;
+  /** The mime type. */
+  type?: string;
+  /** The byte size. */
+  size?: number;
+}
+/** A resolved blob: the displayable url and its authoritative metadata. */
+interface BlobRef {
+  /** The displayable url (http(s)/data/object — the form is the consumer's). */
+  url: string;
+  meta: BlobMeta;
+}
+/** The consumer's blob bridge (injected via the EditorProvider `blobStore` prop). */
+interface BlobStore {
+  /** Key → the displayable url + the authoritative metadata; rejects an unknown key. */
+  resolve(key: string): Promise<BlobRef>;
+  /** Upload: file → the opaque key (the doc holds only the key).
+   *  The consumer may extend or override `meta` (it decides the subtype).
+   *  Throws a typed error on the backend's refusal. */
+  upload(file: File | Blob, meta?: Partial<BlobMeta>): Promise<string>;
+  /** Optional: drop the bit (gc). Not required by the v contract. */
+  remove?(key: string): Promise<void>;
+}
+/** Derive the subtype from the file's mime (the consumer's `meta.subtype` wins). */
+declare function blobSubtypeOf(file: File | Blob): BlobSubtype;
+/**
+ * The package's default in-memory store (the consumer passes no `blobStore`):
+ * uploads stand data urls for the JS session, cleared on the page reload.
+ */
+declare function createMemoryBlobStore(): BlobStore;
+//#endregion
+//#region src/database/bridge/errors.d.ts
+/**
+ * The bridge's structured error: the stable machine-readable code +
+ * the safe message (no stack trace, SQL or tenant details) + the optional
+ * retry hint / the failed field's path. The transport serializes the error
+ * as the rejected result; `toBridgeError` normalizes an unknown rejection
+ * to the same shape.
+ */
+/**
+ * The stable error codes. The client's rule per code group: `validation` /
+ * `protocol_mismatch` — show, no retry; `not_found` / `forbidden` — stop,
+ * clear the sensitive state; `conflict` — rebaseline and offer the retry;
+ * `idempotency_conflict` — no automatic retry; `idempotency_expired` /
+ * `operation_unknown` — rebaseline, never a new operation;
+ * `limit_exceeded` / `payload_too_large` — shrink the request, no retry
+ * unchanged; `cursor_expired` / `replay_expired` — discard the page /
+ * cursor and take a fresh snapshot; `transient` / `unavailable` /
+ * `timeout` — retry only with the same operationId; `enum.option_in_use`
+ * — show, no retry (the delete's default refusal; the explicit
+ * replacement migration is the consumer's separate operation).
+ */
+type BridgeErrorCode = "validation" | "invalid_filter" | "invalid_operator" | "invalid_column" | "protocol_mismatch" | "limit_exceeded" | "payload_too_large" | "not_found" | "forbidden" | "conflict" | "idempotency_conflict" | "idempotency_expired" | "operation_unknown" | "cursor_expired" | "replay_expired" | "transient" | "unavailable" | "timeout" | "enum.option_in_use";
+/** Every code of the set (the closed vocabulary). */
+declare const BRIDGE_ERROR_CODES: readonly BridgeErrorCode[];
+/** The structured bridge error (the rejection of every contract method). */
+declare class BridgeError extends Error {
+  readonly code: BridgeErrorCode;
+  readonly retryAfter?: number;
+  readonly path?: string;
+  constructor(code: BridgeErrorCode, message: string, options?: {
+    retryAfter?: number;
+    path?: string;
+    cause?: unknown;
+  });
+}
+/** The code membership (the closed vocabulary's guard). */
+declare function isBridgeErrorCode(value: unknown): value is BridgeErrorCode;
+/**
+ * The error's guard: the class instance or the plain serialized shape
+ * (the wire-rehydrated `{ code, message }` object).
+ */
+declare function isBridgeError(error: unknown): error is BridgeError;
+/**
+ * Normalizes an unknown rejection to the contract's error. A rejection
+ * that carries no recognizable machine code is a transport-level failure
+ * (the write's outcome is unknown) and stands the `unavailable` group: the
+ * safe recovery is the same-operationId reconciliation, not a blind new
+ * operation.
+ */
+declare function toBridgeError(error: unknown): BridgeError;
+//#endregion
+//#region src/database/bridge/models.d.ts
+/** An opaque stable identifier (the table / row / field / operation id). */
+type Id = string;
+/** The consumer's revision stand (the row / column / table's version). */
+type Revision = string;
+/** The ISO-8601 instant (the mutation's issue time). */
+type IsoInstant = string;
+/** A row's cells: the field id → the stored value. `null` clears a
+ *  nullable cell; an absent key stands "do not change"; `undefined` is
+ *  never a stored value (it is dropped before the JSON serialization). */
+type CellMap = Record<Id, unknown>;
+/** The table's catalog entry (the picker / the block's reference). */
+interface TableRef {
+  id: Id;
+  name: string;
+  revision: Revision;
+  /** The hidden system table (the enum's options' catalog): absent from
+   *  `listTables`, reachable by id. */
+  system?: boolean;
+}
+/** The column's schema entry (the consumer's field registry row). */
+interface Column {
+  id: Id;
+  name: string;
+  type: string;
+  /** The position in the schema order (the 0-based seat). */
+  position: number;
+  nullable: boolean;
+  revision: Revision;
+  /** The operator catalog override; the consumer's default catalog for
+   *  the type stands when absent. */
+  operators?: string[];
+  /** The reference relation over the plain column: the cell holds the
+   *  referenced row's stable id (an option row id for the enum, a linked
+   *  row id for the row link); `many` = the cell holds the array. */
+  reference?: {
+    kind: "enum" | "row";
+    tableId: Id;
+    many: boolean;
+    /** The display column of the linked table (the row-link's stand; the
+     *  default is the first text column / the pk). */
+    displayColumnId?: Id;
+  };
+  /** The number column's display attributes. */
+  numberDisplay?: {
+    decimals?: number;
+    thousands?: boolean;
+    prefix?: string;
+    suffix?: string;
+    allowNegative?: boolean;
+  };
+}
+/** The table's schema + the table reference. */
+interface TableDescription {
+  table: TableRef;
+  columns: Column[];
+  schemaRevision: Revision;
+}
+/** A query operator descriptor (the value's kind the filter builder
+ *  renders). */
+interface QueryOperator {
+  id: string;
+  valueKind: "none" | "scalar" | "list";
+}
+/** The server's query semantics (the canonicalization stand the filter /
+ *  sort values normalize to). */
+interface QuerySemantics {
+  semanticsVersion: string;
+  collation: string;
+  timezone: string;
+  nullOrdering: "first" | "last";
+  operatorsByColumnType: Record<string, QueryOperator[]>;
+}
+/** One filter condition (the column + the operator + the value; the value
+ *  is absent only for the valueless operators). */
+interface FilterConditionInput {
+  columnId: Id;
+  op: string;
+  value?: unknown;
+}
+/** The recursive and/or filter input (the block's `filter` view state; the
+ *  server canonicalizes and validates it against the declared operators —
+ *  the unknown column / operator / type rejects). */
+interface FilterInput {
+  logic: "and" | "or";
+  conditions: FilterConditionInput[];
+  groups?: FilterInput[] | null;
+}
+/** The sort input: the ordered sort keys (the null ordering per key). */
+type SortInput = {
+  fieldId: Id;
+  direction: "asc" | "desc";
+  nulls?: "first" | "last";
+}[];
+/** The page query (the filter + the sort + the page size). */
+interface PageQuery {
+  filter?: FilterInput;
+  sort?: SortInput;
+  limit?: number;
+}
+/** A wire row: the stable id + the canonical physical order key (a finite
+ *  IEEE-754 number — never a string, NaN or infinity; the canonical total
+ *  order is `(orderKey, rowId)`) + the revision + the cells. The page's
+ *  row order is the array's order. */
+interface RowWire {
+  id: Id;
+  orderKey: number;
+  revision: Revision;
+  cells: Record<string, unknown>;
+}
+/** An ordered row page: the rows in the server's order + the opaque next
+ *  cursor (null = the last page) + the snapshot's top event boundary +
+ *  the schema revision + the query fingerprint (the server's signed
+ *  canonical form — the client never constructs one). */
+interface RowPage {
+  rows: RowWire[];
+  nextCursor: string | null;
+  asOfSeq: number;
+  schemaRevision: Revision;
+  queryFingerprint: string;
+}
+/** The page + the query semantics. */
+type PageSnapshot = RowPage & {
+  semantics: QuerySemantics;
+};
+/** The initial load: the schema and the first page from one consistent
+ *  snapshot (the `page.asOfSeq` is the R both represent). */
+type TableSnapshot = TableDescription & {
+  page: PageSnapshot;
+};
+/** The write's context: the client-issued idempotency key (a UUID, unique
+ *  within the operation retention) + the issue time + the optional CAS
+ *  revision (its absence selects the LWW default — the last committed
+ *  write of the same cell wins). */
+interface MutationContext {
+  operationId: Id;
+  issuedAt: IsoInstant;
+  expectedRevision?: Revision;
+}
+/** The committed mutation's receipt: the operation's ids + the commit's
+ *  sequence + the server-normalized result + the new revisions. The outer
+ *  commit envelope of the same operation carries the very same receipt. */
+interface MutationReceipt<T> {
+  operationId: Id;
+  txId: Id;
+  committedSeq: number;
+  result: T;
+  revisions: Record<Id, Revision>;
+}
+/** The operation's status (the lost-response reconciliation: the
+ *  committed receipt or the pending stand). */
+type OperationStatus<T = unknown> = {
+  state: "committed";
+  receipt: MutationReceipt<T>;
+} | {
+  state: "pending";
+};
+/** The protocol capability (the baseline set every conformant bridge
+ *  declares; the optional sets gate the UI paths that need them). */
+type ProtocolCapability = "orderedRows" | "snapshotReplay" | "idempotentWrites" | "structuredErrors" | "viewInvalidation" | "cas" | "rowRestore" | "columnRestore" | "serverSort" | "mixedBatch" | "materializedWindow";
+/** The negotiated finite limits (the server enforces the filter's depth /
+ *  terms, the page size, the batch's count, the request / frame bytes and
+ *  the active subscriptions with `limit_exceeded` / `payload_too_large`). */
+interface ProtocolLimits {
+  maxFilterDepth: number;
+  maxFilterTerms: number;
+  maxPageSize: number;
+  maxBatchOps: number;
+  maxRequestBytes: number;
+  maxFrameBytes: number;
+  maxSubscriptions: number;
+}
+/** The protocol descriptor (the version + the capabilities + the limits +
+ *  the retention horizons). */
+interface ProtocolDescriptor {
+  protocolVersion: 2;
+  capabilities: readonly ProtocolCapability[];
+  limits: ProtocolLimits;
+  operationRetentionSeconds: number;
+  retryHorizonSeconds: number;
+}
+/** The domain event (the nested record of a committed transaction's
+ *  envelope — the nested events never carry their own seq). */
+type DomainEvent = {
+  type: "table.created";
+  payload: {
+    table: TableDescription;
+  };
+} | {
+  type: "table.renamed";
+  payload: {
+    table: TableRef;
+  };
+} | {
+  type: "table.deleted";
+  payload: {
+    tableId: Id;
+    revision: Revision;
+  };
+} | {
+  type: "field.created" | "field.updated" | "field.restored";
+  payload: {
+    column: Column;
+    schemaRevision: Revision;
+  };
+} | {
+  type: "field.deleted";
+  payload: {
+    columnId: Id;
+    before: Column;
+    schemaRevision: Revision;
+  };
+} | {
+  type: "row.created" | "row.updated" | "row.restored" | "row.moved";
+  payload: {
+    row: RowWire;
+  };
+} | {
+  type: "row.deleted";
+  payload: {
+    rowId: Id;
+    deletedRevision: Revision;
+    before: RowWire;
+  };
+} | {
+  type: "enum.option.renamed";
+  payload: {
+    catalogTableId: Id;
+    option: RowWire;
+  };
+};
+/** The committed transaction's envelope base (the per-table ordered
+ *  stream's frame). */
+interface TableEnvelopeBase {
+  tableId: Id;
+  /** The envelope's monotonic sequence (not necessarily the previous's + 1). */
+  seq: number;
+  /** The previous committed envelope's seq (null for the table's first) —
+   *  the client detects a loss by the chain, not by the arithmetic. */
+  prevSeq: number | null;
+  txId: Id;
+}
+/** The per-table stream's frame: one committed transaction → one outer
+ *  envelope → one `seq` / `prevSeq`; the `commit` kind carries the ordered
+ *  nested domain events, the `invalidate` kind stands the explicit
+ *  rebaseline (the server reset signal, the large rebalance). */
+type TableEvent = TableEnvelopeBase & ({
+  kind: "commit";
+  /** The session id of the write's origin (the per-connection stand
+   *  — a second tab of the same user is NOT the origin). */
+  originSessionId: Id;
+  operationId: Id;
+  receipt: MutationReceipt<unknown>;
+  events: DomainEvent[];
+} | {
+  kind: "invalidate";
+  /** Present for a client mutation, null for a server reset signal. */
+  originSessionId: Id | null;
+  operationId: Id | null;
+  receipt: MutationReceipt<unknown> | null;
+  events: [];
+});
+/** The subscription's status (the bootstrap's phases). */
+type SubscriptionStatus = "connecting" | "replaying" | "live" | "closed";
+/** The subscription's observer: the readiness (the replay's cursor + the
+ *  table's head + the protocol), the ordered at-least-once stream, the
+ *  transport's errors, and the forced rebaseline signals. */
+interface SubscriptionObserver {
+  /** The subscriber is registered: the replay stands the events after
+   *  `afterSeq`, `headSeq` is the table's current head. */
+  ready: (value: {
+    afterSeq: number;
+    headSeq: number;
+    protocol: ProtocolDescriptor;
+  }) => void;
+  event: (value: TableEvent) => void;
+  status: (value: SubscriptionStatus) => void;
+  error: (error: BridgeError) => void;
+  /** The local page is discarded and a fresh snapshot is taken (the
+   *  replay expired, the permission lost, the gap detected). */
+  reset: (value: {
+    code: "replay_expired" | "permission_lost" | "gap_detected";
+  }) => void;
+}
+/** The subscription's handle. */
+interface SubscriptionHandle {
+  unsubscribe(): void;
+}
+/**
+ * A bridge column (the grid's view over the wire's `Column` — the display
+ * attributes flattened, the reference relation's fields in the wire's
+ * `reference` stand). The `type` is a standard PostgreSQL type name (or
+ * the consumer's own name): the contract is type-agnostic — the package
+ * does not validate the set; the consumer maps type → DDL and type →
+ * cell editor. `operators` is the consumer's operator catalog override;
+ * when absent, the package's default catalog for the type stands (the
+ * filter builders), and the query must apply exactly the declared
+ * operators. The `decimals` / `thousands` / `prefix` / `suffix` /
+ * `allowNegative` fields are the number column's display attributes (the
+ * column's own data — the package's number formatter reads them). The
+ * reference fields declare a RELATION over the plain column:
+ * `refKind "enum"` — the cell value is the option row id of the dict
+ * table (`refTableId`); `refKind "row"` — the cell value is the linked
+ * table's row id (`refDisplayColumn` declares which column of the linked
+ * table stands the display; the default is the first text column / the
+ * pk). `refMany` is the many cardinality (the cell value is an ARRAY of
+ * the option row ids / the row ids; the consumer maps the array to a
+ * junction table behind the row's write).
+ */
+interface BridgeColumn {
+  id: string;
+  name: string;
+  type: string;
+  operators?: string[];
+  /** The reference table (the dict table for the enum options / the
+   *  linked table for the row links). */
+  refTableId?: string;
+  /** The reference kind: "enum" (the dict table's rows are the options)
+   *  or "row" (the cell holds the linked row's row id). */
+  refKind?: "enum" | "row";
+  /** The many cardinality (the cell value is an array). */
+  refMany?: boolean;
+  /** The display column of the linked table (the row-link display; the
+   *  default is the first text column / the pk). */
+  refDisplayColumn?: string;
+  /** The number's digit count after the point (default 0 = integer). */
+  decimals?: number;
+  /** The thousands' separator (the space grouping: `1 000 000`). */
+  thousands?: boolean;
+  /** The display's prefix stand (e.g. the currency sign). */
+  prefix?: string;
+  /** The display's suffix stand. */
+  suffix?: string;
+  /** Whether negative values are allowed (the edit rejects them otherwise). */
+  allowNegative?: boolean;
+}
+/**
+ * The table description (the grid's view over the wire's
+ * `TableDescription`): the table's name + the grid's columns.
+ */
+interface BridgeTableDescription {
+  name: string;
+  columns: BridgeColumn[];
+}
+/** The cell value input kind the annotation derives from the column type. */
+type BridgeValueInput = "text" | "number" | "boolean" | "date" | "datetime" | "enum" | "row-link" | "none";
+/** The column annotation the filter builder renders from. */
+interface BridgeColumnAnnotation {
+  /** The operator catalog (the consumer's `operators` override or the package default for the type). */
+  operators: string[];
+  /** The value input kind (none = no value is taken: empty / not-empty). */
+  valueInput: BridgeValueInput;
+  /** Whether the operators take no value (empty / not-empty). */
+  valueless: Set<string>;
+}
+/**
+ * The parse result of a typed cell / filter value: the committed value
+ * (`null` for the empty string) or the validation error (the input is not
+ * committed — the editor keeps / reverts to the last valid value).
+ */
+type CellValueParse = {
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+  error: string;
+};
+/** A batch operation (the mixed batch's element; the ordered `ops[]`
+ *  commit as one transaction — either the whole batch or none). */
+type BatchOp = {
+  op: "create";
+  row: CellMap;
+  beforeRowId?: Id | null;
+} | {
+  op: "update";
+  rowId: Id;
+  cells: CellMap;
+  expectedRevision?: Revision;
+} | {
+  op: "delete";
+  rowId: Id;
+  expectedRevision?: Revision;
+} | {
+  op: "move";
+  rowId: Id;
+  beforeRowId: Id | null;
+  expectedRevision?: Revision;
+};
+/**
+ * The bridge contract (all methods async; a failure rejects with a
+ * `BridgeError`). `snapshotTable` is the sole initial read; `queryNextPage`
+ * only follows it over the opaque query-bound cursor. `subscribeTable` is
+ * the only push channel: the client takes the snapshot R first, then
+ * subscribes with `afterSeq: R` — the server registers the subscriber,
+ * replays every `seq > R` in the table's order, then continues the same
+ * stream live. A repeated `operationId` with the same operation body
+ * returns the initial committed result without a second effect; a repeated
+ * id with a different body rejects with `idempotency_conflict`; an id
+ * outside the retention rejects with `idempotency_expired` and is never
+ * executed again.
+ */
+interface DatabaseBridge {
+  /** The protocol descriptor (the version + the capabilities + the
+   *  limits): the client negotiates it before any use — a version /
+   *  baseline-capability mismatch stands the `protocol_mismatch`, not a
+   *  silent downgrade. */
+  describeProtocol(): Promise<ProtocolDescriptor>;
+  /** The visible tables (the system tables stand excluded). */
+  listTables(): Promise<TableRef[]>;
+  /** Create the table (empty — the schema stands the `createColumn`
+   *  calls) → the committed table reference. */
+  createTable(input: {
+    name: string;
+    system?: boolean;
+  }, ctx: MutationContext): Promise<MutationReceipt<TableRef>>;
+  /** Rename the table (the name stands on the table, shared by every
+   *  block that references it). */
+  renameTable(tableId: Id, input: {
+    name: string;
+  }, ctx: MutationContext): Promise<MutationReceipt<TableRef>>;
+  /** The table schema + the pk / order metadata. */
+  describeTable(tableId: Id): Promise<TableDescription>;
+  /** The sole initial load: the schema and the first page from one
+   *  consistent snapshot (the `page.asOfSeq` is the R both represent). */
+  snapshotTable(tableId: Id, query: PageQuery): Promise<TableSnapshot>;
+  /** The next page over the opaque keyset cursor (the cursor is signed
+   *  and bound to its table, its snapshot R and its normalized query);
+   *  any commit that advanced the table's public head after R rejects
+   *  with `cursor_expired` — the client takes a fresh `snapshotTable`. */
+  queryNextPage(tableId: Id, input: {
+    cursor: string;
+    asOfSeq: number;
+    queryFingerprint: string;
+  }): Promise<PageSnapshot>;
+  /** Add a column (after `afterColumnId`, or at the end). */
+  createColumn(tableId: Id, input: {
+    column: Omit<Column, "id" | "revision">;
+    afterColumnId?: Id;
+  }, ctx: MutationContext): Promise<MutationReceipt<Column>>;
+  /** Patch the column's attributes (the rename stands the `name` key —
+   *  the name is an attribute). */
+  updateColumn(tableId: Id, columnId: Id, patch: Partial<Omit<Column, "id" | "revision">>, ctx: MutationContext): Promise<MutationReceipt<Column>>;
+  /** Remove a column. The consumer MAY stand the soft-delete posture
+   *  (the definition, the position and the cell values stay preserved,
+   *  the removal restorable over `restoreDeletedColumn`); the destructing
+   *  posture stands the removal not undoable. */
+  deleteColumn(tableId: Id, columnId: Id, ctx: MutationContext): Promise<MutationReceipt<{
+    columnId: Id;
+  }>>;
+  /** Restore the soft-deleted column — its schema, its position and the
+   *  preserved cell values; the no-op when the column stands in the
+   *  schema again. */
+  restoreDeletedColumn(tableId: Id, columnId: Id, ctx: MutationContext): Promise<MutationReceipt<Column>>;
+  /** The row displays for the row-link cells (the join stands in the
+   *  consumer backend; the missing / deleted target stands `null` — no
+   *  data of the absent target is revealed). */
+  resolveRowDisplay(tableId: Id, input: {
+    rowIds: Id[];
+    displayColumn?: Id;
+  }): Promise<Record<Id, string | null>>;
+  /** The atomic mixed batch: the ordered `ops[]` commit as one
+   *  transaction (either the whole batch or none); the failure stands the
+   *  first unexecutable operation's index and code and publishes no
+   *  partial envelope. The receipt's `rows` stand the CREATED rows over
+   *  the create op's order (the moved / updated / deleted rows stand the
+   *  envelope's events + the `revisions`, not the `rows`). */
+  batchRows(tableId: Id, input: {
+    ops: BatchOp[];
+  }, ctx: MutationContext): Promise<MutationReceipt<{
+    rows: RowWire[];
+  }>>;
+  /** Restore the soft-deleted rows: one atomic operation, independent of
+   *  the input id order (the rows keep their saved order); the row past
+   *  its physical GC stands the safe `not_found`. */
+  undeleteRows(tableId: Id, input: {
+    rowIds: Id[];
+  }, ctx: MutationContext): Promise<MutationReceipt<{
+    rows: RowWire[];
+  }>>;
+  /** The push channel (the consumer's transport): the bootstrap's
+   *  subscriber (the `afterSeq` replay cursor), the ordered at-least-once
+   *  per-table stream, and the unsubscribe. */
+  subscribeTable(tableId: Id, input: {
+    afterSeq: number;
+  }, observer: SubscriptionObserver): SubscriptionHandle;
+  /** The operation's status (the lost-response reconciliation): the
+   *  committed receipt, the pending stand, or the `operation_unknown`
+   *  rejection (an unknown id is never a new mutation). */
+  getOperationStatus(operationId: Id): Promise<OperationStatus>;
+}
+//#endregion
+//#region src/database/grid/use-ref-tables.d.ts
+/** The loaded ref-table data: the row ids in the row order + the row
+ *  displays (rowId → the display text) + the option colors (rowId → the
+ *  `color` column's hex — the absent value stands none). */
+interface RefTableData {
+  rowIds: string[];
+  displays: Record<string, string>;
+  colors: Record<string, string>;
+}
+/** The ref-table data keyed by the entry's key (`refEntryKey`). */
+type RefTableDataMap = Record<string, RefTableData>;
+//#endregion
+//#region src/database/filter-builder/FilterBuilder.d.ts
+interface FilterBuilderProps {
+  /** The payload being edited; null = the empty filter. */
+  value: DatabaseFilterPayload | null;
+  /** The columns (the annotation source). */
+  columns: BridgeColumn[];
+  /** The draft change (the parent keeps the draft until Apply). */
+  onChange: (payload: DatabaseFilterPayload) => void;
+  /** The ref tables' data (the enum's dict options + the row-link's row
+   *  displays — the ref value inputs render from it). */
+  refTableData?: RefTableDataMap;
+}
+declare function FilterBuilder({ value, columns, onChange, refTableData }: FilterBuilderProps): import("react").JSX.Element;
+//#endregion
+//#region src/database/filter-builder/utils.d.ts
+/** The empty filter payload (the "no filter" shape the Clear writes). */
+declare function emptyFilter(): DatabaseFilterPayload;
+/** Whether the payload is applicable: every condition that needs a value
+ *  has one (an empty value = the condition is inapplicable). */
+declare function filterIsComplete(payload: DatabaseFilterPayload | null, columns: BridgeColumn[]): boolean;
+//#endregion
+//#region src/database/use-database-table/models.d.ts
+/** One loaded row: the row id (the pk value) + the cells. */
+interface DatabaseTableRow {
+  rowId: string;
+  cells: Record<string, unknown>;
+}
+type DatabaseTablePhase = "loading" | "ready" | "broken";
+/** The public result of the hook (the grid renderer + the consumer UI read from it). */
+interface UseDatabaseTable {
+  phase: DatabaseTablePhase;
+  /** The table description (the schema); null while loading / broken. */
+  table: BridgeTableDescription | null;
+  /** The loaded rows in the row order. */
+  rows: DatabaseTableRow[];
+  /** The row's live revision (the CAS's stand — the draft session's open
+   *  pin reads it at the session's open). */
+  revisionOf(rowId: string): Revision | undefined;
+  /** The cursor of the next page; null = the last page is loaded. */
+  nextCursor: string | null;
+  /** The last operation error (the transient display); cleared on the next load. */
+  error: string | null;
+  /** The last operation's structured error code (null = no error, or the
+   *  failure carried no machine code). */
+  errorCode: BridgeErrorCode | null;
+  /** The negotiated protocol capabilities (the optional paths' gate — the
+   *  row / column restore, the CAS, the server sort stands). */
+  capabilities: readonly ProtocolCapability[];
+  insertRow(cells?: Record<string, unknown>): Promise<string>;
+  /** The row's write: the pinned revision (the cell's draft session's
+   *  open stand) selects the compare-and-swap over it; its absence stands
+   *  the live revision (the LWW's default). */
+  updateRow(rowId: string, cells: Record<string, unknown>, expectedRevision?: Revision): Promise<void>;
+  /** The batch update: ONE commit (the one bridge call + the one undo
+   *  entry — the inverse restores every touched row over the one undo,
+   *  so the multi-row clear stands back over a single undo press). */
+  updateRows(updates: Array<{
+    rowId: string;
+    cells: Record<string, unknown>;
+  }>): Promise<void>;
+  /** The mixed paste (the spec's paste batch): the visible rows' updates
+   *  (from the active row down) + the overflow's creates — ONE `batchRows`
+   *  (one transaction, one undo entry; the inverse = the updates' restore
+   *  + the created rows' deletion). The updates stand the optimistic
+   *  apply; the creates stand over the post-commit refresh. Returns the
+   *  created rows' ids. */
+  pasteRows(input: {
+    updates: Array<{
+      rowId: string;
+      cells: Record<string, unknown>;
+    }>;
+    creates: Array<Record<string, unknown>>;
+    /** The created rows' seat: the visible successor of the last updated
+     *  row (null = the table's tail). */
+    beforeRowId: string | null;
+  }): Promise<string[]>;
+  removeRow(rowId: string): Promise<void>;
+  moveRow(rowId: string, beforeRowId: string | null): Promise<void>;
+  /** Creates the column over the bridge → the bridge-assigned column id
+   *  (the view state the caller appends to the block's `columnOrder`). */
+  addColumn(column: BridgeColumn, afterColumnId?: string): Promise<string>;
+  updateColumn(columnId: string, patch: Partial<Omit<BridgeColumn, "id" | "name">>): Promise<void>;
+  deleteColumn(columnId: string): Promise<void>;
+  renameColumn(columnId: string, name: string): Promise<void>;
+  /** Renames the table (the bridge's attribute — every block over the
+   *  tableId stands the new name over the table event). */
+  renameTable(name: string): Promise<void>;
+  /** Loads the next page (the `nextCursor` continuation). */
+  loadMore(): Promise<void>;
+  /** Reloads from the bridge (the broken-state retry). */
+  retry(): void;
+  /** The forward-only undo (the inverse operation via the bridge). */
+  undo(): Promise<void>;
+  /** The forward-only redo. */
+  redo(): Promise<void>;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+//#endregion
+//#region src/database/use-database-table/use-database-table.d.ts
+/**
+ * The external-form data provider for one `tableId` (per block
+ * instance: each block has its own row store and its own undo stack, even
+ * when several blocks reference the same table). The `filter` stands the
+ * block's view state (the block's `filter` attr's payload — the contract
+ * filter's input shape).
+ */
+declare function useDatabaseTable(bridge: DatabaseBridge, tableId: string, filter?: DatabaseFilterPayload): UseDatabaseTable;
+//#endregion
+//#region src/canvas/clipboard.d.ts
+/** The one copied canvas item (the deep data; the ids stand the originals). */
+type ClipboardItem = {
+  type: "shape";
+  attrs?: ShapeAttrs;
+  geometry?: Geometry;
+} | {
+  type: "connector";
+  attrs: ConnectorAttrs;
+  geometry?: Geometry;
+} | {
+  type: "canvas-text";
+  attrs?: CanvasTextAttrs;
+  content?: BlockContent;
+  geometry?: Geometry;
+} | {
+  type: "group";
+  attrs: {
+    members: BlockId[];
+    title?: string;
+  };
+  geometry?: Geometry;
+};
+/** The deep copy of the copied canvas items (the ids stand the originals). */
+interface CanvasClipboard {
+  /** The copied items with the original ids (top-level + the containers' transitive members). */
+  entries: {
+    id: BlockId;
+    item: ClipboardItem;
+  }[];
+  /** The top-level ids (the selection order) — the paste's selection stand. */
+  ids: BlockId[];
+}
+//#endregion
+//#region src/state/models.d.ts
+/**
+ * Per-instance editor state: a projection of one docblocks-core Doc.
+ *
+ * The store is never the source of truth — writes go command -> Doc ->
+ * onChange -> applyChange. Slice references are stable across changes a
+ * slice is not involved in, so a component selecting one block re-renders
+ * only when that block actually changed.
+ */
+interface EditorState {
+  /** Block snapshots keyed by id; a block keeps its reference while its JSON is unchanged. */
+  blocks: Record<BlockId, Block>;
+  /**
+   * The entry-list block ids: the document root's children (the page
+   * sequence), or the subtree entry's derived segment (the subtree root
+   * and its deeper followers — re-derived only when the change can affect
+   * it, see `applyChange`'s invalidation: a peer or a local insert into
+   * the segment grows it without touching the subtree root itself).
+   */
+  rootChildren: BlockId[];
+  /** Document meta; replaced only when the title changed. */
+  meta: DocMeta;
+  /**
+   * The sequence-structure stamp: bumped only when the entry sequence's
+   * structure changes (a rootChildren change, or a sequence block's
+   * `indent` / `list` kind changing) — never on a text/mark change of an
+   * unchanged structure. The motion view's row derivation keys on it, so a
+   * text-only edit re-renders the edited row through its own subscription
+   * only (the origin is irrelevant — every change flows through
+   * `applyChange`).
+   */
+  seqStamp: number;
+  /** Local view selection; a separate slice so caret moves never re-render blocks. */
+  selection: Selection;
+  /**
+   * The collapsed block ids (the derived segment's rows are hidden). Local
+   * view state — never document data, no wire traffic; a separate slice,
+   * reset on remount.
+   */
+  collapsedIds: BlockId[];
+  /** Remote peers' ephemeral state; a separate slice for the same reason. */
+  presence: PresenceState[];
+  /**
+   * The canvas clipboard: the deep copy of
+   * the copied canvas items — the view state per editor (not doc data, no
+   * wire); `null` when empty. A separate slice so the copy never re-renders
+   * blocks.
+   */
+  canvasClipboard: CanvasClipboard | null;
+}
+/** Internal write functions, called by the EditorProvider subscriptions. */
+interface EditorActions {
+  /** Re-reads the blocks a doc change touched, keeping stable references for the unchanged ones. */
+  applyChange: (change: Change) => void;
+  /** Replaces the presence slice. */
+  setPresence: (peers: PresenceState[]) => void;
+  /** Replaces the selection slice. */
+  setSelection: (selection: Selection) => void;
+  /** Sets the collapsed state of one list item (view state, no doc command). */
+  setCollapsed: (id: BlockId, collapsed: boolean) => void;
+  /** Replaces the canvas clipboard slice (the copy / the clear). */
+  setCanvasClipboard: (clipboard: CanvasClipboard | null) => void;
+}
+/** The per-instance vanilla store created by `createEditorStore`. */
+type EditorStore = StoreApi<EditorState & EditorActions>;
+//#endregion
+//#region src/editor-provider/models.d.ts
+/**
+ * Resolves a sync-embed ref to the master doc the consumer holds; null when
+ * the master is unknown to the consumer (the block renders its broken state).
+ */
+type SyncEmbedResolver = (ref: SyncEmbedRef) => Doc | null;
+/** The embed sandbox policy: the iframe's `sandbox` value for a given embed
+ *  src; `null` stands no sandbox (a fully trusted embed, the old behavior). */
+type EmbedSandboxPolicy = (src: string) => string | null;
+/** The props a PDF first-page preview renderer receives (the `pdfPreview` provider prop). */
+interface PdfPreviewProps {
+  /** The block's id — the renderer stamps it on its root, like the other block renderers. */
+  id: BlockId;
+  /** The resolved blob url (the store's resolve result). */
+  url: string;
+  /** The blob's display name (absent when the store has none). */
+  name?: string;
+}
+/** A PDF first-page preview renderer: a component over a resolved `pdf` blob. */
+type PdfPreview = ComponentType<PdfPreviewProps>;
+/** A mention search result: the stable target id + the display label. */
+interface MentionEntry {
+  id: string;
+  label: string;
+}
+/**
+ * The consumer's mention search provider: the user / document catalog behind
+ * the `@` mention trigger. The two sections are separate so the picker can
+ * stand "People" and "Documents" groups; a `kind` is derived from the
+ * section on the pick (`user` / `doc`).
+ */
+interface MentionProvider {
+  /** The users matching the query (the `user` mention kind). */
+  searchUsers(query: string): Promise<MentionEntry[]>;
+  /** The documents matching the query (the `doc` mention kind). */
+  searchDocs(query: string): Promise<MentionEntry[]>;
+}
+/** The per-instance selection view; null before the mount effect ran and after unmount. */
+interface SelectionRef {
+  view: SelectionView | null;
+}
+/** The consumer's user access level: the available document modes. "viewer" is locked to the published's view (the current state is never rendered); "editor" (the default) may edit and view. Session state — not document data, never on the wire. */
+type AccessLevel = "viewer" | "editor";
+/** The document's mode (consumer-controlled view state, like the page/canvas `view`): "edit" (the default) is the live document editable; "view" is the live document read-only (the current state, still syncing); "published" is the `publishedDoc`'s snapshot read-only (static). */
+type EditorMode = "edit" | "view" | "published";
+/** Per-instance editor context: the store, the doc, the selection handle, and the customization values. */
+interface EditorContextValue {
+  store: EditorStore;
+  doc: Doc;
+  selection: SelectionRef;
+  /** Consumer renderers by block type; empty when none were supplied. */
+  renderers: BlockRendererMap;
+  /** The effective blob bridge (the consumer's store, the legacy resolver
+   *  wrapped, or the shared default in-memory store) — always present. */
+  blobStore: BlobStore;
+  /** The effective database bridge (the consumer's implementation);
+   *  undefined when none was supplied — the external-form database blocks
+   *  render the disconnected placeholder. */
+  databaseBridge: DatabaseBridge | undefined;
+  /** The sync-embed master-doc resolver; null when none was supplied. */
+  syncEmbedResolver: SyncEmbedResolver | null;
+  /** The consumer's PDF first-page preview renderer; null when none was supplied (the native iframe stands). */
+  pdfPreview: PdfPreview | null;
+  /** The consumer's mention search provider; null when none was supplied (`@` stays plain text). */
+  mentionProvider: MentionProvider | null;
+  /** The effective embed sandbox policy (the consumer's, or the safe default) — always present. */
+  embedSandbox: EmbedSandboxPolicy;
+  /** The entry-list root: the document root by default, a subtree block otherwise. */
+  rootBlockId: BlockId;
+  /** The enclosing providers' doc ids, outermost first (the sync-embed cycle visited-set). */
+  ancestorDocIds: readonly string[];
+  /** The number of enclosing editor renders (the sync-embed cycle depth bound). */
+  embedDepth: number;
+  /** The empty-block hint text (the default points at the slash command palette). */
+  commandPalettePlaceholder: string;
+  /** The consumer's access level (the effective stand: the own prop, else the enclosing one, else "editor"). */
+  accessLevel: AccessLevel;
+  /** The effective document mode (resolved: a viewer stands "published" over any stand; a nested provider without its own `mode` inherits the enclosing one). */
+  mode: EditorMode;
+  /** True over the non-edit modes ("view" / "published"): every editing surface gates off (the read-only stand). */
+  viewMode: boolean;
+}
+interface EditorProviderProps {
+  /**
+   * The headless document to render and edit; must not change after mount.
+   * Required over the editor's stand. Over the `viewer`'s stand the doc IS
+   * the published snapshot — the consumer passes only the stand the reader
+   * may see (the live document never reaches the reader's browser); an
+   * absent stand over the viewer renders the not-published placeholder.
+   */
+  doc?: Doc;
+  /**
+   * Optional user access level: "viewer" locks the render to the
+   * published's view (the `mode`'s stand is ignored — the current state is
+   * never rendered for a reader); "editor" (the default) may edit and
+   * view. Over the viewer's stand the `doc` is the published snapshot and
+   * the `publishedDoc` prop is not consulted (the doc IS the snapshot).
+   * Session state supplied by the consumer — never document data.
+   */
+  accessLevel?: AccessLevel;
+  /**
+   * Optional document mode (consumer-controlled, like the page/canvas
+   * `view`): "edit" (the default) renders the live document editable,
+   * "view" renders it read-only (the current state, the doc keeps
+   * syncing), "published" renders the `publishedDoc`'s snapshot read-only.
+   * A viewer stands "published" over every stand. A nested provider
+   * without its own `mode` inherits the enclosing one.
+   */
+  mode?: EditorMode;
+  /**
+   * Optional published snapshot (a hydrated `Doc`, the consumer's
+   * `loadDoc` / `fromJSON` over its own stored state): rendered
+   * read-only over the "published" mode (a static stand — no sync
+   * transport). Must not change after mount (like `doc`): a new
+   * snapshot is a consumer remount over a `key` change.
+   */
+  publishedDoc?: Doc | null;
+  /** Optional sync transport for presence (awareness); the doc's own changes are always tracked. */
+  provider?: SyncProvider;
+  /**
+   * Optional per-instance block renderers: a consumer renderer for a type
+   * replaces the built-in one (view-layer customization). Replacing a
+   * text-editable type replaces the whole block view, including its
+   * editing affordance; a renderer that needs editing drives the core
+   * commands through the hooks. Pass a stable reference for the map
+   * (module-level or memoized): it is read into the provider context per
+   * render, so a fresh inline object would churn the context value and
+   * re-render every context consumer.
+   */
+  blockRenderers?: BlockRendererMap;
+  /**
+   * Optional resolver of an image's blob key to an img src; without it the
+   * image renders a placeholder.
+   *
+   * Like `blockRenderers`, the value is read per render into the provider
+   * context: pass a stable reference (module-level or memoized) so the
+   * context does not churn on every provider render.
+   */
+  blobResolver?: (key: string) => string;
+  /**
+   * Optional blob bridge: resolves a blob key to its displayable url and
+   * metadata, and uploads a file to a new key (the slash Image path and
+   * the future attachment blocks write the key only after the upload
+   * resolved). Without it — and without `blobResolver` — the editor uses
+   * the shared default in-memory store (uploads stand data urls for the
+   * JS session; a page reload clears them), so the upload path works
+   * out of the box.
+   *
+   * Like `blobResolver`, the value is read per render into the provider
+   * context: pass a stable reference. A nested provider that supplies
+   * none inherits the enclosing store.
+   */
+  blobStore?: BlobStore;
+  /**
+   * Optional database bridge: the consumer's implementation of the table
+   * operations behind the external-form database blocks (the document
+   * keeps only the `tableId` reference; the schema and the rows live in
+   * the consumer's database). Without it the external-form blocks render
+   * the disconnected placeholder (the inline form stands unchanged — its
+   * data is the document's own).
+   *
+   * Like `blobStore`, the value is read per render into the provider
+   * context: pass a stable reference. A nested provider that supplies
+   * none inherits the enclosing bridge.
+   */
+  databaseBridge?: DatabaseBridge;
+  /**
+   * Optional resolver of a sync-embed's ref to the master Doc (the consumer
+   * holds the master in its own store); without it the built-in renderer
+   * renders the broken state for every sync-embed.
+   *
+   * The value is read per render into the provider context (like
+   * `blockRenderers`): pass a stable reference. A provider nested inside
+   * another inherits the enclosing resolver when it supplies none (a
+   * sync-embed inside a rendered master must resolve too).
+   */
+  syncEmbedResolver?: SyncEmbedResolver;
+  /**
+   * Optional PDF first-page preview renderer: a component that renders a
+   * `pdf`-subtype image block's resolved blob as a client-side first-page
+   * preview (the `./pdf` subpath provides one over pdfjs-dist, an optional
+   * peer). Without it the block stands the native iframe viewer.
+   *
+   * Like `blockRenderers`, the value is read per render into the provider
+   * context: pass a stable reference (the component is module-level). A
+   * nested provider that supplies none inherits the enclosing one.
+   */
+  pdfPreview?: PdfPreview;
+  /**
+   * Optional mention search provider: the user / document catalog behind the
+   * `@` mention trigger in page text blocks. Without it the `@` stays plain
+   * text (no picker). Like `pdfPreview`, the value is read per render into
+   * the provider context: pass a stable reference. A nested provider that
+   * supplies none inherits the enclosing one.
+   */
+  mentionProvider?: MentionProvider;
+  /**
+   * Optional embed sandbox policy: the iframe's `sandbox` value for a given
+   * embed src; `null` stands no sandbox (a fully trusted embed). Without it
+   * the safe default applies (`DEFAULT_EMBED_SANDBOX` — interactive but no
+   * `allow-same-origin`, so the embedded content cannot read the parent's DOM
+   * / state). Grant `allow-same-origin` only for trusted origins.
+   *
+   * Like `pdfPreview`, the value is read per render into the provider
+   * context: pass a stable reference. A nested provider that supplies none
+   * inherits the enclosing policy.
+   */
+  embedSandbox?: EmbedSandboxPolicy;
+  /**
+   * Optional entry-list root: render the entry list of this block instead
+   * of the document root (the subtree view — the block itself plus its own
+   * subtree). Defaults to the document root: behavior unchanged.
+   *
+   * Like `doc`, the value must not change after mount.
+   */
+  rootBlockId?: BlockId;
+  /**
+   * The command palette placeholder hint text, shown while the caret sits
+   * in a text block with no content; defaults to "Type '/' for commands"
+   * (`COMMAND_PALETTE_PLACEHOLDER`). A nested provider that supplies none
+   * inherits the enclosing value, like the resolvers.
+   */
+  commandPalettePlaceholder?: string;
+  children: ReactNode;
+}
+//#endregion
+//#region src/editor-provider/EditorProvider.d.ts
+/**
+ * The provider's entry: resolves the viewer's top-level stand before the
+ * stand's hooks (the security stand — the reader's browser never holds the
+ * live document: over the `viewer`'s level the `doc` is the published
+ * snapshot, the only stand the consumer passes, and an absent stand stands
+ * the not-published placeholder — the document was never published). The
+ * editor's stand requires the doc (an explicit throw over the absent
+ * stand).
+ */
+declare function EditorProvider(props: EditorProviderProps): import("react").JSX.Element;
+//#endregion
+//#region src/editor-provider/constants.d.ts
+/**
+ * The safe embed sandbox (the default when no `embedSandbox` policy is
+ * supplied): the embedded content stands an opaque origin (no
+ * `allow-same-origin`), so it cannot read the parent's DOM, cookies, or state;
+ * scripts, forms, and popups still run, so interactive embeds keep working.
+ * Grant `allow-same-origin` — and `allow-scripts` together with it — only for
+ * trusted origins via the `embedSandbox` policy: that combination lets the
+ * frame lift its own sandbox.
+ */
+declare const DEFAULT_EMBED_SANDBOX = "allow-scripts allow-forms allow-popups";
+//#endregion
+//#region src/editor-provider/context.d.ts
+/** Read the per-instance editor context; throws outside an EditorProvider. */
+declare function useEditorContext(): EditorContextValue;
+//#endregion
+export { TableEnvelopeBase as $, DomainEvent as A, ProtocolCapability as B, BridgeColumnAnnotation as C, CellValueParse as D, CellMap as E, MutationContext as F, Revision as G, ProtocolLimits as H, MutationReceipt as I, SortInput as J, RowPage as K, OperationStatus as L, FilterInput as M, Id as N, Column as O, IsoInstant as P, TableDescription as Q, PageQuery as R, BridgeColumn as S, BridgeValueInput as T, QueryOperator as U, ProtocolDescriptor as V, QuerySemantics as W, SubscriptionObserver as X, SubscriptionHandle as Y, SubscriptionStatus as Z, UseDatabaseTable as _, EditorContextValue as a, BridgeErrorCode as at, FilterBuilder as b, EmbedSandboxPolicy as c, toBridgeError as ct, PdfPreview as d, BlobStore as dt, TableEvent as et, PdfPreviewProps as f, BlobSubtype as ft, DatabaseTableRow as g, DatabaseTablePhase as h, AccessLevel as i, BridgeError as it, FilterConditionInput as j, DatabaseBridge as k, MentionEntry as l, BlobMeta as lt, useDatabaseTable as m, createMemoryBlobStore as mt, DEFAULT_EMBED_SANDBOX as n, TableSnapshot as nt, EditorMode as o, isBridgeError as ot, SyncEmbedResolver as p, blobSubtypeOf as pt, RowWire as q, EditorProvider as r, BRIDGE_ERROR_CODES as rt, EditorProviderProps as s, isBridgeErrorCode as st, useEditorContext as t, TableRef as tt, MentionProvider as u, BlobRef as ut, emptyFilter as v, BridgeTableDescription as w, BatchOp as x, filterIsComplete as y, PageSnapshot as z };