grist-widget-sdk 0.3.25 → 0.3.27

package/dist/{chunk-TZB3OZA6.js → chunk-NO6FYX33.js}

@@ -3,7 +3,64 @@ import {
   formatInsufficientAccessMessage,
   isAccessSufficient,
   parseGristRequiredAccess
-} from "./chunk-N3X46JW2.js";
+} from "./chunk-OPTOYD2Y.js";
+
+// 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((token) => {
+    cache.set(key, { token, fetchedAt: Date.now() });
+    inFlight.delete(key);
+    return token;
+  });
+  inFlight.set(key, next);
+  return next;
+}
+function clearGristAccessTokenCache() {
+  cache.clear();
+  inFlight.clear();
+}
+async function fetchWithGristAuth(docApi, path, init) {
+  const readOnly = init?.readOnly ?? false;
+  let token;
+  try {
+    token = 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(`${token.baseUrl.replace(/\/$/, "")}${cleanPath}`);
+  if (!url.searchParams.has("auth")) url.searchParams.set("auth", token.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-mappings.ts
 function asColumnSpec(entry) {
@@ -42,6 +99,9 @@ var pendingColumnMappingStatus = {
   emptyMultiples: []
 };
 
+// src/sdk/internal/hooks/use-grist-core.ts
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+
 // src/sdk/internal/handshake/types.ts
 var ZERO_GENERATION = 0;
 function nextGeneration(current) {
@@ -70,142 +130,6 @@ function initialGristSnapshot() {
   };
 }
 
-// src/sdk/internal/handshake/derive.ts
-function deriveStatus(snapshot) {
-  const { lifecycle, authz, link } = snapshot;
-  if (lifecycle.phase === "idle" || lifecycle.phase === "detecting") return "booting";
-  if (lifecycle.phase === "negotiating") return "booting";
-  if (lifecycle.phase === "terminated") {
-    switch (lifecycle.reason.kind) {
-      case "script_timeout":
-      case "not_embedded":
-        return "unavailable";
-      case "host_rejected":
-      case "ready_failed":
-      case "ready_timeout":
-      case "manual_terminate":
-        return "error";
-    }
-  }
-  if (authz.state === "denied") return "error";
-  if (link.state === "lost") return "error";
-  return "ready";
-}
-function deriveErrorMessage(snapshot) {
-  if (snapshot.lifecycle.phase === "terminated") {
-    switch (snapshot.lifecycle.reason.kind) {
-      case "ready_failed":
-        return snapshot.lifecycle.reason.message;
-      case "ready_timeout":
-        return `Grist handshake timed out after ${snapshot.lifecycle.reason.afterMs}ms`;
-      case "host_rejected":
-        return snapshot.lifecycle.reason.message;
-      case "script_timeout":
-        return `Grist plugin API never loaded (${snapshot.lifecycle.reason.attempts} attempts)`;
-      case "not_embedded":
-        return "This page is not embedded in a Grist iframe";
-      case "manual_terminate":
-        return null;
-    }
-  }
-  if (snapshot.authz.state === "denied") {
-    return snapshot.authz.message ?? `Grist denied requested access (${snapshot.authz.declared})`;
-  }
-  if (snapshot.lifecycle.phase === "online" && snapshot.link.state === "lost") {
-    return `Grist link lost (${snapshot.link.missedPings} consecutive failures)`;
-  }
-  return null;
-}
-function deriveCapabilities(snapshot) {
-  const { lifecycle, authz, link, config, sync } = snapshot;
-  const online = lifecycle.phase === "online";
-  const granted = authz.state === "granted";
-  const grantedReadOrMore = granted && ACCESS_RANK[authz.level] >= ACCESS_RANK["read table"];
-  const grantedFull = granted && authz.level === "full";
-  const linkUsable = link.state !== "lost";
-  const canRead = online && linkUsable && grantedReadOrMore;
-  const canFetchTable = canRead && link.state === "connected";
-  const mappingsUsable = hasUsableMappings(config.mappings);
-  const missing = mappingsMissing(config.mappings);
-  const emptyMultiples = mappingsEmptyMultiples(config.mappings);
-  const canRender = canRead && mappingsUsable;
-  const canWriteRecords = canRender && grantedFull;
-  const canWriteSchema = canWriteRecords && sync.currentTable.state === "known";
-  const hasFreshSelection = canRead && sync.record.state === "hot" && config.mappings.state !== "invalidating";
-  return {
-    canRead,
-    canRender,
-    canWriteRecords,
-    canWriteSchema,
-    canFetchTable,
-    hasFreshSelection,
-    hasUsableMappings: mappingsUsable,
-    missingMappings: missing,
-    emptyMultipleMappings: emptyMultiples
-  };
-}
-function hasUsableMappings(state) {
-  if (state.state === "not_declared") return true;
-  if (state.state === "complete") return true;
-  if (state.state === "invalidating") {
-    return state.previous.state === "complete";
-  }
-  return false;
-}
-function mappingsMissing(state) {
-  if (state.state === "incomplete") return state.missing;
-  if (state.state === "invalidating" && state.previous.state === "incomplete") {
-    return state.previous.missing;
-  }
-  return EMPTY;
-}
-function mappingsEmptyMultiples(state) {
-  if (state.state === "incomplete") return state.emptyMultiples;
-  if (state.state === "invalidating" && state.previous.state === "incomplete") {
-    return state.previous.emptyMultiples;
-  }
-  return EMPTY;
-}
-var EMPTY = Object.freeze([]);
-function extractResolvedMappings(state) {
-  switch (state.state) {
-    case "complete":
-    case "incomplete":
-      return state.mappings;
-    case "invalidating":
-      if (state.previous.state === "complete" || state.previous.state === "incomplete") {
-        return state.previous.mappings;
-      }
-      return null;
-    default:
-      return null;
-  }
-}
-function deriveColumnMappingStatus(mappingState, columns) {
-  if (!columns?.length) {
-    return { ok: true, pending: false, missing: [], emptyMultiples: [] };
-  }
-  switch (mappingState.state) {
-    case "not_declared":
-      return { ok: true, pending: false, missing: [], emptyMultiples: [] };
-    case "pending":
-      return pendingColumnMappingStatus;
-    case "unreported":
-      return pendingColumnMappingStatus;
-    case "complete":
-      return { ok: true, pending: false, missing: [], emptyMultiples: [] };
-    case "incomplete":
-      return {
-        ok: false,
-        pending: false,
-        missing: [...mappingState.missing],
-        emptyMultiples: [...mappingState.emptyMultiples]
-      };
-    case "invalidating":
-      return deriveColumnMappingStatus(mappingState.previous, columns);
-  }
-}
-
 // src/sdk/internal/handshake/actions.ts
 function hasGenerationStamp(action) {
   return "generation" in action && typeof action.generation === "number";
@@ -707,197 +631,212 @@ function updateSync(snapshot, sync) {
   return { ...snapshot, sync };
 }
 
-// src/sdk/helpers/grist-widget-interaction.ts
-function parseGristWidgetLinkingInfo(raw) {
-  if (!raw || typeof raw !== "object" || !("asTarget" in raw)) return void 0;
-  const linking = raw;
-  return {
-    asTarget: linking.asTarget == null ? null : String(linking.asTarget),
-    asSource: Boolean(linking.asSource)
-  };
+// src/sdk/internal/handshake/derive.ts
+function deriveStatus(snapshot) {
+  const { lifecycle, authz, link } = snapshot;
+  if (lifecycle.phase === "idle" || lifecycle.phase === "detecting") return "booting";
+  if (lifecycle.phase === "negotiating") return "booting";
+  if (lifecycle.phase === "terminated") {
+    switch (lifecycle.reason.kind) {
+      case "script_timeout":
+      case "not_embedded":
+        return "unavailable";
+      case "host_rejected":
+      case "ready_failed":
+      case "ready_timeout":
+      case "manual_terminate":
+        return "error";
+    }
+  }
+  if (authz.state === "denied") return "error";
+  if (link.state === "lost") return "error";
+  return "ready";
 }
-function normalizeWidgetInteraction(interaction) {
-  if (!interaction || typeof interaction !== "object") return interaction;
-  const raw = interaction;
-  const access_level = typeof raw.access_level === "string" ? raw.access_level : typeof raw.accessLevel === "string" ? raw.accessLevel : void 0;
-  const linking = parseGristWidgetLinkingInfo(raw.linking);
+function deriveErrorMessage(snapshot) {
+  if (snapshot.lifecycle.phase === "terminated") {
+    switch (snapshot.lifecycle.reason.kind) {
+      case "ready_failed":
+        return snapshot.lifecycle.reason.message;
+      case "ready_timeout":
+        return `Grist handshake timed out after ${snapshot.lifecycle.reason.afterMs}ms`;
+      case "host_rejected":
+        return snapshot.lifecycle.reason.message;
+      case "script_timeout":
+        return `Grist plugin API never loaded (${snapshot.lifecycle.reason.attempts} attempts)`;
+      case "not_embedded":
+        return "This page is not embedded in a Grist iframe";
+      case "manual_terminate":
+        return null;
+    }
+  }
+  if (snapshot.authz.state === "denied") {
+    return snapshot.authz.message ?? `Grist denied requested access (${snapshot.authz.declared})`;
+  }
+  if (snapshot.lifecycle.phase === "online" && snapshot.link.state === "lost") {
+    return `Grist link lost (${snapshot.link.missedPings} consecutive failures)`;
+  }
+  return null;
+}
+function deriveCapabilities(snapshot) {
+  const { lifecycle, authz, link, config, sync } = snapshot;
+  const online = lifecycle.phase === "online";
+  const granted = authz.state === "granted";
+  const grantedReadOrMore = granted && ACCESS_RANK[authz.level] >= ACCESS_RANK["read table"];
+  const grantedFull = granted && authz.level === "full";
+  const linkUsable = link.state !== "lost";
+  const canRead = online && linkUsable && grantedReadOrMore;
+  const canFetchTable = canRead && link.state === "connected";
+  const mappingsUsable = hasUsableMappings(config.mappings);
+  const missing = mappingsMissing(config.mappings);
+  const emptyMultiples = mappingsEmptyMultiples(config.mappings);
+  const canRender = canRead && mappingsUsable;
+  const canWriteRecords = canRender && grantedFull;
+  const canWriteSchema = canWriteRecords && sync.currentTable.state === "known";
+  const hasFreshSelection = canRead && sync.record.state === "hot" && config.mappings.state !== "invalidating";
   return {
-    ...interaction,
-    ...access_level ? { access_level } : {},
-    ...linking ? { linking } : {}
+    canRead,
+    canRender,
+    canWriteRecords,
+    canWriteSchema,
+    canFetchTable,
+    hasFreshSelection,
+    hasUsableMappings: mappingsUsable,
+    missingMappings: missing,
+    emptyMultipleMappings: emptyMultiples
   };
 }
-
-// src/sdk/internal/ready-singleton.ts
-var ACCESS_RANK2 = {
-  none: 0,
-  "read table": 1,
-  full: 2
-};
-var inFlight = null;
-var lastAccess = null;
-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;
-  if (ACCESS_RANK2[next] > ACCESS_RANK2[lastAccess]) return true;
-  for (const name of nextColumns) {
-    if (!lastColumnNames?.has(name)) return true;
+function hasUsableMappings(state) {
+  if (state.state === "not_declared") return true;
+  if (state.state === "complete") return true;
+  if (state.state === "invalidating") {
+    return state.previous.state === "complete";
   }
   return false;
 }
-function ensureGristReady(payload) {
-  const access = payload.requiredAccess ?? "read table";
-  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();
-  });
-  inFlight = next.catch((err) => {
-    inFlight = null;
-    lastAccess = null;
-    lastColumnNames = null;
-    throw err;
-  });
-  return inFlight;
-}
-function resetGristReadySingleton() {
-  inFlight = null;
-  lastAccess = null;
-  lastColumnNames = null;
-}
-var resetGristReadyCacheForTests = resetGristReadySingleton;
-
-// src/sdk/internal/subscriptions.ts
-var GristEvent = class {
-  constructor(bindOnce) {
-    this.bindOnce = bindOnce;
-    this.listeners = /* @__PURE__ */ new Set();
-    this.hasValue = false;
-    this.bind = null;
-  }
-  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);
-    }
-    return () => {
-      this.listeners.delete(listener);
-    };
+function mappingsMissing(state) {
+  if (state.state === "incomplete") return state.missing;
+  if (state.state === "invalidating" && state.previous.state === "incomplete") {
+    return state.previous.missing;
   }
-  /** Last cached value (or `undefined` if no event has fired yet). */
-  peek() {
-    return this.last;
+  return EMPTY;
+}
+function mappingsEmptyMultiples(state) {
+  if (state.state === "incomplete") return state.emptyMultiples;
+  if (state.state === "invalidating" && state.previous.state === "incomplete") {
+    return state.previous.emptyMultiples;
   }
-  /** True once at least one event has fired. */
-  get ready() {
-    return this.hasValue;
+  return EMPTY;
+}
+var EMPTY = Object.freeze([]);
+function extractResolvedMappings(state) {
+  switch (state.state) {
+    case "complete":
+    case "incomplete":
+      return state.mappings;
+    case "invalidating":
+      if (state.previous.state === "complete" || state.previous.state === "incomplete") {
+        return state.previous.mappings;
+      }
+      return null;
+    default:
+      return null;
   }
-  /**
-   * 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;
-    this.last = value;
-    for (const l of this.listeners) l(value);
+}
+function deriveColumnMappingStatus(mappingState, columns) {
+  if (!columns?.length) {
+    return { ok: true, pending: false, missing: [], emptyMultiples: [] };
   }
-  /**
-   * 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() {
-    this.listeners.clear();
-    this.hasValue = false;
-    this.last = void 0;
-    this.bind = null;
+  switch (mappingState.state) {
+    case "not_declared":
+      return { ok: true, pending: false, missing: [], emptyMultiples: [] };
+    case "pending":
+      return pendingColumnMappingStatus;
+    case "unreported":
+      return pendingColumnMappingStatus;
+    case "complete":
+      return { ok: true, pending: false, missing: [], emptyMultiples: [] };
+    case "incomplete":
+      return {
+        ok: false,
+        pending: false,
+        missing: [...mappingState.missing],
+        emptyMultiples: [...mappingState.emptyMultiples]
+      };
+    case "invalidating":
+      return deriveColumnMappingStatus(mappingState.previous, columns);
   }
+}
+
+// src/sdk/internal/handshake-manager-context.ts
+import { createContext, useContext, useEffect, useRef } from "react";
+
+// src/sdk/internal/ready-singleton.ts
+var ACCESS_RANK2 = {
+  none: 0,
+  "read table": 1,
+  full: 2
 };
-var recordEvent = new GristEvent((emit) => {
-  const deliver = (record, mappings) => {
-    emit({ record, mappings });
-  };
-  grist.onRecord(
-    (record, mappings) => {
-      deliver(record, mappings ?? null);
-    },
-    { keepEncoded: false }
-  );
-  const fetchSelectedRecord = grist.fetchSelectedRecord ?? grist.docApi?.fetchSelectedRecord;
-  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;
-    lastRowId = host.rowId;
-    try {
-      const record = await fetchSelectedRecord(host.rowId, { keepEncoded: false });
-      deliver(record, recordEvent.peek()?.mappings ?? null);
-    } catch (err) {
-      if (typeof console !== "undefined") {
-        console.error("[grist-widget-sdk] fetchSelectedRecord on cursor message failed:", err);
-      }
-    }
-  });
-});
-var recordsEvent = new GristEvent((emit) => {
-  grist.onRecords(
-    (records, mappings) => {
-      emit({ records, mappings: mappings ?? null });
-    },
-    { keepEncoded: false, format: "rows" }
-  );
-});
-var optionsEvent = new GristEvent((emit) => {
-  grist.onOptions((options, interaction) => {
-    const normalized = normalizeWidgetInteraction(
-      interaction ?? null
-    );
-    emit({
-      options: options ? { ...options } : null,
-      interaction: normalized
-    });
+var inFlight2 = null;
+var lastAccess = null;
+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;
+  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();
   });
-});
-var newRecordEvent = new GristEvent((emit) => {
-  if (typeof grist.onNewRecord !== "function") return;
-  grist.onNewRecord((mappings) => {
-    emit({ mappings: mappings ?? null });
+  inFlight2 = next.catch((err) => {
+    inFlight2 = null;
+    lastAccess = null;
+    lastColumnNames = null;
+    throw err;
   });
-});
-function resetGristEventsForTests() {
-  recordEvent._resetForTests();
-  recordsEvent._resetForTests();
-  optionsEvent._resetForTests();
-  newRecordEvent._resetForTests();
+  return inFlight2;
+}
+function resetGristReadySingleton() {
+  inFlight2 = null;
+  lastAccess = null;
+  lastColumnNames = null;
+}
+var resetGristReadyCacheForTests = resetGristReadySingleton;
+
+// src/sdk/internal/build-manager-options.ts
+function buildManagerOptionsFromGristOptions(options) {
+  const opts = {
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns ?? [],
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions,
+    negotiate: {
+      readyImpl: (payload) => ensureGristReady(payload)
+    },
+    onBeforeReload: () => resetGristReadySingleton()
+  };
+  if (options?.availabilityMaxAttempts !== void 0 || options?.availabilityIntervalMs !== void 0) {
+    const interval = options?.availabilityIntervalMs ?? 1e3;
+    const max = options?.availabilityMaxAttempts ?? 10;
+    opts.detect = {
+      pollSequenceMs: Array.from({ length: max }, () => interval),
+      budgetMs: interval * max
+    };
+  }
+  return opts;
 }
 
 // src/sdk/internal/handshake/effects/detect.ts
@@ -1049,6 +988,154 @@ function startNegotiateEffect(env, dispatch, signal, payload, options = {}) {
   }) };
 }
 
+// src/sdk/helpers/grist-widget-interaction.ts
+function parseGristWidgetLinkingInfo(raw) {
+  if (!raw || typeof raw !== "object" || !("asTarget" in raw)) return void 0;
+  const linking = raw;
+  return {
+    asTarget: linking.asTarget == null ? null : String(linking.asTarget),
+    asSource: Boolean(linking.asSource)
+  };
+}
+function normalizeWidgetInteraction(interaction) {
+  if (!interaction || typeof interaction !== "object") return interaction;
+  const raw = interaction;
+  const access_level = typeof raw.access_level === "string" ? raw.access_level : typeof raw.accessLevel === "string" ? raw.accessLevel : void 0;
+  const linking = parseGristWidgetLinkingInfo(raw.linking);
+  return {
+    ...interaction,
+    ...access_level ? { access_level } : {},
+    ...linking ? { linking } : {}
+  };
+}
+
+// src/sdk/internal/subscriptions.ts
+var GristEvent = class {
+  constructor(bindOnce) {
+    this.bindOnce = bindOnce;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.hasValue = false;
+    this.bind = null;
+  }
+  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);
+    }
+    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;
+    this.last = 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() {
+    this.listeners.clear();
+    this.hasValue = 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 }
+  );
+  const fetchSelectedRecord = grist.fetchSelectedRecord ?? grist.docApi?.fetchSelectedRecord;
+  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;
+    lastRowId = host.rowId;
+    try {
+      const record = await fetchSelectedRecord(host.rowId, { keepEncoded: false });
+      deliver(record, recordEvent.peek()?.mappings ?? null);
+    } catch (err) {
+      if (typeof console !== "undefined") {
+        console.error("[grist-widget-sdk] fetchSelectedRecord on cursor message failed:", err);
+      }
+    }
+  });
+});
+var recordsEvent = new GristEvent((emit) => {
+  grist.onRecords(
+    (records, mappings) => {
+      emit({ records, mappings: mappings ?? null });
+    },
+    { keepEncoded: false, format: "rows" }
+  );
+});
+var optionsEvent = new GristEvent((emit) => {
+  grist.onOptions((options, interaction) => {
+    const normalized = normalizeWidgetInteraction(
+      interaction ?? null
+    );
+    emit({
+      options: options ? { ...options } : null,
+      interaction: normalized
+    });
+  });
+});
+var newRecordEvent = new GristEvent((emit) => {
+  if (typeof grist.onNewRecord !== "function") return;
+  grist.onNewRecord((mappings) => {
+    emit({ mappings: mappings ?? null });
+  });
+});
+function resetGristEventsForTests() {
+  recordEvent._resetForTests();
+  recordsEvent._resetForTests();
+  optionsEvent._resetForTests();
+  newRecordEvent._resetForTests();
+}
+
 // src/sdk/internal/handshake/effects/subscriptions.ts
 function defaultSubscriptionsBinder(ctx) {
   const offs = [];
@@ -1200,7 +1287,7 @@ function startHeartbeatEffect(env, dispatch, signal, options = {}) {
   let cancelled = false;
   let paused = false;
   let intervalTimer = null;
-  let inFlight2 = false;
+  let inFlight3 = false;
   let inFlightTimeoutTimer = null;
   const clearInterval = () => {
     if (intervalTimer !== null) {
@@ -1222,13 +1309,13 @@ function startHeartbeatEffect(env, dispatch, signal, options = {}) {
   const ping = () => {
     if (cancelled || paused) return;
     intervalTimer = null;
-    if (inFlight2) {
+    if (inFlight3) {
       return;
     }
-    inFlight2 = true;
+    inFlight3 = true;
     inFlightTimeoutTimer = env.setTimeout(() => {
-      if (!inFlight2) return;
-      inFlight2 = false;
+      if (!inFlight3) return;
+      inFlight3 = false;
       clearInFlightTimeout();
       if (!cancelled) {
         dispatch({ type: "HEARTBEAT_FAIL", atMs: env.now() });
@@ -1236,16 +1323,16 @@ function startHeartbeatEffect(env, dispatch, signal, options = {}) {
       }
     }, pingTimeoutMs);
     const handleOk = () => {
-      if (!inFlight2) return;
-      inFlight2 = false;
+      if (!inFlight3) return;
+      inFlight3 = false;
       clearInFlightTimeout();
       if (cancelled) return;
       dispatch({ type: "HEARTBEAT_OK", atMs: env.now() });
       scheduleNext();
     };
     const handleFail = () => {
-      if (!inFlight2) return;
-      inFlight2 = false;
+      if (!inFlight3) return;
+      inFlight3 = false;
       clearInFlightTimeout();
       if (cancelled) return;
       dispatch({ type: "HEARTBEAT_FAIL", atMs: env.now() });
@@ -1285,7 +1372,7 @@ function startHeartbeatEffect(env, dispatch, signal, options = {}) {
     cancelled = true;
     clearInterval();
     clearInFlightTimeout();
-    inFlight2 = false;
+    inFlight3 = false;
     offVisibility?.();
     offOnline?.();
   });
@@ -1295,7 +1382,7 @@ function startHeartbeatEffect(env, dispatch, signal, options = {}) {
       cancelled = true;
       clearInterval();
       clearInFlightTimeout();
-      inFlight2 = false;
+      inFlight3 = false;
       offVisibility?.();
       offOnline?.();
     },
@@ -1605,7 +1692,351 @@ function resetEmbeddedHandshakeManagerForTests() {
   }
 }
 
+// src/sdk/internal/handshake-manager-context.ts
+var GristHandshakeManagerContext = createContext(null);
+function useGristManagerOptional() {
+  return useContext(GristHandshakeManagerContext);
+}
+function useGristManager(options) {
+  const fromProvider = useContext(GristHandshakeManagerContext);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const embeddedRef = useRef(null);
+  const ownsEmbeddedRef = useRef(false);
+  if (fromProvider) {
+    return fromProvider;
+  }
+  if (embeddedRef.current === null) {
+    embeddedRef.current = acquireEmbeddedHandshakeManager(
+      buildManagerOptionsFromGristOptions(optionsRef.current)
+    );
+    ownsEmbeddedRef.current = true;
+  }
+  useEffect(() => {
+    if (!ownsEmbeddedRef.current) return;
+    return () => {
+      releaseEmbeddedHandshakeManager();
+      embeddedRef.current = null;
+      ownsEmbeddedRef.current = false;
+    };
+  }, []);
+  return embeddedRef.current;
+}
+
+// src/sdk/internal/hooks/use-grist-core.ts
+function computeAvailabilityFromSnapshot(snapshot) {
+  const { phase } = snapshot.lifecycle;
+  if (phase === "idle" || phase === "detecting") return null;
+  if (phase === "terminated") {
+    const reason = snapshot.lifecycle.reason.kind;
+    if (reason === "not_embedded" || reason === "script_timeout") return false;
+    return true;
+  }
+  return true;
+}
+function useGristCore(options) {
+  const manager = useGristManager(options);
+  return useGristCoreFromManager(manager);
+}
+function useGristCoreFromManager(manager) {
+  const snapshot = useSyncExternalStore(
+    manager.subscribe,
+    manager.getSnapshot,
+    initialGristSnapshot
+  );
+  const status = deriveStatus(snapshot);
+  const error = deriveErrorMessage(snapshot);
+  const docApi = snapshot.lifecycle.phase === "online" && typeof grist !== "undefined" ? grist.docApi ?? null : null;
+  const isAvailable = computeAvailabilityFromSnapshot(snapshot);
+  const reload = useCallback(async () => {
+    manager.reload();
+  }, [manager]);
+  const capabilities = useMemo(() => deriveCapabilities(snapshot), [snapshot]);
+  return useMemo(
+    () => ({
+      status,
+      isAvailable,
+      isReady: status === "ready",
+      error,
+      docApi,
+      capabilities,
+      reload
+    }),
+    [status, isAvailable, error, docApi, capabilities, reload]
+  );
+}
+
+// src/sdk/low-level-hooks/use-grist-ready.ts
+function useGristReady(options) {
+  const { isAvailable, docApi, error, reload } = useGristCore(options);
+  return { isAvailable, docApi, error, reload };
+}
+
+// src/sdk/mid-level-hooks/use-grist-widget-options-from-context.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo3, useRef as useRef2, useState } from "react";
+
+// src/sdk/internal/contexts.tsx
+import { createContext as createContext2, useContext as useContext2, useMemo as useMemo2 } from "react";
+
+// src/sdk/internal/merge-grist-result.ts
+function mergeGristResultFromSlices(slices) {
+  const { core, selection, currentTable, writes, reads, widgetOptionsApi, linking, attachmentsRest, theme, sectionApi, suppressAlerts, allowSelectBy } = slices;
+  return {
+    status: core.status,
+    isAvailable: core.isAvailable,
+    isReady: core.isReady,
+    error: core.error,
+    capabilities: core.capabilities,
+    record: selection.record,
+    records: selection.records,
+    mappedRecord: selection.mappedRecord,
+    mappings: selection.mappings,
+    recordsMappings: selection.recordsMappings,
+    columnMappingStatus: selection.columnMappingStatus,
+    mode: selection.mode,
+    resolveMappedColumnId: selection.resolveMappedColumnId,
+    mapBack: selection.mapBack,
+    mapBackSkipped: selection.mapBackSkipped,
+    isNewRecord: selection.isNewRecord,
+    newRecordMappings: selection.newRecordMappings,
+    currentTableId: currentTable.currentTableId,
+    currentTableLoading: currentTable.currentTableLoading,
+    refreshCurrentTable: currentTable.refreshCurrentTable,
+    table: writes.table,
+    getTable: writes.getTable,
+    actionStatus: writes.actionStatus,
+    actionError: writes.actionError,
+    applyActions: writes.applyActions,
+    reload: core.reload,
+    fetchTable: reads.fetchTable,
+    fetchTableRows: reads.fetchTableRows,
+    fetchRow: reads.fetchRow,
+    listTables: reads.listTables,
+    listColumns: reads.listColumns,
+    getDocName: reads.getDocName,
+    buildReplicaDocumentFromDocApi: reads.buildReplicaDocumentFromDocApi,
+    getAttachmentUrl: attachmentsRest.getAttachmentUrl,
+    fetchAttachmentBase64: attachmentsRest.fetchAttachmentBase64,
+    fetchAttachmentBlob: attachmentsRest.fetchAttachmentBlob,
+    widgetOptions: selection.widgetOptions,
+    widgetInteraction: selection.widgetInteraction,
+    getWidgetOptions: widgetOptionsApi.getWidgetOptions,
+    getWidgetOption: widgetOptionsApi.getWidgetOption,
+    setWidgetOption: widgetOptionsApi.setWidgetOption,
+    setWidgetOptions: widgetOptionsApi.setWidgetOptions,
+    patchWidgetOptions: widgetOptionsApi.patchWidgetOptions,
+    clearWidgetOptions: widgetOptionsApi.clearWidgetOptions,
+    fetchSelectedTable: reads.fetchSelectedTable,
+    fetchSelectedRecord: reads.fetchSelectedRecord,
+    readError: reads.readError ?? attachmentsRest.readError,
+    setCursorPosition: linking.setCursorPosition,
+    setLinkedRowSelection: linking.setLinkedRowSelection,
+    getAccessToken: attachmentsRest.getAccessToken,
+    fetchWithAuth: attachmentsRest.fetchWithAuth,
+    uploadAttachment: attachmentsRest.uploadAttachment,
+    theme: theme.theme,
+    configure: sectionApi.configure,
+    refreshMappings: sectionApi.refreshMappings,
+    suppressAlerts,
+    allowSelectBy
+  };
+}
+
+// src/sdk/internal/contexts.tsx
+var GristCoreContext = createContext2(null);
+var GristSelectionContext = createContext2(null);
+var GristCurrentTableContext = createContext2(null);
+var GristWritesContext = createContext2(null);
+var GristReadsContext = createContext2(null);
+var GristWidgetOptionsApiContext = createContext2(null);
+var GristLinkingContext = createContext2(null);
+var GristAttachmentsRestContext = createContext2(null);
+var GristThemeContext = createContext2(null);
+var GristSectionApiContext = createContext2(null);
+function useRequiredContext(ctx, name) {
+  const value = useContext2(ctx);
+  if (!value) {
+    throw new Error(`${name} must be used inside <GristWidgetProvider>`);
+  }
+  return value;
+}
+function useGristCoreContext() {
+  return useRequiredContext(GristCoreContext, "useGristCoreContext()");
+}
+function useGristSelectionContext() {
+  return useRequiredContext(GristSelectionContext, "useGristSelectionContext()");
+}
+function useGristCurrentTableContext() {
+  return useRequiredContext(GristCurrentTableContext, "useGristCurrentTableContext()");
+}
+function useGristWritesContext() {
+  return useRequiredContext(GristWritesContext, "useGristWritesContext()");
+}
+function useGristReadsContext() {
+  return useRequiredContext(GristReadsContext, "useGristReadsContext()");
+}
+function useGristWidgetOptionsApiContext() {
+  return useRequiredContext(GristWidgetOptionsApiContext, "useGristWidgetOptionsApiContext()");
+}
+function useGristLinkingContext() {
+  return useRequiredContext(GristLinkingContext, "useGristLinkingContext()");
+}
+function useGristAttachmentsRestContext() {
+  return useRequiredContext(GristAttachmentsRestContext, "useGristAttachmentsRestContext()");
+}
+function useGristThemeContext() {
+  return useRequiredContext(GristThemeContext, "useGristThemeContext()");
+}
+function useGristSectionApiContext() {
+  return useRequiredContext(GristSectionApiContext, "useGristSectionApiContext()");
+}
+function useGristFromProvider() {
+  const core = useGristCoreContext();
+  const selection = useGristSelectionContext();
+  const currentTable = useGristCurrentTableContext();
+  const writes = useGristWritesContext();
+  const reads = useGristReadsContext();
+  const widgetOptionsApi = useGristWidgetOptionsApiContext();
+  const linking = useGristLinkingContext();
+  const attachmentsRest = useGristAttachmentsRestContext();
+  const theme = useGristThemeContext();
+  const sectionApi = useGristSectionApiContext();
+  return useMemo2(
+    () => mergeGristResultFromSlices({
+      core,
+      selection,
+      currentTable,
+      writes,
+      reads,
+      widgetOptionsApi,
+      linking,
+      attachmentsRest,
+      theme,
+      sectionApi
+    }),
+    [
+      core,
+      selection,
+      currentTable,
+      writes,
+      reads,
+      widgetOptionsApi,
+      linking,
+      attachmentsRest,
+      theme,
+      sectionApi
+    ]
+  );
+}
+
+// src/sdk/mid-level-hooks/use-grist-widget-options-from-context.ts
+function mergeWithDefaults(defaults, stored, namespace) {
+  if (stored === null || stored === void 0) return { ...defaults };
+  const source = namespace ? stored[namespace] : stored;
+  if (!source || typeof source !== "object") return { ...defaults };
+  return { ...defaults, ...source };
+}
+function useGristWidgetOptionsFromContext(config) {
+  const debounceMs = config.debounceMs ?? 250;
+  const selection = useGristSelectionContext();
+  const optionsApi = useGristWidgetOptionsApiContext();
+  const defaultsRef = useRef2(config.defaults);
+  useEffect2(() => {
+    defaultsRef.current = config.defaults;
+  }, [config.defaults]);
+  const rawOptions = selection.widgetOptions;
+  const hasReceived = rawOptions !== null;
+  const merged = useMemo3(
+    () => mergeWithDefaults(defaultsRef.current, rawOptions, config.namespace),
+    [rawOptions, config.namespace]
+  );
+  const [localOverride, setLocalOverride] = useState(null);
+  const options = localOverride ?? merged;
+  useEffect2(() => {
+    setLocalOverride(null);
+  }, [rawOptions]);
+  const debounceRef = useRef2(null);
+  const flushWrite = useCallback2(
+    async (value) => {
+      if (config.namespace) {
+        await optionsApi.setWidgetOption(config.namespace, value);
+      } else {
+        await optionsApi.setWidgetOptions({ ...value });
+      }
+    },
+    [config.namespace, optionsApi]
+  );
+  const scheduleWrite = useCallback2(
+    (value) => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+      debounceRef.current = window.setTimeout(() => {
+        debounceRef.current = null;
+        void flushWrite(value);
+      }, debounceMs);
+    },
+    [debounceMs, flushWrite]
+  );
+  useEffect2(() => {
+    return () => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+    };
+  }, []);
+  const setOptions = useCallback2(
+    (next) => {
+      setLocalOverride(next);
+      scheduleWrite(next);
+    },
+    [scheduleWrite]
+  );
+  const patchOptions = useCallback2(
+    (patch) => {
+      setLocalOverride((prev) => {
+        const base = prev ?? merged;
+        const next = { ...base, ...patch };
+        scheduleWrite(next);
+        return next;
+      });
+    },
+    [merged, scheduleWrite]
+  );
+  const reset = useCallback2(async () => {
+    if (debounceRef.current) {
+      window.clearTimeout(debounceRef.current);
+      debounceRef.current = null;
+    }
+    const next = { ...defaultsRef.current };
+    setLocalOverride(null);
+    await flushWrite(next);
+  }, [flushWrite]);
+  return useMemo3(
+    () => ({
+      options,
+      loading: !hasReceived,
+      setOptions,
+      patchOptions,
+      reset
+    }),
+    [options, hasReceived, setOptions, patchOptions, reset]
+  );
+}
+
+// src/sdk/internal/hooks/use-rpc-heartbeat-coalesce.ts
+import { useCallback as useCallback3 } from "react";
+function useRpcHeartbeatCoalesce() {
+  const manager = useGristManagerOptional();
+  return useCallback3(
+    async (fn) => {
+      const result = await fn();
+      manager?.recordRpcSuccess();
+      return result;
+    },
+    [manager]
+  );
+}
+
 export {
+  getGristAccessToken,
+  fetchWithGristAuth,
   validateColumnMappings,
   initialGristSnapshot,
   deriveStatus,
@@ -1617,14 +2048,37 @@ export {
   ensureGristReady,
   resetGristReadySingleton,
   resetGristReadyCacheForTests,
+  buildManagerOptionsFromGristOptions,
   recordEvent,
   recordsEvent,
   optionsEvent,
   newRecordEvent,
   resetGristEventsForTests,
   createGristHandshakeManager,
-  acquireEmbeddedHandshakeManager,
-  releaseEmbeddedHandshakeManager,
-  resetEmbeddedHandshakeManagerForTests
+  resetEmbeddedHandshakeManagerForTests,
+  GristHandshakeManagerContext,
+  useGristManagerOptional,
+  useGristManager,
+  mergeGristResultFromSlices,
+  GristCoreContext,
+  GristSelectionContext,
+  GristCurrentTableContext,
+  GristWritesContext,
+  GristReadsContext,
+  GristWidgetOptionsApiContext,
+  GristLinkingContext,
+  GristAttachmentsRestContext,
+  GristThemeContext,
+  GristSectionApiContext,
+  useGristCoreContext,
+  useGristSelectionContext,
+  useGristCurrentTableContext,
+  useGristWritesContext,
+  useGristThemeContext,
+  useGristFromProvider,
+  useGristCore,
+  useRpcHeartbeatCoalesce,
+  useGristReady,
+  useGristWidgetOptionsFromContext
 };
-//# sourceMappingURL=chunk-TZB3OZA6.js.map
+//# sourceMappingURL=chunk-NO6FYX33.js.map