@desklink/host 0.1.0

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public API of the desktop host engine package.
+ *
+ * The engine itself is a native per-user process; this package is how a
+ * consumer starts it and speaks its local control protocol. Nothing in this
+ * surface refers to any particular application.
+ */
+export * from './protocol.js';
+export { EngineClient } from './engineProcess.js';
+export { resolveEngine, explainMissingEngine, enginePackageRoot } from './resolveEngine.js';
+export { Bridge, BRIDGE_PATH } from './bridge.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAuB,MAAM,oBAAoB,CAAC;AACjH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The engine's local control protocol, as a consumer sees it.
+ *
+ * `docs/PROTOCOL.md` is the prose authority; these types are the same contract
+ * expressed for a caller. They deliberately contain nothing about any particular
+ * application: a machine id, a chat or an account has no place here.
+ */
+export declare const PROTOCOL_VERSION = 2;
+export interface EngineError {
+    code: string;
+    message: string;
+}
+export interface EngineCapabilities {
+    protocol: number;
+    engine: string;
+    platform: string;
+    session: {
+        kind: string;
+    };
+    /** Whether the X11 backend can reach a server here, and that server's screen size. */
+    x11: {
+        available: boolean;
+        size: [number, number] | null;
+    };
+    capture: {
+        mechanism: string;
+        /** Backends this build has, not what this machine can necessarily use. */
+        backends: string[];
+        formats: string[];
+        cursor: string;
+        audio: boolean;
+    };
+    encode: {
+        codecs: string[];
+        hardware: boolean;
+    };
+    input: {
+        mechanism: string;
+        pointer: boolean;
+        wheel: boolean;
+        keyboard: boolean;
+        text: string[];
+        layout: string;
+        unavailable_reason: {
+            reason: string;
+            remedy: string;
+        } | null;
+        grant: string;
+    };
+    clipboard: {
+        read: boolean;
+        write: boolean;
+        mime: string[];
+        maxBytes: number;
+    };
+}
+export interface SurfaceGeometry {
+    source: {
+        width: number;
+        height: number;
+    };
+    encoded: {
+        width: number;
+        height: number;
+    };
+    origin: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Which desktop to capture. Absent means the portal, which is the only backend
+ * that carries a Wayland user's consent; an explicit X display is the supported
+ * alternative for a machine whose screen-cast portal does not work, and it is
+ * what a host with no Wayland session uses.
+ */
+export type SourceRequest = {
+    kind: 'portal';
+} | {
+    kind: 'x11';
+    display?: string;
+};
+export interface OpenSessionRequest {
+    source?: SourceRequest;
+    /** `view` alone is capture-only; `control` needs a working input backend. */
+    permissions: Array<'view' | 'control' | 'clipboard'>;
+    maxWidth?: number;
+    maxHeight?: number;
+    bitrateKbps?: number;
+    maxFps?: number;
+    iceServers?: Array<{
+        urls: string[];
+        username?: string;
+        credential?: string;
+    }>;
+    restoreToken?: string;
+    ttlSeconds?: number;
+    /** Also listen for ICE over TCP on the loopback, for a client behind a local forward. */
+    loopbackTcp?: boolean;
+}
+export interface OpenedSession {
+    sessionId: string;
+    generation: number;
+    source: {
+        kind: string;
+        width: number;
+        height: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+    };
+    geometry: SurfaceGeometry;
+}
+export type EngineEvent = {
+    event: 'session.description';
+    params: {
+        sessionId: string;
+        generation: number;
+        description: {
+            type: 'offer';
+            sdp: string;
+        };
+    };
+} | {
+    event: 'session.candidate';
+    params: {
+        sessionId: string;
+        generation: number;
+        candidate: string;
+        sdpMid: string | null;
+        sdpMLineIndex: number | null;
+    };
+} | {
+    event: 'session.state';
+    params: {
+        sessionId: string;
+        capture: string;
+        transport: string;
+        firstFrame: boolean;
+    };
+} | {
+    event: 'session.restoreToken';
+    params: {
+        sessionId: string;
+        token: string;
+    };
+} | {
+    event: 'session.revoked';
+    params: {
+        sessionId: string;
+        reason: string;
+    };
+};
+export type EngineEventName = EngineEvent['event'];
+export interface SessionMetrics {
+    captured_frames: number;
+    dropped_frames: number;
+    encoded_frames: number;
+    encoded_bytes: number;
+    input_applied: number;
+    input_rejected: number;
+}
+/** A protocol-level failure carrying the engine's stable error code. */
+export declare class EngineRefused extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,18 @@
+/**
+ * The engine's local control protocol, as a consumer sees it.
+ *
+ * `docs/PROTOCOL.md` is the prose authority; these types are the same contract
+ * expressed for a caller. They deliberately contain nothing about any particular
+ * application: a machine id, a chat or an account has no place here.
+ */
+export const PROTOCOL_VERSION = 2;
+/** A protocol-level failure carrying the engine's stable error code. */
+export class EngineRefused extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'EngineRefused';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AA0GlC,wEAAwE;AACxE,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC3B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACrC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ"}

package/dist/resolveEngine.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Finding the engine executable.
+ *
+ * Three sources, in order, and no fourth:
+ *
+ *  1. an explicit path, when a consumer or an operator names one;
+ *  2. this package's platform package, which npm installs as an optional
+ *     dependency on a platform that has a prebuilt engine (Linux x64 glibc);
+ *  3. this package's own build output, for a source build.
+ *
+ * Deliberately not searched: `PATH`. "A program called desklink-host" is not
+ * evidence of which program is about to be given control of a desktop.
+ */
+export interface ResolvedEngine {
+    command: string;
+    args: string[];
+    origin: 'configured' | 'prebuilt' | 'package';
+}
+export declare function enginePackageRoot(): string;
+/**
+ * The platform package for this machine.
+ *
+ * `libc` is part of the tag because a glibc binary on a musl system fails in
+ * ways that look like a broken install rather than an unsupported one, and
+ * because npm's own `libc` selector is not honoured by every client.
+ */
+export declare function platformTag(platform?: string, arch?: string, glibc?: boolean | undefined): string;
+export declare function resolveEngine(configured?: string | undefined): ResolvedEngine | null;
+/**
+ * Why the engine is missing, in words fit to show a user. `null` means it is
+ * there.
+ */
+export declare function explainMissingEngine(configured?: string | undefined): string | null;
+//# sourceMappingURL=resolveEngine.d.ts.map

package/dist/resolveEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveEngine.d.ts","sourceRoot":"","sources":["../src/resolveEngine.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;CACjD;AAKD,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,QAAQ,GAAE,MAAyB,EACnC,IAAI,GAAE,MAAqB,EAC3B,KAAK,GAAE,OAAO,GAAG,SAAsB,GACxC,MAAM,CAGR;AAiCD,wBAAgB,aAAa,CAAC,UAAU,qBAAmC,GAAG,cAAc,GAAG,IAAI,CAelG;AAWD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,qBAAmC,GAAG,MAAM,GAAG,IAAI,CAiBjG"}

package/dist/resolveEngine.js

@@ -0,0 +1,103 @@
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Platforms with a published platform package. */
+const PREBUILT_PLATFORMS = ['linux-x64-gnu'];
+export function enginePackageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+/**
+ * The platform package for this machine.
+ *
+ * `libc` is part of the tag because a glibc binary on a musl system fails in
+ * ways that look like a broken install rather than an unsupported one, and
+ * because npm's own `libc` selector is not honoured by every client.
+ */
+export function platformTag(platform = process.platform, arch = process.arch, glibc = hasGlibc()) {
+    if (platform === 'linux')
+        return `linux-${arch}-${glibc === false ? 'musl' : 'gnu'}`;
+    return `${platform}-${arch}`;
+}
+/** A Linux Node without a reported glibc runtime is taken to be musl. */
+function hasGlibc() {
+    if (process.platform !== 'linux')
+        return undefined;
+    const report = process.report?.getReport?.();
+    return report?.header?.glibcVersionRuntime !== undefined;
+}
+function prebuiltBinary() {
+    const require = createRequire(import.meta.url);
+    const name = `@desklink/host-${platformTag()}`;
+    try {
+        // The platform package's manifest points at the executable, so the
+        // binary's name and location stay that package's business.
+        const manifest = require(`${name}/package.json`);
+        const relative = manifest.executable ?? manifest.bin?.['desklink-host'];
+        if (typeof relative !== 'string')
+            return null;
+        const path = require.resolve(`${name}/${relative.replace(/^\.\//, '')}`);
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+function buildCandidates(root) {
+    return [
+        join(root, 'engine', 'target', 'release', 'desklink-host'),
+        join(root, 'engine', 'target', 'debug', 'desklink-host'),
+        join(root, 'bin', 'desklink-host'),
+    ];
+}
+export function resolveEngine(configured = process.env.MUXR_DESKLINK_ENGINE) {
+    if (configured !== undefined && configured.trim() !== '') {
+        if (!isExecutable(configured))
+            return null;
+        return { command: configured, args: ['serve'], origin: 'configured' };
+    }
+    const prebuilt = prebuiltBinary();
+    if (prebuilt !== null && isExecutable(prebuilt)) {
+        return { command: prebuilt, args: ['serve'], origin: 'prebuilt' };
+    }
+    for (const candidate of buildCandidates(enginePackageRoot())) {
+        if (isExecutable(candidate)) {
+            return { command: candidate, args: ['serve'], origin: 'package' };
+        }
+    }
+    return null;
+}
+function isExecutable(path) {
+    if (!existsSync(path))
+        return false;
+    const stat = statSync(path);
+    if (!stat.isFile())
+        return false;
+    // A file that is not executable is an install that went wrong, and saying so
+    // is more useful than an EACCES three calls later.
+    return (stat.mode & 0o111) !== 0;
+}
+/**
+ * Why the engine is missing, in words fit to show a user. `null` means it is
+ * there.
+ */
+export function explainMissingEngine(configured = process.env.MUXR_DESKLINK_ENGINE) {
+    const resolved = resolveEngine(configured);
+    if (resolved !== null)
+        return null;
+    if (configured !== undefined && configured.trim() !== '') {
+        if (!existsSync(configured)) {
+            return `The desktop engine is not at the configured path (${configured}).`;
+        }
+        return `The desktop engine at ${configured} is not an executable file.`;
+    }
+    if (process.platform !== 'linux') {
+        return `The desktop engine runs on Linux only; ${process.platform} is not supported yet.`;
+    }
+    const tag = platformTag();
+    if (PREBUILT_PLATFORMS.includes(tag)) {
+        return `The prebuilt desktop engine for ${tag} is missing. It arrives as the optional dependency @desklink/host-${tag}: reinstall without omitting optional dependencies, or point MUXR_DESKLINK_ENGINE at an engine built from source.`;
+    }
+    return `There is no prebuilt desktop engine for ${tag}. Build it from source (see the @desklink/host README) and point MUXR_DESKLINK_ENGINE at the binary.`;
+}
+//# sourceMappingURL=resolveEngine.js.map

package/dist/resolveEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveEngine.js","sourceRoot":"","sources":["../src/resolveEngine.ts"],"names":[],"mappings":"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"}

package/docs/BOUNDARY.md

@@ -0,0 +1,145 @@
+# Boundary sketch — two packages, one consumer
+
+Written before implementation as the contract the code has to satisfy. Status
+markers are honest: `[decided]`, `[open]`.
+
+## Why two packages and not one
+
+The host side is a native, per-user, permission-bearing process: capture,
+encode, WebRTC, kernel input. The client side is mobile-native: hardware decode,
+a renderer, an IME bridge, the platform clipboard. They share exactly one thing —
+a versioned wire contract — and nothing else. Putting them in one package would
+mean the phone pins a native host build, or the host pins a mobile runtime.
+
+## Package 1 — host engine `[decided]`
+
+**Boundary:** "given a granted desktop source, produce a WebRTC video track and
+apply authenticated input to the same desktop".
+
+- In: `session.open`, SDP/ICE, scoped WebRTC control-channel input, explicit
+  clipboard read/write, close. See `docs/PROTOCOL.md`.
+- Out: one VP9 video track and session notifications. Metrics are a request, not
+  an event; the wire contract is in `docs/PROTOCOL.md`.
+- Process shape: per-user, on-demand, spawned by a consumer that already owns
+  the session, spoken to over an inherited private channel. No listener, no
+  daemon, no autostart, no root.
+- Never: decides identity, installs rules, grants capabilities, carries audio,
+  arbitrates two controllers, remembers a session across a restart.
+
+The public surface carries no consumer concepts. A machine id, a chat, a pane or
+an account never appears in the protocol or in the engine's state.
+
+## Package 2 — React Native client `[decided]`
+
+**Boundary:** "given an authorized session description, show the desktop and turn
+local gestures into that session's input".
+
+- `useDesktopSession({ authorize, onStateChange, onError })` owns connection,
+  negotiation, readiness, reconnect and typed errors. `authorize()` returns the
+  session's `signaling` channel and the permissions it may ask for.
+- `<DesktopView sessionId style />` owns the live surface and gesture mapping. It
+  owns nothing about layout, chrome, navigation or the conversation it sits in.
+- `session.showKeyboard()/hideKeyboard()`,
+  `session.copyRemoteToLocal()/pasteLocalToRemote()` are the control primitives
+  the app mounts wherever it wants.
+- Native side owns the video decoder factory selection (hardware VP9 rather
+  than the underlying wrapper's software default), the renderer and the IME/text
+  connection. For input enablement and release on background/unmount, see the
+  [client contract](../../desktop-client/README.md#what-the-package-guarantees).
+- The app supplies `authorize()` (a short-lived, engine-scoped capability plus
+  the authenticated `signaling` channel it carries). The package never sees a
+  pairing blob, a machine id or a token format, and never persists one.
+- Platform files: `.native.ts` uses WebRTC through the app's existing native
+  binding; `.web.ts` uses the browser's own `RTCPeerConnection`, so the same
+  screen works in the PWA. `[decided]` the browser shim shares the
+  readiness/state layer (`useDesktopSession`) and carries its own gesture layer
+  in `src/native.web.ts`, exactly as the native view does; observed on an owned
+  display, not on the phone journey.
+
+## What the consumer (this application) keeps
+
+- The computer action in the conversation and the return.
+- Its own pairing, machine identity, authorization decision and revocation.
+- Carrying SDP/ICE over its existing authenticated encrypted channel.
+- Mapping an authorized request onto `session.open`'s permissions, and the
+  product's own start/loading/error copy.
+- Where the keyboard and clipboard controls sit, and the fact that internal ids
+  are never displayed.
+
+## Reused, not rebuilt `[decided]`
+
+| Need | Already in this repository |
+|---|---|
+| Encrypted mobile → host request path, identity, grants | `packages/contract` control plane + `apps/host/src/requests` |
+| Relay stream channel (host joins as machine, client as client) | `packages/contract` `wsTickets` / preview channel pattern |
+| A reference for a "live surface inside a conversation" | `apps/mobile/sources/desktop` |
+| Flow-test style for the packages | `apps/mobile/sources/catalog/application/sessionSync.integration.spec.ts` |
+
+## Reused, not rebuilt, outside the repository `[decided]`
+
+| Need | Library | Licence |
+|---|---|---|
+| WebRTC peer, ICE, DTLS, SRTP, RTP | `webrtc` (webrtc-rs) | MIT / Apache-2.0 |
+| Portal ScreenCast + PipeWire fd | `ashpd` (zbus) | MIT |
+| PipeWire stream client | `pipewire` | MIT |
+| VP9 encode | libvpx | BSD-3-Clause |
+| Virtual mouse/keyboard | inputtino (uinput/libevdev) | MIT |
+| Clipboard read/write | `wl-clipboard-rs` | MIT |
+| Keyboard layout mapping | `xkbcommon` | MIT |
+
+Not adopted: libwebrtc (a multi-gigabyte source build with an LGPL/GIO portal
+seam), GStreamer (LGPL), and every GPL/AGPL remote-desktop application.
+
+## Settled by reading the compositor's own source `[decided]`
+
+**1. Capture is CPU-readable, with no GPU download step.** A compositor's screen
+cast node chooses its buffer type from the client's format pod: xdg-desktop-
+portal-hyprland hard-codes `SPA_DATA_MemFd` unless the client's `EnumFormat`
+carries a `SPA_FORMAT_VIDEO_modifier` property, in which case it switches to
+DMA-BUF (and logs `pw requested dmabuf`). This engine deliberately sends no
+modifier and asks for MemFd, so frames arrive as mapped shared memory. It also
+means the engine has no EGL, GBM or vendor-driver dependency at all — the whole
+capture path is CPU, which is what makes it portable across machine classes. If
+some other compositor ignores the request and produces DMA-BUFs anyway, the
+engine drops those frames rather than reading garbage: a non-mappable buffer only
+increments the dropped counter, and a source that never yields a readable buffer
+gives up with the capture-start timeout, because capture never reports readiness.
+The negotiated buffer type is visible through `desktop-host capture-probe`, which
+is the only place it is reported.
+
+**2. The Android side reuses the app's WebRTC binding.** The client package
+compiles against the `org.webrtc` classes the installed `react-native-webrtc`
+already ships, so one native library serves the whole app, and it builds its own
+`PeerConnectionFactory` with `DefaultVideoDecoderFactory` (hardware-first, VP9
+included). It never touches `WebRTCModule.options`, so the app's shared factory
+and its voice path are unchanged. A second AAR copy was the alternative and was
+rejected: two copies of the JNI library in one app is a worse failure mode than
+one extra factory instance.
+
+## The seam a consumer connects through `[decided]`
+
+The engine needs exactly one thing from a consumer: somewhere for SDP and ICE to
+travel. That is `Signaling` on the client side and `EngineClient.drainEvents` /
+`acceptAnswer` / `addCandidate` on the host side, and it is deliberately small,
+because every application already has an authenticated way to talk to itself.
+
+muxr supplies its existing paired, encrypted request path and nothing else: no
+address, port, code or certificate reaches the user, and the engine's session is
+started by the host that already serves the terminal. A consumer with no channel
+of its own is not left to invent one — `desklink-host bridge` re-serves the same
+protocol over a WebSocket and serves a reference client that needs no build step,
+so a stranger's first run is one command and one URL.
+
+The same substitution is therefore available to both: the packages carry no muxr
+concept, and muxr's contribution is one file that adapts its own channel to the
+`Signaling` interface.
+
+## Still open `[open]`
+
+- Whether a persisted portal restore token makes the second visit to the desktop
+  silent, or whether the compositor asks again. The engine returns the token the
+  portal gives it (`session.restoreToken`) and accepts one on `session.open`; the
+  behaviour is the compositor's to decide and is not claimed until observed.
+- Whether the consumer should set a smaller `maxWidth`/`maxHeight` box per
+  device rather than use the engine's default (see `docs/PROTOCOL.md`). The
+  engine never upscales.