grist-widget-sdk 0.2.0

package/dist/chunk-XE2SKNLH.js

@@ -0,0 +1,1641 @@
+// 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
+  };
+}
+var pendingColumnMappingStatus = {
+  ok: true,
+  pending: true,
+  missing: [],
+  emptyMultiples: []
+};
+
+// 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/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/derive.ts
+function deriveStatus(snapshot) {
+  const { lifecycle, authz, link } = snapshot;
+  if (lifecycle.phase === "idle" || lifecycle.phase === "detecting") return "booting";
+  if (lifecycle.phase === "negotiating") return "booting";
+  if (lifecycle.phase === "terminated") {
+    switch (lifecycle.reason.kind) {
+      case "script_timeout":
+      case "not_embedded":
+        return "unavailable";
+      case "host_rejected":
+      case "ready_failed":
+      case "ready_timeout":
+      case "manual_terminate":
+        return "error";
+    }
+  }
+  if (authz.state === "denied") return "error";
+  if (link.state === "lost") return "error";
+  return "ready";
+}
+function deriveErrorMessage(snapshot) {
+  if (snapshot.lifecycle.phase === "terminated") {
+    switch (snapshot.lifecycle.reason.kind) {
+      case "ready_failed":
+        return snapshot.lifecycle.reason.message;
+      case "ready_timeout":
+        return `Grist handshake timed out after ${snapshot.lifecycle.reason.afterMs}ms`;
+      case "host_rejected":
+        return snapshot.lifecycle.reason.message;
+      case "script_timeout":
+        return `Grist plugin API never loaded (${snapshot.lifecycle.reason.attempts} attempts)`;
+      case "not_embedded":
+        return "This page is not embedded in a Grist iframe";
+      case "manual_terminate":
+        return null;
+    }
+  }
+  if (snapshot.authz.state === "denied") {
+    return snapshot.authz.message ?? `Grist denied requested access (${snapshot.authz.declared})`;
+  }
+  if (snapshot.lifecycle.phase === "online" && snapshot.link.state === "lost") {
+    return `Grist link lost (${snapshot.link.missedPings} consecutive failures)`;
+  }
+  return null;
+}
+function deriveCapabilities(snapshot) {
+  const { lifecycle, authz, link, config, sync } = snapshot;
+  const online = lifecycle.phase === "online";
+  const granted = authz.state === "granted";
+  const grantedReadOrMore = granted && ACCESS_RANK[authz.level] >= ACCESS_RANK["read table"];
+  const grantedFull = granted && authz.level === "full";
+  const linkUsable = link.state !== "lost";
+  const canRead = online && linkUsable && grantedReadOrMore;
+  const canFetchTable = canRead && link.state === "connected";
+  const mappingsUsable = hasUsableMappings(config.mappings);
+  const missing = mappingsMissing(config.mappings);
+  const emptyMultiples = mappingsEmptyMultiples(config.mappings);
+  const canRender = canRead && mappingsUsable;
+  const canWriteRecords = canRender && grantedFull;
+  const canWriteSchema = canWriteRecords && sync.currentTable.state === "known";
+  const hasFreshSelection = canRead && sync.record.state === "hot" && config.mappings.state !== "invalidating";
+  return {
+    canRead,
+    canRender,
+    canWriteRecords,
+    canWriteSchema,
+    canFetchTable,
+    hasFreshSelection,
+    hasUsableMappings: mappingsUsable,
+    missingMappings: missing,
+    emptyMultipleMappings: emptyMultiples
+  };
+}
+function hasUsableMappings(state) {
+  if (state.state === "not_declared") return true;
+  if (state.state === "complete") return true;
+  if (state.state === "invalidating") {
+    return state.previous.state === "complete";
+  }
+  return false;
+}
+function mappingsMissing(state) {
+  if (state.state === "incomplete") return state.missing;
+  if (state.state === "invalidating" && state.previous.state === "incomplete") {
+    return state.previous.missing;
+  }
+  return EMPTY;
+}
+function mappingsEmptyMultiples(state) {
+  if (state.state === "incomplete") return state.emptyMultiples;
+  if (state.state === "invalidating" && state.previous.state === "incomplete") {
+    return state.previous.emptyMultiples;
+  }
+  return EMPTY;
+}
+var EMPTY = Object.freeze([]);
+function extractResolvedMappings(state) {
+  switch (state.state) {
+    case "complete":
+    case "incomplete":
+      return state.mappings;
+    case "invalidating":
+      if (state.previous.state === "complete" || state.previous.state === "incomplete") {
+        return state.previous.mappings;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+function deriveColumnMappingStatus(mappingState, columns) {
+  if (!columns?.length) {
+    return { ok: true, pending: false, missing: [], emptyMultiples: [] };
+  }
+  switch (mappingState.state) {
+    case "not_declared":
+      return { ok: true, pending: false, missing: [], emptyMultiples: [] };
+    case "pending":
+      return pendingColumnMappingStatus;
+    case "unreported":
+      return pendingColumnMappingStatus;
+    case "complete":
+      return { ok: true, pending: false, missing: [], emptyMultiples: [] };
+    case "incomplete":
+      return {
+        ok: false,
+        pending: false,
+        missing: [...mappingState.missing],
+        emptyMultiples: [...mappingState.emptyMultiples]
+      };
+    case "invalidating":
+      return deriveColumnMappingStatus(mappingState.previous, columns);
+  }
+}
+
+// src/sdk/internal/handshake/actions.ts
+function hasGenerationStamp(action) {
+  return "generation" in action && typeof action.generation === "number";
+}
+
+// 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/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/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/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;
+}
+var resetGristReadyCacheForTests = resetGristReadySingleton;
+
+// src/sdk/internal/subscriptions.ts
+var GristEvent = class {
+  constructor(bindOnce) {
+    this.bindOnce = bindOnce;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.hasValue = false;
+    this.bind = null;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    if (!this.bind) {
+      this.bind = () => {
+        this.bind = () => {
+        };
+        try {
+          this.bindOnce((value) => {
+            this.hasValue = true;
+            this.last = value;
+            for (const l of this.listeners) l(value);
+          });
+        } catch (err) {
+          if (typeof console !== "undefined") {
+            console.error("[lib/grist] failed to subscribe to Grist event:", err);
+          }
+        }
+      };
+      this.bind();
+    }
+    if (this.hasValue && this.last !== void 0) {
+      listener(this.last);
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Last cached value (or `undefined` if no event has fired yet). */
+  peek() {
+    return this.last;
+  }
+  /** True once at least one event has fired. */
+  get ready() {
+    return this.hasValue;
+  }
+  /**
+   * Test helper: fan out a payload without calling `grist.on*`.
+   * Used to simulate hosts that reuse one record object and mutate it in place.
+   */
+  deliverForTests(value) {
+    this.hasValue = true;
+    this.last = value;
+    for (const l of this.listeners) l(value);
+  }
+  /**
+   * Test helper: forget the bound state and cached value. Lets a test swap
+   * `window.grist` (e.g. via the emulator's `dispose()` + `createGristEmulator()`)
+   * and re-bind cleanly on the next subscribe.
+   */
+  _resetForTests() {
+    this.listeners.clear();
+    this.hasValue = false;
+    this.last = void 0;
+    this.bind = null;
+  }
+};
+var recordEvent = new GristEvent((emit) => {
+  const deliver = (record, mappings) => {
+    emit({ record, mappings });
+  };
+  grist.onRecord(
+    (record, mappings) => {
+      deliver(record, mappings ?? null);
+    },
+    { keepEncoded: false }
+  );
+  const fetchSelectedRecord = grist.fetchSelectedRecord ?? grist.docApi?.fetchSelectedRecord;
+  if (typeof grist.on !== "function" || typeof fetchSelectedRecord !== "function") {
+    return;
+  }
+  let lastRowId;
+  grist.on("message", async (msg) => {
+    if (!msg || typeof msg !== "object") return;
+    const host = msg;
+    if (!host.tableId || typeof host.rowId !== "number") return;
+    if (host.rowId === lastRowId) return;
+    lastRowId = host.rowId;
+    try {
+      const record = await fetchSelectedRecord(host.rowId, { keepEncoded: false });
+      deliver(record, recordEvent.peek()?.mappings ?? null);
+    } catch (err) {
+      if (typeof console !== "undefined") {
+        console.error("[grist-widget-sdk] fetchSelectedRecord on cursor message failed:", err);
+      }
+    }
+  });
+});
+var recordsEvent = new GristEvent((emit) => {
+  grist.onRecords(
+    (records, mappings) => {
+      emit({ records, mappings: mappings ?? null });
+    },
+    { keepEncoded: false, format: "rows" }
+  );
+});
+var optionsEvent = new GristEvent((emit) => {
+  grist.onOptions((options, interaction) => {
+    const normalized = normalizeWidgetInteraction(
+      interaction ?? null
+    );
+    emit({
+      options: options ? { ...options } : null,
+      interaction: normalized
+    });
+  });
+});
+var newRecordEvent = new GristEvent((emit) => {
+  if (typeof grist.onNewRecord !== "function") return;
+  grist.onNewRecord((mappings) => {
+    emit({ mappings: mappings ?? null });
+  });
+});
+function resetGristEventsForTests() {
+  recordEvent._resetForTests();
+  recordsEvent._resetForTests();
+  optionsEvent._resetForTests();
+  newRecordEvent._resetForTests();
+}
+
+// src/sdk/internal/handshake/effects/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/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 inFlight2 = 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 (inFlight2) {
+      return;
+    }
+    inFlight2 = true;
+    inFlightTimeoutTimer = env.setTimeout(() => {
+      if (!inFlight2) return;
+      inFlight2 = false;
+      clearInFlightTimeout();
+      if (!cancelled) {
+        dispatch({ type: "HEARTBEAT_FAIL", atMs: env.now() });
+        scheduleNext();
+      }
+    }, pingTimeoutMs);
+    const handleOk = () => {
+      if (!inFlight2) return;
+      inFlight2 = false;
+      clearInFlightTimeout();
+      if (cancelled) return;
+      dispatch({ type: "HEARTBEAT_OK", atMs: env.now() });
+      scheduleNext();
+    };
+    const handleFail = () => {
+      if (!inFlight2) return;
+      inFlight2 = 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();
+    inFlight2 = false;
+    offVisibility?.();
+    offOnline?.();
+  });
+  scheduleNext();
+  return {
+    cancel() {
+      cancelled = true;
+      clearInterval();
+      clearInFlightTimeout();
+      inFlight2 = 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;
+  }
+}
+function resetEmbeddedHandshakeManagerForTests() {
+  if (embedded) {
+    embedded.manager.stop();
+    embedded = null;
+  }
+}
+
+export {
+  validateColumnMappings,
+  gristAccessLevelLabel,
+  initialGristSnapshot,
+  deriveStatus,
+  deriveErrorMessage,
+  deriveCapabilities,
+  extractResolvedMappings,
+  deriveColumnMappingStatus,
+  parseGristWidgetLinkingInfo,
+  ensureGristReady,
+  resetGristReadySingleton,
+  resetGristReadyCacheForTests,
+  recordEvent,
+  recordsEvent,
+  optionsEvent,
+  newRecordEvent,
+  resetGristEventsForTests,
+  createGristHandshakeManager,
+  acquireEmbeddedHandshakeManager,
+  releaseEmbeddedHandshakeManager,
+  resetEmbeddedHandshakeManagerForTests
+};
+//# sourceMappingURL=chunk-XE2SKNLH.js.map