screen-relay 0.0.0-stage → 0.1.0

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.
Files changed (88) hide show
  1. package/LICENSE +201 -0
  2. package/Makefile +165 -0
  3. package/README.md +113 -2
  4. package/THIRD-PARTY-NOTICES.md +75 -0
  5. package/dist/cli/client.d.ts +28 -0
  6. package/dist/cli/commands.d.ts +52 -0
  7. package/dist/cli/config.d.ts +32 -0
  8. package/dist/cli/format.d.ts +15 -0
  9. package/dist/cli/help.d.ts +5 -0
  10. package/dist/cli/host/common.d.ts +23 -0
  11. package/dist/cli/host/doctor.d.ts +2 -0
  12. package/dist/cli/host/packages.d.ts +13 -0
  13. package/dist/cli/host/session_commands.d.ts +8 -0
  14. package/dist/cli/host/setup.d.ts +22 -0
  15. package/dist/cli/host/state.d.ts +23 -0
  16. package/dist/cli/host/supervisor.d.ts +91 -0
  17. package/dist/cli/host/watcher.d.ts +4 -0
  18. package/dist/cli/main.d.ts +3 -0
  19. package/dist/cli/mode.d.ts +14 -0
  20. package/dist/cli/output.d.ts +24 -0
  21. package/dist/cli/parser.d.ts +6 -0
  22. package/dist/cli/relay.mjs +12247 -0
  23. package/dist/cli/skills.d.ts +21 -0
  24. package/dist/cli/theme.d.ts +14 -0
  25. package/dist/protocol/errors.d.ts +155 -0
  26. package/dist/protocol/index.d.ts +119 -0
  27. package/dist/protocol/index.js +418 -0
  28. package/dist/sdk/index.d.ts +77 -0
  29. package/dist/sdk/index.js +724 -0
  30. package/dist/viewer/index.html +96 -0
  31. package/dist/viewer/viewer.js +1052 -0
  32. package/package.json +50 -4
  33. package/packages.tsv +38 -0
  34. package/skills/core/SKILL.md +169 -0
  35. package/skills/core/references/cli.md +119 -0
  36. package/skills/core/references/config.md +48 -0
  37. package/skills/core/references/macos.md +50 -0
  38. package/skills/core/references/sdk.md +69 -0
  39. package/skills/core/references/troubleshooting.md +33 -0
  40. package/skills/core/references/wayland.md +47 -0
  41. package/skills/screen-relay/SKILL.md +24 -0
  42. package/skills/vercel-sandbox/SKILL.md +68 -0
  43. package/src/engine/backends/linux/keycodes.hpp +35 -0
  44. package/src/engine/backends/linux/wayland/capture.cpp +298 -0
  45. package/src/engine/backends/linux/wayland/input.cpp +559 -0
  46. package/src/engine/backends/linux/wayland/keymap.cpp +118 -0
  47. package/src/engine/backends/linux/wayland/keymap.hpp +54 -0
  48. package/src/engine/backends/linux/wayland/protocols/virtual-keyboard-unstable-v1.xml +112 -0
  49. package/src/engine/backends/linux/wayland/protocols/wlr-screencopy-unstable-v1.xml +234 -0
  50. package/src/engine/backends/linux/wayland/protocols/wlr-virtual-pointer-unstable-v1.xml +152 -0
  51. package/src/engine/backends/linux/wayland/wayland.cpp +166 -0
  52. package/src/engine/backends/linux/wayland/wayland.hpp +60 -0
  53. package/src/engine/backends/linux/x11/capture.cpp +206 -0
  54. package/src/engine/backends/linux/x11/input.cpp +266 -0
  55. package/src/engine/backends/macos/capture.mm +367 -0
  56. package/src/engine/backends/macos/display.hpp +20 -0
  57. package/src/engine/backends/macos/display.mm +84 -0
  58. package/src/engine/backends/macos/input.mm +287 -0
  59. package/src/engine/backends/macos/keys.hpp +34 -0
  60. package/src/engine/backends/windows/capture.cpp +393 -0
  61. package/src/engine/backends/windows/input.cpp +274 -0
  62. package/src/engine/backends/windows/output.cpp +65 -0
  63. package/src/engine/backends/windows/output.hpp +26 -0
  64. package/src/engine/core/capture-bucket.hpp +40 -0
  65. package/src/engine/core/capture-source.hpp +59 -0
  66. package/src/engine/core/capture.cpp +565 -0
  67. package/src/engine/core/capture.hpp +58 -0
  68. package/src/engine/core/color.cpp +176 -0
  69. package/src/engine/core/color.hpp +16 -0
  70. package/src/engine/core/cpu-budget.hpp +196 -0
  71. package/src/engine/core/flow.hpp +317 -0
  72. package/src/engine/core/input.cpp +98 -0
  73. package/src/engine/core/input.hpp +115 -0
  74. package/src/engine/core/wait.cpp +125 -0
  75. package/src/engine/core/wait.hpp +41 -0
  76. package/src/engine/server/backend.cpp +65 -0
  77. package/src/engine/server/backend.hpp +18 -0
  78. package/src/engine/server/config.cpp +257 -0
  79. package/src/engine/server/config.hpp +24 -0
  80. package/src/engine/server/main.cpp +82 -0
  81. package/src/engine/server/metrics.cpp +47 -0
  82. package/src/engine/server/metrics.hpp +10 -0
  83. package/src/engine/server/screenshot.cpp +108 -0
  84. package/src/engine/server/screenshot.hpp +31 -0
  85. package/src/engine/server/server.cpp +531 -0
  86. package/src/engine/server/server.hpp +88 -0
  87. package/src/engine/server/wire.cpp +65 -0
  88. package/src/engine/server/wire.hpp +27 -0
@@ -0,0 +1,32 @@
1
+ export declare const BACKENDS: readonly ['x11', 'wayland', 'macos'];
2
+ export declare const COMPOSITORS: readonly ['auto', 'on', 'off'];
3
+ export type ConfigSettings = {
4
+ display: {
5
+ resolution: string;
6
+ compositor: (typeof COMPOSITORS)[number];
7
+ };
8
+ stream: {
9
+ fps: number;
10
+ bitrate: {
11
+ min: number;
12
+ start: number;
13
+ max: number;
14
+ };
15
+ };
16
+ server: {
17
+ port: number;
18
+ bind: string;
19
+ public: string | null;
20
+ tls_cert: string | null;
21
+ tls_key: string | null;
22
+ };
23
+ keyboard: {
24
+ layout: string;
25
+ };
26
+ desktop: string;
27
+ backend?: string;
28
+ };
29
+ export declare function locate(path?: string): [string | null, boolean];
30
+ export declare function backendValue(value: unknown, path: string): (typeof BACKENDS)[number];
31
+ export declare function loadConfig(path?: string): [ConfigSettings, string | null, Set<string>];
32
+ export declare function applyTo(args: Record<string, unknown>, settings: ConfigSettings, present: Set<string>): void;
@@ -0,0 +1,15 @@
1
+ import type { OutputOptions } from './mode.js';
2
+ import type { NextCommand } from '../protocol/errors.js';
3
+ /** Splits a command line on whitespace while keeping single- and double-quoted runs together. */
4
+ export declare function tokens(command: string): string[];
5
+ export declare function nextCommand(command: string): NextCommand;
6
+ export declare function nextFor(command: string): NextCommand[];
7
+ export declare function quote(value: string): string;
8
+ export declare function row(label: string, value: unknown, args?: OutputOptions): string;
9
+ export declare function receipt(label: string, value: unknown, args?: OutputOptions): string;
10
+ export declare function nextStep(benefit: string, command: string, args?: OutputOptions): string;
11
+ export declare function hintStep(instruction: string, hint: string): string;
12
+ export declare function sessionCommand(command: string, name: string): string;
13
+ export declare function count(value: number, noun: string): string;
14
+ export declare function duration(seconds: number): string;
15
+ export declare function size(bytes: number): string;
@@ -0,0 +1,5 @@
1
+ import { type OutputOptions } from './mode.js';
2
+ export declare const version: string;
3
+ export declare function helpDocument(name?: string): Record<string, unknown>;
4
+ /** Formats root or command help in the human layout, or the descriptive agent layout when an agent is detected. */
5
+ export declare function formatHelp(name?: string, args?: OutputOptions): string;
@@ -0,0 +1,23 @@
1
+ import { type ChildProcess, type SpawnOptions } from 'node:child_process';
2
+ export declare const DEFAULT_PORT = 8080;
3
+ export declare const COMPONENTS: string[];
4
+ export declare const LAUNCHER_DIR: string;
5
+ /** Version of this CLI, or 0.0.0 in a bundle built without one. */
6
+ export declare const VERSION: string;
7
+ /** Directory that holds the engine built for this CLI version. */
8
+ export declare function engineDirectory(): string;
9
+ export type HostArgs = Record<string, unknown> & {
10
+ command: string;
11
+ json: boolean;
12
+ name: string;
13
+ backend?: string;
14
+ output?: string;
15
+ signal?: AbortSignal;
16
+ };
17
+ export declare function isLinux(): boolean;
18
+ export declare function requireHost(): void;
19
+ export declare function which(program: string): string | undefined;
20
+ /** Clears Linux capabilities or leaves the command unchanged on macOS. */
21
+ export declare function clearedCommand(command: string[]): [string, ...string[]];
22
+ export declare function spawnCleared(command: string[], options?: SpawnOptions): ChildProcess;
23
+ export declare function run(command: string[], options?: SpawnOptions): import("node:child_process").SpawnSyncReturns<string>;
@@ -0,0 +1,2 @@
1
+ import type { HostArgs } from './common.js';
2
+ export declare function cmdDoctor(args: HostArgs): Promise<number>;
@@ -0,0 +1,13 @@
1
+ export type Family = 'apt' | 'dnf' | 'pacman' | 'apk';
2
+ /** Rows of packages.tsv, read on first use from beside the installed CLI or from the root of a source checkout. */
3
+ export declare function rows(): string[][];
4
+ /** Family from os-release text: ID first, then each ID_LIKE word. Returns undefined for an unsupported distro. */
5
+ export declare function detectFamily(osRelease: string): Family | undefined;
6
+ /** Distro package names for the logical names, in table order, deduplicated. Throws on an unknown name. */
7
+ export declare function packagesFor(family: Family, names: string[]): string[];
8
+ /** Distro package names for every row in the given groups, in table order, deduplicated. */
9
+ export declare function groupPackages(family: Family, groups: string[], skip?: string[]): string[];
10
+ /** Whether packages.tsv has a row that provides this program or library. */
11
+ export declare function provides(name: string): boolean;
12
+ /** The non-interactive install command to paste, with prefix '' or 'sudo '. */
13
+ export declare function installCommand(family: Family, packages: string[], prefix: string): string;
@@ -0,0 +1,8 @@
1
+ import { COMPONENTS, HostArgs } from './common.js';
2
+ export { COMPONENTS };
3
+ type Args = HostArgs & Record<string, any>;
4
+ export declare function cmdUp(args: Args): Promise<number>;
5
+ export declare function cmdDown(args: Args): Promise<number>;
6
+ export declare function cmdStatus(args: Args): Promise<number>;
7
+ export declare function cmdLogs(args: Args): Promise<number>;
8
+ export declare function cmdRun(args: Args): Promise<number>;
@@ -0,0 +1,22 @@
1
+ import { BACKENDS } from '../config.js';
2
+ import { type HostArgs } from './common.js';
3
+ type Backend = (typeof BACKENDS)[number];
4
+ type Args = HostArgs & Record<string, any>;
5
+ type Request = {
6
+ backends: Backend[];
7
+ display?: string;
8
+ desktop?: string;
9
+ keyboardLayout?: string;
10
+ };
11
+ type Plan = {
12
+ state: 'ready' | 'needs-build' | 'needs-packages';
13
+ backends: Backend[];
14
+ build: boolean;
15
+ groups: string[];
16
+ };
17
+ /** Decides what this machine still needs before it can run the requested backends. The engine is built with every compiled backend, but the desktop packages follow only the requested ones. */
18
+ export declare function planSetup(request: Request): Plan;
19
+ /** Sets the machine up before a session starts and returns the arguments a prompt chose, for a detached child to repeat. */
20
+ export declare function ensureSetup(args: Args): Promise<string[]>;
21
+ export declare function cmdInstall(args: Args): Promise<number>;
22
+ export {};
@@ -0,0 +1,23 @@
1
+ export type ProcessIdentity = {
2
+ pid: number;
3
+ start: string | null;
4
+ };
5
+ export type SessionData = Record<string, any>;
6
+ export declare function stateDir(name: string): string;
7
+ export declare function readSession(name: string): SessionData | null;
8
+ export declare function writeSession(directory: string, data: SessionData): void;
9
+ export declare function tail(path: string, lines?: number): string;
10
+ export declare function startTime(pid: number): string | null;
11
+ export declare function alive(record: unknown): boolean;
12
+ export declare function identity(pid: number): ProcessIdentity;
13
+ /** Creates a lock file that names this process as its owner, whole or not at all. Returns false when the file already exists. */
14
+ export declare function claimLock(file: string): boolean;
15
+ /** Whether the process that claimed a lock file is still running. A missing, empty, or unreadable file has no owner. */
16
+ export declare function lockOwnerAlive(file: string): boolean;
17
+ /** Signals every Linux process carrying this session's SCREEN_RELAY_SESSION marker; on macOS the app watcher stops each app it holds. */
18
+ export declare function sweep(directory: string, signal?: AbortSignal): Promise<void>;
19
+ export declare function reap(directory: string, session: SessionData | null, signal?: AbortSignal): Promise<void>;
20
+ /** Holds the kernel session lock until close, with flock on Linux and lockf on macOS. */
21
+ export declare function lock(name: string, directory: string): Promise<{
22
+ close(): Promise<void>;
23
+ }>;
@@ -0,0 +1,91 @@
1
+ import { type ChildProcess, type SpawnOptions } from 'node:child_process';
2
+ import { BACKENDS } from '../config.js';
3
+ import { Failure } from '../output.js';
4
+ import { HostArgs } from './common.js';
5
+ import { SessionData } from './state.js';
6
+ export declare const BACKEND_PROGRAMS: {
7
+ x11: string[];
8
+ wayland: string[];
9
+ macos: never[];
10
+ };
11
+ export declare const HINTS: Record<string, string>;
12
+ export type SessionArgs = HostArgs & {
13
+ name: string;
14
+ port: number;
15
+ display?: string;
16
+ desktop?: string;
17
+ public?: string;
18
+ bind?: string;
19
+ resolution: string;
20
+ fps: number;
21
+ bitrateMin: number;
22
+ bitrateStart: number;
23
+ bitrateMax: number;
24
+ timeout?: number;
25
+ 'tls-cert'?: string;
26
+ 'tls-key'?: string;
27
+ keyboardLayout?: string;
28
+ compositor?: string;
29
+ };
30
+ type EngineTarget = {
31
+ url: string;
32
+ token?: string | null;
33
+ caFile?: string | null;
34
+ connect?: string | null;
35
+ };
36
+ export declare function startXvfb(start: (command: string[], options: SpawnOptions) => ChildProcess, auth: string, resolution?: string, signal?: AbortSignal): Promise<string>;
37
+ export declare function xQuery(env: NodeJS.ProcessEnv, ...command: string[]): string;
38
+ export declare function displaySize(env: NodeJS.ProcessEnv): string | null;
39
+ export declare function connectHost(bind?: string | null): string | null;
40
+ export declare class Session {
41
+ readonly args: SessionArgs;
42
+ readonly dir: string;
43
+ readonly children: Map<string, ChildProcess>;
44
+ readonly logs: number[];
45
+ readonly errors: Map<string, Error>;
46
+ runtimeDir?: string;
47
+ env: NodeJS.ProcessEnv;
48
+ data: SessionData;
49
+ constructor(args: SessionArgs, directory: string);
50
+ save(changes?: Record<string, unknown>): void;
51
+ spawn(name: string, command: string[], options?: SpawnOptions): ChildProcess;
52
+ failure(name: string, code: string, message: string): Failure;
53
+ checkChildren(): void;
54
+ startBus(): Promise<void>;
55
+ startWaylandDisplay(layout: string): Promise<string | null>;
56
+ start(): Promise<Record<string, unknown>>;
57
+ engineReady(pid: number, where: EngineTarget): Promise<boolean>;
58
+ desktopReady(desktop: string): boolean;
59
+ waitReady(pid: number, where: EngineTarget, desktop: string): Promise<void>;
60
+ supervise(shouldStop: () => boolean): Promise<void>;
61
+ cleanup(): Promise<void>;
62
+ }
63
+ export declare function desktopEnv(directory: string): NodeJS.ProcessEnv;
64
+ /** Whether screen-relay's own XFCE desktop runs its compositor: `on` or `off` as set, otherwise on only up to 60 fps, because the compositor repaints at most 60 times a second. */
65
+ export declare function compositing(setting: string | undefined, fps: number): boolean;
66
+ /** Sets the xfwm4 compositor on or off in a session's own config dir. Other saved xfwm4 settings are kept. */
67
+ export declare function writeCompositing(configHome: string | undefined, enabled: boolean): void;
68
+ /** Finds the engine beside the CLI, then the one built for this CLI version, then one on PATH. */
69
+ export declare function findEngine(): string | null;
70
+ /** Backends the engine reports it was built with; empty when there is no engine. */
71
+ export declare function compiledBackends(engine?: string | null): string[];
72
+ /** The command that sets this machine up for a backend. */
73
+ export declare function installCommand(backend: string): string;
74
+ /** Resolves the desktop for a session and lists the programs it needs that are not installed. */
75
+ export declare function sessionNeeds(backend: (typeof BACKENDS)[number], args: {
76
+ display?: string;
77
+ desktop?: string;
78
+ keyboardLayout?: string;
79
+ }): {
80
+ desktop: string;
81
+ desktopCommand: string[];
82
+ layout: string;
83
+ missing: string[];
84
+ ownBus: boolean;
85
+ };
86
+ /** The backend the caller asked for, by flag or by the shape of --display; undefined when neither says. */
87
+ export declare function requestedBackend(explicit: string | undefined, display?: string): (typeof BACKENDS)[number] | undefined;
88
+ /** Selects a backend for the platform and checks the engine's compiled backends. */
89
+ export declare function resolveBackend(explicit: string | undefined, display?: string): (typeof BACKENDS)[number];
90
+ export declare function splitCommand(value: string): string[];
91
+ export {};
@@ -0,0 +1,4 @@
1
+ export declare function startWatcher(command: string[], env: NodeJS.ProcessEnv, logFd: number, signal: AbortSignal | undefined, restart: boolean): Promise<{
2
+ pid: number;
3
+ exited?: number;
4
+ }>;
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export { commands } from './commands.js';
3
+ export declare function main(argv?: string[]): Promise<number>;
@@ -0,0 +1,14 @@
1
+ export interface OutputOptions {
2
+ json?: boolean;
3
+ 'no-color'?: boolean;
4
+ color?: boolean;
5
+ }
6
+ export declare const agent: boolean;
7
+ export declare function outputMode(args?: OutputOptions, stream?: NodeJS.WriteStream): {
8
+ tty: boolean;
9
+ plain: boolean;
10
+ color: boolean;
11
+ pretty: boolean;
12
+ };
13
+ /** Whether the CLI may prompt: a person at a terminal, not an agent, CI, or a JSON caller. */
14
+ export declare function interactive(args?: OutputOptions): boolean;
@@ -0,0 +1,24 @@
1
+ import { type OutputOptions } from './mode.js';
2
+ import { RelayError, type ErrorOptions } from '../protocol/errors.js';
3
+ export { count, duration, hintStep, nextCommand, nextFor, nextStep, quote, receipt, row, sessionCommand, size } from './format.js';
4
+ export declare class Failure extends RelayError {
5
+ constructor(code: string, message: string, hint?: string, extra?: Record<string, unknown>, options?: ErrorOptions);
6
+ payload(): Record<string, unknown>;
7
+ }
8
+ export declare function emit(args: OutputOptions, data: unknown, text: string, mutation?: {
9
+ identifier?: string;
10
+ }): void;
11
+ export declare function writeText(text: string): void;
12
+ export declare function printWarning(text: string, args?: OutputOptions): void;
13
+ export declare function printNext(args: OutputOptions, benefit: string, command: string): void;
14
+ export declare function formatReady(info: Record<string, any>, args: Record<string, any>, background?: boolean): string;
15
+ export declare function formatStatus(name: string, session: Record<string, any>, args?: OutputOptions): string;
16
+ export declare function formatStopped(name: string, stopped: boolean, args?: OutputOptions): string;
17
+ export declare function formatStarted(command: string, pid: number, display: string, log: string, args?: OutputOptions): string;
18
+ export declare function formatDoctor(checks: Array<{
19
+ status: string;
20
+ name: string;
21
+ detail: string;
22
+ fix: string;
23
+ }>, args?: OutputOptions): string;
24
+ export declare function printFailure(failure: RelayError, jsonMode: boolean, args?: OutputOptions): void;
@@ -0,0 +1,6 @@
1
+ import { type Args } from './commands.js';
2
+ import { Failure } from './output.js';
3
+ export declare function usageFailure(message: string, command?: string, reason?: string): Failure;
4
+ export declare function unknownToken(kind: string, token: string, choices: string[], command?: string): Failure;
5
+ /** Parses argv against the command metadata, returning validated values or a usage failure. */
6
+ export declare function parseCommand(argv: string[], environment?: NodeJS.ProcessEnv): Args;