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

package/src/client/factory.ts

@@ -0,0 +1,170 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `createDefaultClient` — env-driven `RkClient` factory.
+ *
+ * Extracted from `client.ts` so the file containing the `RkClient`
+ * class stays focused on ECP + log/screenshot/DOM orchestration.
+ * `client.ts` re-exports `createDefaultClient` for public-API
+ * compatibility.
+ *
+ * Sync on purpose — see `device-resolver.ts` doc comment for the
+ * full rationale. The resolver consults, in order:
+ *   1. `RK_DEVICE_IP` env var, then
+ *   2. `<testResultsDir>/.device-ip` written by `globalSetup`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+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 { DeploymentDriver, DeviceInfo, RkClientOptions } from "../types";
+import { RkClient } from "./client";
+
+/**
+ * Constructs an `RkClient` configured from process env. Single source of
+ * truth for client construction; used by both `setup.ts` (worker-side)
+ * and `global-setup.ts` (host-side).
+ */
+export function createDefaultClient(opts: RkClientOptions = {}): RkClient {
+    const resultsDir = defaultTestResultsDir();
+    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()
+    });
+
+    // If globalSetup already wrote a device-env.json snapshot, seed
+    // the worker-side cache from it so tests can call
+    // `client.cachedDeviceInfo()` without a second ECP round-trip.
+    //
+    // Schema-validate before seeding: a corrupted snapshot (truncated
+    // write, hand-edited junk, half-overwritten file) used to be cast
+    // to `DeviceInfo` and silently used to drive baseline selection
+    // (`hd` vs `fhd`) and precondition gating (`firmwareVersion`,
+    // `deviceClass`). The corrupted values then produced wrong
+    // baselines / wrong skip decisions WITHOUT a single warning,
+    // which is exactly the failure mode this gate is supposed to
+    // prevent.
+    //
+    // Failure modes are now distinguished:
+    //   - file unreadable / not JSON          → warn + skip seeding
+    //   - JSON parses but shape is wrong      → warn + skip seeding
+    //   - JSON parses and matches `DeviceInfo`→ seed (happy path)
+    // In every case the explicit `queryDeviceInfo()` call still
+    // works, so we degrade to a slower-but-correct path rather than
+    // failing closed.
+    const envFile = join(resultsDir, ARTIFACT_FILE.DEVICE_ENV);
+    if (existsSync(envFile)) {
+        try {
+            const raw = readFileSync(envFile, "utf8");
+            const parsed = JSON.parse(raw);
+            const validation = validateDeviceInfo(parsed);
+            if (validation.ok) {
+                client.seedDeviceInfo(validation.value);
+            } else {
+                console.warn(
+                    `[device-test-client] Ignoring corrupted device-env snapshot at "${envFile}": ` +
+                        `${validation.reason}. Falling back to live queryDeviceInfo() — baseline ` +
+                        `selection and preconditions will work but a stale/junk snapshot won't ` +
+                        `silently mislead them.`
+                );
+            }
+        } catch (err) {
+            console.warn(
+                `[device-test-client] Failed to read device-env snapshot at "${envFile}": ` +
+                    `${(err as Error).message}. Cache left empty.`
+            );
+        }
+    }
+
+    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);
+    return raw && Number.isFinite(n) && n > 0 ? n : DEFAULT_KEY_DELAY;
+}
+
+type ValidationResult<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+/**
+ * Narrow-checks a value against `DeviceInfo`. Hand-rolled (no zod)
+ * because this is the only place we validate this shape and the
+ * cost of an extra runtime dep is not worth it. Returns the typed
+ * value on success and a human-readable reason on failure so the
+ * warn-log is actionable.
+ *
+ * Required: every string field of `DeviceInfo` must be a non-empty
+ * string, and `libraries` must be a string→string record.
+ *
+ * Exported with an underscore-prefix because it's intentionally
+ * tested in isolation — callers should go through
+ * `createDefaultClient` which decides what to do on validation
+ * failure (currently: warn + skip seeding).
+ */
+export function __validateDeviceInfoForTesting(value: unknown): ValidationResult<DeviceInfo> {
+    return validateDeviceInfo(value);
+}
+
+function validateDeviceInfo(value: unknown): ValidationResult<DeviceInfo> {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {
+            ok: false,
+            reason: `expected an object, got ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`
+        };
+    }
+    const v = value as Record<string, unknown>;
+    const stringFields: ReadonlyArray<keyof DeviceInfo> = [
+        "modelName",
+        "modelNumber",
+        "modelFamily",
+        "deviceClass",
+        "firmwareVersion",
+        "videoMode",
+        "locale",
+        "country"
+    ];
+    for (const field of stringFields) {
+        const fv = v[field as string];
+        if (typeof fv !== "string" || fv.length === 0) {
+            return { ok: false, reason: `field "${String(field)}" must be a non-empty string (got ${typeof fv})` };
+        }
+    }
+    if (typeof v.libraries !== "object" || v.libraries === null || Array.isArray(v.libraries)) {
+        return { ok: false, reason: `field "libraries" must be a string→string object` };
+    }
+    for (const [k, libVal] of Object.entries(v.libraries as Record<string, unknown>)) {
+        if (typeof libVal !== "string") {
+            return { ok: false, reason: `libraries["${k}"] must be a string (got ${typeof libVal})` };
+        }
+    }
+    return { ok: true, value: v as unknown as DeviceInfo };
+}

package/src/client/health.ts

@@ -0,0 +1,345 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Per-process device-health flags. Tests that detect a system
+ * dialog, crash, or unrecoverable condition flip them so subsequent
+ * tests cascade-abort in `beforeEach`.
+ *
+ * Two distinct flags, intentionally separate:
+ *
+ *   1. SOFT health (`deviceHealthy`) — flipped by `markDeviceUnhealthy`,
+ *      cleared by `resetDeviceHealth`. Models a *recoverable* fault:
+ *      a crash/reboot the device can come back from. The deploy-guard
+ *      retry loop and `installDeviceTestHooks`' recovery `beforeEach`
+ *      both clear it after a successful liveness probe.
+ *
+ *   2. FATAL latch (`deviceFatal`) — flipped by `markDeviceFatal`,
+ *      NEVER cleared in production (only the test-only reset clears it).
+ *      Models an *unrecoverable-on-this-VM* fault: the device answers
+ *      ECP and the sideload installer, but it refuses to foreground a
+ *      freshly-sideloaded dev channel ("never left home screen"). No
+ *      amount of `waitForDeviceFullyReady` / reboot-wait can cure that
+ *      from inside the test process — the device host has to be
+ *      recycled. Retrying on the wedged VM only burns the per-attempt
+ *      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
+ *      cell script reads it AFTER Jest exits to tell an unrecoverable
+ *      VM wedge (release the lease, re-acquire a fresh instance, retry
+ *      once) apart from an ordinary test failure (propagate). The
+ *      marker is opt-in via env so unit tests and local runs never
+ *      touch the filesystem, and it lives OUTSIDE `test-results/`
+ *      (which Jest's globalSetup wipes per run).
+ *
+ * Critically, `resetDeviceHealth()` clears ONLY the soft flag. The
+ * fatal latch deliberately survives it: the deploy-guard resets soft
+ * health between attempts, and if that also cleared the fatal latch
+ * the loop would keep retrying a VM that can never launch.
+ *
+ * Load-bearing: single-process execution (Jest `--runInBand`).
+ *
+ * CROSS-FILE LATCH. Jest sandboxes every test FILE in its own module
+ * registry — even under `--runInBand` (which only means "one worker,
+ * serial", NOT "shared module state"). So the in-memory `deviceFatal`
+ * singleton below RESETS to `false` at the start of every test file.
+ * Within a file the latch cascades fine; across files it would not,
+ * and each fresh file would re-pay the full deploy + recovery budget
+ * (~60s) rediscovering a wedge an earlier file already proved — the
+ * shard-wide, ~hour-long waste this module exists to eliminate.
+ *
+ * The ON-DISK sentinel (`RK_DEVICE_FATAL_SENTINEL`) is the only state
+ * that survives a module-registry reset, so it — not the in-memory
+ * flag — is the source of truth for the cross-file cascade.
+ * `markDeviceFatal` writes it on the first latch and `isDeviceFatal()`
+ * rehydrates the in-memory latch from it, so the first deploy in every
+ * subsequent file short-circuits in `beforeAll` instead of deploying.
+ * The CI cell still reads the same sentinel AFTER Jest exits to decide
+ * whether to recycle the lease.
+ *
+ * The only sanctioned mid-run reset is the `deviceRecovery` hook in
+ * `installDeviceTestHooks`, and it refuses to recover once the fatal
+ * latch is set. Forked workers would silently bypass the cascade.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+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;
+}
+
+/**
+ * Flip the soft health flag, remembering the FIRST reason as root
+ * cause so cascade-detection messages don't obscure it.
+ */
+export function markDeviceUnhealthy(reason: string): void {
+    if (!deviceHealthy) return;
+    deviceHealthy = false;
+    unhealthyReason = reason;
+    console.warn(`[device-test-client] device marked unhealthy: ${reason}`);
+}
+
+/** Last reason that flipped the soft health flag, or `null` if still healthy. */
+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.
+ * Idempotent (first reason wins, single warn) like `markDeviceUnhealthy`.
+ *
+ * Also flips the soft health flag so the existing `beforeEach` cascade
+ * and `getUnhealthyReason()` consumers keep working unchanged — callers
+ * never need to call both. `resetDeviceHealth()` clears the soft flag
+ * but NOT this latch, so once a VM is declared wedged every subsequent
+ * deploy/recovery short-circuits instead of re-probing a dead instance.
+ */
+export function markDeviceFatal(reason: string): void {
+    // Flip soft health first (idempotent; preserves an earlier soft
+    // reason as root cause) so the cascade keeps firing even if a
+    // softer fault was recorded before the fatal diagnosis.
+    markDeviceUnhealthy(reason);
+    if (deviceFatal) return;
+    deviceFatal = true;
+    fatalReason = reason;
+    // Drop the recycle marker exactly once, on the first latch, so the
+    // CI cell can re-acquire a fresh instance and retry (see doc-block).
+    writeFatalSentinel(reason);
+    console.warn(
+        `[device-test-client] device marked FATAL (unrecoverable on this VM): ${reason}. ` +
+            `The device answers ECP/installer probes but will not foreground a sideloaded ` +
+            `channel — recovery cannot cure this. The device host must be recycled; ` +
+            `remaining suites will skip their deploys instead of retrying.`
+    );
+}
+
+/**
+ * Best-effort recycle marker for the CI cell. When
+ * `RK_DEVICE_FATAL_SENTINEL` names a path, write a one-line JSON marker
+ * the instant the fatal latch flips; the cell script reads it after
+ * Jest exits to decide whether to release + re-acquire a fresh instance
+ * and retry. Deliberately NOT exported — production code outside this
+ * module has no reason to forge a recycle signal.
+ *
+ * Opt-in via env so unit tests and local runs never touch the
+ * filesystem. A write failure is swallowed on purpose: the cascade
+ * `console.warn` and the thrown `DeviceUnhealthyError` already carry the
+ * reason, so a missing marker degrades to today's fail-fast behaviour
+ * rather than masking the underlying fatal.
+ */
+function writeFatalSentinel(reason: string): void {
+    const sentinelPath = process.env.RK_DEVICE_FATAL_SENTINEL;
+    if (!sentinelPath) return;
+    try {
+        writeFileSync(sentinelPath, `${JSON.stringify({ reason, ts: new Date().toISOString() })}\n`, "utf8");
+    } catch {
+        // best-effort — see doc-block.
+    }
+}
+
+/**
+ * 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.
+ *
+ * Jest gives every test FILE a fresh module registry, so an earlier
+ * file's `markDeviceFatal` does NOT survive in `deviceFatal` here — only
+ * the sentinel it wrote to disk does. Reading it back is what makes the
+ * fatal latch a true CROSS-FILE cascade: the first deploy in every
+ * subsequent file sees `isDeviceFatal()` and short-circuits instead of
+ * paying the ~60s deploy + recovery budget to rediscover the same wedge.
+ *
+ * Once latched in-memory we never re-read (cheap, and the flag never
+ * un-sets within a process). A negative result is re-checked on each
+ * call because the sentinel can appear partway through the run.
+ * Existence is the signal; a malformed/unreadable file still latches
+ * with a fallback reason rather than letting the cascade leak.
+ */
+function hydrateFatalFromSentinel(): void {
+    if (deviceFatal) return;
+    const sentinelPath = process.env.RK_DEVICE_FATAL_SENTINEL;
+    if (!sentinelPath || !existsSync(sentinelPath)) return;
+    deviceFatal = true;
+    try {
+        const parsed = JSON.parse(readFileSync(sentinelPath, "utf8")) as { reason?: unknown };
+        fatalReason =
+            typeof parsed.reason === "string" && parsed.reason.length > 0
+                ? parsed.reason
+                : "device fatally wedged in a prior test file (see RK_DEVICE_FATAL_SENTINEL)";
+    } catch {
+        fatalReason = "device fatally wedged in a prior test file (see RK_DEVICE_FATAL_SENTINEL)";
+    }
+}
+
+/** `true` once the device has been latched as fatally wedged (this process or a prior test file). */
+export function isDeviceFatal(): boolean {
+    hydrateFatalFromSentinel();
+    return deviceFatal;
+}
+
+/** Reason the device was latched fatal, or `null` if not fatal. */
+export function getFatalReason(): string | null {
+    hydrateFatalFromSentinel();
+    return fatalReason;
+}
+
+/**
+ * Clear the SOFT health flag only. The fatal latch deliberately
+ * survives — see the module doc-block. The deploy-guard and recovery
+ * `beforeEach` call this between attempts; clearing the fatal latch
+ * here would defeat the whole fail-fast contract.
+ */
+export function resetDeviceHealth(): void {
+    deviceHealthy = true;
+    unhealthyReason = null;
+}
+
+/**
+ * Test-only: clear BOTH the soft flag and the fatal latch so unit
+ * tests don't leak the process-lifetime fatal state across cases.
+ * NOT exported via `index.ts` — production code has no legitimate
+ * reason to un-wedge a device mid-run.
+ */
+export function __resetDeviceHealthForTests(): void {
+    deviceHealthy = true;
+    unhealthyReason = null;
+    deviceFatal = false;
+    fatalReason = null;
+    foregroundedDeviceIp = null;
+    foregroundFailureStreak = 0;
+}

package/src/client/parsers.ts

@@ -0,0 +1,162 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Pure parsing helpers for ECP XML responses. Extracted from
+ * `client.ts` so they can be unit-tested without an `RkClient`.
+ * No network, no fs, no module state.
+ */
+
+import type { ActiveAppInfo, AppUiNode, DeviceInfo } from "../types";
+
+/**
+ * Tuple tree produced by `xmlToJson`. Tooling types children as
+ * `unknown[]`; we narrow at each recursion step.
+ */
+export type NodeTuple = [string, Record<string, string>, Array<NodeTuple | string>];
+
+/** Runtime cast of the `xmlToJson` return into our strict `NodeTuple` shape. */
+export function asNodeTuple(
+    raw: [string, Record<string, string>, Array<[string, Record<string, string>, unknown[]] | string>] | null
+): NodeTuple | null {
+    return raw as NodeTuple | null;
+}
+
+export function tupleToAppUiNode(tuple: NodeTuple): AppUiNode {
+    const [tag, attrs, rawChildren] = tuple;
+    const children: AppUiNode[] = [];
+    for (const child of rawChildren) {
+        // Skip text nodes (whitespace or stray label literals).
+        if (typeof child !== "string") children.push(tupleToAppUiNode(child));
+    }
+    // ECP serializes SceneGraph `id` as XML `name=`; mirror it back
+    // to `id` so JSX-style selectors work. Raw `attrs.name` still
+    // available for callers that want it.
+    const normalizedAttrs = { ...attrs };
+    if (normalizedAttrs.id === undefined && normalizedAttrs.name !== undefined) {
+        normalizedAttrs.id = normalizedAttrs.name;
+    }
+    return {
+        tag,
+        attrs: normalizedAttrs,
+        bounds: parseBounds(attrs.bounds),
+        focused: attrs.focused === "true",
+        children
+    };
+}
+
+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}"`. 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 = BOUNDS_PATTERN.exec(raw);
+    if (!match) return zero;
+    return {
+        x: Number(match[1]),
+        y: Number(match[2]),
+        width: Number(match[3]),
+        height: Number(match[4])
+    };
+}
+
+/**
+ * Map ECP `/query/device-info` to the `DeviceInfo` contract.
+ * - `modelName`: `model-name` then `friendly-model-name`.
+ * - `modelFamily`: `vendor-name` + `model-name` (ECP has no
+ *   explicit family field).
+ * - `deviceClass`: `is-tv`/`is-stick` boolean flags → `tv|stick|player`.
+ * - `videoMode`: `video-mode` then `ui-resolution` (Streaming
+ *   Stick 4K firmware 15.x lacks `video-mode`).
+ * - `libraries`: every `*-version` key not in `CORE_VERSION_FIELDS`.
+ */
+export function parseDeviceInfo(raw: Record<string, string>): DeviceInfo {
+    const modelName = raw["model-name"] ?? raw["friendly-model-name"] ?? "";
+    const vendor = raw["vendor-name"] ?? "";
+    const modelFamily = vendor && modelName ? `${vendor} ${modelName}` : modelName || vendor;
+
+    let deviceClass: string;
+    if (raw["is-tv"] === "true") deviceClass = "tv";
+    else if (raw["is-stick"] === "true") deviceClass = "stick";
+    else deviceClass = "player";
+
+    return {
+        modelName,
+        modelNumber: raw["model-number"] ?? "",
+        modelFamily,
+        deviceClass,
+        firmwareVersion: raw["software-version"] ?? "",
+        videoMode: raw["video-mode"] ?? raw["ui-resolution"] ?? "",
+        locale: raw["locale"] ?? "",
+        country: raw["user-country"] ?? raw["country"] ?? "",
+        libraries: extractLibraries(raw)
+    };
+}
+
+const CORE_VERSION_FIELDS = new Set([
+    "software-version",
+    "software-build",
+    "build-version",
+    "udn-version",
+    "channel-version"
+]);
+
+function extractLibraries(raw: Record<string, string>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!key.endsWith("-version")) continue;
+        if (CORE_VERSION_FIELDS.has(key)) continue;
+        const name = key.slice(0, -"-version".length);
+        if (name.length === 0) continue;
+        out[name] = value;
+    }
+    return out;
+}
+
+export function parseActiveApp(root: NodeTuple): ActiveAppInfo {
+    const [, , children] = root;
+    for (const child of children) {
+        if (typeof child === "string") continue;
+        const [tag, attrs, inner] = child;
+        if (tag !== "app") continue;
+        let title = "";
+        for (const ic of inner) {
+            if (typeof ic === "string") {
+                title = ic.trim();
+                break;
+            }
+        }
+        return {
+            id: attrs.id ?? "",
+            title,
+            type: attrs.type ?? "",
+            uiLocation: attrs["ui-location"] ?? ""
+        };
+    }
+    return { id: "", title: "", type: "", uiLocation: "" };
+}
+
+/**
+ * True when the active app is a home surface rather than a channel.
+ *
+ * Firmware ships several. The classic home screen reports `<app>Roku</app>`
+ * with no attributes at all. native_tv builds instead report real apps:
+ * `native-ui` (`type="appl"`) while the transition settles, then Roku
+ * Dynamic Menu (`id="562859"`, `type="home"`). `ui-location` is what
+ * separates any of them from a channel, because a foregrounded channel
+ * reports its own id there and never `"home"`.
+ *
+ * The `id`/`title` arms are kept for firmware that omits both `type` and
+ * `ui-location`.
+ */
+export function isHomeScreenActiveApp(active: ActiveAppInfo): boolean {
+    return active.type === "home" || active.uiLocation === "home" || active.id === "" || active.title === "Roku";
+}