@desklink/host 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,44 @@
+desklink host engine
+Copyright the desklink authors. Licensed under the Apache License, Version 2.0.
+
+This distribution links or calls the following third-party components. None of
+them is copyleft; the notices below are the conditions of their permissive
+licences.
+
+  libvpx                        BSD-3-Clause
+    VP9 encoding. A source build links the host system's libvpx; the prebuilt
+    engine (@desklink/host-linux-x64-gnu) links libvpx v1.16.0 statically and
+    carries its licence and patent grant in THIRD_PARTY_LICENSES.txt.
+    https://chromium.googlesource.com/webm/libvpx/+/refs/heads/main/LICENSE
+
+  inputtino                     MIT
+    Virtual pointer and keyboard over uinput/libevdev. Vendored unmodified
+    under engine/vendor/inputtino at commit
+    f4ce2b0df536ef309e9ff318f75b460f7097d7c1; its LICENSE file is retained
+    alongside its source.
+
+  libevdev                      MIT (with a Linux-header GPL notice retained
+                                upstream; no GPL code is linked from it)
+    Used by inputtino to open and manage uinput devices.
+
+  xdg-desktop-portal            LGPL-2.1-or-later (NOT linked)
+  xdg-desktop-portal-hyprland   MIT (NOT linked)
+    Called over D-Bus, in a separate process, as any other desktop client does.
+    No portal implementation is bundled, linked or modified by this package.
+
+  PipeWire                      MIT (NOT bundled)
+    The client library the engine uses to read the portal's stream.
+
+  wayland / wayland-protocols   MIT
+  xkbcommon                     MIT
+    Keyboard layout lookup.
+
+  webrtc (webrtc-rs)            MIT / Apache-2.0
+  rustls, ring and their transitive dependencies: see their own notices. The
+    prebuilt engine reproduces every linked crate's licence text in
+    THIRD_PARTY_LICENSES.txt, and its build refuses any crate whose licence is
+    not permissive.
+
+No code from Sunshine, Moonlight, Apollo, RustDesk, GNOME Remote Desktop, KRdp,
+WayVNC, Guacamole or MeshCentral is copied, linked or derived from here. Those
+projects were read as architecture references only.

package/README.md

@@ -0,0 +1,266 @@
+# @desklink/host
+
+A per-user, on-demand desktop engine: capture the user's own screen, encode it,
+carry it over WebRTC, and apply that session's pointer, keyboard and clipboard
+actions back to the same desktop.
+
+It is a **process with a documented local protocol**, not a service. A consumer
+starts it, owns its stdin/stdout, carries the SDP/ICE over its own authenticated
+channel, and stops it. Nothing in the engine's public surface refers to any
+particular application.
+
+## What it does
+
+- **Capture** through the XDG Desktop Portal (`ScreenCast`) and PipeWire, with
+  compositor consent, or from an explicitly selected X display's root window.
+  The portal path asks for shared-memory buffers rather than DMA-BUFs, keeping
+  its pixel path on the CPU and out of the driver.
+- **Encode** VP9 with libvpx in real time, single pass, no lookahead: one frame
+  in, one packet out. Software by default, because a hardware encoder would put a
+  vendor driver dependency on every machine class. Tuned for a desktop: the
+  desktop's own pixels up to 4K (a phone zooms in, and text has to survive it),
+  screen-content mode, key frames only on request, and a refinement pass that
+  re-codes a still desktop once at a fine quantizer so it reads sharp.
+- **Transport** with WebRTC — ICE, DTLS, SRTP, RTP — and one data channel for the
+  session's pointer/keyboard/clipboard.
+- **Input** through [inputtino](https://github.com/games-on-whales/inputtino)
+  (MIT) over `uinput`/`libevdev` for portal capture, or XTest for an X display.
+  Both release held input when the session ends.
+- **Clipboard** explicitly, in both directions, only when asked. It is never
+  polled and never used as a hidden way to type. On Wayland, writes require
+  `wl-copy` from `wl-clipboard`; its selection server keeps the copied text
+  available after the desktop session ends, until another app replaces it.
+
+## What it deliberately does not do
+
+- It does not decide *who* the user is. The consumer authorizes; the engine
+  enforces the scope it was given.
+- It does not open a public listener, run as root, install udev rules, join
+  groups or raise capabilities.
+- It does not carry audio, arbitrate between two controllers, or remember a
+  session across a restart.
+
+## Install and run
+
+```sh
+npm install @desklink/host
+npx desklink-host path            # the engine this install will run
+npx desklink-host capabilities    # what this machine can do right now
+```
+
+On **Linux x64 with glibc 2.36 or newer** — Debian 12, Ubuntu 24.04, Fedora 37
+or later, Arch — that is the whole install. npm also installs the optional
+platform package `@desklink/host-linux-x64-gnu`, which carries the prebuilt
+engine, and `resolveEngine()` finds it there. No Rust toolchain, compiler or
+install script is involved, so `--ignore-scripts` installs work. The engine
+requires the system's `libpipewire-0.3.so.0`, `libxkbcommon.so.0`,
+`libevdev.so.2` and `libstdc++.so.6` (normally supplied by a modern Linux
+desktop). If one is missing, the host reports `missing system library: <name>`
+with code `missing-system-library` rather than failing silently; it does not
+bundle these system libraries. libvpx and inputtino are linked into the engine.
+
+The one step no install does for you is [kernel input access](#kernel-input-access),
+and only the portal backend needs it.
+
+There is no prebuilt engine for any other platform. Another Linux (arm64, musl)
+can [build it from source](#building-from-source). macOS and Windows are not
+supported: `capabilities` there says the engine runs on Linux only.
+
+Point `MUXR_DESKLINK_ENGINE` at a binary built elsewhere if you have one. The
+package never searches `PATH` for a same-named program: "a binary called
+desklink-host" is not evidence of which program is about to be given control of
+someone's desktop.
+
+### Building from source
+
+```sh
+cd packages/desktop-host        # from the repository root
+cargo build --release --manifest-path engine/Cargo.toml
+./bin/desklink-host.mjs path     # prints the binary this package will run
+./bin/desklink-host.mjs capabilities
+```
+
+A source build links system libraries through `pkg-config` (and libxcb
+directly), compiles `native/vpx_shim.c` against libvpx's headers, and builds
+the vendored inputtino project with CMake. On a clean machine, install:
+
+| Need | Debian/Ubuntu | Fedora | Arch |
+|---|---|---|---|
+| Rust toolchain (`cargo`, `cc`) | `rustup` + `build-essential` | `rustup` + `gcc gcc-c++` | `rustup` + `base-devel` |
+| CMake | `cmake` | `cmake` | `cmake` |
+| `pkg-config` | `pkg-config` | `pkgconf-pkg-config` | `pkgconf` |
+| libvpx (`vpx.pc`) | `libvpx-dev` | `libvpx-devel` | `libvpx` |
+| PipeWire 0.3.65+ (`libpipewire-0.3`) | `libpipewire-0.3-dev` | `pipewire-devel` | `pipewire` |
+| xkbcommon | `libxkbcommon-dev` | `libxkbcommon-devel` | `libxkbcommon` |
+| Wayland (`wayland-client`) | `libwayland-dev` | `wayland-devel` | `wayland` |
+| libevdev | `libevdev-dev` | `libevdev-devel` | `libevdev` |
+| libxcb (source/container builds only) | `libxcb1-dev` | `libxcb-devel` | `libxcb` |
+
+These are build prerequisites, not additional runtime requirements for the
+prebuilt package; in particular, libxcb is not a prebuilt runtime requirement.
+Nothing is downloaded by the build itself. The engine step in `yarn run check`
+skips with a list of missing prerequisites when any of these is absent; direct
+`cargo test --manifest-path engine/Cargo.toml` does not skip and needs them
+installed. Only a machine with all of them compiles and tests the crate.
+
+### Kernel input access
+
+Ordinary tests do not create real desktop devices. To opt into the hardware
+probe explicitly, run `DESKLINK_TEST_UINPUT=1 cargo test this_host_can_create_and_destroy_the_virtual_devices`
+inside `engine/` on a desktop you are authorized to control.
+
+Creating virtual input devices needs write access to `/dev/uinput`. That is
+whole-desktop control of the logged-in session, so it is a decision the user
+makes, not something an installation does for them:
+
+```sh
+npx desklink-host setup-input                     # where @desklink/host is installed
+npx -p @desklink/host desklink-host setup-input   # anywhere else, e.g. under an application that depends on it
+```
+
+That prints the exact, narrowly scoped rule — and changes nothing. Without
+`uinput` access a portal session can still be opened with `view` permission;
+asking for `control` is refused rather than presenting inert controls. An X
+session instead uses XTest and does not need `/dev/uinput`.
+
+## Licence and provenance
+
+Apache-2.0. The engine links two permissive native libraries — libvpx
+(BSD-3-Clause) and inputtino (MIT, vendored under `engine/vendor/`) — and calls
+the portal over D-Bus rather than linking it. See `NOTICE`. The prebuilt engine
+links libvpx statically and carries every licence text it owes, including each
+linked crate's, in its package's `THIRD_PARTY_LICENSES.txt`, with the Rust
+standard library's own notices in `COPYRIGHT-rust-library.html`. Its build
+refuses any crate whose licence is not permissive.
+
+No GPL/AGPL remote-desktop code is copied, linked or derived; Sunshine,
+Moonlight, Apollo and RustDesk were read as architecture references only.
+
+## Connecting an application to it
+
+The engine needs one thing from a consumer: somewhere for the SDP and ICE
+candidates to go, and somewhere for the answer and the client's candidates to
+come back. See `docs/PROTOCOL.md` for the authoritative wire contract.
+
+```ts
+import { EngineClient, resolveEngine } from '@desklink/host';
+
+const engine = resolveEngine();                       // prebuilt, or a source build
+const client = await EngineClient.start(engine.command, engine.args);
+const session = await client.openSession({ permissions: ['view', 'control', 'clipboard'] });
+
+// Everything the engine wants to tell the client arrives here, in order.
+client.drainEvents().forEach((event) => myChannel.send(event));
+
+// Bring the client's answer and candidates back.
+await client.acceptAnswer(session.sessionId, session.generation, answerSdp);
+await client.addCandidate(session.sessionId, session.generation, candidate, sdpMid, sdpMLineIndex);
+```
+
+`myChannel` is the application's own authenticated connection, whatever that is.
+There is no second identity system, no pairing ceremony and no account: the
+engine trusts the consumer's decision and enforces the scope it was given.
+
+### If you have no channel of your own
+
+`desklink-host bridge` is the minimal runnable example for third-party consumers:
+it re-serves the same protocol over a WebSocket and serves a reference client
+at `/` so the first run is one command:
+
+```sh
+desklink-host bridge --listen 127.0.0.1:19400
+#  engine   /path/to/desklink-host
+#  bridge   ws://127.0.0.1:19400/desktop
+#  token    <generated>
+#  open     http://127.0.0.1:19400/?token=<generated>
+```
+
+Open that URL and you have a desktop in a browser. `examples/reference-client.html`
+is that page's source: one file, no build step, and the shortest complete
+description of the protocol that exists. The bridge operator chooses the capture
+source with its flag or environment; clients cannot choose or override it.
+
+Two things the bridge is honest about: `ws://` is plaintext, so keep it on a
+private network or put it behind TLS; and the token in the URL *is* the
+authorisation for that socket, so treat it as a credential.
+
+## Packaging
+
+The engine is a native executable, so the package ships a small JavaScript
+launcher and depends on one platform package per supported target, which npm
+installs only where its `os`, `cpu` and `libc` match:
+
+```text
+@desklink/host
+  optionalDependencies:
+    @desklink/host-linux-x64-gnu     # the executable, THIRD_PARTY_LICENSES.txt, provenance.json
+```
+
+The optional dependency is written into the published manifest by
+`release/pack.mjs`, pinned to the same version, and is deliberately absent from
+the source `package.json`: an optional dependency the registry does not have
+yet makes a workspace's `yarn install --frozen-lockfile` fail outright rather
+than skip it.
+
+`resolveEngine` looks for the platform package first and falls back to a source
+build, and it never searches `PATH`: a program that happens to be called
+`desklink-host` is not evidence of which program is about to be given control of
+a desktop.
+
+The platform packages must be usable **without lifecycle scripts**, because
+muxr's documented install uses `npm install --global --ignore-scripts`. Nothing
+here downloads or chmods anything at install time; the executable arrives with
+the executable bit already set in the tarball.
+
+`platformTag()` includes the libc (`-gnu` or `-musl`) because a glibc binary on a
+musl system fails in ways that read as "broken install" rather than "unsupported
+platform". Only variants that have passed their own qualification are published:
+`linux-x64-gnu` now, `linux-arm64-gnu` when a real machine has run a real
+journey on it. macOS and Windows are separate backends, not separate builds.
+
+### Building and packing a release
+
+Needs Docker and Node, nothing else: no Rust toolchain or system libraries.
+
+```sh
+packages/desktop-host/release/build-engine.sh     # -> dist-desklink/engine-linux-x64-gnu/
+npx tsc --build packages/desktop-host
+node packages/desktop-host/release/pack.mjs --engine dist-desklink/engine-linux-x64-gnu
+packages/desktop-host/release/check-install.sh    # fresh install in a clean container
+```
+
+`build-engine.sh` builds the engine from this checkout in the container that
+`release/linux-x64-gnu.Dockerfile` pins: base images by digest, Debian packages
+by snapshot date, the Rust toolchain by version, libvpx by commit, crates by
+`Cargo.lock`. The same source gives the same executable, byte for byte. The
+build fails if libvpx ends up dynamically linked, if the executable needs a
+glibc newer than 2.36, or if any crate's licence is not permissive
+(`release/notices.mjs`, which also writes `THIRD_PARTY_LICENSES.txt`).
+`provenance.json` records the source commit, the pinned inputs and the
+executable's SHA-256.
+
+The scripts use only the repository's `dist-desklink/` paths shown above; none
+accepts an alternate output or tarball directory. `pack.mjs` requires the
+verified engine output and replaces older desklink tarballs with the current
+`desklink-host-<version>.tgz` and `desklink-host-linux-x64-gnu-<version>.tgz`.
+It cannot pack a host-only release and publishes nothing.
+The package smoke instead uses `npm pack` on this checkout's host package as a
+registry stand-in, without Docker or a native build. `check-install.sh` installs
+only the current version's two tarballs into an empty project in a container
+with no Rust toolchain, no display and no `/dev/uinput`, and checks both
+installed versions. It checks the typed
+missing-library error before installing the system runtime libraries, then has
+the host package resolve the prebuilt engine, start it and answer the protocol
+handshake and a capabilities probe.
+
+Publishing is by hand, from an `npm login` with publish rights on the scope.
+`release/publish.mjs` publishes the platform package first and waits until the
+registry serves it before publishing `@desklink/host`, so the host never points
+at an engine npm does not have. A version already on npm with the same bytes is
+skipped; with different bytes it is refused. `--dry-run` does everything but the
+upload:
+
+```sh
+node packages/desktop-host/release/publish.mjs --dry-run
+node packages/desktop-host/release/publish.mjs
+```

package/bin/desklink-host.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * CLI for the desktop host engine package.
+ *
+ * `path` and `capabilities` work without starting a session, so a consumer can
+ * tell the user what is wrong before a desktop is opened rather than after.
+ * Everything else is forwarded to the engine binary, so the CLI cannot drift
+ * from the process protocol it documents.
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { Bridge } from '../dist/bridge.js';
+import { EngineClient } from '../dist/engineProcess.js';
+import { explainMissingEngine, resolveEngine } from '../dist/resolveEngine.js';
+
+const [command, ...rest] = process.argv.slice(2);
+
+async function main() {
+    if (command === 'help' || command === '--help' || command === undefined) {
+        console.log(`desklink-host
+
+USAGE:
+  desklink-host path                  print the engine binary this package would run
+  desklink-host capabilities          print what this machine can do right now
+  desklink-host bridge [--listen H:P] [--token T] [--source portal|x11] [--display :0]
+                                      re-serve the engine's protocol over a WebSocket and
+                                      print the URL to open; no signaling of your own needed
+  desklink-host <engine command> ...  run the engine directly (serve, capture-probe, setup-input, version)
+
+Set MUXR_DESKLINK_ENGINE to use an engine built somewhere else.`);
+        return 0;
+    }
+    if (command === 'path') {
+        const resolved = resolveEngine();
+        if (resolved === null) {
+            console.error(explainMissingEngine());
+            return 1;
+        }
+        console.log(resolved.command);
+        return 0;
+    }
+    if (command === 'bridge') {
+        const resolved = resolveEngine();
+        if (resolved === null) {
+            console.error(explainMissingEngine());
+            return 1;
+        }
+        const flag = (name, fallback) => {
+            const index = rest.indexOf(`--${name}`);
+            return index === -1 ? fallback : rest[index + 1];
+        };
+        const listen = flag('listen', '127.0.0.1:19400');
+        const token = flag('token', randomBytes(24).toString('base64url'));
+        if (typeof token !== 'string' || token.trim() === '') throw new Error('the bridge token must not be blank');
+        const sourceKind = flag('source', process.env.MUXR_DESKTOP_SOURCE ?? 'portal');
+        const display = flag('display', process.env.MUXR_DESKTOP_X11_DISPLAY);
+        const bridge = await Bridge.start({
+            listen,
+            token,
+            engineCommand: resolved.command,
+            engineArgs: resolved.args,
+            // The engine's own diagnostics are the only clue when a session
+            // fails below the protocol, so they are forwarded rather than
+            // swallowed.
+            engineOptions: { onDiagnostic: (line) => console.error(`engine: ${line}`) },
+            ...(sourceKind === 'x11'
+                ? { source: display === undefined ? { kind: 'x11' } : { kind: 'x11', display } }
+                : {}),
+        });
+        const host = listen.startsWith('0.0.0.0:') ? '<this machine>' : listen.split(':')[0];
+        console.log(`engine   ${resolved.command}`);
+        console.log(`bridge   ws://${listen}${'/desktop'}`);
+        console.log(`token    ${token}`);
+        console.log('');
+        console.log(`open     http://${host}:${bridge.port}/?token=${encodeURIComponent(token)}`);
+        console.log('');
+        console.log('Open that URL in a browser on this machine, or point a phone at it.');
+        console.log('ws:// is plaintext: keep it on a private network, or put it behind TLS.');
+        const stop = async () => { await bridge.close(); process.exit(0); };
+        process.on('SIGINT', () => void stop());
+        process.on('SIGTERM', () => void stop());
+        return await new Promise(() => undefined);
+    }
+    if (command === 'capabilities') {
+        const resolved = resolveEngine();
+        if (resolved === null) {
+            console.error(explainMissingEngine());
+            return 1;
+        }
+        const client = await EngineClient.start(resolved.command, resolved.args);
+        try {
+            console.log(JSON.stringify(await client.capabilities(), null, 2));
+        } finally {
+            await client.stop();
+        }
+        return 0;
+    }
+    const resolved = resolveEngine();
+    if (resolved === null) {
+        console.error(explainMissingEngine());
+        return 1;
+    }
+    const child = spawn(resolved.command, [command, ...rest], { stdio: 'inherit' });
+    return await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0)));
+}
+
+main().then(
+    (code) => process.exit(code),
+    (error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    },
+);