@reticlehq/browser 3.9.0 → 3.10.1

package/dist/actions/actions.js

@@ -1,10 +1,10 @@
-import { ActionType, ActionWarning, clampHoldMs, clickInputProblem, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
+import { ACT_POINT_ARG, ActionType, ActionWarning, actPointProblem, boxFractionFromArgs, clampHoldMs, clickInputProblem, DRAG_TO_POINT_ARG, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
 import { isHiddenNativeOption } from '../dom/query-finders.js';
-import { isReticleUi } from '../dom/dom-ignore.js';
+import { isReticleUi, isUnobserved } from '../dom/dom-ignore.js';
 import { asSyntheticInput } from './synthetic/synthetic-input.js';
 import { echoRef, refs } from '../dom/addressing/refs.js';
 import { requiresDangerousConfirmation, assertOutwardAllowed, assertPaymentEntryAllowed, submitControlFor, } from './danger-context.js';
-import { assertEditable, assertNotRichText, isAutofillSafeTarget, setNativeValue, } from './value-input.js';
+import { assertEditable, assertNotEditorTextArea, assertNotRichText, isAutofillSafeTarget, isRichText, setNativeValue, } from './value-input.js';
 import { getRole, getStates } from '../dom/a11y.js';
 import { isVisible } from '../dom/visibility.js';
 import { selectInCombobox } from './select-combobox.js';
@@ -14,7 +14,7 @@ import { asSettleBudget, nativeSetTimeout, settle } from '../timers/native/nativ
 import { publishSettledField, watchActedField } from '../observers/field.js';
 import { AppearedText } from './appeared-text.js';
 import { alreadyAtCheckedState, assertAriaToggleLanded, isAriaToggle } from './check-state.js';
-import { focusedOrDocument, isReflessDocumentPress, pressCode, pressKey, pressModifiers, pressKeys, holdKey, pressCombo, dispatchKeypress, closeModalOnEscape, keyboardEvent, } from './actions-press.js';
+import { focusedOrDocument, isReflessDocumentPress, pressCode, pressKey, pressModifiers, pressKeys, holdKey, pressCombo, dispatchKeypress, closeModalOnEscape, keyboardEvent, runKeydownDefault, runKeyupDefault, SPACE_KEY, } from './actions-press.js';
 import { anchorOf, result, visibleCanvases, } from './action-report.js';
 function asString(value, fallback = '') {
     return 'string' === typeof value ? value : fallback;
@@ -34,6 +34,7 @@ const FILL_LIKE = new Set([
     ActionType.TYPE,
     ActionType.CLEAR,
     ActionType.SELECT,
+    ActionType.INSERT_TEXT,
 ]);
 const isFillLike = (action) => FILL_LIKE.has(action);
 const CLICK_LIKE = new Set([
@@ -72,7 +73,7 @@ function assertActionAllowed(el, action, args) {
         action === ActionType.UNCHECK ||
         action === ActionType.DRAG ||
         action === ActionType.SUBMIT ||
-        (action === ActionType.PRESS && 'Enter' === pressKey(args));
+        (action === ActionType.PRESS && ('Enter' === pressKey(args) || SPACE_KEY === 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) {
@@ -100,7 +101,7 @@ function optionValueFor(options, 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, scrollIntoViewNow, clickInputOf, } from './actions-dom.js';
+import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, leavePreviousHover, dragElement, mouseEventFor, assertNotLeaving, scrollIntoViewNow, clickInputOf, coordsIn, } from './actions-dom.js';
 import { scrollFrom } from './scroll.js';
 import { clickHitsNoControl } from './click-target.js';
 function enabledOf(el) {
@@ -110,6 +111,9 @@ function valueOf(el) {
     if (isInput(el) || isTextArea(el) || isSelect(el)) {
         return el.value;
     }
+    if (isRichText(el)) {
+        return el.textContent ?? '';
+    }
     return undefined;
 }
 function activeRef(el) {
@@ -122,11 +126,11 @@ function activeRef(el) {
 async function dispatchFor(el, action, args) {
     if (ActionType.CLICK === action) {
         const hold = clampHoldMs(args['holdMs']);
-        return await fireClickSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() }, undefined, clickInputOf(args));
+        return await fireClickSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() }, undefined, clickInputOf(args), boxFractionFromArgs(args, ACT_POINT_ARG));
     }
     if (ActionType.TAP === action) {
         const hold = clampHoldMs(args['holdMs']);
-        return await fireTapSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() });
+        return await fireTapSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() }, boxFractionFromArgs(args, ACT_POINT_ARG));
     }
     return { prevented: await dispatchOther(el, action, args), heldMs: 0 };
 }
@@ -145,24 +149,26 @@ async function dispatchOther(el, action, args) {
     switch (action) {
         case ActionType.DBLCLICK: {
             const input = clickInputOf(args);
-            await fireClickSequence(el, undefined, 1, input);
-            await fireClickSequence(el, undefined, 2, input);
+            const point = boxFractionFromArgs(args, ACT_POINT_ARG);
+            await fireClickSequence(el, undefined, 1, input, point);
+            await fireClickSequence(el, undefined, 2, input, point);
             return !asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'dblclick', {
                 bubbles: true,
                 cancelable: true,
                 detail: 2,
                 ...input.modifiers,
+                ...coordsIn(el, point),
             })));
         }
         case ActionType.HOVER: {
-            const doc = el.ownerDocument;
-            const from = doc.activeElement ?? doc.body;
-            firePointer(el, 'pointerover', from);
-            el.dispatchEvent(mouseEventFor(el, 'mouseover', { bubbles: true, relatedTarget: from }));
-            firePointerNonBubbling(el, 'pointerenter', from);
-            el.dispatchEvent(mouseEventFor(el, 'mouseenter', { relatedTarget: from }));
-            firePointer(el, 'pointermove', from);
-            const moved = el.dispatchEvent(mouseEventFor(el, 'mousemove', { bubbles: true, cancelable: true }));
+            const coords = coordsIn(el, boxFractionFromArgs(args, ACT_POINT_ARG));
+            const from = leavePreviousHover(el);
+            firePointer(el, 'pointerover', from, coords);
+            el.dispatchEvent(mouseEventFor(el, 'mouseover', { bubbles: true, relatedTarget: from, ...coords }));
+            firePointerNonBubbling(el, 'pointerenter', from, coords);
+            el.dispatchEvent(mouseEventFor(el, 'mouseenter', { relatedTarget: from, ...coords }));
+            firePointer(el, 'pointermove', from, coords);
+            const moved = el.dispatchEvent(mouseEventFor(el, 'mousemove', { bubbles: true, cancelable: true, ...coords }));
             const holdMs = clampHoldMs(args['holdMs']);
             if (holdMs > 0) {
                 await sleep(holdMs);
@@ -184,6 +190,7 @@ async function dispatchOther(el, action, args) {
             return false;
         }
         case ActionType.FILL:
+            assertNotEditorTextArea(el, 'fill');
             if (isInput(el) || isTextArea(el)) {
                 if (typeof args['value'] !== 'string') {
                     throw new Error("fill requires a string `value` — pass it nested, as args: { value: '…' }. " +
@@ -198,6 +205,7 @@ async function dispatchOther(el, action, args) {
             assertNotRichText(el, 'fill');
             throw new Error(`cannot fill a <${el.tagName.toLowerCase()}>`);
         case ActionType.TYPE:
+            assertNotEditorTextArea(el, 'type into');
             if (isInput(el) || isTextArea(el)) {
                 if (typeof args['text'] !== 'string') {
                     throw new Error("type requires a string `text` — pass it nested, as args: { text: '…' }.");
@@ -209,10 +217,15 @@ async function dispatchOther(el, action, args) {
             assertNotRichText(el, 'type into');
             throw new Error(`cannot type into a <${el.tagName.toLowerCase()}>`);
         case ActionType.CLEAR:
+            assertNotEditorTextArea(el, 'clear');
             if (isInput(el) || isTextArea(el)) {
                 return setNativeValue(el, '');
             }
             throw new Error(`cannot clear a <${el.tagName.toLowerCase()}>`);
+        case ActionType.INSERT_TEXT: {
+            const { insertText } = await import('./insert-text.js');
+            return insertText(el, args['text']);
+        }
         case ActionType.SELECT:
             if (isSelect(el)) {
                 if (typeof args['value'] !== 'string') {
@@ -281,12 +294,16 @@ async function dispatchOther(el, action, args) {
             closeModalOnEscape(el, key, down);
             if (down) {
                 dispatchKeypress(el, key, code, mods);
+                runKeydownDefault(el, key, mods);
             }
             const hold = clampHoldMs(args['holdMs']);
             if (hold > 0) {
                 await holdKey(el, key, code, mods, hold);
             }
             asSyntheticInput(() => el.dispatchEvent(keyboardEvent('keyup', { key, code, bubbles: true, ...mods })));
+            if (down) {
+                runKeyupDefault(el, key, mods);
+            }
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
@@ -298,7 +315,7 @@ async function dispatchOther(el, action, args) {
             const dy = asFiniteNumber(args['dy']);
             const dx = asFiniteNumber(args['dx']);
             const fraction = asFiniteNumber(args['fraction']);
-            scrollFrom(el, dy, fraction, dx);
+            scrollFrom(el, dy, fraction, dx, true === args['wheel']);
             return false;
         }
         case ActionType.UPLOAD: {
@@ -328,22 +345,35 @@ async function dispatchOther(el, action, args) {
         }
         case ActionType.DRAG: {
             const toRef = dragTargetRef(args);
+            const points = {
+                at: boxFractionFromArgs(args, ACT_POINT_ARG),
+                to: boxFractionFromArgs(args, DRAG_TO_POINT_ARG),
+            };
             if ('' === toRef) {
-                return await dragElement(el, null, args['data']);
+                return await dragElement(el, null, args['data'], points, clickInputOf(args));
             }
             const resolved = refs.resolve(toRef);
             if (!isActionTarget(resolved)) {
                 throw new Error(`drag target '${echoRef(toRef)}' did not resolve to an element — pass a ref from ` +
                     'reticle_snapshot or reticle_query as args.toRef (alias: args.target)');
             }
-            return await dragElement(el, resolved, args['data']);
+            return await dragElement(el, resolved, args['data'], points, clickInputOf(args));
         }
         default:
             throw new Error(`unknown action '${action}'`);
     }
 }
+function isPageMutation(record) {
+    const target = record.target;
+    const el = target instanceof Element ? target : target.parentElement;
+    return null === el || !isUnobserved(el);
+}
 export async function executeAction(ref, action, args = {}) {
     const named = 0 < ref.length;
+    const pointProblem = actPointProblem(action, args);
+    if (pointProblem !== undefined) {
+        throw new Error(`cannot ${action}: ${pointProblem}`);
+    }
     if (ActionType.CLICK === action || ActionType.DBLCLICK === action) {
         const problem = clickInputProblem(action, args);
         if (problem !== undefined) {
@@ -379,7 +409,7 @@ export async function executeAction(ref, action, args = {}) {
     let mutated = 0;
     const said = new AppearedText();
     const obs = new MutationObserver((records) => {
-        mutated += records.length;
+        mutated += records.filter(isPageMutation).length;
         said.collect(records);
     });
     obs.observe(el.ownerDocument.documentElement, {

package/dist/actions/insert-text.d.ts

@@ -0,0 +1,3 @@
+import type { ActionTarget } from '../dom/realm.js';
+export declare function insertText(el: ActionTarget, text: unknown): boolean;
+export declare function insertTextInto(el: ActionTarget, text: string): boolean;

package/dist/actions/insert-text.js

@@ -0,0 +1,90 @@
+import { isRichText } from './value-input.js';
+export function insertText(el, text) {
+    if (typeof text !== 'string') {
+        throw new Error("insertText requires a string `text` — pass it nested, as args: { text: '…' }.");
+    }
+    if (!isRichText(el)) {
+        throw new Error(`cannot insertText into a <${el.tagName.toLowerCase()}> — insertText needs a contenteditable rich-text editor (Tiptap, ProseMirror, Quill), not this surface`);
+    }
+    if (hasEditContext(el)) {
+        throw new Error('cannot insertText into an EditContext editor (Monaco, CodeMirror 6): code that calls updateText does not fire textupdate, so the editor model would keep the old text. Use press for a key.');
+    }
+    return insertTextInto(el, text);
+}
+function hasEditContext(el) {
+    if (!('editContext' in el)) {
+        return false;
+    }
+    const surface = el;
+    return null !== surface.editContext && undefined !== surface.editContext;
+}
+export function insertTextInto(el, text) {
+    el.focus();
+    const selection = window.getSelection();
+    if (selection !== null && !selectionInside(selection, el)) {
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        range.collapse(false);
+        selection.removeAllRanges();
+        selection.addRange(range);
+    }
+    const beforeInput = new InputEvent('beforeinput', {
+        inputType: 'insertText',
+        data: text,
+        bubbles: true,
+        cancelable: true,
+    });
+    if (!el.dispatchEvent(beforeInput)) {
+        return true;
+    }
+    if ('function' !== typeof el.ownerDocument.execCommand) {
+        insertAtCaret(el, text);
+        const input = new InputEvent('input', {
+            inputType: 'insertText',
+            data: text,
+            bubbles: true,
+            cancelable: true,
+        });
+        return !el.dispatchEvent(input);
+    }
+    let sawInput = false;
+    const recordInput = (event) => {
+        if ('input' === event.type) {
+            sawInput = true;
+        }
+    };
+    window.addEventListener('input', recordInput, false);
+    try {
+        if (el.ownerDocument.execCommand('insertText', false, text)) {
+            return false;
+        }
+    }
+    catch {
+    }
+    finally {
+        window.removeEventListener('input', recordInput, false);
+    }
+    if (sawInput) {
+        return false;
+    }
+    throw new Error('the editor did not accept the text: the native insertText command failed, so the editor model is unchanged. Check that the surface is editable and focused.');
+}
+function insertAtCaret(el, text) {
+    const selection = window.getSelection();
+    const range = selection !== null && 0 < selection.rangeCount ? selection.getRangeAt(0) : null;
+    if (range !== null && el.contains(range.commonAncestorContainer)) {
+        range.deleteContents();
+        const node = el.ownerDocument.createTextNode(text);
+        range.insertNode(node);
+        range.setStartAfter(node);
+        range.collapse(true);
+        selection?.removeAllRanges();
+        selection?.addRange(range);
+        return;
+    }
+    el.appendChild(el.ownerDocument.createTextNode(text));
+}
+function selectionInside(selection, el) {
+    const anchor = selection.anchorNode;
+    return anchor !== null && el.contains(anchor);
+}

package/dist/actions/scroll.d.ts

@@ -14,5 +14,5 @@ interface ScrollResult {
 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 declare function scrollFrom(base: Element | undefined, dy: number | undefined, fraction?: number, dx?: number, wheel?: boolean): ScrollResult;
 export {};

package/dist/actions/scroll.js

@@ -2,6 +2,7 @@ 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 ';
+const SCROLL_WHEEL_FRACTION_ERROR = 'scroll with wheel: true cannot use fraction; pass dy or dx';
 export function fractionOutOfRangeMessage(fraction) {
     return `${SCROLL_FRACTION_RANGE_ERROR_PREFIX}${fraction}`;
 }
@@ -21,7 +22,7 @@ export function scrollContainer(ref, dy, fraction, dx) {
     const base = ref !== undefined ? refs.resolve(ref) : null;
     return scrollFrom(base instanceof Element ? base : undefined, dy, fraction, dx);
 }
-export function scrollFrom(base, dy, fraction, dx) {
+export function scrollFrom(base, dy, fraction, dx, wheel) {
     if (fraction !== undefined && (fraction < 0 || fraction > 1 || Number.isNaN(fraction))) {
         throw new RangeError(fractionOutOfRangeMessage(fraction));
     }
@@ -31,6 +32,26 @@ export function scrollFrom(base, dy, fraction, dx) {
         : (document.scrollingElement ?? document.documentElement);
     const before = target.scrollTop;
     const beforeLeft = target.scrollLeft;
+    if (true === wheel) {
+        if (fraction !== undefined) {
+            throw new RangeError(SCROLL_WHEEL_FRACTION_ERROR);
+        }
+        const deltaY = dy ?? (Math.round(target.clientHeight * VIEWPORT_FRACTION) || FALLBACK_STEP_PX);
+        const deltaX = dx ?? 0;
+        const wheelTarget = base ?? target;
+        const rect = wheelTarget.getBoundingClientRect();
+        wheelTarget.dispatchEvent(new WheelEvent('wheel', {
+            deltaX,
+            deltaY,
+            deltaMode: WheelEvent.DOM_DELTA_PIXEL,
+            clientX: rect.width > 0 ? rect.left + rect.width / 2 : 0,
+            clientY: rect.height > 0 ? rect.top + rect.height / 2 : 0,
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        }));
+        return scrollResult(target, before, beforeLeft);
+    }
     if (fraction !== undefined) {
         target.scrollTop = Math.round(target.scrollHeight * fraction);
     }
@@ -44,6 +65,9 @@ export function scrollFrom(base, dy, fraction, dx) {
         }
     }
     target.dispatchEvent(new Event('scroll', { bubbles: false }));
+    return scrollResult(target, before, beforeLeft);
+}
+function scrollResult(target, before, beforeLeft) {
     const after = target.scrollTop;
     const afterLeft = target.scrollLeft;
     return {

package/dist/actions/value-input.d.ts

@@ -1,5 +1,7 @@
 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 isRichText(el: Element): boolean;
 export declare function assertNotRichText(el: ActionTarget, action: string): void;
+export declare function assertNotEditorTextArea(el: ActionTarget, action: string): void;
 export declare function assertEditable(el: HTMLInputElement | HTMLTextAreaElement, action: string): void;

package/dist/actions/value-input.js

@@ -1,14 +1,16 @@
 import { captureValueSetter } from '../patching/capture-method.js';
-import { isHtmlElement, valuePrototypeOf } from '../dom/realm.js';
+import { isHtmlElement, isTextArea, 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))
+    if (!(el instanceof HTMLInputElement)) {
         return false;
+    }
     const password = 'password' === el.type.toLowerCase() ||
         PASSWORD_AUTOCOMPLETE.test(el.getAttribute('autocomplete') ?? '');
-    if (!password || NOT_WEBKIT.test(ua))
+    if (!password || NOT_WEBKIT.test(ua)) {
         return false;
+    }
     return 600 <= Number(/AppleWebKit\/(\d+)/.exec(ua)?.[1] ?? 0);
 }
 export function setNativeValue(el, value) {
@@ -24,21 +26,40 @@ export function setNativeValue(el, value) {
     el.dispatchEvent(new Event('change', { bubbles: true }));
     return !notPrevented;
 }
-function isRichText(el) {
+export function isRichText(el) {
     const flag = el.getAttribute('contenteditable');
-    if ((isHtmlElement(el) && el.isContentEditable) || (null !== flag && 'false' !== flag))
+    if ((isHtmlElement(el) && el.isContentEditable) || (null !== flag && 'false' !== flag)) {
         return true;
-    if ('textbox' === el.getAttribute('role'))
+    }
+    if ('textbox' === el.getAttribute('role')) {
         return true;
-    if (!('editContext' in el))
+    }
+    if (!('editContext' in el)) {
         return false;
+    }
     const surface = el;
     return null !== surface.editContext && undefined !== surface.editContext;
 }
+const EDITOR_ROOT = '.monaco-editor, .CodeMirror, .cm-editor';
+function isEditorTextArea(el) {
+    if (!isTextArea(el)) {
+        return false;
+    }
+    return 'textbox' === el.getAttribute('role') || null !== el.closest(EDITOR_ROOT);
+}
+function refuseEditor(action) {
+    throw new Error(`cannot ${action} a contenteditable or EditContext editor; use insertText, or press for a key`);
+}
 export function assertNotRichText(el, action) {
-    if (!isRichText(el))
+    if (!isRichText(el)) {
         return;
-    throw new Error(`cannot ${action} a contenteditable or EditContext editor; use press or an input`);
+    }
+    refuseEditor(action);
+}
+export function assertNotEditorTextArea(el, action) {
+    if (isEditorTextArea(el)) {
+        refuseEditor(action);
+    }
 }
 export function assertEditable(el, action) {
     if (el.disabled) {

package/dist/commands/commands.js

@@ -1,7 +1,7 @@
-import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, MatchArg, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
+import { ANIMATION_TARGET_ARG, ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, MatchArg, ReticleCommand, SnapshotMode, SESSION_REF, 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';
+import { embeddedRootsUnder, matchQuery, runQuery } from '../dom/query.js';
 import { executeAction, executeSequence } from '../actions/actions.js';
 import { describe } from '../dom/a11y.js';
 import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/addressing/source.js';
@@ -173,23 +173,98 @@ function readState(ref, store, path, depth) {
     }
     return result;
 }
-function listAnimations() {
+function animationName(animation) {
+    const fields = animation;
+    const name = str(fields.animationName);
+    if (name !== undefined && name.length > 0) {
+        return name;
+    }
+    const transition = str(fields.transitionProperty);
+    return transition !== undefined && transition.length > 0 ? transition : undefined;
+}
+function resolveAnimationTarget(target) {
+    if (target === undefined) {
+        return undefined;
+    }
+    const byRef = refs.resolve(target);
+    if (byRef !== null) {
+        const ref = refs.refFor(byRef);
+        return {
+            report: { target, matched: true, refs: [ref], count: 1 },
+            matches: (animationTarget) => animationTarget !== null && refs.refFor(animationTarget) === ref,
+        };
+    }
+    if (SESSION_REF.test(target)) {
+        return {
+            report: { target, matched: false, refs: [], count: 0 },
+            matches: () => false,
+        };
+    }
+    let elements;
+    try {
+        const roots = [document];
+        const container = document.body ?? document.documentElement;
+        if (container !== null) {
+            roots.push(...embeddedRootsUnder(container));
+        }
+        const seen = new Set();
+        elements = [];
+        for (const root of roots) {
+            for (const el of root.querySelectorAll(target)) {
+                if (seen.has(el)) {
+                    continue;
+                }
+                seen.add(el);
+                elements.push(el);
+            }
+        }
+    }
+    catch {
+        return {
+            report: { target, matched: false, refs: [], count: 0, invalid: true },
+            matches: () => false,
+        };
+    }
+    const allRefs = new Set(elements.map((el) => refs.refFor(el)));
+    const refsInReport = Array.from(allRefs).slice(0, TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS);
+    return {
+        report: {
+            target,
+            matched: elements.length > 0,
+            refs: refsInReport,
+            count: elements.length,
+            ...(allRefs.size > refsInReport.length ? { truncated: true } : {}),
+        },
+        matches: (animationTarget) => animationTarget !== null && allRefs.has(refs.refFor(animationTarget)),
+    };
+}
+function listAnimations(args = {}) {
     const doc = document;
+    const targetFilter = resolveAnimationTarget(str(args[ANIMATION_TARGET_ARG]));
     if (typeof doc.getAnimations !== 'function') {
-        return { animations: [] };
+        return {
+            animations: [],
+            ...(targetFilter === undefined ? {} : { target: targetFilter.report }),
+        };
     }
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
         const target = effect?.target ?? null;
+        const name = animationName(a);
         return {
+            ...(name === undefined ? {} : { name }),
             playState: a.playState,
             currentTime: a.currentTime,
             duration: timing?.duration,
             target: null === target ? null : describe(target),
+            ...(targetFilter === undefined ? {} : { targetMatches: targetFilter.matches(target) }),
         };
     });
-    return { animations };
+    return {
+        animations,
+        ...(targetFilter === undefined ? {} : { target: targetFilter.report }),
+    };
 }
 export function resolveNavigationUrl(rawUrl, baseUrl) {
     if (0 === rawUrl.length || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH) {
@@ -211,6 +286,7 @@ export function createCommandRegistry() {
         includeRoot: true === args['includeRoot'],
         ids: true === args['ids'],
         audit: true === args['audit'],
+        charts: true === args['charts'],
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
         const limit = args['limit'];
@@ -229,7 +305,7 @@ export function createCommandRegistry() {
         return result;
     });
     reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? '', true === args[INSPECT_REVEAL_ARG]));
-    reg.set(ReticleCommand.ANIMATIONS, () => listAnimations());
+    reg.set(ReticleCommand.ANIMATIONS, (args) => listAnimations(args));
     reg.set(ReticleCommand.CLOCK, (args) => {
         if (true === args['reset']) {
             resetClock();

package/dist/connect-options.d.ts

@@ -1,4 +1,4 @@
-import { HelloInstrumentation, type HelloEnv, type HelloScope, type RedactionConfig } from '@reticlehq/core';
+import { HelloInstrumentation, HudVisibility, type HelloEnv, type HelloScope, type RedactionConfig } from '@reticlehq/core';
 export interface ReticleConnectOptions {
     url?: string;
     session?: string;
@@ -37,3 +37,13 @@ export declare function helloMode(options: Pick<ReticleConnectOptions, 'env' | '
 };
 export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
 export declare function leaseToken(options: ReticleConnectOptions, current: string | undefined): string | undefined;
+export declare function oneOf<T extends Record<string, string>>(values: T, raw: unknown): T[keyof T] | undefined;
+export declare function reticleParamsFromSearch(search: string): {
+    session?: string;
+    projectId?: string;
+    hud?: HudVisibility;
+};
+export declare function hudWithoutPanel(hud: HudVisibility | undefined): {
+    remember?: HudVisibility;
+    placed: HudVisibility[];
+};

package/dist/connect-options.js

@@ -1,4 +1,4 @@
-import { HelloInstrumentation, } from '@reticlehq/core';
+import { HelloInstrumentation, HudVisibility, RETICLE_URL_PARAM, } from '@reticlehq/core';
 export function helloMode(options) {
     return {
         ...(options.env === undefined ? {} : { env: options.env }),
@@ -16,3 +16,29 @@ export function leaseToken(options, current) {
     }
     return token;
 }
+export function oneOf(values, raw) {
+    return Object.values(values).includes(raw) ? raw : undefined;
+}
+export function reticleParamsFromSearch(search) {
+    const params = new URLSearchParams(search);
+    const out = {};
+    const session = params.get(RETICLE_URL_PARAM.SESSION);
+    const projectId = params.get(RETICLE_URL_PARAM.PROJECT);
+    const hud = oneOf(HudVisibility, params.get(RETICLE_URL_PARAM.HUD));
+    if (session !== null && session.length > 0) {
+        out.session = session;
+    }
+    if (projectId !== null && projectId.length > 0) {
+        out.projectId = projectId;
+    }
+    if (hud !== undefined) {
+        out.hud = hud;
+    }
+    return out;
+}
+export function hudWithoutPanel(hud) {
+    if (hud === undefined) {
+        return { placed: [] };
+    }
+    return { remember: hud, placed: HudVisibility.SHOWN === hud ? [] : [hud] };
+}

package/dist/dom/a11y.js

@@ -5,7 +5,7 @@ import { refs } from './addressing/refs.js';
 import { inspectChart } from './chart.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { formatSource, sourceFromDom } from './addressing/source.js';
-import { HTML_DETAILS_OPEN_ATTRIBUTE, HTML_DETAILS_TAG, HTML_SUMMARY_TAG, isVisible, } from './visibility.js';
+import { HTML_DETAILS_OPEN_ATTRIBUTE, HTML_DETAILS_TAG, HTML_SUMMARY_TAG, isNonRendered, isVisible, } from './visibility.js';
 const NAME_FROM_CONTENT = new Set([
     'button',
     'link',
@@ -30,6 +30,7 @@ const NAME_FROM_CONTENT = new Set([
     'alert',
 ]);
 const INPUT_TEXT_TYPES = new Set(['text', 'email', 'tel', 'url', 'password', '']);
+const INPUT_BUTTON_TYPES = new Set(['submit', 'button', 'reset', 'file', 'image']);
 function inputRole(input) {
     const type = input.type.toLowerCase();
     if ('search' === type) {
@@ -50,7 +51,7 @@ function inputRole(input) {
     if ('number' === type) {
         return 'spinbutton';
     }
-    if ('submit' === type || 'button' === type || 'reset' === type) {
+    if (INPUT_BUTTON_TYPES.has(type)) {
         return 'button';
     }
     return 'textbox';
@@ -182,7 +183,7 @@ function textWithoutHidden(node) {
         return '';
     }
     const el = node;
-    if ('true' === el.getAttribute('aria-hidden')) {
+    if ('true' === el.getAttribute('aria-hidden') || isNonRendered(el)) {
         return '';
     }
     if (isImage(el)) {