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

package/cli/bin.ts

@@ -0,0 +1,379 @@
+#!/usr/bin/env bun
+// `rngpui` — the react-native-gpui developer CLI. A get/do devtool over a running OR
+// launched offscreen rngpui app, modeled on soot's sootsim CLI.
+//
+//   rngpui get describe composer:input --launch examples/superconductor.tsx
+//   rngpui get color 200,300 --attach
+//   rngpui do tap "Run" --launch examples/kitchen-sink.tsx
+//
+// GET commands introspect (tree / stats / webviews / describe / layout / style / color / point); DO
+// commands drive (tap / type / key / scroll / drag). Selectors substring-match testID /
+// identifier / nativeID / label / text / type, or `#<globalId>`, or `x,y`. `--json`
+// for machine output.
+
+import { attachHost, attachSession, closeSession, launchHost, scopeToWindow, type AttachedHost, type LaunchedHost } from "./host";
+import { runGet } from "./commands/get";
+import { runDo } from "./commands/do";
+import { runFlow } from "./commands/flow";
+import { runTrace } from "./commands/trace";
+import { runDiff, runShot, type ShotFlags } from "./commands/shot";
+import { runHotReload } from "./hotReload";
+import { bundleApp } from "./bundle";
+import { runApp } from "./run";
+import { join, resolve } from "node:path";
+
+const HELP = `rngpui — react-native-gpui developer CLI
+
+usage:
+  rngpui bundle <entry.tsx> <out.js> [--dev]                 bundle an app for rngpui-service (production unless --dev)
+  rngpui run <entry.tsx | --bundle app.js> [--dev] [--size WxH]   bundle the app and open its window
+  rngpui shot <--bundle app.js | --launch entry.tsx | --session dir> [--size WxH] [--appearance light|dark] [--select id ...] [--out png] [--fixture] [--keep]
+  rngpui reshot --session <dir> [--window <sel>] [--select id ...] [--out png]   sub-second re-capture of a kept session
+  rngpui dev --launch <entry.tsx> [--root <dir> ...] [--size WxH]   launch once and Fast Refresh on edit
+  rngpui dev --socket <control.sock> --build <cmd> --bundle <bundle.js> --root <dir>   Fast Refresh an owned external instance
+  rngpui diff <before.png> <after.png> [--out highlight.png] [--threshold n]
+  rngpui <get|do> <subcommand> [selector] [--launch <entry.tsx> | --bundle <app.js> | --session <dir> | --attach] [--json]
+  rngpui trace <selector ...|--all> [--keys k1,k2] [--ms n] [--action "tap <sel>"] [target] [--json]
+  rngpui flow [--profile] tap <selector> [tap <selector> ...] [--out <dir>] [target]
+  rngpui close --session <dir>
+
+the fast loop (offscreen, no screenshots, one command):
+  shot                   launch → wait for a stable frame → write png + tree → print
+                         the png path + bounds/color of every --select'd node. ONE call.
+  dev                    launch one development instance and keep its PID and native state
+                         while JavaScriptCore React Refresh applies source edits.
+  reshot                 re-capture a kept --session instantly (state/data changed → look again).
+  diff                   compare two pngs: changed-pixel ratio + changed-region box (+ --out highlight).
+
+shot/dev flags:
+  --appearance light|dark  force the app theme (RNGPUI_FORCE_APPEARANCE) — no system toggle
+  --select <selector>      measure this node (repeatable): prints bounds + sampled color
+  --crop <x,y,w,h>         (reserved) region of interest
+  --fixture                load deterministic demo data (TM_FIXTURE_ONLY=1) — the
+                           team-machine app paints an empty shell without a daemon or fixture
+  --out <png>              where to write the capture (default /tmp/rngpui-shot.png)
+
+target (pick one; defaults to --attach):
+  --launch <entry.tsx>   bundle the entry to JavaScript source, then spawn rngpui-service
+  --bundle <app.js>      spawn rngpui-service against an existing JavaScript source bundle
+  --keep                 keep the launched service alive and print its session dir
+  --session <dir>        reuse a kept driveable session for do-then-get workflows
+  --attach               attach to a running rngpui window; driveable only when
+                         owner metadata advertises RNGPUI_CONTROL_SOCKET
+  --size <WxH>           launched window size (default 1280x860)
+  --window <sel>         aim get/do/trace at one window: an id from \`get windows\`,
+                         main, a <Window testID>, a kind (dialog/popup/normal) or a
+                         title substring
+
+get (introspect — read-only):
+  get windows                    every window the service shows: id, kind, title,
+                                 testID, bounds, node count, frames painted
+  get screen                     actionable visible-screen summary
+  get tree                       full annotated node tree (bounds + ids)
+  get stats [selector]           aggregate node counts, visibility, duplicate IDs,
+                                 type/list-group counts, and webview totals
+  get webviews                   webview inventory: source, bounds, visibility
+  get describe [selector]        path, ids, computed bounds, resolved style, AND
+                                 sampled dominant/average color within the bounds
+  get layout [selector]          computed window-coordinate bounds per node
+  get style <selector>           resolved style facts (incl. background/border/color)
+  get color <selector|x,y>       sampled dominant/average color in a node or at a point
+  get point <x,y>                topmost node + pixel color at a window point
+  get frames                     painted-frame counter + live fps + frame-gap stats
+  get provenance                 native renderer/service/GPUI/JavaScriptCore/bundle identity
+
+trace (animation forensics — no screenshots):
+  trace <selector ...>           record every animated style write (off-thread
+                                 reanimated / tamagui driver) and NativeLayout tween
+                                 tick under the matched subtrees, then report per-key
+                                 curves: sparkline, endpoints, min/max, sample cadence,
+                                 dropped-frame gaps, spring overshoot count.
+  --all                          trace every node instead of a subtree
+  --keys opacity,transform       only record these style keys
+  --ms <n>                       observation window after actions fire (default 1200)
+  --action "tap <sel>"           fire input after arming (repeatable; tap/key/type)
+  example: rngpui trace dialog --action "tap open-settings" --ms 1500 --session <dir>
+
+do (drive):
+  do tap <selector|x,y>          synthesize a press at the node center / point
+  do type <text>                 type into the focused input
+  do hud <on|off>                toggle the native in-window performance HUD
+  do key <key>                   send one key (enter, backspace, space, a, …)
+  do scroll <selector|x,y> <dx,dy>  scroll the container at the point by a delta
+  do drag <from> <to> [steps]    synthesize an owned offscreen press-drag
+
+flow:
+  flow --profile tap "Session A" tap "Session B"
+                                 run semantic taps and write trees/screenshots
+                                 plus profile.json (default /tmp/rngpui-flow-*)
+  --no-screenshots               keep profile timing clean for rapid stress flows
+  --settle-ms <n>                wait up to n ms for first tree change per step
+                                 (default 700; use 0 for rapid fire)
+  --cadence-ms <n>               fixed delay after each tap before the next step
+
+selectors:
+  #42            globalId 42
+  composer       substring match on testID/identifier/nativeID/label/text/type
+  200,300        literal window-coordinate point
+
+examples:
+  rngpui shot --bundle native-shell/.gpui/app.js --size 1360x880 --fixture --appearance dark --select stage --select trees-rail
+  rngpui dev --launch app/index.tsx --fixture                           # Fast Refresh until Ctrl-C
+  rngpui reshot --session /var/.../rngpui-cli-XXXX --select composer
+  rngpui diff /tmp/before.png /tmp/rngpui-shot.png --out /tmp/diff.png
+  rngpui get describe stage --launch examples/superconductor.tsx
+  rngpui get tree --launch examples/kitchen-sink.tsx --keep
+  rngpui do tap count-button --session /tmp/rngpui-cli-abc123
+  rngpui get describe --attach
+  rngpui close --session /tmp/rngpui-cli-abc123
+`;
+
+function parseArgs(argv: string[]) {
+    const args = argv.slice(2);
+    const flags: Record<string, string | boolean> = {};
+    const select: string[] = [];
+    const actions: string[] = [];
+    const roots: string[] = [];
+    const ignores: string[] = [];
+    const extensions: string[] = [];
+    const positional: string[] = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json") flags.json = true;
+        else if (a === "--attach") flags.attach = true;
+        else if (a === "--launch") flags.launch = args[++i] ?? "";
+        else if (a === "--bundle") flags.bundle = args[++i] ?? "";
+        else if (a === "--session") flags.session = args[++i] ?? "";
+        else if (a === "--window") flags.window = args[++i] ?? "";
+        else if (a === "--keep") flags.keep = true;
+        else if (a === "--size") flags.size = args[++i] ?? "";
+        else if (a === "--appearance") flags.appearance = args[++i] ?? "";
+        else if (a === "--select") select.push(args[++i] ?? "");
+        else if (a === "--crop") flags.crop = args[++i] ?? "";
+        else if (a === "--fixture") flags.fixture = true;
+        else if (a === "--threshold") flags.threshold = args[++i] ?? "";
+        else if (a === "--profile") flags.profile = true;
+        else if (a === "--screenshots") flags.screenshots = true;
+        else if (a === "--no-screenshots") flags.screenshots = false;
+        else if (a === "--settle-ms") flags.settleMs = args[++i] ?? "";
+        else if (a === "--cadence-ms") flags.cadenceMs = args[++i] ?? "";
+        else if (a === "--keys") flags.keys = args[++i] ?? "";
+        else if (a === "--ms") flags.ms = args[++i] ?? "";
+        else if (a === "--action") actions.push(args[++i] ?? "");
+        else if (a === "--all") flags.all = true;
+        else if (a === "--out") flags.out = args[++i] ?? "";
+        else if (a === "--socket") flags.socket = args[++i] ?? "";
+        else if (a === "--build") flags.build = args[++i] ?? "";
+        else if (a === "--root") roots.push(args[++i] ?? "");
+        else if (a === "--ignore") ignores.push(args[++i] ?? "");
+        else if (a === "--ext") extensions.push(args[++i] ?? "");
+        else if (a === "--debounce-ms") flags.debounceMs = args[++i] ?? "";
+        else if (a === "--label") flags.label = args[++i] ?? "";
+        else if (a === "--once") flags.once = true;
+        else if (a === "--dev") flags.dev = true;
+        else if (a === "-h" || a === "--help") flags.help = true;
+        else positional.push(a);
+    }
+    return { flags, positional, select, actions, roots, ignores, extensions };
+}
+
+function shotFlags(flags: Record<string, string | boolean>, select: string[]): ShotFlags {
+    return {
+        json: flags.json === true,
+        size: flags.size ? String(flags.size) : undefined,
+        appearance: flags.appearance ? String(flags.appearance) : undefined,
+        out: flags.out ? String(flags.out) : undefined,
+        select: select.filter(Boolean),
+        crop: flags.crop ? String(flags.crop) : undefined,
+        fixture: flags.fixture === true,
+        session: flags.session ? String(flags.session) : process.env.RNGPUI_SESSION || undefined,
+        bundle: flags.bundle !== undefined ? String(flags.bundle) : undefined,
+        launch: flags.launch !== undefined ? String(flags.launch) : undefined,
+        keep: flags.keep === true,
+        window: typeof flags.window === "string" && flags.window ? flags.window : undefined,
+    };
+}
+
+function bundleCommand(args: string[], flags: Record<string, string | boolean>): number {
+    const [entry, positionalOut] = args;
+    const out = flags.out ? String(flags.out) : positionalOut;
+    if (!entry || !out) {
+        console.error("  bundle needs an entry and an output path: rngpui bundle app.tsx dist/app.js");
+        return 1;
+    }
+    bundleApp(entry, out, { development: flags.dev === true, inheritOutput: true });
+    return 0;
+}
+
+function runCommand(entry: string | undefined, flags: Record<string, string | boolean>): Promise<number> {
+    return runApp({
+        entry,
+        bundle: flags.bundle ? String(flags.bundle) : undefined,
+        development: flags.dev === true,
+        size: flags.size ? String(flags.size) : undefined,
+    });
+}
+
+async function main(): Promise<number> {
+    const { flags, positional, select, actions, roots, ignores, extensions } = parseArgs(process.argv);
+    if (flags.help || positional.length === 0) {
+        console.log(HELP);
+        return positional.length === 0 ? 1 : 0;
+    }
+
+    const [group, sub, ...rest] = positional;
+    const json = flags.json === true;
+
+    if (group === "bundle" || group === "run") {
+        try {
+            return group === "bundle" ? bundleCommand(positional.slice(1), flags) : await runCommand(positional[1], flags);
+        } catch (err) {
+            console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+            return 1;
+        }
+    }
+
+    // The fast iteration commands own their whole host lifecycle (launch/attach +
+    // capture + close), so they short-circuit the generic get/do/flow plumbing.
+    if (group === "shot") {
+        return runShot(shotFlags(flags, select));
+    }
+    if (group === "reshot") {
+        const sf = shotFlags(flags, select);
+        if (!sf.session) {
+            console.error("  reshot needs --session <dir> (the dir `rngpui dev` printed) or RNGPUI_SESSION");
+            return 1;
+        }
+        return runShot(sf);
+    }
+    if (group === "dev") {
+        const entry = flags.launch ? resolve(String(flags.launch)) : undefined;
+        if (entry) {
+            const host = await launchHost(entry, {
+                size: flags.size ? String(flags.size) : undefined,
+                development: true,
+                appearance: flags.appearance ? String(flags.appearance) : undefined,
+                fixture: flags.fixture === true,
+            });
+            console.log(`[rngpui-dev] pid=${host.servicePid} session=${host.sessionDir}`);
+            try {
+                return await runHotReload({
+                    socketPath: host.controlSocketPath,
+                    roots: roots.filter(Boolean).length ? roots.filter(Boolean) : [process.cwd()],
+                    entryPath: entry,
+                    bundlePath: join(host.sessionDir, "hot.js"),
+                    ignores: ignores.filter(Boolean),
+                    extensions: extensions.filter(Boolean),
+                    debounceMs: flags.debounceMs ? Number(flags.debounceMs) : undefined,
+                    label: flags.label ? String(flags.label) : "rngpui-dev",
+                    once: flags.once === true,
+                });
+            } finally {
+                host.close();
+            }
+        }
+        return runHotReload({
+            socketPath: flags.socket ? String(flags.socket) : undefined,
+            roots: roots.filter(Boolean),
+            buildCommand: flags.build ? String(flags.build) : undefined,
+            bundlePath: flags.bundle ? String(flags.bundle) : undefined,
+            ignores: ignores.filter(Boolean),
+            extensions: extensions.filter(Boolean),
+            debounceMs: flags.debounceMs ? Number(flags.debounceMs) : undefined,
+            label: flags.label ? String(flags.label) : undefined,
+            once: flags.once === true,
+        });
+    }
+    if (group === "diff") {
+        return runDiff(positional.slice(1), {
+            json,
+            out: flags.out ? String(flags.out) : undefined,
+            threshold: flags.threshold ? Number(flags.threshold) : undefined,
+        });
+    }
+
+    if (group === "close") {
+        const session = flags.session || process.env.RNGPUI_SESSION;
+        if (!session) {
+            console.error("  close needs --session <dir> or RNGPUI_SESSION");
+            return 1;
+        }
+        closeSession(String(session));
+        if (!json) console.log(`  closed ${session}`);
+        else console.log(JSON.stringify({ closed: String(session) }));
+        return 0;
+    }
+
+    if (group !== "get" && group !== "do" && group !== "flow" && group !== "trace") {
+        console.error(`  unknown command group: ${group}`);
+        console.error("  run `rngpui --help` for the surface.");
+        return 1;
+    }
+    if (!sub && group !== "flow" && !(group === "trace" && flags.all === true)) {
+        console.error(`  ${group} needs a ${group === "trace" ? "selector (or --all)" : "subcommand"} — run \`rngpui --help\``);
+        return 1;
+    }
+
+    let host: LaunchedHost | AttachedHost | null = null;
+    try {
+        const session = flags.session || process.env.RNGPUI_SESSION;
+        if (session) {
+            host = await attachSession(String(session));
+        } else if (flags.bundle !== undefined) {
+            host = await launchHost("", {
+                bundle: String(flags.bundle),
+                keep: flags.keep === true,
+                size: flags.size ? String(flags.size) : undefined,
+            });
+        } else if (flags.launch !== undefined) {
+            host = await launchHost(String(flags.launch), {
+                keep: flags.keep === true,
+                size: flags.size ? String(flags.size) : undefined,
+            });
+        } else {
+            // default + explicit --attach both land here
+            host = await attachHost();
+        }
+        if (typeof flags.window === "string" && flags.window) {
+            host = await scopeToWindow(host, flags.window);
+        }
+
+        const code =
+            group === "get"
+                ? await runGet(host, sub, rest, json)
+                : group === "do"
+                  ? await runDo(host, sub, rest, json)
+                  : group === "trace"
+                    ? await runTrace(host, sub ? [sub, ...rest] : [], {
+                          json,
+                          keys: flags.keys ? String(flags.keys).split(",").map((k) => k.trim()).filter(Boolean) : undefined,
+                          ms: flags.ms ? Number(flags.ms) : 1_200,
+                          actions: actions.filter(Boolean),
+                          all: flags.all === true,
+                      })
+                    : await runFlow(host, sub ? [sub, ...rest] : rest, {
+                        json,
+                        profile: flags.profile === true,
+                        screenshots: flags.screenshots === undefined ? undefined : flags.screenshots === true,
+                        settleMs: flags.settleMs === undefined ? undefined : Number(flags.settleMs),
+                        cadenceMs: flags.cadenceMs === undefined ? undefined : Number(flags.cadenceMs),
+                        out: flags.out ? String(flags.out) : undefined,
+                    });
+        if (flags.keep === true && host.mode === "launch") {
+            console.error(`[rngpui] session ${host.sessionDir}`);
+        }
+        return code;
+    } catch (err) {
+        console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    } finally {
+        host?.close();
+    }
+}
+
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+        console.error(err instanceof Error ? err.stack : String(err));
+        process.exit(1);
+    });

package/cli/bundle.ts

@@ -0,0 +1,32 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { packageRoot } from "../scripts/service-binary.mjs";
+
+export type BundleOptions = {
+    development?: boolean;
+    inheritOutput?: boolean;
+};
+
+const bunExecutable = process.versions.bun ? process.execPath : "bun";
+
+export function bundleApp(entry: string, out: string, options: BundleOptions = {}): string {
+    const entryPath = resolve(entry);
+    if (!existsSync(entryPath)) throw new Error(`entry not found: ${entryPath}`);
+    const outPath = resolve(out);
+    mkdirSync(dirname(outPath), { recursive: true });
+    const nodeEnv = options.development ? "development" : "production";
+    const stdio = options.inheritOutput ? "inherit" : "pipe";
+    const result = spawnSync(bunExecutable, [join(packageRoot, "scripts", "bundle-app.mjs"), entryPath, outPath], {
+        cwd: packageRoot,
+        encoding: "utf8",
+        stdio,
+        env: { ...process.env, NODE_ENV: nodeEnv },
+    });
+    if (result.status !== 0) {
+        const output = options.inheritOutput ? "" : `\n${result.stdout}\n${result.stderr}`;
+        throw new Error(`bundle-app failed${output}`);
+    }
+    if (!existsSync(outPath)) throw new Error(`bundle-app did not write ${outPath}`);
+    return outPath;
+}

package/cli/commands/do.ts

@@ -0,0 +1,213 @@
+// `rngpui do ...` - drive the live instance with synthetic input. Launched
+// sessions are driveable, and attached apps become driveable when their owner
+// metadata advertises a debug control socket.
+
+import { isDriveableHost, type AttachedHost, type DriveableHost, type DumpNode, type LaunchedHost } from "../host";
+import { sleep } from "../../scripts/conformance-utils.mjs";
+import { centerOf, parsePoint, resolve } from "../selectors";
+
+type Host = LaunchedHost | AttachedHost;
+type ControlResponse = { ok: boolean; error?: string; targetId?: number; focusedId?: number; activated?: boolean };
+
+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}`);
+}
+
+export async function runDo(host: Host, sub: string, args: string[], json: boolean): Promise<number> {
+    if (!isDriveableHost(host)) {
+        console.error("  do commands need a driveable target: use --launch, --bundle, --session, or attach to an app with RNGPUI_CONTROL_SOCKET metadata");
+        return 1;
+    }
+    const driveable = host;
+
+    switch (sub) {
+        case "hud": {
+            const enabled = args[0] === "on" ? true : args[0] === "off" ? false : null;
+            if (enabled == null) {
+                console.error("  usage: rngpui do hud <on|off>");
+                return 1;
+            }
+            const response = await driveable.request<ControlResponse>({ $cmd: "performanceHud", enabled });
+            if (!response.ok) {
+                console.error(`  performance HUD failed: ${response.error || "native command failed"}`);
+                return 1;
+            }
+            if (json) console.log(JSON.stringify({ performanceHud: enabled }));
+            else console.log(`  performance HUD: ${enabled ? "on" : "off"}`);
+            return 0;
+        }
+
+        case "tap": {
+            const selector = args[0];
+            if (!selector) {
+                console.error("  usage: rngpui do tap <selector|x,y>");
+                return 1;
+            }
+            let x: number;
+            let y: number;
+            let label = selector;
+            const pt = parsePoint(selector);
+            if (pt) {
+                ({ x, y } = pt);
+            } else {
+                const dump = await driveable.dump();
+                const { best } = resolve(dump, selector);
+                if (!best) {
+                    console.error(`  no node matched "${selector}"`);
+                    return 1;
+                }
+                const center = centerOf(best.node);
+                if (!center) {
+                    console.error(`  node ${shortId(best.node)} #${best.node.globalId} has no bounds — not tappable`);
+                    return 1;
+                }
+                ({ x, y } = center);
+                label = `${shortId(best.node)} #${best.node.globalId}`;
+            }
+            const response = await driveable.request<ControlResponse>({ $cmd: "tap", x, y });
+            if (!response.ok) {
+                console.error(`  tap failed: ${response.error || "no native target"}`);
+                return 1;
+            }
+            await sleep(150);
+            if (json) console.log(JSON.stringify({ tapped: label, x, y, targetId: response.targetId }));
+            else console.log(`  tapped ${label} at ${x.toFixed(0)},${y.toFixed(0)}`);
+            return 0;
+        }
+
+        case "type": {
+            const text = args.join(" ");
+            if (!text) {
+                console.error("  usage: rngpui do type <text>");
+                return 1;
+            }
+            const response = await driveable.request<ControlResponse>({ $cmd: "type", text });
+            if (!response.ok) {
+                console.error(`  type failed: ${response.error || "no focused input"}`);
+                return 1;
+            }
+            await sleep(120);
+            if (json) console.log(JSON.stringify({ typed: text, focusedId: response.focusedId }));
+            else console.log(`  typed: ${JSON.stringify(text)}`);
+            return 0;
+        }
+
+        case "key": {
+            const key = args[0];
+            if (!key) {
+                console.error("  usage: rngpui do key <key>   (e.g. enter, backspace, space, a)");
+                return 1;
+            }
+            const response = await driveable.request<ControlResponse>({ $cmd: "key", key });
+            if (!response.ok) {
+                console.error(`  key failed: ${response.error || "no focused input"}`);
+                return 1;
+            }
+            await sleep(100);
+            if (json) console.log(JSON.stringify({ key, focusedId: response.focusedId }));
+            else console.log(`  key: ${key}`);
+            return 0;
+        }
+
+        case "scroll": {
+            const target = args[0];
+            const delta = args[1];
+            if (!target || !delta) {
+                console.error("  usage: rngpui do scroll <selector|x,y> <dx,dy>");
+                return 1;
+            }
+            const d = parsePoint(delta);
+            if (!d) {
+                console.error(`  invalid delta "${delta}" — expected dx,dy`);
+                return 1;
+            }
+            let x: number;
+            let y: number;
+            const pt = parsePoint(target);
+            if (pt) {
+                ({ x, y } = pt);
+            } else {
+                const dump = await driveable.dump();
+                const { best } = resolve(dump, target);
+                const center = best ? centerOf(best.node) : null;
+                if (!center) {
+                    console.error(`  no scrollable node matched "${target}"`);
+                    return 1;
+                }
+                ({ x, y } = center);
+            }
+            const response = await driveable.request<ControlResponse>({ $cmd: "scrollAt", x, y, dx: d.x, dy: d.y });
+            if (!response.ok) {
+                console.error(`  scroll failed: ${response.error || "no scroll container"}`);
+                return 1;
+            }
+            await sleep(120);
+            if (json) console.log(JSON.stringify({ scrolled: { x, y, dx: d.x, dy: d.y, targetId: response.targetId } }));
+            else console.log(`  scrolled at ${x.toFixed(0)},${y.toFixed(0)} by ${d.x},${d.y}`);
+            return 0;
+        }
+
+        case "drag": {
+            const from = args[0];
+            const to = args[1];
+            const steps = Math.max(2, Math.min(120, Number(args[2] ?? 24) || 24));
+            if (!from || !to) {
+                console.error("  usage: rngpui do drag <selector|x,y> <selector|x,y> [steps]");
+                return 1;
+            }
+            const start = await resolveDrivePoint(driveable, from);
+            const end = await resolveDrivePoint(driveable, to);
+            if (!start || !end) return 1;
+            const startResponse = await driveable.request<ControlResponse>({
+                $cmd: "dragAt",
+                phase: "start",
+                x: start.x,
+                y: start.y,
+            });
+            if (!startResponse.ok) {
+                console.error(`  drag start failed: ${startResponse.error || "no native target"}`);
+                return 1;
+            }
+            let lastTargetId = startResponse.targetId;
+            let activations = 0;
+            for (let i = 1; i <= steps; i++) {
+                const t = i / steps;
+                const x = start.x + (end.x - start.x) * t;
+                const y = start.y + (end.y - start.y) * t;
+                const response = await driveable.request<ControlResponse>({ $cmd: "dragAt", phase: "move", x, y });
+                if (!response.ok) {
+                    await driveable.request<ControlResponse>({ $cmd: "dragAt", phase: "end", x, y });
+                    console.error(`  drag move failed: ${response.error || "no native target"}`);
+                    return 1;
+                }
+                if (response.targetId !== lastTargetId && response.activated) activations += 1;
+                lastTargetId = response.targetId;
+                await sleep(16);
+            }
+            await driveable.request<ControlResponse>({ $cmd: "dragAt", phase: "end", x: end.x, y: end.y });
+            await sleep(150);
+            if (json) console.log(JSON.stringify({ dragged: { from: start, to: end, steps, activations } }));
+            else console.log(`  dragged ${steps} steps from ${start.x.toFixed(0)},${start.y.toFixed(0)} to ${end.x.toFixed(0)},${end.y.toFixed(0)}`);
+            return 0;
+        }
+
+        default:
+            console.error(`  unknown do subcommand: ${sub}`);
+            console.error("  available: hud, tap, type, key, scroll, drag");
+            return 1;
+    }
+}
+
+async function resolveDrivePoint(driveable: DriveableHost, selector: string): Promise<{ x: number; y: number } | null> {
+    const pt = parsePoint(selector);
+    if (pt) return pt;
+    const dump = await driveable.dump();
+    const { best } = resolve(dump, selector);
+    const center = best ? centerOf(best.node) : null;
+    if (!center) {
+        console.error(`  no node matched "${selector}"`);
+        return null;
+    }
+    return center;
+}