@classytic/arc-next 0.15.0 → 0.16.0

package/dist/api.d.ts

@@ -114,9 +114,33 @@ interface BaseApiConfig {
 }
 declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   readonly entity: string;
-  readonly config: Required<Omit<BaseApiConfig, "client">>;
-  readonly baseUrl: string;
+  /**
+   * `basePath` stays OPTIONAL here — it holds the explicit per-instance
+   * override and nothing else. The resolved value is {@link basePath}, which is
+   * computed per read; baking it in would defeat the whole point (see below).
+   */
+  readonly config: Required<Omit<BaseApiConfig, "client" | "basePath">> & Pick<BaseApiConfig, "basePath">;
   private readonly requestFn;
+  /**
+   * Per-instance override → the deployment's declared prefix → `/api/v1`.
+   *
+   * The middle step is what lets a package construct its own API internally and
+   * still land on a host mounted elsewhere. Without it the only options were
+   * "every consumer passes `basePath`" — impossible for an instance a package
+   * owns — or "every host mounts at `/api/v1`".
+   *
+   * ## Why this is a GETTER and not resolved in the constructor
+   *
+   * `configureClient()` runs inside a `"use client"` provider, which is LATER
+   * than module evaluation. A package's API instance is created at import time,
+   * so a constructor-time read would capture `/api/v1` before the deployment
+   * ever declared `/api`, and the fallback would win permanently — producing a
+   * 404 that renders as an empty list, which is the failure this was meant to
+   * fix. An explicit `basePath` is unaffected either way.
+   */
+  get basePath(): string;
+  /** `{basePath}/{entity}` — the resource root every request is built from. */
+  get baseUrl(): string;
   constructor(entity: string, config?: BaseApiConfig);
   /** Merge per-instance headers into request options */
   private withHeaders;

package/dist/api.js

@@ -1,4 +1,4 @@
-import { createQueryString, handleApiRequest } from "./client.js";
+import { createQueryString, getBasePath, handleApiRequest } from "./client.js";
 import { STANDARD_RESERVED_PARAMS } from "@classytic/repo-core/query-parser";
 
 //#region src/api.ts
@@ -9,15 +9,43 @@ for (const verb of [
 ]) if (!STANDARD_RESERVED_PARAMS.has(verb)) throw new Error(`[arc-next] dispatch verb '${verb}' is not in repo-core STANDARD_RESERVED_PARAMS`);
 var BaseApi = class {
 	entity;
+	/**
+	* `basePath` stays OPTIONAL here — it holds the explicit per-instance
+	* override and nothing else. The resolved value is {@link basePath}, which is
+	* computed per read; baking it in would defeat the whole point (see below).
+	*/
 	config;
-	baseUrl;
 	requestFn;
+	/**
+	* Per-instance override → the deployment's declared prefix → `/api/v1`.
+	*
+	* The middle step is what lets a package construct its own API internally and
+	* still land on a host mounted elsewhere. Without it the only options were
+	* "every consumer passes `basePath`" — impossible for an instance a package
+	* owns — or "every host mounts at `/api/v1`".
+	*
+	* ## Why this is a GETTER and not resolved in the constructor
+	*
+	* `configureClient()` runs inside a `"use client"` provider, which is LATER
+	* than module evaluation. A package's API instance is created at import time,
+	* so a constructor-time read would capture `/api/v1` before the deployment
+	* ever declared `/api`, and the fallback would win permanently — producing a
+	* 404 that renders as an empty list, which is the failure this was meant to
+	* fix. An explicit `basePath` is unaffected either way.
+	*/
+	get basePath() {
+		return this.config.basePath ?? getBasePath() ?? "/api/v1";
+	}
+	/** `{basePath}/{entity}` — the resource root every request is built from. */
+	get baseUrl() {
+		return `${this.basePath}/${this.entity}`;
+	}
 	constructor(entity, config = {}) {
 		this.entity = entity;
 		const client = config.client;
 		this.requestFn = typeof client === "function" ? (method, endpoint, options) => client().request(method, endpoint, options) : client?.request ?? handleApiRequest;
 		this.config = {
-			basePath: config.basePath ?? "/api/v1",
+			...config.basePath !== void 0 ? { basePath: config.basePath } : {},
 			defaultParams: {
 				limit: 10,
 				page: 1,
@@ -26,7 +54,6 @@ var BaseApi = class {
 			cache: config.cache ?? "no-store",
 			headers: { ...config.headers || {} }
 		};
-		this.baseUrl = `${this.config.basePath}/${this.entity}`;
 	}
 	/** Merge per-instance headers into request options */
 	withHeaders(options) {

package/dist/client.d.ts

@@ -278,6 +278,23 @@ interface ClientEncryptionConfig {
 }
 interface ClientConfig {
   baseUrl: string;
+  /**
+   * Route prefix every API is mounted under, when it is not `/api/v1`.
+   *
+   * `BaseApi` defaults each instance to `/api/v1` and takes a per-instance
+   * `basePath` override. That covers an app's OWN api classes and nothing else:
+   * a package that constructs its own API internally — erp-shell's permission
+   * `platformApi`, an SDK preset — has no seam to be told, so on a host mounted
+   * anywhere but `/api/v1` it silently requests a URL that does not exist and
+   * the feature reads as "no data" rather than as a misconfiguration.
+   *
+   * Setting it here makes the mount point a property of the DEPLOYMENT, stated
+   * once, which is what it actually is. A per-instance `basePath` still wins,
+   * so nothing that already passes one changes.
+   *
+   * @example configureClient({ baseUrl, basePath: '/api' }) // host mounts at /api
+   */
+  basePath?: string;
   internalApiKey?: string;
   defaultHeaders?: Record<string, string>;
   /**
@@ -457,6 +474,15 @@ declare function configureClient(config: ClientConfig): void;
 declare function getAuthMode(): "bearer" | "cookie" | "header";
 /** Get the configured base URL. Returns empty string if not configured. */
 declare function getBaseUrl(): string;
+/**
+ * The deployment's route prefix, or `null` when it has not declared one.
+ *
+ * `null` rather than the `/api/v1` default on purpose: the default belongs to
+ * `BaseApi`, which is the one place that should own it. Returning it here would
+ * put the same literal in two files, and the next person to change one would
+ * have no way to know about the other.
+ */
+declare function getBasePath(): string | null;
 /** Whether auto-idempotency is enabled on the global client. */
 declare function isAutoIdempotency(): boolean;
 /**
@@ -1016,4 +1042,4 @@ declare const arc: {
   delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
 };
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, ServerClientConfig, StreamUrlProtocol, TextResponse, TierRequirement, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, ServerClientConfig, StreamUrlProtocol, TextResponse, TierRequirement, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBasePath, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };

package/dist/client.js

@@ -337,6 +337,17 @@ function getAuthMode() {
 function getBaseUrl() {
 	return clientConfig?.baseUrl ?? "";
 }
+/**
+* The deployment's route prefix, or `null` when it has not declared one.
+*
+* `null` rather than the `/api/v1` default on purpose: the default belongs to
+* `BaseApi`, which is the one place that should own it. Returning it here would
+* put the same literal in two files, and the next person to change one would
+* have no way to know about the other.
+*/
+function getBasePath() {
+	return clientConfig?.basePath ?? null;
+}
 /** Whether auto-idempotency is enabled on the global client. */
 function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
@@ -1276,4 +1287,4 @@ const arc = {
 };
 
 //#endregion
-export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBasePath, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };

package/dist/sse.d.ts

@@ -101,6 +101,22 @@ interface EventStreamOptions<TData = unknown> extends SubscribeToEventsOptions<T
    * high-volume streams that don't read it.
    */
   trackEventCount?: boolean;
+  /**
+   * Hold ONE connection per browser rather than one per tab. Default: true.
+   *
+   * Browsers allow ~6 concurrent connections per origin on HTTP/1.1, so a
+   * per-tab stream lets a user starve their own app with a handful of tabs, and
+   * multiplies every reconnect against one server-side limit. The elected tab
+   * connects and relays events and connection state over `BroadcastChannel`;
+   * followers apply both without a socket.
+   *
+   * React-only — {@link subscribeToEvents} stays a plain per-caller connection,
+   * because tab coordination is a browser lifecycle concern and that function is
+   * the Node-capable core.
+   *
+   * Set false for a stream that must be per-tab.
+   */
+  shareAcrossTabs?: boolean;
 }
 interface EventStreamResult<TData = unknown> {
   isConnected: boolean;

package/dist/sse.js

@@ -1,8 +1,9 @@
 "use client";
 
 import { ArcApiError, _getAuthErrorHandler, _runAuthRecovery, buildStreamUrl, getAuthMode } from "./client.js";
+import { useTabLeader } from "./tab-leader.js";
 import { useQueryClient } from "@tanstack/react-query";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 //#region src/sse.ts
 /**
@@ -31,7 +32,24 @@ function buildSseUrl(path, params = {}) {
 * `Range: bytes=0-0` for servers that 405 on HEAD. Either way, the body
 * is never read — only the status code matters.
 */
-async function probeForAuthFailure(url, retryOn403) {
+/** `Retry-After` is delta-seconds or an HTTP-date. Unparseable ⇒ no opinion. */
+function parseRetryAfter(value) {
+	if (!value) return void 0;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const at = Date.parse(value);
+	return Number.isNaN(at) ? void 0 : Math.max(0, at - Date.now());
+}
+/**
+* Learn WHY the stream failed, since `EventSource` will not say.
+*
+* 429 matters as much as 401 and fails worse: a rate-limited stream that
+* reconnects on the backoff schedule spends a token per attempt, so the window
+* never drains and the client locks itself out indefinitely. The probe is a
+* plain `fetch`, so unlike the stream it can read both the status and
+* `Retry-After`.
+*/
+async function probeConnectionFailure(url, retryOn403) {
 	try {
 		let res = await fetch(url, {
 			method: "HEAD",
@@ -42,11 +60,15 @@ async function probeForAuthFailure(url, retryOn403) {
 			credentials: "include",
 			headers: { Range: "bytes=0-0" }
 		});
-		if (res.status === 401) return "auth-failure";
-		if (retryOn403 && res.status === 403) return "auth-failure";
-		return "not-auth";
+		if (res.status === 401) return { kind: "auth-failure" };
+		if (retryOn403 && res.status === 403) return { kind: "auth-failure" };
+		if (res.status === 429) return {
+			kind: "rate-limited",
+			retryAfterMs: parseRetryAfter(res.headers.get("retry-after"))
+		};
+		return { kind: "not-auth" };
 	} catch {
-		return "not-auth";
+		return { kind: "not-auth" };
 	}
 }
 /**
@@ -129,11 +151,29 @@ function subscribeToEvents(options) {
 			connected = false;
 			options.onConnectionChange?.(false);
 			if (manualClose) return;
+			/**
+			* The probe runs whether or not an auth handler is registered.
+			*
+			* It was gated on `handler`, so a deployment with no `onAuthError` never
+			* learned WHY the stream failed and fell straight to backoff — including
+			* for 429, the one status where backing off on the wrong schedule is
+			* self-defeating rather than merely slow.
+			*/
 			const { handler, retryOn403, maxAuthRetries } = _getAuthErrorHandler();
-			if (handler && sseAuthRetries < maxAuthRetries) {
-				sseAuthRetries += 1;
-				probeForAuthFailure(buildUrl(), retryOn403).then(async (status) => {
-					if (status === "auth-failure") {
+			if (sseProbes < maxAuthRetries) {
+				sseProbes += 1;
+				if (handler) sseAuthRetries += 1;
+				probeConnectionFailure(buildUrl(), retryOn403).then(async ({ kind, retryAfterMs }) => {
+					if (kind === "rate-limited") {
+						/**
+						* Honour the server's own number. Falling back to a full window
+						* rather than the 3s-based curve: retrying inside the window
+						* cannot succeed and each attempt refills the bucket.
+						*/
+						scheduleReconnect(retryAfterMs ?? 6e4);
+						return;
+					}
+					if (kind === "auth-failure" && handler && sseAuthRetries <= maxAuthRetries) {
 						const { decision } = await _runAuthRecovery(handler, {
 							error: new ArcApiError("SSE pre-flight auth failure", {
 								status: 401,
@@ -163,15 +203,21 @@ function subscribeToEvents(options) {
 			scheduleReconnect();
 		};
 	};
-	/** Standard backoff-reconnect — shared between non-auth errors and skipped recoveries. */
-	const scheduleReconnect = () => {
+	/**
+	* Standard backoff-reconnect — shared between non-auth errors and skipped
+	* recoveries. `explicitDelayMs` overrides the curve when the SERVER stated a
+	* wait (`Retry-After`); its number beats any local guess.
+	*/
+	const scheduleReconnect = (explicitDelayMs) => {
 		if (reconnectAttempts < maxReconnectAttempts) {
 			reconnectAttempts += 1;
-			const delay = Math.min(reconnectDelay * 1.5 ** (reconnectAttempts - 1), 3e4);
+			const delay = explicitDelayMs ?? Math.min(reconnectDelay * 1.5 ** (reconnectAttempts - 1), 3e4);
 			reconnectTimer = setTimeout(connect, delay);
 		}
 	};
 	let sseAuthRetries = 0;
+	/** Probes attempted for THIS subscription — bounds the extra fetch per failure. */
+	let sseProbes = 0;
 	connect();
 	return {
 		close: () => {
@@ -214,7 +260,7 @@ function subscribeToEvents(options) {
 * });
 */
 function useEventStream(options) {
-	const { url, resource, path, enabled = true, trackLastEvent = true, trackEventCount = true } = options;
+	const { url, resource, path, enabled = true, trackLastEvent = true, trackEventCount = true, shareAcrossTabs = true } = options;
 	const queryClient = useQueryClient();
 	const [isConnected, setIsConnected] = useState(false);
 	const [lastEvent, setLastEvent] = useState(null);
@@ -230,12 +276,72 @@ function useEventStream(options) {
 	const eventTypesKey = JSON.stringify(options.eventTypes ?? null);
 	const patterns = useMemo(() => options.patterns, [patternsKey]);
 	const eventTypes = useMemo(() => options.eventTypes, [eventTypesKey]);
+	/**
+	* The single place an event is applied, whether it arrived over this tab's
+	* socket or was relayed by the leader. Two copies would drift.
+	*/
+	const applyEvent = useCallback((event) => {
+		if (trackLastEvent) setLastEvent(event);
+		if (trackEventCount) setEventCount((n) => n + 1);
+		onEventRef.current?.(event);
+		for (const key of invalidateKeysRef.current) queryClient.invalidateQueries({ queryKey: key });
+	}, [
+		queryClient,
+		trackLastEvent,
+		trackEventCount
+	]);
+	/**
+	* Stream identity shared by every tab pointing at it — the election key and
+	* the channel name. Derived from the ENDPOINT, not the built URL, so a
+	* per-tab token or org param cannot split one stream into several elections.
+	*/
+	const channelName = `arc-next.sse.${resource ?? path ?? url ?? "/events/stream"}`;
+	const isLeaderTab = useTabLeader({
+		key: channelName,
+		enabled: enabled && shareAcrossTabs
+	});
+	const connectedRef = useRef(false);
 	useEffect(() => {
 		if (!enabled) {
 			handleRef.current?.close();
 			handleRef.current = null;
 			return;
 		}
+		/**
+		* FOLLOWER — no socket. It mirrors the leader's events and connection
+		* state, so its cache, badge and polling decision stay correct at zero
+		* connection cost.
+		*/
+		if (shareAcrossTabs && !isLeaderTab) {
+			handleRef.current?.close();
+			handleRef.current = null;
+			if (typeof BroadcastChannel === "undefined") return;
+			const channel = new BroadcastChannel(channelName);
+			channel.onmessage = (ev) => {
+				const msg = ev.data;
+				if (msg?.kind === "event") applyEvent(msg.event);
+				else if (msg?.kind === "state") {
+					setIsConnected(msg.connected);
+					onConnectionChangeRef.current?.(msg.connected);
+				}
+			};
+			channel.postMessage({ kind: "hello" });
+			return () => {
+				channel.close();
+				setIsConnected(false);
+			};
+		}
+		let channel = null;
+		if (shareAcrossTabs && typeof BroadcastChannel !== "undefined") {
+			channel = new BroadcastChannel(channelName);
+			channel.onmessage = (ev) => {
+				if (ev.data?.kind !== "hello") return;
+				channel?.postMessage({
+					kind: "state",
+					connected: connectedRef.current
+				});
+			};
+		}
 		const handle = subscribeToEvents({
 			url,
 			resource,
@@ -246,20 +352,29 @@ function useEventStream(options) {
 			maxReconnectAttempts: options.maxReconnectAttempts,
 			withCredentials: options.withCredentials,
 			onConnectionChange: (c) => {
+				connectedRef.current = c;
 				setIsConnected(c);
 				onConnectionChangeRef.current?.(c);
+				channel?.postMessage({
+					kind: "state",
+					connected: c
+				});
 			},
 			onEvent: (event) => {
-				if (trackLastEvent) setLastEvent(event);
-				if (trackEventCount) setEventCount((n) => n + 1);
-				onEventRef.current?.(event);
-				for (const key of invalidateKeysRef.current) queryClient.invalidateQueries({ queryKey: key });
+				channel?.postMessage({
+					kind: "event",
+					event
+				});
+				applyEvent(event);
 			}
 		});
 		handleRef.current = handle;
 		return () => {
 			handle.close();
 			handleRef.current = null;
+			channel?.close();
+			channel = null;
+			connectedRef.current = false;
 		};
 	}, [
 		enabled,
@@ -273,7 +388,11 @@ function useEventStream(options) {
 		options.withCredentials,
 		trackLastEvent,
 		trackEventCount,
-		queryClient
+		queryClient,
+		shareAcrossTabs,
+		isLeaderTab,
+		channelName,
+		applyEvent
 	]);
 	return {
 		isConnected,

package/dist/tab-leader.d.ts

@@ -0,0 +1,14 @@
+//#region src/tab-leader.d.ts
+/**
+ * `true` in exactly one tab at a time (per `key`).
+ *
+ * When storage is unavailable every tab reports leader. That is deliberate: a
+ * degraded browser must not lose the feature entirely, and the server-side
+ * concurrency cap is the backstop for the duplicate connections it allows.
+ */
+declare function useTabLeader(options: {
+  key: string;
+  enabled?: boolean;
+}): boolean;
+//#endregion
+export { useTabLeader };

package/dist/tab-leader.js

@@ -0,0 +1,111 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+//#region src/tab-leader.ts
+/**
+* Elect ONE leader tab per browser, so a shared resource is held once.
+*
+* A browser allows only ~6 concurrent connections per origin on HTTP/1.1, so a
+* per-tab stream lets a user with several tabs starve their own app — and it
+* multiplies every reconnect against one server-side limit.
+*
+* Modelled on Odoo's `multi_tab_fallback_service` (addons/bus): the leader
+* writes a heartbeat on an interval, any tab may claim leadership once that
+* heartbeat goes stale, and a closing tab releases it immediately. localStorage
+* is the coordination channel because it is synchronous, origin-scoped and
+* present everywhere — a SharedWorker is tidier but absent in several browsers,
+* which is why Odoo keeps this path too.
+*/
+/** Leader refresh interval. Comfortably under STALE_MS so a live leader is never displaced. */
+const HEARTBEAT_MS = 1500;
+/** A heartbeat older than this means the holder is gone (crashed tab, killed process). */
+const STALE_MS = 5e3;
+/** How often a follower checks whether leadership is up for grabs. */
+const CHECK_MS = 2e3;
+function readRecord(key) {
+	try {
+		const raw = localStorage.getItem(key);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		return typeof parsed?.id === "string" && typeof parsed?.ts === "number" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function writeRecord(key, record) {
+	try {
+		localStorage.setItem(key, JSON.stringify(record));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* `true` in exactly one tab at a time (per `key`).
+*
+* When storage is unavailable every tab reports leader. That is deliberate: a
+* degraded browser must not lose the feature entirely, and the server-side
+* concurrency cap is the backstop for the duplicate connections it allows.
+*/
+function useTabLeader(options) {
+	const { key, enabled = true } = options;
+	const [isLeader, setIsLeader] = useState(false);
+	useEffect(() => {
+		if (!enabled || typeof window === "undefined" || typeof localStorage === "undefined") {
+			setIsLeader(false);
+			return;
+		}
+		const storageKey = `arc-next.leader.${key}`;
+		const tabId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+		let leading = false;
+		let timer = null;
+		const claimOrRenew = () => {
+			const now = Date.now();
+			const held = readRecord(storageKey);
+			const vacant = !held || now - held.ts > STALE_MS;
+			if (held?.id === tabId || vacant) {
+				/**
+				* Last write wins. Two tabs can claim a vacant slot in the same tick;
+				* the loser observes a foreign id on its next pass and steps down, so
+				* the overlap is bounded by one interval rather than persisting.
+				*/
+				if (writeRecord(storageKey, {
+					id: tabId,
+					ts: now
+				})) {
+					const won = readRecord(storageKey)?.id === tabId;
+					if (won !== leading) {
+						leading = won;
+						setIsLeader(won);
+					}
+				} else if (!leading) {
+					leading = true;
+					setIsLeader(true);
+				}
+			} else if (leading) {
+				leading = false;
+				setIsLeader(false);
+			}
+			timer = setTimeout(claimOrRenew, leading ? HEARTBEAT_MS : CHECK_MS);
+		};
+		/** Release immediately so a sibling promotes now rather than after STALE_MS. */
+		const release = () => {
+			if (!leading) return;
+			if (readRecord(storageKey)?.id === tabId) try {
+				localStorage.removeItem(storageKey);
+			} catch {}
+		};
+		claimOrRenew();
+		window.addEventListener("pagehide", release);
+		return () => {
+			if (timer) clearTimeout(timer);
+			release();
+			window.removeEventListener("pagehide", release);
+		};
+	}, [key, enabled]);
+	return isLeader;
+}
+
+//#endregion
+export { useTabLeader };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -78,6 +78,10 @@
       "types": "./dist/sse.d.ts",
       "default": "./dist/sse.js"
     },
+    "./tab-leader": {
+      "types": "./dist/tab-leader.d.ts",
+      "default": "./dist/tab-leader.js"
+    },
     "./ws": {
       "types": "./dist/ws.d.ts",
       "default": "./dist/ws.js"