@jini-ai/agentic 0.6.15-rc.2 → 0.6.16

package/dist/core/a2ui/catalog.js

@@ -211,8 +211,11 @@ const SliderPropsSchema = checkableComponentProps({
  * mutually exclusive in practice, so exactly-one and at-least-one coincide.
  */
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-const ISO_TIME = /^\d{2}:\d{2}(:\d{2}(\.\d+)?)?([Zz]|[+-]\d{2}:\d{2})?$/;
-const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?([Zz]|[+-]\d{2}:\d{2})?$/;
+// `hh:mm[:ss[.fff]]` and an optional `Z`/`±hh:mm` offset, shared by the time and date-time forms.
+const CLOCK_TIME = /\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?/.source;
+const UTC_OFFSET = /(?:[Zz]|[+-]\d{2}:\d{2})?/.source;
+const ISO_TIME = new RegExp(`^${CLOCK_TIME}${UTC_OFFSET}$`);
+const ISO_DATE_TIME = new RegExp(`^\\d{4}-\\d{2}-\\d{2}[Tt ]${CLOCK_TIME}${UTC_OFFSET}$`);
 const IsoDateTimeBoundSchema = DynamicStringSchema.superRefine((value, ctx) => {
     if (typeof value !== 'string')
         return;

package/dist/core/a2ui/common-types.d.ts

@@ -226,7 +226,7 @@ export declare const ComponentCommonSchema: z.ZodObject<{
 export type ComponentCommon = z.infer<typeof ComponentCommonSchema>;
 /** `common_types.json#/$defs/Child` — "A reference to a single child component ID." */
 export declare const ChildSchema: z.ZodString;
-export type Child = ComponentId;
+export type Child = z.infer<typeof ChildSchema>;
 /**
  * `common_types.json#/$defs/ChildList` — either a static array of `ComponentId`s, or a template
  * object (`{componentId, path}`) that generates one child per item in a data-model list.

package/dist/core/a2ui/renderer-to-agent.d.ts

@@ -78,15 +78,15 @@ export declare const ValidationFailedErrorSchema: z.ZodObject<{
     path: z.ZodString;
     message: z.ZodString;
 }, "strict", z.ZodTypeAny, {
+    path: string;
     surfaceId: string;
     code: "VALIDATION_FAILED";
     message: string;
-    path: string;
 }, {
+    path: string;
     surfaceId: string;
     code: "VALIDATION_FAILED";
     message: string;
-    path: string;
 }>;
 export type ValidationFailedError = z.infer<typeof ValidationFailedErrorSchema>;
 export declare const GenericErrorSchema: z.ZodEffects<z.ZodObject<{
@@ -122,15 +122,15 @@ export declare const ErrorPayloadSchema: z.ZodUnion<[z.ZodObject<{
     path: z.ZodString;
     message: z.ZodString;
 }, "strict", z.ZodTypeAny, {
+    path: string;
     surfaceId: string;
     code: "VALIDATION_FAILED";
     message: string;
-    path: string;
 }, {
+    path: string;
     surfaceId: string;
     code: "VALIDATION_FAILED";
     message: string;
-    path: string;
 }>, z.ZodEffects<z.ZodObject<{
     code: z.ZodEffects<z.ZodString, string, string>;
     message: z.ZodString;
@@ -257,15 +257,15 @@ export declare const ErrorMessageSchema: z.ZodObject<{
         path: z.ZodString;
         message: z.ZodString;
     }, "strict", z.ZodTypeAny, {
+        path: string;
         surfaceId: string;
         code: "VALIDATION_FAILED";
         message: string;
-        path: string;
     }, {
+        path: string;
         surfaceId: string;
         code: "VALIDATION_FAILED";
         message: string;
-        path: string;
     }>, z.ZodEffects<z.ZodObject<{
         code: z.ZodEffects<z.ZodString, string, string>;
         message: z.ZodString;
@@ -294,10 +294,10 @@ export declare const ErrorMessageSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>]>;
 }, "strict", z.ZodTypeAny, {
     error: {
+        path: string;
         surfaceId: string;
         code: "VALIDATION_FAILED";
         message: string;
-        path: string;
     } | z.objectOutputType<{
         code: z.ZodEffects<z.ZodString, string, string>;
         message: z.ZodString;
@@ -307,10 +307,10 @@ export declare const ErrorMessageSchema: z.ZodObject<{
     version: "v1.0";
 }, {
     error: {
+        path: string;
         surfaceId: string;
         code: "VALIDATION_FAILED";
         message: string;
-        path: string;
     } | z.objectInputType<{
         code: z.ZodEffects<z.ZodString, string, string>;
         message: z.ZodString;

package/dist/core/a2ui/renderer-to-agent.js

@@ -85,6 +85,8 @@ export function buildGenericErrorMessage({ code, message, target }, _optional =
     return { version: PROTOCOL_VERSION, error: { code, message, ...target } };
 }
 const MESSAGE_KEYS = ['action', 'functionResponse', 'error'];
+/** The schema each message key's envelope is validated against. */
+const MESSAGE_SCHEMAS = { action: ActionMessageSchema, functionResponse: FunctionResponseMessageSchema, error: ErrorMessageSchema };
 /** Same "inspect the shape, validate the one matching branch" dispatcher as `parseAgentToRendererMessage` — see that function's doc for why this beats a plain `z.union`. Used by tests and by anything on the agent side of this fixture that needs to validate what the browser sent. */
 export function parseRendererToAgentMessage({ raw }, _optional = {}) {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
@@ -99,7 +101,7 @@ export function parseRendererToAgentMessage({ raw }, _optional = {}) {
         return { ok: false, reason: `expected exactly one of ${MESSAGE_KEYS.join(', ')}, found ${presentKeys.length}` };
     }
     const key = presentKeys[0];
-    const schema = key === 'action' ? ActionMessageSchema : key === 'functionResponse' ? FunctionResponseMessageSchema : ErrorMessageSchema;
+    const schema = MESSAGE_SCHEMAS[key];
     const result = schema.safeParse(obj);
     if (!result.success) {
         // Same zod guarantee as `parseAgentToRendererMessage` relies on: `success: false` implies a

package/dist/core/a2ui/resolve.js

@@ -27,26 +27,29 @@ import { callableFromOf, isFunctionRegistered } from './catalog.js';
  * `applyAgentMessage`, which this module's own doc says cannot happen.
  */
 function isDataBinding(value) {
-    return typeof value === 'object'
-        && value !== null
-        && !Array.isArray(value)
-        && 'path' in value
-        && typeof value.path === 'string'
-        && Object.keys(value).length === 1;
+    return hasStringField(value, 'path') && Object.keys(value).length === 1;
 }
 function isFunctionCall(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'call' in value && typeof value.call === 'string';
+    return hasStringField(value, 'call');
+}
+/** A plain (non-array) object whose `key` holds a string. */
+function hasStringField(value, key) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    return key in value && typeof value[key] === 'string';
+}
+/** A relative path resolved under the current list item, or null outside any list-template item. */
+function itemRelativePointer(path, ctx) {
+    if (!ctx.itemScope)
+        return null;
+    return joinPointer({ base: ctx.itemScope.basePath, tokens: [String(ctx.itemScope.index), ...parsePointerTokens({ pointer: `/${path}` })] });
 }
 function resolveBindingPath(path, ctx) {
     // A relative path is still RFC 6901 syntax, so its `~0`/`~1` escapes must be decoded into real
     // token text before `joinPointer` re-escapes them. Splitting the raw string on `/` instead would
     // hand `joinPointer` already-escaped text and double-escape it, making a relative `a~1b` resolve
     // the literal key `a~1b` while the equivalent absolute pointer correctly resolves `a/b`.
-    const absolute = path.startsWith('/')
-        ? path
-        : ctx.itemScope
-            ? joinPointer({ base: ctx.itemScope.basePath, tokens: [String(ctx.itemScope.index), ...parsePointerTokens({ pointer: `/${path}` })] })
-            : null;
+    const absolute = path.startsWith('/') ? path : itemRelativePointer(path, ctx);
     if (absolute === null) {
         return { ok: false, reason: 'RELATIVE_PATH_OUTSIDE_LIST_CONTEXT', detail: `relative path "${path}" used outside a list-template item context` };
     }
@@ -69,7 +72,9 @@ function resolveIndexCall(call, ctx) {
     return { ok: true, value: ctx.itemScope.index + offset };
 }
 function isCallableFromSide(callableFrom, side) {
-    return callableFrom === 'rendererOrAgent' || (callableFrom === 'rendererOnly' && side === 'renderer') || (callableFrom === 'agentOnly' && side === 'agent');
+    if (callableFrom === 'rendererOrAgent')
+        return true;
+    return (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) {

package/dist/core/a2ui/tree.js

@@ -11,6 +11,23 @@
  * is orders of magnitude smaller), so this is a fail-safe, not a design budget.
  */
 export const MAX_RENDER_NODES = 50_000;
+/** Emits one node: a cycle back to an ancestor, a missing component, or a rendered node whose
+ *  children are queued (after a `leave` frame that pops it off the ancestor path). */
+function visitNode({ id, depth }, walk) {
+    if (walk.ancestors.has(id)) {
+        walk.output.push({ id, depth, status: 'cycle' });
+        return;
+    }
+    const component = walk.components.get(id);
+    if (!component) {
+        walk.output.push({ id, depth, status: 'missing' });
+        return;
+    }
+    walk.output.push({ id, depth, status: 'ok' });
+    walk.ancestors.add(id);
+    walk.stack.push({ leave: id });
+    pushChildren(walk.stack, walk.getChildIds({ component }), depth + 1);
+}
 /** 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.
@@ -57,20 +74,7 @@ export function flattenRenderTree({ components, rootId, getChildIds }, _optional
             output.push({ id: frame.id, depth: frame.depth, status: 'truncated' });
             return output;
         }
-        const { id, depth } = frame;
-        if (ancestors.has(id)) {
-            output.push({ id, depth, status: 'cycle' });
-            continue;
-        }
-        const component = components.get(id);
-        if (!component) {
-            output.push({ id, depth, status: 'missing' });
-            continue;
-        }
-        output.push({ id, depth, status: 'ok' });
-        ancestors.add(id);
-        stack.push({ leave: id });
-        pushChildren(stack, getChildIds({ component }), depth + 1);
+        visitNode(frame, { output, ancestors, stack, components, getChildIds });
     }
     return output;
 }

package/dist/core/ag-ui.d.ts

@@ -64,18 +64,6 @@ export declare function toAgUiTool({ capability }: {
 export declare function toAgUiTools({ capabilities }: {
     capabilities: readonly CapabilityDef[];
 }, _optional?: Record<string, never>): readonly AgUiTool[];
-/**
- * Builds the result message for a completed frontend tool call.
- *
- * AG-UI carries the result as a string, so structured output is JSON-encoded. Errors are
- * returned through this same channel rather than thrown — the agent needs to see the refusal
- * (a fill guard saying no, an unavailable capability) as a result it can reason about.
- *
- * @param messageId - Id for the result message itself.
- * @param toolCallId - The `toolCallId` from `TOOL_CALL_START`.
- * @param outcome - What happened.
- * @returns The `role: "tool"` message to send back.
- */
 export declare function createAgUiToolResult({ messageId, toolCallId, outcome }: {
     messageId: string;
     toolCallId: string;

package/dist/core/ag-ui.js

@@ -76,10 +76,12 @@ function encodeToolContent(output) {
  * @param outcome - What happened.
  * @returns The `role: "tool"` message to send back.
  */
+/** A string output verbatim; anything else through the tool-content encoder. */
+function toolOutputText(output) {
+    return typeof output === 'string' ? output : encodeToolContent(output);
+}
 export function createAgUiToolResult({ messageId, toolCallId, outcome }, _optional = {}) {
-    const content = outcome.ok
-        ? typeof outcome.output === 'string' ? outcome.output : encodeToolContent(outcome.output)
-        : JSON.stringify({ error: outcome.error });
+    const content = outcome.ok ? toolOutputText(outcome.output) : JSON.stringify({ error: outcome.error });
     return { id: messageId, role: 'tool', content, toolCallId };
 }
 //# sourceMappingURL=ag-ui.js.map

package/dist/core/annotated-actions-script.js

@@ -63,6 +63,8 @@ export function createAnnotatedActionsScript({ preferenceKey, confirmationMessag
       return true;
     }
     function descriptor(element) {
+      // Visitor discovery/disclosure marks are not external WebMCP action declarations.
+      if (['read', 'menu', 'accordion'].includes(element.getAttribute('data-tool-action'))) return null;
       var name = element.getAttribute('data-toolname') || '';
       var description = element.getAttribute('data-tooldescription') || '';
       if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name) || !description.trim() || !visible(element)) return null;
@@ -140,7 +142,7 @@ export function createAnnotatedActionsScript({ preferenceKey, confirmationMessag
     refresh();
     observer = new MutationObserver(refresh);
     observer.observe(doc.documentElement, { subtree: true, childList: true, attributes: true,
-      attributeFilter: ['data-toolname', 'data-tooldescription', 'toolname', 'href', 'download', 'type', 'disabled', 'aria-disabled', 'hidden', 'inert', 'aria-hidden', 'style', 'class', 'open'] });
+      attributeFilter: ['data-tool-action', 'data-toolname', 'data-tooldescription', 'toolname', 'href', 'download', 'type', 'disabled', 'aria-disabled', 'hidden', 'inert', 'aria-hidden', 'style', 'class', 'open'] });
   })(` + config + ');';
 }
 //# sourceMappingURL=annotated-actions-script.js.map

package/dist/core/capability.d.ts

@@ -24,13 +24,17 @@ export type CapabilityRisk = 'read' | 'write';
  * instead of waiting for a timeout that will never resolve.
  */
 export type CapabilitySurface = 'session' | 'server';
+export interface CapabilityInputProperty {
+    readonly type: string;
+    readonly description?: string;
+    readonly enum?: readonly string[];
+    readonly properties?: Record<string, CapabilityInputProperty>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | CapabilityInputProperty;
+}
 export interface CapabilityInputSchema {
     readonly type: 'object';
-    readonly properties: Record<string, {
-        type: string;
-        description?: string;
-        enum?: readonly string[];
-    }>;
+    readonly properties: Record<string, CapabilityInputProperty>;
     readonly required?: readonly string[];
     readonly additionalProperties?: boolean;
 }
@@ -65,8 +69,9 @@ export declare function findCapability({ capabilities, id }: {
  * Manifests advertise `additionalProperties: false` and a `required` list, but nothing was
  * enforcing either — handlers read the fields they knew about and ignored the rest, so a
  * misnamed argument silently became a missing one. This closes that for any surface that calls
- * it. Intentionally a shallow check, not a JSON Schema engine: these schemas are flat by
- * construction, and a real validator is a dependency this package will not take.
+ * it. Intentionally a shallow check, not a JSON Schema engine. Nested schemas describe the public
+ * contract; the owning executor enforces their shape before any effect (for example navigation
+ * entity/query inputs). This check enforces top-level types, required and unknown arguments.
  *
  * @param capability - The capability being invoked.
  * @param input - Raw caller-supplied arguments.

package/dist/core/capability.js

@@ -26,8 +26,9 @@ export function findCapability({ capabilities, id }, _optional = {}) {
  * Manifests advertise `additionalProperties: false` and a `required` list, but nothing was
  * enforcing either — handlers read the fields they knew about and ignored the rest, so a
  * misnamed argument silently became a missing one. This closes that for any surface that calls
- * it. Intentionally a shallow check, not a JSON Schema engine: these schemas are flat by
- * construction, and a real validator is a dependency this package will not take.
+ * it. Intentionally a shallow check, not a JSON Schema engine. Nested schemas describe the public
+ * contract; the owning executor enforces their shape before any effect (for example navigation
+ * entity/query inputs). This check enforces top-level types, required and unknown arguments.
  *
  * @param capability - The capability being invoked.
  * @param input - Raw caller-supplied arguments.
@@ -80,8 +81,14 @@ function findPropertyInputError({ properties, input }, _optional = {}) {
     }
     return null;
 }
+/** `typeof`, except `null` and arrays get their own names. */
+function valueKind(value) {
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'array' : typeof value;
+}
 function propertyInputError({ name, schema, value }) {
-    const actual = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+    const actual = valueKind(value);
     if (!matchesPropertyType({ value, actual, expected: schema.type })) {
         const received = typeof value === 'number' && !Number.isFinite(value) ? String(value) : actual;
         return `"${name}" must be a ${schema.type}, received ${received}`;

package/dist/core/dom/dom-page-driver.d.ts

@@ -1,10 +1,13 @@
+import type { PagePublication } from '../page-publication.js';
+import type { AgentNavigationScreen, PageNavigationInput, PageNavigationResult } from '../page-navigation.js';
 import type { PageDriver } from '../page-driver.js';
 /** One page a host allows navigation to: its human label, and how to actually get there. */
 export interface DomPageDriverPage {
     /** Shown to a caller by `page.find_elements`/`page.navigate`'s refusal message — see
      *  `PageSummary.label` for why this exists at all. */
     readonly label: string;
-    readonly navigate: (required: Record<string, never>) => void;
+    readonly navigation?: AgentNavigationScreen;
+    readonly navigate: (required: PageNavigationInput) => void | PageNavigationResult | Promise<void | PageNavigationResult>;
 }
 export interface DomPageDriverRequired {
     /** The subtree to expose. Never pass `document`. */
@@ -25,6 +28,11 @@ export interface DomPageDriverOptions {
      * view (it is bound to the connection, not the render).
      */
     readonly currentPage?: string | undefined;
+    readonly publication?: PagePublication;
+    /** Public hosts acknowledge terminal native submissions before executing the one saved effect. */
+    readonly deferSubmit?: (args: {
+        execute: () => Promise<void>;
+    }) => void;
 }
 /**
  * Builds a driver over `root`.

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

@@ -1,3 +1,4 @@
+import { createPublicationFilter, publishedText } from './publication-filter.js';
 import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_PRIVATE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_ELEMENT_ROLES, resolveHandleSelector, } from '../element-handles.js';
 import { normalizeAgentLabel } from '../guards.js';
 /**
@@ -147,6 +148,7 @@ function dropdownFieldDescriptorOf({ dropdown }, _optional = {}) {
         return null;
     return {
         type: 'select',
+        autocomplete: dropdown.getAttribute('autocomplete')?.toLowerCase() || undefined,
         name: dropdown.name || undefined,
         id: dropdown.id || undefined,
         // Same reason `fieldDescriptorOf` carries these: a `<select aria-label="Card number"
@@ -160,6 +162,7 @@ function dropdownFieldDescriptorOf({ dropdown }, _optional = {}) {
 }
 function rawElementStateOf({ element, control, checkable, readable, value, dropdown }, _optional = {}) {
     const text = publicTextOf(element);
+    const expanded = expansionOf({ element, control });
     return {
         text,
         // A contenteditable region has no `.value`; its content IS its value, so `text` is the
@@ -172,6 +175,7 @@ function rawElementStateOf({ element, control, checkable, readable, value, dropd
         // driver deciding here which values are secret is a driver holding policy.
         ...(value !== undefined ? { value } : {}),
         ...(checkable ? { checked: control.checked } : {}),
+        ...(expanded !== undefined ? { expanded } : {}),
         ...(disabledOf(control) !== undefined ? { disabled: disabledOf(control) } : {}),
         ...(visibilityOf(element) !== undefined ? { visible: visibilityOf(element) } : {}),
         ...(readable !== null ? { field: readable } : {}),
@@ -184,6 +188,20 @@ function rawElementStateOf({ element, control, checkable, readable, value, dropd
             : {}),
     };
 }
+/** Read disclosure semantics, not text changes: opening a panel often leaves its button unchanged.
+ * Native summaries have no aria-expanded; their owning details element carries the open state.
+ * @returns The platform's disclosure state, or undefined when this is not a disclosure control.
+ */
+function expansionOf({ element, control }, _options = {}) {
+    const aria = control.getAttribute('aria-expanded') ?? element.getAttribute('aria-expanded');
+    if (aria === 'true' || aria === 'false')
+        return aria === 'true';
+    if (element instanceof HTMLDetailsElement)
+        return element.open;
+    if (control.matches('summary') && control.parentElement instanceof HTMLDetailsElement)
+        return control.parentElement.open;
+    return undefined;
+}
 /**
  * Whether the element is actually rendered, or `undefined` when the platform cannot say.
  *
@@ -216,12 +234,9 @@ function visibilityOf(element) {
  * 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;
+    const formControl = control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement
+        || control instanceof HTMLButtonElement || control instanceof HTMLSelectElement;
+    return formControl ? control.matches(':disabled') : undefined;
 }
 const PRIVATE_SELECTOR = `[${AGENT_PRIVATE_ATTRIBUTE}]`;
 /** Whether `node` is inside (or is) a `[data-agent-private]` subtree. @complexity O(depth). */
@@ -244,9 +259,9 @@ function publicTextOf(element) {
     /* c8 ignore next -- as above. */
     return copy.textContent ?? '';
 }
-function describe(element, page) {
+function describe(element, page, publicText) {
     const role = element.getAttribute(AGENT_ROLE_ATTRIBUTE);
-    const text = publicTextOf(element);
+    const text = publicText ?? publicTextOf(element);
     // 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
@@ -325,8 +340,12 @@ export function createDomPageDriver({ root, pages }, options = {}) {
      * 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 })))
-        .filter((element) => !isPrivate(element));
+    const findAll = (handle) => {
+        const matches = Array.from(root.querySelectorAll(resolveHandleSelector({ handle })));
+        if (options.publication && matches.length !== 1)
+            return [];
+        return matches.filter(element => !isPrivate(element) && (!publicationFilter || publicationFilter.allows({ element, action: 'read' })));
+    };
     /**
      * 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.
@@ -338,13 +357,16 @@ export function createDomPageDriver({ root, pages }, options = {}) {
     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 find = (handle, action = 'read') => {
         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];
+        const element = matches[0];
+        if (publicationFilter && !publicationFilter.allows({ element: controlOf(element), action }))
+            throw new Error('Published action unavailable');
+        return element;
     };
     /**
      * The control a handle addresses — for a wrapper like `<li><label><input>`, the input.
@@ -379,11 +401,13 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             .find(owned);
         return candidate ?? element;
     };
+    const publicationFilter = options.publication ? createPublicationFilter({ root, publication: options.publication,
+        fieldOf: element => fieldDescriptorOf(controlOf(element)) ?? dropdownFieldDescriptorOf({ dropdown: element instanceof HTMLSelectElement ? element : undefined }) }) : undefined;
     return {
         async findElements(_required, filter = {}) {
             const found = Array.from(root.querySelectorAll(`[${AGENT_ELEMENT_ATTRIBUTE}]`))
-                .filter((element) => !isPrivate(element))
-                .map((element) => describe(element, pageOf(element)))
+                .filter(element => !isPrivate(element) && (!publicationFilter || findAll(element.getAttribute(AGENT_ELEMENT_ATTRIBUTE) ?? '').includes(element)))
+                .map((element) => describe(element, pageOf(element), publicationFilter ? publishedText({ element }) : undefined))
                 .filter((element) => element.handle.length > 0);
             const query = filter.query?.toLowerCase();
             return found.filter((element) => {
@@ -399,7 +423,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             // `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 }));
+            return Object.entries(pages).map(([id, page]) => ({ id, label: page.label, ...(page.navigation ? { navigation: page.navigation } : {}) }));
         },
         async describeField({ handle }, _optional = {}) {
             return fieldDescriptorOf(controlOf(find(handle)));
@@ -428,7 +452,8 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             const value = field !== null
                 ? control.value
                 : dropdown?.value;
-            return rawElementStateOf({ element, control, checkable, readable, value, dropdown });
+            const state = rawElementStateOf({ element, control, checkable, readable, value, dropdown });
+            return publicationState({ state, element, filtered: Boolean(publicationFilter) });
         },
         /**
          * Two animation frames — long enough for a framework to have re-rendered and the browser to
@@ -457,7 +482,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             });
         },
         async highlight({ handle, durationMs }, _optional = {}) {
-            const element = find(handle);
+            const element = find(handle, 'highlight');
             // 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
@@ -474,7 +499,9 @@ export function createDomPageDriver({ root, pages }, options = {}) {
                 borderRadius: element.style.borderRadius,
             };
             Object.assign(element.style, HIGHLIGHT_STYLE);
-            element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            // Embedded DOMs may omit scrolling; highlighting must still restore its styles.
+            if (typeof element.scrollIntoView === 'function')
+                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);
@@ -483,16 +510,29 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             highlights.set(handle, { timer, restore });
         },
         async scrollTo({ handle }, _optional = {}) {
-            find(handle).scrollIntoView({ behavior: 'smooth', block: 'center' });
+            const element = find(handle, 'scrollTo');
+            // Revealing a clicked control is best-effort in DOMs without layout (including jsdom).
+            if (typeof element.scrollIntoView === 'function')
+                element.scrollIntoView({ behavior: 'smooth', block: 'center' });
         },
         async click({ handle }, _optional = {}) {
-            const control = controlOf(find(handle));
+            const control = controlOf(find(handle, 'click'));
             if (!(control instanceof HTMLElement))
                 throw new Error(`"${handle}" is not clickable`);
-            control.click();
+            if (options.deferSubmit && nativeSubmitter(control)) {
+                options.deferSubmit({ execute: async () => {
+                        // A changed or replaced form/submitter cannot inherit the accepted plan.
+                        const live = controlOf(find(handle, 'click'));
+                        if (live !== control)
+                            throw new Error('Submission target changed');
+                        control.click();
+                    } });
+            }
+            else
+                control.click();
         },
         async fill({ handle, text }, _optional = {}) {
-            const control = controlOf(find(handle));
+            const control = controlOf(find(handle, 'fill'));
             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
@@ -518,7 +558,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             control.dispatchEvent(new Event('change', { bubbles: true }));
         },
         async selectOption({ handle, option }, { selected = true } = {}) {
-            const control = controlOf(find(handle));
+            const control = controlOf(find(handle, 'selectOption'));
             if (!(control instanceof HTMLSelectElement)) {
                 throw new Error(`"${handle}" is not a dropdown`);
             }
@@ -563,7 +603,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             control.dispatchEvent(new Event('input', { bubbles: true }));
             control.dispatchEvent(new Event('change', { bubbles: true }));
         },
-        async navigate({ page }, _optional = {}) {
+        async navigate({ page, ...input }, _optional = {}) {
             // `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,
@@ -579,7 +619,7 @@ export function createDomPageDriver({ root, pages }, options = {}) {
             // applies here too rather than assuming the only caller is the one that already checked.
             if (!published)
                 throw new Error(`"${normalizeAgentLabel({ raw: page }).text}" is not a published page`);
-            pages[page].navigate({});
+            return pages[page].navigate(input);
         },
     };
 }
@@ -634,4 +674,10 @@ export function currentAgentPage({ root }, _optional = {}) {
     const tagged = root.querySelector(`[${AGENT_PAGE_ATTRIBUTE}]`);
     return tagged?.getAttribute(AGENT_PAGE_ATTRIBUTE) ?? undefined;
 }
+function publicationState({ state, element, filtered }) {
+    return filtered ? { ...state, text: publishedText({ element }) } : state;
+}
+function nativeSubmitter(control) {
+    return (control instanceof HTMLButtonElement || control instanceof HTMLInputElement) && control.type === 'submit' && control.form !== null;
+}
 //# sourceMappingURL=dom-page-driver.js.map

package/dist/core/dom/publication-filter.d.ts

@@ -0,0 +1,26 @@
+import type { PagePublication } from '../page-publication.js';
+import { type FieldDescriptor } from '../guards.js';
+/** Rendering/private checks include ancestors, even where checkVisibility is unavailable. */
+export declare function publicElement({ element }: {
+    element: Element;
+}, _options?: {}): boolean;
+/** Read only public text nodes. Never clone private/hidden text or form values into a label.
+ * O(n) over this already-published region, never the document. */
+export declare function publishedText({ element }: {
+    element: Element;
+}, _options?: {}): string;
+/** Snapshot identities and targets once; a re-rendered control needs a fresh publication/binding.
+ * O(p × m) snapshot for p manifest entries and m scoped handles; O(depth) checks plus live duplicate detection per operation. */
+export declare function createPublicationFilter({ root, publication, fieldOf }: {
+    root: ParentNode & {
+        querySelector: Element['querySelector'];
+    };
+    publication: PagePublication;
+    fieldOf: (element: Element) => FieldDescriptor | null;
+}, _options?: {}): {
+    allows({ element, action }: {
+        element: Element;
+        action: string;
+    }): boolean;
+};
+//# sourceMappingURL=publication-filter.d.ts.map