pyric 0.0.1 → 0.1.0-alpha.7

package/dist/sandbox/replay/index.js

@@ -0,0 +1,246 @@
+/**
+ * Replay — capture a session via `sandbox.history()` and re-issue
+ * every write against a fresh sandbox; the engine classifies any
+ * divergences.
+ *
+ * Exported from the main `pyric/sandbox` entry. The file lives at
+ * `src/replay/index.ts` as an organizational unit; importers use
+ * the public bare-package import path.
+ *
+ * Usage:
+ * ```ts
+ * import { initializeSandbox, replay, type SandboxEvent } from 'pyric/sandbox';
+ *
+ * const original = initializeSandbox();
+ * // ... do work, capture events via original.history() ...
+ * const events = original.history();
+ *
+ * const { sandbox: replayed, divergences } = replay(events, rulesSource);
+ * // `replayed` is a fresh sandbox with every captured write re-applied.
+ * // `divergences` classifies any field-level differences.
+ * ```
+ *
+ * Each captured `WriteSandboxEvent` is re-issued on the fresh sandbox.
+ * The engine consults the captured `sentinels`, `autoId`, and
+ * `requestTime` fields so:
+ *   - `serverTimestamp()` sentinels re-resolve to the captured time
+ *     (when `pinRequestTime: true`, the default).
+ *   - `collection.add()` minted IDs alias to fresh mints on replay;
+ *     `pathAliases` maps the original path → the replayed path.
+ *   - rules that branch on `request.time` re-evaluate identically
+ *     (pinned time).
+ *
+ * Divergence classification (deterministic — no shape inference):
+ *   - `autoid-alias`    — path differs because of fresh ID minting,
+ *                          otherwise content matches.
+ *   - `sentinel-drift`  — a captured sentinel sits at this exact field
+ *                          path (e.g. an `increment` at `tags`) and the
+ *                          subtree differs.
+ *   - `time-drift`      — like `sentinel-drift` but specifically a
+ *                          captured `serverTimestamp`. Surfaces when
+ *                          `pinRequestTime: false` and the wall clock
+ *                          advanced between capture and replay.
+ *   - `real-divergence` — anything else. If the captured metadata
+ *                          doesn't license drift at this exact leaf,
+ *                          the engine flags it.
+ *
+ * Field-level diffs use a recursive walk producing dotted/bracket
+ * leaf paths (`profile.lastSeen`, `tags[0]`, `arr[2].nested`). A
+ * sentinel match is *exact-path*, not prefix — a sibling field
+ * changing inside a sentinel-bearing parent surfaces independently as
+ * `real-divergence`.
+ */
+import { initializeSandbox, } from '../index.js';
+import { getInternalEnv } from '../internal/sandbox-impl.js';
+import { Timestamp } from 'pyric/rules';
+/**
+ * Replay a captured SandboxEvent stream on a fresh sandbox.
+ *
+ * The `originalState` snapshot is optional — when provided, the engine
+ * diffs the replayed sandbox's final state against it and returns
+ * classified divergences. When omitted, divergences is `[]` (you still
+ * get the replayed sandbox; you can inspect its state manually).
+ */
+export function replay(events, rules, options = {}, originalState) {
+    const pinRequestTime = options.pinRequestTime !== false; // default true
+    const sandbox = initializeSandbox();
+    const env = getInternalEnv(sandbox);
+    env.seed({ rules });
+    const pathAliases = new Map();
+    const writes = events.filter((e) => e.kind === 'write');
+    // Re-issue every write. For each, look up the matching `request`
+    // event (one before each write in onEvent order — gives us the
+    // pre-resolution `request.resourceData`). Fall back to the write's
+    // own `data` (post-resolution) when the request event isn't
+    // available.
+    for (const wEv of writes) {
+        const bypassRules = isAdminWrite(wEv);
+        const data = preResolutionDataFor(wEv, events) ?? wEv.data;
+        const requestTime = pinRequestTime
+            ? new Timestamp(wEv.requestTime.seconds, wEv.requestTime.nanoseconds)
+            : undefined;
+        if (wEv.autoId) {
+            // Auto-id create: split path, mint a fresh id, record the alias.
+            const collection = wEv.path.slice(0, wEv.path.lastIndexOf('/'));
+            const { path: mintedPath } = env.createWithAutoId(collection, (data ?? {}), wEv.auth, bypassRules);
+            pathAliases.set(wEv.path, mintedPath);
+            continue;
+        }
+        try {
+            env.execute({
+                method: wEv.method,
+                path: wEv.path,
+                auth: wEv.auth,
+                ...(data !== undefined ? { data: data } : {}),
+                ...(requestTime ? { requestTime } : {}),
+                ...(bypassRules ? { bypassRules: true } : {}),
+            });
+        }
+        catch {
+            // Replay denials surface as state divergence below; keep going
+            // to surface as much as possible in one pass.
+        }
+    }
+    const replayedState = sandbox.snapshot().firestore;
+    const divergences = originalState
+        ? computeDivergences(writes, originalState, replayedState, pathAliases)
+        : [];
+    return { sandbox, divergences, pathAliases };
+}
+function isAdminWrite(event) {
+    return event.detail?.admin === true;
+}
+/**
+ * Best-effort pre-resolution data extraction. The `request` event that
+ * precedes a `write` event in onEvent order carries `request.resourceData`
+ * with sentinels intact. Match by path + method + groupId (best-effort)
+ * and take the closest preceding request event.
+ *
+ * When the captured stream doesn't include a paired request event,
+ * fall back to the write's post-resolution `data` (which won't have
+ * sentinel markers but is structurally correct for plain writes).
+ */
+function preResolutionDataFor(wEv, allEvents) {
+    // Find the latest request event AT OR BEFORE this write that matches.
+    const wIdx = allEvents.indexOf(wEv);
+    if (wIdx < 0)
+        return undefined;
+    for (let i = wIdx; i >= 0; i--) {
+        const e = allEvents[i];
+        if (!e || e.kind !== 'request')
+            continue;
+        if (e.path !== wEv.path)
+            continue;
+        return e.request?.resourceData;
+    }
+    return undefined;
+}
+/**
+ * Classify state-level differences against captured write metadata.
+ *
+ * Design:
+ *   - Top level: iterate every doc path present in either snapshot.
+ *     Doc-presence diffs (missing on one side) are `real-divergence`.
+ *   - Inside a doc: recursively walk both objects, building leaf-level
+ *     field paths (`profile.lastSeen`, `tags[0]`, `arr[2].nested`).
+ *     Match captured sentinel paths *exactly* at each path during the
+ *     walk; if a sentinel covers the current subtree, classify the
+ *     whole subtree as drift and STOP recursing into it. Otherwise
+ *     keep recursing until we reach a primitive leaf, then classify.
+ *
+ * Why exact-match instead of prefix-match: a sentinel at
+ * `profile.lastSeen` should classify lastSeen's drift, but a separate
+ * real change at sibling `profile.name` must still surface as
+ * `real-divergence`. The recursive walk visits each sibling independently.
+ *
+ * No shape-based inference: anything not covered by a captured
+ * sentinel and not an auto-id alias becomes `real-divergence`. The
+ * engine reports only what the captured metadata licenses it to
+ * report.
+ */
+function computeDivergences(writes, originalState, replayedState, pathAliases) {
+    const out = [];
+    const aliasedOriginals = new Set(pathAliases.keys());
+    const aliasedReplays = new Set(pathAliases.values());
+    for (const [originalPath, replayedPath] of pathAliases) {
+        out.push({ kind: 'autoid-alias', originalPath, replayedPath });
+    }
+    const sentinelsByPath = new Map();
+    for (const w of writes) {
+        if (w.sentinels && w.sentinels.length > 0) {
+            const m = new Map();
+            for (const s of w.sentinels)
+                m.set(s.field, s.kind);
+            sentinelsByPath.set(w.path, m);
+        }
+    }
+    const allPaths = new Set([...Object.keys(originalState), ...Object.keys(replayedState)]);
+    for (const path of allPaths) {
+        if (aliasedOriginals.has(path) && !(path in replayedState))
+            continue;
+        if (aliasedReplays.has(path) && !(path in originalState))
+            continue;
+        const origDoc = originalState[path];
+        const replDoc = replayedState[path];
+        if (origDoc === undefined && replDoc !== undefined) {
+            out.push({ kind: 'real-divergence', path, before: undefined, after: replDoc });
+            continue;
+        }
+        if (origDoc !== undefined && replDoc === undefined) {
+            out.push({ kind: 'real-divergence', path, before: origDoc, after: undefined });
+            continue;
+        }
+        if (origDoc === undefined || replDoc === undefined)
+            continue;
+        diffDoc(path, origDoc, replDoc, sentinelsByPath.get(path) ?? new Map(), out);
+    }
+    return out;
+}
+function diffDoc(path, original, replayed, sentinelByField, out) {
+    walk(original, replayed, '');
+    function walk(a, b, fieldPath) {
+        // Sentinel-covered subtree: classify whole subtree and stop. This
+        // also correctly handles Timestamps captured via serverTimestamp —
+        // they're objects shaped like `{ seconds, nanos }`, and we must
+        // NOT recurse past the sentinel into per-field leaves.
+        if (fieldPath !== '') {
+            const kind = sentinelByField.get(fieldPath);
+            if (kind) {
+                if (JSON.stringify(a) === JSON.stringify(b))
+                    return;
+                if (kind === 'serverTimestamp') {
+                    out.push({ kind: 'time-drift', path, field: fieldPath, before: a, after: b });
+                }
+                else {
+                    out.push({ kind: 'sentinel-drift', path, field: fieldPath, sentinelKind: kind, before: a, after: b });
+                }
+                return;
+            }
+        }
+        if (a === b)
+            return;
+        const aIsObj = a !== null && typeof a === 'object' && !Array.isArray(a);
+        const bIsObj = b !== null && typeof b === 'object' && !Array.isArray(b);
+        if (aIsObj && bIsObj) {
+            const ao = a;
+            const bo = b;
+            const keys = new Set([...Object.keys(ao), ...Object.keys(bo)]);
+            for (const k of keys) {
+                const next = fieldPath ? `${fieldPath}.${k}` : k;
+                walk(ao[k], bo[k], next);
+            }
+            return;
+        }
+        if (Array.isArray(a) && Array.isArray(b)) {
+            const len = Math.max(a.length, b.length);
+            for (let i = 0; i < len; i++) {
+                walk(a[i], b[i], `${fieldPath}[${i}]`);
+            }
+            return;
+        }
+        if (JSON.stringify(a) === JSON.stringify(b))
+            return;
+        out.push({ kind: 'real-divergence', path, field: fieldPath || undefined, before: a, after: b });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/replay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/replay/index.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/sandbox-context.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `SandboxContext` — identity-bearing handle on a {@link Sandbox}.
+ *
+ * Cheap, immutable `(sandbox, auth)` pair. Service factories
+ * (`getFirestore`, future `getDatabase`, etc.) accept a
+ * `SandboxContext` and route operations through the captured auth.
+ *
+ * Why a class (not just an interface):
+ *   - `instanceof SandboxContextImpl` enables clean routing in
+ *     service factories.
+ *   - Method-based chaining (`ctx.withAuth(...)`) reads more
+ *     naturally than a free function.
+ *   - Class identity supports future debugging hooks
+ *     (`Symbol.toStringTag`) without API breaks.
+ *
+ * Construct via `Sandbox.withAuth(...)` or chained via
+ * `SandboxContext.withAuth(...)`. Consumers don't `new` this
+ * directly — `Sandbox.withAuth` is the public entry. The class is
+ * exported anyway so service-factory authors can name the type
+ * (and so `instanceof` routing works for cross-package refs).
+ */
+import type { AuthState, Sandbox, SandboxContext } from './types.js';
+export declare class SandboxContextImpl implements SandboxContext {
+    readonly sandbox: Sandbox;
+    readonly auth: AuthState;
+    constructor(sandbox: Sandbox, auth: AuthState);
+    withAuth(auth: AuthState): SandboxContext;
+}
+/**
+ * Reject `undefined` and other clearly-malformed inputs at the
+ * `withAuth` call site. `null` is valid (anonymous);
+ * `{ uid: 'someUid' }` is valid; everything else throws so the
+ * mistake surfaces at the boundary instead of leaking into rule
+ * eval as a confusing denial.
+ *
+ * Shared between `Sandbox.withAuth` and `SandboxContext.withAuth`
+ * so both entries enforce the same validation.
+ */
+export declare function validateAuthState(auth: unknown): asserts auth is AuthState;
+//# sourceMappingURL=sandbox-context.d.ts.map

package/dist/sandbox/sandbox-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-context.d.ts","sourceRoot":"","sources":["../../src/sandbox/sandbox-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGrE,qBAAa,kBAAmB,YAAW,cAAc;aAErC,OAAO,EAAE,OAAO;aAChB,IAAI,EAAE,SAAS;gBADf,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,SAAS;IAGjC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc;CAI1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,CAkC1E"}

package/dist/sandbox/sandbox-context.js

@@ -0,0 +1,72 @@
+/**
+ * `SandboxContext` — identity-bearing handle on a {@link Sandbox}.
+ *
+ * Cheap, immutable `(sandbox, auth)` pair. Service factories
+ * (`getFirestore`, future `getDatabase`, etc.) accept a
+ * `SandboxContext` and route operations through the captured auth.
+ *
+ * Why a class (not just an interface):
+ *   - `instanceof SandboxContextImpl` enables clean routing in
+ *     service factories.
+ *   - Method-based chaining (`ctx.withAuth(...)`) reads more
+ *     naturally than a free function.
+ *   - Class identity supports future debugging hooks
+ *     (`Symbol.toStringTag`) without API breaks.
+ *
+ * Construct via `Sandbox.withAuth(...)` or chained via
+ * `SandboxContext.withAuth(...)`. Consumers don't `new` this
+ * directly — `Sandbox.withAuth` is the public entry. The class is
+ * exported anyway so service-factory authors can name the type
+ * (and so `instanceof` routing works for cross-package refs).
+ */
+import { SandboxError } from './types.js';
+export class SandboxContextImpl {
+    sandbox;
+    auth;
+    constructor(sandbox, auth) {
+        this.sandbox = sandbox;
+        this.auth = auth;
+    }
+    withAuth(auth) {
+        validateAuthState(auth);
+        return new SandboxContextImpl(this.sandbox, auth);
+    }
+}
+/**
+ * Reject `undefined` and other clearly-malformed inputs at the
+ * `withAuth` call site. `null` is valid (anonymous);
+ * `{ uid: 'someUid' }` is valid; everything else throws so the
+ * mistake surfaces at the boundary instead of leaking into rule
+ * eval as a confusing denial.
+ *
+ * Shared between `Sandbox.withAuth` and `SandboxContext.withAuth`
+ * so both entries enforce the same validation.
+ */
+export function validateAuthState(auth) {
+    if (auth === null)
+        return;
+    if (auth === undefined) {
+        throw new SandboxError({
+            code: 'invalid-argument',
+            message: 'withAuth() requires an explicit AuthState argument.',
+            remediation: [
+                'For anonymous (unauthenticated) access: withAuth(null)',
+                'For authenticated access: withAuth({ uid: "someUid" })',
+                'For custom claims: withAuth({ uid: "someUid", token: { role: "admin" } })',
+            ].join('\n'),
+        });
+    }
+    if (typeof auth !== 'object') {
+        throw new SandboxError('invalid-argument', 'withAuth() expected null or an object with a `uid` field.');
+    }
+    const obj = auth;
+    if (typeof obj.uid !== 'string' || obj.uid.length === 0) {
+        throw new SandboxError('invalid-argument', 'withAuth() requires `uid` to be a non-empty string.');
+    }
+    if ('token' in obj && obj.token !== undefined) {
+        if (obj.token === null || typeof obj.token !== 'object' || Array.isArray(obj.token)) {
+            throw new SandboxError('invalid-argument', 'withAuth() requires `token` (when present) to be a plain object.');
+        }
+    }
+}
+//# sourceMappingURL=sandbox-context.js.map

package/dist/sandbox/sandbox-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-context.js","sourceRoot":"","sources":["../../src/sandbox/sandbox-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,OAAO,kBAAkB;IAEX;IACA;IAFlB,YACkB,OAAgB,EAChB,IAAe;QADf,YAAO,GAAP,OAAO,CAAS;QAChB,SAAI,GAAJ,IAAI,CAAW;IAC9B,CAAC;IAEJ,QAAQ,CAAC,IAAe;QACtB,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACxB,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO;IAC1B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,qDAAqD;YAC9D,WAAW,EAAE;gBACX,wDAAwD;gBACxD,wDAAwD;gBACxD,2EAA2E;aAC5E,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,YAAY,CACpB,kBAAkB,EAClB,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,YAAY,CACpB,kBAAkB,EAClB,qDAAqD,CACtD,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9C,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACpF,MAAM,IAAI,YAAY,CACpB,kBAAkB,EAClB,kEAAkE,CACnE,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/sandbox/tab-sync/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Cross-tab realtime sync for the sandbox — opt-in, Firestore only.
+ *
+ * # Why this exists
+ * Production Firestore uses WebSockets; every tab's `onSnapshot` listener
+ * receives server-pushed updates from other clients automatically. The
+ * sandbox is in-process: a write in Tab A updates Tab A's in-memory
+ * LocalEnvironment, but Tab B's environment is independent — no connection
+ * between them. This module bridges the gap by broadcasting committed writes
+ * over a `BroadcastChannel` (same-origin, no server required) so a write in
+ * Tab A fires `onSnapshot` listeners in Tab B, restoring the cross-client
+ * realtime that production users expect.
+ *
+ * # Design
+ * Three message kinds:
+ *   - `write`  — a committed write event to propagate to other tabs.
+ *   - `hello`  — sent on attach: "I just joined, please send me your state."
+ *   - `state`  — reply to a specific `hello`: current snapshot of all docs.
+ *
+ * Every message carries `origin` (a per-tab random ID) so:
+ *   (a) Echo suppression: a tab ignores messages it posted itself.
+ *   (b) The `state` reply includes `to` so only the requesting tab applies it.
+ *
+ * # Echo / infinite-loop prevention
+ * The critical invariant: applying a received write to the local env MUST NOT
+ * re-broadcast that write. Without protection, the flow would be:
+ *   Tab A writes → broadcasts → Tab B receives → applies via admin → emits
+ *   `kind:'write'` onEvent → Tab B re-broadcasts → Tab A re-applies → loops.
+ *
+ * We break the loop with a boolean re-entrancy guard `applyingRemote`. It is
+ * set to `true` around the synchronous apply call; the `onEvent` subscriber
+ * checks it before broadcasting. Because `adminSetDocument` / `adminDeleteDocument`
+ * are synchronous, the guard resets to `false` before any subsequent call.
+ *
+ * # Late-join handshake (hello/state)
+ * When a tab joins after others have already written data, it sends a `hello`.
+ * A responding tab replies with `state` (its snapshot). The joining tab applies
+ * the snapshot ONLY when its own Firestore state is empty — it's a fresh tab
+ * and the snapshot is the "initial seed". We don't clobber an active tab's
+ * state with a peer's snapshot; that's a multi-writer concern outside our scope.
+ * We also apply the state only once (first `state` message wins; duplicates are
+ * ignored via the `stateApplied` flag).
+ *
+ * # Multi-writer divergence
+ * Two tabs writing to the same document concurrently will produce divergent
+ * local state (last-write-wins per tab, no conflict resolution). This is a
+ * documented limitation — the intended model is a single active writer at a
+ * time (the common UI development pattern: one user interacting with one tab).
+ * Production Firestore also converges via server ordering that the sandbox
+ * cannot replicate offline.
+ *
+ * # RTDB
+ * Real-Time Database is explicitly NOT included here. Follow-on when RTDB
+ * has its own in-process environment analogous to LocalEnvironment.
+ */
+import type { Sandbox } from '../types.js';
+/**
+ * Minimal interface that `BroadcastChannel` satisfies. Provided as an
+ * injectable seam so tests can run without a real browser channel.
+ *
+ * The real `BroadcastChannel` global satisfies this interface out of the
+ * box — pass it directly:
+ *
+ * ```ts
+ * sandbox.enableTabSync({
+ *   channel: new BroadcastChannel('pyric:tabsync'),
+ * });
+ * ```
+ *
+ * For SSR / Node environments, the default channel construction is guarded
+ * (`typeof BroadcastChannel !== 'undefined'`) so the call site doesn't need
+ * to branch — a missing global just means no sync, which is fine for server
+ * renders that only care about initial data.
+ */
+export interface BroadcastChannelLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    close(): void;
+}
+/**
+ * Options for `sandbox.enableTabSync(options?)`. All fields are optional;
+ * the defaults provide a ready-to-use configuration for browser environments.
+ */
+export interface TabSyncOptions {
+    /**
+     * The broadcast channel to use. Defaults to
+     * `new BroadcastChannel('pyric:tabsync')` when omitted and
+     * `BroadcastChannel` is available in the global scope.
+     *
+     * Pass a custom implementation for tests or Node environments.
+     */
+    channel?: BroadcastChannelLike;
+    /**
+     * A string that uniquely identifies this tab's sandbox instance.
+     * Used for echo suppression (messages with `origin === originId` are
+     * silently dropped) and for directing `state` replies to the requesting tab.
+     *
+     * Defaults to `crypto.randomUUID()` when available, otherwise a
+     * counter + process-uptime string (no `Date.now()` or `Math.random()`
+     * — those change every call and can collide in fast tests).
+     */
+    originId?: string;
+}
+/**
+ * Attach cross-tab sync to a sandbox. Called by `SandboxImpl.enableTabSync`;
+ * kept in a separate module so `sandbox-impl.ts` stays thin.
+ *
+ * Returns a `disable` function: calling it unsubscribes the onEvent listener,
+ * removes the channel message listener, and closes the channel.
+ *
+ * @param sandbox  The sandbox to sync. Must expose `onEvent`, `admin`, and `snapshot`.
+ * @param options  Optional channel and origin override.
+ */
+export declare function attachTabSync(sandbox: Sandbox, options?: TabSyncOptions): () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/tab-sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/tab-sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAsC,MAAM,aAAa,CAAC;AAI/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACnF,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACtF,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAE/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,IAAI,CAwLxF"}