grist-widget-sdk 0.3.26 → 0.4.0

package/dist/emulator/testing.cjs

@@ -20,23 +20,833 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/emulator/testing/index.ts
 var testing_exports = {};
 __export(testing_exports, {
-  act: () => import_react2.act,
+  act: () => import_react11.act,
   actionsOf: () => actionsOf,
-  cleanup: () => import_react2.cleanup,
+  cleanup: () => import_react11.cleanup,
   eventsOf: () => eventsOf,
-  fireEvent: () => import_react2.fireEvent,
+  fireEvent: () => import_react11.fireEvent,
+  installJsdomStubs: () => installJsdomStubs,
   presets: () => presets,
-  render: () => import_react2.render,
+  render: () => import_react11.render,
   renderWithGrist: () => renderWithGrist,
-  screen: () => import_react2.screen,
-  waitFor: () => import_react2.waitFor,
+  screen: () => import_react11.screen,
+  smokeTestWidget: () => smokeTestWidget,
+  waitFor: () => import_react11.waitFor,
   waitForEvent: () => waitForEvent,
-  within: () => import_react2.within
+  within: () => import_react11.within
 });
 module.exports = __toCommonJS(testing_exports);
 
 // src/emulator/testing/render-with-grist.tsx
-var import_react = require("@testing-library/react");
+var import_react2 = require("@testing-library/react");
+
+// src/sdk/use-grist.ts
+var import_react = require("react");
+
+// src/sdk/helpers/grist-value-codec.ts
+var MARSHALLED_TAGS = /* @__PURE__ */ new Set(["E", "L", "D", "d", "R", "r", "P"]);
+function isMarshalledTuple(value) {
+  return Array.isArray(value) && typeof value[0] === "string" && value[0].length <= 2 && MARSHALLED_TAGS.has(value[0]);
+}
+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;
+}
+function looksLikeAttachmentColumn(column) {
+  return column?.type === "Attachments";
+}
+function looksLikeChoiceListColumn(column) {
+  return column?.type === "ChoiceList";
+}
+function looksLikeRefListColumn(column) {
+  return typeof column?.type === "string" && column.type.startsWith("RefList:");
+}
+function looksLikeRefColumn(column) {
+  return typeof column?.type === "string" && column.type.startsWith("Ref:");
+}
+function looksLikeDateColumn(column) {
+  return column?.type === "Date";
+}
+function looksLikeDateTimeColumn(column) {
+  return typeof column?.type === "string" && column.type.startsWith("DateTime");
+}
+function decodeGristValue(value, column) {
+  if (value === null || value === void 0) return null;
+  if (isMarshalledTuple(value)) {
+    const tag = value[0];
+    switch (tag) {
+      case "E":
+        return {
+          __error: true,
+          type: typeof value[1] === "string" ? value[1] : "Error",
+          message: typeof value[2] === "string" ? value[2] : void 0,
+          traceback: typeof value[3] === "string" ? value[3] : void 0
+        };
+      case "L":
+        return value.slice(1).map((v) => decodeGristValue(v, void 0));
+      case "D":
+        if (typeof value[1] === "number") return new Date(value[1] * 1e3);
+        return null;
+      case "d":
+        if (typeof value[1] === "number") return new Date(value[1] * 1e3);
+        return null;
+      case "R":
+        return {
+          __ref: true,
+          tableId: typeof value[1] === "string" ? value[1] : void 0,
+          rowId: typeof value[2] === "number" ? value[2] : 0
+        };
+      case "r":
+        return { __ref: true, rowId: typeof value[1] === "number" ? value[1] : 0 };
+      case "P":
+        return null;
+      default:
+        return null;
+    }
+  }
+  if (looksLikeDateColumn(column) || looksLikeDateTimeColumn(column)) {
+    if (typeof value === "number" && Number.isFinite(value)) return new Date(value * 1e3);
+  }
+  if (looksLikeRefColumn(column) && typeof value === "number") {
+    return { __ref: true, rowId: value };
+  }
+  if ((looksLikeRefListColumn(column) || looksLikeChoiceListColumn(column) || looksLikeAttachmentColumn(column)) && Array.isArray(value)) {
+    return value.map((v) => decodeGristValue(v, void 0));
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.map((v) => decodeGristValue(v, void 0));
+  return null;
+}
+
+// src/sdk/helpers/grist-table-data.ts
+function computeRowCount(data) {
+  const idCol = data.id;
+  if (Array.isArray(idCol)) return idCol.length;
+  for (const key of Object.keys(data)) {
+    const col = data[key];
+    if (Array.isArray(col)) return col.length;
+  }
+  return 0;
+}
+function decodeColumnarToReplicaRows(data, columnIds, columns, maxRows) {
+  const nFull = computeRowCount(data);
+  const n = maxRows !== void 0 ? Math.min(nFull, maxRows) : nFull;
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const row = {};
+    for (const k of columnIds) {
+      const arr = data[k];
+      const raw = Array.isArray(arr) ? arr[i] : void 0;
+      if (k === "id") {
+        row[k] = raw;
+      } else {
+        row[k] = decodeGristValue(raw, columns[k]);
+      }
+    }
+    out.push(row);
+  }
+  return out;
+}
+function tableDataToRows(data) {
+  const idCol = data.id;
+  if (!Array.isArray(idCol) || idCol.length === 0) return [];
+  const keys = Object.keys(data);
+  const n = idCol.length;
+  const rows = [];
+  for (let i = 0; i < n; i++) {
+    const row = {};
+    for (const k of keys) {
+      const col = data[k];
+      row[k] = Array.isArray(col) ? col[i] : void 0;
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+function manualSortKey(row) {
+  const v = row.manualSort;
+  if (typeof v === "number" && !Number.isNaN(v)) return v;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    if (!Number.isNaN(n)) return n;
+  }
+  return null;
+}
+function sortRowsByGristOrder(rows) {
+  const hasManual = rows.some((r) => manualSortKey(r) !== null);
+  if (!hasManual) {
+    return [...rows].sort((a, b) => {
+      const ida = typeof a.id === "number" ? a.id : 0;
+      const idb = typeof b.id === "number" ? b.id : 0;
+      return ida - idb;
+    });
+  }
+  return [...rows].sort((a, b) => {
+    const ma = manualSortKey(a);
+    const mb = manualSortKey(b);
+    if (ma !== null && mb !== null && ma !== mb) return ma - mb;
+    if (ma !== null && mb === null) return -1;
+    if (ma === null && mb !== null) return 1;
+    const ida = typeof a.id === "number" ? a.id : 0;
+    const idb = typeof b.id === "number" ? b.id : 0;
+    return ida - idb;
+  });
+}
+function materializeGristRowsFromColumnar(data, options) {
+  const order = options?.order ?? "grist";
+  let rows;
+  if (options?.columns) {
+    const columnIds = Object.keys(data);
+    rows = decodeColumnarToReplicaRows(data, columnIds, options.columns);
+  } else {
+    rows = tableDataToRows(data);
+  }
+  if (order === "none") return rows;
+  if (order === "id") {
+    return [...rows].sort((a, b) => {
+      const ida = typeof a.id === "number" ? a.id : 0;
+      const idb = typeof b.id === "number" ? b.id : 0;
+      return ida - idb;
+    });
+  }
+  return sortRowsByGristOrder(rows);
+}
+async function fetchGristTableRows(docApi, tableId, options) {
+  const data = await docApi.fetchTable(tableId);
+  return materializeGristRowsFromColumnar(data, options);
+}
+
+// src/sdk/helpers/grist-widget-options.ts
+function parseGristWidgetOptionsCell(raw) {
+  if (raw == null || raw === "") return void 0;
+  if (typeof raw === "string") {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      return void 0;
+    }
+    return void 0;
+  }
+  if (typeof raw === "object" && !Array.isArray(raw)) {
+    return raw;
+  }
+  return void 0;
+}
+
+// src/sdk/helpers/build-replica-document.ts
+function readCellStr(table, key, rowIndex) {
+  const col = table[key];
+  if (!Array.isArray(col)) return void 0;
+  const v = col[rowIndex];
+  if (v === null || v === void 0) return void 0;
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return void 0;
+}
+function readCellNum(table, key, rowIndex) {
+  const col = table[key];
+  if (!Array.isArray(col)) return void 0;
+  const v = col[rowIndex];
+  if (typeof v === "number" && !Number.isNaN(v)) return v;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    if (!Number.isNaN(n)) return n;
+  }
+  return void 0;
+}
+async function loadColumnMetadataByTable(docApi) {
+  const byTable = /* @__PURE__ */ new Map();
+  try {
+    const tables = await docApi.fetchTable("_grist_Tables");
+    const columns = await docApi.fetchTable("_grist_Tables_column");
+    const tableIds = tables.tableId;
+    const tableInternalIds = tables.id;
+    if (!Array.isArray(tableIds) || !Array.isArray(tableInternalIds)) return byTable;
+    const internalIdToTableId = /* @__PURE__ */ new Map();
+    for (let i = 0; i < tableInternalIds.length; i++) {
+      const tid = tableIds[i];
+      const iid = coerceGristDocApiRefRowId(tableInternalIds[i]);
+      if (typeof tid === "string" && iid !== void 0) internalIdToTableId.set(iid, tid);
+    }
+    const parentIds = columns.parentId;
+    const colIds = columns.colId;
+    const columnIds = columns.id;
+    if (!Array.isArray(parentIds) || !Array.isArray(colIds) || !Array.isArray(columnIds) || parentIds.length !== colIds.length || colIds.length !== columnIds.length) {
+      return byTable;
+    }
+    const n = parentIds.length;
+    for (let i = 0; i < n; i++) {
+      const parentRowId = coerceGristDocApiRefRowId(parentIds[i]);
+      const colRef = coerceGristDocApiRefRowId(columnIds[i]);
+      const colId = colIds[i];
+      if (parentRowId === void 0 || colRef === void 0 || typeof colId !== "string") continue;
+      const tableId = internalIdToTableId.get(parentRowId);
+      if (!tableId) continue;
+      let colMap = byTable.get(tableId);
+      if (!colMap) {
+        colMap = /* @__PURE__ */ new Map();
+        byTable.set(tableId, colMap);
+      }
+      const parentPos = readCellNum(columns, "parentPos", i);
+      const isFormulaCol = columns.isFormula;
+      const isFormula = Array.isArray(isFormulaCol) ? Boolean(isFormulaCol[i]) : false;
+      const woCol = columns.widgetOptions;
+      const widgetOptions = Array.isArray(woCol) && i < woCol.length ? parseGristWidgetOptionsCell(woCol[i]) : void 0;
+      const displayColRef = coerceGristDocApiRefRowId(
+        Array.isArray(columns.displayCol) ? columns.displayCol[i] : void 0
+      );
+      const visibleColRef = coerceGristDocApiRefRowId(
+        Array.isArray(columns.visibleCol) ? columns.visibleCol[i] : void 0
+      );
+      colMap.set(colId, {
+        colRef,
+        type: readCellStr(columns, "type", i),
+        label: readCellStr(columns, "label", i),
+        parentPos: parentPos !== void 0 ? parentPos : void 0,
+        isFormula,
+        formula: readCellStr(columns, "formula", i),
+        description: readCellStr(columns, "description", i) ?? readCellStr(columns, "descr", i),
+        widgetOptions,
+        displayColRef,
+        visibleColRef
+      });
+    }
+  } catch {
+  }
+  return byTable;
+}
+
+// src/sdk/helpers/grist-columns-filters.ts
+var NOISE_COLUMN_FORMULAS = /* @__PURE__ */ new Set(["now()"]);
+function normalizeFormulaForComparison(formula) {
+  return formula.trim().toLowerCase().replace(/\s+/g, "");
+}
+function isGristNoiseColumn(colId, col, options) {
+  const excludeId = options?.excludeId ?? true;
+  const excludeGristHelpers = options?.excludeGristHelpers ?? true;
+  const excludeLoggingColumns = options?.excludeLoggingColumns ?? true;
+  const excludeManualSort = options?.excludeManualSort ?? false;
+  if (excludeId && colId === "id") return true;
+  if (excludeManualSort && colId === "manualSort") return true;
+  if (excludeGristHelpers && colId.startsWith("gristHelper_")) return true;
+  if (excludeLoggingColumns) {
+    const formula = typeof col?.formula === "string" ? normalizeFormulaForComparison(col.formula) : "";
+    if (formula && NOISE_COLUMN_FORMULAS.has(formula)) return true;
+    if (formula.startsWith("user.")) return true;
+  }
+  return false;
+}
+
+// src/sdk/helpers/grist-attachment-download.ts
+async function getAttachmentDownloadUrl(docApi, attachmentId, options) {
+  const getAccessToken = docApi.getAccessToken;
+  if (!getAccessToken) {
+    throw new Error("getAccessToken is not available on docApi");
+  }
+  const { token: token2, baseUrl } = await getAccessToken({ readOnly: options?.readOnly ?? false });
+  return `${baseUrl}/attachments/${attachmentId}/download?auth=${token2}`;
+}
+async function fetchBytesFromSignedAttachmentUrl(url) {
+  const response = await fetch(url);
+  const contentType = response.headers.get("content-type")?.trim() || "application/octet-stream";
+  if (!response.ok) {
+    throw new Error(`Attachment download failed (${response.status})`);
+  }
+  const buffer = await response.arrayBuffer();
+  return { buffer, contentType };
+}
+async function fetchAttachmentBlob(docApi, attachmentId, options) {
+  const url = await getAttachmentDownloadUrl(docApi, attachmentId, options);
+  const { buffer, contentType } = await fetchBytesFromSignedAttachmentUrl(url);
+  return { blob: new Blob([buffer], { type: contentType }), contentType };
+}
+
+// src/sdk/helpers/grist-fetch-with-auth.ts
+var TOKEN_TTL_MS = 45e3;
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+function cacheKey(readOnly) {
+  return readOnly ? "ro" : "rw";
+}
+async function getGristAccessToken(docApi, options) {
+  if (!docApi.getAccessToken) {
+    throw new Error("getAccessToken is not available on docApi (need higher access level)");
+  }
+  const readOnly = options?.readOnly ?? false;
+  const key = cacheKey(readOnly);
+  const now = Date.now();
+  const hit = cache.get(key);
+  if (hit && now - hit.fetchedAt < TOKEN_TTL_MS) {
+    return hit.token;
+  }
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+  const next = docApi.getAccessToken({ readOnly }).then((token2) => {
+    cache.set(key, { token: token2, fetchedAt: Date.now() });
+    inFlight.delete(key);
+    return token2;
+  });
+  inFlight.set(key, next);
+  return next;
+}
+function clearGristAccessTokenCache() {
+  cache.clear();
+  inFlight.clear();
+}
+async function fetchWithGristAuth(docApi, path, init) {
+  const readOnly = init?.readOnly ?? false;
+  let token2;
+  try {
+    token2 = await getGristAccessToken(docApi, { readOnly });
+  } catch (err) {
+    clearGristAccessTokenCache();
+    throw err;
+  }
+  const isAbsolute = /^https?:\/\//i.test(path);
+  const cleanPath = isAbsolute ? path : path.startsWith("/") ? path : `/${path}`;
+  const url = isAbsolute ? new URL(path) : new URL(`${token2.baseUrl.replace(/\/$/, "")}${cleanPath}`);
+  const gristOrigin = new URL(token2.baseUrl).origin;
+  if (url.origin !== gristOrigin) {
+    throw new Error(
+      `fetchWithGristAuth: refusing to send the Grist access token to ${url.origin}; absolute URLs must point at this document's Grist instance (${gristOrigin}). Use plain fetch() for other hosts.`
+    );
+  }
+  if (!url.searchParams.has("auth")) url.searchParams.set("auth", token2.token);
+  const headers = new Headers(init?.headers ?? {});
+  headers.delete("Authorization");
+  const response = await fetch(url.toString(), { ...init, headers });
+  if (response.status === 401) {
+    clearGristAccessTokenCache();
+    const retryToken = await getGristAccessToken(docApi, { readOnly });
+    url.searchParams.set("auth", retryToken.token);
+    return fetch(url.toString(), { ...init, headers });
+  }
+  return response;
+}
+
+// src/sdk/helpers/grist-attachment-upload.ts
+function parseGristAttachmentUploadResponseIds(raw, options) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("Attachment upload returned an empty response.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    if (options?.strict) {
+      throw new Error("Attachment upload returned non-JSON response.");
+    }
+    parsed = trimmed;
+  }
+  return extractAttachmentIdsFromUploadPayload(parsed, options);
+}
+function extractAttachmentIdsFromUploadPayload(parsed, options) {
+  if (options?.strict) {
+    return extractAttachmentIdsFromUploadPayloadStrict(parsed);
+  }
+  const first = extractFirstAttachmentIdFromUploadPayload(parsed);
+  if (first !== void 0) {
+    if (Array.isArray(parsed)) {
+      const ids = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const item of parsed) {
+        const id = coerceAttachmentId(item);
+        if (id && !seen.has(id)) {
+          seen.add(id);
+          ids.push(id);
+        }
+      }
+      return ids.length > 0 ? ids : [first];
+    }
+    return [first];
+  }
+  throw new Error("Attachment upload returned an unexpected response shape.");
+}
+function extractAttachmentIdsFromUploadPayloadStrict(parsed) {
+  if (typeof parsed === "number" && Number.isFinite(parsed)) {
+    return [String(parsed)];
+  }
+  if (Array.isArray(parsed)) {
+    const ids = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const item of parsed) {
+      if (typeof item !== "number" || !Number.isFinite(item)) {
+        throw new Error("Attachment upload returned an unexpected response shape.");
+      }
+      const id = String(item);
+      if (!seen.has(id)) {
+        seen.add(id);
+        ids.push(id);
+      }
+    }
+    if (ids.length === 0) {
+      throw new Error("Attachment upload returned an empty id list.");
+    }
+    return ids;
+  }
+  throw new Error("Attachment upload returned an unexpected response shape.");
+}
+function extractFirstAttachmentIdFromUploadPayload(parsed) {
+  if (typeof parsed === "number" && Number.isFinite(parsed)) {
+    return String(parsed);
+  }
+  if (typeof parsed === "string" && parsed.trim()) {
+    return parsed.trim();
+  }
+  if (Array.isArray(parsed)) {
+    for (const item of parsed) {
+      const id = coerceAttachmentId(item);
+      if (id) return id;
+    }
+    return void 0;
+  }
+  if (parsed && typeof parsed === "object") {
+    const record = parsed;
+    for (const key of ["id", "attachmentId", "fileId"]) {
+      const id = coerceAttachmentId(record[key]);
+      if (id) return id;
+    }
+  }
+  return void 0;
+}
+function coerceAttachmentId(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  if (typeof value === "string" && value.trim()) {
+    return value.trim();
+  }
+  return void 0;
+}
+var UPLOAD_HEADERS = {
+  "X-Requested-With": "XMLHttpRequest",
+  Accept: "application/json"
+};
+async function uploadGristAttachment(docApi, file, options) {
+  const form = new FormData();
+  const fileName = options?.fileName ?? (file instanceof File && file.name ? file.name : "upload");
+  form.append("upload", file, fileName);
+  let response;
+  try {
+    response = await fetchWithGristAuth(docApi, "/attachments", {
+      method: "POST",
+      body: form,
+      readOnly: false,
+      headers: UPLOAD_HEADERS
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/failed to fetch/i.test(msg)) {
+      const widgetOrigin = typeof globalThis.location !== "undefined" ? globalThis.location.origin : "this widget origin";
+      throw new Error(
+        `Attachment upload was blocked by the Grist host (CORS). The browser could not POST from ${widgetOrigin} to the document API. If upload worked from a dev URL (e.g. ngrok) but fails after deploy, add the new widget URL to your Grist server CORS allowlist (see grist-core#2040).`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+  const raw = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      raw.trim() ? `Attachment upload failed (${response.status}): ${raw.slice(0, 200)}` : `Attachment upload failed (${response.status})`
+    );
+  }
+  const ids = parseGristAttachmentUploadResponseIds(raw);
+  return { ids, firstId: ids[0] };
+}
+
+// src/sdk/runtime/api.ts
+var ACCESS_ERROR = [/access not granted/i, /need higher access level/i, /requires.*full.*access/i, /RPC_ONCALL_ERROR Access/i];
+function isAccessInsufficientError(message2) {
+  return ACCESS_ERROR.some((re) => re.test(message2));
+}
+var message = (err) => err instanceof Error ? err.message : String(err);
+function createGristApi(runtime) {
+  const docApi = () => {
+    if (runtime.getState().connection !== "ready" || typeof grist === "undefined" || !grist.docApi) {
+      throw new Error('Grist is not ready: wait for useGrist().status === "ready".');
+    }
+    return grist.docApi;
+  };
+  const read = async (fn) => {
+    try {
+      const out = await fn();
+      if (runtime.getState().readError) runtime.update({ readError: null });
+      return out;
+    } catch (err) {
+      if (isAccessInsufficientError(message(err))) runtime.update({ readError: message(err) });
+      throw err;
+    }
+  };
+  const write = async (fn) => {
+    runtime.update({ actionStatus: "running", actionError: null });
+    try {
+      const out = await fn();
+      runtime.update({ actionStatus: "idle" });
+      return out;
+    } catch (err) {
+      runtime.update({ actionStatus: "error", actionError: message(err) });
+      throw err;
+    }
+  };
+  const tableOps = (resolve) => ({
+    getTableId: () => resolve().getTableId(),
+    create: ((records, opts) => write(() => resolve().create(records, opts))),
+    update: (records, opts) => write(() => resolve().update(records, opts)),
+    upsert: (records, opts) => write(() => resolve().upsert(records, opts)),
+    destroy: (ids) => write(() => resolve().destroy(ids))
+  });
+  const tables = /* @__PURE__ */ new Map();
+  return {
+    reload: () => runtime.reload(),
+    fetchSelectedTable: (options) => read(async () => {
+      const impl = docApi().fetchSelectedTable ?? grist.fetchSelectedTable;
+      if (!impl) throw new Error("fetchSelectedTable is not available in this Grist version");
+      return await impl({ keepEncoded: false, ...options });
+    }),
+    fetchTable: (tableId) => read(async () => await docApi().fetchTable(tableId)),
+    fetchTableRows: (tableId, options) => read(() => fetchGristTableRows(docApi(), tableId, options ?? {})),
+    listTables: (options) => read(async () => {
+      const all = [...await docApi().listTables()];
+      return options?.includeSystem ? all : all.filter((t) => !t.startsWith("_grist") && !t.startsWith("GristHidden_"));
+    }),
+    listColumns: (tableId, options) => read(async () => {
+      const meta = (await loadColumnMetadataByTable(docApi())).get(tableId);
+      if (!meta) return [];
+      const noise = {
+        excludeId: options?.excludeId ?? true,
+        excludeGristHelpers: options?.excludeGristHelpers ?? true,
+        excludeLoggingColumns: options?.excludeLoggingColumns ?? true,
+        excludeManualSort: options?.excludeManualSort ?? true
+      };
+      return [...meta].filter(([colId, m]) => options?.includeSystem || !isGristNoiseColumn(colId, m, noise)).map(([colId, m]) => ({ colId, type: m.type, label: m.label, isFormula: m.isFormula, formula: m.formula, description: m.description }));
+    }),
+    table: tableOps(() => {
+      if (!grist.selectedTable) throw new Error("grist.selectedTable is not available in this Grist version");
+      return grist.selectedTable;
+    }),
+    getTable: (tableId) => {
+      let ops = tables.get(tableId);
+      if (!ops) {
+        tables.set(
+          tableId,
+          ops = tableOps(() => {
+            if (typeof grist.getTable !== "function") throw new Error("grist.getTable is not available in this Grist version");
+            return grist.getTable(tableId);
+          })
+        );
+      }
+      return ops;
+    },
+    applyActions: (actions, options) => write(() => docApi().applyUserActions(actions, options)),
+    setWidgetOptions: async (options) => {
+      await grist.setOptions(options);
+    },
+    patchWidgetOptions: async (patch) => {
+      const current = await grist.getOptions() ?? {};
+      await grist.setOptions({ ...current, ...patch });
+    },
+    setCursorPosition: async (pos) => {
+      if (!grist.setCursorPos) throw new Error("setCursorPos is not available in this Grist version");
+      await grist.setCursorPos(pos);
+    },
+    setLinkedRowSelection: async (rowIds) => {
+      if (!grist.setSelectedRows) throw new Error("setSelectedRows is not available in this Grist version");
+      await grist.setSelectedRows(rowIds);
+    },
+    getAttachmentUrl: (id, options) => read(() => getAttachmentDownloadUrl(docApi(), id, options)),
+    fetchAttachmentBlob: (id, options) => read(() => fetchAttachmentBlob(docApi(), id, options)),
+    uploadAttachment: (file, options) => write(() => uploadGristAttachment(docApi(), file, options)),
+    fetchWithAuth: (path, init) => read(() => fetchWithGristAuth(docApi(), path, init))
+  };
+}
+
+// src/sdk/helpers/grist-mappings.ts
+function asColumnSpec(entry) {
+  return typeof entry === "string" ? { name: entry } : entry;
+}
+function validateColumnMappings(spec, mappings) {
+  const missing = [];
+  const emptyMultiples = [];
+  if (!spec) return { ok: true, pending: false, missing, emptyMultiples };
+  const m = mappings ?? {};
+  for (const raw of spec) {
+    const col = asColumnSpec(raw);
+    if (col.optional) continue;
+    const value = m[col.name];
+    if (col.allowMultiple) {
+      if (value === void 0) {
+        missing.push(col.name);
+      } else if (!Array.isArray(value) || value.length === 0) {
+        emptyMultiples.push(col.name);
+      }
+    } else {
+      if (value === void 0 || value === null || value === "") missing.push(col.name);
+    }
+  }
+  return {
+    ok: missing.length === 0 && emptyMultiples.length === 0,
+    pending: false,
+    missing,
+    emptyMultiples
+  };
+}
+
+// src/sdk/runtime/derive.ts
+var ACCESS_RANK = { none: 0, "read table": 1, full: 2 };
+function parseAccess(raw) {
+  return raw === "none" || raw === "read table" || raw === "full" ? raw : null;
+}
+function accessLabel(level) {
+  return level === "full" ? "Full document access" : level === "read table" ? "Read selected table" : "No document access";
+}
+function accessDenied(state) {
+  return state.grantedAccess !== null && ACCESS_RANK[state.grantedAccess] < ACCESS_RANK[state.declaredAccess];
+}
+function deriveStatus(state) {
+  switch (state.connection) {
+    case "connecting":
+      return "booting";
+    case "not-embedded":
+    case "unavailable":
+      return "unavailable";
+    case "error":
+      return "error";
+    case "ready":
+      return accessDenied(state) ? "error" : "ready";
+  }
+}
+var MAPPINGS_OK = Object.freeze({ ok: true, pending: false, missing: [], emptyMultiples: [] });
+var MAPPINGS_PENDING = Object.freeze({ ok: true, pending: true, missing: [], emptyMultiples: [] });
+function deriveColumnMappingStatus(columns, mappings) {
+  if (!columns?.length) return MAPPINGS_OK;
+  if (mappings === null) return MAPPINGS_PENDING;
+  return validateColumnMappings(columns, mappings);
+}
+
+// src/sdk/runtime/cells.ts
+var ok = (value) => ({ ok: true, value });
+var bad = (message2) => ({ ok: false, message: message2 });
+function formulaError(value) {
+  if (Array.isArray(value) && value[0] === "E") return String(value[1] ?? "error");
+  if (value && typeof value === "object" && value.constructor?.name === "RaisedException") {
+    return String(value.name ?? "error");
+  }
+  return null;
+}
+function rowIdOf(value) {
+  if (typeof value === "number" && Number.isInteger(value)) return value === 0 ? null : value;
+  if (value && typeof value === "object" && typeof value.rowId === "number") {
+    const id = value.rowId;
+    return id === 0 ? null : id;
+  }
+  if (Array.isArray(value) && value[0] === "R" && typeof value[2] === "number") return value[2] === 0 ? null : value[2];
+  return void 0;
+}
+function idsOf(value) {
+  if (value === null || value === void 0) return [];
+  const list = Array.isArray(value) ? value[0] === "L" ? value.slice(1) : value : value && typeof value === "object" && Array.isArray(value.rowIds) ? value.rowIds : void 0;
+  return list?.every((v) => typeof v === "number") ? list : void 0;
+}
+function checkOne(base, value) {
+  switch (base) {
+    case "Any":
+      return ok(value);
+    case "Text":
+      return value === null || typeof value === "string" ? ok(value ?? "") : bad("not text");
+    case "Numeric":
+      return value === null || typeof value === "number" && Number.isFinite(value) ? ok(value) : bad("not a number");
+    case "Int":
+      return value === null || typeof value === "number" && Number.isInteger(value) ? ok(value) : bad("not an integer");
+    case "Bool":
+      return value === null || typeof value === "boolean" ? ok(value ?? false) : bad("not true or false");
+    case "Date":
+    case "DateTime":
+      if (value === null) return ok(null);
+      if (value instanceof Date && !Number.isNaN(value.getTime())) return ok(value);
+      if (typeof value === "number" && Number.isFinite(value)) return ok(new Date(value * 1e3));
+      return bad("not a date");
+    case "Choice":
+      return value === null || typeof value === "string" ? ok(value) : bad("not a choice");
+    case "ChoiceList": {
+      if (value === null || value === void 0) return ok([]);
+      const list = Array.isArray(value) ? value[0] === "L" ? value.slice(1) : value : void 0;
+      return list?.every((v) => typeof v === "string") ? ok(list) : bad("not a list of choices");
+    }
+    case "Ref": {
+      if (value === null) return ok(null);
+      const id = rowIdOf(value);
+      return id === void 0 ? bad("not a reference") : ok(id);
+    }
+    case "RefList":
+    case "Attachments": {
+      const ids = idsOf(value);
+      return ids === void 0 ? bad(base === "RefList" ? "not a list of references" : "not a list of attachments") : ok(ids);
+    }
+    default:
+      return ok(value);
+  }
+}
+function checkGristCell(type, value) {
+  const error = formulaError(value);
+  if (error) return bad(`formula error (${error})`);
+  const bases = (type ?? "Any").split(",").map((t) => t.trim().split(":")[0]).filter(Boolean);
+  if (bases.length === 0 || bases.includes("Any")) return ok(value === void 0 ? null : value);
+  let first = null;
+  for (const base of bases) {
+    const check = checkOne(base, value);
+    if (check.ok) return check;
+    first ?? (first = check);
+  }
+  return first;
+}
+var nameOf = (c) => typeof c === "string" ? c : c.name;
+var typeOf = (c) => typeof c === "string" ? void 0 : c.type;
+var isOptional = (c) => typeof c === "object" && c.optional === true;
+function mapAndCheck(record, columns, mappings, schema) {
+  if (!record) return { value: null, issues: [] };
+  if (!columns?.length) return { value: record, issues: [] };
+  if (mappings === null) return { value: null, issues: [] };
+  const rowId = typeof record.id === "number" ? record.id : 0;
+  const out = { id: record.id };
+  const issues = [];
+  for (const col of columns) {
+    const name = nameOf(col);
+    const real = mappings[name];
+    const take = (raw) => {
+      const check = checkGristCell(typeOf(col), raw);
+      if (check.ok) return check.value;
+      issues.push({ rowId, column: name, message: check.message, value: raw });
+      return null;
+    };
+    if (Array.isArray(real) && real.length > 0) out[name] = real.map((r) => take(record[r]));
+    else if (typeof real === "string" && real) out[name] = take(record[real]);
+    else if (!isOptional(col)) return { value: null, issues: [] };
+  }
+  if (schema) {
+    const result = schema["~standard"].validate(out);
+    if (result instanceof Promise) {
+      issues.push({ rowId, column: "", message: "the schema validates asynchronously; useGrist() needs a synchronous one", value: out });
+    } else if ("issues" in result && result.issues) {
+      for (const issue of result.issues) {
+        const key = issue.path?.[0];
+        const column = key === void 0 ? "" : String(typeof key === "object" ? key.key : key);
+        issues.push({ rowId, column, message: issue.message, value: column ? out[column] : out });
+      }
+    } else if ("value" in result) {
+      return { value: result.value, issues };
+    }
+  }
+  return { value: out, issues };
+}
 
 // src/sdk/helpers/grist-widget-interaction.ts
 function parseGristWidgetLinkingInfo(raw) {
@@ -59,152 +869,363 @@ function normalizeWidgetInteraction(interaction) {
   };
 }
 
-// src/sdk/internal/subscriptions.ts
-var GristEvent = class {
-  constructor(bindOnce) {
-    this.bindOnce = bindOnce;
+// src/sdk/runtime/host.ts
+var HostStream = class {
+  constructor(bind) {
+    this.bind = bind;
     this.listeners = /* @__PURE__ */ new Set();
-    this.hasValue = false;
-    this.bind = null;
+    this.bound = false;
+    this.has = false;
   }
   subscribe(listener) {
     this.listeners.add(listener);
-    if (!this.bind) {
-      this.bind = () => {
-        this.bind = () => {
-        };
-        try {
-          this.bindOnce((value) => {
-            this.hasValue = true;
-            this.last = value;
-            for (const l of this.listeners) l(value);
-          });
-        } catch (err) {
-          if (typeof console !== "undefined") {
-            console.error("[lib/grist] failed to subscribe to Grist event:", err);
-          }
-        }
-      };
-      this.bind();
-    }
-    if (this.hasValue && this.last !== void 0) {
-      listener(this.last);
+    if (!this.bound) {
+      this.bound = true;
+      try {
+        this.bind((value) => this.emit(value));
+      } catch (err) {
+        console.error("[grist-widget-sdk] could not subscribe to a Grist event:", err);
+      }
     }
+    if (this.has) listener(this.last);
     return () => {
       this.listeners.delete(listener);
     };
   }
-  /** Last cached value (or `undefined` if no event has fired yet). */
   peek() {
     return this.last;
   }
-  /** True once at least one event has fired. */
-  get ready() {
-    return this.hasValue;
-  }
-  /**
-   * Test helper: fan out a payload without calling `grist.on*`.
-   * Used to simulate hosts that reuse one record object and mutate it in place.
-   */
-  deliverForTests(value) {
-    this.hasValue = true;
+  /** Tests: deliver a value as if Grist had sent it. */
+  emit(value) {
+    this.has = true;
     this.last = value;
-    for (const l of this.listeners) l(value);
+    for (const l of [...this.listeners]) l(value);
   }
-  /**
-   * Test helper: forget the bound state and cached value. Lets a test swap
-   * `window.grist` (e.g. via the emulator's `dispose()` + `createGristEmulator()`)
-   * and re-bind cleanly on the next subscribe.
-   */
-  _resetForTests() {
+  /** Tests: forget the binding, so a new `window.grist` binds afresh. */
+  reset() {
     this.listeners.clear();
-    this.hasValue = false;
+    this.bound = false;
+    this.has = false;
     this.last = void 0;
-    this.bind = null;
   }
 };
-var recordEvent = new GristEvent((emit) => {
-  const deliver = (record, mappings) => {
-    emit({ record, mappings });
-  };
-  grist.onRecord(
-    (record, mappings) => {
-      deliver(record, mappings ?? null);
-    },
-    { keepEncoded: false }
-  );
+var asMappings = (m) => m && typeof m === "object" ? m : null;
+var recordStream = new HostStream((emit) => {
+  grist.onRecord((record, mappings) => emit({ record, mappings: asMappings(mappings) }), { keepEncoded: false });
   const fetchSelectedRecord = grist.fetchSelectedRecord ?? grist.docApi?.fetchSelectedRecord;
-  if (typeof grist.on !== "function" || typeof fetchSelectedRecord !== "function") {
-    return;
-  }
+  if (typeof grist.on !== "function" || typeof fetchSelectedRecord !== "function") return;
   let lastRowId;
   grist.on("message", async (msg) => {
-    if (!msg || typeof msg !== "object") return;
     const host = msg;
-    if (!host.tableId || typeof host.rowId !== "number") return;
-    if (host.rowId === lastRowId) return;
+    if (!host?.tableId || typeof host.rowId !== "number" || host.rowId === lastRowId) return;
     lastRowId = host.rowId;
     try {
       const record = await fetchSelectedRecord(host.rowId, { keepEncoded: false });
-      deliver(record, recordEvent.peek()?.mappings ?? null);
+      emit({ record, mappings: recordStream.peek()?.mappings ?? null });
     } catch (err) {
-      if (typeof console !== "undefined") {
-        console.error("[grist-widget-sdk] fetchSelectedRecord on cursor message failed:", err);
-      }
+      console.error("[grist-widget-sdk] fetchSelectedRecord on a cursor move failed:", err);
     }
   });
 });
-var recordsEvent = new GristEvent((emit) => {
-  grist.onRecords(
-    (records, mappings) => {
-      emit({ records, mappings: mappings ?? null });
-    },
-    { keepEncoded: false, format: "rows" }
-  );
+var recordsStream = new HostStream((emit) => {
+  grist.onRecords((records, mappings) => emit({ records, mappings: asMappings(mappings) }), {
+    keepEncoded: false,
+    format: "rows"
+  });
 });
-var optionsEvent = new GristEvent((emit) => {
-  grist.onOptions((options, interaction) => {
-    const normalized = normalizeWidgetInteraction(
-      interaction ?? null
-    );
-    emit({
+var optionsStream = new HostStream((emit) => {
+  grist.onOptions(
+    (options, interaction) => emit({
       options: options ? { ...options } : null,
-      interaction: normalized
-    });
-  });
+      interaction: normalizeWidgetInteraction(interaction ?? null)
+    })
+  );
 });
-var newRecordEvent = new GristEvent((emit) => {
+var newRecordStream = new HostStream((emit) => {
   if (typeof grist.onNewRecord !== "function") return;
-  grist.onNewRecord((mappings) => {
-    emit({ mappings: mappings ?? null });
-  });
+  grist.onNewRecord((mappings) => emit({ mappings: asMappings(mappings) }));
 });
-function resetGristEventsForTests() {
-  recordEvent._resetForTests();
-  recordsEvent._resetForTests();
-  optionsEvent._resetForTests();
-  newRecordEvent._resetForTests();
-}
-
-// src/sdk/internal/embedded-handshake-manager.ts
-var embedded = null;
-function resetEmbeddedHandshakeManagerForTests() {
-  if (embedded) {
-    embedded.manager.stop();
-    embedded = null;
-  }
-}
+var messageStream = new HostStream((emit) => {
+  if (typeof grist.on !== "function") return;
+  grist.on("message", (msg) => emit(msg));
+});
+var ALL_STREAMS = [recordStream, recordsStream, optionsStream, newRecordStream, messageStream];
 
-// src/sdk/internal/ready-singleton.ts
-var inFlight = null;
+// src/sdk/runtime/ready.ts
+var ACCESS_RANK2 = {
+  none: 0,
+  "read table": 1,
+  full: 2
+};
+var inFlight2 = null;
 var lastAccess = null;
 var lastColumnNames = null;
-function resetGristReadySingleton() {
-  inFlight = null;
+function columnNamesOf(columns) {
+  return new Set((columns ?? []).map((c) => typeof c === "string" ? c : c.name));
+}
+function shouldReinit(next, nextColumns) {
+  if (!lastAccess) return true;
+  if (ACCESS_RANK2[next] > ACCESS_RANK2[lastAccess]) return true;
+  for (const name of nextColumns) {
+    if (!lastColumnNames?.has(name)) return true;
+  }
+  return false;
+}
+function ensureGristReady(payload) {
+  const access = payload.requiredAccess ?? "read table";
+  const columns = columnNamesOf(payload.columns);
+  if (inFlight2 && !shouldReinit(access, columns)) return inFlight2;
+  lastAccess = access;
+  lastColumnNames = columns;
+  const next = Promise.resolve().then(() => {
+    const result = grist.ready(payload);
+    return result instanceof Promise ? result : Promise.resolve();
+  });
+  inFlight2 = next.catch((err) => {
+    inFlight2 = null;
+    lastAccess = null;
+    lastColumnNames = null;
+    throw err;
+  });
+  return inFlight2;
+}
+function resetGristReady() {
+  inFlight2 = null;
   lastAccess = null;
   lastColumnNames = null;
 }
-var resetGristReadyCacheForTests = resetGristReadySingleton;
+
+// src/sdk/helpers/grist-theme-payload.ts
+function parseGristThemePayload(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const raw = payload;
+  const top = raw.theme;
+  if (top === "light" || top === "dark") return top;
+  if (top && typeof top === "object") {
+    const appearance = top.appearance;
+    if (appearance === "light" || appearance === "dark") return appearance;
+  }
+  return null;
+}
+
+// src/sdk/runtime/runtime.ts
+var READY_TIMEOUT_MS = 3e4;
+function initialRuntimeState(options = {}) {
+  return {
+    connection: "connecting",
+    connectionError: null,
+    declaredAccess: options.requiredAccess ?? "read table",
+    grantedAccess: null,
+    record: null,
+    records: null,
+    isNewRecord: false,
+    mappings: null,
+    widgetOptions: null,
+    interaction: null,
+    currentTableId: null,
+    theme: null,
+    actionStatus: "idle",
+    actionError: null,
+    readError: null,
+    mapBackSkipped: []
+  };
+}
+function isEmbedded() {
+  try {
+    return typeof window !== "undefined" && window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+var hasGrist = () => typeof grist !== "undefined" && grist !== null;
+function createGristRuntime(options = {}) {
+  let state = initialRuntimeState(options);
+  const listeners = /* @__PURE__ */ new Set();
+  let starts = 0;
+  let stopStreams = null;
+  let attempt = 0;
+  const update = (patch) => {
+    let changed = false;
+    for (const key of Object.keys(patch)) {
+      if (!Object.is(state[key], patch[key])) changed = true;
+    }
+    if (!changed) return;
+    state = { ...state, ...patch };
+    for (const l of [...listeners]) l();
+  };
+  const payload = {
+    requiredAccess: options.requiredAccess ?? "read table",
+    columns: options.columns ?? [],
+    ...options.allowSelectBy !== void 0 ? { allowSelectBy: options.allowSelectBy } : {},
+    ...options.hasCustomOptions !== void 0 ? { hasCustomOptions: options.hasCustomOptions } : {},
+    ...options.onEditOptions ? { onEditOptions: options.onEditOptions } : {}
+  };
+  const refreshTable = async () => {
+    try {
+      const tableId = await grist.selectedTable?.getTableId();
+      if (tableId) update({ currentTableId: tableId });
+    } catch {
+    }
+  };
+  const refreshMappings = async () => {
+    if (typeof grist.sectionApi?.mappings !== "function") return;
+    try {
+      const mappings = await grist.sectionApi.mappings();
+      if (state.mappings === null) update({ mappings: mappings ?? {} });
+    } catch {
+    }
+  };
+  const connect = async () => {
+    const mine = ++attempt;
+    update({ connection: "connecting", connectionError: null });
+    let timer;
+    try {
+      await Promise.race([
+        ensureGristReady(payload),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`Grist did not answer grist.ready() within ${READY_TIMEOUT_MS / 1e3} s.`)), READY_TIMEOUT_MS);
+        })
+      ]);
+    } catch (err) {
+      if (mine === attempt) update({ connection: "error", connectionError: err instanceof Error ? err.message : String(err) });
+      return;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (mine !== attempt) return;
+    update({ connection: "ready" });
+    await Promise.all([refreshMappings(), refreshTable()]);
+  };
+  const listen = () => {
+    const offs = [
+      // Copies: a host may reuse one record object and mutate it in place.
+      recordStream.subscribe(
+        ({ record, mappings }) => update({
+          record: record ? { ...record } : null,
+          isNewRecord: false,
+          ...mappings ? { mappings } : {}
+        })
+      ),
+      recordsStream.subscribe(({ records, mappings }) => {
+        update({ records: records.map((r) => ({ ...r })), ...mappings ? { mappings } : {} });
+        void refreshTable();
+      }),
+      optionsStream.subscribe(
+        ({ options: widgetOptions, interaction }) => update({
+          widgetOptions,
+          interaction,
+          grantedAccess: parseAccess(interaction?.access_level) ?? state.grantedAccess
+        })
+      ),
+      newRecordStream.subscribe(({ mappings }) => update({ isNewRecord: true, ...mappings ? { mappings } : {} })),
+      messageStream.subscribe((msg) => {
+        const theme = parseGristThemePayload(msg);
+        if (theme) update({ theme });
+      })
+    ];
+    return () => offs.forEach((off) => off());
+  };
+  const begin = () => {
+    if (!isEmbedded()) return update({ connection: "not-embedded" });
+    if (!hasGrist()) {
+      if (typeof document !== "undefined" && document.readyState !== "complete" && typeof window !== "undefined") {
+        window.addEventListener("load", () => hasGrist() ? begin() : update({ connection: "unavailable" }), { once: true });
+        return;
+      }
+      return update({ connection: "unavailable" });
+    }
+    stopStreams ?? (stopStreams = listen());
+    void connect();
+  };
+  return {
+    options,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start() {
+      if (starts++ === 0) begin();
+      return () => {
+        if (--starts > 0) return;
+        stopStreams?.();
+        stopStreams = null;
+      };
+    },
+    async reload() {
+      if (!hasGrist() || !isEmbedded()) return begin();
+      resetGristReady();
+      update({ mappings: null });
+      stopStreams ?? (stopStreams = listen());
+      await connect();
+    },
+    update
+  };
+}
+
+// src/sdk/use-grist.ts
+var GristContext = (0, import_react.createContext)(null);
+GristContext.displayName = "GristContext";
+function useGristRuntime() {
+  return (0, import_react.useContext)(GristContext);
+}
+function newConnection(options) {
+  const runtime = createGristRuntime(options);
+  return { runtime, api: createGristApi(runtime) };
+}
+var pageConnection = null;
+function resetGristForTests() {
+  pageConnection = null;
+  resetGristReady();
+  for (const s of ALL_STREAMS) s.reset();
+}
+var GristContextProvider = GristContext.Provider;
+var serverState = () => initialRuntimeState();
+function useGristState(connection) {
+  const { runtime } = connection;
+  (0, import_react.useEffect)(() => runtime.start(), [runtime]);
+  return (0, import_react.useSyncExternalStore)(runtime.subscribe, runtime.getState, serverState);
+}
+var NO_ISSUES = Object.freeze([]);
+function useMapped(state, options) {
+  const { record, records, mappings } = state;
+  const { columns, schema } = options;
+  return (0, import_react.useMemo)(() => {
+    const issues = [];
+    const rows = records && (columns?.length ? mappings !== null : true) ? records.map((r) => {
+      const out = mapAndCheck(r, columns, mappings, schema);
+      issues.push(...out.issues);
+      return out.value;
+    }) : null;
+    const selected = mapAndCheck(record, columns, mappings, schema);
+    if (record && !records?.some((r) => r.id === record.id)) issues.push(...selected.issues);
+    const mappedRecords = rows && rows.every((r) => r !== null) ? rows : null;
+    return { record: selected.value, records: mappedRecords, issues: issues.length ? issues : NO_ISSUES };
+  }, [record, records, mappings, columns, schema]);
+}
+var EMPTY_MAPPINGS = Object.freeze({});
+var DETACHED = (() => {
+  const state = initialRuntimeState();
+  const runtime = {
+    options: {},
+    getState: () => state,
+    subscribe: () => () => {
+    },
+    start: () => () => {
+    },
+    reload: async () => {
+    },
+    update: () => {
+    }
+  };
+  return { runtime, api: createGristApi(runtime) };
+})();
+function useNearestGristState() {
+  const connection = (0, import_react.useContext)(GristContext);
+  const state = useGristState(connection ?? DETACHED);
+  const { issues } = useMapped(state, (connection ?? DETACHED).runtime.options);
+  return { connection, state, cellIssues: issues };
+}
 
 // src/emulator/api/command-api.ts
 function createCommandApiImpl(bus) {
@@ -252,36 +1273,7 @@ function createGristApiImpl() {
   };
 }
 
-// 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
-]);
+// src/emulator/core/display-helpers.ts
 function inferDisplayHelpersByRef(columns) {
   const out = {};
   const helperColumns = Object.entries(columns).filter(
@@ -482,7 +1474,7 @@ function evaluateRowFormulas(state, table, row) {
       try {
         row[colId] = col.formulaFn(row, { table, document: state });
       } catch (err) {
-        row[colId] = formulaError(err);
+        row[colId] = formulaError2(err);
       }
     }
   }
@@ -569,9 +1561,9 @@ function syncRefListDisplayHelpers(state, table, row) {
     row[helperColId] = labels;
   }
 }
-function formulaError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  return ["E", "Error", message];
+function formulaError2(err) {
+  const message2 = err instanceof Error ? err.message : String(err);
+  return ["E", "Error", message2];
 }
 function synthesizeTablesMeta(state) {
   const ids = [];
@@ -653,8 +1645,8 @@ function synthesizeTablesColumnMeta(state) {
 
 // src/emulator/core/action-engine.ts
 var EmulatorActionError = class extends Error {
-  constructor(action, message) {
-    super(message);
+  constructor(action, message2) {
+    super(message2);
     this.action = action;
     this.name = "EmulatorActionError";
   }
@@ -955,8 +1947,8 @@ function normalizeRefListValue(value) {
     return ["L", ...toIdList(value)];
   }
   if (typeof value === "string") {
-    const tokens = value.split(",").map((t) => t.trim()).filter(Boolean);
-    return ["L", ...toIdList(tokens)];
+    const tokens2 = value.split(",").map((t) => t.trim()).filter(Boolean);
+    return ["L", ...toIdList(tokens2)];
   }
   if (value && typeof value === "object" && Array.isArray(value.rowIds)) {
     return ["L", ...toIdList(value.rowIds)];
@@ -1094,8 +2086,9 @@ function createWidgetApiImpl(state, bus) {
     async getOptions() {
       return Object.keys(state.widgetOptions).length > 0 ? { ...state.widgetOptions } : null;
     },
+    // Replaces every option, as Grist's WidgetAPI.setOptions does.
     async setOptions(options) {
-      state.widgetOptions = { ...state.widgetOptions, ...options };
+      state.widgetOptions = { ...options };
       emit();
     },
     async clearOptions() {
@@ -1161,157 +2154,6 @@ function buildGristThemeHostMessage(appearance, options) {
   };
 }
 
-// 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];
@@ -1367,14 +2209,6 @@ function createInlineTransport(options) {
           logErr(err);
         }
       }
-      lastRecord = { record: null, mappings };
-      for (const [cb] of recordCbs) {
-        try {
-          cb(null, mappings);
-        } catch (err) {
-          logErr(err);
-        }
-      }
       return;
     }
     if (rowId === null) {
@@ -1669,8 +2503,8 @@ function createInlineTransport(options) {
     fireOptions() {
       pushOptions();
     },
-    fireTheme(message) {
-      bus.emit({ type: "theme-change", message });
+    fireTheme(message2) {
+      bus.emit({ type: "theme-change", message: message2 });
     },
     emitInitialState() {
       pushOptions();
@@ -1713,57 +2547,57 @@ function installFakeIframeContext(target) {
 }
 
 // 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(),
+var import_zod = require("zod");
+var emulatorRowSchema = import_zod.z.object({ id: import_zod.z.number() }).catchall(import_zod.z.unknown());
+var formulaKindSchema = import_zod.z.enum(["computed", "trigger", "none", "empty_slot"]);
+var replicaColumnSchema = import_zod.z.object({
+  colRef: import_zod.z.number().optional(),
+  type: import_zod.z.string().optional(),
+  label: import_zod.z.string().optional(),
+  parentPos: import_zod.z.number().optional(),
+  isFormula: import_zod.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()
+  formula: import_zod.z.string().optional(),
+  description: import_zod.z.string().optional(),
+  widgetOptions: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  displayColRef: import_zod.z.number().optional(),
+  visibleColRef: import_zod.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()
+var replicaTableSchema = import_zod.z.object({
+  label: import_zod.z.string().optional(),
+  columns: import_zod.z.record(import_zod.z.string(), replicaColumnSchema).optional(),
+  rows: import_zod.z.array(emulatorRowSchema).optional(),
+  rowCount: import_zod.z.number().optional(),
+  dataOmitted: import_zod.z.boolean().optional(),
+  dataOmittedReason: import_zod.z.string().optional(),
+  error: import_zod.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()
+var replicaSelectionSchema = import_zod.z.object({
+  tableId: import_zod.z.string().optional(),
+  rowId: import_zod.z.union([import_zod.z.number(), import_zod.z.literal("new"), import_zod.z.null()]).optional(),
+  mappings: import_zod.z.unknown().nullable().optional(),
+  cursor: import_zod.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()
+var replicaWidgetConfigurationSchema = import_zod.z.object({
+  requiredAccess: import_zod.z.string().optional(),
+  columns: import_zod.z.unknown().optional(),
+  allowSelectBy: import_zod.z.boolean().optional(),
+  hasCustomOptions: import_zod.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()
+var replicaAccessTokenSchema = import_zod.z.object({
+  token: import_zod.z.string(),
+  baseUrl: import_zod.z.string(),
+  ttlMsecs: import_zod.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),
+var replicaDocumentSchema = import_zod.z.object({
+  generatedAt: import_zod.z.string(),
+  source: import_zod.z.string().optional(),
+  docName: import_zod.z.string().optional(),
+  mode: import_zod.z.enum(["schema-only", "schema+samples", "schema+data"]).optional(),
+  tables: import_zod.z.record(import_zod.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(),
+  widgetOptions: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  widgetInteraction: import_zod.z.unknown().optional(),
   configuration: replicaWidgetConfigurationSchema.optional(),
   accessToken: replicaAccessTokenSchema.nullable().optional()
 }).strict().refine((value) => Object.keys(value.tables).length > 0, {
@@ -1794,34 +2628,21 @@ function createGristEmulator(options) {
   const state = createDocument({
     ...validatedDocument,
     widgetOptions: options.widgetOptions ?? validatedDocument.widgetOptions,
-    widgetInteraction: options.widgetInteraction ?? validatedDocument.widgetInteraction ?? { access_level: "read table" }
+    // No access_level by default: the emulator then grants the access the
+    // widget asks for in grist.ready(), as a user accepting it in Grist would.
+    widgetInteraction: options.widgetInteraction ?? validatedDocument.widgetInteraction ?? {}
   });
   const bus = createEventBus();
   const api = createApiBundle(state, bus);
-  const transportKind = options.transport?.kind ?? "inline";
-  let transport;
-  let grist2;
-  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;
-    grist2 = inline.grist;
-  }
+  const inline = createInlineTransport({
+    state,
+    bus,
+    api,
+    initialTheme: options.initialTheme,
+    target: options.transport?.target
+  });
+  const transport = inline;
+  const grist2 = inline.grist;
   function apply(actions) {
     return applyUserActions(state, bus, actions);
   }
@@ -1963,18 +2784,14 @@ var presets = {
 // src/emulator/testing/render-with-grist.tsx
 function renderWithGrist(ui, options = {}) {
   fakeIframeContext();
-  resetGristEventsForTests();
-  resetGristReadyCacheForTests();
-  resetEmbeddedHandshakeManagerForTests();
+  resetGristForTests();
   const emulator = options.existing ?? createGristEmulator(options.emulator ?? { document: presets.blank() });
-  const result = (0, import_react.render)(ui, options);
+  const result = (0, import_react2.render)(ui, options);
   const originalUnmount = result.unmount;
   result.unmount = () => {
     originalUnmount();
     if (!options.existing) emulator.dispose();
-    resetGristReadyCacheForTests();
-    resetGristEventsForTests();
-    resetEmbeddedHandshakeManagerForTests();
+    resetGristForTests();
   };
   return Object.assign(result, { emulator });
 }
@@ -1990,6 +2807,880 @@ function fakeIframeContext() {
   }
 }
 
+// src/emulator/testing/smoke-test-widget.tsx
+var import_react9 = require("react");
+var import_react10 = require("@testing-library/react");
+
+// src/app/mount-grist-widget.tsx
+var import_react8 = require("react");
+var import_client = require("react-dom/client");
+
+// src/sdk/components/grist-widget-provider.tsx
+var import_react3 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function GristWidgetProvider({ options, children }) {
+  const [connection] = (0, import_react3.useState)(() => newConnection(options));
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GristContextProvider, { value: connection, children });
+}
+
+// src/sdk/components/grist-boundary.tsx
+var import_react4 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var shellStyle = {
+  alignItems: "center",
+  background: "var(--background)",
+  boxSizing: "border-box",
+  color: "var(--foreground)",
+  display: "flex",
+  flexDirection: "column",
+  justifyContent: "center",
+  minHeight: "100%",
+  padding: "clamp(16px, 5vh, 32px)",
+  width: "100%"
+};
+var cardStyle = {
+  background: "var(--card)",
+  border: "1px solid var(--border)",
+  borderRadius: 12,
+  boxShadow: "0 1px 3px rgb(0 0 0 / 0.12)",
+  maxWidth: 420,
+  padding: "20px 22px",
+  textAlign: "center",
+  width: "100%"
+};
+var titleStyle = {
+  color: "var(--foreground)",
+  fontSize: 15,
+  fontWeight: 600,
+  lineHeight: 1.35,
+  margin: 0
+};
+var messageStyle = {
+  color: "var(--muted-foreground)",
+  fontSize: 14,
+  lineHeight: 1.5,
+  margin: "10px 0 0"
+};
+var buttonStyle = {
+  background: "var(--background)",
+  border: "1px solid var(--border)",
+  borderRadius: 8,
+  color: "var(--foreground)",
+  cursor: "pointer",
+  fontSize: 13,
+  fontWeight: 500,
+  marginTop: 16,
+  padding: "8px 14px"
+};
+function GristBoundaryScreen({
+  title,
+  message: message2,
+  tone = "default",
+  showRetry = false,
+  actions,
+  retryLabel = "Try reconnecting",
+  retryBusyLabel = "Reconnecting\u2026"
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: shellStyle, role: tone === "error" ? "alert" : "status", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: cardStyle, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { style: titleStyle, children: title }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { style: messageStyle, children: message2 }),
+    showRetry && actions ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "button",
+      {
+        disabled: actions.isReloading,
+        onClick: () => void actions.reload(),
+        style: {
+          ...buttonStyle,
+          cursor: actions.isReloading ? "not-allowed" : "pointer",
+          opacity: actions.isReloading ? 0.7 : 1
+        },
+        type: "button",
+        children: actions.isReloading ? retryBusyLabel : retryLabel
+      }
+    ) : null
+  ] }) });
+}
+function boundaryScreen(state, columns) {
+  switch (state.connection) {
+    case "connecting":
+      return { title: "Connecting to Grist", message: "Asking Grist for the access this widget needs\u2026" };
+    case "not-embedded":
+      return {
+        title: "Open inside Grist",
+        message: "Open this page as a custom widget inside a Grist document (it runs in an embedded panel, not on its own).",
+        retry: true
+      };
+    case "unavailable":
+      return {
+        title: "Open inside Grist",
+        message: "The Grist plugin did not load. Reload the page, or open this URL as a custom widget inside a Grist document.",
+        retry: true
+      };
+    case "error":
+      return {
+        title: "Something went wrong",
+        message: state.connectionError ?? "Something went wrong connecting to Grist. Try again, or reload the page.",
+        tone: "error",
+        retry: true
+      };
+  }
+  if (accessDenied(state)) {
+    return {
+      title: "More access needed",
+      message: `Set Access level to at least "${accessLabel(state.declaredAccess)}" in the Custom widget settings.`,
+      tone: "error",
+      retry: true
+    };
+  }
+  const mapping = deriveColumnMappingStatus(columns, state.mappings);
+  if (mapping.pending) return { title: "Connecting to Grist", message: "Waiting for Grist to report the column mapping\u2026" };
+  if (!mapping.ok) {
+    return {
+      title: "Map your columns",
+      message: "Open the widget settings in Grist (Creator Panel \u2192 Custom widget) and connect each required column to your table."
+    };
+  }
+  return null;
+}
+function GristBoundary({ children }) {
+  const connection = useGristRuntime();
+  if (!connection) throw new Error("<GristBoundary> must be used inside <GristWidgetProvider> (mountGristWidget renders both).");
+  const state = useGristState(connection);
+  const [isReloading, setIsReloading] = (0, import_react4.useState)(false);
+  const reload = (0, import_react4.useCallback)(async () => {
+    setIsReloading(true);
+    try {
+      await connection.runtime.reload();
+    } catch (err) {
+      console.error("[grist-widget-sdk] reload failed:", err);
+    } finally {
+      setIsReloading(false);
+    }
+  }, [connection]);
+  const screen2 = boundaryScreen(state, connection.runtime.options.columns);
+  if (!screen2) return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+    GristBoundaryScreen,
+    {
+      title: screen2.title,
+      message: screen2.message,
+      tone: screen2.tone,
+      showRetry: screen2.retry,
+      actions: { reload, isReloading },
+      retryLabel: screen2.tone === "error" ? "Try again" : "Try reconnecting",
+      retryBusyLabel: screen2.tone === "error" ? "Retrying\u2026" : "Reconnecting\u2026"
+    }
+  );
+}
+
+// src/app/chrome/tokens.ts
+var token = (name, fallback) => `var(--${name}, ${fallback})`;
+var tokens = {
+  background: token("background", "#ffffff"),
+  foreground: token("foreground", "#0a0a0a"),
+  card: token("card", "#ffffff"),
+  mutedForeground: token("muted-foreground", "#737373"),
+  border: token("border", "#e5e5e5"),
+  primary: token("primary", "#171717"),
+  primaryForeground: token("primary-foreground", "#fafafa"),
+  destructive: token("destructive", "#dc2626"),
+  radius: token("radius", "0.625rem")
+};
+var pageStyle = {
+  boxSizing: "border-box",
+  display: "flex",
+  flexDirection: "column",
+  justifyContent: "center",
+  maxWidth: "28rem",
+  minHeight: "100%",
+  margin: "0 auto",
+  padding: "4rem 1.5rem",
+  color: tokens.foreground,
+  font: "inherit"
+};
+var eyebrowStyle = {
+  margin: "0 0 0.5rem",
+  textAlign: "center",
+  fontSize: "0.875rem",
+  fontWeight: 500,
+  color: tokens.mutedForeground
+};
+var headingStyle = {
+  margin: 0,
+  textAlign: "center",
+  fontSize: "1.5rem",
+  fontWeight: 600,
+  letterSpacing: "-0.01em"
+};
+var leadStyle = {
+  margin: "0.75rem auto 2rem",
+  maxWidth: "24rem",
+  textAlign: "center",
+  fontSize: "0.875rem",
+  lineHeight: 1.5,
+  color: tokens.mutedForeground
+};
+var cardStyle2 = {
+  boxSizing: "border-box",
+  marginBottom: "1rem",
+  padding: "1.25rem",
+  border: `1px solid ${tokens.border}`,
+  borderRadius: tokens.radius,
+  background: tokens.card
+};
+var cardTitleStyle = {
+  margin: "0 0 0.375rem",
+  fontSize: "1rem",
+  fontWeight: 600
+};
+var cardTextStyle = {
+  margin: 0,
+  fontSize: "0.875rem",
+  lineHeight: 1.5,
+  color: tokens.mutedForeground
+};
+var codeStyle = {
+  fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+  fontSize: "0.8125rem",
+  color: tokens.foreground
+};
+
+// src/app/chrome/widget-title.ts
+function widgetTitle() {
+  const title = typeof document === "undefined" ? "" : document.title.trim();
+  return title || "Grist widget";
+}
+
+// src/app/chrome/local-dev-page.tsx
+var import_jsx_runtime3 = require("react/jsx-runtime");
+function LocalDevPage() {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("main", { style: pageStyle, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: eyebrowStyle, children: [
+      widgetTitle(),
+      " \xB7 local dev"
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h1", { style: headingStyle, children: "Not embedded in Grist" }),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("p", { style: leadStyle, children: "This is the local dev server: there's no Grist here to render the widget against." }),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("section", { style: cardStyle2, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { style: cardTitleStyle, children: "Check it against real Grist" }),
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: cardTextStyle, children: [
+        "Push to ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "dev" }),
+        ", then open its ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "/dev/" }),
+        " URL in a custom widget of a real Grist document: later pushes reload it there within seconds. Locally,",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "pnpm test" }),
+        " runs the widget against an emulated Grist."
+      ] })
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("section", { style: cardStyle2, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { style: cardTitleStyle, children: "Starting from another example?" }),
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: cardTextStyle, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "npx create-grist-widget list" }),
+        " shows the examples, and",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "npx create-grist-widget use <example>" }),
+        " swaps this widget for one."
+      ] })
+    ] })
+  ] });
+}
+
+// src/app/chrome/release-page.tsx
+var import_react6 = require("react");
+
+// src/app/deploy-path.ts
+var VERSION_SEGMENT = /^v(\d+\.\d+\.\d+(?:-[\w.]+)?)$/;
+function parseDeployPath(pathname) {
+  const segments = pathname.replace(/\/+$/, "").split("/");
+  const last = segments[segments.length - 1] ?? "";
+  let channel = null;
+  if (last === "latest") channel = { kind: "latest" };
+  else if (last === "dev") channel = { kind: "dev" };
+  else {
+    const match = VERSION_SEGMENT.exec(last);
+    if (match) channel = { kind: "version", version: match[1] };
+  }
+  if (!channel) return { channel: { kind: "latest" }, basePath: withTrailingSlash(pathname) };
+  return { channel, basePath: withTrailingSlash(segments.slice(0, -1).join("/")) };
+}
+function deployChannelLabel(channel) {
+  return channel.kind === "version" ? `v${channel.version}` : channel.kind;
+}
+function withTrailingSlash(path) {
+  return path.endsWith("/") ? path : `${path}/`;
+}
+
+// src/app/released-versions.ts
+var import_react5 = require("react");
+function useReleasedVersions(pathname = typeof window === "undefined" ? "/" : window.location.pathname) {
+  const url = `${parseDeployPath(pathname).basePath}versions.json`;
+  const [result, setResult] = (0, import_react5.useState)({ versions: null, error: false });
+  (0, import_react5.useEffect)(() => {
+    let cancelled = false;
+    fetch(url, { cache: "no-store" }).then((res) => res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))).then((data) => {
+      if (cancelled) return;
+      if (!Array.isArray(data)) throw new Error("versions.json is not an array");
+      setResult({ versions: data, error: false });
+    }).catch(() => {
+      if (!cancelled) setResult({ versions: null, error: true });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [url]);
+  return result;
+}
+
+// src/app/chrome/release-page.tsx
+var import_jsx_runtime4 = require("react/jsx-runtime");
+function ReleasePage({ channel }) {
+  const label = deployChannelLabel(channel);
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("main", { style: pageStyle, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("p", { style: eyebrowStyle, children: [
+      widgetTitle(),
+      " \xB7 ",
+      label
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("h1", { style: headingStyle, children: "Grist isn't loaded here" }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("p", { style: leadStyle, children: [
+      "This is the ",
+      /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("code", { style: codeStyle, children: label }),
+      " build, opened outside Grist. Hover a version to see when it was released."
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ChannelLinks, { current: channel }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(InstallUrl, {})
+  ] });
+}
+function ChannelLinks({ current }) {
+  const { basePath } = parseDeployPath(window.location.pathname);
+  const { versions } = useReleasedVersions();
+  const isCurrent = (channel) => channel.kind === current.kind && (channel.kind !== "version" || current.kind === "version" && channel.version === current.version);
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("nav", { "aria-label": "Versions", style: { display: "flex", flexWrap: "wrap", justifyContent: "center", gap: "0.5rem", marginBottom: "2rem" }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ChannelLink, { href: `${basePath}latest/`, active: isCurrent({ kind: "latest" }), children: "latest" }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ChannelLink, { href: `${basePath}dev/`, active: isCurrent({ kind: "dev" }), children: "dev" }),
+    versions?.map((v) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+      ChannelLink,
+      {
+        href: `${basePath}v${v.version}/`,
+        title: formatDate(v.publishedAt),
+        active: isCurrent({ kind: "version", version: v.version }),
+        children: `v${v.version}`
+      },
+      v.version
+    ))
+  ] });
+}
+function ChannelLink({
+  href,
+  title,
+  active,
+  children
+}) {
+  const style = {
+    padding: "0.25rem 0.75rem",
+    border: `1px solid ${active ? tokens.primary : tokens.border}`,
+    borderRadius: "9999px",
+    background: active ? tokens.primary : "transparent",
+    color: active ? tokens.primaryForeground : tokens.mutedForeground,
+    fontSize: "0.75rem",
+    fontWeight: 500,
+    textDecoration: "none"
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("a", { href, title, "aria-current": active ? "page" : void 0, style, children });
+}
+function InstallUrl() {
+  const url = window.location.href;
+  const [copied, setCopied] = (0, import_react6.useState)(false);
+  function copy() {
+    void navigator.clipboard?.writeText(url).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("section", { style: cardStyle2, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("h2", { style: cardTitleStyle, children: "Use it as a Grist custom widget" }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { style: { ...cardTextStyle, marginBottom: "1rem" }, children: "Paste this URL into a custom widget's URL field in Grist." }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { style: { display: "flex", gap: "0.5rem" }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+        "input",
+        {
+          readOnly: true,
+          value: url,
+          "aria-label": "Widget URL",
+          onFocus: (event) => event.target.select(),
+          style: {
+            flex: 1,
+            minWidth: 0,
+            padding: "0.5rem 0.75rem",
+            border: `1px solid ${tokens.border}`,
+            borderRadius: tokens.radius,
+            background: "transparent",
+            color: tokens.foreground,
+            font: "inherit",
+            fontSize: "0.875rem"
+          }
+        }
+      ),
+      /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+        "button",
+        {
+          type: "button",
+          onClick: copy,
+          style: {
+            padding: "0.5rem 1rem",
+            border: "none",
+            borderRadius: tokens.radius,
+            background: tokens.primary,
+            color: tokens.primaryForeground,
+            font: "inherit",
+            fontSize: "0.875rem",
+            fontWeight: 500,
+            cursor: "pointer"
+          },
+          children: copied ? "Copied" : "Copy"
+        }
+      )
+    ] })
+  ] });
+}
+function formatDate(iso) {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? iso : date.toLocaleDateString(void 0, { year: "numeric", month: "short", day: "numeric" });
+}
+
+// src/sdk/helpers/grist-sdk-alerts.ts
+var TITLE = {
+  "column-mapping": "Column mapping",
+  "mapping-pending": "Column mapping",
+  "section-not-linked": "Widget linking",
+  "source-not-wired": "Widget linking",
+  "action-error": "Action error",
+  "access-insufficient": "Access level",
+  "map-back-skip": "Write skipped",
+  "cell-issues": "Unexpected values"
+};
+var SEVERITY = {
+  "column-mapping": "warning",
+  "mapping-pending": "info",
+  "section-not-linked": "warning",
+  "source-not-wired": "warning",
+  "action-error": "error",
+  "access-insufficient": "error",
+  "map-back-skip": "warning",
+  "cell-issues": "warning"
+};
+var alert = (kind, message2, ariaRole = "status") => ({
+  id: kind,
+  kind,
+  severity: SEVERITY[kind],
+  title: TITLE[kind],
+  ariaRole,
+  message: message2
+});
+function isWidgetSectionNotLinked(interaction) {
+  const linking = parseGristWidgetLinkingInfo(interaction?.linking);
+  return Boolean(linking) && linking.asTarget == null;
+}
+function getGristSdkAlerts(state, widget, options = {}) {
+  if (deriveStatus(state) !== "ready") return [];
+  const out = [];
+  const mapping = deriveColumnMappingStatus(widget.columns, state.mappings);
+  if (mapping.pending) out.push(alert("mapping-pending", "Waiting for Grist to report column mappings."));
+  else if (!mapping.ok) {
+    const parts = ["Column mapping is incomplete."];
+    if (mapping.missing.length) parts.push(`Required columns: ${mapping.missing.join(", ")}.`);
+    if (mapping.emptyMultiples.length) parts.push(`Assign at least one sheet column for: ${mapping.emptyMultiples.join(", ")}.`);
+    out.push(alert("column-mapping", parts.join(" ")));
+  }
+  const failure = state.actionError ?? state.readError;
+  if (failure && isAccessInsufficientError(failure)) {
+    out.push(
+      alert(
+        "access-insufficient",
+        'This operation requires "Full document access". Set the Access level to "Full document access" in the Custom widget configuration panel.',
+        "alert"
+      )
+    );
+  } else if (state.actionError) {
+    out.push(alert("action-error", state.actionError, "alert"));
+  }
+  if (state.mapBackSkipped.length) {
+    const list = state.mapBackSkipped.join(", ");
+    out.push(alert("map-back-skip", `mapBack skipped multi-mapped column${state.mapBackSkipped.length === 1 ? "" : "s"}: ${list}.`));
+  }
+  const cellIssues = widget.cellIssues ?? [];
+  if (cellIssues.length) {
+    const first = cellIssues[0];
+    const where = first.column ? `${first.column} in row ${first.rowId}` : `row ${first.rowId}`;
+    const more = cellIssues.length > 1 ? ` (and ${cellIssues.length - 1} more)` : "";
+    out.push(alert("cell-issues", `${where}: ${first.message}${more}. Check the column's type, or the cell, in Grist.`));
+  }
+  const linking = parseGristWidgetLinkingInfo(state.interaction?.linking);
+  if (widget.allowSelectBy) {
+    if (linking && !linking.asSource) {
+      out.push(
+        alert(
+          "source-not-wired",
+          "This widget is configured as a selector (allowSelectBy) but no other section is using it as a link source yet. Link another section to read from this widget."
+        )
+      );
+    }
+  } else if (isWidgetSectionNotLinked(state.interaction)) {
+    const hint = options.sectionNotLinkedHint?.trim();
+    out.push(
+      alert(
+        "section-not-linked",
+        "This widget section is not linked to a table or selector. Link it from the page settings so the selected row is sent to the widget." + (hint ? ` ${hint}` : "")
+      )
+    );
+  }
+  const suppressed = widget.suppressAlerts ?? [];
+  return out.filter((a) => !suppressed.includes(a.kind));
+}
+function useGristSdkAlerts(options) {
+  const { connection, state, cellIssues } = useNearestGristState();
+  if (!connection) return [];
+  const { columns, allowSelectBy, suppressAlerts } = connection.runtime.options;
+  return getGristSdkAlerts(state, { columns, allowSelectBy, suppressAlerts, cellIssues }, options);
+}
+
+// src/app/chrome/widget-alerts.tsx
+var import_jsx_runtime5 = require("react/jsx-runtime");
+var ALERT_OPTIONS = {
+  sectionNotLinkedHint: "In Grist, select this widget section on the page, then use Link to connect a table, card, or chart view as the selector."
+};
+function WidgetAlerts({ children }) {
+  const alerts = useGristSdkAlerts(ALERT_OPTIONS);
+  if (alerts.length === 0) return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children });
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { display: "flex", flexDirection: "column", gap: "0.75rem" }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { display: "flex", flexDirection: "column", gap: "0.75rem", padding: "0.75rem 0.75rem 0" }, children: alerts.map((alert2) => /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(WidgetAlert, { alert: alert2 }, alert2.id)) }),
+    children
+  ] });
+}
+function WidgetAlert({ alert: alert2 }) {
+  const linkIcon = alert2.kind === "section-not-linked" || alert2.kind === "source-not-wired";
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { role: alert2.ariaRole, style: { ...alertStyle, ...SEVERITY2[alert2.severity] }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { "aria-hidden": true, style: { flexShrink: 0, marginTop: "0.125rem" }, children: linkIcon ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(LinkIcon, {}) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(WarningIcon, {}) }),
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { minWidth: 0 }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("p", { style: { margin: 0, fontWeight: 500 }, children: alert2.title }),
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("p", { style: { margin: "0.25rem 0 0", color: tokens.mutedForeground }, children: alert2.message })
+    ] })
+  ] });
+}
+var alertStyle = {
+  boxSizing: "border-box",
+  display: "flex",
+  gap: "0.75rem",
+  padding: "0.75rem 1rem",
+  border: `1px solid ${tokens.border}`,
+  borderRadius: tokens.radius,
+  color: tokens.foreground,
+  fontSize: "0.875rem",
+  lineHeight: 1.5
+};
+var SEVERITY2 = {
+  error: { borderColor: tokens.destructive, color: tokens.destructive },
+  warning: { borderColor: "rgb(245 158 11 / 0.4)", background: "rgb(245 158 11 / 0.1)" },
+  info: { background: "transparent" }
+};
+var ICON = {
+  width: 16,
+  height: 16,
+  viewBox: "0 0 24 24",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: 2,
+  strokeLinecap: "round",
+  strokeLinejoin: "round"
+};
+function WarningIcon() {
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("svg", { ...ICON, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" }),
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "M12 9v4" }),
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "M12 17h.01" })
+  ] });
+}
+function LinkIcon() {
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("svg", { ...ICON, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "M9 17H7A5 5 0 0 1 7 7h2" }),
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "M15 7h2a5 5 0 1 1 0 10h-2" }),
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("line", { x1: "8", x2: "16", y1: "12", y2: "12" })
+  ] });
+}
+
+// src/app/widget-theme.tsx
+var import_react7 = require("react");
+var import_jsx_runtime6 = require("react/jsx-runtime");
+var STORAGE_KEY = "theme";
+var DARK_QUERY = "(prefers-color-scheme: dark)";
+var THEMES = ["light", "dark", "system"];
+var ThemeContext = (0, import_react7.createContext)(null);
+function EmbeddedThemeProvider({ children }) {
+  const gristTheme = useNearestGristState().state.theme;
+  const system = useSystemTheme(gristTheme === null);
+  const resolvedTheme = gristTheme ?? system;
+  useApplyTheme(resolvedTheme);
+  const value = (0, import_react7.useMemo)(
+    () => ({ theme: gristTheme ?? "system", resolvedTheme, setTheme: noop }),
+    [gristTheme, resolvedTheme]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(ThemeContext.Provider, { value, children });
+}
+function StandaloneThemeProvider({ children }) {
+  const [theme, setThemeState] = (0, import_react7.useState)(() => readStoredTheme() ?? "system");
+  const system = useSystemTheme(theme === "system");
+  const resolvedTheme = theme === "system" ? system : theme;
+  useApplyTheme(resolvedTheme);
+  const setTheme = (0, import_react7.useCallback)((next) => {
+    writeStoredTheme(next);
+    setThemeState(next);
+  }, []);
+  (0, import_react7.useEffect)(() => {
+    const onKeyDown = (event) => {
+      if (event.repeat || event.metaKey || event.ctrlKey || event.altKey) return;
+      if (event.key.toLowerCase() !== "d" || isEditableTarget(event.target)) return;
+      setThemeState((current) => {
+        const currentResolved = current === "system" ? systemTheme() : current;
+        const next = currentResolved === "dark" ? "light" : "dark";
+        writeStoredTheme(next);
+        return next;
+      });
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+  (0, import_react7.useEffect)(() => {
+    const onStorage = (event) => {
+      if (event.key !== STORAGE_KEY) return;
+      setThemeState(isTheme(event.newValue) ? event.newValue : "system");
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, []);
+  const value = (0, import_react7.useMemo)(
+    () => ({ theme, resolvedTheme, setTheme }),
+    [theme, resolvedTheme, setTheme]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(ThemeContext.Provider, { value, children });
+}
+function useSystemTheme(active) {
+  const [theme, setTheme] = (0, import_react7.useState)(systemTheme);
+  (0, import_react7.useEffect)(() => {
+    if (!active || typeof window.matchMedia !== "function") return;
+    const query = window.matchMedia(DARK_QUERY);
+    const onChange = () => setTheme(query.matches ? "dark" : "light");
+    onChange();
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+  }, [active]);
+  return theme;
+}
+function useApplyTheme(theme) {
+  (0, import_react7.useEffect)(() => {
+    const root = document.documentElement;
+    if (root.classList.contains(theme) && !root.classList.contains(other(theme))) return;
+    const restoreTransitions = suspendTransitions();
+    root.classList.remove(other(theme));
+    root.classList.add(theme);
+    restoreTransitions();
+  }, [theme]);
+}
+function systemTheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return "light";
+  return window.matchMedia(DARK_QUERY).matches ? "dark" : "light";
+}
+function other(theme) {
+  return theme === "dark" ? "light" : "dark";
+}
+function suspendTransitions() {
+  const style = document.createElement("style");
+  style.appendChild(
+    document.createTextNode("*,*::before,*::after{-webkit-transition:none!important;transition:none!important}")
+  );
+  document.head.appendChild(style);
+  return () => {
+    window.getComputedStyle(document.body);
+    requestAnimationFrame(() => requestAnimationFrame(() => style.remove()));
+  };
+}
+function isEditableTarget(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.isContentEditable || target.closest("input, textarea, select, [contenteditable='true']") !== null;
+}
+function isTheme(value) {
+  return value !== null && THEMES.includes(value);
+}
+function readStoredTheme() {
+  try {
+    const value = localStorage.getItem(STORAGE_KEY);
+    return isTheme(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function writeStoredTheme(theme) {
+  try {
+    localStorage.setItem(STORAGE_KEY, theme);
+  } catch {
+  }
+}
+function noop() {
+}
+
+// src/app/mount-grist-widget.tsx
+var import_jsx_runtime7 = require("react/jsx-runtime");
+function GristWidgetApp({
+  App,
+  options,
+  dev = false,
+  Alerts = WidgetAlerts,
+  LocalDevPage: LocalDevPage2 = LocalDevPage,
+  ReleasePage: ReleasePage2 = ReleasePage
+}) {
+  const Wrap = Alerts ?? PassThrough;
+  if (isEmbedded2()) {
+    return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristWidgetProvider, { options, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(EmbeddedThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristBoundary, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: FILL, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(Wrap, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_react8.Suspense, { fallback: null, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(App, {}) }) }) }) }) }) });
+  }
+  const channel = parseDeployPath(window.location.pathname).channel;
+  return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(StandaloneThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: FILL, children: dev ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(LocalDevPage2, {}) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(ReleasePage2, { channel }) }) });
+}
+var FILL = { minHeight: "100%", width: "100%" };
+function isEmbedded2() {
+  return typeof window !== "undefined" && window.self !== window.top;
+}
+function PassThrough({ children }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_jsx_runtime7.Fragment, { children });
+}
+
+// src/emulator/testing/jsdom-stubs.ts
+function installJsdomStubs() {
+  if (typeof window === "undefined") return;
+  globalThis.ResizeObserver ?? (globalThis.ResizeObserver = class ResizeObserver {
+    observe() {
+    }
+    unobserve() {
+    }
+    disconnect() {
+    }
+  });
+  window.matchMedia ?? (window.matchMedia = (query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener() {
+    },
+    removeEventListener() {
+    },
+    addListener() {
+    },
+    removeListener() {
+    },
+    dispatchEvent: () => false
+  }));
+}
+
+// src/emulator/testing/smoke-test-widget.tsx
+var import_jsx_runtime8 = require("react/jsx-runtime");
+async function smokeTestWidget({
+  App,
+  options,
+  document: document2,
+  timeout = 1e4
+}) {
+  installJsdomStubs();
+  const crash = { error: void 0 };
+  function Probe() {
+    return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(CatchRenderError, { crash, children: /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("div", { "data-grist-smoke-test": "", children: /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(App, {}) }) });
+  }
+  const columns = declaredColumns(options);
+  const gristDocument = document2 ?? smokeTestDocument(columns);
+  const result = renderWithGrist(/* @__PURE__ */ (0, import_jsx_runtime8.jsx)(GristWidgetApp, { App: Probe, options }), {
+    emulator: {
+      document: gristDocument,
+      // Granted as the user would in Grist's widget panel: the access the
+      // widget asks for, unless the given document says otherwise.
+      widgetInteraction: gristDocument.widgetInteraction ?? { access_level: options.requiredAccess ?? "read table" }
+    }
+  });
+  try {
+    if (columns.length > 0) result.emulator.setColumnMappings(mapEveryColumn(columns));
+    try {
+      await (0, import_react10.waitFor)(
+        () => {
+          if (crash.error !== void 0) return;
+          const probe = result.container.querySelector("[data-grist-smoke-test]");
+          if (!probe || !probe.hasChildNodes()) throw new Error("not rendered yet");
+        },
+        { timeout }
+      );
+    } catch {
+      const shown = result.container.textContent?.trim().replace(/\s+/g, " ") || "nothing";
+      throw new Error(
+        `smokeTestWidget: the widget didn't render past GristBoundary within ${timeout} ms. The page showed: "${shown.slice(0, 300)}".`
+      );
+    }
+    if (crash.error !== void 0) throw crash.error;
+  } finally {
+    result.unmount();
+  }
+}
+var CatchRenderError = class extends import_react9.Component {
+  constructor() {
+    super(...arguments);
+    this.state = { failed: false };
+  }
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch(error) {
+    this.props.crash.error = error;
+  }
+  render() {
+    return this.state.failed ? null : this.props.children;
+  }
+};
+function declaredColumns(options) {
+  return (options.columns ?? []).map(
+    (column) => typeof column === "string" ? { name: column, type: "Any", allowMultiple: false } : { name: column.name, type: firstType(column.type), allowMultiple: column.allowMultiple === true }
+  );
+}
+function firstType(type) {
+  return (type ?? "Any").split(",")[0].trim() || "Any";
+}
+function mapEveryColumn(columns) {
+  return Object.fromEntries(columns.map((c) => [c.name, c.allowMultiple ? [c.name] : c.name]));
+}
+function smokeTestDocument(columns) {
+  return {
+    generatedAt: "1970-01-01T00:00:00.000Z",
+    docName: "Smoke test",
+    mode: "schema+data",
+    tables: {
+      Table1: {
+        columns: Object.fromEntries(columns.map((c) => [c.name, { type: c.type }])),
+        rows: [{ id: 1, ...Object.fromEntries(columns.map((c) => [c.name, sampleValue(c.type)])) }]
+      }
+    }
+  };
+}
+function sampleValue(type) {
+  switch (type) {
+    case "Numeric":
+    case "Int":
+      return 42;
+    case "Bool":
+      return true;
+    case "Date":
+    case "DateTime":
+      return 1767225600;
+    // 2026-01-01, as Grist stores it: epoch seconds
+    default:
+      return "Sample";
+  }
+}
+
 // src/emulator/testing/matchers.ts
 function actionsOf(emulator) {
   return emulator.bus.history().filter((e) => e.type === "user-action").map((e) => e.action);
@@ -2044,7 +3735,7 @@ function waitForEvent(emulator, kindOrPredicate, timeoutOrOptions = 1e3) {
 }
 
 // src/emulator/testing/index.ts
-var import_react2 = require("@testing-library/react");
+var import_react11 = require("@testing-library/react");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   act,
@@ -2052,10 +3743,12 @@ var import_react2 = require("@testing-library/react");
   cleanup,
   eventsOf,
   fireEvent,
+  installJsdomStubs,
   presets,
   render,
   renderWithGrist,
   screen,
+  smokeTestWidget,
   waitFor,
   waitForEvent,
   within