@domicile-desktop/sdk 0.0.0-alpha-f2862631a576

package/LICENSE

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

package/README.md

@@ -0,0 +1,235 @@
+# @domicile-desktop/sdk
+
+> Published to npm, and usable outside this repo. If you are writing a shell,
+> start with [/docs/WRITING-A-SHELL.md](/docs/WRITING-A-SHELL.md) — this is the
+> reference for the package, that is the guide to using it.
+>
+> It ships built JavaScript and `.d.ts` from `dist/`, not the TypeScript in
+> `src/`: run `bun run build` before anything outside the workspace resolves it.
+
+The in-page half of Domicile. A Domicile chrome is ordinary web content; this
+package is what lets that content talk to the compositor and mount real Wayland
+clients as DOM elements.
+
+It provides these:
+
+- **`DomicileClient`** (`./domicile-client`) — the client for `window.domicile`, the
+  typed control channel the forked engine puts on a document it served. It
+  takes a `DomicileHost` and gives back a handler table for what the compositor
+  says and a typed call per thing the chrome asks of it. There is no handshake
+  and no wire: what it adds over the host itself is that it **registers its own
+  listeners in its constructor and holds what arrives before your `on` does** —
+  a DOM event dispatched with no listener is gone, and a React shell registers
+  tens of milliseconds after the compositor has announced every window already
+  running. For the same reason a page must never call `addEventListener` on
+  `window.domicile` itself. One message is not the compositor's: `open_url` is
+  an address `domicile open-url` asked the desktop to open — what `BROWSER`
+  runs inside it. Opening it is the shell's.
+- **`Shell`** (`./shell`) — the type of a shell module's `Shell` export: what
+  Domicile calls, once, with the element to draw in. A module without one is
+  refused on the screen.
+- **`registerElements`** (`./register-elements`) — the input routing behind the
+  engine's `<app>` tag. It forwards the pointer over a window to the client
+  underneath in that client's own surface coordinates, and routes the page's
+  keystrokes to whichever window was last reached for. Nothing here says how big
+  a window is: an `<app>`'s layout box *is* the client's
+  `xdg_toplevel.configure`, and the engine states it off the layout it
+  performed. All of it is delegated from `document` over
+  `closest("app")`: the tag is the engine's, so there is no element class to hang
+  any of it on, and nothing here is registered. A click on a window fires a
+  cancelable `domicile-focus-requested` and then focuses the client, and a press
+  that lands off every window fires a cancelable
+  `domicile-focus-release-requested` on the window that holds the keyboard and
+  then hands it back to the page — so a shell that wants focus to be its own
+  decision calls `preventDefault()` on either, and a shell with no opinion needs
+  to know nothing about them. A right-click over a window also loses the
+  browser's own context menu, because the press is forwarded and the menu a
+  right-click asked for is the client's, drawn inside its surface. Only over an
+  `<app>`: a `contextmenu` anywhere else — the desktop, a shell's chrome, the
+  page inside a `<webview>` — is left uncanceled and keeps its menu.
+- **`<app>`** (`./app-element`) — the tag name, the two focus events, and the
+  TypeScript for the element, which is the fork's. The surface embed and the size
+  a client is configured at are both the layout box's and the engine reports
+  them; there is nothing to call.
+- **`focusApp`** (`./focus-app`) — put the keyboard on a client without a click.
+  Not the same as `DomicileClient.focusApp`, which asks the compositor and stops:
+  keyboard events reach `document` rather than an element, so the SDK has to be
+  told too.
+- **`<webview>`** (`./webview-element`) — types and event names only. The
+  element is the engine's: `src` is the address it loads, `goBack` /
+  `goForward` / `stop` / `reload` are what a chrome's address bar drives it
+  with, `canGoBack` / `canGoForward` say whether the first two would do
+  anything, `loading` says whether a page is still arriving, and `focus` puts
+  the keyboard on the embedded page. What this module adds is the TypeScript
+  for all of that plus the names of the four events the browser process
+  dispatches on it, `domicile-guest-focus`, `domicile-history-change`,
+  `domicile-loading-change` and `domicile-new-window`. The last is the only one
+  that carries anything — `event.url`, the address a link with
+  `target="_blank"` asked to open — because it is the only one that is not about
+  state the element already holds: the browser process opens no window for a
+  guest, so a shell that ignores it is a desktop where such a link does
+  nothing.
+  `domicile-close` is the page calling `window.close()` — an extension's popup
+  closing itself — and removing the view is the shell's answer.
+  `domicile-content-size-change` says `contentWidth` / `contentHeight` moved:
+  the size the page's content wants, which Chrome sizes an extension's popup
+  from.
+  `domicile-popup-window` is an extension's `chrome.windows.create` with a
+  popup: `windowId`, `url`, `width` and `height` (0 where it named none). The
+  shell opens a window whose view carries `popupwindow="<windowId>"` from its
+  first render — the engine reads it once, as the view is connected — and that
+  view is then the extension's window.
+- **`Extension`** (`./extension`) — one row of the tray, as
+  `DomicileClient.on("extensions", …)` delivers it, and the Zod schema it is
+  parsed with. A click on one is `DomicileClient.activateExtension(id)`, which
+  grants it `activeTab`; one with a `popup` is then a `<webview>` at that
+  address.
+- **`TrayItem`, `TrayAction`** (`./tray`) — one icon of the system tray, as
+  `DomicileClient.on("tray", …)` delivers it, and the button a click was. A
+  click is `DomicileClient.activateTrayItem(id, action)`.
+- **`bindKeys`** (`./bind-keys`) — a shell's own keys, claimed and answered:
+  `bindKeys(domicile, { keybindings, modes }, { onCommand, onModeChanged })`,
+  each table a chord (`"Meta+Shift+l"`) to a `KeyAction`. The chords are
+  resolved by `./own-keybindings` against the keyboard the compositor
+  describes (`shell_config`), again whenever the layout moves. A
+  `KeyAction.SendShell(words)` calls `onCommand(words)`, whose meaning is the
+  shell's; `KeyAction.Mode(name)` is answered here, and `onModeChanged` says
+  the mode moved. It returns `{ unbind, setMode }`: `setMode` is how a desktop
+  of several pages keeps one mode across them (one the shell lacks goes back
+  to `default`). It owns the `shell_config` and `shortcut` slots of
+  `DomicileClient.on`, and the chords it claims are never given back — the
+  channel cannot release one. `./keybindings` is its pure half (what a press
+  does in a mode) and `./key-action` the action a binding carries.
+- **`Notification`** (`./notification`) — one notification, as
+  `DomicileClient.on("notifications", …)` delivers it: an application's or a
+  site's. A press is `invokeNotificationAction(id, key)`, a clear
+  `dismissNotifications(ids)`.
+- **`connectToHost`** (`./connect-to-host`) — the `DomicileHost` off the
+  document, or a stand-in that does nothing when there is none. `hasHost` is
+  beside it for code that needs the answer rather than the object.
+- **`reportDesktopSize`** (`./desktop-size`) — tell the host how big the page
+  is, and keep telling it. The desktop spans every display and the page is what
+  measures it, so a shell that never reported would leave the compositor
+  laying windows out against a size it guessed.
+- **`reportDevicePixelRatio`** (`./device-pixel-ratio`) — tell the host what
+  density the page is drawing at, and keep telling it. The ratio changes when
+  the window moves to another display or the page is zoomed, and the page is
+  the only part of Domicile that can see either; a chrome that reported it once
+  would leave every client drawing at the old resolution.
+- **Pure helpers** — affine `./matrix` math mirroring the Rust
+  `domicile-scene::Transform`, `./domicile-host` mirroring the engine's IDL,
+  `./host-message` for what the client delivers and how an event becomes one,
+  `./cursor-shape` for the keyword set a client can ask for, and `./input`
+  keycode mapping.
+- **The routing parts, published so they can be substituted** — `./measure` is
+  what `registerElements` takes an override of, and `./element-transform` and
+  `./surface-coordinates` are what invert a window's affine so a click under a
+  CSS rotation — or a `zoom`, which is not a transform and is carried
+  separately — lands where the user pressed. The one construct they cannot
+  invert is a perspective projection, which is not an affine at all; `./measure`
+  maps the window flat and says so on the console. A shell needs none of them;
+  a test of one does.
+- **The compositor's own JSON wire**, which **a page no longer speaks** —
+  `./protocol`, `./chrome-message`, `./newline-frames` and `./host-stream` are
+  there for `@domicile-desktop/e2e-harness`, a headless stand-in for a chrome that
+  talks to the compositor's socket directly. The one exception is
+  `shell_config`, which the engine forwards as the compositor's line:
+  `./host-message` parses it with `./protocol`'s schema.
+
+## Usage
+
+```ts
+import { DomicileClient } from "@domicile-desktop/sdk/domicile-client";
+import { connectToHost } from "@domicile-desktop/sdk/connect-to-host";
+import { registerElements } from "@domicile-desktop/sdk/register-elements";
+
+const domicile = new DomicileClient(connectToHost(window));
+registerElements(domicile);
+```
+
+That is the whole of it. There is nothing to await: `connect()` is gone with
+the handshake it performed, the compositor's protocol version is checked in the
+browser process and only logged, and the first call on the channel is what
+binds it. Say what you have to say as soon as you have a domicile.
+
+Opened in an ordinary browser there is no `window.domicile` at all —
+`vite dev` on a shell's page is a real thing to do — and `connectToHost` hands
+back a stand-in that does nothing and says so once on the console. Ask
+`hasHost(window)` if your own code needs the answer.
+
+`navigator.domicile` is the same object and still reads, so `connectToHost`
+takes either global and prefers neither. `window.domicile` is the spelling the
+guides use.
+
+Then render `<app app-id="…">` / `<webview src="…">` as normal DOM and style
+them with ordinary CSS — rounding, blur, transforms, and z-index all apply to the
+live client surface. That is the whole point of Domicile.
+
+Both tags are the fork's own HTML elements, so there is nothing to register and
+nothing here to wrap them in — a custom element's name must contain a hyphen, per
+spec, which is exactly why they are the engine's. Note what that costs in a React
+chrome: a tag without a hyphen is an ordinary HTML element to React, so it writes
+no unrecognized property and binds no `on…` prop for an event it has not heard
+of. Bind the events on a ref.
+
+### Knowing which modifiers are held
+
+**Read them off your own key events.** The desktop is the chrome's window, so
+the page hears every key the user presses whatever the compositor's seat is
+pointed at — that is how `registerElements` forwards a keystroke to a client in
+the first place:
+
+```ts
+const follow = (event: KeyboardEvent) => {
+  // While Alt is held, let the pointer reach the page rather than the window
+  // it is over: `pointer-events: none` is what tells the compositor the
+  // window is not taking clicks, and it hit-tests accordingly.
+  portal.style.pointerEvents = event.altKey ? "none" : "";
+};
+document.addEventListener("keydown", follow);
+document.addEventListener("keyup", follow);
+```
+
+**Not off the host's `modifiers` message, today.** It reports the compositor's
+seat, and the seat only knows the keys this page forwarded to it — which is
+only the keys pressed while a client held the keyboard. A modifier pressed
+while the chrome held it never reaches the seat, and the next forwarded key
+makes the message deny it: a shell that believed the message over its own
+keystrokes read a held Alt as let go of. The message is still sent, and is what
+will say so on the day the compositor reads input itself rather than being
+handed it by this page; it cannot know more than this page until then.
+
+## Dependencies
+
+`zod`, in two places and both of them boundaries. `./protocol` parses the
+compositor's JSON for the headless harness rather than casting it. And
+`./cursor-shape` parses one field off the typed channel — not because the
+engine fails to check it, since `DomicileAppCursorEvent.cursor` is a WebIDL
+`enum` over the same closed set, but because this package and the engine are
+published apart. A shape this list has and the running engine does not arrives
+as a keyword no `DomicileCursorShape` names, and an unknown keyword assigned to
+`style.cursor` fails silently.
+
+Nothing else. `@cprussin/option-result` was a dependency for exactly one
+outcome — `connect()` returning `Result<number, HandshakeFailure>` — and there
+is no handshake to fail. Everything here either throws (a bug, per
+[ERRORS.md](/docs/guidelines/ERRORS.md)) or returns `T | undefined` for
+ordinary absence.
+
+## Test
+
+```sh
+bun run turbo test --filter @domicile-desktop/sdk
+```
+
+DOM-dependent suites run against happy-dom via
+[`@domicile-desktop/test-support`](../test-support/README.md). That DOM performs no
+layout, so the routing tests inject a `measure` stub through
+`registerElements(domicile, { measure })` rather than relying on
+`getBoundingClientRect`.
+
+happy-dom has never heard of `<app>`, so it creates one as an
+`HTMLUnknownElement`, which React's development build reports on the console as
+an unrecognized tag. It cannot happen on the fork, where the tag is
+`HTMLAppElement`; React exempts `dialog` and `webview` from that report by name
+and there is no way to add a third.

package/dist/app-element.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The tag a shell writes.
+ *
+ * Exported because the SDK's own delegation and a shell's stylesheets and tests
+ * all have to name it, and one literal is better than five. Nothing registers
+ * it: `customElements.define` cannot take a name without a hyphen, which is
+ * exactly why the fork defines the element instead.
+ */
+export declare const APP_TAG_NAME = "app";
+/**
+ * Fired on an `<app>` when something asks for the keyboard on its behalf — a
+ * click, today — and cancelable, because who holds the keyboard is the
+ * shell's to decide rather than the SDK's.
+ *
+ * Left uncanceled it focuses the client, so a shell with no focus policy of
+ * its own needs to know nothing about this. A shell that has one — focus that
+ * follows the pointer, a window that may not be interrupted, a click that
+ * raises without focusing — calls `preventDefault()` and then does whatever it
+ * decided, which is usually `focusApp` a moment later.
+ *
+ * THE SDK DISPATCHES THIS, unlike `<webview>`'s two events, which the engine
+ * does. A click inside an `<app>` is a pointer event in this document — the
+ * client is a surface rather than a browsing context — so the page is where the
+ * question can be asked at all.
+ *
+ * It bubbles: a shell renders one `<app>` per window and would otherwise have
+ * to bind a listener to each.
+ */
+export declare const APP_FOCUS_REQUESTED_EVENT = "domicile-focus-requested";
+/** The detail of an {@link APP_FOCUS_REQUESTED_EVENT}. */
+export type AppFocusRequest = {
+    /** The host's name for the client whose window was reached for. */
+    appId: string;
+};
+/**
+ * Fired on the `<app>` that holds the keyboard when a press lands off every
+ * window, and cancelable for the same reason its opposite is: the keyboard
+ * leaving a window is a move of it, and every move is the shell's to decide.
+ *
+ * Left uncanceled the keyboard goes back to the page, which is what a press on
+ * the desktop means and what a shell with no window chrome of its own wants.
+ * A shell that draws chrome *for* a window — a title bar, the sheet a drag is
+ * caught on — calls `preventDefault()` when the press landed on it: that is a
+ * reach for the window rather than away from it, and the SDK cannot tell the
+ * two apart because nothing in the press says which window a `<div>` belongs
+ * to. {@link AppFocusReleaseRequest.pressed} is what the shell reads to say.
+ *
+ * It bubbles, the way {@link APP_FOCUS_REQUESTED_EVENT} does and for the same
+ * reason.
+ */
+export declare const APP_FOCUS_RELEASE_REQUESTED_EVENT = "domicile-focus-release-requested";
+/** The detail of an {@link APP_FOCUS_RELEASE_REQUESTED_EVENT}. */
+export type AppFocusReleaseRequest = {
+    /** The host's name for the client that is about to lose the keyboard. */
+    appId: string;
+    /**
+     * What the press landed on, or `undefined` where it landed on nothing an
+     * element can be read off.
+     */
+    pressed: Element | undefined;
+};
+/**
+ * What an `<app>` is, to everything holding one.
+ *
+ * Global rather than exported, and declared rather than imported, for the same
+ * two reasons `<webview>`'s interface is. React resolves a `ref` on a tag to
+ * whatever global interface the tag-name map names, so an identically-shaped
+ * interface exported from here would be a *different* type that a shell holding
+ * the ref could not assign anywhere — the trap `<webview>` fell into, where
+ * `@types/react` had already declared the name. Nothing has declared this one,
+ * so the SDK is free to; it is declared the same way anyway, because the shape
+ * of the answer should not depend on who got there first.
+ *
+ * And there is nothing to import from: the interface is the fork's, and the
+ * engine ships no `.d.ts`. A shell that runs on stock Chromium gets an
+ * `HTMLUnknownElement` with none of it — the same trade `<webview>` makes, and
+ * the reason the SDK's delegation reads `app-id` off the attribute rather than
+ * off this property.
+ */
+declare global {
+    interface HTMLAppElement extends HTMLElement {
+        /**
+         * Which window this element shows. Reflected, so the attribute and the
+         * property are one value, the way `<img src>` is — and empty rather than
+         * absent when the attribute is not set, which is what a reflected
+         * `DOMString` does.
+         */
+        appId: string;
+    }
+    interface HTMLElementTagNameMap {
+        app: HTMLAppElement;
+    }
+}

package/dist/app-element.js

@@ -0,0 +1,63 @@
+// The fork's `<app>`: a Wayland client's window, laid out by the page.
+//
+// There is no element class here, and that is the point. The element belongs to
+// the engine — `app-id` is a reflected content attribute, and the surface embed
+// and the size the client is configured at are both the layout box's, reported
+// by `LayoutAppSurface` without anything in the page asking. What is left for
+// the SDK to say is the part TypeScript cannot read off the fork: what the tag
+// is, and what the SDK dispatches on it.
+//
+// It used to be a `<domicile-app>` custom element, because a custom element's
+// name must contain a hyphen and the SDK predates the fork. That element did
+// far more than forward: it created a `<canvas>` and called
+// `embedExternalSurface` on it, it measured its own box and reported it, it
+// mapped pointer coordinates, and it took five methods and three properties a
+// shell wrote to. The canvas and the embed are the engine's now; the rest moved
+// to document-level delegation over `closest("app")`, which is what
+// `registerElements` installs — see `pointer-input.ts` and `keyboard-input.ts`.
+/**
+ * The tag a shell writes.
+ *
+ * Exported because the SDK's own delegation and a shell's stylesheets and tests
+ * all have to name it, and one literal is better than five. Nothing registers
+ * it: `customElements.define` cannot take a name without a hyphen, which is
+ * exactly why the fork defines the element instead.
+ */
+export const APP_TAG_NAME = "app";
+/**
+ * Fired on an `<app>` when something asks for the keyboard on its behalf — a
+ * click, today — and cancelable, because who holds the keyboard is the
+ * shell's to decide rather than the SDK's.
+ *
+ * Left uncanceled it focuses the client, so a shell with no focus policy of
+ * its own needs to know nothing about this. A shell that has one — focus that
+ * follows the pointer, a window that may not be interrupted, a click that
+ * raises without focusing — calls `preventDefault()` and then does whatever it
+ * decided, which is usually `focusApp` a moment later.
+ *
+ * THE SDK DISPATCHES THIS, unlike `<webview>`'s two events, which the engine
+ * does. A click inside an `<app>` is a pointer event in this document — the
+ * client is a surface rather than a browsing context — so the page is where the
+ * question can be asked at all.
+ *
+ * It bubbles: a shell renders one `<app>` per window and would otherwise have
+ * to bind a listener to each.
+ */
+export const APP_FOCUS_REQUESTED_EVENT = "domicile-focus-requested";
+/**
+ * Fired on the `<app>` that holds the keyboard when a press lands off every
+ * window, and cancelable for the same reason its opposite is: the keyboard
+ * leaving a window is a move of it, and every move is the shell's to decide.
+ *
+ * Left uncanceled the keyboard goes back to the page, which is what a press on
+ * the desktop means and what a shell with no window chrome of its own wants.
+ * A shell that draws chrome *for* a window — a title bar, the sheet a drag is
+ * caught on — calls `preventDefault()` when the press landed on it: that is a
+ * reach for the window rather than away from it, and the SDK cannot tell the
+ * two apart because nothing in the press says which window a `<div>` belongs
+ * to. {@link AppFocusReleaseRequest.pressed} is what the shell reads to say.
+ *
+ * It bubbles, the way {@link APP_FOCUS_REQUESTED_EVENT} does and for the same
+ * reason.
+ */
+export const APP_FOCUS_RELEASE_REQUESTED_EVENT = "domicile-focus-release-requested";

package/dist/audio.d.ts

@@ -0,0 +1,57 @@
+/** A port of a device, or a profile of a card: something to switch it to. */
+export type AudioChoice = {
+    /** What `setAudioPort` and `setAudioProfile` name it by. */
+    name: string;
+    description: string;
+    /**
+     * `false` for a port whose jack is empty, or a profile that needs one.
+     * Still choosable, as every mixer lets it be.
+     */
+    available: boolean;
+};
+/** An output (a sink) or an input (a source). */
+export type AudioDevice = {
+    id: string;
+    description: string;
+    /**
+     * The loudest of its channels, as a fraction of the server's 100% — more
+     * than 1 for one turned up past it.
+     */
+    volume: number;
+    muted: boolean;
+    /** Whether new streams go to it. */
+    default: boolean;
+    /**
+     * Whether it is an output's monitor — what the output plays, as something
+     * to record. Always `false` for an output.
+     */
+    monitor: boolean;
+    /** Speakers, headphones, a line in. Often empty. */
+    ports: readonly AudioChoice[];
+    /** The {@link AudioChoice.name} of the port in use, if it has ports. */
+    port: string | undefined;
+};
+/** Something playing (a sink input) or recording (a source output). */
+export type AudioStream = {
+    id: string;
+    /** Who is playing or recording it. */
+    application: string;
+    /** What it is — a song, a call — where the application said. */
+    title: string | undefined;
+    volume: number;
+    muted: boolean;
+    /**
+     * The {@link AudioDevice.id} it plays to or records from, or `undefined`
+     * for one the next message will settle.
+     */
+    device: string | undefined;
+};
+/** A sound card, and the profiles that say which of its devices are on. */
+export type AudioCard = {
+    id: string;
+    description: string;
+    /** Best first. */
+    profiles: readonly AudioChoice[];
+    /** The {@link AudioChoice.name} of the profile in use. */
+    profile: string | undefined;
+};

package/dist/audio.js

@@ -0,0 +1,9 @@
+// The desk's sound, as a shell's mixer draws it and asks of it.
+//
+// Its own module for `tray.ts`'s reason: both halves of the SDK need these
+// shapes, and only one of them is the wire. The compositor reads the sound
+// server with `pactl` — PulseAudio's or PipeWire's — see `domicile_host::audio`.
+//
+// Every id is the compositor's, opaque here: what a request names a device or
+// a stream by, taken from the last `audio` message.
+export {};

package/dist/bind-keys.d.ts

@@ -0,0 +1,63 @@
+import type { DomicileClient } from "./domicile-client";
+import type { HostMessageOf, HostMessageType } from "./host-message";
+import type { ShellKeybindings } from "./own-keybindings";
+/** What a shell is told as its keys are answered. */
+export type KeyHandlers = {
+    /** A `send-shell` binding was pressed: the words after `send-shell`. */
+    onCommand: (args: readonly string[]) => void;
+    /** The keys are read in another binding mode now. */
+    onModeChanged: (mode: string) => void;
+};
+/** What {@link bindKeys} hands back. */
+export type KeyBinding = {
+    /** Read the keys in `name` from now on — see {@link bindKeys}. */
+    setMode: (name: string) => void;
+    /** Stop answering. The claims stay. */
+    unbind: () => void;
+};
+/**
+ * What `bindKeys` uses of a client: a {@link DomicileClient}, or anything with
+ * its handler slots and its claim.
+ */
+type KeyClient = {
+    grabShortcut: DomicileClient["grabShortcut"];
+    on<T extends HostMessageType>(type: T, handler: (message: HostMessageOf<T>) => void): unknown;
+    off<T extends HostMessageType>(type: T, handler: (message: HostMessageOf<T>) => void): unknown;
+};
+/**
+ * Answer the keys a shell binds, `own`.
+ *
+ * **`own` is resolved as each keyboard arrives** — `shell_config`, every
+ * keysym the layout types and the key it is on — so a reload that changes the
+ * layout moves the keys with it. A chord written wrong, or whose keysym the
+ * keyboard cannot type, throws there.
+ *
+ * **This owns `shell_config` and `shortcut`.** {@link DomicileClient.on} is a
+ * single slot per message, so a shell that registers either of its own
+ * displaces this.
+ *
+ * **A claim is never given back.** Every chord of every mode is claimed as
+ * each keyboard arrives, because the channel has no way to release one — so a
+ * layout change leaves the keys it moved off the desktop's, answering nothing,
+ * until the shell's page reloads. And for that reason, a bare key bound in a
+ * mode is taken from every client for the whole session, not only while the
+ * mode is on.
+ *
+ * **The mode is tracked here, and a shell can set it.** A desktop of several
+ * pages shares one mode across them — a key that entered it may have landed on
+ * another page — so `setMode` is how a page is told: the keys are read in that
+ * mode from then on, and `onModeChanged` is not called for it, the shell
+ * having said so itself. The mode the keys are already in does nothing; one
+ * the shell does not have goes back to `default`, and that is reported. Before
+ * any keyboard, the mode is kept until one arrives and is checked then.
+ *
+ * **Bind once per client.** The keyboard arrives once and again only when it
+ * changes, so keys bound anew after an unbind answer nothing until the next
+ * change of it. A React shell binds in an effect that depends on the client
+ * and its keys, and reads anything else it needs when a key is pressed.
+ *
+ * @returns `unbind`, which stops the answering — the claims stay, as above —
+ *   and `setMode`.
+ */
+export declare const bindKeys: (domicile: KeyClient, own: ShellKeybindings, { onCommand, onModeChanged }: KeyHandlers) => KeyBinding;
+export {};