screencast-axi 0.1.0

package/dist/src/config.d.ts

@@ -0,0 +1,126 @@
+import { type EncodeSettings } from "./encode.js";
+import { type DeepPartial, type OverlayTheme } from "./overlay.js";
+import { type DefinedScenario, type Viewport } from "./types.js";
+import type { AuthConfig, AuthStrategy } from "./auth/types.js";
+/**
+ * Configuration, and finding the scenarios.
+ *
+ * A config file is the scale-up path, not the entry fee: `record ./clip.ts`
+ * works with no config at all, on defaults rooted at the current directory.
+ * Someone recording one page of a site they do not own should not have to
+ * learn a config format first.
+ */
+export interface BrowserConfig {
+    readonly headless: boolean;
+    /**
+     * Persistent Chrome profile directory.
+     *
+     * Present means a warm profile, so a session a human signed into by hand
+     * survives between takes. Absent means an isolated context per take.
+     */
+    readonly profileDir?: string;
+    /** Overrides a device preset's own scale factor. Rarely wanted. */
+    readonly deviceScaleFactor?: number;
+    readonly args: readonly string[];
+    readonly colorScheme?: "light" | "dark";
+    readonly locale?: string;
+    readonly timezoneId?: string;
+}
+export interface ScreencastConfig {
+    readonly outDir?: string;
+    readonly rawDir?: string;
+    /** File paths, directories, or `dir/*.ts` patterns. */
+    readonly scenarios?: readonly string[];
+    readonly baseUrl?: string;
+    readonly viewport?: Viewport;
+    readonly device?: string;
+    readonly pace?: number;
+    readonly deliverables?: Partial<EncodeSettings>;
+    readonly browser?: Partial<BrowserConfig>;
+    readonly overlay?: DeepPartial<OverlayTheme>;
+    /** One strategy, or several by name for `--auth <name>`. */
+    readonly auth?: AuthConfig;
+    readonly timeouts?: {
+        readonly setupMs?: number;
+        readonly runMs?: number;
+        /** Per-action timeout during a rehearsal. Deliberately short. */
+        readonly rehearseMs?: number;
+        /** Ceiling on how long `goto` waits for the network to go quiet. */
+        readonly settleMs?: number;
+    };
+}
+export interface ResolvedConfig {
+    /** Directory every relative path in the config resolves against. */
+    readonly rootDir: string;
+    /** Absolute path of the config file, or null when running without one. */
+    readonly configPath: string | null;
+    readonly outDir: string;
+    readonly rawDir: string;
+    readonly scenarios: readonly string[];
+    readonly baseUrl: string;
+    readonly viewport: Viewport;
+    readonly device?: string;
+    readonly pace: number;
+    readonly deliverables: EncodeSettings;
+    readonly browser: BrowserConfig;
+    readonly overlay: DeepPartial<OverlayTheme>;
+    readonly auth: Readonly<Record<string, AuthStrategy>>;
+    readonly timeouts: {
+        readonly setupMs: number;
+        readonly runMs: number;
+        readonly rehearseMs: number;
+        readonly settleMs: number;
+    };
+}
+export declare const CONFIG_BASENAMES: readonly ["screencast.config.ts", "screencast.config.mts", "screencast.config.js", "screencast.config.mjs"];
+/**
+ * Chromium flags that make a capture look deliberate rather than incidental:
+ * no scrollbars in frame, sRGB so colours match the design, and no font
+ * hinting so text renders the same on every machine that reshoots.
+ */
+export declare const DEFAULT_BROWSER_ARGS: readonly ["--hide-scrollbars", "--force-color-profile=srgb", "--font-render-hinting=none"];
+/** Identity function, for the types and the editor completion. */
+export declare function defineConfig(config: ScreencastConfig): ScreencastConfig;
+/** Walks up from `startDir` looking for a config file. */
+export declare function findConfigPath(startDir: string): string | null;
+export declare function resolveConfigPath(explicit?: string, cwd?: string): string | null;
+export declare function loadConfig(explicit?: string, cwd?: string): Promise<ResolvedConfig>;
+export declare function resolveConfig(raw: ScreencastConfig, configPath: string | null, cwd?: string): ResolvedConfig;
+/**
+ * Expands one `scenarios` entry to concrete files.
+ *
+ * Supports a file path, a directory, `dir/*.ts` and `dir/**` - which is the
+ * whole realistic range. A full glob library would be a dependency bought for
+ * patterns nobody writes here.
+ */
+export declare function expandScenarioPattern(pattern: string, rootDir: string): string[];
+export interface LoadedScenario {
+    readonly scenario: DefinedScenario;
+    /** Absolute path of the module it came from, for error messages. */
+    readonly file: string;
+}
+/**
+ * Loads every scenario the config points at, in declaration order.
+ *
+ * A module may export its scenario as `default`, as a named export, or several
+ * at once: the `defineScenario` stamp is what makes it findable, so nobody has
+ * to remember a naming convention.
+ */
+export declare function loadScenarios(config: ResolvedConfig): Promise<LoadedScenario[]>;
+export declare function loadScenarioFiles(files: readonly string[]): Promise<LoadedScenario[]>;
+/**
+ * Normalises the config's `auth` into a name -> strategy map.
+ *
+ * A single strategy becomes `{ default: it }`, so a scenario saying
+ * `auth: true` or nothing at all resolves without the config author having to
+ * name anything.
+ */
+export declare function normaliseAuth(auth: AuthConfig | undefined): Record<string, AuthStrategy>;
+/**
+ * Picks the strategy for a take.
+ *
+ * `false` on a scenario, or `--no-auth`, means signed out - a deliberate
+ * choice worth being able to make per scenario, since a landing page and a
+ * dashboard often live in the same config.
+ */
+export declare function selectStrategy(config: ResolvedConfig, scenarioAuth: string | false | undefined, override?: string | false): AuthStrategy | null;

package/dist/src/config.js

@@ -0,0 +1,275 @@
+import { ScreencastError } from "./errors.js";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DEFAULT_ENCODE_SETTINGS } from "./encode.js";
+import { DEFAULT_SETTLE_MS } from "./director.js";
+import { DEFAULT_OVERLAY_THEME } from "./overlay.js";
+import { isScenario } from "./types.js";
+import { noAuth } from "./auth/strategies.js";
+export const CONFIG_BASENAMES = [
+    "screencast.config.ts",
+    "screencast.config.mts",
+    "screencast.config.js",
+    "screencast.config.mjs",
+];
+const DEFAULT_VIEWPORT = { width: 1600, height: 1000 };
+/**
+ * Chromium flags that make a capture look deliberate rather than incidental:
+ * no scrollbars in frame, sRGB so colours match the design, and no font
+ * hinting so text renders the same on every machine that reshoots.
+ */
+export const DEFAULT_BROWSER_ARGS = [
+    "--hide-scrollbars",
+    "--force-color-profile=srgb",
+    "--font-render-hinting=none",
+];
+/** Identity function, for the types and the editor completion. */
+export function defineConfig(config) {
+    return config;
+}
+/** Walks up from `startDir` looking for a config file. */
+export function findConfigPath(startDir) {
+    let dir = resolve(startDir);
+    for (;;) {
+        for (const name of CONFIG_BASENAMES) {
+            const candidate = join(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function resolveConfigPath(explicit, cwd = process.cwd()) {
+    const chosen = explicit ?? process.env["SCREENCAST_CONFIG"];
+    if (chosen) {
+        const absolute = isAbsolute(chosen) ? chosen : resolve(cwd, chosen);
+        if (!existsSync(absolute)) {
+            throw new ScreencastError(`Config not found: ${absolute}`, "CONFIG_NOT_FOUND", [
+                "Pass `--config <path>` pointing at an existing file",
+                "Or drop the flag to search upwards from the current directory",
+            ]);
+        }
+        return absolute;
+    }
+    return findConfigPath(cwd);
+}
+/**
+ * Imports a module, registering `tsx` first if Node cannot load TypeScript.
+ *
+ * The package does not own transpilation. Node's own type stripping does not
+ * resolve tsconfig path aliases, which real scenarios use to reach a project's
+ * own code, so `tsx` is the documented way and an optional peer.
+ */
+let tsxRegistered = false;
+async function importModule(file) {
+    const url = pathToFileURL(file).href;
+    try {
+        return (await import(url));
+    }
+    catch (error) {
+        const code = error.code;
+        const needsLoader = code === "ERR_UNKNOWN_FILE_EXTENSION" ||
+            (error instanceof SyntaxError && /\.m?ts$/.test(file));
+        if (!needsLoader || tsxRegistered)
+            throw error;
+        try {
+            const specifier = "tsx/esm/api";
+            const tsx = (await import(specifier));
+            tsx.register?.();
+            tsxRegistered = true;
+        }
+        catch {
+            throw new ScreencastError(`Cannot load ${file}: this Node cannot run TypeScript directly`, "TS_LOADER_MISSING", ["Install the loader: `pnpm add -D tsx`", "Or write the file as .mjs instead of .ts"]);
+        }
+        // Cache-bust so the retry does not get the failed module record back.
+        return (await import(`${url}?tsx=1`));
+    }
+}
+export async function loadConfig(explicit, cwd = process.cwd()) {
+    const configPath = resolveConfigPath(explicit, cwd);
+    const raw = configPath
+        ? ((await importModule(configPath))["default"] ?? {})
+        : {};
+    return resolveConfig(raw, configPath, cwd);
+}
+export function resolveConfig(raw, configPath, cwd = process.cwd()) {
+    // Relative paths anchor to the config file, never to the shell's cwd -
+    // otherwise the same command means different things from different
+    // directories in the same repo.
+    const rootDir = configPath ? dirname(configPath) : resolve(cwd);
+    const at = (p) => (isAbsolute(p) ? p : resolve(rootDir, p));
+    const browser = {
+        headless: raw.browser?.headless ?? true,
+        ...(raw.browser?.profileDir ? { profileDir: at(raw.browser.profileDir) } : {}),
+        // No default: a device preset carries its own (2-3 on phones), and a
+        // config-level default of 1 would silently override it and throw away the
+        // detail that makes a phone clip readable.
+        ...(raw.browser?.deviceScaleFactor !== undefined
+            ? { deviceScaleFactor: raw.browser.deviceScaleFactor }
+            : {}),
+        args: raw.browser?.args ?? DEFAULT_BROWSER_ARGS,
+        ...(raw.browser?.colorScheme ? { colorScheme: raw.browser.colorScheme } : {}),
+        ...(raw.browser?.locale ? { locale: raw.browser.locale } : {}),
+        ...(raw.browser?.timezoneId ? { timezoneId: raw.browser.timezoneId } : {}),
+    };
+    return {
+        rootDir,
+        configPath,
+        outDir: at(raw.outDir ?? "screencasts"),
+        rawDir: at(raw.rawDir ?? ".screencast/raw"),
+        scenarios: raw.scenarios ?? [],
+        baseUrl: raw.baseUrl ?? "http://localhost:3000",
+        viewport: raw.viewport ?? DEFAULT_VIEWPORT,
+        ...(raw.device ? { device: raw.device } : {}),
+        pace: raw.pace ?? 1,
+        deliverables: { ...DEFAULT_ENCODE_SETTINGS, ...raw.deliverables },
+        browser,
+        overlay: { ...DEFAULT_OVERLAY_THEME, ...raw.overlay },
+        auth: normaliseAuth(raw.auth),
+        timeouts: {
+            setupMs: raw.timeouts?.setupMs ?? 120_000,
+            runMs: raw.timeouts?.runMs ?? 300_000,
+            rehearseMs: raw.timeouts?.rehearseMs ?? 8_000,
+            settleMs: raw.timeouts?.settleMs ?? DEFAULT_SETTLE_MS,
+        },
+    };
+}
+const SCENARIO_EXTENSIONS = [".ts", ".mts", ".js", ".mjs"];
+function isScenarioFile(file) {
+    return SCENARIO_EXTENSIONS.some((ext) => file.endsWith(ext)) && !file.endsWith(".d.ts");
+}
+function walk(dir, recursive) {
+    const found = [];
+    for (const name of readdirSync(dir).sort()) {
+        const full = join(dir, name);
+        const stats = statSync(full);
+        if (stats.isDirectory()) {
+            if (recursive)
+                found.push(...walk(full, true));
+        }
+        else if (isScenarioFile(name)) {
+            found.push(full);
+        }
+    }
+    return found;
+}
+/**
+ * Expands one `scenarios` entry to concrete files.
+ *
+ * Supports a file path, a directory, `dir/*.ts` and `dir/**` - which is the
+ * whole realistic range. A full glob library would be a dependency bought for
+ * patterns nobody writes here.
+ */
+export function expandScenarioPattern(pattern, rootDir) {
+    const absolute = isAbsolute(pattern) ? pattern : join(rootDir, pattern);
+    if (!absolute.includes("*")) {
+        if (!existsSync(absolute))
+            return [];
+        return statSync(absolute).isDirectory() ? walk(absolute, false) : [absolute];
+    }
+    const star = absolute.indexOf("*");
+    const base = absolute.slice(0, star);
+    const dir = base.endsWith(sep) ? base.slice(0, -1) : dirname(base);
+    if (!existsSync(dir))
+        return [];
+    const recursive = absolute.includes("**");
+    const suffix = absolute.slice(absolute.lastIndexOf("*") + 1);
+    return walk(dir, recursive).filter((f) => (suffix ? f.endsWith(suffix) : true));
+}
+/**
+ * Loads every scenario the config points at, in declaration order.
+ *
+ * A module may export its scenario as `default`, as a named export, or several
+ * at once: the `defineScenario` stamp is what makes it findable, so nobody has
+ * to remember a naming convention.
+ */
+export async function loadScenarios(config) {
+    const files = [];
+    for (const pattern of config.scenarios) {
+        for (const file of expandScenarioPattern(pattern, config.rootDir)) {
+            if (!files.includes(file))
+                files.push(file);
+        }
+    }
+    return loadScenarioFiles(files);
+}
+export async function loadScenarioFiles(files) {
+    const loaded = [];
+    const seen = new Map();
+    for (const file of files) {
+        const module = await importModule(file);
+        const found = Object.values(module).filter(isScenario);
+        if (found.length === 0) {
+            throw new ScreencastError(`No scenario exported by ${file}`, "NO_SCENARIO", [
+                "Wrap the object: `export default defineScenario({ ... })`",
+                "`defineScenario` is imported from `screencast-axi`",
+            ]);
+        }
+        for (const scenario of found) {
+            const previous = seen.get(scenario.id);
+            if (previous) {
+                // Two clips writing the same file stem would silently overwrite each
+                // other, and whichever ran last would win.
+                throw new ScreencastError(`Duplicate scenario id \`${scenario.id}\``, "DUPLICATE_SCENARIO", [
+                    `Defined in ${relative(process.cwd(), previous)} and ${relative(process.cwd(), file)}`,
+                    "Ids are the output file stem, so they have to be unique",
+                ]);
+            }
+            seen.set(scenario.id, file);
+            loaded.push({ scenario, file });
+        }
+    }
+    return loaded;
+}
+/**
+ * Normalises the config's `auth` into a name -> strategy map.
+ *
+ * A single strategy becomes `{ default: it }`, so a scenario saying
+ * `auth: true` or nothing at all resolves without the config author having to
+ * name anything.
+ */
+export function normaliseAuth(auth) {
+    if (!auth)
+        return { none: noAuth() };
+    if (typeof auth.name === "string") {
+        return { default: auth };
+    }
+    return auth;
+}
+/**
+ * Picks the strategy for a take.
+ *
+ * `false` on a scenario, or `--no-auth`, means signed out - a deliberate
+ * choice worth being able to make per scenario, since a landing page and a
+ * dashboard often live in the same config.
+ */
+export function selectStrategy(config, scenarioAuth, override) {
+    const chosen = override !== undefined ? override : scenarioAuth;
+    if (chosen === false)
+        return null;
+    const names = Object.keys(config.auth);
+    if (chosen === undefined) {
+        // Only a strategy the config supplied on its own - `auth: profileAuth()`,
+        // normalised to `default` - applies without being asked for. A named map
+        // never does, even when it holds exactly one entry: otherwise adding a
+        // second name would silently change what every unmarked scenario does, and
+        // a config with one login would quietly sign every take into it.
+        const strategy = config.auth["default"];
+        return !strategy || strategy.name === "none" ? null : strategy;
+    }
+    const strategy = config.auth[chosen];
+    if (!strategy) {
+        throw new ScreencastError(`Unknown auth strategy: ${chosen}`, "UNKNOWN_AUTH", [
+            names.length > 0
+                ? `This config defines: ${names.join(", ")}`
+                : "No auth strategies are configured. Add one under `auth` in screencast.config.ts",
+            "Use `--no-auth` to record signed out",
+        ]);
+    }
+    return strategy.name === "none" ? null : strategy;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/src/director.d.ts

@@ -0,0 +1,217 @@
+import type { Locator, Page } from "playwright";
+import type { Target } from "./types.js";
+export interface DirectorOptions {
+    /** Base URL used to resolve relative paths passed to `goto`. */
+    readonly baseUrl: string;
+    /**
+     * Playback speed multiplier applied to every pause and tween. 1 = natural
+     * demo pace, 0.5 = twice as fast. Kept as a knob because the right pace
+     * differs between a 6-second GIF and a 30-second explainer.
+     */
+    readonly pace: number;
+    /** The scenario's narration script, addressed by index from `step()`. */
+    readonly steps?: readonly string[];
+    /**
+     * How long {@link Director.goto} will wait for the network to go quiet.
+     *
+     * Settling is an optimisation - start acting once the page has stopped
+     * moving - not a requirement, and it has to be bounded because plenty of
+     * real sites never go quiet at all. GitHub does not: analytics, websockets
+     * and polling keep at least one request in flight forever. Waiting on the
+     * default timeout there put up to 30 seconds of dead air *inside the clip*,
+     * silently, because the failure is caught and ignored.
+     */
+    readonly settleMs?: number;
+}
+/** One thing the scenario did, for the run to report afterwards. */
+export interface DirectorAction {
+    /** Milliseconds since the Director was created. */
+    readonly atMs: number;
+    readonly kind: "goto" | "click" | "doubleClick" | "type" | "press" | "drag" | "scroll" | "waitFor" | "step";
+    /** What it acted on, as written in the scenario. */
+    readonly target?: string;
+    /** Typed text, a key, a distance - whatever makes the line readable. */
+    readonly detail?: string;
+}
+/** Default ceiling on the post-navigation settle wait. */
+export declare const DEFAULT_SETTLE_MS = 2500;
+/** One stop on a {@link Director.tour}. */
+export interface TourStop {
+    /** Path or absolute URL to open. */
+    readonly path: string;
+    /** Index into the scenario's `steps`. Preferred over `caption`. */
+    readonly step?: number;
+    /** Ad-hoc caption, for a tour whose narration is not in `steps`. */
+    readonly caption?: string;
+    /** Scroll after the caption lands: a fraction of the viewport, or pixels. */
+    readonly scroll?: number;
+    /** Override the shared dwell for this stop. */
+    readonly dwellMs?: number;
+    /** Wait for this before narrating, so a slow page does not get a jump cut. */
+    readonly waitFor?: Target;
+}
+/**
+ * The scenario-facing API. Every method is written so the resulting video is
+ * *watchable*: the pointer travels rather than teleports, clicks are preceded
+ * by a beat, and typing is per-character.
+ *
+ * Raw Playwright is still available via `director.page` for anything the
+ * helpers do not cover - but prefer adding a helper here over reaching past it,
+ * so all clips share one visual language.
+ */
+export declare class Director {
+    readonly page: Page;
+    private readonly opts;
+    private readonly contextCreatedAt;
+    private pointer;
+    /** ms since the context was created, at the moment the clip proper began. */
+    private clipStartedAt;
+    /** Indices passed to {@link step}, in the order the take showed them. */
+    private readonly shown;
+    /**
+     * Milliseconds spent in pauses this class controls.
+     *
+     * A take is `fixed + pace x scalable`: the app's own waits - navigation, a
+     * network round trip, an animation - do not get slower because the recorder
+     * does. Tracking the scalable half is what lets `--duration` solve for a
+     * pace exactly rather than assuming the whole clip scales.
+     */
+    private pausedMs;
+    /**
+     * Everything the scenario did, in order.
+     *
+     * A scenario is arbitrary code driving a real browser, often a signed-in
+     * one, so "what will this actually do" is a fair question to want answered
+     * before trusting it. Watching a headed run answers it once; this answers it
+     * in a form that can be read, diffed and kept.
+     */
+    private readonly actions;
+    constructor(page: Page, opts: DirectorOptions, contextCreatedAt: number);
+    /** Seconds of dead air at the head of the raw video, for the encoder to trim. */
+    get trimStartSeconds(): number;
+    /** Marks the end of setup. Everything before this is trimmed off the clip. */
+    markClipStart(): void;
+    private scaled;
+    /** Pace-scaled pause. Every wait this class owns goes through here. */
+    private pause;
+    /** How much of the take so far was pause this class controls, in ms. */
+    get scaledPauseMs(): number;
+    /** Everything the scenario did, in order. */
+    get performed(): readonly DirectorAction[];
+    private record;
+    /** A deliberate pause so the viewer can read what just happened. */
+    beat(ms?: number): Promise<void>;
+    goto(path: string): Promise<void>;
+    /** Which script lines this take put on screen, in order. */
+    get shownSteps(): readonly number[];
+    /**
+     * Puts line `index` of the scenario's `steps` on screen.
+     *
+     * Scenarios narrate through this rather than through {@link caption} so the
+     * text has one home: the same array becomes the burnt-in caption, the
+     * manifest's step list and the text the landing page renders beside the clip.
+     * `record.ts` checks afterwards that the take used every line exactly once,
+     * in order, which is what stops the written workflow from drifting away from
+     * the recorded one.
+     */
+    step(index: number, holdMs?: number): Promise<void>;
+    /** Shows a caption at the bottom of the frame. Pass `null` to clear it. */
+    caption(text: string | null, holdMs?: number): Promise<void>;
+    locator(target: Target): Locator;
+    /** Whether this target is a field whose value should never be logged. */
+    private isSecret;
+    private pointOf;
+    /** Glides the pointer to `target` along an eased path. */
+    moveTo(target: Target, { steps }?: {
+        steps?: number;
+    }): Promise<void>;
+    private glide;
+    /** Move, settle, then click - the pause is what makes the click legible. */
+    click(target: Target, { settleMs }?: {
+        settleMs?: number;
+    }): Promise<void>;
+    /**
+     * The click itself, without logging it.
+     *
+     * `type` focuses its field by clicking it, which is one action from the
+     * scenario's point of view. Logging the inner click too would put a
+     * phantom step in the record of what the take did.
+     */
+    private performClick;
+    doubleClick(target: Target): Promise<void>;
+    /**
+     * Clicks the field, then types character by character. `clear` selects the
+     * existing value first, so typing replaces it instead of appending - what a
+     * person does to a field that already holds a default.
+     */
+    type(target: Target, text: string, { delay, clear }?: {
+        delay?: number;
+        clear?: boolean;
+    }): Promise<void>;
+    press(key: string): Promise<void>;
+    /**
+     * Press-move-release drag. Deliberately slow and eased: this is the shot the
+     * whole harness exists for (reordering a tree row, moving a kanban card), and
+     * a fast drag reads as a teleport once it is re-encoded at 30fps.
+     */
+    drag(from: Target, to: Target, { steps, liftMs, dropMs, }?: {
+        steps?: number;
+        liftMs?: number;
+        dropMs?: number;
+    }): Promise<void>;
+    /**
+     * Drag for the parts of the product that move things with the HTML5
+     * drag-and-drop API (`draggable` + `dragstart`/`dragover`/`drop`) rather than
+     * with raw pointer events: the process-mapper components palette, the kanban
+     * board.
+     *
+     * Chromium does not synthesise those events from `mouse.down`/`move`/`up`, so
+     * {@link drag} silently does nothing there. This dispatches the protocol
+     * itself - one `DataTransfer` shared by every event of the gesture, which is
+     * what carries the payload the source sets in `dragstart` to the drop
+     * handler - while still moving the real pointer, so the overlay cursor shows
+     * a hand carrying the thing across the screen.
+     *
+     * The mouse button is deliberately *not* pressed. A real `mouse.down` on a
+     * `draggable` element makes Chromium open its own native drag session, which
+     * then swallows every following `mousemove` - the overlay pointer freezes at
+     * the source and the clip shows a thing teleporting. Without the press the
+     * pointer travels normally, and `setDragging` puts a ghost chip under it so
+     * the gesture still reads as carrying something.
+     */
+    dragHtml5(from: Target, to: Target, { steps, liftMs, dropMs, }?: {
+        steps?: number;
+        liftMs?: number;
+        dropMs?: number;
+    }): Promise<void>;
+    private setDragging;
+    /**
+     * Dispatches one drag event at `at`, on whatever is under that point.
+     *
+     * `dragenter`/`dragleave` are kept in step with the element under the pointer
+     * because a drop zone that only arms itself on `dragenter` would otherwise
+     * never accept the drop. `drop` also ends the gesture with `dragend` on the
+     * source, which is where a well-behaved source cleans up its drag state.
+     */
+    private dndEvent;
+    /** Smooth wheel scroll, in the page or in whatever is under the pointer. */
+    scrollBy(deltaY: number, { steps }?: {
+        steps?: number;
+    }): Promise<void>;
+    waitFor(target: Target): Promise<void>;
+    /**
+     * A multi-page walkthrough: go somewhere, narrate it, let it breathe, move on.
+     *
+     * This is the shape most requests actually have ("a walkthrough of the five
+     * main pages"), and writing it by hand is fifty lines of goto/caption/scroll
+     * whose only real content is the paths. Going through one helper also keeps
+     * the rhythm identical between stops, which is most of what makes a tour
+     * watchable rather than a run of jump cuts.
+     *
+     * Every pause here is pace-scaled like any other, so `--duration` re-cuts a
+     * tour without the scenario changing.
+     */
+    tour(stops: readonly TourStop[], { dwellMs }?: {
+        dwellMs?: number;
+    }): Promise<void>;
+}