@reticlehq/browser 2.11.0 → 2.12.0

package/dist/presenter/presenter-shell.js

@@ -1,5 +1,5 @@
 import { PresenterReport, reportPanelHtml } from './presenter-report.js';
-import { CHAT_MIN_ATTR, CHAT_PILL_ATTR, REPORT_ATTR, REPORT_BTN_ATTR, ANNOTATE_BTN_ATTR, CHAT_ATTR, CHAT_TOGGLE_ATTR, CHAT_PANEL_ATTR, DOCK_ATTR, FAB_ATTR, MIN_ATTR, HUD_DRAGGED_ATTR, SETTINGS_ATTR, SETTINGS_BTN_ATTR, } from './presenter-config.js';
+import { CHAT_MIN_ATTR, CHAT_PILL_ATTR, REPORT_ATTR, REPORT_BTN_ATTR, ANNOTATE_BTN_ATTR, CHAT_ATTR, CHAT_TOGGLE_ATTR, CHAT_PANEL_ATTR, DOCK_ATTR, FAB_ATTR, MIN_ATTR, SETTINGS_ATTR, SETTINGS_BTN_ATTR, } from './presenter-config.js';
 import { BRAND_NAME, FAB_TOGGLE_HTML, MARK_SVG } from './presenter-brand.js';
 import { settleLogAtLatest } from './presenter-log.js';
 import { installHudDragHandles, installHudPositionGuards } from './presenter-drag.js';
@@ -420,7 +420,3 @@ export class HudShell {
         }
     };
 }
-/** Whether the dock has been dragged off the default bottom-right position. */
-export function isDockDragged(dock) {
-    return '1' === dock.getAttribute(HUD_DRAGGED_ATTR);
-}

package/dist/reticle.d.ts

@@ -55,6 +55,8 @@ export declare function buildEvent(args: {
     sessionId: string;
     data: Record<string, unknown>;
     ref?: string | undefined;
+    documentId?: string | undefined;
+    editEpoch?: number | undefined;
 }): ReticleEvent;
 /**
  * The browser-side orchestrator. Wires observers -> events -> bridge, and bridge
@@ -79,5 +81,15 @@ export declare class Reticle {
     describe(input: CapabilitiesInput): void;
     /** Live-control: end the session programmatically from the host app (drives the panel to ended). */
     endSession(): void;
+    /**
+     * Hand the SDK the page's hot-update channel, so a stale ref can say the code changed underneath it.
+     *
+     * `unknown` on purpose: the only caller that has one is the build integration, the shape it passes
+     * is Vite's `import.meta.hot`, and the SDK must not depend on Vite — it ships to Next, Electron,
+     * Tauri and plain pages. Anything that is not a subscribable channel is ignored, which is the
+     * normal case: with no channel the epoch stays at `NO_EDITS_OBSERVED`, meaning "no edits OBSERVED",
+     * never "no edits happened".
+     */
+    observeHotUpdates(hot: unknown): void;
     disconnect(): void;
 }

package/dist/reticle.js

@@ -1,5 +1,6 @@
-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, } from '@reticlehq/core';
+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, newDocumentId, NO_EDITS_OBSERVED, } 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';
 import { Transport } from './transport/transport.js';
 import { unreachableMessage } from './transport/unreachable-message.js';
@@ -128,6 +129,15 @@ export function buildEvent(args) {
         type: args.type,
         sessionId: args.sessionId,
         ref: args.ref,
+        // Which document this was observed under, so the server can refuse evidence minted before a
+        // navigation replaced the page. Stamped HERE because it is the one place every event passes
+        // through: an observer added later would otherwise emit unstamped events, which read as
+        // "current" by design and would reintroduce the defect silently for one event type.
+        documentId: args.documentId,
+        // Which round of source edits this was observed under. Stamped HERE for exactly the reason
+        // documentId is, and omitted while nothing has hot-updated: absence already reads as "current"
+        // downstream, so `NO_EDITS_OBSERVED` on the wire would be bytes spent saying "unknown".
+        editEpoch: NO_EDITS_OBSERVED === args.editEpoch ? undefined : args.editEpoch,
         data: args.data,
     };
 }
@@ -141,6 +151,13 @@ export class Reticle {
     #teardowns = [];
     #connected = false;
     #session = 'default';
+    /**
+     * Minted once, here, because this class is constructed once per document: a full navigation tears
+     * down the JavaScript context and builds a new one, so the id dies with the document it names. An
+     * SPA route change does not reconstruct it, which is correct — same context, same in-flight
+     * requests, same evidence.
+     */
+    #documentId = newDocumentId(Math.random);
     #start = 0;
     #overlay;
     #presenter;
@@ -321,6 +338,18 @@ export class Reticle {
     endSession() {
         this.#presenter?.setState(SessionState.ENDED);
     }
+    /**
+     * Hand the SDK the page's hot-update channel, so a stale ref can say the code changed underneath it.
+     *
+     * `unknown` on purpose: the only caller that has one is the build integration, the shape it passes
+     * is Vite's `import.meta.hot`, and the SDK must not depend on Vite — it ships to Next, Electron,
+     * Tauri and plain pages. Anything that is not a subscribable channel is ignored, which is the
+     * normal case: with no channel the epoch stays at `NO_EDITS_OBSERVED`, meaning "no edits OBSERVED",
+     * never "no edits happened".
+     */
+    observeHotUpdates(hot) {
+        editEpoch.observe(hot);
+    }
     disconnect() {
         if (!this.#connected)
             return;
@@ -347,6 +376,8 @@ export class Reticle {
             t: Math.round(performance.now() - this.#start),
             type,
             sessionId: this.#session,
+            documentId: this.#documentId,
+            editEpoch: editEpoch.current,
             data,
             ref,
         });

package/dist/transport/unreachable-message.js

@@ -5,12 +5,13 @@
  * than a template inlined in a warn call. The rule it exists to hold: report what this page observed
  * and what it could not determine, never a cause. See unreachable-message.test.ts.
  */
+import { UNREACHABLE_NOTICE_PREFIX } from '@reticlehq/core';
 /**
  * The page tried, failed, and cannot see why. Names the address and the attempt count, refuses to
  * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
  */
 export function unreachableMessage(url, attempts) {
-    return (`[Reticle] this page could not open a websocket to ${url}. ${String(attempts)} attempts, all ` +
+    return (`${UNREACHABLE_NOTICE_PREFIX}${url}. ${String(attempts)} attempts, all ` +
         `failed. That is everything the page can see: from inside the browser it cannot tell a daemon ` +
         `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 ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,21 +13,18 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@testing-library/dom": "^10.4.1",
-    "@reticlehq/core": "2.11.0"
+    "@reticlehq/core": "2.12.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons-outline": "^1.2.1",
     "@iconify-json/heroicons-solid": "^1.2.1",
     "@tanstack/query-core": "^5.101.4",
-    "@types/jsdom": "^30.0.0",
     "jotai": "^2.20.2",
     "jsdom": "^30.0.1",
     "mobx": "^7.0.0",
     "pinia": "^4.0.3",
     "react": "^19.2.8",
     "recoil": "^0.7.7",
-    "sharp": "^0.35.3",
     "svelte": "^5.56.8",
     "valtio": "^2.3.2",
     "vue": "^3.5.41",

package/dist/dom/blind-spots.d.ts

@@ -1,13 +0,0 @@
-/**
- * Blind-spot detection, the detectable half). Cross-origin iframes are a real observation gap — the
- * SDK cannot see inside them (same-origin policy). We COUNT them so a result can say "coverage: partial —
- * 2 cross-origin frames unobserved" instead of implying it saw the whole page. Closed shadow roots are a
- * blind spot too, but undetectable by design (element.shadowRoot === null), so they are not counted here.
- */
-/** Pure: how many frames are cross-origin, given each frame's same-origin flag + whether it has a src. */
-export declare function classifyCrossOriginFrames(frames: ReadonlyArray<{
-    sameOrigin: boolean;
-    hasSrc: boolean;
-}>): number;
-/** Probe the live document: count iframes whose document is unreachable (cross-origin). */
-export declare function countCrossOriginFrames(): number;

package/dist/dom/blind-spots.js

@@ -1,29 +0,0 @@
-/**
- * Blind-spot detection, the detectable half). Cross-origin iframes are a real observation gap — the
- * SDK cannot see inside them (same-origin policy). We COUNT them so a result can say "coverage: partial —
- * 2 cross-origin frames unobserved" instead of implying it saw the whole page. Closed shadow roots are a
- * blind spot too, but undetectable by design (element.shadowRoot === null), so they are not counted here.
- */
-/** Pure: how many frames are cross-origin, given each frame's same-origin flag + whether it has a src. */
-export function classifyCrossOriginFrames(frames) {
-    return frames.filter((f) => f.hasSrc && !f.sameOrigin).length;
-}
-/** Probe the live document: count iframes whose document is unreachable (cross-origin). */
-export function countCrossOriginFrames() {
-    if ('undefined' === typeof document)
-        return 0;
-    const frames = [];
-    for (const frame of document.querySelectorAll('iframe')) {
-        const hasSrc = frame.getAttribute('src') !== null && frame.getAttribute('src') !== '';
-        let sameOrigin;
-        try {
-            // Reaching contentDocument throws (or yields null) for a cross-origin frame.
-            sameOrigin = frame.contentDocument !== null;
-        }
-        catch {
-            sameOrigin = false;
-        }
-        frames.push({ sameOrigin, hasSrc });
-    }
-    return classifyCrossOriginFrames(frames);
-}

package/dist/observers/subresources.d.ts

@@ -1,10 +0,0 @@
-export interface SubresourceObservation {
-    url: string;
-    method: string;
-    status?: number;
-    ok?: boolean;
-    durationMs: number;
-    transferSize?: number;
-    initiatorType: string;
-}
-export declare function collectSubresources(seenUrls: ReadonlySet<string>, nowMs: number, sinceMs: number): SubresourceObservation[];

package/dist/observers/subresources.js

@@ -1,63 +0,0 @@
-import { redactUrl } from './network-redact.js';
-/**
- * Document-initiated subresource observation.
- *
- * fetch/XHR patches never see requests the DOCUMENT makes on its own: `<link rel=icon>`,
- * `<link rel=manifest>`, stylesheets, `<img src>`, `<script src>`. Those are exactly the loads a
- * branding change touches, so a `{net}` predicate over them used to return `assertion_failed`
- * ("your change is broken") when the truthful answer was "not observable" — and an agent trusting
- * that verdict goes and "fixes" working code.
- *
- * `performance.getEntriesByType('resource')` reports these with no CDP and no patching: URL (name),
- * initiator type (`link`, `css`, `img`, `script`, …), duration, transfer size. The known limitation
- * is the status code — resource timing does not expose one directly (`responseStatus` exists only
- * in newer Chromium). Entries carry `status` ONLY when it could be read; predicates asserting a
- * status over unreadable data are handled at the evaluation seam, which downgrades rather than
- * guesses.
- *
- * Deduplication matters: a fetch/XHR-initiated request ALSO lands in resource timing. Every entry
- * is checked against the URLs the patched transports already reported this page, and only genuinely
- * document-initiated loads survive.
- */
-/** Resource-timing initiator types that mean "the document itself asked", not a patched transport. */
-const DOCUMENT_INITIATORS = new Set(['link', 'css', 'img', 'script', 'manifest', 'other']);
-/** Cap per call — a pathological page must not blow the event budget. */
-const MAX_SUBRESOURCE_EVENTS = 200;
-export function collectSubresources(seenUrls, nowMs, sinceMs) {
-    const out = [];
-    try {
-        const entries = performance.getEntriesByType('resource');
-        for (const entry of entries) {
-            const initiatorType = entry.initiatorType || 'other';
-            // fetch/XHR already have richer records from their own patches.
-            if (!DOCUMENT_INITIATORS.has(initiatorType))
-                continue;
-            const raw = entry.name;
-            if (seenUrls.has(raw))
-                continue;
-            const startMs = nowMs - entry.duration;
-            if (startMs < sinceMs)
-                continue;
-            const obs = {
-                url: redactUrl(raw),
-                method: 'GET',
-                durationMs: Math.round(entry.duration),
-                initiatorType,
-                ...(entry.transferSize > 0 ? { transferSize: entry.transferSize } : {}),
-            };
-            // responseStatus is Chromium-only and may be 0 when unreadable. Present ONLY when it says
-            // something real, so the wire never carries a guessed status.
-            const rs = entry.responseStatus;
-            if ('number' === typeof rs && rs > 0) {
-                obs.status = rs;
-                obs.ok = rs >= 200 && rs < 400;
-            }
-            out.push(obs);
-        }
-    }
-    catch {
-        // No resource-timing support / security error: report nothing, honestly.
-        return [];
-    }
-    return out.slice(0, MAX_SUBRESOURCE_EVENTS);
-}