@reticlehq/browser 3.6.0 → 3.8.0

package/dist/reticle.d.ts

@@ -1,8 +1,8 @@
 import { EventType, RETICLE_URL_PARAM, HudVisibility, type ReticleEvent } from '@reticlehq/core';
 import { type CapabilitiesInput } from './registry/capabilities.js';
-import type { ReticleConnectOptions } from './connect-options.js';
+import { type ReticleConnectOptions } from './connect-options.js';
+export { helloMode, shouldBlockProduction } from './connect-options.js';
 export type { ReticleConnectOptions };
-export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
 export declare function withBridgePath(bridgeUrl: string): {
     url: string;
     adjusted: boolean;
@@ -43,7 +43,9 @@ export declare class Reticle {
     #private;
     connect(options?: ReticleConnectOptions): void;
     get connected(): boolean;
+    routes(patterns: readonly string[]): void;
     signal(name: string, data?: Record<string, unknown>): void;
+    busy<T>(work: Promise<T>): Promise<T>;
     state(name: string, value: unknown): void;
     renderCommit(commits: number): void;
     describe(input: CapabilitiesInput): void;

package/dist/reticle.js

@@ -1,4 +1,8 @@
-import { setPresenterVisible } from './dom/dom-ignore.js';
+import { setPresenterViewer, setPresenterVisible } from './dom/dom-ignore.js';
+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 { editEpoch } from './edit-epoch.js';
@@ -12,6 +16,8 @@ import { registerCapabilities, setCapabilitiesListener, hasCapabilities, } from
 import { installAllObservers, runTeardowns } from './observers/install-all.js';
 import { setTestIdAttr } from './dom/addressing/testid-attr.js';
 import { setNetworkBodyMaxChars } from './observers/net-detail/network-body.js';
+import { pageHref } from './security/page-location.js';
+import { scrubKnownSecrets } from './security/serialization.js';
 import { installOverlay } from './presenter/chrome/overlay.js';
 import { LOG_ACTOR, LOG_KIND, LOG_RESULT } from './presenter/chrome/log-kinds.js';
 import { actionVerb } from './presenter/chrome/presenter-verbs.js';
@@ -20,9 +26,8 @@ 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';
-export function shouldBlockProduction(nodeEnv, allowInProduction) {
-    return 'production' === nodeEnv && !allowInProduction;
-}
+import { helloMode, leaseToken, shouldBlockProduction, } from './connect-options.js';
+export { helloMode, shouldBlockProduction } from './connect-options.js';
 export function withBridgePath(bridgeUrl) {
     let parsed;
     try {
@@ -73,6 +78,7 @@ export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, tok
     }
     return { allowed: true };
 }
+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).';
 export function resolveSessionLabel(option, gen) {
@@ -141,6 +147,7 @@ export class Reticle {
     #overlay;
     #presenter;
     #pendingPushes = new Map();
+    #pendingNarrations = [];
     #pendingHud;
     #readPanelSettings;
     #panelRequested = false;
@@ -149,6 +156,7 @@ export class Reticle {
     #annotator;
     #eventCount = 0;
     #token;
+    #mode = {};
     #sdkVersion;
     #captureBodies = false;
     #sourceMapping = undefined;
@@ -156,8 +164,15 @@ export class Reticle {
     #redactKeys = [];
     #actHandle;
     connect(options = {}) {
-        if (this.#connected)
+        if (this.#connected) {
+            const leased = leaseToken(options, this.#token);
+            if (leased !== undefined) {
+                this.#token = leased;
+                this.#transport?.redialAfterRefusal();
+            }
+            this.#adoptLateProjectId(options);
             return;
+        }
         if ('undefined' === typeof window || 'undefined' === typeof document)
             return;
         const proc = globalThis.process;
@@ -194,6 +209,7 @@ export class Reticle {
         this.#token =
             options.token !== undefined && options.token.length > 0 ? options.token : undefined;
         this.#projectId = identity.projectId;
+        this.#mode = helloMode(options);
         this.#applyRedaction(options.redact);
         this.#start = performance.now();
         this.#registry = createCommandRegistry();
@@ -281,6 +297,8 @@ export class Reticle {
             if (options.idleEndMs !== undefined)
                 panelOptions.idleEndMs = options.idleEndMs;
             panelOptions.sessionId = this.#session;
+            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 });
@@ -292,9 +310,14 @@ export class Reticle {
             const panel = new Presenter(panelOptions);
             this.#presenter = panel;
             panel.mount();
+            panel.showSdkVersion(this.#sdkVersion);
             for (const buffered of this.#pendingPushes.values())
                 panel.handlePush(buffered);
             this.#pendingPushes.clear();
+            if (0 < this.#pendingNarrations.length)
+                panel.sessionStart();
+            for (const early of this.#pendingNarrations.splice(0))
+                panel.narrate(early.text, early.level, early.actor, early.summary);
             if (this.#pendingHud !== undefined)
                 panel.placeHud(this.#pendingHud, undefined);
             this.#pendingHud = undefined;
@@ -333,9 +356,17 @@ export class Reticle {
     get connected() {
         return this.#connected;
     }
+    routes(patterns) {
+        declareRoutes(patterns);
+    }
     signal(name, data = {}) {
         this.#emit(EventType.SIGNAL, { name, data });
     }
+    busy(work) {
+        return trackBusy(work, (name, data) => {
+            this.signal(name, data);
+        });
+    }
     state(name, value) {
         this.#emit(EventType.STATE_CHANGE, { name, value });
     }
@@ -396,16 +427,26 @@ export class Reticle {
         setActiveRedactionPolicy(buildRedactionPolicy(config, nativeWarn));
         this.#redactKeys = wireRedactionKeys(config);
     }
+    #adoptLateProjectId(options) {
+        if (this.#projectId !== undefined)
+            return;
+        const late = resolveConnectIdentity(options, window.location.search).projectId;
+        if (late === undefined)
+            return;
+        this.#projectId = late;
+        this.#transport?.reannounce();
+    }
     #hello() {
         return {
             kind: MessageKind.HELLO,
             protocolVersion: RETICLE_PROTOCOL_VERSION,
             sessionId: this.#session,
             ...(this.#projectId === undefined ? {} : { projectId: this.#projectId }),
-            url: location.href,
-            title: document.title,
+            url: pageHref(),
+            title: scrubKnownSecrets(document.title),
             adapters: adapterNames(),
             ...(this.#token === undefined ? {} : { token: this.#token }),
+            ...this.#mode,
             hasCapabilities: hasCapabilities(),
             channels: declaredChannels(),
             platform: declaredPlatform(),
@@ -423,9 +464,25 @@ export class Reticle {
         };
     }
     async #handleCommand(command) {
+        if (command.name === ReticleCommand.MARKERS) {
+            const markers = coverageMarkers(document);
+            const buildPlugin = this.#sdkVersion !== undefined || this.#sourceMapping !== undefined;
+            const na = notApplicableFor({ buildPlugin, adapters: adapterNames(), markers });
+            return { ok: true, result: { markers, ...(0 === na.length ? {} : { notApplicable: na }) } };
+        }
         if (command.name === ReticleCommand.NARRATE) {
+            if (this.#presenter === undefined && this.#panelRequested) {
+                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();
-            this.#presenter?.narrate(str(command.args['text']), str(command.args['level'], 'info'));
+            this.#presenter?.narrate(str(command.args['text']), str(command.args['level'], 'info'), narrationActor(command.args), true === command.args['summary']);
             return { ok: true, result: { shown: this.#presenter !== undefined } };
         }
         if (command.name === ReticleCommand.SESSION_CONFIG) {
@@ -471,6 +528,8 @@ export class Reticle {
         }
         this.#presenter?.sessionStart();
         await this.#presentBefore(command);
+        setPresenterViewer(CommandActor.HARNESS === command.by);
+        setOutwardPolicy(command.outward?.allowed);
         try {
             const result = await handler(command.args);
             this.#actHandle?.result(LOG_RESULT.PASS);
@@ -481,6 +540,8 @@ export class Reticle {
             return { ok: false, error: error instanceof Error ? error.message : String(error) };
         }
         finally {
+            setPresenterViewer(false);
+            setOutwardPolicy(undefined);
             this.#actHandle = undefined;
             this.#presenter?.scheduleIdle();
         }
@@ -515,6 +576,9 @@ 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/security/page-location.d.ts

@@ -0,0 +1,2 @@
+export declare function pageHref(): string;
+export declare function pageRoute(withHash?: boolean): string;

package/dist/security/page-location.js

@@ -0,0 +1,7 @@
+import { redactUrl } from '@reticlehq/core';
+export function pageHref() {
+    return redactUrl(location.href);
+}
+export function pageRoute(withHash = true) {
+    return redactUrl(`${location.pathname}${location.search}${withHash ? location.hash : ''}`);
+}

package/dist/security/serialization.js

@@ -29,7 +29,7 @@ function sanitize(value, state, depth, key) {
     if (null === value || 'boolean' === typeof value)
         return value;
     if ('string' === typeof value) {
-        return boundedString(value, state, 'error' === key?.toLowerCase()
+        return boundedString(scrubKnownSecrets(value), state, 'error' === key?.toLowerCase()
             ? TRANSPORT_LIMITS.MAX_ERROR_LENGTH
             : TRANSPORT_LIMITS.MAX_STRING_LENGTH);
     }

package/dist/storage-keys.d.ts

@@ -5,10 +5,12 @@ export declare const ReticleStorageKey: {
     readonly PRESENTER_LOG_OWNER: "reticle-presenter-log-owner";
     readonly PRESENTER_SETTINGS: "reticle-presenter-settings";
     readonly PRESENTER_MINIMISED: "reticle-presenter-minimised";
+    readonly PRESENTER_OPEN: "reticle-presenter-open";
+    readonly PRESENTER_VIEW: "reticle-presenter-view";
     readonly CAROUSEL_DISMISSED: "reticle.carousel.dismissed";
-    readonly HARNESS_OFFER_DISMISSED: "reticle.harnessOffer.dismissed";
     readonly ANNOTATION_HISTORY: "reticle.annotations.history.v1";
-    readonly RECENT_PLAYS: "reticle.flow.recent.v1";
 };
 export declare const TOUR_SEEN_KEY_PREFIX = "reticle.tour.seen.";
+export declare const PERSONA_KEY_PREFIX = "reticle.harness.persona.";
+export declare const IMPACT_SEEN_KEY_PREFIX = "reticle.impact.seen.";
 export declare function isReticleStorageKey(key: string): boolean;

package/dist/storage-keys.js

@@ -5,13 +5,18 @@ export const ReticleStorageKey = {
     PRESENTER_LOG_OWNER: 'reticle-presenter-log-owner',
     PRESENTER_SETTINGS: 'reticle-presenter-settings',
     PRESENTER_MINIMISED: 'reticle-presenter-minimised',
+    PRESENTER_OPEN: 'reticle-presenter-open',
+    PRESENTER_VIEW: 'reticle-presenter-view',
     CAROUSEL_DISMISSED: 'reticle.carousel.dismissed',
-    HARNESS_OFFER_DISMISSED: 'reticle.harnessOffer.dismissed',
     ANNOTATION_HISTORY: 'reticle.annotations.history.v1',
-    RECENT_PLAYS: 'reticle.flow.recent.v1',
 };
 export const TOUR_SEEN_KEY_PREFIX = 'reticle.tour.seen.';
+export const PERSONA_KEY_PREFIX = 'reticle.harness.persona.';
+export const IMPACT_SEEN_KEY_PREFIX = 'reticle.impact.seen.';
 const OWN_KEYS = new Set(Object.values(ReticleStorageKey));
 export function isReticleStorageKey(key) {
-    return OWN_KEYS.has(key) || key.startsWith(TOUR_SEEN_KEY_PREFIX);
+    return (OWN_KEYS.has(key) ||
+        key.startsWith(TOUR_SEEN_KEY_PREFIX) ||
+        key.startsWith(PERSONA_KEY_PREFIX) ||
+        key.startsWith(IMPACT_SEEN_KEY_PREFIX));
 }

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

@@ -8,4 +8,5 @@ interface FrameOutcome {
 export declare const boundedFrame: (budgetMs?: number) => Promise<FrameOutcome>;
 export declare const nativeFrame: () => Promise<void>;
 export declare const settle: (budgetMs?: number) => Promise<FrameOutcome>;
+export declare function asSettleBudget(raw: unknown): number | undefined;
 export {};

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

@@ -46,3 +46,8 @@ export const settle = async (budgetMs = FRAME_BUDGET_MS) => {
     await Promise.resolve();
     return boundedFrame(budgetMs);
 };
+export function asSettleBudget(raw) {
+    if ('number' !== typeof raw || !Number.isFinite(raw))
+        return undefined;
+    return Math.max(0, Math.min(raw, FRAME_BUDGET_MS));
+}

package/dist/transport/transport.d.ts

@@ -26,6 +26,7 @@ export declare class Transport {
     constructor(deps: TransportDeps);
     connect(): void;
     sendEvent(event: ReticleEvent): void;
+    redialAfterRefusal(): void;
     reannounce(): void;
     close(): void;
 }

package/dist/transport/transport.js

@@ -26,6 +26,8 @@ export class Transport {
     #signalQueue = [];
     #insertOrder = 0;
     #closed = false;
+    #refused = false;
+    #redialOnRefusal = false;
     #disconnectedSince;
     #reconnectDelay = RECONNECT_DELAY_MS;
     #lost = false;
@@ -55,6 +57,7 @@ export class Transport {
         this.#reconnectDelay = RECONNECT_DELAY_MS;
         if (this.#ws !== undefined)
             return;
+        this.#refused = false;
         this.#open();
     }
     #open() {
@@ -92,9 +95,14 @@ export class Transport {
         ws.onclose = (event) => {
             this.#ws = undefined;
             if (event.code === WS_POLICY_VIOLATION) {
-                this.#closed = true;
+                if (this.#redialOnRefusal && !this.#closed) {
+                    this.#redialOnRefusal = false;
+                    this.#open();
+                    return;
+                }
+                this.#refused = true;
                 const reason = event.reason.length > 0 ? event.reason : 'policy violation';
-                nativeWarn(`[reticle] bridge refused the connection: ${reason} — not retrying.`);
+                nativeWarn(`[reticle] bridge refused the connection: ${reason} — not retrying until you come back to this tab.`);
                 this.#deps.onConnectionLost?.();
                 return;
             }
@@ -107,7 +115,7 @@ export class Transport {
         };
     }
     #scheduleReopen() {
-        if (this.#closed)
+        if (this.#closed || this.#refused)
             return;
         const delay = this.#reconnectDelay;
         this.#reconnectDelay = nextReconnectDelay(delay);
@@ -195,6 +203,18 @@ export class Transport {
             type: event.type,
         });
     }
+    redialAfterRefusal() {
+        if (this.#closed) {
+            return;
+        }
+        if (this.#refused && this.#ws === undefined) {
+            this.#refused = false;
+            this.#reconnectDelay = RECONNECT_DELAY_MS;
+            this.#open();
+            return;
+        }
+        this.#redialOnRefusal = true;
+    }
     reannounce() {
         if (this.#ws === undefined || this.#ws.readyState !== WebSocket.OPEN)
             return;

package/dist/transport/unreachable-message.d.ts

@@ -1,2 +1,2 @@
 export declare function unreachableMessage(url: string, attempts: number): string;
-export declare function unreachableStripText(url: string, attempts: number): string;
+export declare const UNREACHABLE_HEADLINE = "Can't reach Reticle from this page. Run reticle status to check, or reticle serve to start it.";

package/dist/transport/unreachable-message.js

@@ -5,9 +5,7 @@ export function unreachableMessage(url, attempts) {
         `that is not there from one it is not allowed to reach, so this is not evidence about the ` +
         `daemon. What answers it: run \`npx @reticlehq/server status\` to see whether one is listening ` +
         `and on which port. If your app runs in a container, devcontainer or WSL, the daemon is on a ` +
-        `different host, so set the URL explicitly (Vite: VITE_RETICLE_WS_URL, or ` +
-        `reticle.connect({ url })). An https page cannot open a ws:// socket at all. Still retrying…`);
-}
-export function unreachableStripText(url, attempts) {
-    return `no bridge at ${url} — ${String(attempts)} attempt${1 === attempts ? '' : 's'}`;
+        `different host, so point the page at it: RETICLE_PORT or reticle({ port }) with the Vite ` +
+        `plugin, reticle.connect({ url }) by hand. An https page cannot open a ws:// socket. Still retrying…`);
 }
+export const UNREACHABLE_HEADLINE = "Can't reach Reticle from this page. Run reticle status to check, or reticle serve to start it.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,10 +15,14 @@
     "./inject": {
       "types": "./dist/reticle-inject.d.ts",
       "default": "./dist/reticle-inject.js"
+    },
+    "./activate": {
+      "types": "./dist/activate.d.ts",
+      "default": "./dist/activate.js"
     }
   },
   "dependencies": {
-    "@reticlehq/core": "3.6.0"
+    "@reticlehq/core": "3.8.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons-outline": "^1.2.1",

package/dist/presenter/carousel/offer-card.d.ts

@@ -1,21 +0,0 @@
-export declare const OFFER_ATTR = "data-reticle-offer";
-export declare const OFFER_CLAIM_ATTR = "data-reticle-offer-claim";
-export declare const OFFER_DISMISSED_KEY: "reticle.harnessOffer.dismissed";
-export declare const OFFER_TEXT: {
-    readonly HEADLINE: "Get Harness free for 3 months";
-    readonly BODY: "Explores your app and saves every journey as a free replay.";
-    readonly CLAIM: "Claim now";
-    readonly DISMISS: "Not now";
-    readonly claimed: (days: number) => string;
-    readonly ending: (days: number) => string;
-};
-export declare function offerDismissed(storage: Pick<Storage, 'getItem'> | undefined): boolean;
-export interface OfferState {
-    claimed: boolean;
-    daysRemaining?: number | undefined;
-    claimUrl?: string | undefined;
-    eligible?: boolean | undefined;
-    drivable?: boolean | undefined;
-}
-export declare function offerHtml(offer: OfferState | undefined, dismissed: boolean): string;
-export declare const OFFER_CSS: string;

package/dist/presenter/carousel/offer-card.js

@@ -1,56 +0,0 @@
-import { ReticleStorageKey } from '../../storage-keys.js';
-export const OFFER_ATTR = 'data-reticle-offer';
-export const OFFER_CLAIM_ATTR = 'data-reticle-offer-claim';
-export const OFFER_DISMISSED_KEY = ReticleStorageKey.HARNESS_OFFER_DISMISSED;
-export const OFFER_TEXT = {
-    HEADLINE: 'Get Harness free for 3 months',
-    BODY: 'Explores your app and saves every journey as a free replay.',
-    CLAIM: 'Claim now',
-    DISMISS: 'Not now',
-    claimed: (days) => `Harness active — ${String(days)} days left`,
-    ending: (days) => 1 >= days
-        ? 'Harness free period ends today'
-        : `Harness free period ends in ${String(days)} days`,
-};
-const ENDING_SOON_DAYS = 14;
-export function offerDismissed(storage) {
-    try {
-        return '1' === storage?.getItem(OFFER_DISMISSED_KEY);
-    }
-    catch {
-        return false;
-    }
-}
-const escape = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-export function offerHtml(offer, dismissed) {
-    if (offer === undefined)
-        return '';
-    if (offer.claimed) {
-        const days = offer.daysRemaining;
-        if (days === undefined || 0 > days)
-            return '';
-        const text = ENDING_SOON_DAYS >= days ? OFFER_TEXT.ending(days) : OFFER_TEXT.claimed(days);
-        return `<div ${OFFER_ATTR} class="reticle-offer reticle-offer-claimed">${escape(text)}</div>`;
-    }
-    if (false === offer.eligible)
-        return '';
-    if (false === offer.drivable)
-        return '';
-    if (dismissed)
-        return '';
-    const url = offer.claimUrl;
-    if (url === undefined || 0 === url.length)
-        return '';
-    return `<div ${OFFER_ATTR} class="reticle-offer" role="note">
-      <span class="reticle-offer-title">${escape(OFFER_TEXT.HEADLINE)}</span>
-      <p class="reticle-offer-body">${escape(OFFER_TEXT.BODY)}</p>
-      <a ${OFFER_CLAIM_ATTR} class="reticle-offer-claim" href="${escape(url)}" target="_blank" rel="noopener noreferrer">${escape(OFFER_TEXT.CLAIM)}</a>
-    </div>`;
-}
-export const OFFER_CSS = `
-.reticle-offer{margin:8px 10px;padding:10px 12px;border:1px solid var(--reticle-line,#2a2f3a);border-radius:10px;background:var(--reticle-surface-inset,rgba(255,255,255,.03));}
-.reticle-offer-title{display:block;font-weight:600;font-size:12px;padding-right:18px;}
-.reticle-offer-body{margin:6px 0 8px;font-size:11px;line-height:1.45;opacity:.8;}
-.reticle-offer-claim{display:inline-block;font-size:11px;font-weight:600;padding:4px 10px;border-radius:6px;background:var(--reticle-accent,#4f7cff);color:#fff;text-decoration:none;}
-.reticle-offer-claimed{margin:6px 10px;font-size:10px;opacity:.6;}
-`;