@roku-sdk/device-test-client 0.0.0-stage → 2.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roku, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @roku-sdk/device-test-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Single entry-point SDK for writing **integration tests that drive real Roku
+devices** from a Jest suite running on your host. The package bundles:
+
+- a queued, rate-limited **ECP client** (`RkClient`) that talks to the device,
+- **build + sideload + launch** primitives with readiness and health checks,
+- **DOM, screenshot, and log assertion** pillars with baseline workflows,
+- **precondition-aware `it`/`describe` wrappers** that skip on firmware /
+model / resolution mismatches,
+- first-class **Jest wiring** (`globalSetup`, `globalTeardown`,
+`installDeviceTestHooks`, a custom test environment) that captures rich
+per-failure diagnostic bundles out of the box.
+
+Everything is a named export of the package root — there is no deep-path
+import surface to remember.
+
+```ts
+import {
+    createDefaultClient,
+    installDeviceTestHooks,
+    itOnDevice,
+    expectTree,
+    expectScreenshot,
+    findNode
+} from "@roku-sdk/device-test-client";
+```
+
+## Install
+
+```bash
+pnpm add -D @roku-sdk/device-test-client
+# or
+npm install -D @roku-sdk/device-test-client
+```
+
+Requires **Node 24+** (for global `fetch`), **Jest 29+**, and the
+`[rk](../tooling)` CLI/daemon checked in alongside this package. Log
+assertions need `rk server` running on the host.
+
+## 60-second quick start
+
+```ts
+import {
+    createDefaultClient,
+    installDeviceTestHooks
+} from "@roku-sdk/device-test-client";
+
+const client = createDefaultClient();
+installDeviceTestHooks({ client });
+
+test("app launches and shows the home scene", async () => {
+    await client.buildAndDeploy("apps/buttons", {
+        readyNode: { attr: { id: "home-title", text: "Welcome" } }
+    });
+    await client.keypress("Select");
+    await client.waitForNode(
+        { focused: true, attr: { id: "first-button" } },
+        { timeout: 3_000 }
+    );
+});
+```
+
+For a full Jest skeleton (config + setup files) jump to
+`[docs/getting-started.md](docs/getting-started.md)`.
+
+## Documentation
+
+The `docs/` folder is the manual. Each page opens with a short summary so
+you can skim the table of contents; every documented symbol ships with its
+TypeScript signature **and** a runnable example.
+
+
+| Topic                                                  | What's inside                                                                                        |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| [Getting started](docs/getting-started.md)             | Prerequisites, install, first test, Jest config skeleton                                             |
+| `[RkClient` reference](docs/rkclient.md)               | Every method, every option type, rate limits, retries                                                |
+| [DOM assertions](docs/dom-assertions.md)               | `findNode`, `expectFocused`, `waitForNode`, tree baselines                                           |
+| [Screenshot assertions](docs/screenshot-assertions.md) | `captureStableScreenshot`, `expectScreenshot`, masks, thresholds, alignment tolerance                 |
+| [Log assertions](docs/log-assertions.md)               | `logPosition`, `waitForLog`, `expectNoLog`, gap handling                                             |
+| [Preconditions](docs/preconditions.md)                 | `itOnDevice` / `describeOnDevice` / `requirePrecondition`, device-class tiering                      |
+| [Jest integration](docs/jest-integration.md)           | `globalSetup` / `globalTeardown`, `installDeviceTestHooks`, custom test environment, failure bundles |
+| [Baselines](docs/baselines.md)                         | `hd/` + `fhd/` routing, `UPDATE_BASELINES=1` workflow, CI guard                                      |
+| [Configuration](docs/configuration.md)                 | Env vars, tunable constants, `test-results/` artifact layout                                         |
+| [Error reference](docs/errors.md)                      | Every exported error class with fields and recovery advice                                           |
+
+
+Worked examples that cross feature boundaries live under
+`[docs/examples/](docs/examples/)`:
+
+- `[smoke-test](docs/examples/smoke-test.md)` — shortest possible deploy + one assertion
+- `[deep-link-cold-start](docs/examples/deep-link-cold-start.md)` — reliable cold-sideload deep-link delivery
+- `[focus-navigation](docs/examples/focus-navigation.md)` — `keysequence` + focus-change polling
+- `[screenshot-regression](docs/examples/screenshot-regression.md)` — stable capture + masked `expectScreenshot`
+- `[log-driven-assertion](docs/examples/log-driven-assertion.md)` — `logPosition` → `keypress` → `waitForLog`
+- `[precondition-skips](docs/examples/precondition-skips.md)` — skipping by firmware / model / resolution
+
+## Feature matrix
+
+- **ECP queries** — `queryAppUi`, `queryDeviceInfo` (+ cache),
+`queryActiveApp`, `captureScreenshot`
+- **Input** — `keypress`, `keysequence` with validated key names and an
+enforced inter-key delay
+- **Lifecycle** — `launch`, `buildAndDeploy`, `buildAndLaunchWithParams`
+(cold sideload + reliable deep-link delivery)
+- **Readiness & health** — semantic readiness gate via `readyNode`, system
+dialog detection, per-worker health flag with fail-fast `beforeEach`
+- **Polling** — `waitForNode`, `captureStableScreenshot` with crash-probe
+on every iteration
+- **DOM assertions** — `findNode` / `findAllNodes` / `findFocusedNode` /
+`expectFocused`, plus baseline comparison via
+`expectTree(...).toMatchBaseline(...)`
+- **Screenshot assertions** — `expectScreenshot(...).toMatchBaseline(...)`
+with pixelmatch, mask regions, decoupled aggregate + per-pixel thresholds,
+and opt-in alignment tolerance for firmware-drawn surfaces that re-center
+between devices
+- **Log assertions** — `logPosition`, `waitForLog`, `expectNoLog`, bulk
+`logs`, gap-aware semantics
+- **Preconditions** — firmware semver ranges, videoMode prefix, exact
+modelFamily / locale / country, derived device-class tiering
+- **Failure diagnostics** — per-failure bundles under
+`test-results/failures/<sanitized>/` (screenshot, DOM tree, recent logs,
+error) and a streaming `test-results/device.log`
+
+## Compatibility
+
+- **Runtime:** Node 24+ (global `fetch`).
+- **Test runner:** Jest 29 or 30 (the custom environment `require()`s
+`jest-environment-node` at runtime so either works).
+- **Roku firmware:** any firmware that serves the standard ECP surface
+(`/query/app-ui`, `/query/device-info`, `/query/active-app`,
+`/launch/…`, `/keypress/…`, `/capture-screen/png`).
+- **Videomodes:** `720p`, `720p60`, `1080p`, `1080p60`. See
+`[SUPPORTED_VIDEO_MODES](docs/baselines.md#supported-video-modes)`.
+
+## Versioning
+
+The package follows semver. The public surface is everything exported by
+`@roku-sdk/device-test-client` (see `[src/index.ts](src/index.ts)`) — no
+other import paths are supported. Renames of public symbols are major
+bumps; additions are minor.
+
+## License
+
+See the repository root.

package/docs/baselines.md

@@ -0,0 +1,221 @@
+# Baselines
+
+Both [DOM](dom-assertions.md) and [screenshot](screenshot-assertions.md)
+assertions read ground-truth artifacts from a **baselines directory**
+routed by the device's current **videoMode**. This page documents the
+directory layout, the resolution-routing rules, how to create or
+update baselines via `UPDATE_BASELINES=1`, and the CI guard that
+prevents accidental mutation.
+
+- [Directory layout](#directory-layout)
+- [Wiring via `installDeviceTestHooks`](#wiring-via-installdevicetesthooks)
+- [Resolution routing](#resolution-routing)
+- `[DEVICE_TEST_RESOLUTION` override](#device_test_resolution-override)
+- [Supported videoModes](#supported-videomodes)
+- `[UPDATE_BASELINES=1` workflow](#update_baselines1-workflow)
+- [CI guard](#ci-guard)
+- [Errors thrown](#errors-thrown)
+
+## Directory layout
+
+```
+baselines/
+├── hd/                         # 720p devices
+│   └── grid/
+│       ├── initial-tree.json
+│       └── initial.png
+└── fhd/                        # 1080p devices
+    └── grid/
+        ├── initial-tree.json
+        └── initial.png
+```
+
+Every assertion call with a relative baseline path (e.g.
+`"grid/initial-tree.json"`) is rewritten to
+`<baselineRoot>/<hd|fhd>/<relPath>` at runtime. The relative path is
+identical across resolutions — only the subdir differs.
+
+## Wiring via `installDeviceTestHooks`
+
+In v2.0.0 both the baselines root and the "which client owns the
+active `videoMode`" signal are set through `installDeviceTestHooks`:
+
+```ts
+import {
+    createDefaultClient,
+    installDeviceTestHooks
+} from "@roku-sdk/device-test-client";
+import { resolve } from "node:path";
+
+const client = createDefaultClient();
+
+installDeviceTestHooks({
+    client,                                            // → active-client signal
+    baselineRoot: resolve(__dirname, "../baselines")   // → baseline root
+});
+```
+
+Behind the scenes these map to the internal `setActiveClient` /
+`setBaselineRoot` module-level singletons that previous versions
+asked consumers to call directly; centralising the wiring in one
+options-object call removes a whole class of "forgot to register the
+client" bugs.
+
+**Precedence for the baseline root** (checked in order):
+
+1. `installDeviceTestHooks({ baselineRoot })` value.
+2. `DEVICE_TEST_BASELINES` env var.
+3. `<process.cwd()>/baselines`.
+
+> **Internal / deep-import.** The raw `setBaselineRoot(absPath)` and
+> `setActiveClient(client | null)` functions still exist inside the
+> package but are no longer re-exported from the barrel. The tiny
+> number of out-of-band consumers (ad-hoc reporters, tests of this
+> package's own internals) can still import them via
+> `@roku-sdk/device-test-client/src/assertions/baselines`, but deep
+> paths are **not** covered by the SemVer contract — prefer
+> `installDeviceTestHooks` in normal test code.
+
+## Resolution routing
+
+```ts
+type BaselineResolution = "hd" | "fhd";
+
+function videoModeToResolution(videoMode: string): BaselineResolution | null;
+```
+
+Resolution is picked with the following precedence:
+
+1. **Active client registered + videoMode recognised** — map to the
+  corresponding subdir. The env override is intentionally **not**
+   consulted in this path.
+2. **Active client registered + videoMode unrecognised** — throw
+  `BaselineResolutionError({ reason: "unsupported-videoMode" })`.
+   The client is authoritative; silently falling back would paper
+   over a misconfigured fixture or unexpected firmware mode.
+3. **No active client** — consult `DEVICE_TEST_RESOLUTION`:
+  - `"hd"` or `"fhd"` → use it.
+  - any other value → `invalid-env-value`.
+  - unset → `no-active-client-and-no-env`.
+
+`videoModeToResolution` lives alongside the internal
+`setActiveClient` / `setBaselineRoot` helpers on the same deep-import
+module (`@roku-sdk/device-test-client/src/assertions/baselines`) — it
+is not part of the v2.0.0 barrel.
+
+## `DEVICE_TEST_RESOLUTION` override
+
+```bash
+DEVICE_TEST_RESOLUTION=fhd pnpm jest path/to/file.test.ts
+```
+
+Only consulted when no client is registered. Useful for ad-hoc
+debugging when running a single test before `installDeviceTestHooks`
+has a chance to wire the client — e.g. a throwaway reporter that
+constructs its own assertion loop without the full setup.
+
+## Supported videoModes
+
+```ts
+const SUPPORTED_VIDEO_MODES: ReadonlySet<string>;
+```
+
+The SDK ships with:
+
+- `720p` / `720p60` → `hd`
+- `1080p` / `1080p60` → `fhd`
+
+`assertSupportedVideoMode` (from
+[Jest integration](jest-integration.md#artifact-helpers)) rejects
+everything else in `createGlobalSetup` so misconfigured fixtures
+fail before any baseline write.
+
+## `UPDATE_BASELINES=1` workflow
+
+First-run (create baselines) and intentional-update flows share the
+same toggle:
+
+```bash
+UPDATE_BASELINES=1 pnpm jest path/to/file.test.ts
+```
+
+**Behaviour per assertion:**
+
+
+| Baseline state                          | Without flag                                              | With flag                                       |
+| --------------------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
+| Missing                                 | `BaselineMissingError` / `ScreenshotBaselineMissingError` | Baseline created atomically; assertion passes   |
+| Exists, matches                         | passes                                                    | passes (no write)                               |
+| Exists, mismatch (tree)                 | `TreeMismatchError`                                       | Overwritten atomically; assertion passes        |
+| Exists, mismatch (screenshot)           | `ScreenshotMismatchError` + diff PNG                      | Overwritten atomically; **no diff PNG written** |
+| Exists, dimension mismatch (screenshot) | `ScreenshotDimensionsMismatchError`                       | Overwritten atomically; assertion passes        |
+
+
+**Atomic writes.** Every baseline write goes through a per-pid +
+random-suffix tmp file + `renameSync`, so readers always observe
+either the old or new contents, never a half-written file.
+
+**Accepted truthy spellings** (case-insensitive): `1`, `true`, `yes`.
+
+**Workflow.**
+
+```bash
+# 1. Make your UI change.
+# 2. Refresh baselines locally.
+UPDATE_BASELINES=1 pnpm jest
+
+# 3. Review the git diff on the baselines directory.
+git diff baselines/
+
+# 4. Commit the updated baselines alongside the source change.
+```
+
+## CI guard
+
+```ts
+function assertBaselineUpdatesAllowed(): void;
+function isCi(): boolean;
+```
+
+`assertBaselineUpdatesAllowed` throws when `CI` **and**
+`UPDATE_BASELINES` are both set to a truthy value. It runs at the
+top of `createGlobalSetup` **and** inline before every baseline
+write, so an out-of-band `expectTree`/`expectScreenshot` call cannot
+sneak past the `globalSetup` check.
+
+`isCi()` and `assertBaselineUpdatesAllowed()` are internal helpers
+of the baseline-write path; they are not exported from the v2.0.0
+barrel. Consumers needing a parallel CI check should read
+`process.env.CI` directly or import from
+`@roku-sdk/device-test-client/src/assertions/baselines` as a
+deep-import (SemVer-uncovered).
+
+The error message cites `UPDATE_BASELINES=1` as the canonical
+remediation regardless of the spelling that tripped the guard — if
+you see it, drop the variable entirely, don't try a different
+casing.
+
+## Errors thrown
+
+- `BaselineResolutionError` — resolution could not be picked.
+Fields: `videoMode` (when applicable), `reason` (one of
+`"unsupported-videoMode"`, `"no-active-client-and-no-env"`,
+`"invalid-env-value"`).
+- `BaselineMissingError` — DOM baseline missing. Fields:
+`baselinePath`, `resolution`, `videoMode`.
+- `ScreenshotBaselineMissingError` — screenshot baseline missing.
+Fields: `baselinePath`, `resolution`.
+- `TreeMismatchError` — DOM baseline diff. Fields: `baselinePath`,
+`firstDiff`, `expectedSnippet`, `actualSnippet`.
+- `ScreenshotMismatchError` — screenshot diff over threshold.
+Fields: `baselinePath`, `resolution`, `actual.w/h`,
+`mismatchedPixels`, `totalPixels`, `ratio`, `threshold`,
+`diffPath`.
+- `ScreenshotDimensionsMismatchError` — canvas size diverged from
+baseline. Fields: `baselinePath`, `resolution`, `baseline.w/h`,
+`actual.w/h`.
+- `Error` — raw from `assertBaselineUpdatesAllowed` in CI with
+`UPDATE_BASELINES` set.
+
+Full field lists and recovery advice in
+`[errors.md](errors.md)`.

package/docs/configuration.md

@@ -0,0 +1,258 @@
+# Configuration
+
+All behaviour users typically need to tune is driven by environment
+variables or passed via `RkClientOptions`. The rest of this page
+lists every knob the package exposes plus the on-disk artifact layout
+it writes under `test-results/`.
+
+- [Environment variables](#environment-variables)
+- [Tunable constants](#tunable-constants)
+- `[test-results/` layout](#test-results-layout)
+
+## Environment variables
+
+
+| Variable                 | Type                               | Default                 | Purpose                                                                                                                                                            |
+| ------------------------ | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `RK_DEVICE_IP`           | IPv4 string                        | —                       | Explicit override for the target Roku device. When set, bypasses `.roku/` active-device resolution. Consumed by the package's internal IP-resolver and `createDefaultClient`. See [Device credentials](#device-credentials) for the deploy-path contract. |
+| `RK_DEVICE_PASSWORD`     | string                             | —                       | Developer-mode password for the device named by `RK_DEVICE_IP`. **Must be set together with `RK_DEVICE_IP`** — a partial pair fails the deploy with `DeployFailedError({ phase: "config" })`. See [Device credentials](#device-credentials). |
+| `RK_SERVER_URL`          | `http://host:port[/api]`           | `http://localhost:3737/api` | `rk server` base URL. Resolution precedence: `RkClientOptions.serverUrl` → `RK_SERVER_URL` → `.roku/rk-server.json` → default. Normalized to end with `/api` (and no trailing slash) regardless of source — every server route is mounted under `/api/...`, so a bare `http://host:port` is auto-promoted to the canonical shape. |
+| `UPDATE_BASELINES`       | `1` / `true` / `yes` (case-insens) | unset                   | Re-run writes baselines instead of diffing. Blocked by the CI guard when `CI` is also truthy.                                                                      |
+| `CI`                     | `1` / `true` / `yes` (case-insens) | unset                   | Marks the current run as CI. Blocks `UPDATE_BASELINES`.                                                                                                            |
+| `DEVICE_TEST_BASELINES`  | absolute path                      | `<cwd>/baselines`       | Override for the baselines root. Primary mechanism is `installDeviceTestHooks({ baselineRoot })`; this is the escape hatch for ad-hoc runs.                        |
+| `DEVICE_TEST_RESOLUTION` | `hd` | `fhd`                       | —                       | Ad-hoc baseline resolution override. **Ignored when a client is registered** via `installDeviceTestHooks({ client })`.                                             |
+| `DEVICE_TEST_KEY_DELAY`  | decimal ms                         | `100`                   | Default inter-key delay for `keysequence`. Override per call via `KeySequenceOptions.keyDelay`.                                                                    |
+
+### Device credentials
+
+The deploy path (`RkClient.buildAndDeploy` →
+`buildAndLaunchWithParams`) needs **both** an IP and a developer-mode
+password. They are resolved in this order:
+
+1. **Env-var pair** — `RK_DEVICE_IP` + `RK_DEVICE_PASSWORD`. When both
+   are set, they are used as-is and `.roku/` is not read. An empty
+   value counts as unset. Skipped when the caller passes an explicit
+   `BuildAndDeployOptions.deviceSelector` (a selector only makes sense
+   against a multi-device store).
+2. **`RK_DEVICE_IP` alone** — the device is looked up in
+   `.roku/roku-dev-config.json` by that IP (not by the active pointer),
+   and its stored password is used. This is the normal local run:
+   `globalSetup` exports the IP it resolved, so a run against a device
+   registered with `rk device add` / `rk device update` arrives here
+   with only the IP set.
+3. **`.roku/roku-dev-config.json`** — the active device record (or
+   the device matching `deviceSelector`), written by `rk device add`
+   / `rk device update`.
+
+The env-var pair is the recommended path for CI, where credentials
+typically live in masked pipeline variables and materialising a
+`.roku/` config file would either leak the secret to disk or require
+an extra scaffolding step. The file path is the recommended local
+workflow because it's discoverable, persistent across shells, and
+shared with the rest of the `rk` CLI.
+
+Failure modes (all surface as `DeployFailedError({ phase: "config" })`
+and mark the device unhealthy):
+
+- Only `RK_DEVICE_PASSWORD` set → `"RK_DEVICE_PASSWORD is set but
+  RK_DEVICE_IP is empty; set both env vars or neither"`.
+- Only `RK_DEVICE_IP` set, and no stored device has that IP →
+  `"RK_DEVICE_IP (X) is not a registered rk device; run `rk device
+  add X` and `rk device update X --password <pw>`, or set
+  RK_DEVICE_PASSWORD"`.
+- `RK_DEVICE_IP` disagrees with the IP the `RkClient` was constructed
+  with (typically by `globalSetup`) → `"RK_DEVICE_IP env var (X)
+  does not match RkClient deviceIp (Y); fix one of them"`.
+- Neither path produces a device → `"no active device configured;
+  run `rk device add <ip>` or set RK_DEVICE_IP +
+  RK_DEVICE_PASSWORD"`.
+- `.roku/` device record has no password →
+  `"device '…' has no password; run `rk device update` to set one or
+  set RK_DEVICE_PASSWORD"`.
+
+**Example — running against a specific device on a different `rk server`.**
+
+```bash
+RK_DEVICE_IP=192.168.1.42 \
+RK_SERVER_URL=http://10.0.0.5:3737 \
+pnpm jest
+```
+
+**Example — full CI invocation (no `.roku/` on disk).**
+
+```bash
+RK_DEVICE_IP=192.168.1.42 \
+RK_DEVICE_PASSWORD=$ROKU_DEV_PASSWORD_FROM_VAULT \
+pnpm jest
+```
+
+**Example — regenerating baselines locally.**
+
+```bash
+UPDATE_BASELINES=1 pnpm jest tests/smoke.test.ts
+```
+
+**Example — ad-hoc baseline inspection without a device.**
+
+```bash
+DEVICE_TEST_RESOLUTION=fhd DEVICE_TEST_BASELINES=./baselines pnpm jest
+```
+
+## Tunable constants
+
+Values exported as named constants from `@roku-sdk/device-test-client`.
+Most can be overridden per-client via `RkClientOptions.intervals` or
+per-call via option objects.
+
+### ECP timing
+
+```ts
+const DEFAULT_KEY_DELAY = 100;                  // ms
+const DEFAULT_REQUEST_TIMEOUT_MS = 5000;        // ms
+const ECP_RETRY_BACKOFF_MS = 500;               // ms (single retry)
+
+const ECP_INTERVAL_MS: Record<EcpCategory, number> = {
+    "query-appui": 200,
+    "query-device-info": 0,
+    "query-active-app": 0,
+    keypress: 0,
+    launch: 0,
+    capture: 500
+};
+```
+
+`ECP_INTERVAL_MS` values can be per-client-overridden:
+
+```ts
+const client = new RkClient({
+    deviceIp: "192.168.1.42",
+    intervals: {
+        "query-appui": 50,   // DANGEROUS — here be dragons
+        capture: 200
+    }
+});
+```
+
+The intervals are **gap-based** (end of previous call to start of
+next), not start-to-start, so tightening them beyond what the device
+can sustain causes silent slow responses that look like timeouts.
+
+### Readiness
+
+```ts
+const READINESS_TIMEOUT_MS = 10_000;          // default for buildAndDeploy / launch
+const READINESS_POLL_INTERVAL_MS = 200;
+const READINESS_CONFIRM_POLLS = 2;            // consecutive predicate passes
+```
+
+Override per-call via `BuildAndDeployOptions.readinessTimeout` /
+`LaunchOptions.readinessTimeout`.
+
+### Polling
+
+```ts
+const WAIT_FOR_NODE_DEFAULT_INTERVAL_MS = 200;
+const WAIT_FOR_LOG_DEFAULT_TIMEOUT_MS = 5_000;
+const SCREENSHOT_STABLE_DEFAULT_INTERVAL_MS = 500;
+```
+
+### Screenshot comparison
+
+```ts
+const DEFAULT_SCREENSHOT_THRESHOLD = 0.01;       // 1% of unmasked pixels
+const PIXELMATCH_COLOR_THRESHOLD = 0.1;          // internal, NOT caller-tunable
+const SCREENSHOT_DIFF_DIR = "test-results/diffs";
+```
+
+### Log buffer
+
+```ts
+const LOG_BUFFER_MAX_LINES = 10_000;
+const LOG_BUFFER_DROP_HALF = 5_000;
+const SSE_PENDING_MAX_BYTES = 1_048_576;         // SSE parser hard cap
+```
+
+The underlying log buffer accepts `max` / `dropHalf` overrides for
+unit tests via its deep-import module — see
+[log-assertions.md](log-assertions.md#internal--deep-import-only).
+
+### System dialogs
+
+```ts
+const SYSTEM_DIALOG_TAGS: ReadonlySet<string>;
+// "Dialog" | "StandardMessageDialog" | "StandardDialog"
+// | "ProblemDialog" | "KeyboardDialog" | "PinEntryDialog"
+```
+
+### Baselines
+
+```ts
+const SUPPORTED_VIDEO_MODES: ReadonlySet<string>;
+// "720p" | "720p60" | "1080p" | "1080p60"
+
+const BASELINE_RESOLUTION_DIR = { hd: "hd", fhd: "fhd" };
+```
+
+### Failure bundles
+
+```ts
+const FAILURES_DIR = "failures";
+const FAILURE_ARTIFACT_FILE = {
+    SCREENSHOT: "screenshot.png",
+    DOM_TREE: "dom-tree.json",
+    RECENT_LOGS: "recent-logs.txt",
+    ERROR: "error.txt"
+} as const;
+const FAILURE_RECENT_LOG_LINES = 100;
+```
+
+### Diagnostics text
+
+```ts
+const TREE_SUMMARY_MAX_DEPTH = 3;
+const TREE_SUMMARY_MAX_CHARS = 2_000;
+const TREE_DIFF_SNIPPET_MAX_CHARS = 200;
+const WAIT_FOR_LOG_RECENT_LINES_MAX = 20;
+const WAIT_FOR_LOG_RECENT_CHARS_MAX = 600;
+```
+
+### Handoff + daemon
+
+```ts
+const ROKU_LOG_PORT = 8085;
+const DEFAULT_RK_SERVER_URL = "http://localhost:3737/api";
+const DEVICE_IP_CACHE_FILE = ".device-ip";
+
+const ARTIFACT_FILE = {
+    DEVICE_ENV: "device-env.json",
+    JUNIT: "junit.xml",
+    DEVICE_LOG: "device.log"
+} as const;
+```
+
+## `test-results/` layout
+
+```
+test-results/
+├── .device-ip                         # resolved IP, written by globalSetup
+├── device-env.json                    # DeviceInfo snapshot + lease provenance
+├── device.log                         # every buffered log line, with header
+├── junit.xml                          # if a junit reporter is wired
+├── diffs/
+│   └── home--initial.diff.png         # screenshot mismatch artifacts
+└── failures/
+    └── grid--grid-scroll--renders-12-items/
+        ├── screenshot.png
+        ├── dom-tree.json
+        ├── recent-logs.txt
+        └── error.txt
+```
+
+All files are **rewritten on every run** — `cleanArtifacts` inside
+`createGlobalSetup` wipes the directory (preserving only
+`.gitkeep`) before the suite starts. Commit a `.gitkeep` if you want
+the directory to exist in the repo.
+
+Artifact filenames are stable constants (`ARTIFACT_FILE` and
+`FAILURE_ARTIFACT_FILE`); CI reporters that upload them can rely on
+the shape.