grist-widget-sdk 0.2.1 → 0.2.15

package/dist/advanced.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var advanced_exports = {};
 __export(advanced_exports, {
   GristHandshakeProvider: () => GristHandshakeProvider,
+  useAmbientGristHandshake: () => useAmbientGristHandshake,
   useGristAccessToken: () => useGristAccessToken,
   useGristActions: () => useGristActions,
   useGristAvailability: () => useGristAvailability,
@@ -743,14 +744,24 @@ var ACCESS_RANK2 = {
 };
 var inFlight = null;
 var lastAccess = null;
-function shouldReinit(next) {
+var lastColumnNames = null;
+function columnNamesOf(columns) {
+  return new Set((columns ?? []).map((c) => typeof c === "string" ? c : c.name));
+}
+function shouldReinit(next, nextColumns) {
   if (!lastAccess) return true;
-  return ACCESS_RANK2[next] > ACCESS_RANK2[lastAccess];
+  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";
-  if (inFlight && !shouldReinit(access)) return inFlight;
+  const columns = columnNamesOf(payload.columns);
+  if (inFlight && !shouldReinit(access, columns)) return inFlight;
   lastAccess = access;
+  lastColumnNames = columns;
   const next = Promise.resolve().then(() => {
     const result = grist.ready(payload);
     return result instanceof Promise ? result : Promise.resolve();
@@ -758,6 +769,7 @@ function ensureGristReady(payload) {
   inFlight = next.catch((err) => {
     inFlight = null;
     lastAccess = null;
+    lastColumnNames = null;
     throw err;
   });
   return inFlight;
@@ -765,6 +777,7 @@ function ensureGristReady(payload) {
 function resetGristReadySingleton() {
   inFlight = null;
   lastAccess = null;
+  lastColumnNames = null;
 }
 
 // src/sdk/internal/build-manager-options.ts
@@ -1729,7 +1742,17 @@ function useGristHandshake(options = {}) {
   optionsRef.current = options;
   const managerRef = (0, import_react3.useRef)(null);
   if (managerRef.current === null) {
-    managerRef.current = createGristHandshakeManager(options);
+    managerRef.current = createGristHandshakeManager({
+      ...options,
+      negotiate: {
+        readyImpl: (payload) => ensureGristReady(payload),
+        ...options.negotiate
+      },
+      onBeforeReload: () => {
+        resetGristReadySingleton();
+        options.onBeforeReload?.();
+      }
+    });
   }
   const manager = managerRef.current;
   (0, import_react3.useEffect)(() => {
@@ -1767,28 +1790,63 @@ function useGristCapabilities(options = {}) {
   return useGristHandshake(options).capabilities;
 }
 
-// src/sdk/components/grist-handshake-provider.tsx
+// src/sdk/low-level-hooks/use-ambient-grist-handshake.ts
 var import_react4 = require("react");
+var noopSubscribe = () => () => {
+};
+var getInitialSnapshot = () => initialGristSnapshot();
+function useAmbientGristHandshake() {
+  const manager = useGristManagerOptional();
+  const snapshot = (0, import_react4.useSyncExternalStore)(
+    manager?.subscribe ?? noopSubscribe,
+    manager?.getSnapshot ?? getInitialSnapshot,
+    getInitialSnapshot
+  );
+  return (0, import_react4.useMemo)(() => {
+    if (!manager) return null;
+    return {
+      snapshot,
+      status: deriveStatus(snapshot),
+      error: deriveErrorMessage(snapshot),
+      capabilities: deriveCapabilities(snapshot),
+      reload: manager.reload,
+      restart: manager.restart
+    };
+  }, [manager, snapshot]);
+}
+
+// src/sdk/components/grist-handshake-provider.tsx
+var import_react5 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-var GristHandshakeReactContext = (0, import_react4.createContext)(null);
+var GristHandshakeReactContext = (0, import_react5.createContext)(null);
 function GristHandshakeProvider({ options, children }) {
-  const managerRef = (0, import_react4.useRef)(null);
+  const managerRef = (0, import_react5.useRef)(null);
   if (managerRef.current === null) {
-    managerRef.current = createGristHandshakeManager(options ?? {});
+    managerRef.current = createGristHandshakeManager({
+      ...options,
+      negotiate: {
+        readyImpl: (payload) => ensureGristReady(payload),
+        ...options?.negotiate
+      },
+      onBeforeReload: () => {
+        resetGristReadySingleton();
+        options?.onBeforeReload?.();
+      }
+    });
   }
   const manager = managerRef.current;
-  (0, import_react4.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     manager.start();
     return () => {
       manager.stop();
     };
   }, [manager]);
-  const snapshot = (0, import_react4.useSyncExternalStore)(
+  const snapshot = (0, import_react5.useSyncExternalStore)(
     manager.subscribe,
     manager.getSnapshot,
     initialGristSnapshot
   );
-  const value = (0, import_react4.useMemo)(
+  const value = (0, import_react5.useMemo)(
     () => ({
       snapshot,
       status: deriveStatus(snapshot),
@@ -1804,7 +1862,7 @@ function GristHandshakeProvider({ options, children }) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GristHandshakeReactContext.Provider, { value, children });
 }
 function useGristHandshakeContext() {
-  const ctx = (0, import_react4.useContext)(GristHandshakeReactContext);
+  const ctx = (0, import_react5.useContext)(GristHandshakeReactContext);
   if (!ctx) {
     throw new Error(
       "useGristHandshakeContext() must be used inside <GristHandshakeProvider>"
@@ -1813,17 +1871,17 @@ function useGristHandshakeContext() {
   return ctx;
 }
 function useGristHandshakeContextOptional() {
-  return (0, import_react4.useContext)(GristHandshakeReactContext);
+  return (0, import_react5.useContext)(GristHandshakeReactContext);
 }
 
 // src/sdk/low-level-hooks/use-grist-record.ts
-var import_react5 = require("react");
+var import_react6 = require("react");
 function useGristRecord(cb, options) {
-  const cbRef = (0, import_react5.useRef)(cb);
-  (0, import_react5.useEffect)(() => {
+  const cbRef = (0, import_react6.useRef)(cb);
+  (0, import_react6.useEffect)(() => {
     cbRef.current = cb;
   }, [cb]);
-  const [mappings, setMappings] = (0, import_react5.useState)(null);
+  const [mappings, setMappings] = (0, import_react6.useState)(null);
   const { docApi, error: readyError } = useGristReady({
     requiredAccess: options?.requiredAccess ?? "read table",
     columns: options?.columns,
@@ -1831,7 +1889,7 @@ function useGristRecord(cb, options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  (0, import_react5.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (!docApi) return;
     return recordEvent.subscribe(({ record, mappings: nextMappings }) => {
       setMappings(nextMappings);
@@ -1846,13 +1904,13 @@ function useGristRecord(cb, options) {
 }
 
 // src/sdk/low-level-hooks/use-grist-records.ts
-var import_react6 = require("react");
+var import_react7 = require("react");
 function useGristRecords(cb, options) {
-  const cbRef = (0, import_react6.useRef)(cb);
-  (0, import_react6.useEffect)(() => {
+  const cbRef = (0, import_react7.useRef)(cb);
+  (0, import_react7.useEffect)(() => {
     cbRef.current = cb;
   }, [cb]);
-  const [mappings, setMappings] = (0, import_react6.useState)(null);
+  const [mappings, setMappings] = (0, import_react7.useState)(null);
   const { docApi, error: readyError } = useGristReady({
     requiredAccess: options?.requiredAccess ?? "read table",
     columns: options?.columns,
@@ -1860,7 +1918,7 @@ function useGristRecords(cb, options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  (0, import_react6.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     if (!docApi) return;
     return recordsEvent.subscribe(({ records, mappings: nextMappings }) => {
       setMappings(nextMappings);
@@ -1875,7 +1933,7 @@ function useGristRecords(cb, options) {
 }
 
 // src/sdk/low-level-hooks/use-grist-new-record.ts
-var import_react7 = require("react");
+var import_react8 = require("react");
 function useGristNewRecord(options) {
   const { docApi, error: readyError } = useGristReady({
     requiredAccess: options?.requiredAccess ?? "read table",
@@ -1884,10 +1942,10 @@ function useGristNewRecord(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [isNewRecord, setIsNewRecord] = (0, import_react7.useState)(false);
-  const [mappings, setMappings] = (0, import_react7.useState)(null);
-  const subscribedRef = (0, import_react7.useRef)(false);
-  (0, import_react7.useEffect)(() => {
+  const [isNewRecord, setIsNewRecord] = (0, import_react8.useState)(false);
+  const [mappings, setMappings] = (0, import_react8.useState)(null);
+  const subscribedRef = (0, import_react8.useRef)(false);
+  (0, import_react8.useEffect)(() => {
     if (!docApi || subscribedRef.current) return;
     if (typeof grist.onNewRecord !== "function") return;
     subscribedRef.current = true;
@@ -1905,7 +1963,7 @@ function useGristNewRecord(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-actions.ts
-var import_react9 = require("react");
+var import_react10 = require("react");
 
 // src/sdk/helpers/grist-user-actions.ts
 function gristUpdateRecordAction(tableId, rowId, patch) {
@@ -1934,10 +1992,10 @@ function inferBulkLength(values) {
 }
 
 // src/sdk/internal/hooks/use-rpc-heartbeat-coalesce.ts
-var import_react8 = require("react");
+var import_react9 = require("react");
 function useRpcHeartbeatCoalesce() {
   const manager = useGristManagerOptional();
-  return (0, import_react8.useCallback)(
+  return (0, import_react9.useCallback)(
     async (fn) => {
       try {
         const result = await fn();
@@ -1961,10 +2019,10 @@ function useGristActions(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [status, setStatus] = (0, import_react9.useState)("idle");
-  const [actionError, setActionError] = (0, import_react9.useState)(null);
+  const [status, setStatus] = (0, import_react10.useState)("idle");
+  const [actionError, setActionError] = (0, import_react10.useState)(null);
   const coalesceRpc = useRpcHeartbeatCoalesce();
-  const apply = (0, import_react9.useCallback)(
+  const apply = (0, import_react10.useCallback)(
     async (actions, applyOptions) => {
       if (!docApi) throw new Error("Grist docApi is not ready");
       setStatus("running");
@@ -1982,27 +2040,27 @@ function useGristActions(options) {
     },
     [docApi, coalesceRpc]
   );
-  const updateRecord = (0, import_react9.useCallback)(
+  const updateRecord = (0, import_react10.useCallback)(
     (tableId, recordId, patch, applyOptions) => apply([gristUpdateRecordAction(tableId, recordId, patch)], applyOptions),
     [apply]
   );
-  const addRecord = (0, import_react9.useCallback)(
+  const addRecord = (0, import_react10.useCallback)(
     (tableId, values, applyOptions) => apply([gristAddRecordAction(tableId, values)], applyOptions),
     [apply]
   );
-  const removeRecord = (0, import_react9.useCallback)(
+  const removeRecord = (0, import_react10.useCallback)(
     (tableId, recordId, applyOptions) => apply([gristRemoveRecordAction(tableId, recordId)], applyOptions),
     [apply]
   );
-  const bulkAddRecord = (0, import_react9.useCallback)(
+  const bulkAddRecord = (0, import_react10.useCallback)(
     (tableId, values, applyOptions) => apply([gristBulkAddRecordAction(tableId, values)], applyOptions),
     [apply]
   );
-  const bulkUpdateRecord = (0, import_react9.useCallback)(
+  const bulkUpdateRecord = (0, import_react10.useCallback)(
     (tableId, rowIds, columnarPatch, applyOptions) => apply([gristBulkUpdateRecordAction(tableId, rowIds, columnarPatch)], applyOptions),
     [apply]
   );
-  const bulkRemoveRecord = (0, import_react9.useCallback)(
+  const bulkRemoveRecord = (0, import_react10.useCallback)(
     (tableId, rowIds, applyOptions) => apply([gristBulkRemoveRecordAction(tableId, rowIds)], applyOptions),
     [apply]
   );
@@ -2020,7 +2078,7 @@ function useGristActions(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-mapped-record.ts
-var import_react10 = require("react");
+var import_react11 = require("react");
 function manualMapBack(patch, mappings) {
   if (!mappings) return { ...patch };
   const out = {};
@@ -2045,10 +2103,10 @@ function useGristMappedRecord(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [rawRecord, setRawRecord] = (0, import_react10.useState)(null);
-  const [mappedRecord, setMappedRecord] = (0, import_react10.useState)(null);
-  const [mappings, setMappings] = (0, import_react10.useState)(null);
-  (0, import_react10.useEffect)(() => {
+  const [rawRecord, setRawRecord] = (0, import_react11.useState)(null);
+  const [mappedRecord, setMappedRecord] = (0, import_react11.useState)(null);
+  const [mappings, setMappings] = (0, import_react11.useState)(null);
+  (0, import_react11.useEffect)(() => {
     if (!docApi) return;
     return recordEvent.subscribe(({ record, mappings: nextMappings }) => {
       setRawRecord(record);
@@ -2067,7 +2125,7 @@ function useGristMappedRecord(options) {
       setMappedRecord(record);
     });
   }, [docApi]);
-  const mapBack = (0, import_react10.useCallback)(
+  const mapBack = (0, import_react11.useCallback)(
     (patch) => {
       if (typeof grist.mapColumnNamesBack === "function") {
         return grist.mapColumnNamesBack(patch);
@@ -2076,7 +2134,7 @@ function useGristMappedRecord(options) {
     },
     [mappings]
   );
-  const resolveColumnId = (0, import_react10.useCallback)(
+  const resolveColumnId = (0, import_react11.useCallback)(
     (logicalName) => {
       const value = mappings?.[logicalName];
       if (Array.isArray(value)) return void 0;
@@ -2096,7 +2154,7 @@ function useGristMappedRecord(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-table-ops.ts
-var import_react11 = require("react");
+var import_react12 = require("react");
 function resolveOps(tableId) {
   if (tableId === "selected") {
     if (!grist.selectedTable) throw new Error("grist.selectedTable is not available");
@@ -2117,8 +2175,8 @@ function useGristTableOps(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [status, setStatus] = (0, import_react11.useState)("idle");
-  const [actionError, setActionError] = (0, import_react11.useState)(null);
+  const [status, setStatus] = (0, import_react12.useState)("idle");
+  const [actionError, setActionError] = (0, import_react12.useState)(null);
   const coalesceRpc = useRpcHeartbeatCoalesce();
   let ops = null;
   let resolveError = null;
@@ -2129,7 +2187,7 @@ function useGristTableOps(options) {
       resolveError = err instanceof Error ? err.message : String(err);
     }
   }
-  const wrap = (0, import_react11.useCallback)(
+  const wrap = (0, import_react12.useCallback)(
     async (run) => {
       if (!ops) throw new Error("Grist table operations are not ready");
       setStatus("running");
@@ -2147,23 +2205,23 @@ function useGristTableOps(options) {
     },
     [ops, coalesceRpc]
   );
-  const getTableId = (0, import_react11.useCallback)(async () => {
+  const getTableId = (0, import_react12.useCallback)(async () => {
     if (!ops) throw new Error("Grist table operations are not ready");
     return ops.getTableId();
   }, [ops]);
-  const create = (0, import_react11.useCallback)(
+  const create = (0, import_react12.useCallback)(
     (records, opOptions) => wrap((o) => o.create(records, opOptions)),
     [wrap]
   );
-  const update = (0, import_react11.useCallback)(
+  const update = (0, import_react12.useCallback)(
     (records, opOptions) => wrap((o) => o.update(records, opOptions)),
     [wrap]
   );
-  const upsert = (0, import_react11.useCallback)(
+  const upsert = (0, import_react12.useCallback)(
     (records, opOptions) => wrap((o) => o.upsert(records, opOptions)),
     [wrap]
   );
-  const destroy = (0, import_react11.useCallback)(
+  const destroy = (0, import_react12.useCallback)(
     (recordIds) => wrap((o) => o.destroy(recordIds)),
     [wrap]
   );
@@ -2179,7 +2237,7 @@ function useGristTableOps(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-rows-from-table.ts
-var import_react13 = require("react");
+var import_react14 = require("react");
 
 // src/sdk/helpers/grist-table-data.ts
 function tableDataToRows(data) {
@@ -2200,19 +2258,19 @@ function tableDataToRows(data) {
 }
 
 // src/sdk/internal/contexts.tsx
-var import_react12 = require("react");
-var GristCoreContext = (0, import_react12.createContext)(null);
-var GristSelectionContext = (0, import_react12.createContext)(null);
-var GristCurrentTableContext = (0, import_react12.createContext)(null);
-var GristWritesContext = (0, import_react12.createContext)(null);
-var GristReadsContext = (0, import_react12.createContext)(null);
-var GristWidgetOptionsApiContext = (0, import_react12.createContext)(null);
-var GristLinkingContext = (0, import_react12.createContext)(null);
-var GristAttachmentsRestContext = (0, import_react12.createContext)(null);
-var GristThemeContext = (0, import_react12.createContext)(null);
-var GristSectionApiContext = (0, import_react12.createContext)(null);
+var import_react13 = require("react");
+var GristCoreContext = (0, import_react13.createContext)(null);
+var GristSelectionContext = (0, import_react13.createContext)(null);
+var GristCurrentTableContext = (0, import_react13.createContext)(null);
+var GristWritesContext = (0, import_react13.createContext)(null);
+var GristReadsContext = (0, import_react13.createContext)(null);
+var GristWidgetOptionsApiContext = (0, import_react13.createContext)(null);
+var GristLinkingContext = (0, import_react13.createContext)(null);
+var GristAttachmentsRestContext = (0, import_react13.createContext)(null);
+var GristThemeContext = (0, import_react13.createContext)(null);
+var GristSectionApiContext = (0, import_react13.createContext)(null);
 function useRequiredContext(ctx, name) {
-  const value = (0, import_react12.useContext)(ctx);
+  const value = (0, import_react13.useContext)(ctx);
   if (!value) {
     throw new Error(`${name} must be used inside <GristWidgetProvider>`);
   }
@@ -2235,14 +2293,14 @@ function useGristRowsFromTable(options) {
     hasCustomOptions: options.hasCustomOptions,
     onEditOptions: options.onEditOptions
   });
-  const providerFetchTable = (0, import_react13.useContext)(GristReadsContext)?.fetchTable;
-  const [rows, setRows] = (0, import_react13.useState)(null);
-  const [loading, setLoading] = (0, import_react13.useState)(false);
-  const [fetchError, setFetchError] = (0, import_react13.useState)(null);
-  const transformRef = (0, import_react13.useRef)(options.transform);
+  const providerFetchTable = (0, import_react14.useContext)(GristReadsContext)?.fetchTable;
+  const [rows, setRows] = (0, import_react14.useState)(null);
+  const [loading, setLoading] = (0, import_react14.useState)(false);
+  const [fetchError, setFetchError] = (0, import_react14.useState)(null);
+  const transformRef = (0, import_react14.useRef)(options.transform);
   transformRef.current = options.transform;
   const coalesceRpc = useRpcHeartbeatCoalesce();
-  const refresh = (0, import_react13.useCallback)(async () => {
+  const refresh = (0, import_react14.useCallback)(async () => {
     if (!docApi) return;
     setLoading(true);
     setFetchError(null);
@@ -2260,10 +2318,10 @@ function useGristRowsFromTable(options) {
       setLoading(false);
     }
   }, [docApi, providerFetchTable, options.tableId, coalesceRpc]);
-  (0, import_react13.useEffect)(() => {
+  (0, import_react14.useEffect)(() => {
     if (docApi) void refresh();
   }, [docApi, refresh]);
-  (0, import_react13.useEffect)(() => {
+  (0, import_react14.useEffect)(() => {
     if (!docApi || !options.pollIntervalMs || options.pollIntervalMs <= 0) return;
     const id = window.setInterval(() => void refresh(), options.pollIntervalMs);
     return () => window.clearInterval(id);
@@ -2277,7 +2335,7 @@ function useGristRowsFromTable(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-access-token.ts
-var import_react14 = require("react");
+var import_react15 = require("react");
 
 // src/sdk/helpers/grist-fetch-with-auth.ts
 var TOKEN_TTL_MS = 45e3;
@@ -2349,10 +2407,10 @@ function useGristAccessToken(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [token, setToken] = (0, import_react14.useState)(null);
-  const [loading, setLoading] = (0, import_react14.useState)(false);
-  const [error, setError] = (0, import_react14.useState)(null);
-  const refresh = (0, import_react14.useCallback)(
+  const [token, setToken] = (0, import_react15.useState)(null);
+  const [loading, setLoading] = (0, import_react15.useState)(false);
+  const [error, setError] = (0, import_react15.useState)(null);
+  const refresh = (0, import_react15.useCallback)(
     async (overrides) => {
       if (!docApi) throw new Error("Grist is not ready");
       setLoading(true);
@@ -2371,14 +2429,14 @@ function useGristAccessToken(options) {
     },
     [docApi, readOnlyDefault]
   );
-  const fetchFn = (0, import_react14.useCallback)(
+  const fetchFn = (0, import_react15.useCallback)(
     (path, init) => {
       if (!docApi) throw new Error("Grist is not ready");
       return fetchWithGristAuth(docApi, path, { readOnly: readOnlyDefault, ...init });
     },
     [docApi, readOnlyDefault]
   );
-  (0, import_react14.useEffect)(() => {
+  (0, import_react15.useEffect)(() => {
     if (docApi && prefetch) void refresh();
   }, [docApi, prefetch, refresh]);
   return {
@@ -2391,7 +2449,7 @@ function useGristAccessToken(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-section.ts
-var import_react15 = require("react");
+var import_react16 = require("react");
 function useGristSection(options) {
   const { docApi, error: readyError } = useGristReady({
     requiredAccess: options?.requiredAccess ?? "read table",
@@ -2400,10 +2458,10 @@ function useGristSection(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [mappings, setMappings] = (0, import_react15.useState)(null);
-  const [loading, setLoading] = (0, import_react15.useState)(false);
-  const [error, setError] = (0, import_react15.useState)(null);
-  const refresh = (0, import_react15.useCallback)(async () => {
+  const [mappings, setMappings] = (0, import_react16.useState)(null);
+  const [loading, setLoading] = (0, import_react16.useState)(false);
+  const [error, setError] = (0, import_react16.useState)(null);
+  const refresh = (0, import_react16.useCallback)(async () => {
     if (!docApi) return;
     if (!grist.sectionApi?.mappings) {
       setError("grist.sectionApi.mappings is not available in this Grist version");
@@ -2420,13 +2478,13 @@ function useGristSection(options) {
       setLoading(false);
     }
   }, [docApi]);
-  const configure = (0, import_react15.useCallback)(async (next) => {
+  const configure = (0, import_react16.useCallback)(async (next) => {
     if (!grist.sectionApi?.configure) {
       throw new Error("grist.sectionApi.configure is not available in this Grist version");
     }
     await grist.sectionApi.configure(next);
   }, []);
-  (0, import_react15.useEffect)(() => {
+  (0, import_react16.useEffect)(() => {
     if (docApi) void refresh();
   }, [docApi, refresh]);
   return {
@@ -2439,7 +2497,7 @@ function useGristSection(options) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-widget-options.ts
-var import_react16 = require("react");
+var import_react17 = require("react");
 function mergeWithDefaults(defaults, stored, namespace) {
   if (stored === null || stored === void 0) return { ...defaults };
   const source = namespace ? stored[namespace] : stored;
@@ -2457,16 +2515,16 @@ function useGristWidgetOptions(config) {
     hasCustomOptions,
     onEditOptions: config.onEditOptions
   });
-  const defaultsRef = (0, import_react16.useRef)(config.defaults);
-  (0, import_react16.useEffect)(() => {
+  const defaultsRef = (0, import_react17.useRef)(config.defaults);
+  (0, import_react17.useEffect)(() => {
     defaultsRef.current = config.defaults;
   }, [config.defaults]);
-  const [options, setOptionsState] = (0, import_react16.useState)(() => ({ ...config.defaults }));
-  const [loading, setLoading] = (0, import_react16.useState)(true);
-  const [error, setError] = (0, import_react16.useState)(null);
-  const lastWrittenRef = (0, import_react16.useRef)(null);
-  const debounceRef = (0, import_react16.useRef)(null);
-  (0, import_react16.useEffect)(() => {
+  const [options, setOptionsState] = (0, import_react17.useState)(() => ({ ...config.defaults }));
+  const [loading, setLoading] = (0, import_react17.useState)(true);
+  const [error, setError] = (0, import_react17.useState)(null);
+  const lastWrittenRef = (0, import_react17.useRef)(null);
+  const debounceRef = (0, import_react17.useRef)(null);
+  (0, import_react17.useEffect)(() => {
     if (!docApi) return;
     return optionsEvent.subscribe(({ options: stored }) => {
       const merged = mergeWithDefaults(defaultsRef.current, stored, config.namespace);
@@ -2475,7 +2533,7 @@ function useGristWidgetOptions(config) {
       setLoading(false);
     });
   }, [docApi, config.namespace]);
-  const flushWrite = (0, import_react16.useCallback)(
+  const flushWrite = (0, import_react17.useCallback)(
     async (value) => {
       try {
         if (config.namespace) {
@@ -2490,7 +2548,7 @@ function useGristWidgetOptions(config) {
     },
     [config.namespace]
   );
-  const scheduleWrite = (0, import_react16.useCallback)(
+  const scheduleWrite = (0, import_react17.useCallback)(
     (value) => {
       if (debounceRef.current) window.clearTimeout(debounceRef.current);
       debounceRef.current = window.setTimeout(() => {
@@ -2500,19 +2558,19 @@ function useGristWidgetOptions(config) {
     },
     [debounceMs, flushWrite]
   );
-  (0, import_react16.useEffect)(() => {
+  (0, import_react17.useEffect)(() => {
     return () => {
       if (debounceRef.current) window.clearTimeout(debounceRef.current);
     };
   }, []);
-  const setOptionsApi = (0, import_react16.useCallback)(
+  const setOptionsApi = (0, import_react17.useCallback)(
     (next) => {
       setOptionsState(next);
       scheduleWrite(next);
     },
     [scheduleWrite]
   );
-  const patchOptionsApi = (0, import_react16.useCallback)(
+  const patchOptionsApi = (0, import_react17.useCallback)(
     (patch) => {
       setOptionsState((prev) => {
         const next = { ...prev, ...patch };
@@ -2522,7 +2580,7 @@ function useGristWidgetOptions(config) {
     },
     [scheduleWrite]
   );
-  const reset = (0, import_react16.useCallback)(async () => {
+  const reset = (0, import_react17.useCallback)(async () => {
     if (debounceRef.current) {
       window.clearTimeout(debounceRef.current);
       debounceRef.current = null;
@@ -2531,7 +2589,7 @@ function useGristWidgetOptions(config) {
     setOptionsState(next);
     await flushWrite(next);
   }, [flushWrite]);
-  return (0, import_react16.useMemo)(
+  return (0, import_react17.useMemo)(
     () => ({
       options,
       loading,
@@ -2545,7 +2603,7 @@ function useGristWidgetOptions(config) {
 }
 
 // src/sdk/mid-level-hooks/use-grist-widget-options-from-context.ts
-var import_react17 = require("react");
+var import_react18 = require("react");
 function mergeWithDefaults2(defaults, stored, namespace) {
   if (stored === null || stored === void 0) return { ...defaults };
   const source = namespace ? stored[namespace] : stored;
@@ -2556,23 +2614,23 @@ function useGristWidgetOptionsFromContext(config) {
   const debounceMs = config.debounceMs ?? 250;
   const selection = useGristSelectionContext();
   const optionsApi = useGristWidgetOptionsApiContext();
-  const defaultsRef = (0, import_react17.useRef)(config.defaults);
-  (0, import_react17.useEffect)(() => {
+  const defaultsRef = (0, import_react18.useRef)(config.defaults);
+  (0, import_react18.useEffect)(() => {
     defaultsRef.current = config.defaults;
   }, [config.defaults]);
   const rawOptions = selection.widgetOptions;
   const hasReceived = rawOptions !== null;
-  const merged = (0, import_react17.useMemo)(
+  const merged = (0, import_react18.useMemo)(
     () => mergeWithDefaults2(defaultsRef.current, rawOptions, config.namespace),
     [rawOptions, config.namespace]
   );
-  const [localOverride, setLocalOverride] = (0, import_react17.useState)(null);
+  const [localOverride, setLocalOverride] = (0, import_react18.useState)(null);
   const options = localOverride ?? merged;
-  (0, import_react17.useEffect)(() => {
+  (0, import_react18.useEffect)(() => {
     setLocalOverride(null);
   }, [rawOptions]);
-  const debounceRef = (0, import_react17.useRef)(null);
-  const flushWrite = (0, import_react17.useCallback)(
+  const debounceRef = (0, import_react18.useRef)(null);
+  const flushWrite = (0, import_react18.useCallback)(
     async (value) => {
       if (config.namespace) {
         await optionsApi.setWidgetOption(config.namespace, value);
@@ -2582,7 +2640,7 @@ function useGristWidgetOptionsFromContext(config) {
     },
     [config.namespace, optionsApi]
   );
-  const scheduleWrite = (0, import_react17.useCallback)(
+  const scheduleWrite = (0, import_react18.useCallback)(
     (value) => {
       if (debounceRef.current) window.clearTimeout(debounceRef.current);
       debounceRef.current = window.setTimeout(() => {
@@ -2592,19 +2650,19 @@ function useGristWidgetOptionsFromContext(config) {
     },
     [debounceMs, flushWrite]
   );
-  (0, import_react17.useEffect)(() => {
+  (0, import_react18.useEffect)(() => {
     return () => {
       if (debounceRef.current) window.clearTimeout(debounceRef.current);
     };
   }, []);
-  const setOptions = (0, import_react17.useCallback)(
+  const setOptions = (0, import_react18.useCallback)(
     (next) => {
       setLocalOverride(next);
       scheduleWrite(next);
     },
     [scheduleWrite]
   );
-  const patchOptions = (0, import_react17.useCallback)(
+  const patchOptions = (0, import_react18.useCallback)(
     (patch) => {
       setLocalOverride((prev) => {
         const base = prev ?? merged;
@@ -2615,7 +2673,7 @@ function useGristWidgetOptionsFromContext(config) {
     },
     [merged, scheduleWrite]
   );
-  const reset = (0, import_react17.useCallback)(async () => {
+  const reset = (0, import_react18.useCallback)(async () => {
     if (debounceRef.current) {
       window.clearTimeout(debounceRef.current);
       debounceRef.current = null;
@@ -2624,7 +2682,7 @@ function useGristWidgetOptionsFromContext(config) {
     setLocalOverride(null);
     await flushWrite(next);
   }, [flushWrite]);
-  return (0, import_react17.useMemo)(
+  return (0, import_react18.useMemo)(
     () => ({
       options,
       loading: !hasReceived,
@@ -2637,7 +2695,7 @@ function useGristWidgetOptionsFromContext(config) {
 }
 
 // src/sdk/use-grist-table.ts
-var import_react18 = require("react");
+var import_react19 = require("react");
 function isCurrentMode(option) {
   return option === void 0 || option === "current";
 }
@@ -2651,26 +2709,26 @@ function useGristTable(options) {
     hasCustomOptions: options?.hasCustomOptions,
     onEditOptions: options?.onEditOptions
   });
-  const [tableId, setTableId] = (0, import_react18.useState)(null);
-  const [loading, setLoading] = (0, import_react18.useState)(false);
-  const [error, setError] = (0, import_react18.useState)(null);
-  const fetchTable = (0, import_react18.useCallback)(
+  const [tableId, setTableId] = (0, import_react19.useState)(null);
+  const [loading, setLoading] = (0, import_react19.useState)(false);
+  const [error, setError] = (0, import_react19.useState)(null);
+  const fetchTable = (0, import_react19.useCallback)(
     async (targetTableId) => {
       if (!docApi) throw new Error("Grist is not ready");
       return docApi.fetchTable(targetTableId);
     },
     [docApi]
   );
-  const listTables = (0, import_react18.useCallback)(async () => {
+  const listTables = (0, import_react19.useCallback)(async () => {
     if (!docApi) throw new Error("Grist is not ready");
     const out = await Promise.resolve(docApi.listTables());
     return [...out];
   }, [docApi]);
-  const getDocName = (0, import_react18.useCallback)(async () => {
+  const getDocName = (0, import_react19.useCallback)(async () => {
     if (!docApi) throw new Error("Grist is not ready");
     return String(await Promise.resolve(docApi.getDocName()));
   }, [docApi]);
-  const fetchSelectedTable = (0, import_react18.useCallback)(
+  const fetchSelectedTable = (0, import_react19.useCallback)(
     async (fetchOptions) => {
       if (!docApi) throw new Error("Grist is not ready");
       const impl = docApi.fetchSelectedTable ?? grist.fetchSelectedTable;
@@ -2680,7 +2738,7 @@ function useGristTable(options) {
     },
     [docApi]
   );
-  const fetchSelectedRecord = (0, import_react18.useCallback)(
+  const fetchSelectedRecord = (0, import_react19.useCallback)(
     async (rowId, fetchOptions) => {
       if (!docApi) throw new Error("Grist is not ready");
       const impl = docApi.fetchSelectedRecord ?? grist.fetchSelectedRecord;
@@ -2690,7 +2748,7 @@ function useGristTable(options) {
     },
     [docApi]
   );
-  const refresh = (0, import_react18.useCallback)(async () => {
+  const refresh = (0, import_react19.useCallback)(async () => {
     if (!docApi) return;
     if (!isCurrentMode(tableIdOption)) {
       setTableId(tableIdOption);
@@ -2709,7 +2767,7 @@ function useGristTable(options) {
       setLoading(false);
     }
   }, [docApi, tableIdOption]);
-  (0, import_react18.useEffect)(() => {
+  (0, import_react19.useEffect)(() => {
     if (docApi) void refresh();
   }, [docApi, refresh]);
   return {
@@ -2727,6 +2785,7 @@ function useGristTable(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GristHandshakeProvider,
+  useAmbientGristHandshake,
   useGristAccessToken,
   useGristActions,
   useGristAvailability,