@domicile-desktop/sdk 0.0.0-alpha-e455955b57c7 → 0.0.0-alpha-cd52ce30fbe6

package/README.md

@@ -68,7 +68,7 @@ See [docs/ELEMENTS.md](docs/ELEMENTS.md) for `<app>` input and focus, and the
 | `./file-preview` | `previewFile(domicile, path)`: a launcher's preview of a path, read through `domicile.files`: a directory's entries, a song's tags and cover, or the start of a text file. |
 | `./dbusmenu` | `watchMenu(domicile, { bus, path })`: a tray item's `com.canonical.dbusmenu` menu, read again on each change, with `click` and `aboutToShow`. Hidden entries are left out; labels lose their mnemonic underscore, and `mnemonic` says where it was. `icon-data` comes as a PNG `data:` URL. See [SYSTEM-TRAY.md](/docs/architecture/SYSTEM-TRAY.md). |
 | `./system` | The types of the compositor's system calls: `SystemError`, `FileType`, `Listening`, … The calls are the desktop's `files`, `processes`, `dbus` and the rest; the compositor refuses most while the desktop is locked. See [SHELL-SYSTEM-ACCESS.md](/docs/SHELL-SYSTEM-ACCESS.md). |
-| `./portal` | The types of application dialogs from `xdg-desktop-portal` (`PortalRequest`, `PortalAnswer`, …) and of running sessions that record the screen or control or capture input (`Capturing`). The desktop's `portals` lists and answers them; `<PortalDialogs />` in component-library draws them. See [PORTALS.md](/docs/PORTALS.md). |
+| `./portal` | The types of application dialogs from `xdg-desktop-portal` (`PortalRequest`, `PortalAnswer`, …) and of running sessions that record the screen or control or capture input (`Capturing`). The desktop's `portals` lists and answers them, and pauses, resumes and discards the shell's own recording; `hideFromCaptures` leaves an element of the shell's out of every capture of the desk; `<PortalDialogs />` in component-library draws them. See [PORTALS.md](/docs/PORTALS.md). |
 | `./global-shortcuts` | `fireGlobalShortcuts`: grab the chords applications hold through the GlobalShortcuts portal and report each press and release. `<PortalDialogs />` calls it. |
 | `./options` | `defineOptions` and `option`: the options a shell declares as its `options` export, which the Settings app edits. `watchShellOptions` reads the config's values of them, live. See [WRITING-A-SHELL.md](/docs/WRITING-A-SHELL.md#options). |
 | `./icon-theme` | `readIconTheme(domicile)`: the config's `theme.icon_theme`, read from the compositor's Settings portal, or `None` for `hicolor` only. `watchIconTheme` reads it and follows `SettingChanged`. `@domicile-desktop/system-apps/app-icons` takes it. |

package/dist/desktop/capture.d.ts

@@ -1,7 +1,9 @@
 import type { System } from "./system-calls";
 export type Capture = {
     screenshot: System["screenshot"];
+    /** Record what the shell's dialog picks; see {@link System.screenRecord}. */
+    screenRecord: System["screenRecord"];
     /** A window as it last drew itself, as a `data:` URL of a PNG. */
     preview: System["previewWindow"];
 };
-export declare const capture: (calls: Pick<System, "previewWindow" | "screenshot">) => Capture;
+export declare const capture: (calls: Pick<System, "previewWindow" | "screenRecord" | "screenshot">) => Capture;

package/dist/desktop/capture.js

@@ -1,6 +1,7 @@
-// Pictures of the desk: a screenshot through the shell's dialog, and a
-// window's last frame for a picker.
+// Pictures of the desk: a screenshot or a screen recording through the shell's
+// dialog, and a window's last frame for a picker.
 export const capture = (calls) => ({
     preview: (window) => calls.previewWindow(window),
+    screenRecord: () => calls.screenRecord(),
     screenshot: () => calls.screenshot(),
 });

package/dist/desktop/portal-wire.d.ts

@@ -32,3 +32,9 @@ export declare const watchPortalWallpaper: (host: PortalHost, listener: (wallpap
 export declare const answerPortalRequest: (host: PortalHost, id: number, answer: PortalAnswer) => void;
 /** End capturing session `id`. */
 export declare const stopCapturing: (host: PortalHost, id: number) => void;
+/** Pause recording `id`. Its file leaves the pause out. */
+export declare const pauseRecording: (host: PortalHost, id: number) => void;
+/** Resume paused recording `id`. */
+export declare const resumeRecording: (host: PortalHost, id: number) => void;
+/** Stop recording `id` and delete its file. */
+export declare const discardRecording: (host: PortalHost, id: number) => void;

package/dist/desktop/portal-wire.js

@@ -59,6 +59,18 @@ export const answerPortalRequest = (host, id, answer) => {
 export const stopCapturing = (host, id) => {
     answerPortalRequest(host, id, PortalAnswer.Stop());
 };
+/** Pause recording `id`. Its file leaves the pause out. */
+export const pauseRecording = (host, id) => {
+    answerPortalRequest(host, id, PortalAnswer.Pause());
+};
+/** Resume paused recording `id`. */
+export const resumeRecording = (host, id) => {
+    answerPortalRequest(host, id, PortalAnswer.Resume());
+};
+/** Stop recording `id` and delete its file. */
+export const discardRecording = (host, id) => {
+    answerPortalRequest(host, id, PortalAnswer.Discard());
+};
 /** Each `portal_requests` push, parsed. */
 const watch = (host, listener) => {
     const heard = (event) => {
@@ -263,6 +275,19 @@ const capturedSchema = z
     }
 });
 const screenCastingSchema = z.object({ sources: z.array(capturedSchema) });
+const recordingSchema = z
+    .object({
+    file: z.string(),
+    recorded_ms: z.number(),
+    running_since_ms: z.number().optional(),
+    sources: z.array(capturedSchema),
+})
+    .transform((recording) => ({
+    file: recording.file,
+    recordedMs: recording.recorded_ms,
+    runningSinceMs: recording.running_since_ms,
+    sources: recording.sources,
+}));
 const shortcutsSchema = z
     .object({
     shortcuts: z.array(z.object({
@@ -539,6 +564,10 @@ const CAPTURING_KINDS = new Map([
         "screen_cast",
         (base, body) => Capturing.ScreenCast(base, screenCastingSchema.parse(body)),
     ],
+    [
+        "recording",
+        (base, body) => Capturing.Recording(base, recordingSchema.parse(body)),
+    ],
 ]);
 const itemSchema = z.object({
     app_id: z.string(),
@@ -623,6 +652,12 @@ const wireAnswer = (answer) => {
             };
         case PortalAnswerKind.Stop:
             return { kind: "stop" };
+        case PortalAnswerKind.Pause:
+            return { kind: "pause" };
+        case PortalAnswerKind.Resume:
+            return { kind: "resume" };
+        case PortalAnswerKind.Discard:
+            return { kind: "discard" };
         case PortalAnswerKind.Canceled:
             return { kind: "canceled" };
         case PortalAnswerKind.DynamicLauncher:

package/dist/desktop/portals.d.ts

@@ -19,6 +19,12 @@ export type Portals = {
     answer: (id: number, answer: PortalAnswer) => void;
     /** End capturing session `id`. */
     stopCapturing: (id: number) => void;
+    /** Pause the shell's screen recording `id`. */
+    pauseRecording: (id: number) => void;
+    /** Resume the shell's paused screen recording `id`. */
+    resumeRecording: (id: number) => void;
+    /** End the shell's screen recording `id` and delete its file. */
+    discardRecording: (id: number) => void;
     /**
      * Tell the application holding bound shortcut `id` its chord went down or
      * up. See {@link Portals.boundShortcuts}.

package/dist/desktop/portals.js

@@ -1,7 +1,7 @@
 // Portal dialogs and the sessions they started: Domicile is the only
 // xdg-desktop-portal backend, and the shell draws its dialogs. See
 // docs/PORTALS.md.
-import { answerPortalRequest, stopCapturing, watchBoundShortcuts, watchCapturing, watchPortalRequests, watchPortalWallpaper, } from "./portal-wire";
+import { answerPortalRequest, discardRecording, pauseRecording, resumeRecording, stopCapturing, watchBoundShortcuts, watchCapturing, watchPortalRequests, watchPortalWallpaper, } from "./portal-wire";
 import { hostEvent, on } from "./subscribe";
 /** Listens from the start: the engine sends the latest push to a new listener. */
 export const portals = (host) => {
@@ -28,15 +28,24 @@ export const portals = (host) => {
         get capturing() {
             return latest.capturing;
         },
+        discardRecording: (id) => {
+            discardRecording(host, id);
+        },
         fireShortcut: (id, kind) => {
             host.answerPortalRequest(id, JSON.stringify({ kind }));
         },
         on: on({
             change: (listener) => hostEvent(host, "portalrequests", () => listener()),
         }),
+        pauseRecording: (id) => {
+            pauseRecording(host, id);
+        },
         get requests() {
             return latest.requests;
         },
+        resumeRecording: (id) => {
+            resumeRecording(host, id);
+        },
         stopCapturing: (id) => {
             stopCapturing(host, id);
         },

package/dist/desktop/system-calls.d.ts

@@ -38,6 +38,13 @@ export type System = {
      * the user presses Ctrl+C. Resolves with where it went.
      */
     screenshot: () => Promise<Result<ScreenshotKept, SystemError>>;
+    /**
+     * Record the screen: `<PortalDialogs />` draws the screen cast picker, and
+     * what is picked is recorded, with its sound, until its toolbar stops it.
+     * Resolves with the WebM under `$XDG_VIDEOS_DIR/Screen recordings/`, or
+     * fails `Canceled` when the picker is dismissed or the recording discarded.
+     */
+    screenRecord: () => Promise<Result<string, SystemError>>;
     /**
      * Draw `window` as it last drew itself, as a `data:` URL of a PNG, for a
      * picker to preview a window that is not on screen. A browser window's page

package/dist/desktop/system-calls.js

@@ -76,6 +76,7 @@ export const system = (host) => {
             ]);
             return exited.map((exit) => ({ ...exit, stderr, stdout }));
         }),
+        screenRecord: () => oneShot(calls, { call: "screen_record" }, (reply) => reply.kind === "saved" ? reply.path : unexpected(reply)),
         screenshot: () => oneShot(calls, { call: "screenshot" }, (reply) => keptOf(reply)),
         selectKeymap: (choice) => oneShot(calls, { call: "select_keymap", keymap: wireKeymapChoice(choice) }, (reply) => (reply.kind === "set" ? "set" : unexpected(reply))),
         setWindowStates: (appId, states) => oneShot(calls, {

package/dist/portal.d.ts

@@ -468,6 +468,19 @@ export declare const Captured: {
 };
 /** One source a running screen cast records. */
 export type Captured = ReturnType<(typeof Captured)[keyof typeof Captured]>;
+/** A {@link CapturingKind.Recording}: what it records, where, and for how long. */
+export type RecordingBody = {
+    sources: readonly Captured[];
+    /** The absolute path of the WebM it records into. */
+    file: string;
+    /** How long it recorded until `runningSinceMs`, or until it paused. */
+    recordedMs: number;
+    /**
+     * When it last started or resumed, in milliseconds since the Unix epoch, as
+     * `Date.now()` counts. Undefined while it is paused.
+     */
+    runningSinceMs: number | undefined;
+};
 /** IPP's `sides`. */
 export declare enum Sides {
     OneSided = 0,
@@ -729,32 +742,38 @@ export declare enum PortalAnswerKind {
     ScreenCast = 5,
     /** The user stopped a {@link Capturing} session. */
     Stop = 6,
+    /** The user paused a {@link CapturingKind.Recording}. */
+    Pause = 7,
+    /** The user resumed a paused {@link CapturingKind.Recording}. */
+    Resume = 8,
+    /** The user stopped a {@link CapturingKind.Recording} and threw it away. */
+    Discard = 9,
     /** The chords the user chose in a {@link PortalKind.GlobalShortcuts} review. */
-    GlobalShortcuts = 7,
+    GlobalShortcuts = 10,
     /** The name the user installs a {@link PortalKind.DynamicLauncher} under. */
-    DynamicLauncher = 8,
+    DynamicLauncher = 11,
     /** The printer and options the user chose in a {@link PortalKind.Print}. */
-    Print = 9,
+    Print = 12,
     /** The file a {@link PortalKind.Print} saves its PDF to, and its options. */
-    SaveToPdf = 10,
+    SaveToPdf = 13,
     /** The area of a {@link PortalKind.Screenshot} the user kept. */
-    Screenshot = 11,
+    Screenshot = 14,
     /**
      * The window of a {@link PortalKind.Screenshot} the user picked, saved from
      * its own last frame.
      */
-    ScreenshotWindow = 12,
+    ScreenshotWindow = 15,
     /**
      * A browser window of a {@link PortalKind.Screenshot} the user picked, saved
      * from the engine's capture of its page alone.
      */
-    ScreenshotBrowserWindow = 13,
+    ScreenshotBrowserWindow = 16,
     /** The pixel of a {@link PortalKind.PickColor} the user picked. */
-    PickColor = 14,
+    PickColor = 17,
     /** The user dismissed or denied the dialog. */
-    Canceled = 15,
+    Canceled = 18,
     /** The shell has no dialog for this kind. */
-    Refused = 16
+    Refused = 19
 }
 export declare const PortalAnswer: {
     Access: () => {
@@ -768,6 +787,9 @@ export declare const PortalAnswer: {
     Canceled: () => {
         kind: PortalAnswerKind.Canceled;
     };
+    Discard: () => {
+        kind: PortalAnswerKind.Discard;
+    };
     /** Not empty; the request's own name unless `editableName`. */
     DynamicLauncher: (name: string) => {
         kind: PortalAnswerKind.DynamicLauncher;
@@ -784,6 +806,9 @@ export declare const PortalAnswer: {
     InputCapture: () => {
         kind: PortalAnswerKind.InputCapture;
     };
+    Pause: () => {
+        kind: PortalAnswerKind.Pause;
+    };
     /** A pixel inside the request's frame. */
     PickColor: (at: {
         x: number;
@@ -809,6 +834,9 @@ export declare const PortalAnswer: {
         devices: Devices;
         kind: PortalAnswerKind.RemoteDesktop;
     };
+    Resume: () => {
+        kind: PortalAnswerKind.Resume;
+    };
     /** An absolute `path`; `options` within the request's `pdf`. */
     SaveToPdf: (path: string, options: PrintOptions) => {
         kind: PortalAnswerKind.SaveToPdf;
@@ -861,8 +889,13 @@ export declare enum CapturingKind {
     InputCapture = 1,
     /** An application records windows, monitors or a region. */
     ScreenCast = 2,
+    /**
+     * The shell's own screen recording, which `System.screenRecord` started.
+     * Paused, resumed and discarded as well as stopped.
+     */
+    Recording = 3,
     /** A kind this SDK cannot parse. It can still be stopped. */
-    Unknown = 3
+    Unknown = 4
 }
 /** What every capturing session carries. */
 export type CapturingBase = {
@@ -880,6 +913,23 @@ export declare const Capturing: {
         appId: string;
         kind: CapturingKind.InputCapture;
     };
+    Recording: (base: CapturingBase, body: RecordingBody) => {
+        sources: readonly Captured[];
+        /** The absolute path of the WebM it records into. */
+        file: string;
+        /** How long it recorded until `runningSinceMs`, or until it paused. */
+        recordedMs: number;
+        /**
+         * When it last started or resumed, in milliseconds since the Unix epoch, as
+         * `Date.now()` counts. Undefined while it is paused.
+         */
+        runningSinceMs: number | undefined;
+        /** The id {@link stopCapturing} takes. */
+        id: number;
+        /** The application's desktop file id. Empty when unknown. */
+        appId: string;
+        kind: CapturingKind.Recording;
+    };
     RemoteDesktop: (base: CapturingBase, body: RemoteDesktopBody) => {
         devices: Devices;
         clipboard: boolean;
@@ -909,3 +959,19 @@ export declare const Capturing: {
     };
 };
 export type Capturing = ReturnType<(typeof Capturing)[keyof typeof Capturing]>;
+/** Element Capture's `RestrictionTarget`, which TypeScript's DOM lacks. */
+type RestrictionTargets = {
+    fromElement: (element: Element) => Promise<unknown>;
+};
+/**
+ * Leave `element` out of every capture of the desk: screen recordings, screen
+ * casts and screenshots. It still shows on screen. For the shell's page only;
+ * see `docs/PORTALS.md#screen-recording`.
+ *
+ * The element must be a stacking context and its own group, such as with
+ * `isolation: isolate`, or Element Capture ignores it. `targets` is
+ * `RestrictionTarget`, absent in an engine without Element Capture, where this
+ * does nothing.
+ */
+export declare const hideFromCaptures: (element: Element, targets?: RestrictionTargets | undefined) => Promise<void>;
+export {};

package/dist/portal.js

@@ -272,32 +272,38 @@ export var PortalAnswerKind;
     PortalAnswerKind[PortalAnswerKind["ScreenCast"] = 5] = "ScreenCast";
     /** The user stopped a {@link Capturing} session. */
     PortalAnswerKind[PortalAnswerKind["Stop"] = 6] = "Stop";
+    /** The user paused a {@link CapturingKind.Recording}. */
+    PortalAnswerKind[PortalAnswerKind["Pause"] = 7] = "Pause";
+    /** The user resumed a paused {@link CapturingKind.Recording}. */
+    PortalAnswerKind[PortalAnswerKind["Resume"] = 8] = "Resume";
+    /** The user stopped a {@link CapturingKind.Recording} and threw it away. */
+    PortalAnswerKind[PortalAnswerKind["Discard"] = 9] = "Discard";
     /** The chords the user chose in a {@link PortalKind.GlobalShortcuts} review. */
-    PortalAnswerKind[PortalAnswerKind["GlobalShortcuts"] = 7] = "GlobalShortcuts";
+    PortalAnswerKind[PortalAnswerKind["GlobalShortcuts"] = 10] = "GlobalShortcuts";
     /** The name the user installs a {@link PortalKind.DynamicLauncher} under. */
-    PortalAnswerKind[PortalAnswerKind["DynamicLauncher"] = 8] = "DynamicLauncher";
+    PortalAnswerKind[PortalAnswerKind["DynamicLauncher"] = 11] = "DynamicLauncher";
     /** The printer and options the user chose in a {@link PortalKind.Print}. */
-    PortalAnswerKind[PortalAnswerKind["Print"] = 9] = "Print";
+    PortalAnswerKind[PortalAnswerKind["Print"] = 12] = "Print";
     /** The file a {@link PortalKind.Print} saves its PDF to, and its options. */
-    PortalAnswerKind[PortalAnswerKind["SaveToPdf"] = 10] = "SaveToPdf";
+    PortalAnswerKind[PortalAnswerKind["SaveToPdf"] = 13] = "SaveToPdf";
     /** The area of a {@link PortalKind.Screenshot} the user kept. */
-    PortalAnswerKind[PortalAnswerKind["Screenshot"] = 11] = "Screenshot";
+    PortalAnswerKind[PortalAnswerKind["Screenshot"] = 14] = "Screenshot";
     /**
      * The window of a {@link PortalKind.Screenshot} the user picked, saved from
      * its own last frame.
      */
-    PortalAnswerKind[PortalAnswerKind["ScreenshotWindow"] = 12] = "ScreenshotWindow";
+    PortalAnswerKind[PortalAnswerKind["ScreenshotWindow"] = 15] = "ScreenshotWindow";
     /**
      * A browser window of a {@link PortalKind.Screenshot} the user picked, saved
      * from the engine's capture of its page alone.
      */
-    PortalAnswerKind[PortalAnswerKind["ScreenshotBrowserWindow"] = 13] = "ScreenshotBrowserWindow";
+    PortalAnswerKind[PortalAnswerKind["ScreenshotBrowserWindow"] = 16] = "ScreenshotBrowserWindow";
     /** The pixel of a {@link PortalKind.PickColor} the user picked. */
-    PortalAnswerKind[PortalAnswerKind["PickColor"] = 14] = "PickColor";
+    PortalAnswerKind[PortalAnswerKind["PickColor"] = 17] = "PickColor";
     /** The user dismissed or denied the dialog. */
-    PortalAnswerKind[PortalAnswerKind["Canceled"] = 15] = "Canceled";
+    PortalAnswerKind[PortalAnswerKind["Canceled"] = 18] = "Canceled";
     /** The shell has no dialog for this kind. */
-    PortalAnswerKind[PortalAnswerKind["Refused"] = 16] = "Refused";
+    PortalAnswerKind[PortalAnswerKind["Refused"] = 19] = "Refused";
 })(PortalAnswerKind || (PortalAnswerKind = {}));
 export const PortalAnswer = {
     Access: () => ({ kind: PortalAnswerKind.Access }),
@@ -307,6 +313,7 @@ export const PortalAnswer = {
         kind: PortalAnswerKind.AppChooser,
     }),
     Canceled: () => ({ kind: PortalAnswerKind.Canceled }),
+    Discard: () => ({ kind: PortalAnswerKind.Discard }),
     /** Not empty; the request's own name unless `editableName`. */
     DynamicLauncher: (name) => ({
         kind: PortalAnswerKind.DynamicLauncher,
@@ -321,6 +328,7 @@ export const PortalAnswer = {
         triggers,
     }),
     InputCapture: () => ({ kind: PortalAnswerKind.InputCapture }),
+    Pause: () => ({ kind: PortalAnswerKind.Pause }),
     /** A pixel inside the request's frame. */
     PickColor: (at) => ({
         at,
@@ -338,6 +346,7 @@ export const PortalAnswer = {
         devices,
         kind: PortalAnswerKind.RemoteDesktop,
     }),
+    Resume: () => ({ kind: PortalAnswerKind.Resume }),
     /** An absolute `path`; `options` within the request's `pdf`. */
     SaveToPdf: (path, options) => ({
         kind: PortalAnswerKind.SaveToPdf,
@@ -388,8 +397,13 @@ export var CapturingKind;
     CapturingKind[CapturingKind["InputCapture"] = 1] = "InputCapture";
     /** An application records windows, monitors or a region. */
     CapturingKind[CapturingKind["ScreenCast"] = 2] = "ScreenCast";
+    /**
+     * The shell's own screen recording, which `System.screenRecord` started.
+     * Paused, resumed and discarded as well as stopped.
+     */
+    CapturingKind[CapturingKind["Recording"] = 3] = "Recording";
     /** A kind this SDK cannot parse. It can still be stopped. */
-    CapturingKind[CapturingKind["Unknown"] = 3] = "Unknown";
+    CapturingKind[CapturingKind["Unknown"] = 4] = "Unknown";
 })(CapturingKind || (CapturingKind = {}));
 export const Capturing = {
     InputCapture: (base, body) => ({
@@ -397,6 +411,11 @@ export const Capturing = {
         ...body,
         kind: CapturingKind.InputCapture,
     }),
+    Recording: (base, body) => ({
+        ...base,
+        ...body,
+        kind: CapturingKind.Recording,
+    }),
     RemoteDesktop: (base, body) => ({
         ...base,
         ...body,
@@ -413,3 +432,16 @@ export const Capturing = {
         wireKind,
     }),
 };
+/**
+ * Leave `element` out of every capture of the desk: screen recordings, screen
+ * casts and screenshots. It still shows on screen. For the shell's page only;
+ * see `docs/PORTALS.md#screen-recording`.
+ *
+ * The element must be a stacking context and its own group, such as with
+ * `isolation: isolate`, or Element Capture ignores it. `targets` is
+ * `RestrictionTarget`, absent in an engine without Element Capture, where this
+ * does nothing.
+ */
+export const hideFromCaptures = async (element, targets = globalThis.RestrictionTarget) => {
+    await targets?.fromElement(element);
+};

package/package.json

@@ -236,7 +236,7 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-e455955b57c7",
+  "version": "0.0.0-alpha-cd52ce30fbe6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cprussin/domicile.git",