@reticlehq/browser 2.7.0 → 2.9.0

package/dist/timers/clock.js

@@ -2,6 +2,7 @@
 // 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.
+import { requireCapturedMethod } from '../util/captured-method.js';
 let installed = false;
 let virtualNow = 0;
 let realBase = 0;
@@ -17,12 +18,14 @@ export function freezeClock() {
     installed = true;
     virtualNow = 0;
     realBase = Date.now();
+    // Captured as stored VALUES, so teardown restores the same function objects the page had. See
+    // capturedMethod: these are deliberate unbound captures and the descriptor read says so.
     originals = {
-        setTimeout: window.setTimeout,
-        clearTimeout: window.clearTimeout,
-        setInterval: window.setInterval,
-        clearInterval: window.clearInterval,
-        dateNow: Date.now,
+        setTimeout: requireCapturedMethod(window, 'setTimeout'),
+        clearTimeout: requireCapturedMethod(window, 'clearTimeout'),
+        setInterval: requireCapturedMethod(window, 'setInterval'),
+        clearInterval: requireCapturedMethod(window, 'clearInterval'),
+        dateNow: requireCapturedMethod(Date, 'now'),
     };
     const schedule = (cb, delay, interval) => {
         const id = seq;

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

@@ -0,0 +1,12 @@
+/**
+ * What the page says when its websocket never opened.
+ *
+ * Pulled out of the connect path so it is a pure string function with a test on its CLAIMS rather
+ * 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.
+ */
+/**
+ * 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 declare function unreachableMessage(url: string, attempts: number): string;

package/dist/transport/unreachable-message.js

@@ -0,0 +1,20 @@
+/**
+ * What the page says when its websocket never opened.
+ *
+ * Pulled out of the connect path so it is a pure string function with a test on its CLAIMS rather
+ * 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.
+ */
+/**
+ * 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 ` +
+        `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 ` +
+        `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…`);
+}

package/dist/util/captured-method.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read a host object's method as a STORED VALUE, for code that has to put it back.
+ *
+ * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
+ * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
+ * object, so teardown restores exactly what was there and a later install can recognise it by
+ * identity — and calling through a separately bound copy, because a host method invoked with the
+ * wrong receiver throws (`fetch` gives "Illegal invocation").
+ *
+ * Written as `const original = window.fetch`, that is a bare unbound method reference, and
+ * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
+ * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
+ * the slot it came from.
+ *
+ * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
+ * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
+ * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
+ * reason the binding exists.
+ *
+ * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
+ * value, not a method being detached from its object, which is exactly the distinction the rule is
+ * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
+ * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
+ * defined on the object cannot be silently flattened into its result.
+ *
+ * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
+ * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
+ */
+export declare function capturedMethod<T>(target: object, key: PropertyKey): T | undefined;
+/**
+ * The same, for a property this code knows is present — the globals every observer patches.
+ *
+ * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
+ * caller here can recover from, and silently installing a patch that cannot be undone is worse than
+ * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
+ */
+export declare function requireCapturedMethod<T>(target: object, key: PropertyKey): T;

package/dist/util/captured-method.js

@@ -0,0 +1,45 @@
+/**
+ * Read a host object's method as a STORED VALUE, for code that has to put it back.
+ *
+ * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
+ * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
+ * object, so teardown restores exactly what was there and a later install can recognise it by
+ * identity — and calling through a separately bound copy, because a host method invoked with the
+ * wrong receiver throws (`fetch` gives "Illegal invocation").
+ *
+ * Written as `const original = window.fetch`, that is a bare unbound method reference, and
+ * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
+ * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
+ * the slot it came from.
+ *
+ * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
+ * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
+ * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
+ * reason the binding exists.
+ *
+ * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
+ * value, not a method being detached from its object, which is exactly the distinction the rule is
+ * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
+ * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
+ * defined on the object cannot be silently flattened into its result.
+ *
+ * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
+ * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
+ */
+export function capturedMethod(target, key) {
+    return Object.getOwnPropertyDescriptor(target, key)?.value;
+}
+/**
+ * The same, for a property this code knows is present — the globals every observer patches.
+ *
+ * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
+ * caller here can recover from, and silently installing a patch that cannot be undone is worse than
+ * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
+ */
+export function requireCapturedMethod(target, key) {
+    const value = capturedMethod(target, key);
+    if (value === undefined) {
+        throw new Error(`[Reticle] cannot patch ${String(key)}: it is not an own property of the target`);
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,17 +14,20 @@
   },
   "dependencies": {
     "@testing-library/dom": "^10.4.1",
-    "@reticlehq/core": "2.7.0"
+    "@reticlehq/core": "2.9.0"
   },
   "devDependencies": {
+    "@iconify-json/heroicons-outline": "^1.2.1",
+    "@iconify-json/heroicons-solid": "^1.2.1",
     "@tanstack/query-core": "^5.101.4",
-    "@types/jsdom": "^28.0.3",
+    "@types/jsdom": "^30.0.0",
     "jotai": "^2.20.2",
-    "jsdom": "^29.1.1",
+    "jsdom": "^30.0.1",
     "mobx": "^7.0.0",
-    "pinia": "^4.0.2",
+    "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",
@@ -59,7 +62,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsc -b",
+    "build": "node scripts/embed-heroicons.mjs && tsc -b",
     "typecheck": "tsc -b",
     "lint": "eslint src",
     "test:unit": "vitest run src --passWithNoTests",