@morscherlab/mint-sdk 1.5.0-beta.15 → 1.5.0-beta.17

package/dist/useRealtime-t7Qg2a5h.js

@@ -0,0 +1,216 @@
+import { computed, getCurrentScope, onScopeDispose, readonly, ref, toValue, watch } from "vue";
+import { defineStore } from "pinia";
+//#region src/stores/auth.ts
+/** localStorage key of the platform session token. The platform owns the stored value. */
+var AUTH_TOKEN_STORAGE_KEY = "mint-auth-token";
+/** localStorage key of the platform session token expiry (ISO 8601). */
+var AUTH_EXPIRES_STORAGE_KEY = "mint-auth-expires";
+function readStoredItem(key) {
+	try {
+		const storage = globalThis.localStorage;
+		return typeof storage?.getItem === "function" ? storage.getItem(key) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Read-only session bridge between the platform and SDK code.
+*
+* SDK clients read the session token from here. Only the platform writes the
+* session, through `@morscherlab/mint-sdk/host`. The SDK never writes or removes
+* the stored platform token.
+*/
+var useAuthStore = defineStore("mint-auth", () => {
+	const token = ref(null);
+	const tokenExpires = ref(null);
+	const userInfo = ref(null);
+	const authRequired = ref(true);
+	const isInitialized = ref(false);
+	const isAuthenticated = computed(() => {
+		if (!authRequired.value) return true;
+		if (!token.value) return false;
+		return !(tokenExpires.value && tokenExpires.value < /* @__PURE__ */ new Date());
+	});
+	/** Read the stored platform session token, once per page. */
+	function initialize() {
+		const storedToken = readStoredItem(AUTH_TOKEN_STORAGE_KEY);
+		const storedExpires = readStoredItem(AUTH_EXPIRES_STORAGE_KEY);
+		const expires = storedExpires ? new Date(storedExpires) : null;
+		if (storedToken && !(expires && expires <= /* @__PURE__ */ new Date())) {
+			token.value = storedToken;
+			tokenExpires.value = expires;
+		}
+		isInitialized.value = true;
+	}
+	/** Forget the session in memory after the server rejected its token. */
+	function clearToken() {
+		token.value = null;
+		tokenExpires.value = null;
+		userInfo.value = null;
+	}
+	return {
+		token,
+		tokenExpires,
+		userInfo,
+		authRequired,
+		isInitialized,
+		isAuthenticated,
+		initialize,
+		clearToken
+	};
+});
+//#endregion
+//#region src/composables/useRealtime.ts
+var EVENTS_URL = "/api/events";
+var RECONNECT_BASE_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+/** Merges the subscriptions of components that mount together into one connection. */
+var TOPIC_DEBOUNCE_MS = 50;
+var RESYNC = { type: "resync" };
+var listeners = /* @__PURE__ */ new Set();
+/** The last `presence.changed` of each topic of the open stream; the server sends one per topic at open. */
+var presence = /* @__PURE__ */ new Map();
+var connected = ref(false);
+var source = null;
+var sourceTopics = "";
+var failures = 0;
+var syncTimer = null;
+var retryTimer = null;
+/** The lowest `X-MINT-Event-Seq` of the responses since the page loaded, and their boot id (`''` once two differ). */
+var tracked = null;
+/** The cursor the current stream was opened with. */
+var streamCursor = null;
+/** @internal Record the `X-MINT-Event-Seq` / `X-MINT-Boot-Id` headers of one platform response. */
+function noteEventSeq(seq, bootId) {
+	const value = Number(seq);
+	if (!seq || !bootId || !Number.isSafeInteger(value)) return;
+	if (streamCursor && (value < streamCursor.seq || bootId !== streamCursor.boot)) {
+		streamCursor = {
+			seq: value,
+			boot: bootId
+		};
+		dispatch(RESYNC);
+	}
+	tracked = tracked ? {
+		seq: Math.min(tracked.seq, value),
+		boot: tracked.boot === bootId ? tracked.boot : ""
+	} : {
+		seq: value,
+		boot: bootId
+	};
+}
+function dispatch(event) {
+	const isPresence = event.type === "presence.changed";
+	if (isPresence && event.topic) presence.set(event.topic, event);
+	for (const listener of [...listeners]) {
+		if (isPresence && !listener.presence) continue;
+		if (event.type === "resync" || event.topic && listener.topics().includes(event.topic)) listener.handler(event);
+	}
+}
+function close() {
+	source?.close();
+	source = null;
+	sourceTopics = "";
+	presence.clear();
+	streamCursor = null;
+	connected.value = false;
+}
+function open(topics) {
+	const cursor = tracked && [...listeners].every((listener) => listener.cursor) ? tracked : null;
+	const query = cursor ? `&since=${cursor.seq}&boot=${encodeURIComponent(cursor.boot)}` : "";
+	const stream = new EventSource(`${EVENTS_URL}?topics=${encodeURIComponent(topics)}${query}`);
+	source = stream;
+	sourceTopics = topics;
+	streamCursor = cursor;
+	stream.onopen = () => {
+		connected.value = true;
+		if (!cursor || ![...listeners].every((listener) => listener.cursor)) dispatch(RESYNC);
+		failures = 0;
+	};
+	stream.onmessage = (message) => {
+		dispatch(JSON.parse(message.data));
+	};
+	stream.onerror = () => {
+		if (source !== stream) return;
+		close();
+		if (syncTimer !== null) clearTimeout(syncTimer);
+		syncTimer = null;
+		retryTimer = setTimeout(() => {
+			retryTimer = null;
+			sync();
+		}, Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** failures));
+		failures += 1;
+	};
+}
+function sync() {
+	syncTimer = null;
+	const topics = [...new Set([...listeners].flatMap((listener) => listener.topics()))].sort().join(",");
+	if (source && topics === sourceTopics) return;
+	close();
+	if (topics) open(topics);
+}
+function schedule() {
+	if (retryTimer !== null) return;
+	if (syncTimer !== null) clearTimeout(syncTimer);
+	syncTimer = setTimeout(sync, TOPIC_DEBOUNCE_MS);
+}
+/**
+* Subscribe to topics of the platform's realtime stream.
+*
+* Every caller in a tab shares one `EventSource`, opened on the union of
+* their topics and reopened when that union changes. `handler` receives the
+* write events of the caller's own topics (not `presence.changed`, which goes
+* to `usePresence`) plus every `resync`: one comes from the
+* server when this tab fell behind, and one follows each open of the stream:
+* the first open, each reconnect (backoff from 1 s to 30 s) and each reopen for
+* a changed topic union. With `options.cursor` set by every caller, the open
+* sends no `resync` of its own; the server sends one when a topic changed since
+* the oldest recorded REST load. On `resync`, refetch. The union of all callers' topics
+* in a tab may hold at most 50 topics; the platform refuses a larger stream.
+*
+* The stream authenticates with the session cookie, so it works in the
+* platform and in plugin frontends served by it. It exists only when the
+* platform's `realtime` feature flag is on; check that flag first.
+*
+* A plugin topic reaches a caller whose role may use the plugin; an
+* experiment plugin topic also needs a caller who may view the experiment.
+*
+* @example
+* useRealtime(() => [`experiment:${id.value}`], () => refetch())
+* @example
+* useRealtime(['plugin:drp'], (event) => {
+*   if (event.type === 'drp.run.progress') progress.value = event.payload as RunProgress
+* })
+*/
+function useRealtime(topics, handler, options = {}) {
+	return subscribeRealtime(topics, handler, false, options.cursor ?? false);
+}
+/** The last `presence.changed` of `topic` while the open stream views it (for `usePresence`). */
+function currentPresence(topic) {
+	return presence.get(topic);
+}
+/** `useRealtime`, and with `withPresence` also the `presence.changed` events (for `usePresence`). */
+function subscribeRealtime(topics, handler, withPresence, cursor = false) {
+	const listener = {
+		topics: () => toValue(topics),
+		handler,
+		presence: withPresence,
+		cursor: cursor || withPresence
+	};
+	listeners.add(listener);
+	const stopWatch = watch(() => listener.topics().join(","), () => schedule());
+	schedule();
+	function stop() {
+		stopWatch();
+		if (listeners.delete(listener)) schedule();
+	}
+	if (getCurrentScope()) onScopeDispose(stop);
+	return {
+		connected: readonly(connected),
+		stop
+	};
+}
+//#endregion
+export { AUTH_EXPIRES_STORAGE_KEY as a, useRealtime as i, noteEventSeq as n, AUTH_TOKEN_STORAGE_KEY as o, subscribeRealtime as r, useAuthStore as s, currentPresence as t };
+
+//# sourceMappingURL=useRealtime-t7Qg2a5h.js.map

package/dist/useRealtime-t7Qg2a5h.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRealtime-t7Qg2a5h.js","names":[],"sources":["../src/stores/auth.ts","../src/composables/useRealtime.ts"],"sourcesContent":["import { defineStore } from 'pinia'\nimport { ref, computed } from 'vue'\nimport type { UserInfo } from '../types'\n\n/** localStorage key of the platform session token. The platform owns the stored value. */\nexport const AUTH_TOKEN_STORAGE_KEY = 'mint-auth-token'\n/** localStorage key of the platform session token expiry (ISO 8601). */\nexport const AUTH_EXPIRES_STORAGE_KEY = 'mint-auth-expires'\n\nfunction readStoredItem(key: string): string | null {\n  try {\n    const storage = globalThis.localStorage\n    return typeof storage?.getItem === 'function' ? storage.getItem(key) : null\n  } catch {\n    return null\n  }\n}\n\n/**\n * Read-only session bridge between the platform and SDK code.\n *\n * SDK clients read the session token from here. Only the platform writes the\n * session, through `@morscherlab/mint-sdk/host`. The SDK never writes or removes\n * the stored platform token.\n */\nexport const useAuthStore = defineStore('mint-auth', () => {\n  const token = ref<string | null>(null)\n  const tokenExpires = ref<Date | null>(null)\n  const userInfo = ref<UserInfo | null>(null)\n  const authRequired = ref(true)\n  const isInitialized = ref(false)\n\n  const isAuthenticated = computed(() => {\n    if (!authRequired.value) return true\n    if (!token.value) return false\n    return !(tokenExpires.value && tokenExpires.value < new Date())\n  })\n\n  /** Read the stored platform session token, once per page. */\n  function initialize() {\n    const storedToken = readStoredItem(AUTH_TOKEN_STORAGE_KEY)\n    const storedExpires = readStoredItem(AUTH_EXPIRES_STORAGE_KEY)\n    const expires = storedExpires ? new Date(storedExpires) : null\n\n    if (storedToken && !(expires && expires <= new Date())) {\n      token.value = storedToken\n      tokenExpires.value = expires\n    }\n\n    isInitialized.value = true\n  }\n\n  /** Forget the session in memory after the server rejected its token. */\n  function clearToken() {\n    token.value = null\n    tokenExpires.value = null\n    userInfo.value = null\n  }\n\n  return {\n    token,\n    tokenExpires,\n    userInfo,\n    authRequired,\n    isInitialized,\n    isAuthenticated,\n    initialize,\n    clearToken,\n  }\n})\n","import {\n  getCurrentScope,\n  onScopeDispose,\n  readonly,\n  ref,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type Ref,\n} from 'vue'\n\n/**\n * One event of the platform's realtime stream (`GET /api/events`).\n *\n * Platform events carry no entity data: refetch the entity through REST.\n * `type` is `resync` (refetch everything you show), the audit action of a\n * committed write, such as `experiment.update` or `analysis.artifact_create`,\n * or the `\"<plugin>.<event>\"` name of a plugin event, which carries `payload`.\n * Only `usePresence` receives `presence.changed`.\n */\nexport interface RealtimeEvent {\n  type: string\n  id?: string\n  /**\n   * `experiment:{id}`, `project:{id}`, `experiments`, `user:{id}`, or a plugin's\n   * `plugin:{name}` / `plugin:{name}:experiment:{id}`; absent on `resync`.\n   */\n  topic?: string\n  /** A plugin event: the JSON payload the plugin published (at most 16 KiB). */\n  payload?: unknown\n  /** Changed fields of an update, when the write names them. */\n  fields?: string[] | null\n  actor_id?: string | null\n  request_id?: string | null\n  at?: string\n  /** `presence.changed`: the topic's viewers (at most 20, `editing` first). */\n  viewers?: { user_id: string, activity: string }[]\n  /** `presence.changed`: the number of viewers, also those beyond `viewers`. */\n  count?: number\n}\n\nexport type RealtimeHandler = (event: RealtimeEvent) => void\n\nexport interface UseRealtimeOptions {\n  /**\n   * The caller loads all its data through a client that records\n   * `X-MINT-Event-Seq`: `useApi()`, a `createClient` client (it sends each\n   * request through `useApi()`) or the platform's own client. Responses of a\n   * plain `fetch` or another HTTP client are not recorded, so a caller that\n   * loads through them must not set it. When every caller of the tab sets it, the stream opens with the\n   * lowest recorded sequence since the page loaded, and the server sends\n   * `resync` only when a topic changed since then, instead of one at each open.\n   */\n  cursor?: boolean\n}\n\nexport interface UseRealtimeReturn {\n  /** True while the shared stream is open. */\n  connected: Readonly<Ref<boolean>>\n  /** Unsubscribe; also runs when the calling component or effect scope is disposed. */\n  stop: () => void\n}\n\nconst EVENTS_URL = '/api/events'\nconst RECONNECT_BASE_MS = 1_000\nconst RECONNECT_MAX_MS = 30_000\n/** Merges the subscriptions of components that mount together into one connection. */\nconst TOPIC_DEBOUNCE_MS = 50\nconst RESYNC: RealtimeEvent = { type: 'resync' }\n\ninterface Listener {\n  topics: () => string[]\n  handler: RealtimeHandler\n  /** Receives `presence.changed`; a write listener would refetch on each viewer change. */\n  presence: boolean\n  /** Its data loads record their event cursor (see `UseRealtimeOptions.cursor`). */\n  cursor: boolean\n}\n\ninterface EventCursor {\n  seq: number\n  boot: string\n}\n\nconst listeners = new Set<Listener>()\n/** The last `presence.changed` of each topic of the open stream; the server sends one per topic at open. */\nconst presence = new Map<string, RealtimeEvent>()\nconst connected = ref(false)\nlet source: EventSource | null = null\nlet sourceTopics = ''\nlet failures = 0\nlet syncTimer: ReturnType<typeof setTimeout> | null = null\nlet retryTimer: ReturnType<typeof setTimeout> | null = null\n/** The lowest `X-MINT-Event-Seq` of the responses since the page loaded, and their boot id (`''` once two differ). */\nlet tracked: EventCursor | null = null\n/** The cursor the current stream was opened with. */\nlet streamCursor: EventCursor | null = null\n\n/** @internal Record the `X-MINT-Event-Seq` / `X-MINT-Boot-Id` headers of one platform response. */\nexport function noteEventSeq(seq: string | null | undefined, bootId: string | null | undefined): void {\n  const value = Number(seq)\n  // No header: the response tells nothing (an older platform, another origin).\n  if (!seq || !bootId || !Number.isSafeInteger(value)) return\n  // A request that started before the stream's cursor, or on another process,\n  // may miss an event the server did not check: refetch.\n  if (streamCursor && (value < streamCursor.seq || bootId !== streamCursor.boot)) {\n    // Moved, so each late condition refetches once instead of on every refetch response.\n    streamCursor = { seq: value, boot: bootId }\n    dispatch(RESYNC)\n  }\n  // Sequences of two processes do not compare: '' never matches, so every later open resyncs.\n  tracked = tracked\n    ? { seq: Math.min(tracked.seq, value), boot: tracked.boot === bootId ? tracked.boot : '' }\n    : { seq: value, boot: bootId }\n}\n\nfunction dispatch(event: RealtimeEvent): void {\n  const isPresence = event.type === 'presence.changed'\n  if (isPresence && event.topic) presence.set(event.topic, event)\n  for (const listener of [...listeners]) {\n    if (isPresence && !listener.presence) continue\n    if (event.type === 'resync' || (event.topic && listener.topics().includes(event.topic))) {\n      listener.handler(event)\n    }\n  }\n}\n\nfunction close(): void {\n  source?.close()\n  source = null\n  sourceTopics = ''\n  presence.clear()\n  streamCursor = null\n  connected.value = false\n}\n\nfunction open(topics: string): void {\n  const cursor = tracked && [...listeners].every(listener => listener.cursor) ? tracked : null\n  const query = cursor ? `&since=${cursor.seq}&boot=${encodeURIComponent(cursor.boot)}` : ''\n  const stream = new EventSource(`${EVENTS_URL}?topics=${encodeURIComponent(topics)}${query}`)\n  source = stream\n  sourceTopics = topics\n  streamCursor = cursor\n  stream.onopen = () => {\n    connected.value = true\n    // The server subscribes only now: a write between a caller's REST load (or\n    // the close of the previous stream) and this point sent no event. With a\n    // cursor the server sends `resync` when needed; otherwise every caller refetches.\n    // A caller that did not opt in may have joined while the stream connected.\n    if (!cursor || ![...listeners].every(listener => listener.cursor)) dispatch(RESYNC)\n    failures = 0\n  }\n  stream.onmessage = (message) => {\n    dispatch(JSON.parse(message.data) as RealtimeEvent)\n  }\n  stream.onerror = () => {\n    // EventSource retries a dropped connection itself but gives up after an\n    // HTTP error, so one backoff path handles both.\n    if (source !== stream) return\n    close()\n    // A topic change during the wait does not shorten it: the retry reads the topics when it runs.\n    if (syncTimer !== null) clearTimeout(syncTimer)\n    syncTimer = null\n    retryTimer = setTimeout(() => {\n      retryTimer = null\n      sync()\n    }, Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** failures))\n    failures += 1\n  }\n}\n\nfunction sync(): void {\n  syncTimer = null\n  const topics = [...new Set([...listeners].flatMap(listener => listener.topics()))].sort().join(',')\n  if (source && topics === sourceTopics) return\n  close()\n  if (topics) open(topics)\n}\n\nfunction schedule(): void {\n  if (retryTimer !== null) return\n  if (syncTimer !== null) clearTimeout(syncTimer)\n  syncTimer = setTimeout(sync, TOPIC_DEBOUNCE_MS)\n}\n\n/**\n * Subscribe to topics of the platform's realtime stream.\n *\n * Every caller in a tab shares one `EventSource`, opened on the union of\n * their topics and reopened when that union changes. `handler` receives the\n * write events of the caller's own topics (not `presence.changed`, which goes\n * to `usePresence`) plus every `resync`: one comes from the\n * server when this tab fell behind, and one follows each open of the stream:\n * the first open, each reconnect (backoff from 1 s to 30 s) and each reopen for\n * a changed topic union. With `options.cursor` set by every caller, the open\n * sends no `resync` of its own; the server sends one when a topic changed since\n * the oldest recorded REST load. On `resync`, refetch. The union of all callers' topics\n * in a tab may hold at most 50 topics; the platform refuses a larger stream.\n *\n * The stream authenticates with the session cookie, so it works in the\n * platform and in plugin frontends served by it. It exists only when the\n * platform's `realtime` feature flag is on; check that flag first.\n *\n * A plugin topic reaches a caller whose role may use the plugin; an\n * experiment plugin topic also needs a caller who may view the experiment.\n *\n * @example\n * useRealtime(() => [`experiment:${id.value}`], () => refetch())\n * @example\n * useRealtime(['plugin:drp'], (event) => {\n *   if (event.type === 'drp.run.progress') progress.value = event.payload as RunProgress\n * })\n */\nexport function useRealtime(\n  topics: MaybeRefOrGetter<string[]>,\n  handler: RealtimeHandler,\n  options: UseRealtimeOptions = {},\n): UseRealtimeReturn {\n  return subscribeRealtime(topics, handler, false, options.cursor ?? false)\n}\n\n/** The last `presence.changed` of `topic` while the open stream views it (for `usePresence`). */\nexport function currentPresence(topic: string): RealtimeEvent | undefined {\n  return presence.get(topic)\n}\n\n/** `useRealtime`, and with `withPresence` also the `presence.changed` events (for `usePresence`). */\nexport function subscribeRealtime(\n  topics: MaybeRefOrGetter<string[]>,\n  handler: RealtimeHandler,\n  withPresence: boolean,\n  cursor = false,\n): UseRealtimeReturn {\n  // A presence caller does not refetch on resync, so it never needs the client-side one.\n  const listener: Listener = { topics: () => toValue(topics), handler, presence: withPresence, cursor: cursor || withPresence }\n  listeners.add(listener)\n  const stopWatch = watch(() => listener.topics().join(','), () => schedule())\n  schedule()\n\n  function stop(): void {\n    stopWatch()\n    if (listeners.delete(listener)) schedule()\n  }\n\n  if (getCurrentScope()) onScopeDispose(stop)\n  return { connected: readonly(connected), stop }\n}\n"],"mappings":"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"}

package/dist/{useRequest-CXyPw3eh.js → useRequest-CcgNnT2V.js}

@@ -1,4 +1,4 @@
-import { r as readErrorMessage } from "./experiment-DyO54FQB.js";
+import { r as readErrorMessage } from "./experiment-CNMuOEGc.js";
 import { ref } from "vue";
 //#region src/composables/useRequest.ts
 /** Loading, error and timestamp state for one request at a time; `run()` drives it. */
@@ -73,4 +73,4 @@ function useRequest(defaultErrorMessage = "Request failed.") {
 //#endregion
 export { useRequest as t };
 
-//# sourceMappingURL=useRequest-CXyPw3eh.js.map
+//# sourceMappingURL=useRequest-CcgNnT2V.js.map

package/dist/{useRequest-CXyPw3eh.js.map → useRequest-CcgNnT2V.js.map}

@@ -1 +1 @@
-{"version":3,"file":"useRequest-CXyPw3eh.js","names":[],"sources":["../src/composables/useRequest.ts"],"sourcesContent":["import { ref, type Ref } from 'vue'\nimport { readErrorMessage as readSharedErrorMessage } from '../utils/errors'\n\nexport type RequestKind = 'load' | 'save' | 'run'\n\n/**\n * The unit of work `run()` drives.\n *\n * It receives an `AbortSignal` that fires when the run is superseded by a\n * newer `run()` or by `cancel()`. Zero-argument operations stay valid and\n * simply ignore it.\n */\nexport type RequestOperation<T> = (signal: AbortSignal) => Promise<T>\n\nexport interface RequestRunOptions {\n  /** Which timestamp a successful run moves: `lastLoadedAt`, `lastSavedAt` or `lastRunAt`. */\n  kind?: RequestKind\n  errorMessage?: string\n  /**\n   * Abort the previously started run when this one starts. Default `true`;\n   * pass `false` to let overlapping runs finish their own work (the stale\n   * guard on shared state still applies either way).\n   */\n  abortPrevious?: boolean\n  /** Caller-owned signal; aborting it aborts this run's signal too. */\n  signal?: AbortSignal\n}\n\nexport interface UseRequestReturn {\n  /** Whether a request is in progress. */\n  isLoading: Ref<boolean>\n  /** Message from the last failed request, or null. */\n  error: Ref<string | null>\n  /** Timestamp of the last successful load operation, or null. */\n  lastLoadedAt: Ref<Date | null>\n  /** Timestamp of the last successful save operation, or null. */\n  lastSavedAt: Ref<Date | null>\n  /** Timestamp of the last successful run operation, or null. */\n  lastRunAt: Ref<Date | null>\n  /** Clear the current error without changing loading or timestamps. */\n  clearError: () => void\n  /** Convert thrown values into a developer-facing error message. */\n  readErrorMessage: (value: unknown, fallback?: string) => string\n  /** Store and return a normalized error message. */\n  setError: (value: unknown, fallback?: string) => string\n  /**\n   * Run a request with shared loading/error handling and optional sync marking.\n   *\n   * ## Stale-response semantics\n   *\n   * Every call takes a monotonically increasing token. Starting a run\n   * supersedes any run started before it, and a superseded run writes **no**\n   * shared state when it finally settles: it does not clear `isLoading`, does not\n   * set `error`, and does not move `lastLoadedAt` / `lastSavedAt` / `lastRunAt`.\n   * Only the newest run owns those.\n   *\n   * The caller's own promise is untouched by the guard — a superseded run still\n   * resolves with its value or rejects with its own error, exactly as the\n   * operation did. The guard never invents a rejection, so a caller awaiting\n   * `run()` never sees a \"superseded\" error it did not cause.\n   *\n   * The operation additionally receives an `AbortSignal` that fires when its\n   * run is superseded or `cancel()` is called, so an operation that forwards\n   * the signal (`fetch(url, { signal })`) stops work instead of racing.\n   */\n  run: <T>(operation: RequestOperation<T>, options?: RequestRunOptions) => Promise<T>\n  /**\n   * Abort the in-flight run and drop `isLoading`. The aborted run's completion\n   * is treated as stale and writes no state.\n   */\n  cancel: () => void\n}\n\n/** Loading, error and timestamp state for one request at a time; `run()` drives it. */\nexport function useRequest(\n  defaultErrorMessage = 'Request failed.',\n): UseRequestReturn {\n  const isLoading = ref(false)\n  const error = ref<string | null>(null)\n  const lastLoadedAt = ref<Date | null>(null)\n  const lastSavedAt = ref<Date | null>(null)\n  const lastRunAt = ref<Date | null>(null)\n\n  function clearError(): void {\n    error.value = null\n  }\n\n  function readErrorMessage(value: unknown, fallback = defaultErrorMessage): string {\n    return readSharedErrorMessage(value, fallback)\n  }\n\n  function setError(value: unknown, fallback?: string): string {\n    const message = readErrorMessage(value, fallback)\n    error.value = message\n    return message\n  }\n\n  // Monotonic token guarding every write to the shared loading/error/timestamp\n  // state. Overlapping runs settle in any order, and a superseded one must not\n  // clear a newer run's loading flag or overwrite its error.\n  let runToken = 0\n  let activeController: AbortController | null = null\n\n  function cancel(): void {\n    runToken += 1\n    activeController?.abort()\n    activeController = null\n    isLoading.value = false\n  }\n\n  async function run<T>(\n    operation: RequestOperation<T>,\n    options: RequestRunOptions = {},\n  ): Promise<T> {\n    if (options.abortPrevious !== false) {\n      activeController?.abort()\n    }\n\n    const token = (runToken += 1)\n    const controller = new AbortController()\n    activeController = controller\n\n    const callerSignal = options.signal\n    if (callerSignal) {\n      if (callerSignal.aborted) controller.abort(callerSignal.reason)\n      else callerSignal.addEventListener(\n        'abort',\n        () => controller.abort(callerSignal.reason),\n        { once: true },\n      )\n    }\n\n    const isCurrent = (): boolean => token === runToken\n\n    isLoading.value = true\n    clearError()\n    try {\n      const response = await operation(controller.signal)\n      if (isCurrent() && options.kind) {\n        const settledAt = new Date()\n        if (options.kind === 'load') lastLoadedAt.value = settledAt\n        else if (options.kind === 'save') lastSavedAt.value = settledAt\n        else lastRunAt.value = settledAt\n      }\n      return response\n    } catch (err) {\n      if (isCurrent()) {\n        setError(err, options.errorMessage)\n      }\n      throw err\n    } finally {\n      if (isCurrent()) {\n        isLoading.value = false\n      }\n      if (activeController === controller) {\n        activeController = null\n      }\n    }\n  }\n\n  return {\n    isLoading,\n    error,\n    lastLoadedAt,\n    lastSavedAt,\n    lastRunAt,\n    clearError,\n    readErrorMessage,\n    setError,\n    run,\n    cancel,\n  }\n}\n"],"mappings":";;;;AA0EA,SAAgB,WACd,sBAAsB,mBACJ;CAClB,MAAM,YAAY,IAAI,KAAK;CAC3B,MAAM,QAAQ,IAAmB,IAAI;CACrC,MAAM,eAAe,IAAiB,IAAI;CAC1C,MAAM,cAAc,IAAiB,IAAI;CACzC,MAAM,YAAY,IAAiB,IAAI;CAEvC,SAAS,aAAmB;EAC1B,MAAM,QAAQ;CAChB;CAEA,SAAS,mBAAiB,OAAgB,WAAW,qBAA6B;EAChF,OAAO,iBAAuB,OAAO,QAAQ;CAC/C;CAEA,SAAS,SAAS,OAAgB,UAA2B;EAC3D,MAAM,UAAU,mBAAiB,OAAO,QAAQ;EAChD,MAAM,QAAQ;EACd,OAAO;CACT;CAKA,IAAI,WAAW;CACf,IAAI,mBAA2C;CAE/C,SAAS,SAAe;EACtB,YAAY;EACZ,kBAAkB,MAAM;EACxB,mBAAmB;EACnB,UAAU,QAAQ;CACpB;CAEA,eAAe,IACb,WACA,UAA6B,CAAC,GAClB;EACZ,IAAI,QAAQ,kBAAkB,OAC5B,kBAAkB,MAAM;EAG1B,MAAM,QAAS,YAAY;EAC3B,MAAM,aAAa,IAAI,gBAAgB;EACvC,mBAAmB;EAEnB,MAAM,eAAe,QAAQ;EAC7B,IAAI,cAAc;GAChB,IAAI,aAAa,SAAS,WAAW,MAAM,aAAa,MAAM;QACzD,aAAa,iBAChB,eACM,WAAW,MAAM,aAAa,MAAM,GAC1C,EAAE,MAAM,KAAK,CACf;EACF;EAEA,MAAM,kBAA2B,UAAU;EAE3C,UAAU,QAAQ;EAClB,WAAW;EACX,IAAI;GACF,MAAM,WAAW,MAAM,UAAU,WAAW,MAAM;GAClD,IAAI,UAAU,KAAK,QAAQ,MAAM;IAC/B,MAAM,4BAAY,IAAI,KAAK;IAC3B,IAAI,QAAQ,SAAS,QAAQ,aAAa,QAAQ;SAC7C,IAAI,QAAQ,SAAS,QAAQ,YAAY,QAAQ;SACjD,UAAU,QAAQ;GACzB;GACA,OAAO;EACT,SAAS,KAAK;GACZ,IAAI,UAAU,GACZ,SAAS,KAAK,QAAQ,YAAY;GAEpC,MAAM;EACR,UAAU;GACR,IAAI,UAAU,GACZ,UAAU,QAAQ;GAEpB,IAAI,qBAAqB,YACvB,mBAAmB;EAEvB;CACF;CAEA,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA,kBAAA;EACA;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"useRequest-CcgNnT2V.js","names":[],"sources":["../src/composables/useRequest.ts"],"sourcesContent":["import { ref, type Ref } from 'vue'\nimport { readErrorMessage as readSharedErrorMessage } from '../utils/errors'\n\nexport type RequestKind = 'load' | 'save' | 'run'\n\n/**\n * The unit of work `run()` drives.\n *\n * It receives an `AbortSignal` that fires when the run is superseded by a\n * newer `run()` or by `cancel()`. Zero-argument operations stay valid and\n * simply ignore it.\n */\nexport type RequestOperation<T> = (signal: AbortSignal) => Promise<T>\n\nexport interface RequestRunOptions {\n  /** Which timestamp a successful run moves: `lastLoadedAt`, `lastSavedAt` or `lastRunAt`. */\n  kind?: RequestKind\n  errorMessage?: string\n  /**\n   * Abort the previously started run when this one starts. Default `true`;\n   * pass `false` to let overlapping runs finish their own work (the stale\n   * guard on shared state still applies either way).\n   */\n  abortPrevious?: boolean\n  /** Caller-owned signal; aborting it aborts this run's signal too. */\n  signal?: AbortSignal\n}\n\nexport interface UseRequestReturn {\n  /** Whether a request is in progress. */\n  isLoading: Ref<boolean>\n  /** Message from the last failed request, or null. */\n  error: Ref<string | null>\n  /** Timestamp of the last successful load operation, or null. */\n  lastLoadedAt: Ref<Date | null>\n  /** Timestamp of the last successful save operation, or null. */\n  lastSavedAt: Ref<Date | null>\n  /** Timestamp of the last successful run operation, or null. */\n  lastRunAt: Ref<Date | null>\n  /** Clear the current error without changing loading or timestamps. */\n  clearError: () => void\n  /** Convert thrown values into a developer-facing error message. */\n  readErrorMessage: (value: unknown, fallback?: string) => string\n  /** Store and return a normalized error message. */\n  setError: (value: unknown, fallback?: string) => string\n  /**\n   * Run a request with shared loading/error handling and optional sync marking.\n   *\n   * ## Stale-response semantics\n   *\n   * Every call takes a monotonically increasing token. Starting a run\n   * supersedes any run started before it, and a superseded run writes **no**\n   * shared state when it finally settles: it does not clear `isLoading`, does not\n   * set `error`, and does not move `lastLoadedAt` / `lastSavedAt` / `lastRunAt`.\n   * Only the newest run owns those.\n   *\n   * The caller's own promise is untouched by the guard — a superseded run still\n   * resolves with its value or rejects with its own error, exactly as the\n   * operation did. The guard never invents a rejection, so a caller awaiting\n   * `run()` never sees a \"superseded\" error it did not cause.\n   *\n   * The operation additionally receives an `AbortSignal` that fires when its\n   * run is superseded or `cancel()` is called, so an operation that forwards\n   * the signal (`fetch(url, { signal })`) stops work instead of racing.\n   */\n  run: <T>(operation: RequestOperation<T>, options?: RequestRunOptions) => Promise<T>\n  /**\n   * Abort the in-flight run and drop `isLoading`. The aborted run's completion\n   * is treated as stale and writes no state.\n   */\n  cancel: () => void\n}\n\n/** Loading, error and timestamp state for one request at a time; `run()` drives it. */\nexport function useRequest(\n  defaultErrorMessage = 'Request failed.',\n): UseRequestReturn {\n  const isLoading = ref(false)\n  const error = ref<string | null>(null)\n  const lastLoadedAt = ref<Date | null>(null)\n  const lastSavedAt = ref<Date | null>(null)\n  const lastRunAt = ref<Date | null>(null)\n\n  function clearError(): void {\n    error.value = null\n  }\n\n  function readErrorMessage(value: unknown, fallback = defaultErrorMessage): string {\n    return readSharedErrorMessage(value, fallback)\n  }\n\n  function setError(value: unknown, fallback?: string): string {\n    const message = readErrorMessage(value, fallback)\n    error.value = message\n    return message\n  }\n\n  // Monotonic token guarding every write to the shared loading/error/timestamp\n  // state. Overlapping runs settle in any order, and a superseded one must not\n  // clear a newer run's loading flag or overwrite its error.\n  let runToken = 0\n  let activeController: AbortController | null = null\n\n  function cancel(): void {\n    runToken += 1\n    activeController?.abort()\n    activeController = null\n    isLoading.value = false\n  }\n\n  async function run<T>(\n    operation: RequestOperation<T>,\n    options: RequestRunOptions = {},\n  ): Promise<T> {\n    if (options.abortPrevious !== false) {\n      activeController?.abort()\n    }\n\n    const token = (runToken += 1)\n    const controller = new AbortController()\n    activeController = controller\n\n    const callerSignal = options.signal\n    if (callerSignal) {\n      if (callerSignal.aborted) controller.abort(callerSignal.reason)\n      else callerSignal.addEventListener(\n        'abort',\n        () => controller.abort(callerSignal.reason),\n        { once: true },\n      )\n    }\n\n    const isCurrent = (): boolean => token === runToken\n\n    isLoading.value = true\n    clearError()\n    try {\n      const response = await operation(controller.signal)\n      if (isCurrent() && options.kind) {\n        const settledAt = new Date()\n        if (options.kind === 'load') lastLoadedAt.value = settledAt\n        else if (options.kind === 'save') lastSavedAt.value = settledAt\n        else lastRunAt.value = settledAt\n      }\n      return response\n    } catch (err) {\n      if (isCurrent()) {\n        setError(err, options.errorMessage)\n      }\n      throw err\n    } finally {\n      if (isCurrent()) {\n        isLoading.value = false\n      }\n      if (activeController === controller) {\n        activeController = null\n      }\n    }\n  }\n\n  return {\n    isLoading,\n    error,\n    lastLoadedAt,\n    lastSavedAt,\n    lastRunAt,\n    clearError,\n    readErrorMessage,\n    setError,\n    run,\n    cancel,\n  }\n}\n"],"mappings":";;;;AA0EA,SAAgB,WACd,sBAAsB,mBACJ;CAClB,MAAM,YAAY,IAAI,KAAK;CAC3B,MAAM,QAAQ,IAAmB,IAAI;CACrC,MAAM,eAAe,IAAiB,IAAI;CAC1C,MAAM,cAAc,IAAiB,IAAI;CACzC,MAAM,YAAY,IAAiB,IAAI;CAEvC,SAAS,aAAmB;EAC1B,MAAM,QAAQ;CAChB;CAEA,SAAS,mBAAiB,OAAgB,WAAW,qBAA6B;EAChF,OAAO,iBAAuB,OAAO,QAAQ;CAC/C;CAEA,SAAS,SAAS,OAAgB,UAA2B;EAC3D,MAAM,UAAU,mBAAiB,OAAO,QAAQ;EAChD,MAAM,QAAQ;EACd,OAAO;CACT;CAKA,IAAI,WAAW;CACf,IAAI,mBAA2C;CAE/C,SAAS,SAAe;EACtB,YAAY;EACZ,kBAAkB,MAAM;EACxB,mBAAmB;EACnB,UAAU,QAAQ;CACpB;CAEA,eAAe,IACb,WACA,UAA6B,CAAC,GAClB;EACZ,IAAI,QAAQ,kBAAkB,OAC5B,kBAAkB,MAAM;EAG1B,MAAM,QAAS,YAAY;EAC3B,MAAM,aAAa,IAAI,gBAAgB;EACvC,mBAAmB;EAEnB,MAAM,eAAe,QAAQ;EAC7B,IAAI,cAAc;GAChB,IAAI,aAAa,SAAS,WAAW,MAAM,aAAa,MAAM;QACzD,aAAa,iBAChB,eACM,WAAW,MAAM,aAAa,MAAM,GAC1C,EAAE,MAAM,KAAK,CACf;EACF;EAEA,MAAM,kBAA2B,UAAU;EAE3C,UAAU,QAAQ;EAClB,WAAW;EACX,IAAI;GACF,MAAM,WAAW,MAAM,UAAU,WAAW,MAAM;GAClD,IAAI,UAAU,KAAK,QAAQ,MAAM;IAC/B,MAAM,4BAAY,IAAI,KAAK;IAC3B,IAAI,QAAQ,SAAS,QAAQ,aAAa,QAAQ;SAC7C,IAAI,QAAQ,SAAS,QAAQ,YAAY,QAAQ;SACjD,UAAU,QAAQ;GACzB;GACA,OAAO;EACT,SAAS,KAAK;GACZ,IAAI,UAAU,GACZ,SAAS,KAAK,QAAQ,YAAY;GAEpC,MAAM;EACR,UAAU;GACR,IAAI,UAAU,GACZ,UAAU,QAAQ;GAEpB,IAAI,qBAAqB,YACvB,mBAAmB;EAEvB;CACF;CAEA,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA,kBAAA;EACA;EACA;EACA;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.5.0-beta.15",
+  "version": "1.5.0-beta.17",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec Infrastructure for Next-generation Toolkits.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/components/AutoGroupModal.adapter.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
   candidateColumns,
-  engineFieldsToCards,
   engineGroupsToRail,
   engineSchemasToCards,
   engineToQcRoute,
@@ -56,36 +55,6 @@ describe('candidateColumns', () => {
   })
 })
 
-describe('engineFieldsToCards', () => {
-  it('should build cards with role label, joined values, rep flag, and aligned enabled state', () => {
-    const columns = [
-      col({ index: 0, name: 'Condition', role: 'factor', uniqueValues: ['Control', 'Treatment'] }),
-      col({ index: 1, name: 'Replicate', role: 'replicate', uniqueValues: ['Rep1', 'Rep2'] }),
-    ]
-    const { fields, enabled } = engineFieldsToCards(columns, [0])
-    expect(fields).toEqual([
-      { key: 'Condition', role: 'Factor', vals: 'Control, Treatment', rep: false },
-      { key: 'Replicate', role: 'Replicate', vals: 'Rep1, Rep2', rep: true },
-    ])
-    expect(enabled).toEqual([true, false])
-  })
-
-  it('should prefer displayName over name when present', () => {
-    const columns = [col({ index: 0, name: 'c0', displayName: 'Dose', role: 'factor', uniqueValues: ['Low'] })]
-    expect(engineFieldsToCards(columns, []).fields[0].key).toBe('Dose')
-  })
-
-  it('should map each card to its 1-based hierarchy layer from the groupBy order', () => {
-    const columns = [
-      col({ index: 0, name: 'Tissue', role: 'factor' }),
-      col({ index: 1, name: 'Timepoint', role: 'factor' }),
-      col({ index: 2, name: 'Rep', role: 'replicate' }),
-    ]
-    // Layer 1 = Timepoint (column 1), layer 2 = Tissue (column 0); Rep is off.
-    expect(engineFieldsToCards(columns, [1, 0]).layers).toEqual([2, 1, null])
-  })
-})
-
 describe('engineSchemasToCards', () => {
   it('should expose enabled fields from another schema when the active schema has none enabled', () => {
     const schemas: Record<string, ClassSchema> = {

package/src/__tests__/composables/usePresence.test.ts

@@ -35,6 +35,11 @@ async function loadBoth() {
   return { usePresence, useRealtime: (await import('../../composables/useRealtime')).useRealtime }
 }
 
+async function loadPresenceAndTracker() {
+  const usePresence = await loadUsePresence()
+  return { usePresence, noteEventSeq: (await import('../../composables/useRealtime')).noteEventSeq }
+}
+
 const alice = { user_id: '7', activity: 'editing' }
 
 describe('usePresence', () => {
@@ -123,6 +128,22 @@ describe('usePresence', () => {
     scope.stop()
   })
 
+  it('should report the activity when the stream opens with the cursor and sends no resync', async () => {
+    const { usePresence, noteEventSeq } = await loadPresenceAndTracker()
+    const scope = effectScope()
+    scope.run(() => usePresence('experiment:4', 'editing'))
+    noteEventSeq('7', 'boot-a')
+    vi.runAllTimers()
+
+    latest().onopen?.()
+
+    expect([new URL(latest().url, 'http://test').searchParams.get('since'), post.mock.calls]).toEqual([
+      '7',
+      [['/presence/activity', { topic: 'experiment:4', activity: 'editing' }]],
+    ])
+    scope.stop()
+  })
+
   it('should show the viewers and report the activity when the open stream already views the topic', async () => {
     const { usePresence, useRealtime } = await loadBoth()
     const scope = effectScope()

package/src/__tests__/composables/useRealtime.test.ts

@@ -1,4 +1,4 @@
-import { effectScope, ref } from 'vue'
+import { effectScope, nextTick, ref } from 'vue'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 class FakeEventSource {
@@ -23,12 +23,22 @@ class FakeEventSource {
   get topics(): string {
     return new URL(this.url, 'http://test').searchParams.get('topics') ?? ''
   }
+
+  get cursor(): [string | null, string | null] {
+    const params = new URL(this.url, 'http://test').searchParams
+    return [params.get('since'), params.get('boot')]
+  }
 }
 
 function live(): FakeEventSource[] {
   return FakeEventSource.instances.filter(source => !source.closed)
 }
 
+async function loadRealtime() {
+  vi.resetModules()
+  return await import('../../composables/useRealtime')
+}
+
 async function loadUseRealtime() {
   vi.resetModules()
   return (await import('../../composables/useRealtime')).useRealtime
@@ -193,4 +203,219 @@ describe('useRealtime', () => {
 
     expect([FakeEventSource.instances.length, live().length]).toEqual([1, 0])
   })
+
+  describe('with the event cursor', () => {
+    it('should record the sequence of a createClient response', async () => {
+      const { useRealtime } = await loadRealtime()
+      const { default: axios } = await import('axios')
+      const { createPinia, setActivePinia } = await import('pinia')
+      const { createClient } = await import('../../composables/createClient')
+      setActivePinia(createPinia())
+      const adapter = axios.defaults.adapter
+      axios.defaults.adapter = async config => ({
+        data: {}, status: 200, statusText: 'OK', config,
+        headers: { 'x-mint-event-seq': '7', 'x-mint-boot-id': 'boot-a' },
+      })
+      const client = createClient(
+        {
+          schemaVersion: 2,
+          plugin: { routesPrefix: '/p', apiPrefix: '/api/p', type: 'analysis' },
+          settings: { modelName: 'Settings', valueSchema: { type: 'object', properties: {} }, formSchema: { groups: [] } },
+          endpoints: [],
+          hash: 'sha256:test',
+        },
+        { endpoints: { health: { method: 'get', path: '/health' } } },
+      )
+      const scope = effectScope()
+      scope.run(() => useRealtime(['plugin:p'], vi.fn(), { cursor: true }))
+
+      await client.health()
+      axios.defaults.adapter = adapter
+      vi.runAllTimers()
+
+      expect(FakeEventSource.instances[0].cursor).toEqual(['7', 'boot-a'])
+      scope.stop()
+    })
+
+    it('should open with since and boot and send no resync of its own when every caller opts in', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const handler = vi.fn()
+      const scope = effectScope()
+      scope.run(() => {
+        useRealtime(['experiments'], handler, { cursor: true })
+        useRealtime(['experiment:1'], handler, { cursor: true })
+      })
+      noteEventSeq('9', 'boot-a')
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      expect([FakeEventSource.instances[0].cursor, handler.mock.calls]).toEqual([['7', 'boot-a'], []])
+      scope.stop()
+    })
+
+    it('should keep the open resync when one caller does not opt in', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const handler = vi.fn()
+      const scope = effectScope()
+      scope.run(() => {
+        useRealtime(['experiments'], handler, { cursor: true })
+        useRealtime(['experiment:1'], vi.fn())
+      })
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      expect([FakeEventSource.instances[0].cursor, handler.mock.calls]).toEqual([[null, null], [[{ type: 'resync' }]]])
+      scope.stop()
+    })
+
+    it('should keep the open resync when no response recorded a cursor', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const handler = vi.fn()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], handler, { cursor: true }))
+      noteEventSeq(null, null)
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      expect([FakeEventSource.instances[0].cursor, handler.mock.calls]).toEqual([[null, null], [[{ type: 'resync' }]]])
+      scope.stop()
+    })
+
+    it('should deliver a resync the server sends on a cursor stream', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const handler = vi.fn()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], handler, { cursor: true }))
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      live()[0].emit({ type: 'resync' })
+
+      expect(handler.mock.calls).toEqual([[{ type: 'resync' }]])
+      scope.stop()
+    })
+
+    it.each([
+      ['an older sequence', '6', 'boot-a', 1],
+      ['another boot', '9', 'boot-b', 1],
+      ['the same or a later sequence', '7', 'boot-a', 0],
+    ])('should resync for a late response with %s', async (_label, seq, boot, resyncs) => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const handler = vi.fn()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], handler, { cursor: true }))
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      noteEventSeq(seq, boot)
+
+      expect(handler.mock.calls.length).toBe(resyncs)
+      scope.stop()
+    })
+
+    it('should resync once when the responses of the refetch come from the new boot', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const handler = vi.fn()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], handler, { cursor: true }))
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      noteEventSeq('0', 'boot-b')
+      noteEventSeq('0', 'boot-b')
+
+      expect(handler.mock.calls.length).toBe(1)
+      scope.stop()
+    })
+
+    it('should send a boot that never matches once responses came from two processes', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], vi.fn(), { cursor: true }))
+      noteEventSeq('2', 'boot-b')
+      noteEventSeq('5000', 'boot-a')
+
+      vi.runAllTimers()
+
+      expect(FakeEventSource.instances[0].cursor).toEqual(['2', ''])
+      scope.stop()
+    })
+
+    it('should reopen after a failure with the cursor of the first load', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], vi.fn(), { cursor: true }))
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+      FakeEventSource.instances[0].onerror?.()
+      noteEventSeq('9', 'boot-a')
+
+      vi.advanceTimersByTime(1000)
+
+      expect(FakeEventSource.instances[1].cursor).toEqual(['7', 'boot-a'])
+      scope.stop()
+    })
+
+    it('should reopen with the cursor of a load made while the stream connected when a topic joins', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const later = ref<string[]>([])
+      const scope = effectScope()
+      scope.run(() => {
+        useRealtime(['experiments'], vi.fn(), { cursor: true })
+        useRealtime(later, vi.fn(), { cursor: true })
+      })
+      noteEventSeq('3', 'boot-a')
+      vi.runAllTimers()
+      noteEventSeq('5', 'boot-a')
+      FakeEventSource.instances[0].onopen?.()
+      noteEventSeq('20', 'boot-a')
+
+      later.value = ['project:2']
+      await nextTick()
+      vi.runAllTimers()
+
+      expect(FakeEventSource.instances[1].cursor).toEqual(['3', 'boot-a'])
+      scope.stop()
+    })
+
+    it('should keep the first cursor when the topics change before the server resync arrives', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const topics = ref(['experiments'])
+      const scope = effectScope()
+      scope.run(() => useRealtime(topics, vi.fn(), { cursor: true }))
+      noteEventSeq('3', 'boot-a')
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+      noteEventSeq('9', 'boot-a')
+
+      topics.value = ['experiments', 'project:2']
+      await nextTick()
+      vi.runAllTimers()
+
+      expect(FakeEventSource.instances[1].cursor).toEqual(['3', 'boot-a'])
+      scope.stop()
+    })
+
+    it('should resync on a cursor open when a caller without the option joined while it connected', async () => {
+      const { useRealtime, noteEventSeq } = await loadRealtime()
+      const late = vi.fn()
+      const scope = effectScope()
+      scope.run(() => useRealtime(['experiments'], vi.fn(), { cursor: true }))
+      noteEventSeq('7', 'boot-a')
+      vi.runAllTimers()
+
+      scope.run(() => useRealtime(['experiments'], late))
+      vi.runAllTimers()
+      FakeEventSource.instances[0].onopen?.()
+
+      expect([FakeEventSource.instances.length, late.mock.calls]).toEqual([1, [[{ type: 'resync' }]]])
+      scope.stop()
+    })
+  })
 })