@kontsedal/olas-cross-tab 0.0.1-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bohdan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @kontsedal/olas-cross-tab
+
+`BroadcastChannel`-backed cache sync for `@kontsedal/olas-core`. When one tab writes via `query.setData(...)` or `query.invalidate(...)`, every other tab of the same origin sees the same write — without re-fetching, without persistence, without a server round-trip. SPEC §13.2.
+
+This is the **in-memory** sibling to `@kontsedal/olas-persist`. Persistence mirrors *durable* state on the `storage` event; this mirrors the (much larger) in-memory query cache that never touches disk. Both are independently opt-in.
+
+## Install
+
+```bash
+pnpm add @kontsedal/olas-cross-tab @kontsedal/olas-core @preact/signals-core
+```
+
+## 30-second example
+
+```ts
+import { createRoot, defineController, defineQuery } from '@kontsedal/olas-core'
+import { crossTabPlugin } from '@kontsedal/olas-cross-tab'
+
+// Opt the query in. `queryId` is required — it routes inbound messages
+// across tabs without depending on the in-memory `Query` reference.
+const userQuery = defineQuery({
+  queryId: 'app/user/v1',
+  crossTab: true,
+  key: (id: string) => ['user', id],
+  fetcher: (_ctx, id: string) => fetch(`/api/user/${id}`).then((r) => r.json()),
+})
+
+const appController = defineController((ctx) => {
+  const user = ctx.use(userQuery, () => ['me' as string])
+  return { user }
+})
+
+const root = createRoot(appController, {
+  deps: {},
+  plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],
+})
+```
+
+Tab A calls `userQuery.setData('me', (prev) => ({ ...prev, name: 'New' }))` — Tab B's subscribers see the new value on the next signal flush. No fetch fires in Tab B.
+
+## API
+
+```ts
+function crossTabPlugin(options: CrossTabOptions): QueryClientPlugin
+
+type CrossTabOptions = {
+  channelName: string
+  onWarn?: (message: string, cause?: unknown) => void
+  channelFactory?: (name: string) => ChannelLike | undefined
+}
+```
+
+| Option | Default | What |
+|---|---|---|
+| `channelName` | required | Name of the `BroadcastChannel`. Include a version suffix (`my-app/v2`) for clean cross-deploy isolation — receivers from a different deploy with a different channel name simply don't see each other's traffic. |
+| `onWarn` | `console.warn` | Called on non-fatal conditions: `DataCloneError` while broadcasting (the data isn't structured-cloneable) or a malformed inbound message. |
+| `channelFactory` | `defaultChannelFactory` (wraps `BroadcastChannel`) | Override the channel constructor. Mainly for tests. Return `undefined` to disable cross-tab (the plugin becomes a no-op). |
+
+## How it works
+
+Every `setData` or `invalidate` on a `crossTab: true` query fires a `QueryClientPlugin` event (§13.2). This plugin posts the event onto a `BroadcastChannel`. Receiving tabs replay the write via the plugin api's `applyRemoteSetData` / `applyRemoteInvalidate` — both flagged `isRemote: true`, so the receiving tab's plugin doesn't echo back.
+
+```
+Tab A: query.setData(...) → QueryClient.setData → plugin.onSetData (isRemote: false)
+                                                        ↓
+                                                  channel.postMessage(msg)
+                                                        ↓
+                              ━━━━━━━━━━━━━━━━━━━ BroadcastChannel ━━━━━━━━━━━━━━━━━━━
+                                                        ↓
+Tab B: api.applyRemoteSetData(...) ← channel listener ← msg
+       QueryClient.setData → plugin.onSetData (isRemote: true) → no rebroadcast
+```
+
+### Echo prevention (three layers)
+
+1. **Sender-side:** the plugin skips outbound broadcasts when `SetDataEvent.isRemote === true` (the write was triggered by an inbound message).
+2. **Own-source drop:** receivers filter messages by `sourceId` — every plugin instance picks a random one at construction. If the transport echoes the message back, the sender ignores it.
+3. **`(sourceId, msgId)` dedup:** monotonic `msgId` per `sourceId` lets receivers drop out-of-order or duplicate messages.
+
+### Protocol versioning
+
+Messages carry `v: PROTOCOL_VERSION`. Receivers drop messages with a `v` they don't understand. Channel names themselves are user-supplied; for cross-deploy isolation, embed a version in your `channelName` (e.g. `'app/cache/v2'`).
+
+### Non-cloneable data
+
+`BroadcastChannel` uses structured clone. Cache data containing functions, class instances, or symbols throws `DataCloneError` at `postMessage`. The plugin catches the throw, calls `onWarn(...)`, and drops the message. **The sender's cache is unaffected** — only the cross-tab echo is lost.
+
+## Per-query opt-in
+
+Two fields on the spec gate cross-tab behavior:
+
+- **`queryId: string`** — required. Stable name routed across tabs. Don't auto-derive from `fetcher.name` (fragile under minification) or argument hashing.
+- **`crossTab: true`** — flips the per-query gate. Without it, the plugin doesn't broadcast (so module-internal queries don't leak).
+
+Setting `crossTab: true` without a `queryId` logs a one-time `console.warn` (dev only) and disables sync for that query.
+
+## SSR
+
+When `BroadcastChannel === undefined` (Node, older browsers) and no `channelFactory` override is supplied, `crossTabPlugin(...)` returns a no-op plugin. The root still constructs cleanly; cross-tab is just disabled. This means you can wire the plugin unconditionally in shared code paths.
+
+## Interaction with `@kontsedal/olas-persist`
+
+These two layers solve different problems:
+
+- `@kontsedal/olas-persist` mirrors **durable** state via `localStorage` + the `storage` event.
+- `@kontsedal/olas-cross-tab` mirrors the **in-memory** query cache via `BroadcastChannel`.
+
+You can combine them on the same logical entity, but it's redundant — `@kontsedal/olas-persist`'s cross-tab sync already covers the durable copy.
+
+## Limitations (v1)
+
+- **No infinite queries.** `defineInfiniteQuery` syncs are intentionally skipped — the page-array payload is too heavy to be a safe default. Plugin events fire with `kind: 'infinite'` for forward compatibility; this plugin filters them out.
+- **No structural diffs.** Every `setData` broadcasts the full post-update value. For chunky cache entries this is fine because `BroadcastChannel` is in-memory; for very large arrays it's a known cost.
+- **No pending-mutation arbitration.** If two tabs run optimistic mutations on the same entry concurrently, the last `setData` to arrive wins on both sides. Your mutation `onError` / `onSuccess` then re-syncs from the server, which restores convergence at the cost of a temporary divergence.
+- **Optimistic writes cross tabs.** `setData` events fire regardless of cause, so optimistic state (and any rollback) is visible cross-tab. If you need optimistic UI to stay local, gate the write yourself.
+
+## Further reading
+
+- [`../../.wiki/modules/cross-tab.md`](../../.wiki/modules/cross-tab.md)
+- SPEC §13.2 — Cross-tab in-memory cache sync.
+- SPEC §5.2 — Query definition (`queryId`, `crossTab`).
+- SPEC §20.8 — `RootOptions.plugins`.

package/dist/index.cjs

@@ -0,0 +1,199 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _kontsedal_olas_core = require("@kontsedal/olas-core");
+//#region src/channel.ts
+/**
+* Default factory: wraps the platform `BroadcastChannel`. Returns
+* `undefined` when `BroadcastChannel` is not defined (SSR / Node without
+* `--experimental-broadcastchannel`, older browsers).
+*/
+function defaultChannelFactory(name) {
+	if (typeof BroadcastChannel === "undefined") return void 0;
+	const ch = new BroadcastChannel(name);
+	return {
+		postMessage(data) {
+			ch.postMessage(data);
+		},
+		addEventListener(type, listener) {
+			ch.addEventListener(type, listener);
+		},
+		removeEventListener(type, listener) {
+			ch.removeEventListener(type, listener);
+		},
+		close() {
+			ch.close();
+		}
+	};
+}
+//#endregion
+//#region src/protocol.ts
+/**
+* Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.
+*
+* `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)
+* combine to make the three-layer echo prevention work:
+*
+* 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the
+*    write originated from `applyRemoteSetData`).
+* 2. Receiver filters its own `sourceId` (catches the case where the
+*    transport echoes the message back to the sender).
+* 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order
+*    messages from the same peer are dropped.
+*
+* Receivers also drop messages with a `v` they don't understand. The
+* channel name itself is user-supplied; consumers who want clean
+* cross-deploy isolation should embed a version in their `channelName`.
+*/
+const PROTOCOL_VERSION = 1;
+//#endregion
+//#region src/plugin.ts
+/**
+* Generate a unique-enough source id for a plugin instance. Combines
+* `Date.now()` with `Math.random()` — collisions across same-millisecond
+* tab-opens are negligible at one-decimal-place randomness, and even a
+* collision only loses dedup, not correctness.
+*/
+function makeSourceId() {
+	const rand = Math.random().toString(36).slice(2, 10);
+	return `${Date.now().toString(36)}-${rand}`;
+}
+const NOOP_PLUGIN = {};
+/**
+* Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /
+* `invalidate` writes across tabs of the same origin.
+*
+* Wire it up via `RootOptions.plugins`:
+*
+* ```ts
+* createRoot(appController, {
+*   deps,
+*   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],
+* })
+* ```
+*
+* Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`
+* — the `queryId` routes inbound messages back to the right query, and
+* `crossTab: true` is the per-query opt-in (queries that don't set it are
+* ignored by the sender so module-internal queries don't leak).
+*
+* **SSR safety.** When `BroadcastChannel` is not defined (Node, older
+* browsers without the feature) and no `channelFactory` override is
+* supplied, the function returns a no-op plugin object. The root still
+* boots cleanly; cross-tab is just disabled.
+*
+* **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache
+* data containing functions, class instances, or symbols throws a
+* `DataCloneError` at `postMessage`. The plugin catches the throw, calls
+* `onWarn(...)`, and drops the message — the sender's cache is unaffected.
+*/
+function crossTabPlugin(options) {
+	const channelName = options.channelName;
+	const onWarn = options.onWarn ?? defaultWarn;
+	const factory = options.channelFactory ?? defaultChannelFactory;
+	const probe = factory(channelName);
+	if (!probe) return NOOP_PLUGIN;
+	probe.close();
+	const sourceId = makeSourceId();
+	let msgIdCounter = 0;
+	const seenByPeer = /* @__PURE__ */ new Map();
+	let api = null;
+	let channel = null;
+	const listener = (event) => {
+		const msg = event.data;
+		if (!msg || typeof msg !== "object") return;
+		if (msg.v !== 1) return;
+		if (msg.sourceId === sourceId) return;
+		if (typeof msg.sourceId !== "string" || typeof msg.msgId !== "number") return;
+		const last = seenByPeer.get(msg.sourceId) ?? -1;
+		if (msg.msgId <= last) return;
+		seenByPeer.set(msg.sourceId, msg.msgId);
+		if (msg.type === "setData") {
+			if (typeof msg.queryId !== "string" || !Array.isArray(msg.keyArgs)) {
+				onWarn("[olas/cross-tab] malformed setData message");
+				return;
+			}
+			api?.applyRemoteSetData(msg.queryId, msg.keyArgs, msg.data);
+			return;
+		}
+		if (msg.type === "invalidate") {
+			if (typeof msg.queryId !== "string" || !Array.isArray(msg.keyArgs)) {
+				onWarn("[olas/cross-tab] malformed invalidate message");
+				return;
+			}
+			api?.applyRemoteInvalidate(msg.queryId, msg.keyArgs);
+			return;
+		}
+	};
+	const send = (msg) => {
+		if (channel === null) return;
+		try {
+			channel.postMessage(msg);
+		} catch (cause) {
+			onWarn(`[olas/cross-tab] failed to broadcast ${msg.type} for queryId="${msg.queryId}": data is not structured-cloneable`, cause);
+		}
+	};
+	return {
+		init(a) {
+			api = a;
+			channel = factory(channelName) ?? null;
+			channel?.addEventListener("message", listener);
+		},
+		onSetData(event) {
+			if (event.isRemote) return;
+			if (event.kind !== "data") return;
+			if (!shouldBroadcast(event.queryId)) return;
+			send({
+				v: 1,
+				type: "setData",
+				sourceId,
+				msgId: ++msgIdCounter,
+				queryId: event.queryId,
+				keyArgs: event.keyArgs,
+				data: event.data
+			});
+		},
+		onInvalidate(event) {
+			if (event.isRemote) return;
+			if (event.kind !== "data") return;
+			if (!shouldBroadcast(event.queryId)) return;
+			send({
+				v: 1,
+				type: "invalidate",
+				sourceId,
+				msgId: ++msgIdCounter,
+				queryId: event.queryId,
+				keyArgs: event.keyArgs
+			});
+		},
+		onGc(_event) {},
+		dispose() {
+			if (channel !== null) {
+				channel.removeEventListener("message", listener);
+				channel.close();
+				channel = null;
+			}
+			api = null;
+		}
+	};
+}
+function defaultWarn(message, cause) {
+	if (cause !== void 0) console.warn(message, cause);
+	else console.warn(message);
+}
+/**
+* Per-query gate. `crossTab: true` is a static opt-in on the spec; the
+* QueryClient doesn't filter on it (its events fire for every query that
+* has a `queryId`), so the plugin checks here. We look it up from the
+* core's query registry on every event — no caching, since the registry
+* lookup is a Map.get.
+*/
+function shouldBroadcast(queryId) {
+	const registered = (0, _kontsedal_olas_core.lookupRegisteredQuery)(queryId);
+	if (!registered) return false;
+	return registered.__spec.crossTab === true;
+}
+//#endregion
+exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
+exports.crossTabPlugin = crossTabPlugin;
+exports.defaultChannelFactory = defaultChannelFactory;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/channel.ts","../src/protocol.ts","../src/plugin.ts"],"sourcesContent":["/**\n * Tiny `BroadcastChannel`-shaped abstraction. Lets tests inject a fake\n * (a shared in-memory bus across multiple \"tabs\" in the same process) and\n * keeps SSR-safety in one place — when `BroadcastChannel` is absent and\n * no `channelFactory` override is supplied, the plugin returns a no-op\n * variant up the stack.\n */\n\nexport type ChannelLike = {\n  postMessage(data: unknown): void\n  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void\n  removeEventListener(type: 'message', listener: (event: { data: unknown }) => void): void\n  close(): void\n}\n\n/**\n * Default factory: wraps the platform `BroadcastChannel`. Returns\n * `undefined` when `BroadcastChannel` is not defined (SSR / Node without\n * `--experimental-broadcastchannel`, older browsers).\n */\nexport function defaultChannelFactory(name: string): ChannelLike | undefined {\n  if (typeof BroadcastChannel === 'undefined') return undefined\n  const ch = new BroadcastChannel(name)\n  return {\n    postMessage(data) {\n      ch.postMessage(data)\n    },\n    addEventListener(type, listener) {\n      // The platform BroadcastChannel typing wants a `MessageEvent`\n      // listener, but we only care about `event.data` — cast through\n      // `unknown` since the shapes don't structurally overlap.\n      ch.addEventListener(type, listener as unknown as EventListener)\n    },\n    removeEventListener(type, listener) {\n      ch.removeEventListener(type, listener as unknown as EventListener)\n    },\n    close() {\n      ch.close()\n    },\n  }\n}\n","/**\n * Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.\n *\n * `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)\n * combine to make the three-layer echo prevention work:\n *\n * 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the\n *    write originated from `applyRemoteSetData`).\n * 2. Receiver filters its own `sourceId` (catches the case where the\n *    transport echoes the message back to the sender).\n * 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order\n *    messages from the same peer are dropped.\n *\n * Receivers also drop messages with a `v` they don't understand. The\n * channel name itself is user-supplied; consumers who want clean\n * cross-deploy isolation should embed a version in their `channelName`.\n */\n\nexport const PROTOCOL_VERSION = 1\n\nexport type SetDataMessage = {\n  v: typeof PROTOCOL_VERSION\n  type: 'setData'\n  sourceId: string\n  msgId: number\n  queryId: string\n  keyArgs: readonly unknown[]\n  data: unknown\n}\n\nexport type InvalidateMessage = {\n  v: typeof PROTOCOL_VERSION\n  type: 'invalidate'\n  sourceId: string\n  msgId: number\n  queryId: string\n  keyArgs: readonly unknown[]\n}\n\nexport type Message = SetDataMessage | InvalidateMessage\n","import {\n  type GcEvent,\n  type InvalidateEvent,\n  lookupRegisteredQuery,\n  type QueryClientPlugin,\n  type QueryClientPluginApi,\n  type SetDataEvent,\n} from '@kontsedal/olas-core'\nimport { type ChannelLike, defaultChannelFactory } from './channel'\nimport { type Message, PROTOCOL_VERSION } from './protocol'\n\n/**\n * Options accepted by `crossTabPlugin(...)`. SPEC §13.2.\n *\n * - `channelName` — name of the `BroadcastChannel`. Required. Users who\n *   want clean cross-deploy isolation should include a version suffix\n *   (e.g. `'my-app/cache/v2'`).\n * - `onWarn` — called for non-fatal conditions: a `DataCloneError` while\n *   posting (the data isn't structured-cloneable), or a malformed\n *   inbound message. Default: `console.warn`.\n * - `channelFactory` — override the channel constructor. Mainly for\n *   tests that share an in-memory bus across two QueryClients.\n */\nexport type CrossTabOptions = {\n  channelName: string\n  onWarn?: (message: string, cause?: unknown) => void\n  channelFactory?: (name: string) => ChannelLike | undefined\n}\n\n/**\n * Generate a unique-enough source id for a plugin instance. Combines\n * `Date.now()` with `Math.random()` — collisions across same-millisecond\n * tab-opens are negligible at one-decimal-place randomness, and even a\n * collision only loses dedup, not correctness.\n */\nfunction makeSourceId(): string {\n  const rand = Math.random().toString(36).slice(2, 10)\n  return `${Date.now().toString(36)}-${rand}`\n}\n\nconst NOOP_PLUGIN: QueryClientPlugin = {}\n\n/**\n * Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /\n * `invalidate` writes across tabs of the same origin.\n *\n * Wire it up via `RootOptions.plugins`:\n *\n * ```ts\n * createRoot(appController, {\n *   deps,\n *   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],\n * })\n * ```\n *\n * Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`\n * — the `queryId` routes inbound messages back to the right query, and\n * `crossTab: true` is the per-query opt-in (queries that don't set it are\n * ignored by the sender so module-internal queries don't leak).\n *\n * **SSR safety.** When `BroadcastChannel` is not defined (Node, older\n * browsers without the feature) and no `channelFactory` override is\n * supplied, the function returns a no-op plugin object. The root still\n * boots cleanly; cross-tab is just disabled.\n *\n * **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache\n * data containing functions, class instances, or symbols throws a\n * `DataCloneError` at `postMessage`. The plugin catches the throw, calls\n * `onWarn(...)`, and drops the message — the sender's cache is unaffected.\n */\nexport function crossTabPlugin(options: CrossTabOptions): QueryClientPlugin {\n  const channelName = options.channelName\n  const onWarn = options.onWarn ?? defaultWarn\n  const factory = options.channelFactory ?? defaultChannelFactory\n\n  // Cheap probe — if the environment can't produce a channel at all we can\n  // return a no-op plugin without opening anything. The real channel opens\n  // lazily in `init` so a plugin that's constructed but never passed to a\n  // root doesn't leak a BroadcastChannel.\n  const probe = factory(channelName)\n  if (!probe) {\n    // SSR / unsupported environment. Caller's plugin slot still receives a\n    // valid plugin object; it just does nothing.\n    return NOOP_PLUGIN\n  }\n  probe.close()\n\n  const sourceId = makeSourceId()\n  let msgIdCounter = 0\n  const seenByPeer = new Map<string, number>()\n  let api: QueryClientPluginApi | null = null\n  let channel: ChannelLike | null = null\n\n  const listener = (event: { data: unknown }) => {\n    const msg = event.data as Partial<Message> | null\n    if (!msg || typeof msg !== 'object') return\n    // Layer 1 — protocol version drop.\n    if (msg.v !== PROTOCOL_VERSION) return\n    // Layer 2 — own-source drop (transport echoed our own message back).\n    if (msg.sourceId === sourceId) return\n    // Layer 3 — out-of-order / duplicate drop.\n    if (typeof msg.sourceId !== 'string' || typeof msg.msgId !== 'number') return\n    const last = seenByPeer.get(msg.sourceId) ?? -1\n    if (msg.msgId <= last) return\n    seenByPeer.set(msg.sourceId, msg.msgId)\n\n    if (msg.type === 'setData') {\n      if (typeof msg.queryId !== 'string' || !Array.isArray(msg.keyArgs)) {\n        onWarn('[olas/cross-tab] malformed setData message')\n        return\n      }\n      api?.applyRemoteSetData(msg.queryId, msg.keyArgs, msg.data)\n      return\n    }\n    if (msg.type === 'invalidate') {\n      if (typeof msg.queryId !== 'string' || !Array.isArray(msg.keyArgs)) {\n        onWarn('[olas/cross-tab] malformed invalidate message')\n        return\n      }\n      api?.applyRemoteInvalidate(msg.queryId, msg.keyArgs)\n      return\n    }\n  }\n\n  const send = (msg: Message): void => {\n    if (channel === null) return\n    try {\n      channel.postMessage(msg)\n    } catch (cause) {\n      // Structured clone failed — most likely non-cloneable data on a\n      // setData payload. Warn and drop.\n      onWarn(\n        `[olas/cross-tab] failed to broadcast ${msg.type} for queryId=\"${msg.queryId}\": data is not structured-cloneable`,\n        cause,\n      )\n    }\n  }\n\n  return {\n    init(a) {\n      api = a\n      channel = factory(channelName) ?? null\n      channel?.addEventListener('message', listener)\n    },\n\n    onSetData(event: SetDataEvent) {\n      // Don't echo inbound writes — Layer-1 sender-side echo prevention.\n      if (event.isRemote) return\n      // Infinite queries are deferred for v1 — see SPEC §13.2.\n      if (event.kind !== 'data') return\n      if (!shouldBroadcast(event.queryId)) return\n\n      send({\n        v: PROTOCOL_VERSION,\n        type: 'setData',\n        sourceId,\n        msgId: ++msgIdCounter,\n        queryId: event.queryId,\n        keyArgs: event.keyArgs,\n        data: event.data,\n      })\n    },\n\n    onInvalidate(event: InvalidateEvent) {\n      if (event.isRemote) return\n      if (event.kind !== 'data') return\n      if (!shouldBroadcast(event.queryId)) return\n\n      send({\n        v: PROTOCOL_VERSION,\n        type: 'invalidate',\n        sourceId,\n        msgId: ++msgIdCounter,\n        queryId: event.queryId,\n        keyArgs: event.keyArgs,\n      })\n    },\n\n    onGc(_event: GcEvent) {\n      // GC is local — we don't propagate it. Each tab gc's its own entries\n      // when its own subscribers drop.\n    },\n\n    dispose() {\n      if (channel !== null) {\n        channel.removeEventListener('message', listener)\n        channel.close()\n        channel = null\n      }\n      api = null\n    },\n  }\n}\n\nfunction defaultWarn(message: string, cause?: unknown): void {\n  if (cause !== undefined) {\n    console.warn(message, cause)\n  } else {\n    console.warn(message)\n  }\n}\n\n/**\n * Per-query gate. `crossTab: true` is a static opt-in on the spec; the\n * QueryClient doesn't filter on it (its events fire for every query that\n * has a `queryId`), so the plugin checks here. We look it up from the\n * core's query registry on every event — no caching, since the registry\n * lookup is a Map.get.\n */\nfunction shouldBroadcast(queryId: string): boolean {\n  const registered = lookupRegisteredQuery(queryId)\n  if (!registered) return false\n  return registered.__spec.crossTab === true\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,115 @@
+import { QueryClientPlugin } from "@kontsedal/olas-core";
+
+//#region src/channel.d.ts
+/**
+ * Tiny `BroadcastChannel`-shaped abstraction. Lets tests inject a fake
+ * (a shared in-memory bus across multiple "tabs" in the same process) and
+ * keeps SSR-safety in one place — when `BroadcastChannel` is absent and
+ * no `channelFactory` override is supplied, the plugin returns a no-op
+ * variant up the stack.
+ */
+type ChannelLike = {
+  postMessage(data: unknown): void;
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  removeEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  close(): void;
+};
+/**
+ * Default factory: wraps the platform `BroadcastChannel`. Returns
+ * `undefined` when `BroadcastChannel` is not defined (SSR / Node without
+ * `--experimental-broadcastchannel`, older browsers).
+ */
+declare function defaultChannelFactory(name: string): ChannelLike | undefined;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Options accepted by `crossTabPlugin(...)`. SPEC §13.2.
+ *
+ * - `channelName` — name of the `BroadcastChannel`. Required. Users who
+ *   want clean cross-deploy isolation should include a version suffix
+ *   (e.g. `'my-app/cache/v2'`).
+ * - `onWarn` — called for non-fatal conditions: a `DataCloneError` while
+ *   posting (the data isn't structured-cloneable), or a malformed
+ *   inbound message. Default: `console.warn`.
+ * - `channelFactory` — override the channel constructor. Mainly for
+ *   tests that share an in-memory bus across two QueryClients.
+ */
+type CrossTabOptions = {
+  channelName: string;
+  onWarn?: (message: string, cause?: unknown) => void;
+  channelFactory?: (name: string) => ChannelLike | undefined;
+};
+/**
+ * Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /
+ * `invalidate` writes across tabs of the same origin.
+ *
+ * Wire it up via `RootOptions.plugins`:
+ *
+ * ```ts
+ * createRoot(appController, {
+ *   deps,
+ *   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],
+ * })
+ * ```
+ *
+ * Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`
+ * — the `queryId` routes inbound messages back to the right query, and
+ * `crossTab: true` is the per-query opt-in (queries that don't set it are
+ * ignored by the sender so module-internal queries don't leak).
+ *
+ * **SSR safety.** When `BroadcastChannel` is not defined (Node, older
+ * browsers without the feature) and no `channelFactory` override is
+ * supplied, the function returns a no-op plugin object. The root still
+ * boots cleanly; cross-tab is just disabled.
+ *
+ * **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache
+ * data containing functions, class instances, or symbols throws a
+ * `DataCloneError` at `postMessage`. The plugin catches the throw, calls
+ * `onWarn(...)`, and drops the message — the sender's cache is unaffected.
+ */
+declare function crossTabPlugin(options: CrossTabOptions): QueryClientPlugin;
+//#endregion
+//#region src/protocol.d.ts
+/**
+ * Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.
+ *
+ * `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)
+ * combine to make the three-layer echo prevention work:
+ *
+ * 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the
+ *    write originated from `applyRemoteSetData`).
+ * 2. Receiver filters its own `sourceId` (catches the case where the
+ *    transport echoes the message back to the sender).
+ * 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order
+ *    messages from the same peer are dropped.
+ *
+ * Receivers also drop messages with a `v` they don't understand. The
+ * channel name itself is user-supplied; consumers who want clean
+ * cross-deploy isolation should embed a version in their `channelName`.
+ */
+declare const PROTOCOL_VERSION = 1;
+type SetDataMessage = {
+  v: typeof PROTOCOL_VERSION;
+  type: 'setData';
+  sourceId: string;
+  msgId: number;
+  queryId: string;
+  keyArgs: readonly unknown[];
+  data: unknown;
+};
+type InvalidateMessage = {
+  v: typeof PROTOCOL_VERSION;
+  type: 'invalidate';
+  sourceId: string;
+  msgId: number;
+  queryId: string;
+  keyArgs: readonly unknown[];
+};
+type Message = SetDataMessage | InvalidateMessage;
+//#endregion
+export { type ChannelLike, type CrossTabOptions, type InvalidateMessage, type Message, PROTOCOL_VERSION, type SetDataMessage, crossTabPlugin, defaultChannelFactory };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/channel.ts","../src/plugin.ts","../src/protocol.ts"],"mappings":";;;;;;AAQA;;;;KAAY,WAAA;EACV,WAAA,CAAY,IAAA;EACZ,gBAAA,CAAiB,IAAA,aAAiB,QAAA,GAAW,KAAA;IAAS,IAAA;EAAA;EACtD,mBAAA,CAAoB,IAAA,aAAiB,QAAA,GAAW,KAAA;IAAS,IAAA;EAAA;EACzD,KAAA;AAAA;;;;;AAAK;iBAQS,qBAAA,CAAsB,IAAA,WAAe,WAAW;;;;AAZhE;;;;;;;;;;;KCeY,eAAA;EACV,WAAA;EACA,MAAA,IAAU,OAAA,UAAiB,KAAA;EAC3B,cAAA,IAAkB,IAAA,aAAiB,WAAW;AAAA;;;ADdzC;AAQP;;;;AAAgE;;;;ACGhE;;;;;;;;;;;;AAGgD;AA4ChD;;;;iBAAgB,cAAA,CAAe,OAAA,EAAS,eAAA,GAAkB,iBAAiB;;;;;;AD9D3E;;;;;;;;;;;;;;cEUa,gBAAA;AAAA,KAED,cAAA;EACV,CAAA,SAAU,gBAAgB;EAC1B,IAAA;EACA,QAAA;EACA,KAAA;EACA,OAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,KAGU,iBAAA;EACV,CAAA,SAAU,gBAAgB;EAC1B,IAAA;EACA,QAAA;EACA,KAAA;EACA,OAAA;EACA,OAAA;AAAA;AAAA,KAGU,OAAA,GAAU,cAAA,GAAiB,iBAAiB"}

package/dist/index.d.mts

@@ -0,0 +1,115 @@
+import { QueryClientPlugin } from "@kontsedal/olas-core";
+
+//#region src/channel.d.ts
+/**
+ * Tiny `BroadcastChannel`-shaped abstraction. Lets tests inject a fake
+ * (a shared in-memory bus across multiple "tabs" in the same process) and
+ * keeps SSR-safety in one place — when `BroadcastChannel` is absent and
+ * no `channelFactory` override is supplied, the plugin returns a no-op
+ * variant up the stack.
+ */
+type ChannelLike = {
+  postMessage(data: unknown): void;
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  removeEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  close(): void;
+};
+/**
+ * Default factory: wraps the platform `BroadcastChannel`. Returns
+ * `undefined` when `BroadcastChannel` is not defined (SSR / Node without
+ * `--experimental-broadcastchannel`, older browsers).
+ */
+declare function defaultChannelFactory(name: string): ChannelLike | undefined;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Options accepted by `crossTabPlugin(...)`. SPEC §13.2.
+ *
+ * - `channelName` — name of the `BroadcastChannel`. Required. Users who
+ *   want clean cross-deploy isolation should include a version suffix
+ *   (e.g. `'my-app/cache/v2'`).
+ * - `onWarn` — called for non-fatal conditions: a `DataCloneError` while
+ *   posting (the data isn't structured-cloneable), or a malformed
+ *   inbound message. Default: `console.warn`.
+ * - `channelFactory` — override the channel constructor. Mainly for
+ *   tests that share an in-memory bus across two QueryClients.
+ */
+type CrossTabOptions = {
+  channelName: string;
+  onWarn?: (message: string, cause?: unknown) => void;
+  channelFactory?: (name: string) => ChannelLike | undefined;
+};
+/**
+ * Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /
+ * `invalidate` writes across tabs of the same origin.
+ *
+ * Wire it up via `RootOptions.plugins`:
+ *
+ * ```ts
+ * createRoot(appController, {
+ *   deps,
+ *   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],
+ * })
+ * ```
+ *
+ * Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`
+ * — the `queryId` routes inbound messages back to the right query, and
+ * `crossTab: true` is the per-query opt-in (queries that don't set it are
+ * ignored by the sender so module-internal queries don't leak).
+ *
+ * **SSR safety.** When `BroadcastChannel` is not defined (Node, older
+ * browsers without the feature) and no `channelFactory` override is
+ * supplied, the function returns a no-op plugin object. The root still
+ * boots cleanly; cross-tab is just disabled.
+ *
+ * **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache
+ * data containing functions, class instances, or symbols throws a
+ * `DataCloneError` at `postMessage`. The plugin catches the throw, calls
+ * `onWarn(...)`, and drops the message — the sender's cache is unaffected.
+ */
+declare function crossTabPlugin(options: CrossTabOptions): QueryClientPlugin;
+//#endregion
+//#region src/protocol.d.ts
+/**
+ * Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.
+ *
+ * `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)
+ * combine to make the three-layer echo prevention work:
+ *
+ * 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the
+ *    write originated from `applyRemoteSetData`).
+ * 2. Receiver filters its own `sourceId` (catches the case where the
+ *    transport echoes the message back to the sender).
+ * 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order
+ *    messages from the same peer are dropped.
+ *
+ * Receivers also drop messages with a `v` they don't understand. The
+ * channel name itself is user-supplied; consumers who want clean
+ * cross-deploy isolation should embed a version in their `channelName`.
+ */
+declare const PROTOCOL_VERSION = 1;
+type SetDataMessage = {
+  v: typeof PROTOCOL_VERSION;
+  type: 'setData';
+  sourceId: string;
+  msgId: number;
+  queryId: string;
+  keyArgs: readonly unknown[];
+  data: unknown;
+};
+type InvalidateMessage = {
+  v: typeof PROTOCOL_VERSION;
+  type: 'invalidate';
+  sourceId: string;
+  msgId: number;
+  queryId: string;
+  keyArgs: readonly unknown[];
+};
+type Message = SetDataMessage | InvalidateMessage;
+//#endregion
+export { type ChannelLike, type CrossTabOptions, type InvalidateMessage, type Message, PROTOCOL_VERSION, type SetDataMessage, crossTabPlugin, defaultChannelFactory };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/channel.ts","../src/plugin.ts","../src/protocol.ts"],"mappings":";;;;;;AAQA;;;;KAAY,WAAA;EACV,WAAA,CAAY,IAAA;EACZ,gBAAA,CAAiB,IAAA,aAAiB,QAAA,GAAW,KAAA;IAAS,IAAA;EAAA;EACtD,mBAAA,CAAoB,IAAA,aAAiB,QAAA,GAAW,KAAA;IAAS,IAAA;EAAA;EACzD,KAAA;AAAA;;;;;AAAK;iBAQS,qBAAA,CAAsB,IAAA,WAAe,WAAW;;;;AAZhE;;;;;;;;;;;KCeY,eAAA;EACV,WAAA;EACA,MAAA,IAAU,OAAA,UAAiB,KAAA;EAC3B,cAAA,IAAkB,IAAA,aAAiB,WAAW;AAAA;;;ADdzC;AAQP;;;;AAAgE;;;;ACGhE;;;;;;;;;;;;AAGgD;AA4ChD;;;;iBAAgB,cAAA,CAAe,OAAA,EAAS,eAAA,GAAkB,iBAAiB;;;;;;AD9D3E;;;;;;;;;;;;;;cEUa,gBAAA;AAAA,KAED,cAAA;EACV,CAAA,SAAU,gBAAgB;EAC1B,IAAA;EACA,QAAA;EACA,KAAA;EACA,OAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,KAGU,iBAAA;EACV,CAAA,SAAU,gBAAgB;EAC1B,IAAA;EACA,QAAA;EACA,KAAA;EACA,OAAA;EACA,OAAA;AAAA;AAAA,KAGU,OAAA,GAAU,cAAA,GAAiB,iBAAiB"}

package/dist/index.mjs

@@ -0,0 +1,196 @@
+import { lookupRegisteredQuery } from "@kontsedal/olas-core";
+//#region src/channel.ts
+/**
+* Default factory: wraps the platform `BroadcastChannel`. Returns
+* `undefined` when `BroadcastChannel` is not defined (SSR / Node without
+* `--experimental-broadcastchannel`, older browsers).
+*/
+function defaultChannelFactory(name) {
+	if (typeof BroadcastChannel === "undefined") return void 0;
+	const ch = new BroadcastChannel(name);
+	return {
+		postMessage(data) {
+			ch.postMessage(data);
+		},
+		addEventListener(type, listener) {
+			ch.addEventListener(type, listener);
+		},
+		removeEventListener(type, listener) {
+			ch.removeEventListener(type, listener);
+		},
+		close() {
+			ch.close();
+		}
+	};
+}
+//#endregion
+//#region src/protocol.ts
+/**
+* Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.
+*
+* `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)
+* combine to make the three-layer echo prevention work:
+*
+* 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the
+*    write originated from `applyRemoteSetData`).
+* 2. Receiver filters its own `sourceId` (catches the case where the
+*    transport echoes the message back to the sender).
+* 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order
+*    messages from the same peer are dropped.
+*
+* Receivers also drop messages with a `v` they don't understand. The
+* channel name itself is user-supplied; consumers who want clean
+* cross-deploy isolation should embed a version in their `channelName`.
+*/
+const PROTOCOL_VERSION = 1;
+//#endregion
+//#region src/plugin.ts
+/**
+* Generate a unique-enough source id for a plugin instance. Combines
+* `Date.now()` with `Math.random()` — collisions across same-millisecond
+* tab-opens are negligible at one-decimal-place randomness, and even a
+* collision only loses dedup, not correctness.
+*/
+function makeSourceId() {
+	const rand = Math.random().toString(36).slice(2, 10);
+	return `${Date.now().toString(36)}-${rand}`;
+}
+const NOOP_PLUGIN = {};
+/**
+* Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /
+* `invalidate` writes across tabs of the same origin.
+*
+* Wire it up via `RootOptions.plugins`:
+*
+* ```ts
+* createRoot(appController, {
+*   deps,
+*   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],
+* })
+* ```
+*
+* Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`
+* — the `queryId` routes inbound messages back to the right query, and
+* `crossTab: true` is the per-query opt-in (queries that don't set it are
+* ignored by the sender so module-internal queries don't leak).
+*
+* **SSR safety.** When `BroadcastChannel` is not defined (Node, older
+* browsers without the feature) and no `channelFactory` override is
+* supplied, the function returns a no-op plugin object. The root still
+* boots cleanly; cross-tab is just disabled.
+*
+* **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache
+* data containing functions, class instances, or symbols throws a
+* `DataCloneError` at `postMessage`. The plugin catches the throw, calls
+* `onWarn(...)`, and drops the message — the sender's cache is unaffected.
+*/
+function crossTabPlugin(options) {
+	const channelName = options.channelName;
+	const onWarn = options.onWarn ?? defaultWarn;
+	const factory = options.channelFactory ?? defaultChannelFactory;
+	const probe = factory(channelName);
+	if (!probe) return NOOP_PLUGIN;
+	probe.close();
+	const sourceId = makeSourceId();
+	let msgIdCounter = 0;
+	const seenByPeer = /* @__PURE__ */ new Map();
+	let api = null;
+	let channel = null;
+	const listener = (event) => {
+		const msg = event.data;
+		if (!msg || typeof msg !== "object") return;
+		if (msg.v !== 1) return;
+		if (msg.sourceId === sourceId) return;
+		if (typeof msg.sourceId !== "string" || typeof msg.msgId !== "number") return;
+		const last = seenByPeer.get(msg.sourceId) ?? -1;
+		if (msg.msgId <= last) return;
+		seenByPeer.set(msg.sourceId, msg.msgId);
+		if (msg.type === "setData") {
+			if (typeof msg.queryId !== "string" || !Array.isArray(msg.keyArgs)) {
+				onWarn("[olas/cross-tab] malformed setData message");
+				return;
+			}
+			api?.applyRemoteSetData(msg.queryId, msg.keyArgs, msg.data);
+			return;
+		}
+		if (msg.type === "invalidate") {
+			if (typeof msg.queryId !== "string" || !Array.isArray(msg.keyArgs)) {
+				onWarn("[olas/cross-tab] malformed invalidate message");
+				return;
+			}
+			api?.applyRemoteInvalidate(msg.queryId, msg.keyArgs);
+			return;
+		}
+	};
+	const send = (msg) => {
+		if (channel === null) return;
+		try {
+			channel.postMessage(msg);
+		} catch (cause) {
+			onWarn(`[olas/cross-tab] failed to broadcast ${msg.type} for queryId="${msg.queryId}": data is not structured-cloneable`, cause);
+		}
+	};
+	return {
+		init(a) {
+			api = a;
+			channel = factory(channelName) ?? null;
+			channel?.addEventListener("message", listener);
+		},
+		onSetData(event) {
+			if (event.isRemote) return;
+			if (event.kind !== "data") return;
+			if (!shouldBroadcast(event.queryId)) return;
+			send({
+				v: 1,
+				type: "setData",
+				sourceId,
+				msgId: ++msgIdCounter,
+				queryId: event.queryId,
+				keyArgs: event.keyArgs,
+				data: event.data
+			});
+		},
+		onInvalidate(event) {
+			if (event.isRemote) return;
+			if (event.kind !== "data") return;
+			if (!shouldBroadcast(event.queryId)) return;
+			send({
+				v: 1,
+				type: "invalidate",
+				sourceId,
+				msgId: ++msgIdCounter,
+				queryId: event.queryId,
+				keyArgs: event.keyArgs
+			});
+		},
+		onGc(_event) {},
+		dispose() {
+			if (channel !== null) {
+				channel.removeEventListener("message", listener);
+				channel.close();
+				channel = null;
+			}
+			api = null;
+		}
+	};
+}
+function defaultWarn(message, cause) {
+	if (cause !== void 0) console.warn(message, cause);
+	else console.warn(message);
+}
+/**
+* Per-query gate. `crossTab: true` is a static opt-in on the spec; the
+* QueryClient doesn't filter on it (its events fire for every query that
+* has a `queryId`), so the plugin checks here. We look it up from the
+* core's query registry on every event — no caching, since the registry
+* lookup is a Map.get.
+*/
+function shouldBroadcast(queryId) {
+	const registered = lookupRegisteredQuery(queryId);
+	if (!registered) return false;
+	return registered.__spec.crossTab === true;
+}
+//#endregion
+export { PROTOCOL_VERSION, crossTabPlugin, defaultChannelFactory };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/channel.ts","../src/protocol.ts","../src/plugin.ts"],"sourcesContent":["/**\n * Tiny `BroadcastChannel`-shaped abstraction. Lets tests inject a fake\n * (a shared in-memory bus across multiple \"tabs\" in the same process) and\n * keeps SSR-safety in one place — when `BroadcastChannel` is absent and\n * no `channelFactory` override is supplied, the plugin returns a no-op\n * variant up the stack.\n */\n\nexport type ChannelLike = {\n  postMessage(data: unknown): void\n  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void\n  removeEventListener(type: 'message', listener: (event: { data: unknown }) => void): void\n  close(): void\n}\n\n/**\n * Default factory: wraps the platform `BroadcastChannel`. Returns\n * `undefined` when `BroadcastChannel` is not defined (SSR / Node without\n * `--experimental-broadcastchannel`, older browsers).\n */\nexport function defaultChannelFactory(name: string): ChannelLike | undefined {\n  if (typeof BroadcastChannel === 'undefined') return undefined\n  const ch = new BroadcastChannel(name)\n  return {\n    postMessage(data) {\n      ch.postMessage(data)\n    },\n    addEventListener(type, listener) {\n      // The platform BroadcastChannel typing wants a `MessageEvent`\n      // listener, but we only care about `event.data` — cast through\n      // `unknown` since the shapes don't structurally overlap.\n      ch.addEventListener(type, listener as unknown as EventListener)\n    },\n    removeEventListener(type, listener) {\n      ch.removeEventListener(type, listener as unknown as EventListener)\n    },\n    close() {\n      ch.close()\n    },\n  }\n}\n","/**\n * Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.\n *\n * `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)\n * combine to make the three-layer echo prevention work:\n *\n * 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the\n *    write originated from `applyRemoteSetData`).\n * 2. Receiver filters its own `sourceId` (catches the case where the\n *    transport echoes the message back to the sender).\n * 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order\n *    messages from the same peer are dropped.\n *\n * Receivers also drop messages with a `v` they don't understand. The\n * channel name itself is user-supplied; consumers who want clean\n * cross-deploy isolation should embed a version in their `channelName`.\n */\n\nexport const PROTOCOL_VERSION = 1\n\nexport type SetDataMessage = {\n  v: typeof PROTOCOL_VERSION\n  type: 'setData'\n  sourceId: string\n  msgId: number\n  queryId: string\n  keyArgs: readonly unknown[]\n  data: unknown\n}\n\nexport type InvalidateMessage = {\n  v: typeof PROTOCOL_VERSION\n  type: 'invalidate'\n  sourceId: string\n  msgId: number\n  queryId: string\n  keyArgs: readonly unknown[]\n}\n\nexport type Message = SetDataMessage | InvalidateMessage\n","import {\n  type GcEvent,\n  type InvalidateEvent,\n  lookupRegisteredQuery,\n  type QueryClientPlugin,\n  type QueryClientPluginApi,\n  type SetDataEvent,\n} from '@kontsedal/olas-core'\nimport { type ChannelLike, defaultChannelFactory } from './channel'\nimport { type Message, PROTOCOL_VERSION } from './protocol'\n\n/**\n * Options accepted by `crossTabPlugin(...)`. SPEC §13.2.\n *\n * - `channelName` — name of the `BroadcastChannel`. Required. Users who\n *   want clean cross-deploy isolation should include a version suffix\n *   (e.g. `'my-app/cache/v2'`).\n * - `onWarn` — called for non-fatal conditions: a `DataCloneError` while\n *   posting (the data isn't structured-cloneable), or a malformed\n *   inbound message. Default: `console.warn`.\n * - `channelFactory` — override the channel constructor. Mainly for\n *   tests that share an in-memory bus across two QueryClients.\n */\nexport type CrossTabOptions = {\n  channelName: string\n  onWarn?: (message: string, cause?: unknown) => void\n  channelFactory?: (name: string) => ChannelLike | undefined\n}\n\n/**\n * Generate a unique-enough source id for a plugin instance. Combines\n * `Date.now()` with `Math.random()` — collisions across same-millisecond\n * tab-opens are negligible at one-decimal-place randomness, and even a\n * collision only loses dedup, not correctness.\n */\nfunction makeSourceId(): string {\n  const rand = Math.random().toString(36).slice(2, 10)\n  return `${Date.now().toString(36)}-${rand}`\n}\n\nconst NOOP_PLUGIN: QueryClientPlugin = {}\n\n/**\n * Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /\n * `invalidate` writes across tabs of the same origin.\n *\n * Wire it up via `RootOptions.plugins`:\n *\n * ```ts\n * createRoot(appController, {\n *   deps,\n *   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],\n * })\n * ```\n *\n * Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`\n * — the `queryId` routes inbound messages back to the right query, and\n * `crossTab: true` is the per-query opt-in (queries that don't set it are\n * ignored by the sender so module-internal queries don't leak).\n *\n * **SSR safety.** When `BroadcastChannel` is not defined (Node, older\n * browsers without the feature) and no `channelFactory` override is\n * supplied, the function returns a no-op plugin object. The root still\n * boots cleanly; cross-tab is just disabled.\n *\n * **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache\n * data containing functions, class instances, or symbols throws a\n * `DataCloneError` at `postMessage`. The plugin catches the throw, calls\n * `onWarn(...)`, and drops the message — the sender's cache is unaffected.\n */\nexport function crossTabPlugin(options: CrossTabOptions): QueryClientPlugin {\n  const channelName = options.channelName\n  const onWarn = options.onWarn ?? defaultWarn\n  const factory = options.channelFactory ?? defaultChannelFactory\n\n  // Cheap probe — if the environment can't produce a channel at all we can\n  // return a no-op plugin without opening anything. The real channel opens\n  // lazily in `init` so a plugin that's constructed but never passed to a\n  // root doesn't leak a BroadcastChannel.\n  const probe = factory(channelName)\n  if (!probe) {\n    // SSR / unsupported environment. Caller's plugin slot still receives a\n    // valid plugin object; it just does nothing.\n    return NOOP_PLUGIN\n  }\n  probe.close()\n\n  const sourceId = makeSourceId()\n  let msgIdCounter = 0\n  const seenByPeer = new Map<string, number>()\n  let api: QueryClientPluginApi | null = null\n  let channel: ChannelLike | null = null\n\n  const listener = (event: { data: unknown }) => {\n    const msg = event.data as Partial<Message> | null\n    if (!msg || typeof msg !== 'object') return\n    // Layer 1 — protocol version drop.\n    if (msg.v !== PROTOCOL_VERSION) return\n    // Layer 2 — own-source drop (transport echoed our own message back).\n    if (msg.sourceId === sourceId) return\n    // Layer 3 — out-of-order / duplicate drop.\n    if (typeof msg.sourceId !== 'string' || typeof msg.msgId !== 'number') return\n    const last = seenByPeer.get(msg.sourceId) ?? -1\n    if (msg.msgId <= last) return\n    seenByPeer.set(msg.sourceId, msg.msgId)\n\n    if (msg.type === 'setData') {\n      if (typeof msg.queryId !== 'string' || !Array.isArray(msg.keyArgs)) {\n        onWarn('[olas/cross-tab] malformed setData message')\n        return\n      }\n      api?.applyRemoteSetData(msg.queryId, msg.keyArgs, msg.data)\n      return\n    }\n    if (msg.type === 'invalidate') {\n      if (typeof msg.queryId !== 'string' || !Array.isArray(msg.keyArgs)) {\n        onWarn('[olas/cross-tab] malformed invalidate message')\n        return\n      }\n      api?.applyRemoteInvalidate(msg.queryId, msg.keyArgs)\n      return\n    }\n  }\n\n  const send = (msg: Message): void => {\n    if (channel === null) return\n    try {\n      channel.postMessage(msg)\n    } catch (cause) {\n      // Structured clone failed — most likely non-cloneable data on a\n      // setData payload. Warn and drop.\n      onWarn(\n        `[olas/cross-tab] failed to broadcast ${msg.type} for queryId=\"${msg.queryId}\": data is not structured-cloneable`,\n        cause,\n      )\n    }\n  }\n\n  return {\n    init(a) {\n      api = a\n      channel = factory(channelName) ?? null\n      channel?.addEventListener('message', listener)\n    },\n\n    onSetData(event: SetDataEvent) {\n      // Don't echo inbound writes — Layer-1 sender-side echo prevention.\n      if (event.isRemote) return\n      // Infinite queries are deferred for v1 — see SPEC §13.2.\n      if (event.kind !== 'data') return\n      if (!shouldBroadcast(event.queryId)) return\n\n      send({\n        v: PROTOCOL_VERSION,\n        type: 'setData',\n        sourceId,\n        msgId: ++msgIdCounter,\n        queryId: event.queryId,\n        keyArgs: event.keyArgs,\n        data: event.data,\n      })\n    },\n\n    onInvalidate(event: InvalidateEvent) {\n      if (event.isRemote) return\n      if (event.kind !== 'data') return\n      if (!shouldBroadcast(event.queryId)) return\n\n      send({\n        v: PROTOCOL_VERSION,\n        type: 'invalidate',\n        sourceId,\n        msgId: ++msgIdCounter,\n        queryId: event.queryId,\n        keyArgs: event.keyArgs,\n      })\n    },\n\n    onGc(_event: GcEvent) {\n      // GC is local — we don't propagate it. Each tab gc's its own entries\n      // when its own subscribers drop.\n    },\n\n    dispose() {\n      if (channel !== null) {\n        channel.removeEventListener('message', listener)\n        channel.close()\n        channel = null\n      }\n      api = null\n    },\n  }\n}\n\nfunction defaultWarn(message: string, cause?: unknown): void {\n  if (cause !== undefined) {\n    console.warn(message, cause)\n  } else {\n    console.warn(message)\n  }\n}\n\n/**\n * Per-query gate. `crossTab: true` is a static opt-in on the spec; the\n * QueryClient doesn't filter on it (its events fire for every query that\n * has a `queryId`), so the plugin checks here. We look it up from the\n * core's query registry on every event — no caching, since the registry\n * lookup is a Map.get.\n */\nfunction shouldBroadcast(queryId: string): boolean {\n  const registered = lookupRegisteredQuery(queryId)\n  if (!registered) return false\n  return registered.__spec.crossTab === true\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kontsedal/olas-cross-tab",
+  "version": "0.0.1-rc.0",
+  "description": "Olas cross-tab in-memory query cache sync via BroadcastChannel",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@kontsedal/olas-core": "^0.0.1-rc.0"
+  },
+  "devDependencies": {
+    "@kontsedal/olas-core": "^0.0.1-rc.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,41 @@
+/**
+ * Tiny `BroadcastChannel`-shaped abstraction. Lets tests inject a fake
+ * (a shared in-memory bus across multiple "tabs" in the same process) and
+ * keeps SSR-safety in one place — when `BroadcastChannel` is absent and
+ * no `channelFactory` override is supplied, the plugin returns a no-op
+ * variant up the stack.
+ */
+
+export type ChannelLike = {
+  postMessage(data: unknown): void
+  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void
+  removeEventListener(type: 'message', listener: (event: { data: unknown }) => void): void
+  close(): void
+}
+
+/**
+ * Default factory: wraps the platform `BroadcastChannel`. Returns
+ * `undefined` when `BroadcastChannel` is not defined (SSR / Node without
+ * `--experimental-broadcastchannel`, older browsers).
+ */
+export function defaultChannelFactory(name: string): ChannelLike | undefined {
+  if (typeof BroadcastChannel === 'undefined') return undefined
+  const ch = new BroadcastChannel(name)
+  return {
+    postMessage(data) {
+      ch.postMessage(data)
+    },
+    addEventListener(type, listener) {
+      // The platform BroadcastChannel typing wants a `MessageEvent`
+      // listener, but we only care about `event.data` — cast through
+      // `unknown` since the shapes don't structurally overlap.
+      ch.addEventListener(type, listener as unknown as EventListener)
+    },
+    removeEventListener(type, listener) {
+      ch.removeEventListener(type, listener as unknown as EventListener)
+    },
+    close() {
+      ch.close()
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@kontsedal/olas-cross-tab` — BroadcastChannel-backed in-memory cache sync across
+ * tabs of the same origin. See SPEC §13.2 and the package README.
+ */
+
+export type { ChannelLike } from './channel'
+export { defaultChannelFactory } from './channel'
+export { type CrossTabOptions, crossTabPlugin } from './plugin'
+export {
+  type InvalidateMessage,
+  type Message,
+  PROTOCOL_VERSION,
+  type SetDataMessage,
+} from './protocol'

package/src/plugin.ts

@@ -0,0 +1,214 @@
+import {
+  type GcEvent,
+  type InvalidateEvent,
+  lookupRegisteredQuery,
+  type QueryClientPlugin,
+  type QueryClientPluginApi,
+  type SetDataEvent,
+} from '@kontsedal/olas-core'
+import { type ChannelLike, defaultChannelFactory } from './channel'
+import { type Message, PROTOCOL_VERSION } from './protocol'
+
+/**
+ * Options accepted by `crossTabPlugin(...)`. SPEC §13.2.
+ *
+ * - `channelName` — name of the `BroadcastChannel`. Required. Users who
+ *   want clean cross-deploy isolation should include a version suffix
+ *   (e.g. `'my-app/cache/v2'`).
+ * - `onWarn` — called for non-fatal conditions: a `DataCloneError` while
+ *   posting (the data isn't structured-cloneable), or a malformed
+ *   inbound message. Default: `console.warn`.
+ * - `channelFactory` — override the channel constructor. Mainly for
+ *   tests that share an in-memory bus across two QueryClients.
+ */
+export type CrossTabOptions = {
+  channelName: string
+  onWarn?: (message: string, cause?: unknown) => void
+  channelFactory?: (name: string) => ChannelLike | undefined
+}
+
+/**
+ * Generate a unique-enough source id for a plugin instance. Combines
+ * `Date.now()` with `Math.random()` — collisions across same-millisecond
+ * tab-opens are negligible at one-decimal-place randomness, and even a
+ * collision only loses dedup, not correctness.
+ */
+function makeSourceId(): string {
+  const rand = Math.random().toString(36).slice(2, 10)
+  return `${Date.now().toString(36)}-${rand}`
+}
+
+const NOOP_PLUGIN: QueryClientPlugin = {}
+
+/**
+ * Cross-tab cache sync over `BroadcastChannel`. Mirrors `setData` /
+ * `invalidate` writes across tabs of the same origin.
+ *
+ * Wire it up via `RootOptions.plugins`:
+ *
+ * ```ts
+ * createRoot(appController, {
+ *   deps,
+ *   plugins: [crossTabPlugin({ channelName: 'my-app/cache/v1' })],
+ * })
+ * ```
+ *
+ * Queries must opt in via `defineQuery({ queryId: '<unique>', crossTab: true })`
+ * — the `queryId` routes inbound messages back to the right query, and
+ * `crossTab: true` is the per-query opt-in (queries that don't set it are
+ * ignored by the sender so module-internal queries don't leak).
+ *
+ * **SSR safety.** When `BroadcastChannel` is not defined (Node, older
+ * browsers without the feature) and no `channelFactory` override is
+ * supplied, the function returns a no-op plugin object. The root still
+ * boots cleanly; cross-tab is just disabled.
+ *
+ * **Non-cloneable data.** `BroadcastChannel` uses structured clone. Cache
+ * data containing functions, class instances, or symbols throws a
+ * `DataCloneError` at `postMessage`. The plugin catches the throw, calls
+ * `onWarn(...)`, and drops the message — the sender's cache is unaffected.
+ */
+export function crossTabPlugin(options: CrossTabOptions): QueryClientPlugin {
+  const channelName = options.channelName
+  const onWarn = options.onWarn ?? defaultWarn
+  const factory = options.channelFactory ?? defaultChannelFactory
+
+  // Cheap probe — if the environment can't produce a channel at all we can
+  // return a no-op plugin without opening anything. The real channel opens
+  // lazily in `init` so a plugin that's constructed but never passed to a
+  // root doesn't leak a BroadcastChannel.
+  const probe = factory(channelName)
+  if (!probe) {
+    // SSR / unsupported environment. Caller's plugin slot still receives a
+    // valid plugin object; it just does nothing.
+    return NOOP_PLUGIN
+  }
+  probe.close()
+
+  const sourceId = makeSourceId()
+  let msgIdCounter = 0
+  const seenByPeer = new Map<string, number>()
+  let api: QueryClientPluginApi | null = null
+  let channel: ChannelLike | null = null
+
+  const listener = (event: { data: unknown }) => {
+    const msg = event.data as Partial<Message> | null
+    if (!msg || typeof msg !== 'object') return
+    // Layer 1 — protocol version drop.
+    if (msg.v !== PROTOCOL_VERSION) return
+    // Layer 2 — own-source drop (transport echoed our own message back).
+    if (msg.sourceId === sourceId) return
+    // Layer 3 — out-of-order / duplicate drop.
+    if (typeof msg.sourceId !== 'string' || typeof msg.msgId !== 'number') return
+    const last = seenByPeer.get(msg.sourceId) ?? -1
+    if (msg.msgId <= last) return
+    seenByPeer.set(msg.sourceId, msg.msgId)
+
+    if (msg.type === 'setData') {
+      if (typeof msg.queryId !== 'string' || !Array.isArray(msg.keyArgs)) {
+        onWarn('[olas/cross-tab] malformed setData message')
+        return
+      }
+      api?.applyRemoteSetData(msg.queryId, msg.keyArgs, msg.data)
+      return
+    }
+    if (msg.type === 'invalidate') {
+      if (typeof msg.queryId !== 'string' || !Array.isArray(msg.keyArgs)) {
+        onWarn('[olas/cross-tab] malformed invalidate message')
+        return
+      }
+      api?.applyRemoteInvalidate(msg.queryId, msg.keyArgs)
+      return
+    }
+  }
+
+  const send = (msg: Message): void => {
+    if (channel === null) return
+    try {
+      channel.postMessage(msg)
+    } catch (cause) {
+      // Structured clone failed — most likely non-cloneable data on a
+      // setData payload. Warn and drop.
+      onWarn(
+        `[olas/cross-tab] failed to broadcast ${msg.type} for queryId="${msg.queryId}": data is not structured-cloneable`,
+        cause,
+      )
+    }
+  }
+
+  return {
+    init(a) {
+      api = a
+      channel = factory(channelName) ?? null
+      channel?.addEventListener('message', listener)
+    },
+
+    onSetData(event: SetDataEvent) {
+      // Don't echo inbound writes — Layer-1 sender-side echo prevention.
+      if (event.isRemote) return
+      // Infinite queries are deferred for v1 — see SPEC §13.2.
+      if (event.kind !== 'data') return
+      if (!shouldBroadcast(event.queryId)) return
+
+      send({
+        v: PROTOCOL_VERSION,
+        type: 'setData',
+        sourceId,
+        msgId: ++msgIdCounter,
+        queryId: event.queryId,
+        keyArgs: event.keyArgs,
+        data: event.data,
+      })
+    },
+
+    onInvalidate(event: InvalidateEvent) {
+      if (event.isRemote) return
+      if (event.kind !== 'data') return
+      if (!shouldBroadcast(event.queryId)) return
+
+      send({
+        v: PROTOCOL_VERSION,
+        type: 'invalidate',
+        sourceId,
+        msgId: ++msgIdCounter,
+        queryId: event.queryId,
+        keyArgs: event.keyArgs,
+      })
+    },
+
+    onGc(_event: GcEvent) {
+      // GC is local — we don't propagate it. Each tab gc's its own entries
+      // when its own subscribers drop.
+    },
+
+    dispose() {
+      if (channel !== null) {
+        channel.removeEventListener('message', listener)
+        channel.close()
+        channel = null
+      }
+      api = null
+    },
+  }
+}
+
+function defaultWarn(message: string, cause?: unknown): void {
+  if (cause !== undefined) {
+    console.warn(message, cause)
+  } else {
+    console.warn(message)
+  }
+}
+
+/**
+ * Per-query gate. `crossTab: true` is a static opt-in on the spec; the
+ * QueryClient doesn't filter on it (its events fire for every query that
+ * has a `queryId`), so the plugin checks here. We look it up from the
+ * core's query registry on every event — no caching, since the registry
+ * lookup is a Map.get.
+ */
+function shouldBroadcast(queryId: string): boolean {
+  const registered = lookupRegisteredQuery(queryId)
+  if (!registered) return false
+  return registered.__spec.crossTab === true
+}

package/src/protocol.ts

@@ -0,0 +1,40 @@
+/**
+ * Wire protocol for `@kontsedal/olas-cross-tab` messages. SPEC §13.2.
+ *
+ * `v` (protocol version) and `sourceId` (per-plugin-instance unique tag)
+ * combine to make the three-layer echo prevention work:
+ *
+ * 1. Sender skips broadcast when `SetDataEvent.isRemote === true` (the
+ *    write originated from `applyRemoteSetData`).
+ * 2. Receiver filters its own `sourceId` (catches the case where the
+ *    transport echoes the message back to the sender).
+ * 3. Receiver dedupes by `(sourceId, msgId)` — duplicate or out-of-order
+ *    messages from the same peer are dropped.
+ *
+ * Receivers also drop messages with a `v` they don't understand. The
+ * channel name itself is user-supplied; consumers who want clean
+ * cross-deploy isolation should embed a version in their `channelName`.
+ */
+
+export const PROTOCOL_VERSION = 1
+
+export type SetDataMessage = {
+  v: typeof PROTOCOL_VERSION
+  type: 'setData'
+  sourceId: string
+  msgId: number
+  queryId: string
+  keyArgs: readonly unknown[]
+  data: unknown
+}
+
+export type InvalidateMessage = {
+  v: typeof PROTOCOL_VERSION
+  type: 'invalidate'
+  sourceId: string
+  msgId: number
+  queryId: string
+  keyArgs: readonly unknown[]
+}
+
+export type Message = SetDataMessage | InvalidateMessage