@reticlehq/server 3.9.0 → 3.10.1

package/dist/language/flows/recording/tape/recordings.js

@@ -28,6 +28,16 @@ export const AMBIENT_RECORDING = '__ambient__';
 export const ambientRecordingOf = (session) => session === undefined ? AMBIENT_RECORDING : `${AMBIENT_RECORDING}:${session}`;
 /** Whether a recording is an ambient tape: the daemon's own, never one somebody opened. */
 export const isAmbient = (name) => AMBIENT_RECORDING === name || name.startsWith(`${AMBIENT_RECORDING}:`);
+/**
+ * Whether a step, or one of its sub-steps, declared a consequence.
+ * ponytail: the same test as `carriesAnAssertion` in memory/journal/drive-flow.ts, which this
+ * directory may not import. Move both into core if a third caller needs it.
+ */
+const isChecked = (step) => {
+    const subs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
+    return (step.expect !== undefined ||
+        subs.some((sub) => 'object' === typeof sub && null !== sub && 'expect' in sub));
+};
 /**
  * How long a journey the ambient tape will hold.
  *
@@ -36,17 +46,43 @@ export const isAmbient = (name) => AMBIENT_RECORDING === name || name.startsWith
  * 400-step regression test: the longest saved flow in the corpus is a small fraction of this.
  */
 const AMBIENT_STEP_CAP = 400;
+/** How many ended pages keep their unchecked steps for a successor. See takeAmbient. */
+const CARRY_CAP = 32;
 export class RecordingStore {
     byHarness;
+    successorOf;
     #active = new Map();
     #compiled = new Map();
     /** A navigation came after the last captured step — see markNavigated. */
     #navigatedSinceStep = false;
     /** Tabs with network mocks installed now, keyed by session ('' for none named). See markMocked. */
     #mocked = new Set();
-    /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
-    constructor(byHarness = () => false) {
+    /**
+     * Steps a tab took after its last check, kept when the APP loaded a new page, by the session that
+     * ended. The page that loaded takes them when its own tape opens. See takeAmbient.
+     */
+    #carried = new Map();
+    /**
+     * `byHarness`: whether the step being captured was driven by the Harness, which tapes its own.
+     * `successorOf`: the session that the same tab connected as after a page load, if any.
+     */
+    constructor(byHarness = () => false, successorOf = () => undefined) {
         this.byHarness = byHarness;
+        this.successorOf = successorOf;
+    }
+    /** The carried steps that this session continues, taken. */
+    #takeCarried(session) {
+        if (session === undefined) {
+            return [];
+        }
+        for (const [ended, steps] of this.#carried) {
+            // A leased tab comes back from a page load with its own id; any other tab with a new one.
+            if (ended === session || this.successorOf(ended) === session) {
+                this.#carried.delete(ended);
+                return steps;
+            }
+        }
+        return [];
     }
     start(name, cursor, startPath, session, document) {
         const openedOver = new Map();
@@ -114,7 +150,7 @@ export class RecordingStore {
         if (!this.#active.has(ambient)) {
             this.#active.set(ambient, {
                 cursor: 0,
-                steps: [],
+                steps: this.#takeCarried(session),
                 openedOver: new Map(),
                 ...(session === undefined ? {} : { session }),
             });
@@ -265,9 +301,39 @@ export class RecordingStore {
         // One tab's tape is that tab's: the list names what somebody opened, and the plain tape as before.
         return [...this.#active.keys()].filter((name) => !name.startsWith(`${AMBIENT_RECORDING}:`));
     }
-    /** The ambient tape of one tab (or of steps no tab named), taken: what its session end saves. */
+    /**
+     * The ambient tape of one tab (or of steps no tab named), taken: what its session end saves.
+     *
+     * A session also ends when the app itself loads a page (a form post on a server-rendered app), and
+     * the journey goes on in the page that loaded. A tape with no check is not saved, so the next
+     * page's tape starts with a copy of it: a fill and the submit that proves it are then one flow, not
+     * a fill that is dropped and a submit on an empty form. When Reticle navigated away, the agent
+     * started a new journey, and nothing is carried.
+     * ponytail: only a tape with NO check is carried; unchecked steps after a check stay behind.
+     * ponytail: kept for the last CARRY_CAP ended pages; a tab that never loads a successor drops them.
+     */
     takeAmbient(session) {
-        return this.stop(ambientRecordingOf(session));
+        const tape = this.stop(ambientRecordingOf(session));
+        const unchecked = tape !== undefined && !tape.steps.some(isChecked);
+        if (tape === undefined || session === undefined || this.#navigatedSinceStep || !unchecked) {
+            return tape;
+        }
+        // The next page may already have a tape: its step was recorded before this session ended.
+        const next = this.successorOf(session);
+        const nextTape = next === undefined ? undefined : this.#active.get(ambientRecordingOf(next));
+        if (nextTape !== undefined) {
+            nextTape.steps.unshift(...tape.steps);
+            return tape;
+        }
+        this.#carried.set(session, [...tape.steps]);
+        while (this.#carried.size > CARRY_CAP) {
+            const oldest = this.#carried.keys().next().value;
+            if (oldest === undefined) {
+                break;
+            }
+            this.#carried.delete(oldest);
+        }
+        return tape;
     }
     /**
      * Names of recordings that have been STOPPED and compiled.

package/dist/language/flows/replay.d.ts

@@ -1,4 +1,4 @@
-import { pathOf, type Predicate, type ReticleEvent } from '@reticlehq/core';
+import { type Predicate, type ReticleEvent } from '@reticlehq/core';
 import { type CommandResult } from '@reticlehq/core';
 import type { RecordedStep, CompiledProgram } from './recording/tape/recordings.js';
 import type { Session } from '../../portal/session/session.js';
@@ -13,6 +13,15 @@ export declare function ambiguousTestidNote(value: string): string;
  * replay engines (replayProgram + flow-replay's step runner) so element extraction — the core of anchor
  * resolution — can't drift between them.
  */
+/**
+ * The refs of a role query's matches that have NO accessible name, in page order.
+ *
+ * A role query without a name returns every control of the role, named ones included. A nameless
+ * anchor's recorded position (`nth` of `of`) counts only the nameless ones — an icon-only edit
+ * button is the 2nd nameless button of its row, not the 5th button — so the named ones are dropped
+ * before the position is read.
+ */
+export declare function namelessRefs(result: CommandResult): string[];
 export declare function queryRefs(result: CommandResult): string[];
 /**
  * A destructive-action confirmation is one-shot and must never persist into a recording.
@@ -29,12 +38,16 @@ export declare function queryRefs(result: CommandResult): string[];
  */
 export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean, field?: string): Record<string, unknown>;
 /**
- * The pathname of a session's live url, or undefined when it has none yet.
+ * The page a session's live url is on, as a NAVIGABLE path: pathname + query + hash, with
+ * Reticle's own params dropped. Undefined when the session has no url yet.
  *
- * Pathname rather than the whole url, because that is what `startPath` is compared against and what
- * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ * Every recorded page comes from here: a step's page, the route a tape is cut on, and the
+ * `startPath` and route `requires` of a saved flow. The pathname alone dropped the query, so a
+ * journey leased on `/?showModal=login` saved `startPath: "/"`, and its replay asserted "the modal
+ * is absent" on a page where the modal never opens. Under a hash router it dropped the hash too,
+ * which made every page `/` (#1411).
  */
-export { pathOf };
+export declare function pageOf(url: string | undefined): string | undefined;
 /**
  * Did the app send a write request in this window? A step that did is saved `writes: true`, so a
  * replay does not repeat it unasked. The dev server's own traffic is not the app's.
@@ -134,3 +147,4 @@ via?: readonly {
     flow: string;
     step: number;
 }[]): Promise<ReplayStepResult[]>;
+export {};

package/dist/language/flows/replay.js

@@ -1,9 +1,10 @@
 import { SECRET_FIELD_ARG, SECRET_NAME_ARG, secretKeyForFill, secretValue, } from './fields/flow-secret-field.js';
-import { EventType, FlowPredicateSchema, MUTATING_METHODS, isDevToolingUrl, pathOf, } from '@reticlehq/core';
+import { EventType, FlowPredicateSchema, MUTATING_METHODS, isDevToolingUrl, } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, DOCUMENT_ANCHOR_ROLE, ReticleCommand, QueryBy, isGlobalPressCall, } from '@reticlehq/core';
 import { ReticleTool, invokedFlowMissing } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
 import { refFor } from './flow-anchor.js';
+import { navigablePath, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -21,6 +22,32 @@ function ambiguousRoleNote(role, name) {
  * replay engines (replayProgram + flow-replay's step runner) so element extraction — the core of anchor
  * resolution — can't drift between them.
  */
+/**
+ * The refs of a role query's matches that have NO accessible name, in page order.
+ *
+ * A role query without a name returns every control of the role, named ones included. A nameless
+ * anchor's recorded position (`nth` of `of`) counts only the nameless ones — an icon-only edit
+ * button is the 2nd nameless button of its row, not the 5th button — so the named ones are dropped
+ * before the position is read.
+ */
+export function namelessRefs(result) {
+    if (!result.ok) {
+        return [];
+    }
+    const elements = asRecord(result.result)['elements'];
+    if (!Array.isArray(elements)) {
+        return [];
+    }
+    const refs = [];
+    for (const element of elements) {
+        const e = asRecord(element);
+        const ref = asString(e['ref']);
+        if (0 === (asString(e['name']) ?? '').trim().length && ref !== undefined) {
+            refs.push(ref);
+        }
+    }
+    return refs;
+}
 export function queryRefs(result) {
     if (!result.ok) {
         return [];
@@ -86,12 +113,22 @@ function sourceFromResult(res) {
     return out;
 }
 /**
- * The pathname of a session's live url, or undefined when it has none yet.
+ * The page a session's live url is on, as a NAVIGABLE path: pathname + query + hash, with
+ * Reticle's own params dropped. Undefined when the session has no url yet.
  *
- * Pathname rather than the whole url, because that is what `startPath` is compared against and what
- * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ * Every recorded page comes from here: a step's page, the route a tape is cut on, and the
+ * `startPath` and route `requires` of a saved flow. The pathname alone dropped the query, so a
+ * journey leased on `/?showModal=login` saved `startPath: "/"`, and its replay asserted "the modal
+ * is absent" on a page where the modal never opens. Under a hash router it dropped the hash too,
+ * which made every page `/` (#1411).
  */
-export { pathOf };
+export function pageOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    const parts = routeOfUrl(url);
+    return parts === undefined ? undefined : navigablePath(parts);
+}
 /**
  * Did the app send a write request in this window? A step that did is saved `writes: true`, so a
  * replay does not repeat it unasked. The dev server's own traffic is not the app's.
@@ -300,6 +337,9 @@ function anchorArgs(r, ref, action, actArgs) {
         }
         if (testidOf !== undefined) {
             testidArgs['of'] = testidOf;
+            if ('number' === typeof r['testidNth'] && 0 <= r['testidNth']) {
+                testidArgs['nth'] = r['testidNth'];
+            }
         }
         return { args: testidArgs, stable: true };
     }
@@ -324,8 +364,33 @@ function anchorArgs(r, ref, action, actArgs) {
             roleArgs['nth'] = r['nth'];
             roleArgs['of'] = r['of'];
         }
+        if (Array.isArray(r['within'])) {
+            roleArgs['within'] = r['within'];
+        }
         return { args: roleArgs, stable: true };
     }
+    // A role and NO accessible name (an icon-only button): the role plus the control's position among
+    // the nameless controls of that role. Without this branch the step fell to a component anchor or
+    // to the stale ref, and a replay on a fresh page could not find the control again.
+    if (role !== undefined &&
+        role !== 'generic' &&
+        name === undefined &&
+        asString(r['component']) === undefined) {
+        const namelessArgs = {
+            by: QueryBy.ROLE,
+            value: role,
+            action,
+            args: actArgs,
+        };
+        if (source !== undefined) {
+            namelessArgs['source'] = source;
+        }
+        if ('number' === typeof r['nth'] && 'number' === typeof r['of']) {
+            namelessArgs['nth'] = r['nth'];
+            namelessArgs['of'] = r['of'];
+        }
+        return { args: namelessArgs, stable: true };
+    }
     const component = asString(r['component']);
     if (component !== undefined || source !== undefined) {
         const componentArgs = { by: QueryBy.COMPONENT, action, args: actArgs };
@@ -335,6 +400,21 @@ function anchorArgs(r, ref, action, actArgs) {
         if (source !== undefined) {
             componentArgs['source'] = source;
         }
+        // Which of the elements this anchor matches was acted on: a list renders every item from one site.
+        // The element's own words, when it has no accessible name: they survive a change of layout.
+        const ownText = asString(r['ownText']);
+        if (ownText !== undefined && ownText.length > 0) {
+            componentArgs['text'] = ownText;
+        }
+        // The role, too: a nameless control with no own words has no other identity a layout keeps.
+        const role = asString(r['role']);
+        if (role !== undefined && role.length > 0) {
+            componentArgs['role'] = role;
+        }
+        if ('number' === typeof r['componentNth'] && 'number' === typeof r['componentOf']) {
+            componentArgs['nth'] = r['componentNth'];
+            componentArgs['of'] = r['componentOf'];
+        }
         return { args: componentArgs, stable: true };
     }
     return { args: { ref, action, args: actArgs }, stable: false };
@@ -350,6 +430,8 @@ export function compileSequenceStep(args, res) {
         ? asRecord(res)['steps']
         : [];
     let stable = inputSteps.length > 0;
+    // A declared `expect` that a flow cannot keep (a session ref), said on save as for a single act (#2188).
+    let unkept = false;
     const subSteps = inputSteps.flatMap((raw, i) => {
         // A step on Reticle's own panel is not a step of the app's journey, as for a single act.
         if (true === asRecord(resolved[i])['reticleUi']) {
@@ -364,14 +446,22 @@ export function compileSequenceStep(args, res) {
         // one batch, but what each step CLAIMED is per step -- folding them together would let one
         // signal answer for every click in the journey.
         const expect = enforceableExpect(step['expect']);
+        if (expect === undefined && step['expect'] !== undefined) {
+            unkept = true;
+        }
         return [expect === undefined ? compiled.args : { ...compiled.args, expect }];
     });
     const timeoutMs = explicitTimeoutMs(args);
+    // The pace is part of what the sequence did: replay at the default settle answered differently (#2130).
+    const burst = args['burst'];
+    const burstMs = 'number' === typeof burst && Number.isFinite(burst) && 0 <= burst ? burst : undefined;
     return {
         tool: ReticleTool.ACT_SEQUENCE,
         stable,
         args: { steps: subSteps },
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(burstMs === undefined ? {} : { burstMs }),
+        ...(unkept ? { unkeptExpect: UNKEPT_EXPECT } : {}),
     };
 }
 /**
@@ -412,11 +502,13 @@ async function resolveRef(session, step) {
         if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
         }
-        const refs = queryRefs(result);
+        const refs = name === undefined ? namelessRefs(result) : queryRefs(result);
         const meant = refFor(step, refs);
         const ref = meant ?? refs[0];
         if (ref === undefined) {
-            throw new Error(`${value} named '${String(name)}' did not resolve in current page`);
+            throw new Error(name === undefined
+                ? `no ${value} with no accessible name resolved in current page`
+                : `${value} named '${String(name)}' did not resolve in current page`);
         }
         return meant === undefined ? { ref, note: ambiguousRoleNote(value, String(name)) } : { ref };
     }

package/dist/language/flows/steps/page-steps.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Steps that reach past the page the journey is on: one opens another page (`navigate`), one sends a
+ * request to the app (`request`). Neither acts on an element, and both depend on a caller that owns
+ * what the replay cannot reach by itself: the sessions, the origin, the cookies.
+ */
+import { type Drift, type FlowRequest, type FlowStep, type FlowStepResult } from '@reticlehq/core';
+/**
+ * Opens the page a `navigate` step names and returns the session of the page that loaded, or why no
+ * page of the app answered. A full page load ends the session that asked for it, so only the caller
+ * that owns the sessions can do this.
+ */
+export type OpenPage<S> = (url: string) => Promise<{
+    session: S;
+} | {
+    error: string;
+}>;
+/**
+ * Sends the request a `request` step names and returns the answer, or why nothing could be sent.
+ * Supplied by the caller that knows the app's origin and the page's cookies.
+ */
+export type SendRequest = (request: FlowRequest) => Promise<{
+    status: number;
+    body: string;
+} | {
+    error: string;
+}>;
+/** Where the page's cookies come from: the driven browser's storage state. */
+interface CookieSource {
+    storageState?(sessionUrl: string): Promise<unknown>;
+}
+/** The step's result before its `expect` is judged, and the session to go on with. */
+export declare function openStepPage<S>(step: FlowStep, index: number, open: OpenPage<S> | undefined): Promise<{
+    result: FlowStepResult;
+    session?: S;
+}>;
+export declare function runRequestStep(step: FlowStep, index: number, send: SendRequest | undefined, judged: boolean, 
+/**
+ * The run's own yes to steps that change data, never the flow file's: flow files are shared, and a
+ * saved `DELETE` would otherwise run with the user's cookies on any app the flow is pointed at.
+ */
+confirmDangerous: boolean): Promise<FlowStepResult>;
+/** True for a step that reaches past the page: `navigate` or `request`. */
+export declare function isPageStep(step: FlowStep): boolean;
+/**
+ * Run a `navigate` or `request` step. `judge` evaluates an `expect` on a page; it comes from the
+ * replay so this file does not import the replay back. `checked` is false for a setup step, whose
+ * consequence is not checked. A navigate step returns the session to go on with.
+ */
+export declare function runPageStep<S>(step: FlowStep, index: number, ctx: {
+    open?: OpenPage<S> | undefined;
+    send?: SendRequest | undefined;
+    checked: boolean;
+    confirmDangerous: boolean;
+    judge: (session: S, expect: NonNullable<FlowStep['expect']>) => Promise<Drift | undefined>;
+    route: (session: S) => string | undefined;
+}): Promise<{
+    result: FlowStepResult;
+    session?: S;
+}>;
+/**
+ * The sender a `request` step uses: same origin as the page only, the page's cookies unless the step
+ * is anonymous, no redirects followed (a 302 is the answer to judge). `pageUrl` is read at send time,
+ * because a `navigate` step changes the page.
+ */
+export declare function requestSender(pageUrl: () => string | undefined, provider: CookieSource | undefined, 
+/** The `Cookie` header of the account a step names in `as`, or undefined when not supplied. */
+accountCookie?: (name: string) => string | undefined): SendRequest;
+export {};

package/dist/language/flows/steps/page-steps.js

@@ -0,0 +1,198 @@
+/**
+ * Steps that reach past the page the journey is on: one opens another page (`navigate`), one sends a
+ * request to the app (`request`). Neither acts on an element, and both depend on a caller that owns
+ * what the replay cannot reach by itself: the sessions, the origin, the cookies.
+ */
+import { FlowStepTool, } from '@reticlehq/core';
+/*
+ * A step that opens a page in the middle of a journey. The replay goes on with the page that loaded,
+ * and the step's `expect` is judged there (see `OpenPage`).
+ */
+/** The step's result before its `expect` is judged, and the session to go on with. */
+export async function openStepPage(step, index, open) {
+    const url = step.navigate ?? '';
+    const base = { step: index, tool: FlowStepTool.NAVIGATE, anchor: url };
+    // Never skipped: a journey that reports green without the page it was meant to check is a false
+    // green arriving through the step meant to make the check stronger.
+    if (open === undefined) {
+        return {
+            result: {
+                ...base,
+                ok: false,
+                error: `this replay cannot open a page, so the step that opens ${url} did not run`,
+            },
+        };
+    }
+    const opened = await open(url);
+    if ('error' in opened) {
+        return { result: { ...base, ok: false, error: opened.error } };
+    }
+    return { result: { ...base, ok: true }, session: opened.session };
+}
+/** Why an answer does not match the step's `response`, or undefined when it does. */
+function responseMismatch(response, answer) {
+    const statuses = response.status === undefined ? [] : [response.status].flat();
+    if (statuses.length > 0 && !statuses.includes(answer.status)) {
+        return `the answer was ${String(answer.status)}, expected ${statuses.join(' or ')}`;
+    }
+    if (response.contains !== undefined && !answer.body.includes(response.contains)) {
+        return `the answer (${String(answer.status)}) does not contain "${response.contains}"`;
+    }
+    if (response.absent !== undefined && answer.body.includes(response.absent)) {
+        return `the answer (${String(answer.status)}) contains "${response.absent}", which it must not`;
+    }
+    return undefined;
+}
+/*
+ * A step that sends one request and judges the answer. It never skips: a rule the flow says it
+ * checks and did not is a false green.
+ */
+/** Methods that only read. Any other method changes data and needs the run's confirmation. */
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+export async function runRequestStep(step, index, send, judged, 
+/**
+ * The run's own yes to steps that change data, never the flow file's: flow files are shared, and a
+ * saved `DELETE` would otherwise run with the user's cookies on any app the flow is pointed at.
+ */
+confirmDangerous) {
+    const request = step.request;
+    const label = request === undefined ? '' : `${request.method} ${request.url}`;
+    const base = { step: index, tool: FlowStepTool.REQUEST, anchor: label };
+    if (request === undefined || send === undefined) {
+        return {
+            ...base,
+            ok: false,
+            error: `this replay cannot send a request, so ${label} did not run`,
+        };
+    }
+    if (!READ_METHODS.has(request.method.toUpperCase()) && !confirmDangerous) {
+        return {
+            ...base,
+            ok: false,
+            error: `potentially destructive request blocked: ${label} changes data, so it was not sent. ` +
+                'Confirm it for this run: reticle_verify{action:"flows", confirmDangerous: true}, or ' +
+                '`reticle verify <url> --confirm-dangerous`. It cannot be confirmed in the flow file.',
+        };
+    }
+    const answer = await send(request);
+    if ('error' in answer) {
+        return { ...base, ok: false, error: answer.error };
+    }
+    const mismatch = !judged || step.response === undefined ? undefined : responseMismatch(step.response, answer);
+    return mismatch === undefined ? { ...base, ok: true } : { ...base, ok: false, error: mismatch };
+}
+/** True for a step that reaches past the page: `navigate` or `request`. */
+export function isPageStep(step) {
+    return step.navigate !== undefined || step.request !== undefined;
+}
+/**
+ * Run a `navigate` or `request` step. `judge` evaluates an `expect` on a page; it comes from the
+ * replay so this file does not import the replay back. `checked` is false for a setup step, whose
+ * consequence is not checked. A navigate step returns the session to go on with.
+ */
+export async function runPageStep(step, index, ctx) {
+    if (step.request !== undefined) {
+        return {
+            result: await runRequestStep(step, index, ctx.send, ctx.checked, ctx.confirmDangerous),
+        };
+    }
+    const opened = await openStepPage(step, index, ctx.open);
+    if (opened.session === undefined) {
+        return opened;
+    }
+    const result = opened.result;
+    const page = ctx.route(opened.session);
+    if (page !== undefined) {
+        result.page = page;
+    }
+    const drift = step.expect === undefined || !ctx.checked
+        ? undefined
+        : await ctx.judge(opened.session, step.expect);
+    if (drift !== undefined) {
+        result.ok = false;
+        result.drift = drift;
+    }
+    return { result, session: opened.session };
+}
+/** How long a `request` step waits for the answer. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/** The `Cookie` header the page would send to `host`, from the driven browser's storage state. */
+function cookieHeader(state, host) {
+    const cookies = state?.cookies;
+    if (!Array.isArray(cookies)) {
+        return '';
+    }
+    return cookies
+        .filter((c) => {
+        const domain = c.domain;
+        if (typeof domain !== 'string') {
+            return false;
+        }
+        const bare = domain.replace(/^\./, '');
+        return host === bare || host.endsWith(`.${bare}`);
+    })
+        .map((c) => `${c.name}=${c.value}`)
+        .join('; ');
+}
+/**
+ * The sender a `request` step uses: same origin as the page only, the page's cookies unless the step
+ * is anonymous, no redirects followed (a 302 is the answer to judge). `pageUrl` is read at send time,
+ * because a `navigate` step changes the page.
+ */
+export function requestSender(pageUrl, provider, 
+/** The `Cookie` header of the account a step names in `as`, or undefined when not supplied. */
+accountCookie = () => undefined) {
+    return async (request) => {
+        const url = pageUrl();
+        if (url === undefined) {
+            return { error: 'the page has no known address, so the request has nowhere to go' };
+        }
+        const origin = new URL(url).origin;
+        const target = new URL(request.url, origin);
+        if (target.origin !== origin) {
+            return {
+                error: `${request.url} is not on the app's origin ${origin}; a flow sends requests only to its app`,
+            };
+        }
+        const headers = {};
+        if (request.body !== undefined) {
+            headers['content-type'] = request.contentType ?? 'application/json';
+        }
+        if (request.as !== undefined) {
+            const cookie = accountCookie(request.as);
+            if (cookie === undefined || '' === cookie) {
+                return {
+                    error: `the session of the account "${request.as}" was not supplied, so the request was not ` +
+                        'sent. Supply its Cookie header as a secret for this run.',
+                };
+            }
+            headers['cookie'] = cookie;
+        }
+        else if (true !== request.anonymous) {
+            const state = await provider?.storageState?.(url);
+            if (state === undefined) {
+                return {
+                    error: 'the page cookies cannot be read here (this is not a driven browser), so the request ' +
+                        'cannot go as the signed-in user. Mark it `anonymous`, or replay with `reticle verify`.',
+                };
+            }
+            const cookie = cookieHeader(state, target.hostname);
+            if (cookie !== '') {
+                headers['cookie'] = cookie;
+            }
+        }
+        try {
+            const answer = await fetch(target, {
+                method: request.method,
+                headers,
+                ...(request.body === undefined ? {} : { body: request.body }),
+                redirect: 'manual',
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return { status: answer.status, body: await answer.text() };
+        }
+        catch (error) {
+            return { error: `the request ${request.method} ${target.pathname} failed: ${String(error)}` };
+        }
+    };
+}