@xopcai/xopc 0.0.432 → 0.0.434

package/dist/src/phone/hdc-driver.js

@@ -0,0 +1,331 @@
+import { PhoneError, init_contracts } from "./contracts.js";
+import { runPhoneCommandBuffer } from "../process/phone-process.js";
+import { managedHdcPath } from "../runtime-tools/harmony-paths.js";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
+import sharp from "sharp";
+//#region src/phone/hdc-driver.ts
+init_contracts();
+function resolveHdcPath(configured, stateDir) {
+	if (configured) return configured;
+	const roots = [
+		process.env.HARMONYOS_SDK_HOME,
+		process.env.DEVECO_SDK_HOME,
+		"/Applications/DevEco-Studio.app/Contents/sdk/default",
+		join(homedir(), "Library/Huawei/Sdk")
+	];
+	for (const root of roots) if (root) for (const suffix of ["openharmony/toolchains", "toolchains"]) {
+		const candidate = join(root, suffix, process.platform === "win32" ? "hdc.exe" : "hdc");
+		if (existsSync(candidate)) return candidate;
+	}
+	const managed = managedHdcPath(stateDir);
+	return existsSync(managed) ? managed : "hdc";
+}
+function parseHdcDevices(raw) {
+	return raw.split(/\r?\n/).flatMap((line) => {
+		const fields = line.trim().split(/\s+/);
+		if (fields.length < 3 || fields[1] !== "USB") return [];
+		const state = fields[2] === "Connected" ? "device" : /unauth/i.test(fields[2]) ? "unauthorized" : "offline";
+		return [{
+			serial: fields[0],
+			name: `HarmonyOS ${fields[0]}`,
+			state,
+			emulator: false,
+			platform: "harmonyos"
+		}];
+	});
+}
+const bundlePattern = /^[a-zA-Z]\w*(?:\.\w+)+$/;
+const flag = (value) => value === true || value === "true";
+function parseHarmonyLayout(raw, windowId) {
+	const active = (JSON.parse(raw).children ?? []).filter((node) => String(node.attributes?.hostWindowId) === windowId && bundlePattern.test(String(node.attributes?.bundleName)));
+	if (active.length !== 1) throw new PhoneError("PHONE_APP_UNKNOWN", "Unable to identify the focused HarmonyOS window", 409);
+	const displayId = active[0].attributes?.displayId;
+	if (displayId !== void 0 && displayId !== "" && String(displayId) !== "0") throw new PhoneError("PHONE_UI_UNAVAILABLE", "HarmonyOS USB observation supports the primary display only", 409);
+	const elements = [];
+	let visited = 0;
+	const visit = (node, depth, sensitive = false) => {
+		if (++visited > 1e4 || depth > 100) throw new PhoneError("PHONE_UI_UNAVAILABLE", "HarmonyOS UI tree exceeds observation limits", 502);
+		const a = node.attributes ?? {};
+		if (a.visible === false || a.visible === "false") return;
+		const bounds = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(String(a.bounds ?? ""));
+		const editable = /^(TextInput|TextArea|Search)$/.test(String(a.type));
+		const password = sensitive || flag(a.password) || flag(a.isPassword) || editable && a.password !== false && a.password !== "false";
+		if (bounds && elements.length < 500) elements.push({
+			text: password ? "" : String(a.text ?? "").slice(0, 500),
+			description: password ? "" : String(a.description ?? "").slice(0, 300),
+			resourceId: String(a.id || a.key || ""),
+			clickable: flag(a.clickable),
+			focused: flag(a.focused),
+			editable,
+			password,
+			bounds: bounds.slice(1).map(Number)
+		});
+		if (Array.isArray(node.children)) for (const child of node.children) visit(child, depth + 1, password);
+	};
+	visit(active[0], 0);
+	return {
+		package: String(active[0].attributes.bundleName),
+		elements
+	};
+}
+function parseHarmonyLaunch(raw) {
+	const start = raw.indexOf("{");
+	if (start < 0) throw new PhoneError("PHONE_APP_UNAVAILABLE", "Unable to read HarmonyOS bundle information");
+	const entries = (JSON.parse(raw.slice(start)).hapModuleInfos ?? []).flatMap((module) => (module.abilityInfos ?? []).flatMap((ability) => ability.skills?.some((skill) => skill.entities?.includes("entity.system.home")) && /^[\w.$]+$/.test(ability.name ?? "") && /^[\w.]+$/.test(module.moduleName ?? "") ? [{
+		ability: ability.name,
+		module: module.moduleName
+	}] : []));
+	if (entries.length !== 1) throw new PhoneError("PHONE_APP_UNAVAILABLE", "The HarmonyOS app has no unique launcher ability");
+	return entries[0];
+}
+var HdcPhoneDriver = class {
+	constructor(path = resolveHdcPath(), command = runPhoneCommandBuffer) {
+		this.path = path;
+		this.command = command;
+	}
+	async run(args, signal) {
+		signal?.throwIfAborted();
+		try {
+			const output = await this.command(this.path, args, signal);
+			if (/^(?:\[Fail\]|error:|Error:|ErrorCode:|Failed to|Missing parameter|usage:|Permission denied|.*: not found|Unknown command)/im.test(output.toString())) throw new Error("HDC rejected command");
+			return output;
+		} catch (error) {
+			signal?.throwIfAborted();
+			if (error instanceof PhoneError) throw error;
+			throw new PhoneError("PHONE_HDC_FAILED", "HDC operation failed. Check the SDK path, USB authorization and UiTest availability.", 502);
+		}
+	}
+	async shell(serial, args, signal) {
+		return (await this.run([
+			"-t",
+			serial,
+			"shell",
+			...args
+		], signal)).toString();
+	}
+	async discover(signal) {
+		return parseHdcDevices((await this.run([
+			"list",
+			"targets",
+			"-v"
+		], signal)).toString());
+	}
+	async applications(serial, signal) {
+		const raw = await this.shell(serial, [
+			"bm",
+			"dump",
+			"-a"
+		], signal);
+		return [...new Set(raw.split(/\s+/).filter((name) => bundlePattern.test(name)))].slice(0, 500).map((packageName) => ({
+			packageName,
+			label: packageName
+		}));
+	}
+	async textInputStatus(_serial, _signal) {
+		return {
+			unicode: "unsupported",
+			method: "hdc-uitest",
+			keyboardRequired: false
+		};
+	}
+	async foreground(serial, signal) {
+		const raw = await this.shell(serial, [
+			"hidumper",
+			"-s",
+			"WindowManagerService",
+			"-a",
+			"-a"
+		], signal);
+		const focus = /^Focus window:\s*(\d+)\s*$/m.exec(raw)?.[1];
+		const row = raw.split(/\r?\n/).map((line) => line.trim().split(/\s+/)).find((parts) => parts[3] === focus && /^\d+$/.test(parts[2]) && parts[1] === "0");
+		if (!row) throw new PhoneError("PHONE_APP_UNKNOWN", "Unable to identify the focused HarmonyOS process", 409);
+		const bundle = (await this.shell(serial, ["cat", `/proc/${row[2]}/cmdline`], signal)).split("\0")[0].split(":")[0];
+		if (!bundlePattern.test(bundle)) throw new PhoneError("PHONE_APP_UNKNOWN", "Unable to identify the focused HarmonyOS app", 409);
+		return bundle;
+	}
+	async window(serial, signal) {
+		const raw = await this.shell(serial, [
+			"hidumper",
+			"-s",
+			"WindowManagerService",
+			"-a",
+			"-a"
+		], signal);
+		const id = /^Focus window:\s*(\d+)\s*$/m.exec(raw)?.[1];
+		if (!id || id === "0") throw new PhoneError("PHONE_APP_UNKNOWN", "No focused HarmonyOS window", 409);
+		return id;
+	}
+	async rotation(serial, signal) {
+		const screen = (await this.shell(serial, [
+			"hidumper",
+			"-s",
+			"DisplayManagerService",
+			"-a",
+			"-a"
+		], signal)).split(/-+ Screen ID: 0 -+/)[1]?.split(/-+ Screen ID:/)[0];
+		const rotation = screen && /^Rotation:\s*(0|1|2|3|90|180|270)\s*$/m.exec(screen)?.[1];
+		if (rotation === void 0) throw new PhoneError("PHONE_UI_UNAVAILABLE", "Unable to identify HarmonyOS display rotation", 502);
+		const value = Number(rotation);
+		return value > 3 ? value / 90 : value;
+	}
+	async observe(serial, signal) {
+		const directory = await mkdtemp(join(tmpdir(), "xopc-hdc-"));
+		const prefix = `/data/local/tmp/xopc-phone-${randomUUID()}`;
+		let frame;
+		try {
+			const windowId = await this.window(serial, signal);
+			const rotation = await this.rotation(serial, signal);
+			await this.shell(serial, [
+				"uitest",
+				"dumpLayout",
+				"-p",
+				`${prefix}.json`
+			], signal);
+			await this.run([
+				"-t",
+				serial,
+				"file",
+				"recv",
+				`${prefix}.json`,
+				join(directory, "layout.json")
+			], signal);
+			const native = parseHarmonyLayout(await readFile(join(directory, "layout.json"), "utf8"), windowId);
+			const capturedAt = Date.now();
+			try {
+				await this.shell(serial, [
+					"uitest",
+					"screenCap",
+					"-p",
+					`${prefix}.png`
+				], signal);
+				await this.run([
+					"-t",
+					serial,
+					"file",
+					"recv",
+					`${prefix}.png`,
+					join(directory, "screen.png")
+				], signal);
+			} catch {
+				signal.throwIfAborted();
+				await this.shell(serial, [
+					"snapshot_display",
+					"-f",
+					`${prefix}.jpeg`
+				], signal);
+				await this.run([
+					"-t",
+					serial,
+					"file",
+					"recv",
+					`${prefix}.jpeg`,
+					join(directory, "screen.jpeg")
+				], signal);
+				const jpeg = await readFile(join(directory, "screen.jpeg"));
+				try {
+					await sharp(jpeg, { limitInputPixels: 16e6 }).png().toFile(join(directory, "screen.png"));
+				} finally {
+					jpeg.fill(0);
+				}
+			}
+			frame = await readFile(join(directory, "screen.png"));
+			if (await this.window(serial, signal) !== windowId || await this.rotation(serial, signal) !== rotation) throw new PhoneError("PHONE_FRAME_CHANGED", "HarmonyOS foreground changed during capture; observe again", 409);
+			const info = await sharp(frame, { limitInputPixels: 16e6 }).metadata();
+			if (info.format !== "png" || !info.width || !info.height) throw new PhoneError("PHONE_UI_UNAVAILABLE", "Invalid HarmonyOS screenshot", 502);
+			return {
+				platform: "harmonyos",
+				frameId: randomUUID(),
+				capturedAt,
+				width: info.width,
+				height: info.height,
+				rotation,
+				package: native.package,
+				frame,
+				elements: native.elements
+			};
+		} catch (error) {
+			frame?.fill(0);
+			throw error;
+		} finally {
+			await this.shell(serial, [
+				"rm",
+				"-f",
+				`${prefix}.json`,
+				`${prefix}.png`,
+				`${prefix}.jpeg`
+			], AbortSignal.timeout(3e3)).catch(() => {});
+			await rm(directory, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	async execute(serial, action, observation, signal, options) {
+		const point = ([x, y]) => [String(Math.max(0, Math.min(observation.width - 1, Math.round(x * observation.width / 1e3)))), String(Math.max(0, Math.min(observation.height - 1, Math.round(y * observation.height / 1e3))))];
+		const input = (args) => this.shell(serial, [
+			"uitest",
+			"uiInput",
+			...args
+		], signal);
+		switch (action.type) {
+			case "tap":
+				await input(["click", ...point(action.point)]);
+				break;
+			case "doubleTap":
+				await input(["doubleClick", ...point(action.point)]);
+				break;
+			case "longPress":
+				await input(["longClick", ...point(action.point)]);
+				break;
+			case "swipe": {
+				const distance = Math.hypot((action.end[0] - action.start[0]) * observation.width / 1e3, (action.end[1] - action.start[1]) * observation.height / 1e3);
+				const velocity = Math.max(200, Math.min(4e4, Math.round(distance * 1e3 / action.durationMs)));
+				await input([
+					"swipe",
+					...point(action.start),
+					...point(action.end),
+					String(velocity)
+				]);
+				break;
+			}
+			case "back":
+			case "home":
+				await input(["keyEvent", action.type === "back" ? "Back" : "Home"]);
+				break;
+			case "launch": {
+				if (!bundlePattern.test(action.package)) throw new PhoneError("PHONE_INVALID_INPUT", "Invalid HarmonyOS bundle name");
+				const entry = parseHarmonyLaunch(await this.shell(serial, [
+					"bm",
+					"dump",
+					"-n",
+					action.package
+				], signal));
+				const output = await this.shell(serial, [
+					"aa",
+					"start",
+					"-b",
+					action.package,
+					"-m",
+					entry.module,
+					"-a",
+					entry.ability
+				], signal);
+				if (!/start ability successfully/i.test(output)) throw new PhoneError("PHONE_LAUNCH_FAILED", "HarmonyOS app launch was not confirmed", 502);
+				break;
+			}
+			case "typeText": throw new PhoneError("PHONE_TEXT_INPUT_UNAVAILABLE", "This HarmonyOS connection requires text entry with the phone keyboard. Take over, enter text on the phone, then hand back.", 409);
+			case "tapElement": throw new PhoneError("PHONE_SEMANTIC_UNRESOLVED", "Resolve the native element before dispatch", 409);
+			case "wait":
+				await setTimeout(action.durationMs, void 0, { signal });
+				return;
+		}
+		await setTimeout(options?.settleMs ?? 350, void 0, { signal });
+	}
+};
+//#endregion
+export { HdcPhoneDriver, parseHarmonyLaunch, parseHarmonyLayout, parseHdcDevices, resolveHdcPath };

package/dist/src/phone/hdc-video-bridge.d.ts

@@ -0,0 +1,2 @@
+/** Compiled against the user's DevEco libraries; no vendor binaries are redistributed. */
+export declare const HDC_VIDEO_BRIDGE_SOURCE: string;

package/dist/src/phone/hdc-video-bridge.js

@@ -0,0 +1,91 @@
+//#region src/phone/hdc-video-bridge.ts
+/** Compiled against the user's DevEco libraries; no vendor binaries are redistributed. */
+const HDC_VIDEO_BRIDGE_SOURCE = String.raw`
+import com.huawei.hosscrcpy.api.HosRemoteConfig;
+import com.huawei.hosscrcpy.api.HosRemoteDevice;
+import com.huawei.hosscrcpy.api.ScreenCapCallback;
+import java.io.*;
+import java.nio.ByteBuffer;
+import java.util.jar.*;
+import java.util.Enumeration;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+public final class XopcHdcVideo {
+  private static final DataOutputStream WIRE = new DataOutputStream(new FileOutputStream(FileDescriptor.out));
+  private static final AtomicBoolean STOPPED = new AtomicBoolean(false);
+  private static HosRemoteDevice device;
+  private static synchronized void emit(int kind, byte[] bytes) {
+    if (STOPPED.get()) return;
+    try {
+      if (bytes.length > 4 * 1024 * 1024) throw new IOException("Video packet exceeds limit");
+      WIRE.writeByte(kind); WIRE.writeInt(bytes.length); WIRE.write(bytes); WIRE.flush();
+    } catch (IOException error) { STOPPED.set(true); System.exit(2); }
+  }
+  private static void stop() {
+    if (!STOPPED.compareAndSet(false, true)) return;
+    if (device != null) {
+      Thread cleanup = new Thread(() -> { try { device.stopCaptureScreen(); } catch (Throwable ignored) {} });
+      cleanup.setDaemon(true); cleanup.start();
+      try { cleanup.join(3000); } catch (InterruptedException ignored) { Thread.currentThread().interrupt(); }
+    }
+  }
+  private static String className(InputStream stream) throws IOException {
+    DataInputStream input = new DataInputStream(stream);
+    if (input.readInt() != 0xcafebabe) throw new IOException("Invalid library class");
+    input.readInt(); int count = input.readUnsignedShort(); Object[] pool = new Object[count];
+    for (int index = 1; index < count; index++) {
+      switch (input.readUnsignedByte()) {
+        case 1: pool[index] = input.readUTF(); break;
+        case 7: pool[index] = input.readUnsignedShort(); break;
+        case 8: case 16: case 19: case 20: input.skipNBytes(2); break;
+        case 3: case 4: case 9: case 10: case 11: case 12: case 17: case 18: input.skipNBytes(4); break;
+        case 5: case 6: input.skipNBytes(8); index++; break;
+        case 15: input.skipNBytes(3); break;
+        default: throw new IOException("Unsupported library class");
+      }
+    }
+    input.readUnsignedShort(); return (String) pool[(Integer) pool[input.readUnsignedShort()]];
+  }
+  private static boolean validLibrary(String path) throws IOException {
+    try (JarFile jar = new JarFile(path)) {
+      Enumeration<JarEntry> entries = jar.entries();
+      while (entries.hasMoreElements()) {
+        JarEntry entry = entries.nextElement(); String name = entry.getName();
+        // Some DevEco distributions contain incorrectly cased obfuscated class entries.
+        if (!name.endsWith(".class") || !(name.startsWith("com/a/") || name.startsWith("com/huawei/hosscrcpy/"))) continue;
+        try (InputStream input = jar.getInputStream(entry)) { if (!name.equals(className(input) + ".class")) return false; }
+      }
+    }
+    return true;
+  }
+  public static void main(String[] args) throws Exception {
+    // Vendor diagnostics must never corrupt the framed stdout transport.
+    System.setOut(new PrintStream(new FileOutputStream(FileDescriptor.err), true, "UTF-8"));
+    Runtime.getRuntime().addShutdownHook(new Thread(XopcHdcVideo::stop));
+    if (!validLibrary(args[2])) { emit(4, new byte[0]); stop(); System.exit(2); }
+    if (args[0].equals("--probe")) { HosRemoteConfig.class.getDeclaredMethods(); HosRemoteDevice.class.getDeclaredMethods(); ScreenCapCallback.class.getDeclaredMethods(); stop(); System.exit(0); }
+    HosRemoteConfig config = new HosRemoteConfig(args[0]);
+    config.setHdcPath(args[1]); config.setIp("127.0.0.1");
+    config.setScale(2); config.setFrameRate(24); config.setBitRate(2); config.setIFrameInterval(1);
+    device = new HosRemoteDevice(config);
+    Thread capture = new Thread(() -> {
+      try {
+        device.startCaptureScreen(new ScreenCapCallback() {
+          public void onReady() { emit(2, new byte[0]); }
+          public void onData(ByteBuffer source) {
+            if (source.remaining() > 4 * 1024 * 1024) { emit(3, new byte[0]); return; }
+            byte[] bytes = new byte[source.remaining()]; source.get(bytes); emit(1, bytes);
+          }
+          public void onException(Throwable error) { error.printStackTrace(System.err); emit(3, new byte[0]); }
+        });
+      } catch (Throwable error) { error.printStackTrace(System.err); emit(3, new byte[0]); }
+    });
+    capture.setDaemon(true); capture.start();
+    // A private pipe owns this bridge. EOF, explicit close and parent death stop capture.
+    while (System.in.read() != -1) { break; }
+    stop(); System.exit(0);
+  }
+}
+`;
+//#endregion
+export { HDC_VIDEO_BRIDGE_SOURCE };

package/dist/src/phone/hdc-video-tools.d.ts

@@ -0,0 +1,15 @@
+import type { PhoneConfig } from './contracts.js';
+export type HdcVideoTools = {
+    java: string;
+    javac: string;
+    classpath: string;
+    jar: string;
+};
+export declare function hdcJavaHomes(config: Pick<PhoneConfig, 'hdcVideo' | 'hdcPath'>, stateDir?: string): string[];
+export declare function resolveHdcJavaHome(config: Pick<PhoneConfig, 'hdcVideo' | 'hdcPath'>, stateDir?: string): string | undefined;
+export declare function resolveHdcVideoTools(config: Pick<PhoneConfig, 'hdcPath' | 'hdcVideo'>, stateDir?: string): HdcVideoTools | undefined;
+export declare function compileHdcVideoBridge(tools: HdcVideoTools, signal: AbortSignal): Promise<{
+    program: string;
+    args: string[];
+    cleanup: () => Promise<void>;
+}>;

package/dist/src/phone/hdc-video-tools.js

@@ -0,0 +1,123 @@
+import { PhoneError, init_contracts } from "./contracts.js";
+import { runPhoneCommandBuffer } from "../process/phone-process.js";
+import { managedHosJar, managedJavaHome } from "../runtime-tools/harmony-paths.js";
+import { resolveHdcPath } from "./hdc-driver.js";
+import { HDC_VIDEO_BRIDGE_SOURCE } from "./hdc-video-bridge.js";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+//#region src/phone/hdc-video-tools.ts
+init_contracts();
+function hdcJavaHomes(config, stateDir) {
+	const inferred = resolveHdcPath(config.hdcPath, stateDir).split(/[\\/]sdk[\\/]/)[0];
+	const roots = [
+		config.hdcVideo?.devecoPath,
+		process.env.DEVECO_HOME,
+		inferred,
+		"/Applications/DevEco-Studio.app/Contents",
+		"C:/Program Files/Huawei/DevEco Studio"
+	];
+	const suffix = process.platform === "win32" ? ".exe" : "";
+	const pathHomes = (process.env.PATH ?? "").split(delimiter).filter(Boolean).slice(0, 64).flatMap((directory) => {
+		try {
+			return [dirname(dirname(realpathSync(join(directory, `java${suffix}`))))];
+		} catch {
+			return [];
+		}
+	});
+	return [
+		config.hdcVideo?.javaHome,
+		managedJavaHome(stateDir),
+		process.env.JAVA_HOME,
+		...roots.flatMap((candidate) => {
+			if (!candidate) return [];
+			const root = existsSync(join(candidate, "Contents")) ? join(candidate, "Contents") : candidate;
+			return [join(root, "jbr", "Contents", "Home"), join(root, "jbr")];
+		}),
+		...pathHomes
+	].filter((home) => Boolean(home));
+}
+function resolveHdcJavaHome(config, stateDir) {
+	const suffix = process.platform === "win32" ? ".exe" : "";
+	return hdcJavaHomes(config, stateDir).find((home) => existsSync(join(home, "bin", `java${suffix}`)) && existsSync(join(home, "bin", `javac${suffix}`)));
+}
+function resolveHdcVideoTools(config, stateDir) {
+	const home = resolveHdcJavaHome(config, stateDir);
+	if (!home) return void 0;
+	const suffix = process.platform === "win32" ? ".exe" : "";
+	const executables = {
+		java: join(home, "bin", `java${suffix}`),
+		javac: join(home, "bin", `javac${suffix}`)
+	};
+	const standalone = config.hdcVideo?.sdkJar ?? (existsSync(managedHosJar(stateDir)) ? managedHosJar(stateDir) : void 0);
+	if (standalone) return existsSync(standalone) ? {
+		...executables,
+		jar: standalone,
+		classpath: standalone
+	} : void 0;
+	const inferred = resolveHdcPath(config.hdcPath, stateDir).split(/[\\/]sdk[\\/]/)[0];
+	const roots = [
+		config.hdcVideo?.devecoPath,
+		process.env.DEVECO_HOME,
+		inferred,
+		"/Applications/DevEco-Studio.app/Contents",
+		"C:/Program Files/Huawei/DevEco Studio"
+	];
+	for (const candidate of roots) {
+		if (!candidate) continue;
+		const root = existsSync(join(candidate, "Contents")) ? join(candidate, "Contents") : candidate;
+		const lib = join(root, "plugins", "screen-mirroring", "lib");
+		if (!existsSync(lib)) continue;
+		const jar = readdirSync(lib).find((name) => /^hosScrcpy-[\w.-]+\.jar$/.test(name));
+		if (jar) {
+			const sdkJar = join(lib, jar);
+			return {
+				...executables,
+				jar: sdkJar,
+				classpath: [
+					sdkJar,
+					join(root, "plugins", "harmony", "lib", "*"),
+					join(root, "lib", "*")
+				].join(delimiter)
+			};
+		}
+	}
+}
+async function compileHdcVideoBridge(tools, signal) {
+	const directory = await mkdtemp(join(tmpdir(), "xopc-hdc-video-"));
+	try {
+		await writeFile(join(directory, "XopcHdcVideo.java"), HDC_VIDEO_BRIDGE_SOURCE, { mode: 384 });
+		await runPhoneCommandBuffer(tools.javac, [
+			"-proc:none",
+			"--release",
+			"17",
+			"-cp",
+			tools.classpath,
+			"-d",
+			directory,
+			join(directory, "XopcHdcVideo.java")
+		], signal, 2e4);
+		return {
+			program: tools.java,
+			args: [
+				"-cp",
+				`${directory}${delimiter}${tools.classpath}`,
+				"XopcHdcVideo"
+			],
+			cleanup: () => rm(directory, {
+				recursive: true,
+				force: true
+			})
+		};
+	} catch {
+		await rm(directory, {
+			recursive: true,
+			force: true
+		});
+		signal.throwIfAborted();
+		throw new PhoneError("PHONE_HDC_VIDEO_DEPENDENCY", `Unable to compile the HarmonyOS video bridge. Check the full JDK 17+ and compatible HOScrcpy library (${dirname(tools.jar)}).`, 502);
+	}
+}
+//#endregion
+export { compileHdcVideoBridge, hdcJavaHomes, resolveHdcJavaHome, resolveHdcVideoTools };

package/dist/src/phone/hdc-video.d.ts

@@ -0,0 +1,69 @@
+import { runPhoneCommandBuffer, spawnPhoneInteractiveCommand } from '../process/phone-process.js';
+import { HdcPhoneDriver } from './hdc-driver.js';
+import { type PhoneConfig } from './contracts.js';
+import type { PhoneInteractiveProvider, PhonePointer, PhoneVideoGeometry, PhoneVideoPacket } from './live-provider.js';
+import { compileHdcVideoBridge, resolveHdcVideoTools } from './hdc-video-tools.js';
+/** Each bridge callback carries one complete Annex-B encoded buffer. */
+export declare class HdcVideoParser {
+    geometry: PhoneVideoGeometry;
+    private sps?;
+    private pps?;
+    private configuration?;
+    push(bytes: Buffer, emit: (packet: PhoneVideoPacket) => void): void;
+}
+/** Binary pipe framing prevents vendor logs or partial writes from becoming video. */
+export declare class HdcBridgeParser {
+    private buffer;
+    push(bytes: Buffer, emit: (kind: number, bytes: Buffer) => void): void;
+}
+type Dependencies = {
+    driver?: HdcPhoneDriver;
+    compile?: typeof compileHdcVideoBridge;
+    spawn?: typeof spawnPhoneInteractiveCommand;
+    command?: typeof runPhoneCommandBuffer;
+    tools?: typeof resolveHdcVideoTools;
+    validateScreen?: (app: string) => void;
+};
+/** H.264 video with completed-gesture input: cancellation never creates a tap. */
+export declare class HdcVideoProvider implements PhoneInteractiveProvider {
+    private serial;
+    private configOptions;
+    private onFailure;
+    private deps;
+    readonly descriptor: {
+        readonly kind: "hdc-h264";
+        readonly protocolVersion: 1;
+        readonly continuousTouch: false;
+        readonly maxPointers: 1;
+    };
+    private parser;
+    get geometry(): PhoneVideoGeometry;
+    private driver;
+    private listeners;
+    private config?;
+    private process?;
+    private bridge?;
+    private controller;
+    private inputController;
+    private opening?;
+    private started?;
+    private closing?;
+    private closed;
+    private input;
+    private inputEpoch;
+    private gesture?;
+    private forwards;
+    private ownedForwards;
+    private path;
+    constructor(serial: string, configOptions: PhoneConfig, onFailure: () => void, deps?: Dependencies);
+    foreground(signal: AbortSignal): Promise<string>;
+    private listForwards;
+    start(): Promise<void>;
+    private open;
+    subscribe(listener: (packet: PhoneVideoPacket) => void): () => void;
+    refresh(): void;
+    pointer(pointer: PhonePointer): Promise<void>;
+    revoke(): Promise<void>;
+    close(): Promise<void>;
+}
+export {};