@jini-ai/agentic 0.4.3 → 0.4.4

package/dist/dom/dom-page-driver.js

@@ -1,601 +0,0 @@
-import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_ELEMENT_ROLES, resolveHandleSelector, } from '../element-handles.js';
-import { normalizeAgentLabel } from '../guards.js';
-/**
- * A {@link PageDriver} over a real DOM subtree.
- *
- * Deliberately mechanical: every refusal — handle validation, the credential-field guard, the
- * page allowlist, highlight clamping — already ran in `executePageCapability` before anything
- * here is called. Re-checking would duplicate policy in a place that will drift from it.
- *
- * Scoped to a `root` the host names, never `document`. Scanning the whole document would make
- * any markup anywhere — including rendered user content — an authorization decision, which
- * inverts the point of an explicit allowlist.
- */
-/** How the marker is drawn. Inline styles, so no stylesheet or CSP allowance is needed. */
-const HIGHLIGHT_STYLE = {
-    outline: '3px solid #e11d48',
-    outlineOffset: '2px',
-    borderRadius: '4px',
-};
-/**
- * Upper bound on {@link createDomPageDriver}'s `settle`.
- *
- * A hidden tab stops delivering animation frames, so waiting for one never returns — and a
- * background tab is exactly where an agent-driven page ends up while the user works elsewhere.
- * This is the ceiling that keeps every write bounded regardless.
- */
-const SETTLE_TIMEOUT_MS = 120;
-function isAgentElementRole(value) {
-    return value !== null && AGENT_ELEMENT_ROLES.includes(value);
-}
-/**
- * Whether the element is a rich-text surface — a `contenteditable` region rather than a form
- * control. Rich-text editors are built this way, so treating one as unfillable makes every
- * comment box, description field and document editor unreachable.
- */
-function isEditableRegion(element) {
-    if (!(element instanceof HTMLElement))
-        return false;
-    // A control embedded in a rich-text document is still that control. Without this, a real
-    // browser — which, unlike jsdom, propagates `isContentEditable` to every descendant — reports
-    // the Save button inside an editor as a fillable text region, and `fill` overwrites its label
-    // instead of refusing. The type-based refusals in `findFieldFillRefusal` cannot catch that
-    // either, because the descriptor would say `contenteditable` rather than `button`.
-    if (element.matches('input, textarea, select, button, a[href], summary, option'))
-        return false;
-    // The attribute is checked before `isContentEditable` because a headless DOM does not compute
-    // the latter — relying on it alone makes every one of these tests pass vacuously while the real
-    // browser behaves differently. `contenteditable=""` and `"plaintext-only"` are both editable;
-    // only an explicit `"false"` is not.
-    const attribute = element.getAttribute('contenteditable');
-    if (attribute !== null)
-        return attribute !== 'false';
-    // Editability inherited from an ancestor, which only a real layout engine can tell us about.
-    return element.isContentEditable === true;
-}
-/** The text of every `<label>` associated with `control`, by any of the relationships that link one. */
-function labelTextsOf(control) {
-    const texts = [];
-    const add = (text) => {
-        const trimmed = text?.trim();
-        if (trimmed)
-            texts.push(trimmed);
-    };
-    // Real form controls carry `.labels` — every associated <label>, both for-linked and wrapping.
-    const associated = 'labels' in control
-        ? Array.from(control.labels ?? [])
-        : [];
-    for (const label of associated)
-        add(label.textContent);
-    // A contenteditable region is not a form control and has no `.labels`; resolve the same two
-    // relationships by hand — an ancestor <label> (implicit wrapping) and a for-linked one (explicit).
-    const wrapping = control.closest('label');
-    if (wrapping)
-        add(wrapping.textContent);
-    if (control.id) {
-        for (const label of Array.from(control.ownerDocument.querySelectorAll('label'))) {
-            if (label.htmlFor === control.id)
-                add(label.textContent);
-        }
-    }
-    return texts;
-}
-/**
- * **Every** human-visible naming of the field, for the guard's benefit: `name`/`id` are the machine
- * names, and a CMS emitting `name="field_47"` next to a visibly-labelled "Card number" leaves every
- * guard here nothing to judge unless this is populated. Sources, in the order a human would read
- * them: `aria-label`, `placeholder`, then the text of each associated `<label>` (for-linked or
- * wrapping).
- *
- * All of them, not the first that resolves. Stopping at the first made the *page* the one choosing
- * which of its own labels the guard is allowed to see, which is the opposite of what a guard is
- * for: `<label for=f>Card number</label><input id=f name=field_47 placeholder="Enter value">` was
- * described to the guard as "Enter value" alone, and its value read back in full.
- *
- * De-duplicated because one label is often reachable twice (a wrapping `<label>` is also in
- * `.labels`), and a repeated entry is noise in every refusal built from these.
- */
-function accessibleLabelsOf(control) {
-    const candidates = [
-        control.getAttribute('aria-label')?.trim(),
-        control.getAttribute('placeholder')?.trim(),
-        ...labelTextsOf(control),
-    ];
-    return [...new Set(candidates.filter((text) => !!text))];
-}
-/** The field attributes the guards need, or `null` when the control is not a text-bearing input. */
-function fieldDescriptorOf(control) {
-    if (isEditableRegion(control)) {
-        // Reported as a field so the same guards run: a contenteditable div named `card-number` is
-        // no more fillable than an input would be. `type` is not a real HTML input type, and is not
-        // in any denied set, which is correct — the guard should judge it by name and attributes.
-        return {
-            type: 'contenteditable',
-            // Read for the same reason `name` is: neither attribute is standard on a div, but a page
-            // that bothers to set one is telling the guard what the field holds, and honouring `name`
-            // while ignoring `autocomplete` would refuse `name="card_number"` and accept the
-            // `autocomplete="cc-number"` spelling of the same field.
-            autocomplete: control.getAttribute('autocomplete')?.toLowerCase() || undefined,
-            name: control.getAttribute('name') || undefined,
-            id: control.id || undefined,
-            accessibleLabels: accessibleLabelsOf(control),
-            readOnly: control.getAttribute('aria-readonly') === 'true',
-            disabled: control.getAttribute('aria-disabled') === 'true',
-        };
-    }
-    if (!(control instanceof HTMLInputElement) && !(control instanceof HTMLTextAreaElement)) {
-        return null;
-    }
-    return {
-        type: control instanceof HTMLInputElement ? control.type.toLowerCase() : 'textarea',
-        autocomplete: control.getAttribute('autocomplete')?.toLowerCase() ?? undefined,
-        name: control.name || undefined,
-        id: control.id || undefined,
-        accessibleLabels: accessibleLabelsOf(control),
-        readOnly: control.readOnly,
-        // `.disabled` reflects only this element's own attribute — not the "actually disabled" state
-        // a control gets from an ancestor `<fieldset disabled>`. `:disabled` is the platform's own
-        // answer for both, and is what decides whether the value even reaches form submission.
-        disabled: control.matches(':disabled'),
-    };
-}
-/**
- * Whether the element is actually rendered, or `undefined` when the platform cannot say.
- *
- * `checkVisibility` is the only answer that accounts for `display:none` on an ancestor, `hidden`,
- * `content-visibility` and an empty box at once. Where it is missing, this reports nothing rather
- * than falling back to a layout measurement — a headless DOM has no layout, so that fallback would
- * confidently declare every element invisible.
- *
- * The options are passed explicitly rather than relying on the method's defaults: per spec every
- * option defaults to `false`, so a bare `checkVisibility()` misses `visibility:hidden` and
- * `opacity:0` ancestors — two of the most common real ways to hide interactive UI (fade
- * transitions, visually-hidden-but-focusable patterns) — while still correctly reporting
- * `display:none`. Confirmed in real Chromium: `checkOpacity`/`checkVisibilityCSS` (this build's
- * spelling) turn a false `visible: true` on a `visibility:hidden`/`opacity:0` ancestor into the
- * correct `false`; jsdom does not implement the method at all, so no unit test can show this.
- */
-function visibilityOf(element) {
-    const check = element.checkVisibility;
-    return typeof check === 'function'
-        ? check.call(element, { checkOpacity: true, checkVisibilityCSS: true })
-        : undefined;
-}
-/**
- * `disabled` for the controls that have one; `undefined` for everything else, which is not the
- * same as `false`.
- *
- * `:disabled` rather than the `.disabled` IDL property: the property only reflects the element's
- * own attribute, so a control disabled solely by an ancestor `<fieldset disabled>` reads as
- * enabled even though a real user cannot type into or click it, and its value is excluded from
- * form submission entirely. `:disabled` is the platform's own answer and covers both cases.
- */
-function disabledOf(control) {
-    return control instanceof HTMLInputElement
-        || control instanceof HTMLTextAreaElement
-        || control instanceof HTMLButtonElement
-        || control instanceof HTMLSelectElement
-        ? control.matches(':disabled')
-        : undefined;
-}
-function describe(element, page) {
-    const role = element.getAttribute(AGENT_ROLE_ATTRIBUTE);
-    /* c8 ignore next -- `Node.textContent` is typed nullable for the abstract node; on an Element it is always a string, so the `?? ''` satisfies the type and is not a reachable path. */
-    const text = element.textContent ?? '';
-    // Live text is a fine fallback label for an ordinary element — it is the page's own ontology,
-    // rendered openly. For an editable region it is not: a contenteditable's content is the *user's
-    // data*, so falling back to it published the contents of a rich-text field to every
-    // `find_elements` caller, with no `withState` asked for and no read guard anywhere in the way
-    // (`<div contenteditable name="password">hunter2</div>` reported `label: "hunter2"`). Such a
-    // region is named by what labels it instead, exactly as `fieldDescriptorOf` describes it.
-    const fallback = isEditableRegion(element) ? (accessibleLabelsOf(element)[0] ?? '') : text;
-    const label = element.getAttribute(AGENT_LABEL_ATTRIBUTE) ?? fallback;
-    /* c8 ignore next -- only ever called on a `[data-agent-element]` match, so the attribute is present by construction. */
-    const handle = element.getAttribute(AGENT_ELEMENT_ATTRIBUTE) ?? '';
-    return {
-        handle,
-        role: isAgentElementRole(role) ? role : undefined,
-        // The executor normalizes and bounds this; raw here on purpose so the guard is applied in
-        // exactly one place rather than half-applied in two.
-        label,
-        labelTruncated: false,
-        page,
-    };
-}
-/**
- * Builds a driver over `root`.
- *
- * @param options - The subtree, the navigable pages, and the current page id.
- * @returns A driver ready to hand to `executePageCapability`.
- */
-export function createDomPageDriver(options) {
-    const { root, pages } = options;
-    /**
-     * The page a specific element belongs to — its own nearest `[data-agent-page]` ancestor, not a
-     * single document-wide guess.
-     *
-     * A host that keeps more than one `[data-agent-page]` section mounted at once (tabs, wizard
-     * steps toggled with CSS rather than unmounted — the kind of SPA this driver's own options doc
-     * anticipates) previously had every element attributed to whichever section happened to be
-     * first in the DOM, regardless of which one it actually lived in. `closest` answers per element
-     * instead of once for the whole call.
-     *
-     * Still overridden by a pinned `currentPage`, unchanged: that value is the host's own claim
-     * about what is showing, taking precedence over whatever the DOM happens to say.
-     */
-    const pageOf = (element) => options.currentPage ?? element.closest(`[${AGENT_PAGE_ATTRIBUTE}]`)?.getAttribute(AGENT_PAGE_ATTRIBUTE) ?? undefined;
-    /**
-     * Active markers keyed by handle, so re-highlighting the same element restarts rather than
-     * stacks — and carrying the styling to put back, which must be captured once, on the first
-     * highlight. Re-reading the element on a restart would snapshot the marker itself, and the
-     * element would keep it forever: a capability classified `read` precisely because it is
-     * transient would permanently change how someone's page looks.
-     */
-    const highlights = new Map();
-    /**
-     * Every element published under `handle`. A page that (accidentally, or via a templating bug)
-     * publishes the same handle twice makes `find`'s single-match resolution ambiguous — surfaced
-     * here so both callers below can refuse rather than silently pick one.
-     */
-    const findAll = (handle) => Array.from(root.querySelectorAll(resolveHandleSelector(handle)));
-    /**
-     * More than one element answers to the same handle — a page-authoring bug (duplicate
-     * `data-agent-element`), not something a caller passing that handle can resolve on its own.
-     *
-     * `findElements` still lists every one of them, so the collision is discoverable; resolving a
-     * single handle to act on refuses instead of silently taking the first DOM match and leaving the
-     * others permanently unreachable with no signal that they were ever unreachable at all.
-     */
-    const ambiguousHandleError = (handle, count) => new Error(`"${handle}" is published on ${count} elements on this page, so which one it addresses is `
-        + 'ambiguous — this is a page-authoring bug (duplicate data-agent-element), not something a '
-        + 'caller can resolve; publish a unique handle per element');
-    const find = (handle) => {
-        const matches = findAll(handle);
-        if (matches.length === 0)
-            throw new Error(`no element published as "${handle}" on this page`);
-        if (matches.length > 1)
-            throw ambiguousHandleError(handle, matches.length);
-        return matches[0];
-    };
-    /**
-     * The control a handle addresses — for a wrapper like `<li><label><input>`, the input.
-     *
-     * `<details>` is called out because its interactive part is the `<summary>`: clicking the
-     * `<details>` element itself dispatches an event the platform ignores, so a disclosure widget
-     * would never open and the caller would be told the click landed.
-     */
-    const controlOf = (element) => {
-        // An editable region IS the control. Descending would find a link inside a rich-text document
-        // and address that instead of the text the caller meant to write.
-        if (isEditableRegion(element))
-            return element;
-        // `:scope >` because only a *direct child* `<summary>` is the disclosure control. An
-        // unscoped query returns the first summary anywhere in the subtree, so a `<details>`
-        // containing another one would toggle the inner disclosure while reporting that the outer
-        // handle was clicked — the false success this whole suite exists to catch.
-        if (element instanceof HTMLDetailsElement) {
-            return element.querySelector(':scope > summary') ?? element;
-        }
-        if (element.matches('input, textarea, select, button, a'))
-            return element;
-        // A descendant that is itself independently published (its own `[data-agent-element]`) must
-        // never be silently adopted as this handle's control — it is a distinct, separately
-        // addressable target with its own label, not unhandled wrapper markup like the plain
-        // `<li><label><input>` this descent exists for. Filtering to descendants whose nearest
-        // published ancestor is still `element` itself excludes exactly that case while leaving
-        // ordinary wrapper descent untouched.
-        const owned = (node) => node.closest(`[${AGENT_ELEMENT_ATTRIBUTE}]`) === element;
-        const candidate = Array.from(element.querySelectorAll('input, textarea, select, button, a, summary'))
-            .find(owned);
-        return candidate ?? element;
-    };
-    return {
-        async findElements(filter) {
-            const found = Array.from(root.querySelectorAll(`[${AGENT_ELEMENT_ATTRIBUTE}]`))
-                .map((element) => describe(element, pageOf(element)))
-                .filter((element) => element.handle.length > 0);
-            const query = filter.query?.toLowerCase();
-            return found.filter((element) => {
-                if (filter.role !== undefined && element.role !== filter.role)
-                    return false;
-                if (query === undefined)
-                    return true;
-                return element.handle.toLowerCase().includes(query)
-                    || element.label.toLowerCase().includes(query);
-            });
-        },
-        async listPages() {
-            // `Object.entries`, same own-enumerable-keys-only guarantee `Object.keys` gives `navigate`'s
-            // own `hasOwnProperty` check above — no risk of a `pages.label`/`pages.navigate`-shaped
-            // prototype entry leaking in as a fake page id.
-            return Object.entries(pages).map(([id, page]) => ({ id, label: page.label }));
-        },
-        async describeField(handle) {
-            return fieldDescriptorOf(controlOf(find(handle)));
-        },
-        async describeState(handle) {
-            // Unlike every other method here, a handle that no longer resolves is an answer rather than
-            // an error: an element that a click removed is exactly what the caller is asking about. A
-            // handle resolving to *more than one* element is a different situation entirely — not an
-            // absence but an ambiguity — so that case still refuses, same as `find`.
-            const matches = findAll(handle);
-            if (matches.length === 0)
-                return null;
-            if (matches.length > 1)
-                throw ambiguousHandleError(handle, matches.length);
-            const element = matches[0];
-            const control = controlOf(element);
-            const field = fieldDescriptorOf(control);
-            const checkable = control instanceof HTMLInputElement
-                && (control.type === 'checkbox' || control.type === 'radio');
-            // A dropdown reports its option texts alongside its value. Without them a caller can only
-            // guess what to pass to `page.select_option`, and a wrong guess is a refusal it could have
-            // avoided by looking. It carries a descriptor too, so the read guard still runs — a
-            // `<select name="secret_token">` is no more readable than an input of the same name.
-            const dropdown = control instanceof HTMLSelectElement ? control : undefined;
-            const readable = field ?? (dropdown === undefined ? null : {
-                type: 'select',
-                name: dropdown.name || undefined,
-                id: dropdown.id || undefined,
-                // Same reason `fieldDescriptorOf` carries these: a `<select aria-label="Card number"
-                // name="f9">` states its sensitivity nowhere else, and this descriptor is built by hand
-                // rather than going through that function, so it needs the labels wired up separately.
-                accessibleLabels: accessibleLabelsOf(dropdown),
-                // Same `:disabled` reasoning as `disabledOf` — a `<select>` inside a disabled `<fieldset>`
-                // is not itself flagged by the `.disabled` IDL property.
-                disabled: dropdown.matches(':disabled'),
-            });
-            const value = field !== null
-                ? control.value
-                : dropdown?.value;
-            /* c8 ignore next -- as in `describe`: an Element's textContent is always a string. */
-            const text = element.textContent ?? '';
-            return {
-                text,
-                // A contenteditable region has no `.value`; its content IS its value, so `text` is the
-                // one channel carrying it and the executor has to gate it exactly like a value. Reported
-                // as a mechanical fact about the element, not as a judgment about the content — the
-                // decision of whether it may be shown stays in `projectElementState`, with every other
-                // secrecy rule.
-                ...(isEditableRegion(control) ? { textIsValue: true } : {}),
-                // Reported raw and unconditionally; `projectElementState` applies the read guard. A
-                // driver deciding here which values are secret is a driver holding policy.
-                ...(value !== undefined ? { value } : {}),
-                ...(checkable ? { checked: control.checked } : {}),
-                ...(disabledOf(control) !== undefined ? { disabled: disabledOf(control) } : {}),
-                ...(visibilityOf(element) !== undefined ? { visible: visibilityOf(element) } : {}),
-                ...(readable !== null ? { field: readable } : {}),
-                ...(dropdown !== undefined
-                    ? {
-                        options: Array.from(dropdown.options)
-                            .map((entry) => entry.text.trim())
-                            .filter((entry) => entry.length > 0),
-                    }
-                    : {}),
-            };
-        },
-        /**
-         * Two animation frames — long enough for a framework to have re-rendered and the browser to
-         * have painted — or {@link SETTLE_TIMEOUT_MS}, whichever lands first. Without the timeout this
-         * would hang for the whole life of a backgrounded tab; without the frames every write would
-         * report its own target unchanged, because the read would beat the render.
-         */
-        async settle() {
-            await new Promise((resolve) => {
-                let timer;
-                // No re-entry guard: whichever side loses the race calls this again, and both of its
-                // effects are already idempotent — clearing an elapsed timer is a no-op, and a second
-                // `resolve` on a settled promise is ignored. A flag here would only be a branch nothing
-                // can distinguish.
-                const finish = () => {
-                    if (timer !== undefined)
-                        clearTimeout(timer);
-                    resolve();
-                };
-                const raf = globalThis.requestAnimationFrame;
-                // With no animation frames to wait for, one macrotask is the whole mechanism, and waiting
-                // the full ceiling on every write would be pure latency.
-                timer = setTimeout(finish, typeof raf === 'function' ? SETTLE_TIMEOUT_MS : 0);
-                if (typeof raf === 'function')
-                    raf(() => raf(finish));
-            });
-        },
-        async highlight(handle, durationMs) {
-            const element = find(handle);
-            // Same refusal as `click()`, for the same reason: an SVG (or other non-HTMLElement) target
-            // has no `.style` to draw an outline on, so silently returning here drew nothing while
-            // `page-executor.ts` unconditionally reports the highlight as successful — a guaranteed
-            // false positive with no way for the caller to tell. Refusing makes that visible instead.
-            if (!(element instanceof HTMLElement))
-                throw new Error(`"${handle}" is not highlightable`);
-            const active = highlights.get(handle);
-            if (active !== undefined)
-                clearTimeout(active.timer);
-            // Reuse the first capture on a restart; see the map's own doc for what re-reading would cost.
-            const restore = active?.restore ?? {
-                outline: element.style.outline,
-                outlineOffset: element.style.outlineOffset,
-                borderRadius: element.style.borderRadius,
-            };
-            Object.assign(element.style, HIGHLIGHT_STYLE);
-            element.scrollIntoView({ behavior: 'smooth', block: 'center' });
-            const timer = setTimeout(() => {
-                // Restore what was there rather than clearing: the element may have had its own outline.
-                Object.assign(element.style, restore);
-                highlights.delete(handle);
-            }, durationMs);
-            highlights.set(handle, { timer, restore });
-        },
-        async scrollTo(handle) {
-            find(handle).scrollIntoView({ behavior: 'smooth', block: 'center' });
-        },
-        async click(handle) {
-            const control = controlOf(find(handle));
-            if (!(control instanceof HTMLElement))
-                throw new Error(`"${handle}" is not clickable`);
-            control.click();
-        },
-        async fill(handle, text) {
-            const control = controlOf(find(handle));
-            if (isEditableRegion(control)) {
-                // A contenteditable region has no `value`; its content *is* its children, and a real
-                // editor owns that subtree. See `fillEditableRegion` for why this drives it through
-                // selection + `execCommand` rather than replacing `textContent` directly.
-                fillEditableRegion(control, text);
-                return;
-            }
-            if (!(control instanceof HTMLInputElement) && !(control instanceof HTMLTextAreaElement)) {
-                throw new Error(`"${handle}" is not a fillable field`);
-            }
-            // Assign through the prototype setter, then dispatch: React tracks the previous value on
-            // the node and ignores an input event whose value it believes it already has, so a plain
-            // `control.value = text` updates the DOM but leaves React state stale.
-            const prototype = control instanceof HTMLInputElement
-                ? HTMLInputElement.prototype
-                : HTMLTextAreaElement.prototype;
-            const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set;
-            if (setter)
-                setter.call(control, text);
-            else
-                control.value = text;
-            control.dispatchEvent(new Event('input', { bubbles: true }));
-            control.dispatchEvent(new Event('change', { bubbles: true }));
-        },
-        async selectOption(handle, option, selected = true) {
-            const control = controlOf(find(handle));
-            if (!(control instanceof HTMLSelectElement)) {
-                throw new Error(`"${handle}" is not a dropdown`);
-            }
-            // A disabled control is not one a user could touch, so writing to it is a way around the
-            // page's own rule and the resulting selection cannot be submitted. The per-`<option>` filter
-            // below reads as if it enforced that, but only ever looked at each option — a
-            // `<select disabled>` (and a `<select>` inside a `<fieldset disabled>`, which `:disabled`
-            // also covers and `.disabled` does not) was written to happily, and the executor then
-            // reported `targetChanged: true` because the value really had changed.
-            //
-            // Checked before the option lookup on purpose: the refusal is about the control, so it must
-            // not depend on the caller having named a real option, and the "Available: ..." message must
-            // not enumerate a disabled control's options.
-            if (control.matches(':disabled')) {
-                throw new Error(`"${handle}" is disabled, so its selection cannot be changed — `
-                    + 'a user cannot change it either, and its value would not be submitted');
-            }
-            // Visible text first, then value: the text is what a caller saw in `find_elements`, and
-            // matching value first would make an option whose value collides with another's label
-            // resolve to the wrong entry.
-            // A disabled option is not selectable by the user either, for the same reason.
-            const options = Array.from(control.options).filter((entry) => !entry.disabled);
-            const match = options.find((entry) => entry.text.trim() === option)
-                ?? options.find((entry) => entry.value === option);
-            if (match === undefined) {
-                // Every other piece of page-authored text this system hands to a model goes through
-                // normalizeAgentLabel first — bounded, control- and bidi-stripped. `available` is exactly
-                // that: the page's own <option> texts, read verbatim with no length bound of their own.
-                // The caller's `option` is sanitized too, for the same reason page.navigate's caller-
-                // supplied `page` now is — an unbounded value reaching a thrown message a model reads is
-                // the same shape of problem regardless of which side authored it. `handle` needs no
-                // treatment: it is already validated ASCII, length-capped by isValidElementHandle before
-                // this driver is ever called.
-                const safeOption = normalizeAgentLabel(option).text;
-                const available = options.map((entry) => normalizeAgentLabel(entry.text.trim()).text)
-                    .filter((text) => text.length > 0);
-                throw new Error(`"${safeOption}" is not an option of "${handle}". Available: ${available.length > 0 ? available.join(', ') : '(none)'}`);
-            }
-            if (control.multiple) {
-                // A multi-select accumulates by default. Assigning `value` would silently clear every
-                // prior choice, so a caller building up a selection would end with only its last call's
-                // option — and setting `.selected` directly is also how a caller narrows one back off
-                // without disturbing the rest.
-                match.selected = selected;
-            }
-            else if (!selected) {
-                // A single-select's one option IS its value; there is no "off" state to put it in. Silently
-                // ignoring this would tell the caller a deselect happened when nothing changed, and clearing
-                // the control would invent a third state (no selection) that a native <select> cannot hold.
-                throw new Error(`"${handle}" is a single-select; its choice cannot be removed, only replaced — `
-                    + `select a different option instead of deselecting "${normalizeAgentLabel(option).text}"`);
-            }
-            else {
-                // Same prototype-setter dance as `fill`, for the same reason: React tracks the previous
-                // value on the node and ignores a change event whose value it believes it already has.
-                const setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
-                if (setter)
-                    setter.call(control, match.value);
-                else
-                    control.value = match.value;
-            }
-            control.dispatchEvent(new Event('input', { bubbles: true }));
-            control.dispatchEvent(new Event('change', { bubbles: true }));
-        },
-        async navigate(page) {
-            // `hasOwnProperty`, not `pages[page]`: a plain object literal inherits everything
-            // `Object.prototype` contributes, so a bare lookup answered `navigate("constructor")` with
-            // the `Object` constructor — a function the host never published, which this then called,
-            // reporting a navigation that never happened. `navigate("__proto__")` was worse in a
-            // different way: it resolved a non-callable object and failed with "go is not a function"
-            // instead of the refusal this check exists to produce. `listPages` already reports only own
-            // keys (`Object.keys`), so this is what makes the two agree.
-            const published = Object.prototype.hasOwnProperty.call(pages, page);
-            // The executor already checked the allowlist and sanitizes this same message before this
-            // driver-level check would ever be reached through it; this is the belt on the braces. But
-            // `PageDriver` is a public interface — a caller that reaches this method directly, bypassing
-            // the executor entirely, hands `page` in unsanitized, so the same bound-and-strip treatment
-            // applies here too rather than assuming the only caller is the one that already checked.
-            if (!published)
-                throw new Error(`"${normalizeAgentLabel(page).text}" is not a published page`);
-            pages[page].navigate();
-        },
-    };
-}
-/**
- * Writes into a contenteditable region the way a real user typing would, rather than by replacing
- * its DOM directly.
- *
- * A framework rich-text editor (Lexical, ProseMirror, Quill, CodeMirror) owns its subtree: it
- * keeps its own model and reconciles the DOM to match it, so a direct `textContent =` write is
- * either invisible to that model or gets reverted on the editor's next render — and it always
- * destroys whatever node structure the editor had built (a mention's `<span>`, a paragraph's `<p>`)
- * in favour of one bare text node. Selecting the existing contents and issuing a real editing
- * command instead is what Playwright's own `fill` does against a contenteditable, for the same
- * reason: `execCommand('insertText'|'delete')` is the platform's own command, so the browser fires
- * `beforeinput`/`input` itself with the correct `inputType` — the exact signal these editors
- * listen for — rather than this driver guessing at a contract it does not own by hand-rolling one.
- *
- * jsdom implements neither a real editing host nor `execCommand`, so every unit test here exercises
- * the fallback: the previous `textContent` + synthetic `input` behaviour, kept for exactly that
- * case and for a real browser that reports the command did not run.
- *
- * Verified 2026-07-26 in Chromium against real Lexical 0.36.2 — the editor
- * `packages/ui/src/features/rich-text-input/` is built on — driving both paths at one editor each
- * and reading back Lexical's own `EditorState`, not the DOM. The `textContent` write left the
- * model at its seed value and was reverted in the DOM too; the `execCommand` path landed in the
- * model. That is the whole reason this function exists, and no unit test in this repo can show it.
- */
-function fillEditableRegion(control, text) {
-    control.focus();
-    const selection = globalThis.getSelection?.();
-    if (selection) {
-        const range = control.ownerDocument.createRange();
-        range.selectNodeContents(control);
-        selection.removeAllRanges();
-        selection.addRange(range);
-    }
-    const execCommand = control.ownerDocument.execCommand?.bind(control.ownerDocument);
-    if (typeof execCommand === 'function') {
-        // An empty replacement has no text to insert; `delete` removes the just-selected contents,
-        // which `insertText` with an empty string is not guaranteed to do in every engine.
-        const ran = text.length > 0 ? execCommand('insertText', false, text) : execCommand('delete');
-        if (ran)
-            return;
-    }
-    control.textContent = text;
-    // Editors listen for `input`, not `change`; `change` is a form-control event and firing it here
-    // would be inventing an event the platform never sends for this element.
-    control.dispatchEvent(new Event('input', { bubbles: true }));
-}
-/** Reads the current page's `data-agent-page`, for hosts that tag the body. */
-export function currentAgentPage(root) {
-    const tagged = root.querySelector(`[${AGENT_PAGE_ATTRIBUTE}]`);
-    return tagged?.getAttribute(AGENT_PAGE_ATTRIBUTE) ?? undefined;
-}
-//# sourceMappingURL=dom-page-driver.js.map

package/dist/dom/index.d.ts

@@ -1,17 +0,0 @@
-/**
- * @jini-ai/agentic/dom — the browser half of agent control.
- *
- * The one `PageDriver` (see `@jini-ai/agentic`'s `page-driver.ts`) that reads and writes a real DOM
- * subtree. Split into its own entry point, compiled under its own `DOM`-lib `tsconfig.dom.json`,
- * so the rest of this package can stay provably DOM-free — see source-map.md's "The DOM split".
- *
- * `@jini-ai/chat-react` is this package's one in-repo consumer today.
- */
-export { createDomPageDriver, currentAgentPage, type DomPageDriverOptions, type DomPageDriverPage, } from './dom-page-driver.js';
-/**
- * WebMCP feature detection — moved 2026-07-26 from `@jini-ai/ui`'s `agent-tools/model-context.ts`
- * (plan §8 step 6). See `model-context.ts`'s module doc for why it lives here rather than
- * alongside `../webmcp.ts`'s DOM-free projection.
- */
-export { getAgentModelContext, type AgentModelContextLike, type AgentModelContextToolRegistration, } from './model-context.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/dom/index.js

@@ -1,17 +0,0 @@
-/**
- * @jini-ai/agentic/dom — the browser half of agent control.
- *
- * The one `PageDriver` (see `@jini-ai/agentic`'s `page-driver.ts`) that reads and writes a real DOM
- * subtree. Split into its own entry point, compiled under its own `DOM`-lib `tsconfig.dom.json`,
- * so the rest of this package can stay provably DOM-free — see source-map.md's "The DOM split".
- *
- * `@jini-ai/chat-react` is this package's one in-repo consumer today.
- */
-export { createDomPageDriver, currentAgentPage, } from './dom-page-driver.js';
-/**
- * WebMCP feature detection — moved 2026-07-26 from `@jini-ai/ui`'s `agent-tools/model-context.ts`
- * (plan §8 step 6). See `model-context.ts`'s module doc for why it lives here rather than
- * alongside `../webmcp.ts`'s DOM-free projection.
- */
-export { getAgentModelContext, } from './model-context.js';
-//# sourceMappingURL=index.js.map