@roku-sdk/device-test-client 2.18.0 → 2.19.1

package/src/client/deploy.ts

@@ -265,14 +265,19 @@ export async function requestServerBuild(serverUrl: string, payload: ServerBuild
     }
 }
 
-export function buildLaunchUrl(ip: string, channelId: string, deepLink?: Record<string, string>): string {
-    const base = `http://${ip}:${ECP_PORT}/launch/${encodeURIComponent(channelId)}`;
+/** Path and query of an ECP launch request, independent of any host. */
+export function buildLaunchPath(channelId: string, deepLink?: Record<string, string>): string {
+    const base = `/launch/${encodeURIComponent(channelId)}`;
     if (!deepLink || Object.keys(deepLink).length === 0) return base;
     const params = new URLSearchParams();
     for (const [k, v] of Object.entries(deepLink)) params.append(k, v);
     return `${base}?${params.toString()}`;
 }
 
+export function buildLaunchUrl(ip: string, channelId: string, deepLink?: Record<string, string>): string {
+    return `http://${ip}:${ECP_PORT}${buildLaunchPath(channelId, deepLink)}`;
+}
+
 /**
  * POST a no-body ECP request with the caller's timeout. Throws
  * `ToolingError` with the standard tooling code taxonomy so retry

package/src/client/factory.ts

@@ -20,7 +20,7 @@ import { join } from "node:path";
 import { ARTIFACT_FILE, DEFAULT_KEY_DELAY, ENV_VAR } from "../constants";
 import { resolveDeviceIpSync } from "../device/device-resolver-sync";
 import { defaultTestResultsDir } from "../paths";
-import type { DeviceInfo, RkClientOptions } from "../types";
+import type { DeploymentDriver, DeviceInfo, RkClientOptions } from "../types";
 import { RkClient } from "./client";
 
 /**
@@ -30,9 +30,11 @@ import { RkClient } from "./client";
  */
 export function createDefaultClient(opts: RkClientOptions = {}): RkClient {
     const resultsDir = defaultTestResultsDir();
-    const deviceIp = opts.deviceIp ?? resolveDeviceIpSync(resultsDir);
+    const driver = opts.driver ?? loadDriverFromEnv();
+    const deviceIp = driver ? opts.deviceIp : (opts.deviceIp ?? resolveDeviceIpSync(resultsDir));
     const client = new RkClient({
         ...opts,
+        driver,
         deviceIp,
         keyDelay: opts.keyDelay ?? envKeyDelay()
     });
@@ -84,6 +86,27 @@ export function createDefaultClient(opts: RkClientOptions = {}): RkClient {
     return client;
 }
 
+/**
+ * `RK_DEVICE_DRIVER_MODULE` names a module providing the deployment driver
+ * (see `DeploymentDriver`). Loaded synchronously: client construction is sync.
+ */
+function loadDriverFromEnv(): DeploymentDriver | undefined {
+    const modulePath = process.env[ENV_VAR.RK_DEVICE_DRIVER_MODULE];
+    if (!modulePath) return undefined;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require(modulePath) as {
+        createDeploymentDriver?: () => DeploymentDriver;
+        default?: () => DeploymentDriver;
+    };
+    const factory = mod.createDeploymentDriver ?? mod.default;
+    if (typeof factory !== "function") {
+        throw new Error(
+            `${ENV_VAR.RK_DEVICE_DRIVER_MODULE}=${modulePath} must export createDeploymentDriver() (or a default factory).`
+        );
+    }
+    return factory();
+}
+
 function envKeyDelay(): number {
     const raw = process.env[ENV_VAR.KEY_DELAY];
     const n = Number(raw);

package/src/client/health.ts

@@ -24,6 +24,17 @@
  *      budget × every remaining suite (the ~20-minute waste this latch
  *      exists to eliminate).
  *
+ *      Because the latch is this expensive to get wrong — it fails the
+ *      whole shard and recycles the lease — it requires the device to
+ *      have no record of ever foregrounding a channel, and the failing
+ *      deploy's device log to show no launch of its own. A deploy that saw
+ *      one on screen calls `markChannelForegrounded`, and from then on a
+ *      stalled launch on that VM is reported as the soft, recoverable
+ *      fault it is indistinguishable from. A deploy whose log shows its
+ *      channel entering is soft for the same reason: the VM can start
+ *      one. Both stay soft only until `noteForegroundFailure`'s streak
+ *      reaches its limit.
+ *
  *      Recycling is the CELL's job, not this process's. When
  *      `RK_DEVICE_FATAL_SENTINEL` names a path, `markDeviceFatal` drops
  *      a one-line JSON marker there the instant the latch flips. The CI
@@ -70,6 +81,9 @@ let deviceHealthy = true;
 let unhealthyReason: string | null = null;
 let deviceFatal = false;
 let fatalReason: string | null = null;
+let foregroundedDeviceIp: string | null = null;
+/** Deploys in a row that failed to foreground the channel; reset by any success. */
+let foregroundFailureStreak = 0;
 
 export function isDeviceHealthy(): boolean {
     return deviceHealthy;
@@ -91,6 +105,59 @@ export function getUnhealthyReason(): string | null {
     return unhealthyReason;
 }
 
+/**
+ * Record that `deviceIp` foregrounded a sideloaded channel — a deploy
+ * saw one on screen, so the VM is structurally capable of launching
+ * one. Keyed by IP because that is the granularity the fatal
+ * latch claims ("unrecoverable on THIS VM"): a re-leased slot is a
+ * different instance and starts with no history.
+ *
+ * Persisted beside the recycle sentinel for the same reason it exists —
+ * Jest's per-file module registry reset (see doc-block) would otherwise
+ * drop the evidence between test files, which is exactly where the
+ * misdiagnosis it prevents occurs: one file foregrounds the app, the
+ * next file's deploy stalls and, remembering nothing, declares the VM
+ * incapable of what the previous file just watched it do.
+ */
+export function markChannelForegrounded(deviceIp: string): void {
+    if (foregroundedDeviceIp === deviceIp && foregroundFailureStreak === 0) return;
+    foregroundedDeviceIp = deviceIp;
+    // A channel on screen ends whatever streak was building: the next
+    // failure starts counting from a VM that just demonstrably worked.
+    foregroundFailureStreak = 0;
+    writeLaunchEvidence(deviceIp);
+}
+
+/**
+ * Record a deploy that never got the channel on screen, and report how
+ * many have now failed in a row on `deviceIp`.
+ *
+ * Launch history alone cannot separate a bad launch from a VM that
+ * worked and then died, because both look identical from inside the
+ * failing deploy. The streak separates them over time: a transient
+ * stall is followed by a channel on screen, which resets it, while a
+ * dead VM only ever adds to it. Persisted beside the launch evidence
+ * and for the same reason — Jest's per-file registry reset would
+ * otherwise restart the count in every file, which is precisely the
+ * span over which a wedge has to be recognised.
+ */
+export function noteForegroundFailure(deviceIp: string): number {
+    if (foregroundedDeviceIp !== deviceIp) {
+        hydrateLaunchEvidenceFor(deviceIp);
+    }
+    foregroundFailureStreak += 1;
+    writeLaunchEvidence(deviceIp);
+    return foregroundFailureStreak;
+}
+
+/** `true` once `deviceIp` has been seen foregrounding a sideloaded channel (this process or a prior test file). */
+export function hasForegroundedChannel(deviceIp: string): boolean {
+    if (foregroundedDeviceIp !== deviceIp) {
+        hydrateLaunchEvidenceFor(deviceIp);
+    }
+    return foregroundedDeviceIp === deviceIp;
+}
+
 /**
  * Latch the device as FATALLY wedged: reachable on the network but
  * structurally unable to foreground a sideloaded channel on this VM.
@@ -145,6 +212,68 @@ function writeFatalSentinel(reason: string): void {
     }
 }
 
+/**
+ * Path of the launch-evidence marker: a sibling of the recycle sentinel,
+ * so one env var configures the whole wedge-classification state and the
+ * two files share a lifetime. `undefined` (env unset) keeps local runs
+ * and unit tests off the filesystem, at the cost of evidence that does
+ * not cross test files — the same opt-in trade the sentinel makes.
+ *
+ * The marker records the IP it was written for, so a file left behind by
+ * an earlier job on a reused workspace is inert: a later lease answers on
+ * a different IP and the evidence simply does not match.
+ */
+function launchEvidencePath(): string | undefined {
+    const sentinelPath = process.env.RK_DEVICE_FATAL_SENTINEL;
+    return sentinelPath ? `${sentinelPath}.launched` : undefined;
+}
+
+/** Best-effort, like `writeFatalSentinel`: a lost marker degrades to today's stricter verdict, never to a missed wedge. */
+function writeLaunchEvidence(deviceIp: string): void {
+    const path = launchEvidencePath();
+    if (!path) return;
+    try {
+        const record = {
+            deviceIp,
+            ts: new Date().toISOString(),
+            foregrounded: foregroundedDeviceIp === deviceIp,
+            failures: foregroundFailureStreak
+        };
+        writeFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+    } catch {
+        // best-effort — see doc-block.
+    }
+}
+
+/** Adopt the on-disk launch evidence when it was recorded for `deviceIp`. */
+function hydrateLaunchEvidenceFor(deviceIp: string): void {
+    const path = launchEvidencePath();
+    if (!path || !existsSync(path)) return;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8")) as {
+            deviceIp?: unknown;
+            foregrounded?: unknown;
+            failures?: unknown;
+        };
+        if (parsed.deviceIp === deviceIp) {
+            // A streak can be recorded for a device that has never put a
+            // channel on screen; only an explicit `false` says so.
+            if (parsed.foregrounded !== false) {
+                foregroundedDeviceIp = deviceIp;
+            }
+            // A marker written before the streak existed, or with a
+            // junk count, reads as no failures — the stricter verdict
+            // is the fatal one, so an unreadable count must not latch it.
+            foregroundFailureStreak =
+                typeof parsed.failures === "number" && Number.isFinite(parsed.failures) && parsed.failures > 0
+                    ? Math.floor(parsed.failures)
+                    : 0;
+        }
+    } catch {
+        // Unreadable evidence proves nothing; leave the stricter verdict in place.
+    }
+}
+
 /**
  * Rehydrate the in-memory fatal latch from the on-disk sentinel.
  *
@@ -211,4 +340,6 @@ export function __resetDeviceHealthForTests(): void {
     unhealthyReason = null;
     deviceFatal = false;
     fatalReason = null;
+    foregroundedDeviceIp = null;
+    foregroundFailureStreak = 0;
 }

package/src/client/parsers.ts

@@ -44,14 +44,21 @@ export function tupleToAppUiNode(tuple: NodeTuple): AppUiNode {
     };
 }
 
+const BOUNDS_NUMBER = String.raw`(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)`;
+const BOUNDS_PATTERN = new RegExp(
+    String.raw`\{\s*${BOUNDS_NUMBER}\s*,\s*${BOUNDS_NUMBER}\s*,\s*${BOUNDS_NUMBER}\s*,\s*${BOUNDS_NUMBER}\s*\}`
+);
+
 /**
- * Parse a SceneGraph bounds string `"{x, y, w, h}"`. Returns a
- * zero rect on parse failure so callers don't branch on `null`.
+ * Parse a SceneGraph bounds string `"{x, y, w, h}"`. Values are
+ * returned unrounded: a 720p device reports FHD-canvas bounds in
+ * float32, e.g. `"{250, 899.99994, 10, 10}"`. Returns a zero rect on
+ * parse failure so callers don't branch on `null`.
  */
 export function parseBounds(raw: string | undefined): AppUiNode["bounds"] {
     const zero = { x: 0, y: 0, width: 0, height: 0 };
     if (!raw) return zero;
-    const match = /\{\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*\}/.exec(raw);
+    const match = BOUNDS_PATTERN.exec(raw);
     if (!match) return zero;
     return {
         x: Number(match[1]),

package/src/constants.ts

@@ -14,6 +14,12 @@ export const ENV_VAR = {
      * `.roku/` active-device resolution. Must be a local-network IPv4.
      */
     RK_DEVICE_IP: "RK_DEVICE_IP",
+    /**
+     * Path to a module that default-exports (or exports `createDeploymentDriver`)
+     * a factory returning a `DeploymentDriver`. When set, `createDefaultClient`
+     * runs apps through the driver instead of a device and needs no device IP.
+     */
+    RK_DEVICE_DRIVER_MODULE: "RK_DEVICE_DRIVER_MODULE",
     /**
      * Roku developer-mode password. Set together with `RK_DEVICE_IP`
      * to bypass `.roku/roku-dev-config.json`. A partial pair is a
@@ -207,6 +213,19 @@ export const INSTALLER_PORT_TCP_TIMEOUT_MS = 1_500;
  */
 export const DEVICE_RECOVERY_DEFAULT_RETRIES = 3;
 
+/**
+ * Consecutive deploys that may fail to foreground the channel on a VM
+ * known to have foregrounded one earlier before the wedge is treated as
+ * fatal rather than as a bad launch.
+ *
+ * One file's full deploy-retry budget is allowed to fail softly, so a
+ * genuinely transient stall still resolves the way it always has; the
+ * next failure after that is a second file reaching the same verdict,
+ * which no amount of further retrying has ever cured. Derived from the
+ * retry budget so the two cannot drift apart.
+ */
+export const FOREGROUND_FAILURE_STREAK_FATAL = DEVICE_RECOVERY_DEFAULT_RETRIES + 1;
+
 /**
  * Default post-sideload readiness deadline. Covers cold-start on the
  * slowest reference hardware (Express ~3s, Ultra ~1s) with headroom
@@ -247,6 +266,24 @@ export const HOME_SCREEN_GRACE_FRACTION = 0.25;
  */
 export const HOME_SCREEN_GRACE_MIN_MS = 500;
 
+/**
+ * Launch requests the readiness gate re-sends, per deploy, when the
+ * device log shows the channel entering and then exiting with
+ * `EXIT_APP_ERROR`. Firmware 15.3.4 on virtualized hosts ends some
+ * launches that way right after a sideload, its TypeScript process still
+ * compiling the build `replace()` removed, and a launch of the same build
+ * a few seconds later succeeds. A build that crashes during mount exits
+ * the same way and pays at most this many extra launches per deploy.
+ */
+export const LAUNCH_CRASH_RELAUNCH_MAX = 2;
+
+/**
+ * Minimum spacing between two launch requests from the readiness gate.
+ * A relaunch also waits out the home-screen grace window, so InstantOn's
+ * own exit-and-relaunch is not raced.
+ */
+export const LAUNCH_CRASH_RELAUNCH_GAP_MS = 2_000;
+
 /**
  * Tag names of root-level system dialogs (e.g. "Display type detection").
  * Matching on tag at the root rules out app-authored `Dialog` subclasses
@@ -282,6 +319,9 @@ export const BASELINE_RESOLUTION_DIR = {
     fhd: "fhd"
 } as const;
 
+/** Build output directory the client uses for fixture apps, relative to the app root. */
+export const INTEGRATION_BUILD_OUT_DIR = "dist-integration-test";
+
 /** Filenames written under each consumer's `test-results/` directory. */
 export const ARTIFACT_FILE = {
     DEVICE_ENV: "device-env.json",
@@ -417,6 +457,15 @@ export const WAIT_FOR_LOG_RECENT_CHARS_MAX = 600;
  */
 export const SSE_PENDING_MAX_BYTES = 1_048_576;
 
+/**
+ * Grace window granted to a log assertion whose wait window stayed
+ * empty, measured from the re-attach it triggers. `/logs/tail`
+ * resolves readiness on its first status frame and emits the
+ * replayed buffer immediately after, so the lines land a round trip
+ * — not a device operation — later.
+ */
+export const LOG_STREAM_RESYNC_GRACE_MS = 1_000;
+
 /**
  * Default per-call idle timeout (ms) for the `POST /api/build` SSE
  * stream consumed by `requestServerBuild`. Sized for the worst-case

package/src/errors.ts

@@ -70,7 +70,8 @@ export type DeviceTestErrorCode =
     | "SCREENSHOT_BASELINE_MISSING"
     | "SCREENSHOT_DIMENSIONS_MISMATCH"
     | "SCREENSHOT_MASK"
-    | "SCREENSHOT_ALIGN_TOLERANCE";
+    | "SCREENSHOT_ALIGN_TOLERANCE"
+    | "SCREENSHOT_UNSUPPORTED_TARGET";
 
 /**
  * Shared base for every error type in this package. New code paths

package/src/index.ts

@@ -9,32 +9,27 @@
  * device resolvers, and sync device-env helpers are no longer part
  * of the documented API.
  *
- * **Internal symbols (not on the public surface):**
- * the `package.json` `exports` map no longer carries a `./src/*`
- * wildcard. Symbols deliberately kept off this barrel are reachable
- * ONLY via the dedicated, documented internal subpaths:
+ * **Harness support entry points.** The `package.json` `exports` map
+ * has no `./src/*` wildcard. Symbols kept off this barrel for harness
+ * code are on documented `./support/<name>` entry points:
  *
- *   - `@roku-sdk/device-test-client/internal/deploy` — `resolveAppPath`
- *     for the integration-test deploy guard's directory-wipe path.
- *   - `@roku-sdk/device-test-client/internal/constants` — the small
- *     subset of `src/constants.ts` symbols (currently `ARTIFACT_FILE`)
- *     that `*.config.ts` files load at parse time. The public barrel
- *     is unreachable from CommonJS-mode config loaders because it
- *     transitively pulls in `@roku-sdk/tooling` ESM (`import.meta.url`);
- *     this subpath bypasses the offending chain.
- *   - `@roku-sdk/device-test-client/internal/paths` — load-safe
+ *   - `@roku-sdk/device-test-client/support/deploy` — `resolveAppPath`
+ *     and `invalidateBuildCacheForApp` for a deploy guard that wipes
+ *     and rebuilds an app between retries.
+ *   - `@roku-sdk/device-test-client/support/constants` — the subset of
+ *     `src/constants.ts` (currently `ARTIFACT_FILE`) that `*.config.ts`
+ *     files load at parse time. This barrel is unreachable from
+ *     CommonJS-mode config loaders because it transitively pulls in
+ *     `@roku-sdk/tooling` ESM (`import.meta.url`); this entry point
+ *     bypasses that chain.
+ *   - `@roku-sdk/device-test-client/support/paths` — load-safe
  *     `test-results/` path helpers used by multi-device test setup.
  *
- * If a future internal symbol needs the same escape hatch, prefer
- * extending one of the existing `internal/<name>` subpaths (grouped
- * by concern: deploy-side helpers under `deploy`, config-load
- * constants under `constants`) rather than reintroducing the
- * wildcard or minting a parallel subpath. The wildcard was tech
- * debt that compounded — every `./src/<x>` deep import bound the
- * (already-internal) module topology into the published API surface
- * for consumers using `moduleResolution: "Node16"` or `"Bundler"`.
- * Named subpaths are grep-able, audit-able, and break loudly at
- * install time when a partner reaches for a symbol that has moved.
+ * The former `./internal/<name>` subpaths were removed (BREAKING_CHANGES.md).
+ * Prefer extending an existing `support/<name>` entry point over
+ * minting a parallel one, and never reintroduce the wildcard: every
+ * `./src/<x>` deep import bound the module topology into the
+ * published API surface.
  *
  * Constants surface (M14): `index.ts` no longer re-exports every
  * value in `constants.ts`. The curated set below covers the env

package/src/jest/global-setup.ts

@@ -69,6 +69,10 @@ export function createGlobalSetup(opts: GlobalSetupOptions): () => Promise<void>
         assertBaselineUpdatesAllowed();
         cleanArtifacts(opts.testResultsDir);
 
+        // A run through a deployment driver has no physical device to
+        // resolve, probe, or lease; each worker builds its own host.
+        if (process.env[ENV_VAR.RK_DEVICE_DRIVER_MODULE]) return;
+
         const ip = await resolveActiveDeviceIp();
         await persistDeviceIp(opts.testResultsDir, ip);
         process.env[ENV_VAR.RK_DEVICE_IP] = ip;

package/src/jest/install-hooks.ts

@@ -99,7 +99,8 @@ export const HOOK_NAMES = {
     DIFF_ROOT: "deviceTestHooks:diffRoot",
     DEVICE_INFO_CACHE: "deviceTestHooks:deviceInfoCache",
     LOG_SESSION_ATTACH: "deviceTestHooks:logSessionAttach",
-    LOG_SESSION_DETACH: "deviceTestHooks:logSessionDetach"
+    LOG_SESSION_DETACH: "deviceTestHooks:logSessionDetach",
+    DRIVER_RELEASE: "deviceTestHooks:driverRelease"
 } as const;
 
 /**
@@ -211,6 +212,7 @@ export function installDeviceTestHooks(opts: InstallDeviceTestHooksOptions = {})
 
     if (opts.client) {
         const client = opts.client;
+        namedAfterAll(HOOK_NAMES.DRIVER_RELEASE, () => client.releaseDriver());
         namedBeforeAll(HOOK_NAMES.DEVICE_INFO_CACHE, async () => {
             if (!client.cachedDeviceInfo()) {
                 await client.queryDeviceInfo();

package/src/logs/log-buffer.ts

@@ -202,15 +202,28 @@ export class LogBuffer {
 
     /**
      * First gap overlapping `[from, to ?? currentPosition)`.
-     * Half-open: `from == to` is empty. Includes the currently-open
-     * gap so a still-reconnecting stream is detectable mid-wait.
+     * Half-open, and includes the currently-open gap so a
+     * still-reconnecting stream is detectable mid-wait.
+     *
+     * `from == to` is an empty *line* range but not an empty
+     * question: a wait that received nothing while the stream was
+     * reconnecting is the case where "no lines" and "lines we never
+     * heard about" are indistinguishable, so an open gap still
+     * answers. Only an inverted range answers `null` outright.
      */
     hasGapWithin(from: LogPosition, to?: LogPosition): Gap | null {
         const fromN = parsePos(from);
         const toN = to !== undefined ? parsePos(to) : this.nextSeq;
-        if (toN <= fromN) return null;
+        if (toN < fromN) return null;
+        // Overlap is the wrong test for an empty range — nothing
+        // overlaps it — so ask instead whether a gap contains `fromN`
+        // itself, which is what `findGapContaining` means by tainted
+        // and what a gap closed at `[fromN, fromN + 1)` records. A gap
+        // lying entirely to either side stays excluded either way.
+        const empty = toN === fromN;
         for (const g of this.gaps) {
-            if (g.start < toN && g.end > fromN) return { ...g };
+            const reachesWindow = empty ? fromN >= g.start && fromN < g.end : g.start < toN && g.end > fromN;
+            if (reachesWindow) return { ...g };
         }
         if (this.openGapStart !== null) {
             // Open gap extends forward indefinitely; any un-arrived

package/src/logs/log-session.ts

@@ -72,6 +72,14 @@ export class LogSession {
     // Warn at most once per session for post-ready SSE errors so
     // a server burst doesn't flood CI logs.
     private postReadyErrorWarned = false;
+    // In-flight `resync()`, shared by concurrent callers.
+    private resyncPromise: Promise<void> | null = null;
+    // Bumped per `dispose()`, so a re-attach in flight can tell that
+    // the caller gave up on the subscription while it was opening.
+    private disposeCount = 0;
+    // Set by `dispose()`, cleared by an explicit `ensureStarted()`. While
+    // set there is no subscription to re-attach, so `resync()` is a no-op.
+    private disposed = false;
 
     constructor(opts: LogSessionOptions) {
         this.opts = opts;
@@ -90,6 +98,7 @@ export class LogSession {
      * daemon that comes back online isn't permanently rejected.
      */
     ensureStarted(): Promise<void> {
+        this.disposed = false;
         if (this.startPromise) return this.startPromise;
         this.startPromise = this.doStart().catch(err => {
             this.startPromise = null;
@@ -295,12 +304,65 @@ export class LogSession {
         this.postReadyErrorWarned = false;
     }
 
+    /**
+     * Drop the current subscription and open a fresh one.
+     *
+     * `/logs/tail` replays the whole server-side buffer on attach and
+     * `lastServerSeq` drops the duplicates, so a line the previous
+     * subscription never delivered still reaches the buffer — and
+     * through it any in-flight waiter, since `append` notifies
+     * subscribers. A subscription that stops delivering while the
+     * server still considers it active reports nothing and closes
+     * nothing, so re-attaching is the only way to find out whether
+     * the lines exist.
+     *
+     * Records no gap: a replay fills the window rather than losing
+     * it, and an open gap would mark the replayed lines themselves
+     * suspect, which is the opposite of the intent. Loss on the
+     * device→server leg is the server's own `reconnecting` status,
+     * which already marks a gap through `onStatus`.
+     *
+     * Concurrent callers share one re-attach. After `dispose()` it opens
+     * nothing: a waiter whose deadline fires once its test was torn down
+     * must not reopen the subscription the teardown closed.
+     */
+    resync(): Promise<void> {
+        if (this.resyncPromise) return this.resyncPromise;
+        if (this.disposed) return Promise.resolve();
+        const attempt = (async () => {
+            const generation = this.disposeCount;
+            this.teardownStream();
+            await this.ensureStarted();
+            // A `dispose()` that landed while we were attaching wins:
+            // the caller asked for no subscription, not a newer one.
+            // Without this a worker teardown can be followed by a
+            // fresh SSE socket opening behind it.
+            if (this.disposeCount !== generation) this.teardownStream();
+        })();
+        this.resyncPromise = attempt.finally(() => {
+            this.resyncPromise = null;
+        });
+        return this.resyncPromise;
+    }
+
     /**
      * Close the SSE subscription. Does NOT `/logs/stop` — global
      * teardown owns server-side lifecycle so cross-worker sessions
      * aren't torn down mid-suite.
      */
     dispose(): void {
+        this.disposed = true;
+        this.disposeCount += 1;
+        this.teardownStream();
+    }
+
+    /**
+     * Close the stream and clear the memoized session state so the
+     * next `ensureStarted()` re-runs `/logs/start` and reopens SSE.
+     * The buffer is deliberately untouched: its entries and gap
+     * records outlive any one subscription.
+     */
+    private teardownStream(): void {
         if (this.stream) {
             try {
                 this.stream.close();

package/src/types.ts

@@ -1,5 +1,7 @@
 // Copyright (c) 2026 Roku, Inc.
 // SPDX-License-Identifier: MIT
+import type { DeviceTarget } from "@roku-sdk/tooling/src/tooling-utils/device-target";
+
 export interface DeviceInfo {
     modelName: string;
     modelNumber: string;
@@ -369,7 +371,28 @@ export interface ActiveAppInfo {
 /** ECP request categories. Keys in `ECP_INTERVAL_MS` must match. */
 export type EcpCategory = "query-appui" | "query-device-info" | "query-active-app" | "keypress" | "launch" | "capture";
 
+/**
+ * A host that runs fixture apps in place of a physical device. The client
+ * deploys through it (instead of the rk server build + installer sideload)
+ * and then speaks ECP to the transport it returns. Lets a suite run against
+ * any host that answers ECP, without the specs knowing.
+ */
+export interface DeploymentDriver {
+    /** Short name used where a device IP would appear (artifact names, messages). */
+    readonly label: string;
+    /** Answers ECP before the first deploy (e.g. `/query/device-info`). */
+    readonly initialTarget: DeviceTarget;
+    /** Subscribe to the console lines of whichever app is running; returns the unsubscribe. */
+    onLog(listener: (line: string) => void): () => void;
+    /** Build and start the app at `absPath`; resolves with the transport to use for it. */
+    deploy(request: { absPath: string; launchParams?: Record<string, string> }): Promise<DeviceTarget>;
+    /** Stop whatever the driver started. Idempotent. */
+    release?(): Promise<void>;
+}
+
 export interface RkClientOptions {
+    /** Run apps through this driver instead of a device at `deviceIp`. */
+    driver?: DeploymentDriver;
     /** Device IPv4. Required directly; `createDefaultClient()` resolves from env/`.roku/`. */
     deviceIp?: string;
     /** Default inter-key delay for `keysequence` (ms). */
@@ -391,6 +414,12 @@ export interface RkClientOptions {
 export interface LogSessionLike {
     ensureStarted(): Promise<void>;
     dispose(): void;
+    /**
+     * Re-attach the subscription, recovering lines the current one
+     * stopped delivering. Optional so an injected fake stays valid
+     * without it; callers feature-detect and skip the recovery.
+     */
+    resync?(): Promise<void>;
     readonly buffer: LogBufferLike;
 }
 

package/support/constants.ts

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * `@roku-sdk/device-test-client/support/constants`: constants a Jest config can load at parse time.
+ *
+ * The package root re-exports `RkClient`, which loads `@roku-sdk/tooling`. That package is ESM
+ * and uses `import.meta.url`, so a CommonJS-mode loader parsing `jest.config.ts` (ts-node, or the
+ * loader Jest uses) fails with `ERR_REQUIRE_ESM` before any test runs. This entry point loads only
+ * `src/constants.ts`, whose imports are type-only, so a config file can import from it safely.
+ * The same values are also exported from the package root.
+ *
+ * Only add constants a config loader needs at parse time. The file sits at this physical path so
+ * it also resolves under `moduleResolution: "Node"`, which ignores the `exports` map.
+ */
+
+export { ARTIFACT_FILE, INTEGRATION_BUILD_OUT_DIR } from "../src/constants";

package/support/deploy.ts

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * `@roku-sdk/device-test-client/support/deploy`: deploy-guard helpers for test harnesses.
+ *
+ * These are for harness code that recovers from a bad deploy, not for test bodies. A harness
+ * that wipes an app's integration build output between deploy retries calls
+ * `invalidateBuildCacheForApp` with the same root, so the next `RkClient.buildAndDeploy` rebuilds
+ * instead of reusing a memoised result. Call the two together: wiping without invalidating
+ * sideloads an empty package, and invalidating without wiping rebuilds for nothing.
+ *
+ * A harness whose deployment driver sideloads through its own transport (rather than
+ * `RkClient.buildAndDeploy`) can reuse the build and manifest steps through `requestServerBuild`,
+ * `readAppTypeFromManifest` and `resolveServerUrl`.
+ *
+ * Importing this entry point loads `@roku-sdk/tooling`, which is ESM, so a CommonJS-mode config
+ * loader (ts-node parsing `jest.config.ts`) cannot load it. Config files should use
+ * `./support/constants` or `./support/paths`, which are safe to load at parse time.
+ *
+ * The file sits at this physical path, not just in the `exports` map, so it also resolves under
+ * `moduleResolution: "Node"`, which ignores `exports`.
+ */
+
+export { readAppTypeFromManifest, requestServerBuild, resolveAppPath } from "../src/client/deploy";
+export { resolveServerUrl } from "../src/client/server-url";
+export { invalidateBuildCacheForApp } from "../src/client/build-cache";