@reticlehq/browser 2.0.0

package/dist/timers/clock.js

@@ -0,0 +1,80 @@
+// Fake clock: patch the APP's setTimeout/setInterval/Date.now/performance.now so the agent
+// can deterministically advance time (toasts, debounces, auto-dismiss, commit-on-blur).
+// We do NOT patch requestAnimationFrame/microtasks/MessageChannel — React's scheduler relies
+// on those, and freezing them would stall the page. Opt-in + reversible.
+let installed = false;
+let virtualNow = 0;
+let realBase = 0;
+let seq = 1;
+let tasks = [];
+let originals = null;
+export function isClockFrozen() {
+    return installed;
+}
+export function freezeClock() {
+    if (installed || typeof window === 'undefined')
+        return;
+    installed = true;
+    virtualNow = 0;
+    realBase = Date.now();
+    originals = {
+        setTimeout: window.setTimeout,
+        clearTimeout: window.clearTimeout,
+        setInterval: window.setInterval,
+        clearInterval: window.clearInterval,
+        dateNow: Date.now,
+    };
+    const schedule = (cb, delay, interval) => {
+        const id = seq;
+        seq += 1;
+        tasks.push({ id, time: virtualNow + Math.max(0, delay), cb, interval });
+        return id;
+    };
+    const cancel = (id) => {
+        tasks = tasks.filter((t) => t.id !== id);
+    };
+    window.setTimeout = ((cb, delay = 0) => schedule(cb, delay));
+    window.clearTimeout = ((id) => cancel(id));
+    window.setInterval = ((cb, delay = 0) => schedule(cb, delay, Math.max(1, delay)));
+    window.clearInterval = ((id) => cancel(id));
+    // Note: we deliberately do NOT patch performance.now — React 19's scheduler uses it to
+    // flush updates, and freezing it stalls re-renders. setTimeout/Date.now cover app timers.
+    Date.now = () => realBase + virtualNow;
+}
+/** Run all timers due within the next `ms` of virtual time, in order. */
+export function advanceClock(ms) {
+    if (!installed)
+        return;
+    const target = virtualNow + Math.max(0, ms);
+    let guard = 0;
+    for (;;) {
+        guard += 1;
+        if (guard > 100000)
+            break;
+        const due = tasks.filter((t) => t.time <= target).sort((a, b) => a.time - b.time);
+        const next = due[0];
+        if (next === undefined)
+            break;
+        tasks = tasks.filter((t) => t !== next);
+        virtualNow = next.time;
+        next.cb();
+        if (next.interval !== undefined) {
+            tasks.push({ ...next, id: seq++, time: virtualNow + next.interval });
+        }
+    }
+    virtualNow = target;
+}
+export function resetClock() {
+    if (!installed || originals === null)
+        return;
+    window.setTimeout = originals.setTimeout;
+    window.clearTimeout = originals.clearTimeout;
+    window.setInterval = originals.setInterval;
+    window.clearInterval = originals.clearInterval;
+    Date.now = originals.dateNow;
+    originals = null;
+    tasks = [];
+    installed = false;
+    virtualNow = 0;
+}
+//# sourceMappingURL=clock.js.map

package/dist/timers/clock.js.map

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

package/dist/timers/native-timers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Monotonic "now" bound at load. clock.ts deliberately does NOT patch performance.now, so this
+ * stays live even when the app clock (reticle_clock) is frozen — the presenter state machine relies
+ * on it. Falls back to 0 in SSR where performance is absent.
+ */
+export declare const nativeNow: () => number;
+export declare const nativeSetTimeout: (cb: () => void, ms?: number) => number;
+export declare const nativeClearTimeout: (id: number) => void;
+/**
+ * A self-rescheduling interval built on the bound real timer. We do NOT use
+ * `setInterval` because reticle_clock can freeze the app's timers — a native, pre-bound
+ * timer keeps the page-health heartbeat ticking so a frozen clock never reads as stale.
+ * Returns a stop function.
+ */
+export declare const nativeSetInterval: (cb: () => void, ms: number) => (() => void);
+/** Outcome of a bounded frame/settle wait. */
+interface FrameOutcome {
+    /** true = a real rAF fired within budget; false = the timeout fallback fired. */
+    settled: boolean;
+}
+/**
+ * One animation frame, BOUNDED: races real rAF against a nativeSetTimeout(FRAME_BUDGET_MS).
+ * In a throttled/background tab rAF never fires, so the timer wins and we still resolve.
+ * Returns whether rAF won (settled:true) or the fallback fired (settled:false).
+ */
+export declare const boundedFrame: (budgetMs?: number) => Promise<FrameOutcome>;
+/** One animation frame, BOUNDED — delegates to boundedFrame so it never hangs in a throttled tab. */
+export declare const nativeFrame: () => Promise<void>;
+/**
+ * "Settle": let the framework flush. Awaits a microtask then one BOUNDED animation frame so a
+ * React commit (and the MutationObserver records it triggers) lands before the caller returns.
+ * Uses native timers/rAF so a frozen app clock (reticle_clock) never stalls it, AND is bounded so a
+ * throttled/background tab (rAF never fires) never deadlocks. Reports whether a real frame fired.
+ */
+export declare const settle: (budgetMs?: number) => Promise<FrameOutcome>;
+export {};
+//# sourceMappingURL=native-timers.d.ts.map

package/dist/timers/native-timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-timers.d.ts","sourceRoot":"","sources":["../../src/timers/native-timers.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,MAA2C,CAAC;AAEzE,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,IAAI,EAAE,WAAM,KAAG,MACU,CAAC;AAErE,eAAO,MAAM,kBAAkB,GAAI,IAAI,MAAM,KAAG,IAE/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,KAAG,CAAC,MAAM,IAAI,CAczE,CAAC;AAKF,8CAA8C;AAC9C,UAAU,YAAY;IACpB,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,iBAA0B,KAAG,OAAO,CAAC,YAAY,CAY1E,CAAC;AAEL,qGAAqG;AACrG,eAAO,MAAM,WAAW,QAAO,OAAO,CAAC,IAAI,CAAyC,CAAC;AAErF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAU,iBAA0B,KAAG,OAAO,CAAC,YAAY,CAG7E,CAAC"}

package/dist/timers/native-timers.js

@@ -0,0 +1,79 @@
+// Native timers captured (bound) at module load, BEFORE any fake-clock patch. The SDK uses
+// these for its own internal waits (presenter pacing, hover dwell, transport reconnect) so
+// that freezing the app's clock (reticle_clock) never deadlocks Reticle itself.
+//
+// Important: we bind the reference now. Resolving `setTimeout` at call time would pick up the
+// patched (frozen) timer once reticle_clock freezes the clock — which would hang the SDK.
+const g = globalThis;
+const realSetTimeout = typeof g.setTimeout === 'function' ? g.setTimeout.bind(g) : null;
+const realClearTimeout = typeof g.clearTimeout === 'function' ? g.clearTimeout.bind(g) : null;
+const realRaf = typeof g.requestAnimationFrame === 'function' ? g.requestAnimationFrame.bind(g) : null;
+const realPerfNow = typeof g.performance?.now === 'function' ? g.performance.now.bind(g.performance) : null;
+/**
+ * Monotonic "now" bound at load. clock.ts deliberately does NOT patch performance.now, so this
+ * stays live even when the app clock (reticle_clock) is frozen — the presenter state machine relies
+ * on it. Falls back to 0 in SSR where performance is absent.
+ */
+export const nativeNow = () => (realPerfNow ? realPerfNow() : 0);
+export const nativeSetTimeout = (cb, ms = 0) => realSetTimeout ? realSetTimeout(cb, ms) : 0;
+export const nativeClearTimeout = (id) => {
+    realClearTimeout?.(id);
+};
+/**
+ * A self-rescheduling interval built on the bound real timer. We do NOT use
+ * `setInterval` because reticle_clock can freeze the app's timers — a native, pre-bound
+ * timer keeps the page-health heartbeat ticking so a frozen clock never reads as stale.
+ * Returns a stop function.
+ */
+export const nativeSetInterval = (cb, ms) => {
+    let stopped = false;
+    let id = 0;
+    const tick = () => {
+        if (stopped)
+            return;
+        cb();
+        if (stopped)
+            return;
+        id = nativeSetTimeout(tick, ms);
+    };
+    id = nativeSetTimeout(tick, ms);
+    return () => {
+        stopped = true;
+        nativeClearTimeout(id);
+    };
+};
+/** Max time we wait for a real animation frame before giving up and resolving anyway. */
+const FRAME_BUDGET_MS = 200;
+/**
+ * One animation frame, BOUNDED: races real rAF against a nativeSetTimeout(FRAME_BUDGET_MS).
+ * In a throttled/background tab rAF never fires, so the timer wins and we still resolve.
+ * Returns whether rAF won (settled:true) or the fallback fired (settled:false).
+ */
+export const boundedFrame = (budgetMs = FRAME_BUDGET_MS) => new Promise((resolve) => {
+    let done = false;
+    const finish = (settled) => {
+        if (done)
+            return;
+        done = true;
+        nativeClearTimeout(timer);
+        resolve({ settled });
+    };
+    const timer = nativeSetTimeout(() => finish(false), budgetMs);
+    if (realRaf)
+        realRaf(() => finish(true));
+    else
+        nativeSetTimeout(() => finish(true), 0); // jsdom/SSR: 0ms timer "is" the frame
+});
+/** One animation frame, BOUNDED — delegates to boundedFrame so it never hangs in a throttled tab. */
+export const nativeFrame = () => boundedFrame().then(() => undefined);
+/**
+ * "Settle": let the framework flush. Awaits a microtask then one BOUNDED animation frame so a
+ * React commit (and the MutationObserver records it triggers) lands before the caller returns.
+ * Uses native timers/rAF so a frozen app clock (reticle_clock) never stalls it, AND is bounded so a
+ * throttled/background tab (rAF never fires) never deadlocks. Reports whether a real frame fired.
+ */
+export const settle = async (budgetMs = FRAME_BUDGET_MS) => {
+    await Promise.resolve(); // drain the current microtask queue (React scheduler tick)
+    return boundedFrame(budgetMs); // one bounded frame so commit + MutationObserver records flush
+};
+//# sourceMappingURL=native-timers.js.map

package/dist/timers/native-timers.js.map

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

package/dist/transport/transport.d.ts

@@ -0,0 +1,54 @@
+import { type CommandMessage, type HelloMessage, type ReticleEvent } from '@reticlehq/core';
+export interface CommandOutcome {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+interface TransportDeps {
+    url: string;
+    hello: () => HelloMessage;
+    handleCommand: (command: CommandMessage) => Promise<CommandOutcome>;
+    /** Unthrottled, unpatched clock for bridge-loss timing. Defaults to nativeNow (performance.now). */
+    now?: () => number;
+    /** Fired each time the WebSocket (re-)connects to the bridge. */
+    onConnected?: () => void;
+    /**
+     * Liveness fallback: fired once when the bridge has been unreachable for SESSION_LIFECYCLE
+     * .BRIDGE_LOST_MS — i.e. the server/agent process is gone, so no server-pushed end can arrive and
+     * the SDK must end the session itself instead of showing a forever-"running" HUD.
+     */
+    onConnectionLost?: () => void;
+    /**
+     * Called with the cumulative drop count each time the outbound queue overflows. The
+     * caller (Reticle) emits a synthetic TRANSPORT_OVERFLOW event so the agent learns about gaps.
+     */
+    onOverflow?: (dropped: number) => void;
+    /**
+     * Fired once when the VERY FIRST connection keeps failing (never opened) — i.e. the bridge is
+     * unreachable at this URL, most often a wrong port or a container/WSL network boundary. Distinct
+     * from onConnectionLost (which is about losing an ALREADY-established session). The caller surfaces
+     * an actionable hint instead of retrying silently forever.
+     */
+    onUnreachable?: (detail: {
+        url: string;
+        attempts: number;
+    }) => void;
+    /**
+     * Subscribe to "the tab became visible again" (default: document `visibilitychange`). Browsers
+     * throttle or suspend timers in a backgrounded tab, so the 1s reconnect loop stalls while hidden —
+     * a bridge blip during sleep/background otherwise leaves the panel stuck on "ENDED" until a manual
+     * reload. On foreground we retry IMMEDIATELY instead of waiting for the throttled timer. Returns an
+     * unsubscribe; injected so a test can drive visibility without a real document.
+     */
+    onVisible?: (handler: () => void) => () => void;
+}
+/** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */
+export declare class Transport {
+    #private;
+    constructor(deps: TransportDeps);
+    connect(): void;
+    sendEvent(event: ReticleEvent): void;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,YAAY,CAAC;IAC1B,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpE;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CACjD;AAiBD,4FAA4F;AAC5F,qBAAa,SAAS;;gBAoBR,IAAI,EAAE,aAAa;IAK/B,OAAO,IAAI,IAAI;IAqHf,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAepC,KAAK,IAAI,IAAI;CAOd"}

package/dist/transport/transport.js

@@ -0,0 +1,182 @@
+import { CommandMessageSchema, MessageKind, SESSION_LIFECYCLE, } from '@reticlehq/core';
+import { nativeSetTimeout, nativeNow } from '../timers/native-timers.js';
+import { safeStringify } from '../security/serialization.js';
+/** Default visibility source: fire `handler` whenever the document returns to the foreground. */
+function subscribeDocumentVisible(handler) {
+    if (typeof document === 'undefined')
+        return () => undefined;
+    const listener = () => {
+        if (document.visibilityState === 'visible')
+            handler();
+    };
+    document.addEventListener('visibilitychange', listener);
+    return () => document.removeEventListener('visibilitychange', listener);
+}
+const RECONNECT_DELAY_MS = 1000;
+const MAX_QUEUE = 500;
+/** Warn that the bridge is unreachable after this many consecutive failed INITIAL connects (~3s). */
+const UNREACHABLE_WARN_AFTER = 3;
+/** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */
+export class Transport {
+    #ws;
+    #queue = [];
+    #closed = false;
+    /** When the current continuous outage began (nativeNow), or undefined while connected. */
+    #disconnectedSince;
+    /** Whether onConnectionLost has already fired for the current outage (fire-once). */
+    #lost = false;
+    /** True once the socket has opened at least once — gates the "unreachable" first-connect warning. */
+    #everConnected = false;
+    /** Consecutive failed INITIAL connects (before any success). */
+    #initialFailures = 0;
+    /** Whether the unreachable warning has fired (fire-once). */
+    #warnedUnreachable = false;
+    #overflowCount = 0;
+    /** Teardown for the visibility subscription (foreground-triggered reconnect), while connected. */
+    #unsubscribeVisible;
+    #deps;
+    #now;
+    constructor(deps) {
+        this.#deps = deps;
+        this.#now = deps.now ?? nativeNow;
+    }
+    connect() {
+        if (typeof WebSocket === 'undefined')
+            return;
+        this.#closed = false;
+        this.#unsubscribeVisible ??= (this.#deps.onVisible ?? subscribeDocumentVisible)(() => this.#onVisible());
+        this.#open();
+    }
+    /**
+     * The tab returned to the foreground. If we're disconnected (and not deliberately closed), reconnect
+     * NOW — a hidden tab's throttled timer may be minutes from firing. A no-op when a socket already
+     * exists (connected or mid-connect), so we never open a duplicate racing the scheduled retry.
+     */
+    #onVisible() {
+        if (this.#closed || this.#ws !== undefined)
+            return;
+        this.#open();
+    }
+    #open() {
+        const ws = new WebSocket(this.#deps.url);
+        this.#ws = ws;
+        ws.onopen = () => {
+            this.#disconnectedSince = undefined; // healthy again — reset the loss timer
+            this.#lost = false;
+            this.#everConnected = true; // a real connection happened ⇒ never warn "unreachable"
+            // HELLO is SDK-owned schema data. Preserve its pairing token; the generic sanitizer
+            // intentionally redacts fields named "token" from app-controlled payloads.
+            ws.send(JSON.stringify(this.#deps.hello()));
+            for (const msg of this.#queue)
+                ws.send(msg);
+            this.#queue = [];
+            this.#deps.onConnected?.();
+        };
+        ws.onmessage = (event) => {
+            const data = event.data;
+            void this.#onMessage(typeof data === 'string' ? data : String(data));
+        };
+        ws.onclose = () => {
+            this.#ws = undefined;
+            this.#noteOutage();
+            this.#noteInitialFailure();
+            if (!this.#closed)
+                nativeSetTimeout(() => this.#reopen(), RECONNECT_DELAY_MS);
+        };
+        ws.onerror = () => {
+            ws.close();
+        };
+    }
+    /**
+     * A scheduled reconnect — skipped if the SDK was torn down, or if a foreground-triggered reconnect
+     * already opened a socket (guard against the throttled timer racing #onVisible into a duplicate).
+     */
+    #reopen() {
+        if (this.#closed || this.#ws !== undefined)
+            return;
+        this.#open();
+    }
+    /**
+     * The first connection has never opened: count failures and, once they cross the threshold, fire
+     * onUnreachable ONCE so the app surfaces an actionable hint (wrong port / container network) rather
+     * than retrying silently forever. Suppressed entirely once any connection has succeeded.
+     */
+    #noteInitialFailure() {
+        if (this.#everConnected || this.#warnedUnreachable)
+            return;
+        this.#initialFailures += 1;
+        if (this.#initialFailures >= UNREACHABLE_WARN_AFTER) {
+            this.#warnedUnreachable = true;
+            this.#deps.onUnreachable?.({ url: this.#deps.url, attempts: this.#initialFailures });
+        }
+    }
+    /**
+     * Track how long the bridge has been unreachable. Once the outage exceeds BRIDGE_LOST_MS, fire
+     * onConnectionLost exactly once so the SDK can end the session (the server/agent is gone and can
+     * no longer push an end itself).
+     */
+    #noteOutage() {
+        const at = this.#now();
+        this.#disconnectedSince ??= at;
+        if (!this.#lost && at - this.#disconnectedSince >= SESSION_LIFECYCLE.BRIDGE_LOST_MS) {
+            this.#lost = true;
+            this.#deps.onConnectionLost?.();
+        }
+    }
+    async #onMessage(text) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        const result = CommandMessageSchema.safeParse(parsed);
+        if (!result.success)
+            return;
+        const command = result.data;
+        const currentSessionId = this.#deps.hello().sessionId;
+        if (command.sessionId !== undefined && command.sessionId !== currentSessionId)
+            return;
+        let outcome;
+        try {
+            outcome = await this.#deps.handleCommand(command);
+        }
+        catch (error) {
+            outcome = {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        this.#sendRaw(safeStringify({
+            kind: MessageKind.COMMAND_RESULT,
+            id: command.id,
+            ok: outcome.ok,
+            result: outcome.result,
+            error: outcome.error,
+        }));
+    }
+    sendEvent(event) {
+        this.#sendRaw(safeStringify({ kind: MessageKind.EVENT, event }));
+    }
+    #sendRaw(text) {
+        if (this.#ws !== undefined && this.#ws.readyState === WebSocket.OPEN) {
+            this.#ws.send(text);
+        }
+        else if (this.#queue.length < MAX_QUEUE) {
+            this.#queue.push(text);
+        }
+        else {
+            this.#overflowCount += 1;
+            this.#deps.onOverflow?.(this.#overflowCount);
+        }
+    }
+    close() {
+        this.#closed = true;
+        this.#unsubscribeVisible?.();
+        this.#unsubscribeVisible = undefined;
+        this.#ws?.close();
+        this.#ws = undefined;
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport/transport.js.map

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

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@reticlehq/browser",
+  "version": "2.0.0",
+  "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@reticlehq/core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^28.0.3",
+    "jsdom": "^29.1.1"
+  },
+  "license": "Apache-2.0",
+  "author": "Reticle contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reticlehq/reticle.git",
+    "directory": "packages/browser"
+  },
+  "homepage": "https://github.com/reticlehq/reticle#readme",
+  "bugs": "https://github.com/reticlehq/reticle/issues",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "mcp",
+    "ai-agents",
+    "testing",
+    "instrumentation",
+    "observability"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "lint": "eslint src",
+    "test:unit": "vitest run src --passWithNoTests"
+  }
+}