@reticlehq/server 3.8.2 → 3.10.0

package/dist/surface/tools/merge-tools.js

@@ -36,14 +36,104 @@ function strayKeysRefusal(tool, action, stray, actions) {
 /** The union of member input shapes, every field optional so one schema serves every action. */
 function unionShape(actions) {
     const shape = {};
+    const contested = contestedKeys(actions);
     for (const tool of Object.values(actions)) {
         for (const [key, schema] of Object.entries(tool.inputSchema)) {
-            // First definition wins; siblings share field names/meanings by construction.
-            shape[key] ??= schema.isOptional() ? schema : schema.optional();
+            if (key in shape) {
+                continue;
+            }
+            // First definition wins, unless members accept different values for it: see contestedKeys.
+            if (contested.has(key)) {
+                shape[key] = eitherBound(key, actions);
+            }
+            else {
+                shape[key] = schema.isOptional() ? schema : schema.optional();
+            }
         }
     }
     return shape;
 }
+/**
+ * What a field accepts, without its description: two members that word one field differently
+ * still accept the same values.
+ */
+function boundOf(schema) {
+    try {
+        const json = { ...z.toJSONSchema(schema, { unrepresentable: 'any' }) };
+        delete json['description'];
+        return JSON.stringify(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The fields two members accept different values for (#2144).
+ *
+ * `reticle_assert { action: "now" }` caps `timeout_ms` at one request, and `action: "wait"` takes up
+ * to 600000 and answers `resume_ms` for the rest. With the first definition winning, the merged tool
+ * kept the cap of "now", and refused every wait longer than one request: `reticle verify --expect
+ * --timeout 120000` printed `verified: unknown`.
+ */
+function contestedKeys(actions) {
+    const seen = new Map();
+    const contested = new Set();
+    for (const tool of Object.values(actions)) {
+        for (const [key, schema] of Object.entries(tool.inputSchema)) {
+            const bound = boundOf(schema);
+            if (!seen.has(key)) {
+                seen.set(key, bound);
+            }
+            else if (seen.get(key) !== bound) {
+                contested.add(key);
+            }
+        }
+    }
+    return contested;
+}
+/**
+ * A contested field accepts what any member accepts. The dispatch then checks the value against the
+ * chosen action's own schema (`contestedRefusal`), so no action gets a value it would refuse.
+ */
+function eitherBound(key, actions) {
+    const owners = Object.entries(actions).filter(([, tool]) => key in tool.inputSchema);
+    const schemas = owners.flatMap(([, tool]) => {
+        const schema = tool.inputSchema[key];
+        return schema === undefined ? [] : [schema];
+    });
+    const described = owners
+        .map(([action, tool]) => {
+        const said = tool.inputSchema[key]?.description;
+        return said === undefined ? undefined : `For action "${action}": ${said}`;
+    })
+        .filter((said) => said !== undefined)
+        .join(' ');
+    const [first, second, ...rest] = schemas;
+    if (first === undefined || second === undefined) {
+        throw new Error(`mergeTools: contested key '${key}' has fewer than two schemas`);
+    }
+    const either = z.union([first, second, ...rest]).optional();
+    return 0 === described.length ? either : either.describe(described);
+}
+/** The refusal for a contested field whose value the chosen action does not accept. */
+function contestedRefusal(tool, action, args, chosen, contested) {
+    const named = [];
+    for (const key of contested) {
+        const schema = chosen.inputSchema[key];
+        if (schema === undefined || args[key] === undefined) {
+            continue;
+        }
+        const checked = schema.safeParse(args[key]);
+        if (!checked.success) {
+            named.push(`${key} (${checked.error.issues.map((issue) => issue.message).join('; ')})`);
+        }
+    }
+    if (0 === named.length) {
+        return undefined;
+    }
+    return (`invalid ${1 === named.length ? 'parameter' : 'parameters'} for ${tool} { action: "${action}" }: ` +
+        `${named.join('; ')} — NOT applied, so any result would be an answer to a different question`);
+}
 /**
  * A member that declares `action` itself cannot be merged, and the failure was SILENT.
  *
@@ -120,6 +210,7 @@ export function mergeTools(spec) {
     if (spec.defaultAction !== undefined && !(spec.defaultAction in spec.actions)) {
         throw new Error(`mergeTools(${spec.name}): defaultAction '${spec.defaultAction}' is not one of its actions`);
     }
+    const contested = contestedKeys(spec.actions);
     return {
         name: spec.name,
         description: spec.description,
@@ -148,6 +239,12 @@ export function mergeTools(spec) {
             if (0 < stray.length && action !== undefined) {
                 return Promise.reject(new Error(strayKeysRefusal(spec.name, action, stray, spec.actions)));
             }
+            const outOfBounds = action === undefined
+                ? undefined
+                : contestedRefusal(spec.name, action, args, chosen, contested);
+            if (outOfBounds !== undefined) {
+                return Promise.reject(new Error(outOfBounds));
+            }
             return chosen.handler(deps, args, call);
         },
     };

package/dist/surface/tools/merged-name-redirect.js

@@ -1,7 +1,7 @@
 /**
  * Where a merged or retired tool's old name went.
  *
- * Twenty-two names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
+ * Many names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
  * `reticle_record { action: "start" }`, `reticle_diff` became `reticle_baseline { action: "diff" }`,
  * and three were retired outright. Confirmed live in a field sweep, they all answered `unknown tool`
  * — which is the wrong answer, because the capability exists and only moved. An agent trained on an
@@ -23,6 +23,10 @@ const RETIRED_NOTE = {
         tool: ReticleTool.PROJECT,
         note: 'run outcomes are persisted automatically by reticle_flow_replay; read them with reticle_project',
     },
+    [ReticleTool.EXPLORE]: {
+        tool: ReticleTool.LOOK,
+        note: 'list the controls with reticle_look { action: "page", mode: "interactive" } (reticle_snapshot { mode: "interactive" }), and read console errors with reticle_observe { action: "console" } (reticle_console)',
+    },
     [ReticleTool.WAIT_READY]: {
         tool: ReticleTool.SESSIONS,
         note: 'waiting is implicit — the first live call already blocks until the session is ready',

package/dist/surface/tools/observe-tools.js

@@ -4,6 +4,7 @@
  */
 import { checkWords, runIdOfCall } from '../../judgement/runs/drive-run.js';
 import { noteEmptyRead } from './gaps/observed-nothing.js';
+import { withPreAttach } from './read/console-pre-attach.js';
 import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
 import { CONSOLE_ATTACH_NOTE, CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, checkIntent, } from '@reticlehq/core';
@@ -450,13 +451,15 @@ export const OBSERVE_TOOLS = [
             // Two nudges, both only on a GREEN verdict (a failing one is moot): a presence-only assertion
             // a wrong element can fake, and an assertion pinned to a status Reticle derived rather than one
             // a server sent. Neither blocks — the assertion still passes; they steer the next one.
-            const advice = !verdict.pass
-                ? {}
-                : isPresenceOnlyAssertion(predicate)
-                    ? { advice: PRESENCE_ONLY_ADVICE }
-                    : assertsDerivedIpcStatus(predicate)
-                        ? { advice: DERIVED_IPC_STATUS_ADVICE }
-                        : {};
+            let advice = {};
+            if (verdict.pass) {
+                if (isPresenceOnlyAssertion(predicate)) {
+                    advice = { advice: PRESENCE_ONLY_ADVICE };
+                }
+                else if (assertsDerivedIpcStatus(predicate)) {
+                    advice = { advice: DERIVED_IPC_STATUS_ADVICE };
+                }
+            }
             // Asked of every verdict drawn after an observed edit, not once per edit — see
             // isChangeUndeclared for why repeating it is disclosure rather than nagging.
             // Read once: the undeclared-change check and the engine's claim reading share it.
@@ -609,7 +612,10 @@ export const OBSERVE_TOOLS = [
              * `true` and `false` keep their exact old meanings, so a caller that already passes one is
              * unaffected. Only the omitted case moves.
              */
-            const bodyMode = 'boolean' === typeof args['bodies'] ? (args['bodies'] ? 'all' : 'none') : 'auto';
+            let bodyMode = 'auto';
+            if ('boolean' === typeof args['bodies']) {
+                bodyMode = args['bodies'] ? 'all' : 'none';
+            }
             // A filter names specific calls, so under `auto` their bodies are the thing being asked about.
             const named = method !== undefined || urlContains !== undefined || status !== undefined;
             const buffer = bufferEnvelope(session);
@@ -729,7 +735,7 @@ export const OBSERVE_TOOLS = [
             }
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
-            const logs = budgeted.map(projectConsoleLog);
+            const logs = budgeted.map((e) => withPreAttach(projectConsoleLog(e), e));
             // Say the look HAPPENED when it found nothing. A quiet page and a dead console observer both
             // produced `{ logs: [] }`, and "no console errors" is the claim agents lean on most — see
             // observed-nothing.ts, whose own header names this exact case and which every other array-

package/dist/surface/tools/read/console-pre-attach.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Say on a console line that the page raised it before the SDK attached (#1540).
+ *
+ * The build plugin's inline buffer holds what an app raised while nothing listened: an entry module
+ * that 404'd or threw, a rejection, a `console.error` during start-up. The SDK reports it when it
+ * attaches, marked `preAttach`. Without the mark on the line the agent reads, a reported error looks
+ * like one the last action caused, and the reason a page is blank is not read as a load failure.
+ *
+ * Here and not in the engine's `projectConsoleLog`: the engine does not take new names from core.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+export interface PreAttachMark {
+    /** The page raised it before the SDK attached. */
+    preAttach?: true;
+    /** How many more pre-attach errors the full buffer did not keep — loss, declared. */
+    droppedPreAttach?: number;
+}
+/** The console line, with the pre-attach mark and the declared loss when the event carries them. */
+export declare function withPreAttach<T extends object>(view: T, e: ReticleEvent): T & PreAttachMark;

package/dist/surface/tools/read/console-pre-attach.js

@@ -0,0 +1,23 @@
+/**
+ * Say on a console line that the page raised it before the SDK attached (#1540).
+ *
+ * The build plugin's inline buffer holds what an app raised while nothing listened: an entry module
+ * that 404'd or threw, a rejection, a `console.error` during start-up. The SDK reports it when it
+ * attaches, marked `preAttach`. Without the mark on the line the agent reads, a reported error looks
+ * like one the last action caused, and the reason a page is blank is not read as a load failure.
+ *
+ * Here and not in the engine's `projectConsoleLog`: the engine does not take new names from core.
+ */
+import { CONSOLE_EVENT, asNumber } from '@reticlehq/core';
+/** The console line, with the pre-attach mark and the declared loss when the event carries them. */
+export function withPreAttach(view, e) {
+    const mark = {};
+    if (true === e.data[CONSOLE_EVENT.PRE_ATTACH]) {
+        mark.preAttach = true;
+    }
+    const dropped = asNumber(e.data[CONSOLE_EVENT.DROPPED_PRE_ATTACH]);
+    if (dropped !== undefined && dropped > 0) {
+        mark.droppedPreAttach = dropped;
+    }
+    return { ...view, ...mark };
+}

package/dist/surface/tools/read-tools.js

@@ -2,12 +2,14 @@
  * Read / record / replay tools — baselines + diff, recordings + replay, narrate, clock, state,
  * explore. Split out of tools.ts; assembled back via...READ_TOOLS.
  */
-import { UNKEPT_EXPECT } from '../../language/flows/replay.js';
+import { UNKEPT_EXPECT, pageOf } from '../../language/flows/replay.js';
 import { resolveAnnotateTarget } from '../../language/flows/annotate-notes/annotate-target.js';
 import { z } from 'zod';
 import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode, StorageArea, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { advanceMsSchema, depthSchema } from './args/numeric-bounds.js';
+import { StepFramesSchema } from '../../portal/pool/determinism.js';
+const NOT_DETERMINISTIC = 'stepFrames needs a deterministic lease. Acquire one with reticle_lease { action: "acquire", url, deterministic: {} }, then pass its sessionId.';
 import { aliasParam, aliasUsed } from './args/alias-args.js';
 /** `name` for `recordingName`: the spelling every other naming argument uses. */
 const RECORDING_NAME_ALIAS = z.string().optional().describe('Alias for `recordingName`.');
@@ -22,25 +24,6 @@ import { buildReactionReport, summarizeReaction } from '@reticlehq/engine/questi
 import { asNumber, asString, parseInteractive } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../../portal/session/session-health.js';
-import { navigablePath, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
-/** The route part of a session URL. A host belongs to the machine, not to the journey. */
-/**
- * The page a recording started on, as a NAVIGABLE path: pathname + query + hash.
- *
- * The hash matters and the pathname alone is not enough. Under a hash router every page has the
- * document pathname `/`, so a recording made on `#/posts/12` stored `/`, the replay's start-path
- * comparison saw `/` on both sides and never warned about drift, and the navigate it suggests
- * pointed at the default route rather than the recorded one.
- */
-function pathnameOf(url) {
-    if (url === undefined)
-        return undefined;
-    const parts = routeOfUrl(url);
-    // The query too, minus Reticle's own params: `/products?scope=TOPWEAR` and `/products` are different
-    // pages, and replay compares the query when the flow recorded one (#1059), so dropping it here
-    // started the replay on the unfiltered page (#1411).
-    return parts === undefined ? undefined : navigablePath(parts);
-}
 /** What record-stop says when the span crossed a full-page load (#1411). */
 const RECORDING_CROSSED_RELOAD = 'The recording crossed a full-page load: the page it started on unloaded, so the reaction report and the proposed consequences cover only the page that loaded after it.';
 /**
@@ -161,7 +144,7 @@ export const READ_TOOLS = [
             recordingName: z
                 .string()
                 .optional()
-                .describe('Identifier for this recording. Pass the same name to reticle_record{action:"stop"} and reticle_replay.'),
+                .describe('Identifier for this recording. Pass the same name to reticle_record{action:"stop"} and reticle_record{action:"replay"}.'),
             name: RECORDING_NAME_ALIAS,
             ...sessionIdShape,
         },
@@ -176,9 +159,9 @@ export const READ_TOOLS = [
             const name = asString(aliasParam(args, 'recordingName', ['name'])['recordingName']) ?? 'default';
             const cursor = session.elapsed();
             // Where the journey begins, so a saved flow can navigate here before step 1 instead of
-            // replaying from wherever the page happens to be. Pathname only: a host or port belongs to
-            // the machine that recorded it, not to the journey.
-            deps.recordings.start(name, cursor, pathnameOf(session.url), session.id, session.currentDocumentId);
+            // replaying from wherever the page happens to be. No host or port: they belong to the machine
+            // that recorded it, not to the journey. The app's query and hash stay (see pageOf).
+            deps.recordings.start(name, cursor, pageOf(session.url), session.id, session.currentDocumentId);
             return Promise.resolve({
                 recordingName: name,
                 since: cursor,
@@ -339,7 +322,7 @@ export const READ_TOOLS = [
     },
     {
         name: ReticleTool.CLOCK,
-        description: 'Control a fake clock: { freeze:true } to freeze time, { advanceMs:N } to fast-forward timers (toasts, debounces, auto-dismiss), { reset:true } to restore. Lets you test time-gated UI deterministically.',
+        description: 'Control a fake clock: { freeze:true } to freeze time, { advanceMs:N } to fast-forward timers (toasts, debounces, auto-dismiss), { reset:true } to restore. Lets you test time-gated UI deterministically. On a lease acquired with `deterministic`, { stepFrames:N } moves its clock N frames of 16.67 ms: due timers run, then the requestAnimationFrame callbacks, once each frame.',
         inputSchema: {
             freeze: z
                 .boolean()
@@ -349,6 +332,7 @@ export const READ_TOOLS = [
                 .optional()
                 .describe('Fast-forward time by this many milliseconds — triggers debounces, toasts, auto-dismiss timers.'),
             reset: z.boolean().optional().describe('Restore the real clock.'),
+            stepFrames: StepFramesSchema.optional().describe('Step a deterministic lease by this many frames (60 each second). Only for a lease acquired with `deterministic`.'),
             ...sessionIdShape,
         },
         // The command returns `{ frozen }`. It used to declare `{ ok, elapsed }` — neither of which any
@@ -356,12 +340,31 @@ export const READ_TOOLS = [
         // successful freeze and a failed one both validated to `{}` and became indistinguishable.
         outputSchema: {
             frozen: z.boolean().optional(),
+            frame: z
+                .number()
+                .optional()
+                .describe('After stepFrames: the frames stepped since the page loaded.'),
+            nowMs: z
+                .number()
+                .optional()
+                .describe("After stepFrames: the page's performance.now(), in virtual milliseconds."),
+        },
+        handler: async (deps, args) => {
+            if (args['stepFrames'] !== undefined) {
+                const session = deps.sessions.resolve(asString(args['sessionId']));
+                const frames = StepFramesSchema.parse(args['stepFrames']);
+                const stepped = await deps.pool?.stepLease(session.id, frames);
+                if (stepped === undefined) {
+                    throw new Error(NOT_DETERMINISTIC);
+                }
+                return { frozen: true, ...stepped };
+            }
+            return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
+                freeze: args['freeze'],
+                advanceMs: args['advanceMs'],
+                reset: args['reset'],
+            });
         },
-        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
-            freeze: args['freeze'],
-            advanceMs: args['advanceMs'],
-            reset: args['reset'],
-        }),
     },
     {
         name: ReticleTool.STATE,

package/dist/surface/tools/real-input-attempt.d.ts

@@ -62,13 +62,5 @@ export declare const HOVER_OFF_VIEWPORT_MSG = "cannot hover: the target is outsi
  * or throws.
  */
 export declare function tryRealInput(deps: ToolDeps, session: Session, ref: string, action: ActionType, args: Record<string, unknown>): Promise<RealActResult>;
-/**
- * The session a flow replay runs on, with a press sent to the lease's real keyboard.
- *
- * Replay dispatches its steps itself, not through `reticle_act`, so a recorded Tab replayed as a
- * synthetic keydown that moves no focus, and a keyboard flow that passed live drifted on replay.
- * Every other command, and a press this lease cannot drive for real, goes to the page as before.
- * A Proxy, not a copy: the session keeps private state its own methods read.
- */
 export declare function withLeaseKeyboard(deps: ToolDeps, session: Session): Session;
 export {};

package/dist/surface/tools/real-input-attempt.js

@@ -19,14 +19,15 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, clickInputProblem, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
-import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
+import { ACT_POINT_ARG, ActionType, actPointProblem, boxFractionFromArgs, clickInputProblem, DRAG_TO_POINT_ARG, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { boxPoint, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
 import { assertNativeAllowed } from '../../portal/production/production-drive.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { commandOrThrow } from './tool-kit.js';
 import { asBox } from './act/act-helpers.js';
+import { isStaleRefError } from './act/act-sequence-retry.js';
 import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { RETICLE_CONFIG_BASENAME } from '../../command/cli/ports/resolve/cli-port.js';
@@ -269,6 +270,15 @@ function performArgsOf(inner) {
     if (holdMs !== undefined) {
         performArgs.holdMs = holdMs;
     }
+    // A point inside the target: a canvas has no child elements, so its centre is not enough.
+    const at = boxFractionFromArgs(inner, ACT_POINT_ARG);
+    if (at !== undefined) {
+        performArgs.at = at;
+    }
+    const to = boxFractionFromArgs(inner, DRAG_TO_POINT_ARG);
+    if (to !== undefined) {
+        performArgs.to = to;
+    }
     // `keys` and `code` are read but not forwarded: both are routed away by the caller — a multi-key
     // sequence and an explicit physical code have no driver spelling — so carrying them into the
     // provider would only invite it to guess at a gesture the caller did not ask for.
@@ -284,7 +294,11 @@ const ANCHOR_FIELDS = [
     'name',
     'nth',
     'of',
+    'componentNth',
+    'componentOf',
+    'ownText',
     'secret',
+    'within',
 ];
 /**
  * Press with a leased page's real keyboard, or undefined when this session is not such a lease.
@@ -298,6 +312,31 @@ const ANCHOR_FIELDS = [
  * keeps the in-page press, with the reason: a person's keyboard could not reach it either.
  * ponytail: lease only; the drive provider keeps its documented element-press rule.
  */
+/**
+ * Put focus on a press's target, as a person does before they press a key in a field.
+ *
+ * A real keyboard cannot aim at an element, but focus can: focus the element, confirm it holds
+ * focus, and the real key then lands there, with every default action a browser gives a trusted
+ * key (an Enter in a text field submits its form). Returns what the focused element is called, so
+ * the saved step can find it again (the real keyboard reports no element of its own), or
+ * `undefined` when the element did not take focus. No ref: nothing to focus, nothing to name.
+ */
+async function focusForPress(deps, session, ref) {
+    if (0 === ref.length) {
+        return {};
+    }
+    const focus = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.ACT, {
+        ref,
+        action: ActionType.FOCUS,
+        args: {},
+    }));
+    const inspected = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref }));
+    const states = Array.isArray(inspected['states']) ? inspected['states'] : [];
+    if (!states.includes(ElementState.FOCUSED)) {
+        return undefined;
+    }
+    return Object.fromEntries(ANCHOR_FIELDS.flatMap((k) => (k in focus ? [[k, focus[k]]] : [])));
+}
 async function pressOnLease(deps, session, ref, inner) {
     const pool = deps.pool;
     if (pool === undefined || !pool.hasKeyboard(session.id)) {
@@ -307,21 +346,9 @@ async function pressOnLease(deps, session, ref, inner) {
     if (unspellable !== undefined) {
         return synthetic(unspellable);
     }
-    // What the focused element is called, from the focus act's own report, so the saved step can
-    // find it again: the real keyboard reports no element of its own.
-    let anchor = {};
-    if (0 < ref.length) {
-        const focus = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.ACT, {
-            ref,
-            action: ActionType.FOCUS,
-            args: {},
-        }));
-        anchor = Object.fromEntries(ANCHOR_FIELDS.flatMap((k) => (k in focus ? [[k, focus[k]]] : [])));
-        const inspected = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref }));
-        const states = Array.isArray(inspected['states']) ? inspected['states'] : [];
-        if (!states.includes(ElementState.FOCUSED)) {
-            return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
-        }
+    const anchor = await focusForPress(deps, session, ref);
+    if (anchor === undefined) {
+        return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
     }
     const performed = await pool.pressLease(session.id, performArgsOf(inner));
     if (performed?.performed !== true) {
@@ -403,20 +430,21 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (!inView) {
         throw new Error(HOVER_OFF_VIEWPORT_MSG);
     }
+    const at = boxFractionFromArgs(inner, ACT_POINT_ARG);
     if (providerReady && provider !== undefined) {
         try {
-            const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
+            const performed = await provider.perform(session.url, ActionType.HOVER, box, at === undefined ? {} : { at });
             // Hover always has a resolved box, so there is always a center to report: the provider's own
             // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
             if (performed.performed) {
-                return hoverSucceeded(performed.center ?? boxCenter(box), scrolled);
+                return hoverSucceeded(performed.center ?? boxPoint(box, at), scrolled);
             }
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
         }
     }
-    const { cx, cy } = boxCenter(box);
+    const { cx, cy } = boxPoint(box, at);
     if (true === (await deps.pool?.hoverLease(session.id, cx, cy))) {
         return hoverSucceeded({ cx, cy }, scrolled);
     }
@@ -436,6 +464,11 @@ export async function tryRealInput(deps, session, ref, action, args) {
     const provider = deps.realInput;
     const inner = asRecord(args['args']);
     const askedForNative = true === inner[NATIVE_INPUT_ARG];
+    // The page refuses the same point on the synthetic path, with the same sentence.
+    const pointProblem = actPointProblem(action, inner);
+    if (pointProblem !== undefined) {
+        throw new Error(`cannot ${action}: ${pointProblem}`);
+    }
     if (action === ActionType.HOVER) {
         return hoverForReal(deps, session, ref, inner, provider);
     }
@@ -460,8 +493,10 @@ export async function tryRealInput(deps, session, ref, action, args) {
     }
     // Two `press`es this module will NOT drive, and neither is a fallback — the reason says which
     // one was asked for, instead of a different gesture being sent. See `unspellablePressReason`.
+    // A press aimed at an element is focused first (focusForPress), as on a lease; only a chord and
+    // an explicit key code stay in the page.
     if (action === ActionType.PRESS) {
-        const unspellable = unspellablePressReason(ref, inner);
+        const unspellable = unspellablePressReason('', inner);
         if (unspellable !== undefined) {
             return synthetic(unspellable);
         }
@@ -500,8 +535,12 @@ export async function tryRealInput(deps, session, ref, action, args) {
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
     }
     const performArgs = performArgsOf(inner);
-    // A document key has no element of its own: skip INSPECT and the box entirely.
+    // A key addresses focus, not a point: focus the target (if any), then skip INSPECT and the box.
     if (action === ActionType.PRESS) {
+        const anchor = await focusForPress(deps, session, ref);
+        if (anchor === undefined) {
+            return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
+        }
         try {
             const performed = await provider.perform(session.url, action, PRESS_HAS_NO_BOX, performArgs);
             if (!performed.performed) {
@@ -516,6 +555,7 @@ export async function tryRealInput(deps, session, ref, action, args) {
             // `holdMs` to — an agent checking for an armed hold-to-confirm control read `undefined`.
             return {
                 result: {
+                    ...anchor,
                     performed: true,
                     action,
                     inputMode: performed.inputMode,
@@ -557,8 +597,12 @@ export async function tryRealInput(deps, session, ref, action, args) {
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
     }
     let toBox;
-    if (action === ActionType.DRAG) {
-        const toRef = asString(inner['toRef']);
+    const toRef = asString(inner['toRef']);
+    // A drag that names only its end point moves inside the source, such as a stroke on one canvas.
+    if (action === ActionType.DRAG && toRef === undefined && performArgs.to !== undefined) {
+        toBox = box;
+    }
+    else if (action === ActionType.DRAG) {
         if (toRef === undefined) {
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
         }
@@ -614,18 +658,89 @@ export async function tryRealInput(deps, session, ref, action, args) {
     }
 }
 /**
- * The session a flow replay runs on, with a press sent to the lease's real keyboard.
+ * The session a flow replay runs on, with a press sent to the real keyboard, as `reticle_act` does.
  *
  * Replay dispatches its steps itself, not through `reticle_act`, so a recorded Tab replayed as a
  * synthetic keydown that moves no focus, and a keyboard flow that passed live drifted on replay.
- * Every other command, and a press this lease cannot drive for real, goes to the page as before.
- * A Proxy, not a copy: the session keeps private state its own methods read.
+ * The real keyboard is a lease's, or the driven browser's when a real-input provider is configured:
+ * that is `reticle verify`'s own page, where a synthetic Enter submitted no form, so a recorded
+ * "fill, press Enter" journey failed on a working app. Every other command, and a press that cannot
+ * be driven for real, goes to the page as before. A Proxy, not a copy: the session keeps private
+ * state its own methods read.
+ */
+/**
+ * A sequence with a press in it, run as the page and the keyboard would run it.
+ *
+ * Replay sends a recorded sequence as one in-page command, so a press inside it stayed a synthetic
+ * key event: a recorded "fill, press Enter" sequence submitted no form and failed on a working app.
+ * The other sub-steps still go to the page together, in order; each press goes to the real keyboard
+ * (focus, then the key), and to the page as before when the real keyboard cannot take it. The
+ * first failure is returned as the page returned it, so a stale-ref retry still finds its step.
  */
+async function sequenceWithRealPresses(deps, session, steps, timeoutMs) {
+    const share = (n) => timeoutMs === undefined ? undefined : Math.ceil((timeoutMs * n) / Math.max(1, steps.length));
+    let last = {
+        kind: 'command_result',
+        id: ReticleCommand.ACT_SEQUENCE,
+        ok: true,
+        result: {},
+    };
+    let chunk = [];
+    const flush = async () => {
+        if (0 === chunk.length) {
+            return true;
+        }
+        last = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: chunk }, share(chunk.length));
+        chunk = [];
+        return last.ok;
+    };
+    for (const sub of steps) {
+        const step = asRecord(sub);
+        if (ActionType.PRESS !== step['action']) {
+            chunk.push(sub);
+            continue;
+        }
+        if (!(await flush())) {
+            return last;
+        }
+        // A click before this press can load a new page, and then the press's ref is stale. Answered as
+        // the page answers a stale ref, so the caller's retry finds the press again on the new page.
+        let real;
+        try {
+            real = await tryRealInput(deps, session, asString(step['ref']) ?? '', ActionType.PRESS, step);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!isStaleRefError(message)) {
+                throw error;
+            }
+            return { kind: 'command_result', id: ActionType.PRESS, ok: false, error: message };
+        }
+        if (real.result === undefined) {
+            chunk.push(sub);
+            continue;
+        }
+        last = {
+            kind: 'command_result',
+            id: ActionType.PRESS,
+            ok: true,
+            result: { dispatched: true, settled: real.settled, ...asRecord(real.result) },
+        };
+    }
+    await flush();
+    return last;
+}
 export function withLeaseKeyboard(deps, session) {
-    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true) {
+    if (deps.realInput === undefined && deps.pool?.hasKeyboard(session.id) !== true) {
         return session;
     }
     const command = async (name, args = {}, timeoutMs) => {
+        const steps = args['steps'];
+        if (ReticleCommand.ACT_SEQUENCE === name &&
+            Array.isArray(steps) &&
+            steps.some((sub) => ActionType.PRESS === asRecord(sub)['action'])) {
+            return await sequenceWithRealPresses(deps, session, steps, timeoutMs);
+        }
         if (ReticleCommand.ACT === name && ActionType.PRESS === args['action']) {
             const ref = asString(args['ref']) ?? '';
             const real = await tryRealInput(deps, session, ref, ActionType.PRESS, args);