grist-widget-sdk 0.2.0

package/dist/advanced.cjs

@@ -0,0 +1,2749 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sdk/advanced/index.ts
+var advanced_exports = {};
+__export(advanced_exports, {
+  GristHandshakeProvider: () => GristHandshakeProvider,
+  useGristAccessToken: () => useGristAccessToken,
+  useGristActions: () => useGristActions,
+  useGristAvailability: () => useGristAvailability,
+  useGristCapabilities: () => useGristCapabilities,
+  useGristHandshake: () => useGristHandshake,
+  useGristHandshakeContext: () => useGristHandshakeContext,
+  useGristHandshakeContextOptional: () => useGristHandshakeContextOptional,
+  useGristMappedRecord: () => useGristMappedRecord,
+  useGristNewRecord: () => useGristNewRecord,
+  useGristReady: () => useGristReady,
+  useGristRecord: () => useGristRecord,
+  useGristRecords: () => useGristRecords,
+  useGristRowsFromTable: () => useGristRowsFromTable,
+  useGristSection: () => useGristSection,
+  useGristTable: () => useGristTable,
+  useGristTableOps: () => useGristTableOps,
+  useGristWidgetOptions: () => useGristWidgetOptions,
+  useGristWidgetOptionsFromContext: () => useGristWidgetOptionsFromContext
+});
+module.exports = __toCommonJS(advanced_exports);
+
+// src/sdk/internal/hooks/use-grist-core.ts
+var import_react2 = require("react");
+
+// src/sdk/internal/handshake/types.ts
+var ZERO_GENERATION = 0;
+function nextGeneration(current) {
+  return current + 1;
+}
+var MAPPING_SOURCE_PRIORITY = [
+  "section_api",
+  "stream_record",
+  "stream_records",
+  "stream_new_record"
+];
+function initialGristSnapshot() {
+  return {
+    generation: ZERO_GENERATION,
+    lifecycle: { phase: "idle" },
+    link: { state: "connected", lastSuccessMs: null, missedPings: 0 },
+    authz: { state: "pending", declared: "read table" },
+    config: { mappings: { state: "not_declared" } },
+    sync: {
+      record: { state: "cold" },
+      records: { state: "cold" },
+      options: { state: "cold" },
+      newRecord: { state: "cold" },
+      currentTable: { state: "unknown" }
+    }
+  };
+}
+
+// src/sdk/internal/handshake/actions.ts
+function hasGenerationStamp(action) {
+  return "generation" in action && typeof action.generation === "number";
+}
+
+// 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/internal/handshake/mapping-resolver.ts
+var MappingResolver = class {
+  constructor(declared, generation) {
+    /** Latest accepted payload per source. */
+    this.payloads = /* @__PURE__ */ new Map();
+    /** Last resolved state, used to detect duplicate ingests. */
+    this.lastResolvedHash = null;
+    this.declared = declared;
+    this.currentGeneration = generation;
+  }
+  /**
+   * Replace the declared columns (e.g. user passed a new `columns` array to
+   * the provider). Clears accumulated payloads — they were validated against
+   * the previous declaration.
+   */
+  redeclare(declared, atGeneration) {
+    this.declared = declared;
+    this.currentGeneration = atGeneration;
+    this.payloads.clear();
+    this.lastResolvedHash = null;
+  }
+  /** Bump the active generation. Payloads from older generations are dropped. */
+  bumpGeneration(next) {
+    if (next <= this.currentGeneration) return;
+    this.currentGeneration = next;
+    for (const [src, p] of this.payloads) {
+      if (p.generation < next) this.payloads.delete(src);
+    }
+    this.lastResolvedHash = null;
+  }
+  /** Forget every payload and reset the hash. The declaration is preserved. */
+  reset() {
+    this.payloads.clear();
+    this.lastResolvedHash = null;
+  }
+  /** Cheap, deterministic snapshot for tests/debug. */
+  knownSources() {
+    return [...this.payloads.keys()];
+  }
+  /**
+   * Ingest one payload. Returns a {@link ResolveOutcome}:
+   *   - `still_pending`        — no payloads accepted yet.
+   *   - `no_change/stale_*`    — input generation is older than current.
+   *   - `no_change/duplicate_payload` — input did not move the resolution.
+   *   - `resolved`             — new resolution differs from the previous one.
+   *
+   * Call {@link current} to read the latest resolution without affecting
+   * the duplicate-detection hash.
+   */
+  ingest(input) {
+    if (input.generation < this.currentGeneration) {
+      return { kind: "no_change", reason: "stale_generation" };
+    }
+    if (input.generation > this.currentGeneration) {
+      this.bumpGeneration(input.generation);
+    }
+    this.payloads.set(input.source, input);
+    const computed = this.compute();
+    if (computed === null) return { kind: "still_pending" };
+    const hash = computeMappingHash(
+      computed.mappings,
+      computed.state === "complete",
+      computed.source
+    );
+    if (hash === this.lastResolvedHash) {
+      return { kind: "no_change", reason: "duplicate_payload" };
+    }
+    this.lastResolvedHash = hash;
+    return { kind: "resolved", state: computed };
+  }
+  /**
+   * Return the resolver's current resolution (pure read). Equivalent to
+   * `ingest(...)` without mutating any state — used by tests and by the
+   * reducer when re-applying after `MAPPING_INVALIDATION_RESOLVE`.
+   */
+  current() {
+    const computed = this.compute();
+    if (computed === null) return { kind: "still_pending" };
+    return { kind: "resolved", state: computed };
+  }
+  /**
+   * Compute the current best mapping from accumulated payloads (pure).
+   *
+   * Priority: higher-priority sources **override** specific keys from
+   * lower-priority sources. Keys absent from a higher-priority source fall
+   * back to lower-priority sources. This matches the production behaviour
+   * where `sectionApi.mappings()` is authoritative for the keys it reports,
+   * but stream payloads can fill in keys the section_api hasn't reported yet.
+   */
+  compute() {
+    if (this.payloads.size === 0) return null;
+    const merged = {};
+    let latestReportedAt = 0;
+    const contributors = [];
+    for (const src of [...MAPPING_SOURCE_PRIORITY].reverse()) {
+      const p = this.payloads.get(src);
+      if (!p) continue;
+      contributors.push(src);
+      if (p.receivedAtMs > latestReportedAt) latestReportedAt = p.receivedAtMs;
+      if (p.payload === null) continue;
+      for (const [k, v] of Object.entries(p.payload)) {
+        merged[k] = v;
+      }
+    }
+    if (contributors.length === 0) return null;
+    const validation = validateColumnMappings(this.declared, merged);
+    const source = contributors.length === 1 ? contributors[0] : "merged";
+    if (validation.ok) {
+      return {
+        state: "complete",
+        declared: this.declared,
+        mappings: merged,
+        source,
+        reportedAtMs: latestReportedAt
+      };
+    }
+    return {
+      state: "incomplete",
+      declared: this.declared,
+      mappings: merged,
+      missing: validation.missing,
+      emptyMultiples: validation.emptyMultiples,
+      source,
+      reportedAtMs: latestReportedAt
+    };
+  }
+};
+function computeMappingHash(mappings, ok, source) {
+  const keys = Object.keys(mappings).sort();
+  const body = keys.map((k) => {
+    const v = mappings[k];
+    if (Array.isArray(v)) return `${k}=[${v.join(",")}]`;
+    return `${k}=${v ?? ""}`;
+  }).join("|");
+  return `${ok ? "OK" : "KO"}::${source}::${body}`;
+}
+
+// src/sdk/internal/handshake/access.ts
+var ACCESS_RANK = {
+  none: 0,
+  "read table": 1,
+  full: 2
+};
+var GRIST_ACCESS_LEVELS = ["none", "read table", "full"];
+function parseGristRequiredAccess(raw) {
+  if (!raw) return null;
+  return GRIST_ACCESS_LEVELS.includes(raw) ? raw : null;
+}
+function isAccessSufficient(granted, required) {
+  return ACCESS_RANK[granted] >= ACCESS_RANK[required];
+}
+function gristAccessLevelLabel(level) {
+  switch (level) {
+    case "none":
+      return "No document access";
+    case "read table":
+      return "Read selected table";
+    case "full":
+      return "Full document access";
+  }
+}
+function formatInsufficientAccessMessage(required, _granted) {
+  const need = gristAccessLevelLabel(required);
+  return `Set Access level to at least "${need}" in the Custom widget settings.`;
+}
+
+// src/sdk/internal/handshake/reducer.ts
+function createReducerContext() {
+  return { resolver: null };
+}
+var DEFAULT_REDUCER_CONFIG = {
+  staleAfterMissed: 1,
+  lostAfterMissed: 3
+};
+function gristReducer(snapshot, action, ctx, config = DEFAULT_REDUCER_CONFIG) {
+  if (hasGenerationStamp(action) && action.generation < snapshot.generation) {
+    return snapshot;
+  }
+  switch (action.type) {
+    // -- Lifecycle --------------------------------------------------------
+    case "DETECT_START":
+      return reduceDetectStart(snapshot, action.atMs);
+    case "DETECT_TICK":
+      return reduceDetectTick(snapshot, action.attempts);
+    case "DETECT_AVAILABLE":
+      return reduceDetectAvailable(snapshot, action.atMs);
+    case "DETECT_TIMEOUT":
+      return reduceTerminate(snapshot, {
+        kind: "script_timeout",
+        attempts: action.attempts
+      }, action.atMs);
+    case "NOT_EMBEDDED":
+      return reduceTerminate(snapshot, { kind: "not_embedded" }, action.atMs);
+    case "NEGOTIATE_START":
+      return reduceNegotiateStart(snapshot, action.access, action.atMs);
+    case "NEGOTIATE_SUCCESS":
+      return reduceNegotiateSuccess(snapshot, action.access, action.grantedLevel, action.atMs);
+    case "NEGOTIATE_FAIL":
+      return reduceTerminate(snapshot, action.reason, action.atMs);
+    case "TERMINATE":
+      return reduceTerminate(snapshot, action.reason, action.atMs);
+    case "AUTHZ_REPORT":
+      return reduceAuthzReport(snapshot, action.level, action.atMs);
+    // -- Link -------------------------------------------------------------
+    case "RPC_SUCCESS":
+    case "HEARTBEAT_OK":
+      return reduceLinkSuccess(snapshot, action.atMs);
+    case "RPC_FAILURE":
+    case "HEARTBEAT_FAIL":
+      return reduceLinkFailure(snapshot, action.atMs, config);
+    // -- Generation -------------------------------------------------------
+    case "BUMP_GENERATION":
+      return reduceBumpGeneration(snapshot, ctx);
+    // -- Config / mappings -----------------------------------------------
+    case "MAPPING_DECLARE":
+    case "MAPPING_REPORT":
+    case "MAPPING_INVALIDATE":
+    case "MAPPING_INVALIDATION_RESOLVE":
+    case "MAPPING_TIMEOUT":
+      return reduceMapping(snapshot, action, ctx);
+    // -- Sync -------------------------------------------------------------
+    case "STREAM_RECEIVED":
+    case "STREAM_WARMING":
+    case "STREAM_STALE":
+      return reduceStream(snapshot, action);
+    case "CURRENT_TABLE_KNOWN":
+      return updateSync(snapshot, {
+        ...snapshot.sync,
+        currentTable: { state: "known", tableId: action.tableId, refreshing: false }
+      });
+    case "CURRENT_TABLE_REFRESH_START":
+      if (snapshot.sync.currentTable.state !== "known") return snapshot;
+      return updateSync(snapshot, {
+        ...snapshot.sync,
+        currentTable: { ...snapshot.sync.currentTable, refreshing: true }
+      });
+    case "CURRENT_TABLE_ERROR":
+      return updateSync(snapshot, {
+        ...snapshot.sync,
+        currentTable: { state: "errored", message: action.message, sinceMs: action.atMs }
+      });
+    default: {
+      const _exhaustive = action;
+      void _exhaustive;
+      return snapshot;
+    }
+  }
+}
+function reduceDetectStart(snapshot, atMs) {
+  if (snapshot.lifecycle.phase !== "idle") return snapshot;
+  return {
+    ...snapshot,
+    lifecycle: { phase: "detecting", attempts: 0, startedAtMs: atMs }
+  };
+}
+function reduceDetectTick(snapshot, attempts) {
+  if (snapshot.lifecycle.phase !== "detecting") return snapshot;
+  if (attempts === snapshot.lifecycle.attempts) return snapshot;
+  return {
+    ...snapshot,
+    lifecycle: { ...snapshot.lifecycle, attempts }
+  };
+}
+function reduceDetectAvailable(snapshot, atMs) {
+  if (snapshot.lifecycle.phase !== "detecting" && snapshot.lifecycle.phase !== "idle") {
+    return snapshot;
+  }
+  return {
+    ...snapshot,
+    lifecycle: {
+      phase: "negotiating",
+      access: snapshot.authz.declared,
+      startedAtMs: atMs
+    }
+  };
+}
+function reduceNegotiateStart(snapshot, access, atMs) {
+  if (snapshot.lifecycle.phase === "terminated") return snapshot;
+  return {
+    ...snapshot,
+    authz: { state: "pending", declared: access },
+    lifecycle: snapshot.lifecycle.phase === "online" ? snapshot.lifecycle : { phase: "negotiating", access, startedAtMs: atMs }
+  };
+}
+function authzDeclared(snapshot) {
+  return snapshot.authz.declared;
+}
+function reduceAuthzReport(snapshot, level, _atMs) {
+  if (snapshot.lifecycle.phase !== "online") return snapshot;
+  const declared = authzDeclared(snapshot);
+  if (isAccessSufficient(level, declared)) {
+    const previousLevel = snapshot.authz.state === "granted" ? snapshot.authz.level : null;
+    const widened = previousLevel !== null && ACCESS_RANK[level] > ACCESS_RANK[previousLevel];
+    const nextAuthz2 = {
+      state: "granted",
+      level,
+      declared,
+      widened
+    };
+    if (snapshot.authz.state === "granted" && snapshot.authz.level === nextAuthz2.level && snapshot.authz.declared === nextAuthz2.declared && snapshot.authz.widened === nextAuthz2.widened) {
+      return snapshot;
+    }
+    return { ...snapshot, authz: nextAuthz2 };
+  }
+  const message = formatInsufficientAccessMessage(declared, level);
+  const nextAuthz = { state: "denied", declared, message };
+  if (snapshot.authz.state === "denied" && snapshot.authz.declared === nextAuthz.declared && snapshot.authz.message === nextAuthz.message) {
+    return snapshot;
+  }
+  return { ...snapshot, authz: nextAuthz };
+}
+function reduceNegotiateSuccess(snapshot, access, grantedLevel, atMs) {
+  if (snapshot.lifecycle.phase === "terminated") return snapshot;
+  const previousLevel = snapshot.authz.state === "granted" ? snapshot.authz.level : null;
+  const widened = previousLevel !== null && ACCESS_RANK[grantedLevel] > ACCESS_RANK[previousLevel];
+  return {
+    ...snapshot,
+    authz: {
+      state: "granted",
+      level: grantedLevel,
+      declared: access,
+      widened
+    },
+    lifecycle: snapshot.lifecycle.phase === "online" ? snapshot.lifecycle : { phase: "online", sinceMs: atMs, declaredAccess: access },
+    link: { state: "connected", lastSuccessMs: atMs, missedPings: 0 }
+  };
+}
+function reduceTerminate(snapshot, reason, atMs) {
+  if (snapshot.lifecycle.phase === "terminated") return snapshot;
+  const lifecycle = { phase: "terminated", reason, atMs };
+  return { ...snapshot, lifecycle };
+}
+function reduceLinkSuccess(snapshot, atMs) {
+  if (snapshot.lifecycle.phase !== "online") return snapshot;
+  const link = { state: "connected", lastSuccessMs: atMs, missedPings: 0 };
+  if (snapshot.link.state === link.state && snapshot.link.lastSuccessMs === link.lastSuccessMs && snapshot.link.missedPings === link.missedPings) {
+    return snapshot;
+  }
+  return { ...snapshot, link };
+}
+function reduceLinkFailure(snapshot, _atMs, config) {
+  if (snapshot.lifecycle.phase !== "online") return snapshot;
+  const missed = snapshot.link.missedPings + 1;
+  let state = snapshot.link.state;
+  if (missed >= config.lostAfterMissed) state = "lost";
+  else if (missed >= config.staleAfterMissed) state = "stale";
+  return {
+    ...snapshot,
+    link: { state, lastSuccessMs: snapshot.link.lastSuccessMs, missedPings: missed }
+  };
+}
+function reduceBumpGeneration(snapshot, ctx) {
+  const next = nextGeneration(snapshot.generation);
+  ctx.resolver?.bumpGeneration(next);
+  return {
+    ...snapshot,
+    generation: next,
+    // Marking streams as warming again ensures hooks treat the data as
+    // "in transit" until a fresh event arrives under the new generation.
+    sync: {
+      ...snapshot.sync,
+      record: degradeForRefresh(snapshot.sync.record, snapshot.generation),
+      records: degradeForRefresh(snapshot.sync.records, snapshot.generation),
+      options: degradeForRefresh(snapshot.sync.options, snapshot.generation),
+      newRecord: degradeForRefresh(snapshot.sync.newRecord, snapshot.generation)
+    }
+  };
+}
+function degradeForRefresh(freshness, prevGeneration) {
+  if (freshness.state === "hot" && freshness.generation === prevGeneration) {
+    return { state: "stale", lastEventMs: freshness.lastEventMs, reason: "host_quiet" };
+  }
+  return freshness;
+}
+function reduceMapping(snapshot, action, ctx) {
+  switch (action.type) {
+    case "MAPPING_DECLARE": {
+      if (action.declared.length === 0) {
+        if (snapshot.config.mappings.state === "not_declared") return snapshot;
+        ctx.resolver = null;
+        return {
+          ...snapshot,
+          config: { mappings: { state: "not_declared" } }
+        };
+      }
+      if (!ctx.resolver) {
+        ctx.resolver = new MappingResolver(action.declared, snapshot.generation);
+      } else {
+        ctx.resolver.redeclare(action.declared, snapshot.generation);
+      }
+      return {
+        ...snapshot,
+        config: {
+          mappings: {
+            state: "pending",
+            declared: action.declared,
+            declaredAtMs: action.atMs
+          }
+        }
+      };
+    }
+    case "MAPPING_REPORT": {
+      if (!ctx.resolver) return snapshot;
+      const outcome = ctx.resolver.ingest({
+        source: action.source,
+        payload: action.payload,
+        receivedAtMs: action.atMs,
+        generation: action.generation
+      });
+      if (outcome.kind !== "resolved") return snapshot;
+      return applyResolved(snapshot, outcome.state);
+    }
+    case "MAPPING_INVALIDATE": {
+      const previous = snapshot.config.mappings;
+      if (previous.state !== "complete" && previous.state !== "incomplete") {
+        return snapshot;
+      }
+      return {
+        ...snapshot,
+        config: {
+          mappings: {
+            state: "invalidating",
+            previous,
+            sinceMs: action.atMs
+          }
+        }
+      };
+    }
+    case "MAPPING_INVALIDATION_RESOLVE": {
+      if (snapshot.config.mappings.state !== "invalidating") return snapshot;
+      if (!ctx.resolver) {
+        return {
+          ...snapshot,
+          config: { mappings: snapshot.config.mappings.previous }
+        };
+      }
+      const outcome = ctx.resolver.current();
+      if (outcome.kind !== "resolved") {
+        return {
+          ...snapshot,
+          config: { mappings: snapshot.config.mappings.previous }
+        };
+      }
+      return applyResolved(snapshot, outcome.state);
+    }
+    case "MAPPING_TIMEOUT": {
+      const previous = snapshot.config.mappings;
+      if (previous.state !== "pending") return snapshot;
+      return {
+        ...snapshot,
+        config: {
+          mappings: {
+            state: "unreported",
+            declared: previous.declared,
+            afterMs: action.atMs - previous.declaredAtMs
+          }
+        }
+      };
+    }
+  }
+}
+function applyResolved(snapshot, resolved) {
+  const existing = snapshot.config.mappings;
+  if ((existing.state === "complete" || existing.state === "incomplete") && sameResolved(existing, resolved)) {
+    return snapshot;
+  }
+  return { ...snapshot, config: { mappings: resolved } };
+}
+function sameResolved(a, b) {
+  if (a.state !== b.state) return false;
+  if (a.state !== "complete" && a.state !== "incomplete") return false;
+  if (a.source !== b.source) return false;
+  const ak = Object.keys(a.mappings);
+  const bk = Object.keys(b.mappings);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    const av = a.mappings[k];
+    const bv = b.mappings[k];
+    if (Array.isArray(av) && Array.isArray(bv)) {
+      if (av.length !== bv.length) return false;
+      for (let i = 0; i < av.length; i++) if (av[i] !== bv[i]) return false;
+    } else if (av !== bv) {
+      return false;
+    }
+  }
+  return true;
+}
+function reduceStream(snapshot, action) {
+  if (action.type === "CURRENT_TABLE_KNOWN" || action.type === "CURRENT_TABLE_REFRESH_START" || action.type === "CURRENT_TABLE_ERROR") {
+    return snapshot;
+  }
+  const stream = action.stream;
+  const current = snapshot.sync[stream];
+  if (action.type === "STREAM_WARMING") {
+    if (current.state === "warming" || current.state === "hot") return snapshot;
+    return updateStream(snapshot, stream, { state: "warming", sinceMs: action.atMs });
+  }
+  if (action.type === "STREAM_STALE") {
+    if (current.state !== "hot") return snapshot;
+    return updateStream(snapshot, stream, {
+      state: "stale",
+      lastEventMs: current.lastEventMs,
+      reason: action.reason
+    });
+  }
+  if (current.state === "hot" && current.generation === action.generation && current.payloadHash === action.payloadHash) {
+    return snapshot;
+  }
+  return updateStream(snapshot, stream, {
+    state: "hot",
+    lastEventMs: action.atMs,
+    generation: action.generation,
+    payloadHash: action.payloadHash
+  });
+}
+function updateStream(snapshot, stream, next) {
+  return {
+    ...snapshot,
+    sync: { ...snapshot.sync, [stream]: next }
+  };
+}
+function updateSync(snapshot, sync) {
+  return { ...snapshot, sync };
+}
+
+// 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([]);
+
+// src/sdk/internal/handshake-manager-context.ts
+var import_react = require("react");
+
+// src/sdk/internal/ready-singleton.ts
+var ACCESS_RANK2 = {
+  none: 0,
+  "read table": 1,
+  full: 2
+};
+var inFlight = null;
+var lastAccess = null;
+function shouldReinit(next) {
+  if (!lastAccess) return true;
+  return ACCESS_RANK2[next] > ACCESS_RANK2[lastAccess];
+}
+function ensureGristReady(payload) {
+  const access = payload.requiredAccess ?? "read table";
+  if (inFlight && !shouldReinit(access)) return inFlight;
+  lastAccess = access;
+  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;
+    throw err;
+  });
+  return inFlight;
+}
+function resetGristReadySingleton() {
+  inFlight = null;
+  lastAccess = null;
+}
+
+// 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
+var DEFAULT_POLL_SEQUENCE_MS = [
+  200,
+  200,
+  400,
+  400,
+  800,
+  1600,
+  3200,
+  5e3,
+  5e3,
+  5e3,
+  5e3,
+  5e3,
+  5e3,
+  5e3
+];
+function defaultBudgetMs(hint) {
+  if (hint === "slow-2g" || hint === "2g") return 12e4;
+  if (hint === "3g") return 6e4;
+  return 3e4;
+}
+function startDetectEffect(env, dispatch, signal, options = {}) {
+  const sequence = options.pollSequenceMs ?? DEFAULT_POLL_SEQUENCE_MS;
+  const budgetMs = options.budgetMs ?? defaultBudgetMs(env.effectiveTypeHint());
+  const startedAt = env.now();
+  let attempts = 0;
+  let timer = null;
+  let cancelled = false;
+  signal.addEventListener("abort", () => {
+    cancelled = true;
+    if (timer !== null) env.clearTimeout(timer);
+  });
+  dispatch({ type: "DETECT_START", atMs: startedAt });
+  const tick = () => {
+    if (cancelled) return;
+    timer = null;
+    const probe = env.probeGrist();
+    if (probe !== null) {
+      if (probe.embedded) {
+        dispatch({ type: "DETECT_AVAILABLE", atMs: env.now() });
+      } else {
+        dispatch({ type: "NOT_EMBEDDED", atMs: env.now() });
+      }
+      return;
+    }
+    attempts += 1;
+    dispatch({ type: "DETECT_TICK", attempts, atMs: env.now() });
+    const elapsed = env.now() - startedAt;
+    if (elapsed >= budgetMs) {
+      dispatch({ type: "DETECT_TIMEOUT", attempts, atMs: env.now() });
+      return;
+    }
+    const next = sequence[Math.min(attempts - 1, sequence.length - 1)] ?? 1e3;
+    const remaining = budgetMs - elapsed;
+    timer = env.setTimeout(tick, Math.max(0, Math.min(next, remaining)));
+  };
+  tick();
+  return {
+    cancel() {
+      cancelled = true;
+      if (timer !== null) {
+        env.clearTimeout(timer);
+        timer = null;
+      }
+    }
+  };
+}
+
+// src/sdk/internal/handshake/effects/negotiate.ts
+var DEFAULT_NEGOTIATE_TIMEOUT_MS = 3e4;
+function startNegotiateEffect(env, dispatch, signal, payload, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_NEGOTIATE_TIMEOUT_MS;
+  const access = payload.requiredAccess ?? "read table";
+  let settled = false;
+  let timer = null;
+  const settle = (next) => {
+    if (settled) return;
+    settled = true;
+    if (timer !== null) env.clearTimeout(timer);
+    if (signal.aborted) return;
+    next();
+  };
+  dispatch({ type: "NEGOTIATE_START", access, atMs: env.now() });
+  const grist2 = env.getGrist();
+  if (!grist2) {
+    settle(
+      () => dispatch({
+        type: "NEGOTIATE_FAIL",
+        reason: { kind: "ready_failed", message: "grist global missing at negotiate" },
+        atMs: env.now()
+      })
+    );
+    return { cancel: () => settle(() => {
+    }) };
+  }
+  timer = env.setTimeout(() => {
+    if (settled) return;
+    settle(
+      () => dispatch({
+        type: "NEGOTIATE_FAIL",
+        reason: { kind: "ready_timeout", afterMs: timeoutMs },
+        atMs: env.now()
+      })
+    );
+  }, timeoutMs);
+  const handleSuccess = (g) => {
+    if (!g.docApi) {
+      dispatch({
+        type: "NEGOTIATE_FAIL",
+        reason: { kind: "ready_failed", message: "grist.docApi missing after ready" },
+        atMs: env.now()
+      });
+      return;
+    }
+    dispatch({
+      type: "NEGOTIATE_SUCCESS",
+      access,
+      grantedLevel: access,
+      // host doesn't report effective level; widen later via authz events
+      atMs: env.now()
+    });
+  };
+  const handleFailure = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    const reason = { kind: "ready_failed", message };
+    dispatch({ type: "NEGOTIATE_FAIL", reason, atMs: env.now() });
+  };
+  const readyImpl = options.readyImpl ?? ((p) => grist2.ready(p));
+  try {
+    const result = readyImpl(payload);
+    if (result && typeof result.then === "function") {
+      ;
+      result.then(
+        () => settle(() => handleSuccess(env.getGrist() ?? grist2)),
+        (err) => settle(() => handleFailure(err))
+      );
+    } else {
+      settle(() => handleSuccess(env.getGrist() ?? grist2));
+    }
+  } catch (err) {
+    settle(() => handleFailure(err));
+  }
+  signal.addEventListener("abort", () => settle(() => {
+  }));
+  return { cancel: () => settle(() => {
+  }) };
+}
+
+// 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 });
+  });
+});
+
+// src/sdk/internal/handshake/effects/subscriptions.ts
+function defaultSubscriptionsBinder(ctx) {
+  const offs = [];
+  offs.push(
+    recordEvent.subscribe((payload) => {
+      const hash = quickHash("record", payload);
+      dispatchStream(ctx, "record", hash);
+      ctx.onRecordPayload?.(payload.mappings ?? null);
+    })
+  );
+  offs.push(
+    recordsEvent.subscribe((payload) => {
+      const hash = quickHash("records", payload);
+      dispatchStream(ctx, "records", hash);
+      ctx.onRecordsPayload?.(payload.mappings ?? null);
+    })
+  );
+  offs.push(
+    optionsEvent.subscribe((payload) => {
+      const hash = quickHash("options", payload);
+      dispatchStream(ctx, "options", hash);
+      const level = parseGristRequiredAccess(payload.interaction?.access_level);
+      if (level !== null) {
+        ctx.dispatch({
+          type: "AUTHZ_REPORT",
+          level,
+          atMs: Date.now(),
+          generation: ctx.getGeneration()
+        });
+      }
+      ctx.onOptionsPayload?.(payload.options ?? null);
+    })
+  );
+  offs.push(
+    newRecordEvent.subscribe((payload) => {
+      const hash = quickHash("newRecord", payload);
+      dispatchStream(ctx, "newRecord", hash);
+      ctx.onNewRecordPayload?.(payload.mappings ?? null);
+    })
+  );
+  return {
+    cancel() {
+      for (const off of offs.splice(0)) off();
+    }
+  };
+}
+function dispatchStream(ctx, stream, payloadHash) {
+  ctx.dispatch({
+    type: "STREAM_RECEIVED",
+    stream,
+    payloadHash,
+    atMs: Date.now(),
+    generation: ctx.getGeneration()
+  });
+}
+function quickHash(kind, payload) {
+  return `${kind}::${stableSerialize(payload)}`;
+}
+function stableSerialize(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  const t = typeof value;
+  if (t === "number" || t === "string" || t === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(stableSerialize).join(",")}]`;
+  }
+  if (t === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const body = keys.map((k) => `${JSON.stringify(k)}:${stableSerialize(obj[k])}`).join(",");
+    return `{${body}}`;
+  }
+  return String(value);
+}
+
+// src/sdk/internal/handshake/effects/mappings.ts
+var DEFAULT_MAPPING_TIMEOUT_MS = 5e3;
+function startMappingsEffect(env, dispatch, signal, declared, getGeneration, options = {}) {
+  let timeoutHandle = null;
+  let cancelled = false;
+  const startMs = env.now();
+  dispatch({ type: "MAPPING_DECLARE", declared, atMs: startMs, generation: getGeneration() });
+  if (declared.length === 0) {
+    return {
+      ingestStreamPayload: () => {
+      },
+      refetchSectionApi: async () => {
+      },
+      cancel: () => {
+      }
+    };
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_MAPPING_TIMEOUT_MS;
+  timeoutHandle = env.setTimeout(() => {
+    if (cancelled || signal.aborted) return;
+    dispatch({ type: "MAPPING_TIMEOUT", atMs: env.now(), generation: getGeneration() });
+  }, timeoutMs);
+  signal.addEventListener("abort", () => {
+    cancelled = true;
+    if (timeoutHandle !== null) env.clearTimeout(timeoutHandle);
+  });
+  const ingestPayload = (source, raw) => {
+    if (cancelled || signal.aborted) return;
+    const payload = coerceMappingsPayload(raw);
+    dispatch({
+      type: "MAPPING_REPORT",
+      source,
+      payload,
+      atMs: env.now(),
+      generation: getGeneration()
+    });
+  };
+  const refetchSectionApi = async () => {
+    if (cancelled || signal.aborted) return;
+    const grist2 = env.getGrist();
+    const api = grist2?.sectionApi;
+    if (!api || typeof api.mappings !== "function") return;
+    try {
+      const payload = await api.mappings();
+      ingestPayload("section_api", payload);
+    } catch {
+      ingestPayload("section_api", null);
+    }
+  };
+  void refetchSectionApi();
+  return {
+    ingestStreamPayload: (source, payload) => ingestPayload(source, payload),
+    refetchSectionApi,
+    cancel() {
+      cancelled = true;
+      if (timeoutHandle !== null) env.clearTimeout(timeoutHandle);
+    }
+  };
+}
+function coerceMappingsPayload(raw) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw !== "object") return null;
+  return raw;
+}
+
+// src/sdk/internal/handshake/effects/heartbeat.ts
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+var DEFAULT_HEARTBEAT_PING_TIMEOUT_MS = 1e4;
+function startHeartbeatEffect(env, dispatch, signal, options = {}) {
+  const intervalMs = options.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const pingTimeoutMs = options.pingTimeoutMs ?? DEFAULT_HEARTBEAT_PING_TIMEOUT_MS;
+  const pauseWhenHidden = options.pauseWhenHidden ?? true;
+  const probe = options.probe ?? defaultProbe(env);
+  let cancelled = false;
+  let paused = false;
+  let intervalTimer = null;
+  let inFlight3 = false;
+  let inFlightTimeoutTimer = null;
+  const clearInterval = () => {
+    if (intervalTimer !== null) {
+      env.clearTimeout(intervalTimer);
+      intervalTimer = null;
+    }
+  };
+  const clearInFlightTimeout = () => {
+    if (inFlightTimeoutTimer !== null) {
+      env.clearTimeout(inFlightTimeoutTimer);
+      inFlightTimeoutTimer = null;
+    }
+  };
+  const scheduleNext = (delay = intervalMs) => {
+    clearInterval();
+    if (cancelled || paused) return;
+    intervalTimer = env.setTimeout(ping, delay);
+  };
+  const ping = () => {
+    if (cancelled || paused) return;
+    intervalTimer = null;
+    if (inFlight3) {
+      return;
+    }
+    inFlight3 = true;
+    inFlightTimeoutTimer = env.setTimeout(() => {
+      if (!inFlight3) return;
+      inFlight3 = false;
+      clearInFlightTimeout();
+      if (!cancelled) {
+        dispatch({ type: "HEARTBEAT_FAIL", atMs: env.now() });
+        scheduleNext();
+      }
+    }, pingTimeoutMs);
+    const handleOk = () => {
+      if (!inFlight3) return;
+      inFlight3 = false;
+      clearInFlightTimeout();
+      if (cancelled) return;
+      dispatch({ type: "HEARTBEAT_OK", atMs: env.now() });
+      scheduleNext();
+    };
+    const handleFail = () => {
+      if (!inFlight3) return;
+      inFlight3 = false;
+      clearInFlightTimeout();
+      if (cancelled) return;
+      dispatch({ type: "HEARTBEAT_FAIL", atMs: env.now() });
+      scheduleNext();
+    };
+    let result;
+    try {
+      result = probe();
+    } catch {
+      handleFail();
+      return;
+    }
+    if (result && typeof result.then === "function") {
+      ;
+      result.then(handleOk, handleFail);
+    } else {
+      handleOk();
+    }
+  };
+  const offVisibility = pauseWhenHidden && env.onVisibilityChange ? env.onVisibilityChange((visible) => {
+    if (cancelled) return;
+    if (visible) {
+      if (paused) {
+        paused = false;
+        ping();
+      }
+    } else {
+      paused = true;
+      clearInterval();
+    }
+  }) : null;
+  const offOnline = env.onOnline?.(() => {
+    if (cancelled || paused) return;
+    ping();
+  }) ?? null;
+  signal.addEventListener("abort", () => {
+    cancelled = true;
+    clearInterval();
+    clearInFlightTimeout();
+    inFlight3 = false;
+    offVisibility?.();
+    offOnline?.();
+  });
+  scheduleNext();
+  return {
+    cancel() {
+      cancelled = true;
+      clearInterval();
+      clearInFlightTimeout();
+      inFlight3 = false;
+      offVisibility?.();
+      offOnline?.();
+    },
+    recordRpcSuccess() {
+      if (cancelled || paused) return;
+      dispatch({ type: "RPC_SUCCESS", atMs: env.now() });
+      scheduleNext();
+    },
+    recordRpcFailure() {
+      if (cancelled || paused) return;
+      dispatch({ type: "RPC_FAILURE", atMs: env.now(), kind: "other" });
+      scheduleNext(Math.min(intervalMs, 1e3));
+    },
+    pingNow() {
+      if (cancelled) return;
+      ping();
+    }
+  };
+}
+function defaultProbe(env) {
+  return async () => {
+    const g = env.getGrist();
+    if (!g) throw new Error("grist global missing");
+    const docApi = g.docApi;
+    if (!docApi || typeof docApi.getDocName !== "function") {
+      throw new Error("grist.docApi.getDocName unavailable");
+    }
+    return docApi.getDocName();
+  };
+}
+
+// src/sdk/internal/handshake/authz-from-options-cache.ts
+function denyAuthzFromCachedOptionsIfInsufficient(snapshot, dispatch, env) {
+  if (snapshot.lifecycle.phase !== "online") return;
+  if (snapshot.authz.state === "denied") return;
+  const payload = optionsEvent.peek();
+  const level = parseGristRequiredAccess(payload?.interaction?.access_level);
+  if (level === null) return;
+  const declared = snapshot.authz.declared;
+  if (isAccessSufficient(level, declared)) return;
+  dispatch({
+    type: "AUTHZ_REPORT",
+    level,
+    atMs: env.now(),
+    generation: snapshot.generation
+  });
+}
+
+// src/sdk/internal/handshake/environment.ts
+function createBrowserEnvironment() {
+  return {
+    now: () => typeof performance !== "undefined" ? performance.now() : Date.now(),
+    setTimeout: (cb, ms) => globalThis.setTimeout(cb, ms),
+    clearTimeout: (h) => globalThis.clearTimeout(h),
+    probeGrist() {
+      if (typeof globalThis === "undefined") return null;
+      const g = globalThis.grist;
+      if (typeof g === "undefined") return null;
+      const embedded2 = typeof window === "undefined" ? false : window.self !== window.top;
+      return { embedded: embedded2 };
+    },
+    getGrist() {
+      const g = globalThis.grist;
+      return g ?? null;
+    },
+    effectiveTypeHint() {
+      if (typeof navigator === "undefined") return null;
+      const conn = navigator.connection;
+      const t = conn?.effectiveType;
+      if (t === "slow-2g" || t === "2g" || t === "3g" || t === "4g" || t === "5g") return t;
+      return null;
+    },
+    onVisibilityChange(listener) {
+      if (typeof document === "undefined") return () => {
+      };
+      const handler = () => listener(document.visibilityState === "visible");
+      document.addEventListener("visibilitychange", handler);
+      return () => document.removeEventListener("visibilitychange", handler);
+    },
+    onOnline(listener) {
+      if (typeof window === "undefined") return () => {
+      };
+      const handler = () => listener();
+      window.addEventListener("online", handler);
+      return () => window.removeEventListener("online", handler);
+    }
+  };
+}
+
+// src/sdk/internal/handshake/manager.ts
+function createGristHandshakeManager(options = {}) {
+  const env = options.env ?? createBrowserEnvironment();
+  const reducerConfig = {
+    ...DEFAULT_REDUCER_CONFIG,
+    ...options.reducerConfig ?? {}
+  };
+  let snapshot = initialGristSnapshot();
+  const ctx = createReducerContext();
+  const listeners = /* @__PURE__ */ new Set();
+  let started = false;
+  let abort = null;
+  let detectHandle = null;
+  let negotiateHandle = null;
+  let subscriptionsHandle = null;
+  let mappingsHandle = null;
+  let heartbeatHandle = null;
+  let recheckAuthzFromCacheAfterOnline = false;
+  const declared = options.columns ?? [];
+  const subscriptionsBinder = options.subscriptionsBinder ?? defaultSubscriptionsBinder;
+  const notify = () => {
+    for (const l of listeners) {
+      try {
+        l();
+      } catch (err) {
+        options.onError?.(err, "listener");
+      }
+    }
+  };
+  const dispatch = (action) => {
+    const prev = snapshot;
+    const next = gristReducer(prev, action, ctx, reducerConfig);
+    if (next !== prev) {
+      snapshot = next;
+      onTransition(prev, next);
+      notify();
+    }
+  };
+  const onTransition = (prev, next) => {
+    if (prev.lifecycle.phase !== "negotiating" && next.lifecycle.phase === "negotiating") {
+      launchNegotiate();
+      launchSubscriptions();
+    }
+    if (prev.lifecycle.phase !== "online" && next.lifecycle.phase === "online") {
+      launchMappings();
+      launchHeartbeat();
+      if (recheckAuthzFromCacheAfterOnline) {
+        recheckAuthzFromCacheAfterOnline = false;
+        denyAuthzFromCachedOptionsIfInsufficient(next, dispatch, env);
+      }
+    }
+    if (prev.lifecycle.phase === "online" && next.lifecycle.phase !== "online") {
+      heartbeatHandle?.cancel();
+      heartbeatHandle = null;
+    }
+  };
+  const launchDetect = () => {
+    if (!abort) return;
+    detectHandle?.cancel();
+    detectHandle = startDetectEffect(env, dispatch, abort.signal, options.detect);
+  };
+  const launchNegotiate = () => {
+    if (!abort) return;
+    negotiateHandle?.cancel();
+    negotiateHandle = startNegotiateEffect(
+      env,
+      dispatch,
+      abort.signal,
+      buildReadyPayload(options),
+      options.negotiate
+    );
+  };
+  const launchSubscriptions = () => {
+    if (!abort) return;
+    if (subscriptionsHandle) return;
+    subscriptionsHandle = subscriptionsBinder({
+      dispatch,
+      getGeneration: () => snapshot.generation,
+      onRecordPayload: (m) => mappingsHandle?.ingestStreamPayload("stream_record", m),
+      onRecordsPayload: (m) => mappingsHandle?.ingestStreamPayload("stream_records", m),
+      onNewRecordPayload: (m) => mappingsHandle?.ingestStreamPayload("stream_new_record", m)
+    });
+  };
+  const launchMappings = () => {
+    if (!abort) return;
+    launchSubscriptions();
+    if (mappingsHandle) return;
+    mappingsHandle = startMappingsEffect(
+      env,
+      dispatch,
+      abort.signal,
+      declared,
+      () => snapshot.generation,
+      options.mappings
+    );
+  };
+  const launchHeartbeat = () => {
+    if (!abort) return;
+    if (options.heartbeat === false) return;
+    if (heartbeatHandle) return;
+    heartbeatHandle = startHeartbeatEffect(
+      env,
+      dispatch,
+      abort.signal,
+      options.heartbeat ?? {}
+    );
+  };
+  const cancelAllEffects = () => {
+    detectHandle?.cancel();
+    detectHandle = null;
+    negotiateHandle?.cancel();
+    negotiateHandle = null;
+    mappingsHandle?.cancel();
+    mappingsHandle = null;
+    heartbeatHandle?.cancel();
+    heartbeatHandle = null;
+    if (abort && !abort.signal.aborted) abort.abort();
+  };
+  const controls = {
+    start() {
+      if (started) return;
+      started = true;
+      abort = new AbortController();
+      launchDetect();
+    },
+    stop() {
+      if (!started) return;
+      started = false;
+      cancelAllEffects();
+      subscriptionsHandle?.cancel();
+      subscriptionsHandle = null;
+      snapshot = initialGristSnapshot();
+      notify();
+    },
+    reload() {
+      if (!started) {
+        controls.start();
+        return;
+      }
+      recheckAuthzFromCacheAfterOnline = true;
+      try {
+        options.onBeforeReload?.();
+      } catch (err) {
+        options.onError?.(err, "onBeforeReload");
+      }
+      cancelAllEffects();
+      dispatch({ type: "BUMP_GENERATION", atMs: env.now(), reason: "reload" });
+      snapshot = {
+        ...initialGristSnapshot(),
+        generation: nextGeneration(snapshot.generation)
+      };
+      ctx.resolver = null;
+      abort = new AbortController();
+      launchDetect();
+      notify();
+    },
+    restart() {
+      controls.reload();
+      if (typeof window !== "undefined" && typeof window.location?.reload === "function") {
+        try {
+          window.location.reload();
+        } catch (err) {
+          options.onError?.(err, "restart");
+        }
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getSnapshot: () => snapshot,
+    dispatch,
+    recordRpcSuccess() {
+      heartbeatHandle?.recordRpcSuccess();
+    },
+    recordRpcFailure() {
+      heartbeatHandle?.recordRpcFailure();
+    }
+  };
+  return controls;
+}
+function buildReadyPayload(options) {
+  const payload = {
+    requiredAccess: options.requiredAccess ?? "read table",
+    columns: options.columns ?? []
+  };
+  if (options.allowSelectBy !== void 0) payload.allowSelectBy = options.allowSelectBy;
+  if (options.hasCustomOptions !== void 0) payload.hasCustomOptions = options.hasCustomOptions;
+  if (options.onEditOptions) payload.onEditOptions = options.onEditOptions;
+  return payload;
+}
+
+// src/sdk/internal/embedded-handshake-manager.ts
+var embedded = null;
+function acquireEmbeddedHandshakeManager(options) {
+  if (!embedded) {
+    embedded = {
+      manager: createGristHandshakeManager(options),
+      refCount: 0
+    };
+    embedded.manager.start();
+  }
+  embedded.refCount += 1;
+  return embedded.manager;
+}
+function releaseEmbeddedHandshakeManager() {
+  if (!embedded) return;
+  embedded.refCount -= 1;
+  if (embedded.refCount <= 0) {
+    embedded.manager.stop();
+    embedded = null;
+  }
+}
+
+// src/sdk/internal/handshake-manager-context.ts
+var GristHandshakeManagerContext = (0, import_react.createContext)(null);
+function useGristManagerOptional() {
+  return (0, import_react.useContext)(GristHandshakeManagerContext);
+}
+function useGristManager(options) {
+  const fromProvider = (0, import_react.useContext)(GristHandshakeManagerContext);
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  const embeddedRef = (0, import_react.useRef)(null);
+  const ownsEmbeddedRef = (0, import_react.useRef)(false);
+  if (fromProvider) {
+    return fromProvider;
+  }
+  if (embeddedRef.current === null) {
+    embeddedRef.current = acquireEmbeddedHandshakeManager(
+      buildManagerOptionsFromGristOptions(optionsRef.current)
+    );
+    ownsEmbeddedRef.current = true;
+  }
+  (0, import_react.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 = (0, import_react2.useSyncExternalStore)(
+    manager.subscribe,
+    manager.getSnapshot,
+    initialGristSnapshot
+  );
+  const status = deriveStatus(snapshot);
+  const error = deriveErrorMessage(snapshot);
+  const docApi = (0, import_react2.useMemo)(() => {
+    if (snapshot.lifecycle.phase !== "online") return null;
+    if (typeof grist === "undefined") return null;
+    return grist.docApi ?? null;
+  }, [snapshot.lifecycle.phase, snapshot.generation]);
+  const isAvailable = computeAvailabilityFromSnapshot(snapshot);
+  const reload = (0, import_react2.useCallback)(async () => {
+    manager.reload();
+  }, [manager]);
+  const capabilities = (0, import_react2.useMemo)(() => deriveCapabilities(snapshot), [snapshot]);
+  return (0, import_react2.useMemo)(
+    () => ({
+      status,
+      isAvailable,
+      isReady: status === "ready",
+      error,
+      docApi,
+      capabilities,
+      reload
+    }),
+    [status, isAvailable, error, docApi, capabilities, reload]
+  );
+}
+
+// src/sdk/low-level-hooks/use-grist-availability.ts
+function useGristAvailability(options) {
+  const { isAvailable } = useGristCore(options);
+  return isAvailable;
+}
+
+// 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/low-level-hooks/use-grist-handshake.ts
+var import_react3 = require("react");
+function useGristHandshake(options = {}) {
+  const optionsRef = (0, import_react3.useRef)(options);
+  optionsRef.current = options;
+  const managerRef = (0, import_react3.useRef)(null);
+  if (managerRef.current === null) {
+    managerRef.current = createGristHandshakeManager(options);
+  }
+  const manager = managerRef.current;
+  (0, import_react3.useEffect)(() => {
+    manager.start();
+    return () => {
+      manager.stop();
+    };
+  }, [manager]);
+  const snapshot = (0, import_react3.useSyncExternalStore)(
+    manager.subscribe,
+    manager.getSnapshot,
+    initialGristSnapshot
+  );
+  const projected = (0, import_react3.useMemo)(
+    () => ({
+      status: deriveStatus(snapshot),
+      error: deriveErrorMessage(snapshot),
+      capabilities: deriveCapabilities(snapshot)
+    }),
+    [snapshot]
+  );
+  return (0, import_react3.useMemo)(
+    () => ({
+      snapshot,
+      status: projected.status,
+      error: projected.error,
+      capabilities: projected.capabilities,
+      reload: manager.reload,
+      restart: manager.restart
+    }),
+    [snapshot, projected, manager]
+  );
+}
+function useGristCapabilities(options = {}) {
+  return useGristHandshake(options).capabilities;
+}
+
+// src/sdk/components/grist-handshake-provider.tsx
+var import_react4 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var GristHandshakeReactContext = (0, import_react4.createContext)(null);
+function GristHandshakeProvider({ options, children }) {
+  const managerRef = (0, import_react4.useRef)(null);
+  if (managerRef.current === null) {
+    managerRef.current = createGristHandshakeManager(options ?? {});
+  }
+  const manager = managerRef.current;
+  (0, import_react4.useEffect)(() => {
+    manager.start();
+    return () => {
+      manager.stop();
+    };
+  }, [manager]);
+  const snapshot = (0, import_react4.useSyncExternalStore)(
+    manager.subscribe,
+    manager.getSnapshot,
+    initialGristSnapshot
+  );
+  const value = (0, import_react4.useMemo)(
+    () => ({
+      snapshot,
+      status: deriveStatus(snapshot),
+      error: deriveErrorMessage(snapshot),
+      capabilities: deriveCapabilities(snapshot),
+      reload: manager.reload,
+      restart: manager.restart,
+      recordRpcSuccess: manager.recordRpcSuccess,
+      recordRpcFailure: manager.recordRpcFailure
+    }),
+    [snapshot, manager]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GristHandshakeReactContext.Provider, { value, children });
+}
+function useGristHandshakeContext() {
+  const ctx = (0, import_react4.useContext)(GristHandshakeReactContext);
+  if (!ctx) {
+    throw new Error(
+      "useGristHandshakeContext() must be used inside <GristHandshakeProvider>"
+    );
+  }
+  return ctx;
+}
+function useGristHandshakeContextOptional() {
+  return (0, import_react4.useContext)(GristHandshakeReactContext);
+}
+
+// src/sdk/low-level-hooks/use-grist-record.ts
+var import_react5 = require("react");
+function useGristRecord(cb, options) {
+  const cbRef = (0, import_react5.useRef)(cb);
+  (0, import_react5.useEffect)(() => {
+    cbRef.current = cb;
+  }, [cb]);
+  const [mappings, setMappings] = (0, import_react5.useState)(null);
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  (0, import_react5.useEffect)(() => {
+    if (!docApi) return;
+    return recordEvent.subscribe(({ record, mappings: nextMappings }) => {
+      setMappings(nextMappings);
+      cbRef.current(record, nextMappings);
+    });
+  }, [docApi]);
+  return {
+    loading: docApi === null && !readyError,
+    error: readyError,
+    mappings
+  };
+}
+
+// src/sdk/low-level-hooks/use-grist-records.ts
+var import_react6 = require("react");
+function useGristRecords(cb, options) {
+  const cbRef = (0, import_react6.useRef)(cb);
+  (0, import_react6.useEffect)(() => {
+    cbRef.current = cb;
+  }, [cb]);
+  const [mappings, setMappings] = (0, import_react6.useState)(null);
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  (0, import_react6.useEffect)(() => {
+    if (!docApi) return;
+    return recordsEvent.subscribe(({ records, mappings: nextMappings }) => {
+      setMappings(nextMappings);
+      cbRef.current(records, nextMappings);
+    });
+  }, [docApi]);
+  return {
+    loading: docApi === null && !readyError,
+    error: readyError,
+    mappings
+  };
+}
+
+// src/sdk/low-level-hooks/use-grist-new-record.ts
+var import_react7 = require("react");
+function useGristNewRecord(options) {
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    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)(() => {
+    if (!docApi || subscribedRef.current) return;
+    if (typeof grist.onNewRecord !== "function") return;
+    subscribedRef.current = true;
+    return newRecordEvent.subscribe(({ mappings: nextMappings }) => {
+      setIsNewRecord(true);
+      setMappings(nextMappings);
+    });
+  }, [docApi]);
+  return {
+    isNewRecord,
+    mappings,
+    loading: docApi === null && !readyError,
+    error: readyError
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-actions.ts
+var import_react9 = require("react");
+
+// src/sdk/helpers/grist-user-actions.ts
+function gristUpdateRecordAction(tableId, rowId, patch) {
+  return ["UpdateRecord", tableId, rowId, patch];
+}
+function gristAddRecordAction(tableId, values) {
+  return ["AddRecord", tableId, null, values];
+}
+function gristRemoveRecordAction(tableId, rowId) {
+  return ["RemoveRecord", tableId, rowId];
+}
+function gristBulkUpdateRecordAction(tableId, rowIds, columnarPatch) {
+  return ["BulkUpdateRecord", tableId, rowIds, columnarPatch];
+}
+function gristBulkAddRecordAction(tableId, values, rowIds) {
+  const length = inferBulkLength(values);
+  const ids = rowIds ?? new Array(length).fill(null);
+  return ["BulkAddRecord", tableId, ids, values];
+}
+function gristBulkRemoveRecordAction(tableId, rowIds) {
+  return ["BulkRemoveRecord", tableId, rowIds];
+}
+function inferBulkLength(values) {
+  for (const arr of Object.values(values)) if (Array.isArray(arr)) return arr.length;
+  return 0;
+}
+
+// src/sdk/internal/hooks/use-rpc-heartbeat-coalesce.ts
+var import_react8 = require("react");
+function useRpcHeartbeatCoalesce() {
+  const manager = useGristManagerOptional();
+  return (0, import_react8.useCallback)(
+    async (fn) => {
+      try {
+        const result = await fn();
+        manager?.recordRpcSuccess();
+        return result;
+      } catch (err) {
+        throw err;
+      }
+    },
+    [manager]
+  );
+}
+
+// src/sdk/mid-level-hooks/use-grist-actions.ts
+function useGristActions(options) {
+  const requiredAccess = options?.requiredAccess ?? "full";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [status, setStatus] = (0, import_react9.useState)("idle");
+  const [actionError, setActionError] = (0, import_react9.useState)(null);
+  const coalesceRpc = useRpcHeartbeatCoalesce();
+  const apply = (0, import_react9.useCallback)(
+    async (actions, applyOptions) => {
+      if (!docApi) throw new Error("Grist docApi is not ready");
+      setStatus("running");
+      setActionError(null);
+      try {
+        const out = await coalesceRpc(() => docApi.applyUserActions(actions, applyOptions));
+        setStatus("idle");
+        return out;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setActionError(message);
+        setStatus("error");
+        throw err;
+      }
+    },
+    [docApi, coalesceRpc]
+  );
+  const updateRecord = (0, import_react9.useCallback)(
+    (tableId, recordId, patch, applyOptions) => apply([gristUpdateRecordAction(tableId, recordId, patch)], applyOptions),
+    [apply]
+  );
+  const addRecord = (0, import_react9.useCallback)(
+    (tableId, values, applyOptions) => apply([gristAddRecordAction(tableId, values)], applyOptions),
+    [apply]
+  );
+  const removeRecord = (0, import_react9.useCallback)(
+    (tableId, recordId, applyOptions) => apply([gristRemoveRecordAction(tableId, recordId)], applyOptions),
+    [apply]
+  );
+  const bulkAddRecord = (0, import_react9.useCallback)(
+    (tableId, values, applyOptions) => apply([gristBulkAddRecordAction(tableId, values)], applyOptions),
+    [apply]
+  );
+  const bulkUpdateRecord = (0, import_react9.useCallback)(
+    (tableId, rowIds, columnarPatch, applyOptions) => apply([gristBulkUpdateRecordAction(tableId, rowIds, columnarPatch)], applyOptions),
+    [apply]
+  );
+  const bulkRemoveRecord = (0, import_react9.useCallback)(
+    (tableId, rowIds, applyOptions) => apply([gristBulkRemoveRecordAction(tableId, rowIds)], applyOptions),
+    [apply]
+  );
+  return {
+    status: readyError ? "error" : status,
+    error: readyError ?? actionError,
+    apply,
+    updateRecord,
+    addRecord,
+    removeRecord,
+    bulkAddRecord,
+    bulkUpdateRecord,
+    bulkRemoveRecord
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-mapped-record.ts
+var import_react10 = require("react");
+function manualMapBack(patch, mappings) {
+  if (!mappings) return { ...patch };
+  const out = {};
+  for (const [name, value] of Object.entries(patch)) {
+    const target = mappings[name];
+    if (Array.isArray(target)) {
+      if (typeof console !== "undefined") {
+        console.warn(`[lib/grist] mapBack: cannot reverse-map allowMultiple field "${name}" without grist.mapColumnNamesBack`);
+      }
+      continue;
+    }
+    out[target ?? name] = value;
+  }
+  return out;
+}
+function useGristMappedRecord(options) {
+  const requiredAccess = options?.requiredAccess ?? "read table";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    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)(() => {
+    if (!docApi) return;
+    return recordEvent.subscribe(({ record, mappings: nextMappings }) => {
+      setRawRecord(record);
+      setMappings(nextMappings);
+      if (!record) {
+        setMappedRecord(null);
+        return;
+      }
+      if (typeof grist.mapColumnNames === "function") {
+        const mapped = grist.mapColumnNames(record);
+        setMappedRecord(
+          mapped !== null && mapped !== void 0 ? mapped : null
+        );
+        return;
+      }
+      setMappedRecord(record);
+    });
+  }, [docApi]);
+  const mapBack = (0, import_react10.useCallback)(
+    (patch) => {
+      if (typeof grist.mapColumnNamesBack === "function") {
+        return grist.mapColumnNamesBack(patch);
+      }
+      return manualMapBack(patch, mappings);
+    },
+    [mappings]
+  );
+  const resolveColumnId = (0, import_react10.useCallback)(
+    (logicalName) => {
+      const value = mappings?.[logicalName];
+      if (Array.isArray(value)) return void 0;
+      return value ?? void 0;
+    },
+    [mappings]
+  );
+  return {
+    rawRecord,
+    mappedRecord,
+    mappings,
+    loading: docApi === null && !readyError,
+    error: readyError,
+    mapBack,
+    resolveColumnId
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-table-ops.ts
+var import_react11 = require("react");
+function resolveOps(tableId) {
+  if (tableId === "selected") {
+    if (!grist.selectedTable) throw new Error("grist.selectedTable is not available");
+    return grist.selectedTable;
+  }
+  if (typeof grist.getTable !== "function") {
+    throw new Error("grist.getTable is not available in this Grist version");
+  }
+  return grist.getTable(tableId);
+}
+function useGristTableOps(options) {
+  const requiredAccess = options?.requiredAccess ?? "full";
+  const tableIdOption = options?.tableId ?? "selected";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [status, setStatus] = (0, import_react11.useState)("idle");
+  const [actionError, setActionError] = (0, import_react11.useState)(null);
+  const coalesceRpc = useRpcHeartbeatCoalesce();
+  let ops = null;
+  let resolveError = null;
+  if (docApi) {
+    try {
+      ops = resolveOps(tableIdOption);
+    } catch (err) {
+      resolveError = err instanceof Error ? err.message : String(err);
+    }
+  }
+  const wrap = (0, import_react11.useCallback)(
+    async (run) => {
+      if (!ops) throw new Error("Grist table operations are not ready");
+      setStatus("running");
+      setActionError(null);
+      try {
+        const out = await coalesceRpc(() => run(ops));
+        setStatus("idle");
+        return out;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setActionError(message);
+        setStatus("error");
+        throw err;
+      }
+    },
+    [ops, coalesceRpc]
+  );
+  const getTableId = (0, import_react11.useCallback)(async () => {
+    if (!ops) throw new Error("Grist table operations are not ready");
+    return ops.getTableId();
+  }, [ops]);
+  const create = (0, import_react11.useCallback)(
+    (records, opOptions) => wrap((o) => o.create(records, opOptions)),
+    [wrap]
+  );
+  const update = (0, import_react11.useCallback)(
+    (records, opOptions) => wrap((o) => o.update(records, opOptions)),
+    [wrap]
+  );
+  const upsert = (0, import_react11.useCallback)(
+    (records, opOptions) => wrap((o) => o.upsert(records, opOptions)),
+    [wrap]
+  );
+  const destroy = (0, import_react11.useCallback)(
+    (recordIds) => wrap((o) => o.destroy(recordIds)),
+    [wrap]
+  );
+  return {
+    status: readyError || resolveError ? "error" : status,
+    error: readyError ?? resolveError ?? actionError,
+    getTableId,
+    create,
+    update,
+    upsert,
+    destroy
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-rows-from-table.ts
+var import_react13 = require("react");
+
+// src/sdk/helpers/grist-table-data.ts
+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;
+}
+
+// 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);
+function useRequiredContext(ctx, name) {
+  const value = (0, import_react12.useContext)(ctx);
+  if (!value) {
+    throw new Error(`${name} must be used inside <GristWidgetProvider>`);
+  }
+  return value;
+}
+function useGristSelectionContext() {
+  return useRequiredContext(GristSelectionContext, "useGristSelectionContext()");
+}
+function useGristWidgetOptionsApiContext() {
+  return useRequiredContext(GristWidgetOptionsApiContext, "useGristWidgetOptionsApiContext()");
+}
+
+// src/sdk/mid-level-hooks/use-grist-rows-from-table.ts
+function useGristRowsFromTable(options) {
+  const requiredAccess = options.requiredAccess ?? "read table";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options.columns,
+    allowSelectBy: options.allowSelectBy,
+    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);
+  transformRef.current = options.transform;
+  const coalesceRpc = useRpcHeartbeatCoalesce();
+  const refresh = (0, import_react13.useCallback)(async () => {
+    if (!docApi) return;
+    setLoading(true);
+    setFetchError(null);
+    try {
+      const data = providerFetchTable ? await providerFetchTable(options.tableId) : await coalesceRpc(
+        () => docApi.fetchTable(options.tableId)
+      );
+      const raw = tableDataToRows(data);
+      const t = transformRef.current;
+      setRows(t ? raw.map((r) => t(r)) : raw);
+    } catch (err) {
+      setFetchError(err instanceof Error ? err.message : String(err));
+      setRows(null);
+    } finally {
+      setLoading(false);
+    }
+  }, [docApi, providerFetchTable, options.tableId, coalesceRpc]);
+  (0, import_react13.useEffect)(() => {
+    if (docApi) void refresh();
+  }, [docApi, refresh]);
+  (0, import_react13.useEffect)(() => {
+    if (!docApi || !options.pollIntervalMs || options.pollIntervalMs <= 0) return;
+    const id = window.setInterval(() => void refresh(), options.pollIntervalMs);
+    return () => window.clearInterval(id);
+  }, [docApi, options.pollIntervalMs, refresh]);
+  return {
+    rows,
+    loading,
+    error: readyError ?? fetchError,
+    refresh
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-access-token.ts
+var import_react14 = require("react");
+
+// src/sdk/helpers/grist-fetch-with-auth.ts
+var TOKEN_TTL_MS = 45e3;
+var cache = /* @__PURE__ */ new Map();
+var inFlight2 = /* @__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 = inFlight2.get(key);
+  if (pending) return pending;
+  const next = docApi.getAccessToken({ readOnly }).then((token) => {
+    cache.set(key, { token, fetchedAt: Date.now() });
+    inFlight2.delete(key);
+    return token;
+  });
+  inFlight2.set(key, next);
+  return next;
+}
+function clearGristAccessTokenCache() {
+  cache.clear();
+  inFlight2.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 method = (init?.method ?? "GET").toUpperCase();
+  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/mid-level-hooks/use-grist-access-token.ts
+function useGristAccessToken(options) {
+  const requiredAccess = options?.requiredAccess ?? "full";
+  const readOnlyDefault = options?.readOnly ?? false;
+  const prefetch = options?.prefetch ?? false;
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    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)(
+    async (overrides) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      setLoading(true);
+      setError(null);
+      try {
+        const next = await getGristAccessToken(docApi, { readOnly: overrides?.readOnly ?? readOnlyDefault });
+        setToken(next);
+        return next;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setError(message);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [docApi, readOnlyDefault]
+  );
+  const fetchFn = (0, import_react14.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)(() => {
+    if (docApi && prefetch) void refresh();
+  }, [docApi, prefetch, refresh]);
+  return {
+    token,
+    loading,
+    error: readyError ?? error,
+    refresh,
+    fetch: fetchFn
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-section.ts
+var import_react15 = require("react");
+function useGristSection(options) {
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    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 () => {
+    if (!docApi) return;
+    if (!grist.sectionApi?.mappings) {
+      setError("grist.sectionApi.mappings is not available in this Grist version");
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const next = await grist.sectionApi.mappings();
+      setMappings(next);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [docApi]);
+  const configure = (0, import_react15.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)(() => {
+    if (docApi) void refresh();
+  }, [docApi, refresh]);
+  return {
+    mappings,
+    loading,
+    error: readyError ?? error,
+    refresh,
+    configure
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-widget-options.ts
+var import_react16 = require("react");
+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 useGristWidgetOptions(config) {
+  const requiredAccess = config.requiredAccess ?? "read table";
+  const debounceMs = config.debounceMs ?? 250;
+  const hasCustomOptions = config.hasCustomOptions ?? true;
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: config.columns,
+    allowSelectBy: config.allowSelectBy,
+    hasCustomOptions,
+    onEditOptions: config.onEditOptions
+  });
+  const defaultsRef = (0, import_react16.useRef)(config.defaults);
+  (0, import_react16.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)(() => {
+    if (!docApi) return;
+    return optionsEvent.subscribe(({ options: stored }) => {
+      const merged = mergeWithDefaults(defaultsRef.current, stored, config.namespace);
+      lastWrittenRef.current = merged;
+      setOptionsState(merged);
+      setLoading(false);
+    });
+  }, [docApi, config.namespace]);
+  const flushWrite = (0, import_react16.useCallback)(
+    async (value) => {
+      try {
+        if (config.namespace) {
+          await grist.setOption(config.namespace, value);
+        } else {
+          await grist.setOptions({ ...value });
+        }
+        lastWrittenRef.current = value;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err));
+      }
+    },
+    [config.namespace]
+  );
+  const scheduleWrite = (0, import_react16.useCallback)(
+    (value) => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+      debounceRef.current = window.setTimeout(() => {
+        debounceRef.current = null;
+        void flushWrite(value);
+      }, debounceMs);
+    },
+    [debounceMs, flushWrite]
+  );
+  (0, import_react16.useEffect)(() => {
+    return () => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+    };
+  }, []);
+  const setOptionsApi = (0, import_react16.useCallback)(
+    (next) => {
+      setOptionsState(next);
+      scheduleWrite(next);
+    },
+    [scheduleWrite]
+  );
+  const patchOptionsApi = (0, import_react16.useCallback)(
+    (patch) => {
+      setOptionsState((prev) => {
+        const next = { ...prev, ...patch };
+        scheduleWrite(next);
+        return next;
+      });
+    },
+    [scheduleWrite]
+  );
+  const reset = (0, import_react16.useCallback)(async () => {
+    if (debounceRef.current) {
+      window.clearTimeout(debounceRef.current);
+      debounceRef.current = null;
+    }
+    const next = { ...defaultsRef.current };
+    setOptionsState(next);
+    await flushWrite(next);
+  }, [flushWrite]);
+  return (0, import_react16.useMemo)(
+    () => ({
+      options,
+      loading,
+      error: readyError ?? error,
+      setOptions: setOptionsApi,
+      patchOptions: patchOptionsApi,
+      reset
+    }),
+    [options, loading, readyError, error, setOptionsApi, patchOptionsApi, reset]
+  );
+}
+
+// src/sdk/mid-level-hooks/use-grist-widget-options-from-context.ts
+var import_react17 = require("react");
+function mergeWithDefaults2(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 = (0, import_react17.useRef)(config.defaults);
+  (0, import_react17.useEffect)(() => {
+    defaultsRef.current = config.defaults;
+  }, [config.defaults]);
+  const rawOptions = selection.widgetOptions;
+  const hasReceived = rawOptions !== null;
+  const merged = (0, import_react17.useMemo)(
+    () => mergeWithDefaults2(defaultsRef.current, rawOptions, config.namespace),
+    [rawOptions, config.namespace]
+  );
+  const [localOverride, setLocalOverride] = (0, import_react17.useState)(null);
+  const options = localOverride ?? merged;
+  (0, import_react17.useEffect)(() => {
+    setLocalOverride(null);
+  }, [rawOptions]);
+  const debounceRef = (0, import_react17.useRef)(null);
+  const flushWrite = (0, import_react17.useCallback)(
+    async (value) => {
+      if (config.namespace) {
+        await optionsApi.setWidgetOption(config.namespace, value);
+      } else {
+        await optionsApi.setWidgetOptions({ ...value });
+      }
+    },
+    [config.namespace, optionsApi]
+  );
+  const scheduleWrite = (0, import_react17.useCallback)(
+    (value) => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+      debounceRef.current = window.setTimeout(() => {
+        debounceRef.current = null;
+        void flushWrite(value);
+      }, debounceMs);
+    },
+    [debounceMs, flushWrite]
+  );
+  (0, import_react17.useEffect)(() => {
+    return () => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+    };
+  }, []);
+  const setOptions = (0, import_react17.useCallback)(
+    (next) => {
+      setLocalOverride(next);
+      scheduleWrite(next);
+    },
+    [scheduleWrite]
+  );
+  const patchOptions = (0, import_react17.useCallback)(
+    (patch) => {
+      setLocalOverride((prev) => {
+        const base = prev ?? merged;
+        const next = { ...base, ...patch };
+        scheduleWrite(next);
+        return next;
+      });
+    },
+    [merged, scheduleWrite]
+  );
+  const reset = (0, import_react17.useCallback)(async () => {
+    if (debounceRef.current) {
+      window.clearTimeout(debounceRef.current);
+      debounceRef.current = null;
+    }
+    const next = { ...defaultsRef.current };
+    setLocalOverride(null);
+    await flushWrite(next);
+  }, [flushWrite]);
+  return (0, import_react17.useMemo)(
+    () => ({
+      options,
+      loading: !hasReceived,
+      setOptions,
+      patchOptions,
+      reset
+    }),
+    [options, hasReceived, setOptions, patchOptions, reset]
+  );
+}
+
+// src/sdk/use-grist-table.ts
+var import_react18 = require("react");
+function isCurrentMode(option) {
+  return option === void 0 || option === "current";
+}
+function useGristTable(options) {
+  const requiredAccess = options?.requiredAccess ?? "read table";
+  const tableIdOption = options?.tableId ?? "current";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    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)(
+    async (targetTableId) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      return docApi.fetchTable(targetTableId);
+    },
+    [docApi]
+  );
+  const listTables = (0, import_react18.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 () => {
+    if (!docApi) throw new Error("Grist is not ready");
+    return String(await Promise.resolve(docApi.getDocName()));
+  }, [docApi]);
+  const fetchSelectedTable = (0, import_react18.useCallback)(
+    async (fetchOptions) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      const impl = docApi.fetchSelectedTable ?? grist.fetchSelectedTable;
+      if (!impl) throw new Error("fetchSelectedTable is not available in this Grist version");
+      const merged = { keepEncoded: false, format: "rows", ...fetchOptions };
+      return await impl(merged);
+    },
+    [docApi]
+  );
+  const fetchSelectedRecord = (0, import_react18.useCallback)(
+    async (rowId, fetchOptions) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      const impl = docApi.fetchSelectedRecord ?? grist.fetchSelectedRecord;
+      if (!impl) throw new Error("fetchSelectedRecord is not available in this Grist version");
+      const merged = { keepEncoded: false, format: "rows", ...fetchOptions };
+      return await impl(rowId, merged);
+    },
+    [docApi]
+  );
+  const refresh = (0, import_react18.useCallback)(async () => {
+    if (!docApi) return;
+    if (!isCurrentMode(tableIdOption)) {
+      setTableId(tableIdOption);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const next = await grist.selectedTable?.getTableId();
+      setTableId(next ?? null);
+    } catch (err) {
+      setTableId(null);
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [docApi, tableIdOption]);
+  (0, import_react18.useEffect)(() => {
+    if (docApi) void refresh();
+  }, [docApi, refresh]);
+  return {
+    tableId,
+    loading,
+    error: readyError ?? error,
+    refresh,
+    fetchTable,
+    listTables,
+    getDocName,
+    fetchSelectedTable,
+    fetchSelectedRecord
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GristHandshakeProvider,
+  useGristAccessToken,
+  useGristActions,
+  useGristAvailability,
+  useGristCapabilities,
+  useGristHandshake,
+  useGristHandshakeContext,
+  useGristHandshakeContextOptional,
+  useGristMappedRecord,
+  useGristNewRecord,
+  useGristReady,
+  useGristRecord,
+  useGristRecords,
+  useGristRowsFromTable,
+  useGristSection,
+  useGristTable,
+  useGristTableOps,
+  useGristWidgetOptions,
+  useGristWidgetOptionsFromContext
+});
+//# sourceMappingURL=advanced.cjs.map