@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/docs/api/shell.md

@@ -0,0 +1,1788 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / shell
+
+# shell
+
+## Classes
+
+### WorkbenchHost
+
+Child-window, command and callback lifetime for the trusted shell the host
+composes into its own document. Each child mounts inside the window slot the
+shell hands it, so the browser moves, clips and stacks it with that window; the
+host never positions a child itself.
+
+#### Implements
+
+- [`TeamWorkbenchHostHandle`](#teamworkbenchhosthandle)
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new WorkbenchHost(options): WorkbenchHost;
+```
+
+###### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `options` | [`WorkbenchHostOptions`](#workbenchhostoptions) |
+
+###### Returns
+
+[`WorkbenchHost`](#workbenchhost)
+
+#### Methods
+
+##### team()
+
+```ts
+team(): Promise<WhistleJsonValue>;
+```
+
+The authenticated Team hosting this dashboard; the caller parses it.
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.team;
+```
+
+##### computers()
+
+```ts
+computers(input): Promise<WhistleJsonValue>;
+```
+
+A page of the Team's Computer inventory; the caller parses it.
+
+###### Parameters
+
+| Parameter | Type                                                       |
+| --------- | ---------------------------------------------------------- |
+| `input`   | `Readonly`\<\{ `limit`: `number`; `offset`: `number`; \}\> |
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.computers;
+```
+
+##### directory()
+
+```ts
+directory(): Promise<WhistleJsonValue>;
+```
+
+The Team's effective App directory and role choices; the caller parses it.
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.directory;
+```
+
+##### requestGill()
+
+```ts
+requestGill(input): Promise<
+  | {
+  viewId: string;
+  title: string;
+  state: "empty";
+  rows: readonly [];
+  next?: string;
+}
+  | {
+  viewId: string;
+  title: string;
+  state: "error";
+  rows: readonly [];
+  reason?: "exec_isolation_required" | "params_required";
+  error: string;
+  recovery?:   | {
+     kind: "configure";
+     param: string;
+   }
+     | {
+     kind: "open";
+   };
+}
+  | {
+  viewId: string;
+  title: string;
+  state: "full";
+  rows: readonly object[];
+  next?: string;
+}
+  | {
+  options: readonly object[];
+  next?: string;
+}>;
+```
+
+Invoke a declared Gill of an admitted App in this Team. No caller-provided
+resource data.
+
+###### Parameters
+
+| Parameter         | Type                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`           | \{ `viewId`: `string`; `params?`: \{ \[`key`: `string`\]: `string`; \}; `after?`: `string`; `options?`: `string`; `surfaceId`: `string`; \} |
+| `input.viewId`    | `string`                                                                                                                                    |
+| `input.params?`   | \{ \[`key`: `string`\]: `string`; \}                                                                                                        |
+| `input.after?`    | `string`                                                                                                                                    |
+| `input.options?`  | `string`                                                                                                                                    |
+| `input.surfaceId` | `string`                                                                                                                                    |
+
+###### Returns
+
+`Promise`\< \| \{ `viewId`: `string`; `title`: `string`; `state`: `"empty"`;
+`rows`: readonly \[\]; `next?`: `string`; \} \| \{ `viewId`: `string`; `title`:
+`string`; `state`: `"error"`; `rows`: readonly \[\]; `reason?`:
+`"exec_isolation_required"` \| `"params_required"`; `error`: `string`;
+`recovery?`: \| \{ `kind`: `"configure"`; `param`: `string`; \} \| \{ `kind`:
+`"open"`; \}; \} \| \{ `viewId`: `string`; `title`: `string`; `state`: `"full"`;
+`rows`: readonly `object`[]; `next?`: `string`; \} \| \{ `options`: readonly
+`object`[]; `next?`: `string`; \}\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.requestGill;
+```
+
+##### watchGillChanges()
+
+```ts
+watchGillChanges(...input): Promise<WorkbenchGillWatch>;
+```
+
+Observe resource changes; only the host owns the authenticated stream. Close
+while covered.
+
+###### Parameters
+
+| Parameter  | Type                                    |
+| ---------- | --------------------------------------- |
+| ...`input` | \[`object`, () => `Promise`\<`void`\>\] |
+
+###### Returns
+
+`Promise`\<[`WorkbenchGillWatch`](#workbenchgillwatch)\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.watchGillChanges;
+```
+
+##### platformDestinations()
+
+```ts
+platformDestinations(): Promise<readonly Readonly<{
+  id: string;
+  label: string;
+}>[]>;
+```
+
+The platform destinations the host currently offers.
+
+###### Returns
+
+`Promise`\<readonly `Readonly`\<\{ `id`: `string`; `label`: `string`; \}\>[]\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.platformDestinations;
+```
+
+##### openPlatformDestination()
+
+```ts
+openPlatformDestination(id): Promise<void>;
+```
+
+Ask the host to navigate to one offered platform destination.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.openPlatformDestination;
+```
+
+##### settingsSections()
+
+```ts
+settingsSections(): Promise<readonly string[] | null>;
+```
+
+Describe the actual controls without offering unsupported Settings.
+
+###### Returns
+
+`Promise`\<readonly `string`[] \| `null`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.settingsSections;
+```
+
+##### takeAppOpenRequest()
+
+```ts
+takeAppOpenRequest(): Promise<
+  | {
+  role: string;
+  intent:   | {
+     kind: "compose";
+     text: string;
+   }
+     | {
+     kind: "navigate";
+     params: readonly object[];
+   };
+}
+  | {
+  appId: string;
+  intent:   | {
+     kind: "compose";
+     text: string;
+   }
+     | {
+     kind: "navigate";
+     params: readonly object[];
+   };
+}
+| null>;
+```
+
+Take, once, the App-open handoff the visitor's Hub address carried (for example
+`?open=inbox&intent=compose`). The host consumes it from its own address; the
+dashboard opens it like any other `apps.open` request.
+
+###### Returns
+
+`Promise`\< \| \{ `role`: `string`; `intent`: \| \{ `kind`: `"compose"`; `text`:
+`string`; \} \| \{ `kind`: `"navigate"`; `params`: readonly `object`[]; \}; \}
+\| \{ `appId`: `string`; `intent`: \| \{ `kind`: `"compose"`; `text`: `string`;
+\} \| \{ `kind`: `"navigate"`; `params`: readonly `object`[]; \}; \} \| `null`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.takeAppOpenRequest;
+```
+
+##### registerDesktopSettings()
+
+```ts
+registerDesktopSettings(handler): Promise<WorkbenchDesktopRegistration>;
+```
+
+Bind the admitted dashboard's arranger to the host's member-consent UI. Only the
+host invokes it; ordinary Apps can only open their own Settings.
+
+###### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `handler` | `unknown` |
+
+###### Returns
+
+`Promise`\<[`WorkbenchDesktopRegistration`](#workbenchdesktopregistration)\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.registerDesktopSettings;
+```
+
+##### openSettings()
+
+```ts
+openSettings(location): Promise<void>;
+```
+
+Open the host's own Team settings at a dashboard-defined location (the host
+parses it). Administration there runs with the signed-in person's own authority
+in host-rendered UI, never through the dashboard. Resolves when Settings close,
+so the dashboard restores its own focus.
+
+###### Parameters
+
+| Parameter  | Type               |
+| ---------- | ------------------ |
+| `location` | `WhistleJsonValue` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.openSettings;
+```
+
+##### memberAvatar()
+
+```ts
+memberAvatar(): Promise<WhistleJsonValue>;
+```
+
+The signed-in person's own avatar preference; the caller parses it.
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.memberAvatar;
+```
+
+##### watchSettingsChanges()
+
+```ts
+watchSettingsChanges(onChanged): Promise<void>;
+```
+
+Hear when host-rendered settings or App access consent changed the Team's Apps
+or the person's settings, so the dashboard refreshes.
+
+###### Parameters
+
+| Parameter   | Type                      |
+| ----------- | ------------------------- |
+| `onChanged` | () => `Promise`\<`void`\> |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.watchSettingsChanges;
+```
+
+##### \[dispose\]()
+
+```ts
+dispose: void;
+```
+
+The shell unmounted: stop notifying its callbacks.
+
+###### Returns
+
+`void`
+
+##### mount()
+
+```ts
+mount(
+   container,
+   input,
+   events
+): Promise<WorkbenchChildHandle>;
+```
+
+Resolve, authorize and mount one child App inside `container`, the shell's own
+slot in that App's window. The host never moves the child: the shell keeps
+`container` attached and moves its window instead.
+
+###### Parameters
+
+| Parameter   | Type                                                    |
+| ----------- | ------------------------------------------------------- |
+| `container` | `HTMLElement`                                           |
+| `input`     | [`WorkbenchChildLaunch`](#workbenchchildlaunch)         |
+| `events`    | [`TeamWorkbenchChildEvents`](#teamworkbenchchildevents) |
+
+###### Returns
+
+`Promise`\<[`WorkbenchChildHandle`](#workbenchchildhandle)\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.mount;
+```
+
+##### reportAgentSessionSelection()
+
+```ts
+reportAgentSessionSelection(windowId, selection): Promise<void>;
+```
+
+Bind one mounted child's explicit Agent Session selection to the host.
+
+###### Parameters
+
+| Parameter   | Type                                                                         |
+| ----------- | ---------------------------------------------------------------------------- |
+| `windowId`  | `string`                                                                     |
+| `selection` | \| `Readonly`\<\{ `agentId`: `string`; `sessionId`: `string`; \}\> \| `null` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Implementation of
+
+```ts
+TeamWorkbenchHostHandle.reportAgentSessionSelection;
+```
+
+## Type Aliases
+
+### TeamWorkbenchChildEvents
+
+```ts
+type TeamWorkbenchChildEvents = WorkbenchChildEvents &
+  Readonly<{
+    onAgentSessionSelection: (selection) => Promise<void>;
+  }>;
+```
+
+Team dashboards additionally relay the selected Agent Session to the Hub.
+
+---
+
+### TeamWorkbenchHostHandle
+
+```ts
+type TeamWorkbenchHostHandle = object;
+```
+
+Team/Computer/App-directory reads and child-App hosting for the trusted shell.
+The host composes the shell into its own top-level document, so the shell runs
+with the host's escalated permissions; each child App still runs in its own
+sandboxed frame with its own separately resolved approvals.
+
+#### Methods
+
+##### team()
+
+```ts
+team(): Promise<WhistleJsonValue>;
+```
+
+The authenticated Team hosting this dashboard; the caller parses it.
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+##### computers()
+
+```ts
+computers(input): Promise<WhistleJsonValue>;
+```
+
+A page of the Team's Computer inventory; the caller parses it.
+
+###### Parameters
+
+| Parameter | Type                                                       |
+| --------- | ---------------------------------------------------------- |
+| `input`   | `Readonly`\<\{ `limit`: `number`; `offset`: `number`; \}\> |
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+##### directory()
+
+```ts
+directory(): Promise<WhistleJsonValue>;
+```
+
+The Team's effective App directory and role choices; the caller parses it.
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+##### requestGill()
+
+```ts
+requestGill(input): Promise<
+  | {
+  viewId: Schema.String;
+  title: Schema.String;
+  state: Schema.Literal<"empty">;
+  rows: Schema.Tuple<readonly []>;
+  next?: Schema.optional<Schema.String>;
+}
+  | {
+  viewId: Schema.String;
+  title: Schema.String;
+  state: Schema.Literal<"error">;
+  rows: Schema.Tuple<readonly []>;
+  reason?: Schema.optional<Schema.Literals<readonly ["exec_isolation_required", "params_required"]>>;
+  error: Schema.String;
+  recovery?: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+     kind: Schema.Literal<...>;
+     param: Schema.String;
+   }>, Schema.Struct<{
+     kind: Schema.Literal<...>;
+  }>]>>;
+}
+  | {
+  viewId: Schema.String;
+  title: Schema.String;
+  state: Schema.Literal<"full">;
+  rows: Schema.$Array<Schema.Struct<{
+     id: Schema.String;
+     title: Schema.String;
+     detail: Schema.optional<Schema.String>;
+     tone: Schema.optional<Schema.Literals<readonly [..., ..., ..., ..., ...]>>;
+     status: Schema.optional<Schema.Struct<{
+        label: Schema.String;
+        tone: Schema.Literals<...>;
+     }>>;
+     open: Schema.optional<Schema.Struct<{
+        params: Schema.$Array<...>;
+     }>>;
+  }>>;
+  next?: Schema.optional<Schema.String>;
+}
+  | {
+  options: Schema.$Array<Schema.Struct<{
+     value: Schema.String;
+     label: Schema.String;
+     detail: Schema.optional<Schema.String>;
+  }>>;
+  next?: Schema.optional<Schema.String>;
+}>;
+```
+
+Invoke a declared Gill of an admitted App in this Team. No caller-provided
+resource data.
+
+###### Parameters
+
+| Parameter         | Type                                                                                                                                                                                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`           | \{ `viewId`: `Schema.String`; `params?`: `Schema.optional`\<`Schema.$Record`\<`Schema.String`, `Schema.String`\>\>; `after?`: `Schema.optional`\<`Schema.String`\>; `options?`: `Schema.optional`\<`Schema.String`\>; `surfaceId`: `string`; \} |
+| `input.viewId`    | `Schema.String`                                                                                                                                                                                                                                 |
+| `input.params?`   | `Schema.optional`\<`Schema.$Record`\<`Schema.String`, `Schema.String`\>\>                                                                                                                                                                       |
+| `input.after?`    | `Schema.optional`\<`Schema.String`\>                                                                                                                                                                                                            |
+| `input.options?`  | `Schema.optional`\<`Schema.String`\>                                                                                                                                                                                                            |
+| `input.surfaceId` | `string`                                                                                                                                                                                                                                        |
+
+###### Returns
+
+`Promise`\< \| \{ `viewId`: `Schema.String`; `title`: `Schema.String`; `state`:
+`Schema.Literal`\<`"empty"`\>; `rows`: `Schema.Tuple`\<readonly \[\]\>; `next?`:
+`Schema.optional`\<`Schema.String`\>; \} \| \{ `viewId`: `Schema.String`;
+`title`: `Schema.String`; `state`: `Schema.Literal`\<`"error"`\>; `rows`:
+`Schema.Tuple`\<readonly \[\]\>; `reason?`:
+`Schema.optional`\<`Schema.Literals`\<readonly \[`"exec_isolation_required"`,
+`"params_required"`\]\>\>; `error`: `Schema.String`; `recovery?`:
+`Schema.optional`\<`Schema.Union`\<readonly \[`Schema.Struct`\<\{ `kind`:
+`Schema.Literal`\<...\>; `param`: `Schema.String`; \}\>, `Schema.Struct`\<\{
+`kind`: `Schema.Literal`\<...\>; \}\>\]\>\>; \} \| \{ `viewId`: `Schema.String`;
+`title`: `Schema.String`; `state`: `Schema.Literal`\<`"full"`\>; `rows`:
+`Schema.$Array`\<`Schema.Struct`\<\{ `id`: `Schema.String`; `title`:
+`Schema.String`; `detail`: `Schema.optional`\<`Schema.String`\>; `tone`:
+`Schema.optional`\<`Schema.Literals`\<readonly \[..., ..., ..., ..., ...\]\>\>;
+`status`: `Schema.optional`\<`Schema.Struct`\<\{ `label`: `Schema.String`;
+`tone`: `Schema.Literals`\<...\>; \}\>\>; `open`:
+`Schema.optional`\<`Schema.Struct`\<\{ `params`: `Schema.$Array`\<...\>; \}\>\>;
+\}\>\>; `next?`: `Schema.optional`\<`Schema.String`\>; \} \| \{ `options`:
+`Schema.$Array`\<`Schema.Struct`\<\{ `value`: `Schema.String`; `label`:
+`Schema.String`; `detail`: `Schema.optional`\<`Schema.String`\>; \}\>\>;
+`next?`: `Schema.optional`\<`Schema.String`\>; \}\>
+
+##### watchGillChanges()
+
+```ts
+watchGillChanges(input, onChanged): Promise<WorkbenchGillWatch>;
+```
+
+Observe resource changes; only the host owns the authenticated stream. Close
+while covered.
+
+###### Parameters
+
+| Parameter         | Type                                                                                                                                                                                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`           | \{ `viewId`: `Schema.String`; `params?`: `Schema.optional`\<`Schema.$Record`\<`Schema.String`, `Schema.String`\>\>; `after?`: `Schema.optional`\<`Schema.String`\>; `options?`: `Schema.optional`\<`Schema.String`\>; `surfaceId`: `string`; \} |
+| `input.viewId`    | `Schema.String`                                                                                                                                                                                                                                 |
+| `input.params?`   | `Schema.optional`\<`Schema.$Record`\<`Schema.String`, `Schema.String`\>\>                                                                                                                                                                       |
+| `input.after?`    | `Schema.optional`\<`Schema.String`\>                                                                                                                                                                                                            |
+| `input.options?`  | `Schema.optional`\<`Schema.String`\>                                                                                                                                                                                                            |
+| `input.surfaceId` | `string`                                                                                                                                                                                                                                        |
+| `onChanged`       | () => `Promise`\<`void`\>                                                                                                                                                                                                                       |
+
+###### Returns
+
+`Promise`\<[`WorkbenchGillWatch`](#workbenchgillwatch)\>
+
+##### mount()
+
+```ts
+mount(
+   container,
+   input,
+   events
+): Promise<WorkbenchChildHandle>;
+```
+
+Resolve, authorize and mount one child App inside `container`, the shell's own
+slot in that App's window. The host never moves the child: the shell keeps
+`container` attached and moves its window instead.
+
+###### Parameters
+
+| Parameter   | Type                                                    |
+| ----------- | ------------------------------------------------------- |
+| `container` | `HTMLElement`                                           |
+| `input`     | [`WorkbenchChildLaunch`](#workbenchchildlaunch)         |
+| `events`    | [`TeamWorkbenchChildEvents`](#teamworkbenchchildevents) |
+
+###### Returns
+
+`Promise`\<[`WorkbenchChildHandle`](#workbenchchildhandle)\>
+
+##### reportAgentSessionSelection()
+
+```ts
+reportAgentSessionSelection(windowId, selection): Promise<void>;
+```
+
+Bind one mounted child's explicit Agent Session selection to the host.
+
+###### Parameters
+
+| Parameter   | Type                                                                         |
+| ----------- | ---------------------------------------------------------------------------- |
+| `windowId`  | `string`                                                                     |
+| `selection` | \| `Readonly`\<\{ `agentId`: `string`; `sessionId`: `string`; \}\> \| `null` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### platformDestinations()
+
+```ts
+platformDestinations(): Promise<readonly Readonly<{
+  id: string;
+  label: string;
+}>[]>;
+```
+
+The platform destinations the host currently offers.
+
+###### Returns
+
+`Promise`\<readonly `Readonly`\<\{ `id`: `string`; `label`: `string`; \}\>[]\>
+
+##### settingsSections()
+
+```ts
+settingsSections(): Promise<readonly string[] | null>;
+```
+
+Offered Settings categories, or null for unrestricted host controls.
+
+###### Returns
+
+`Promise`\<readonly `string`[] \| `null`\>
+
+##### openPlatformDestination()
+
+```ts
+openPlatformDestination(id): Promise<void>;
+```
+
+Ask the host to navigate to one offered platform destination.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### takeAppOpenRequest()
+
+```ts
+takeAppOpenRequest(): Promise<
+  | {
+  role: Schema.String;
+  intent: Schema.Union<readonly [Schema.Struct<{
+     kind: Schema.Literal<"compose">;
+     text: Schema.String;
+   }>, Schema.Struct<{
+     kind: Schema.Literal<"navigate">;
+     params: Schema.$Array<Schema.Struct<...>>;
+  }>]>;
+}
+  | {
+  appId: Schema.String;
+  intent: Schema.Union<readonly [Schema.Struct<{
+     kind: Schema.Literal<"compose">;
+     text: Schema.String;
+   }>, Schema.Struct<{
+     kind: Schema.Literal<"navigate">;
+     params: Schema.$Array<Schema.Struct<...>>;
+  }>]>;
+}
+| null>;
+```
+
+Take, once, the App-open handoff the visitor's Hub address carried (for example
+`?open=inbox&intent=compose`). The host consumes it from its own address; the
+dashboard opens it like any other `apps.open` request.
+
+###### Returns
+
+`Promise`\< \| \{ `role`: `Schema.String`; `intent`: `Schema.Union`\<readonly
+\[`Schema.Struct`\<\{ `kind`: `Schema.Literal`\<`"compose"`\>; `text`:
+`Schema.String`; \}\>, `Schema.Struct`\<\{ `kind`:
+`Schema.Literal`\<`"navigate"`\>; `params`:
+`Schema.$Array`\<`Schema.Struct`\<...\>\>; \}\>\]\>; \} \| \{ `appId`:
+`Schema.String`; `intent`: `Schema.Union`\<readonly \[`Schema.Struct`\<\{
+`kind`: `Schema.Literal`\<`"compose"`\>; `text`: `Schema.String`; \}\>,
+`Schema.Struct`\<\{ `kind`: `Schema.Literal`\<`"navigate"`\>; `params`:
+`Schema.$Array`\<`Schema.Struct`\<...\>\>; \}\>\]\>; \} \| `null`\>
+
+##### openSettings()
+
+```ts
+openSettings(location): Promise<void>;
+```
+
+Open the host's own Team settings at a dashboard-defined location (the host
+parses it). Administration there runs with the signed-in person's own authority
+in host-rendered UI, never through the dashboard. Resolves when Settings close,
+so the dashboard restores its own focus.
+
+###### Parameters
+
+| Parameter  | Type               |
+| ---------- | ------------------ |
+| `location` | `WhistleJsonValue` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### registerDesktopSettings()
+
+```ts
+registerDesktopSettings(handler): Promise<WorkbenchDesktopRegistration>;
+```
+
+Bind the admitted dashboard's arranger to the host's member-consent UI. Only the
+host invokes it; ordinary Apps can only open their own Settings.
+
+###### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `handler` | [`WorkbenchDesktopSettings`](#workbenchdesktopsettings) |
+
+###### Returns
+
+`Promise`\<[`WorkbenchDesktopRegistration`](#workbenchdesktopregistration)\>
+
+##### watchSettingsChanges()
+
+```ts
+watchSettingsChanges(onChanged): Promise<void>;
+```
+
+Hear when host-rendered settings or App access consent changed the Team's Apps
+or the person's settings, so the dashboard refreshes.
+
+###### Parameters
+
+| Parameter   | Type                      |
+| ----------- | ------------------------- |
+| `onChanged` | () => `Promise`\<`void`\> |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### memberAvatar()
+
+```ts
+memberAvatar(): Promise<WhistleJsonValue>;
+```
+
+The signed-in person's own avatar preference; the caller parses it.
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue`\>
+
+---
+
+### WorkbenchResolvedChild
+
+```ts
+type WorkbenchResolvedChild = Readonly<{
+  launch: Omit<WorkbenchChildLaunch, "title">;
+  title?: string;
+}>;
+```
+
+A launch checked against the embedding host's own installation authority.
+
+---
+
+### WorkbenchChildSurface
+
+```ts
+type WorkbenchChildSurface = Pick<
+  WorkbenchChildHandle,
+  "setVisibility" | "requestClose" | "requestBack" | "activateStatus"
+> &
+  object;
+```
+
+The host's real mounted App; selection and lease replacement stay with it.
+
+#### Type Declaration
+
+| Name            | Type                              | Description                                                             |
+| --------------- | --------------------------------- | ----------------------------------------------------------------------- |
+| `dispose()`     | () => `void`                      | Release the mounted child or host-owned observations.                   |
+| `reconfigure()` | (`launch`) => `Promise`\<`void`\> | Replace the host-admitted selection while retaining the child document. |
+
+---
+
+### WorkbenchChildMountOptions
+
+```ts
+type WorkbenchChildMountOptions = Readonly<{
+  container: HTMLElement;
+  hostWindow: Window;
+  title?: string;
+  events: TeamWorkbenchChildEvents;
+  commands: AppSurfaceCommandMount;
+  onDesktopSettings: (surfaceId) => Promise<void>;
+  onPermissionRequest: (input) => Promise<AppPermissionOutcome>;
+}>;
+```
+
+Inputs shared child-window mechanics supply to the host's admitted mount.
+
+---
+
+### WorkbenchPreparedChild
+
+```ts
+type WorkbenchPreparedChild = Readonly<{
+  commands: readonly AppCommandDeclaration[];
+  mount: Promise<WorkbenchChildSurface>;
+  dispose: Promise<void>;
+}>;
+```
+
+Host-owned admission and lifetime of one prepared child.
+
+---
+
+### WorkbenchHostServices
+
+```ts
+type WorkbenchHostServices = Pick<
+  TeamWorkbenchHostHandle,
+  | "team"
+  | "computers"
+  | "directory"
+  | "requestGill"
+  | "watchGillChanges"
+  | "memberAvatar"
+> &
+  Readonly<{
+    suggestDesktopSettings: Promise<void>;
+    dispose: void;
+  }>;
+```
+
+Host services retain their own Team, account, Gill and consent authority.
+
+---
+
+### WorkbenchHostControls
+
+```ts
+type WorkbenchHostControls = Readonly<{
+  sections?: readonly string[];
+  parseSettings: WhistleJsonValue;
+  openSettings: void;
+  subscribeSettingsClosed: () => void;
+  subscribeChanges: () => void;
+  attachDesktopSettings: () => void;
+  requestAppAccess: Promise<AppPermissionOutcome>;
+}>;
+```
+
+Controls offered by the real embedding host, never grants lent by the App.
+
+---
+
+### WorkbenchWarningEvent
+
+```ts
+type WorkbenchWarningEvent =
+  | "team_workbench_commands_failed"
+  | "team_workbench_settings_notification_failed"
+  | "team_workbench_focus_notification_failed";
+```
+
+Retained host warning identifiers; adapters own their diagnostic sink.
+
+---
+
+### WorkbenchWarningFields
+
+```ts
+type WorkbenchWarningFields =
+  | Readonly<{
+      cause: unknown;
+    }>
+  | Readonly<{
+      stage: "update" | "dispose";
+      cause: unknown;
+    }>;
+```
+
+Fields of a retained child/settings notification failure.
+
+---
+
+### WorkbenchHostOptions
+
+```ts
+type WorkbenchHostOptions = Readonly<{
+  hostWindow: Window;
+  resolveLaunch: WorkbenchResolvedChild;
+  prepareChild: Promise<
+    Readonly<{
+      commands: readonly AppCommandDeclaration[];
+      mount: Promise<WorkbenchChildSurface>;
+      dispose: Promise<void>;
+    }>
+  >;
+  services: WorkbenchHostServices;
+  reportAgentSessionSelection: void;
+  platform: Readonly<{
+    controls: WorkbenchHostControls;
+    destinations: Promise<
+      readonly Readonly<{
+        id: string;
+        label: string;
+      }>[]
+    >;
+    open: void;
+    takeAppOpenRequest: TeamWorkbenchHostHandle["takeAppOpenRequest"];
+  }>;
+  log: void;
+}>;
+```
+
+One workbench's child mechanics over host-owned admission and services.
+
+---
+
+### WorkbenchChildLaunch
+
+```ts
+type WorkbenchChildLaunch = Readonly<{
+  windowId: string;
+  appId: string;
+  releaseId: string;
+  surfaceId: string;
+  href: string;
+  title?: string;
+  openRequest: AppOpenRequest | null;
+}>;
+```
+
+A request to resolve and mount one child App, by its own identity.
+
+---
+
+### WorkbenchCommandInvocation
+
+```ts
+type WorkbenchCommandInvocation = Readonly<{
+  arguments?: WhistleJsonValue;
+  origin: WhistleExecutionOrigin;
+}>;
+```
+
+One invocation of a mounted child's own Release-declared command.
+
+---
+
+### WorkbenchChildEvents
+
+```ts
+type WorkbenchChildEvents = Readonly<{
+  onComputerChoice?: () => Promise<void>;
+  onNavigation?: (input) => Promise<void>;
+  onAppOpen?: (input) => Promise<void>;
+  onAppRole?: (role) => Promise<AppRoleChoice>;
+  onSelectionChanged?: () => Promise<boolean>;
+  onCommands?: (commands) => Promise<void>;
+  onReservedChord?: (input) => Promise<void>;
+  onFocus?: (focused) => Promise<void>;
+  onNavigationState?: (state) => Promise<void>;
+  onStatusItems?: (items) => Promise<void>;
+}>;
+```
+
+Events a mounted child raises toward its dashboard. A child's permission
+requests never reach the dashboard: the host asks the person itself. The host
+validates a child's commands against that child's own Release declaration before
+forwarding them, so the dashboard can present them but never widen them.
+
+---
+
+### WorkbenchChildHandle
+
+```ts
+type WorkbenchChildHandle = object;
+```
+
+One mounted child App; every method proxies to its real host-owned mount.
+
+#### Methods
+
+##### setVisibility()
+
+```ts
+setVisibility(visibility): Promise<void>;
+```
+
+Show or hide the mounted child without changing its identity.
+
+###### Parameters
+
+| Parameter    | Type                      |
+| ------------ | ------------------------- |
+| `visibility` | `"hidden"` \| `"visible"` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### reconfigure()
+
+```ts
+reconfigure(launch): Promise<void>;
+```
+
+Update the launch descriptor of the existing mount.
+
+###### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `launch`  | [`WorkbenchChildLaunch`](#workbenchchildlaunch) |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### requestClose()
+
+```ts
+requestClose(): Promise<boolean>;
+```
+
+Ask whether the child permits a user-initiated close.
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
+##### requestBack()
+
+```ts
+requestBack(): Promise<boolean>;
+```
+
+Ask the child to go back one step in its own history; `true` when it did.
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
+##### activateStatus()
+
+```ts
+activateStatus(action): Promise<boolean>;
+```
+
+Deliver the person's use of a child's status item; `true` when it acted.
+
+###### Parameters
+
+| Parameter | Type              |
+| --------- | ----------------- |
+| `action`  | `AppStatusAction` |
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
+##### invokeCommand()
+
+```ts
+invokeCommand(commandId, input): Promise<WhistleJsonValue | undefined>;
+```
+
+Run one of the child's currently presented commands.
+
+###### Parameters
+
+| Parameter   | Type                                                        |
+| ----------- | ----------------------------------------------------------- |
+| `commandId` | `string`                                                    |
+| `input`     | [`WorkbenchCommandInvocation`](#workbenchcommandinvocation) |
+
+###### Returns
+
+`Promise`\<`WhistleJsonValue` \| `undefined`\>
+
+##### dispose()
+
+```ts
+dispose(): Promise<void>;
+```
+
+Release the child mount and its resources.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+---
+
+### WorkbenchPlatformDestination
+
+```ts
+type WorkbenchPlatformDestination = Readonly<{
+  id: string;
+  label: string;
+}>;
+```
+
+A platform destination the host offers the dashboard, such as opening a host
+settings page. The host owns the labels and the navigation; the dashboard only
+presents them and asks the host to follow one.
+
+---
+
+### WorkbenchGillRequest
+
+```ts
+type WorkbenchGillRequest = typeof workbenchGillRequestSchema.Type;
+```
+
+Decoded Gill request for a surface in the host directory.
+
+---
+
+### DesktopGillSelection
+
+```ts
+type DesktopGillSelection = z.output<typeof desktopGillSelectionSchema>;
+```
+
+The identity of a Gill selected in a host-rendered settings view.
+
+---
+
+### DesktopGillAddition
+
+```ts
+type DesktopGillAddition = z.output<typeof desktopGillAdditionSchema>;
+```
+
+A decoded request to add a Gill placement.
+
+---
+
+### WorkbenchDesktopSettings
+
+```ts
+type WorkbenchDesktopSettings = object;
+```
+
+A dashboard supplies its own arranger, not an endpoint for ordinary Apps.
+
+#### Properties
+
+##### readGill
+
+```ts
+readGill: (input) => Promise<z.output<typeof desktopGillSizesSchema>>;
+```
+
+Read the sizes currently assigned to this Gill in the dashboard layout.
+
+###### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `input`   | [`DesktopGillSelection`](#desktopgillselection) |
+
+###### Returns
+
+`Promise`\<`z.output`\<_typeof_
+[`desktopGillSizesSchema`](#desktopgillsizesschema)\>\>
+
+##### addGill
+
+```ts
+addGill: (input) => Promise<void>;
+```
+
+Add a Gill at the requested size to the dashboard layout.
+
+###### Parameters
+
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `input`   | [`DesktopGillAddition`](#desktopgilladdition) |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### removeGill
+
+```ts
+removeGill: (input) => Promise<void>;
+```
+
+Remove this Gill from the dashboard layout.
+
+###### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `input`   | [`DesktopGillSelection`](#desktopgillselection) |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+---
+
+### WorkbenchDesktopRegistration
+
+```ts
+type WorkbenchDesktopRegistration = object;
+```
+
+A registration lease; close it when the dashboard unmounts.
+
+#### Methods
+
+##### close()
+
+```ts
+close(): Promise<void>;
+```
+
+Release this host registration.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+---
+
+### WorkbenchGillWatch
+
+```ts
+type WorkbenchGillWatch = object;
+```
+
+A host-owned change subscription; close it when no longer visible.
+
+#### Methods
+
+##### close()
+
+```ts
+close(): Promise<void>;
+```
+
+Release this host registration.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+## Variables
+
+### workbenchGillRequestSchema
+
+```ts
+const workbenchGillRequestSchema: Struct<{
+  viewId: String;
+  params: optional<$Record<String, String>>;
+  after: optional<String>;
+  options: optional<String>;
+  surfaceId: String;
+}>;
+```
+
+A declared Gill request addressed to one host-selected App surface.
+
+---
+
+### desktopGillSelectionSchema
+
+```ts
+const desktopGillSelectionSchema: ZodObject<
+  {
+    surfaceId: ZodString;
+    gillId: ZodString;
+  },
+  $strict
+>;
+```
+
+The member chooses a declared Gill and size in host-rendered Settings.
+
+---
+
+### desktopGillSizesSchema
+
+```ts
+const desktopGillSizesSchema: ZodArray<
+  ZodEnum<{
+    S: "S";
+    M: "M";
+    L: "L";
+  }>
+>;
+```
+
+The dashboard layout sizes currently assigned to one Gill.
+
+---
+
+### desktopGillAdditionSchema
+
+```ts
+const desktopGillAdditionSchema: ZodObject<
+  {
+    surfaceId: ZodString;
+    gillId: ZodString;
+    size: ZodEnum<{
+      S: "S";
+      M: "M";
+      L: "L";
+    }>;
+  },
+  $strict
+>;
+```
+
+A selected Gill and the layout size requested for a new placement.
+
+---
+
+### desktopSettingsHandlerSchema
+
+```ts
+const desktopSettingsHandlerSchema: ZodPipe<
+  ZodUnknown,
+  ZodTransform<object & object, unknown>
+>;
+```
+
+Shape of the arranger callbacks the shell supplies to its host.
+
+---
+
+### appOpenRequestSchema
+
+```ts
+const appOpenRequestSchema: Union<
+  readonly [
+    Struct<{
+      kind: Literal<"compose">;
+      requestId: String;
+      text: String;
+    }>,
+    Struct<{
+      kind: Literal<"navigate">;
+      requestId: String;
+      params: $Array<
+        Struct<{
+          key: String;
+          value: String;
+        }>
+      >;
+    }>,
+  ]
+>;
+```
+
+Runtime check for an App-open handoff arriving across an untrusted boundary.
+
+## Functions
+
+### createBrowserActionHandler()
+
+```ts
+function createBrowserActionHandler(
+  options,
+): (request) => Promise<AppBrowserActionOutcome>;
+```
+
+Browser effects stay in the trusted host, bound to one mounted App frame.
+
+#### Parameters
+
+| Parameter            | Type                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| `options`            | \{ `frame`: `HTMLIFrameElement`; `hostWindow`: `Window`; `signal`: `AbortSignal`; \} |
+| `options.frame`      | `HTMLIFrameElement`                                                                  |
+| `options.hostWindow` | `Window`                                                                             |
+| `options.signal`     | `AbortSignal`                                                                        |
+
+#### Returns
+
+(`request`) => `Promise`\<`AppBrowserActionOutcome`\>
+
+## References
+
+### appAddressSchema
+
+Re-exports [appAddressSchema](shell/app-directory.md#appaddressschema)
+
+---
+
+### appAuthorityEnforcementSchema
+
+Re-exports
+[appAuthorityEnforcementSchema](shell/app-directory.md#appauthorityenforcementschema)
+
+---
+
+### AppAddress
+
+Re-exports [AppAddress](shell/app-directory.md#appaddress)
+
+---
+
+### addressKey
+
+Re-exports [addressKey](shell/app-directory.md#addresskey)
+
+---
+
+### AppAuthorityEnforcement
+
+Re-exports
+[AppAuthorityEnforcement](shell/app-directory.md#appauthorityenforcement)
+
+---
+
+### AppDirectoryGill
+
+Re-exports [AppDirectoryGill](shell/app-directory.md#appdirectorygill)
+
+---
+
+### appDirectoryEntrySchema
+
+Re-exports
+[appDirectoryEntrySchema](shell/app-directory.md#appdirectoryentryschema)
+
+---
+
+### AppDirectoryEntry
+
+Re-exports [AppDirectoryEntry](shell/app-directory.md#appdirectoryentry)
+
+---
+
+### appRoleSelectionSchema
+
+Re-exports
+[appRoleSelectionSchema](shell/app-directory.md#approleselectionschema)
+
+---
+
+### appCatalogEntrySchema
+
+Re-exports [appCatalogEntrySchema](shell/app-directory.md#appcatalogentryschema)
+
+---
+
+### appCatalogResponseSchema
+
+Re-exports
+[appCatalogResponseSchema](shell/app-directory.md#appcatalogresponseschema)
+
+---
+
+### AppCatalog
+
+Re-exports [AppCatalog](shell/app-directory.md#appcatalog)
+
+---
+
+### appCatalogBrokerResultSchema
+
+Re-exports
+[appCatalogBrokerResultSchema](shell/app-directory.md#appcatalogbrokerresultschema)
+
+---
+
+### AppCommandOptional
+
+Re-exports [AppCommandOptional](shell/command-host.md#appcommandoptional)
+
+---
+
+### AppCommandDeclaration
+
+Re-exports [AppCommandDeclaration](shell/command-host.md#appcommanddeclaration)
+
+---
+
+### commandPaletteReservedChordForPlatform
+
+Re-exports
+[commandPaletteReservedChordForPlatform](shell/command-host.md#commandpalettereservedchordforplatform)
+
+---
+
+### commandPaletteReservedChordForUserAgent
+
+Re-exports
+[commandPaletteReservedChordForUserAgent](shell/command-host.md#commandpalettereservedchordforuseragent)
+
+---
+
+### appDirectorySourceId
+
+Re-exports [appDirectorySourceId](shell/command-host.md#appdirectorysourceid)
+
+---
+
+### AppSurfaceCommandMount
+
+Re-exports
+[AppSurfaceCommandMount](shell/command-host.md#appsurfacecommandmount)
+
+---
+
+### PaneCommands
+
+Re-exports [PaneCommands](shell/command-host.md#panecommands)
+
+---
+
+### PaneCommandMount
+
+Re-exports [PaneCommandMount](shell/command-host.md#panecommandmount)
+
+---
+
+### AppSurfaceCommandHost
+
+Re-exports [AppSurfaceCommandHost](shell/command-host.md#appsurfacecommandhost)
+
+---
+
+### createAppSurfaceCommandHost
+
+Re-exports
+[createAppSurfaceCommandHost](shell/command-host.md#createappsurfacecommandhost)
+
+---
+
+### backBinding
+
+Re-exports [backBinding](shell/commands.md#backbinding)
+
+---
+
+### ShellActions
+
+Re-exports [ShellActions](shell/commands.md#shellactions)
+
+---
+
+### shellCommands
+
+Re-exports [shellCommands](shell/commands.md#shellcommands)
+
+---
+
+### ShellChord
+
+Re-exports [ShellChord](shell/keys.md#shellchord)
+
+---
+
+### KeyEventFacts
+
+Re-exports [KeyEventFacts](shell/keys.md#keyeventfacts)
+
+---
+
+### parseChord
+
+Re-exports [parseChord](shell/keys.md#parsechord)
+
+---
+
+### chordMatches
+
+Re-exports [chordMatches](shell/keys.md#chordmatches)
+
+---
+
+### LeaderKey
+
+Re-exports [LeaderKey](shell/keys.md#leaderkey)
+
+---
+
+### leaderKeys
+
+Re-exports [leaderKeys](shell/keys.md#leaderkeys)
+
+---
+
+### leaderKeyMatches
+
+Re-exports [leaderKeyMatches](shell/keys.md#leaderkeymatches)
+
+---
+
+### ShellKeyHost
+
+Re-exports [ShellKeyHost](shell/keys.md#shellkeyhost)
+
+---
+
+### installShellKeys
+
+Re-exports [installShellKeys](shell/keys.md#installshellkeys)
+
+---
+
+### WindowLaunch
+
+Re-exports [WindowLaunch](shell/window-manager.md#windowlaunch)
+
+---
+
+### WindowStatus
+
+Re-exports [WindowStatus](shell/window-manager.md#windowstatus)
+
+---
+
+### WindowHost
+
+Re-exports [WindowHost](shell/window-manager.md#windowhost)
+
+---
+
+### WindowEvents
+
+Re-exports [WindowEvents](shell/window-manager.md#windowevents)
+
+---
+
+### WindowProjection
+
+Re-exports [WindowProjection](shell/window-manager.md#windowprojection)
+
+---
+
+### WindowsProjection
+
+Re-exports [WindowsProjection](shell/window-manager.md#windowsprojection)
+
+---
+
+### hasVisibleWindows
+
+Re-exports [hasVisibleWindows](shell/window-manager.md#hasvisiblewindows)
+
+---
+
+### WindowMount
+
+Re-exports [WindowMount](shell/window-manager.md#windowmount)
+
+---
+
+### WindowManager
+
+Re-exports [WindowManager](shell/window-manager.md#windowmanager)
+
+---
+
+### WindowManagerOptions
+
+Re-exports [WindowManagerOptions](shell/window-manager.md#windowmanageroptions)
+
+---
+
+### createWindowManager
+
+Re-exports [createWindowManager](shell/window-manager.md#createwindowmanager)