@unotest/web 0.52.1 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,11 +1,11 @@
1
- import { L as LocatorValue, q as DriverDownload, D as DriverContext, W as WebDriver, i as DriverPage } from '../interfaces-BSGmF_Tv.js';
2
- export { r as LocatorStep, s as appendStep, t as describeLocator, u as isLocatorValue, v as rootedAt } from '../interfaces-BSGmF_Tv.js';
1
+ import { L as LocatorValue, j as DriverPage, r as DriverDownload, D as DriverContext, W as WebDriver } from '../interfaces-BU-PQbt4.js';
2
+ export { s as LocatorStep, t as appendStep, u as describeLocator, v as isLocatorValue, w as rootedAt } from '../interfaces-BU-PQbt4.js';
3
3
  import { Matcher, RegexLiteral, JudgeRequest, JudgeVerdict, VisualFailureRecord, SoftFailureRecord, TeardownStateRecord, TeardownFailureRecord } from '@unotest/protocol';
4
- import { SandboxConfig } from '../config/schema.js';
4
+ import { Browser, SandboxConfig } from '../config/schema.js';
5
5
  import { UnotestError, RuntimeExecState } from '@unotest/core';
6
6
  import { ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
7
7
  export { ExecutionError, ScenarioEvent as ExecutionEvent, ScenarioRunOptions as RunOptions, RunResult } from '@unotest/dsl/executor';
8
- export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-CYRlmOLy.js';
8
+ export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-BpaIstU3.js';
9
9
  import 'zod';
10
10
  import '@unotest/dsl';
11
11
 
@@ -125,6 +125,61 @@ interface Logger {
125
125
  child(prefix: string): Logger;
126
126
  }
127
127
 
128
+ /** How deep a redaction goes. */
129
+ interface RedactOptions {
130
+ /** Fields (by key, at any depth) whose strings are left alone. */
131
+ keep?: readonly string[];
132
+ /** `"exact"` also masks NUMBERS whose decimal form is exactly a
133
+ * registered secret — a numeric one-time code reaching a field typed
134
+ * `number | string`.
135
+ *
136
+ * Off by default, and that is a decision rather than an oversight: in
137
+ * a page capture the numbers are the structure — coordinates, widths,
138
+ * counts, unit totals — and masking one turns a graph the grounder
139
+ * reads into a graph it cannot. The caller that has a field where a
140
+ * number can BE the secret asks for it there. */
141
+ numbers?: "exact";
142
+ }
143
+ declare class SecretRegistry {
144
+ private readonly byValue;
145
+ private ordered;
146
+ /** Register a secret. Empty values are ignored — they'd match everywhere
147
+ * and can't be meaningfully masked. */
148
+ register(name: string, value: string): void;
149
+ get size(): number;
150
+ /** Copy every registered secret into `target`. Used when a per-session
151
+ * env overlay (`.secrets.<env>`) must also be masked by the
152
+ * process-wide sinks (debug log, session recorder) that hold the
153
+ * server's own registry. */
154
+ mergeInto(target: SecretRegistry): void;
155
+ /** Replace every registered secret value occurring in `s` with
156
+ * `‹secret:NAME›`. Returns `s` unchanged when no secrets are registered. */
157
+ redactString(s: string): string;
158
+ /** `redactString` for a terminal screen: a value the terminal wrapped
159
+ * onto the next row is masked too, the screen keeping its rows. */
160
+ redactScreen(screen: string): string;
161
+ /** Deep-redact a JSON-ish structure: every string field is run through
162
+ * `redactString`. Returns a new value; the input is not mutated. No-op
163
+ * (returns the input as-is) when no secrets are registered.
164
+ *
165
+ * `keep` names fields (by key, at any depth) whose strings are left as
166
+ * they are: the runner's own identifiers — a scenario path, a test
167
+ * function name, a run id. They are not page content, and a secret
168
+ * whose value happens to be a word inside them (`LOGIN=admin` against
169
+ * `guard-admin.js`) would otherwise mask the identifier itself into
170
+ * something no tool can open. An explicit list, never a guess at what
171
+ * "looks like a path". */
172
+ redact<T>(data: T, opts?: RedactOptions): T;
173
+ private redactValue;
174
+ /** A number is masked only when its decimal form IS a secret, whole —
175
+ * never when a secret occurs inside it. A number has no text for a
176
+ * value to hide in: `447213` either is the one-time code or is a
177
+ * quantity, and substring matching would mask the `99` in every price
178
+ * on the page. Masking yields a STRING, which is why the caller opts
179
+ * in per field rather than getting it everywhere. */
180
+ private redactNumber;
181
+ }
182
+
128
183
  /** Read-only lookup over external scenario variables. */
129
184
  interface VariableStore {
130
185
  has(name: string): boolean;
@@ -185,6 +240,11 @@ interface NoteRecord {
185
240
  /** The value as text: strings as-is, everything else JSON. The sink
186
241
  * applies the journal cap; the DSL layer does not know the limit. */
187
242
  text: string;
243
+ /** Run-dir-relative file holding the whole text, when `text` is a cut
244
+ * of it. Set by the sink; the DSL layer never fills it. */
245
+ full?: string;
246
+ /** Characters of the whole text that `text` leaves out. */
247
+ omittedChars?: number;
188
248
  }
189
249
  /** The notes of the step block the run is in, as the sink recorded them
190
250
  * (secrets masked). Read when a statement fails, so the failure carries
@@ -310,6 +370,16 @@ interface VisualSink {
310
370
  failure(): VisualFailureRecord | null;
311
371
  }
312
372
 
373
+ /** Says, once per run, that a snapshot taken on WebKit leaves out the
374
+ * backdrop blur the page asks for. Only a page that has one is worth the
375
+ * line; the engine is the run's `launch.browser`. */
376
+ declare class BackdropFilterNotice {
377
+ private readonly engine;
378
+ private readonly warn;
379
+ private said;
380
+ constructor(engine: Browser, warn: (line: string) => void);
381
+ check(page: Pick<DriverPage, "hasBackdropFilter">): Promise<void>;
382
+ }
313
383
  /** What the assert needs besides the page — wired per run entry. */
314
384
  interface VisualAssertDeps {
315
385
  comparator: ImageComparator;
@@ -321,6 +391,7 @@ interface VisualAssertDeps {
321
391
  attempt: number;
322
392
  /** The names this run has given, to refuse two that became one file. */
323
393
  names: BaselineNames;
394
+ backdrop?: BackdropFilterNotice;
324
395
  }
325
396
 
326
397
  type FrameFormat = "png" | "webp";
@@ -331,6 +402,11 @@ interface ScreenshotSink {
331
402
  * holds webp is the kind of thing nobody notices until a tool tries
332
403
  * to read it. Returns the project-relative path it landed at. */
333
404
  save(name: string, bytes: Buffer, format: FrameFormat): Promise<string>;
405
+ /** Persist the text that stands in for a picture which could not be
406
+ * shown — a terminal screen with a secret on it, already masked. Filed
407
+ * in the same sequence as the pictures; the event says `redacted`.
408
+ * Returns the project-relative path it landed at. */
409
+ saveMaskedText(name: string, text: string): Promise<string>;
334
410
  }
335
411
 
336
412
  interface SavedDownload {
@@ -347,6 +423,26 @@ interface DownloadSink {
347
423
  }
348
424
 
349
425
  type ContextFactory = () => Promise<DriverContext>;
426
+ /** How the runner opens a context on a browser profile of its own
427
+ * (`newContext({profile})`). It owns what a directory name means: where a
428
+ * relative one starts, that it exists. */
429
+ interface ProfileContexts {
430
+ /** The directory as the browser will open it: absolute, made if it was
431
+ * missing, symlinks resolved — the form two names of one directory agree on. */
432
+ resolve(dir: string): string;
433
+ open(resolvedDir: string): Promise<DriverContext>;
434
+ /** Whether `resolvedDir` is the profile directory the run's own context
435
+ * sits on (a run on `launch.userDataDir`, or a browser per test). */
436
+ isRunProfile(resolvedDir: string): boolean;
437
+ }
438
+ /** How the runner opens a context in a browser it joins over CDP
439
+ * (`newContext({cdpEndpoint})`): a browser somebody else started, left
440
+ * running when the test ends. */
441
+ type RemoteContextFactory = (endpoint: string) => Promise<DriverContext>;
442
+ interface NewContextTarget {
443
+ profile?: string;
444
+ cdpEndpoint?: string;
445
+ }
350
446
  /** A context that did not close — reported, never swallowed. */
351
447
  interface ContextCloseFailure {
352
448
  index: number;
@@ -355,19 +451,42 @@ interface ContextCloseFailure {
355
451
  declare class ContextSet {
356
452
  private readonly opts;
357
453
  private readonly list;
454
+ private pendingFirst;
455
+ private readonly openFirst;
358
456
  private activeIdx;
457
+ /** Profile directories opened by `open({profile})`, and the context on each. */
458
+ private readonly profileDirs;
459
+ /** Contexts opened in a browser joined over CDP, and the ones already
460
+ * closed — `closeRemote` closes the first early, `closeAll` skips the second. */
461
+ private readonly remoteIdx;
462
+ private readonly closedIdx;
359
463
  /** Called with the new active index on every switch (open or select). */
360
464
  private readonly listeners;
361
- constructor(first: DriverContext, opts?: {
465
+ constructor(first: DriverContext | ContextFactory, opts?: {
362
466
  open?: ContextFactory;
467
+ profiles?: ProfileContexts;
468
+ remote?: RemoteContextFactory;
363
469
  max?: number;
364
470
  });
471
+ /** Whether context 0 exists — false only for a lazy set nothing has needed yet. */
472
+ opened(): boolean;
473
+ /** Context 0, opened on the first call; calls made meanwhile share the
474
+ * one opening. A failed opening is not remembered: the next need tries again. */
475
+ ready(): Promise<DriverContext>;
365
476
  active(): DriverContext;
366
477
  activeIndex(): number;
367
478
  size(): number;
368
479
  all(): readonly DriverContext[];
369
- /** Open one more context, make it active, return its index. */
370
- open(): Promise<number>;
480
+ /** Open one more context, make it active, return its index — on a
481
+ * browser profile of its own when `profile` names a directory, in a
482
+ * browser somebody else runs when `cdpEndpoint` names one. */
483
+ open(target?: NewContextTarget): Promise<number>;
484
+ private openRemote;
485
+ private openProfile;
486
+ /** Context 0 first, then room under the ceiling, then the new one —
487
+ * active from the moment it is in. */
488
+ private place;
489
+ private requireRoom;
371
490
  select(index: unknown): void;
372
491
  /** Put `next` in the active context's place — same index, so whatever is
373
492
  * bound to the index (teardowns, the journal's context number) follows —
@@ -375,11 +494,82 @@ declare class ContextSet {
375
494
  * active context is a different one now. */
376
495
  replaceActive(next: DriverContext): Promise<void>;
377
496
  onSwitch(listener: (index: number) => void): () => void;
378
- /** Close every context, newest first; the failures come back. */
497
+ /** Close every context not closed yet, newest first; the failures come back. */
379
498
  closeAll(): Promise<ContextCloseFailure[]>;
499
+ /** Close the contexts that live in other people's browsers, ahead of
500
+ * everything else: what they sit in can go away (a VM) before the
501
+ * test's own teardown is done, and a close then waits on a dead
502
+ * connection. `closeAll` leaves them alone afterwards. */
503
+ closeRemote(): Promise<ContextCloseFailure[]>;
504
+ private closeIndices;
380
505
  private switchTo;
381
506
  }
382
507
 
508
+ /** What a wait reads of the test's time budget. */
509
+ interface BudgetClock {
510
+ /** Milliseconds left; Infinity when the test has no budget. */
511
+ leftMs(): number;
512
+ /** The budget's setting and size, for a message. */
513
+ describe(): {
514
+ setting: string;
515
+ limitMs: number;
516
+ };
517
+ }
518
+ interface BudgetCut {
519
+ readonly askedMs: number;
520
+ readonly leftMs: number;
521
+ readonly setting: string;
522
+ readonly limitMs: number;
523
+ }
524
+ /** The clock a runtime holds for its whole life; the executor binds the
525
+ * run's budget to it while the run lasts. Unbound, there is no budget. */
526
+ declare class BindableBudgetClock implements BudgetClock {
527
+ private source;
528
+ bind(source: BudgetClock): void;
529
+ unbind(): void;
530
+ leftMs(): number;
531
+ describe(): {
532
+ setting: string;
533
+ limitMs: number;
534
+ };
535
+ }
536
+
537
+ type KeyModifier = 'Shift' | 'Control' | 'Alt' | 'Meta';
538
+ declare const NAMED_KEYS: readonly ["Enter", "Tab", "Space", "Backspace", "Escape", "Delete", "Home", "End", "PageUp", "PageDown", "ArrowLeft", "ArrowRight", "ArrowDown", "ArrowUp", "F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "F9", "F10", "F11", "F12"];
539
+ type NamedKey = (typeof NAMED_KEYS)[number];
540
+ declare const US_KEY_CHARS: readonly ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "`", "-", "=", "[", "]", "\\", ";", "'", ",", ".", "/"];
541
+ type UsKeyChar = (typeof US_KEY_CHARS)[number];
542
+ type KeyTarget = {
543
+ readonly kind: 'named';
544
+ readonly name: NamedKey;
545
+ }
546
+ /** A key of a US keyboard, held with modifiers. */
547
+ | {
548
+ readonly kind: 'us';
549
+ readonly char: UsKeyChar;
550
+ }
551
+ /** A character alone: text. */
552
+ | {
553
+ readonly kind: 'char';
554
+ readonly char: string;
555
+ };
556
+ interface KeyChord {
557
+ readonly modifiers: readonly KeyModifier[];
558
+ readonly key: KeyTarget;
559
+ }
560
+
561
+ interface ScreenWaitOptions {
562
+ readonly timeoutMs: number;
563
+ /** Pass once the text is NOT on the screen. */
564
+ readonly not?: boolean;
565
+ /** Set when the budget of the test shortened `timeoutMs`. */
566
+ readonly cut?: BudgetCut;
567
+ }
568
+ /** What a wait saw: a regex gives the match array JS does (`[whole,
569
+ * group1, …]`, a group that took no part is null), a string the first
570
+ * screen row that holds it, `not` nothing. Taken from the masked screen. */
571
+ type ScreenMatch = readonly (string | null)[] | string | null;
572
+
383
573
  interface CommandRun {
384
574
  /** Fed to the program's stdin — a script travels here, never inside
385
575
  * argv, so its text is not limited or quoted by any shell. */
@@ -390,55 +580,30 @@ interface CommandHost {
390
580
  /** Where the terminal is, for a report: `this Mac`, `admin@192.168.64.38`.
391
581
  * Never carries a credential. */
392
582
  readonly name: string;
583
+ /** Who macOS asks for Screen Recording on this host — the app whose
584
+ * process runs `screencapture`, named for a message that tells the user
585
+ * where to allow it. */
586
+ permissionHolder(): string;
393
587
  /** Run `argv` (no shell) and resolve with its stdout. A non-zero exit
394
588
  * rejects with `TerminalHostError` carrying the program's stderr. */
395
589
  run(argv: readonly string[], opts?: CommandRun): Promise<Buffer>;
396
590
  }
397
591
 
398
- declare class AppleScriptRunner {
399
- private readonly host;
400
- constructor(host: CommandHost);
401
- /** Run `body` inside `on run argv … end run`; resolve with what it
402
- * returned, as text, without the newline osascript adds. */
403
- run(body: string, argv?: readonly string[]): Promise<string>;
404
- /** Run JXA `source` — a script whose `run(argv)` takes `argv` — and
405
- * resolve with what it returned, as `run` does. */
406
- runJavaScript(source: string, argv?: readonly string[]): Promise<string>;
407
- private osascript;
592
+ type StopSignal = 'HUP' | 'KILL';
593
+ interface StoppedProcess {
594
+ readonly pid: number;
595
+ readonly command: string;
596
+ /** The signal after which it was gone. */
597
+ readonly signal: StopSignal;
408
598
  }
409
-
410
- interface TerminalApp {
411
- /** The name a scenario opens it by: `openTerminal('iTerm2')`. */
412
- readonly name: string;
413
- /** The process System Events reports as frontmost while it has focus. */
414
- readonly processName: string;
415
- /** Script: open a new window with a login shell; return its id. */
416
- readonly openScript: string;
417
- /** Statements: bring window `winId` to the front and the app forward. */
418
- readonly focusStatements: string;
419
- /** Script: return the visible text of window `winId`. */
420
- readonly textScript: string;
421
- /** Script: return the tty of the shell in window `winId`. */
422
- readonly ttyScript: string;
423
- /** Statements: set window `winId` to `cols` × `rows` (argv items 2, 3). */
424
- readonly resizeStatements: string;
425
- /** Statements: close window `winId`; its shell has already exited. */
426
- readonly closeStatements: string;
427
- /** The `screencapture` arguments that frame window `winId`. */
428
- captureArgs(script: AppleScriptRunner, windowId: string): Promise<readonly string[]>;
599
+ interface SurvivingProcess {
600
+ readonly pid: number;
601
+ readonly command: string;
429
602
  }
430
-
431
- type KeyModifier = 'Shift' | 'Control' | 'Alt' | 'Meta';
432
- type KeyTarget = {
433
- readonly kind: 'code';
434
- readonly code: number;
435
- } | {
436
- readonly kind: 'char';
437
- readonly char: string;
438
- };
439
- interface KeyChord {
440
- readonly modifiers: readonly KeyModifier[];
441
- readonly key: KeyTarget;
603
+ /** What a window's end did to the processes of its tty. */
604
+ interface StopReport {
605
+ readonly killed: readonly StoppedProcess[];
606
+ readonly survived: readonly SurvivingProcess[];
442
607
  }
443
608
 
444
609
  interface TypeOptions {
@@ -446,46 +611,75 @@ interface TypeOptions {
446
611
  * does not echo, such as a password. */
447
612
  readonly echo: boolean;
448
613
  }
449
- interface ScreenWaitOptions {
450
- readonly timeoutMs: number;
451
- /** Pass once the text is NOT on the screen. */
452
- readonly not?: boolean;
614
+ /** The clipboard a terminal's programs share with the test. Its text is
615
+ * often a secret: nothing here repeats it in a message. */
616
+ interface TerminalClipboard {
617
+ read(): Promise<string>;
618
+ write(text: string): Promise<void>;
453
619
  }
454
- declare class TerminalSession {
455
- private readonly host;
456
- readonly app: TerminalApp;
457
- readonly windowId: string;
458
- private readonly script;
459
- private constructor();
460
- /** Where the window is, for a report — never a credential. */
461
- get hostName(): string;
462
- static open(host: CommandHost, app: TerminalApp): Promise<TerminalSession>;
463
- /** Paste `text` line by line, Return between the lines; with `echo`,
464
- * each line must show on the screen before the next goes. The user's
465
- * pasteboard is theirs again when this returns or throws. */
620
+ /** How a terminal's shell ended: its exit code and, when a signal ended
621
+ * it, the signal's name (`SIGTERM`). */
622
+ interface TerminalExit {
623
+ readonly exitCode: number;
624
+ readonly signal: string | null;
625
+ }
626
+ interface TerminalExitOptions {
627
+ readonly timeoutMs: number;
628
+ /** The exit code the shell must have ended with. */
629
+ readonly code?: number;
630
+ }
631
+ interface TerminalSession {
632
+ /** What a scenario opened: `Terminal`, `iTerm2`, `shell`. */
633
+ readonly appName: string;
634
+ /** Where it runs, for a report — never a credential. */
635
+ readonly hostName: string;
636
+ readonly clipboard: TerminalClipboard;
637
+ /** Send `text` line by line, Return between the lines; with `echo`, each
638
+ * line must show on the screen before the next goes. */
466
639
  type(fnName: string, text: string, opts: TypeOptions): Promise<void>;
467
- /** A character alone is text: it goes as `type` sends it, unchecked —
468
- * a key such as `q` or `y` is often not echoed. */
640
+ /** A key by its name or chord; a character alone goes as text. */
469
641
  press(fnName: string, chord: KeyChord): Promise<void>;
642
+ /** The screen as text (see screenText). */
470
643
  text(): Promise<string>;
471
644
  resize(cols: number, rows: number): Promise<void>;
472
- /** A PNG of the window as it is on screen now. */
645
+ /** A PNG of the terminal as it is now. */
473
646
  frame(): Promise<Buffer>;
474
647
  /** Resolve once the screen shows `matcher` (or, with `not`, no longer
475
- * does); a string occurs anywhere on it, a regex is tested against it. */
476
- waitForText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<void>;
648
+ * does); returns what it saw. */
649
+ waitForText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<ScreenMatch>;
477
650
  assertText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<void>;
478
- /** Stop the shell (and whatever runs in it) and close the window. */
479
- close(): Promise<void>;
480
- private screenMatches;
481
- private windowScript;
482
- /** Paste one line — the pasting script checks the front again before
483
- * it pastes — then wait for the screen to show it. */
484
- private pasteLine;
485
- /** Bring the window to the front and run `statement` (System Events key
486
- * presses) while it is there; nothing when it is not. */
487
- private sendKeys;
488
- private expectSent;
651
+ /** Resolve once the shell has exited, with how it ended; at once when it
652
+ * already has. With `code`, any other code fails. A session that cannot
653
+ * see its shell's exit refuses. */
654
+ waitForExit(fnName: string, opts: TerminalExitOptions): Promise<TerminalExit>;
655
+ /** Stop the shell and everything that runs from it — HUP, then KILL for
656
+ * what ignored it — and close the terminal; the report names what was
657
+ * stopped and what no signal stopped. */
658
+ close(): Promise<StopReport>;
659
+ }
660
+
661
+ /** The secrets a terminal masks: `redactString` for a line of output,
662
+ * `redactScreen` for a whole screen, where a value may be wrapped. */
663
+ type TerminalSecrets = Pick<SecretRegistry, 'redactString' | 'redactScreen'>;
664
+ /** A frame of a window: its picture, or — a secret was on the screen —
665
+ * the screen text with the secret masked. */
666
+ type GuardedFrame = {
667
+ readonly kind: 'png';
668
+ readonly png: Buffer;
669
+ } | {
670
+ readonly kind: 'masked';
671
+ readonly text: string;
672
+ };
673
+
674
+ interface TerminalLaunch {
675
+ readonly env?: Readonly<Record<string, string>>;
676
+ readonly cwd?: string;
677
+ readonly shell?: string;
678
+ readonly cols?: number;
679
+ readonly rows?: number;
680
+ readonly term?: string;
681
+ readonly locale?: string;
682
+ readonly cleanProfile?: boolean;
489
683
  }
490
684
 
491
685
  /** The host of `openTerminal(app, {host})`: this Mac without one, the Mac
@@ -494,29 +688,61 @@ interface CommandHosts {
494
688
  local(): CommandHost;
495
689
  remote(destination: string): CommandHost;
496
690
  }
691
+ interface OpenRequest {
692
+ readonly fnName: string;
693
+ /** `{host}` as the scenario gave it, unchecked: an opener that takes no
694
+ * host refuses it; one that does resolves it through `hosts`. */
695
+ readonly destination: string | undefined;
696
+ readonly hosts: CommandHosts;
697
+ readonly redactScreen: TerminalSecrets['redactScreen'];
698
+ /** How the shell of a pty terminal starts; absent when the scenario set
699
+ * none of the launch keys. */
700
+ readonly launch?: TerminalLaunch;
701
+ }
702
+ interface TerminalOpener {
703
+ /** The name a scenario opens it by: `openTerminal('iTerm2')`. */
704
+ readonly name: string;
705
+ open(req: OpenRequest): Promise<TerminalSession>;
706
+ }
707
+
497
708
  interface TerminalSetDeps {
498
709
  readonly hosts: CommandHosts;
499
- readonly apps: readonly TerminalApp[];
710
+ /** What `openTerminal(name)` can open, by name. */
711
+ readonly openers: readonly TerminalOpener[];
712
+ /** The run's registered secrets: what a terminal's screen must never
713
+ * carry out of the run unmasked. */
714
+ readonly secrets: TerminalSecrets;
715
+ }
716
+ /** A window the set closed: which one, where, and what its end stopped. */
717
+ interface ClosedTerminal extends StopReport {
718
+ readonly index: number;
719
+ readonly host: string;
500
720
  }
501
721
  declare class TerminalSet {
502
722
  private readonly deps;
503
723
  private readonly sessions;
504
724
  private activeIdx;
505
725
  private readonly remotes;
726
+ private readonly frames;
506
727
  constructor(deps: TerminalSetDeps);
507
- /** Open a window of `appName` on `destination` (this Mac when absent),
508
- * make it active, return its index. */
509
- open(fnName: string, appName: string, destination?: string): Promise<number>;
728
+ /** Open a terminal by its opener's name on `destination` (this machine
729
+ * when absent), make it active, return its index. */
730
+ open(fnName: string, name: string, destination?: string, launch?: TerminalLaunch): Promise<number>;
510
731
  select(fnName: string, index: number): void;
511
732
  /** The window the terminal steps act on. */
512
733
  active(fnName: string): TerminalSession;
513
734
  /** The active window, or none — for a failure bundle, which must not
514
735
  * fail over a test that never opened a terminal. */
515
736
  current(): TerminalSession | undefined;
516
- /** Close window `index`; a closed one stays closed, quietly. */
517
- close(index: number): Promise<void>;
737
+ /** A frame of `session` fit to leave the run: its picture, or its
738
+ * masked screen text when a secret is on the screen. */
739
+ frame(session: TerminalSession): Promise<GuardedFrame>;
740
+ /** The screen text of `session`, every secret on it masked. */
741
+ screen(session: TerminalSession): Promise<string>;
742
+ /** Close window `index`; a closed one stays closed, quietly (null). */
743
+ close(index: number): Promise<ClosedTerminal | null>;
518
744
  /** `closeTerminal()`: the active window; refused when none is open. */
519
- closeActive(fnName: string): Promise<void>;
745
+ closeActive(fnName: string): Promise<ClosedTerminal | null>;
520
746
  private remote;
521
747
  private openAt;
522
748
  }
@@ -696,11 +922,19 @@ type DslValue = DslPrimitive | DslObject | DslArray;
696
922
  * context the runner opened — or one it SHARES with its host (a flow
697
923
  * replayed in an MCP session switches the session's contexts). */
698
924
  type RuntimeContexts = {
699
- /** Context 0 — the one the runner opened for this entry. */
700
- readonly context: DriverContext;
925
+ /** Context 0 — the one the runner opened for this entry, or the way
926
+ * to open it on the first need (a test that never uses a page
927
+ * never starts a browser). */
928
+ readonly context: DriverContext | ContextFactory;
701
929
  /** Opens one more context with the entry's options (`newContext()`).
702
930
  * Absent → the runtime cannot add one (an attached debug session). */
703
931
  readonly openContext?: ContextFactory;
932
+ /** Opens a context on a browser profile of its own
933
+ * (`newContext({profile})`). Absent → it cannot be. */
934
+ readonly profiles?: ProfileContexts;
935
+ /** Opens a context in a browser joined over CDP
936
+ * (`newContext({cdpEndpoint})`). Absent → it cannot be. */
937
+ readonly remote?: RemoteContextFactory;
704
938
  /** Ceiling on contexts per entry (`config.maxContexts`). */
705
939
  readonly maxContexts?: number;
706
940
  /** Opens the entry's context again with the same options on the real
@@ -797,6 +1031,9 @@ declare class TestRuntime {
797
1031
  readonly testTimeout?: {
798
1032
  ms?: number;
799
1033
  };
1034
+ /** What is left of the test's time; the executor binds it for the run.
1035
+ * Unbound (explore, bare runtimes) there is no budget to wait within. */
1036
+ readonly budget: BindableBudgetClock;
800
1037
  readonly annotations?: AnnotationSink;
801
1038
  readonly stepNotes?: StepNotesReader;
802
1039
  readonly visual?: VisualAssertDeps;
@@ -1054,8 +1291,12 @@ declare class TestRuntimeManager {
1054
1291
  * is gone or has no context yet. */
1055
1292
  pages(id: string): readonly DriverPage[];
1056
1293
  /** The runtime's driver context (for capture artifacts — console/network).
1057
- * Null when the runtime isn't registered. */
1294
+ * Null when the runtime isn't registered, or its test has not opened a
1295
+ * browser page. */
1058
1296
  currentContext(id: string): DriverContext | null;
1297
+ /** Every browser context the runtime opened, in index order — the active
1298
+ * one is only one of them. Empty when the runtime isn't registered. */
1299
+ contexts(id: string): readonly DriverContext[];
1059
1300
  list(): RuntimeSummary[];
1060
1301
  /** A client acted on the runtime — a debug command arrived. A runtime
1061
1302
  * paused on a failure gets its full TTL again: somebody is there. A read