@reticlehq/browser 3.6.0 → 3.7.0

package/dist/actions/action-report.d.ts

@@ -0,0 +1,54 @@
+import { type SettleReason } from '@reticlehq/core';
+export interface ActionEffect {
+    dispatched: true;
+    targetMatched: boolean;
+    visible: boolean;
+    enabled: boolean;
+    defaultPrevented: boolean;
+    focusMoved: string | null;
+    valueChanged: boolean;
+    autofillSafe?: true;
+    domMutatedWithin: number;
+    appeared?: string;
+    occluded: boolean;
+    occludedBy: string | null;
+    scrolledIntoView: boolean;
+    heldMs?: number;
+    alreadyAtValue?: true;
+}
+export interface ActionResult {
+    ok: true;
+    ref: string;
+    action: string;
+    dispatched: boolean;
+    settled: boolean;
+    settleReason: SettleReason | null;
+    effect: ActionEffect;
+    testid?: string;
+    component?: string;
+    role?: string;
+    name?: string;
+    nth?: number;
+    of?: number;
+    source?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
+    warning?: string;
+}
+export interface CapturedAnchor {
+    testid?: string;
+    component?: string;
+    source?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
+    role?: string;
+    name?: string;
+    nth?: number;
+    of?: number;
+}
+export declare function anchorOf(el: Element): CapturedAnchor;
+export declare const result: (ref: string, action: string, effect: ActionEffect, settled: boolean, settleReason: SettleReason | null, anchor: CapturedAnchor, warning?: string) => ActionResult;

package/dist/actions/action-report.js

@@ -0,0 +1,60 @@
+import { readTestId } from '../dom/addressing/testid-attr.js';
+import { QueryBy } from '@reticlehq/core';
+import { elementsMatching } from '../dom/query.js';
+import { getAccessibleName, getRole } from '../dom/a11y.js';
+import { identifyComponent } from '../registry/stores/adapters.js';
+export function anchorOf(el) {
+    const testid = readTestId(el) ?? undefined;
+    const info = identifyComponent(el);
+    const out = {};
+    if (testid !== undefined)
+        out.testid = testid;
+    const component = info?.componentStack[0];
+    if (component !== undefined)
+        out.component = component;
+    if (info?.source !== undefined)
+        out.source = info.source;
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+    if (role.length > 0)
+        out.role = role;
+    if (name.length > 0)
+        out.name = name;
+    if (role.length > 0 && name.length > 0) {
+        const same = elementsMatching({ by: QueryBy.ROLE, value: role, name });
+        const at = same.indexOf(el);
+        if (1 < same.length && 0 <= at) {
+            out.nth = at;
+            out.of = same.length;
+        }
+    }
+    return out;
+}
+export const result = (ref, action, effect, settled, settleReason, anchor, warning) => {
+    const base = {
+        ok: true,
+        ref,
+        action,
+        dispatched: true,
+        settled,
+        settleReason,
+        effect,
+    };
+    if (anchor.testid !== undefined)
+        base.testid = anchor.testid;
+    if (anchor.component !== undefined)
+        base.component = anchor.component;
+    if (anchor.source !== undefined)
+        base.source = anchor.source;
+    if (anchor.role !== undefined)
+        base.role = anchor.role;
+    if (anchor.name !== undefined)
+        base.name = anchor.name;
+    if (anchor.nth !== undefined)
+        base.nth = anchor.nth;
+    if (anchor.of !== undefined)
+        base.of = anchor.of;
+    if (warning !== undefined)
+        base.warning = warning;
+    return base;
+};

package/dist/actions/actions-dom.d.ts

@@ -26,4 +26,5 @@ export declare function fireTapSequence(el: ActionTarget, hold: {
     prevented: boolean;
     heldMs: number;
 }>;
+export declare function assertNotLeaving(el: Element): void;
 export {};

package/dist/actions/actions-dom.js

@@ -231,3 +231,15 @@ function makeTouchEvent(type, touches) {
     }
     return new Event(type, { bubbles: true, cancelable: true });
 }
+const POPUP_ROLES = new Set(['menu', 'menubar', 'listbox', 'dialog', 'alertdialog', 'tooltip']);
+const CLOSED_STATE = 'closed';
+export function assertNotLeaving(el) {
+    for (let up = el.parentElement; up !== null; up = up.parentElement) {
+        if (CLOSED_STATE !== up.getAttribute('data-state'))
+            continue;
+        if (!POPUP_ROLES.has(up.getAttribute('role') ?? ''))
+            continue;
+        throw new Error(`'${up.getAttribute('role') ?? 'popup'}' holding this element is closing (data-state="closed"), ` +
+            'so a person could not click it: look again once it has gone and act on what is open');
+    }
+}

package/dist/actions/actions-press.d.ts

@@ -8,6 +8,7 @@ export interface ModifierFlags {
 }
 export declare function pressModifiers(args: Record<string, unknown>): ModifierFlags;
 export declare function pressCode(args: Record<string, unknown>, key: string): string;
+export declare function dispatchKeypress(el: ActionTarget, key: string, code: string, mods: ModifierFlags, repeat?: boolean): void;
 export declare function focusedOrDocument(): HTMLElement;
 export declare function isReflessDocumentPress(ref: string, action: string, args: Record<string, unknown>): boolean;
 export declare function pressKeys(args: Record<string, unknown>): string[];

package/dist/actions/actions-press.js

@@ -57,6 +57,26 @@ export function pressCode(args, key) {
     }
     return /^[A-Z][A-Za-z0-9]*$/.test(key) && KNOWN_NAMED_KEYS.has(key) ? key : '';
 }
+export function dispatchKeypress(el, key, code, mods, repeat = false) {
+    if (ENTER_KEY !== key && 1 !== key.length)
+        return;
+    const event = new KeyboardEvent('keypress', {
+        key,
+        code,
+        bubbles: true,
+        cancelable: true,
+        repeat,
+        ...mods,
+    });
+    const legacy = ENTER_KEY === key ? ENTER_CHAR_CODE : key.charCodeAt(0);
+    for (const field of LEGACY_KEY_CODE_FIELDS) {
+        Object.defineProperty(event, field, { value: legacy });
+    }
+    asSyntheticInput(() => el.dispatchEvent(event));
+}
+const ENTER_KEY = 'Enter';
+const ENTER_CHAR_CODE = 13;
+const LEGACY_KEY_CODE_FIELDS = ['keyCode', 'charCode', 'which'];
 const KNOWN_NAMED_KEYS = new Set([
     'Enter',
     'Escape',
@@ -139,7 +159,7 @@ export async function holdKey(el, key, code, mods, ms) {
     if (ms > KEY_REPEAT_DELAY_MS)
         await sleep(KEY_REPEAT_DELAY_MS);
     while (Date.now() - started < ms) {
-        asSyntheticInput(() => el.dispatchEvent(keyboardEvent('keydown', {
+        const down = asSyntheticInput(() => el.dispatchEvent(keyboardEvent('keydown', {
             key,
             code,
             bubbles: true,
@@ -147,6 +167,8 @@ export async function holdKey(el, key, code, mods, ms) {
             repeat: true,
             ...mods,
         })));
+        if (down)
+            dispatchKeypress(el, key, code, mods, true);
         await sleep(Math.min(KEY_REPEAT_MS, Math.max(0, ms - (Date.now() - started))));
     }
 }
@@ -179,6 +201,8 @@ export async function pressCombo(el, keys, mods, holdMs) {
         const ok = dispatch('keydown', key);
         if (!ok)
             prevented = true;
+        if (ok)
+            dispatchKeypress(el, key, pressCode({}, key), held);
         closeModalOnEscape(el, key, ok);
     }
     if (holdMs > 0)

package/dist/actions/actions.d.ts

@@ -1,41 +1,5 @@
 import { SettleReason } from '@reticlehq/core';
-interface ActionEffect {
-    dispatched: true;
-    targetMatched: boolean;
-    visible: boolean;
-    enabled: boolean;
-    defaultPrevented: boolean;
-    focusMoved: string | null;
-    valueChanged: boolean;
-    domMutatedWithin: number;
-    appeared?: string;
-    occluded: boolean;
-    occludedBy: string | null;
-    scrolledIntoView: boolean;
-    heldMs?: number;
-    alreadyAtValue?: true;
-}
-interface ActionResult {
-    ok: true;
-    ref: string;
-    action: string;
-    dispatched: boolean;
-    settled: boolean;
-    settleReason: SettleReason | null;
-    effect: ActionEffect;
-    testid?: string;
-    component?: string;
-    role?: string;
-    name?: string;
-    nth?: number;
-    of?: number;
-    source?: {
-        file: string;
-        line: number;
-        column?: number;
-    };
-    warning?: string;
-}
+import { type ActionEffect, type ActionResult } from './action-report.js';
 export declare const ZOOM_NEEDS_REAL_BROWSER_MSG: string;
 export declare function executeAction(ref: string, action: string, args?: Record<string, unknown>): Promise<ActionResult>;
 export interface ActionStep {

package/dist/actions/actions.js

@@ -1,17 +1,16 @@
-import { readTestId } from '../dom/addressing/testid-attr.js';
-import { ActionType, ActionWarning, clampHoldMs, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, QueryBy, SettleReason, } from '@reticlehq/core';
-import { elementsMatching } from '../dom/query.js';
+import { ActionType, ActionWarning, clampHoldMs, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
 import { asSyntheticInput } from './synthetic/synthetic-input.js';
 import { echoRef, refs } from '../dom/addressing/refs.js';
-import { dangerousActionContext, requiresDangerousConfirmation, submitControlFor, } from './danger-context.js';
-import { assertEditable, assertNotRichText, setNativeValue } from './value-input.js';
-import { getAccessibleName, getRole, isVisible, getStates } from '../dom/a11y.js';
-import { elementHasHoverHandlers, identifyComponent } from '../registry/stores/adapters.js';
+import { dangerousActionContext, requiresDangerousConfirmation, assertOutwardAllowed, submitControlFor, } from './danger-context.js';
+import { assertEditable, assertNotRichText, isAutofillSafeTarget, setNativeValue, } from './value-input.js';
+import { getRole, isVisible, getStates } from '../dom/a11y.js';
+import { elementHasHoverHandlers } from '../registry/stores/adapters.js';
 import { isActionTarget, isForm, isInput, isSelect, isTextArea, } from '../dom/realm.js';
 import { nativeSetTimeout, settle } from '../timers/native/native-timers.js';
 import { AppearedText } from './appeared-text.js';
 import { alreadyAtCheckedState, assertAriaToggleLanded, isAriaToggle } from './check-state.js';
-import { focusedOrDocument, isReflessDocumentPress, pressCode, pressKey, pressModifiers, pressKeys, holdKey, pressCombo, closeModalOnEscape, keyboardEvent, } from './actions-press.js';
+import { focusedOrDocument, isReflessDocumentPress, pressCode, pressKey, pressModifiers, pressKeys, holdKey, pressCombo, dispatchKeypress, closeModalOnEscape, keyboardEvent, } from './actions-press.js';
+import { anchorOf, result } from './action-report.js';
 function asString(value, fallback = '') {
     return 'string' === typeof value ? value : fallback;
 }
@@ -23,61 +22,6 @@ function requireElement(ref) {
         throw new Error(`ref '${echoRef(ref)}' is not an HTML or SVG element`);
     return el;
 }
-function anchorOf(el) {
-    const testid = readTestId(el) ?? undefined;
-    const info = identifyComponent(el);
-    const out = {};
-    if (testid !== undefined)
-        out.testid = testid;
-    const component = info?.componentStack[0];
-    if (component !== undefined)
-        out.component = component;
-    if (info?.source !== undefined)
-        out.source = info.source;
-    const role = getRole(el);
-    const name = getAccessibleName(el);
-    if (role.length > 0)
-        out.role = role;
-    if (name.length > 0)
-        out.name = name;
-    if (role.length > 0 && name.length > 0) {
-        const same = elementsMatching({ by: QueryBy.ROLE, value: role, name });
-        const at = same.indexOf(el);
-        if (1 < same.length && 0 <= at) {
-            out.nth = at;
-            out.of = same.length;
-        }
-    }
-    return out;
-}
-const result = (ref, action, effect, settled, settleReason, anchor, warning) => {
-    const base = {
-        ok: true,
-        ref,
-        action,
-        dispatched: true,
-        settled,
-        settleReason,
-        effect,
-    };
-    if (anchor.testid !== undefined)
-        base.testid = anchor.testid;
-    if (anchor.component !== undefined)
-        base.component = anchor.component;
-    if (anchor.source !== undefined)
-        base.source = anchor.source;
-    if (anchor.role !== undefined)
-        base.role = anchor.role;
-    if (anchor.name !== undefined)
-        base.name = anchor.name;
-    if (anchor.nth !== undefined)
-        base.nth = anchor.nth;
-    if (anchor.of !== undefined)
-        base.of = anchor.of;
-    if (warning !== undefined)
-        base.warning = warning;
-    return base;
-};
 const FILL_LIKE = new Set([
     ActionType.FILL,
     ActionType.TYPE,
@@ -123,6 +67,8 @@ function assertActionAllowed(el, action, args) {
         (action === ActionType.PRESS && 'Enter' === pressKey(args));
     const dragTarget = action === ActionType.DRAG ? refs.resolve(dragTargetRef(args)) : null;
     const submitter = action === ActionType.PRESS && 'Enter' === pressKey(args) ? submitControlFor(el) : null;
+    if (canTrigger)
+        assertOutwardAllowed([el, submitter, isActionTarget(dragTarget) ? dragTarget : null]);
     const sourceDangerous = requiresDangerousConfirmation(dangerousActionContext(el), getRole(el)) ||
         (submitter !== null &&
             requiresDangerousConfirmation(dangerousActionContext(submitter), getRole(submitter)));
@@ -134,7 +80,13 @@ function assertActionAllowed(el, action, args) {
         throw new Error(`potentially destructive action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
     }
 }
-import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, mouseEventFor, } from './actions-dom.js';
+function optionValueFor(options, named) {
+    if (options.some((option) => option.value === named))
+        return named;
+    const byLabel = options.filter((option) => option.label.trim() === named.trim());
+    return 1 === byLabel.length ? (byLabel[0]?.value ?? named) : named;
+}
+import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, mouseEventFor, assertNotLeaving, } from './actions-dom.js';
 import { scrollFrom } from './scroll.js';
 function enabledOf(el) {
     return !getStates(el).includes(ElementState.DISABLED);
@@ -209,7 +161,8 @@ async function dispatchOther(el, action, args) {
                         'To empty a field on purpose use the `clear` action, or fill with an explicit "".');
                 }
                 assertEditable(el, 'fill');
-                el.focus();
+                if (!isAutofillSafeTarget(el))
+                    el.focus();
                 return setNativeValue(el, args['value']);
             }
             assertNotRichText(el, 'fill');
@@ -235,8 +188,8 @@ async function dispatchOther(el, action, args) {
                 if (typeof args['value'] !== 'string') {
                     throw new Error("select requires a string `value` — pass it nested, as args: { value: '…' }.");
                 }
-                const wanted = args['value'];
                 const options = Array.from(el.options);
+                const wanted = optionValueFor(options, args['value']);
                 if (!options.some((option) => option.value === wanted)) {
                     const available = options.map((option) => `${option.value} (${option.label})`).join(', ');
                     throw new Error(`no <option> with value '${echoRef(wanted)}' — available: ${0 === options.length ? '(none)' : available}`);
@@ -287,6 +240,8 @@ async function dispatchOther(el, action, args) {
             const code = pressCode(args, key);
             const down = asSyntheticInput(() => el.dispatchEvent(keyboardEvent('keydown', { key, code, bubbles: true, cancelable: true, ...mods })));
             closeModalOnEscape(el, key, down);
+            if (down)
+                dispatchKeypress(el, key, code, mods);
             const hold = clampHoldMs(args['holdMs']);
             if (hold > 0)
                 await holdKey(el, key, code, mods, hold);
@@ -355,6 +310,8 @@ export async function executeAction(ref, action, args = {}) {
     const el = isReflessDocumentPress(ref, action, args) ? focusedOrDocument() : requireElement(ref);
     if (named)
         assertActionAllowed(el, action, args);
+    if (named)
+        assertNotLeaving(el);
     const anchor = named ? anchorOf(el) : {};
     const visible = isVisible(el);
     const enabled = enabledOf(el);
@@ -401,6 +358,7 @@ export async function executeAction(ref, action, args = {}) {
         defaultPrevented,
         focusMoved: prevFocus !== nextFocus ? `${prevFocus ?? 'null'}->${nextFocus ?? 'null'}` : null,
         valueChanged: isFillLike(action) ? valueBefore !== valueAfter : false,
+        ...(ActionType.FILL === action && isAutofillSafeTarget(el) ? { autofillSafe: true } : {}),
         domMutatedWithin: mutated,
         ...said.effect(valueAfter),
         occluded: geometry.occluded,

package/dist/actions/appeared-text.js

@@ -1,4 +1,5 @@
 import { isIgnored } from '../dom/dom-ignore.js';
+import { isSensitiveField } from '../dom/a11y.js';
 const APPEARED_MAX = 200;
 const JOIN = ' | ';
 const TEXT_NODE = 3;
@@ -46,6 +47,8 @@ export class AppearedText {
     #add(raw, owner) {
         if (null !== owner && isIgnored(owner))
             return;
+        if (null !== owner && isSensitiveField(owner))
+            return;
         const text = (raw ?? '').replace(/\s+/g, ' ').trim();
         if (0 === text.length)
             return;

package/dist/actions/danger-context.d.ts

@@ -2,3 +2,5 @@ import { type ActionTarget } from '../dom/realm.js';
 export declare function dangerousActionContext(el: ActionTarget): string;
 export declare function submitControlFor(el: ActionTarget): HTMLElement | null;
 export declare function requiresDangerousConfirmation(text: string, role?: string): boolean;
+export declare function setOutwardPolicy(allowed: readonly string[] | undefined): void;
+export declare function assertOutwardAllowed(targets: readonly (ActionTarget | null)[]): void;

package/dist/actions/danger-context.js

@@ -1,5 +1,5 @@
-import { isDangerousActionText } from '@reticlehq/core';
-import { getAccessibleName } from '../dom/a11y.js';
+import { isDangerousActionText, 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,18 @@ function holdsUserText(el) {
         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)
+        return undefined;
+    const href = el.getAttribute('href');
+    return null === href || INERT_HREF.test(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)
         ? ['', '']
@@ -38,3 +49,18 @@ export function submitControlFor(el) {
 export function requiresDangerousConfirmation(text, role) {
     return isDangerousActionText(text, role);
 }
+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));
+    }
+}

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/commands/commands.js

@@ -122,6 +122,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;
@@ -220,6 +223,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'];