@reticlehq/browser 3.6.0 → 3.8.0

package/dist/actions/danger-context.js

@@ -1,5 +1,5 @@
-import { isDangerousActionText } from '@reticlehq/core';
-import { getAccessibleName } from '../dom/a11y.js';
+import { OutwardAction, isDangerousActionText, isInertHref, isDangerousNavigation, isPaymentField, outwardActionOf, outwardRefusal, } from '@reticlehq/core';
+import { getAccessibleName, getRole } from '../dom/a11y.js';
 import { isHtmlElement } from '../dom/realm.js';
 const LABEL_VALUED_INPUT_TYPES = new Set([
     'submit',
@@ -16,7 +16,17 @@ function holdsUserText(el) {
         return !LABEL_VALUED_INPUT_TYPES.has(el.type.toLowerCase());
     return false;
 }
+const ANCHOR_TAG = 'A';
+function navigatingHref(el) {
+    if (ANCHOR_TAG !== el.tagName)
+        return undefined;
+    const href = el.getAttribute('href');
+    return null === href || isInertHref(href) ? undefined : href;
+}
 export function dangerousActionContext(el) {
+    const href = navigatingHref(el);
+    if (href !== undefined)
+        return href;
     const form = el.closest('form');
     const ownText = holdsUserText(el)
         ? ['', '']
@@ -35,6 +45,37 @@ 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)
+        return;
+    for (const el of targets) {
+        if (null === el)
+            continue;
+        const kind = outwardActionOf(dangerousActionContext(el), getRole(el));
+        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/value-input.d.ts

@@ -1,4 +1,5 @@
 import { type ActionTarget } from '../dom/realm.js';
+export declare function isAutofillSafeTarget(el: Element, ua?: string): boolean;
 export declare function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): boolean;
 export declare function assertNotRichText(el: ActionTarget, action: string): void;
 export declare function assertEditable(el: HTMLInputElement | HTMLTextAreaElement, action: string): void;

package/dist/actions/value-input.js

@@ -1,5 +1,16 @@
 import { captureValueSetter } from '../patching/capture-method.js';
 import { isHtmlElement, valuePrototypeOf } from '../dom/realm.js';
+const PASSWORD_AUTOCOMPLETE = /\b(current|new)-password\b/;
+const NOT_WEBKIT = /Chrome|Chromium|Edg\/|Firefox|Gecko\//;
+export function isAutofillSafeTarget(el, ua = navigator.userAgent) {
+    if (!(el instanceof HTMLInputElement))
+        return false;
+    const password = 'password' === el.type.toLowerCase() ||
+        PASSWORD_AUTOCOMPLETE.test(el.getAttribute('autocomplete') ?? '');
+    if (!password || NOT_WEBKIT.test(ua))
+        return false;
+    return 600 <= Number(/AppleWebKit\/(\d+)/.exec(ua)?.[1] ?? 0);
+}
 export function setNativeValue(el, value) {
     const proto = valuePrototypeOf(el);
     const setter = proto === undefined ? undefined : captureValueSetter(proto);

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,
@@ -122,6 +135,9 @@ function readState(ref, store, path, depth) {
     const names = storeNames();
     if (path !== undefined || depth !== undefined) {
         const rawStores = readStoresRaw(store);
+        if (store !== undefined && !Object.hasOwn(rawStores, store)) {
+            return { store, path, found: false, value: null, storeNames: names };
+        }
         const base = store !== undefined ? rawStores[store] : { stores: rawStores, storeNames: names };
         const selection = path !== undefined ? selectPath(base, path) : { found: true, value: base };
         const selected = selection.found && depth !== undefined ? capDepth(selection.value, depth) : selection.value;
@@ -142,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) {
@@ -158,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();
@@ -174,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;
@@ -190,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() };
     });
@@ -220,6 +249,7 @@ export function createCommandRegistry() {
     reg.set(ReticleCommand.STORAGE_READ, (args) => readStorage(str(args['area'])));
     reg.set(ReticleCommand.CAPABILITIES, () => getCapabilities());
     reg.set(ReticleCommand.CAPTURE, (args) => captureDesktopWindow(true === args['fullPage']));
+    reg.set(ReticleCommand.RENDER, () => import('../dom/render-page.js').then((m) => m.renderPage()));
     reg.set(ReticleCommand.SCROLL, (args) => {
         const dy = args['dy'];
         const fraction = args['fraction'];
@@ -227,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,8 @@ 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 isHiddenByAriaOnly(el: Element): boolean;
+export declare function isRenderedOutsideAriaHidden(el: Element): boolean;
 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;