@reticlehq/browser 3.5.0 → 3.6.0

package/dist/reticle.d.ts

@@ -1,8 +1,12 @@
-import { EventType, RETICLE_URL_PARAM, type ReticleEvent } from '@reticlehq/core';
+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';
 export type { ReticleConnectOptions };
 export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
+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;
@@ -12,6 +16,11 @@ 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;

package/dist/reticle.js

@@ -1,5 +1,5 @@
 import { setPresenterVisible } from './dom/dom-ignore.js';
-import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, 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, } from '@reticlehq/core';
+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';
 import { createCommandRegistry, RELOAD_CACHE_BUST_PARAM, } from './commands/commands.js';
@@ -10,9 +10,10 @@ import { declaredChannels } from './registry/declared-channels.js';
 import { declaredCommands, declaredPlatform } from './registry/declared-platform.js';
 import { registerCapabilities, setCapabilitiesListener, hasCapabilities, } from './registry/capabilities.js';
 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 { installOverlay } from './presenter/chrome/overlay.js';
-import { LOG_KIND, LOG_RESULT } from './presenter/chrome/log-kinds.js';
+import { LOG_ACTOR, LOG_KIND, LOG_RESULT } from './presenter/chrome/log-kinds.js';
 import { actionVerb } from './presenter/chrome/presenter-verbs.js';
 import { str, refLabel, modeForCommand, presentStatus } from './reticle-presenter-helpers.js';
 import { resetClock } from './timers/clock.js';
@@ -22,6 +23,21 @@ import { Annotator } from './review/annotator.js';
 export function shouldBlockProduction(nodeEnv, allowInProduction) {
     return 'production' === nodeEnv && !allowInProduction;
 }
+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 {
@@ -57,6 +73,7 @@ export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, tok
     }
     return { allowed: true };
 }
+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) {
     return option === undefined || option === SESSION_AUTO ? gen() : option;
@@ -78,12 +95,20 @@ export function reticleParamsFromSearch(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;
@@ -116,6 +141,7 @@ export class Reticle {
     #overlay;
     #presenter;
     #pendingPushes = new Map();
+    #pendingHud;
     #readPanelSettings;
     #panelRequested = false;
     #bridgeConnected = false;
@@ -142,7 +168,11 @@ export class Reticle {
             return;
         }
         stripReloadCacheBustParam();
-        const url = options.url ?? bridgeWsUrl(RETICLE_DEFAULT_PORT);
+        const bridge = withBridgePath(options.url ?? bridgeWsUrl(RETICLE_DEFAULT_PORT));
+        const url = bridge.url;
+        if (bridge.adjusted) {
+            globalThis.console.warn(`[Reticle] bridge URL has no path; using ${url} (the bridge only accepts WebSocket upgrades on ${RETICLE_WS_PATH}).`);
+        }
         const policy = connectionPolicy(window.location.hostname, url, true === options.allowNonLocalhost, options.token, window.location.protocol);
         if (!policy.allowed) {
             globalThis.console.warn(`[Reticle] ${policy.reason ?? 'connection blocked'}`);
@@ -188,6 +218,7 @@ export class Reticle {
         });
         setCapabilitiesListener(() => this.#transport?.reannounce());
         setPresenterVisible(true === options.exposePresenter);
+        setTestIdAttr(options.testIdAttribute);
         if (options.networkBodyMaxChars !== undefined) {
             setNetworkBodyMaxChars(options.networkBodyMaxChars);
         }
@@ -205,7 +236,8 @@ export class Reticle {
             this.#overlay = installOverlay();
             this.#overlay.update({ connected: true, events: 0 });
         }
-        if (options.present !== false)
+        this.#pendingHud = reticleParamsFromSearch(window.location.search).hud;
+        if (options.present !== false && HudVisibility.REMOVED !== this.#pendingHud)
             this.#fetchAndShowPanel(options);
         if (true === options.recorder) {
             this.#recorder = installRecorder({ emit, now: () => Date.now() });
@@ -215,7 +247,7 @@ export class Reticle {
             this.#annotator = new Annotator({
                 emit,
                 now: () => Date.now(),
-                onMark: (mark) => this.#presenter?.log(LOG_KIND.HUMAN, `🚩 #${String(mark.index)} ${mark.anchor}${mark.source !== undefined ? ` · ${mark.source}` : ''} — ${mark.note}`),
+                onMark: (mark) => this.#presenter?.log(LOG_KIND.HUMAN, `🚩 #${String(mark.index)} ${mark.label}${mark.source !== undefined ? ` · ${mark.source}` : ''} — ${mark.note}`),
                 shouldBlock: () => this.#readPanelSettings?.().blockPageInteractions ?? true,
             });
             this.#annotator.mount();
@@ -253,12 +285,19 @@ export class Reticle {
                 ? { kind: intent.kind, text: intent.text }
                 : { kind: intent.kind });
             panelOptions.onHudUse = (use) => this.#emit(EventType.HUD_USED, { ...use });
+            panelOptions.onKill = () => {
+                this.disconnect();
+                nativeWarn(KILLED_MESSAGE);
+            };
             const panel = new Presenter(panelOptions);
             this.#presenter = panel;
             panel.mount();
             for (const buffered of this.#pendingPushes.values())
                 panel.handlePush(buffered);
             this.#pendingPushes.clear();
+            if (this.#pendingHud !== undefined)
+                panel.placeHud(this.#pendingHud, undefined);
+            this.#pendingHud = undefined;
             void import('./presenter/tour/tour.js').then((tour) => {
                 if (!this.#connected)
                     return;
@@ -393,10 +432,31 @@ export class Reticle {
             const idleEndMs = command.args['idleEndMs'];
             if ('number' === typeof idleEndMs)
                 this.#presenter?.setIdleEndMs(idleEndMs);
-            return { ok: true, result: { applied: this.#presenter !== undefined, idleEndMs } };
+            const hud = oneOf(HudVisibility, command.args['hud']);
+            const corner = oneOf(HudCorner, command.args['corner']);
+            const presenter = this.#presenter;
+            let placed;
+            if (presenter !== undefined)
+                placed = presenter.placeHud(hud, corner);
+            else {
+                const early = hudWithoutPanel(hud);
+                if (early.remember !== undefined)
+                    this.#pendingHud = early.remember;
+                placed = early.placed;
+            }
+            return {
+                ok: true,
+                result: {
+                    applied: this.#presenter !== undefined,
+                    idleEndMs,
+                    ...(0 < placed.length ? { hud: placed } : {}),
+                },
+            };
         }
         if (command.name === ReticleCommand.PRESENTER ||
             command.name === ReticleCommand.FLOWS ||
+            command.name === ReticleCommand.FLOW_PROGRESS ||
+            command.name === ReticleCommand.PLAN ||
             command.name === ReticleCommand.IMPACT) {
             if (this.#presenter === undefined) {
                 this.#pendingPushes.set(command.name, command);
@@ -431,10 +491,11 @@ export class Reticle {
             return;
         p.setMode(modeForCommand(command.name));
         this.#actHandle = undefined;
+        const actor = CommandActor.HARNESS === command.by ? LOG_ACTOR.HARNESS : LOG_ACTOR.AGENT;
         if (command.name === ReticleCommand.ACT) {
             const ref = str(command.args['ref']);
             const label = refLabel(ref);
-            this.#actHandle = p.log(LOG_KIND.ACT, `${actionVerb(str(command.args['action']))} ${label}`);
+            this.#actHandle = p.log(LOG_KIND.ACT, `${actionVerb(str(command.args['action']))} ${label}`, undefined, actor);
             await p.beforeAct(ref, str(command.args['action']), label);
         }
         else if (command.name === ReticleCommand.ACT_SEQUENCE) {
@@ -443,14 +504,17 @@ export class Reticle {
                 const s = step;
                 const ref = str(s.ref);
                 const label = refLabel(ref);
-                this.#actHandle = p.log(LOG_KIND.ACT, `${actionVerb(str(s.action))} ${label}`);
+                this.#actHandle = p.log(LOG_KIND.ACT, `${actionVerb(str(s.action))} ${label}`, undefined, actor);
                 await p.beforeAct(ref, str(s.action), label);
             }
         }
         else {
             const label = presentStatus(command.name, command.args);
             p.status(label);
-            p.log(LOG_KIND.READ, label);
+            p.log(LOG_KIND.READ, label, undefined, actor);
         }
     }
 }
+function oneOf(values, raw) {
+    return Object.values(values).includes(raw) ? raw : undefined;
+}

package/dist/review/annotator-styles.d.ts

@@ -3,4 +3,4 @@ export declare const MARK_SUBMIT = "Add";
 export declare const MARK_CANCEL = "Cancel";
 export declare const MARK_PENDING_GLYPH = "+";
 export declare const ANNOTATOR_CSS: string;
-export declare const ANNOTATOR_ROOT_HTML = "<div data-reticle-mark=\"hi\"><span data-reticle-mark=\"hilabel\"></span></div><div data-reticle-mark=\"sel\" hidden></div>";
+export declare const ANNOTATOR_ROOT_HTML: string;

package/dist/review/annotator.d.ts

@@ -1,4 +1,5 @@
 import { EventType } from '@reticlehq/core';
+import type { MarkForAgent } from './marks-for-agent.js';
 interface MarkReport {
     note: string;
     anchor: string;
@@ -19,12 +20,18 @@ export interface AnnotatorChrome {
     copyRow?: HTMLElement;
     countEl?: HTMLElement;
     onCount?: (count: number) => void;
+    onMarksChange?: (marks: readonly AnnotationItem[]) => void;
+}
+export interface AnnotationItem extends MarkForAgent {
+    id: string;
+    createdAt: number;
 }
 export declare class Annotator {
     #private;
     constructor(deps: AnnotatorDeps);
     get active(): boolean;
     get markCount(): number;
+    annotations(): AnnotationItem[];
     mount(): void;
     setAccent(hex: string): void;
     attachChrome(chrome: AnnotatorChrome): void;

package/dist/review/annotator.js

@@ -1,3 +1,4 @@
+import { readTestId } from '../dom/addressing/testid-attr.js';
 import { isSyntheticInput } from '../actions/synthetic/synthetic-input.js';
 import { EventType } from '@reticlehq/core';
 import { isReticleUi, isReticleOverlay } from '../dom/dom-ignore.js';
@@ -36,6 +37,7 @@ export class Annotator {
     #clearBtn;
     #copyRow;
     #onChromeCount;
+    #onMarksChange;
     #countEl;
     #accent;
     #ac;
@@ -53,6 +55,17 @@ export class Annotator {
     get markCount() {
         return this.#marks.length;
     }
+    annotations() {
+        return this.#marks.map(({ id, createdAt, note, label, anchor, route, source }) => ({
+            id,
+            createdAt,
+            note,
+            label,
+            anchor,
+            route,
+            ...(source === undefined ? {} : { source }),
+        }));
+    }
     mount() {
         if (this.#root !== undefined || 'undefined' === typeof document)
             return;
@@ -99,6 +112,7 @@ export class Annotator {
         this.#clearBtn = chrome.clearBtn;
         this.#copyRow = chrome.copyRow;
         this.#onChromeCount = chrome.onCount;
+        this.#onMarksChange = chrome.onMarksChange;
         this.#countEl = chrome.countEl;
         this.#markersBtn?.addEventListener('click', (e) => {
             e.stopPropagation();
@@ -184,6 +198,7 @@ export class Annotator {
         }
         this.#clearBtn?.toggleAttribute('disabled', 0 === n);
         this.#onChromeCount?.(n);
+        this.#onMarksChange?.(this.annotations());
         if (this.#copyRow !== undefined) {
             this.#copyRow.hidden = 0 === n;
             const text = this.#copyRow.querySelector('[data-reticle-marks-text]');
@@ -406,6 +421,7 @@ export class Annotator {
                 route: editing.route,
             });
             this.#report(note, editing.anchor, editing.label, this.#marks.indexOf(editing) + 1, editing.source);
+            this.#syncChrome();
             this.#closePopover();
             return;
         }
@@ -480,8 +496,10 @@ export class Annotator {
         pin.style.left = `${String((x / window.innerWidth) * 100)}%`;
         pin.style.top = `${String(isFixed ? y : yDoc - window.scrollY)}px`;
         this.#root.appendChild(pin);
+        const createdAt = this.#now();
         const mark = {
-            id: `${resolved.anchor}:${String(this.#now())}:${String(n)}`,
+            id: `${resolved.anchor}:${String(createdAt)}:${String(n)}`,
+            createdAt,
             note,
             label: resolved.label,
             anchor: resolved.anchor,
@@ -593,7 +611,7 @@ function clampPop(x, y) {
     return { left, top };
 }
 function describeEl(el) {
-    const testid = el.getAttribute('data-testid');
+    const testid = readTestId(el);
     if (testid !== null && testid.length > 0)
         return testid;
     const tag = el.tagName.toLowerCase();

package/dist/review/mark-anchor.js

@@ -1,9 +1,9 @@
+import { readTestId } from '../dom/addressing/testid-attr.js';
 import { MarkAnchorStrategy } from '@reticlehq/core';
 import { AnchorStrategy, synthesizeAnchor, } from '../dom/addressing/auto-anchor.js';
 import { getAccessibleName, getRole } from '../dom/a11y.js';
 import { identifyComponent } from '../registry/stores/adapters.js';
 import { sourceFor } from '../dom/addressing/source.js';
-const TESTID_ATTR = 'data-testid';
 const STRATEGY = {
     [AnchorStrategy.TESTID]: MarkAnchorStrategy.TESTID,
     [AnchorStrategy.COMPONENT]: MarkAnchorStrategy.COMPONENT,
@@ -16,7 +16,7 @@ function labelFor(el, role, name) {
     return role.length > 0 ? role : el.tagName.toLowerCase();
 }
 export function resolveMarkAnchor(el) {
-    const testid = el.getAttribute(TESTID_ATTR) ?? undefined;
+    const testid = readTestId(el) ?? undefined;
     const info = identifyComponent(el);
     const component = info?.componentStack[0];
     const source = sourceFor(el, info?.source);

package/dist/session-continuity.js

@@ -1,4 +1,5 @@
-const STORAGE_KEY = '__reticle_session';
+import { ReticleStorageKey } from './storage-keys.js';
+const STORAGE_KEY = ReticleStorageKey.SESSION;
 export function rememberSessionLabel(explicit, store, generate) {
     const read = () => {
         try {

package/dist/storage-keys.d.ts

@@ -0,0 +1,14 @@
+export declare const ReticleStorageKey: {
+    readonly SESSION: "__reticle_session";
+    readonly REF_BASE: "__reticle_ref_base";
+    readonly PRESENTER_LOG: "reticle-presenter-log";
+    readonly PRESENTER_LOG_OWNER: "reticle-presenter-log-owner";
+    readonly PRESENTER_SETTINGS: "reticle-presenter-settings";
+    readonly PRESENTER_MINIMISED: "reticle-presenter-minimised";
+    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 function isReticleStorageKey(key: string): boolean;

package/dist/storage-keys.js

@@ -0,0 +1,17 @@
+export const ReticleStorageKey = {
+    SESSION: '__reticle_session',
+    REF_BASE: '__reticle_ref_base',
+    PRESENTER_LOG: 'reticle-presenter-log',
+    PRESENTER_LOG_OWNER: 'reticle-presenter-log-owner',
+    PRESENTER_SETTINGS: 'reticle-presenter-settings',
+    PRESENTER_MINIMISED: 'reticle-presenter-minimised',
+    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.';
+const OWN_KEYS = new Set(Object.values(ReticleStorageKey));
+export function isReticleStorageKey(key) {
+    return OWN_KEYS.has(key) || key.startsWith(TOUR_SEEN_KEY_PREFIX);
+}

package/package.json

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