@domicile-desktop/sdk 0.0.0-alpha-e040773499e5 → 0.0.0-alpha-019dff1d8582

package/README.md

@@ -57,7 +57,7 @@ See [docs/ELEMENTS.md](docs/ELEMENTS.md) for `<app>` input and focus, and the
 | `./bind-keys` | `bindKeys`: grab a shell's own chords by name and handle them by mode. `./key-action` and `./own-keybindings` are its parts. |
 | `./fake-host` | `FakeDomicileHost`: a desktop for a shell's tests. |
 | `./system` | `system(domicile)`: files, watches, processes and D-Bus. Calls resolve a `Result`; the compositor refuses most while the desktop is locked. See [SHELL-SYSTEM-ACCESS.md](/docs/SHELL-SYSTEM-ACCESS.md). |
-| `./portal` | `watchPortalRequests` and `answerPortalRequest`: application dialogs from `xdg-desktop-portal`, parsed by kind. `<PortalDialogs />` in component-library draws them. See [PORTALS.md](/docs/architecture/PORTALS.md). |
+| `./portal` | `watchPortalRequests` and `answerPortalRequest`: application dialogs from `xdg-desktop-portal`, parsed by kind. `watchCapturing` and `stopCapturing`: running sessions that control or capture input. `<PortalDialogs />` in component-library draws them. See [PORTALS.md](/docs/architecture/PORTALS.md). |
 | `./extension`, `./tray`, `./notification`, `./theme`, `./file-preview`, `./display-transform` | Data types and Zod schemas for what the desktop holds. |
 
 Internal, not needed by shells: `./cursor-shape`.

package/dist/portal.d.ts

@@ -11,8 +11,12 @@ export declare enum PortalKind {
      * lets go. Not a question: the compositor refuses answers to it.
      */
     Inhibit = 3,
+    /** Which input devices, and the clipboard, an application may control. */
+    RemoteDesktop = 4,
+    /** Whether an application may take input that crosses a screen edge. */
+    InputCapture = 5,
     /** A kind this SDK cannot parse. Answer it with {@link PortalAnswer.Refused}. */
-    Unknown = 4
+    Unknown = 6
 }
 /** What every request carries. */
 export type PortalRequestBase = {
@@ -115,6 +119,21 @@ export type InhibitBody = {
     what: readonly Inhibited[];
     reason: string | undefined;
 };
+/** Input devices a session asks for or holds. */
+export type Devices = {
+    keyboard: boolean;
+    pointer: boolean;
+    touchscreen: boolean;
+};
+/** What a remote desktop session asks to control. */
+export type RemoteDesktopBody = {
+    devices: Devices;
+    clipboard: boolean;
+};
+/** What an input capture session asks to take. */
+export type InputCaptureBody = {
+    devices: Devices;
+};
 export declare const PortalRequest: {
     Access: (base: PortalRequestBase, body: AccessBody) => {
         /** The id {@link answerPortalRequest} takes. */
@@ -156,6 +175,26 @@ export declare const PortalRequest: {
         body: InhibitBody;
         kind: PortalKind.Inhibit;
     };
+    InputCapture: (base: PortalRequestBase, body: InputCaptureBody) => {
+        /** The id {@link answerPortalRequest} takes. */
+        id: number;
+        /** The asking application's desktop file id. Empty when unknown. */
+        appId: string;
+        /** The `<app>` to show the dialog over, or the focused screen when absent. */
+        parentAppId: string | undefined;
+        body: InputCaptureBody;
+        kind: PortalKind.InputCapture;
+    };
+    RemoteDesktop: (base: PortalRequestBase, body: RemoteDesktopBody) => {
+        /** The id {@link answerPortalRequest} takes. */
+        id: number;
+        /** The asking application's desktop file id. Empty when unknown. */
+        appId: string;
+        /** The `<app>` to show the dialog over, or the focused screen when absent. */
+        parentAppId: string | undefined;
+        body: RemoteDesktopBody;
+        kind: PortalKind.RemoteDesktop;
+    };
     Unknown: (base: PortalRequestBase, wireKind: string) => {
         /** The id {@link answerPortalRequest} takes. */
         id: number;
@@ -175,10 +214,16 @@ export declare enum PortalAnswerKind {
     AppChooser = 1,
     /** The user chose in a {@link PortalKind.FileChooser}. */
     FileChooser = 2,
+    /** The user granted a {@link PortalKind.RemoteDesktop} no more than it asked. */
+    RemoteDesktop = 3,
+    /** The user allowed a {@link PortalKind.InputCapture} request. */
+    InputCapture = 4,
+    /** The user stopped a {@link Capturing} session. */
+    Stop = 5,
     /** The user dismissed or denied the dialog. */
-    Canceled = 3,
+    Canceled = 6,
     /** The shell has no dialog for this kind. */
-    Refused = 4
+    Refused = 7
 }
 export declare const PortalAnswer: {
     Access: () => {
@@ -196,11 +241,65 @@ export declare const PortalAnswer: {
         chosen: FileChosen;
         kind: PortalAnswerKind.FileChooser;
     };
+    InputCapture: () => {
+        kind: PortalAnswerKind.InputCapture;
+    };
     Refused: () => {
         kind: PortalAnswerKind.Refused;
     };
+    RemoteDesktop: (devices: Devices, clipboard: boolean) => {
+        clipboard: boolean;
+        devices: Devices;
+        kind: PortalAnswerKind.RemoteDesktop;
+    };
+    Stop: () => {
+        kind: PortalAnswerKind.Stop;
+    };
 };
 export type PortalAnswer = ReturnType<(typeof PortalAnswer)[keyof typeof PortalAnswer]>;
+export declare enum CapturingKind {
+    /** An application controls input, and the clipboard when `clipboard` is set. */
+    RemoteDesktop = 0,
+    /** An application takes the user's input once it crosses a screen edge. */
+    InputCapture = 1,
+    /** A kind this SDK cannot parse. It can still be stopped. */
+    Unknown = 2
+}
+/** What every capturing session carries. */
+export type CapturingBase = {
+    /** The id {@link stopCapturing} takes. */
+    id: number;
+    /** The application's desktop file id. Empty when unknown. */
+    appId: string;
+};
+export declare const Capturing: {
+    InputCapture: (base: CapturingBase, body: InputCaptureBody) => {
+        devices: Devices;
+        /** The id {@link stopCapturing} takes. */
+        id: number;
+        /** The application's desktop file id. Empty when unknown. */
+        appId: string;
+        kind: CapturingKind.InputCapture;
+    };
+    RemoteDesktop: (base: CapturingBase, body: RemoteDesktopBody) => {
+        devices: Devices;
+        clipboard: boolean;
+        /** The id {@link stopCapturing} takes. */
+        id: number;
+        /** The application's desktop file id. Empty when unknown. */
+        appId: string;
+        kind: CapturingKind.RemoteDesktop;
+    };
+    Unknown: (base: CapturingBase, wireKind: string) => {
+        /** The id {@link stopCapturing} takes. */
+        id: number;
+        /** The application's desktop file id. Empty when unknown. */
+        appId: string;
+        kind: CapturingKind.Unknown;
+        wireKind: string;
+    };
+};
+export type Capturing = ReturnType<(typeof Capturing)[keyof typeof Capturing]>;
 /** What the portal functions need of the desktop `Shell` is handed. */
 export type PortalHost = Pick<DomicileHost, "answerPortalRequest"> & {
     addEventListener: (type: "portalrequests", listener: (event: MessageEvent<string>) => void) => void;
@@ -212,5 +311,12 @@ export type PortalHost = Pick<DomicileHost, "answerPortalRequest"> & {
  * whose body does not parse: the compositor and this SDK disagree.
  */
 export declare const watchPortalRequests: (host: PortalHost, listener: (requests: readonly PortalRequest[]) => void) => (() => void);
+/**
+ * Call `listener` with every session that controls or captures input, on each
+ * change. Returns a function that stops listening.
+ */
+export declare const watchCapturing: (host: PortalHost, listener: (sessions: readonly Capturing[]) => void) => (() => void);
 /** Answer request `id`. The first answer to reach the compositor wins. */
 export declare const answerPortalRequest: (host: PortalHost, id: number, answer: PortalAnswer) => void;
+/** End capturing session `id`. */
+export declare const stopCapturing: (host: PortalHost, id: number) => void;

package/dist/portal.js

@@ -4,6 +4,7 @@
 //
 // The engine relays each request's body untyped; it is parsed here, by kind.
 // A new kind is one schema in `KINDS`, one `PortalKind` and one constructor.
+// The same push lists the sessions that control or capture input.
 import { z } from "zod";
 export var PortalKind;
 (function (PortalKind) {
@@ -18,8 +19,12 @@ export var PortalKind;
      * lets go. Not a question: the compositor refuses answers to it.
      */
     PortalKind[PortalKind["Inhibit"] = 3] = "Inhibit";
+    /** Which input devices, and the clipboard, an application may control. */
+    PortalKind[PortalKind["RemoteDesktop"] = 4] = "RemoteDesktop";
+    /** Whether an application may take input that crosses a screen edge. */
+    PortalKind[PortalKind["InputCapture"] = 5] = "InputCapture";
     /** A kind this SDK cannot parse. Answer it with {@link PortalAnswer.Refused}. */
-    PortalKind[PortalKind["Unknown"] = 4] = "Unknown";
+    PortalKind[PortalKind["Unknown"] = 6] = "Unknown";
 })(PortalKind || (PortalKind = {}));
 /** Which `FileChooser` method asked. */
 export var FileChooserMode;
@@ -59,6 +64,16 @@ export const PortalRequest = {
         body,
         kind: PortalKind.Inhibit,
     }),
+    InputCapture: (base, body) => ({
+        ...base,
+        body,
+        kind: PortalKind.InputCapture,
+    }),
+    RemoteDesktop: (base, body) => ({
+        ...base,
+        body,
+        kind: PortalKind.RemoteDesktop,
+    }),
     Unknown: (base, wireKind) => ({
         ...base,
         kind: PortalKind.Unknown,
@@ -73,10 +88,16 @@ export var PortalAnswerKind;
     PortalAnswerKind[PortalAnswerKind["AppChooser"] = 1] = "AppChooser";
     /** The user chose in a {@link PortalKind.FileChooser}. */
     PortalAnswerKind[PortalAnswerKind["FileChooser"] = 2] = "FileChooser";
+    /** The user granted a {@link PortalKind.RemoteDesktop} no more than it asked. */
+    PortalAnswerKind[PortalAnswerKind["RemoteDesktop"] = 3] = "RemoteDesktop";
+    /** The user allowed a {@link PortalKind.InputCapture} request. */
+    PortalAnswerKind[PortalAnswerKind["InputCapture"] = 4] = "InputCapture";
+    /** The user stopped a {@link Capturing} session. */
+    PortalAnswerKind[PortalAnswerKind["Stop"] = 5] = "Stop";
     /** The user dismissed or denied the dialog. */
-    PortalAnswerKind[PortalAnswerKind["Canceled"] = 3] = "Canceled";
+    PortalAnswerKind[PortalAnswerKind["Canceled"] = 6] = "Canceled";
     /** The shell has no dialog for this kind. */
-    PortalAnswerKind[PortalAnswerKind["Refused"] = 4] = "Refused";
+    PortalAnswerKind[PortalAnswerKind["Refused"] = 7] = "Refused";
 })(PortalAnswerKind || (PortalAnswerKind = {}));
 export const PortalAnswer = {
     Access: () => ({ kind: PortalAnswerKind.Access }),
@@ -90,7 +111,40 @@ export const PortalAnswer = {
         chosen,
         kind: PortalAnswerKind.FileChooser,
     }),
+    InputCapture: () => ({ kind: PortalAnswerKind.InputCapture }),
     Refused: () => ({ kind: PortalAnswerKind.Refused }),
+    RemoteDesktop: (devices, clipboard) => ({
+        clipboard,
+        devices,
+        kind: PortalAnswerKind.RemoteDesktop,
+    }),
+    Stop: () => ({ kind: PortalAnswerKind.Stop }),
+};
+export var CapturingKind;
+(function (CapturingKind) {
+    /** An application controls input, and the clipboard when `clipboard` is set. */
+    CapturingKind[CapturingKind["RemoteDesktop"] = 0] = "RemoteDesktop";
+    /** An application takes the user's input once it crosses a screen edge. */
+    CapturingKind[CapturingKind["InputCapture"] = 1] = "InputCapture";
+    /** A kind this SDK cannot parse. It can still be stopped. */
+    CapturingKind[CapturingKind["Unknown"] = 2] = "Unknown";
+})(CapturingKind || (CapturingKind = {}));
+export const Capturing = {
+    InputCapture: (base, body) => ({
+        ...base,
+        ...body,
+        kind: CapturingKind.InputCapture,
+    }),
+    RemoteDesktop: (base, body) => ({
+        ...base,
+        ...body,
+        kind: CapturingKind.RemoteDesktop,
+    }),
+    Unknown: (base, wireKind) => ({
+        ...base,
+        kind: CapturingKind.Unknown,
+        wireKind,
+    }),
 };
 /**
  * Call `listener` with every unanswered request, oldest first, on each change.
@@ -108,10 +162,29 @@ export const watchPortalRequests = (host, listener) => {
         host.removeEventListener("portalrequests", heard);
     };
 };
+/**
+ * Call `listener` with every session that controls or captures input, on each
+ * change. Returns a function that stops listening.
+ */
+export const watchCapturing = (host, listener) => {
+    const heard = (event) => {
+        listener(requestsSchema
+            .parse(JSON.parse(event.data))
+            .capturing.map((item) => parseCapturing(item)));
+    };
+    host.addEventListener("portalrequests", heard);
+    return () => {
+        host.removeEventListener("portalrequests", heard);
+    };
+};
 /** Answer request `id`. The first answer to reach the compositor wins. */
 export const answerPortalRequest = (host, id, answer) => {
     host.answerPortalRequest(id, JSON.stringify(wireAnswer(answer)));
 };
+/** End capturing session `id`. */
+export const stopCapturing = (host, id) => {
+    answerPortalRequest(host, id, PortalAnswer.Stop());
+};
 const accessSchema = z
     .object({
     body: z.string(),
@@ -190,6 +263,16 @@ const inhibitSchema = z
     reason: body.reason,
     what: body.what.map((inhibited) => INHIBITED[inhibited]),
 }));
+const devicesSchema = z.object({
+    keyboard: z.boolean(),
+    pointer: z.boolean(),
+    touchscreen: z.boolean(),
+});
+const remoteDesktopSchema = z.object({
+    clipboard: z.boolean(),
+    devices: devicesSchema,
+});
+const inputCaptureSchema = z.object({ devices: devicesSchema });
 /** Each kind's wire name, and how to read its body into a request. */
 const KINDS = new Map([
     [
@@ -208,6 +291,25 @@ const KINDS = new Map([
         "inhibit",
         (base, body) => PortalRequest.Inhibit(base, inhibitSchema.parse(body)),
     ],
+    [
+        "remote_desktop",
+        (base, body) => PortalRequest.RemoteDesktop(base, remoteDesktopSchema.parse(body)),
+    ],
+    [
+        "input_capture",
+        (base, body) => PortalRequest.InputCapture(base, inputCaptureSchema.parse(body)),
+    ],
+]);
+/** Each capturing kind's wire name, and how to read its body into a session. */
+const CAPTURING_KINDS = new Map([
+    [
+        "remote_desktop",
+        (base, body) => Capturing.RemoteDesktop(base, remoteDesktopSchema.parse(body)),
+    ],
+    [
+        "input_capture",
+        (base, body) => Capturing.InputCapture(base, inputCaptureSchema.parse(body)),
+    ],
 ]);
 const itemSchema = z.object({
     app_id: z.string(),
@@ -216,7 +318,15 @@ const itemSchema = z.object({
     kind: z.string(),
     parent_app_id: z.string().optional(),
 });
+const capturingSchema = z.object({
+    app_id: z.string(),
+    body: z.unknown(),
+    id: z.number(),
+    kind: z.string(),
+});
 const requestsSchema = z.object({
+    // Optional on the wire, so a line without it parses.
+    capturing: z.array(capturingSchema).default([]),
     items: z.array(itemSchema),
     type: z.literal("portal_requests"),
 });
@@ -241,6 +351,13 @@ const chooserMode = (mode) => {
             return FileChooserMode.SaveFiles;
     }
 };
+const parseCapturing = (item) => {
+    const base = { appId: item.app_id, id: item.id };
+    const parse = CAPTURING_KINDS.get(item.kind);
+    return parse === undefined
+        ? Capturing.Unknown(base, item.kind)
+        : parse(base, item.body);
+};
 /** `answer` as the compositor reads it. */
 const wireAnswer = (answer) => {
     switch (answer.kind) {
@@ -248,6 +365,16 @@ const wireAnswer = (answer) => {
             return { kind: "access" };
         case PortalAnswerKind.AppChooser:
             return { choice: answer.choice, kind: "app_chooser" };
+        case PortalAnswerKind.RemoteDesktop:
+            return {
+                clipboard: answer.clipboard,
+                devices: answer.devices,
+                kind: "remote_desktop",
+            };
+        case PortalAnswerKind.InputCapture:
+            return { kind: "input_capture" };
+        case PortalAnswerKind.Stop:
+            return { kind: "stop" };
         case PortalAnswerKind.Canceled:
             return { kind: "canceled" };
         case PortalAnswerKind.FileChooser:

package/package.json

@@ -96,7 +96,7 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-e040773499e5",
+  "version": "0.0.0-alpha-019dff1d8582",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cprussin/domicile.git",