@tapflowio/android-agent 0.6.0 → 0.7.0

package/dist/AndroidAgent.d.ts

@@ -1,6 +1,7 @@
 import type { Device, DeviceAgent } from '@tapflowio/agent-core';
 import { type SleepBlocker } from '@tapflowio/agent-core/utils';
 import { AdbWrapper } from './AdbWrapper.js';
+export declare function pickAndroidBackend(serial: string, env?: NodeJS.ProcessEnv): 'grpc' | 'scrcpy';
 export interface AndroidAgentOptions {
     fps?: number;
     /** AVD name or emulator serial to expose. Omit to expose all detected devices. */
@@ -32,7 +33,14 @@ export declare class AndroidAgent implements DeviceAgent {
     private reportResources;
     private cleanupDeviceState;
     private sendDeviceInfo;
+    private forceScrcpy;
+    private useGrpc;
+    private pointerControl;
+    private fire;
+    private grpcPort;
     private startVideoStream;
+    private pumpVideo;
+    private startGrpcVideoStream;
     private restartVideoStream;
     private openStreamWs;
     private handleDeviceBoot;

package/dist/AndroidAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AndroidAgent.d.ts","sourceRoot":"","sources":["../src/AndroidAgent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,MAAM,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAE/E,OAAO,EAOL,KAAK,YAAY,EAIlB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AA+G5C,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B;AAED,qBAAa,YAAa,YAAW,WAAW;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,YAAY,CAAiC;IAGrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,iBAAiB,CAAI;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;gBAE9B,OAAO,GAAE,mBAAwB,EAAE,GAAG,CAAC,EAAE,UAAU;IAS/D,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAG7B;IAEK,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD9C,OAAO,CAAC,gBAAgB;IAsBxB,UAAU,IAAI,IAAI;IAclB,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,cAAc;YAYR,gBAAgB;YA0EhB,kBAAkB;YAmClB,YAAY;YAOZ,gBAAgB;YA2DhB,oBAAoB;IAsBlC,OAAO,CAAC,kBAAkB;YAyNZ,cAAc;IAqC5B,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAE1B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAOnC,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC;IAUhC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM1C"}
+{"version":3,"file":"AndroidAgent.d.ts","sourceRoot":"","sources":["../src/AndroidAgent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,MAAM,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAE/E,OAAO,EASL,KAAK,YAAY,EAKlB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAqI5C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,QAAQ,CAI1G;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B;AAED,qBAAa,YAAa,YAAW,WAAW;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,YAAY,CAAiC;IAGrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,iBAAiB,CAAI;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;gBAE9B,OAAO,GAAE,mBAAwB,EAAE,GAAG,CAAC,EAAE,UAAU;IAS/D,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAG7B;IAEK,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD9C,OAAO,CAAC,gBAAgB;IA2BxB,UAAU,IAAI,IAAI;IAclB,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,QAAQ;YAIF,gBAAgB;YA2DhB,SAAS;YAsDT,oBAAoB;YA6CpB,kBAAkB;YAuClB,YAAY;YAOZ,gBAAgB;YA6DhB,oBAAoB;IAsBlC,OAAO,CAAC,kBAAkB;YAiOZ,cAAc;IAqC5B,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAE1B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAOnC,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC;IAWhC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM1C"}

package/dist/AndroidAgent.js

@@ -1,11 +1,13 @@
 import os from 'os';
 import { WebSocket } from 'ws';
 import { createLogger, PlatformError, ValidationError } from '@tapflowio/agent-core';
-import { createResourceSampler, registerStreamWs, sendBinaryWithBackpressure, createRateLimitedDropWarn, createThroughputSampler, createSleepBlocker, DEFAULT_BACKPRESSURE_BYTES, writeEnvelopeHeader, CODEC_H264, } from '@tapflowio/agent-core/utils';
+import { createResourceSampler, registerStreamWs, disableNagle, createKeyframeAwareSender, pickMaxSize, createRateLimitedDropWarn, createThroughputSampler, createSleepBlocker, DEFAULT_BACKPRESSURE_BYTES, writeEnvelopeHeader, rewriteLowLatencySpsInFrame, CODEC_H264, } from '@tapflowio/agent-core/utils';
 import { AdbWrapper } from './AdbWrapper.js';
 import { EmulatorLauncher } from './EmulatorLauncher.js';
 import { AndroidTouchHelper } from './AndroidTouchHelper.js';
 import { ScrcpySession } from './scrcpy/ScrcpySession.js';
+import { EmulatorGrpcClient } from './emulator/EmulatorGrpcClient.js';
+import { EmulatorVideo } from './emulator/EmulatorVideo.js';
 const logger = createLogger('android-agent');
 // Parse H.264 SPS NAL unit to extract frame dimensions.
 // scrcpy sends a new SPS (inside an IDR keyframe) whenever the capture size changes —
@@ -110,6 +112,16 @@ const ANDROID_BUTTONS = [
     { name: 'volume_down', accessibilityTitle: 'Volume Down', keyCode: 25 },
     { name: 'power', accessibilityTitle: 'Power', keyCode: 26 },
 ];
+// Video backend per device: emulators (serial `emulator-*`) default to the gRPC host-encode path
+// (bypasses the guest SW H.264 encoder); real devices use scrcpy (their SoC has a HW encoder).
+// `TAPFLOW_ANDROID_BACKEND=scrcpy|grpc` overrides either way.
+export function pickAndroidBackend(serial, env = process.env) {
+    if (env.TAPFLOW_ANDROID_BACKEND === 'scrcpy')
+        return 'scrcpy';
+    if (env.TAPFLOW_ANDROID_BACKEND === 'grpc')
+        return 'grpc';
+    return serial.startsWith('emulator-') ? 'grpc' : 'scrcpy';
+}
 export class AndroidAgent {
     adb;
     launcher;
@@ -152,6 +164,7 @@ export class AndroidAgent {
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(relayUrl);
             ws.once('open', () => {
+                disableNagle(ws);
                 ws.send(JSON.stringify({
                     type: 'agent:register',
                     platform: 'android',
@@ -197,6 +210,11 @@ export class AndroidAgent {
                 touchHelper: null,
                 streamWs: null,
                 scrcpySession: null,
+                emulatorVideo: null,
+                grpcClient: null,
+                cornerRadius: 0,
+                secureContext: false,
+                external: false,
                 displayWidth: 0,
                 displayHeight: 0,
                 videoWidth: 0,
@@ -258,7 +276,7 @@ export class AndroidAgent {
     reportResources() {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        const bootedCount = Array.from(this.deviceStates.values()).filter((s) => s.scrcpySession !== null).length;
+        const bootedCount = Array.from(this.deviceStates.values()).filter((s) => s.scrcpySession !== null || s.emulatorVideo !== null).length;
         const slotsTotal = this.deviceStates.size;
         const { memUsedMB, memTotalMB } = this.resources.getMemoryUsage();
         this.ws.send(JSON.stringify({
@@ -278,6 +296,11 @@ export class AndroidAgent {
         if (serial && state.scrcpySession)
             state.scrcpySession.stop(serial);
         state.scrcpySession = null;
+        state.emulatorVideo?.stop();
+        state.emulatorVideo = null;
+        state.grpcClient?.close();
+        state.grpcClient = null;
+        state.cornerRadius = 0;
         state.touchHelper?.stop();
         state.touchHelper = null;
         state.streamWs?.close();
@@ -295,10 +318,55 @@ export class AndroidAgent {
             },
         }));
     }
+    forceScrcpy() {
+        return process.env.TAPFLOW_ANDROID_BACKEND === 'scrcpy';
+    }
+    useGrpc(serial) {
+        return pickAndroidBackend(serial) === 'grpc';
+    }
+    // The active low-latency pointer backend (gRPC preferred), or null when only the ADB fallback
+    // (AndroidTouchHelper) is available. Coordinates go in state.videoWidth/Height px.
+    pointerControl(state) {
+        if (state.grpcClient)
+            return state.grpcClient;
+        if (state.scrcpySession)
+            return state.scrcpySession.control;
+        return null;
+    }
+    // Fire-and-forget a pointer call: gRPC methods are async (swallow rejection), scrcpy sync (no-op).
+    fire(r) {
+        if (r)
+            r.catch(() => { });
+    }
+    // Port to launch the emulator with (`-grpc <port>`, unsecured localhost). A plain `-grpc` endpoint
+    // is unsecured; without it the emulator opens its DEFAULT gRPC port with token auth, which our
+    // unauthenticated client can't use. Launches are always AVDs (emulators), so default to gRPC
+    // unless explicitly forced to scrcpy. undefined = don't open gRPC.
+    grpcPort() {
+        return this.forceScrcpy() ? undefined : (Number(process.env.TAPFLOW_ANDROID_GRPC_PORT) || 8554);
+    }
     async startVideoStream(state, streamWs) {
         const serial = this.adb.getSerial(state.deviceId);
         if (!serial)
             return;
+        // Emulator: capture via gRPC streamScreenshot + Mac VideoToolbox (bypasses the guest SW H.264
+        // encoder). On any failure (e.g. an externally-booted emulator without `-grpc`), fall back to
+        // scrcpy so streaming still works.
+        if (this.useGrpc(serial)) {
+            try {
+                await this.startGrpcVideoStream(state, streamWs, serial);
+                return;
+            }
+            catch (e) {
+                logger.warn(`gRPC backend failed (${e.message}) — falling back to scrcpy`);
+                state.emulatorVideo?.stop();
+                state.emulatorVideo = null;
+                state.grpcClient?.close();
+                state.grpcClient = null;
+                state.touchHelper?.stop();
+                state.touchHelper = null;
+            }
+        }
         const touchHelper = new AndroidTouchHelper(this.adb, serial);
         touchHelper.start();
         state.touchHelper = touchHelper;
@@ -310,14 +378,46 @@ export class AndroidAgent {
         state.displayHeight = info.height;
         state.videoWidth = info.width;
         state.videoHeight = info.height;
-        const stream = session.video.start();
-        const reader = stream.getReader();
+        const reader = session.video.start().getReader();
+        // Detect video size changes via H.264 SPS so ScrcpyControl.screenSize always matches what
+        // scrcpy is encoding (landscape-aware vs portrait-locked). The SPS leads the keyframe AU.
+        const onFrame = (value) => {
+            const parsed = parseSpsFromNal(value.payload);
+            if (parsed && (parsed.width !== state.videoWidth || parsed.height !== state.videoHeight)) {
+                state.videoWidth = parsed.width;
+                state.videoHeight = parsed.height;
+                state.scrcpySession?.control.updateScreenSize(parsed.width, parsed.height);
+                logger.info(`video size → ${parsed.width}×${parsed.height}`);
+            }
+        };
+        void this.pumpVideo(state, streamWs, reader, onFrame, () => session.control.resetVideo()).then(() => {
+            if (state.scrcpySession === session && !state.restarting) {
+                state.restarting = true;
+                void this.restartVideoStream(state);
+            }
+        });
+    }
+    // Shared frame pump for both video backends: reads H.264 access units, wraps each in the TFFE
+    // envelope (codec + per-AU keyframe flag, so the relay's keyframe-aware backpressure preserves the
+    // reference chain), and sends with backpressure + optional throughput metrics. `onFrame` lets a
+    // backend inspect each frame (scrcpy parses SPS for size). Resolves when the source stream ends.
+    async pumpVideo(state, streamWs, reader, onFrame, requestIdr) {
         const threshold = Number(process.env.TAPFLOW_WS_BACKPRESSURE_BYTES) || DEFAULT_BACKPRESSURE_BYTES;
         const warnDrop = createRateLimitedDropWarn(logger, state.deviceId);
-        // Opt-in throughput baseline (TAPFLOW_STREAM_METRICS=1): logs fps/KB·s/drop every 5s,
-        // so the Android source rate can be compared against the relay→browser drop logs and
-        // against the iOS agent (which already samples). Distinguishes source-bound (low fpsSent)
-        // from decode/LAN-bound (high fpsSent, high dropRate).
+        // Keyframe-aware backpressure: when the agent→relay socket fills, drop whole GOPs to the next
+        // keyframe (never forward an orphan P-frame whose reference was dropped — that decodes to a
+        // sheared/ghosted frame until the next IDR). On a drop with no keyframe, ask the encoder for an
+        // IDR (throttled) so the stream resyncs fast instead of waiting for the periodic one.
+        const dropper = createKeyframeAwareSender();
+        let lastIdrReq = 0;
+        const onWantKeyframe = requestIdr
+            ? () => { const now = Date.now(); if (now - lastIdrReq >= 500) {
+                lastIdrReq = now;
+                requestIdr();
+            } }
+            : undefined;
+        // Opt-in throughput baseline (TAPFLOW_STREAM_METRICS=1): logs fps/KB·s/drop every 5s, so the
+        // Android source rate can be compared against the relay→browser drop logs and the iOS agent.
         const metrics = process.env.TAPFLOW_STREAM_METRICS === '1' ? createThroughputSampler() : null;
         const metricsTimer = metrics
             ? setInterval(() => {
@@ -327,41 +427,71 @@ export class AndroidAgent {
             : undefined;
         metricsTimer?.unref();
         const onDrop = metrics ? () => { metrics.recordDropped(); warnDrop(); } : warnDrop;
-        const pump = async () => {
-            try {
-                while (true) {
-                    const { value, done } = await reader.read();
-                    if (done)
-                        break;
-                    // Detect video size changes via H.264 SPS so ScrcpyControl.screenSize always
-                    // matches what scrcpy server is actually encoding (landscape-aware vs portrait-locked).
-                    // The SPS leads the keyframe access unit, so parsing value.payload finds it.
-                    const parsed = parseSpsFromNal(value.payload);
-                    if (parsed && (parsed.width !== state.videoWidth || parsed.height !== state.videoHeight)) {
-                        state.videoWidth = parsed.width;
-                        state.videoHeight = parsed.height;
-                        state.scrcpySession?.control.updateScreenSize(parsed.width, parsed.height);
-                        logger.info(`video size → ${parsed.width}×${parsed.height}`);
-                    }
-                    // Mark codec=H.264 + per-AU keyframe so the relay's keyframe-aware backpressure
-                    // preserves the reference chain (drops to the next IDR instead of tearing).
-                    const frame = writeEnvelopeHeader(value.payload, Date.now(), { codec: CODEC_H264, keyframe: value.keyframe });
-                    const sent = sendBinaryWithBackpressure(streamWs, frame, threshold, onDrop);
-                    if (sent)
-                        metrics?.recordSent(value.payload.length);
-                }
-            }
-            catch {
-                // stream cancelled or ws closed — expected on disconnect
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                onFrame?.(value);
+                // Declare reorder=0 on the keyframe SPS so the decoder (WASM/WebCodecs) emits frames
+                // immediately instead of buffering the level's max DPB (~hundreds of ms of latency on every
+                // frame). The gRPC/VideoToolbox SPS omits bitstream_restriction; scrcpy's is a no-op.
+                const payload = value.keyframe ? rewriteLowLatencySpsInFrame(value.payload) : value.payload;
+                const frame = writeEnvelopeHeader(payload, Date.now(), { codec: CODEC_H264, keyframe: value.keyframe });
+                const sent = dropper.send(streamWs, frame, threshold, value.keyframe, onDrop, onWantKeyframe);
+                if (sent)
+                    metrics?.recordSent(value.payload.length);
             }
-            if (metricsTimer)
-                clearInterval(metricsTimer);
-            if (state.scrcpySession === session && !state.restarting) {
+        }
+        catch {
+            // stream cancelled or ws closed — expected on disconnect
+        }
+        if (metricsTimer)
+            clearInterval(metricsTimer);
+    }
+    // gRPC emulator backend: capture via EmulatorVideo (gRPC streamScreenshot + Mac VT encode) through
+    // the shared pump. Input is routed to the gRPC client in handleRelayMessage. No auto-restart —
+    // the backend is torn down with the device state.
+    async startGrpcVideoStream(state, streamWs, serial) {
+        const port = this.grpcPort() ?? 8554;
+        // Downscale box (longest side), server-side resize. Per-session tier from the viewer context
+        // (secure→native / LAN-HTTP→1280 / external→1000); TAPFLOW_ANDROID_MAX_SIZE | TAPFLOW_MAX_SIZE
+        // is a hard override.
+        const maxSize = pickMaxSize({
+            secureContext: state.secureContext,
+            external: state.external,
+            override: process.env.TAPFLOW_ANDROID_MAX_SIZE ?? process.env.TAPFLOW_MAX_SIZE,
+        });
+        // Default 30fps (iOS parity) — caps source 60fps to halve decode/transport for LAN-HTTP.
+        const fps = Number(process.env.TAPFLOW_ANDROID_FPS) || 30;
+        const touchHelper = new AndroidTouchHelper(this.adb, serial);
+        touchHelper.start();
+        state.touchHelper = touchHelper;
+        const client = new EmulatorGrpcClient(`127.0.0.1:${port}`);
+        const video = new EmulatorVideo(client, { fps, ...(maxSize ? { maxWidth: maxSize, maxHeight: maxSize } : {}) });
+        // Assign before start() so the caller's fallback cleanup can tear these down on failure.
+        state.grpcClient = client;
+        state.emulatorVideo = video;
+        const info = await video.start();
+        // gRPC sendTouch coordinates are in the device's native display resolution — not the (possibly
+        // downscaled) video size — so query it for correct normalized→px touch mapping. The aspect
+        // ratio matches the downscaled video, so native dims also drive the dashboard chrome.
+        const native = await this.adb.getScreenSize(serial).catch(() => ({ width: info.width, height: info.height }));
+        state.landscape = false;
+        state.displayWidth = native.width;
+        state.displayHeight = native.height;
+        state.videoWidth = native.width;
+        state.videoHeight = native.height;
+        state.cornerRadius = info.cornerRadius;
+        const reader = video.frames().getReader();
+        // If the gRPC video ends unexpectedly (emulator crash / disconnect), restart the stream so the
+        // session recovers instead of going dead — mirrors the scrcpy pump's auto-restart.
+        void this.pumpVideo(state, streamWs, reader, undefined, () => video.requestIdr()).then(() => {
+            if (state.emulatorVideo === video && !state.restarting) {
                 state.restarting = true;
                 void this.restartVideoStream(state);
             }
-        };
-        void pump();
+        });
     }
     async restartVideoStream(state) {
         const serial = this.adb.getSerial(state.deviceId);
@@ -371,6 +501,10 @@ export class AndroidAgent {
         }
         state.scrcpySession?.stop(serial);
         state.scrcpySession = null;
+        state.emulatorVideo?.stop();
+        state.emulatorVideo = null;
+        state.grpcClient?.close();
+        state.grpcClient = null;
         state.touchHelper?.stop();
         state.touchHelper = null;
         const { streamWs } = state;
@@ -404,12 +538,16 @@ export class AndroidAgent {
         await registerStreamWs(streamWs, state.sessionId);
         return streamWs;
     }
-    async handleDeviceBoot(sessionId, avdId) {
+    async handleDeviceBoot(sessionId, avdId, tier) {
         const state = this.deviceStates.get(sessionId);
         if (!state || !this.ws)
             return;
         const seq = ++state.bootSeq;
         this.cleanupDeviceState(state);
+        if (tier) {
+            state.secureContext = tier.secureContext;
+            state.external = tier.external;
+        }
         this.ws.send(JSON.stringify({ type: 'device:booting', sessionId }));
         try {
             const avdName = avdId.replace(/^avd:/, '');
@@ -420,7 +558,7 @@ export class AndroidAgent {
             if (!target)
                 throw new PlatformError(`Device not found: ${avdId}`);
             if (target.status !== 'booted') {
-                this.launcher.launch(avdName);
+                this.launcher.launch(avdName, this.grpcPort());
                 const serial = await this.launcher.findSerial(avdName);
                 if (seq !== state.bootSeq)
                     return;
@@ -450,6 +588,7 @@ export class AndroidAgent {
                     streamType: 'h264',
                     screenWidth: state.displayWidth,
                     screenHeight: state.displayHeight,
+                    cornerRadius: state.cornerRadius,
                 },
             }));
             this.ws?.send(JSON.stringify({ type: 'device:ready', sessionId, payload: { deviceId: avdId } }));
@@ -485,8 +624,8 @@ export class AndroidAgent {
     handleRelayMessage(msg) {
         switch (msg.type) {
             case 'device:boot': {
-                const { deviceId } = msg.payload;
-                this.handleDeviceBoot(msg.sessionId, deviceId)
+                const { deviceId, secureContext, external } = msg.payload;
+                this.handleDeviceBoot(msg.sessionId, deviceId, { secureContext: !!secureContext, external: !!external })
                     .catch((e) => logger.error('handleDeviceBoot failed:', e));
                 break;
             }
@@ -548,11 +687,12 @@ export class AndroidAgent {
                 if (!state)
                     break;
                 const { x, y } = msg.payload;
-                if (state.scrcpySession && state.videoWidth > 0) {
+                const pc = this.pointerControl(state);
+                if (pc && state.videoWidth > 0) {
                     const px = Math.round(x * state.videoWidth);
                     const py = Math.round(y * state.videoHeight);
                     state.lastTouchPx = { x: px, y: py };
-                    state.scrcpySession.control.touchDown(0, px, py);
+                    this.fire(pc.touchDown(0, px, py));
                 }
                 else {
                     state.touchHelper?.touchStart(x, y);
@@ -564,11 +704,12 @@ export class AndroidAgent {
                 if (!state)
                     break;
                 const { x, y } = msg.payload;
-                if (state.scrcpySession && state.videoWidth > 0) {
+                const pc = this.pointerControl(state);
+                if (pc && state.videoWidth > 0) {
                     const px = Math.round(x * state.videoWidth);
                     const py = Math.round(y * state.videoHeight);
                     state.lastTouchPx = { x: px, y: py };
-                    state.scrcpySession.control.touchMove(0, px, py);
+                    this.fire(pc.touchMove(0, px, py));
                 }
                 else {
                     state.touchHelper?.touchMove(x, y);
@@ -579,8 +720,9 @@ export class AndroidAgent {
                 const state = this.deviceStates.get(msg.sessionId);
                 if (!state)
                     break;
-                if (state.scrcpySession) {
-                    state.scrcpySession.control.touchUp(0, state.lastTouchPx.x, state.lastTouchPx.y);
+                const pc = this.pointerControl(state);
+                if (pc) {
+                    this.fire(pc.touchUp(0, state.lastTouchPx.x, state.lastTouchPx.y));
                 }
                 else {
                     state.touchHelper?.touchEnd();
@@ -592,10 +734,11 @@ export class AndroidAgent {
                 if (!state)
                     break;
                 const { f0, f1 } = msg.payload;
-                if (state.scrcpySession && state.videoWidth > 0) {
+                const pc = this.pointerControl(state);
+                if (pc && state.videoWidth > 0) {
                     const px1 = Math.round(f0.x * state.videoWidth), py1 = Math.round(f0.y * state.videoHeight);
                     const px2 = Math.round(f1.x * state.videoWidth), py2 = Math.round(f1.y * state.videoHeight);
-                    state.scrcpySession.control.pinchStart(px1, py1, px2, py2);
+                    this.fire(pc.pinchStart(px1, py1, px2, py2));
                 }
                 else {
                     state.touchHelper?.pinchStart(f0.x, f0.y, f1.x, f1.y);
@@ -607,10 +750,11 @@ export class AndroidAgent {
                 if (!state)
                     break;
                 const { f0, f1 } = msg.payload;
-                if (state.scrcpySession && state.videoWidth > 0) {
+                const pc = this.pointerControl(state);
+                if (pc && state.videoWidth > 0) {
                     const px1 = Math.round(f0.x * state.videoWidth), py1 = Math.round(f0.y * state.videoHeight);
                     const px2 = Math.round(f1.x * state.videoWidth), py2 = Math.round(f1.y * state.videoHeight);
-                    state.scrcpySession.control.pinchMove(px1, py1, px2, py2);
+                    this.fire(pc.pinchMove(px1, py1, px2, py2));
                 }
                 else {
                     state.touchHelper?.pinchMove(f0.x, f0.y, f1.x, f1.y);
@@ -621,8 +765,9 @@ export class AndroidAgent {
                 const state = this.deviceStates.get(msg.sessionId);
                 if (!state)
                     break;
-                if (state.scrcpySession) {
-                    state.scrcpySession.control.pinchEnd();
+                const pc = this.pointerControl(state);
+                if (pc) {
+                    this.fire(pc.pinchEnd());
                 }
                 else {
                     state.touchHelper?.pinchEnd();
@@ -654,9 +799,11 @@ export class AndroidAgent {
                 break;
             }
             case 'stream:request-idr': {
-                // Relay drop-to-keyframe recovery: reset the encoder so it re-emits SPS/PPS + IDR,
+                // Relay drop-to-keyframe / join recovery: reset the encoder so it re-emits SPS/PPS + IDR,
                 // resyncing fast instead of waiting for the periodic IDR. Throttled by the relay.
-                this.deviceStates.get(msg.sessionId)?.scrcpySession?.control.resetVideo();
+                const st = this.deviceStates.get(msg.sessionId);
+                st?.scrcpySession?.control.resetVideo();
+                st?.emulatorVideo?.requestIdr();
                 break;
             }
             case 'open-url': {
@@ -793,11 +940,12 @@ export class AndroidAgent {
     }
     stream() {
         const state = this.deviceStates.values().next().value;
-        if (!state?.scrcpySession)
-            throw new ValidationError('no active scrcpy session — call connect() first');
+        // Works on either video backend (scrcpy for real devices, gRPC host-encode for emulators).
+        const frames = state?.scrcpySession?.video.start() ?? state?.emulatorVideo?.frames();
+        if (!frames)
+            throw new ValidationError('no active video stream — call connect() first');
         // DeviceAgent.stream() is the platform-neutral Buffer contract; unwrap ScrcpyFrame payloads.
-        return state.scrcpySession.video.start()
-            .pipeThrough(new TransformStream({
+        return frames.pipeThrough(new TransformStream({
             transform(frame, controller) { controller.enqueue(frame.payload); },
         }));
     }