@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/mobile.js

@@ -0,0 +1,65 @@
+// Mobile app handle for tests — drives an Expo/React-Native-Web app rendered
+// in a phone-emulated headless Chromium and recorded as an rrweb session that
+// the dashboard replays inside a phone bezel.
+//
+// `ctx.mobile(ctx.svc.app)` opens one of these already pointed at the app. The
+// surface is the SAME Playwright-native one as `ctx.browser()` (the shared
+// `Browser` session + `Locator`s from browser.ts/locator.ts) plus two mobile
+// extensions: a `touchscreen` and `swipe`. There is no mobile-specific locator
+// type — `getByTestId`/`getByRole`/`getByText`/… return the same `Locator`,
+// and on a mobile session a locator's `tap()` dispatches a real CDP touch with
+// the press dwell RN Pressables need (the `mobileStrategy` in locator.ts;
+// desktop `tap()` throws and steers you to `click()`).
+//
+// This file is now just the `MobileApp` handle (`ctx.mobile` accepts it) and
+// the `Mobile` public view of the shared backend. React Native Web renders
+// `testID="x"` to `data-testid="x"` and `accessibilityLabel` to `aria-label`,
+// so `getByTestId`/`getByLabel` map straight onto Playwright's built-ins.
+import { acquirePersistentMobileBackend, openMobileBackend } from "./browser.js";
+/** Branded handle a mobile-app component (e.g. `expo()`) exposes on
+ *  `ctx.svc.<name>`. The brand is a `Symbol.for` key so `JSON.stringify`
+ *  drops it (wire-invisible) while `ctx.mobile(...)` can still type-check
+ *  against it. */
+export const MOBILE_APP = Symbol.for("spectest.mobileApp");
+/** True if `x` is a {@link MobileApp} handle. */
+export function isMobileApp(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x[MOBILE_APP] === true &&
+        typeof x.url === "string");
+}
+/** Build a {@link MobileApp} handle from a resolved URL (and an optional
+ *  init script installed before the session's first navigation). */
+export function mobileApp(url, initScript) {
+    return { [MOBILE_APP]: true, url, initScript };
+}
+/**
+ * Open an EPHEMERAL phone-emulated session pointed at `url` (`close()`
+ * destroys it). Library callers only — the daemon's `ctx.mobile(app)` goes
+ * through {@link openPersistentMobile} so sessions survive across tests.
+ */
+export async function openMobile(opts) {
+    const backend = await openMobileBackend({
+        frame: "mobile",
+        url: opts.url,
+        recorder: opts.recorder,
+    });
+    // MobileBackend is a superset of Mobile (adds the low-level primitives).
+    return backend;
+}
+/**
+ * Acquire the persistent phone-emulated session for an app (one per app URL,
+ * created on first use). The daemon calls this from `ctx.mobile(app)` with a
+ * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
+ * the dashboard renders a phone bezel. `detach` is the test-end hook;
+ * `mobile.close()` destroys the session for real.
+ */
+export async function openPersistentMobile(opts) {
+    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.recorder, opts.initScript);
+    return {
+        mobile: browser,
+        attached,
+        detach,
+        safeAreaInsets: browser.safeAreaInsets,
+    };
+}

package/dist/record-secrets.d.ts

@@ -0,0 +1,9 @@
+/** Replace the eval-scoped secret set. Called by the daemon at the start
+ *  of each `/eval` with the values the control plane resolved. */
+export declare function setRecordSecrets(secrets: Record<string, string> | undefined): void;
+/** Drop all secrets. Called from the eval's `finally` so nothing survives
+ *  past the eval that supplied them. */
+export declare function clearRecordSecrets(): void;
+/** Resolve a secret by its platform `ref`. `undefined` if the control
+ *  plane didn't supply it (ref not configured, or not on the eval path). */
+export declare function getRecordSecret(ref: string): string | undefined;

package/{src/record-secrets.ts → dist/record-secrets.js}

@@ -15,27 +15,25 @@
 // eval means a secret never persists into anything a replay run can reach.
 // This module is shared (one instance per daemon process) so the daemon
 // writes and the component reads the same map.
-
-const SECRETS = new Map<string, string>();
-
+const SECRETS = new Map();
 /** Replace the eval-scoped secret set. Called by the daemon at the start
  *  of each `/eval` with the values the control plane resolved. */
-export function setRecordSecrets(secrets: Record<string, string> | undefined): void {
-  SECRETS.clear();
-  if (!secrets) return;
-  for (const [ref, value] of Object.entries(secrets)) {
-    if (typeof value === "string") SECRETS.set(ref, value);
-  }
+export function setRecordSecrets(secrets) {
+    SECRETS.clear();
+    if (!secrets)
+        return;
+    for (const [ref, value] of Object.entries(secrets)) {
+        if (typeof value === "string")
+            SECRETS.set(ref, value);
+    }
 }
-
 /** Drop all secrets. Called from the eval's `finally` so nothing survives
  *  past the eval that supplied them. */
-export function clearRecordSecrets(): void {
-  SECRETS.clear();
+export function clearRecordSecrets() {
+    SECRETS.clear();
 }
-
 /** Resolve a secret by its platform `ref`. `undefined` if the control
  *  plane didn't supply it (ref not configured, or not on the eval path). */
-export function getRecordSecret(ref: string): string | undefined {
-  return SECRETS.get(ref);
+export function getRecordSecret(ref) {
+    return SECRETS.get(ref);
 }

package/dist/recorder.d.ts

@@ -0,0 +1,527 @@
+export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | EnvEvent | EmailEvent;
+interface BaseEvent {
+    /** Order of *start* within the test. Reserved when an op begins (see
+     *  `reserveEvent`), so an op whose nested children finish — and record —
+     *  before it does still sorts ahead of them. Ops that don't reserve get
+     *  their seq at record (= finish) time. */
+    seq: number;
+    /** Milliseconds since the recorder started, captured when the op began
+     *  (reserved) or, absent a reservation, when it was recorded. */
+    tOffsetMs: number;
+    /**
+     * Optional grouping pointer. When set, this event was emitted inside
+     * a larger logical step (e.g. an HTTP call that fed the predicate of
+     * a `ctx.poll(...)`) and should render nested under the parent in
+     * timelines. The parent event is identified by its `seq`.
+     */
+    parentSeq?: number;
+}
+export interface ExecEvent extends BaseEvent {
+    kind: "exec";
+    service: string;
+    command: string;
+    /**
+     * Working directory the command ran from (`ctx.exec(svc, cmd, { cwd })`),
+     * if any. Kept off `command` so the sidebar shows just the command; the
+     * detail view surfaces it. Absent when the call used no `cwd`.
+     */
+    cwd?: string;
+    /**
+     * The payload piped to the command's stdin (`ctx.exec(svc, cmd, {
+     * stdin })`), truncated to OUTPUT_SNIPPET_BYTES. Recorded because the
+     * asciicast only captures what the command *wrote* — without this, a
+     * `kubectl apply -f -` step shows its error but not the manifest that
+     * caused it. Absent when the call piped nothing.
+     */
+    stdin?: string;
+    stdinTruncated?: boolean;
+    exitCode: number;
+    /** stdout truncated to OUTPUT_SNIPPET_BYTES. */
+    stdout: string;
+    stdoutTruncated: boolean;
+    stderr: string;
+    stderrTruncated: boolean;
+    durationMs: number;
+    /**
+     * Links this exec to the asciicast `TerminalSessionRecord` of its run
+     * (mirroring `TerminalEvent.sessionId`): one exec step covers one full
+     * CLI run, so the whole recording belongs to this event. Absent on
+     * events recorded before exec runs were captured.
+     */
+    sessionId?: string;
+}
+export interface AssertionEvent extends BaseEvent {
+    kind: "assertion";
+    /** Matcher name, e.g. "toBe", "toEqual". */
+    matcher: string;
+    /** Whether this was `expect(x).not.toBe(...)`. */
+    negated: boolean;
+    passed: boolean;
+    /** Best-effort JSON-safe serialization. */
+    actual: unknown;
+    expected?: unknown;
+    /** Failure message produced by the matcher (only when `passed` is false). */
+    error?: string;
+    /**
+     * Author-supplied label for the assertion. **Required** for a raw assertion
+     * (`expectRaw(value, message)`), where it renders as the summary
+     * ("ASSERT <message>") and serves as the diff-alignment key since a raw
+     * assertion has no provenance `path`. **Optional** for a provenance-linked
+     * `expect(value, message)`, where it leads the summary as a clarifying note
+     * alongside the rendered matcher/target. Absent when `expect(...)` was called
+     * without a message.
+     */
+    message?: string;
+    /**
+     * `seq` of the op (http / db / browser) whose return value this
+     * assertion drilled into. Set when `expect()` received a value wrapped
+     * by `inspect.wrap()`. The UI nests assertions with `sourceSeq` under
+     * the matching op; assertions without it render at top level.
+     */
+    sourceSeq?: number;
+    /** JSON-path of property accesses from the op return value down to
+     * the asserted value (e.g. `["body", "user", "name"]`). Empty for
+     * direct asserts on the op return itself. */
+    path?: string[];
+}
+export interface DbEvent extends BaseEvent {
+    kind: "db";
+    /** Service the query ran against (the key in `environment.services`). */
+    service: string;
+    /** SQL text. For tagged-template calls, values appear as `$1`, `$2`, … */
+    query: string;
+    /** Parameter values. Best-effort JSON-safe; large/binary values stringified. */
+    params?: unknown[];
+    /** Rows returned — or rows AFFECTED when `rowsAffected` is set. */
+    rowCount?: number;
+    /** Set when `rowCount` counts affected rows (a non-RETURNING
+     *  INSERT/UPDATE/DELETE) rather than a result set — rendered as
+     *  "N affected" so an `UPDATE → 0 rows` can't read as "nothing updated". */
+    rowsAffected?: boolean;
+    /** Captured rows for table rendering in the web UI. Capped at
+     *  MAX_DB_ROWS; `rowsTruncated` is set when there were more. */
+    rows?: unknown[];
+    rowsTruncated?: boolean;
+    /** Column names in the order Bun.SQL returned them. Derived from the
+     *  first captured row, so omitted when no rows. */
+    columns?: string[];
+    durationMs: number;
+    /** Set if the driver threw. */
+    error?: string;
+}
+/**
+ * One Redis/Valkey command issued through the instrumented {@link
+ * "../redis".RedisClient} (a drop-in for `Bun.RedisClient` / `Bun.redis`).
+ *
+ * The return value is `wrap()`ped against this event's seq, so a later
+ * `expect(...)` that drills into it nests under this step in the timeline
+ * (same mechanism as http/db).
+ */
+export interface RedisEvent extends BaseEvent {
+    kind: "redis";
+    /** Label for the connection — the URL host (often the service name). */
+    service: string;
+    /** Command name, upper-cased (`GET`, `SET`, `HGETALL`, `PUBLISH`, …). */
+    command: string;
+    /** First argument — almost always the key the command targets. Surfaced
+     *  separately so the UI can read `GET session:42` at a glance. */
+    key?: string;
+    /** Remaining arguments (best-effort JSON-safe; large/binary stringified).
+     *  Omitted when there are none. */
+    args?: unknown[];
+    /** Reply, best-effort JSON-safe and capped. Omitted when the command threw
+     *  or returned `null`/`undefined`. */
+    result?: unknown;
+    resultTruncated?: boolean;
+    durationMs: number;
+    /** Set if the command threw. */
+    error?: string;
+}
+/**
+ * One object-storage operation through the instrumented {@link
+ * "../s3".S3Client} (a drop-in for `Bun.S3Client` / `Bun.s3`), covering both
+ * client-level calls (`write`/`delete`/`exists`/`list`/`presign`/`stat`) and
+ * the `S3File` handle `.file(path)` returns (`text`/`json`/`write`/…).
+ *
+ * The return value is `wrap()`ped against this event's seq, so `expect(...)`
+ * drilling into it nests under this step (same mechanism as http/db).
+ */
+export interface S3Event extends BaseEvent {
+    kind: "s3";
+    /** Operation: `write` | `read` | `delete` | `exists` | `list` |
+     *  `presign` | `stat`. */
+    op: string;
+    /** Bucket, when the client/handle knows it. */
+    bucket?: string;
+    /** Object key (path) the op targeted. Omitted for bucket-wide `list`. */
+    key?: string;
+    /** Bytes written or read, when known. */
+    size?: number;
+    /** Content type, when known (read/write/stat). */
+    contentType?: string;
+    /** Small text preview of the body (read/write of text), capped. */
+    preview?: string;
+    previewTruncated?: boolean;
+    /** For `list`: number of keys returned. */
+    count?: number;
+    durationMs: number;
+    /** Set if the op threw. */
+    error?: string;
+}
+export interface HttpEvent extends BaseEvent {
+    kind: "http";
+    method: string;
+    url: string;
+    /** Truncated to OUTPUT_SNIPPET_BYTES. Only set for non-binary text bodies. */
+    requestBody?: string;
+    requestBodyTruncated?: boolean;
+    status?: number;
+    responseBody?: string;
+    responseBodyTruncated?: boolean;
+    durationMs: number;
+    /** Set if the request threw (network error, abort, etc.). */
+    error?: string;
+}
+/**
+ * A Kubernetes API call (from `ctx.svc.<k3s>.client.*` / `apply(...)`).
+ *
+ * The k3s component routes the kube client through `globalThis.fetch`, so
+ * the daemon's fetch wrapper first records it as a plain `http` event;
+ * the component then parses the request path and *reclassifies* that event
+ * into this richer shape via `recorderAnnotate`, so the UI can show
+ * `verb resource/name` (e.g. `list pods · default`) instead of an opaque
+ * `GET https://k8s.internal:6443/api/v1/...`. The underlying HTTP fields
+ * are retained so the request/response bodies (the actual K8s objects)
+ * still render in the detail view, and `expect(...)` on the returned
+ * object nests under this event exactly as it does for `http`.
+ */
+export interface KubeEvent extends BaseEvent {
+    kind: "kube";
+    /** API verb derived from the HTTP method + path shape: `get` | `list` |
+     *  `watch` | `create` | `update` | `patch` | `delete` |
+     *  `deletecollection`. */
+    verb: string;
+    /** API group — `""` for the core group (`/api/v1`), else e.g. `"apps"`,
+     *  `"networking.k8s.io"`. */
+    group?: string;
+    /** API version, e.g. `"v1"`. */
+    apiVersion?: string;
+    /** Resource plural, e.g. `"pods"`, `"deployments"`, `"ingresses"`. */
+    resource?: string;
+    /** Subresource, when addressed, e.g. `"status"`, `"scale"`, `"log"`. */
+    subresource?: string;
+    /** Object name, when the request targets a single object. */
+    name?: string;
+    /** Namespace, when namespaced. Absent for cluster-scoped requests. */
+    namespace?: string;
+    method: string;
+    url: string;
+    requestBody?: string;
+    requestBodyTruncated?: boolean;
+    status?: number;
+    responseBody?: string;
+    responseBodyTruncated?: boolean;
+    durationMs: number;
+    error?: string;
+}
+/**
+ * One call to a fake's helper function (`ctx.fakes.<name>.<fn>(...)`).
+ * Helpers are user-authored functions that read or mutate the fake's
+ * private state, so this is the only window into what a test asked the
+ * fake — distinct from the `http` events the *app under test* generates
+ * when it actually calls the fake's endpoints.
+ *
+ * The return value is `wrap()`ped against this event's seq, so a later
+ * `expect(...)` that drills into it nests under this step in the
+ * timeline (same mechanism as http/db/exec).
+ */
+export interface FakeEvent extends BaseEvent {
+    kind: "fake";
+    /** Fake name — the key in `ctx.fakes`. */
+    fake: string;
+    /** Helper function called, e.g. `"lastCharge"`. */
+    member: string;
+    /** Call arguments (best-effort JSON-safe). */
+    args?: unknown[];
+    /** Return value (best-effort JSON-safe). Omitted when the helper threw
+     *  or returned `undefined`. */
+    result?: unknown;
+    durationMs: number;
+    /** Set if the helper threw. */
+    error?: string;
+}
+/**
+ * One captured email, as embedded on an {@link EmailEvent}. The HTML and
+ * text bodies ride along (truncated to the output cap) so the dashboard
+ * can render the actual email a test asserted against.
+ */
+export interface EmailEventMessage {
+    /** Sender address. */
+    from?: string;
+    /** Recipient addresses. */
+    to?: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject?: string;
+    /** RFC date of the message, ISO-formatted. */
+    date?: string;
+    /** HTML body (truncated to the output cap). */
+    html?: string;
+    htmlTruncated?: boolean;
+    /** Plain-text body (truncated to the output cap). */
+    text?: string;
+    textTruncated?: boolean;
+    attachments?: {
+        filename: string;
+        contentType: string;
+        size: number;
+    }[];
+}
+/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
+export interface EmailEventSummary {
+    from?: string;
+    to?: string[];
+    subject?: string;
+    /** Plain-text preview of the body. */
+    snippet?: string;
+    date?: string;
+}
+/**
+ * One call to an email service's helpers (`ctx.svc.<name>.lastEmail(...)`
+ * etc.). Single-message ops embed the full captured message — including its
+ * HTML body — so timelines can render the email itself; listing ops embed
+ * compact summaries. The return value is `wrap()`ped against this event's
+ * seq, so `expect(...)` on it nests under this step (same mechanism as
+ * http/db/fake). Inside a `ctx.poll` predicate the event ride-alongs with
+ * the poll's iteration events: failed iterations get truncated, the winning
+ * one survives as a child of the `wait` event.
+ */
+export interface EmailEvent extends BaseEvent {
+    kind: "email";
+    /** Service key of the mail server (`ctx.svc.<service>`). */
+    service: string;
+    /** Helper called, e.g. `"lastEmail"`. */
+    op: string;
+    /** Human-readable match criteria, e.g. `to alice@example.com`. */
+    query?: string;
+    /** Number of matching messages (listing ops / mailbox size on error). */
+    count?: number;
+    /** The captured message (single-message ops). */
+    message?: EmailEventMessage;
+    /** Message summaries (listing ops). */
+    messages?: EmailEventSummary[];
+    durationMs: number;
+    /** Set if the op threw (e.g. the mail server's query API failed). */
+    error?: string;
+}
+/**
+ * A runtime mutation of the environment — `ctx.startService` /
+ * `ctx.stopService` / `ctx.dnsName`, whether called from a test or from a
+ * fake handler reacting to the app under test. Distinct from the `http`
+ * event the app generates when it calls the fake: this is the
+ * infrastructure the fake (or test) created in response. No-op outside a
+ * running test (bootstrap / project-setup / eval), same as every record*.
+ */
+export interface EnvEvent extends BaseEvent {
+    kind: "env";
+    /** Which environment primitive ran. */
+    op: "startService" | "stopService" | "dnsName" | "certificate";
+    /** SANs of a minted leaf (certificate). */
+    hostnames?: string[];
+    /** Service name (startService / stopService). */
+    service?: string;
+    /** Image reference started (startService). */
+    image?: string;
+    /** Resolved IP — the new container's (startService) or the target's (dnsName). */
+    ip?: string;
+    /** Hostname registered (dnsName). */
+    hostname?: string;
+    durationMs: number;
+    /** Set if the op threw. */
+    error?: string;
+}
+export type BrowserAction = string;
+export interface BrowserEvent extends BaseEvent {
+    kind: "browser";
+    action: BrowserAction;
+    /** Target URL (navigate). */
+    url?: string;
+    /** CSS selector (click, scrollTo). */
+    selector?: string;
+    /** Human-readable label for `evaluate` ops. */
+    description?: string;
+    /** Evaluated script, truncated. */
+    script?: string;
+    scriptTruncated?: boolean;
+    /** Typed text, truncated. */
+    text?: string;
+    textTruncated?: boolean;
+    /** Key name (press). */
+    key?: string;
+    /** Scroll/click coordinates. */
+    dx?: number;
+    dy?: number;
+    x?: number;
+    y?: number;
+    /** Screenshot image format. */
+    format?: string;
+    /** For `waitFor`: how many times the predicate was polled. */
+    attempts?: number;
+    durationMs: number;
+    error?: string;
+    /**
+     * Session this op belonged to. Set whenever the Browser was opened
+     * with a `BrowserSessionRecorder` attached (the daemon always does).
+     */
+    sessionId?: string;
+    /**
+     * Wall-clock `Date.now()` captured at the moment this op *finished*.
+     * Lives in the same time base as rrweb's `event.timestamp` fields,
+     * so the dashboard can seek the player by computing
+     * `event.timestamp - events[0].timestamp`. Using the post-op time
+     * (rather than op start) means clicking a "type 'foo'" step lands
+     * on the frame where the field already shows the text.
+     */
+    sessionTimestamp?: number;
+}
+/**
+ * Inline event for a single `ctx.terminal(...)` call. The heavy
+ * asciicast frames live separately on a `TerminalSessionRecord`
+ * (mirroring how `BrowserEvent` points at a `BrowserSessionRecord`).
+ * The UI shows this row in the step list and seeks the player to
+ * the session's start when clicked.
+ */
+export interface TerminalEvent extends BaseEvent {
+    kind: "terminal";
+    service: string;
+    command: string;
+    exitCode: number;
+    durationMs: number;
+    /** Links this event to its TerminalSessionRecord. */
+    sessionId: string;
+    /** PTY size used for the run. */
+    cols: number;
+    rows: number;
+    /** First N bytes of decoded output, for tooltip/inline preview. */
+    outputPreview: string;
+    outputTruncated: boolean;
+    /** Set if spawning the PTY itself failed. */
+    error?: string;
+}
+/** Action taken on an open interactive terminal session. */
+export type TerminalStepAction = "send" | "sendLine" | "press" | "waitFor" | "exit" | "close";
+/**
+ * One operation on an open interactive terminal — analogous to
+ * `BrowserEvent`. The session's heavy asciicast frames live on the
+ * `TerminalSessionRecord`; this event just carries metadata so the
+ * step shows up in the timeline and the UI can seek the player.
+ */
+export interface TerminalStepEvent extends BaseEvent {
+    kind: "terminal-step";
+    /** Links this event back to its TerminalSessionRecord. */
+    sessionId: string;
+    /** Service the terminal is attached to (mirrors TerminalEvent.service). */
+    service: string;
+    /** Which Terminal method produced this event. */
+    action: TerminalStepAction;
+    /** Bytes sent (send/sendLine), truncated. */
+    text?: string;
+    textTruncated?: boolean;
+    /** Key name passed to `press`. */
+    key?: string;
+    /** Human label passed to `waitFor`. */
+    description?: string;
+    /** How many polls `waitFor` made. */
+    attempts?: number;
+    /** Whether `waitFor` matched (false means it timed out). */
+    matched?: boolean;
+    /** Exit code observed on `close`. */
+    exitCode?: number;
+    /** Rendered screen at the moment of the op (post-action), truncated. */
+    screenPreview: string;
+    screenTruncated: boolean;
+    /**
+     * Player-relative offset, in seconds, captured against the *same*
+     * clock the asciicast frames use (the terminal factory's spawn
+     * time). The UI seeks the asciinema-player to this value when the
+     * step is clicked. Persisting it directly avoids ever subtracting
+     * `step.tOffsetMs - session.openedAtMs` on the front-end, which is
+     * fragile because the two timestamps live in slightly different
+     * Date.now() frames (recorder vs. spawn).
+     */
+    castTimeSec: number;
+    durationMs: number;
+    error?: string;
+}
+/** An ordering slot claimed at op *start* and handed back to the matching
+ *  `record*` call at op finish. Lets a triggering op (an `exec`/`fetch` that
+ *  reaches the app, which calls a fake, which calls `ctx.startService`) keep a
+ *  lower seq than the nested events it sets off — even though those nested
+ *  events finish, and record, first. */
+export interface EventReservation {
+    seq: number;
+    tOffsetMs: number;
+}
+export declare function pauseRecording(): void;
+export declare function resumeRecording(): void;
+export declare function startRecording(): void;
+export declare function stopRecording(): TestEvent[];
+export declare function isRecording(): boolean;
+/** Reserve an ordering slot at the start of an op so nested events it triggers
+ *  (which finish — and record — first) still sort after it. Hand the returned
+ *  reservation to the matching `record*` call at op finish. Returns `undefined`
+ *  when nothing is recording, in which case `record*` falls back to allocating
+ *  the seq at record time. */
+export declare function reserveEvent(): EventReservation | undefined;
+export declare function recordExec(ev: Omit<ExecEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordAssertion(ev: Omit<AssertionEvent, "seq" | "tOffsetMs" | "kind">): number | undefined;
+export declare function recordHttp(ev: Omit<HttpEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordBrowser(ev: Omit<BrowserEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordDb(ev: Omit<DbEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordRedis(ev: Omit<RedisEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordS3(ev: Omit<S3Event, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordTerminal(ev: Omit<TerminalEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordTerminalStep(ev: Omit<TerminalStepEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordFake(ev: Omit<FakeEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordEnv(ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordEmail(ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+/**
+ * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed
+ * intermediate iterations and gives downstream tagged values
+ * (`wrap(polledValue, waitSeq)`) a single, stable event to point at —
+ * assertions on those values then link to the wait, not to one of N
+ * dropped polls.
+ */
+export interface WaitEvent extends BaseEvent {
+    kind: "wait";
+    description: string;
+    attempts: number;
+    durationMs: number;
+    passed: boolean;
+    /** Set when the predicate threw or the wait timed out. */
+    error?: string;
+}
+export declare function recordWait(ev: Omit<WaitEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+/** Number of events the active recorder has accumulated. Returns 0
+ *  when no recorder is active. */
+export declare function recorderEventCount(): number;
+/** Drop events with index >= `toLen` from the active recorder. */
+export declare function recorderTruncate(toLen: number): void;
+/** Stamp `parentSeq` onto every event from `startIdx` onward, so the
+ *  UI groups them under the parent in the timeline. */
+export declare function recorderMarkChildren(startIdx: number, parentSeq: number): void;
+/** Shallow-merge `patch` into the active recorder's event with this
+ *  `seq` (enrich/reclassify after the fact). No-op when nothing is
+ *  recording or no event carries that seq. */
+export declare function recorderAnnotate(seq: number, patch: Record<string, unknown>): void;
+/** Retract the active recorder's event with this `seq` (an instrumentation
+ *  site recorded it, then decided it's noise). No-op when nothing is
+ *  recording or no event carries that seq. */
+export declare function recorderRemove(seq: number): void;
+/** Best-effort JSON-safe deep clone; falls back to `String(v)`. */
+export declare function safeSerialize(v: unknown): unknown;
+export declare function truncateUtf8(s: string): {
+    value: string;
+    truncated: boolean;
+};
+export {};