@houwert/conductor 0.24.0 → 0.25.0

package/dist/commands/input-server.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.inputServer = inputServer;
+exports.HELP = `  input-server                        Start (if needed) and print the streaming-input WebSocket for the device`;
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+/**
+ * Ensure the device daemon + streaming-input socket are up and print the
+ * loopback WebSocket URL the host IDE connects to for pointer/key/button
+ * streaming. See docs/device-input-migration.md.
+ */
+async function inputServer(opts = {}, sessionName = 'default') {
+    try {
+        const info = await (0, runner_js_1.inputServerInfo)(sessionName);
+        if (opts.json) {
+            (0, output_js_1.printData)(info, opts);
+        }
+        else {
+            console.log(`input server [${info.device}] (${info.platform}): ${info.url}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`input-server — ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+}

package/dist/commands/launch-app.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.launchApp = launchApp;
@@ -12,11 +15,16 @@ exports.HELP = `  launch-app <appId>                  Launch app (saves to sessi
                                       the user out of every app on the simulator. Cannot be undone
                                       without re-entering credentials.
     --no-stop-app                     Do not stop the app before launching (resume instead of restart)
-    --argument key=value              Set launch argument (repeatable)`;
+    --argument key=value              Set launch argument (repeatable)
+    --inject                          iOS simulator only: inject the in-process control library
+                                      (DYLD_INSERT_LIBRARIES) so native-* inspection commands work`;
 const runner_js_1 = require("../runner.js");
 const session_js_1 = require("../session.js");
 const output_js_1 = require("../output.js");
 const ios_js_1 = require("../drivers/ios.js");
+const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const ios_inproc_js_1 = require("../drivers/ios-inproc.js");
+const fs_1 = __importDefault(require("fs"));
 const android_js_1 = require("../drivers/android.js");
 const web_js_1 = require("../drivers/web.js");
 const vega_js_1 = require("../drivers/vega.js");
@@ -30,6 +38,7 @@ async function launchApp(appId, deviceId, opts = {}, sessionName = 'default', fl
         process.stderr.write('warning: --clear-state / --clear-keychain wipes app data AND signed-in state; ' +
             'the user will be signed out and cannot be recovered without their credentials.\n');
     }
+    let injectionNote = '';
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
         if (flags.clearKeychain)
             await driver.clearKeychain();
@@ -47,7 +56,25 @@ async function launchApp(appId, deviceId, opts = {}, sessionName = 'default', fl
                 await driver.stopApp(appId);
         }
         if (driver instanceof ios_js_1.IOSDriver) {
-            await driver.launchApp(appId, flags.launchArgs);
+            if (flags.inject) {
+                const dylibPath = await (0, bootstrap_js_1.getInprocDylibPath)(driver.platform);
+                if (!fs_1.default.existsSync(dylibPath)) {
+                    throw new Error(`--inject: in-process library not found at ${dylibPath}. ` +
+                        `Build it with packages/ios-inproc/tools/build-inproc-dylib.sh`);
+                }
+                const deviceId = driver.deviceId;
+                if (!deviceId)
+                    throw new Error('--inject requires a resolved iOS simulator device');
+                const inprocPort = (0, ios_inproc_js_1.getInprocPort)(deviceId);
+                await driver.launchApp(appId, flags.launchArgs, { dylibPath, inprocPort });
+                const ready = await new ios_inproc_js_1.InprocClient(inprocPort).waitUntilReady(10000);
+                injectionNote = ready
+                    ? ` (in-process control ready on :${inprocPort})`
+                    : ` (warning: injected but in-process server did not answer on :${inprocPort})`;
+            }
+            else {
+                await driver.launchApp(appId, flags.launchArgs);
+            }
         }
         else if (driver instanceof web_js_1.WebDriver) {
             await driver.launchApp(appId);
@@ -60,7 +87,7 @@ async function launchApp(appId, deviceId, opts = {}, sessionName = 'default', fl
         }
     }, sessionName);
     if (result.success) {
-        (0, output_js_1.printSuccess)(`launch-app "${appId}" — done`, opts);
+        (0, output_js_1.printSuccess)(`launch-app "${appId}" — done${injectionNote}`, opts);
         return 0;
     }
     else {

package/dist/commands/native-rn.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RN_PROPS_HELP = exports.RN_SET_HELP = void 0;
+exports.nativeRnSet = nativeRnSet;
+exports.nativeRnProps = nativeRnProps;
+/**
+ * React Native prop live-editing over the Metro CDP (JS) channel.
+ *
+ * `RCTParagraphComponentView` and other Fabric host views have no working native
+ * setter and the injected dylib can't reach RN's C++ Fabric layer — so text/style
+ * edits must go through React itself. These commands drive React DevTools'
+ * `overrideProps` (edit) and read a fiber's `memoizedProps` (raw JSX props),
+ * reusing the same Metro CDP connection as `conductor debug`.
+ *
+ * Reads a component's reactTag from `native-inspect` (`rn.reactTag`).
+ */
+exports.RN_SET_HELP = `  native-rn-set --react-tag <n> --path <dot.path> --value <json>   Live-edit an RN component's props via React (text, style.color, …; dev builds only)`;
+exports.RN_PROPS_HELP = `  native-rn-props --react-tag <n>      Raw JSX props (memoizedProps) of an RN fiber by reactTag`;
+const metro_cdp_js_1 = require("../drivers/metro-cdp.js");
+const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const metro_scripts_js_1 = require("../drivers/metro-scripts.js");
+const output_js_1 = require("../output.js");
+/** Session → device/platform for Metro target selection (mirrors debug.ts). */
+function resolveSession(sessionName) {
+    if (!sessionName || sessionName === 'default') {
+        return { deviceId: undefined, platformPromise: Promise.resolve(undefined) };
+    }
+    return {
+        deviceId: sessionName,
+        platformPromise: (0, bootstrap_js_1.detectPlatform)(sessionName).catch(() => undefined),
+    };
+}
+/** JSON-parse a --value, falling back to the raw string (so bare text works). */
+function parseValue(raw) {
+    try {
+        return { json: JSON.stringify(JSON.parse(raw)) };
+    }
+    catch {
+        return { json: JSON.stringify(raw) };
+    }
+}
+async function nativeRnSet(args, opts, sessionName, rnOpts) {
+    const tag = Number(args.reactTag);
+    if (!Number.isInteger(tag)) {
+        (0, output_js_1.printError)('native-rn-set needs --react-tag <n> (from native-inspect rn.reactTag)', opts);
+        return 1;
+    }
+    if (!args.path) {
+        (0, output_js_1.printError)('native-rn-set needs --path <dot.path> (e.g. children, style.color)', opts);
+        return 1;
+    }
+    if (args.value === undefined) {
+        (0, output_js_1.printError)('native-rn-set needs --value <json> (JSON; a bare string is fine for text)', opts);
+        return 1;
+    }
+    const path = args.path.split('.').filter((s) => s.length > 0);
+    const { json } = parseValue(args.value);
+    const port = rnOpts.port ?? 8081;
+    const { deviceId, platformPromise } = resolveSession(sessionName);
+    const client = new metro_cdp_js_1.MetroCdpClient();
+    try {
+        const platform = await platformPromise;
+        await client.connect({ port, deviceId, platform, targetIndex: rnOpts.targetIndex });
+        const raw = await client.evaluate((0, metro_scripts_js_1.makeOverridePropsScript)(tag, path, json), true);
+        const res = JSON.parse(raw);
+        client.close();
+        if (res.status !== 'ok') {
+            (0, output_js_1.printError)(res.message ?? 'overrideProps failed', opts);
+            return 1;
+        }
+        const out = { status: 'ok', applied: res.applied ?? true };
+        if (res.note)
+            out.note = res.note;
+        (0, output_js_1.printData)(out, opts);
+        return 0;
+    }
+    catch (err) {
+        client.close();
+        (0, output_js_1.printError)(`native-rn-set — ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+}
+async function nativeRnProps(args, opts, sessionName, rnOpts) {
+    const tag = Number(args.reactTag);
+    if (!Number.isInteger(tag)) {
+        (0, output_js_1.printError)('native-rn-props needs --react-tag <n> (from native-inspect rn.reactTag)', opts);
+        return 1;
+    }
+    const port = rnOpts.port ?? 8081;
+    const { deviceId, platformPromise } = resolveSession(sessionName);
+    const client = new metro_cdp_js_1.MetroCdpClient();
+    try {
+        const platform = await platformPromise;
+        await client.connect({ port, deviceId, platform, targetIndex: rnOpts.targetIndex });
+        const raw = await client.evaluate((0, metro_scripts_js_1.makeRnPropsScript)(tag), true);
+        const res = JSON.parse(raw);
+        client.close();
+        if (res.status !== 'ok') {
+            (0, output_js_1.printError)(res.message ?? 'reading props failed', opts);
+            return 1;
+        }
+        (0, output_js_1.printData)({ status: 'ok', props: res.props ?? {} }, opts);
+        return 0;
+    }
+    catch (err) {
+        client.close();
+        (0, output_js_1.printError)(`native-rn-props — ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+}

package/dist/commands/native.js

@@ -0,0 +1,320 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIND_HELP = exports.HIGHLIGHT_HELP = exports.HITTEST_HELP = exports.CONSTRAINTS_HELP = exports.PROPS_HELP = exports.SET_HELP = exports.VIEW_HELP = exports.EVAL_HELP = exports.APPEARANCE_HELP = exports.HEAP_HELP = exports.NETWORK_HELP = exports.CONSOLE_HELP = exports.RAW_HELP = exports.SNAPSHOT_HELP = exports.IMAGE_HELP = exports.SCREENSHOT_HELP = exports.NAV_HELP = exports.INSPECT_HELP = exports.PING_HELP = void 0;
+exports.nativePing = nativePing;
+exports.nativeInspect = nativeInspect;
+exports.nativeNav = nativeNav;
+exports.nativeScreenshot = nativeScreenshot;
+exports.nativeImage = nativeImage;
+exports.nativeRaw = nativeRaw;
+exports.nativeConsole = nativeConsole;
+exports.nativeNetwork = nativeNetwork;
+exports.nativeHeap = nativeHeap;
+exports.nativeAppearance = nativeAppearance;
+exports.nativeEval = nativeEval;
+exports.nativeSnapshot = nativeSnapshot;
+exports.nativeView = nativeView;
+exports.nativeSet = nativeSet;
+exports.nativeProps = nativeProps;
+exports.nativeConstraints = nativeConstraints;
+exports.nativeHittest = nativeHittest;
+exports.nativeHighlight = nativeHighlight;
+exports.nativeFind = nativeFind;
+// iOS/tvOS simulator only; the app must be launched with `launch-app --inject`.
+exports.PING_HELP = `  native-ping                          Check the injected in-process control library is alive`;
+exports.INSPECT_HELP = `  native-inspect                       Full native view tree: colors, fonts, text, layer visuals, absFrame`;
+exports.NAV_HELP = `  native-nav                           Navigation state: view-controller stacks, tabs, presented`;
+exports.SCREENSHOT_HELP = `  native-screenshot --output <p.png>   In-process PNG of the key window`;
+exports.IMAGE_HELP = `  native-image <x,y,w,h> --output <p>  PNG crop of a window-absolute rect (use a node's absFrame)`;
+exports.SNAPSHOT_HELP = `  native-snapshot <id> --output <p>    Isolated PNG of one view (own content, transparent) for 3D-explosion layers; --with-subviews for the composited view`;
+exports.RAW_HELP = `  native-raw <path>                    GET any in-process endpoint (e.g. '/get?id=..&keyPath=layer.cornerRadius'); --output <f> saves image endpoints. See packages/ios-inproc/README.md for the full list`;
+exports.CONSOLE_HELP = `  native-console [--since <n>]         App stdout/stderr + logs (poll with the returned cursor)`;
+exports.NETWORK_HELP = `  native-network [--since <n>]         Captured HTTP requests/responses (poll with cursor)`;
+exports.HEAP_HELP = `  native-heap --class <name> | --pattern <s> | --read <addr> [--key <keyPath>]   Live object browser`;
+exports.APPEARANCE_HELP = `  native-appearance <light|dark|system> | --direction <ltr|rtl> | --content-size <cat> | --anim-speed <n>`;
+exports.EVAL_HELP = `  native-eval <swift>                  Compile & run arbitrary Swift inside the app; --mode full for a whole function body. e.g. native-eval 'UIApplication.shared.connectedScenes.count'`;
+exports.VIEW_HELP = `  native-view <id>                     Full property detail for a view (id from native-inspect)`;
+exports.SET_HELP = `  native-set <id> <key> <value>        Live-edit a view property (alpha, hidden, backgroundColor, tintColor, cornerRadius, borderWidth, borderColor, frame, text, textColor). text/textColor also apply to RN Fabric text`;
+exports.PROPS_HELP = `  native-props <id>                    React Native Fabric props: typed ViewProps + raw JS prop bag (Fabric views only)`;
+exports.CONSTRAINTS_HELP = `  native-constraints <id>              Auto Layout constraints affecting a view + ambiguity`;
+exports.HITTEST_HELP = `  native-hittest <x,y>                 Topmost view at a screen point + ancestor chain`;
+exports.HIGHLIGHT_HELP = `  native-highlight <id>                Flash a highlight over the view on the device`;
+exports.FIND_HELP = `  native-find [--class <name>] [--text <s>]  Search views by class and/or text`;
+const fs_1 = __importDefault(require("fs"));
+const runner_js_1 = require("../runner.js");
+const session_js_1 = require("../session.js");
+const output_js_1 = require("../output.js");
+const ios_js_1 = require("../drivers/ios.js");
+const ios_inproc_js_1 = require("../drivers/ios-inproc.js");
+const eval_compiler_js_1 = require("../drivers/eval-compiler.js");
+/** Resolve the in-process client for the current iOS/tvOS session, or print why not. */
+async function resolveClient(sessionName, opts) {
+    const driver = await (0, runner_js_1.getDriver)(sessionName);
+    if (!(driver instanceof ios_js_1.IOSDriver)) {
+        (0, output_js_1.printError)('native commands are iOS/tvOS simulator only', opts);
+        return null;
+    }
+    const deviceId = driver.deviceId;
+    if (!deviceId) {
+        (0, output_js_1.printError)('native commands require a resolved simulator device', opts);
+        return null;
+    }
+    return new ios_inproc_js_1.InprocClient((0, ios_inproc_js_1.getInprocPort)(deviceId));
+}
+async function nativePing(opts = {}, sessionName = 'default') {
+    try {
+        const client = await resolveClient(sessionName, opts);
+        if (!client)
+            return 1;
+        const res = await client.ping().catch(() => null);
+        if (!res || res.status !== 'ok') {
+            (0, output_js_1.printError)('no in-process server. Launch the app with: launch-app <appId> --inject', opts);
+            return 1;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...res, status: 'ok' }));
+        }
+        else {
+            (0, output_js_1.printSuccess)(`in-process control alive — pid ${res.pid}, app ${res.app}`, opts);
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`native-ping failed: ${err.message}`, opts);
+        return 1;
+    }
+}
+async function nativeInspect(opts = {}, sessionName = 'default') {
+    return runQuery('native-inspect', (c) => c.inspect(), opts, sessionName);
+}
+async function nativeNav(opts = {}, sessionName = 'default') {
+    return runQuery('native-nav', (c) => c.nav(), opts, sessionName);
+}
+async function nativeScreenshot(output, opts = {}, sessionName = 'default') {
+    return saveImage('native-screenshot', (c) => c.screenshot(), output, opts, sessionName);
+}
+async function nativeImage(frameArg, output, opts = {}, sessionName = 'default') {
+    const parts = (frameArg ?? '').split(',').map((n) => Number(n.trim()));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+        (0, output_js_1.printError)('native-image needs a rect: native-image <x,y,w,h> --output <file>', opts);
+        return 1;
+    }
+    const [x, y, w, h] = parts;
+    return saveImage('native-image', (c) => c.image({ x, y, w, h }), output, opts, sessionName);
+}
+async function nativeRaw(reqPath, output, opts = {}, sessionName = 'default') {
+    if (!reqPath) {
+        (0, output_js_1.printError)("native-raw needs a path, e.g. native-raw '/get?id=0x..&keyPath=alpha'", opts);
+        return 1;
+    }
+    try {
+        const client = await resolveClient(sessionName, opts);
+        if (!client)
+            return 1;
+        const { contentType, body } = await client.rawRequest(reqPath);
+        if (contentType.startsWith('image/')) {
+            const dest = output ?? `native-raw-${Date.now()}.png`;
+            fs_1.default.writeFileSync(dest, body);
+            (0, output_js_1.printSuccess)(`saved ${body.length} bytes → ${dest}`, opts);
+        }
+        else {
+            // Pretty-print JSON when possible.
+            const text = body.toString('utf-8');
+            try {
+                console.log(JSON.stringify(JSON.parse(text), null, opts.json ? 0 : 2));
+            }
+            catch {
+                console.log(text);
+            }
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`native-raw failed: ${err.message}. Is the app launched with --inject?`, opts);
+        return 1;
+    }
+}
+async function nativeConsole(since, opts = {}, sessionName = 'default') {
+    return runQuery('native-console', (c) => c.rawJson(`/console?since=${since ?? 0}`), opts, sessionName);
+}
+async function nativeNetwork(since, opts = {}, sessionName = 'default') {
+    return runQuery('native-network', (c) => c.rawJson(`/network?since=${since ?? 0}`), opts, sessionName);
+}
+async function nativeHeap(filters, opts = {}, sessionName = 'default') {
+    let path;
+    if (filters.read) {
+        path = `/heap/read?address=${encodeURIComponent(filters.read)}`;
+        if (filters.key)
+            path += `&keyPath=${encodeURIComponent(filters.key)}`;
+    }
+    else if (filters.className) {
+        path = `/heap/instances?class=${encodeURIComponent(filters.className)}`;
+    }
+    else {
+        path = `/heap/classes?pattern=${encodeURIComponent(filters.pattern ?? '')}`;
+    }
+    return runQuery('native-heap', (c) => c.rawJson(path), opts, sessionName);
+}
+async function nativeAppearance(args, opts = {}, sessionName = 'default') {
+    let path;
+    if (args.direction)
+        path = `/direction?direction=${encodeURIComponent(args.direction)}`;
+    else if (args.contentSize)
+        path = `/contentsize?category=${encodeURIComponent(args.contentSize)}`;
+    else if (args.animSpeed)
+        path = `/animspeed?speed=${encodeURIComponent(args.animSpeed)}`;
+    else if (args.style)
+        path = `/appearance?style=${encodeURIComponent(args.style)}`;
+    else {
+        (0, output_js_1.printError)('native-appearance needs <light|dark|system> or --direction/--content-size/--anim-speed', opts);
+        return 1;
+    }
+    return runQuery('native-appearance', (c) => c.rawJson(path), opts, sessionName);
+}
+async function nativeEval(code, mode, opts = {}, sessionName = 'default') {
+    if (!code) {
+        (0, output_js_1.printError)("native-eval needs Swift code, e.g. native-eval 'UIScreen.main.bounds'", opts);
+        return 1;
+    }
+    try {
+        const driver = await (0, runner_js_1.getDriver)(sessionName);
+        if (!(driver instanceof ios_js_1.IOSDriver)) {
+            (0, output_js_1.printError)('native-eval is iOS/tvOS simulator only', opts);
+            return 1;
+        }
+        const deviceId = driver.deviceId;
+        const bundleId = (await (0, session_js_1.getSession)(sessionName)).appId;
+        if (!deviceId || !bundleId) {
+            (0, output_js_1.printError)('native-eval needs a resolved device and a launched app (launch-app <appId> --inject)', opts);
+            return 1;
+        }
+        const compiled = await (0, eval_compiler_js_1.compileEval)(code, mode, driver.platform, deviceId, bundleId);
+        if (!compiled.ok || !compiled.dylibPath) {
+            (0, output_js_1.printError)(compiled.error ?? 'compile failed', opts);
+            return 1;
+        }
+        const client = new ios_inproc_js_1.InprocClient((0, ios_inproc_js_1.getInprocPort)(deviceId));
+        const res = await client
+            .rawJson(`/eval?dylib=${encodeURIComponent(compiled.dylibPath)}`, 30000)
+            .catch((err) => {
+            throw new Error(`${err.message}. Is the app running with launch-app --inject?`);
+        });
+        if (res.status !== 'ok') {
+            (0, output_js_1.printError)(`eval error: ${res.message ?? JSON.stringify(res)}`, opts);
+            return 1;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ status: 'ok', result: res.result, info: compiled.info }));
+        }
+        else {
+            (0, output_js_1.printSuccess)(`[${compiled.info}] ${res.result}`, opts);
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`native-eval failed: ${err.message}`, opts);
+        return 1;
+    }
+}
+async function nativeSnapshot(id, withSubviews, output, opts = {}, sessionName = 'default') {
+    if (!id) {
+        (0, output_js_1.printError)('native-snapshot needs a view id (from native-inspect)', opts);
+        return 1;
+    }
+    return saveImage('native-snapshot', (c) => c.snapshot(id, withSubviews), output, opts, sessionName);
+}
+async function nativeView(id, opts = {}, sessionName = 'default') {
+    if (!id) {
+        (0, output_js_1.printError)('native-view needs a view id (from native-inspect)', opts);
+        return 1;
+    }
+    return runQuery('native-view', (c) => c.view(id), opts, sessionName);
+}
+async function nativeSet(args, opts = {}, sessionName = 'default') {
+    const [id, key, ...valueParts] = args;
+    const value = valueParts.join(' ');
+    if (!id || !key || value === '') {
+        (0, output_js_1.printError)('usage: native-set <id> <key> <value>', opts);
+        return 1;
+    }
+    return runQuery('native-set', (c) => c.set(id, key, value), opts, sessionName);
+}
+async function nativeProps(id, opts = {}, sessionName = 'default') {
+    if (!id) {
+        (0, output_js_1.printError)('native-props needs a view id (from native-inspect)', opts);
+        return 1;
+    }
+    return runQuery('native-props', (c) => c.props(id), opts, sessionName);
+}
+async function nativeConstraints(id, opts = {}, sessionName = 'default') {
+    if (!id) {
+        (0, output_js_1.printError)('native-constraints needs a view id', opts);
+        return 1;
+    }
+    return runQuery('native-constraints', (c) => c.constraints(id), opts, sessionName);
+}
+async function nativeHittest(point, opts = {}, sessionName = 'default') {
+    const [x, y] = (point ?? '').split(',').map((n) => Number(n.trim()));
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        (0, output_js_1.printError)('usage: native-hittest <x,y>', opts);
+        return 1;
+    }
+    return runQuery('native-hittest', (c) => c.hittest(x, y), opts, sessionName);
+}
+async function nativeHighlight(id, opts = {}, sessionName = 'default') {
+    if (!id) {
+        (0, output_js_1.printError)('native-highlight needs a view id', opts);
+        return 1;
+    }
+    return runQuery('native-highlight', (c) => c.highlight(id), opts, sessionName);
+}
+async function nativeFind(filters, opts = {}, sessionName = 'default') {
+    if (!filters.className && !filters.text) {
+        (0, output_js_1.printError)('native-find needs --class <name> and/or --text <substring>', opts);
+        return 1;
+    }
+    return runQuery('native-find', (c) => c.find(filters), opts, sessionName);
+}
+async function saveImage(label, fetch, output, opts, sessionName) {
+    try {
+        const client = await resolveClient(sessionName, opts);
+        if (!client)
+            return 1;
+        const png = await fetch(client).catch((err) => {
+            throw new Error(`${err.message}. Is the app running with launch-app --inject?`);
+        });
+        const dest = output ?? `${label}-${Date.now()}.png`;
+        fs_1.default.writeFileSync(dest, png);
+        if (opts.json) {
+            console.log(JSON.stringify({ status: 'ok', output: dest, bytes: png.length }));
+        }
+        else {
+            (0, output_js_1.printSuccess)(`${label} → ${dest} (${png.length} bytes)`, opts);
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`${label} failed: ${err.message}`, opts);
+        return 1;
+    }
+}
+async function runQuery(label, query, opts, sessionName) {
+    try {
+        const client = await resolveClient(sessionName, opts);
+        if (!client)
+            return 1;
+        const res = await query(client).catch((err) => {
+            throw new Error(`${err.message}. Is the app running with launch-app --inject?`);
+        });
+        // Always emit JSON — these payloads are structured data for the agent.
+        console.log(JSON.stringify(res, null, opts.json ? 0 : 2));
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`${label} failed: ${err.message}`, opts);
+        return 1;
+    }
+}

package/dist/commands/start-device.js

@@ -8,6 +8,7 @@ exports.pickAndroidArch = pickAndroidArch;
 exports.parseInstalledSystemImages = parseInstalledSystemImages;
 exports.pickSystemImage = pickSystemImage;
 exports.buildAvdmanagerCreateArgs = buildAvdmanagerCreateArgs;
+exports.raiseAvdConfigRam = raiseAvdConfigRam;
 exports.startDevice = startDevice;
 exports.HELP = `  start-device
     --platform <ios|android|tvos|web|vega> Boot a simulator/emulator, start the web driver (Playwright), or boot/attach a Vega VVD
@@ -16,10 +17,14 @@ exports.HELP = `  start-device
     --name <name>                     Set a custom name on the device after creation (iOS/tvOS/web)
     --device-type <name>              iOS/tvOS device type (e.g. "iPhone 16 Pro", "Apple TV 4K") or
                                       Android device profile (e.g. "pixel_7"); creates if needed
+    --memory <mb>                     Android only: RAM (MB) for a newly-created AVD (default: 4096).
+                                      Only raises; applied at creation time, never to an existing AVD
     --system-image <id>               Android only: override auto-picked system image
                                       (e.g. "system-images;android-34;google_apis;arm64-v8a")
     --browser <chromium|firefox|webkit> Web only: which Playwright browser to launch (default: chromium)`;
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const runner_js_1 = require("../runner.js");
 const sdk_js_1 = require("../android/sdk.js");
@@ -32,6 +37,10 @@ const cli_js_1 = require("../drivers/vega/cli.js");
 const IOS_BOOT_TIMEOUT_MS = 120000;
 const ANDROID_BOOT_TIMEOUT_MS = 120000;
 const POLL_MS = 1000;
+// Stock TV device profiles default to 1024MB RAM, which OOM-kills heavy RN debug
+// builds during JS bundle load. Raise freshly-created AVDs to this floor.
+const ANDROID_AVD_RAM_FLOOR_MB = 4096;
+const ANDROID_AVD_HEAP_MB = 512;
 async function listIOSSimulators() {
     const result = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'list', 'devices', '--json']);
     if (!result.success)
@@ -496,6 +505,38 @@ function pickSystemImage(installed, apiLevel, arch) {
 function buildAvdmanagerCreateArgs(avdName, systemImage, deviceProfile) {
     return ['create', 'avd', '-n', avdName, '-k', systemImage, '-d', deviceProfile];
 }
+/** Parse a config.ini RAM value; only plain integer MB counts — `M`-suffixed or bogus values are 0. */
+function parsePlainMb(value) {
+    const m = /^(\d+)$/.exec(value.trim());
+    return m ? parseInt(m[1], 10) : 0;
+}
+/**
+ * Rewrite an AVD `config.ini` to raise `hw.ramSize`/`vm.heapSize` to the given floors.
+ * Pure and exported for tests. Values are written as plain integer MB — an `M` suffix
+ * makes the emulator silently fall back to 1024MB. Only ever raises; higher existing
+ * values are kept, and non-integer/`M`-suffixed existing values are treated as 0 so they
+ * get overwritten. Missing keys are appended; all other lines/ordering are preserved.
+ */
+function raiseAvdConfigRam(configIni, targetRamMb, heapMb = ANDROID_AVD_HEAP_MB) {
+    const raiseKey = (contents, key, target) => {
+        const lines = contents.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const m = /^(\s*)([^=\s]+)(\s*=\s*)(.*)$/.exec(lines[i]);
+            if (!m || m[2] !== key)
+                continue;
+            const next = Math.max(parsePlainMb(m[4]), target);
+            lines[i] = `${m[1]}${key}${m[3]}${next}`;
+            return lines.join('\n');
+        }
+        let out = contents;
+        if (out.length > 0 && !out.endsWith('\n'))
+            out += '\n';
+        return `${out}${key} = ${target}\n`;
+    };
+    let result = raiseKey(configIni, 'hw.ramSize', targetRamMb);
+    result = raiseKey(result, 'vm.heapSize', heapMb);
+    return result;
+}
 async function listInstalledSystemImages() {
     const result = await (0, runner_js_1.spawnCommand)('sdkmanager', ['--list_installed']);
     if (!result.success) {
@@ -524,7 +565,7 @@ async function spawnAvdmanagerCreate(args) {
         proc.stdin.end('no\n');
     });
 }
-async function createAndroidAVD(avdName, deviceProfile, apiLevel, systemImageOverride) {
+async function createAndroidAVD(avdName, deviceProfile, apiLevel, systemImageOverride, targetRamMb) {
     const arch = pickAndroidArch();
     let systemImage;
     if (systemImageOverride) {
@@ -562,6 +603,22 @@ async function createAndroidAVD(avdName, deviceProfile, apiLevel, systemImageOve
     if (!avds.includes(avdName)) {
         throw new Error(`AVD "${avdName}" was not registered after creation (not in emulator -list-avds).`);
     }
+    // Raise RAM above the stock profile default so heavy RN debug builds aren't OOM-killed.
+    const avdHome = process.env.ANDROID_AVD_HOME || path_1.default.join(os_1.default.homedir(), '.android', 'avd');
+    const configPath = path_1.default.join(avdHome, `${avdName}.avd`, 'config.ini');
+    if (fs_1.default.existsSync(configPath)) {
+        try {
+            const current = fs_1.default.readFileSync(configPath, 'utf-8');
+            fs_1.default.writeFileSync(configPath, raiseAvdConfigRam(current, targetRamMb), 'utf-8');
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.warn(`Warning: could not raise RAM for AVD "${avdName}" (${msg}). Continuing.`);
+        }
+    }
+    else {
+        console.warn(`Warning: config.ini not found for AVD "${avdName}" at ${configPath}. Continuing.`);
+    }
 }
 async function waitForAndroidBoot(avdName) {
     const deadline = Date.now() + ANDROID_BOOT_TIMEOUT_MS;
@@ -596,7 +653,7 @@ async function waitForAndroidBoot(avdName) {
     }
     throw new Error(`Android emulator (${avdName}) did not appear within ${ANDROID_BOOT_TIMEOUT_MS / 1000}s`);
 }
-async function startAndroid(avdName, opts, deviceType, osVersion, systemImage) {
+async function startAndroid(avdName, opts, deviceType, osVersion, systemImage, memory) {
     let avds;
     try {
         avds = await listAVDs();
@@ -616,8 +673,9 @@ async function startAndroid(avdName, opts, deviceType, osVersion, systemImage) {
             return 1;
         }
         console.log(`No AVD "${avdName}" found. Creating one with device profile "${deviceType}"...`);
+        const targetRamMb = memory && memory > 0 ? memory : ANDROID_AVD_RAM_FLOOR_MB;
         try {
-            await createAndroidAVD(avdName, deviceType, osVersion, systemImage);
+            await createAndroidAVD(avdName, deviceType, osVersion, systemImage, targetRamMb);
         }
         catch (e) {
             (0, output_js_1.printError)(e instanceof Error ? e.message : String(e), opts);
@@ -761,7 +819,7 @@ async function startDevice(platform, opts, flags) {
         case 'tvos':
             return startTvOS(flags.osVersion, opts, flags.name, flags.deviceType);
         case 'android':
-            return startAndroid(flags.avd, opts, flags.deviceType, flags.osVersion, flags.systemImage);
+            return startAndroid(flags.avd, opts, flags.deviceType, flags.osVersion, flags.systemImage, flags.memory);
         case 'web':
             return startWebDriver(opts, flags.browser, flags.name);
         case 'vega':