@linkshell/host 0.3.1 → 0.4.0

package/dist/host/src/input.d.ts

@@ -107,25 +107,92 @@ export interface HelperStatus {
     trusted: boolean;
     recording: boolean;
     app: string;
+    /** The app can send the screen as a video track (it carries the media engine). */
+    video: boolean;
 }
+/** A display as the app sees it. `screen` is its number in everything said to the app. */
+export interface AppDisplay {
+    screen: number;
+    name: string;
+    /** In pixels. */
+    w: number;
+    h: number;
+    main: boolean;
+}
+/** The picture asked of the app for a pipe that loses nothing: rates in bits a second. */
+export interface StreamProfile {
+    width: number;
+    fps: number;
+    bitrate: number;
+    ceiling: number;
+}
+/** A stream under way. */
+export interface AppStream {
+    /** Another profile, without stopping: a new size starts a new generation, at a keyframe. */
+    set(profile: StreamProfile): void;
+    /** The next frame a keyframe. */
+    key(): void;
+    end(): void;
+}
+/** How the app is to offer a screen as a video track. */
+export interface VideoOffer {
+    /** Which of the system's displays. */
+    screen: number;
+    iceServers: {
+        urls: string[];
+    }[];
+    /** Frames a second; the app's own choice when left out. */
+    fps?: number;
+}
+/** What a viewer answers the app's offer with, and the candidates it finds. */
+export type VideoSignal = {
+    t: "rtc.answer";
+    sdp: string;
+} | {
+    t: "rtc.ice";
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+};
+export declare const videoSignal: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
+    t: z.ZodLiteral<"rtc.answer">;
+    sdp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    t: "rtc.answer";
+    sdp: string;
+}, {
+    t: "rtc.answer";
+    sdp: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"rtc.ice">;
+    candidate: z.ZodString;
+    sdpMid: z.ZodNullable<z.ZodString>;
+    sdpMLineIndex: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    t: "rtc.ice";
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+}, {
+    t: "rtc.ice";
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+}>]>;
 /**
- * The app as it came in the package, made runnable. Packing a package drops
- * the program's permission to run (pnpm stores every file that isn't a `bin`
- * as a plain one): it is given back here, and where the installation can't be
- * written to (a root-owned one), a copy under the user's own directory is used.
- * Neither touches the signature.
+ * The app out of the archive it is shipped in, unpacked under the user's own
+ * directory. An archive, because a package can carry neither the links a
+ * framework is made of nor a program's permission to run; unpacked whole, the
+ * app is as it was signed. Always at the same place, so that an upgrade
+ * replaces the app instead of adding another: macOS has been seen to ask
+ * about recording again for the same app run from a new path. (A host still
+ * running the app being replaced keeps the one it has open.)
  */
-export declare function usableApp(packaged: string, copyTo?: string): string | undefined;
-/** The signed app this package was made with, if it was. */
+export declare function unpackedApp(archive: string, at?: string): string | undefined;
+/** LinkShell.app, where this installation has it: a Mac with Apple silicon, with `@linkshell/mac` installed beside the host. */
 export declare function shippedApp(): string | undefined;
-/** The helper compiled here; built on first use, once per version of its source. */
-export declare function inputHelper(log?: (message: string) => void): Promise<string>;
-/**
- * What this process itself (so: the host, and the capture it starts) is
- * allowed to do, and under which app's name. `ask` has the system put its
- * question for that permission, and opens the settings page for it.
- */
-export declare function hostAccess(log: (message: string) => void, ask?: "recording" | "control"): Promise<HelperStatus>;
+/** What to tell someone whose Mac has no LinkShell.app: it is an Intel Mac (the app is built for Apple silicon only), or the package that carries it wasn't installed. */
+export declare const NO_APP: string;
 type Route = (message: Record<string, unknown>) => void;
 declare class HelperApp {
     private readonly app;
@@ -138,6 +205,7 @@ declare class HelperApp {
     private readonly routes;
     private readonly watchers;
     private waiting;
+    private listing;
     constructor(app: string, dryRun: boolean, log: (message: string) => void);
     /** The app's end of the socket; opens the app when it isn't there. */
     private link;
@@ -146,17 +214,34 @@ declare class HelperApp {
     private write;
     /** What the app may do. It says so as it connects; asked again, it looks again. */
     access(): Promise<HelperStatus>;
-    /** The system's dialog and its settings page, for the app. */
-    ask(what?: "control" | "recording"): Promise<void>;
+    /** The displays there are to watch. */
+    displays(): Promise<AppDisplay[]>;
+    /**
+     * Has the app capture a screen and encode it for a pipe that loses nothing:
+     * the socket to a viewer it couldn't reach directly. Whole frames come to
+     * `on.frame`, each with the generation of picture size it belongs to.
+     */
+    stream(screen: number, profile: StreamProfile, on: {
+        frame(unit: Buffer, key: boolean, generation: number): void;
+        exit(error?: string): void;
+    }): Promise<AppStream>;
+    /**
+     * Opens LinkShell's own window for its permissions, on this computer: it says
+     * what each is for, has the system ask, takes the user to the switch, and
+     * ticks each off as it is turned on. Nothing appears when both are allowed
+     * already, and there is only ever one such window.
+     */
+    ask(): Promise<void>;
     /**
-     * Has the app run a screen capture: as the app's child, the recording is the
-     * app's to be allowed. The picture comes down a socket of its own; the
-     * returned function ends the capture.
+     * Has the app offer a screen to one viewer as a video track. What the app
+     * says of it (`rtc.offer`, `rtc.ice`, `rtc.state`, `rtc.error`, and `gone`
+     * when the app itself went) comes to `route`; the viewer's answer goes back
+     * with `signal`. The picture and the viewer's hands then travel between the
+     * two of them, not through here.
      */
-    capture(exec: string, args: string[], on: {
-        data(chunk: Buffer): void;
-        exit(code: number, errors: string): void;
-    }): Promise<() => void>;
+    offerVideo(id: string, offer: VideoOffer, route: Route): Promise<void>;
+    signal(id: string, signal: VideoSignal): void;
+    endVideo(id: string): void;
     join(id: string, screen: number, route: Route, watcher: (status: HelperStatus) => void): Promise<void>;
     send(id: string, event: InputEvent): void;
     leave(id: string, watcher: (status: HelperStatus) => void): void;
@@ -171,19 +256,19 @@ export type { HelperApp };
 export declare class InputControl {
     private readonly listener;
     private readonly log;
-    /** `app: false` keeps to a child process even when the package has the app (tests). */
+    /** `app: false` runs the app's program as this process's child instead of having the system open it (tests). */
     private readonly options;
     private child?;
     private joined?;
     private stopped;
     private started;
     constructor(listener: InputListener, log: (message: string) => void, 
-    /** `app: false` keeps to a child process even when the package has the app (tests). */
+    /** `app: false` runs the app's program as this process's child instead of having the system open it (tests). */
     options?: {
         dryRun?: boolean;
         app?: boolean;
     });
-    /** Starts the helper for the display ffmpeg calls "Capture screen `screen`". Reports through the listener; never throws. */
+    /** Starts control of the display the app numbers `screen`. Reports through the listener; never throws. */
     start(screen: number): Promise<void>;
     private joinApp;
     private spawn;