@putdotio/rokit 1.1.0 → 1.3.0

package/README.md

@@ -47,7 +47,13 @@ pnpm exec rokit screenshot artifacts/live/player.png
 App-specific scenario scripts can also import the generic helpers:
 
 ```ts
-import { assertSceneGraphNode, pressKey, querySceneGraph, type RokuContext } from "@putdotio/rokit";
+import {
+  assertSceneGraphNode,
+  pressKey,
+  querySceneGraph,
+  readNamedNodeTranslation,
+  type RokuContext,
+} from "@putdotio/rokit";
 
 const target = process.env.ROKIT_TARGET;
 
@@ -62,8 +68,9 @@ const context: RokuContext = {
 };
 
 await pressKey(context, "Info");
+const xml = await querySceneGraph(context, { attempts: 3 });
 await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
-await querySceneGraph(context);
+console.log(readNamedNodeTranslation(xml, "videoPlayerScreen"));
 ```
 
 ## Commands
@@ -88,13 +95,17 @@ rokit --version
   is reachable.
 - `device-info` prints enhanced Roku device metadata as JSON.
 - `active-app` prints the foreground app.
-- `wait-active` waits until the requested app is foregrounded.
+- `wait-active` waits until the requested app is foregrounded and tolerates
+  transient ECP read failures while polling.
 - `launch` opens an app and waits until it is active. Use repeated `--param`
-  values for deeplink parameters.
+  values for deeplink parameters. Roku launch responses can race app startup, so
+  launch accepts transient timeout/fetch failures and then verifies foreground
+  state.
 - `press` sends Roku remote keys through ECP. Use `--delay-ms` for navigation
   sequences that need a stable gap between keys.
 - `query` prints a raw ECP response such as `/query/sgnodes/all`.
-- `sgnodes` prints the raw SceneGraph tree from `/query/sgnodes/all`.
+- `sgnodes` prints the raw SceneGraph tree from `/query/sgnodes/all`. Library
+  callers can pass retry options to `querySceneGraph`.
 - `assert-node` checks a named SceneGraph node once.
 - `wait-node` polls SceneGraph until a named node condition matches.
 - `screenshot` saves a developer screenshot. It requires `ROKIT_PASSWORD`.
@@ -126,6 +137,7 @@ tokens, and app-specific media identifiers do not belong in git.
 - remote keypresses
 - raw ECP queries
 - SceneGraph state queries and named-node assertions
+- SceneGraph attribute, numeric geometry, bounds, and translation readers
 - screenshots
 
 App repositories should keep their own scenario commands for product behavior,

package/dist/index.d.mts

@@ -2,6 +2,8 @@ import * as rokuDeploy from "roku-deploy";
 
 //#region src/scenegraph.d.ts
 type NodeState = "absent" | "hidden" | "visible";
+type SceneGraphBounds = readonly [x: number, y: number, width: number, height: number];
+type SceneGraphPoint = readonly [x: number, y: number];
 type NodeExpectation = {
   readonly state: NodeState;
   readonly text?: string;
@@ -11,10 +13,14 @@ type NodeExpectation = {
 };
 declare const readNamedNodeAttributes: (xml: string, nodeName: string) => string | undefined;
 declare const readNamedNodeAttribute: (xml: string, nodeName: string, attributeName: string) => string | undefined;
+declare const readNamedNodeNumber: (xml: string, nodeName: string, attributeName: string) => number | undefined;
+declare const readNamedNodeBounds: (xml: string, nodeName: string) => SceneGraphBounds | undefined;
+declare const readNamedNodeTranslation: (xml: string, nodeName: string) => SceneGraphPoint | undefined;
 declare const isNamedNodeVisible: (xml: string, nodeName: string) => boolean;
 declare const assertNamedNode: (xml: string, nodeName: string, expectation: NodeExpectation) => void;
 declare const assertNamedNodeState: (xml: string, nodeName: string, state: NodeState) => void;
 declare const assertNamedNodeText: (xml: string, nodeName: string, expectedText: string) => void;
+declare const parseSceneGraphNumberList: (value: string) => number[];
 //#endregion
 //#region src/xml.d.ts
 type ActiveApp = {
@@ -42,6 +48,10 @@ type DeviceSummary = {
   readonly model: string;
   readonly name: string;
 };
+type RetryOptions = {
+  readonly attempts?: number;
+  readonly retryDelayMs?: number;
+};
 declare const checkDevice: (context: RokuContext) => Promise<DeviceSummary>;
 declare const getDeviceInfo: (context: RokuContext) => Promise<rokuDeploy.DeviceInfo>;
 declare const queryActiveApp: (context: RokuContext) => Promise<ActiveApp>;
@@ -49,7 +59,7 @@ declare const waitForActiveApp: (context: RokuContext, appId: string, timeoutMs?
 declare const launchApp: (context: RokuContext, appId: string, params?: ReadonlyMap<string, string>) => Promise<ActiveApp>;
 declare const pressKey: (context: RokuContext, key: string) => Promise<void>;
 declare const queryEcp: (context: RokuContext, path: string) => Promise<string>;
-declare const querySceneGraph: (context: RokuContext) => Promise<string>;
+declare const querySceneGraph: (context: RokuContext, options?: RetryOptions) => Promise<string>;
 declare const assertSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation) => Promise<void>;
 declare const waitForSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation, timeoutMs?: number) => Promise<void>;
 declare const installPackage: (context: RokuContext & {
@@ -60,4 +70,4 @@ declare const takeScreenshot: (context: RokuContext & {
 }, outputPath: string) => Promise<string>;
 declare const validateRemoteKey: (key: string) => void;
 //#endregion
-export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RokuContext, assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };
+export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphBounds, type SceneGraphPoint, assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { S as readXmlTag, _ as isNamedNodeVisible, a as launchApp, b as readActiveApp, c as queryEcp, d as validateRemoteKey, f as waitForActiveApp, g as assertNamedNodeText, h as assertNamedNodeState, i as installPackage, l as querySceneGraph, m as assertNamedNode, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot, v as readNamedNodeAttribute, x as readXmlAttribute, y as readNamedNodeAttributes } from "./roku-D-FxlWPE.mjs";
-export { assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };
+import { C as readNamedNodeTranslation, E as readXmlTag, S as readNamedNodeNumber, T as readXmlAttribute, _ as isNamedNodeVisible, a as launchApp, b as readNamedNodeAttributes, c as queryEcp, d as validateRemoteKey, f as waitForActiveApp, g as assertNamedNodeText, h as assertNamedNodeState, i as installPackage, l as querySceneGraph, m as assertNamedNode, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot, v as parseSceneGraphNumberList, w as readActiveApp, x as readNamedNodeBounds, y as readNamedNodeAttribute } from "./roku-7hiM97p0.mjs";
+export { assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as launchApp, c as queryEcp, f as waitForActiveApp, i as installPackage, l as querySceneGraph, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot } from "./roku-D-FxlWPE.mjs";
+import { a as launchApp, c as queryEcp, f as waitForActiveApp, i as installPackage, l as querySceneGraph, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot } from "./roku-7hiM97p0.mjs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";

package/dist/{roku-D-FxlWPE.mjs → roku-7hiM97p0.mjs}

@@ -28,6 +28,36 @@ const readNamedNodeAttribute = (xml, nodeName, attributeName) => {
 	if (!attributes) return;
 	return readXmlAttribute(attributes, attributeName);
 };
+const readNamedNodeNumber = (xml, nodeName, attributeName) => {
+	const value = readNamedNodeAttribute(xml, nodeName, attributeName);
+	if (value !== void 0) {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+	if (attributeName !== "width" && attributeName !== "height") return;
+	const bounds = readNamedNodeBounds(xml, nodeName);
+	if (!bounds) return;
+	return attributeName === "width" ? bounds[2] : bounds[3];
+};
+const readNamedNodeBounds = (xml, nodeName) => {
+	const bounds = readNamedNodeAttribute(xml, nodeName, "bounds");
+	if (!bounds) return;
+	const parts = parseSceneGraphNumberList(bounds);
+	if (parts.length < 4) return;
+	return [
+		parts[0],
+		parts[1],
+		parts[2],
+		parts[3]
+	];
+};
+const readNamedNodeTranslation = (xml, nodeName) => {
+	const translation = readNamedNodeAttribute(xml, nodeName, "translation");
+	if (!translation) return;
+	const parts = parseSceneGraphNumberList(translation);
+	if (parts.length < 2) return;
+	return [parts[0], parts[1]];
+};
 const isNamedNodeVisible = (xml, nodeName) => {
 	const attributes = readNamedNodeAttributes(xml, nodeName);
 	return attributes !== void 0 && !attributes.includes("visible=\"false\"");
@@ -59,6 +89,7 @@ const assertNamedNodeAttribute = (xml, nodeName, attributeName, expectedValue) =
 	if (value !== expectedValue) throw new Error(`expected "${nodeName}" ${attributeName} "${expectedValue}", got "${value ?? "missing"}"`);
 };
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const parseSceneGraphNumberList = (value) => value.replace(/[[\]{}]/g, "").split(",").map((part) => Number(part.trim())).filter((part) => Number.isFinite(part));
 //#endregion
 //#region src/roku.ts
 const ecpPort = 8060;
@@ -110,18 +141,27 @@ const queryActiveApp = async (context) => readActiveApp(await fetchText(context,
 const waitForActiveApp = async (context, appId, timeoutMs = 1e4) => {
 	const start = Date.now();
 	let lastApp;
+	let lastError;
 	while (Date.now() - start < timeoutMs) {
-		lastApp = await queryActiveApp(context);
+		try {
+			lastApp = await queryActiveApp(context);
+			lastError = void 0;
+		} catch (error) {
+			lastError = formatErrorMessage(error);
+			await sleep(500);
+			continue;
+		}
 		if (lastApp.id === appId) return lastApp;
 		await sleep(500);
 	}
 	const last = lastApp ? `${lastApp.id} ${lastApp.name}` : "unknown";
-	throw new Error(`expected active app ${appId}, got ${last}`);
+	const errorSuffix = lastError ? `; last ECP error: ${lastError}` : "";
+	throw new Error(`expected active app ${appId}, got ${last}${errorSuffix}`);
 };
 const launchApp = async (context, appId, params = /* @__PURE__ */ new Map()) => {
 	const url = ecpUrl(context, `/launch/${encodeURIComponent(appId)}`);
 	for (const [key, value] of params) url.searchParams.set(key, value);
-	await postOk(context, url);
+	await postLaunchMaybeAccepted(context, url);
 	return await waitForActiveApp(context, appId);
 };
 const pressKey = async (context, key) => {
@@ -129,7 +169,18 @@ const pressKey = async (context, key) => {
 	await postOk(context, ecpUrl(context, `/keypress/${encodeURIComponent(key)}`));
 };
 const queryEcp = async (context, path) => await fetchText(context, path.startsWith("/") ? path : `/${path}`);
-const querySceneGraph = async (context) => await queryEcp(context, "/query/sgnodes/all");
+const querySceneGraph = async (context, options = {}) => {
+	const attempts = options.attempts ?? 1;
+	const retryDelayMs = options.retryDelayMs ?? 500;
+	let lastError;
+	for (let attempt = 0; attempt < attempts; attempt += 1) try {
+		return await queryEcp(context, "/query/sgnodes/all");
+	} catch (error) {
+		lastError = error;
+		if (attempt < attempts - 1) await sleep(retryDelayMs);
+	}
+	throw new Error(`SceneGraph query failed: ${formatErrorMessage(lastError)}`);
+};
 const assertSceneGraphNode = async (context, nodeName, expectation) => {
 	assertNamedNode(await querySceneGraph(context), nodeName, expectation);
 };
@@ -189,9 +240,22 @@ const postOk = async (context, url) => {
 	});
 	if (!response.ok) throw new Error(`POST ${url.pathname} returned HTTP ${response.status}`);
 };
+const postLaunchMaybeAccepted = async (context, url) => {
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			signal: AbortSignal.timeout(context.timeoutMs)
+		});
+		if (!response.ok && response.status !== 503) throw new Error(`POST ${url.pathname} returned HTTP ${response.status}`);
+	} catch (error) {
+		const message = formatErrorMessage(error).toLowerCase();
+		if (!message.includes("abort") && !message.includes("timeout") && !message.includes("fetch failed")) throw error;
+	}
+};
 const ecpUrl = (context, path) => new URL(path, `http://${context.target}:${ecpPort}`);
 const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
+const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
-export { readXmlTag as S, isNamedNodeVisible as _, launchApp as a, readActiveApp as b, queryEcp as c, validateRemoteKey as d, waitForActiveApp as f, assertNamedNodeText as g, assertNamedNodeState as h, installPackage as i, querySceneGraph as l, assertNamedNode as m, checkDevice as n, pressKey as o, waitForSceneGraphNode as p, getDeviceInfo as r, queryActiveApp as s, assertSceneGraphNode as t, takeScreenshot as u, readNamedNodeAttribute as v, readXmlAttribute as x, readNamedNodeAttributes as y };
+export { readNamedNodeTranslation as C, readXmlTag as E, readNamedNodeNumber as S, readXmlAttribute as T, isNamedNodeVisible as _, launchApp as a, readNamedNodeAttributes as b, queryEcp as c, validateRemoteKey as d, waitForActiveApp as f, assertNamedNodeText as g, assertNamedNodeState as h, installPackage as i, querySceneGraph as l, assertNamedNode as m, checkDevice as n, pressKey as o, waitForSceneGraphNode as p, getDeviceInfo as r, queryActiveApp as s, assertSceneGraphNode as t, takeScreenshot as u, parseSceneGraphNumberList as v, readActiveApp as w, readNamedNodeBounds as x, readNamedNodeAttribute as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",