@felipe-software/react-native-gpui 0.0.0-placeholder → 1.0.1

package/cli/commands/get.ts

@@ -0,0 +1,584 @@
+// `rngpui get …` — introspection commands. Everything here is read-only and reports
+// what the node tree + a fresh pixel capture actually say, never a guess.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isDriveableHost, listServiceWindows, type AttachedHost, type DumpNode, type LaunchedHost } from "../host";
+import { isVisible, nodeAtPoint, parsePoint, resolve, walk } from "../selectors";
+import { averageColor, dominantColor, pixelAt } from "../../scripts/pixel.mjs";
+import { readPng } from "../../scripts/png.mjs";
+import type { RendererProvenance } from "../../src/runtime";
+
+type Host = LaunchedHost | AttachedHost;
+
+function out(json: boolean, human: () => void, data: unknown) {
+    if (json) console.log(JSON.stringify(data, null, 2));
+    else human();
+}
+
+function shortId(node: DumpNode): string {
+    const a = node.accessibility ?? {};
+    return a.testID ?? a.identifier ?? a.nativeID ?? a.label ?? (node.text ? `"${node.text.slice(0, 24)}"` : `#${node.globalId}`);
+}
+
+function boundsStr(node: DumpNode): string {
+    const b = node.bounds;
+    return b ? `${b.x.toFixed(0)},${b.y.toFixed(0)} ${b.width.toFixed(0)}x${b.height.toFixed(0)}` : "—";
+}
+
+// Sample dominant + average color within a node's bounds from a fresh capture. The
+// capture is the WindowServer composite (full-opacity), so this is the ACTUAL rendered
+// color, including occlusion by native child windows (WebView) — the whole point.
+function sampleNode(host: Host, node: DumpNode): { dominant: string; average: string; coverage: number } | null {
+    const b = node.bounds;
+    if (!b || b.width < 1 || b.height < 1) return null;
+    const dir = mkdtempSync(join(tmpdir(), "rngpui-sample-"));
+    const png = join(dir, "shot.png");
+    try {
+        host.capture(png);
+        const img = readPng(png);
+        const scaleX = img.width / host.window.width;
+        const scaleY = img.height / host.window.height;
+        const rect = {
+            x: Math.round(b.x * scaleX),
+            y: Math.round(b.y * scaleY),
+            width: Math.max(1, Math.round(b.width * scaleX)),
+            height: Math.max(1, Math.round(b.height * scaleY)),
+        };
+        const dom = dominantColor(img, rect);
+        const avg = averageColor(img, rect);
+        return { dominant: dom.hex, average: avg.hex, coverage: dom.coverage };
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+function renderTree(node: DumpNode, depth: number, lines: string[], filter?: (n: DumpNode) => boolean) {
+    const indent = "  ".repeat(depth);
+    const id = shortId(node);
+    const ev = node.events?.length ? ` (${node.events.includes("press") || node.events.includes("click") ? "tap" : node.events[0]})` : "";
+    const vis = isVisible(node) ? "" : " [hidden]";
+    if (!filter || filter(node)) {
+        lines.push(`${indent}${node.type} ${id !== `#${node.globalId}` ? id + " " : ""}#${node.globalId} [${boundsStr(node)}]${ev}${vis}`);
+    }
+    for (const child of node.children ?? []) renderTree(child, depth + 1, lines, filter);
+}
+
+type ScreenSummary = {
+    target: {
+        mode: Host["mode"];
+        appName: string | null;
+        servicePid: number;
+        window: { id: number; width: number; height: number; owner: string; title: string };
+        driveable: boolean;
+        controlSocketPath: string | null;
+    };
+    stats: TreeStats;
+    webviews: Array<{ globalId: number; id: string; bounds: DumpNode["bounds"] | null; visible: boolean; source: string | null }>;
+    interactive: Array<{
+        globalId: number;
+        selector: string;
+        type: string;
+        bounds: DumpNode["bounds"] | null;
+        events: string[];
+        stateStyle: Record<string, unknown>;
+    }>;
+};
+
+function screenSummary(host: Host, dump: DumpNode): ScreenSummary {
+    const interactive = [...walk(dump)]
+        .filter((node) => isVisible(node) && !!node.events?.length)
+        .sort((a, b) => (a.bounds!.y - b.bounds!.y || a.bounds!.x - b.bounds!.x || areaOf(a) - areaOf(b)))
+        .slice(0, 40)
+        .map((node) => ({
+            globalId: node.globalId,
+            selector: selectorFor(node),
+            type: node.type,
+            bounds: node.bounds ?? null,
+            events: node.events ?? [],
+            stateStyle: stateStyleOf(node),
+        }));
+    const webviews = [...walk(dump)]
+        .filter((node) => node.type === "webview")
+        .map((node) => ({
+            globalId: node.globalId,
+            id: shortId(node),
+            bounds: node.bounds ?? null,
+            visible: isVisible(node),
+            source: node.src ?? (node.text ? `inline-html ${node.text.length}b` : null),
+        }));
+    return {
+        target: {
+            mode: host.mode,
+            appName: host.mode === "launch" ? host.appName : host.appName ?? null,
+            servicePid: host.servicePid,
+            window: {
+                id: host.window.id ?? host.window.window_id,
+                width: host.window.width,
+                height: host.window.height,
+                owner: host.window.owner,
+                title: host.window.title,
+            },
+            driveable: isDriveableHost(host),
+            controlSocketPath: host.mode === "attach" ? host.controlSocketPath ?? null : "(session)",
+        },
+        stats: treeStats(dump),
+        webviews,
+        interactive,
+    };
+}
+
+function printScreenSummary(summary: ScreenSummary) {
+    const t = summary.target;
+    console.log(
+        `  target: ${t.mode} ${t.appName ?? t.window.owner} pid=${t.servicePid} window=${t.window.width}x${t.window.height} driveable=${t.driveable}${t.controlSocketPath ? ` socket=${t.controlSocketPath}` : ""}`
+    );
+    console.log(
+        `  tree: nodes=${summary.stats.nodes} visible=${summary.stats.visible} hidden=${summary.stats.hidden} interactive=${summary.stats.interactive} webviews=${summary.stats.webviews.visible}/${summary.stats.webviews.total}`
+    );
+    if (summary.webviews.length) {
+        console.log("  webviews:");
+        for (const webview of summary.webviews.slice(0, 8)) {
+            console.log(`    ${webview.id} #${webview.globalId} [${webview.bounds ? `${webview.bounds.x.toFixed(0)},${webview.bounds.y.toFixed(0)} ${webview.bounds.width.toFixed(0)}x${webview.bounds.height.toFixed(0)}` : "-"}] visible=${webview.visible} source=${webview.source ?? "(none)"}`);
+        }
+    }
+    console.log("  tappable selectors:");
+    for (const node of summary.interactive.slice(0, 24)) {
+        const state = formatStateStyle(node.stateStyle);
+        console.log(`    ${JSON.stringify(node.selector)} #${node.globalId} ${node.type} [${node.bounds ? `${node.bounds.x.toFixed(0)},${node.bounds.y.toFixed(0)} ${node.bounds.width.toFixed(0)}x${node.bounds.height.toFixed(0)}` : "-"}] (${node.events.join(",")})${state ? ` ${state}` : ""}`);
+    }
+}
+
+function selectorFor(node: DumpNode): string {
+    const a = node.accessibility ?? {};
+    return cleanSelector(a.testID) ?? cleanSelector(a.identifier) ?? cleanSelector(a.nativeID) ?? cleanSelector(a.label) ?? cleanSelector(node.text) ?? shortId(node);
+}
+
+function cleanSelector(value: unknown): string | null {
+    if (typeof value !== "string") return null;
+    const cleaned = value.replace(/\s+/g, " ").trim();
+    return cleaned ? cleaned.slice(0, 120) : null;
+}
+
+function areaOf(node: DumpNode): number {
+    const b = node.bounds;
+    return b ? b.width * b.height : Infinity;
+}
+
+function stateStyleOf(node: DumpNode): Record<string, unknown> {
+    const style = node.style ?? {};
+    const out: Record<string, unknown> = {};
+    for (const key of ["backgroundColor", "borderColor", "boxShadow", "opacity", "display"]) {
+        const value = style[key];
+        if (value !== undefined && value !== "none" && value !== "#00000000") out[key] = value;
+    }
+    return out;
+}
+
+function formatStateStyle(style: Record<string, unknown>): string {
+    const entries = Object.entries(style);
+    return entries.length ? entries.map(([key, value]) => `${key}=${String(value)}`).join(" ") : "";
+}
+
+export async function runGet(host: Host, sub: string, args: string[], json: boolean): Promise<number> {
+    if (sub === "windows") {
+        const windows = await listServiceWindows(host);
+        out(
+            json,
+            () => {
+                for (const window of windows) {
+                    const b = window.bounds;
+                    const geometry = b ? `${b.width.toFixed(0)}x${b.height.toFixed(0)} at ${b.x.toFixed(0)},${b.y.toFixed(0)}${b.active ? " active" : ""}` : "—";
+                    const name = window.testID ? ` ${window.testID}` : "";
+                    const title = window.title ? ` "${window.title}"` : "";
+                    console.log(`  ${window.id} ${window.kind}${name}${title} ${geometry} nodes=${window.nodes} frames=${window.framesPainted}`);
+                }
+            },
+            windows,
+        );
+        return 0;
+    }
+    if (sub === "provenance") {
+        if (!isDriveableHost(host)) {
+            console.error("  get provenance needs a driveable target (control socket)");
+            return 1;
+        }
+        const result = await host.request<{ ok: boolean; error?: string } & Partial<RendererProvenance>>({
+            $cmd: "rendererProvenance",
+        });
+        if (!result.ok) {
+            console.error(`  renderer provenance failed: ${result.error || "native command failed"}`);
+            return 1;
+        }
+        out(
+            json,
+            () => {
+                console.log(`  renderer: ${result.renderer} ${result.rendererVersion}`);
+                console.log(`  service: ${result.serviceVersion}  GPUI: ${result.gpuiRevision}  JS: ${result.jsEngine} ${result.jsEngineVersion}`);
+                console.log(`  bundle: ${result.bundleUrl ?? "(embedded)"}  development=${result.development === true}`);
+            },
+            result,
+        );
+        return 0;
+    }
+    if (sub === "frames") {
+        if (!isDriveableHost(host)) {
+            console.error("  get frames needs a driveable target (control socket)");
+            return 1;
+        }
+        const stats = await host.request<{ ok: boolean; framesPainted: number; fpsLast1s: number; lastFrameAgoMs: number | null; avgFrameGapMs: number | null }>({ $cmd: "frameStats" });
+        out(json, () => {
+            const ago = stats.lastFrameAgoMs == null ? "n/a" : `${stats.lastFrameAgoMs.toFixed(0)}ms ago`;
+            const gap = stats.avgFrameGapMs == null ? "n/a" : `${stats.avgFrameGapMs.toFixed(1)}ms`;
+            console.log(`  frames painted: ${stats.framesPainted} — ${stats.fpsLast1s}fps last 1s, last frame ${ago}, avg gap ${gap}`);
+        }, stats);
+        return 0;
+    }
+    const dump = await host.dump();
+    if (!dump) {
+        if (sub === "color") {
+            const pt = parsePoint(args[0] ?? "");
+            if (!pt) {
+                console.error("  attached color sampling only supports a literal point: rngpui get color <x,y> --attach");
+                return 1;
+            }
+            return getColorAtPoint(host, pt.x, pt.y, json);
+        }
+        if (sub === "point") {
+            const pt = parsePoint(args[0] ?? "");
+            if (!pt) {
+                console.error("  usage: rngpui get point <x,y>");
+                return 1;
+            }
+            const color = getColorSampleAtPoint(host, pt.x, pt.y);
+            out(json, () => console.log(`  topmost: (attach has no tree)\n  pixel: ${color ?? "(unavailable)"}`), {
+                point: pt,
+                topmost: null,
+                pixel: color,
+            });
+            return color ? 0 : 1;
+        }
+        console.error("  no tree available (attach exposes trees only when the app publishes RNGPUI_CONTROL_SOCKET metadata)");
+        return 1;
+    }
+
+    switch (sub) {
+        case "screen": {
+            const summary = screenSummary(host, dump);
+            out(json, () => printScreenSummary(summary), summary);
+            return 0;
+        }
+
+        case "tree": {
+            if (json) {
+                console.log(JSON.stringify(dump, null, 2));
+            } else {
+                const lines: string[] = [];
+                renderTree(dump, 0, lines);
+                console.log(lines.join("\n"));
+            }
+            return 0;
+        }
+
+        case "stats": {
+            const selector = args[0];
+            const root = selector ? matchNodes(dump, selector)[0] : dump;
+            if (!root) {
+                console.error(`  no node matched "${selector}"`);
+                return 1;
+            }
+            const stats = treeStats(root);
+            out(
+                json,
+                () => {
+                    console.log(
+                        `  nodes=${stats.nodes} visible=${stats.visible} hidden=${stats.hidden} interactive=${stats.interactive} maxDepth=${stats.maxDepth}`
+                    );
+                    console.log(
+                        `  webviews=${stats.webviews.total} visible=${stats.webviews.visible} hidden=${stats.webviews.hidden}`
+                    );
+                    if (stats.duplicateGlobalIds.length) {
+                        console.log(`  duplicate globalIds: ${stats.duplicateGlobalIds.join(", ")}`);
+                    }
+                    console.log(`  by type: ${formatCounts(stats.byType)}`);
+                    if (Object.keys(stats.byNativeListGroup).length) {
+                        console.log(`  list groups: ${formatCounts(stats.byNativeListGroup)}`);
+                    }
+                    if (Object.keys(stats.unpaintedByType).length) {
+                        console.log(`  unpainted by type: ${formatCounts(stats.unpaintedByType)}`);
+                    }
+                },
+                stats,
+            );
+            return 0;
+        }
+
+        case "webviews": {
+            const webviews = [...walk(dump)]
+                .filter((node) => node.type === "webview")
+                .map((node) => ({
+                    globalId: node.globalId,
+                    id: shortId(node),
+                    source: node.src ? { kind: "uri", value: node.src } : node.text ? { kind: "html", bytes: node.text.length } : null,
+                    bounds: node.bounds ?? null,
+                    visible: isVisible(node),
+                    display: node.style?.display ?? null,
+                }));
+            out(
+                json,
+                () => {
+                    if (!webviews.length) {
+                        console.log("  no webviews");
+                        return;
+                    }
+                    for (const webview of webviews) {
+                        const source =
+                            webview.source?.kind === "uri"
+                                ? webview.source.value
+                                : webview.source?.kind === "html"
+                                  ? `inline-html ${webview.source.bytes}b`
+                                  : "(no source)";
+                        console.log(
+                            `  webview ${webview.id} #${webview.globalId} [${webview.bounds ? `${webview.bounds.x.toFixed(0)},${webview.bounds.y.toFixed(0)} ${webview.bounds.width.toFixed(0)}x${webview.bounds.height.toFixed(0)}` : "—"}] visible=${webview.visible} display=${String(webview.display ?? "default")} source=${source}`
+                        );
+                    }
+                },
+                webviews,
+            );
+            return 0;
+        }
+
+        case "describe": {
+            const selector = args[0];
+            if (!selector) {
+                const summary = screenSummary(host, dump);
+                out(json, () => printScreenSummary(summary), summary);
+                return 0;
+            }
+            const nodes: DumpNode[] = selector ? matchNodes(dump, selector) : [dump];
+            if (nodes.length === 0) {
+                console.error(`  no node matched "${selector}"`);
+                return 1;
+            }
+            const results = nodes.slice(0, 8).map((node) => {
+                const color = isVisible(node) ? sampleNode(host, node) : null;
+                return {
+                    globalId: node.globalId,
+                    type: node.type,
+                    testID: node.accessibility?.testID ?? null,
+                    identifier: node.accessibility?.identifier ?? null,
+                    nativeID: node.accessibility?.nativeID ?? null,
+                    label: node.accessibility?.label ?? null,
+                    text: node.text ?? null,
+                    value: node.value ?? null,
+                    events: node.events ?? [],
+                    bounds: node.bounds ?? null,
+                    visible: isVisible(node),
+                    style: node.style ?? {},
+                    sampledColor: color,
+                };
+            });
+            out(
+                json,
+                () => {
+                    for (const r of results) {
+                        console.log(`  ${r.type} #${r.globalId}${r.testID ? ` testID=${r.testID}` : ""}${r.identifier ? ` id=${r.identifier}` : ""}${r.label ? ` label=${JSON.stringify(r.label)}` : ""}`);
+                        if (r.text) console.log(`    text: ${JSON.stringify(r.text)}`);
+                        console.log(`    bounds: ${r.bounds ? `${r.bounds.x.toFixed(0)},${r.bounds.y.toFixed(0)} ${r.bounds.width.toFixed(0)}x${r.bounds.height.toFixed(0)}` : "(not painted)"}  visible=${r.visible}`);
+                        if (r.events.length) console.log(`    events: ${r.events.join(", ")}`);
+                        const styleKeys = Object.keys(r.style);
+                        if (styleKeys.length) console.log(`    style: ${styleKeys.map((k) => `${k}=${(r.style as Record<string, unknown>)[k]}`).join(" ")}`);
+                        if (r.sampledColor) console.log(`    sampled: dominant=${r.sampledColor.dominant} (${(r.sampledColor.coverage * 100).toFixed(0)}%) average=${r.sampledColor.average}`);
+                    }
+                },
+                results.length === 1 ? results[0] : results,
+            );
+            return 0;
+        }
+
+        case "layout": {
+            const selector = args[0];
+            const nodes = selector ? matchNodes(dump, selector) : [...walk(dump)].filter(isVisible);
+            const rows = nodes.slice(0, 50).map((n) => ({ globalId: n.globalId, type: n.type, id: shortId(n), bounds: n.bounds ?? null, visible: isVisible(n) }));
+            out(json, () => rows.forEach((r) => console.log(`  ${r.type} ${r.id} #${r.globalId} [${r.bounds ? `${r.bounds.x.toFixed(0)},${r.bounds.y.toFixed(0)} ${r.bounds.width.toFixed(0)}x${r.bounds.height.toFixed(0)}` : "—"}]`)), rows.length === 1 ? rows[0] : rows);
+            return 0;
+        }
+
+        case "style": {
+            const selector = args[0];
+            if (!selector) {
+                console.error("  usage: rngpui get style <selector>");
+                return 1;
+            }
+            const nodes = matchNodes(dump, selector);
+            if (nodes.length === 0) {
+                console.error(`  no node matched "${selector}"`);
+                return 1;
+            }
+            const rows = nodes.slice(0, 8).map((n) => ({ globalId: n.globalId, type: n.type, style: n.style ?? {} }));
+            out(json, () => rows.forEach((r) => console.log(`  ${r.type} #${r.globalId}: ${JSON.stringify(r.style)}`)), rows.length === 1 ? rows[0] : rows);
+            return 0;
+        }
+
+        case "color": {
+            const selector = args[0];
+            if (!selector) {
+                console.error("  usage: rngpui get color <selector|x,y>");
+                return 1;
+            }
+            const pt = parsePoint(selector);
+            if (pt) return getColorAtPoint(host, pt.x, pt.y, json);
+            const nodes = matchNodes(dump, selector);
+            const node = nodes[0];
+            if (!node) {
+                console.error(`  no node matched "${selector}"`);
+                return 1;
+            }
+            const color = sampleNode(host, node);
+            if (!color) {
+                console.error(`  node ${shortId(node)} #${node.globalId} is not painted (no bounds) — nothing to sample`);
+                return 1;
+            }
+            out(json, () => console.log(`  ${shortId(node)} #${node.globalId} [${boundsStr(node)}]  dominant=${color.dominant} (${(color.coverage * 100).toFixed(0)}%) average=${color.average}`), { globalId: node.globalId, bounds: node.bounds, ...color });
+            return 0;
+        }
+
+        case "point": {
+            const pt = parsePoint(args[0] ?? "");
+            if (!pt) {
+                console.error("  usage: rngpui get point <x,y>");
+                return 1;
+            }
+            const node = nodeAtPoint(dump, pt.x, pt.y);
+            const color = getColorSampleAtPoint(host, pt.x, pt.y);
+            out(
+                json,
+                () => {
+                    if (node) console.log(`  topmost: ${node.type} ${shortId(node)} #${node.globalId} [${boundsStr(node)}]${node.events?.length ? ` (${node.events.join(",")})` : ""}`);
+                    else console.log("  topmost: (no node at point)");
+                    if (color) console.log(`  pixel: ${color}`);
+                },
+                {
+                    point: pt,
+                    topmost: node ? { globalId: node.globalId, type: node.type, id: shortId(node), bounds: node.bounds, events: node.events ?? [] } : null,
+                    pixel: color,
+                },
+            );
+            return 0;
+        }
+
+        default:
+            console.error(`  unknown get subcommand: ${sub}`);
+            console.error("  available: provenance, frames, screen, tree, stats, webviews, describe, layout, style, color, point");
+            return 1;
+    }
+}
+
+type TreeStats = {
+    root: { globalId: number; type: string; id: string };
+    nodes: number;
+    visible: number;
+    hidden: number;
+    interactive: number;
+    maxDepth: number;
+    duplicateGlobalIds: number[];
+    byType: Record<string, number>;
+    unpaintedByType: Record<string, number>;
+    byNativeListGroup: Record<string, number>;
+    webviews: { total: number; visible: number; hidden: number };
+};
+
+function treeStats(root: DumpNode): TreeStats {
+    const seen = new Map<number, number>();
+    const byType: Record<string, number> = {};
+    const unpaintedByType: Record<string, number> = {};
+    const byNativeListGroup: Record<string, number> = {};
+    const webviews = { total: 0, visible: 0, hidden: 0 };
+    let nodes = 0;
+    let visible = 0;
+    let interactive = 0;
+    let maxDepth = 0;
+
+    const visit = (node: DumpNode, depth: number) => {
+        nodes += 1;
+        maxDepth = Math.max(maxDepth, depth);
+        seen.set(node.globalId, (seen.get(node.globalId) ?? 0) + 1);
+        byType[node.type] = (byType[node.type] ?? 0) + 1;
+        if (node.nativeListGroup) {
+            byNativeListGroup[node.nativeListGroup] = (byNativeListGroup[node.nativeListGroup] ?? 0) + 1;
+        }
+        if (node.events?.length) interactive += 1;
+        if (isVisible(node)) {
+            visible += 1;
+        } else {
+            unpaintedByType[node.type] = (unpaintedByType[node.type] ?? 0) + 1;
+        }
+        if (node.type === "webview") {
+            webviews.total += 1;
+            if (isVisible(node)) webviews.visible += 1;
+            else webviews.hidden += 1;
+        }
+        for (const child of node.children ?? []) visit(child, depth + 1);
+    };
+    visit(root, 0);
+
+    return {
+        root: { globalId: root.globalId, type: root.type, id: shortId(root) },
+        nodes,
+        visible,
+        hidden: nodes - visible,
+        interactive,
+        maxDepth,
+        duplicateGlobalIds: [...seen.entries()]
+            .filter(([, count]) => count > 1)
+            .map(([id]) => id)
+            .sort((a, b) => a - b),
+        byType: sortCounts(byType),
+        unpaintedByType: sortCounts(unpaintedByType),
+        byNativeListGroup: sortCounts(byNativeListGroup),
+        webviews,
+    };
+}
+
+function sortCounts(counts: Record<string, number>) {
+    return Object.fromEntries(Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])));
+}
+
+function formatCounts(counts: Record<string, number>) {
+    const entries = Object.entries(counts);
+    return entries.length ? entries.map(([key, value]) => `${key}=${value}`).join(" ") : "(none)";
+}
+
+function matchNodes(dump: DumpNode, selector: string): DumpNode[] {
+    const { best, candidates } = resolve(dump, selector);
+    if (!best) return [];
+    // return the best plus any equally-named siblings (same matchedValue) for context.
+    return candidates.filter((c) => c.matchedValue === best.matchedValue).map((c) => c.node);
+}
+
+function getColorSampleAtPoint(host: Host, x: number, y: number): string | null {
+    const dir = mkdtempSync(join(tmpdir(), "rngpui-px-"));
+    const png = join(dir, "shot.png");
+    try {
+        host.capture(png);
+        const img = readPng(png);
+        const scaleX = img.width / host.window.width;
+        const scaleY = img.height / host.window.height;
+        return pixelAt(img, Math.round(x * scaleX), Math.round(y * scaleY)).hex;
+    } catch {
+        return null;
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+function getColorAtPoint(host: Host, x: number, y: number, json: boolean): number {
+    const hex = getColorSampleAtPoint(host, x, y);
+    if (!hex) {
+        console.error(`  could not sample pixel at ${x},${y}`);
+        return 1;
+    }
+    out(json, () => console.log(`  ${x},${y}: ${hex}`), { x, y, hex });
+    return 0;
+}