@reticlehq/browser 3.8.2 → 3.10.0

package/dist/reticle.d.ts

@@ -1,27 +1,11 @@
-import { EventType, RETICLE_URL_PARAM, HudVisibility, type ReticleEvent } from '@reticlehq/core';
+import { EventType, RETICLE_URL_PARAM, type ReticleEvent } from '@reticlehq/core';
 import { type CapabilitiesInput } from './registry/capabilities.js';
 import { type ReticleConnectOptions } from './connect-options.js';
-export { helloMode, shouldBlockProduction } from './connect-options.js';
+export { helloMode, hudWithoutPanel, reticleParamsFromSearch, shouldBlockProduction, } from './connect-options.js';
 export type { ReticleConnectOptions };
-export declare function withBridgePath(bridgeUrl: string): {
-    url: string;
-    adjusted: boolean;
-};
-export declare function connectionPolicy(pageHostname: string, bridgeUrl: string, allowNonLocalhost: boolean, token: string | undefined, pageProtocol?: string): {
-    allowed: boolean;
-    reason?: string;
-};
+export { connectionPolicy, withBridgePath } from './transport/bridge-url.js';
 export declare function resolveSessionLabel(option: string | undefined, gen: () => string): string;
 export { RETICLE_URL_PARAM };
-export declare function reticleParamsFromSearch(search: string): {
-    session?: string;
-    projectId?: string;
-    hud?: HudVisibility;
-};
-export declare function hudWithoutPanel(hud: HudVisibility | undefined): {
-    remember?: HudVisibility;
-    placed: HudVisibility[];
-};
 export declare function resolveConnectIdentity(options: {
     session?: string;
     projectId?: string;

package/dist/reticle.js

@@ -3,8 +3,8 @@ import { trackBusy } from './busy.js';
 import { declareRoutes } from './observers/route.js';
 import { setOutwardPolicy } from './actions/danger-context.js';
 import { coverageMarkers, notApplicableFor } from './dom/addressing/coverage-markers.js';
-import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, RETICLE_WS_PATH, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, buildRedactionPolicy, isLoopbackHostname, isLocalPage, setActiveRedactionPolicy, wireRedactionKeys, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, CONTRACT_FINGERPRINT, CONTRACT_PARTS, newDocumentId, NO_EDITS_OBSERVED, PresenterMode, CommandActor, HudCorner, HudVisibility, } from '@reticlehq/core';
-import { rememberSessionLabel } from './session-continuity.js';
+import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, RETICLE_WS_PATH, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, buildRedactionPolicy, setActiveRedactionPolicy, wireRedactionKeys, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, CONTRACT_FINGERPRINT, CONTRACT_PARTS, newDocumentId, NO_EDITS_OBSERVED, PresenterMode, CommandActor, HudCorner, HudVisibility, } from '@reticlehq/core';
+import { rememberSessionLabel, tabSessionStore } from './session-continuity.js';
 import { editEpoch } from './edit-epoch.js';
 import { createCommandRegistry, RELOAD_CACHE_BUST_PARAM, } from './commands/commands.js';
 import { Transport } from './transport/transport.js';
@@ -24,60 +24,11 @@ import { actionVerb } from './presenter/chrome/presenter-verbs.js';
 import { str, refLabel, modeForCommand, presentStatus } from './reticle-presenter-helpers.js';
 import { resetClock } from './timers/clock.js';
 import { nativeWarn } from './timers/console/native-console.js';
-import { installRecorder } from './recorder/recorder.js';
 import { Annotator } from './review/annotator.js';
-import { helloMode, leaseToken, shouldBlockProduction, } from './connect-options.js';
-export { helloMode, shouldBlockProduction } from './connect-options.js';
-export function withBridgePath(bridgeUrl) {
-    let parsed;
-    try {
-        parsed = new URL(bridgeUrl);
-    }
-    catch {
-        return { url: bridgeUrl, adjusted: false };
-    }
-    if ((parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') ||
-        (parsed.pathname !== '' && parsed.pathname !== '/')) {
-        return { url: bridgeUrl, adjusted: false };
-    }
-    parsed.pathname = RETICLE_WS_PATH;
-    return { url: parsed.toString(), adjusted: true };
-}
-export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, token, pageProtocol = 'http:') {
-    let bridge;
-    try {
-        bridge = new URL(bridgeUrl);
-    }
-    catch {
-        return { allowed: false, reason: 'invalid Reticle bridge URL' };
-    }
-    if (bridge.protocol !== 'ws:' && bridge.protocol !== 'wss:') {
-        return { allowed: false, reason: 'Reticle bridge URL must use ws:// or wss://' };
-    }
-    if ((token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
-        return {
-            allowed: false,
-            reason: `Reticle pairing token exceeds ${String(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH)} characters`,
-        };
-    }
-    const remoteBridge = !isLoopbackHostname(bridge.hostname);
-    if (remoteBridge && bridge.protocol !== 'wss:') {
-        return { allowed: false, reason: 'a non-local Reticle bridge must use wss://' };
-    }
-    const remote = !isLocalPage(pageProtocol, pageHostname) || remoteBridge;
-    if (!remote)
-        return { allowed: true };
-    if (!allowNonLocalhost) {
-        return {
-            allowed: false,
-            reason: 'Reticle is disabled outside localhost unless allowNonLocalhost is explicitly enabled',
-        };
-    }
-    if (token === undefined || 0 === token.length) {
-        return { allowed: false, reason: 'a pairing token is required outside localhost' };
-    }
-    return { allowed: true };
-}
+import { helloMode, hudWithoutPanel, leaseToken, oneOf, reticleParamsFromSearch, shouldBlockProduction, } from './connect-options.js';
+export { helloMode, hudWithoutPanel, reticleParamsFromSearch, shouldBlockProduction, } from './connect-options.js';
+export { connectionPolicy, withBridgePath } from './transport/bridge-url.js';
+import { connectionPolicy, withBridgePath } from './transport/bridge-url.js';
 const MAX_PENDING_NARRATIONS = 20;
 const KILLED_MESSAGE = '[Reticle] killed for this page. Restart your dev server or reload the page to bring it back.';
 const BRIDGE_LOST_SUMMARY = 'Session ended - lost connection to Reticle (the agent is no longer running).';
@@ -88,33 +39,15 @@ export { RETICLE_URL_PARAM };
 function stripReloadCacheBustParam() {
     try {
         const current = new URL(window.location.href);
-        if (!current.searchParams.has(RELOAD_CACHE_BUST_PARAM))
+        if (!current.searchParams.has(RELOAD_CACHE_BUST_PARAM)) {
             return;
+        }
         current.searchParams.delete(RELOAD_CACHE_BUST_PARAM);
         window.history.replaceState(window.history.state, '', current.toString());
     }
     catch {
     }
 }
-export function reticleParamsFromSearch(search) {
-    const params = new URLSearchParams(search);
-    const out = {};
-    const session = params.get(RETICLE_URL_PARAM.SESSION);
-    const projectId = params.get(RETICLE_URL_PARAM.PROJECT);
-    const hud = oneOf(HudVisibility, params.get(RETICLE_URL_PARAM.HUD));
-    if (session !== null && session.length > 0)
-        out.session = session;
-    if (projectId !== null && projectId.length > 0)
-        out.projectId = projectId;
-    if (hud !== undefined)
-        out.hud = hud;
-    return out;
-}
-export function hudWithoutPanel(hud) {
-    if (hud === undefined)
-        return { placed: [] };
-    return { remember: hud, placed: HudVisibility.SHOWN === hud ? [] : [hud] };
-}
 export function resolveConnectIdentity(options, search) {
     const url = reticleParamsFromSearch(search);
     const explicitSession = options.session !== undefined && options.session !== SESSION_AUTO ? options.session : undefined;
@@ -173,8 +106,9 @@ export class Reticle {
             this.#adoptLateProjectId(options);
             return;
         }
-        if ('undefined' === typeof window || 'undefined' === typeof document)
+        if ('undefined' === typeof window || 'undefined' === typeof document) {
             return;
+        }
         const proc = globalThis.process;
         const nodeEnv = proc?.env?.['NODE_ENV'];
         if (shouldBlockProduction(nodeEnv, true === options.allowInProduction)) {
@@ -203,7 +137,7 @@ export class Reticle {
                 : undefined;
         const identity = resolveConnectIdentity(options, window.location.search);
         const explicitSession = resolveSessionLabel(identity.session, () => '');
-        this.#session = rememberSessionLabel(explicitSession.length > 0 ? explicitSession : undefined, 'undefined' === typeof globalThis.sessionStorage ? undefined : globalThis.sessionStorage, () => 'function' === typeof globalThis.crypto?.randomUUID
+        this.#session = rememberSessionLabel(explicitSession.length > 0 ? explicitSession : undefined, tabSessionStore(window), () => 'function' === typeof globalThis.crypto?.randomUUID
             ? `s${globalThis.crypto.randomUUID()}`
             : `s${Date.now().toString(36)}`);
         this.#token =
@@ -253,11 +187,19 @@ export class Reticle {
             this.#overlay.update({ connected: true, events: 0 });
         }
         this.#pendingHud = reticleParamsFromSearch(window.location.search).hud;
-        if (options.present !== false && HudVisibility.REMOVED !== this.#pendingHud)
+        if (options.present !== false && HudVisibility.REMOVED !== this.#pendingHud) {
             this.#fetchAndShowPanel(options);
+        }
         if (true === options.recorder) {
-            this.#recorder = installRecorder({ emit, now: () => Date.now() });
-            this.#recorder.mount();
+            void import('./recorder/recorder.js')
+                .then(({ installRecorder }) => {
+                if (!this.#connected || this.#recorder !== undefined) {
+                    return;
+                }
+                this.#recorder = installRecorder({ emit, now: () => Date.now() });
+                this.#recorder.mount();
+            })
+                .catch(() => undefined);
         }
         if (options.annotate ?? options.present !== false) {
             this.#annotator = new Annotator({
@@ -273,32 +215,40 @@ export class Reticle {
         this.#connected = true;
     }
     #fetchAndShowPanel(options) {
-        if (this.#panelRequested)
+        if (this.#panelRequested) {
             return;
+        }
         this.#panelRequested = true;
         void import('./presenter/presenter.js')
             .then(({ Presenter }) => import('./presenter/presenter-settings.js').then((settings) => ({ Presenter, settings })))
             .then(({ Presenter, settings }) => {
-            if (!this.#connected)
+            if (!this.#connected) {
                 return;
+            }
             this.#readPanelSettings = settings.getPresenterSettings;
             const panelOptions = {};
-            if (options.pace !== undefined)
+            if (options.pace !== undefined) {
                 panelOptions.paceMs = options.pace;
+            }
             if (options.narrationDwellMs !== undefined) {
                 panelOptions.narrationDwellMs = options.narrationDwellMs;
             }
-            if (options.border !== undefined)
+            if (options.border !== undefined) {
                 panelOptions.border = options.border;
-            if (options.logMax !== undefined)
+            }
+            if (options.logMax !== undefined) {
                 panelOptions.logMax = options.logMax;
-            if (options.endedFadeMs !== undefined)
+            }
+            if (options.endedFadeMs !== undefined) {
                 panelOptions.endedFadeMs = options.endedFadeMs;
-            if (options.idleEndMs !== undefined)
+            }
+            if (options.idleEndMs !== undefined) {
                 panelOptions.idleEndMs = options.idleEndMs;
+            }
             panelOptions.sessionId = this.#session;
-            if (this.#projectId !== undefined)
+            if (this.#projectId !== undefined) {
                 panelOptions.projectId = this.#projectId;
+            }
             panelOptions.onControl = (intent) => this.#emit(EventType.HUMAN_CONTROL, intent.text !== undefined
                 ? { kind: intent.kind, text: intent.text }
                 : { kind: intent.kind });
@@ -311,19 +261,24 @@ export class Reticle {
             this.#presenter = panel;
             panel.mount();
             panel.showSdkVersion(this.#sdkVersion);
-            for (const buffered of this.#pendingPushes.values())
+            for (const buffered of this.#pendingPushes.values()) {
                 panel.handlePush(buffered);
+            }
             this.#pendingPushes.clear();
-            if (0 < this.#pendingNarrations.length)
+            if (0 < this.#pendingNarrations.length) {
                 panel.sessionStart();
-            for (const early of this.#pendingNarrations.splice(0))
+            }
+            for (const early of this.#pendingNarrations.splice(0)) {
                 panel.narrate(early.text, early.level, early.actor, early.summary);
-            if (this.#pendingHud !== undefined)
+            }
+            if (this.#pendingHud !== undefined) {
                 panel.placeHud(this.#pendingHud, undefined);
+            }
             this.#pendingHud = undefined;
             void import('./presenter/tour/tour.js').then((tour) => {
-                if (!this.#connected)
+                if (!this.#connected) {
                     return;
+                }
                 const shown = tour.mountTour({
                     document,
                     storage: tour.safeLocalStorage(),
@@ -334,21 +289,25 @@ export class Reticle {
                     copy: (text) => navigator.clipboard?.writeText(text).then(() => true, () => false) ?? false,
                     select: (element) => {
                         const selection = window.getSelection();
-                        if (null === selection)
+                        if (null === selection) {
                             return;
+                        }
                         const range = document.createRange();
                         range.selectNodeContents(element);
                         selection.removeAllRanges();
                         selection.addRange(range);
                     },
                 });
-                if (shown !== undefined)
+                if (shown !== undefined) {
                     this.#teardowns.push(shown.destroy);
+                }
             });
-            if (this.#bridgeConnected)
+            if (this.#bridgeConnected) {
                 panel.sessionStart();
-            if (this.#annotator !== undefined)
+            }
+            if (this.#annotator !== undefined) {
                 panel.bindAnnotator(this.#annotator);
+            }
         })
             .catch(() => {
         });
@@ -371,8 +330,9 @@ export class Reticle {
         this.#emit(EventType.STATE_CHANGE, { name, value });
     }
     renderCommit(commits) {
-        if (commits > 0)
+        if (commits > 0) {
             this.#emit(EventType.RENDER_COMMIT, { commits });
+        }
     }
     describe(input) {
         registerCapabilities(input);
@@ -384,8 +344,9 @@ export class Reticle {
         editEpoch.observe(hot);
     }
     disconnect() {
-        if (!this.#connected)
+        if (!this.#connected) {
             return;
+        }
         runTeardowns(this.#emit, this.#teardowns);
         this.#teardowns = [];
         this.#transport?.close();
@@ -417,8 +378,9 @@ export class Reticle {
             this.#transport?.sendEvent(event);
             this.#eventCount += 1;
             this.#overlay?.update({ connected: true, events: this.#eventCount });
-            if (type === EventType.ROUTE_CHANGE)
+            if (type === EventType.ROUTE_CHANGE) {
                 this.#presenter?.refilterFlows();
+            }
         }
         catch {
         }
@@ -428,11 +390,13 @@ export class Reticle {
         this.#redactKeys = wireRedactionKeys(config);
     }
     #adoptLateProjectId(options) {
-        if (this.#projectId !== undefined)
+        if (this.#projectId !== undefined) {
             return;
+        }
         const late = resolveConnectIdentity(options, window.location.search).projectId;
-        if (late === undefined)
+        if (late === undefined) {
             return;
+        }
         this.#projectId = late;
         this.#transport?.reannounce();
     }
@@ -472,13 +436,14 @@ export class Reticle {
         }
         if (command.name === ReticleCommand.NARRATE) {
             if (this.#presenter === undefined && this.#panelRequested) {
-                if (this.#pendingNarrations.length < MAX_PENDING_NARRATIONS)
+                if (this.#pendingNarrations.length < MAX_PENDING_NARRATIONS) {
                     this.#pendingNarrations.push({
                         text: str(command.args['text']),
                         level: str(command.args['level'], 'info'),
                         actor: narrationActor(command.args),
                         summary: true === command.args['summary'],
                     });
+                }
                 return { ok: true, result: { shown: false, buffered: true } };
             }
             this.#presenter?.sessionStart();
@@ -487,18 +452,21 @@ export class Reticle {
         }
         if (command.name === ReticleCommand.SESSION_CONFIG) {
             const idleEndMs = command.args['idleEndMs'];
-            if ('number' === typeof idleEndMs)
+            if ('number' === typeof idleEndMs) {
                 this.#presenter?.setIdleEndMs(idleEndMs);
+            }
             const hud = oneOf(HudVisibility, command.args['hud']);
             const corner = oneOf(HudCorner, command.args['corner']);
             const presenter = this.#presenter;
             let placed;
-            if (presenter !== undefined)
+            if (presenter !== undefined) {
                 placed = presenter.placeHud(hud, corner);
+            }
             else {
                 const early = hudWithoutPanel(hud);
-                if (early.remember !== undefined)
+                if (early.remember !== undefined) {
                     this.#pendingHud = early.remember;
+                }
                 placed = early.placed;
             }
             return {
@@ -548,8 +516,9 @@ export class Reticle {
     }
     async #presentBefore(command) {
         const p = this.#presenter;
-        if (p === undefined)
+        if (p === undefined) {
             return;
+        }
         p.setMode(modeForCommand(command.name));
         this.#actHandle = undefined;
         const actor = CommandActor.HARNESS === command.by ? LOG_ACTOR.HARNESS : LOG_ACTOR.AGENT;
@@ -579,6 +548,3 @@ export class Reticle {
 function narrationActor(args) {
     return CommandActor.HARNESS === args['actor'] ? LOG_ACTOR.HARNESS : LOG_ACTOR.AGENT;
 }
-function oneOf(values, raw) {
-    return Object.values(values).includes(raw) ? raw : undefined;
-}

package/dist/review/annotator.js

@@ -69,6 +69,10 @@ export class Annotator {
     mount() {
         if (this.#root !== undefined || 'undefined' === typeof document)
             return;
+        if (null === document.head || null === document.body) {
+            document.addEventListener('DOMContentLoaded', () => this.mount(), { once: true });
+            return;
+        }
         const style = document.createElement('style');
         style.setAttribute(MARK_ATTR, 'style');
         style.textContent = ANNOTATOR_CSS;

package/dist/security/serialization.js

@@ -2,6 +2,12 @@ import { REDACTED_VALUE, TRANSPORT_LIMITS, isSensitiveKey, scrubKnownSecrets, }
 const TRUNCATED_VALUE = '[TRUNCATED]';
 const UNSERIALIZABLE_VALUE = '[UNSERIALIZABLE]';
 const OMIT_VALUE = Symbol('omit');
+const PROMISE_SUMMARY = '[Promise]';
+const WINDOW_SUMMARY = '[Window]';
+const WINDOW_TAG = 'Window';
+const PROMISE_TAG = 'Promise';
+const PLAIN_OBJECT_TAG = 'Object';
+const OBJECT_TAG_PATTERN = /^\[object (\w+)\]$/;
 const MAX_KEY_LENGTH = 256;
 const MAX_TOTAL_CHARACTERS = Math.floor(TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / 4);
 const MAX_TOTAL_NODES = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS * 5;
@@ -18,6 +24,30 @@ function boundedString(value, state, max) {
     state.remainingCharacters -= truncated.length;
     return truncated;
 }
+function opaqueSummary(value) {
+    try {
+        const tag = OBJECT_TAG_PATTERN.exec(Object.prototype.toString.call(value))?.[1];
+        if (WINDOW_TAG === tag) {
+            return WINDOW_SUMMARY;
+        }
+        if (PROMISE_TAG === tag) {
+            return PROMISE_SUMMARY;
+        }
+        if (tag !== undefined && PLAIN_OBJECT_TAG !== tag) {
+            const node = value;
+            if ('number' === typeof node.nodeType && 'string' === typeof node.nodeName) {
+                return `[${tag}]`;
+            }
+        }
+        if ('function' === typeof value.then) {
+            return PROMISE_SUMMARY;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
 function sanitize(value, state, depth, key) {
     if (key !== undefined && isSensitiveKey(key))
         return REDACTED_VALUE;
@@ -40,6 +70,11 @@ function sanitize(value, state, depth, key) {
     if ('undefined' === typeof value || 'function' === typeof value || 'symbol' === typeof value) {
         return OMIT_VALUE;
     }
+    const opaque = opaqueSummary(value);
+    if (opaque !== undefined) {
+        state.truncatedValues += 1;
+        return boundedString(opaque, state, MAX_KEY_LENGTH);
+    }
     if (value instanceof Date)
         return Number.isNaN(value.getTime()) ? null : value.toISOString();
     if (value instanceof Map) {

package/dist/session-continuity.d.ts

@@ -1 +1,2 @@
 export declare function rememberSessionLabel(explicit: string | undefined, store: Storage | undefined, generate: () => string): string;
+export declare function tabSessionStore(win: Window & typeof globalThis): Storage | undefined;

package/dist/session-continuity.js

@@ -22,3 +22,21 @@ export function rememberSessionLabel(explicit, store, generate) {
     write(chosen);
     return chosen;
 }
+export function tabSessionStore(win) {
+    let topFrame;
+    try {
+        topFrame = win.top === win;
+    }
+    catch {
+        topFrame = false;
+    }
+    if (!topFrame) {
+        return undefined;
+    }
+    try {
+        return win.sessionStorage;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/storage-keys.js

@@ -1,5 +1,6 @@
+import { RETICLE_SESSION_STORAGE_KEY } from '@reticlehq/core';
 export const ReticleStorageKey = {
-    SESSION: '__reticle_session',
+    SESSION: RETICLE_SESSION_STORAGE_KEY,
     REF_BASE: '__reticle_ref_base',
     PRESENTER_LOG: 'reticle-presenter-log',
     PRESENTER_LOG_OWNER: 'reticle-presenter-log-owner',

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

@@ -1,8 +1,25 @@
+import { DETERMINISM_GLOBAL_KEY } from '@reticlehq/core';
 const g = globalThis;
-const realSetTimeout = 'function' === typeof g.setTimeout ? g.setTimeout.bind(g) : null;
-const realClearTimeout = 'function' === typeof g.clearTimeout ? g.clearTimeout.bind(g) : null;
-const realRaf = 'function' === typeof g.requestAnimationFrame ? g.requestAnimationFrame.bind(g) : null;
-const realPerfNow = 'function' === typeof g.performance?.now ? g.performance.now.bind(g.performance) : null;
+function kept(name) {
+    const holder = g[Symbol.for(DETERMINISM_GLOBAL_KEY)];
+    if ('object' !== typeof holder || null === holder) {
+        return undefined;
+    }
+    const natives = holder.natives;
+    if ('object' !== typeof natives || null === natives) {
+        return undefined;
+    }
+    const fn = natives[name];
+    return 'function' === typeof fn ? fn : undefined;
+}
+const realSetTimeout = kept('setTimeout') ??
+    ('function' === typeof g.setTimeout ? g.setTimeout.bind(g) : null);
+const realClearTimeout = kept('clearTimeout') ??
+    ('function' === typeof g.clearTimeout ? g.clearTimeout.bind(g) : null);
+const realRaf = kept('requestAnimationFrame') ??
+    ('function' === typeof g.requestAnimationFrame ? g.requestAnimationFrame.bind(g) : null);
+const realPerfNow = kept('performanceNow') ??
+    ('function' === typeof g.performance?.now ? g.performance.now.bind(g.performance) : null);
 export const nativeNow = () => (realPerfNow ? realPerfNow() : 0);
 export const nativeSetTimeout = (cb, ms = 0) => realSetTimeout ? realSetTimeout(cb, ms) : 0;
 export const nativeClearTimeout = (id) => {

package/dist/transport/bridge-url.d.ts

@@ -0,0 +1,8 @@
+export declare function withBridgePath(bridgeUrl: string): {
+    url: string;
+    adjusted: boolean;
+};
+export declare function connectionPolicy(pageHostname: string, bridgeUrl: string, allowNonLocalhost: boolean, token: string | undefined, pageProtocol?: string): {
+    allowed: boolean;
+    reason?: string;
+};

package/dist/transport/bridge-url.js

@@ -0,0 +1,52 @@
+import { RETICLE_WS_PATH, TRANSPORT_LIMITS, isLocalPage, isLoopbackHostname, } from '@reticlehq/core';
+export function withBridgePath(bridgeUrl) {
+    let parsed;
+    try {
+        parsed = new URL(bridgeUrl);
+    }
+    catch {
+        return { url: bridgeUrl, adjusted: false };
+    }
+    if ((parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') ||
+        (parsed.pathname !== '' && parsed.pathname !== '/')) {
+        return { url: bridgeUrl, adjusted: false };
+    }
+    parsed.pathname = RETICLE_WS_PATH;
+    return { url: parsed.toString(), adjusted: true };
+}
+export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, token, pageProtocol = 'http:') {
+    let bridge;
+    try {
+        bridge = new URL(bridgeUrl);
+    }
+    catch {
+        return { allowed: false, reason: 'invalid Reticle bridge URL' };
+    }
+    if (bridge.protocol !== 'ws:' && bridge.protocol !== 'wss:') {
+        return { allowed: false, reason: 'Reticle bridge URL must use ws:// or wss://' };
+    }
+    if ((token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
+        return {
+            allowed: false,
+            reason: `Reticle pairing token exceeds ${String(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH)} characters`,
+        };
+    }
+    const remoteBridge = !isLoopbackHostname(bridge.hostname);
+    if (remoteBridge && bridge.protocol !== 'wss:') {
+        return { allowed: false, reason: 'a non-local Reticle bridge must use wss://' };
+    }
+    const remote = !isLocalPage(pageProtocol, pageHostname) || remoteBridge;
+    if (!remote) {
+        return { allowed: true };
+    }
+    if (!allowNonLocalhost) {
+        return {
+            allowed: false,
+            reason: 'Reticle is disabled outside localhost unless allowNonLocalhost is explicitly enabled',
+        };
+    }
+    if (token === undefined || 0 === token.length) {
+        return { allowed: false, reason: 'a pairing token is required outside localhost' };
+    }
+    return { allowed: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "3.8.2",
+  "version": "3.10.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,23 +22,23 @@
     }
   },
   "dependencies": {
-    "@reticlehq/core": "3.8.2"
+    "@reticlehq/core": "3.10.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons-outline": "^1.2.1",
     "@iconify-json/heroicons-solid": "^1.2.1",
-    "@tanstack/query-core": "^5.103.2",
+    "@tanstack/query-core": "^5.105.2",
     "esbuild": "^0.28.2",
-    "jotai": "^3.0.0",
+    "jotai": "^3.0.1",
     "jsdom": "^30.0.1",
-    "mobx": "^7.0.5",
-    "pinia": "^4.0.3",
-    "react": "^19.3.0",
+    "mobx": "^7.1.4",
+    "pinia": "^4.1.0",
+    "react": "^19.3.1",
     "recoil": "^0.7.7",
-    "svelte": "^5.57.1",
+    "svelte": "^5.57.3",
     "valtio": "^2.3.2",
-    "vue": "^3.5.43",
-    "xstate": "^5.33.2"
+    "vue": "^3.5.44",
+    "xstate": "^5.33.3"
   },
   "license": "Apache-2.0",
   "author": "Reticle contributors",