screen-relay 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -19
- package/dist/cli/client.d.ts +1 -1
- package/dist/cli/config.d.ts +1 -1
- package/dist/cli/host/common.d.ts +1 -1
- package/dist/cli/host/state.d.ts +1 -1
- package/dist/cli/host/supervisor.d.ts +4 -1
- package/dist/cli/host/windows.d.ts +82 -0
- package/dist/cli/relay.mjs +563 -179
- package/dist/protocol/index.d.ts +2 -2
- package/dist/sdk/index.d.ts +2 -1
- package/dist/sdk/index.js +131 -21
- package/dist/sdk/transport.d.ts +20 -0
- package/dist/viewer/index.html +1 -1
- package/dist/viewer/viewer.js +40 -13
- package/package.json +2 -2
- package/skills/core/SKILL.md +7 -5
- package/skills/core/references/cli.md +13 -13
- package/skills/core/references/config.md +3 -3
- package/skills/core/references/sdk.md +1 -1
- package/skills/core/references/troubleshooting.md +2 -2
- package/skills/screen-relay/SKILL.md +1 -1
- package/src/engine/server/server.cpp +15 -11
- package/src/engine/server/server.hpp +3 -2
- package/src/engine/server/wire.cpp +5 -0
- package/src/engine/server/wire.hpp +2 -0
package/dist/protocol/index.d.ts
CHANGED
|
@@ -104,8 +104,8 @@ export type Message = {
|
|
|
104
104
|
export declare function parseMessage(bytes: Uint8Array | ArrayBuffer): Message;
|
|
105
105
|
/** Returns the `avc1.PPCCLL` codec string from the SPS in an H.264 Annex B keyframe. */
|
|
106
106
|
export declare function h264Codec(bytes: Uint8Array): string;
|
|
107
|
-
/** Returns the WebSocket URL and subprotocols for `/stream
|
|
108
|
-
export declare function socketTarget(origin: URL, path: '/stream' | '/control', token?: string): {
|
|
107
|
+
/** Returns the WebSocket URL and subprotocols for `/stream`, `/stream?view=1`, or `/control` on an engine origin. */
|
|
108
|
+
export declare function socketTarget(origin: URL, path: '/stream' | '/stream?view=1' | '/control', token?: string): {
|
|
109
109
|
url: URL;
|
|
110
110
|
protocols: string[];
|
|
111
111
|
};
|
package/dist/sdk/index.d.ts
CHANGED
|
@@ -3,12 +3,13 @@ export { RelayError, ERROR_REASONS } from '../protocol/index.js';
|
|
|
3
3
|
export type { ErrorClass, ErrorReason, ErrorOptions, NextCommand } from '../protocol/index.js';
|
|
4
4
|
export type { InputEvent };
|
|
5
5
|
export type Input = InputEvent;
|
|
6
|
-
/** Connection settings. `url` is the engine origin (default `http://127.0.0.1:8080`), `token` is the 64-character session token that remote hosts require, and `timeout` is in milliseconds (default 10000). */
|
|
6
|
+
/** Connection settings. `url` is the engine origin (default `http://127.0.0.1:8080`), `token` is the 64-character session token that remote hosts require, and `timeout` is in milliseconds (default 10000). `ca` trusts a CA bundle and still checks the URL host name; `certificate` pins one exact server certificate and skips the host name check. */
|
|
7
7
|
export interface ClientOptions {
|
|
8
8
|
url?: string;
|
|
9
9
|
token?: string;
|
|
10
10
|
timeout?: number;
|
|
11
11
|
ca?: string;
|
|
12
|
+
certificate?: string;
|
|
12
13
|
connect?: string;
|
|
13
14
|
signal?: AbortSignal;
|
|
14
15
|
}
|
package/dist/sdk/index.js
CHANGED
|
@@ -1,11 +1,18 @@
|
|
|
1
1
|
import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
|
|
2
2
|
|
|
3
3
|
// src/sdk/index.ts
|
|
4
|
-
import { readFileSync } from "node:fs";
|
|
5
4
|
import { writeFile } from "node:fs/promises";
|
|
6
5
|
import { request as httpRequest } from "node:http";
|
|
7
6
|
import { request as httpsRequest } from "node:https";
|
|
8
7
|
|
|
8
|
+
// src/sdk/transport.ts
|
|
9
|
+
import { X509Certificate } from "node:crypto";
|
|
10
|
+
import { readFileSync } from "node:fs";
|
|
11
|
+
import { Agent as HttpAgent } from "node:http";
|
|
12
|
+
import { Agent as HttpsAgent } from "node:https";
|
|
13
|
+
import { isIP } from "node:net";
|
|
14
|
+
import { checkServerIdentity } from "node:tls";
|
|
15
|
+
|
|
9
16
|
// src/protocol/errors.ts
|
|
10
17
|
var ERROR_REASONS = {
|
|
11
18
|
invalid_input: { class: "usage", code: "INVALID_ARGUMENT", exitCode: 2 },
|
|
@@ -367,9 +374,123 @@ function baseUrl(url, token) {
|
|
|
367
374
|
return parsed;
|
|
368
375
|
}
|
|
369
376
|
|
|
377
|
+
// src/sdk/transport.ts
|
|
378
|
+
var PEM_CERTIFICATE = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/;
|
|
379
|
+
function readCertificates(path) {
|
|
380
|
+
try {
|
|
381
|
+
return readFileSync(path);
|
|
382
|
+
} catch (error) {
|
|
383
|
+
throw new RelayError("io_error", `Cannot read certificate ${path}: ${error instanceof Error ? error.message : String(error)}`);
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
function leafCertificate(pem, path) {
|
|
387
|
+
const block = PEM_CERTIFICATE.exec(pem.toString())?.[0];
|
|
388
|
+
if (!block) throw new RelayError("io_error", `Cannot read certificate ${path}: the file contains no certificate`);
|
|
389
|
+
try {
|
|
390
|
+
const certificate = new X509Certificate(block);
|
|
391
|
+
return {
|
|
392
|
+
der: certificate.raw,
|
|
393
|
+
validFrom: Date.parse(certificate.validFrom),
|
|
394
|
+
validTo: Date.parse(certificate.validTo)
|
|
395
|
+
};
|
|
396
|
+
} catch (error) {
|
|
397
|
+
throw new RelayError("io_error", `Cannot read certificate ${path}: ${error instanceof Error ? error.message : String(error)}`);
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
function trust(target2) {
|
|
401
|
+
if (target2.certificate) {
|
|
402
|
+
return { kind: "certificate", certificate: leafCertificate(readCertificates(target2.certificate), target2.certificate) };
|
|
403
|
+
}
|
|
404
|
+
if (target2.ca) return { kind: "authority", bundle: readCertificates(target2.ca) };
|
|
405
|
+
return { kind: "system" };
|
|
406
|
+
}
|
|
407
|
+
function verifyPin(pin, peer) {
|
|
408
|
+
if (!peer.raw || !peer.raw.equals(pin.der)) return new Error("The server certificate does not match the pinned certificate.");
|
|
409
|
+
const now = Date.now();
|
|
410
|
+
if (!Number.isFinite(pin.validFrom) || !Number.isFinite(pin.validTo) || now < pin.validFrom || now > pin.validTo) {
|
|
411
|
+
return new Error("The pinned certificate is not valid.");
|
|
412
|
+
}
|
|
413
|
+
return void 0;
|
|
414
|
+
}
|
|
415
|
+
var PinnedAgent = class extends HttpsAgent {
|
|
416
|
+
constructor(pin, options, timeout, signal) {
|
|
417
|
+
super(options);
|
|
418
|
+
this.timeout = timeout;
|
|
419
|
+
this.signal = signal;
|
|
420
|
+
this.pin = pin;
|
|
421
|
+
}
|
|
422
|
+
timeout;
|
|
423
|
+
signal;
|
|
424
|
+
pin;
|
|
425
|
+
createConnection(options, callback) {
|
|
426
|
+
const socket = super.createConnection({ ...options, rejectUnauthorized: false });
|
|
427
|
+
if (!socket || !callback) return socket;
|
|
428
|
+
let state = "handshaking";
|
|
429
|
+
const finish = (error) => {
|
|
430
|
+
if (state !== "handshaking") return;
|
|
431
|
+
state = error ? "failed" : "verified";
|
|
432
|
+
clearTimeout(timer);
|
|
433
|
+
socket.removeListener("error", fail);
|
|
434
|
+
socket.removeListener("close", close);
|
|
435
|
+
socket.removeListener("secureConnect", verify);
|
|
436
|
+
this.signal?.removeEventListener("abort", abort);
|
|
437
|
+
if (error) socket.destroy();
|
|
438
|
+
callback(error, socket);
|
|
439
|
+
};
|
|
440
|
+
const fail = (error) => finish(error);
|
|
441
|
+
const close = () => finish(new RelayError("unreachable", "The connection was closed."));
|
|
442
|
+
const abort = () => finish(new RelayError("canceled", "Request canceled."));
|
|
443
|
+
const verify = () => finish(verifyPin(this.pin, socket.getPeerCertificate()) ?? null);
|
|
444
|
+
const timer = setTimeout(() => finish(new RelayError("timeout", "The request timed out.")), this.timeout);
|
|
445
|
+
socket.once("error", fail);
|
|
446
|
+
socket.once("close", close);
|
|
447
|
+
socket.once("secureConnect", verify);
|
|
448
|
+
this.signal?.addEventListener("abort", abort, { once: true });
|
|
449
|
+
if (this.signal?.aborted) abort();
|
|
450
|
+
return void 0;
|
|
451
|
+
}
|
|
452
|
+
};
|
|
453
|
+
function route(target2) {
|
|
454
|
+
const identity = target2.url.hostname.replace(/^\[|\]$/g, "");
|
|
455
|
+
return { dial: target2.connect ?? identity, identity, ...isIP(identity) ? {} : { servername: identity } };
|
|
456
|
+
}
|
|
457
|
+
function httpsAgent(where, trust2, timeout, signal) {
|
|
458
|
+
const servername = where.servername ? { servername: where.servername } : {};
|
|
459
|
+
if (trust2.kind === "certificate") {
|
|
460
|
+
return new PinnedAgent(trust2.certificate, { keepAlive: true, rejectUnauthorized: false, ...servername }, timeout, signal);
|
|
461
|
+
}
|
|
462
|
+
const verify = (_dialed, certificate) => checkServerIdentity(where.identity, certificate);
|
|
463
|
+
return new HttpsAgent({
|
|
464
|
+
keepAlive: true,
|
|
465
|
+
...servername,
|
|
466
|
+
checkServerIdentity: verify,
|
|
467
|
+
...trust2.kind === "authority" ? { ca: trust2.bundle } : {}
|
|
468
|
+
});
|
|
469
|
+
}
|
|
470
|
+
function plan(target2) {
|
|
471
|
+
if (!target2.ca && !target2.certificate && !target2.connect) return { kind: "fetch" };
|
|
472
|
+
const where = route(target2);
|
|
473
|
+
if (target2.url.protocol !== "https:") return { kind: "node", dial: where.dial, agent: new HttpAgent({ keepAlive: true }) };
|
|
474
|
+
return { kind: "node", dial: where.dial, agent: httpsAgent(where, trust(target2), target2.timeout, target2.signal) };
|
|
475
|
+
}
|
|
476
|
+
|
|
370
477
|
// src/sdk/index.ts
|
|
371
|
-
function target({ url = "http://127.0.0.1:8080", timeout = 1e4, token, ca, connect: connect2, signal }) {
|
|
372
|
-
|
|
478
|
+
function target({ url = "http://127.0.0.1:8080", timeout = 1e4, token, ca, certificate, connect: connect2, signal }) {
|
|
479
|
+
if (ca && certificate) throw new RelayError("invalid_option", "Pass ca or certificate, not both.");
|
|
480
|
+
return {
|
|
481
|
+
base: baseUrl(url, token),
|
|
482
|
+
timeout: integer(timeout, 1, 2147483647, "timeout"),
|
|
483
|
+
token,
|
|
484
|
+
ca,
|
|
485
|
+
certificate,
|
|
486
|
+
connect: connect2,
|
|
487
|
+
signal,
|
|
488
|
+
transport: void 0
|
|
489
|
+
};
|
|
490
|
+
}
|
|
491
|
+
function transportPlan(server) {
|
|
492
|
+
server.transport ??= plan({ url: server.base, ca: server.ca, certificate: server.certificate, connect: server.connect, timeout: server.timeout, signal: server.signal });
|
|
493
|
+
return server.transport;
|
|
373
494
|
}
|
|
374
495
|
function headers(server, body) {
|
|
375
496
|
const result = server.token ? { Authorization: `Bearer ${server.token}` } : {};
|
|
@@ -384,34 +505,22 @@ function decode(data, binary) {
|
|
|
384
505
|
throw new RelayError("protocol_error", "Invalid JSON response");
|
|
385
506
|
}
|
|
386
507
|
}
|
|
387
|
-
function nodeRequest(server, path, binary, body) {
|
|
508
|
+
function nodeRequest(server, where, path, binary, body) {
|
|
388
509
|
const base = server.base;
|
|
389
|
-
let ca;
|
|
390
|
-
if (server.ca) {
|
|
391
|
-
try {
|
|
392
|
-
ca = readFileSync(server.ca);
|
|
393
|
-
} catch (error) {
|
|
394
|
-
return Promise.reject(new RelayError("io_error", `Cannot read certificate ${server.ca}: ${error instanceof Error ? error.message : String(error)}`));
|
|
395
|
-
}
|
|
396
|
-
}
|
|
397
|
-
const hostname = server.connect ?? base.hostname.replace(/^\[|\]$/g, "");
|
|
398
510
|
const requestHeaders = headers(server, body);
|
|
399
511
|
if (body !== void 0) requestHeaders["Content-Length"] = String(body.length);
|
|
400
512
|
if (server.connect) requestHeaders.Host = base.host;
|
|
401
513
|
const options = {
|
|
402
514
|
protocol: base.protocol,
|
|
403
|
-
hostname,
|
|
515
|
+
hostname: where.dial,
|
|
404
516
|
port: Number(base.port || (base.protocol === "https:" ? 443 : 80)),
|
|
405
517
|
path: `${base.pathname === "/" ? "" : base.pathname}${path}`,
|
|
406
518
|
method: body === void 0 ? "GET" : "POST",
|
|
407
519
|
headers: requestHeaders,
|
|
408
520
|
timeout: server.timeout,
|
|
409
|
-
signal: server.signal
|
|
521
|
+
signal: server.signal,
|
|
522
|
+
agent: where.agent
|
|
410
523
|
};
|
|
411
|
-
if (ca) {
|
|
412
|
-
options.ca = ca;
|
|
413
|
-
options.checkServerIdentity = () => void 0;
|
|
414
|
-
}
|
|
415
524
|
return new Promise((resolve, reject) => {
|
|
416
525
|
const transport = base.protocol === "https:" ? httpsRequest : httpRequest;
|
|
417
526
|
const sent = transport(options, (response) => {
|
|
@@ -460,7 +569,8 @@ function nodeRequest(server, path, binary, body) {
|
|
|
460
569
|
}
|
|
461
570
|
async function request(server, path, binary = false, body) {
|
|
462
571
|
if (server.signal?.aborted) throw new RelayError("canceled", "Request canceled.");
|
|
463
|
-
|
|
572
|
+
const transport = transportPlan(server);
|
|
573
|
+
if (transport.kind === "node") return nodeRequest(server, transport, path, binary, body);
|
|
464
574
|
const controller = new AbortController();
|
|
465
575
|
let timer;
|
|
466
576
|
const deadline = new Promise((_, reject) => {
|
|
@@ -613,7 +723,7 @@ function createClient(options = {}) {
|
|
|
613
723
|
}
|
|
614
724
|
async function connect(options = {}) {
|
|
615
725
|
const server = target(options);
|
|
616
|
-
if (server.ca || server.connect) throw new RelayError("invalid_option", "Control connections do not support ca or connect options.");
|
|
726
|
+
if (server.ca || server.certificate || server.connect) throw new RelayError("invalid_option", "Control connections do not support ca, certificate, or connect options.");
|
|
617
727
|
if (server.signal?.aborted) throw new RelayError("canceled", "Control connection canceled.");
|
|
618
728
|
if (typeof WebSocket === "undefined") throw new RelayError("unsupported_platform", "Control sessions require Node 22 or newer");
|
|
619
729
|
const { url, protocols } = socketTarget(server.base, "/control", server.token);
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { Agent as HttpAgent } from 'node:http';
|
|
2
|
+
import { Agent as HttpsAgent } from 'node:https';
|
|
3
|
+
interface TransportTarget {
|
|
4
|
+
url: URL;
|
|
5
|
+
timeout: number;
|
|
6
|
+
signal?: AbortSignal;
|
|
7
|
+
ca?: string;
|
|
8
|
+
certificate?: string;
|
|
9
|
+
connect?: string;
|
|
10
|
+
}
|
|
11
|
+
export type Plan = {
|
|
12
|
+
kind: 'fetch';
|
|
13
|
+
} | {
|
|
14
|
+
kind: 'node';
|
|
15
|
+
dial: string;
|
|
16
|
+
agent: HttpAgent | HttpsAgent;
|
|
17
|
+
};
|
|
18
|
+
/** Chooses the transport and prepares its TLS settings. A CA file never turns off host name checking. */
|
|
19
|
+
export declare function plan(target: TransportTarget): Plan;
|
|
20
|
+
export {};
|
package/dist/viewer/index.html
CHANGED
|
@@ -58,7 +58,7 @@ button:focus-visible,input:focus-visible{outline:2px solid #3b82f6;outline-offse
|
|
|
58
58
|
<button type="button" data-action="scale" aria-expanded="false" aria-controls="scale-panel" aria-label="Scaling" title="Scaling"><svg viewBox="0 0 24 24"><path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/></svg></button>
|
|
59
59
|
<button type="button" data-action="keys" aria-expanded="false" aria-controls="keys-panel" aria-label="Send keys" title="Send keys"><svg viewBox="0 0 24 24"><rect x="2" y="6" width="20" height="12" rx="2"/><path d="M6 10h.01M10 10h.01M14 10h.01M18 10h.01M7 14h10"/></svg></button>
|
|
60
60
|
<button type="button" data-action="screenshot" aria-label="Save screenshot" title="Save screenshot"><svg viewBox="0 0 24 24"><path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3z"/><circle cx="12" cy="13" r="3"/></svg></button>
|
|
61
|
-
<button type="button" data-action="
|
|
61
|
+
<button type="button" data-action="control" aria-pressed="false" aria-label="Take control" title="Take control"><svg viewBox="0 0 24 24"><path d="M8 13V6a1.5 1.5 0 0 1 3 0v6M11 12V4.5a1.5 1.5 0 0 1 3 0V12M14 12V6a1.5 1.5 0 0 1 3 0v8a6 6 0 0 1-6 6h-1.5A5.5 5.5 0 0 1 4 14.5V12"/></svg></button>
|
|
62
62
|
<button type="button" data-action="stats" aria-pressed="false" aria-label="Stream statistics" title="Stream statistics"><svg viewBox="0 0 24 24"><path d="M22 12h-4l-3 9L9 3l-3 9H2"/></svg></button>
|
|
63
63
|
<button type="button" data-action="connection" aria-expanded="false" aria-controls="connection-panel" aria-label="Connection" title="Connection"><svg viewBox="0 0 24 24"><circle cx="7.5" cy="15.5" r="5.5"/><path d="m21 2-9.6 9.6M15.5 7.5l3 3L22 7l-3-3"/></svg></button>
|
|
64
64
|
</div>
|
package/dist/viewer/viewer.js
CHANGED
|
@@ -27,6 +27,7 @@ var relayViewer = (() => {
|
|
|
27
27
|
connect: () => connect,
|
|
28
28
|
reset: () => reset,
|
|
29
29
|
setScale: () => setScale,
|
|
30
|
+
setViewOnly: () => setViewOnly,
|
|
30
31
|
socket: () => socket,
|
|
31
32
|
toggleMeta: () => toggleMeta,
|
|
32
33
|
toggleSharp: () => toggleSharp,
|
|
@@ -349,7 +350,7 @@ var relayViewer = (() => {
|
|
|
349
350
|
var modifiers = 0;
|
|
350
351
|
var x = 0;
|
|
351
352
|
var y = 0;
|
|
352
|
-
var viewOnly =
|
|
353
|
+
var viewOnly = true;
|
|
353
354
|
var capsLock = false;
|
|
354
355
|
var metaAsCtrl = stored("relay.metaCtrl") === null ? macos() : stored("relay.metaCtrl") === "1";
|
|
355
356
|
var pending = /* @__PURE__ */ new Map();
|
|
@@ -523,7 +524,7 @@ var relayViewer = (() => {
|
|
|
523
524
|
ready = true;
|
|
524
525
|
if (!wasReady) renderCursor();
|
|
525
526
|
retry = 0;
|
|
526
|
-
setStatus("Live \xB7
|
|
527
|
+
setStatus(viewOnly ? "Live \xB7 view only" : "Live \xB7 you have control");
|
|
527
528
|
drawnThisFrame = true;
|
|
528
529
|
return ackFrame(item);
|
|
529
530
|
}
|
|
@@ -594,7 +595,7 @@ var relayViewer = (() => {
|
|
|
594
595
|
setStatus("WebCodecs unavailable in this browser");
|
|
595
596
|
return;
|
|
596
597
|
}
|
|
597
|
-
const target = socketTarget(new URL(`${location.protocol}//${location.host}`), "/stream", accessToken);
|
|
598
|
+
const target = socketTarget(new URL(`${location.protocol}//${location.host}`), viewOnly ? "/stream?view=1" : "/stream", accessToken);
|
|
598
599
|
socket = new WebSocket(target.url, target.protocols);
|
|
599
600
|
transportBroken = false;
|
|
600
601
|
loadCapabilities();
|
|
@@ -773,14 +774,29 @@ var relayViewer = (() => {
|
|
|
773
774
|
if (buttons) release();
|
|
774
775
|
});
|
|
775
776
|
canvas.addEventListener("contextmenu", (e) => e.preventDefault());
|
|
777
|
+
var WHEEL_LINES_PER_NOTCH = 3;
|
|
778
|
+
var WHEEL_PIXELS_PER_NOTCH = 100;
|
|
779
|
+
var wheelRemainder = [0, 0];
|
|
780
|
+
function wheelNotches(e, axis) {
|
|
781
|
+
const legacy = axis ? e.wheelDeltaX : e.wheelDeltaY;
|
|
782
|
+
if (typeof legacy === "number" && legacy !== 0) return -legacy / 120;
|
|
783
|
+
const delta = axis ? e.deltaX : e.deltaY;
|
|
784
|
+
if (e.deltaMode === 1) return delta / WHEEL_LINES_PER_NOTCH;
|
|
785
|
+
if (e.deltaMode === 2) return delta;
|
|
786
|
+
return delta / WHEEL_PIXELS_PER_NOTCH;
|
|
787
|
+
}
|
|
776
788
|
canvas.addEventListener("wheel", (e) => {
|
|
777
789
|
e.preventDefault();
|
|
778
790
|
position(e);
|
|
779
|
-
for (const
|
|
780
|
-
if (
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
791
|
+
for (const axis of [0, 1]) {
|
|
792
|
+
if (!(axis ? e.deltaX : e.deltaY)) continue;
|
|
793
|
+
const notches = wheelNotches(e, axis);
|
|
794
|
+
if (Math.sign(notches) !== Math.sign(wheelRemainder[axis])) wheelRemainder[axis] = 0;
|
|
795
|
+
wheelRemainder[axis] += notches;
|
|
796
|
+
const whole = Math.trunc(wheelRemainder[axis]);
|
|
797
|
+
if (!whole) continue;
|
|
798
|
+
wheelRemainder[axis] -= whole;
|
|
799
|
+
sendInput({ type: "wheel", axis: axis ? "horizontal" : "vertical", delta: clamp(whole * 120, -1200, 1200), x, y });
|
|
784
800
|
}
|
|
785
801
|
}, { passive: false });
|
|
786
802
|
canvas.addEventListener("blur", release);
|
|
@@ -953,6 +969,20 @@ var relayViewer = (() => {
|
|
|
953
969
|
toggle.setAttribute("aria-expanded", String(open));
|
|
954
970
|
if (!open) showPanel(null);
|
|
955
971
|
}
|
|
972
|
+
function applyControl() {
|
|
973
|
+
const button = actions.querySelector('[data-action="control"]');
|
|
974
|
+
const label = viewOnly ? "Take control" : "Release control";
|
|
975
|
+
button.setAttribute("aria-pressed", String(!viewOnly));
|
|
976
|
+
button.setAttribute("aria-label", label);
|
|
977
|
+
button.setAttribute("title", label);
|
|
978
|
+
}
|
|
979
|
+
function setViewOnly(next) {
|
|
980
|
+
if (viewOnly === next) return;
|
|
981
|
+
release();
|
|
982
|
+
viewOnly = next;
|
|
983
|
+
applyControl();
|
|
984
|
+
connect();
|
|
985
|
+
}
|
|
956
986
|
function syncStatus() {
|
|
957
987
|
const text = status.textContent ?? "";
|
|
958
988
|
dot.className = "dot" + (text.startsWith("Live") ? " live" : /^(Connecting|Waiting|Paused)/.test(text) ? "" : " error");
|
|
@@ -977,11 +1007,7 @@ var relayViewer = (() => {
|
|
|
977
1007
|
link.click();
|
|
978
1008
|
setTimeout(() => URL.revokeObjectURL(link.href), 1e3);
|
|
979
1009
|
}, "image/png"),
|
|
980
|
-
|
|
981
|
-
release();
|
|
982
|
-
viewOnly = !viewOnly;
|
|
983
|
-
button.setAttribute("aria-pressed", String(viewOnly));
|
|
984
|
-
},
|
|
1010
|
+
control: () => setViewOnly(!viewOnly),
|
|
985
1011
|
stats: (button) => {
|
|
986
1012
|
const panel = document.querySelector("#stats");
|
|
987
1013
|
panel.hidden = !panel.hidden;
|
|
@@ -1046,6 +1072,7 @@ var relayViewer = (() => {
|
|
|
1046
1072
|
if (!document.hidden) startHud();
|
|
1047
1073
|
applyScale();
|
|
1048
1074
|
applyMeta();
|
|
1075
|
+
applyControl();
|
|
1049
1076
|
watchDpr();
|
|
1050
1077
|
connect();
|
|
1051
1078
|
return __toCommonJS(main_exports);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "screen-relay",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Stream a desktop to a browser and control it from a CLI and a Node SDK.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"@types/node": "26.6.6",
|
|
43
|
-
"agent-browser": "0.
|
|
43
|
+
"agent-browser": "0.42.0",
|
|
44
44
|
"esbuild": "0.28.2",
|
|
45
45
|
"typescript": "7.0.2"
|
|
46
46
|
},
|
package/skills/core/SKILL.md
CHANGED
|
@@ -6,7 +6,7 @@ allowed-tools: Bash(screen-relay:*)
|
|
|
6
6
|
|
|
7
7
|
# screen-relay core workflow
|
|
8
8
|
|
|
9
|
-
screen-relay streams a desktop to a browser viewer and gives you CLI control. Run it on the Linux or
|
|
9
|
+
screen-relay streams a desktop to a browser viewer and gives you CLI control. Run it on the Linux, macOS or Windows machine that shows the desktop. Node 22 or newer is required.
|
|
10
10
|
|
|
11
11
|
## Set up
|
|
12
12
|
|
|
@@ -23,12 +23,14 @@ screen-relay up -d
|
|
|
23
23
|
- After an upgrade, the next `up` rebuilds the engine. That needs no `sudo`.
|
|
24
24
|
- Linux: automatic setup supports Debian, Ubuntu, Fedora, Arch Linux and Alpine on x64 and arm64. It needs root or passwordless `sudo`. On another distribution, install the build tools and libraries yourself, then run `screen-relay install`.
|
|
25
25
|
- macOS: setup needs Homebrew and the Xcode Command Line Tools. See [macOS](references/macos.md).
|
|
26
|
+
- Windows: setup needs Windows 10 or later on x64. It installs MSYS2 with winget when MSYS2 is missing, and it refuses an installation that another account owns or can write to. For an MSYS2 that the user installed, the error prints an `icacls` command that removes the rules it inherits from `C:\`. Without winget, install MSYS2 from https://www.msys2.org first. Run the commands in a terminal on the signed-in user's desktop. `up` over SSH or from a service session fails with `No display is attached to this session` or `Desktop Duplication is unavailable`. See [Windows](https://screen-relay.dev/docs/windows).
|
|
26
27
|
|
|
27
28
|
## Pick a backend
|
|
28
29
|
|
|
29
30
|
| Platform | Backend | Start |
|
|
30
31
|
| --- | --- | --- |
|
|
31
32
|
| macOS | `macos`: streams the logged-in user's display. Starts no virtual display or desktop. | `screen-relay up -d` |
|
|
33
|
+
| Windows | `windows`: streams the signed-in user's desktop. Starts no virtual display or desktop. | `screen-relay up -d` |
|
|
32
34
|
| Linux | `x11`: a virtual display with XFCE. | `screen-relay up -d` |
|
|
33
35
|
| Linux | `wayland`: a headless sway desktop with foot. | `screen-relay up -d --backend wayland` |
|
|
34
36
|
| Linux | Attach to a compositor you already run. | `screen-relay up -d --backend wayland --display "$WAYLAND_DISPLAY"` |
|
|
@@ -41,7 +43,7 @@ screen-relay up -d
|
|
|
41
43
|
|
|
42
44
|
## Where commands run
|
|
43
45
|
|
|
44
|
-
- VM commands (`install`, `up`, `down`, `logs`, `run`, `doctor`) run on the Linux or
|
|
46
|
+
- VM commands (`install`, `up`, `down`, `logs`, `run`, `doctor`) run on the Linux, macOS or Windows machine that shows the desktop. `up`, `down` and `run` fail with `unsupported_platform` elsewhere.
|
|
45
47
|
- Client commands (`status`, `screenshot`, `click`, `move`, `scroll`, `key`, `type`, `input`) reach the engine through the local session, or from another machine with `--url` and a token file (`--token-file` or `SCREEN_RELAY_TOKEN_FILE`). See [Client target](references/cli.md#client-target).
|
|
46
48
|
- `skills` and `help` work anywhere and never contact an engine.
|
|
47
49
|
- A script can use the Node SDK instead of the CLI. See [Node SDK](references/sdk.md).
|
|
@@ -138,14 +140,14 @@ Exit codes: [CLI exit codes](references/cli.md#exit-codes).
|
|
|
138
140
|
| `missing_command` | `run` was given no app (exit 2). | `screen-relay run -- APP`. |
|
|
139
141
|
| `spawn_failed` | `run` could not start the app. | Check the app name and `screen-relay logs apps`. |
|
|
140
142
|
| `unsupported_input` | The backend cannot produce a character or apply the input. | Use `screen-relay type` for layout-neutral text. |
|
|
141
|
-
| `unsupported_platform` | `up`, `down` or `run` ran
|
|
143
|
+
| `unsupported_platform` | `up`, `down` or `run` ran on a platform other than Linux, macOS or Windows. | Run host commands on the Linux, macOS or Windows machine that shows the desktop. |
|
|
142
144
|
| `invalid_config` | A config key or value is invalid. The message names the file and key. | Fix the file and start again. |
|
|
143
145
|
| `invalid_input`, `invalid_option`, `unknown_command` | Usage error (exit 2). | Read the `next` command, usually `screen-relay help <command>`. |
|
|
144
146
|
| `internal` | A bug in screen-relay. | Report it with the command you ran. |
|
|
145
147
|
|
|
146
148
|
## One controller
|
|
147
149
|
|
|
148
|
-
Only one controller sends input at a time: a browser viewer, an SDK control session, or your CLI. A second controller gets `busy` with the message `Another controller holds control of the desktop.`, and nothing is applied. Screenshots, `status` and `capabilities` keep working. Do not retry in a loop. Wait for the other controller to close, then retry once.
|
|
150
|
+
Only one controller sends input at a time: a browser viewer that took control, an SDK control session, or your CLI. A viewer opens view-only, so it can watch while your CLI sends input. A second controller gets `busy` with the message `Another controller holds control of the desktop.`, and nothing is applied. Screenshots, `status` and `capabilities` keep working. Do not retry in a loop. Wait for the other controller to release control or close, then retry once.
|
|
149
151
|
|
|
150
152
|
## Config
|
|
151
153
|
|
|
@@ -166,4 +168,4 @@ Keys, defaults, file location and precedence: [config](references/config.md).
|
|
|
166
168
|
- `references/macos.md`: macOS install, permissions, display choice and limits.
|
|
167
169
|
- `references/troubleshooting.md`: symptoms and fixes.
|
|
168
170
|
- `screen-relay skills get vercel-sandbox`: run screen-relay in a Vercel Sandbox.
|
|
169
|
-
- https://relay.
|
|
171
|
+
- https://screen-relay.dev/docs: the published documentation.
|
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
# CLI reference
|
|
2
2
|
|
|
3
|
-
The published reference is at https://relay.
|
|
3
|
+
The published reference is at https://screen-relay.dev/docs/cli.
|
|
4
4
|
|
|
5
5
|
Run `screen-relay help` for root help, `screen-relay help <command>` for one command, and `screen-relay help --all --json` for every command's metadata. Help works offline.
|
|
6
6
|
|
|
7
7
|
## VM commands
|
|
8
8
|
|
|
9
|
-
Run these on the Linux or
|
|
9
|
+
Run these on the Linux, macOS or Windows machine that shows the desktop. `up`, `down` and `run` fail with `unsupported_platform` elsewhere.
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
|
-
screen-relay install [--backend x11|wayland|all|macos] [--desktop xfce|none|COMMAND]
|
|
12
|
+
screen-relay install [--backend x11|wayland|all|macos|windows] [--desktop xfce|none|COMMAND]
|
|
13
13
|
[--config FILE] [--yes]
|
|
14
14
|
screen-relay up [-d] [--name NAME] [--config FILE] [--port PORT] [--desktop xfce|none|COMMAND]
|
|
15
|
-
[--display DISPLAY] [--backend x11|wayland|macos] [--output NAME|DISPLAY_ID]
|
|
15
|
+
[--display DISPLAY] [--backend x11|wayland|macos|windows] [--output NAME|DISPLAY_ID]
|
|
16
16
|
[--public HTTPS_URL] [--tls-cert FILE --tls-key FILE]
|
|
17
17
|
[--bind ADDRESS] [--timeout SECONDS] [--yes]
|
|
18
18
|
screen-relay down [--name NAME]
|
|
@@ -22,23 +22,23 @@ screen-relay doctor [--config FILE]
|
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
- `install` sets up the machine without starting a session. It installs the system packages for the backend and builds the engine. It is safe to repeat. When nothing is missing, it reports `unchanged`.
|
|
25
|
-
- `--backend`: `x11`, `wayland` or `all` on Linux, `macos` on macOS. The default is `x11` on Linux and `macos` on macOS. The value also comes from `SCREEN_RELAY_BACKEND` and the config `backend` key. Adding a backend keeps the ones already set up.
|
|
25
|
+
- `--backend`: `x11`, `wayland` or `all` on Linux, `macos` on macOS, `windows` on Windows (the only value there). The default is `x11` on Linux and `macos` on macOS. The value also comes from `SCREEN_RELAY_BACKEND` and the config `backend` key. Adding a backend keeps the ones already set up.
|
|
26
26
|
- `--desktop`: the same values as `up --desktop`. With `xfce` on x11, the XFCE packages are installed. With `none` or a command, they are skipped.
|
|
27
27
|
- `--config FILE`: read `backend` and `desktop` from this file.
|
|
28
28
|
- `--yes`, `-y`: install packages without asking. Required when there is no terminal.
|
|
29
29
|
- JSON outcome: `installed` or `unchanged`, with the backends and the engine path under `install`.
|
|
30
|
-
- `up` starts a display (Xvfb on X11, or sway with XWayland on Wayland) or attaches to an existing one. On macOS it attaches to the logged-in user's display and starts no desktop. It then starts the desktop when enabled and the engine, waits until both are ready, and supervises the session. `--timeout` defaults to 30 seconds.
|
|
30
|
+
- `up` starts a display (Xvfb on X11, or sway with XWayland on Wayland) or attaches to an existing one. On macOS it attaches to the logged-in user's display and starts no desktop. On Windows it attaches to the signed-in user's desktop and starts no virtual display or desktop. It then starts the desktop when enabled and the engine, waits until both are ready, and supervises the session. `--timeout` defaults to 30 seconds.
|
|
31
31
|
- Without `-d`, it runs in the foreground. The first Ctrl+C stops the session (exit 130). Piped, it prints only the viewer URL.
|
|
32
|
-
- `--display DISPLAY`: attach to an X display (`:0`) or a Wayland socket (`wayland-1`). It keeps the caller's environment. A Wayland socket needs `XDG_RUNTIME_DIR`. macOS rejects it with `invalid_input`.
|
|
33
|
-
- `--backend x11|wayland|macos`: on Linux, defaults to `x11` when the engine has it, else `wayland`. A `--display` without a colon, such as `wayland-1`, selects `wayland` on its own. On macOS the only backend is `macos`. `x11` and `wayland` fail there with `invalid_input`, and `macos` fails on Linux the same way.
|
|
34
|
-
- `--output NAME|DISPLAY_ID`: capture this Wayland output by name,
|
|
32
|
+
- `--display DISPLAY`: attach to an X display (`:0`) or a Wayland socket (`wayland-1`). It keeps the caller's environment. A Wayland socket needs `XDG_RUNTIME_DIR`. macOS rejects it with `invalid_input`. Windows does not support it.
|
|
33
|
+
- `--backend x11|wayland|macos|windows`: on Linux, defaults to `x11` when the engine has it, else `wayland`. A `--display` without a colon, such as `wayland-1`, selects `wayland` on its own. On macOS the only backend is `macos`, and on Windows it is `windows`. `x11` and `wayland` fail there with `invalid_input`, and `macos` fails on Linux the same way.
|
|
34
|
+
- `--output NAME|DISPLAY_ID`: capture this Wayland output by name, a macOS display by its CGDirectDisplayID, or a Windows display such as `'\\.\DISPLAY2'`. `up` fails on x11.
|
|
35
35
|
- `--yes`: when setup is needed, set it up without asking. Without a terminal, `up` never prompts and fails with `missing_input` unless `--yes` is given.
|
|
36
36
|
- `--public HTTPS_URL`: advertises an HTTPS origin. Expects a TLS proxy unless `--tls-cert` is set.
|
|
37
37
|
- Backend setup: [Wayland](wayland.md) and [macOS](macos.md).
|
|
38
|
-
- `down` stops the session and everything it started. It is safe to repeat. JSON outcome: `stopped` or `unchanged`.
|
|
38
|
+
- `down` stops the session and everything it started. On Windows, apps started with `run` keep running. It is safe to repeat. JSON outcome: `stopped` or `unchanged`.
|
|
39
39
|
- `logs` prints the last 200 lines of one component (`display`, `dbus`, `desktop`, `engine`, `apps`), or of every component log. `-f` follows; it cannot be combined with `--json`.
|
|
40
|
-
- `run` starts an app on the session desktop and returns its pid. The app shares the desktop's display, the available D-Bus session bus, runtime, config, cache and X authority settings, and it clears ambient capabilities. On Wayland it also sets `WAYLAND_DISPLAY`. On macOS it clears `DISPLAY`, `WAYLAND_DISPLAY` and `XAUTHORITY`. `--restart` restarts the app until the session stops. App output goes to `screen-relay logs apps`.
|
|
41
|
-
- `doctor` checks the machine it runs on and prints a fix command for each problem. On macOS it checks `platform` (macOS 12.3 or later), `engine` and `permissions`. Off Linux and
|
|
40
|
+
- `run` starts an app on the session desktop and returns its pid. The app shares the desktop's display, the available D-Bus session bus, runtime, config, cache and X authority settings, and it clears ambient capabilities. On Wayland it also sets `WAYLAND_DISPLAY`. On macOS it clears `DISPLAY`, `WAYLAND_DISPLAY` and `XAUTHORITY`. `--restart` restarts the app until the session stops. Windows does not support `--restart`. App output goes to `screen-relay logs apps`.
|
|
41
|
+
- `doctor` checks the machine it runs on and prints a fix command for each problem. On macOS it checks `platform` (macOS 12.3 or later), `engine` and `permissions`. On Windows it checks the Windows version, MSYS2, the engine and whether it runs in a desktop session; the MSYS2 check fails when another account owns the installation or can write to it. Off Linux, macOS and Windows, the platform check fails. The backend comes from `SCREEN_RELAY_BACKEND`, then the config file's `backend` key (from `--config FILE` or the default config), then the engine's default. Use `SCREEN_RELAY_BACKEND=wayland screen-relay doctor` for a Wayland setup.
|
|
42
42
|
|
|
43
43
|
## Client commands
|
|
44
44
|
|
|
@@ -59,7 +59,7 @@ screen-relay input --stdin
|
|
|
59
59
|
|
|
60
60
|
- `status` with no URL reads the local session and exits 0 for any existing session. With `--url` (or `SCREEN_RELAY_URL`), it queries a remote engine. A missing session is `not_running`, exit 1.
|
|
61
61
|
- `status --json` puts the session under `session`. These fields name the display server:
|
|
62
|
-
- `backend`: `x11`, `wayland` or `
|
|
62
|
+
- `backend`: `x11`, `wayland`, `macos` or `windows`.
|
|
63
63
|
- `waylandDisplay`: the Wayland socket, such as `wayland-1`. Wayland only.
|
|
64
64
|
- `runtimeDir`: the runtime directory of the sway session. Wayland only, when screen-relay starts sway. `down` deletes it.
|
|
65
65
|
- `screenshot` writes `screen.png` by default. `-` writes PNG bytes to stdout (not with `--json`).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Configuration
|
|
2
2
|
|
|
3
|
-
The published reference is at https://relay.
|
|
3
|
+
The published reference is at https://screen-relay.dev/docs/configuration.
|
|
4
4
|
|
|
5
5
|
Precedence, highest first:
|
|
6
6
|
|
|
@@ -25,8 +25,8 @@ Precedence, highest first:
|
|
|
25
25
|
| `server.tls_cert` | none | Certificate file; `server.tls_key` must be set too | `SCREEN_RELAY_TLS_CERT` |
|
|
26
26
|
| `server.tls_key` | none | Private key file | `SCREEN_RELAY_TLS_KEY` |
|
|
27
27
|
| `keyboard.layout` | `us` | Comma-separated XKB layout such as `fr,us` | `SCREEN_RELAY_KEYBOARD_LAYOUT` |
|
|
28
|
-
| `backend` | Linux: `x11` when the engine has it, else `wayland`. macOS: `macos` | `x11`, `wayland` or `
|
|
29
|
-
| `desktop` | `xfce` (x11) or `foot` (wayland) | `xfce`, `none`, or a desktop command; defaults to `none` with `--display`;
|
|
28
|
+
| `backend` | Linux: `x11` when the engine has it, else `wayland`. macOS: `macos`. Windows: `windows` | `x11`, `wayland`, `macos` or `windows`; `--backend` overrides it | `SCREEN_RELAY_BACKEND` |
|
|
29
|
+
| `desktop` | `xfce` (x11) or `foot` (wayland) | `xfce`, `none`, or a desktop command; defaults to `none` with `--display`; ignored on macOS and Windows, which start no desktop | `SCREEN_RELAY_DESKTOP` |
|
|
30
30
|
|
|
31
31
|
Example:
|
|
32
32
|
|
|
@@ -49,7 +49,7 @@ input(event): Promise<void> // one raw SDK input event
|
|
|
49
49
|
close(): void
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
Only one controller sends input at a time. See [One controller](../SKILL.md#one-controller).
|
|
52
|
+
Only one controller sends input at a time. A control session needs the viewer closed, because the engine serves one stream or control connection at a time. See [One controller](../SKILL.md#one-controller).
|
|
53
53
|
|
|
54
54
|
## Errors
|
|
55
55
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Troubleshooting
|
|
2
2
|
|
|
3
|
-
The published guide is at https://relay.
|
|
3
|
+
The published guide is at https://screen-relay.dev/docs/troubleshooting.
|
|
4
4
|
|
|
5
5
|
Start with `screen-relay doctor`. For each reason, such as `busy` or `unauthorized`, see [Reasons and recovery](../SKILL.md#reasons-and-recovery). This page covers symptoms that have no reason code.
|
|
6
6
|
|
|
@@ -11,7 +11,7 @@ Start with `screen-relay doctor`. For each reason, such as `busy` or `unauthoriz
|
|
|
11
11
|
| `unreachable` with `Connection refused.` | Nothing is listening on the address. | For a local session, run `screen-relay up -d`. Otherwise check the port. |
|
|
12
12
|
| `unreachable` with `The TLS certificate was rejected.` | The certificate is not trusted or names another host. | Use a trusted certificate for the public host, or pass the local session's certificate. |
|
|
13
13
|
| Engine log says `Cannot listen on 127.0.0.1:8080` | Another process owns the port. | `screen-relay up --port 8081`, or stop the old session. |
|
|
14
|
-
| Engine log names a missing Wayland protocol (`zwlr_screencopy_manager_v1`, `zwp_virtual_keyboard_manager_v1` or `zwlr_virtual_pointer_manager_v1`) | The compositor from `--display` lacks it. | Attach to a supported compositor. See [Linux](https://relay.
|
|
14
|
+
| Engine log names a missing Wayland protocol (`zwlr_screencopy_manager_v1`, `zwp_virtual_keyboard_manager_v1` or `zwlr_virtual_pointer_manager_v1`) | The compositor from `--display` lacks it. | Attach to a supported compositor. See [Linux](https://screen-relay.dev/docs/linux). |
|
|
15
15
|
| Engine log shows `Unsupported root size` | The attached output is outside 320x240 to 16384x16384, or has an odd side. | Create a headless output of a supported size and pass its name with `--output`. |
|
|
16
16
|
| `missing_input` saying `XDG_RUNTIME_DIR is required` | `--display` on wayland without `XDG_RUNTIME_DIR`. | Export the compositor's runtime directory. If it is `/run/user/$(id -u)`, run `export XDG_RUNTIME_DIR=/run/user/$(id -u)`. |
|
|
17
17
|
| `component_failed` or `timeout` for `display` with `--backend wayland` | sway did not start or did not report its displays. | `SCREEN_RELAY_BACKEND=wayland screen-relay doctor`, then `screen-relay logs display`. |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: screen-relay
|
|
3
|
-
description: Stream a desktop and control it with the screen-relay CLI (screenshot, click, type, key). Use when an agent needs to see and operate a GUI on a Linux VM, sandbox or container, or on a Mac.
|
|
3
|
+
description: Stream a desktop and control it with the screen-relay CLI (screenshot, click, type, key). Use when an agent needs to see and operate a GUI on a Linux VM, sandbox or container, or on a Mac or Windows PC.
|
|
4
4
|
hidden: true
|
|
5
5
|
---
|
|
6
6
|
|