@teaui/remote-control 1.17.16

package/.dist/Callbacks.d.ts

@@ -0,0 +1,14 @@
+import type { Unsubscribe } from '@teaui/core';
+import { type Result } from '@teaui/result';
+type Listener<T> = (value: T) => void | Promise<void>;
+/** Internal callback registrations. A detach function owns one registration. */
+export declare class Callbacks<T> {
+    #private;
+    constructor(onRejected: (cause: unknown) => void);
+    subscribe(listener: Listener<T>): Unsubscribe;
+    /** Snapshot delivery: additions wait for the next event; removals take effect now. */
+    emit(value: T, isCurrent?: () => boolean): unknown[];
+    /** Use the same error policy for both broadcasts and targeted readiness notifications. */
+    invoke(listener: Listener<T>, value: T): Result<void, unknown>;
+}
+export {};

package/.dist/Callbacks.js

@@ -0,0 +1,45 @@
+import { ok, err } from '@teaui/result';
+/** Internal callback registrations. A detach function owns one registration. */
+export class Callbacks {
+    #listeners = new Set();
+    #onRejected;
+    constructor(onRejected) {
+        this.#onRejected = onRejected;
+    }
+    subscribe(listener) {
+        const registration = value => listener(value);
+        this.#listeners.add(registration);
+        return () => {
+            this.#listeners.delete(registration);
+        };
+    }
+    /** Snapshot delivery: additions wait for the next event; removals take effect now. */
+    emit(value, isCurrent = () => true) {
+        const errors = [];
+        const snapshot = [...this.#listeners];
+        for (const listener of snapshot) {
+            if (!isCurrent())
+                break;
+            if (!this.#listeners.has(listener))
+                continue;
+            const result = this.invoke(listener, value);
+            if (!result.ok)
+                errors.push(result.error);
+        }
+        return errors;
+    }
+    /** Use the same error policy for both broadcasts and targeted readiness notifications. */
+    invoke(listener, value) {
+        try {
+            const pending = listener(value);
+            if (pending) {
+                void Promise.resolve(pending).catch(cause => this.#onRejected(cause));
+            }
+            return ok(undefined);
+        }
+        catch (cause) {
+            return err(cause);
+        }
+    }
+}
+//# sourceMappingURL=Callbacks.js.map

package/.dist/Callbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Callbacks.js","sourceRoot":"","sources":["../lib/Callbacks.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,EAAE,EAAE,GAAG,EAAc,MAAM,eAAe,CAAA;AAIlD,gFAAgF;AAChF,MAAM,OAAO,SAAS;IACpB,UAAU,GAAG,IAAI,GAAG,EAAe,CAAA;IACnC,WAAW,CAA0B;IAErC,YAAY,UAAoC;QAC9C,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;IAC/B,CAAC;IAED,SAAS,CAAC,QAAqB;QAC7B,MAAM,YAAY,GAAgB,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QAC1D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACjC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QACtC,CAAC,CAAA;IACH,CAAC;IAED,sFAAsF;IACtF,IAAI,CAAC,KAAQ,EAAE,YAA2B,GAAG,EAAE,CAAC,IAAI;QAClD,MAAM,MAAM,GAAc,EAAE,CAAA;QAC5B,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAA;QACrC,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;YAChC,IAAI,CAAC,SAAS,EAAE;gBAAE,MAAK;YACvB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAAE,SAAQ;YAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;YAC3C,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC3C,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAED,0FAA0F;IAC1F,MAAM,CAAC,QAAqB,EAAE,KAAQ;QACpC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;YAC/B,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;YACvE,CAAC;YACD,OAAO,EAAE,CAAC,SAAS,CAAC,CAAA;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,GAAG,CAAC,KAAK,CAAC,CAAA;QACnB,CAAC;IACH,CAAC;CACF"}

package/.dist/RemoteControl.d.ts

@@ -0,0 +1,43 @@
+import { type SystemEvent, type EventSource, type Unsubscribe } from '@teaui/core';
+import { type Result } from '@teaui/result';
+import { type RemoteControlError } from './errors.js';
+import type { RemoteControlOptions, RemoteControlAddress, SnapshotFormat } from './types.js';
+/** A reusable input source with optional snapshot output. Registrations survive restart. */
+export declare class RemoteControlServer implements EventSource {
+    #private;
+    constructor(options?: RemoteControlOptions);
+    /**
+     * Start listening, or join the current startup. When already listening, return
+     * its address. After close/failure, start a fresh run once prior cleanup ends.
+     * Startup failures resolve an error Result and notify onError; they do not reject.
+     */
+    listen(): Promise<Result<RemoteControlAddress, RemoteControlError>>;
+    /**
+     * Supply snapshots on demand without coupling this source to a screen. Replaces
+     * the previous provider; its detach function cannot remove a newer provider.
+     * The registration survives close/restart. Providers synchronously return ANSI.
+     */
+    setSnapshotProvider(provider: () => string): Unsubscribe;
+    /** Format and broadcast an ANSI snapshot. No queue/replay while stopped. */
+    sendSnapshot(format: SnapshotFormat, ansiSnapshot: string): void;
+    /** Register input delivery independently of whether the server is running. */
+    onEvents(listener: (event: SystemEvent) => void): Unsubscribe;
+    /**
+     * Notify once per successful run, until detached. A subscriber added while
+     * listening gets the current address in a microtask, unless that run stops.
+     */
+    onListening(listener: (address: RemoteControlAddress) => void | Promise<void>): Unsubscribe;
+    /** Future errors only. Registration survives close; no past failures are replayed. */
+    onError(listener: (error: RemoteControlError) => void | Promise<void>): Unsubscribe;
+    /** The current bound address only. Undefined before binding and after close. */
+    get url(): string | undefined;
+    get port(): number | undefined;
+    /** True when idle or closing; false while starting or listening. */
+    get closed(): boolean;
+    /**
+     * Cancel the current run immediately, without removing subscriptions. Wait for
+     * cleanup if needed. Cleanup failures resolve an error Result and notify onError.
+     * A following listen() waits for cleanup attempts, then starts a fresh run.
+     */
+    close(): Promise<Result<void, RemoteControlError>>;
+}

package/.dist/RemoteControl.js

@@ -0,0 +1,174 @@
+import { removeAnsi, } from '@teaui/core';
+import { ok, err } from '@teaui/result';
+import { Callbacks } from './Callbacks.js';
+import { Session } from './Session.js';
+import { remoteError, } from './errors.js';
+/** A reusable input source with optional snapshot output. Registrations survive restart. */
+export class RemoteControlServer {
+    #options;
+    #session;
+    #snapshotProvider;
+    #closing = Promise.resolve(ok(undefined));
+    #events = new Callbacks(cause => this.#reportError(remoteError({ type: 'dispatch-failed', causes: [cause] })));
+    #listening = new Callbacks(cause => this.#reportError(remoteError({ type: 'callback-failed', callback: 'listening', cause })));
+    #errors = new Callbacks(cause => this.#warn(cause));
+    constructor(options = {}) {
+        this.#options = { ...options };
+    }
+    /**
+     * Start listening, or join the current startup. When already listening, return
+     * its address. After close/failure, start a fresh run once prior cleanup ends.
+     * Startup failures resolve an error Result and notify onError; they do not reject.
+     */
+    listen() {
+        if (this.#session)
+            return this.#session.ready;
+        const session = new Session(this.#options, {
+            dispatch: event => this.#dispatch(event),
+            snapshot: format => this.#snapshot(format),
+            failed: error => {
+                if (this.#session !== session)
+                    return;
+                void this.close(); // Cleanup failures are reported through onError.
+                this.#reportError(error);
+            },
+            sendFailed: error => {
+                if (this.#session === session)
+                    this.#reportError(error);
+            },
+        });
+        this.#session = session;
+        // A failed cleanup is reported by close(). Wait for all its attempts before
+        // starting again; a new bind must report its own result, not an old failure.
+        session.start(this.#closing.then(() => { }));
+        void session.ready.then(result => {
+            if (!result.ok || this.#session !== session)
+                return;
+            for (const cause of this.#listening.emit(result.value, () => this.#session === session)) {
+                this.#reportError(remoteError({ type: 'callback-failed', callback: 'listening', cause }));
+            }
+        });
+        return session.ready;
+    }
+    /** Synchronous delivery errors become dispatch-failed replies; later rejections use onError. */
+    #dispatch(event) {
+        const causes = this.#events.emit(event);
+        return causes.length
+            ? err(remoteError({ type: 'dispatch-failed', causes }))
+            : ok(undefined);
+    }
+    /**
+     * Supply snapshots on demand without coupling this source to a screen. Replaces
+     * the previous provider; its detach function cannot remove a newer provider.
+     * The registration survives close/restart. Providers synchronously return ANSI.
+     */
+    setSnapshotProvider(provider) {
+        const registration = () => provider();
+        this.#snapshotProvider = registration;
+        return () => {
+            if (this.#snapshotProvider === registration)
+                this.#snapshotProvider = undefined;
+        };
+    }
+    #snapshot(format) {
+        if (!this.#snapshotProvider)
+            return err(remoteError({ type: 'snapshot-unavailable' }));
+        try {
+            return ok(formatSnapshot(this.#snapshotProvider(), format));
+        }
+        catch (cause) {
+            return err(remoteError({ type: 'snapshot-failed', cause }));
+        }
+    }
+    /** Format and broadcast an ANSI snapshot. No queue/replay while stopped. */
+    sendSnapshot(format, ansiSnapshot) {
+        this.#session?.sendSnapshot(format, formatSnapshot(ansiSnapshot, format));
+    }
+    /** Register input delivery independently of whether the server is running. */
+    onEvents(listener) {
+        return this.#events.subscribe(listener);
+    }
+    /**
+     * Notify once per successful run, until detached. A subscriber added while
+     * listening gets the current address in a microtask, unless that run stops.
+     */
+    onListening(listener) {
+        let active = true;
+        let notified;
+        const notify = (address) => {
+            const session = this.#session;
+            if (!active || !session || notified === session)
+                return;
+            notified = session;
+            return listener(address);
+        };
+        const detach = this.#listening.subscribe(notify);
+        const session = this.#session;
+        const address = session?.address;
+        if (address)
+            queueMicrotask(() => {
+                if (this.#session !== session)
+                    return;
+                const result = this.#listening.invoke(notify, address);
+                if (!result.ok)
+                    this.#reportError(remoteError({
+                        type: 'callback-failed',
+                        callback: 'listening',
+                        cause: result.error,
+                    }));
+            });
+        return () => {
+            active = false;
+            detach();
+        };
+    }
+    /** Future errors only. Registration survives close; no past failures are replayed. */
+    onError(listener) {
+        return this.#errors.subscribe(listener);
+    }
+    #reportError(error) {
+        for (const failure of this.#errors.emit(error))
+            this.#warn(failure);
+    }
+    #warn(cause) {
+        // Do not recursively call a failing error callback. Node accepts warning text.
+        const error = remoteError({
+            type: 'callback-failed',
+            callback: 'error',
+            cause,
+        });
+        process.emitWarning(error.message);
+    }
+    /** The current bound address only. Undefined before binding and after close. */
+    get url() {
+        return this.#session?.address?.url;
+    }
+    get port() {
+        return this.#session?.address?.port;
+    }
+    /** True when idle or closing; false while starting or listening. */
+    get closed() {
+        return this.#session === undefined;
+    }
+    /**
+     * Cancel the current run immediately, without removing subscriptions. Wait for
+     * cleanup if needed. Cleanup failures resolve an error Result and notify onError.
+     * A following listen() waits for cleanup attempts, then starts a fresh run.
+     */
+    close() {
+        const session = this.#session;
+        if (!session)
+            return this.#closing;
+        this.#session = undefined;
+        this.#closing = session.close();
+        void this.#closing.then(result => {
+            if (!result.ok)
+                this.#reportError(result.error);
+        });
+        return this.#closing;
+    }
+}
+function formatSnapshot(snapshot, format) {
+    return format === 'plain' ? removeAnsi(snapshot) : snapshot;
+}
+//# sourceMappingURL=RemoteControl.js.map

package/.dist/RemoteControl.js.map

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

package/.dist/Session.d.ts

@@ -0,0 +1,23 @@
+import { type SystemEvent } from '@teaui/core';
+import { type Result } from '@teaui/result';
+import { type RemoteControlError, type RequestError } from './errors.js';
+import type { RemoteControlOptions, RemoteControlAddress, SnapshotFormat } from './types.js';
+interface Callbacks {
+    dispatch(event: SystemEvent): Result<void, RequestError>;
+    snapshot(format: SnapshotFormat): Result<string, RequestError>;
+    failed(error: RemoteControlError): void;
+    sendFailed(error: RemoteControlError): void;
+}
+/** One listening run. Never reused; callbacks cannot access another run's resources. */
+export declare class Session {
+    #private;
+    readonly ready: Promise<Result<RemoteControlAddress, RemoteControlError>>;
+    constructor(options: RemoteControlOptions, callbacks: Callbacks);
+    get address(): RemoteControlAddress | undefined;
+    start(afterCleanup: Promise<void>): void;
+    /** Unsolicited messages deliberately have no request sequence. */
+    sendSnapshot(format: SnapshotFormat, snapshot: string): void;
+    /** Stop now; attempt all cleanup tasks and return any failures as a Result. */
+    close(): Promise<Result<void, RemoteControlError>>;
+}
+export {};

package/.dist/Session.js

@@ -0,0 +1,248 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { ok, err } from '@teaui/result';
+import { decodeMessage, errorReply } from './protocol.js';
+import { remoteError, } from './errors.js';
+const HOST = '127.0.0.1';
+const MAX_PAYLOAD = 64 * 1024;
+// Styled full-screen snapshots can be much larger than individual input events.
+const MAX_BUFFERED_REPLY_BYTES = 8 * 1024 * 1024;
+const OPEN = 1;
+/** One listening run. Never reused; callbacks cannot access another run's resources. */
+export class Session {
+    #options;
+    #callbacks;
+    #http;
+    #server;
+    #abort = new AbortController();
+    #stopped = false;
+    #setup;
+    #cleanup;
+    #address;
+    #resolve;
+    ready = new Promise(resolve => {
+        this.#resolve = resolve;
+    });
+    constructor(options, callbacks) {
+        this.#options = options;
+        this.#callbacks = callbacks;
+    }
+    get address() {
+        return this.#address;
+    }
+    start(afterCleanup) {
+        this.#setup = afterCleanup
+            .then(() => this.#bind())
+            .catch(cause => this.#fail(remoteError({ type: 'startup-failed', cause })));
+    }
+    #settle(result) {
+        this.#resolve?.(result);
+        this.#resolve = undefined;
+    }
+    async #bind() {
+        if (this.#stopped)
+            return;
+        const { port = 0 } = this.#options;
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+            this.#fail(remoteError({ type: 'invalid-port', port }));
+            return;
+        }
+        const { WebSocketServer } = await import('ws');
+        if (this.#stopped)
+            return;
+        const token = randomBytes(32).toString('hex');
+        const secret = Buffer.from(token);
+        const http = createServer((_req, response) => {
+            response.writeHead(426);
+            response.end('WebSocket upgrade required');
+        });
+        this.#http = http;
+        // Keep an HTTP error handler even after ws removes its forwarding handlers.
+        http.on('error', cause => this.#transportFailed(cause));
+        const server = new WebSocketServer({
+            server: http,
+            maxPayload: MAX_PAYLOAD,
+            perMessageDeflate: false,
+            verifyClient: ({ req }) => {
+                if (this.#stopped || req.headers.origin !== undefined)
+                    return false;
+                try {
+                    const url = new URL(req.url ?? '/', `http://${HOST}`);
+                    const candidate = Buffer.from(url.searchParams.get('token') ?? '');
+                    return (url.pathname === '/' &&
+                        candidate.length === secret.length &&
+                        timingSafeEqual(candidate, secret));
+                }
+                catch {
+                    return false;
+                }
+            },
+        });
+        this.#server = server;
+        server.on('error', cause => this.#transportFailed(cause));
+        server.on('connection', socket => this.#connect(socket));
+        server.once('listening', () => {
+            if (this.#stopped)
+                return;
+            const boundPort = http.address().port;
+            this.#address = Object.freeze({
+                port: boundPort,
+                url: `ws://${HOST}:${boundPort}/?token=${token}`,
+            });
+            this.#settle(ok(this.#address));
+        });
+        http.listen({ host: HOST, port, signal: this.#abort.signal });
+    }
+    #transportFailed(cause) {
+        this.#fail(remoteError({
+            type: this.#address ? 'server-failed' : 'startup-failed',
+            cause,
+        }));
+    }
+    #fail(error) {
+        if (this.#stopped)
+            return;
+        this.#settle(err(error));
+        this.#callbacks.failed(error);
+    }
+    #connect(socket) {
+        if (this.#stopped) {
+            socket.terminate();
+            return;
+        }
+        let sequence = 0;
+        // Invalid frames and oversized messages affect this client only.
+        socket.on('error', () => socket.terminate());
+        socket.on('message', (data, isBinary) => {
+            if (this.#stopped)
+                return;
+            sequence += 1;
+            const decoded = decodeMessage(isBinary ? '' : data.toString(), isBinary);
+            let result;
+            if (!decoded.ok) {
+                result = decoded;
+            }
+            else if (decoded.value.type === 'snapshot') {
+                const { format } = decoded.value;
+                const captured = this.#callbacks.snapshot(format);
+                result = captured.ok
+                    ? ok({
+                        type: 'snapshot',
+                        sequence,
+                        format,
+                        snapshot: captured.value,
+                    })
+                    : captured;
+            }
+            else {
+                const delivered = this.#callbacks.dispatch(decoded.value);
+                result = delivered.ok ? ok({ type: 'ack', sequence }) : delivered;
+            }
+            const reply = result.ok
+                ? result.value
+                : errorReply(sequence, result.error);
+            // Transmission is not part of dispatch. Never relabel a send failure.
+            this.#send([socket], reply);
+        });
+    }
+    /** Unsolicited messages deliberately have no request sequence. */
+    sendSnapshot(format, snapshot) {
+        if (this.#stopped || !this.#address || !this.#server)
+            return;
+        this.#send(this.#server.clients, { type: 'snapshot', format, snapshot });
+    }
+    #send(sockets, reply) {
+        if (this.#stopped)
+            return;
+        const recipients = [...sockets].filter(socket => socket.readyState === OPEN);
+        if (!recipients.length)
+            return;
+        // One encoding for this send, shared by all recipients; never retained.
+        let text;
+        let bytes;
+        try {
+            text = JSON.stringify(reply);
+            bytes = Buffer.byteLength(text);
+        }
+        catch (error) {
+            for (const socket of recipients)
+                this.#sendFailed(socket, error);
+            return;
+        }
+        for (const socket of recipients) {
+            if (this.#stopped || socket.readyState !== OPEN)
+                continue;
+            try {
+                if (socket.bufferedAmount + bytes > MAX_BUFFERED_REPLY_BYTES) {
+                    socket.terminate();
+                    continue;
+                }
+                socket.send(text, error => {
+                    if (error)
+                        this.#sendFailed(socket, error);
+                });
+            }
+            catch (error) {
+                this.#sendFailed(socket, error);
+            }
+        }
+    }
+    #sendFailed(socket, error) {
+        if (this.#stopped)
+            return;
+        socket.terminate();
+        this.#callbacks.sendFailed(remoteError({ type: 'send-failed', cause: error }));
+    }
+    /** Stop now; attempt all cleanup tasks and return any failures as a Result. */
+    close() {
+        if (this.#cleanup)
+            return this.#cleanup;
+        this.#stopped = true;
+        this.#address = undefined;
+        const canceled = remoteError({ type: 'startup-canceled' });
+        this.#settle(err(canceled));
+        const tasks = this.#setup ? [this.#setup] : [];
+        const attempt = (fn) => {
+            try {
+                fn();
+            }
+            catch (error) {
+                tasks.push(Promise.reject(error));
+            }
+        };
+        if (this.#http) {
+            const http = this.#http;
+            tasks.push(new Promise((resolve, reject) => http.close(error => {
+                if (error &&
+                    error.code !== 'ERR_SERVER_NOT_RUNNING')
+                    reject(error);
+                else
+                    resolve();
+            })));
+            attempt(() => http.closeAllConnections());
+        }
+        attempt(() => this.#abort.abort(canceled));
+        if (this.#server) {
+            const server = this.#server;
+            for (const socket of server.clients)
+                attempt(() => socket.terminate());
+            tasks.push(new Promise((resolve, reject) => server.close(error => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            })));
+        }
+        // Waiting for setup (not readiness) also covers cancellation during import.
+        this.#cleanup = Promise.allSettled(tasks).then(results => {
+            const failures = results
+                .filter(result => result.status === 'rejected')
+                .map(result => result.reason);
+            return failures.length
+                ? err(remoteError({ type: 'cleanup-failed', causes: failures }))
+                : ok(undefined);
+        });
+        return this.#cleanup;
+    }
+}
+//# sourceMappingURL=Session.js.map

package/.dist/Session.js.map

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

package/.dist/errors.d.ts

@@ -0,0 +1,50 @@
+type RequestErrorDetail = {
+    readonly type: 'invalid-json';
+} | {
+    readonly type: 'invalid-event';
+    readonly reason: 'shape' | 'snapshot-format';
+} | {
+    readonly type: 'binary-message';
+} | {
+    readonly type: 'dispatch-failed';
+    readonly causes: readonly unknown[];
+} | {
+    readonly type: 'snapshot-unavailable';
+} | {
+    readonly type: 'snapshot-failed';
+    readonly cause: unknown;
+};
+type ErrorDetail = RequestErrorDetail | {
+    readonly type: 'invalid-port';
+    readonly port: number;
+} | {
+    readonly type: 'startup-canceled';
+} | {
+    readonly type: 'startup-failed';
+    readonly cause: unknown;
+} | {
+    readonly type: 'server-failed';
+    readonly cause: unknown;
+} | {
+    readonly type: 'send-failed';
+    readonly cause: unknown;
+} | {
+    readonly type: 'cleanup-failed';
+    readonly causes: readonly unknown[];
+} | {
+    readonly type: 'callback-failed';
+    readonly callback: 'listening' | 'error';
+    readonly cause: unknown;
+};
+/** Plain error values, discriminated by type. Original failures remain local causes. */
+export type RemoteControlError = ErrorDetail & {
+    readonly message: string;
+};
+export type RequestError = RequestErrorDetail & {
+    readonly message: string;
+};
+/** The one place that assigns messages to remote-control failures. */
+export declare function remoteError<T extends ErrorDetail>(detail: T): T & {
+    readonly message: string;
+};
+export {};

package/.dist/errors.js

@@ -0,0 +1,55 @@
+/** The one place that assigns messages to remote-control failures. */
+export function remoteError(detail) {
+    return { ...detail, message: errorMessage(detail) };
+}
+function errorMessage(error) {
+    switch (error.type) {
+        case 'invalid-json':
+            return 'Invalid JSON';
+        case 'invalid-event':
+            return error.reason === 'snapshot-format'
+                ? "Snapshot format must be 'plain' or 'ansi'"
+                : 'Expected a SystemEvent (key, mouse, paste, focus, blur, or resize) or snapshot request';
+        case 'binary-message':
+            return 'Send a SystemEvent or snapshot request as a JSON text message';
+        case 'dispatch-failed':
+            return error.causes.length === 1
+                ? causeMessage(error.causes[0], 'Remote control input callback failed')
+                : 'Remote control input callbacks failed';
+        case 'snapshot-unavailable':
+            return 'No snapshot provider registered';
+        case 'snapshot-failed':
+            return causeMessage(error.cause, 'Remote control snapshot failed');
+        case 'invalid-port':
+            return 'Remote control port must be an integer from 0 to 65535';
+        case 'startup-canceled':
+            return 'Remote control startup canceled';
+        case 'startup-failed':
+            return causeMessage(error.cause, 'Remote control setup failed');
+        case 'server-failed':
+            return causeMessage(error.cause, 'Remote control server failed');
+        case 'send-failed':
+            return causeMessage(error.cause, 'Remote control reply failed');
+        case 'cleanup-failed':
+            return 'Remote control cleanup failed';
+        case 'callback-failed':
+            return `Remote control ${error.callback} callback failed: ${causeMessage(error.cause, 'unknown cause')}`;
+    }
+}
+// Never coerce an arbitrary thrown value. Even reading a message can throw.
+function causeMessage(cause, fallback) {
+    if (typeof cause === 'string')
+        return cause;
+    try {
+        if (typeof cause === 'object' && cause !== null && 'message' in cause) {
+            const message = cause.message;
+            if (typeof message === 'string')
+                return message;
+        }
+    }
+    catch {
+        // A throwing getter/proxy must not escape the error boundary.
+    }
+    return fallback;
+}
+//# sourceMappingURL=errors.js.map

package/.dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../lib/errors.ts"],"names":[],"mappings":"AA6BA,sEAAsE;AACtE,MAAM,UAAU,WAAW,CACzB,MAAS;IAET,OAAO,EAAC,GAAG,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,EAAC,CAAA;AACnD,CAAC;AAED,SAAS,YAAY,CAAC,KAAkB;IACtC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAA;QACvB,KAAK,eAAe;YAClB,OAAO,KAAK,CAAC,MAAM,KAAK,iBAAiB;gBACvC,CAAC,CAAC,2CAA2C;gBAC7C,CAAC,CAAC,wFAAwF,CAAA;QAC9F,KAAK,gBAAgB;YACnB,OAAO,+DAA+D,CAAA;QACxE,KAAK,iBAAiB;YACpB,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;gBAC9B,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,sCAAsC,CAAC;gBACvE,CAAC,CAAC,uCAAuC,CAAA;QAC7C,KAAK,sBAAsB;YACzB,OAAO,iCAAiC,CAAA;QAC1C,KAAK,iBAAiB;YACpB,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,gCAAgC,CAAC,CAAA;QACpE,KAAK,cAAc;YACjB,OAAO,wDAAwD,CAAA;QACjE,KAAK,kBAAkB;YACrB,OAAO,iCAAiC,CAAA;QAC1C,KAAK,gBAAgB;YACnB,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,6BAA6B,CAAC,CAAA;QACjE,KAAK,eAAe;YAClB,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,8BAA8B,CAAC,CAAA;QAClE,KAAK,aAAa;YAChB,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,6BAA6B,CAAC,CAAA;QACjE,KAAK,gBAAgB;YACnB,OAAO,+BAA+B,CAAA;QACxC,KAAK,iBAAiB;YACpB,OAAO,kBAAkB,KAAK,CAAC,QAAQ,qBAAqB,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,eAAe,CAAC,EAAE,CAAA;IAC5G,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,YAAY,CAAC,KAAc,EAAE,QAAgB;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,CAAC;QACH,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;YACtE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAA;YAC7B,IAAI,OAAO,OAAO,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAA;QACjD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/.dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RemoteControlServer } from './RemoteControl.js';
+export type { RemoteControlError } from './errors.js';
+export type { RemoteControlOptions, RemoteControlAddress, RemoteControlRequest, RemoteControlReply, SnapshotFormat, SnapshotRequest, SnapshotMessage, } from './types.js';

package/.dist/index.js

@@ -0,0 +1,2 @@
+export { RemoteControlServer } from './RemoteControl.js';
+//# sourceMappingURL=index.js.map

package/.dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAA"}

package/.dist/protocol.d.ts

@@ -0,0 +1,9 @@
+import { type Result } from '@teaui/result';
+import type { RemoteControlRequest, RemoteControlReply } from './types.js';
+import { type RequestError } from './errors.js';
+/** Only public wire fields leave the process; never serialize local causes. */
+export declare function errorReply(sequence: number, error: RequestError): Extract<RemoteControlReply, {
+    type: 'error';
+}>;
+/** Decode one message. This function has no socket or subscriber side effects. */
+export declare function decodeMessage(text: string, isBinary: boolean): Result<RemoteControlRequest, RequestError>;

package/.dist/protocol.js

@@ -0,0 +1,32 @@
+import { isSystemEvent } from './validate.js';
+import { ok, err } from '@teaui/result';
+import { remoteError } from './errors.js';
+/** Only public wire fields leave the process; never serialize local causes. */
+export function errorReply(sequence, error) {
+    return { type: 'error', sequence, code: error.type, message: error.message };
+}
+/** Decode one message. This function has no socket or subscriber side effects. */
+export function decodeMessage(text, isBinary) {
+    if (isBinary)
+        return err(remoteError({ type: 'binary-message' }));
+    let event;
+    try {
+        event = JSON.parse(text);
+    }
+    catch {
+        return err(remoteError({ type: 'invalid-json' }));
+    }
+    if (typeof event === 'object' &&
+        event !== null &&
+        !Array.isArray(event) &&
+        event.type === 'snapshot') {
+        const format = event.format;
+        if (format === 'plain' || format === 'ansi')
+            return ok({ type: 'snapshot', format });
+        return err(remoteError({ type: 'invalid-event', reason: 'snapshot-format' }));
+    }
+    return isSystemEvent(event)
+        ? ok(event)
+        : err(remoteError({ type: 'invalid-event', reason: 'shape' }));
+}
+//# sourceMappingURL=protocol.js.map

package/.dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../lib/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAC,EAAE,EAAE,GAAG,EAAc,MAAM,eAAe,CAAA;AAElD,OAAO,EAAC,WAAW,EAAoB,MAAM,aAAa,CAAA;AAE1D,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,KAAmB;IAEnB,OAAO,EAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAC,CAAA;AAC5E,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,QAAiB;IAEjB,IAAI,QAAQ;QAAE,OAAO,GAAG,CAAC,WAAW,CAAC,EAAC,IAAI,EAAE,gBAAgB,EAAC,CAAC,CAAC,CAAA;IAC/D,IAAI,KAAc,CAAA;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC,WAAW,CAAC,EAAC,IAAI,EAAE,cAAc,EAAC,CAAC,CAAC,CAAA;IACjD,CAAC;IACD,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACpB,KAAiC,CAAC,IAAI,KAAK,UAAU,EACtD,CAAC;QACD,MAAM,MAAM,GAAI,KAAiC,CAAC,MAAM,CAAA;QACxD,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,MAAM;YACzC,OAAO,EAAE,CAAC,EAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAC,CAAC,CAAA;QACvC,OAAO,GAAG,CAAC,WAAW,CAAC,EAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,iBAAiB,EAAC,CAAC,CAAC,CAAA;IAC7E,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC;QACzB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC;QACX,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,EAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAC,CAAC,CAAC,CAAA;AAChE,CAAC"}

package/.dist/types.d.ts

@@ -0,0 +1,32 @@
+import type { SystemEvent } from '@teaui/core';
+import type { RequestError } from './errors.js';
+export interface RemoteControlOptions {
+    /** Loopback port. Defaults to 0 (let the OS choose an unused port). */
+    port?: number;
+}
+export interface RemoteControlAddress {
+    readonly url: string;
+    readonly port: number;
+}
+export type SnapshotFormat = 'plain' | 'ansi';
+export interface SnapshotRequest {
+    type: 'snapshot';
+    format: SnapshotFormat;
+}
+export type RemoteControlRequest = SystemEvent | SnapshotRequest;
+export interface SnapshotMessage {
+    type: 'snapshot';
+    /** Request sequence, or absent for an application-initiated broadcast. */
+    sequence?: number;
+    format: SnapshotFormat;
+    snapshot: string;
+}
+export type RemoteControlReply = {
+    type: 'ack';
+    sequence: number;
+} | {
+    type: 'error';
+    sequence: number;
+    code: RequestError['type'];
+    message: string;
+} | SnapshotMessage;

package/.dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/.dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":""}

package/.dist/validate.d.ts

@@ -0,0 +1,3 @@
+import type { SystemEvent } from '@teaui/core';
+/** Validate untrusted JSON before passing it to Screen.dispatch(). */
+export declare function isSystemEvent(value: unknown): value is SystemEvent;

package/.dist/validate.js

@@ -0,0 +1,48 @@
+const MOUSE_NAMES = new Set([
+    'mouse.move.in',
+    'mouse.button.down',
+    'mouse.button.up',
+    'mouse.wheel.up',
+    'mouse.wheel.down',
+    'mouse.wheel.left',
+    'mouse.wheel.right',
+]);
+const MOUSE_BUTTONS = new Set([
+    'left',
+    'middle',
+    'right',
+    'wheel',
+    'unknown',
+]);
+const MODIFIERS = ['ctrl', 'alt', 'gui', 'shift'];
+/** Validate untrusted JSON before passing it to Screen.dispatch(). */
+export function isSystemEvent(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const event = value;
+    switch (event.type) {
+        case 'resize':
+        case 'focus':
+        case 'blur':
+            return true;
+        case 'paste':
+            return typeof event.text === 'string';
+        case 'key':
+            return (MODIFIERS.every(mod => typeof event[mod] === 'boolean') &&
+                typeof event.char === 'string' &&
+                typeof event.name === 'string' &&
+                event.name.length > 0 &&
+                typeof event.full === 'string' &&
+                event.full.length > 0);
+        case 'mouse':
+            return (MODIFIERS.every(mod => typeof event[mod] === 'boolean') &&
+                MOUSE_NAMES.has(event.name) &&
+                MOUSE_BUTTONS.has(event.button) &&
+                Number.isSafeInteger(event.x) &&
+                Number.isSafeInteger(event.y));
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=validate.js.map

package/.dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../lib/validate.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,GAAG,IAAI,GAAG,CAAuB;IAChD,eAAe;IACf,mBAAmB;IACnB,iBAAiB;IACjB,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,mBAAmB;CACpB,CAAC,CAAA;AACF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAc;IACzC,MAAM;IACN,QAAQ;IACR,OAAO;IACP,OAAO;IACP,SAAS;CACV,CAAC,CAAA;AACF,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAU,CAAA;AAE1D,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,KAAK,GAAG,KAAgC,CAAA;IAE9C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,MAAM;YACT,OAAO,IAAI,CAAA;QACb,KAAK,OAAO;YACV,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAA;QACvC,KAAK,KAAK;YACR,OAAO,CACL,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;gBACvD,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;gBACrB,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CACtB,CAAA;QACH,KAAK,OAAO;YACV,OAAO,CACL,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;gBACvD,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAA4B,CAAC;gBACnD,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,MAAqB,CAAC;gBAC9C,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC7B,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAC9B,CAAA;QACH;YACE,OAAO,KAAK,CAAA;IAChB,CAAC;AACH,CAAC"}

package/LICENSE

@@ -0,0 +1,24 @@
+TeaUI
+Copyright (c) 2023, Colin T.A. Gray
+https://github.com/colinta/teaui
+
+With code from multiple sources
+see https://github.com/colinta/teaui/blob/master/packages/core/LICENSE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @teaui/remote-control
+
+Optional local WebSocket input and snapshot transport for TeaUI. Depends on the
+public APIs of `@teaui/core` and `@teaui/result`; core does not depend on this package.
+
+```ts
+import {RemoteControlServer} from '@teaui/remote-control'
+
+const remote = new RemoteControlServer()
+screen.addEventSource(remote)
+const detachSnapshot = remote.setSnapshotProvider(() => screen.snapshot())
+screen.onExit(() => {
+  detachSnapshot()
+  void remote.close()
+})
+
+const result = await remote.listen()
+if (result.ok) {
+  // Publish result.value.url privately. It contains the connection secret.
+} else {
+  // Report result.error through the application's logger.
+}
+```
+
+Send a `SystemEvent` JSON message for input, or
+`{"type":"snapshot","format":"plain"}` to request a snapshot. Use `"ansi"` for
+styled output. The provider always returns one ANSI string; remote control removes
+ANSI when plain output is requested. Capture never triggers a render.
+`remote.sendSnapshot(format, ansiSnapshot)` applies the same conversion and
+broadcasts to current clients. Each broadcast is encoded once, with per-client
+backpressure checks and no retained snapshot cache.
+
+Screen owns event subscriptions. The application owns the server's lifetime.
+Closing the server preserves registrations, and a later `listen()` starts a fresh
+session with a new token. `listen()` returns
+`Result<RemoteControlAddress, RemoteControlError>` and `close()` returns
+`Result<void, RemoteControlError>` through their promises; neither rejects for
+operation failures. Result types and helpers are exported by `@teaui/result`.
+
+`RemoteControlError` is a plain discriminated union exported by this package, not
+a JavaScript `Error` subclass. Switch on `error.type`: `invalid-port` carries
+`port`; `startup-failed`, `server-failed`, `send-failed`, and `snapshot-failed`
+carry an original `cause`; `dispatch-failed` and `cleanup-failed` carry `causes`.
+`callback-failed` identifies `callback: 'listening' | 'error'` and its `cause`.
+Cancellation is `startup-canceled`. Request-validation variants are
+`invalid-json`, `invalid-event` (with a `reason`), `binary-message`, and
+`snapshot-unavailable`. Every variant has a display `message`.
+
+`onError()` receives the same union. Startup and cleanup failures are reported
+both through their Result and `onError()`; choose one reporting path to avoid
+duplicates. Cancellation is not an error notification. Request failures keep the
+existing wire `{type: 'error', sequence, code, message}` shape; local causes and
+other diagnostic details are never serialized into replies.
+
+See [the remote-control guide](../../apps/docs/docs/remote-control.mdx) for lifecycle,
+protocol, and security details. The source-checkout JSONL driver is
+`examples/remote-control.mjs`.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@teaui/remote-control",
+  "description": "Opt-in local WebSocket input and snapshots for TeaUI applications",
+  "author": "Colin T.A. Gray <colinta@colinta.com>",
+  "version": "1.17.16",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/colinta/teaui"
+  },
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.ts",
+      "import": "./.dist/index.js",
+      "default": "./.dist/index.js"
+    }
+  },
+  "main": ".dist/index.js",
+  "types": ".dist/index.d.ts",
+  "files": [
+    ".dist/"
+  ],
+  "engines": {
+    "node": ">= 18.12.0"
+  },
+  "dependencies": {
+    "ws": "^8.21.3",
+    "@teaui/core": "1.18.16",
+    "@teaui/result": "1.17.16"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "@teaui/shared": "1.18.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf .dist/",
+    "_build": "pnpm clean && pnpm tsc",
+    "build": "node ../../shared/check.js",
+    "typecheck": "tsc -p tsconfig.check.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}