@reticlehq/browser 3.7.0 → 3.8.1

package/dist/actions/danger-context.js

@@ -1,4 +1,4 @@
-import { isDangerousActionText, outwardActionOf, outwardRefusal } from '@reticlehq/core';
+import { OutwardAction, isDangerousActionText, isDangerousNavigation, isInertHref, isPaymentField, outwardActionOf, outwardRefusal, withoutFilenameTokens, } from '@reticlehq/core';
 import { getAccessibleName, getRole } from '../dom/a11y.js';
 import { isHtmlElement } from '../dom/realm.js';
 const LABEL_VALUED_INPUT_TYPES = new Set([
@@ -8,35 +8,39 @@ const LABEL_VALUED_INPUT_TYPES = new Set([
     'image',
 ]);
 function holdsUserText(el) {
-    if (isHtmlElement(el) && el.isContentEditable)
+    if (isHtmlElement(el) && el.isContentEditable) {
         return true;
-    if (el instanceof HTMLTextAreaElement)
+    }
+    if (el instanceof HTMLTextAreaElement) {
         return true;
-    if (el instanceof HTMLInputElement)
+    }
+    if (el instanceof HTMLInputElement) {
         return !LABEL_VALUED_INPUT_TYPES.has(el.type.toLowerCase());
+    }
     return false;
 }
 const ANCHOR_TAG = 'A';
-const INERT_HREF = /^\s*(#.*|javascript:.*)?$/i;
 function navigatingHref(el) {
-    if (ANCHOR_TAG !== el.tagName)
+    if (ANCHOR_TAG !== el.tagName) {
         return undefined;
+    }
     const href = el.getAttribute('href');
-    return null === href || INERT_HREF.test(href) ? undefined : href;
+    return null === href || isInertHref(href) ? undefined : href;
 }
 export function dangerousActionContext(el) {
     const href = navigatingHref(el);
-    if (href !== undefined)
+    if (href !== undefined) {
         return href;
+    }
     const form = el.closest('form');
     const ownText = holdsUserText(el)
         ? ['', '']
         : [el.textContent ?? '', el.getAttribute('value') ?? ''];
     return [
-        getAccessibleName(el),
-        ...ownText,
-        el.getAttribute('title') ?? '',
-        el.getAttribute('aria-label') ?? '',
+        withoutFilenameTokens(getAccessibleName(el)),
+        withoutFilenameTokens(ownText.join(' ')),
+        withoutFilenameTokens(el.getAttribute('title') ?? ''),
+        withoutFilenameTokens(el.getAttribute('aria-label') ?? ''),
         el.getAttribute('href') ?? '',
         form?.getAttribute('action') ?? '',
     ].join(' ');
@@ -46,21 +50,43 @@ export function submitControlFor(el) {
     const found = el.closest('form')?.querySelector(SUBMIT_CONTROL_SELECTOR);
     return isHtmlElement(found) ? found : null;
 }
-export function requiresDangerousConfirmation(text, role) {
-    return isDangerousActionText(text, role);
+export function requiresDangerousConfirmation(el) {
+    const href = navigatingHref(el);
+    if (href !== undefined) {
+        return isDangerousNavigation(href);
+    }
+    return isDangerousActionText(dangerousActionContext(el), getRole(el));
 }
 let outwardAllowed;
 export function setOutwardPolicy(allowed) {
     outwardAllowed = allowed;
 }
 export function assertOutwardAllowed(targets) {
-    if (outwardAllowed === undefined)
+    if (outwardAllowed === undefined) {
         return;
+    }
     for (const el of targets) {
-        if (null === el)
+        if (null === el) {
             continue;
+        }
         const kind = outwardActionOf(dangerousActionContext(el), getRole(el));
-        if (kind !== undefined && !outwardAllowed.includes(kind))
+        if (kind !== undefined && !outwardAllowed.includes(kind)) {
             throw new Error(outwardRefusal(kind));
+        }
+    }
+}
+export function assertPaymentEntryAllowed(el) {
+    if (outwardAllowed === undefined || outwardAllowed.includes(OutwardAction.PAY)) {
+        return;
+    }
+    const facts = {
+        autocomplete: el.getAttribute('autocomplete') ?? undefined,
+        name: el.getAttribute('name') ?? undefined,
+        id: el.getAttribute('id') ?? undefined,
+        inputMode: el.getAttribute('inputmode') ?? undefined,
+        label: `${getAccessibleName(el)} ${el.getAttribute('placeholder') ?? ''}`,
+    };
+    if (isPaymentField(facts)) {
+        throw new Error(outwardRefusal(OutwardAction.PAY));
     }
 }

package/dist/actions/scroll.d.ts

@@ -11,6 +11,8 @@ interface ScrollResult {
     atLeftEnd: boolean;
     atRightEnd: boolean;
 }
+export declare const SCROLL_FRACTION_RANGE_ERROR_PREFIX = "scroll fraction must be between 0 and 1, got ";
+export declare function fractionOutOfRangeMessage(fraction: number): string;
 export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number, dx?: number): ScrollResult;
 export declare function scrollFrom(base: Element | undefined, dy: number | undefined, fraction?: number, dx?: number): ScrollResult;
 export {};

package/dist/actions/scroll.js

@@ -1,6 +1,10 @@
 import { refs } from '../dom/addressing/refs.js';
 const FALLBACK_STEP_PX = 400;
 const VIEWPORT_FRACTION = 0.8;
+export const SCROLL_FRACTION_RANGE_ERROR_PREFIX = 'scroll fraction must be between 0 and 1, got ';
+export function fractionOutOfRangeMessage(fraction) {
+    return `${SCROLL_FRACTION_RANGE_ERROR_PREFIX}${fraction}`;
+}
 function nearestScrollable(el, axis) {
     let cur = el;
     while (cur !== null && cur !== document.body) {
@@ -18,18 +22,22 @@ export function scrollContainer(ref, dy, fraction, dx) {
     return scrollFrom(base instanceof Element ? base : undefined, dy, fraction, dx);
 }
 export function scrollFrom(base, dy, fraction, dx) {
+    if (fraction !== undefined && (fraction < 0 || fraction > 1 || Number.isNaN(fraction))) {
+        throw new RangeError(fractionOutOfRangeMessage(fraction));
+    }
     const axis = dx !== undefined && dx !== 0 && (dy === undefined || 0 === dy) ? 'x' : 'y';
     const target = base !== undefined
         ? nearestScrollable(base, axis)
         : (document.scrollingElement ?? document.documentElement);
     const before = target.scrollTop;
     const beforeLeft = target.scrollLeft;
-    if (fraction !== undefined && fraction >= 0 && fraction <= 1) {
+    if (fraction !== undefined) {
         target.scrollTop = Math.round(target.scrollHeight * fraction);
     }
     else {
-        if (dx !== undefined && dx !== 0)
+        if (dx !== undefined && dx !== 0) {
             target.scrollLeft = beforeLeft + dx;
+        }
         if (dx === undefined || (dy !== undefined && 0 !== dy)) {
             const step = dy ?? (Math.round(target.clientHeight * VIEWPORT_FRACTION) || FALLBACK_STEP_PX);
             target.scrollTop = before + step;

package/dist/activate.d.ts

@@ -0,0 +1,14 @@
+import type { ReticleConnectOptions } from './connect-options.js';
+export interface ActivateOptions {
+    publicKey: string;
+}
+export interface ActivateHost {
+    location: Pick<Location, 'href' | 'origin'>;
+    history: Pick<History, 'replaceState' | 'state'>;
+    now: () => number;
+    connect: () => Promise<{
+        connect: (options: ReticleConnectOptions) => void;
+    }>;
+    warn: (message: string) => void;
+}
+export declare function activate(options: ActivateOptions, host?: ActivateHost | undefined): Promise<boolean>;

package/dist/activate.js

@@ -0,0 +1,43 @@
+import { HelloEnv, PRODUCTION_ACTIVATE_PARAM, verifyActivationTicket, } from '@reticlehq/core/activation';
+const REFUSED_PREFIX = '[Reticle] activation refused: ';
+function pageHost() {
+    if ('undefined' === typeof location || 'undefined' === typeof history)
+        return undefined;
+    return {
+        location,
+        history,
+        now: () => Date.now(),
+        connect: () => import('./reticle-singleton.js').then((sdk) => sdk.reticle),
+        warn: (message) => console.warn(message),
+    };
+}
+export async function activate(options, host = pageHost()) {
+    if (host === undefined)
+        return false;
+    const url = new URL(host.location.href);
+    const ticket = url.searchParams.get(PRODUCTION_ACTIVATE_PARAM);
+    if (null === ticket)
+        return false;
+    url.searchParams.delete(PRODUCTION_ACTIVATE_PARAM);
+    host.history.replaceState(host.history.state, '', url.toString());
+    const verdict = await verifyActivationTicket(ticket, {
+        publicKey: options.publicKey,
+        origin: host.location.origin,
+        now: host.now(),
+    });
+    if (!verdict.ok) {
+        host.warn(`${REFUSED_PREFIX}${verdict.reason}`);
+        return false;
+    }
+    const { payload } = verdict;
+    const sdk = await host.connect();
+    sdk.connect({
+        url: payload.bridge,
+        token: payload.nonce,
+        env: HelloEnv.PRODUCTION,
+        scope: payload.scope,
+        allowInProduction: true,
+        allowNonLocalhost: true,
+    });
+    return true;
+}

package/dist/busy.d.ts

@@ -0,0 +1,3 @@
+export declare function trackBusy<T>(work: Promise<T>, signal: (name: string, data: Record<string, unknown>) => void): Promise<T>;
+export declare const SHORT_TIMER_MS = 1000;
+export declare function trackShortTimers(signal: (name: string, data: Record<string, unknown>) => void, maxMs?: number): () => void;

package/dist/busy.js

@@ -0,0 +1,42 @@
+import { RETICLE_BUSY_SIGNAL } from '@reticlehq/core';
+import { captureMethod } from './patching/capture-method.js';
+export function trackBusy(work, signal) {
+    signal(RETICLE_BUSY_SIGNAL, { delta: 1 });
+    const done = () => {
+        signal(RETICLE_BUSY_SIGNAL, { delta: -1 });
+    };
+    work.then(done, done);
+    return work;
+}
+export const SHORT_TIMER_MS = 1000;
+export function trackShortTimers(signal, maxMs = SHORT_TIMER_MS) {
+    const realSet = captureMethod(window, 'setTimeout');
+    const realClear = captureMethod(window, 'clearTimeout');
+    const callSet = realSet.bind(window);
+    const callClear = realClear.bind(window);
+    const pending = new Set();
+    const end = (id) => {
+        if (pending.delete(id))
+            signal(RETICLE_BUSY_SIGNAL, { delta: -1 });
+    };
+    window.setTimeout = ((cb, delay = 0, ...args) => {
+        if ('function' !== typeof cb || delay > maxMs)
+            return Reflect.apply(realSet, window, [cb, delay, ...args]);
+        signal(RETICLE_BUSY_SIGNAL, { delta: 1 });
+        const id = callSet(() => {
+            end(id);
+            cb(...args);
+        }, delay);
+        pending.add(id);
+        return id;
+    });
+    window.clearTimeout = ((id) => {
+        if (id !== undefined)
+            end(id);
+        callClear(id);
+    });
+    return () => {
+        window.setTimeout = realSet;
+        window.clearTimeout = realClear;
+    };
+}

package/dist/commands/commands.js

@@ -1,4 +1,4 @@
-import { ComponentStateReason, ElementQuerySchema, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
+import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
 import { buildSnapshot } from '../dom/snapshot.js';
 import { paintContextOf } from '../dom/paint-context.js';
 import { matchQuery, runQuery } from '../dom/query.js';
@@ -11,6 +11,7 @@ import { editEpoch } from '../edit-epoch.js';
 import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
+import { canvasAfterAct } from '../observers/canvas.js';
 import { captureDesktopWindow } from '../dom/desktop-capture.js';
 import { identifyComponent, readComponentState } from '../registry/stores/adapters.js';
 import { readStoresWithTruncation, readStoresRaw, storeNames } from '../registry/stores.js';
@@ -18,6 +19,7 @@ import { sanitizeWithReport } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { freezeClock, advanceClock, resetClock, isClockFrozen } from '../timers/clock.js';
 import { scrollContainer } from '../actions/scroll.js';
+import { isOffViewport } from '../actions/actions-dom.js';
 export const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
 function str(value) {
     return 'string' === typeof value ? value : undefined;
@@ -29,11 +31,13 @@ function record(value) {
     return 'object' === typeof value && value !== null ? value : {};
 }
 function sourceLocation(value) {
-    if (typeof value !== 'object' || null === value)
+    if (typeof value !== 'object' || null === value) {
         return undefined;
+    }
     const obj = value;
-    if (typeof obj['file'] !== 'string' || typeof obj['line'] !== 'number')
+    if (typeof obj['file'] !== 'string' || typeof obj['line'] !== 'number') {
         return undefined;
+    }
     return { file: obj['file'], line: obj['line'], column: num(obj['column']) };
 }
 function queryFromArgs(args) {
@@ -56,10 +60,17 @@ function queryFromArgs(args) {
         source: sourceLocation(args['source']),
     };
 }
-function inspect(ref) {
+function inspect(ref, reveal = false) {
     const el = refs.resolve(ref);
-    if (null === el)
+    if (null === el) {
         throw new Error(editEpoch.staleRefMessage(ref));
+    }
+    const scrolledIntoView = reveal &&
+        'function' === typeof el.scrollIntoView &&
+        isOffViewport(el, el.getBoundingClientRect());
+    if (scrolledIntoView) {
+        el.scrollIntoView({ block: 'center', inline: 'center' });
+    }
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
     const view = el.ownerDocument.defaultView;
@@ -101,6 +112,8 @@ function inspect(ref) {
         formAction: isButton(el) || isInput(el) ? (el.form?.getAttribute('action') ?? undefined) : undefined,
         formText: isButton(el) || isInput(el) ? (el.form?.textContent ?? undefined) : undefined,
         box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+        ...(scrolledIntoView ? { scrolledIntoView: true } : {}),
+        ...(reveal ? { [INSPECT_IN_VIEWPORT_FIELD]: !isOffViewport(el, rect) } : {}),
         occluded: isOccluded(el, rect),
         styles,
         scroll,
@@ -145,8 +158,9 @@ function readState(ref, store, path, depth) {
         stores,
         storeNames: names,
     };
-    if (truncation !== undefined)
+    if (truncation !== undefined) {
         result.truncation = truncation;
+    }
     if (ref !== undefined && ref.length > 0) {
         const el = refs.resolve(ref);
         if (null === el) {
@@ -161,8 +175,9 @@ function readState(ref, store, path, depth) {
 }
 function listAnimations() {
     const doc = document;
-    if (typeof doc.getAnimations !== 'function')
+    if (typeof doc.getAnimations !== 'function') {
         return { animations: [] };
+    }
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
@@ -177,8 +192,9 @@ function listAnimations() {
     return { animations };
 }
 export function resolveNavigationUrl(rawUrl, baseUrl) {
-    if (0 === rawUrl.length || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH)
+    if (0 === rawUrl.length || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH) {
         return null;
+    }
     try {
         const url = new URL(rawUrl, baseUrl);
         return 'http:' === url.protocol || 'https:' === url.protocol ? url.toString() : null;
@@ -193,29 +209,39 @@ export function createCommandRegistry() {
         scope: str(args['scope']),
         mode: str(args['mode']) ?? SnapshotMode.FULL,
         includeRoot: true === args['includeRoot'],
+        ids: true === args['ids'],
+        audit: true === args['audit'],
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
         const limit = args['limit'];
         return runQuery(queryFromArgs(args), 'number' === typeof limit ? limit : undefined);
     });
-    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state'])));
-    reg.set(ReticleCommand.ACT, (args) => {
+    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state']), undefined, undefined, true === args['diagnose']));
+    reg.set(ReticleCommand.ACT, async (args) => {
         const action = str(args['action']) ?? '';
-        return executeAction(str(args['ref']) ?? '', action, record(args['args']));
+        const result = await executeAction(str(args['ref']) ?? '', action, record(args['args']));
+        canvasAfterAct();
+        return result;
+    });
+    reg.set(ReticleCommand.ACT_SEQUENCE, async (args) => {
+        const result = await executeSequence((Array.isArray(args['steps']) ? args['steps'] : []));
+        canvasAfterAct();
+        return result;
     });
-    reg.set(ReticleCommand.ACT_SEQUENCE, (args) => executeSequence((Array.isArray(args['steps']) ? args['steps'] : [])));
-    reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? ''));
+    reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? '', true === args[INSPECT_REVEAL_ARG]));
     reg.set(ReticleCommand.ANIMATIONS, () => listAnimations());
     reg.set(ReticleCommand.CLOCK, (args) => {
         if (true === args['reset']) {
             resetClock();
         }
         else {
-            if (true === args['freeze'])
+            if (true === args['freeze']) {
                 freezeClock();
+            }
             const adv = args['advanceMs'];
-            if ('number' === typeof adv)
+            if ('number' === typeof adv) {
                 advanceClock(adv);
+            }
         }
         return { frozen: isClockFrozen() };
     });
@@ -231,11 +257,13 @@ export function createCommandRegistry() {
     });
     reg.set(ReticleCommand.NAVIGATE, (args) => {
         const rawUrl = str(args['url']);
-        if (rawUrl === undefined || 0 === rawUrl.length)
+        if (rawUrl === undefined || 0 === rawUrl.length) {
             return { ok: false, reason: 'url required' };
+        }
         const url = resolveNavigationUrl(rawUrl, window.location.href);
-        if (null === url)
+        if (null === url) {
             return { ok: false, reason: 'only http(s) navigation is allowed' };
+        }
         window.location.assign(url);
         return { ok: true, url };
     });

package/dist/connect-options.d.ts

@@ -1,4 +1,4 @@
-import type { RedactionConfig } from '@reticlehq/core';
+import { HelloInstrumentation, type HelloEnv, type HelloScope, type RedactionConfig } from '@reticlehq/core';
 export interface ReticleConnectOptions {
     url?: string;
     session?: string;
@@ -6,6 +6,10 @@ export interface ReticleConnectOptions {
     token?: string;
     allowNonLocalhost?: boolean;
     allowInProduction?: boolean;
+    env?: HelloEnv;
+    scope?: HelloScope;
+    injected?: boolean;
+    lease?: boolean;
     testIdAttribute?: string;
     overlay?: boolean;
     captureNetworkBodies?: boolean;
@@ -26,3 +30,10 @@ export interface ReticleConnectOptions {
     idleEndMs?: number;
     redact?: RedactionConfig;
 }
+export declare function helloMode(options: Pick<ReticleConnectOptions, 'env' | 'scope' | 'injected'>): {
+    env?: HelloEnv;
+    scope?: HelloScope;
+    instrumentation?: HelloInstrumentation;
+};
+export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
+export declare function leaseToken(options: ReticleConnectOptions, current: string | undefined): string | undefined;

package/dist/connect-options.js

@@ -1 +1,18 @@
-export {};
+import { HelloInstrumentation, } from '@reticlehq/core';
+export function helloMode(options) {
+    return {
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.scope === undefined ? {} : { scope: options.scope }),
+        ...(true === options.injected ? { instrumentation: HelloInstrumentation.INJECTED } : {}),
+    };
+}
+export function shouldBlockProduction(nodeEnv, allowInProduction) {
+    return 'production' === nodeEnv && !allowInProduction;
+}
+export function leaseToken(options, current) {
+    const token = options.token;
+    if (true !== options.lease || token === undefined || 0 === token.length || token === current) {
+        return undefined;
+    }
+    return token;
+}

package/dist/dom/a11y.d.ts

@@ -4,6 +4,4 @@ export declare function getAccessibleName(el: Element): string;
 export declare function getStates(el: Element, visible?: boolean): ElementState[];
 export declare function isSensitiveField(el: Element): boolean;
 export declare function getValue(el: Element): string | undefined;
-export declare function isInViewport(el: Element, memo?: Map<Element, boolean>): boolean;
-export declare function isVisible(el: Element, memo?: Map<Element, boolean>): boolean;
 export declare function describe(el: Element, memo?: Map<Element, boolean>): ElementDescriptor;