@teaflask/assistant 0.7.0 → 0.7.1

package/dist/affordances/aria-dropdowns.js

@@ -0,0 +1,315 @@
+import { CLOSE_SETTLE_MS, clicked, OPEN_SETTLE_MS, PICK_SETTLE_MS, pressKey, pressLikeAPointer, settledReading, theClickWouldSubmitOrLeaveThePage, theControlIsInert, } from "./page-gestures.js";
+import { CONTROL_REDRAWN_REASON, CURATED_OPTIONS_REASON, DROPDOWN_NEVER_OPENED_REASON, DROPDOWN_PICK_DID_NOT_LAND_REASON, INERT_FIELD_REASON, MULTI_CHOICE_REASON, NO_OPTIONS_SHOWN_REASON, noMatchingOptionReasonListing, SUBMITTING_CONTROL_REASON, unavailableOptionReason, } from "./prefill-reasons.js";
+import { accessibleNameOf, } from "../reader/accessible-name.js";
+import { ariaBooleanOf, roleOf, theControlIsDisabled, } from "../reader/roles.js";
+import { alreadyShowsTheValue, comboboxOwnerOf, confirmsLabel, displayNamesTheMatch, ownDisplayIsReliable, ownerShowsThePick, shownTextOf, } from "./dropdown-display.js";
+import { _normalizedNodeName } from "../reader/snapshot-node.js";
+import { lastReadIgnoreSelectors } from "../reader/snapshot.js";
+import { theElementSitsInACuratedSubtree } from "../reader/snapshot-root.js";
+import { visibilityOracleOf } from "../reader/visibility.js";
+export async function customDropdownRefusalOf(element, value, probe, listingBudget, whenNoListOpens) {
+    const entryRefusal = _dropdownEntryRefusalOf(element);
+    if (entryRefusal !== null) {
+        return entryRefusal;
+    }
+    const want = value.trim();
+    if (ownDisplayIsReliable(element) &&
+        alreadyShowsTheValue(element, want, probe, null)) {
+        return null;
+    }
+    if (!(element instanceof HTMLInputElement) &&
+        theClickWouldSubmitOrLeaveThePage(element)) {
+        return SUBMITTING_CONTROL_REASON;
+    }
+    const found = await _openedListboxFor(element, probe);
+    const listbox = found.listbox;
+    const closedIfOurs = async () => {
+        if (found.provenance === "ours") {
+            await _closedPopup(element, listbox, probe);
+        }
+    };
+    if (listbox === null) {
+        if (!element.isConnected) {
+            return CONTROL_REDRAWN_REASON;
+        }
+        if (found.gesturesWereDispatched) {
+            await _closedPopup(element, listbox, probe);
+        }
+        return whenNoListOpens !== undefined
+            ? whenNoListOpens(DROPDOWN_NEVER_OPENED_REASON)
+            : DROPDOWN_NEVER_OPENED_REASON;
+    }
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    if (!ownDisplayIsReliable(element) &&
+        alreadyShowsTheValue(element, want, probe, listbox)) {
+        await closedIfOurs();
+        return null;
+    }
+    if (theElementSitsInACuratedSubtree(listbox, lastReadIgnoreSelectors())) {
+        await closedIfOurs();
+        return CURATED_OPTIONS_REASON;
+    }
+    if (ariaBooleanOf(listbox.getAttribute("aria-multiselectable")) === true) {
+        await closedIfOurs();
+        return MULTI_CHOICE_REASON;
+    }
+    const options = _visibleOptionsOf(listbox, probe);
+    if (options.length === 0) {
+        await closedIfOurs();
+        return whenNoListOpens !== undefined
+            ? whenNoListOpens(NO_OPTIONS_SHOWN_REASON)
+            : NO_OPTIONS_SHOWN_REASON;
+    }
+    const cache = new Map();
+    const nameOf = (option) => accessibleNameOf(option, probe, cache).trim();
+    const match = _optionMatching(options, want, value, nameOf);
+    if (match === null) {
+        await closedIfOurs();
+        return _noMatchRefusalOf(element, options, nameOf, listingBudget);
+    }
+    const label = nameOf(match) !== "" ? nameOf(match) : want;
+    if (match.getAttribute("aria-selected") === "true" &&
+        displayNamesTheMatch(shownTextOf(element, probe, listbox), label, options, nameOf)) {
+        await closedIfOurs();
+        return null;
+    }
+    if (theControlIsDisabled(match, "option")) {
+        await closedIfOurs();
+        return unavailableOptionReason(label);
+    }
+    if (theClickWouldSubmitOrLeaveThePage(match)) {
+        await closedIfOurs();
+        return SUBMITTING_CONTROL_REASON;
+    }
+    return _confirmedPickRefusalOf(element, listbox, match, label, probe);
+}
+async function _confirmedPickRefusalOf(element, listbox, match, label, probe) {
+    const beforeText = shownTextOf(element, probe, listbox);
+    clicked(match);
+    const after = await settledReading(() => shownTextOf(element, probe, listbox), (text) => !element.isConnected ||
+        (text !== beforeText && confirmsLabel(text, label)), PICK_SETTLE_MS);
+    await _closedPopup(element, listbox, probe);
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    const landed = after !== beforeText && confirmsLabel(after, label);
+    return landed ? null : DROPDOWN_PICK_DID_NOT_LAND_REASON;
+}
+export async function listboxPickRefusalOf(element, value, probe, listingBudget) {
+    if (theControlIsInert(element)) {
+        return INERT_FIELD_REASON;
+    }
+    if (ariaBooleanOf(element.getAttribute("aria-multiselectable")) === true) {
+        return MULTI_CHOICE_REASON;
+    }
+    const options = _visibleOptionsOf(element, probe);
+    if (options.length === 0) {
+        return NO_OPTIONS_SHOWN_REASON;
+    }
+    const cache = new Map();
+    const nameOf = (option) => accessibleNameOf(option, probe, cache).trim();
+    const want = value.trim();
+    const match = _optionMatching(options, want, value, nameOf);
+    if (match === null) {
+        return _noMatchRefusalOf(element, options, nameOf, listingBudget);
+    }
+    if (match.getAttribute("aria-selected") === "true") {
+        return null;
+    }
+    const label = nameOf(match) !== "" ? nameOf(match) : want;
+    if (theControlIsDisabled(match, "option")) {
+        return unavailableOptionReason(label);
+    }
+    if (theClickWouldSubmitOrLeaveThePage(match)) {
+        return SUBMITTING_CONTROL_REASON;
+    }
+    const owner = comboboxOwnerOf(element);
+    const ownerBefore = owner === null ? "" : shownTextOf(owner, probe, element);
+    clicked(match);
+    const selected = await settledReading(() => match.getAttribute("aria-selected"), (state) => state === "true" || !element.isConnected || !match.isConnected, PICK_SETTLE_MS);
+    if (element.isConnected && match.isConnected) {
+        return selected === "true" ? null : DROPDOWN_PICK_DID_NOT_LAND_REASON;
+    }
+    if (owner !== null) {
+        return (await ownerShowsThePick(owner, ownerBefore, label, probe))
+            ? null
+            : DROPDOWN_PICK_DID_NOT_LAND_REASON;
+    }
+    return CONTROL_REDRAWN_REASON;
+}
+async function _openedListboxFor(element, probe) {
+    if (element.getAttribute("aria-expanded") === "true") {
+        const alreadyOpen = _openedListboxOf(element, probe, new Set(), (candidate) => _popupBelongsToTrigger(candidate, element, probe));
+        return {
+            listbox: alreadyOpen,
+            provenance: alreadyOpen !== null ? "users" : "unattributed",
+            gesturesWereDispatched: false,
+        };
+    }
+    const alreadyShowing = visibilityOracleOf(probe);
+    const before = new Set(Array.from(document.querySelectorAll('[role="listbox"]')).filter((candidate) => alreadyShowing.isVisible(candidate)));
+    if (element instanceof HTMLElement) {
+        element.focus();
+    }
+    pressKey(element, "ArrowDown");
+    const viaKeyboard = await settledReading(() => _openedListboxOf(element, probe, before, () => true), (listbox) => listbox !== null || !element.isConnected, OPEN_SETTLE_MS);
+    if (viaKeyboard !== null) {
+        return {
+            listbox: viaKeyboard,
+            provenance: "ours",
+            gesturesWereDispatched: true,
+        };
+    }
+    if (!element.isConnected ||
+        theClickWouldSubmitOrLeaveThePage(element) ||
+        element.getAttribute("aria-expanded") === "true") {
+        return {
+            listbox: null,
+            provenance: "unattributed",
+            gesturesWereDispatched: true,
+        };
+    }
+    pressLikeAPointer(element);
+    const viaPointer = await settledReading(() => _openedListboxOf(element, probe, before, () => true), (listbox) => listbox !== null || !element.isConnected, OPEN_SETTLE_MS);
+    return {
+        listbox: viaPointer,
+        provenance: viaPointer !== null ? "ours" : "unattributed",
+        gesturesWereDispatched: true,
+    };
+}
+const KINSHIP_CLIMB_MAX = 5;
+function _popupBelongsToTrigger(candidate, trigger, probe) {
+    if (candidate.contains(trigger) || trigger.contains(candidate)) {
+        return true;
+    }
+    const oracle = visibilityOracleOf(probe);
+    const body = trigger.ownerDocument.body;
+    let current = trigger.parentElement;
+    for (let depth = 0; depth < KINSHIP_CLIMB_MAX && current !== null && current !== body; depth++) {
+        const visibleInside = Array.from(current.querySelectorAll('[role="listbox"]')).filter((listbox) => oracle.isVisible(listbox));
+        if (visibleInside.length > 0) {
+            return visibleInside.length === 1 && visibleInside[0] === candidate;
+        }
+        current = current.parentElement;
+    }
+    return false;
+}
+function _openedListboxOf(trigger, probe, before, unlinkedIsOurs) {
+    const oracle = visibilityOracleOf(probe);
+    const byId = _idReferencedListboxOf(trigger, "aria-controls") ??
+        _idReferencedListboxOf(trigger, "aria-owns");
+    if (byId !== null && oracle.isVisible(byId)) {
+        return byId;
+    }
+    const active = _resolvedIdNear(trigger, trigger.getAttribute("aria-activedescendant"));
+    const viaActive = active?.closest('[role="listbox"]') ?? null;
+    if (viaActive !== null && oracle.isVisible(viaActive)) {
+        return viaActive;
+    }
+    for (const candidate of Array.from(document.querySelectorAll('[role="listbox"]'))) {
+        if (!before.has(candidate) &&
+            oracle.isVisible(candidate) &&
+            unlinkedIsOurs(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function _idReferencedListboxOf(trigger, attribute) {
+    const ids = (trigger.getAttribute(attribute) ?? "")
+        .split(/\s+/)
+        .filter((id) => id !== "");
+    for (const id of ids) {
+        const hit = _resolvedIdNear(trigger, id);
+        if (hit === null) {
+            continue;
+        }
+        if (roleOf(hit) === "listbox") {
+            return hit;
+        }
+        const inner = hit.querySelector('[role="listbox"]');
+        if (inner !== null) {
+            return inner;
+        }
+    }
+    return null;
+}
+function _resolvedIdNear(trigger, id) {
+    if (id === null || id === "") {
+        return null;
+    }
+    const root = trigger.getRootNode();
+    if (root instanceof Document || root instanceof ShadowRoot) {
+        return root.getElementById(id);
+    }
+    return document.getElementById(id);
+}
+function _optionMatching(options, want, rawValue, nameOf) {
+    if (want === "") {
+        return null;
+    }
+    return (options.find((option) => nameOf(option) === want) ??
+        options.find((option) => nameOf(option).toLowerCase() === want.toLowerCase()) ??
+        options.find((option) => {
+            const shownToTheModel = _normalizedNodeName(nameOf(option));
+            const comparable = shownToTheModel.trimEnd();
+            return (shownToTheModel !== nameOf(option) &&
+                (comparable === want || comparable.toLowerCase() === want.toLowerCase()));
+        }) ??
+        options.find((option) => option.getAttribute("data-value") === rawValue) ??
+        null);
+}
+function _visibleOptionsOf(listbox, probe) {
+    const oracle = visibilityOracleOf(probe);
+    const ignoreSelectors = lastReadIgnoreSelectors();
+    return Array.from(listbox.querySelectorAll('[role="option"]')).filter((option) => oracle.isVisible(option) &&
+        !theElementSitsInACuratedSubtree(option, ignoreSelectors));
+}
+async function _closedPopup(control, listbox, probe) {
+    if (_popupLooksClosed(control, listbox, probe)) {
+        return;
+    }
+    const active = control.ownerDocument.activeElement;
+    const focused = active !== null &&
+        (control.contains(active) || (listbox?.contains(active) ?? false))
+        ? active
+        : null;
+    if (focused instanceof HTMLInputElement) {
+        focused.blur();
+    }
+    else if (control instanceof HTMLInputElement) {
+        control.blur();
+    }
+    else {
+        pressKey(focused ?? control, "Escape");
+    }
+    await settledReading(() => _popupLooksClosed(control, listbox, probe), (closed) => closed, CLOSE_SETTLE_MS);
+}
+function _popupLooksClosed(control, listbox, probe) {
+    if (!control.isConnected) {
+        return true;
+    }
+    if (control.hasAttribute("aria-expanded")) {
+        return control.getAttribute("aria-expanded") !== "true";
+    }
+    return !_popupShowing(listbox, probe);
+}
+function _popupShowing(listbox, probe) {
+    return (listbox !== null &&
+        listbox.isConnected &&
+        visibilityOracleOf(probe).isVisible(listbox));
+}
+function _dropdownEntryRefusalOf(element) {
+    if (theControlIsInert(element) || theControlIsDisabled(element, "combobox")) {
+        return INERT_FIELD_REASON;
+    }
+    return null;
+}
+function _noMatchRefusalOf(element, options, nameOf, listingBudget) {
+    const labels = options
+        .filter((option) => !theControlIsDisabled(option, "option"))
+        .map(nameOf);
+    return noMatchingOptionReasonListing(labels, listingBudget, element instanceof HTMLInputElement && !element.readOnly);
+}

package/dist/affordances/aria-toggles.js

@@ -0,0 +1,39 @@
+import { clicked, settledReading, theClickWouldSubmitOrLeaveThePage, theControlIsInert, TOGGLE_SETTLE_MS, } from "./page-gestures.js";
+import { CHECKBOX_VALUE_REASON, CHECKED_STATE_UNKNOWN_REASON, CONTROL_REDRAWN_REASON, INERT_FIELD_REASON, RADIO_VALUE_REASON, SUBMITTING_CONTROL_REASON, VALUE_DID_NOT_LAND_REASON, } from "./prefill-reasons.js";
+import { roleOf } from "../reader/roles.js";
+export async function ariaToggleRefusalOf(element, value) {
+    if (roleOf(element) === "radio" && value !== "true") {
+        return RADIO_VALUE_REASON;
+    }
+    if (value !== "true" && value !== "false") {
+        return CHECKBOX_VALUE_REASON;
+    }
+    if (theControlIsInert(element)) {
+        return INERT_FIELD_REASON;
+    }
+    const state = _rawCheckedOf(element);
+    if (state === null) {
+        return CHECKED_STATE_UNKNOWN_REASON;
+    }
+    if (state === value) {
+        return null;
+    }
+    if (theClickWouldSubmitOrLeaveThePage(element)) {
+        return SUBMITTING_CONTROL_REASON;
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const before = _rawCheckedOf(element);
+        clicked(element);
+        const after = await settledReading(() => _rawCheckedOf(element), (read) => read === value || !element.isConnected, TOGGLE_SETTLE_MS);
+        if (after === value || after === before) {
+            break;
+        }
+    }
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    return _rawCheckedOf(element) === value ? null : VALUE_DID_NOT_LAND_REASON;
+}
+function _rawCheckedOf(element) {
+    return element.getAttribute("aria-checked")?.toLowerCase() ?? null;
+}

package/dist/affordances/dropdown-display.js

@@ -0,0 +1,129 @@
+import { PICK_SETTLE_MS, settledReading } from "./page-gestures.js";
+import { roleOf } from "../reader/roles.js";
+import { lastReadIgnoreSelectors } from "../reader/snapshot.js";
+import { _theSubtreeIsCurated } from "../reader/snapshot-root.js";
+import { visibilityOracleOf, } from "../reader/visibility.js";
+export function shownTextOf(control, probe, excluding) {
+    if (control instanceof HTMLInputElement) {
+        const own = _normalized(control.value);
+        if (own !== "") {
+            return own;
+        }
+        return _nearestAncestorTextOf(control, probe, excluding);
+    }
+    const text = _visibleTextOf(control, probe, excluding);
+    if (text !== "") {
+        return text;
+    }
+    const inner = Array.from(control.querySelectorAll("input")).find((candidate) => !excluding?.contains(candidate));
+    return inner === undefined ? "" : _normalized(inner.value);
+}
+export function ownDisplayIsReliable(element) {
+    return element instanceof HTMLInputElement
+        ? element.value.trim() !== ""
+        : element.querySelector('[role="listbox"]') === null;
+}
+export function alreadyShowsTheValue(element, want, probe, excluding) {
+    return (want !== "" &&
+        _normalized(shownTextOf(element, probe, excluding)).toLowerCase() ===
+            _normalized(want).toLowerCase());
+}
+export function confirmsLabel(text, label) {
+    const shown = _normalized(text).toLowerCase();
+    const wanted = _normalized(label).toLowerCase();
+    if (shown === wanted) {
+        return true;
+    }
+    return _containsAsAWholeToken(shown, wanted);
+}
+export function displayNamesTheMatch(shown, matchLabel, options, nameOf) {
+    if (!confirmsLabel(shown, matchLabel)) {
+        return false;
+    }
+    return options.every((option) => {
+        const other = nameOf(option);
+        return other.length <= matchLabel.length || !confirmsLabel(shown, other);
+    });
+}
+export function comboboxOwnerOf(listbox) {
+    const id = listbox.id;
+    if (id === "") {
+        return null;
+    }
+    const root = listbox.getRootNode();
+    const scope = root instanceof Document || root instanceof ShadowRoot ? root : document;
+    for (const candidate of Array.from(scope.querySelectorAll("[aria-controls], [aria-owns]"))) {
+        const named = [
+            candidate.getAttribute("aria-controls") ?? "",
+            candidate.getAttribute("aria-owns") ?? "",
+        ]
+            .join(" ")
+            .split(/\s+/)
+            .filter((token) => token !== "");
+        if (named.includes(id) && roleOf(candidate) === "combobox") {
+            return candidate;
+        }
+    }
+    return null;
+}
+export async function ownerShowsThePick(owner, ownerBefore, label, probe) {
+    const after = await settledReading(() => shownTextOf(owner, probe, null), (text) => text !== ownerBefore && confirmsLabel(text, label), PICK_SETTLE_MS);
+    return after !== ownerBefore && confirmsLabel(after, label);
+}
+function _containsAsAWholeToken(shown, wanted) {
+    if (wanted === "") {
+        return false;
+    }
+    for (let from = 0;; from += 1) {
+        const at = shown.indexOf(wanted, from);
+        if (at === -1) {
+            return false;
+        }
+        const before = at === 0 ? "" : shown[at - 1];
+        const after = at + wanted.length >= shown.length ? "" : shown[at + wanted.length];
+        if (!_isWordCharacter(before) && !_isWordCharacter(after)) {
+            return true;
+        }
+        from = at;
+    }
+}
+function _isWordCharacter(character) {
+    return character !== "" && /[\p{L}\p{N}_]/u.test(character);
+}
+function _nearestAncestorTextOf(control, probe, excluding) {
+    const body = control.ownerDocument.body;
+    let current = control.parentElement;
+    for (let depth = 0; depth < 5 && current !== null && current !== body; depth++) {
+        const text = _visibleTextOf(current, probe, excluding);
+        if (text !== "") {
+            return text;
+        }
+        current = current.parentElement;
+    }
+    return "";
+}
+function _visibleTextOf(root, probe, excluding) {
+    return _normalized(_textWithin(root, visibilityOracleOf(probe), excluding));
+}
+function _textWithin(node, oracle, excluding) {
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? "";
+    }
+    if (!(node instanceof Element) || node === excluding) {
+        return "";
+    }
+    if (node.getAttribute("aria-hidden") === "true" || !oracle.isVisible(node)) {
+        return "";
+    }
+    if (_theSubtreeIsCurated(node, lastReadIgnoreSelectors())) {
+        return "";
+    }
+    let text = "";
+    for (const child of Array.from(node.childNodes)) {
+        text += _textWithin(child, oracle, excluding);
+    }
+    return text;
+}
+function _normalized(text) {
+    return text.replace(/\s+/g, " ").trim();
+}

package/dist/affordances/page-gestures.js

@@ -0,0 +1,91 @@
+import { ariaBooleanOf, roleOf, theControlIsDisabled, } from "../reader/roles.js";
+export const TOGGLE_SETTLE_MS = 500;
+export const OPEN_SETTLE_MS = 750;
+export const PICK_SETTLE_MS = 750;
+export const CLOSE_SETTLE_MS = 500;
+const SETTLE_POLL_MS = 25;
+export function typeLikeAUser(control, value) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(control), "value");
+    if (descriptor?.set !== undefined) {
+        descriptor.set.call(control, value);
+    }
+    else {
+        control.value = value;
+    }
+    control.dispatchEvent(new Event("input", { bubbles: true }));
+    control.dispatchEvent(new Event("change", { bubbles: true }));
+}
+export function pressKey(target, key) {
+    const init = {
+        key,
+        code: key,
+        bubbles: true,
+        cancelable: true,
+    };
+    target.dispatchEvent(new KeyboardEvent("keydown", init));
+    target.dispatchEvent(new KeyboardEvent("keyup", init));
+}
+export function pressLikeAPointer(target) {
+    const armed = target.dispatchEvent(_pointerEventOf("pointerdown"));
+    if (armed) {
+        target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true }));
+    }
+    target.dispatchEvent(_pointerEventOf("pointerup"));
+    if (armed) {
+        target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true }));
+    }
+    clicked(target);
+}
+export function clicked(target) {
+    if (target instanceof HTMLElement) {
+        target.click();
+    }
+    else {
+        target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    }
+}
+function _pointerEventOf(type) {
+    const init = { bubbles: true, cancelable: true, pointerId: 1 };
+    return typeof PointerEvent === "function"
+        ? new PointerEvent(type, init)
+        : new MouseEvent(type, init);
+}
+export async function settledReading(read, isSettled, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    await _afterMs(0);
+    let value = read();
+    while (!isSettled(value) && Date.now() < deadline) {
+        await _afterMs(SETTLE_POLL_MS);
+        value = read();
+    }
+    return value;
+}
+export function settledValueOf(read) {
+    return settledReading(read, () => true, 0);
+}
+function _afterMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function theClickWouldSubmitOrLeaveThePage(element) {
+    if (element.closest("a[href], area[href]") !== null) {
+        return true;
+    }
+    const button = element.closest("button");
+    return button !== null && button.form !== null && button.type !== "button";
+}
+export function theControlIsInert(element) {
+    if (theControlIsDisabled(element, roleOf(element))) {
+        return true;
+    }
+    if (ariaBooleanOf(element.getAttribute("aria-readonly")) === true) {
+        return true;
+    }
+    const group = element.closest('[role="radiogroup"]');
+    if (group !== null &&
+        ariaBooleanOf(group.getAttribute("aria-readonly")) === true) {
+        return true;
+    }
+    return element.closest("[inert]") !== null;
+}

package/dist/affordances/prefill-reasons.js

@@ -0,0 +1,75 @@
+export const SECRET_FIELD_REASON = "This field holds a secret (a password or payment detail) — the user " +
+    "must type it themselves.";
+export const FILE_FIELD_REASON = "File pickers cannot be filled by the assistant — the user must choose " +
+    "the file themselves.";
+export const INERT_FIELD_REASON = "This field is disabled or read-only and cannot take a value right now.";
+export const NOT_FILLABLE_REASON = "This element is not a fillable form field — take a fresh read and " +
+    "pick a textbox, dropdown, checkbox, radio button, switch, or editor ref.";
+export const CHECKBOX_VALUE_REASON = 'A checkbox or switch takes "true" or "false", nothing else — call ' +
+    "again with one of those.";
+export const RADIO_VALUE_REASON = 'A radio button can only be selected — pass "true" on the option to ' +
+    "select instead.";
+const NO_MATCHING_OPTION_REASON = "No option in this dropdown matches that value — read the page to see " +
+    "the options it offers.";
+export const VALUE_DID_NOT_LAND_REASON = "The page's own scripts rejected this value — it did not stay in the " +
+    "field.";
+export const EDITOR_UNAVAILABLE_REASON = "This editor cannot be filled on this page — tell the user what to " +
+    "type instead.";
+export const MIRROR_INPUT_REASON = "This checkbox is the page's hidden mirror of a styled control — take " +
+    "a fresh read and fill the visible checkbox or switch beside it instead.";
+export const CHECKED_STATE_UNKNOWN_REASON = "This control does not report its checked state — tell the user to " +
+    "toggle it themselves.";
+export const CONTROL_REDRAWN_REASON = "The page redrew this control while it was being set — take a fresh " +
+    "read and use the new ref.";
+export const SUBMITTING_CONTROL_REASON = "Clicking this control would submit the form or leave the page — tell " +
+    "the user to set it themselves.";
+export const DROPDOWN_NEVER_OPENED_REASON = "This dropdown would not open its options — tell the user to pick the " +
+    "option themselves.";
+export const CURATED_OPTIONS_REASON = "This dropdown's options sit in a part of the page that has opted out " +
+    "of page reads — tell the user to pick it themselves.";
+export const MULTI_CHOICE_REASON = "This control takes several choices at once, which prefill cannot set " +
+    "safely — tell the user which options to pick themselves.";
+export const NO_OPTIONS_SHOWN_REASON = "This dropdown opened with nothing to pick — tell the user to fill it " +
+    "themselves.";
+export const DROPDOWN_PICK_DID_NOT_LAND_REASON = "Picking that option did not change the dropdown's value — tell the " +
+    "user to pick it themselves.";
+const OPTION_LIST_MAX = 15;
+const OPTION_LABEL_MAX = 60;
+const LISTING_REPORT_BUDGET_CHARS = 8_000;
+export function reportListingBudget() {
+    return { remainingChars: LISTING_REPORT_BUDGET_CHARS };
+}
+export function noMatchingOptionReasonListing(labels, budget, freeTextHint = false) {
+    const named = labels.filter((label) => label !== "");
+    const shown = named.slice(0, OPTION_LIST_MAX);
+    if (shown.length === 0) {
+        return NO_MATCHING_OPTION_REASON;
+    }
+    const more = named.length - shown.length;
+    const overflow = more > 0 ? `, and ${String(more)} more` : "";
+    const next = shown.some((label) => label.length > OPTION_LABEL_MAX)
+        ? "— a label ending in … is cut short here: read the page for its " +
+            "full text, then call prefill_form again with one exactly."
+        : "— call prefill_form again with one of these exactly.";
+    const hint = freeTextHint
+        ? " If this field accepts typed text instead, tell the user the " +
+            "exact value to enter."
+        : "";
+    const listed = "No option in this dropdown matches that value. It offers: " +
+        `${shown.map(_quotedLabel).join(", ")}${overflow} ${next}${hint}`;
+    if (listed.length > budget.remainingChars) {
+        return NO_MATCHING_OPTION_REASON;
+    }
+    budget.remainingChars -= listed.length;
+    return listed;
+}
+export function unavailableOptionReason(label) {
+    return (`The option ${_quotedLabel(label)} is disabled right now — call ` +
+        "again with a different option or tell the user to pick it themselves.");
+}
+function _quotedLabel(label) {
+    const cut = label.length > OPTION_LABEL_MAX
+        ? `${label.slice(0, OPTION_LABEL_MAX)}…`
+        : label;
+    return `"${cut}"`;
+}

package/dist/affordances/prefill.js

@@ -1,26 +1,15 @@
+import { settledValueOf, theClickWouldSubmitOrLeaveThePage, theControlIsInert, typeLikeAUser, } from "./page-gestures.js";
+import { CHECKBOX_VALUE_REASON, CONTROL_REDRAWN_REASON, EDITOR_UNAVAILABLE_REASON, FILE_FIELD_REASON, INERT_FIELD_REASON, MIRROR_INPUT_REASON, MULTI_CHOICE_REASON, noMatchingOptionReasonListing, NOT_FILLABLE_REASON, RADIO_VALUE_REASON, reportListingBudget, SECRET_FIELD_REASON, SUBMITTING_CONTROL_REASON, unavailableOptionReason, VALUE_DID_NOT_LAND_REASON, } from "./prefill-reasons.js";
 import { theFieldHoldsASecret } from "../reader/redaction.js";
-import { resolvedElementOfRef } from "../reader/snapshot.js";
-import { isContentEditableElement } from "../reader/roles.js";
-const SECRET_FIELD_REASON = "This field holds a secret (a password or payment detail) — the user " +
-    "must type it themselves.";
-const FILE_FIELD_REASON = "File pickers cannot be filled by the assistant — the user must choose " +
-    "the file themselves.";
-const INERT_FIELD_REASON = "This field is disabled or read-only and cannot take a value right now.";
-const NOT_FILLABLE_REASON = "This element is not a fillable form field — take a fresh read and " +
-    "pick a textbox, dropdown, checkbox, or editor ref.";
-const CHECKBOX_VALUE_REASON = 'A checkbox takes "true" or "false", nothing else.';
-const RADIO_VALUE_REASON = 'A radio button can only be selected — pass "true" on the option to ' +
-    "select instead.";
-const NO_MATCHING_OPTION_REASON = "No option in this dropdown matches that value — read the page to see " +
-    "the options it offers.";
-const VALUE_DID_NOT_LAND_REASON = "The page's own scripts rejected this value — it did not stay in the " +
-    "field.";
-const EDITOR_UNAVAILABLE_REASON = "This editor cannot be filled on this page — tell the user what to " +
-    "type instead.";
-export function prefilledFieldsReport(fields) {
+import { renderedOptionTextOf } from "../reader/render.js";
+import { lastReadIgnoreSelectors, resolvedElementOfRef, } from "../reader/snapshot.js";
+import { theElementSitsInACuratedSubtree } from "../reader/snapshot-root.js";
+import { isContentEditableElement, roleOf, theControlIsDisabled, } from "../reader/roles.js";
+export async function prefilledFieldsReport(fields, probe) {
     const report = { filled: [], refused: [] };
+    const listingBudget = reportListingBudget();
     for (const field of fields) {
-        const refusal = _filledFieldRefusalOf(field);
+        const refusal = await _filledFieldRefusalOf(field, probe, listingBudget);
         if (refusal === null) {
             report.filled.push(field.refId);
         }
@@ -30,26 +19,52 @@ export function prefilledFieldsReport(fields) {
     }
     return report;
 }
-function _filledFieldRefusalOf(field) {
+async function _filledFieldRefusalOf(field, probe, listingBudget) {
     const resolved = resolvedElementOfRef(field.refId);
     if (resolved.error !== null) {
         return resolved.error;
     }
     const element = resolved.element;
     if (element instanceof HTMLInputElement) {
-        return _inputRefusalOf(element, field.value);
+        return _inputRefusalOf(element, field.value, probe, listingBudget);
     }
     if (element instanceof HTMLTextAreaElement) {
         return _textAreaRefusalOf(element, field.value);
     }
     if (element instanceof HTMLSelectElement) {
-        return _selectRefusalOf(element, field.value);
+        return _selectRefusalOf(element, field.value, listingBudget);
     }
     if (isContentEditableElement(element)) {
         return _editorRefusalOf(element, field.value);
     }
+    if (_isAriaToggle(element)) {
+        const { ariaToggleRefusalOf } = await import("./aria-toggles.js");
+        return ariaToggleRefusalOf(element, field.value);
+    }
+    if (_isCustomDropdown(element)) {
+        const { customDropdownRefusalOf } = await import("./aria-dropdowns.js");
+        return customDropdownRefusalOf(element, field.value, probe, listingBudget);
+    }
+    if (_isStandingListbox(element)) {
+        const { listboxPickRefusalOf } = await import("./aria-dropdowns.js");
+        return listboxPickRefusalOf(element, field.value, probe, listingBudget);
+    }
     return NOT_FILLABLE_REASON;
 }
+const _TOGGLE_ROLES = new Set(["checkbox", "radio", "switch"]);
+function _isAriaToggle(element) {
+    return _TOGGLE_ROLES.has(roleOf(element));
+}
+function _isCustomDropdown(element) {
+    if (element instanceof HTMLSelectElement) {
+        return false;
+    }
+    return (roleOf(element) === "combobox" ||
+        (element.getAttribute("aria-haspopup") ?? "").toLowerCase() === "listbox");
+}
+function _isStandingListbox(element) {
+    return roleOf(element) === "listbox";
+}
 const _NOT_A_FIELD_INPUT_TYPES = new Set([
     "hidden",
     "submit",
@@ -57,7 +72,7 @@ const _NOT_A_FIELD_INPUT_TYPES = new Set([
     "reset",
     "image",
 ]);
-function _inputRefusalOf(input, value) {
+async function _inputRefusalOf(input, value, probe, listingBudget) {
     if (input.type === "password" || theFieldHoldsASecret(input)) {
         return SECRET_FIELD_REASON;
     }
@@ -67,59 +82,105 @@ function _inputRefusalOf(input, value) {
     if (_NOT_A_FIELD_INPUT_TYPES.has(input.type)) {
         return NOT_FILLABLE_REASON;
     }
-    if (input.disabled || input.readOnly) {
+    const isComboboxInput = roleOf(input) === "combobox";
+    if (theControlIsInert(input) ||
+        input.disabled ||
+        (input.readOnly && !isComboboxInput)) {
         return INERT_FIELD_REASON;
     }
     if (input.type === "checkbox" || input.type === "radio") {
+        if (input.getAttribute("aria-hidden") === "true") {
+            return MIRROR_INPUT_REASON;
+        }
         return _checkedRefusalOf(input, value);
     }
-    _setThroughThePrototype(input, value);
-    _announceTheEdit(input);
-    return input.value === value ? null : VALUE_DID_NOT_LAND_REASON;
+    if (isComboboxInput) {
+        const { customDropdownRefusalOf } = await import("./aria-dropdowns.js");
+        return customDropdownRefusalOf(input, value, probe, listingBudget, async (fallbackReason) => input.readOnly
+            ? fallbackReason
+            : _typedValueRefusalOf(input, value, () => input.value));
+    }
+    return _typedValueRefusalOf(input, value, () => input.value);
 }
-function _checkedRefusalOf(input, value) {
-    if (value !== "true" && value !== "false") {
-        return CHECKBOX_VALUE_REASON;
+async function _typedValueRefusalOf(control, value, read) {
+    typeLikeAUser(control, value);
+    const landed = (await settledValueOf(read)) === value;
+    if (!control.isConnected) {
+        return CONTROL_REDRAWN_REASON;
     }
-    if (input.type === "radio" && value === "false") {
+    return landed ? null : VALUE_DID_NOT_LAND_REASON;
+}
+async function _checkedRefusalOf(input, value) {
+    if (input.type === "radio" && value !== "true") {
         return RADIO_VALUE_REASON;
     }
+    if (value !== "true" && value !== "false") {
+        return CHECKBOX_VALUE_REASON;
+    }
     const desired = value === "true";
-    if (input.checked !== desired) {
-        input.click();
+    if (input.checked === desired) {
+        return null;
+    }
+    if (theClickWouldSubmitOrLeaveThePage(input)) {
+        return SUBMITTING_CONTROL_REASON;
     }
-    return input.checked === desired ? null : VALUE_DID_NOT_LAND_REASON;
+    input.click();
+    const landed = (await settledValueOf(() => input.checked)) === desired;
+    if (!input.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    return landed ? null : VALUE_DID_NOT_LAND_REASON;
 }
-function _textAreaRefusalOf(textArea, value) {
+async function _textAreaRefusalOf(textArea, value) {
     if (theFieldHoldsASecret(textArea)) {
         return SECRET_FIELD_REASON;
     }
-    if (textArea.disabled || textArea.readOnly) {
+    if (theControlIsInert(textArea) || textArea.disabled || textArea.readOnly) {
         return INERT_FIELD_REASON;
     }
-    _setThroughThePrototype(textArea, value);
-    _announceTheEdit(textArea);
-    return textArea.value === value ? null : VALUE_DID_NOT_LAND_REASON;
+    return _typedValueRefusalOf(textArea, value, () => textArea.value);
 }
-function _selectRefusalOf(select, value) {
-    if (select.disabled) {
+async function _selectRefusalOf(select, value, listingBudget) {
+    if (theControlIsInert(select) || select.disabled) {
         return INERT_FIELD_REASON;
     }
+    if (select.multiple) {
+        return MULTI_CHOICE_REASON;
+    }
     const option = _optionMatching(select, value);
     if (option === null) {
-        return NO_MATCHING_OPTION_REASON;
+        const labels = _matchableOptionsOf(select)
+            .filter((candidate) => !theControlIsDisabled(candidate, "option"))
+            .map((candidate) => candidate.label.trim());
+        return noMatchingOptionReasonListing(labels, listingBudget);
+    }
+    if (select.value === option.value) {
+        return null;
     }
-    _setThroughThePrototype(select, option.value);
-    _announceTheEdit(select);
-    return select.value === option.value ? null : VALUE_DID_NOT_LAND_REASON;
+    if (theControlIsDisabled(option, "option")) {
+        return unavailableOptionReason(option.label.trim());
+    }
+    return _typedValueRefusalOf(select, option.value, () => select.value);
 }
 function _optionMatching(select, value) {
-    const options = Array.from(select.options);
+    const options = _matchableOptionsOf(select);
     return (options.find((option) => option.value === value) ??
         options.find((option) => option.label.trim() === value.trim()) ??
+        options.find((option) => {
+            const shownToTheModel = renderedOptionTextOf(option);
+            const full = option.text.replace(/\s+/g, " ").trim();
+            return (shownToTheModel !== full && shownToTheModel.trimEnd() === value.trim());
+        }) ??
         null);
 }
-function _editorRefusalOf(element, value) {
+function _matchableOptionsOf(select) {
+    const ignoreSelectors = lastReadIgnoreSelectors();
+    return Array.from(select.options).filter((option) => !theElementSitsInACuratedSubtree(option, ignoreSelectors));
+}
+async function _editorRefusalOf(element, value) {
+    if (theControlIsInert(element)) {
+        return INERT_FIELD_REASON;
+    }
     if (!(element instanceof HTMLElement)) {
         return EDITOR_UNAVAILABLE_REASON;
     }
@@ -133,19 +194,9 @@ function _editorRefusalOf(element, value) {
     }
     selection.selectAllChildren(element);
     document.execCommand("insertText", false, value);
-    const landed = element.textContent.includes(value);
-    return landed ? null : VALUE_DID_NOT_LAND_REASON;
-}
-function _setThroughThePrototype(control, value) {
-    const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(control), "value");
-    if (descriptor?.set !== undefined) {
-        descriptor.set.call(control, value);
+    const landed = await settledValueOf(() => element.textContent.includes(value));
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
     }
-    else {
-        control.value = value;
-    }
-}
-function _announceTheEdit(control) {
-    control.dispatchEvent(new Event("input", { bubbles: true }));
-    control.dispatchEvent(new Event("change", { bubbles: true }));
+    return landed ? null : VALUE_DID_NOT_LAND_REASON;
 }

package/dist/core/execution-handlers.js

@@ -55,7 +55,7 @@ export function executionHandlersFor(navigate, executeActionIntent, threadId) {
     }
     handlers.set(READ_PAGE_REQUEST_KIND, (entry) => _readPageOutcomeOf(threadId, entry));
     handlers.set(HIGHLIGHT_REQUEST_KIND, (entry) => Promise.resolve(_highlightOutcomeOf(entry)));
-    handlers.set(PREFILL_FORM_REQUEST_KIND, (entry) => Promise.resolve(_prefillFormOutcomeOf(entry)));
+    handlers.set(PREFILL_FORM_REQUEST_KIND, (entry) => _prefillFormOutcomeOf(entry));
     return handlers;
 }
 async function _navigateOutcomeOf(navigate, entry) {
@@ -316,13 +316,13 @@ function _highlightFailedOutcome(error) {
         },
     };
 }
-function _prefillFormOutcomeOf(entry) {
+async function _prefillFormOutcomeOf(entry) {
     const fields = _prefillFieldsOf(entry.action);
     if (fields === null) {
         return UNUSABLE_FIELDS_OUTCOME;
     }
     try {
-        const result = prefilledFieldsReport(fields);
+        const result = await prefilledFieldsReport(fields, browserLayoutProbe());
         return { ok: true, result: { ...result } };
     }
     catch (error) {

package/dist/reader/render.js

@@ -55,10 +55,7 @@ function _renderNode(node, depth, lines) {
 function _renderSelectOptions(select, depth, lines) {
     const indent = _indentOf(depth);
     for (const option of Array.from(select.options)) {
-        const text = option.text
-            .replace(/\s+/g, " ")
-            .trim()
-            .substring(0, MAX_OPTION_TEXT_LENGTH);
+        const text = renderedOptionTextOf(option);
         let line = `${indent}- option "${_escapedText(text)}"`;
         if (option.selected) {
             line += " (selected)";
@@ -115,3 +112,9 @@ function _escapedText(text) {
 function _indentOf(depth) {
     return "  ".repeat(depth);
 }
+export function renderedOptionTextOf(option) {
+    return option.text
+        .replace(/\s+/g, " ")
+        .trim()
+        .substring(0, MAX_OPTION_TEXT_LENGTH);
+}

package/dist/reader/roles.js

@@ -1,3 +1,4 @@
+import { parentAcrossShadowBoundaryOf } from "./visibility.js";
 const IMPLICIT_ROLE_BY_TAG = {
     a: "link",
     button: "button",
@@ -131,7 +132,7 @@ export const ARIA_CHECKED_ROLES = new Set([
     "menuitemradio",
     "switch",
 ]);
-export const ARIA_DISABLED_ROLES = new Set([
+const ARIA_DISABLED_ROLES = new Set([
     "application",
     "button",
     "composite",
@@ -213,6 +214,32 @@ export function ariaBooleanOf(attribute) {
     }
     return attribute.toLowerCase() === "true";
 }
+export function theControlIsDisabled(element, role) {
+    if (!ARIA_DISABLED_ROLES.has(role)) {
+        return false;
+    }
+    if (_isNativelyDisabled(element)) {
+        return true;
+    }
+    for (let current = element; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
+        if (ariaBooleanOf(current.getAttribute("aria-disabled")) === true) {
+            return true;
+        }
+    }
+    return false;
+}
+function _isNativelyDisabled(element) {
+    const tag = element.tagName.toLowerCase();
+    if (!["button", "input", "select", "textarea", "option", "optgroup"].includes(tag)) {
+        return false;
+    }
+    try {
+        return element.matches(":disabled");
+    }
+    catch {
+        return false;
+    }
+}
 function _implicitRoleOf(element) {
     const tag = element.tagName.toLowerCase();
     if (isContentEditableElement(element)) {

package/dist/reader/snapshot-node.js

@@ -1,8 +1,7 @@
 import { accessibleNameOf } from "./accessible-name.js";
 import { CONTENT_REF_ROLES, INTERACTIVE_REF_ROLES, interactivitySignalsOf, isScrollable, } from "./interactivity.js";
 import { textboxValueOf } from "./redaction.js";
-import { ariaBooleanOf, ariaLevelOf, ARIA_CHECKED_ROLES, ARIA_DISABLED_ROLES, ARIA_SELECTED_ROLES, roleOf, } from "./roles.js";
-import { parentAcrossShadowBoundaryOf } from "./visibility.js";
+import { ariaBooleanOf, ariaLevelOf, ARIA_CHECKED_ROLES, ARIA_SELECTED_ROLES, roleOf, theControlIsDisabled, } from "./roles.js";
 const MAX_NODE_NAME_LENGTH = 100;
 export function _snapshotNodeOf(element, context, refFor) {
     const { options, oracle, nameCache } = context;
@@ -35,7 +34,7 @@ export function _snapshotNodeOf(element, context, refFor) {
         checked: _checkedStateOf(element, roleLower),
         selected: _selectedStateOf(element, roleLower),
         focused: element.ownerDocument.activeElement === element,
-        disabled: _disabledStateOf(element, roleLower),
+        disabled: theControlIsDisabled(element, roleLower),
         offscreen: !hidden && oracle.isOffscreen(element),
         refId,
         hints,
@@ -63,32 +62,6 @@ function _selectedStateOf(element, role) {
     }
     return ariaBooleanOf(element.getAttribute("aria-selected")) === true;
 }
-function _disabledStateOf(element, role) {
-    if (!ARIA_DISABLED_ROLES.has(role)) {
-        return false;
-    }
-    if (_isNativelyDisabled(element)) {
-        return true;
-    }
-    for (let current = element; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
-        if (ariaBooleanOf(current.getAttribute("aria-disabled")) === true) {
-            return true;
-        }
-    }
-    return false;
-}
-function _isNativelyDisabled(element) {
-    const tag = element.tagName.toLowerCase();
-    if (!["button", "input", "select", "textarea", "option", "optgroup"].includes(tag)) {
-        return false;
-    }
-    try {
-        return element.matches(":disabled");
-    }
-    catch {
-        return false;
-    }
-}
 export function _normalizedNodeName(name) {
     return name.replace(/\s+/g, " ").trim().substring(0, MAX_NODE_NAME_LENGTH);
 }

package/dist/reader/snapshot-root.js

@@ -34,17 +34,23 @@ export function _resolvedRootOf(options, elementByRef) {
     return { root: body, error: null };
 }
 function _rootUnlessCurated(root, options) {
-    for (let current = root; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
-        if (_theSubtreeIsCurated(current, options.ignoreSelectors)) {
-            return {
-                root: null,
-                error: "That part of the page has opted out of page reads — " +
-                    "take a full read to see what is available.",
-            };
-        }
+    if (theElementSitsInACuratedSubtree(root, options.ignoreSelectors)) {
+        return {
+            root: null,
+            error: "That part of the page has opted out of page reads — " +
+                "take a full read to see what is available.",
+        };
     }
     return { root, error: null };
 }
+export function theElementSitsInACuratedSubtree(element, ignoreSelectors) {
+    for (let current = element; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
+        if (_theSubtreeIsCurated(current, ignoreSelectors)) {
+            return true;
+        }
+    }
+    return false;
+}
 function _safeQuerySelector(selector) {
     try {
         const direct = document.querySelector(selector);

package/dist/reader/snapshot.js

@@ -18,6 +18,10 @@ const SKIP_TAGS = new Set([
 let _refCounter = 0;
 const _refBadgeByElement = new WeakMap();
 const _elementByRef = new Map();
+let _lastReadIgnoreSelectors = [];
+export function lastReadIgnoreSelectors() {
+    return _lastReadIgnoreSelectors;
+}
 export function snapshotTreeOf(options) {
     const context = {
         options,
@@ -30,6 +34,7 @@ export function snapshotTreeOf(options) {
     }
     const root = rooting.root;
     _elementByRef.clear();
+    _lastReadIgnoreSelectors = options.ignoreSelectors;
     const fragment = _fragmentNode();
     _traverse(root, 0, fragment, context);
     _mergeStringChildren(fragment);
@@ -52,7 +57,7 @@ export function resolvedElementOfRef(refId) {
         rootElement: null,
         refId,
         selector: null,
-        ignoreSelectors: [],
+        ignoreSelectors: _lastReadIgnoreSelectors,
     };
     const rooting = _resolvedRootOf(address, _elementByRef);
     if (rooting.error !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teaflask/assistant",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "The AI assistant for your product: drop it into your React app or any page with a script tag.",
   "license": "FSL-1.1-ALv2",
   "author": "Teaflask",