dsh-mobilecode 0.2.1 → 0.3.0

package/README.md

@@ -87,6 +87,34 @@ drawer:
 - `device_apps` / `device_launch_app` — list installed packages (third-party by
   default) so a package name is never guessed / launch one by package or a
   unique substring, with `relaunch` for a cold start.
+- `device_stream` — drive the live screen stream the panel shows: `start` an
+  online device (returns a signed `streamUrl`), `status`, or `stop`. Agents that
+  just need to see the screen should prefer `device_screen` / `device_ui_tree`.
+
+**Live device stream (the panel)**
+
+The Devices pane shows a real-time mirror of the attached device. It is produced
+**in-process** — no inner loopback port, no external helper:
+
+- ONE persistent `adb exec-out "while :; do screencap -p; done"` child streams
+  ~8 fps with zero per-frame process cost (spawning adb per frame caps at ~5 fps
+  and 100% churn). A quote-safe PNG splitter cuts the concatenated output into
+  frames by walking chunk headers (no marker scanning, no false positives).
+- The browser `<img>` reads a `multipart/x-mixed-replace` body served straight
+  from the latest-frame buffer. Backpressure is **latest-wins**: a slow tab skips
+  frames instead of building an unbounded queue or watching a growing delay.
+- A consumer refcount + idle timeout stops the loop when nobody is watching; a
+  keep-alive restarts a crashed loop; switching devices retires the old child.
+- **Tap or drag directly on the screen** to drive the device; a Back / Home /
+  Recents / Rotate / Power bar sits below it, and a device picker switches which
+  online device streams (it never boots one — use `device_boot` for that).
+- **Security**: every stream route sits behind a loopback + trusted-browser
+  transport fence (peer address, loopback `Host`, `Sec-Fetch-Site` / `Origin` —
+  so a LAN client cannot spoof localhost and a DNS-rebinding `Host` is rejected),
+  and the stream URL is an **HMAC-SHA256 capability** signed with a per-install
+  key (`~/.dsh/mobilecode/stream-access.key`, `0600`), expiring within 10 minutes
+  and re-minted automatically. Coordinates are normalized 0..1 of the streamed
+  frame, so one mapping serves every rotation.
 - `device_log` — device logs: logcat `main`/`crash`/`events`/`kernel` buffers
   (kernel = dmesg, needs adb root — works on emulators) with an optional
   case-insensitive substring filter, capped line count.

package/lib/android-stream.js

@@ -0,0 +1,378 @@
+/**
+ * dsh-mobilecode — host-side lifecycle manager for the one live Android stream.
+ *
+ * Ported (lean) from ZSeven-W/dsh-android (android-host.ts, MIT). The stream is
+ * in-process: one AdbFrameLoop per streamed serial, a consumer refcount with an
+ * idle timeout, and a keep-alive that restarts a crashed loop. Emulators and
+ * physical devices share this path — the serial is the only identity.
+ *
+ * The control surface takes NORMALIZED 0..1 coordinates of the streamed frame
+ * (the panel's <img> is scaled, so the browser knows fractions, not pixels) and
+ * maps them onto `adb shell input` pixels using the latest frame's own size.
+ */
+
+import * as DeviceBuild from './device-build.js'
+import { AdbFrameLoop } from './frame-source.js'
+
+const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60 * 1000
+const DEFAULT_RESTART_DELAY_MS = 5000
+const KEEP_ALIVE_TICK_MS = 1000
+const FIRST_FRAME_TIMEOUT_MS = 15000
+const CONTROL_TIMEOUT_MS = 30000
+const MAX_SWIPE_MS = 5000
+
+/** Navigation/hardware buttons the panel may press. */
+export const ANDROID_BUTTONS = {
+  home: 'KEYCODE_HOME',
+  back: 'KEYCODE_BACK',
+  recents: 'KEYCODE_APP_SWITCH',
+  power: 'KEYCODE_POWER',
+  volume_up: 'KEYCODE_VOLUME_UP',
+  volume_down: 'KEYCODE_VOLUME_DOWN',
+  menu: 'KEYCODE_MENU',
+  enter: 'KEYCODE_ENTER',
+  delete: 'KEYCODE_DEL',
+}
+
+/** Clockwise user_rotation cycle (Surface.ROTATION_0..270). */
+export const ROTATION_CYCLE = [0, 1, 2, 3]
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function requireNormalized(x, y) {
+  if (!Number.isFinite(x) || !Number.isFinite(y) || x < 0 || x > 1 || y < 0 || y > 1) {
+    throw new RangeError('dsh-mobilecode: tap/drag coordinates must be normalized 0..1 of the streamed frame')
+  }
+}
+
+/** Lifecycle manager for the (single) in-process Android device stream. */
+export class AndroidStreamHost {
+  #options
+  #loop
+  #starting
+  #launchQueue = Promise.resolve()
+  #consumers = 0
+  #keepAliveTimer
+  #idleTimer
+  #restarts = 0
+  #startedAt
+  #exitAt
+  #lastError
+  #lastSerial
+  #intentionalStop = false
+  #disposed = false
+  #frameSubscribers = new Set()
+
+  constructor(options = {}) {
+    this.#options = {
+      restartDelayMs: options.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS,
+      idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS,
+      firstFrameTimeoutMs: options.firstFrameTimeoutMs ?? FIRST_FRAME_TIMEOUT_MS,
+    }
+  }
+
+  get running() {
+    return this.#loop?.running === true
+  }
+
+  get streamedSerial() {
+    return this.running ? this.#loop?.serial : undefined
+  }
+
+  get latestFrame() {
+    return this.#loop?.latestFrame
+  }
+
+  /** Observe every decoded frame; the returned function unsubscribes. */
+  subscribeFrames(subscriber) {
+    this.#frameSubscribers.add(subscriber)
+    return () => {
+      this.#frameSubscribers.delete(subscriber)
+    }
+  }
+
+  /**
+   * Make sure the frame loop is live for `serial`. Concurrent callers share one
+   * launch; a call for a different serial retires the current loop first (one
+   * streamed device at a time).
+   */
+  async ensureStreaming({ serial }) {
+    if (this.#disposed) throw new Error('dsh-mobilecode: the stream host is disposed')
+    if (typeof serial !== 'string' || serial === '') throw new TypeError('dsh-mobilecode: ensureStreaming requires a non-empty serial')
+    const startFor = async () => {
+      const current = this.#loop
+      if (current !== undefined && current.running && current.serial === serial) return this.#infoOf(current)
+      if (current !== undefined && current.serial !== serial) {
+        current.stop()
+        this.#loop = undefined
+      }
+      return this.#startFor(serial)
+    }
+    let starting = this.#starting
+    if (starting !== undefined) {
+      try {
+        await starting
+      } catch {
+        // A failed shared launch is settled; retry below.
+      }
+      if (this.running && this.#loop?.serial === serial) {
+        this.#armIdle()
+        return this.#infoOf(this.#loop)
+      }
+      starting = undefined
+    }
+    starting = this.#serializeLaunch(startFor)
+    this.#starting = starting
+    try {
+      const info = await starting
+      this.#lastError = undefined
+      this.#armIdle()
+      return info
+    } catch (error) {
+      this.#lastError = errorMessage(error)
+      throw error
+    } finally {
+      if (this.#starting === starting) this.#starting = undefined
+    }
+  }
+
+  /** Start the crash keep-alive loop (restarts an unintentionally dead loop). */
+  startKeepAlive() {
+    if (this.#keepAliveTimer !== undefined || this.#disposed) return
+    this.#keepAliveTimer = setInterval(() => {
+      void this.#keepAliveTick().catch(() => {})
+    }, KEEP_ALIVE_TICK_MS)
+    this.#keepAliveTimer.unref?.()
+  }
+
+  stopKeepAlive() {
+    if (this.#keepAliveTimer !== undefined) clearInterval(this.#keepAliveTimer)
+    this.#keepAliveTimer = undefined
+  }
+
+  /** Stop the stream intentionally (keep-alive will not fight it). */
+  async stop() {
+    this.#clearIdle()
+    this.#intentionalStop = true
+    this.#exitAt = undefined
+    const loop = this.#loop
+    this.#loop = undefined
+    this.#startedAt = undefined
+    loop?.stop()
+    await this.#starting?.catch(() => {})
+    const landed = this.#loop
+    if (landed !== undefined) {
+      this.#loop = undefined
+      landed.stop()
+    }
+  }
+
+  /** Hold the stream alive for one consumer; release exactly once. */
+  acquire() {
+    this.#consumers += 1
+    this.#armIdle()
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.#consumers = Math.max(0, this.#consumers - 1)
+      this.#armIdle()
+    }
+  }
+
+  status() {
+    const loop = this.#loop
+    const frame = loop?.latestFrame
+    return {
+      running: this.running,
+      ...(loop === undefined ? {} : { serial: loop.serial }),
+      restarts: this.#restarts,
+      ...(this.#lastError === undefined ? {} : { lastError: this.#lastError }),
+      consumers: this.#consumers,
+      ...(frame === undefined ? {} : { frameSequence: frame.sequence, lastFrameAt: frame.at, width: frame.width, height: frame.height }),
+      stderr: loop?.stderrLines ?? [],
+    }
+  }
+
+  dispose() {
+    this.#disposed = true
+    this.stopKeepAlive()
+    this.#frameSubscribers.clear()
+    return this.stop()
+  }
+
+  // ── control surface (normalized 0..1 of the streamed frame) ────────────────
+
+  async tap(serial, x, y) {
+    requireNormalized(x, y)
+    const point = await this.#pixels(serial, x, y)
+    await this.#shell(serial, ['input', 'tap', String(point.x), String(point.y)])
+  }
+
+  async drag(serial, drag) {
+    requireNormalized(drag.fromX, drag.fromY)
+    requireNormalized(drag.toX, drag.toY)
+    const from = await this.#pixels(serial, drag.fromX, drag.fromY)
+    const to = await this.#pixels(serial, drag.toX, drag.toY)
+    const durationMs = Math.min(MAX_SWIPE_MS, Math.max(20, Math.round((drag.duration ?? 0.3) * 1000)))
+    await this.#shell(serial, ['input', 'swipe', String(from.x), String(from.y), String(to.x), String(to.y), String(durationMs)])
+  }
+
+  async button(serial, name = 'home') {
+    const keycode = ANDROID_BUTTONS[name] ?? (/^KEYCODE_[A-Z0-9_]+$/.test(name) ? name : undefined)
+    if (keycode === undefined) throw new Error(`unknown button "${name}"; expected one of ${Object.keys(ANDROID_BUTTONS).join(', ')} or a KEYCODE_* name`)
+    await this.#shell(serial, ['input', 'keyevent', keycode])
+  }
+
+  /** ASCII via `input text`; non-ASCII via the ADBKeyboard IME, else refused. */
+  async type(serial, text) {
+    if (typeof text !== 'string' || text === '') throw new TypeError('dsh-mobilecode: type requires a non-empty text')
+    if (DeviceBuild.isAsciiInput(text)) {
+      await this.#shell(serial, ['input', 'text', DeviceBuild.escapeInputText(text)])
+      return
+    }
+    if (!(await DeviceBuild.adbKeyboardReady(serial))) {
+      throw new Error('the text contains non-ASCII characters that `input text` cannot deliver; install the ADBKeyboard IME (github.com/senzhk/ADBKeyBoard) and select it')
+    }
+    await DeviceBuild.typeViaAdbKeyboard(serial, text)
+  }
+
+  async rotate(serial, rotation) {
+    if (!ROTATION_CYCLE.includes(rotation)) throw new RangeError('dsh-mobilecode: rotation must be 0, 1, 2 or 3')
+    await this.#shell(serial, ['settings', 'put', 'system', 'accelerometer_rotation', '0'])
+    await this.#shell(serial, ['settings', 'put', 'system', 'user_rotation', String(rotation)])
+  }
+
+  async getRotation(serial) {
+    try {
+      const value = Number((await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'settings', 'get', 'system', 'user_rotation'])).trim())
+      return ROTATION_CYCLE.includes(value) ? value : 0
+    } catch {
+      return 0
+    }
+  }
+
+  /** The online device list for the panel picker (serial + kind). */
+  async listDevices() {
+    const rows = await DeviceBuild.devices()
+    return rows
+      .filter((row) => row.state === 'device')
+      .map((row) => ({ serial: row.serial, kind: row.serial.startsWith('emulator-') ? 'emulator' : 'physical' }))
+  }
+
+  async #shell(serial, shell) {
+    const code = await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', ...shell], { timeoutMs: CONTROL_TIMEOUT_MS }).exit
+    if (code !== 0) throw new Error(`adb shell ${shell.join(' ')} failed (exit ${code})`)
+  }
+
+  async #keepAliveTick() {
+    if (this.#disposed || this.#intentionalStop) return
+    const exitAt = this.#exitAt
+    const serial = this.#lastSerial
+    if (exitAt === undefined || serial === undefined) return
+    if (Date.now() - exitAt < this.#options.restartDelayMs) return
+    this.#exitAt = undefined
+    this.#restarts += 1
+    try {
+      await this.ensureStreaming({ serial })
+    } catch (error) {
+      this.#lastError = errorMessage(error)
+      if (this.#exitAt === undefined) this.#exitAt = Date.now()
+    }
+  }
+
+  async #startFor(serial) {
+    if (this.#disposed) throw new Error('dsh-mobilecode: the stream host is disposed')
+    const online = await DeviceBuild.devices()
+    if (!online.some((row) => row.serial === serial && row.state === 'device')) {
+      const known = online.find((row) => row.serial === serial)
+      throw new Error(
+        known === undefined
+          ? `no connected device has the serial ${serial}`
+          : `device ${serial} is ${known.state}, not ready to stream`,
+      )
+    }
+    const loop = new AdbFrameLoop(serial, {
+      onFrame: (frame) => {
+        for (const subscriber of this.#frameSubscribers) {
+          try {
+            subscriber(frame)
+          } catch {
+            // One broken consumer must not stall the fan-out.
+          }
+        }
+      },
+      onExit: (detail) => {
+        if (this.#loop !== loop) return
+        this.#loop = undefined
+        this.#startedAt = undefined
+        this.#lastError = `the screencap loop for ${serial} died (${detail})`
+        this.#exitAt = Date.now()
+      },
+    })
+    this.#loop = loop
+    this.#lastSerial = serial
+    this.#intentionalStop = false
+    loop.reset()
+    loop.start()
+    const frame = await loop.waitForFrame(this.#options.firstFrameTimeoutMs)
+    if (frame === undefined) {
+      const stderr = loop.stderrLines.join('\n')
+      loop.stop()
+      if (this.#loop === loop) this.#loop = undefined
+      throw new Error(`no frame arrived from ${serial} within ${this.#options.firstFrameTimeoutMs} ms${stderr === '' ? '' : `: ${stderr}`}`)
+    }
+    this.#startedAt = Date.now()
+    this.#exitAt = undefined
+    return this.#infoOf(loop)
+  }
+
+  #infoOf(loop) {
+    const frame = loop.latestFrame
+    return { serial: loop.serial, ...(frame === undefined ? {} : { width: frame.width, height: frame.height }) }
+  }
+
+  /** Normalized frame coordinates → `input` pixels via the live frame size. */
+  async #pixels(serial, x, y) {
+    const frame = this.streamedSerial === serial ? this.latestFrame : undefined
+    if (frame !== undefined) return { x: Math.round(x * frame.width), y: Math.round(y * frame.height) }
+    const size = await screenSize(serial)
+    return { x: Math.round(x * size.width), y: Math.round(y * size.height) }
+  }
+
+  #armIdle() {
+    this.#clearIdle()
+    const idleMs = this.#options.idleTimeoutMs
+    if (idleMs <= 0) return
+    this.#idleTimer = setTimeout(() => {
+      this.#idleTimer = undefined
+      if (this.#consumers > 0) {
+        this.#armIdle()
+        return
+      }
+      void this.stop()
+    }, idleMs)
+    this.#idleTimer.unref?.()
+  }
+
+  #clearIdle() {
+    if (this.#idleTimer !== undefined) clearTimeout(this.#idleTimer)
+    this.#idleTimer = undefined
+  }
+
+  #serializeLaunch(task) {
+    const run = this.#launchQueue.then(task, task)
+    this.#launchQueue = run.then(() => undefined, () => undefined)
+    return run
+  }
+}
+
+/** Override-aware physical screen size for the non-streaming control fallback. */
+async function screenSize(serial) {
+  const output = await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'wm', 'size'])
+  const match = /Override size:\s*(\d+)x(\d+)/.exec(output) ?? /Physical size:\s*(\d+)x(\d+)/.exec(output)
+  if (!match) throw new Error(`cannot read the screen size of ${serial}`)
+  return { width: Number(match[1]), height: Number(match[2]) }
+}

package/lib/client.js

@@ -110,6 +110,17 @@ window.__ModuleLoader__.load({
 .mc-section-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; padding: 2px 0 10px; }
 .mc-section-head .mc-hint { flex: 1; min-width: 200px; }
 .mc-section .mc-tabs { padding: 0; margin-bottom: 4px; }
+/* ── live device stream ── */
+.mc-live { display: flex; flex-direction: column; gap: 8px; }
+.mc-live-bar { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.mc-live-bar select { background: light-dark(#fff, #20242b); color: inherit; border: 1px solid light-dark(rgba(0,0,0,.18), rgba(255,255,255,.18)); border-radius: 6px; padding: 3px 6px; font: inherit; font-size: 12px; max-width: 200px; }
+.mc-live-stage { position: relative; align-self: center; background: #000; border-radius: 10px; overflow: hidden; line-height: 0; box-shadow: inset 0 0 0 1px light-dark(rgba(0,0,0,.12), rgba(255,255,255,.14)); }
+.mc-live-stage img { display: block; max-width: 100%; max-height: 60vh; width: auto; height: auto; cursor: crosshair; touch-action: none; user-select: none; }
+.mc-live-stage .mc-live-off { display: flex; align-items: center; justify-content: center; width: 260px; height: 460px; color: #9aa0a8; font-size: 13px; line-height: 1.5; text-align: center; }
+.mc-live-nav { display: flex; align-items: center; justify-content: center; gap: 8px; }
+.mc-live-nav button { border: 1px solid light-dark(rgba(0,0,0,.16), rgba(255,255,255,.18)); background: light-dark(#fff, #20242b); color: inherit; border-radius: 999px; width: 40px; height: 32px; cursor: pointer; font-size: 14px; }
+.mc-live-nav button:hover { background: light-dark(rgba(0,0,0,.06), rgba(255,255,255,.1)); }
+.mc-live-cap { font-size: 11px; color: light-dark(#6b7078, #9aa0a8); text-align: center; }
 `;
 		//#endregion
 
@@ -148,6 +159,20 @@ window.__ModuleLoader__.load({
 			if (!response.ok) throw new Error("HTTP " + response.status);
 			return response.json();
 		};
+		// POST that surfaces the server's JSON error copy (stream routes return
+		// human-readable 4xx bodies the generic post() would flatten to "HTTP 409").
+		const streamPost = async (path, body) => {
+			const response = await fetch(API_BASE + path, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body ?? {}),
+			});
+			const text = await response.text();
+			let json;
+			try { json = JSON.parse(text); } catch { json = {}; }
+			if (!response.ok) throw new Error(json.error || ("HTTP " + response.status));
+			return json;
+		};
 		const copyText = async (text) => {
 			try { await navigator.clipboard.writeText(text); return true; } catch { return false; }
 		};
@@ -259,6 +284,7 @@ window.__ModuleLoader__.load({
 							);
 						}),
 					),
+					h(LiveDeviceCard, null),
 					platforms.map((platform) => {
 						const srv = server(platform);
 						const bld = build(platform);
@@ -333,6 +359,113 @@ window.__ModuleLoader__.load({
 			);
 		}
 
+		/** Live device stream: an <img> fed by the in-process multipart route, with
+		 *  tap/drag control and the Back/Home/Recents/rotate/power nav bar. */
+		function LiveDeviceCard() {
+			const [devices, setDevices] = useState([]);
+			const [serial, setSerial] = useState("");
+			const [streamUrl, setStreamUrl] = useState("");
+			const [error, setError] = useState("");
+			const imgRef = useRef(null);
+			const dragRef = useRef(null);
+			const grantTimer = useRef(null);
+
+			const grant = async (device) => {
+				if (!device) return;
+				try {
+					const r = await streamPost("/stream/grant", { device });
+					setStreamUrl(r.streamUrl);
+					setSerial(r.device);
+					setError("");
+					clearTimeout(grantTimer.current);
+					// Re-mint a minute before the 10-minute capability expires.
+					const ms = Math.max(30000, (r.expiresAt - Date.now()) - 60000);
+					grantTimer.current = setTimeout(() => { grant(r.device).catch(() => {}); }, ms);
+				} catch (err) {
+					setError(err instanceof Error ? err.message : String(err));
+					setStreamUrl("");
+				}
+			};
+
+			const refreshDevices = async () => {
+				try {
+					const r = await streamPost("/stream/devices", {});
+					setDevices(r.devices);
+					setSerial((cur) => cur || (r.devices.find((d) => d.streaming)?.serial ?? r.devices[0]?.serial ?? ""));
+				} catch (err) {
+					setError(err instanceof Error ? err.message : String(err));
+				}
+			};
+
+			useEffect(() => {
+				refreshDevices();
+				const timer = setInterval(refreshDevices, 5000);
+				return () => { clearInterval(timer); clearTimeout(grantTimer.current); };
+			}, []);
+
+			// Auto-grant once a serial is known but no stream is up yet.
+			useEffect(() => { if (serial !== "" && streamUrl === "") grant(serial).catch(() => {}); }, [serial, streamUrl]);
+
+			const control = async (action) => {
+				if (serial === "") return;
+				try { await streamPost("/stream/control", { device: serial, action }); }
+				catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+			};
+
+			const norm = (clientX, clientY) => {
+				const el = imgRef.current;
+				if (!el) return null;
+				const rect = el.getBoundingClientRect();
+				if (rect.width === 0 || rect.height === 0) return null;
+				return {
+					x: Math.min(1, Math.max(0, (clientX - rect.left) / rect.width)),
+					y: Math.min(1, Math.max(0, (clientY - rect.top) / rect.height)),
+				};
+			};
+			const onDown = (e) => { const p = norm(e.clientX, e.clientY); if (p) dragRef.current = p; };
+			const onUp = (e) => {
+				const start = dragRef.current;
+				dragRef.current = null;
+				const end = norm(e.clientX, e.clientY);
+				if (!start || !end) return;
+				if (Math.hypot(end.x - start.x, end.y - start.y) > 0.02) {
+					control({ kind: "drag", fromX: start.x, fromY: start.y, toX: end.x, toY: end.y });
+				} else {
+					control({ kind: "tap", x: end.x, y: end.y });
+				}
+			};
+
+			return h("div", { className: "mc-card mc-live" },
+				h("div", { className: "mc-card-head" },
+					h("span", null, "Live device"),
+					h("span", { className: "sp" }),
+					devices.length > 0
+						? h("select", {
+							value: serial,
+							onChange: (e) => { setSerial(e.target.value); setStreamUrl(""); setError(""); },
+						}, devices.map((d) => h("option", { key: d.serial, value: d.serial }, d.serial + (d.kind === "emulator" ? " · emu" : " · phone"))))
+						: h("span", { className: "mc-hint" }, "no device"),
+					h("button", { className: "mc-btn", disabled: serial === "", onClick: () => grant(serial) }, "Reconnect"),
+				),
+				error !== "" && h("div", { className: "mc-error" }, error),
+				h("div", { className: "mc-live-stage" },
+					streamUrl !== ""
+						? h("img", { ref: imgRef, src: streamUrl, alt: "device screen", draggable: false, onPointerDown: onDown, onPointerUp: onUp, onError: () => grant(serial) })
+						: h("div", { className: "mc-live-off" }, devices.length === 0
+							? "No device attached. Boot one with device_boot, or press Run app."
+							: "Connecting to " + serial + "…"),
+				),
+				h("div", { className: "mc-live-nav" },
+					h("button", { title: "Back", disabled: serial === "", onClick: () => control({ kind: "button", name: "back" }) }, "◁"),
+					h("button", { title: "Home", disabled: serial === "", onClick: () => control({ kind: "button", name: "home" }) }, "○"),
+					h("button", { title: "Recents", disabled: serial === "", onClick: () => control({ kind: "button", name: "recents" }) }, "▢"),
+					h("button", { title: "Rotate", disabled: serial === "", onClick: () => control({ kind: "rotate" }) }, "⟳"),
+					h("button", { title: "Power", disabled: serial === "", onClick: () => control({ kind: "button", name: "power" }) }, "⏻"),
+				),
+				h("div", { className: "mc-live-cap" }, "tap or drag on the screen to drive the device"),
+			);
+		}
+
 		//#region setup UI (welcome + settings)
 
 		/** PaddleOCR status card: fetch /ocr, Install button, log tail. */

package/lib/frame-source.js

@@ -0,0 +1,274 @@
+/**
+ * dsh-mobilecode — in-process MJPEG-style frame pipeline for one Android device.
+ *
+ * Ported from ZSeven-W/dsh-android (frame-source.ts, MIT). No external stream
+ * helper and no inner loopback port: ONE persistent `adb exec-out` child runs a
+ * `screencap -p` loop on the device, this module splits the concatenated PNG
+ * output into frames, and the web routes serve the latest frame straight from
+ * memory as a `multipart/x-mixed-replace` body (PNG parts — Chromium and
+ * Firefox render those exactly like JPEG parts).
+ *
+ * The persistent child is the heart of the design: spawning adb per frame costs
+ * ~200 ms per screenshot (~5 fps ceiling), while one `while :; do screencap -p;
+ * done` child streams ~8 fps on an emulator with zero per-frame process cost.
+ * The child is intentionally dumb — it exits, this module reports it, and the
+ * host controller (android-stream.js) owns restart / keep-alive policy.
+ */
+
+import * as DeviceBuild from './device-build.js'
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const IEND_TYPE = 0x49454e44 // 'IEND'
+/** A screencap frame larger than this means we lost sync; rescan. */
+const MAX_FRAME_BYTES = 64 * 1024 * 1024
+/** Bytes kept while hunting for a signature in garbage (stderr noise, …). */
+const MAX_UNSYNCED_BYTES = 1024 * 1024
+const STDERR_RING_LINES = 20
+const STDERR_LINE_MAX_CHARS = 240
+export const STREAM_BOUNDARY = 'dsh-mobilecode-frame'
+
+/** Pixel size of a PNG from its IHDR chunk, without decoding the image. */
+export function pngDimensions(buffer) {
+  if (buffer.length < 24) return undefined
+  if (!buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return undefined
+  if (buffer.readUInt32BE(12) !== 0x49484452) return undefined // 'IHDR'
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+}
+
+/**
+ * Incremental splitter over a byte stream of back-to-back PNG images.
+ *
+ * PNG framing is self-describing (8-byte signature, then length-prefixed chunks
+ * until IEND), so frames are cut by walking chunk headers — no scanning of image
+ * data for markers, no false positives. When the stream derails the splitter
+ * drops bytes until the next signature instead of stalling.
+ */
+export class PngFrameSplitter {
+  #buffer = Buffer.alloc(0)
+
+  /** Feed bytes; returns every complete PNG that ended inside them. */
+  push(chunk) {
+    this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk])
+    const frames = []
+    for (;;) {
+      const start = this.#buffer.indexOf(PNG_SIGNATURE)
+      if (start < 0) {
+        if (this.#buffer.length > MAX_UNSYNCED_BYTES) {
+          this.#buffer = this.#buffer.subarray(this.#buffer.length - PNG_SIGNATURE.length)
+        }
+        return frames
+      }
+      if (start > 0) this.#buffer = this.#buffer.subarray(start)
+      const end = this.#frameEnd()
+      if (end === undefined) {
+        if (this.#buffer.length > MAX_FRAME_BYTES) {
+          this.#buffer = this.#buffer.subarray(1)
+          continue
+        }
+        return frames
+      }
+      frames.push(this.#buffer.subarray(0, end))
+      this.#buffer = this.#buffer.subarray(end)
+    }
+  }
+
+  /** Byte length of the complete PNG at the buffer start, if fully buffered. */
+  #frameEnd() {
+    let offset = PNG_SIGNATURE.length
+    for (;;) {
+      if (offset + 8 > this.#buffer.length) return undefined
+      const dataLength = this.#buffer.readUInt32BE(offset)
+      const type = this.#buffer.readUInt32BE(offset + 4)
+      if (dataLength > MAX_FRAME_BYTES) return undefined // corrupt header; caller rescans
+      const next = offset + 8 + dataLength + 4
+      if (next > this.#buffer.length) return undefined
+      if (type === IEND_TYPE) return next
+      offset = next
+    }
+  }
+}
+
+/**
+ * Owns the one persistent screencap child for one device serial and the
+ * latest-frame buffer every consumer reads from.
+ */
+export class AdbFrameLoop {
+  #child
+  #splitter = new PngFrameSplitter()
+  #latest
+  #sequence = 0
+  #stderrRing = []
+  #stderrPartial = ''
+  #frameWaiters = []
+  #stopped = false
+
+  constructor(serial, events = {}) {
+    this.serial = serial
+    this.events = events
+  }
+
+  get running() {
+    const child = this.#child
+    return child !== undefined && child.exitCode === null && child.signalCode === null
+  }
+
+  get latestFrame() {
+    return this.#latest
+  }
+
+  get stderrLines() {
+    return [...this.#stderrRing]
+  }
+
+  /** Spawn the screencap loop child (idempotent while running). */
+  start() {
+    if (this.running || this.#stopped) return
+    // `exec-out` skips the pty (binary-safe); the single-string command runs
+    // through the *device* shell, so one child produces frames forever.
+    const child = DeviceBuild.launch(
+      DeviceBuild.adb(),
+      ['-s', this.serial, 'exec-out', 'while :; do screencap -p; done'],
+      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true },
+    )
+    this.#child = child
+    child.stdout?.on('data', (chunk) => {
+      for (const png of this.#splitter.push(chunk)) this.#acceptFrame(png)
+    })
+    child.stderr?.on('data', (chunk) => this.#recordStderr(chunk))
+    child.once('error', (error) => {
+      this.#recordStderr(Buffer.from(`spawn error: ${error.message}\n`))
+    })
+    child.once('close', (code, signal) => {
+      if (this.#child !== child) return
+      this.#child = undefined
+      const detail = signal !== null ? `killed by ${signal}` : `exit ${String(code)}`
+      if (!this.#stopped) this.events.onExit?.(detail)
+    })
+  }
+
+  /** Kill the child; the loop object can be started again later. */
+  stop() {
+    this.#stopped = true
+    const child = this.#child
+    this.#child = undefined
+    if (child !== undefined && child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGTERM')
+      const hardKill = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL')
+      }, 2000)
+      hardKill.unref?.()
+    }
+    const waiters = this.#frameWaiters
+    this.#frameWaiters = []
+    if (this.#latest !== undefined) for (const waiter of waiters) waiter(this.#latest)
+  }
+
+  /** Allow a stopped loop to be started again (host restart path). */
+  reset() {
+    this.#stopped = false
+    this.#splitter = new PngFrameSplitter()
+  }
+
+  /** The next frame (or the latest one already buffered), bounded in time. */
+  waitForFrame(timeoutMs) {
+    const latest = this.#latest
+    if (latest !== undefined) return Promise.resolve(latest)
+    return new Promise((resolve) => {
+      let settled = false
+      const waiter = (frame) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(frame)
+      }
+      const timer = setTimeout(() => {
+        if (settled) return
+        settled = true
+        const index = this.#frameWaiters.indexOf(waiter)
+        if (index >= 0) this.#frameWaiters.splice(index, 1)
+        resolve(undefined)
+      }, timeoutMs)
+      timer.unref?.()
+      this.#frameWaiters.push(waiter)
+    })
+  }
+
+  #acceptFrame(png) {
+    const size = pngDimensions(png)
+    if (size === undefined) return
+    this.#sequence += 1
+    const frame = { png, width: size.width, height: size.height, sequence: this.#sequence, at: Date.now() }
+    this.#latest = frame
+    const waiters = this.#frameWaiters
+    this.#frameWaiters = []
+    for (const waiter of waiters) waiter(frame)
+    this.events.onFrame?.(frame)
+  }
+
+  #recordStderr(chunk) {
+    const text = this.#stderrPartial + chunk.toString('utf8')
+    const lines = text.split('\n')
+    this.#stderrPartial = lines.pop() ?? ''
+    for (const line of lines) {
+      const trimmed = line.trimEnd()
+      if (trimmed === '') continue
+      this.#stderrRing.push(trimmed.length > STDERR_LINE_MAX_CHARS ? `${trimmed.slice(0, STDERR_LINE_MAX_CHARS)}…` : trimmed)
+      if (this.#stderrRing.length > STDERR_RING_LINES) this.#stderrRing.shift()
+    }
+  }
+}
+
+/**
+ * Write one live multipart/x-mixed-replace response from a frame feed.
+ * Backpressure is latest-wins: when the client socket is saturated the writer
+ * skips frames instead of queueing them, so a slow tab never builds an
+ * unbounded buffer or watches a growing delay.
+ */
+export class MultipartFrameWriter {
+  #closed = false
+  #congested = false
+
+  constructor(res) {
+    this.res = res
+    res.writeHead(200, {
+      'content-type': `multipart/x-mixed-replace; boundary=${STREAM_BOUNDARY}`,
+      'cache-control': 'no-cache, no-store',
+      'x-content-type-options': 'nosniff',
+      'cross-origin-resource-policy': 'same-origin',
+      'referrer-policy': 'no-referrer',
+    })
+    res.on('drain', () => {
+      this.#congested = false
+    })
+  }
+
+  get closed() {
+    return this.#closed
+  }
+
+  /** Write one frame part; silently skipped while the socket is congested. */
+  writeFrame(frame) {
+    if (this.#closed || this.#congested) return
+    const header = `--${STREAM_BOUNDARY}\r\n`
+      + 'Content-Type: image/png\r\n'
+      + `Content-Length: ${frame.png.length}\r\n\r\n`
+    try {
+      this.res.write(header)
+      const flushed = this.res.write(frame.png)
+      this.res.write('\r\n')
+      if (!flushed) this.#congested = true
+    } catch {
+      this.close()
+    }
+  }
+
+  close() {
+    if (this.#closed) return
+    this.#closed = true
+    try {
+      this.res.end()
+    } catch {
+      // The socket may already be gone.
+    }
+  }
+}

package/lib/index.js

@@ -18,6 +18,9 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import * as DeviceBuild from './device-build.js'
 import * as UiTree from './uitree.js'
+import * as FrameSource from './frame-source.js'
+import * as StreamAccess from './stream-access.js'
+import { AndroidStreamHost, ROTATION_CYCLE } from './android-stream.js'
 import { DevicePreviewEngine } from './device-preview.js'
 import * as Setup from './setup.js'
 import { registerMobileSkill } from './skill.js'
@@ -70,11 +73,21 @@ function resolveDirectory(body, config) {
   return process.cwd()
 }
 
-function makeRoutes(engine, config) {
+function makeRoutes(engine, config, stream) {
   const guard = (req, res) => {
     if (!isLoopbackRequest(req)) { writeJson(res, 403, { error: 'forbidden: loopback-only' }); return false }
     return true
   }
+  // Stronger fence for the stream routes: loopback peer + loopback Host +
+  // Sec-Fetch-Site/Origin. POSTs (which mint capabilities) also require Origin.
+  const fence = (req, res, requireOrigin) => {
+    if (!StreamAccess.isTrustedRequest(req, requireOrigin)) { writeJson(res, 403, { error: 'forbidden: loopback trusted-browser only' }); return false }
+    return true
+  }
+  const isPost = (req, res) => {
+    if ((req.method ?? 'GET') !== 'POST') { writeJson(res, 405, { error: 'method not allowed' }); return false }
+    return true
+  }
   const platformOf = (value) => (value === 'ios' || value === 'android' ? value : undefined)
   const routes = [
     // GET /api/dsh-mobilecode?directory=... → current info (platforms, servers, builds, bundler).
@@ -290,6 +303,154 @@ function makeRoutes(engine, config) {
         writeJson(res, 405, { error: 'method not allowed' })
       },
     },
+    // ── live device stream (panel) ──────────────────────────────────────────
+    // GET /api/dsh-mobilecode/stream?token=… — live multipart/x-mixed-replace PNG
+    // stream from the in-process frame loop. The <img> GET carries no Origin, so
+    // the fence here is loopback-only (requireOrigin false).
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream',
+      handler: async (req, res) => {
+        if (!fence(req, res, false)) return
+        if ((req.method ?? 'GET') !== 'GET') { writeJson(res, 405, { error: 'method not allowed' }); return }
+        const token = new URL(req.url ?? '/', 'http://localhost').searchParams.get('token') ?? ''
+        const payload = await stream.access.verifyStreamToken(token)
+        if (payload === undefined) { writeJson(res, 403, { error: 'the stream token is invalid or expired' }); return }
+        if (stream.host.streamedSerial !== payload.serial) { writeJson(res, 503, { error: 'the device stream is not running; request a fresh grant' }); return }
+        const release = stream.host.acquire()
+        try {
+          await stream.host.ensureStreaming({ serial: payload.serial })
+        } catch (error) {
+          release()
+          writeJson(res, 502, { error: `the device stream failed to start: ${error instanceof Error ? error.message : String(error)}` })
+          return
+        }
+        const writer = new FrameSource.MultipartFrameWriter(res)
+        let finished = false
+        const teardown = () => {
+          if (finished) return
+          finished = true
+          unsubscribe()
+          writer.close()
+          release()
+        }
+        const unsubscribe = stream.host.subscribeFrames((frame) => {
+          // Frames for a different serial (after a device switch) must not leak
+          // into a capability minted for the old device.
+          if (stream.host.streamedSerial === payload.serial) writer.writeFrame(frame)
+          else teardown()
+        })
+        res.on('error', teardown)
+        res.on('close', teardown)
+        const latest = stream.host.latestFrame
+        if (latest !== undefined) writer.writeFrame(latest)
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/grant {device?} — mint a fresh stream URL.
+    // Only starts the loop for an ONLINE device; never boots an emulator, never
+    // yanks the stream from a different streaming device.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/grant',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          const serial = typeof body.device === 'string' && body.device !== '' ? body.device : stream.host.streamedSerial
+          if (!serial) { writeJson(res, 409, { error: 'no device is streaming; pass a serial' }); return }
+          if (!StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { error: 'device must be an adb device serial' }); return }
+          if (stream.host.streamedSerial !== serial) {
+            const online = await stream.host.listDevices()
+            if (!online.some((device) => device.serial === serial)) { writeJson(res, 409, { error: `device ${serial} is not online` }); return }
+          }
+          await stream.host.ensureStreaming({ serial })
+          const signed = await stream.access.signStreamToken(serial)
+          writeJson(res, 200, { ok: true, streamUrl: `${API_BASE}/stream?token=${encodeURIComponent(signed.token)}`, expiresAt: signed.expiresAt, device: serial })
+        } catch (error) {
+          writeJson(res, 502, { error: `the device stream failed to start: ${error instanceof Error ? error.message : String(error)}` })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/status {device?} — read-only snapshot;
+    // never starts a stream and never mints tokens.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/status',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const status = stream.host.status()
+        const filter = body.device
+        const running = status.running && status.serial !== undefined && (filter === undefined || filter === '' || status.serial === filter)
+        if (!running) { writeJson(res, 200, { ok: true, running: false }); return }
+        writeJson(res, 200, { ok: true, running: true, serial: status.serial, width: status.width, height: status.height })
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/devices — online device list for the picker.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/devices',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        await readBody(req, res)
+        try {
+          const devices = await stream.host.listDevices()
+          const streamed = stream.host.streamedSerial
+          writeJson(res, 200, { ok: true, devices: devices.map((device) => ({ ...device, ...(device.serial === streamed ? { streaming: true } : {}) })) })
+        } catch (error) {
+          writeJson(res, 503, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/control {device, action} — one control op.
+    // tap/drag coordinates are NORMALIZED 0..1 of the streamed frame.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/control',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const serial = body.device
+        if (typeof serial !== 'string' || !StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { error: 'device must be an adb device serial' }); return }
+        const action = body.action
+        if (typeof action !== 'object' || action === null || typeof action.kind !== 'string') { writeJson(res, 400, { error: 'action must be an object with a kind' }); return }
+        const point = (x, y) => typeof x === 'number' && typeof y === 'number' && x >= 0 && x <= 1 && y >= 0 && y <= 1
+        if (action.kind === 'tap' && !point(action.x, action.y)) { writeJson(res, 400, { error: 'tap needs normalized x,y in 0..1' }); return }
+        if (action.kind === 'drag' && !(point(action.fromX, action.fromY) && point(action.toX, action.toY))) { writeJson(res, 400, { error: 'drag needs normalized fromX,fromY,toX,toY in 0..1' }); return }
+        if (action.kind === 'button' && (typeof action.name !== 'string' || action.name === '')) { writeJson(res, 400, { error: 'button requires a non-empty name' }); return }
+        if (action.kind === 'type' && (typeof action.text !== 'string' || action.text === '')) { writeJson(res, 400, { error: 'type requires a non-empty text' }); return }
+        if (stream.host.streamedSerial !== serial) {
+          const online = await stream.host.listDevices()
+          if (!online.some((device) => device.serial === serial)) { writeJson(res, 409, { error: `device ${serial} is not online` }); return }
+        }
+        const release = stream.host.acquire()
+        try {
+          let result = { ok: true }
+          switch (action.kind) {
+            case 'tap': await stream.host.tap(serial, action.x, action.y); break
+            case 'drag': await stream.host.drag(serial, { fromX: action.fromX, fromY: action.fromY, toX: action.toX, toY: action.toY, ...(typeof action.durationMs === 'number' ? { duration: Math.min(5, action.durationMs / 1000) } : {}) }); break
+            case 'button': await stream.host.button(serial, action.name); break
+            case 'type': await stream.host.type(serial, action.text); break
+            case 'rotate': {
+              const current = await stream.host.getRotation(serial)
+              const next = ROTATION_CYCLE[(ROTATION_CYCLE.indexOf(current) + 1) % ROTATION_CYCLE.length]
+              await stream.host.rotate(serial, next)
+              result = { ok: true, rotation: next }
+              break
+            }
+            default: writeJson(res, 400, { error: `unknown control action ${JSON.stringify(action.kind)}` }); return
+          }
+          writeJson(res, 200, result)
+        } catch (error) {
+          writeJson(res, 502, { error: `the device control failed: ${error instanceof Error ? error.message : String(error)}` })
+        } finally {
+          release()
+        }
+      },
+    },
   ]
   return routes
 }
@@ -908,6 +1069,57 @@ function deviceLaunchAppTool() {
   })
 }
 
+function deviceStreamTool(host, access) {
+  return defineTool({
+    name: 'device_stream',
+    description: 'Drive the live device screen stream the Devices panel shows. action=start begins the frame loop for an ' +
+      'online device and returns a signed streamUrl; status reports whether it is running; stop tears it down. This is a ' +
+      'human-panel feature — agents that just need to see the screen should use device_screen or device_ui_tree instead.',
+    parameters: {
+      action: { type: 'string', enum: ['status', 'start', 'stop'], description: 'What to do (default status).' },
+      serial: { type: 'string', description: 'Device serial (start needs an online device; omit to use the first attached one).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          action: { type: 'string', required: true },
+          running: { type: 'boolean', required: true },
+          serial: { type: 'string' },
+          streamUrl: { type: 'string' },
+          width: { type: 'integer' },
+          height: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { action: 'status', running: false }
+        const text = v.action === 'start' && v.streamUrl
+          ? `Streaming ${v.serial} (${v.width}x${v.height}) — ${v.streamUrl}`
+          : `Stream ${v.action}: running=${v.running}${v.serial ? ` (${v.serial})` : ''}`
+        return [{ type: 'text', text }]
+      },
+    },
+    async execute(args) {
+      const action = args.action ?? 'status'
+      if (action === 'stop') {
+        await host.stop()
+        return { action, running: false }
+      }
+      if (action === 'status') {
+        const s = host.status()
+        return { action, running: s.running, ...(s.serial !== undefined ? { serial: s.serial } : {}), ...(s.width !== undefined ? { width: s.width, height: s.height } : {}) }
+      }
+      const serial = await requireAndroidDevice(args.serial)
+      const online = await host.listDevices()
+      if (!online.some((device) => device.serial === serial)) throw new Error(`device ${serial} is not online; cannot stream it`)
+      const info = await host.ensureStreaming({ serial })
+      const signed = await access.signStreamToken(serial)
+      return { action, running: true, serial: info.serial, width: info.width, height: info.height, streamUrl: `${API_BASE}/stream?token=${encodeURIComponent(signed.token)}` }
+    },
+  })
+}
+
 function deviceScreenTool(engine) {
   return defineTool({
     name: 'device_screen',
@@ -1360,6 +1572,8 @@ function guidance() {
     '- device_action: notifications / quick_settings / collapse / lock / wake / assistant / rotate.',
     '- device_boot / device_shutdown: boot an AVD by name and wait for boot / shut an emulator down (refuses physical devices).',
     '- device_apps / device_launch_app: list installed packages (never guess a package name) / launch one by package or unique substring.',
+    '- device_stream: drive the live screen stream the Devices panel shows (status / start an online device / stop). Agents',
+    '  that just need to see the screen should prefer device_screen or device_ui_tree.',
     '- device_log: read device logs (logcat main/crash/events, kernel dmesg). Call it when a run fails or an app misbehaves.',
     '- device_status: one normalized snapshot of attached devices, AVDs, running/parked projects, Metro and preview servers.',
     '',
@@ -1388,8 +1602,11 @@ export function apply(ctx, config) {
   })
 
   const engine = new DevicePreviewEngine()
+  const streamHost = new AndroidStreamHost()
+  const streamAccess = new StreamAccess.StreamAccessController()
   const handle = {
     engine,
+    stream: streamHost,
     status: () => ({
       directories: [...new Set([...engine.builds.keys()].map((key) => key.split('\0')[0]))],
       servers: [...engine.servers.keys()],
@@ -1400,7 +1617,7 @@ export function apply(ctx, config) {
   if (typeof ctx.provide === 'function') ctx.provide('mobilecode', handle)
   else ctx.mobilecode = handle
 
-  const routes = makeRoutes(engine, config)
+  const routes = makeRoutes(engine, config, { host: streamHost, access: streamAccess })
   let disposeRoutes
   let disposeTools
   let disposeSection
@@ -1411,6 +1628,7 @@ export function apply(ctx, config) {
     if (disposeRoutes !== undefined) { disposeRoutes(); disposeRoutes = undefined }
     if (disposeTools !== undefined) { disposeTools(); disposeTools = undefined }
     if (!value.enabled) return
+    streamHost.startKeepAlive()
     if (value.announceToAgent) {
       disposeSection = ctx.systemPrompt.section({
         name: 'plugin:dsh-mobilecode',
@@ -1435,6 +1653,7 @@ export function apply(ctx, config) {
         deviceActionTool(),
         deviceAppsTool(),
         deviceLaunchAppTool(),
+        deviceStreamTool(streamHost, streamAccess),
         deviceLogTool(engine),
         deviceStatusTool(engine),
         deviceInputTool(),
@@ -1445,6 +1664,7 @@ export function apply(ctx, config) {
 
   ctx.effect(() => () => {
     disposeSkill()
+    void streamHost.dispose()
     void engine.dispose()
   }, 'dsh-mobilecode: engine')
 

package/lib/stream-access.js

@@ -0,0 +1,220 @@
+/**
+ * dsh-mobilecode — capability tokens and the transport fence for the live
+ * stream routes.
+ *
+ * Ported from ZSeven-W/dsh-android (stream-access.ts, MIT), same security
+ * posture:
+ * - HMAC-SHA256 capabilities `base64url(payload).base64url(mac)`, signed with a
+ *   32-byte per-install key (`~/.dsh/mobilecode/stream-access.key`, created
+ *   atomically); tokens expire within 10 minutes.
+ * - Every route applies the loopback / trusted-browser transport fence (peer
+ *   address, loopback Host, Sec-Fetch-Site / Origin) BEFORE any capability is
+ *   consulted — Host/Origin are caller-controlled, so a LAN client cannot spoof
+ *   localhost and a DNS-rebinding Host is rejected.
+ *
+ * The screenshot-cache containment walk of the reference is not ported: this
+ * plugin serves only the live stream over its routes (device_screen writes PNGs
+ * to disk directly), so there is no arbitrary-path-serving surface to fence.
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { HOME } from './setup.js'
+
+/** Hard capability lifetime (tokens expire within 10 minutes). */
+export const TOKEN_TTL_MS = 10 * 60 * 1000
+
+const KEY_BYTES = 32
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/
+const MAX_TOKEN_LENGTH = 16 * 1024
+/** Signing may run ahead of verification by this much before the TTL cap trips. */
+const CLOCK_SKEW_MS = 60 * 1000
+
+/** adb device serials: `emulator-5554`, `RFCX123ABC`, or `host:port` for network adb. */
+export const SERIAL_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/
+
+function keyPath() {
+  return path.join(HOME, 'stream-access.key')
+}
+
+function mac(key, payload) {
+  return createHmac('sha256', key).update(payload).digest()
+}
+
+function safeEqual(left, right) {
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+/** Load or atomically create the per-install 32-byte signing key. */
+export async function prepareStreamAccessKey() {
+  await mkdir(HOME, { recursive: true })
+  const file = keyPath()
+  if (existsSync(file)) {
+    const key = await readFile(file)
+    if (key.length === KEY_BYTES) return key
+    throw new Error('dsh-mobilecode: stream access key has an invalid length')
+  }
+  const candidate = randomBytes(KEY_BYTES)
+  try {
+    await writeFile(file, candidate, { flag: 'wx', mode: 0o600 })
+    return candidate
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+    const key = await readFile(file)
+    if (key.length !== KEY_BYTES) throw new Error('dsh-mobilecode: stream access key has an invalid length')
+    return key
+  }
+}
+
+function parseStreamPayload(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  if (
+    value.v !== 1
+    || value.kind !== 'mobilecode-stream'
+    || typeof value.serial !== 'string'
+    || !SERIAL_PATTERN.test(value.serial)
+    || typeof value.exp !== 'number'
+    || !Number.isSafeInteger(value.exp)
+  ) return undefined
+  return { v: 1, kind: 'mobilecode-stream', serial: value.serial, exp: value.exp }
+}
+
+/** HMAC capability encoder/verifier for the live stream URL. */
+export class StreamAccessController {
+  #routeCount = 0
+  #keyPromise
+
+  constructor(resolveKey = prepareStreamAccessKey) {
+    this.resolveKey = resolveKey
+  }
+
+  /** Whether at least one HTTP carrier currently owns the routes. */
+  get routeAvailable() {
+    return this.#routeCount > 0
+  }
+
+  /** Mark one route attachment; the returned disposer removes it. */
+  attachRoute() {
+    this.#routeCount += 1
+    let active = true
+    return () => {
+      if (!active) return
+      active = false
+      this.#routeCount -= 1
+    }
+  }
+
+  /** Mint a stream capability for one device serial. */
+  async signStreamToken(serial, options = {}) {
+    if (!SERIAL_PATTERN.test(serial)) throw new TypeError('dsh-mobilecode: signStreamToken requires a device serial')
+    const key = await this.#key()
+    const payload = { v: 1, kind: 'mobilecode-stream', serial, exp: Date.now() + this.#ttl(options.ttlMs) }
+    const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url')
+    return { token: `${encoded}.${mac(key, encoded).toString('base64url')}`, expiresAt: payload.exp }
+  }
+
+  async verifyStreamToken(token) {
+    if (token.length === 0 || token.length > MAX_TOKEN_LENGTH || !TOKEN_PATTERN.test(token)) return undefined
+    const [encoded, signature] = token.split('.')
+    if (encoded === undefined || signature === undefined) return undefined
+    const key = await this.#key().catch(() => undefined)
+    if (key === undefined) return undefined
+    let supplied
+    try {
+      supplied = Buffer.from(signature, 'base64url')
+    } catch {
+      return undefined
+    }
+    if (!safeEqual(mac(key, encoded), supplied)) return undefined
+    try {
+      const payload = parseStreamPayload(JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8')))
+      if (payload === undefined) return undefined
+      const now = Date.now()
+      if (payload.exp <= now) return undefined
+      if (payload.exp - now > TOKEN_TTL_MS + CLOCK_SKEW_MS) return undefined
+      return payload
+    } catch {
+      return undefined
+    }
+  }
+
+  #ttl(ttlMs) {
+    if (ttlMs === undefined || !Number.isFinite(ttlMs)) return TOKEN_TTL_MS
+    return Math.min(TOKEN_TTL_MS, Math.max(1, Math.floor(ttlMs)))
+  }
+
+  #key() {
+    this.#keyPromise ??= this.resolveKey()
+    return this.#keyPromise
+  }
+}
+
+// ── loopback / trusted-browser transport fence ───────────────────────────────
+
+function isIpv4LoopbackAddress(address) {
+  const parts = address.split('.')
+  return parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * Trust the transport peer, never forwarded or caller-controlled host data.
+ * Node may expose an IPv4 peer directly or as an IPv4-mapped IPv6 address,
+ * including the compact hexadecimal form used by some platforms.
+ */
+export function isLoopbackRemoteAddress(address) {
+  if (address === undefined) return false
+  const normalized = address.toLowerCase().split('%', 1)[0]
+  if (normalized === '::1' || isIpv4LoopbackAddress(normalized)) return true
+  if (!normalized.startsWith('::ffff:')) return false
+  const mapped = normalized.slice('::ffff:'.length)
+  if (isIpv4LoopbackAddress(mapped)) return true
+  const hexadecimal = /^([a-f0-9]{1,4}):([a-f0-9]{1,4})$/.exec(mapped)
+  return hexadecimal !== null && (Number.parseInt(hexadecimal[1], 16) >>> 8) === 127
+}
+
+function isLoopbackHostname(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]' || hostname === '::1') return true
+  return isIpv4LoopbackAddress(hostname)
+}
+
+function requestAuthority(req) {
+  const host = req.headers.host
+  if (typeof host !== 'string') return undefined
+  try {
+    const parsed = new URL(`http://${host}`)
+    if (parsed.pathname !== '/' || parsed.search !== '' || parsed.hash !== '' || parsed.username !== '' || parsed.password !== '') {
+      return undefined
+    }
+    return parsed
+  } catch {
+    return undefined
+  }
+}
+
+function isLoopbackRequest(req) {
+  if (!isLoopbackRemoteAddress(req.socket?.remoteAddress)) return false
+  const authority = requestAuthority(req)
+  return authority !== undefined && isLoopbackHostname(authority.hostname)
+}
+
+function isTrustedBrowserRequest(req, requireOrigin) {
+  if (req.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = req.headers.origin
+  if (origin === undefined) return !requireOrigin
+  if (typeof origin !== 'string') return false
+  const authority = requestAuthority(req)
+  if (authority === undefined) return false
+  try {
+    const parsed = new URL(origin)
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && parsed.host === authority.host
+  } catch {
+    return false
+  }
+}
+
+/** The transport fence applied to every stream route. */
+export function isTrustedRequest(req, requireOrigin = false) {
+  return isLoopbackRequest(req) && isTrustedBrowserRequest(req, requireOrigin)
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mobilecode",
   "description": "MobileCode for the dsh web GUI: detect iOS/Android projects, run serve-sim / serve-avd preview servers, and build-install-launch the app on the simulator or emulator from the session — plus agent tools (device_run, device_detect). Hot-pluggable — mounted via the profile bundle list + cordis.patch.yml, no dsh source changes.",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "packageManager": "pnpm@11.22.0",
   "engines": {