@slack/radar-mcp 1.4.0 → 1.5.0

package/dist/shared/screen.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Live device-screen mirror + record, for the dashboard's Screen overlay.
+ *
+ * Pipeline (scrcpy-lite, no custom decoder): `adb exec-out screenrecord
+ * --output-format=h264` on the active display -> `ffmpeg` transcodes h264 to
+ * MJPEG -> the server pushes JPEG frames to a browser <img> over
+ * multipart/x-mixed-replace. Record tees the same JPEG frames to a second
+ * ffmpeg (mjpeg in -> libx264 mp4), so the live view and the recording share one
+ * screenrecord (the way scrcpy shares one capture).
+ *
+ * SENSITIVE: this mirrors the real device screen, which shows live DMs, message
+ * content, and anything else on screen. It is OFF by default and gated behind an
+ * explicit per-process consent (see consent state below); the server refuses the
+ * stream and record routes until consent is granted.
+ *
+ * DEPENDENCY POLICY: ffmpeg is NOT bundled and NOT a hard dependency (it is large
+ * and license-encumbered; the published package keeps a single runtime dep). The
+ * stream/record paths detect-and-degrade: present -> embedded MJPEG; absent ->
+ * a clear message plus the platform install command, and a scrcpy fallback hint.
+ * The screenshot path uses pure `screencap` (PNG, no transcode) so it MUST keep
+ * working with no ffmpeg.
+ *
+ * Hard-won device facts baked in (Pixel 10 Pro Fold and similar):
+ *  - Active-display detect must be deterministic: pick the powered-ON physical
+ *    panel from `cmd display get-displays`. Byte-probing cannot tell a dozing
+ *    black panel from a live one (a DOZE panel still emits ~1 keyframe).
+ *  - `screencap -p` prepends a "[Warning] Multiple displays were found" text line
+ *    on multi-display devices, corrupting the PNG. Strip everything before the
+ *    PNG magic bytes.
+ *  - screenrecord emits full-range YUV that the mjpeg encoder rejects; `-vf
+ *    format=yuvj420p` fixes it.
+ *  - H.264 emits nothing on a static screen (correct, not a hang). A
+ *    multipart/x-mixed-replace viewer only paints part N when part N+1 arrives,
+ *    so a keepalive re-pushes the last frame while idle to flush it.
+ *  - adb does not reliably SIGKILL the device-side screenrecord on host pipe
+ *    close; orphaned screenrecord procs congest the single adb transport. Kill
+ *    explicitly on cleanup.
+ */
+import { type ChildProcess } from "child_process";
+/**
+ * Remove all recorded mp4s from the screen tmp dir. Recordings capture sensitive
+ * live screen content and must not linger across sessions on disk. Called on
+ * resetScreenState() (device re-enable) and on process exit — the same posture the
+ * DB-browser uses for its pulled copies. Scoped to the radar_screen_*.mp4 names this
+ * module writes so it never deletes an unrelated file that landed in the dir.
+ */
+export declare function cleanupRecordings(): void;
+/** Resolve an ffmpeg binary, or null if none is installed. Cached. */
+export declare function resolveFfmpeg(): string | null;
+/** Whether scrcpy is installed (the no-ffmpeg fallback hint). Cached. */
+export declare function hasScrcpy(): boolean;
+/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+export declare function ffmpegInstallHint(): string;
+/** Capability summary for /health: what the screen overlay can do on this machine. */
+export declare function screenCapabilities(): {
+    screenshot: boolean;
+    liveCast: boolean;
+    ffmpeg: boolean;
+    scrcpy: boolean;
+    installHint: string | null;
+};
+/** Grant consent to mirror the live screen. Per server process. */
+export declare function grantScreenConsent(): void;
+export declare function hasScreenConsent(): boolean;
+export interface DisplayInfo {
+    on: boolean;
+    phys: string;
+}
+/**
+ * Parse `adb shell cmd display get-displays` output into per-display
+ * {on, phys}, dropping any block without a physical id. The active panel is the
+ * one whose block reports state ON.
+ */
+export declare function parseDisplays(out: string): DisplayInfo[];
+/** Choose the physical display id to record: the powered-ON panel, else a lone panel, else null. */
+export declare function pickDisplay(displays: DisplayInfo[]): {
+    phys: string | null;
+    note: string;
+};
+/** Strip any text prefix (e.g. a multi-display warning) before the PNG magic header. */
+export declare function stripPngPrefix(raw: Buffer): Buffer;
+/** Detect (and cache) the active display id. resetScreenState() forces a re-detect. */
+export declare function detectDisplay(): Promise<string | null>;
+export declare function displayNote(): string;
+/** Capture a full-resolution PNG of the active display. Works without ffmpeg. */
+export declare function captureScreenshot(): Promise<Buffer | null>;
+interface Recording {
+    proc: ChildProcess;
+    path: string;
+}
+interface LiveCast {
+    sr: ChildProcess;
+    ff: ChildProcess;
+    viewers: Set<NodeJS.WritableStream>;
+    lastFrame: Buffer | null;
+    lastFrameTs: number;
+    recording: Recording | null;
+    fps: number;
+    keepalive: NodeJS.Timeout | null;
+}
+/**
+ * Start (or return the existing) live cast. Returns null if ffmpeg is unavailable
+ * — callers must degrade rather than assume a stream. The boundary string is
+ * SC_BOUNDARY; the route serves multipart/x-mixed-replace with it.
+ */
+export declare function startLive(fps: number): LiveCast | null;
+/** Attach an HTTP response as a viewer of the live cast (after the multipart headers are written). */
+export declare function addViewer(L: LiveCast, res: NodeJS.WritableStream): void;
+export declare function removeViewer(res: NodeJS.WritableStream): void;
+export declare function getLive(): LiveCast | null;
+export declare function lastFrame(): Buffer | null;
+export declare function primeIfNeeded(): Promise<void>;
+export declare const SCREEN_BOUNDARY = "radarframe";
+export declare function startRecording(): string | null;
+export declare function stopRecording(L?: LiveCast): Promise<string | null>;
+/**
+ * Resolve a recording for download. Restricted to the screen tmp dir AND to the
+ * radar_screen_*.mp4 name this module writes: path.basename strips any directory
+ * (no traversal), and the prefix/extension check means a download request can only
+ * ever name a radar recording, never an arbitrary file that happened to land in the dir.
+ */
+export declare function recordingPath(file: string): string | null;
+/** Reset detection + tear down any live cast. Called on device re-enable and shutdown. */
+export declare function resetScreenState(): void;
+/**
+ * Kill any live cast (and orphaned device-side screenrecord) on process exit. Mirrors
+ * logcat-capture.registerCleanup(); without it, Ctrl-C on an open mirror orphans the
+ * screenrecord + ffmpeg children and leaves the device transport congested for the
+ * next session. Called from createServer().
+ */
+export declare function registerScreenCleanup(): void;
+export {};