@domicile-desktop/sdk 0.0.0-alpha-028d5f9f87e0 → 0.0.0-alpha-e040773499e5

package/README.md

@@ -51,7 +51,7 @@ See [docs/ELEMENTS.md](docs/ELEMENTS.md) for `<app>` input and focus, and the
 
 | Module | What it is |
 | --- | --- |
-| `./domicile-host` | `DomicileHost`: the type of the desktop `Shell` is handed, mirroring the engine's IDL. |
+| `./domicile-host` | `DomicileHost`: the type of the desktop `Shell` is handed. Generated from the engine's IDL; see [Generated types](#generated-types). |
 | `./shell` | `Shell`: the export a shell module must provide. Domicile calls it once with the element to draw in. |
 | `./app-element`, `./webview-element` | Types and event names for `<app>` and `<webview>`. |
 | `./bind-keys` | `bindKeys`: grab a shell's own chords by name and handle them by mode. `./key-action` and `./own-keybindings` are its parts. |
@@ -66,6 +66,22 @@ The compositor's JSON socket protocol lives in
 [`@domicile-desktop/e2e-harness`](../e2e-harness/README.md); a page never
 speaks it.
 
+## Generated types
+
+`src/domicile-host.ts` is generated from the engine's WebIDL in
+`packages/domicile-engine/src/third_party/blink/renderer/modules/domicile/`,
+with the IDL's comments as its docs. Do not edit it.
+
+```sh
+bun run generate    # after changing the IDL
+```
+
+- `codegen/` holds the generator: a parser for the IDL subset the engine uses,
+  and the TypeScript it emits. It throws on syntax outside that subset.
+- `EVENT_TYPES` in `codegen/generate-domicile-host.ts` names the event type
+  each `on<name>` handler dispatches, which WebIDL cannot express.
+- `scripts/test-host-types-match-the-idl.sh` fails when the file is stale.
+
 ## Dependencies
 
 - `zod` only. Its schemas parse the keywords and rows a newer engine may send

package/dist/domicile-host.d.ts

@@ -1,540 +1,775 @@
-import type { CursorShape } from "./cursor-shape";
-import type { Theme } from "./theme";
-import type { TrayAction } from "./tray";
 /**
- * A key combination the shell claims, matching {@link DomicileShortcutEvent}.
+ * The cursors a client can ask the chrome to show over its window.
  *
- * An omitted modifier defaults to `false`, so it must not be held.
+ * The `wp_cursor_shape_v1` shapes, named by the CSS `cursor` keyword the
+ * chrome assigns, plus `none` for a hidden cursor. The same set is defined by
+ * `domicile_protocol::CursorShape`, `components/domicile/common/cursor_shape.h`
+ * and `cursorShapeSchema` in `@domicile/chrome-sdk`.
+ *
+ * An enum, not a DOMString, so the bindings reject unknown values. CSS ignores
+ * an unknown cursor keyword, so a bad value would otherwise show the wrong
+ * cursor with no error.
+ *
+ * Keep the values in the same order as the other lists:
+ * `scripts/test-cursor-shapes-agree.sh` compares all four as sequences.
  */
-export type DomicileShortcut = {
-    /** An evdev code. Zero is not a key and the engine refuses it. */
-    keycode: number;
-    altKey?: boolean;
-    ctrlKey?: boolean;
-    shiftKey?: boolean;
-    metaKey?: boolean;
-};
+export type DomicileCursorShape = "none" | "default" | "context-menu" | "help" | "pointer" | "progress" | "wait" | "cell" | "crosshair" | "text" | "vertical-text" | "alias" | "copy" | "move" | "no-drop" | "not-allowed" | "grab" | "grabbing" | "e-resize" | "n-resize" | "ne-resize" | "nw-resize" | "s-resize" | "se-resize" | "sw-resize" | "w-resize" | "ew-resize" | "ns-resize" | "nesw-resize" | "nwse-resize" | "col-resize" | "row-resize" | "all-scroll" | "zoom-in" | "zoom-out";
 /**
- * One screen of the desktop.
+ * The desktop's light or dark theme.
  *
- * Sizes are integers because they come from the config, not from layout.
+ * One of four copies of this set: `domicile_protocol::Theme`,
+ * `components/domicile/common/theme.h`, this enum, and `themeSchema` in
+ * `@domicile/chrome-sdk`.
+ *
+ * An enum rather than a `DOMString` because `setTheme()` takes it, so the
+ * bindings reject an invalid value at the call. There is no `system` value:
+ * the compositor owns the theme.
+ *
+ * Keep the order in sync with the other copies. `mojom::Theme` is numbered by
+ * position, and `scripts/test-themes-agree.sh` compares the order.
  */
-export type DomicileDisplay = {
+export type DomicileTheme = "dark" | "light";
+/**
+ * Which button clicked a tray icon: StatusNotifierItem's Activate,
+ * SecondaryActivate and ContextMenu.
+ *
+ * An enum rather than a `DOMString` because activateTrayItem() takes it, so
+ * the bindings reject an invalid value at the call.
+ *
+ * Keep the order in sync with `mojom::TrayAction`, which is numbered by
+ * position.
+ */
+export type DomicileTrayAction = "primary" | "secondary" | "context";
+export type DomicileAppEventInit = EventInit & {
+    appId?: string;
+};
+/** What `DomicileHost.previewFile()` resolves with. */
+export type DomicileFilePreview = {
     /**
-     * The screen's name from the config, such as `left`, or `domicile-0` when
-     * Domicile runs in a window instead of driving displays.
+     * Which of the rest means anything: "text", "directory", "audio", "binary"
+     * or "unreadable". "unreadable" is also what a path outside the compositor's
+     * index of the home gets -- see previewFile(). A DOMString rather than an
+     * enum: the browser drops an answer whose kind is not one of the five.
      */
-    readonly name: string;
+    readonly kind: string;
+    /** The front of the file, for "text". */
+    readonly text: string;
+    /** What is in it, for "directory": names, a subdirectory ending in `/`. */
+    readonly entries: readonly string[];
     /**
-     * The top-left corner in desktop coordinates, which start at the top-left
-     * of the displays' bounding box. Can be negative.
+     * What a song says of itself, for "audio": each tag empty when it does not
+     * say it.
      */
-    readonly x: number;
-    readonly y: number;
-    /** Logical size in CSS pixels. The `wl_output` mode is this × `scale`. */
-    readonly width: number;
-    readonly height: number;
+    readonly title: string;
+    readonly artist: string;
+    readonly album: string;
+    /** How long it plays, in seconds, for "audio". */
+    readonly duration: number;
     /**
-     * The scale clients on this screen render at. This is not the shell's
-     * `devicePixelRatio`; do not use it for layout.
+     * The picture it carries of itself, for "audio", as a `data:` URL -- the
+     * page cannot read the file to draw one of its own.
      */
-    readonly scale: number;
+    readonly cover: string;
+};
+/** What `DomicileHost.searchFiles()` resolves with. */
+export type DomicileFileSearch = {
     /**
-     * The panel's physical mode in pixels, before rotation.
-     *
-     * It cannot be derived from `width`, `height` and `scale`. Zero when the
-     * compositor reports no mode. For display only.
+     * The front of what matched: paths relative to the home directory the
+     * desktop is running as -- `Notes/today.org`, not
+     * `/home/you/Notes/today.org` -- already in the order they go on screen, and
+     * a directory ends in `/`. Empty is a query that matched nothing.
      */
-    readonly modeWidth: number;
-    readonly modeHeight: number;
+    readonly files: readonly string[];
+    /** How many paths matched, of which `files` is the front. */
+    readonly matched: number;
     /**
-     * The monitor's rotation: `normal`, `rotate-90`, `rotate-180` or
-     * `rotate-270`.
+     * Whether the compositor is still building the index this was found in.
      *
-     * Uses `wl_output` naming, which counts counterclockwise: `rotate-90` turns
-     * content a quarter turn counterclockwise.
+     * THE DIFFERENCE BETWEEN AN INCOMPLETE ANSWER AND A WRONG ONE. The rows are
+     * a launcher's whole evidence that a file exists, so an answer from an index
+     * still being walked has to arrive saying so. A shell draws this as a line
+     * saying the index is being built, and asks again.
      */
-    readonly transform: string;
+    readonly indexing: boolean;
 };
 /**
- * One client window, as {@link DomicileHost.windows} lists it: what the
- * compositor has said about it so far. Replaced, never edited — any change is
- * a new `windows` array and a `windowschanged`.
+ * A key combination the desktop grabs.
+ *
+ * Same fields as `DomicileShortcutEvent`, so a shell can compare a press
+ * against it directly. `keycode` is a Linux evdev code; `KeyboardEvent.key` is
+ * already a string such as "Enter".
  */
-export type DomicileWindow = {
-    readonly appId: string;
-    /** Empty until the client names itself. */
-    readonly title: string;
-    /** The size the client last committed, in CSS pixels; `null` until it has. */
-    readonly width: number | null;
-    readonly height: number | null;
-    /** The limits the client asked for; `null` where it asked for none. */
-    readonly minWidth: number | null;
-    readonly minHeight: number | null;
-    readonly maxWidth: number | null;
-    readonly maxHeight: number | null;
-    readonly cursor: CursorShape;
-    /** A popup's parent window; `null` for a toplevel. */
-    readonly parent: string | null;
-    /** A popup's place relative to its parent; `null` for a toplevel. */
-    readonly x: number | null;
-    readonly y: number | null;
-    /** Whether a popup grabbed the pointer; `false` for a toplevel. */
-    readonly grab: boolean;
+export type DomicileShortcut = {
+    keycode: number;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    metaKey?: boolean;
+};
+export type DomicileShortcutEventInit = EventInit & {
+    chord?: string;
+    keycode?: number;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    metaKey?: boolean;
 };
 /**
- * A client asked for the keyboard (`focusrequested`). Focus has not moved; the
- * shell answers with {@link DomicileHost.focusApp} or ignores it.
+ * The event behind DomicileHost.onfocusrequested: a client asked for the
+ * keyboard.
  */
 export type DomicileAppEvent = Event & {
-    /** The window's id. */
+    /** The window that asked: the id an <app> element names. */
     readonly appId: string;
 };
-/** A combination claimed with `grabShortcut()` was pressed. */
-export type DomicileShortcutEvent = Event & {
-    /**
-     * The chord as {@link DomicileHost.grabShortcut} was given it by name —
-     * `Meta+Shift+l` — or empty for one grabbed as a keycode.
-     */
-    readonly chord: string;
-    readonly keycode: number;
-    readonly altKey: boolean;
-    readonly ctrlKey: boolean;
-    readonly shiftKey: boolean;
-    readonly metaKey: boolean;
-};
 /**
- * The answer {@link DomicileHost.previewFile} resolves with.
+ * One of the desk's browser windows: a page the browser holds, drawn with
+ * `<webview window="id">`. See components/domicile/mojom/browser_windows.mojom.
  *
- * `kind` is `text`, `directory`, `audio`, `binary` or `unreadable`. Only the
- * fields for that kind are filled; the rest are empty.
+ * An interface for DomicileDisplay's reason: these are read from the
+ * desktop's `browserWindows` attribute, and WebIDL forbids a dictionary as an
+ * attribute type.
  */
-export type DomicileFilePreview = {
-    readonly kind: string;
-    /** The start of the file, for a `text` preview. */
-    readonly text: string;
-    /** The first entries, for a `directory` preview. */
-    readonly entries: readonly string[];
-    /** Tags for an `audio` preview; empty when missing. */
+export type DomicileBrowserWindow = {
+    /**
+     * The id `<webview window>` and closeBrowserWindow() use. Never reused while
+     * the browser runs.
+     */
+    readonly id: string;
+    /** The page's address. Empty before it has shown anything. */
+    readonly url: string;
+    /** The page's title. Empty when the page has none. */
     readonly title: string;
-    readonly artist: string;
-    readonly album: string;
-    /** Length of an `audio` preview, in seconds. */
-    readonly duration: number;
-    /** Cover art of an `audio` preview, as a `data:` URL. */
-    readonly cover: string;
+    /**
+     * The extension popup window (chrome.windows) whose one tab this is. Null
+     * for a tab of the desk's own window.
+     */
+    readonly popupWindow: number | null;
+    /**
+     * The size the popup window asked for, in CSS pixels. 0 on an axis it left
+     * unset.
+     */
+    readonly width: number;
+    readonly height: number;
 };
 /**
- * The answer {@link DomicileHost.searchFiles} resolves with. The home's index
- * never crosses into the page.
+ * One thing that was copied, as a row of the clipboard's history.
  *
- * Paths are relative to the home directory and sorted; directories end in
- * `/`. Only the first matches are included; `matched` counts them all.
+ * An interface rather than a dictionary because WebIDL will not have a
+ * dictionary as the element type of an attribute's array, which is how these
+ * are read -- off DomicileHost.clipboard rather than handed over in a call.
  */
-export type DomicileFileSearch = {
-    readonly files: readonly string[];
-    /** The total number of matches; {@link files} holds the first of them. */
-    readonly matched: number;
-    /**
-     * Whether the compositor is still building the index.
-     *
-     * When true, the results may be incomplete. Show them and search again.
-     */
-    readonly indexing: boolean;
-};
-/** One entry in the clipboard history. */
 export type DomicileClipboardEntry = {
     /**
-     * The id to pass to {@link DomicileHost.copyClipboardEntry}.
+     * What DomicileHost.copyClipboardEntry() names this row by.
      *
-     * Never reused, and stable when the list is reordered.
+     * Assigned by the compositor and never reused, so an id a shell is holding
+     * either names the row it was told about or names nothing at all. NOT a
+     * position: the list a copy re-orders keeps every id it had.
      */
     readonly id: number;
     /**
-     * The copied text, truncated if long. Copying the entry back restores the
-     * full content.
+     * Enough of what was copied to recognize it by, and not necessarily all of
+     * it: a long copy is cut down to a row, because this is what a panel draws
+     * and the rest of a copied file is not a row.
+     *
+     * What goes back on the clipboard is always the whole thing, which is the
+     * reason a row is an id and a preview rather than the text: the bytes stay
+     * in the compositor, and a password manager's copy is a row in this list.
      */
     readonly preview: string;
 };
-/** One system tray icon. */
-export type DomicileTrayItem = {
-    /** The id to pass to {@link DomicileHost.activateTrayItem}. */
-    readonly id: string;
-    /** A text label. Never empty. */
-    readonly title: string;
-    /** The icon as a `data:` URL, or empty if it could not be drawn. */
-    readonly icon: string;
-};
-/** One button of a notification. */
-export type DomicileNotificationAction = {
-    /** The key to pass to {@link DomicileHost.invokeNotificationAction}. */
-    readonly key: string;
-    /** The button text. */
-    readonly label: string;
-};
-/** One notification. */
-export type DomicileNotification = {
-    /** The id the host's dismiss and invoke calls take. */
-    readonly id: number;
-    /** The sender's name; may be empty. */
-    readonly appName: string;
-    readonly summary: string;
-    /** Plain text, never markup; may be empty. */
-    readonly body: string;
-    /** A `data:` URL, or empty. */
-    readonly icon: string;
-    /** `"low"`, `"normal"` or `"critical"`. */
-    readonly urgency: string;
-    readonly actions: readonly DomicileNotificationAction[];
-    /** Whether it offers the `"default"` action, triggered by clicking it. */
-    readonly clickable: boolean;
-    /**
-     * Requested display time in milliseconds: `0` until dismissed, `-1` for
-     * the shell's default.
-     */
-    readonly timeoutMs: number;
-    /** Milliseconds since the epoch, on the compositor's clock. */
-    readonly time: number;
-};
 /**
- * A browser window, drawn with `<webview window={id}>`.
+ * One screen of the desktop.
+ *
+ * An interface because WebIDL does not allow a dictionary as an attribute type.
  *
- * The engine holds the page, so it outlives the shell's document. After
- * `domicile load-shell` the new shell gets the same windows. See
- * docs/SHELL-BROWSER-WINDOWS.md.
+ * Sizes are integers because the desktop config uses whole pixels. Other sizes
+ * on this channel come from layout boxes and are fractional.
  */
-export type DomicileBrowserWindow = {
-    /**
-     * The id `<webview window>` and {@link DomicileHost.closeBrowserWindow} take.
-     * Never reused while the browser runs.
-     */
-    readonly id: string;
-    /** The page's address. Empty before the page has loaded. */
-    readonly url: string;
-    /** The page's title. Empty when the page has none. */
-    readonly title: string;
+export type DomicileDisplay = {
     /**
-     * The extension popup window (`chrome.windows` id) whose one tab this is.
-     * `null` for an ordinary browser window.
+     * The compositor's name for this screen from the config, such as `left`.
+     * `domicile-0` when Domicile runs in a window instead of driving displays.
      */
-    readonly popupWindow: number | null;
+    readonly name: string;
     /**
-     * The size the popup window asked for, in CSS pixels. 0 on an axis it left
-     * unset.
+     * The top-left corner in desktop coordinates. The origin is the top-left of
+     * the displays' bounding box. Signed because the config can place a display
+     * left of or above the origin.
      */
+    readonly x: number;
+    readonly y: number;
+    /** The logical size, in the CSS pixels a shell lays out in. */
     readonly width: number;
     readonly height: number;
+    /**
+     * The scale advertised to Wayland clients on this screen. This is not the
+     * shell's `devicePixelRatio`: the shell is one page at one density across
+     * all screens.
+     */
+    readonly scale: number;
+    /**
+     * The panel's mode in physical pixels, before rotation. A portrait 4K
+     * panel has a 3840x2160 mode and an 1800x3200 logical size. The mode does
+     * not follow from the size because `scale` is an integer.
+     *
+     * Zero when the desktop has no modes, such as when running in a window.
+     */
+    readonly modeWidth: number;
+    readonly modeHeight: number;
+    /**
+     * The monitor's rotation: `normal`, `rotate-90`, `rotate-180` or
+     * `rotate-270`, as the config file spells them.
+     *
+     * Follows the wl_output convention: the name is the clockwise turn applied
+     * to content, not the panel's turn. A shell applies it as written.
+     *
+     * A DOMString because an enum would need another IDL file and another patched
+     * entry in `bindings/idl_in_modules.gni`. The browser maps any other name to
+     * `normal`.
+     */
+    readonly transform: string;
 };
 /**
- * One extension with an action.
+ * One extension with an action, as a shell's tray draws it.
+ *
+ * An interface rather than a dictionary for DomicileClipboardEntry's reason:
+ * WebIDL will not have a dictionary as the element type of an attribute's
+ * array, and these are read off DomicileHost.extensions.
  *
- * The state is the action's default (tab `-1`), not per browser window.
+ * The state is the active tab's -- the <webview> that last had focus -- or the
+ * action's default where there is none. See docs/architecture/EXTENSIONS.md.
  */
 export type DomicileExtension = {
-    /** The id to pass to {@link DomicileHost.activateExtension}. */
+    /** What DomicileHost.activateExtension() names it by. */
     readonly id: string;
     readonly name: string;
     /** The action's tooltip. */
     readonly title: string;
     /**
-     * A `data:image/png` URL at the page's device pixel ratio. Not a
-     * `chrome-extension://` URL, because icons set with
-     * `action.setIcon({imageData})` have none.
+     * data:image/png;base64,..., drawn at this page's device pixel ratio. Not a
+     * chrome-extension:// URL: action.setIcon({imageData}) sets an icon that has
+     * none.
      */
     readonly icon: string;
     readonly badgeText: string;
-    /** A CSS color, `#rrggbbaa`; transparent when the extension set none. */
+    /** A CSS color, #rrggbbaa. Fully transparent when the extension set none. */
     readonly badgeColor: string;
     /**
-     * The popup to open in a `<webview>` on click, or `null` when the click
-     * fires `action.onClicked`. Either way, call
-     * {@link DomicileHost.activateExtension}.
+     * The popup a click opens, in a <webview> the shell draws; null for an
+     * action whose click is its `action.onClicked`. Either way the click is
+     * activateExtension().
      */
     readonly popup: string | null;
-    /** `false` after `action.disable()`. */
+    /** False after the extension's action.disable(). */
     readonly enabled: boolean;
 };
-/** Every event the desktop fires, by name. */
+/** Every event `DomicileHost` fires, by name. */
 export type DomicileHostEventMap = {
-    /**
-     * A client asked for keyboard focus. Focus has not moved; the shell may call
-     * `focusApp()`. See `focus_requested` in `domicile-protocol`.
-     */
-    focusrequested: DomicileAppEvent;
+    /** A grabbed shortcut fired, as a DomicileShortcutEvent. */
     shortcut: DomicileShortcutEvent;
     /**
-     * An answer to {@link DomicileHost.callSystem}: `data` is the compositor's
-     * `system_reply`, `system_event` or `system_end` line. See the `system`
-     * module.
+     * A client asked for the keyboard, as a DomicileAppEvent naming it; nothing
+     * has moved. The shell answers by calling focusApp(), or does not, which
+     * refuses it.
      */
-    system: MessageEvent<string>;
-    /**
-     * Every unanswered portal request: `data` is the compositor's
-     * `portal_requests` line. Fired on every change. A listener added later is
-     * sent the latest line. See `docs/architecture/PORTALS.md`.
-     */
-    portalrequests: MessageEvent<string>;
+    focusrequested: DomicileAppEvent;
     /**
-     * A screen was added, removed, resized or rescaled. Read
-     * {@link DomicileHost.displays} for the new state.
+     * The desktop changed: a screen arrived or left, a display was resized, or
+     * its density moved. Read `displays` for what it is now.
      */
     displayschanged: Event;
     /**
-     * A browser window opened, closed, navigated or changed title. Read
-     * {@link DomicileHost.browserWindows} for the new list.
-     */
-    browserwindowschanged: Event;
-    /**
-     * A window appeared, closed, or changed. Bare — read
-     * {@link DomicileHost.windows} for what they are now.
+     * A window appeared, closed, or changed: its title, size, limits, cursor or
+     * popup placement. Read `windows` for what they are now.
      */
     windowschanged: Event;
     /**
-     * The compositor said where the keyboard is. Bare — read
-     * {@link DomicileHost.focusedWindow}. Every time, not only when it moves, and
-     * once after the windows already running are replayed to a page that has
-     * just connected: a window listed after the first of these is one opened
-     * now.
+     * The compositor said where the keyboard is: `focusedWindow` may have
+     * changed. Every time, and once after the windows already running are
+     * replayed to a page that has just connected -- which is how a page tells a
+     * window opened now from one that was running.
      */
     focusedwindowchanged: Event;
-    /** Bare: the attribute it names moved. */
     clipboardchanged: Event;
-    /** Bare: the attribute it names moved. */
     traychanged: Event;
-    /** Bare: the attribute it names moved. */
     notificationschanged: Event;
-    /** Bare: the attribute it names moved. */
     extensionschanged: Event;
-    /** Bare: the attribute it names moved. */
     idlechanged: Event;
-    /** Bare: the attribute it names moved. */
     lockedchanged: Event;
-    /** Bare: the attribute it names moved. */
     themechanged: Event;
-    /** Bare: the attribute it names moved. */
     windowsthemechanged: Event;
-    /** Bare: the attributes it names moved. */
     modifierschanged: Event;
+    /**
+     * Fires when a window opens, closes, navigates or changes title. Read
+     * `browserWindows` for the current list.
+     */
+    browserwindowschanged: Event;
+    /**
+     * An answer to callSystem(), as a MessageEvent whose `data` is the
+     * compositor's `system_reply`, `system_event` or `system_end` line.
+     */
+    system: MessageEvent<string>;
+    /**
+     * Every unanswered portal request, as a MessageEvent whose `data` is the
+     * compositor's `portal_requests` line. Fired on every change. A listener
+     * added later is sent the latest line, so a shell that listens late still
+     * sees pending dialogs.
+     */
+    portalrequests: MessageEvent<string>;
 };
 /**
- * The shell's control channel to the compositor.
+ * The desktop a shell is handed — the shell's control channel to the compositor.
  *
- * In the IDL this is an `EventTarget`. The first `addEventListener` binds the
- * channel, so nothing is dispatched before something listens.
+ * Not a web standard and not proposed as one. It exists in Domicile's engine
+ * fork, on documents served over domicile://, and nowhere else.
  *
- * It is not typed as `EventTarget` here: that would add `lib.dom`'s overload
- * and type listeners as plain `Event`. `dispatchEvent` is left out; nothing
- * in a page dispatches to the host. As a result, an `EventTarget` does not
- * satisfy this type, so test doubles register listeners themselves.
+ * This is the typed surface rather than a message pipe: the page calls methods
+ * and listens for events, and the wire protocol lives in the browser process.
+ * The reason is that the protocol carries Spawn, and a page that cannot
+ * construct a message cannot construct a malformed one. The cost, which is
+ * real, is that adding a message means an engine release rather than editing a
+ * TypeScript file.
  */
 export type DomicileHost = {
     /**
-     * Run a command on the desktop's machine.
+     * Run a command on the machine running the desktop.
      *
-     * Takes an argv array because no shell parses it. Throws if empty.
+     * Sequence<DOMString> rather than a single string: splitting a command line
+     * is a shell's job and there is no shell in this path.
      */
     spawn(command: readonly string[]): void;
     /**
-     * Search the home directory for `query`. Resolves with the result. A newer
-     * call rejects this one with an `AbortError`.
+     * Ask what in the home matches `query`. Resolves with the answer. A newer
+     * call supersedes this one, which rejects with an AbortError: a launcher
+     * wants the answer to what is typed now.
+     *
+     * IT TAKES NO PATH, AND THAT IS THE POINT RATHER THAN AN OVERSIGHT. A shell
+     * is served over domicile:// so that it has an origin without a TCP port,
+     * not so that it gets a filesystem. A call that named a directory would be
+     * one, and every document this engine serves would have it. What gets
+     * searched is the compositor's decision -- see `domicile_host::file_search`
+     * -- and the query is only words to match.
      *
-     * It takes no path on purpose, so pages cannot browse the filesystem. The
-     * compositor matches against its index and sends only the matches. See
-     * `domicile_host::file_search`.
+     * ONLY WHAT MATCHED CROSSES. The compositor's index is the whole home; a
+     * page handed that to filter was a desktop that took no input while it
+     * arrived.
      */
     searchFiles(query: string): Promise<DomicileFileSearch>;
     /**
-     * Preview `path`. Resolves with the result. A newer call rejects this one, as
-     * with {@link searchFiles}.
+     * Ask what is in one file. Resolves with the answer. A newer call
+     * supersedes this one, as with searchFiles().
      *
-     * Paths outside the compositor's home index are `unreadable`, so a page can
-     * only read what a search could return. See `domicile_host::file_preview`.
+     * THIS ONE TAKES A PATH, which searchFiles() above says is the point of not
+     * taking one -- so what it may name is narrow: a path relative to the home,
+     * as searchFiles() named it (a directory without its trailing `/`). The
+     * compositor answers only for a path in its own index of the home, and
+     * anything else comes back "unreadable", so this reads nothing a search
+     * could not already have named.
      */
     previewFile(path: string): Promise<DomicileFilePreview>;
     /**
-     * A system call: `request` is the call as JSON, answered with `system`
-     * events carrying `id`. The compositor checks every call, the lock
-     * included. Use the `system` module rather than calling this. See
-     * `docs/SHELL-SYSTEM-ACCESS.md`.
+     * A system call: a file, a directory, a watch or a process. `request` is
+     * the call as JSON, such as `{"call":"read_file","path":"/sys/x"}`. Answered
+     * with `system` events whose `data` carries `id`. The compositor checks
+     * every call, the lock included. See docs/SHELL-SYSTEM-ACCESS.md and
+     * the SDK's `system` module, which is the way to call this.
      */
     callSystem(id: number, request: string): void;
     /**
-     * Answer portal request `id` from a `portalrequests` event. `answer` is JSON
-     * with a string `kind`, such as `{"kind":"access"}`; the engine drops any
-     * other. The compositor checks the rest.
+     * Answer portal request `id`, which a `portalrequests` event listed.
+     * `answer` is JSON with a string `kind`, such as `{"kind":"access"}`. One
+     * that is not is dropped in the browser. The compositor checks the rest. See
+     * docs/architecture/PORTALS.md.
      */
     answerPortalRequest(id: number, answer: string): void;
     /**
-     * Put a clipboard history entry back on the clipboard.
+     * Put a row of the clipboard's history back on the clipboard.
      *
-     * Takes an id from {@link clipboard}, not text, so a page cannot write
-     * arbitrary data to the clipboard. The compositor then serves the entry,
-     * even if the client that copied it has exited.
+     * IT NAMES A ROW AND CARRIES NO TEXT: a shell is served over domicile:// so
+     * that it has an origin, not so that it gets the machine, and a call that
+     * took bytes would let this document write the desktop's clipboard rather
+     * than choose among what has already been copied on it. `entry` is an id
+     * `clipboard` lists.
+     *
+     * No answer, and none to want: what follows is that the next paste in any
+     * window is that row, served by the compositor rather than by whichever
+     * client first copied it -- which is the whole of what a clipboard manager
+     * is for. An id the history has since dropped sets nothing.
      */
     copyClipboardEntry(entry: number): void;
     /**
-     * Move the compositor's keyboard focus and where the keys this page hears
-     * are sent. `focusChrome()` takes it back to the page.
+     * Click an icon in the system tray, with the button `action` names.
+     *
+     * It names an icon `tray` lists and a button, and nothing about
+     * what the click does, for copyClipboardEntry's reason: that is the
+     * application's. An id that names no icon now is a click that raced the
+     * application going away, and does nothing; an empty one throws.
+     */
+    activateTrayItem(id: string, action: DomicileTrayAction): void;
+    /**
+     * Clear notifications: ids `notifications` lists. Each application hears
+     * its notification was dismissed, and the next `notificationschanged`
+     * leaves them out. An id already gone is passed over.
+     */
+    dismissNotifications(ids: readonly number[]): void;
+    /**
+     * Press one of a notification's actions -- "default" for the notification
+     * itself. It names a notification and a key it offered, and nothing about
+     * what the press does, for copyClipboardEntry's reason: that is the
+     * application's. An empty action throws.
+     */
+    invokeNotificationAction(id: number, action: string): void;
+    /**
+     * Which window has the keyboard: the compositor's seat, and where the keys
+     * this page hears are sent. focusChrome() takes it back to the page.
      */
     focusApp(appId: string): void;
     focusChrome(): void;
     /**
-     * Move the pointer to `x`, `y` in page coordinates (`clientX`/`clientY`).
+     * Put the pointer at a place in this page, in the page's own coordinates --
+     * the ones a PointerEvent reports as clientX/clientY.
      *
-     * Handled by the engine, which draws the cursor. Does nothing when nested in
-     * another compositor.
+     * THE COMPANION TO MOVING THE KEYBOARD. A desktop whose focus follows the
+     * cursor has to take the cursor with it when a key moves the focus, or the
+     * next pointer event hands the focus back to whatever the pointer is still
+     * over. Every other compositor does this itself; here the shell is a page,
+     * and a page can read where the pointer is and cannot put it anywhere.
+     *
+     * Doubles for resizeApp's reason: a place in a page is a CSS pixel and a CSS
+     * pixel is fractional. A coordinate outside this page is clamped to its own
+     * box -- what a page may move is the pointer over itself -- and NaN throws.
      */
     warpPointer(x: number, y: number): void;
-    /** Ask a client to close. It may refuse, for example to offer a save. */
+    /**
+     * Ask a client to close. Not a kill -- the client decides, which is why a
+     * window can refuse and show a save dialog instead.
+     */
     closeApp(appId: string): void;
     /**
-     * Report where the page put an `<app>`, in page CSS pixels. The client draws
-     * at the scale of the monitor holding most of that box.
+     * The layout box, as a resize. For an <app> the box IS the configure.
+     *
+     * Doubles because a CSS pixel is fractional and this comes from a layout box.
+     */
+    resizeApp(appId: string, width: number, height: number): void;
+    /**
+     * Where the page put an <app>, in the page's CSS pixels. The client draws at
+     * the scale of the monitor holding most of that box. Layout still places the
+     * window; this only tells the compositor where it ended up.
      */
     setAppBounds(appId: string, x: number, y: number, width: number, height: number): void;
     /**
-     * Set the desktop theme.
+     * Draw the desktop the other way round.
+     *
+     * THE ONE CALL HERE THAT SAYS WHAT THE DESKTOP IS rather than asking it for
+     * something. It reaches the compositor and comes back as `themechanged` --
+     * to every chrome on the desk, this one included, which is why a shell
+     * renders from `theme` rather than from its own click. Three monitors are
+     * three pages and the toggle is on one of them.
      *
-     * Answered with `themechanged` to every chrome, including this one, so
-     * render from {@link theme}. The compositor also serves the theme to clients
-     * through the settings portal. Not saved to the config.
+     * It has to leave the page at all because the compositor is the only process
+     * the desk's CLIENTS can hear: it answers the settings portal GTK, Qt and
+     * Electron read a color scheme from, out of this same value. A theme kept in
+     * the renderer would be a desktop whose panels went dark and whose windows
+     * stayed light.
+     *
+     * A DomicileTheme rather than a DOMString, so a word that is not one of the
+     * two is refused at the call instead of at the socket -- see
+     * domicile_theme.idl.
      */
-    setTheme(theme: Theme): void;
+    setTheme(theme: DomicileTheme): void;
     /**
-     * Try to unlock the desktop with `passphrase`.
+     * Offer a passphrase at a locked desk.
+     *
+     * THE WAY OUT OF THE ONE STATE THIS PAGE CANNOT CHANGE BY DRAWING. While the
+     * desk is locked the compositor puts nothing this page forwards into the
+     * Wayland seat -- no client sees a keystroke or a click -- and this call is
+     * the only thing that ends it. The page keeps its own keys throughout, which
+     * is what makes a lock screen possible: it is the thing forwarding, so it can
+     * take a passphrase while nothing it forwards arrives anywhere.
      *
-     * Answered with `lockedchanged` to every chrome. Hide the lock screen only
-     * when {@link locked} says unlocked. A wrong passphrase leaves it `true`.
-     * There is no retry limit or delay yet.
+     * ANSWERED WITH `lockedchanged` AND NOT WITH A RETURN VALUE, and only when
+     * the desk actually opened. A wrong passphrase produces nothing at all: the
+     * compositor says so in its own log, without the passphrase in it. A page
+     * that cleared its own lock screen because it believed its own keystrokes
+     * would be a lock anybody with the devtools could open -- and the event goes
+     * to every chrome on the desk rather than to this one, because three monitors
+     * are three pages and the desk they draw has one lock.
      */
     unlock(passphrase: string): void;
     /**
-     * Lock the desktop now.
-     *
-     * Answered with `lockedchanged` to every chrome. Does nothing when no lock
-     * is configured.
+     * Lock the desk now, whoever is at it. Answered like unlock(): with
+     * `lockedchanged` to every chrome, and only when the desk actually shut.
      */
     lock(): void;
     /**
-     * Tell the compositor this page has captured its old frame for a `theme`
-     * transition, so client windows can switch theme now.
+     * This page's old frame is held for `theme`: turn the desk's windows now.
      *
-     * The windows must switch after the capture and before the transition
-     * starts. The compositor waits for every chrome (with a timeout), updates
-     * the windows, and fires `windowsthemechanged` once they repaint.
+     * Called from inside a shell's wipe, once the frame it wipes away from is
+     * captured, so that the wipe passes across windows that turn inside it
+     * rather than over windows that had already turned. Answered with a
+     * `windowsthemechanged` once every chrome has called it and the windows have
+     * had their chance to repaint -- or once the compositor stopped waiting.
      */
-    themeCaptured(theme: Theme): void;
+    themeCaptured(theme: DomicileTheme): void;
     /**
-     * Route a key combination to the page instead of the focused client.
+     * Route a key combination to the page rather than to the focused client.
      *
-     * By name (`grabShortcut("Meta+Shift+l")`, sway's grammar), the engine finds
-     * the key the keysym is on, and again on layout change. Presses arrive as
-     * `shortcut` events whose `chord` is this string, from a `<webview>` or this
-     * page (taken from the page).
+     * The press comes back as a `shortcut` event carrying the same fields, so a
+     * shell compares what it grabbed against what fired without parsing a string.
      *
-     * As a {@link DomicileShortcut}, presses arrive with the same fields and an
-     * empty `chord`.
+     * The same, by name: `grabShortcut("Meta+Shift+l")`, in sway's grammar. The
+     * engine finds the key the keysym is on, from the keyboard the compositor
+     * describes, and finds it again whenever the layout changes. The press comes
+     * back as a `shortcut` event whose `chord` is this string -- pressed in a
+     * `<webview>` or on this page, where it is taken from the page.
      *
-     * @throws `SyntaxError` for a malformed chord; `NotFoundError` for a keysym
-     *   the keyboard cannot type, once the compositor has described it.
+     * Throws a SyntaxError for a chord written wrong, and a NotFoundError for a
+     * keysym the keyboard cannot type; before any keyboard is described, that
+     * one is a console warning once it is.
      */
-    grabShortcut(shortcut: string | DomicileShortcut): void;
+    grabShortcut(shortcut: DomicileShortcut | string): void;
     /**
-     * Click an extension's action: grants `activeTab` on the active tab, and
-     * fires `action.onClicked` if there is no popup. The shell opens any popup
-     * itself, in a `<webview>` at {@link DomicileExtension.popup}.
+     * Click an extension's action, popup or not: the extension is granted
+     * activeTab on the active tab, as a toolbar click grants it in Chrome. Then
+     * an action with no popup has its `action.onClicked` dispatched; one with a
+     * popup is the shell's to open, as a <webview> at the `popup` its
+     * `extensions` entry names, and is opened after this call.
+     *
+     * NOT THE COMPOSITOR'S. An action lives in this browser, so the call goes no
+     * further than the browser process, over the tray's own pipe -- see
+     * components/domicile/mojom/extension_tray.mojom. An id that names no
+     * extension with an action now is a click that raced an uninstall, and does
+     * nothing; an empty one throws.
      */
     activateExtension(id: string): void;
     /**
      * Opens a browser window at `url`, for the shell's own UI such as a `+`
-     * button. It appears in the next `browserwindowschanged`. Windows that
-     * programs open (`domicile open-url`, `target="_blank"`, extensions) arrive
-     * the same way.
+     * button or a launcher. It appears in the next `browserwindowschanged`. A
+     * domicile:// address shows blocked, as in a <webview>.
      */
     openBrowserWindow(url: string): void;
     /**
-     * Closes browser window `id`. It leaves the next `browserwindowschanged`.
-     * Does nothing for an unknown id.
+     * Closes window `id`; it leaves the next `browserwindowschanged`. An unknown
+     * id does nothing.
      */
     closeBrowserWindow(id: string): void;
     /**
-     * Click a system tray icon with the button `action` names. Does nothing if
-     * the application has exited. Throws on an empty id.
-     */
-    activateTrayItem(id: string, action: TrayAction): void;
-    /**
-     * Dismiss notifications by id (from {@link notifications}) and tell their
-     * applications. Unknown ids are ignored.
-     */
-    dismissNotifications(ids: readonly number[]): void;
-    /**
-     * Invoke a notification's action (`"default"` for clicking it), then close
-     * it. Unknown actions are ignored.
-     */
-    invokeNotificationAction(id: number, action: string): void;
-    /**
-     * The desktop's screens.
+     * The screens of the desktop.
      *
-     * An attribute so components that mount late can read it. `null` until the
-     * compositor reports, which differs from an empty array (no screens). A new
-     * frozen array after each `displayschanged`.
-     */
-    readonly displays: readonly DomicileDisplay[] | null;
-    /**
-     * The browser windows, oldest first.
+     * An attribute rather than an event payload, because the desktop is a fact
+     * and not a stream. A shell reads this when it needs it -- including a
+     * component that mounts long after the description arrived, which an event
+     * would have left with nothing.
      *
-     * An attribute so components that mount late can read it. `null` until the
-     * browser lists them, which it does as soon as something listens.
+     * NULL UNTIL THE COMPOSITOR HAS DESCRIBED THE DESKTOP, and an empty array
+     * for a desktop with no screens on it. They are different states and a shell
+     * renders them differently: nothing at all is what an unknown screen shows,
+     * which is the right answer for "there is no such screen" and the wrong one
+     * for "wait". `domicile-protocol` carries that distinction deliberately --
+     * an empty `Vec` that serializes to nothing and one that serializes to `[]`
+     * both come back empty, and only the second is a desktop a shell can parse
+     * -- and an attribute that started empty threw it away again here.
+     *
+     * The compositor describes at least one output, so it does not send the
+     * empty one; the `domicile` daemon, which no desktop has been described to,
+     * does. Leaning on "in practice it never happens" is what made the SDK guess,
+     * and this is instead of the guess.
+     *
+     * No [SameObject]: the compositor sends the whole desktop each time it
+     * changes and a FrozenArray is frozen, so this is a different array after
+     * every `displayschanged`. That is also the shape a shell wants -- an
+     * identity that survived a desktop it no longer describes would be worse.
      */
-    readonly browserWindows: readonly DomicileBrowserWindow[] | null;
+    readonly displays: readonly DomicileDisplay[] | null;
     /**
-     * Every client window, in the order they appeared. Reading it binds the
-     * channel, and the compositor announces the windows already running as it
-     * does, so a shell that reads late misses nothing: read, then listen for
-     * `windowschanged`. A different frozen array after every change.
+     * Every client window on the desktop, in the order they appeared: what the
+     * compositor has said about each so far. Reading it binds the channel, and
+     * the compositor announces the windows already running as it does, so a
+     * shell that reads late misses nothing -- it reads, then listens for
+     * `windowschanged`. A different array after every change, for `displays`'s
+     * reason.
      */
     readonly windows: readonly DomicileWindow[];
-    /** The window holding the keyboard, or `null` when the shell's page holds it. */
+    /** The window holding the keyboard, or null when the shell's page holds it. */
     readonly focusedWindow: string | null;
     /**
-     * What has been copied on this desktop, newest first. **Not
-     * `navigator.clipboard`**, which answers out of the browser's own clipboard
-     * and no Wayland client's.
+     * THE DESK'S STATE, AS ATTRIBUTES. Each is what the compositor last said,
+     * null until it has said anything, and a bare `<name>changed` event says it
+     * moved: a shell reads, then listens, and one that listens late misses
+     * nothing. See docs/architecture/WINDOW-DOMICILE.md.
      */
     readonly clipboard: readonly DomicileClipboardEntry[] | null;
-    /** The system tray: every application showing an icon, in the order they registered. */
     readonly tray: readonly DomicileTrayItem[] | null;
-    /** The desk's notifications: every one not yet cleared, oldest first. */
     readonly notifications: readonly DomicileNotification[] | null;
-    /** The extensions with an action, from this browser rather than the compositor. */
     readonly extensions: readonly DomicileExtension[] | null;
-    /**
-     * Whether anybody is at this desktop. **Not `document.visibilityState`**: a
-     * shell's document stays visible while the glass is off. `null` on a desktop
-     * with no idle timeout.
-     */
     readonly idle: boolean | null;
-    /**
-     * Whether this desk is locked: `true` is a desk that delivers nothing to
-     * any client. The compositor holds it, so a reload does not open it. `null`
-     * on a desktop with no passphrase.
-     */
     readonly locked: boolean | null;
+    readonly theme: DomicileTheme | null;
+    readonly windowsTheme: DomicileTheme | null;
     /**
-     * Which way round the desktop is drawn. **Not `prefers-color-scheme`**: the
-     * theme is the compositor's, and {@link setTheme} is how a page moves it.
-     */
-    readonly theme: Theme | null;
-    /**
-     * Which way round the desk's windows are drawn: {@link theme}'s other half,
-     * moved once they have turned — see {@link themeCaptured}.
+     * The compositor seat's modifiers -- only the keys forwarded to a client;
+     * see @domicile-desktop/sdk's README before trusting them over a page's
+     * own key events.
      */
-    readonly windowsTheme: Theme | null;
-    /** The compositor seat's — see the README before trusting them. */
     readonly altKey: boolean | null;
     readonly ctrlKey: boolean | null;
     readonly shiftKey: boolean | null;
     readonly metaKey: boolean | null;
+    /**
+     * The desk's browser windows, oldest first. Null until the browser lists
+     * them, which it does as soon as this page listens. The browser holds each
+     * page; draw one with `<webview window="id">`. A shell loaded over this one
+     * gets the same windows and pages. See
+     * components/domicile/mojom/browser_windows.mojom.
+     *
+     * A window a program opens (`domicile open-url`, a page's target="_blank",
+     * an extension) appears here in the next `browserwindowschanged`. No
+     * [SameObject], for `displays`' reason.
+     */
+    readonly browserWindows: readonly DomicileBrowserWindow[] | null;
+    /**
+     * Typed by the event map rather than by inheriting `EventTarget`, whose
+     * overloads take any name and type every listener's event as `Event`.
+     * `dispatchEvent` is left out: a page does not dispatch to it.
+     */
     addEventListener<T extends keyof DomicileHostEventMap>(type: T, listener: (event: DomicileHostEventMap[T]) => void): void;
     removeEventListener<T extends keyof DomicileHostEventMap>(type: T, listener: (event: DomicileHostEventMap[T]) => void): void;
 };
+/**
+ * One notification: an application's call to org.freedesktop.Notifications,
+ * which the compositor serves -- a page's own Web Notification included,
+ * because the browser shows one by calling that server.
+ *
+ * An interface rather than a dictionary for DomicileTrayItem's reason: these
+ * are read off DomicileHost.notifications.
+ */
+export type DomicileNotification = {
+    /**
+     * What DomicileHost.dismissNotifications() and invokeNotificationAction()
+     * name this notification by. One its application replaced keeps its id.
+     */
+    readonly id: number;
+    /** Who sent it, as it named itself. May be empty. */
+    readonly appName: string;
+    /** The one line that says what happened. */
+    readonly summary: string;
+    /** More, as plain text: the compositor tells senders it takes no markup. */
+    readonly body: string;
+    /**
+     * The picture, as a `data:` URL, or empty for nothing to draw. A URL rather
+     * than a path for DomicileTrayItem.icon's reason.
+     */
+    readonly icon: string;
+    /**
+     * "low", "normal" or "critical": the spec's urgency hint. A word rather than
+     * an enum because it is only ever read, and the SDK parses it.
+     */
+    readonly urgency: string;
+    /** Its buttons. A press on the notification itself is `clickable`. */
+    readonly actions: readonly DomicileNotificationAction[];
+    /** Whether it offers the "default" action: a press on the notification. */
+    readonly clickable: boolean;
+    /**
+     * How long it asked to stay up, in milliseconds: 0 for until it is
+     * dismissed, -1 for the shell's choice.
+     */
+    readonly timeoutMs: number;
+    /**
+     * When it arrived or was last replaced, in milliseconds since the epoch on
+     * the compositor's clock.
+     */
+    readonly time: number;
+};
+/**
+ * One button of a notification.
+ *
+ * An interface rather than a dictionary because these are read off a
+ * DomicileNotification's array; see DomicileTrayItem.
+ */
+export type DomicileNotificationAction = {
+    /** The id DomicileHost.invokeNotificationAction() takes. */
+    readonly key: string;
+    /** The button's label. */
+    readonly label: string;
+};
+/**
+ * A combination claimed with grabShortcut() was pressed.
+ *
+ * Its own type rather than a DomicileAppEvent with the combination in the
+ * `title` slot. A shortcut is not a window's name and does not belong to a
+ * window at all: it fires whatever holds the keyboard, which is the point of
+ * grabbing it.
+ *
+ * Only presses. A release changes nothing and would arrive as a second event
+ * for one keystroke.
+ */
+export type DomicileShortcutEvent = Event & {
+    /**
+     * The chord as the shell grabbed it -- `Meta+Shift+l` -- or empty for one
+     * grabbed as a keycode. See DomicileHost.grabShortcut().
+     */
+    readonly chord: string;
+    /** The Linux evdev code, the same numbering key() forwards in. */
+    readonly keycode: number;
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly shiftKey: boolean;
+    readonly metaKey: boolean;
+};
+/**
+ * One icon in the system tray.
+ *
+ * An interface rather than a dictionary for DomicileClipboardEntry's reason:
+ * WebIDL will not have a dictionary as the element type of an attribute's
+ * array, and these are read off DomicileHost.tray.
+ */
+export type DomicileTrayItem = {
+    /**
+     * What DomicileHost.activateTrayItem() names this icon by: the bus name the
+     * application answers on and the object path it answers at, written together.
+     */
+    readonly id: string;
+    /**
+     * What the icon is, in words: its tooltip's title, its title, or its id, the
+     * first the application said. Never empty.
+     */
+    readonly title: string;
+    /**
+     * The picture, as a `data:` URL to draw, or empty for one the compositor
+     * could not draw. A URL rather than a path: the page may draw what the
+     * compositor read and cannot read it.
+     */
+    readonly icon: string;
+};
+/**
+ * One client window on the desktop, as `DomicileHost.windows` lists it: what
+ * the compositor has said about it so far. Replaced, never edited: a change to
+ * any window is a new `windows` array and a `windowschanged` event.
+ */
+export type DomicileWindow = {
+    readonly appId: string;
+    /** Empty until the client names itself. */
+    readonly title: string;
+    /**
+     * The size the client last committed, in CSS pixels; null until it has
+     * committed one.
+     */
+    readonly width: number | null;
+    readonly height: number | null;
+    /** The limits the client asked for; null where it asked for none. */
+    readonly minWidth: number | null;
+    readonly minHeight: number | null;
+    readonly maxWidth: number | null;
+    readonly maxHeight: number | null;
+    readonly cursor: DomicileCursorShape;
+    /**
+     * A popup's parent window and its place relative to it, and whether it
+     * grabbed the pointer; null and false for a toplevel.
+     */
+    readonly parent: string | null;
+    readonly x: number | null;
+    readonly y: number | null;
+    readonly grab: boolean;
+};

package/dist/domicile-host.js

@@ -1,16 +1,11 @@
-// Types for the desktop a shell is handed (`Shell(root, domicile)`), its
-// channel to the compositor.
+// Generated from the engine's WebIDL by `codegen/generate-domicile-host.ts`.
+// Do not edit. Change the IDL in
+// `packages/domicile-engine/src/third_party/blink/renderer/modules/domicile/`
+// and run `bun run generate` in `packages/chrome-sdk`.
 //
-// This mirrors the engine's WebIDL in
-// `packages/domicile-engine/src/third_party/blink/renderer/modules/domicile/`.
-// If they disagree, the IDL is correct. See
-// `docs/architecture/WINDOW-DOMICILE.md`.
+// The desktop a shell is handed (`Shell(root, domicile)`). There is no global;
+// a shell keeps what it was handed. See `shell.ts`.
 //
-// The engine runs the shell module and passes the host into its `Shell`
-// (`DomicileShell`). There is no `navigator.domicile` or `window.domicile`, so
-// no global is declared here; a shell keeps what it was handed. See
-// `shell.ts`.
-//
-// Sizes and coordinates are fractional CSS pixels, except in
-// {@link DomicileDisplay}. Keycodes are Linux evdev codes.
+// Sizes and coordinates are fractional CSS pixels, except in `DomicileDisplay`.
+// Keycodes are Linux evdev codes.
 export {};

package/package.json

@@ -91,11 +91,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "generate": "bun codegen/generate-domicile-host.ts",
     "test:types": "tsc --noEmit",
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-028d5f9f87e0",
+  "version": "0.0.0-alpha-e040773499e5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cprussin/domicile.git",