grist-widget-sdk 0.3.27 → 0.5.0

package/dist/chunk-NO6FYX33.js

@@ -1,2084 +0,0 @@
-import {
-  ACCESS_RANK,
-  formatInsufficientAccessMessage,
-  isAccessSufficient,
-  parseGristRequiredAccess
-} from "./chunk-OPTOYD2Y.js";
-
-// src/sdk/helpers/grist-fetch-with-auth.ts
-var TOKEN_TTL_MS = 45e3;
-var cache = /* @__PURE__ */ new Map();
-var inFlight = /* @__PURE__ */ new Map();
-function cacheKey(readOnly) {
-  return readOnly ? "ro" : "rw";
-}
-async function getGristAccessToken(docApi, options) {
-  if (!docApi.getAccessToken) {
-    throw new Error("getAccessToken is not available on docApi (need higher access level)");
-  }
-  const readOnly = options?.readOnly ?? false;
-  const key = cacheKey(readOnly);
-  const now = Date.now();
-  const hit = cache.get(key);
-  if (hit && now - hit.fetchedAt < TOKEN_TTL_MS) {
-    return hit.token;
-  }
-  const pending = inFlight.get(key);
-  if (pending) return pending;
-  const next = docApi.getAccessToken({ readOnly }).then((token) => {
-    cache.set(key, { token, fetchedAt: Date.now() });
-    inFlight.delete(key);
-    return token;
-  });
-  inFlight.set(key, next);
-  return next;
-}
-function clearGristAccessTokenCache() {
-  cache.clear();
-  inFlight.clear();
-}
-async function fetchWithGristAuth(docApi, path, init) {
-  const readOnly = init?.readOnly ?? false;
-  let token;
-  try {
-    token = await getGristAccessToken(docApi, { readOnly });
-  } catch (err) {
-    clearGristAccessTokenCache();
-    throw err;
-  }
-  const isAbsolute = /^https?:\/\//i.test(path);
-  const cleanPath = isAbsolute ? path : path.startsWith("/") ? path : `/${path}`;
-  const url = isAbsolute ? new URL(path) : new URL(`${token.baseUrl.replace(/\/$/, "")}${cleanPath}`);
-  if (!url.searchParams.has("auth")) url.searchParams.set("auth", token.token);
-  const headers = new Headers(init?.headers ?? {});
-  headers.delete("Authorization");
-  const response = await fetch(url.toString(), { ...init, headers });
-  if (response.status === 401) {
-    clearGristAccessTokenCache();
-    const retryToken = await getGristAccessToken(docApi, { readOnly });
-    url.searchParams.set("auth", retryToken.token);
-    return fetch(url.toString(), { ...init, headers });
-  }
-  return response;
-}
-
-// src/sdk/helpers/grist-mappings.ts
-function asColumnSpec(entry) {
-  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/hooks/use-grist-core.ts
-import { useCallback, useMemo, useSyncExternalStore } from "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/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/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-manager-context.ts
-import { createContext, useContext, useEffect, useRef } from "react";
-
-// src/sdk/internal/ready-singleton.ts
-var ACCESS_RANK2 = {
-  none: 0,
-  "read table": 1,
-  full: 2
-};
-var inFlight2 = null;
-var lastAccess = null;
-var lastColumnNames = null;
-function columnNamesOf(columns) {
-  return new Set((columns ?? []).map((c) => typeof c === "string" ? c : c.name));
-}
-function shouldReinit(next, nextColumns) {
-  if (!lastAccess) return true;
-  if (ACCESS_RANK2[next] > ACCESS_RANK2[lastAccess]) return true;
-  for (const name of nextColumns) {
-    if (!lastColumnNames?.has(name)) return true;
-  }
-  return false;
-}
-function ensureGristReady(payload) {
-  const access = payload.requiredAccess ?? "read table";
-  const columns = columnNamesOf(payload.columns);
-  if (inFlight2 && !shouldReinit(access, columns)) return inFlight2;
-  lastAccess = access;
-  lastColumnNames = columns;
-  const next = Promise.resolve().then(() => {
-    const result = grist.ready(payload);
-    return result instanceof Promise ? result : Promise.resolve();
-  });
-  inFlight2 = next.catch((err) => {
-    inFlight2 = null;
-    lastAccess = null;
-    lastColumnNames = null;
-    throw err;
-  });
-  return inFlight2;
-}
-function resetGristReadySingleton() {
-  inFlight2 = null;
-  lastAccess = null;
-  lastColumnNames = null;
-}
-var resetGristReadyCacheForTests = resetGristReadySingleton;
-
-// src/sdk/internal/build-manager-options.ts
-function buildManagerOptionsFromGristOptions(options) {
-  const opts = {
-    requiredAccess: options?.requiredAccess ?? "read table",
-    columns: options?.columns ?? [],
-    allowSelectBy: options?.allowSelectBy,
-    hasCustomOptions: options?.hasCustomOptions,
-    onEditOptions: options?.onEditOptions,
-    negotiate: {
-      readyImpl: (payload) => ensureGristReady(payload)
-    },
-    onBeforeReload: () => resetGristReadySingleton()
-  };
-  if (options?.availabilityMaxAttempts !== void 0 || options?.availabilityIntervalMs !== void 0) {
-    const interval = options?.availabilityIntervalMs ?? 1e3;
-    const max = options?.availabilityMaxAttempts ?? 10;
-    opts.detect = {
-      pollSequenceMs: Array.from({ length: max }, () => interval),
-      budgetMs: interval * max
-    };
-  }
-  return opts;
-}
-
-// src/sdk/internal/handshake/effects/detect.ts
-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 });
-  });
-});
-function resetGristEventsForTests() {
-  recordEvent._resetForTests();
-  recordsEvent._resetForTests();
-  optionsEvent._resetForTests();
-  newRecordEvent._resetForTests();
-}
-
-// 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;
-  }
-}
-function resetEmbeddedHandshakeManagerForTests() {
-  if (embedded) {
-    embedded.manager.stop();
-    embedded = null;
-  }
-}
-
-// src/sdk/internal/handshake-manager-context.ts
-var GristHandshakeManagerContext = createContext(null);
-function useGristManagerOptional() {
-  return useContext(GristHandshakeManagerContext);
-}
-function useGristManager(options) {
-  const fromProvider = useContext(GristHandshakeManagerContext);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  const embeddedRef = useRef(null);
-  const ownsEmbeddedRef = useRef(false);
-  if (fromProvider) {
-    return fromProvider;
-  }
-  if (embeddedRef.current === null) {
-    embeddedRef.current = acquireEmbeddedHandshakeManager(
-      buildManagerOptionsFromGristOptions(optionsRef.current)
-    );
-    ownsEmbeddedRef.current = true;
-  }
-  useEffect(() => {
-    if (!ownsEmbeddedRef.current) return;
-    return () => {
-      releaseEmbeddedHandshakeManager();
-      embeddedRef.current = null;
-      ownsEmbeddedRef.current = false;
-    };
-  }, []);
-  return embeddedRef.current;
-}
-
-// src/sdk/internal/hooks/use-grist-core.ts
-function computeAvailabilityFromSnapshot(snapshot) {
-  const { phase } = snapshot.lifecycle;
-  if (phase === "idle" || phase === "detecting") return null;
-  if (phase === "terminated") {
-    const reason = snapshot.lifecycle.reason.kind;
-    if (reason === "not_embedded" || reason === "script_timeout") return false;
-    return true;
-  }
-  return true;
-}
-function useGristCore(options) {
-  const manager = useGristManager(options);
-  return useGristCoreFromManager(manager);
-}
-function useGristCoreFromManager(manager) {
-  const snapshot = useSyncExternalStore(
-    manager.subscribe,
-    manager.getSnapshot,
-    initialGristSnapshot
-  );
-  const status = deriveStatus(snapshot);
-  const error = deriveErrorMessage(snapshot);
-  const docApi = snapshot.lifecycle.phase === "online" && typeof grist !== "undefined" ? grist.docApi ?? null : null;
-  const isAvailable = computeAvailabilityFromSnapshot(snapshot);
-  const reload = useCallback(async () => {
-    manager.reload();
-  }, [manager]);
-  const capabilities = useMemo(() => deriveCapabilities(snapshot), [snapshot]);
-  return useMemo(
-    () => ({
-      status,
-      isAvailable,
-      isReady: status === "ready",
-      error,
-      docApi,
-      capabilities,
-      reload
-    }),
-    [status, isAvailable, error, docApi, capabilities, reload]
-  );
-}
-
-// src/sdk/low-level-hooks/use-grist-ready.ts
-function useGristReady(options) {
-  const { isAvailable, docApi, error, reload } = useGristCore(options);
-  return { isAvailable, docApi, error, reload };
-}
-
-// src/sdk/mid-level-hooks/use-grist-widget-options-from-context.ts
-import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo3, useRef as useRef2, useState } from "react";
-
-// src/sdk/internal/contexts.tsx
-import { createContext as createContext2, useContext as useContext2, useMemo as useMemo2 } from "react";
-
-// src/sdk/internal/merge-grist-result.ts
-function mergeGristResultFromSlices(slices) {
-  const { core, selection, currentTable, writes, reads, widgetOptionsApi, linking, attachmentsRest, theme, sectionApi, suppressAlerts, allowSelectBy } = slices;
-  return {
-    status: core.status,
-    isAvailable: core.isAvailable,
-    isReady: core.isReady,
-    error: core.error,
-    capabilities: core.capabilities,
-    record: selection.record,
-    records: selection.records,
-    mappedRecord: selection.mappedRecord,
-    mappings: selection.mappings,
-    recordsMappings: selection.recordsMappings,
-    columnMappingStatus: selection.columnMappingStatus,
-    mode: selection.mode,
-    resolveMappedColumnId: selection.resolveMappedColumnId,
-    mapBack: selection.mapBack,
-    mapBackSkipped: selection.mapBackSkipped,
-    isNewRecord: selection.isNewRecord,
-    newRecordMappings: selection.newRecordMappings,
-    currentTableId: currentTable.currentTableId,
-    currentTableLoading: currentTable.currentTableLoading,
-    refreshCurrentTable: currentTable.refreshCurrentTable,
-    table: writes.table,
-    getTable: writes.getTable,
-    actionStatus: writes.actionStatus,
-    actionError: writes.actionError,
-    applyActions: writes.applyActions,
-    reload: core.reload,
-    fetchTable: reads.fetchTable,
-    fetchTableRows: reads.fetchTableRows,
-    fetchRow: reads.fetchRow,
-    listTables: reads.listTables,
-    listColumns: reads.listColumns,
-    getDocName: reads.getDocName,
-    buildReplicaDocumentFromDocApi: reads.buildReplicaDocumentFromDocApi,
-    getAttachmentUrl: attachmentsRest.getAttachmentUrl,
-    fetchAttachmentBase64: attachmentsRest.fetchAttachmentBase64,
-    fetchAttachmentBlob: attachmentsRest.fetchAttachmentBlob,
-    widgetOptions: selection.widgetOptions,
-    widgetInteraction: selection.widgetInteraction,
-    getWidgetOptions: widgetOptionsApi.getWidgetOptions,
-    getWidgetOption: widgetOptionsApi.getWidgetOption,
-    setWidgetOption: widgetOptionsApi.setWidgetOption,
-    setWidgetOptions: widgetOptionsApi.setWidgetOptions,
-    patchWidgetOptions: widgetOptionsApi.patchWidgetOptions,
-    clearWidgetOptions: widgetOptionsApi.clearWidgetOptions,
-    fetchSelectedTable: reads.fetchSelectedTable,
-    fetchSelectedRecord: reads.fetchSelectedRecord,
-    readError: reads.readError ?? attachmentsRest.readError,
-    setCursorPosition: linking.setCursorPosition,
-    setLinkedRowSelection: linking.setLinkedRowSelection,
-    getAccessToken: attachmentsRest.getAccessToken,
-    fetchWithAuth: attachmentsRest.fetchWithAuth,
-    uploadAttachment: attachmentsRest.uploadAttachment,
-    theme: theme.theme,
-    configure: sectionApi.configure,
-    refreshMappings: sectionApi.refreshMappings,
-    suppressAlerts,
-    allowSelectBy
-  };
-}
-
-// src/sdk/internal/contexts.tsx
-var GristCoreContext = createContext2(null);
-var GristSelectionContext = createContext2(null);
-var GristCurrentTableContext = createContext2(null);
-var GristWritesContext = createContext2(null);
-var GristReadsContext = createContext2(null);
-var GristWidgetOptionsApiContext = createContext2(null);
-var GristLinkingContext = createContext2(null);
-var GristAttachmentsRestContext = createContext2(null);
-var GristThemeContext = createContext2(null);
-var GristSectionApiContext = createContext2(null);
-function useRequiredContext(ctx, name) {
-  const value = useContext2(ctx);
-  if (!value) {
-    throw new Error(`${name} must be used inside <GristWidgetProvider>`);
-  }
-  return value;
-}
-function useGristCoreContext() {
-  return useRequiredContext(GristCoreContext, "useGristCoreContext()");
-}
-function useGristSelectionContext() {
-  return useRequiredContext(GristSelectionContext, "useGristSelectionContext()");
-}
-function useGristCurrentTableContext() {
-  return useRequiredContext(GristCurrentTableContext, "useGristCurrentTableContext()");
-}
-function useGristWritesContext() {
-  return useRequiredContext(GristWritesContext, "useGristWritesContext()");
-}
-function useGristReadsContext() {
-  return useRequiredContext(GristReadsContext, "useGristReadsContext()");
-}
-function useGristWidgetOptionsApiContext() {
-  return useRequiredContext(GristWidgetOptionsApiContext, "useGristWidgetOptionsApiContext()");
-}
-function useGristLinkingContext() {
-  return useRequiredContext(GristLinkingContext, "useGristLinkingContext()");
-}
-function useGristAttachmentsRestContext() {
-  return useRequiredContext(GristAttachmentsRestContext, "useGristAttachmentsRestContext()");
-}
-function useGristThemeContext() {
-  return useRequiredContext(GristThemeContext, "useGristThemeContext()");
-}
-function useGristSectionApiContext() {
-  return useRequiredContext(GristSectionApiContext, "useGristSectionApiContext()");
-}
-function useGristFromProvider() {
-  const core = useGristCoreContext();
-  const selection = useGristSelectionContext();
-  const currentTable = useGristCurrentTableContext();
-  const writes = useGristWritesContext();
-  const reads = useGristReadsContext();
-  const widgetOptionsApi = useGristWidgetOptionsApiContext();
-  const linking = useGristLinkingContext();
-  const attachmentsRest = useGristAttachmentsRestContext();
-  const theme = useGristThemeContext();
-  const sectionApi = useGristSectionApiContext();
-  return useMemo2(
-    () => mergeGristResultFromSlices({
-      core,
-      selection,
-      currentTable,
-      writes,
-      reads,
-      widgetOptionsApi,
-      linking,
-      attachmentsRest,
-      theme,
-      sectionApi
-    }),
-    [
-      core,
-      selection,
-      currentTable,
-      writes,
-      reads,
-      widgetOptionsApi,
-      linking,
-      attachmentsRest,
-      theme,
-      sectionApi
-    ]
-  );
-}
-
-// src/sdk/mid-level-hooks/use-grist-widget-options-from-context.ts
-function mergeWithDefaults(defaults, stored, namespace) {
-  if (stored === null || stored === void 0) return { ...defaults };
-  const source = namespace ? stored[namespace] : stored;
-  if (!source || typeof source !== "object") return { ...defaults };
-  return { ...defaults, ...source };
-}
-function useGristWidgetOptionsFromContext(config) {
-  const debounceMs = config.debounceMs ?? 250;
-  const selection = useGristSelectionContext();
-  const optionsApi = useGristWidgetOptionsApiContext();
-  const defaultsRef = useRef2(config.defaults);
-  useEffect2(() => {
-    defaultsRef.current = config.defaults;
-  }, [config.defaults]);
-  const rawOptions = selection.widgetOptions;
-  const hasReceived = rawOptions !== null;
-  const merged = useMemo3(
-    () => mergeWithDefaults(defaultsRef.current, rawOptions, config.namespace),
-    [rawOptions, config.namespace]
-  );
-  const [localOverride, setLocalOverride] = useState(null);
-  const options = localOverride ?? merged;
-  useEffect2(() => {
-    setLocalOverride(null);
-  }, [rawOptions]);
-  const debounceRef = useRef2(null);
-  const flushWrite = useCallback2(
-    async (value) => {
-      if (config.namespace) {
-        await optionsApi.setWidgetOption(config.namespace, value);
-      } else {
-        await optionsApi.setWidgetOptions({ ...value });
-      }
-    },
-    [config.namespace, optionsApi]
-  );
-  const scheduleWrite = useCallback2(
-    (value) => {
-      if (debounceRef.current) window.clearTimeout(debounceRef.current);
-      debounceRef.current = window.setTimeout(() => {
-        debounceRef.current = null;
-        void flushWrite(value);
-      }, debounceMs);
-    },
-    [debounceMs, flushWrite]
-  );
-  useEffect2(() => {
-    return () => {
-      if (debounceRef.current) window.clearTimeout(debounceRef.current);
-    };
-  }, []);
-  const setOptions = useCallback2(
-    (next) => {
-      setLocalOverride(next);
-      scheduleWrite(next);
-    },
-    [scheduleWrite]
-  );
-  const patchOptions = useCallback2(
-    (patch) => {
-      setLocalOverride((prev) => {
-        const base = prev ?? merged;
-        const next = { ...base, ...patch };
-        scheduleWrite(next);
-        return next;
-      });
-    },
-    [merged, scheduleWrite]
-  );
-  const reset = useCallback2(async () => {
-    if (debounceRef.current) {
-      window.clearTimeout(debounceRef.current);
-      debounceRef.current = null;
-    }
-    const next = { ...defaultsRef.current };
-    setLocalOverride(null);
-    await flushWrite(next);
-  }, [flushWrite]);
-  return useMemo3(
-    () => ({
-      options,
-      loading: !hasReceived,
-      setOptions,
-      patchOptions,
-      reset
-    }),
-    [options, hasReceived, setOptions, patchOptions, reset]
-  );
-}
-
-// src/sdk/internal/hooks/use-rpc-heartbeat-coalesce.ts
-import { useCallback as useCallback3 } from "react";
-function useRpcHeartbeatCoalesce() {
-  const manager = useGristManagerOptional();
-  return useCallback3(
-    async (fn) => {
-      const result = await fn();
-      manager?.recordRpcSuccess();
-      return result;
-    },
-    [manager]
-  );
-}
-
-export {
-  getGristAccessToken,
-  fetchWithGristAuth,
-  validateColumnMappings,
-  initialGristSnapshot,
-  deriveStatus,
-  deriveErrorMessage,
-  deriveCapabilities,
-  extractResolvedMappings,
-  deriveColumnMappingStatus,
-  parseGristWidgetLinkingInfo,
-  ensureGristReady,
-  resetGristReadySingleton,
-  resetGristReadyCacheForTests,
-  buildManagerOptionsFromGristOptions,
-  recordEvent,
-  recordsEvent,
-  optionsEvent,
-  newRecordEvent,
-  resetGristEventsForTests,
-  createGristHandshakeManager,
-  resetEmbeddedHandshakeManagerForTests,
-  GristHandshakeManagerContext,
-  useGristManagerOptional,
-  useGristManager,
-  mergeGristResultFromSlices,
-  GristCoreContext,
-  GristSelectionContext,
-  GristCurrentTableContext,
-  GristWritesContext,
-  GristReadsContext,
-  GristWidgetOptionsApiContext,
-  GristLinkingContext,
-  GristAttachmentsRestContext,
-  GristThemeContext,
-  GristSectionApiContext,
-  useGristCoreContext,
-  useGristSelectionContext,
-  useGristCurrentTableContext,
-  useGristWritesContext,
-  useGristThemeContext,
-  useGristFromProvider,
-  useGristCore,
-  useRpcHeartbeatCoalesce,
-  useGristReady,
-  useGristWidgetOptionsFromContext
-};
-//# sourceMappingURL=chunk-NO6FYX33.js.map