@jini-ai/agentic 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @jini-ai/agentic
 
+## 0.4.5 — 2026-10-22
+
+- 2026-10-22: Complexity refactors with characterization pins, coverage.
+
 ## 0.4.3
 
 ### Patch Changes

package/dist/core/a2ui/json-pointer.js

@@ -64,42 +64,108 @@ export function parsePointerTokens({ pointer }, _optional = {}) {
     return pointer.slice(1).split('/').map(unescapeToken);
 }
 export function joinPointer({ base, tokens }, _optional = {}) {
-    const baseTokens = base === '' || base === '/' ? [] : parsePointerTokens({ pointer: base });
+    const baseTokens = isRootPointer(base) ? [] : parsePointerTokens({ pointer: base });
     return '/' + [...baseTokens, ...tokens].map(escapeToken).join('/');
 }
-/** Reads the value at `pointer` in `doc`. Never throws on a non-resolving path — `found: false` degrades sanely, matching this port's "a bad binding must not crash the renderer" adversarial requirement (see `resolve.ts`). */
-export function getAtPointer({ doc, pointer }, _optional = {}) {
-    if (isRootPointer(pointer))
-        return { found: true, value: doc };
-    let tokens;
+/** The pointer's tokens, or `null` for a malformed pointer — the read and write paths both degrade on that instead of throwing. */
+function tryParsePointerTokens(pointer) {
     try {
-        tokens = parsePointerTokens({ pointer });
+        return parsePointerTokens({ pointer });
     }
     catch {
-        return { found: false, value: undefined };
+        return null;
+    }
+}
+/** The array index `token` names, or `undefined` unless it is a canonical RFC 6901 index (`0`, or digits with no leading zero — never `-`, signs, exponents or whitespace). */
+function arrayIndexOf(token) {
+    return /^(0|[1-9]\d*)$/.test(token) ? Number(token) : undefined;
+}
+function isObjectLike(value) {
+    return value !== null && typeof value === 'object';
+}
+function notFound() {
+    return { found: false, value: undefined };
+}
+/** One step of a read: the member `token` names in `current`, if `current` itself (never its prototype chain) has it. */
+function readMember(current, token) {
+    if (Array.isArray(current)) {
+        const index = arrayIndexOf(token);
+        return index !== undefined && index < current.length ? { found: true, value: current[index] } : notFound();
     }
+    return isObjectLike(current) && hasOwnToken(current, token) ? { found: true, value: current[token] } : notFound();
+}
+/** Reads the value at `pointer` in `doc`. Never throws on a non-resolving path — `found: false` degrades sanely, matching this port's "a bad binding must not crash the renderer" adversarial requirement (see `resolve.ts`). */
+export function getAtPointer({ doc, pointer }, _optional = {}) {
+    if (isRootPointer(pointer))
+        return { found: true, value: doc };
+    const tokens = tryParsePointerTokens(pointer);
+    if (tokens === null)
+        return notFound();
     let current = doc;
     for (const token of tokens) {
-        if (Array.isArray(current)) {
-            if (!/^(0|[1-9]\d*)$/.test(token))
-                return { found: false, value: undefined };
-            const index = Number(token);
-            if (index >= current.length)
-                return { found: false, value: undefined };
-            current = current[index];
-            continue;
-        }
-        if (current !== null && typeof current === 'object') {
-            const record = current;
-            if (!hasOwnToken(record, token))
-                return { found: false, value: undefined };
-            current = record[token];
-            continue;
-        }
-        return { found: false, value: undefined };
+        const step = readMember(current, token);
+        if (!step.found)
+            return step;
+        current = step.value;
     }
     return { found: true, value: current };
 }
+/** A shallow copy of `current` when it is an object, otherwise a fresh empty object to write into. */
+function copyRecord(current) {
+    return isObjectLike(current) ? { ...current } : {};
+}
+/** The final write/delete into an array parent. A non-index token leaves the array untouched (same instance). */
+function writeArrayLeaf(array, token, value) {
+    const index = arrayIndexOf(token);
+    if (index === undefined)
+        return array;
+    const next = array.slice();
+    // `splice` past the end removes nothing, so an out-of-range delete needs no guard of its own.
+    if (value === null) {
+        next.splice(index, 1);
+    }
+    else {
+        next[index] = value;
+    }
+    return next;
+}
+/** The final write/delete into an object parent (a non-object parent is replaced by a fresh object). */
+function writeRecordLeaf(current, token, value) {
+    const record = copyRecord(current);
+    if (value === null) {
+        delete record[token];
+    }
+    else {
+        defineOwn(record, token, value);
+    }
+    return record;
+}
+/** Returns a copy of `current` with `leaf` applied at `remaining` (the parent tokens still to walk). */
+function writePath(current, remaining, leaf) {
+    if (remaining.length === 0) {
+        // `current` here is the parent container; apply the final write/delete.
+        return Array.isArray(current) ? writeArrayLeaf(current, leaf.token, leaf.value) : writeRecordLeaf(current, leaf.token, leaf.value);
+    }
+    const [head, ...rest] = remaining;
+    return Array.isArray(current) ? writeArrayBranch(current, head, rest, leaf) : writeRecordBranch(current, head, rest, leaf);
+}
+/** An intermediate array segment. A non-index token (the empty token included) leaves the array untouched. */
+function writeArrayBranch(array, head, rest, leaf) {
+    const index = arrayIndexOf(head);
+    if (index === undefined)
+        return array;
+    const next = array.slice();
+    next[index] = writePath(index < next.length ? next[index] : {}, rest, leaf);
+    return next;
+}
+/** An intermediate object segment. An empty-string token is a documented no-op (see the `"//x"` test): the copy is returned unwritten. */
+function writeRecordBranch(current, head, rest, leaf) {
+    const record = copyRecord(current);
+    if (!head)
+        return record;
+    defineOwn(record, head, writePath(hasOwnToken(record, head) ? record[head] : {}, rest, leaf));
+    return record;
+}
 /**
  * Writes `value` at `pointer` in `doc`, returning a **new** document (the original is never
  * mutated — every intermediate object on the path is shallow-copied). Missing intermediate
@@ -121,54 +187,9 @@ export function getAtPointer({ doc, pointer }, _optional = {}) {
 export function setAtPointer({ doc, pointer, value }, _optional = {}) {
     if (isRootPointer(pointer))
         return value;
-    let tokens;
-    try {
-        tokens = parsePointerTokens({ pointer });
-    }
-    catch {
+    const tokens = tryParsePointerTokens(pointer);
+    if (tokens === null)
         return doc;
-    }
-    const parentTokens = tokens.slice(0, -1);
-    const lastToken = tokens[tokens.length - 1];
-    function recurse(current, remaining) {
-        if (remaining.length === 0) {
-            // `current` here is the parent container; apply the final write/delete.
-            if (Array.isArray(current)) {
-                if (!/^(0|[1-9]\d*)$/.test(lastToken))
-                    return current;
-                const index = Number(lastToken);
-                const next = current.slice();
-                if (value === null) {
-                    if (index < next.length)
-                        next.splice(index, 1);
-                    return next;
-                }
-                next[index] = value;
-                return next;
-            }
-            const record = current !== null && typeof current === 'object' ? { ...current } : {};
-            if (value === null) {
-                delete record[lastToken];
-                return record;
-            }
-            defineOwn(record, lastToken, value);
-            return record;
-        }
-        const [head, ...rest] = remaining;
-        if (Array.isArray(current)) {
-            if (!head || !/^(0|[1-9]\d*)$/.test(head))
-                return current;
-            const index = Number(head);
-            const next = current.slice();
-            next[index] = recurse(index < next.length ? next[index] : {}, rest);
-            return next;
-        }
-        const record = current !== null && typeof current === 'object' ? { ...current } : {};
-        if (!head)
-            return record;
-        defineOwn(record, head, recurse(hasOwnToken(record, head) ? record[head] : {}, rest));
-        return record;
-    }
-    return recurse(doc, parentTokens);
+    return writePath(doc, tokens.slice(0, -1), { token: tokens[tokens.length - 1], value });
 }
 //# sourceMappingURL=json-pointer.js.map

package/dist/core/a2ui/resolve.js

@@ -56,41 +56,60 @@ function resolveBindingPath(path, ctx) {
     }
     return { ok: true, value: result.value };
 }
-function resolveFunctionCall(call, ctx) {
-    if (call.call === '@index') {
-        if (!ctx.itemScope) {
-            return { ok: false, reason: 'INDEX_OUTSIDE_LIST_CONTEXT', detail: '@index used outside a list-template item context' };
-        }
-        const offsetArg = call.args?.offset;
-        const offsetResult = offsetArg === undefined ? { ok: true, value: 0 } : resolveDynamicValue({ value: offsetArg, ctx: ctx }, { itemScope: ctx.itemScope });
-        if (!offsetResult.ok)
-            return offsetResult;
-        const offset = typeof offsetResult.value === 'number' ? offsetResult.value : 0;
-        return { ok: true, value: ctx.itemScope.index + offset };
+/** `@index` (the one system function, answered without the catalog): the item scope's index plus an optional, resolved `offset` arg (non-numeric counts as 0). */
+function resolveIndexCall(call, ctx) {
+    if (!ctx.itemScope) {
+        return { ok: false, reason: 'INDEX_OUTSIDE_LIST_CONTEXT', detail: '@index used outside a list-template item context' };
     }
+    const offsetArg = call.args?.offset;
+    const offsetResult = offsetArg === undefined ? { ok: true, value: 0 } : resolveValue(offsetArg, ctx);
+    if (!offsetResult.ok)
+        return offsetResult;
+    const offset = typeof offsetResult.value === 'number' ? offsetResult.value : 0;
+    return { ok: true, value: ctx.itemScope.index + offset };
+}
+function isCallableFromSide(callableFrom, side) {
+    return callableFrom === 'rendererOrAgent' || (callableFrom === 'rendererOnly' && side === 'renderer') || (callableFrom === 'agentOnly' && side === 'agent');
+}
+/** The catalog-side refusals, in the order they apply: not registered, then the `callableFrom` boundary, then no implementation. Returns the implementation when all three pass. */
+function lookUpCallableImpl(call, ctx) {
     if (!isFunctionRegistered({ catalog: ctx.catalog, functionName: call.call })) {
         return { ok: false, reason: 'FUNCTION_NOT_REGISTERED', detail: `function "${call.call}" is not registered in catalog "${ctx.catalog.catalogId}"` };
     }
     const callableFrom = callableFromOf({ catalog: ctx.catalog, functionName: call.call });
-    const allowed = callableFrom === 'rendererOrAgent' || (callableFrom === 'rendererOnly' && ctx.side === 'renderer') || (callableFrom === 'agentOnly' && ctx.side === 'agent');
-    if (!allowed) {
+    if (!isCallableFromSide(callableFrom, ctx.side)) {
         return {
             ok: false,
             reason: 'FUNCTION_NOT_CALLABLE_FROM_SIDE',
             detail: `function "${call.call}" has callableFrom="${callableFrom}", not callable from the "${ctx.side}" side`,
         };
     }
-    const spec = ctx.catalog.functions.get(call.call);
-    if (!spec?.impl) {
+    const impl = ctx.catalog.functions.get(call.call)?.impl;
+    if (!impl) {
         return { ok: false, reason: 'FUNCTION_NOT_IMPLEMENTED', detail: `function "${call.call}" is registered but this renderer has no implementation for it` };
     }
+    return { ok: true, impl };
+}
+/** Resolves every arg value in key order, stopping at the first failure. */
+function resolveArgs(args, ctx) {
     const resolvedArgs = {};
-    for (const [key, argValue] of Object.entries(call.args ?? {})) {
+    for (const [key, argValue] of Object.entries(args ?? {})) {
         const argResult = resolveArgValue(argValue, ctx);
         if (!argResult.ok)
             return argResult;
         resolvedArgs[key] = argResult.value;
     }
+    return { ok: true, value: resolvedArgs };
+}
+function resolveFunctionCall(call, ctx) {
+    if (call.call === '@index')
+        return resolveIndexCall(call, ctx);
+    const lookup = lookUpCallableImpl(call, ctx);
+    if (!lookup.ok)
+        return lookup;
+    const argsResult = resolveArgs(call.args, ctx);
+    if (!argsResult.ok)
+        return argsResult;
     // `impl` is host-supplied code handed agent-supplied arguments, and this module validates
     // neither against the other (the catalog's per-function arg schemas are not implemented — see
     // `catalog.ts`'s module doc). An entirely ordinary implementation therefore throws the moment an
@@ -98,7 +117,7 @@ function resolveFunctionCall(call, ctx) {
     // travel out through `applyAgentMessage` into the host's render, where nothing catches it. It is
     // a resolution failure like any other: reported, not propagated.
     try {
-        return { ok: true, value: spec.impl(resolvedArgs) };
+        return { ok: true, value: lookup.impl(argsResult.value) };
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
@@ -131,15 +150,18 @@ function resolveArgValue(argValue, ctx) {
         }
         return { ok: true, value: resolvedItems };
     }
-    return resolveDynamicValue({ value: argValue, ctx: ctx }, { itemScope: ctx.itemScope });
+    return resolveValue(argValue, ctx);
 }
-/** Resolves any `Dynamic*` value (`DynamicString`/`DynamicNumber`/`DynamicBoolean`/`DynamicStringList`/`DynamicValue` all share this one shape: literal | `DataBinding` | `FunctionCall`). */
-export function resolveDynamicValue({ value, ctx }, { itemScope } = {}) {
-    const context = { ...ctx, ...(itemScope === undefined ? {} : { itemScope }) };
+/** Resolves one `Dynamic*` value in an already-built context (the item scope, if any, is in `ctx`). */
+function resolveValue(value, ctx) {
     if (isDataBinding(value))
-        return resolveBindingPath(value.path, context);
+        return resolveBindingPath(value.path, ctx);
     if (isFunctionCall(value))
-        return resolveFunctionCall(value, context);
+        return resolveFunctionCall(value, ctx);
     return { ok: true, value };
 }
+/** Resolves any `Dynamic*` value (`DynamicString`/`DynamicNumber`/`DynamicBoolean`/`DynamicStringList`/`DynamicValue` all share this one shape: literal | `DataBinding` | `FunctionCall`). */
+export function resolveDynamicValue({ value, ctx }, { itemScope } = {}) {
+    return resolveValue(value, { ...ctx, ...(itemScope === undefined ? {} : { itemScope }) });
+}
 //# sourceMappingURL=resolve.js.map

package/dist/core/a2ui/tree.js

@@ -11,6 +11,13 @@
  * is orders of magnitude smaller), so this is a fail-safe, not a design budget.
  */
 export const MAX_RENDER_NODES = 50_000;
+/** Pushes `childIds` onto the walk's stack at `depth`. */
+function pushChildren(stack, childIds, depth) {
+    // Pushed in reverse so the first child is popped first, preserving pre-order.
+    for (let index = childIds.length - 1; index >= 0; index -= 1) {
+        stack.push({ id: childIds[index], depth });
+    }
+}
 /**
  * @param components The full component map (id -> instance).
  * @param rootId The id to start walking from (typically `'root'`, but not assumed — a surface
@@ -63,11 +70,7 @@ export function flattenRenderTree({ components, rootId, getChildIds }, _optional
         output.push({ id, depth, status: 'ok' });
         ancestors.add(id);
         stack.push({ leave: id });
-        // Pushed in reverse so the first child is popped first, preserving pre-order.
-        const childIds = getChildIds({ component });
-        for (let index = childIds.length - 1; index >= 0; index -= 1) {
-            stack.push({ id: childIds[index], depth: depth + 1 });
-        }
+        pushChildren(stack, getChildIds({ component }), depth + 1);
     }
     return output;
 }

package/dist/core/capability.js

@@ -40,19 +40,28 @@ export function findCapabilityInputError({ capability, input }, _optional = {})
             return `"${name}" is required`;
     }
     if (additionalProperties === false) {
-        // `key in properties` walks the whole prototype chain, so a key that happens to be inherited
-        // from Object.prototype (`__proto__`, `constructor`, `toString`, `valueOf`, …) reads as
-        // "known" regardless of whether the schema actually lists it — `'constructor' in {}` is
-        // true even on an empty object. `JSON.parse('{"__proto__":...}')` creates a real own data
-        // property (not the accessor), so this was a live way for such a key to escape the
-        // "unknown argument" refusal entirely. hasOwnProperty ignores the prototype chain, so only
-        // keys the schema actually declares count as known.
-        const unknown = Object.keys(input)
-            .filter((key) => !Object.prototype.hasOwnProperty.call(properties, key));
-        if (unknown.length > 0) {
-            return `unknown ${unknown.length === 1 ? 'argument' : 'arguments'}: ${unknown.sort().join(', ')}`;
-        }
+        const unknownError = findUnknownArgumentError({ properties, input });
+        if (unknownError !== null)
+            return unknownError;
+    }
+    return findPropertyInputError({ properties, input });
+}
+function findUnknownArgumentError({ properties, input }, _optional = {}) {
+    // `key in properties` walks the whole prototype chain, so a key that happens to be inherited
+    // from Object.prototype (`__proto__`, `constructor`, `toString`, `valueOf`, …) reads as
+    // "known" regardless of whether the schema actually lists it — `'constructor' in {}` is
+    // true even on an empty object. `JSON.parse('{"__proto__":...}')` creates a real own data
+    // property (not the accessor), so this was a live way for such a key to escape the
+    // "unknown argument" refusal entirely. hasOwnProperty ignores the prototype chain, so only
+    // keys the schema actually declares count as known.
+    const unknown = Object.keys(input)
+        .filter((key) => !Object.prototype.hasOwnProperty.call(properties, key));
+    if (unknown.length > 0) {
+        return `unknown ${unknown.length === 1 ? 'argument' : 'arguments'}: ${unknown.sort().join(', ')}`;
     }
+    return null;
+}
+function findPropertyInputError({ properties, input }, _optional = {}) {
     for (const [name, schema] of Object.entries(properties)) {
         const value = input[name];
         if (value === undefined)

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

@@ -103,25 +103,28 @@ function accessibleLabelsOf(control) {
     ];
     return [...new Set(candidates.filter((text) => !!text))];
 }
+function editableFieldDescriptorOf({ control }, _optional = {}) {
+    // 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',
+    };
+}
 /** 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',
-        };
+        return editableFieldDescriptorOf({ control });
     }
     if (!(control instanceof HTMLInputElement) && !(control instanceof HTMLTextAreaElement)) {
         return null;
@@ -139,6 +142,48 @@ function fieldDescriptorOf(control) {
         disabled: control.matches(':disabled'),
     };
 }
+function dropdownFieldDescriptorOf({ dropdown }, _optional = {}) {
+    if (dropdown === undefined)
+        return null;
+    return {
+        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'),
+    };
+}
+function rawElementStateOf({ element, control, checkable, readable, value, dropdown }, _optional = {}) {
+    const text = publicTextOf(element);
+    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),
+            }
+            : {}),
+    };
+}
 /**
  * Whether the element is actually rendered, or `undefined` when the platform cannot say.
  *
@@ -222,6 +267,30 @@ function describe(element, page) {
         page,
     };
 }
+function findSelectableOption({ control, handle, option }, _optional = {}) {
+    // 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({ raw: option }).text;
+        const available = options.map((entry) => normalizeAgentLabel({ raw: 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)'}`);
+    }
+    return match;
+}
 /**
  * Builds a driver over `root`.
  *
@@ -355,45 +424,11 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             // 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 readable = field ?? dropdownFieldDescriptorOf({ dropdown });
             const value = field !== null
                 ? control.value
                 : dropdown?.value;
-            const text = publicTextOf(element);
-            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),
-                    }
-                    : {}),
-            };
+            return rawElementStateOf({ element, control, checkable, readable, value, dropdown });
         },
         /**
          * Two animation frames — long enough for a framework to have re-rendered and the browser to
@@ -489,7 +524,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             }
             // 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
+            // in `findSelectableOption` 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.
@@ -501,27 +536,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
                 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({ raw: option }).text;
-                const available = options.map((entry) => normalizeAgentLabel({ raw: 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)'}`);
-            }
+            const match = findSelectableOption({ control, handle, option });
             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