grist-widget-sdk 0.2.0

package/dist/emulator.cjs

@@ -0,0 +1,1796 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/emulator/index.ts
+var emulator_exports = {};
+__export(emulator_exports, {
+  EmulatorActionError: () => EmulatorActionError,
+  createGristEmulator: () => createGristEmulator,
+  enrichEmulatorColumnMetadata: () => enrichEmulatorColumnMetadata,
+  parseDocument: () => parseDocument,
+  presets: () => presets,
+  resolveMappings: () => resolveMappings,
+  safeParseDocument: () => safeParseDocument
+});
+module.exports = __toCommonJS(emulator_exports);
+
+// src/emulator/api/command-api.ts
+function createCommandApiImpl(bus) {
+  return {
+    async run(name) {
+      bus.emit({ type: "user-action", action: ["RunCommand", name] });
+    }
+  };
+}
+
+// src/emulator/core/mappings.ts
+function resolveMappings(state) {
+  if (state.selection.mappings !== void 0 && state.selection.mappings !== null) {
+    return state.selection.mappings;
+  }
+  return null;
+}
+
+// src/emulator/api/custom-section-api.ts
+function createCustomSectionApiImpl(state, bus) {
+  return {
+    async configure(settings) {
+      const config = {
+        requiredAccess: settings.requiredAccess,
+        columns: settings.columns,
+        allowSelectBy: settings.allowSelectBy,
+        hasCustomOptions: settings.hasCustomOptions
+      };
+      state.configuration = config;
+      bus.emit({ type: "ready", configuration: config });
+      bus.emit({ type: "mappings-change", mappings: resolveMappings(state) });
+    },
+    async mappings() {
+      return resolveMappings(state);
+    }
+  };
+}
+
+// src/emulator/api/grist-api.ts
+function createGristApiImpl() {
+  return {
+    async ping() {
+      return "pong";
+    }
+  };
+}
+
+// src/sdk/helpers/grist-value-codec.ts
+function coerceGristDocApiRefRowId(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (!Array.isArray(value) || value.length < 2) return void 0;
+  const tag = value[0];
+  if (tag === "R" && typeof value[2] === "number" && Number.isFinite(value[2])) return value[2];
+  if (tag === "r" && typeof value[1] === "number" && Number.isFinite(value[1])) return value[1];
+  return void 0;
+}
+
+// src/sdk/helpers/grist-safe-parse.ts
+var import_zod = require("zod");
+var gristSafeRefValueSchema = import_zod.z.object({
+  rowId: import_zod.z.number(),
+  display: import_zod.z.string().nullable().optional()
+});
+var gristSafeRefListValueSchema = import_zod.z.object({
+  rowIds: import_zod.z.array(import_zod.z.number()),
+  displays: import_zod.z.array(import_zod.z.string()).optional()
+});
+var gristCellValueSchema = import_zod.z.union([
+  import_zod.z.null(),
+  import_zod.z.string(),
+  import_zod.z.number(),
+  import_zod.z.boolean(),
+  import_zod.z.date(),
+  import_zod.z.array(import_zod.z.unknown()),
+  gristSafeRefValueSchema,
+  gristSafeRefListValueSchema
+]);
+function inferDisplayHelpersByRef(columns) {
+  const out = {};
+  const helperColumns = Object.entries(columns).filter(
+    ([colId]) => colId.startsWith("gristHelper_")
+  );
+  const usedHelpers = /* @__PURE__ */ new Set();
+  const colRefToColId = /* @__PURE__ */ new Map();
+  for (const [colId, col] of Object.entries(columns)) {
+    if (typeof col?.colRef === "number" && Number.isFinite(col.colRef)) {
+      colRefToColId.set(col.colRef, colId);
+    }
+  }
+  for (const [colId, col] of Object.entries(columns)) {
+    const type = col?.type;
+    if (typeof type !== "string" || !type.startsWith("Ref:") && !type.startsWith("RefList:")) {
+      continue;
+    }
+    if (typeof col.displayColRef === "number" && Number.isFinite(col.displayColRef)) {
+      const helperColId = colRefToColId.get(col.displayColRef);
+      if (helperColId) {
+        out[colId] = helperColId;
+        usedHelpers.add(helperColId);
+        continue;
+      }
+    }
+    const match = helperColumns.find(([, helper]) => {
+      const formula = helper?.formula;
+      return typeof formula === "string" && (formula.includes(`$${colId}.`) || formula.includes(`$${colId}`));
+    });
+    if (match) {
+      out[colId] = match[0];
+      usedHelpers.add(match[0]);
+    }
+  }
+  const unresolvedRefs = Object.entries(columns).filter(([colId, col]) => {
+    const type = col?.type;
+    return !out[colId] && typeof type === "string" && (type.startsWith("Ref:") || type.startsWith("RefList:"));
+  }).sort((a, b) => (a[1]?.parentPos ?? Number.MAX_SAFE_INTEGER) - (b[1]?.parentPos ?? Number.MAX_SAFE_INTEGER));
+  const helperByPos = helperColumns.filter(([helperId]) => !usedHelpers.has(helperId)).sort((a, b) => (a[1]?.parentPos ?? Number.MAX_SAFE_INTEGER) - (b[1]?.parentPos ?? Number.MAX_SAFE_INTEGER));
+  for (const [refId, refCol] of unresolvedRefs) {
+    const refPos = refCol?.parentPos ?? Number.MAX_SAFE_INTEGER;
+    const candidate = helperByPos.find(([, helperCol]) => {
+      const helperPos = helperCol?.parentPos ?? Number.MAX_SAFE_INTEGER;
+      return helperPos > refPos;
+    });
+    if (!candidate) continue;
+    out[refId] = candidate[0];
+    usedHelpers.add(candidate[0]);
+  }
+  for (const [refId] of unresolvedRefs) {
+    if (out[refId]) continue;
+    const candidate = helperByPos.find(([helperId]) => !usedHelpers.has(helperId));
+    if (!candidate) continue;
+    out[refId] = candidate[0];
+    usedHelpers.add(candidate[0]);
+  }
+  return out;
+}
+
+// src/sdk/helpers/replica-normalize.ts
+function normalizeReplicaTableInput(table) {
+  return { ...table, rows: table.rows ?? [] };
+}
+function normalizeReplicaDocumentInput(doc) {
+  return {
+    ...doc,
+    tables: Object.fromEntries(
+      Object.entries(doc.tables).map(([tableId, t]) => [tableId, normalizeReplicaTableInput(t)])
+    )
+  };
+}
+
+// src/emulator/core/document.ts
+var SYSTEM_COLUMN = "id";
+var EMULATOR_JS_FORMULA_PLACEHOLDER = "(emulator JavaScript formula)";
+function enrichEmulatorColumnMetadata(col) {
+  const originalTrimmed = col.formula?.trim() ?? "";
+  const explicitInferred = col.inferredFormula?.trim() ?? "";
+  if (col.formulaFn) {
+    const inferredFormula = explicitInferred || originalTrimmed || EMULATOR_JS_FORMULA_PLACEHOLDER;
+    return {
+      ...col,
+      ...originalTrimmed ? { formula: col.formula } : {},
+      inferredFormula
+    };
+  }
+  if (explicitInferred || originalTrimmed) {
+    return {
+      ...col,
+      inferredFormula: explicitInferred || originalTrimmed || void 0
+    };
+  }
+  return col;
+}
+function sortEmulatorColumnsByParentPos(columns) {
+  const entries = Object.entries(columns);
+  entries.sort(([ka, a], [kb, b]) => {
+    const pa = a.parentPos;
+    const pb = b.parentPos;
+    if (pa !== void 0 && pb !== void 0 && pa !== pb) return pa - pb;
+    if (pa !== void 0 && pb === void 0) return -1;
+    if (pa === void 0 && pb !== void 0) return 1;
+    return ka.localeCompare(kb);
+  });
+  return Object.fromEntries(entries);
+}
+function inferColumnsFromRows(rows) {
+  const columns = {};
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (key === SYSTEM_COLUMN) continue;
+      if (!columns[key]) columns[key] = inferColumnType(row[key]);
+    }
+  }
+  return columns;
+}
+function inferColumnType(sample) {
+  switch (typeof sample) {
+    case "number":
+      return { type: "Numeric" };
+    case "boolean":
+      return { type: "Bool" };
+    case "string":
+      return { type: "Text" };
+    default:
+      return { type: "Any" };
+  }
+}
+function buildTable(tableId, input) {
+  const rows = input.rows ?? [];
+  const inferred = inferColumnsFromRows(rows);
+  const merged = {};
+  for (const [colId, col] of Object.entries({ ...inferred, ...input.columns ?? {} })) {
+    merged[colId] = enrichEmulatorColumnMetadata(col);
+  }
+  const columns = sortEmulatorColumnsByParentPos(merged);
+  return {
+    tableId,
+    label: input.label,
+    columns,
+    rows: rows.map((row) => ({ ...row }))
+  };
+}
+function createDocument(input) {
+  if (!input.tables || Object.keys(input.tables).length === 0) {
+    throw new Error("createDocument: at least one table is required");
+  }
+  const normalized = normalizeReplicaDocumentInput(input);
+  const tables = /* @__PURE__ */ new Map();
+  for (const [tableId, tableInput] of Object.entries(normalized.tables)) {
+    tables.set(tableId, buildTable(tableId, tableInput));
+  }
+  const firstTableId = tables.keys().next().value;
+  const requestedTableId = normalized.selection?.tableId;
+  const selectedTableId = requestedTableId && tables.has(requestedTableId) ? requestedTableId : firstTableId;
+  const selectedTable = tables.get(selectedTableId);
+  const fallbackRowId = typeof selectedTable.rows[0]?.id === "number" ? selectedTable.rows[0].id : null;
+  const selection = {
+    tableId: selectedTableId,
+    rowId: normalized.selection?.rowId ?? fallbackRowId,
+    mappings: normalized.selection?.mappings,
+    cursor: normalized.selection?.cursor
+  };
+  return {
+    docName: normalized.docName ?? "Untitled emulator document",
+    tables,
+    selection,
+    widgetOptions: { ...normalized.widgetOptions ?? {} },
+    widgetInteraction: { ...normalized.widgetInteraction ?? {} },
+    configuration: normalized.configuration ?? null,
+    accessToken: normalized.accessToken ?? null
+  };
+}
+function getTable(state, tableId) {
+  const table = state.tables.get(tableId);
+  if (!table) throw new Error(`Unknown table: ${tableId}`);
+  return table;
+}
+function getSelectedTable(state) {
+  return getTable(state, state.selection.tableId);
+}
+function nextRowId(table) {
+  let max = 0;
+  for (const row of table.rows) {
+    if (typeof row.id === "number" && row.id > max) max = row.id;
+  }
+  return max + 1;
+}
+function findRow(table, rowId) {
+  return table.rows.find((r) => r.id === rowId);
+}
+function findRowIndex(table, rowId) {
+  return table.rows.findIndex((r) => r.id === rowId);
+}
+function evaluateRowFormulas(state, table, row) {
+  for (const [colId, col] of Object.entries(table.columns)) {
+    if (col.formulaFn) {
+      try {
+        row[colId] = col.formulaFn(row, { table, document: state });
+      } catch (err) {
+        row[colId] = formulaError(err);
+      }
+    }
+  }
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractRefListIdsFromWire(raw) {
+  if (raw == null) return [];
+  if (!Array.isArray(raw)) return [];
+  const items = raw[0] === "L" ? raw.slice(1) : raw;
+  const out = [];
+  for (const item of items) {
+    if (typeof item === "number" && Number.isFinite(item) && item > 0) {
+      out.push(Math.trunc(item));
+      continue;
+    }
+    if (item && typeof item === "object" && "rowId" in item) {
+      const r = item.rowId;
+      if (typeof r === "number" && Number.isFinite(r) && r > 0) {
+        out.push(Math.trunc(r));
+        continue;
+      }
+    }
+    const t = coerceGristDocApiRefRowId(item);
+    if (t !== void 0 && t > 0) out.push(Math.trunc(t));
+  }
+  return Array.from(new Set(out));
+}
+function fieldFromRefListHelperFormula(formula, refColId) {
+  if (!formula) return null;
+  const re = new RegExp(`\\$${escapeRegExp(refColId)}\\.([A-Za-z_]\\w*)`);
+  const m = formula.match(re);
+  return m?.[1] ?? null;
+}
+function firstTextLikeColumnId(columns) {
+  let best = null;
+  for (const [colId, col] of Object.entries(columns)) {
+    if (colId === "id" || colId.startsWith("gristHelper_")) continue;
+    const t = col.type;
+    if (t !== "Text" && t !== "Choice") continue;
+    const pos = col.parentPos ?? 99999;
+    if (!best || pos < best.pos) best = { id: colId, pos };
+  }
+  return best?.id ?? null;
+}
+function formatLabelFromCell(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value.trim();
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value) && value[0] === "E") return "";
+  if (typeof value === "object" && value && "__ref" in value) {
+    const r = value.rowId;
+    return typeof r === "number" && Number.isFinite(r) ? String(r) : "";
+  }
+  return "";
+}
+function syncRefListDisplayHelpers(state, table, row) {
+  const displayHelpersByRef = inferDisplayHelpersByRef(table.columns);
+  for (const [colId, col] of Object.entries(table.columns)) {
+    const type = col.type;
+    if (typeof type !== "string" || !type.startsWith("RefList:")) continue;
+    const helperColId = displayHelpersByRef[colId];
+    if (!helperColId) continue;
+    const helperMeta = table.columns[helperColId];
+    if (!helperMeta || helperMeta.formulaFn) continue;
+    const targetTableId = type.slice("RefList:".length);
+    const targetTable = state.tables.get(targetTableId);
+    if (!targetTable) continue;
+    const ids = extractRefListIdsFromWire(row[colId]);
+    if (ids.length === 0) {
+      row[helperColId] = [];
+      continue;
+    }
+    const fieldId = fieldFromRefListHelperFormula(helperMeta.formula, colId) ?? firstTextLikeColumnId(targetTable.columns);
+    const labels = ids.map((rid) => {
+      if (!fieldId) return String(rid);
+      const trow = findRow(targetTable, rid);
+      if (!trow) return String(rid);
+      const lbl = formatLabelFromCell(trow[fieldId]);
+      return lbl !== "" ? lbl : String(rid);
+    });
+    row[helperColId] = labels;
+  }
+}
+function formulaError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return ["E", "Error", message];
+}
+function synthesizeTablesMeta(state) {
+  const ids = [];
+  const tableIds = [];
+  const labels = [];
+  let nextId = 1;
+  for (const [tableId, table] of state.tables.entries()) {
+    ids.push(nextId);
+    tableIds.push(tableId);
+    labels.push(table.label ?? null);
+    nextId += 1;
+  }
+  return {
+    id: ids,
+    tableId: tableIds,
+    // Optional human-readable label; real Grist keeps more fields, but these
+    // are sufficient for `buildReplicaDocumentFromDocApi` to resolve table ids.
+    label: labels
+  };
+}
+function synthesizeTablesColumnMeta(state) {
+  const parentIds = [];
+  const colIds = [];
+  const columnIds = [];
+  const types = [];
+  const labels = [];
+  const parentPos = [];
+  const isFormula = [];
+  const formulas = [];
+  const descriptions = [];
+  const widgetOptions = [];
+  const displayCol = [];
+  const visibleCol = [];
+  const tableIdToInternalId = /* @__PURE__ */ new Map();
+  {
+    let nextId = 1;
+    for (const [tableId] of state.tables.entries()) {
+      tableIdToInternalId.set(tableId, nextId);
+      nextId += 1;
+    }
+  }
+  for (const [tableId, table] of state.tables.entries()) {
+    const parentInternalId = tableIdToInternalId.get(tableId);
+    if (parentInternalId === void 0) continue;
+    for (const [colId, col] of Object.entries(table.columns)) {
+      parentIds.push(parentInternalId);
+      colIds.push(colId);
+      const ref = typeof col.colRef === "number" ? col.colRef : columnIds.length + 1;
+      columnIds.push(ref);
+      types.push(col.type ?? null);
+      labels.push(col.label ?? null);
+      parentPos.push(col.parentPos ?? null);
+      isFormula.push(Boolean(col.isFormula));
+      const formula = typeof col.formula === "string" ? col.formula : null;
+      formulas.push(formula);
+      descriptions.push(col.description ?? null);
+      widgetOptions.push(col.widgetOptions ?? null);
+      displayCol.push(typeof col.displayColRef === "number" ? col.displayColRef : null);
+      visibleCol.push(typeof col.visibleColRef === "number" ? col.visibleColRef : null);
+    }
+  }
+  return {
+    parentId: parentIds,
+    colId: colIds,
+    id: columnIds,
+    type: types,
+    label: labels,
+    parentPos,
+    isFormula,
+    formula: formulas,
+    description: descriptions,
+    // Also expose legacy `descr` for robustness.
+    descr: descriptions,
+    widgetOptions,
+    displayCol,
+    visibleCol
+  };
+}
+
+// src/emulator/core/action-engine.ts
+var EmulatorActionError = class extends Error {
+  constructor(action, message) {
+    super(message);
+    this.action = action;
+    this.name = "EmulatorActionError";
+  }
+};
+function applyUserActions(state, bus, actions) {
+  const retValues = [];
+  const changed = /* @__PURE__ */ new Set();
+  for (const action of actions) {
+    bus.emit({ type: "user-action", action });
+    const ret = applySingle(state, action, changed);
+    retValues.push(ret);
+  }
+  for (const tableId of changed) {
+    bus.emit({ type: "data-change", tableId });
+  }
+  return { retValues, changedTableIds: [...changed] };
+}
+function applySingle(state, action, changed) {
+  const [name, ...args] = action;
+  switch (name) {
+    case "AddRecord":
+      return addRecord(state, args, changed);
+    case "BulkAddRecord":
+      return bulkAddRecord(state, args, changed);
+    case "UpdateRecord":
+      return updateRecord(state, args, changed);
+    case "BulkUpdateRecord":
+      return bulkUpdateRecord(state, args, changed);
+    case "RemoveRecord":
+      return removeRecord(state, args, changed);
+    case "BulkRemoveRecord":
+      return bulkRemoveRecord(state, args, changed);
+    case "AddColumn":
+      return addColumn(state, args);
+    case "AddVisibleColumn":
+      return addColumn(state, args);
+    case "RemoveColumn":
+      return removeColumn(state, args, changed);
+    case "RenameColumn":
+      return renameColumn(state, args, changed);
+    case "ModifyColumn":
+      return modifyColumn(state, args, changed);
+    case "AddTable":
+      return addTable(state, args);
+    case "RemoveTable":
+      return removeTable(state, args);
+    case "RenameTable":
+      return renameTable(state, args);
+    default:
+      throw new EmulatorActionError(action, `Unsupported user action: ${String(name)}`);
+  }
+}
+function addRecord(state, [tableId, rowId, values], changed) {
+  const table = getTable(state, requireString(tableId, "AddRecord.tableId"));
+  const id = typeof rowId === "number" ? rowId : nextRowId(table);
+  const normalizedValues = normalizeValuesForTable(
+    table,
+    values ?? {}
+  );
+  const row = { id, ...normalizedValues };
+  ensureColumns(table, normalizedValues);
+  evaluateRowFormulas(state, table, row);
+  syncRefListDisplayHelpers(state, table, row);
+  table.rows.push(row);
+  changed.add(table.tableId);
+  return id;
+}
+function bulkAddRecord(state, [tableId, rowIds, columnar], changed) {
+  const table = getTable(state, requireString(tableId, "BulkAddRecord.tableId"));
+  const cols = normalizeColumnarForTable(
+    table,
+    columnar ?? {}
+  );
+  const ids = Array.isArray(rowIds) ? rowIds : [];
+  const length = ids.length || lengthOf(cols);
+  const out = [];
+  ensureColumns(table, cols, true);
+  for (let i = 0; i < length; i++) {
+    const id = typeof ids[i] === "number" ? ids[i] : nextRowId(table);
+    const row = { id };
+    for (const colId of Object.keys(cols)) row[colId] = cols[colId][i];
+    evaluateRowFormulas(state, table, row);
+    syncRefListDisplayHelpers(state, table, row);
+    table.rows.push(row);
+    out.push(id);
+  }
+  changed.add(table.tableId);
+  return out;
+}
+function updateRecord(state, [tableId, rowId, values], changed) {
+  const table = getTable(state, requireString(tableId, "UpdateRecord.tableId"));
+  const id = requireNumber(rowId, "UpdateRecord.rowId");
+  const row = findRow(table, id);
+  if (!row) throw new EmulatorActionError(["UpdateRecord", tableId, rowId, values], `Row ${id} not found in ${table.tableId}`);
+  const normalizedValues = normalizeValuesForTable(
+    table,
+    values ?? {}
+  );
+  ensureColumns(table, normalizedValues);
+  Object.assign(row, normalizedValues);
+  evaluateRowFormulas(state, table, row);
+  syncRefListDisplayHelpers(state, table, row);
+  changed.add(table.tableId);
+  return null;
+}
+function bulkUpdateRecord(state, [tableId, rowIds, columnar], changed) {
+  const table = getTable(state, requireString(tableId, "BulkUpdateRecord.tableId"));
+  const ids = rowIds;
+  const cols = normalizeColumnarForTable(
+    table,
+    columnar ?? {}
+  );
+  ensureColumns(table, cols, true);
+  ids.forEach((id, idx) => {
+    const row = findRow(table, id);
+    if (!row) throw new EmulatorActionError(["BulkUpdateRecord", tableId, ids, cols], `Row ${id} not found in ${table.tableId}`);
+    for (const colId of Object.keys(cols)) row[colId] = cols[colId][idx];
+    evaluateRowFormulas(state, table, row);
+    syncRefListDisplayHelpers(state, table, row);
+  });
+  changed.add(table.tableId);
+  return null;
+}
+function removeRecord(state, [tableId, rowId], changed) {
+  const table = getTable(state, requireString(tableId, "RemoveRecord.tableId"));
+  const id = requireNumber(rowId, "RemoveRecord.rowId");
+  const idx = findRowIndex(table, id);
+  if (idx >= 0) table.rows.splice(idx, 1);
+  if (state.selection.tableId === table.tableId && state.selection.rowId === id) {
+    state.selection.rowId = table.rows[0]?.id ?? null;
+  }
+  changed.add(table.tableId);
+  return null;
+}
+function bulkRemoveRecord(state, [tableId, rowIds], changed) {
+  const table = getTable(state, requireString(tableId, "BulkRemoveRecord.tableId"));
+  const ids = new Set(rowIds);
+  table.rows = table.rows.filter((r) => !ids.has(r.id));
+  if (state.selection.tableId === table.tableId && typeof state.selection.rowId === "number" && ids.has(state.selection.rowId)) {
+    state.selection.rowId = table.rows[0]?.id ?? null;
+  }
+  changed.add(table.tableId);
+  return null;
+}
+function addColumn(state, [tableId, colId, info]) {
+  const table = getTable(state, requireString(tableId, "AddColumn.tableId"));
+  const col = requireString(colId, "AddColumn.colId");
+  if (table.columns[col]) throw new EmulatorActionError(["AddColumn", tableId, colId], `Column ${col} already exists`);
+  table.columns[col] = info ?? {};
+  for (const row of table.rows) {
+    if (!(col in row)) row[col] = null;
+  }
+  return null;
+}
+function removeColumn(state, [tableId, colId], changed) {
+  const table = getTable(state, requireString(tableId, "RemoveColumn.tableId"));
+  const col = requireString(colId, "RemoveColumn.colId");
+  delete table.columns[col];
+  for (const row of table.rows) delete row[col];
+  changed.add(table.tableId);
+  return null;
+}
+function renameColumn(state, [tableId, colId, newColId], changed) {
+  const table = getTable(state, requireString(tableId, "RenameColumn.tableId"));
+  const from = requireString(colId, "RenameColumn.colId");
+  const to = requireString(newColId, "RenameColumn.newColId");
+  if (!table.columns[from]) throw new EmulatorActionError(["RenameColumn", tableId, from, to], `Column ${from} not found`);
+  if (from === to) return null;
+  table.columns[to] = table.columns[from];
+  delete table.columns[from];
+  for (const row of table.rows) {
+    if (from in row) {
+      row[to] = row[from];
+      delete row[from];
+    }
+  }
+  changed.add(table.tableId);
+  return null;
+}
+function modifyColumn(state, [tableId, colId, info], changed) {
+  const table = getTable(state, requireString(tableId, "ModifyColumn.tableId"));
+  const col = requireString(colId, "ModifyColumn.colId");
+  if (!table.columns[col]) throw new EmulatorActionError(["ModifyColumn", tableId, colId], `Column ${col} not found`);
+  table.columns[col] = { ...table.columns[col], ...info };
+  changed.add(table.tableId);
+  return null;
+}
+function addTable(state, [tableId, columns]) {
+  const id = requireString(tableId, "AddTable.tableId");
+  if (state.tables.has(id)) throw new EmulatorActionError(["AddTable", tableId], `Table ${id} already exists`);
+  const cols = {};
+  for (const c of columns ?? []) {
+    cols[c.id] = { ...c };
+  }
+  state.tables.set(id, { tableId: id, columns: cols, rows: [] });
+  return id;
+}
+function removeTable(state, [tableId]) {
+  const id = requireString(tableId, "RemoveTable.tableId");
+  state.tables.delete(id);
+  if (state.selection.tableId === id) {
+    const fallback = state.tables.keys().next().value;
+    if (fallback) {
+      state.selection.tableId = fallback;
+      state.selection.rowId = null;
+    }
+  }
+  return null;
+}
+function renameTable(state, [from, to]) {
+  const fromId = requireString(from, "RenameTable.from");
+  const toId = requireString(to, "RenameTable.to");
+  const table = state.tables.get(fromId);
+  if (!table) throw new EmulatorActionError(["RenameTable", fromId], `Table ${fromId} not found`);
+  state.tables.delete(fromId);
+  table.tableId = toId;
+  state.tables.set(toId, table);
+  if (state.selection.tableId === fromId) state.selection.tableId = toId;
+  return null;
+}
+function ensureColumns(table, values, bulk = false) {
+  for (const col of Object.keys(values)) {
+    if (!table.columns[col]) {
+      const sample = bulk ? values[col]?.[0] : values[col];
+      table.columns[col] = inferType(sample);
+    }
+  }
+}
+function inferType(sample) {
+  switch (typeof sample) {
+    case "number":
+      return { type: "Numeric" };
+    case "boolean":
+      return { type: "Bool" };
+    case "string":
+      return { type: "Text" };
+    default:
+      return { type: "Any" };
+  }
+}
+function lengthOf(cols) {
+  for (const arr of Object.values(cols)) if (Array.isArray(arr)) return arr.length;
+  return 0;
+}
+function requireString(value, name) {
+  if (typeof value !== "string" || !value) throw new Error(`Expected non-empty string for ${name}`);
+  return value;
+}
+function requireNumber(value, name) {
+  if (typeof value !== "number" || Number.isNaN(value)) throw new Error(`Expected number for ${name}`);
+  return value;
+}
+function normalizeValuesForTable(table, values) {
+  const out = {};
+  for (const [colId, value] of Object.entries(values)) {
+    out[colId] = normalizeCellValueForType(value, table.columns[colId]?.type);
+  }
+  return out;
+}
+function normalizeColumnarForTable(table, columns) {
+  const out = {};
+  for (const [colId, values] of Object.entries(columns)) {
+    const type = table.columns[colId]?.type;
+    out[colId] = Array.isArray(values) ? values.map((value) => normalizeCellValueForType(value, type)) : [];
+  }
+  return out;
+}
+function normalizeCellValueForType(value, type) {
+  if (value === null || value === void 0 || typeof type !== "string") return value;
+  if (type.startsWith("Ref:")) return normalizeRefValue(value);
+  if (type.startsWith("RefList:")) return normalizeRefListValue(value);
+  return value;
+}
+function extractRefRowId(value) {
+  if (value === null || value === void 0) return null;
+  if (value && typeof value === "object" && "__ref" in value) {
+    const inner = value.rowId;
+    return extractRefRowId(inner);
+  }
+  if (value && typeof value === "object" && "rowId" in value) {
+    return extractRefRowId(value.rowId);
+  }
+  const fromTuple = coerceGristDocApiRefRowId(value);
+  if (fromTuple !== void 0 && fromTuple > 0) return Math.trunc(fromTuple);
+  return toPositiveInt(value);
+}
+function normalizeRefValue(value) {
+  return extractRefRowId(value);
+}
+function normalizeRefListValue(value) {
+  const toIdList = (items) => Array.from(
+    new Set(items.map((item) => extractRefRowId(item)).filter((item) => item !== null))
+  );
+  if (Array.isArray(value) && value[0] === "L") {
+    return ["L", ...toIdList(value.slice(1))];
+  }
+  if (Array.isArray(value)) {
+    return ["L", ...toIdList(value)];
+  }
+  if (typeof value === "string") {
+    const tokens = value.split(",").map((t) => t.trim()).filter(Boolean);
+    return ["L", ...toIdList(tokens)];
+  }
+  if (value && typeof value === "object" && Array.isArray(value.rowIds)) {
+    return ["L", ...toIdList(value.rowIds)];
+  }
+  return ["L"];
+}
+function toPositiveInt(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.trunc(value);
+  if (typeof value === "string") {
+    const n = Number.parseInt(value.trim(), 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}
+
+// src/emulator/core/columnar.ts
+function rowsToColumnar(table, rows, options = {}) {
+  const cols = Object.keys(table.columns);
+  const out = { id: rows.map((r) => r.id) };
+  for (const col of cols) {
+    out[col] = rows.map((r) => encodeForWire(r[col], table.columns[col]?.type, options.keepEncoded));
+  }
+  return out;
+}
+function rowToRecord(table, row, options = {}) {
+  const out = { id: row.id };
+  for (const col of Object.keys(table.columns)) {
+    out[col] = encodeForWire(row[col], table.columns[col]?.type, options.keepEncoded);
+  }
+  return out;
+}
+function encodeForWire(value, type, keepEncoded) {
+  if (value instanceof Date) {
+    const epoch = Math.floor(value.getTime() / 1e3);
+    if (keepEncoded) {
+      return type && type.startsWith("DateTime") ? ["D", epoch, "UTC"] : ["d", epoch];
+    }
+    return epoch;
+  }
+  return value;
+}
+
+// src/emulator/api/grist-doc-api.ts
+function createGristDocApiImpl(state, bus) {
+  return {
+    async getDocName() {
+      return state.docName;
+    },
+    async listTables() {
+      return [...state.tables.keys()];
+    },
+    async fetchTable(tableId) {
+      if (tableId === "_grist_Tables") {
+        return synthesizeTablesMeta(state);
+      }
+      if (tableId === "_grist_Tables_column") {
+        return synthesizeTablesColumnMeta(state);
+      }
+      const table = getTable(state, tableId);
+      return rowsToColumnar(table, table.rows);
+    },
+    async applyUserActions(actions) {
+      const result = applyUserActions(state, bus, actions);
+      return { retValues: result.retValues };
+    },
+    async getAccessToken() {
+      if (!state.accessToken) {
+        const err = new Error("getAccessToken not available (no token configured on emulator)");
+        throw err;
+      }
+      return { ...state.accessToken };
+    }
+  };
+}
+
+// src/emulator/api/grist-view.ts
+function createGristViewImpl(state, bus) {
+  return {
+    async fetchSelectedTable(options) {
+      const table = getSelectedTable(state);
+      return rowsToColumnar(table, table.rows, { keepEncoded: options?.keepEncoded });
+    },
+    async fetchSelectedRecord(rowId, options) {
+      const table = getSelectedTable(state);
+      const row = findRow(table, rowId);
+      if (!row) throw new Error(`No row ${rowId} in ${table.tableId}`);
+      return rowToRecord(table, row, { keepEncoded: options?.keepEncoded });
+    },
+    async allowSelectBy() {
+      return state.configuration?.allowSelectBy ?? false;
+    },
+    async setSelectedRows(rowIds) {
+      if (!rowIds || rowIds.length === 0) {
+        state.selection.rowId = null;
+      } else {
+        state.selection.rowId = rowIds[0];
+      }
+      bus.emit({
+        type: "cursor-change",
+        tableId: state.selection.tableId,
+        rowId: state.selection.rowId
+      });
+    },
+    async setCursorPos(cursor) {
+      const tableId = state.selection.tableId;
+      if (typeof cursor.rowId === "number") state.selection.rowId = cursor.rowId;
+      state.selection.cursor = { ...state.selection.cursor, ...cursor };
+      bus.emit({
+        type: "cursor-change",
+        tableId,
+        rowId: state.selection.rowId,
+        cursor: state.selection.cursor
+      });
+    }
+  };
+}
+
+// src/emulator/api/widget-api.ts
+function createWidgetApiImpl(state, bus) {
+  function emit() {
+    bus.emit({
+      type: "options-change",
+      options: { ...state.widgetOptions },
+      interaction: { ...state.widgetInteraction }
+    });
+  }
+  return {
+    async getOption(key) {
+      return state.widgetOptions[key];
+    },
+    async setOption(key, value) {
+      state.widgetOptions[key] = value;
+      emit();
+    },
+    async getOptions() {
+      return Object.keys(state.widgetOptions).length > 0 ? { ...state.widgetOptions } : null;
+    },
+    async setOptions(options) {
+      state.widgetOptions = { ...state.widgetOptions, ...options };
+      emit();
+    },
+    async clearOptions() {
+      state.widgetOptions = {};
+      emit();
+    }
+  };
+}
+
+// src/emulator/api/index.ts
+function createApiBundle(state, bus) {
+  return {
+    GristView: createGristViewImpl(state, bus),
+    GristDocAPI: createGristDocApiImpl(state, bus),
+    WidgetAPI: createWidgetApiImpl(state, bus),
+    CustomSectionAPI: createCustomSectionApiImpl(state, bus),
+    GristAPI: createGristApiImpl(),
+    CommandAPI: createCommandApiImpl(bus)
+  };
+}
+
+// src/emulator/core/event-bus.ts
+function createEventBus(options = {}) {
+  const limit = options.historyLimit ?? 200;
+  const listeners = /* @__PURE__ */ new Set();
+  const history = [];
+  return {
+    emit(event) {
+      history.push(event);
+      if (history.length > limit) history.shift();
+      for (const fn of [...listeners]) {
+        try {
+          fn(event);
+        } catch (err) {
+          console.error("[grist-emulator] event listener threw:", err);
+        }
+      }
+    },
+    on(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    history() {
+      return history;
+    },
+    clear() {
+      history.length = 0;
+    }
+  };
+}
+
+// src/emulator/theme-message.ts
+function buildGristThemeHostMessage(appearance, options) {
+  return {
+    theme: {
+      appearance,
+      name: appearance,
+      colors: {}
+    },
+    ...options?.fromReady ? { fromReady: true } : {}
+  };
+}
+
+// src/emulator/transports/iframe.ts
+var import_grain_rpc = require("grain-rpc");
+function createIframeTransport(options) {
+  const { iframe, state, bus, api, targetOrigin = "*" } = options;
+  const timers = /* @__PURE__ */ new Set();
+  const rpc = new import_grain_rpc.Rpc({
+    sendMessage: (msg) => {
+      const target = iframe.contentWindow;
+      if (!target) return;
+      target.postMessage(msg, targetOrigin);
+    },
+    logger: { info: () => {
+    }, warn: () => {
+    } }
+  });
+  rpc.queueOutgoingUntilReadyMessage();
+  const receiveFromWidget = rpc.receiveMessage.bind(rpc);
+  rpc.receiveMessage = (msg) => {
+    if (msg && typeof msg === "object" && msg.mtype === import_grain_rpc.MsgType.RpcCall && msg.mdest === "grist") {
+      const copy = { ...msg };
+      delete copy.mdest;
+      receiveFromWidget(copy);
+      return;
+    }
+    receiveFromWidget(msg);
+  };
+  const onMessage = (event) => {
+    if (event.source !== iframe.contentWindow) return;
+    if (!isRpcEnvelope(event.data)) return;
+    rpc.receiveMessage(event.data);
+  };
+  window.addEventListener("message", onMessage);
+  rpc.registerImpl("GristView", api.GristView);
+  rpc.registerImpl("GristDocAPI", api.GristDocAPI);
+  rpc.registerImpl("WidgetAPI", api.WidgetAPI);
+  rpc.registerImpl("CustomSectionAPI", api.CustomSectionAPI);
+  rpc.registerImpl("_grist_api", api.GristAPI);
+  rpc.registerImpl("CommandAPI", api.CommandAPI);
+  const buildInteraction = options.buildInteraction ?? defaultInteraction(state);
+  const cursorOf = options.cursor ?? (() => state.selection.cursor);
+  const initialCursorOf = options.initialCursor ?? (() => state.selection.rowId);
+  function fireDataChange(tableId, opts) {
+    safePostMessage({
+      tableId: tableId ?? state.selection.tableId,
+      dataChange: true,
+      ...opts?.mappingsChange ? { mappingsChange: true } : {}
+    });
+  }
+  function fireCursor(rowId, opts) {
+    const id = rowId === void 0 ? initialCursorOf() : rowId;
+    if (id === null) return;
+    safePostMessage({
+      tableId: state.selection.tableId,
+      rowId: id,
+      cursor: cursorOf(),
+      ...opts?.mappingsChange ? { mappingsChange: true } : {}
+    });
+  }
+  function fireOptions() {
+    safePostMessage({
+      options: hasOptions(state.widgetOptions) ? { ...state.widgetOptions } : null,
+      settings: { ...buildInteraction() }
+    });
+  }
+  function fireTheme(message) {
+    safePostMessage(message);
+  }
+  function emitInitialState(opts) {
+    fireOptions();
+    if (options.initialTheme) {
+      fireTheme(buildGristThemeHostMessage(options.initialTheme, { fromReady: true }));
+    }
+    fireDataChange(void 0, opts);
+    fireCursor(void 0, opts);
+  }
+  function emitInitialStateWithReplay(opts) {
+    emitInitialState(opts);
+    queueMicrotask(() => emitInitialState(opts));
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      emitInitialState(opts);
+    }, 0);
+    timers.add(timer);
+  }
+  const offBus = bus.on((event) => {
+    switch (event.type) {
+      case "ready":
+        emitInitialStateWithReplay();
+        break;
+      case "data-change":
+        fireDataChange(event.tableId);
+        break;
+      case "cursor-change": {
+        const rowId = event.rowId === null ? state.selection.rowId : event.rowId;
+        if (rowId !== null) {
+          safePostMessage({
+            tableId: event.tableId,
+            rowId,
+            cursor: cursorOf()
+          });
+        }
+        fireDataChange(event.tableId);
+        break;
+      }
+      case "options-change":
+        fireOptions();
+        break;
+      case "mappings-change":
+        emitInitialStateWithReplay({ mappingsChange: true });
+        break;
+      case "theme-change":
+        fireTheme(event.message);
+        break;
+    }
+  });
+  rpc.processIncoming();
+  function safePostMessage(payload) {
+    try {
+      rpc.postMessage(payload);
+    } catch (err) {
+      console.warn("[grist-emulator/iframe] failed to deliver postMessage", err);
+    }
+  }
+  return {
+    dispose() {
+      window.removeEventListener("message", onMessage);
+      offBus();
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+    },
+    fireDataChange,
+    fireCursor,
+    fireOptions,
+    fireTheme,
+    emitInitialState
+  };
+}
+function hasOptions(options) {
+  return Object.keys(options).length > 0;
+}
+function isRpcEnvelope(data) {
+  if (!data || typeof data !== "object") return false;
+  return typeof data.mtype === "number";
+}
+function defaultInteraction(state) {
+  return () => ({
+    access_level: state.configuration?.requiredAccess ?? "read table",
+    ...state.widgetInteraction
+  });
+}
+
+// src/sdk/helpers/grist-user-actions.ts
+function gristUpdateRecordAction(tableId, rowId, patch) {
+  return ["UpdateRecord", tableId, rowId, patch];
+}
+function gristAddRecordAction(tableId, values) {
+  return ["AddRecord", tableId, null, values];
+}
+function gristRemoveRecordAction(tableId, rowId) {
+  return ["RemoveRecord", tableId, rowId];
+}
+function gristBulkUpdateRecordAction(tableId, rowIds, columnarPatch) {
+  return ["BulkUpdateRecord", tableId, rowIds, columnarPatch];
+}
+function gristBulkAddRecordAction(tableId, values, rowIds) {
+  const length = inferBulkLength(values);
+  const ids = rowIds ?? new Array(length).fill(null);
+  return ["BulkAddRecord", tableId, ids, values];
+}
+function gristBulkRemoveRecordAction(tableId, rowIds) {
+  return ["BulkRemoveRecord", tableId, rowIds];
+}
+function inferBulkLength(values) {
+  for (const arr of Object.values(values)) if (Array.isArray(arr)) return arr.length;
+  return 0;
+}
+
+// src/emulator/transports/inline.ts
+function createInlineTransport(options) {
+  const { state, bus, api } = options;
+  const target = options.target ?? globalThis;
+  installFakeIframeContext(target);
+  const recordCbs = /* @__PURE__ */ new Map();
+  const recordsCbs = /* @__PURE__ */ new Map();
+  const optionsCbs = /* @__PURE__ */ new Set();
+  const newRecordCbs = /* @__PURE__ */ new Set();
+  const generic = /* @__PURE__ */ new Map();
+  let lastRecord = null;
+  let lastRecords = null;
+  let lastOptions = null;
+  let lastNewRecord = void 0;
+  const buildInteraction = options.buildInteraction ?? (() => ({
+    access_level: state.configuration?.requiredAccess ?? "read table",
+    ...state.widgetInteraction
+  }));
+  async function pushRecord(rowId) {
+    const mappings = resolveMappings(state);
+    if (rowId === "new") {
+      lastNewRecord = mappings;
+      for (const cb of newRecordCbs) {
+        try {
+          cb(mappings);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+      lastRecord = { record: null, mappings };
+      for (const [cb] of recordCbs) {
+        try {
+          cb(null, mappings);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+      return;
+    }
+    if (rowId === null) {
+      lastRecord = { record: null, mappings };
+      for (const [cb] of recordCbs) {
+        try {
+          cb(null, mappings);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+      return;
+    }
+    let record = null;
+    try {
+      record = await api.GristView.fetchSelectedRecord(rowId);
+    } catch (err) {
+      logErr(err);
+    }
+    lastRecord = { record, mappings };
+    for (const [cb, opts] of recordCbs) {
+      try {
+        const r = opts?.keepEncoded ? await api.GristView.fetchSelectedRecord(rowId, { keepEncoded: true }) : record;
+        cb(r, mappings);
+      } catch (err) {
+        logErr(err);
+      }
+    }
+  }
+  async function pushRecords() {
+    const mappings = resolveMappings(state);
+    let baseRows = [];
+    try {
+      const columnar = await api.GristView.fetchSelectedTable({});
+      baseRows = columnsToRows(columnar);
+    } catch (err) {
+      logErr(err);
+    }
+    lastRecords = { records: baseRows, mappings };
+    for (const [cb, opts] of recordsCbs) {
+      try {
+        const fetchOptions = coerceFetchOptions(opts);
+        const rows = fetchOptions?.keepEncoded ? columnsToRows(await api.GristView.fetchSelectedTable({ keepEncoded: true })) : baseRows;
+        cb(rows, mappings);
+      } catch (err) {
+        logErr(err);
+      }
+    }
+  }
+  async function fetchSelectedTableShaped(opts) {
+    const fetchOptions = coerceFetchOptions(opts);
+    const columnar = await api.GristView.fetchSelectedTable(
+      fetchOptions ? { keepEncoded: fetchOptions.keepEncoded } : {}
+    );
+    if (fetchOptions?.format === "rows") return columnsToRows(columnar);
+    return columnar;
+  }
+  function pushOptions() {
+    const opts = Object.keys(state.widgetOptions).length > 0 ? { ...state.widgetOptions } : null;
+    const interaction = buildInteraction();
+    lastOptions = { options: opts, interaction };
+    for (const cb of optionsCbs) {
+      try {
+        cb(opts, interaction);
+      } catch (err) {
+        logErr(err);
+      }
+    }
+  }
+  const offBus = bus.on(async (event) => {
+    switch (event.type) {
+      case "data-change":
+        await pushRecords();
+        await pushRecord(state.selection.rowId);
+        break;
+      case "cursor-change":
+        await pushRecord(event.rowId);
+        break;
+      case "options-change":
+        pushOptions();
+        break;
+      case "ready":
+        pushOptions();
+        if (options.initialTheme) {
+          notify("message", buildGristThemeHostMessage(options.initialTheme, { fromReady: true }));
+        }
+        await pushRecords();
+        await pushRecord(state.selection.rowId);
+        break;
+      case "mappings-change":
+        await pushRecords();
+        await pushRecord(state.selection.rowId);
+        break;
+      case "theme-change":
+        notify("message", event.message);
+        break;
+    }
+  });
+  function makeTableOps(tableId) {
+    return {
+      async getTableId() {
+        return tableId;
+      },
+      async create(records, options2) {
+        const list = Array.isArray(records) ? records : [records];
+        const ids = [];
+        for (const r of list) {
+          const result = applyUserActions(state, bus, [
+            gristAddRecordAction(tableId, parseFields(r.fields, options2))
+          ]);
+          ids.push({ id: result.retValues[0] });
+        }
+        return Array.isArray(records) ? ids : ids[0];
+      },
+      async update(records, options2) {
+        const list = Array.isArray(records) ? records : [records];
+        const actions = list.map((r) => gristUpdateRecordAction(tableId, r.id, parseFields(r.fields, options2)));
+        applyUserActions(state, bus, actions);
+      },
+      async upsert(records, options2) {
+        const list = Array.isArray(records) ? records : [records];
+        const allowAdd = options2?.add !== false;
+        const allowUpdate = options2?.update !== false;
+        const table = getTable(state, tableId);
+        const actions = [];
+        for (const r of list) {
+          const matches = table.rows.filter(
+            (row) => Object.entries(r.require).every(([k, v]) => row[k] === v)
+          );
+          if (matches.length > 0) {
+            if (!allowUpdate) continue;
+            const fields = parseFields(r.fields ?? {}, options2);
+            for (const m of matches) actions.push(gristUpdateRecordAction(tableId, m.id, fields));
+          } else if (allowAdd) {
+            actions.push(gristAddRecordAction(tableId, { ...r.require, ...parseFields(r.fields ?? {}, options2) }));
+          }
+        }
+        if (actions.length > 0) applyUserActions(state, bus, actions);
+      },
+      async destroy(recordIds) {
+        if (Array.isArray(recordIds)) {
+          applyUserActions(state, bus, [gristBulkRemoveRecordAction(tableId, recordIds)]);
+        } else {
+          applyUserActions(state, bus, [gristRemoveRecordAction(tableId, recordIds)]);
+        }
+        void gristBulkAddRecordAction;
+        void gristBulkUpdateRecordAction;
+      }
+    };
+  }
+  function notify(event, ...args) {
+    const set = generic.get(event);
+    if (!set) return;
+    for (const fn of set) {
+      try {
+        fn(...args);
+      } catch (err) {
+        logErr(err);
+      }
+    }
+  }
+  const grist = {
+    async ready(opts) {
+      await api.CustomSectionAPI.configure(opts ? { ...opts, onEditOptions: void 0 } : {});
+    },
+    onRecord(cb, opts) {
+      recordCbs.set(cb, opts);
+      if (lastRecord) {
+        try {
+          cb(lastRecord.record, lastRecord.mappings);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+    },
+    onRecords(cb, opts) {
+      recordsCbs.set(cb, opts);
+      if (lastRecords) {
+        try {
+          cb(lastRecords.records, lastRecords.mappings);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+    },
+    onOptions(cb) {
+      optionsCbs.add(cb);
+      if (lastOptions) {
+        try {
+          cb(lastOptions.options, lastOptions.interaction);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+    },
+    onNewRecord(cb) {
+      newRecordCbs.add(cb);
+      if (lastNewRecord !== void 0) {
+        try {
+          cb(lastNewRecord);
+        } catch (err) {
+          logErr(err);
+        }
+      }
+    },
+    mapColumnNames(data) {
+      const mappings = resolveMappings(state);
+      if (!mappings) return null;
+      const out = {};
+      let allMapped = true;
+      for (const [logical, real] of Object.entries(mappings)) {
+        if (Array.isArray(real)) {
+          out[logical] = real.map((r) => data[r]);
+        } else if (typeof real === "string") {
+          out[logical] = data[real];
+        } else {
+          allMapped = false;
+        }
+      }
+      return allMapped ? out : null;
+    },
+    mapColumnNamesBack(data) {
+      const mappings = resolveMappings(state);
+      if (!mappings) return data;
+      const out = {};
+      for (const [logical, real] of Object.entries(mappings)) {
+        if (typeof real === "string" && logical in data) {
+          out[real] = data[logical];
+        }
+      }
+      return out;
+    },
+    getOption: (k) => api.WidgetAPI.getOption(k),
+    setOption: (k, v) => api.WidgetAPI.setOption(k, v),
+    getOptions: () => api.WidgetAPI.getOptions(),
+    setOptions: (o) => api.WidgetAPI.setOptions(o),
+    clearOptions: () => api.WidgetAPI.clearOptions(),
+    setCursorPos: (pos) => api.GristView.setCursorPos(pos),
+    setSelectedRows: (rowIds) => api.GristView.setSelectedRows(rowIds),
+    fetchSelectedTable: (opts) => fetchSelectedTableShaped(opts),
+    fetchSelectedRecord: (rowId, opts) => api.GristView.fetchSelectedRecord(rowId, coerceFetchOptions(opts)),
+    docApi: {
+      getDocName: () => api.GristDocAPI.getDocName(),
+      listTables: () => api.GristDocAPI.listTables(),
+      fetchTable: (id) => api.GristDocAPI.fetchTable(id),
+      applyUserActions: (actions, options2) => api.GristDocAPI.applyUserActions(actions, options2),
+      getAccessToken: (opts) => api.GristDocAPI.getAccessToken(opts),
+      fetchSelectedTable: (opts) => fetchSelectedTableShaped(opts),
+      fetchSelectedRecord: (rowId, opts) => api.GristView.fetchSelectedRecord(rowId, coerceFetchOptions(opts))
+    },
+    get selectedTable() {
+      return makeTableOps(state.selection.tableId);
+    },
+    getTable(tableId) {
+      return makeTableOps(tableId ?? state.selection.tableId);
+    },
+    sectionApi: {
+      configure: (settings) => api.CustomSectionAPI.configure(settings),
+      mappings: () => api.CustomSectionAPI.mappings()
+    },
+    on(eventName, listener) {
+      let set = generic.get(eventName);
+      if (!set) generic.set(eventName, set = /* @__PURE__ */ new Set());
+      set.add(listener);
+      return () => set.delete(listener);
+    }
+  };
+  target.grist = grist;
+  return {
+    grist,
+    dispose() {
+      offBus();
+      const t = target;
+      if (t.grist === grist) delete t.grist;
+      recordCbs.clear();
+      recordsCbs.clear();
+      optionsCbs.clear();
+      newRecordCbs.clear();
+      generic.clear();
+      lastRecord = null;
+      lastRecords = null;
+      lastOptions = null;
+      lastNewRecord = void 0;
+    },
+    fireDataChange(tableId) {
+      bus.emit({ type: "data-change", tableId: tableId ?? state.selection.tableId });
+    },
+    fireCursor(rowId) {
+      const id = rowId === void 0 ? state.selection.rowId : rowId;
+      bus.emit({ type: "cursor-change", tableId: state.selection.tableId, rowId: id });
+    },
+    fireOptions() {
+      pushOptions();
+    },
+    fireTheme(message) {
+      bus.emit({ type: "theme-change", message });
+    },
+    emitInitialState() {
+      pushOptions();
+      void pushRecords().then(() => pushRecord(state.selection.rowId));
+    }
+  };
+}
+function columnsToRows(columnar) {
+  const cols = Object.keys(columnar);
+  if (cols.length === 0) return [];
+  const length = (columnar[cols[0]] ?? []).length;
+  const rows = [];
+  for (let i = 0; i < length; i++) {
+    const row = {};
+    for (const c of cols) row[c] = columnar[c][i];
+    rows.push(row);
+  }
+  return rows;
+}
+function parseFields(fields, _options) {
+  return { ...fields };
+}
+function coerceFetchOptions(opts) {
+  if (!opts) return void 0;
+  const format = opts.format === "rows" || opts.format === "columns" ? opts.format : void 0;
+  return { keepEncoded: opts.keepEncoded, format };
+}
+function logErr(err) {
+  console.error("[grist-emulator/inline]", err);
+}
+function installFakeIframeContext(target) {
+  try {
+    if (target.self !== target.top) return;
+    Object.defineProperty(target, "top", {
+      configurable: true,
+      get: () => ({})
+    });
+  } catch {
+  }
+}
+
+// src/emulator/validators.ts
+var import_zod2 = require("zod");
+var emulatorRowSchema = import_zod2.z.object({ id: import_zod2.z.number() }).catchall(import_zod2.z.unknown());
+var formulaKindSchema = import_zod2.z.enum(["computed", "trigger", "none", "empty_slot"]);
+var replicaColumnSchema = import_zod2.z.object({
+  colRef: import_zod2.z.number().optional(),
+  type: import_zod2.z.string().optional(),
+  label: import_zod2.z.string().optional(),
+  parentPos: import_zod2.z.number().optional(),
+  isFormula: import_zod2.z.boolean().optional(),
+  formulaKind: formulaKindSchema.optional(),
+  formula: import_zod2.z.string().optional(),
+  description: import_zod2.z.string().optional(),
+  widgetOptions: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional(),
+  displayColRef: import_zod2.z.number().optional(),
+  visibleColRef: import_zod2.z.number().optional()
+}).strict();
+var replicaTableSchema = import_zod2.z.object({
+  label: import_zod2.z.string().optional(),
+  columns: import_zod2.z.record(import_zod2.z.string(), replicaColumnSchema).optional(),
+  rows: import_zod2.z.array(emulatorRowSchema).optional(),
+  rowCount: import_zod2.z.number().optional(),
+  dataOmitted: import_zod2.z.boolean().optional(),
+  dataOmittedReason: import_zod2.z.string().optional(),
+  error: import_zod2.z.string().optional()
+}).strict();
+var replicaSelectionSchema = import_zod2.z.object({
+  tableId: import_zod2.z.string().optional(),
+  rowId: import_zod2.z.union([import_zod2.z.number(), import_zod2.z.literal("new"), import_zod2.z.null()]).optional(),
+  mappings: import_zod2.z.unknown().nullable().optional(),
+  cursor: import_zod2.z.unknown().optional()
+}).strict();
+var replicaWidgetConfigurationSchema = import_zod2.z.object({
+  requiredAccess: import_zod2.z.string().optional(),
+  columns: import_zod2.z.unknown().optional(),
+  allowSelectBy: import_zod2.z.boolean().optional(),
+  hasCustomOptions: import_zod2.z.boolean().optional()
+}).strict();
+var replicaAccessTokenSchema = import_zod2.z.object({
+  token: import_zod2.z.string(),
+  baseUrl: import_zod2.z.string(),
+  ttlMsecs: import_zod2.z.number()
+}).strict();
+var replicaDocumentSchema = import_zod2.z.object({
+  generatedAt: import_zod2.z.string(),
+  source: import_zod2.z.string().optional(),
+  docName: import_zod2.z.string().optional(),
+  mode: import_zod2.z.enum(["schema-only", "schema+samples", "schema+data"]).optional(),
+  tables: import_zod2.z.record(import_zod2.z.string(), replicaTableSchema),
+  selection: replicaSelectionSchema.optional(),
+  widgetOptions: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional(),
+  widgetInteraction: import_zod2.z.unknown().optional(),
+  configuration: replicaWidgetConfigurationSchema.optional(),
+  accessToken: replicaAccessTokenSchema.nullable().optional()
+}).strict().refine((value) => Object.keys(value.tables).length > 0, {
+  message: "at least one table is required",
+  path: ["tables"]
+});
+function formatZodError(prefix, error) {
+  const details = error.issues.map((issue) => {
+    const where = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+    return `${where}: ${issue.message}`;
+  }).join("; ");
+  return new Error(`${prefix}: ${details}`);
+}
+function safeParseDocument(input) {
+  return replicaDocumentSchema.safeParse(input);
+}
+function parseDocument(input) {
+  const result = safeParseDocument(input);
+  if (!result.success) {
+    throw formatZodError("parseDocument", result.error);
+  }
+  return result.data;
+}
+
+// src/emulator/create-grist-emulator.ts
+function createGristEmulator(options) {
+  const validatedDocument = parseDocument(options.document);
+  const state = createDocument({
+    ...validatedDocument,
+    widgetOptions: options.widgetOptions ?? validatedDocument.widgetOptions,
+    widgetInteraction: options.widgetInteraction ?? validatedDocument.widgetInteraction ?? { access_level: "read table" }
+  });
+  const bus = createEventBus();
+  const api = createApiBundle(state, bus);
+  const transportKind = options.transport?.kind ?? "inline";
+  let transport;
+  let grist;
+  if (transportKind === "iframe") {
+    if (options.transport?.kind !== "iframe") throw new Error("transport mismatch");
+    transport = createIframeTransport({
+      iframe: options.transport.iframe,
+      targetOrigin: options.transport.targetOrigin,
+      state,
+      bus,
+      api,
+      initialTheme: options.initialTheme
+    });
+  } else {
+    const inline = createInlineTransport({
+      state,
+      bus,
+      api,
+      initialTheme: options.initialTheme,
+      target: options.transport?.kind === "inline" ? options.transport.target : void 0
+    });
+    transport = inline;
+    grist = inline.grist;
+  }
+  function apply(actions) {
+    return applyUserActions(state, bus, actions);
+  }
+  return {
+    state,
+    bus,
+    api,
+    transport,
+    grist,
+    apply,
+    mutate: {
+      addRow: (tableId, fields) => apply([["AddRecord", tableId, null, fields]]).retValues[0],
+      updateRow: (tableId, rowId, fields) => {
+        apply([["UpdateRecord", tableId, rowId, fields]]);
+      },
+      removeRow: (tableId, rowId) => {
+        apply([["RemoveRecord", tableId, rowId]]);
+      }
+    },
+    selectRow(rowId) {
+      state.selection.rowId = rowId;
+      bus.emit({ type: "cursor-change", tableId: state.selection.tableId, rowId });
+    },
+    selectTable(tableId) {
+      if (!state.tables.has(tableId)) throw new Error(`Unknown table: ${tableId}`);
+      state.selection.tableId = tableId;
+      const first = state.tables.get(tableId).rows[0]?.id ?? null;
+      state.selection.rowId = first;
+      bus.emit({ type: "data-change", tableId });
+      bus.emit({ type: "cursor-change", tableId, rowId: first });
+    },
+    setColumnMappings(mappings) {
+      if (mappings === void 0) {
+        delete state.selection.mappings;
+      } else {
+        state.selection.mappings = mappings;
+      }
+      bus.emit({ type: "mappings-change", mappings: resolveMappings(state) });
+    },
+    async setOptions(opts) {
+      await api.WidgetAPI.setOptions(opts);
+    },
+    setInteraction(interaction) {
+      state.widgetInteraction = { ...interaction };
+      bus.emit({ type: "options-change", options: { ...state.widgetOptions }, interaction: { ...interaction } });
+    },
+    theme: {
+      set(next) {
+        bus.emit({ type: "theme-change", message: buildGristThemeHostMessage(next) });
+      }
+    },
+    dispose() {
+      transport.dispose();
+      bus.clear();
+    }
+  };
+}
+
+// src/emulator/templates.ts
+var PRESET_GENERATED_AT = "1970-01-01T00:00:00.000Z";
+function replicaBase(overrides) {
+  return {
+    generatedAt: PRESET_GENERATED_AT,
+    ...overrides
+  };
+}
+var presets = {
+  /**
+   * Default starter fixture for demos / sandboxes that need a neutral document
+   * without choosing a domain-specific preset.
+   */
+  defaultTemplate() {
+    return replicaBase({
+      docName: "Default",
+      tables: {
+        Table1: {
+          label: "Table1",
+          rows: [
+            { id: 1, Name: "Alice" },
+            { id: 2, Name: "Bob" }
+          ]
+        }
+      }
+    });
+  },
+  blank() {
+    return replicaBase({
+      docName: "Blank",
+      tables: {
+        Table1: { rows: [{ id: 1 }] }
+      }
+    });
+  },
+  todoList() {
+    return replicaBase({
+      docName: "Todo list",
+      mode: "schema+data",
+      tables: {
+        Tasks: {
+          label: "Tasks",
+          columns: {
+            title: { type: "Text", label: "Title" },
+            done: { type: "Bool", label: "Done" },
+            priority: { type: "Choice", label: "Priority" }
+          },
+          rows: [
+            { id: 1, title: "Buy milk", done: false, priority: "high" },
+            { id: 2, title: "Write the SOTA emulator", done: true, priority: "high" },
+            { id: 3, title: "Ship it", done: false, priority: "medium" }
+          ]
+        }
+      }
+    });
+  },
+  contacts() {
+    return replicaBase({
+      docName: "Contacts",
+      mode: "schema+data",
+      tables: {
+        Contacts: {
+          label: "Contacts",
+          columns: {
+            firstName: { type: "Text" },
+            lastName: { type: "Text" },
+            email: { type: "Text" },
+            company: { type: "Text" }
+          },
+          rows: [
+            { id: 1, firstName: "Ada", lastName: "Lovelace", email: "ada@analytical.engine", company: "British Crown" },
+            { id: 2, firstName: "Linus", lastName: "Torvalds", email: "linus@kernel.org", company: "Linux Foundation" },
+            { id: 3, firstName: "Margaret", lastName: "Hamilton", email: "margaret@apollo.nasa", company: "NASA" }
+          ]
+        }
+      }
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EmulatorActionError,
+  createGristEmulator,
+  enrichEmulatorColumnMetadata,
+  parseDocument,
+  presets,
+  resolveMappings,
+  safeParseDocument
+});
+//# sourceMappingURL=emulator.cjs.map