API reference

nacre

Import

import * as api from "@fungi.computer/nacre";

Exports

Kind	Export	Description
class	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.
type alias	TeamWorkbenchChildEvents	Team dashboards additionally relay the selected Agent Session to the Hub.
type alias	TeamWorkbenchHostHandle	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.
type alias	WorkbenchResolvedChild	A launch checked against the embedding host’s own installation authority.
type alias	WorkbenchChildSurface	The host’s real mounted App; selection and lease replacement stay with it.
type alias	WorkbenchChildMountOptions	Inputs shared child-window mechanics supply to the host’s admitted mount.
type alias	WorkbenchPreparedChild	Host-owned admission and lifetime of one prepared child.
type alias	WorkbenchHostServices	Host services retain their own Team, account, Gill and consent authority.
type alias	WorkbenchHostControls	Controls offered by the real embedding host, never grants lent by the App.
type alias	WorkbenchWarningEvent	Retained host warning identifiers; adapters own their diagnostic sink.
type alias	WorkbenchWarningFields	Fields of a retained child/settings notification failure.
type alias	WorkbenchHostOptions	One workbench’s child mechanics over host-owned admission and services.
type alias	WorkbenchChildLaunch	A request to resolve and mount one child App, by its own identity.
type alias	WorkbenchCommandInvocation	One invocation of a mounted child’s own Release-declared command.
type alias	WorkbenchChildEvents	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.
type alias	WorkbenchChildHandle	One mounted child App; every method proxies to its real host-owned mount.
type alias	WorkbenchPlatformDestination	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.
type alias	WorkbenchGillRequest	Decoded Gill request for a surface in the host directory.
type alias	DesktopGillSelection	The identity of a Gill selected in a host-rendered settings view.
type alias	DesktopGillAddition	A decoded request to add a Gill placement.
type alias	WorkbenchDesktopSettings	A dashboard supplies its own arranger, not an endpoint for ordinary Apps.
type alias	WorkbenchDesktopRegistration	A registration lease; close it when the dashboard unmounts.
type alias	WorkbenchGillWatch	A host-owned change subscription; close it when no longer visible.
type alias	TeamComputer	A decoded Team Computer inventory record.
constant	workbenchGillRequestSchema	A declared Gill request addressed to one host-selected App surface.
constant	desktopGillSelectionSchema	The member chooses a declared Gill and size in host-rendered Settings.
constant	desktopGillSizesSchema	The dashboard layout sizes currently assigned to one Gill.
constant	desktopGillAdditionSchema	A selected Gill and the layout size requested for a new placement.
constant	desktopSettingsHandlerSchema	Shape of the arranger callbacks the shell supplies to its host.
constant	appOpenRequestSchema	Runtime check for an App-open handoff arriving across an untrusted boundary.
constant	teamComputerSchema	One Team Computer in a host’s inventory: the wire of `computers()`.
constant	teamComputerDirectorySchema	One page of a host’s Team Computer inventory.
function	createBrowserActionHandler()	Browser effects stay in the trusted host, bound to one mounted App frame.

WorkbenchHostclass

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

Constructors

Constructor

new WorkbenchHost(options): WorkbenchHost;

Parameters

Parameter	Type
`options`	`WorkbenchHostOptions`

Returns

WorkbenchHost

Methods

team()

team(): Promise<WhistleJsonValue>;

The authenticated Team hosting this dashboard; the caller parses it.

Returns

Promise<WhistleJsonValue>

Implementation of

TeamWorkbenchHostHandle.team;

computers()

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

TeamWorkbenchHostHandle.computers;

directory()

directory(): Promise<WhistleJsonValue>;

The Team’s effective App directory and role choices; the caller parses it.

Returns

Promise<WhistleJsonValue>

Implementation of

TeamWorkbenchHostHandle.directory;

requestGill()

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	Description
`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`	The App surface the Gill request is addressed to.

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

TeamWorkbenchHostHandle.requestGill;

watchGillChanges()

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>

Implementation of

TeamWorkbenchHostHandle.watchGillChanges;

platformDestinations()

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

TeamWorkbenchHostHandle.platformDestinations;

openPlatformDestination()

openPlatformDestination(id): Promise<void>;

Ask the host to navigate to one offered platform destination.

Parameters

Parameter	Type
`id`	`string`

Returns

Promise<void>

Implementation of

TeamWorkbenchHostHandle.openPlatformDestination;

settingsSections()

settingsSections(): Promise<readonly string[] | null>;

Describe the actual controls without offering unsupported Settings.

Returns

Promise<readonly string[] | null>

Implementation of

TeamWorkbenchHostHandle.settingsSections;

takeAppOpenRequest()

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

TeamWorkbenchHostHandle.takeAppOpenRequest;

registerDesktopSettings()

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>

Implementation of

TeamWorkbenchHostHandle.registerDesktopSettings;

openSettings()

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

TeamWorkbenchHostHandle.openSettings;

memberAvatar()

memberAvatar(): Promise<WhistleJsonValue>;

The signed-in person’s own avatar preference; the caller parses it.

Returns

Promise<WhistleJsonValue>

Implementation of

TeamWorkbenchHostHandle.memberAvatar;

watchSettingsChanges()

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

TeamWorkbenchHostHandle.watchSettingsChanges;

[dispose]()

dispose: void;

The shell unmounted: stop notifying its callbacks.

Returns

void

mount()

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`
`events`	`TeamWorkbenchChildEvents`

Returns

Promise<WorkbenchChildHandle>

Implementation of

TeamWorkbenchHostHandle.mount;

reportAgentSessionSelection()

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

TeamWorkbenchHostHandle.reportAgentSessionSelection;

TeamWorkbenchChildEventstype alias

type TeamWorkbenchChildEvents = WorkbenchChildEvents &
  Readonly<{
    onAgentSessionSelection: (selection) => Promise<void>;
  }>;

Team dashboards additionally relay the selected Agent Session to the Hub.

TeamWorkbenchHostHandletype alias

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()

team(): Promise<WhistleJsonValue>;

The authenticated Team hosting this dashboard; the caller parses it.

Returns

Promise<WhistleJsonValue>

computers()

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()

directory(): Promise<WhistleJsonValue>;

The Team’s effective App directory and role choices; the caller parses it.

Returns

Promise<WhistleJsonValue>

requestGill()

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	Description
`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`	The App surface the Gill request is addressed to.

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()

watchGillChanges(input, onChanged): Promise<WorkbenchGillWatch>;

Observe resource changes; only the host owns the authenticated stream. Close while covered.

Parameters

Parameter	Type	Description
`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`	The App surface the Gill request is addressed to.
`onChanged`	`() => Promise<void>`	-

Returns

Promise<WorkbenchGillWatch>

mount()

mount(
   container,
   input,
   events
): Promise<WorkbenchChildHandle>;

Parameters

Parameter	Type
`container`	`HTMLElement`
`input`	`WorkbenchChildLaunch`
`events`	`TeamWorkbenchChildEvents`

Returns

Promise<WorkbenchChildHandle>

reportAgentSessionSelection()

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()

platformDestinations(): Promise<readonly Readonly<{
  id: string;
  label: string;
}>[]>;

The platform destinations the host currently offers.

Returns

Promise<readonly Readonly<{ id: string; label: string; }>[]>

settingsSections()

settingsSections(): Promise<readonly string[] | null>;

Offered Settings categories, or null for unrestricted host controls.

Returns

Promise<readonly string[] | null>

openPlatformDestination()

openPlatformDestination(id): Promise<void>;

Ask the host to navigate to one offered platform destination.

Parameters

Parameter	Type
`id`	`string`

Returns

Promise<void>

takeAppOpenRequest()

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>;

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()

openSettings(location): Promise<void>;

Parameters

Parameter	Type
`location`	`WhistleJsonValue`

Returns

Promise<void>

registerDesktopSettings()

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`

Returns

Promise<WorkbenchDesktopRegistration>

watchSettingsChanges()

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()

memberAvatar(): Promise<WhistleJsonValue>;

The signed-in person’s own avatar preference; the caller parses it.

Returns

Promise<WhistleJsonValue>

WorkbenchResolvedChildtype alias

type WorkbenchResolvedChild = Readonly<{
  launch: Omit<WorkbenchChildLaunch, "title">;
  title?: string;
}>;

A launch checked against the embedding host’s own installation authority.

WorkbenchChildSurfacetype alias

type WorkbenchChildSurface = Pick<
  WorkbenchChildHandle,
  | "setVisibility"
  | "requestClose"
  | "requestBack"
  | "activateStatus"
  | "activateNavigation"
> &
  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.

WorkbenchChildMountOptionstype alias

type WorkbenchChildMountOptions = Readonly<{
  container: HTMLElement;
  hostWindow: Window;
  title?: string;
  events: TeamWorkbenchChildEvents;
  commands: AppSurfaceCommandMount;
  onDesktopSettings: (surfaceId) => Promise<void>;
  onPermissionRequest: (input, context) => Promise<AppPermissionOutcome>;
}>;

Inputs shared child-window mechanics supply to the host’s admitted mount.

WorkbenchPreparedChildtype alias

type WorkbenchPreparedChild = Readonly<{
  commands: readonly AppCommandDeclaration[];
  mount: Promise<WorkbenchChildSurface>;
  dispose: Promise<void>;
}>;

Host-owned admission and lifetime of one prepared child.

WorkbenchHostServicestype alias

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.

WorkbenchHostControlstype alias

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.

WorkbenchWarningEventtype alias

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.

WorkbenchWarningFieldstype alias

type WorkbenchWarningFields =
  | Readonly<{
      cause: unknown;
    }>
  | Readonly<{
      stage: "update" | "dispose";
      cause: unknown;
    }>;

Fields of a retained child/settings notification failure.

WorkbenchHostOptionstype alias

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.

WorkbenchChildLaunchtype alias

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.

WorkbenchCommandInvocationtype alias

type WorkbenchCommandInvocation = Readonly<{
  arguments?: WhistleJsonValue;
  origin: WhistleExecutionOrigin;
}>;

One invocation of a mounted child’s own Release-declared command.

WorkbenchChildEventstype alias

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.

WorkbenchChildHandletype alias

type WorkbenchChildHandle = object;

One mounted child App; every method proxies to its real host-owned mount.

Methods

setVisibility()

setVisibility(visibility): Promise<void>;

Show or hide the mounted child without changing its identity.

Parameters

Parameter	Type
`visibility`	`"hidden" \| "visible"`

Returns

Promise<void>

reconfigure()

reconfigure(launch): Promise<void>;

Update the launch descriptor of the existing mount.

Parameters

Parameter	Type
`launch`	`WorkbenchChildLaunch`

Returns

Promise<void>

requestClose()

requestClose(): Promise<boolean>;

Ask whether the child permits a user-initiated close.

Returns

Promise<boolean>

requestBack()

requestBack(): Promise<boolean>;

Ask the child to go back one step in its own history; true when it did.

Returns

Promise<boolean>

activateStatus()

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>

activateNavigation()

activateNavigation(activation): Promise<boolean>;

Deliver the person’s use of a child’s crumb or header command; true when it acted.

Parameters

Parameter	Type
`activation`	`AppNavigationActivation`

Returns

Promise<boolean>

invokeCommand()

invokeCommand(commandId, input): Promise<WhistleJsonValue | undefined>;

Run one of the child’s currently presented commands.

Parameters

Parameter	Type
`commandId`	`string`
`input`	`WorkbenchCommandInvocation`

Returns

Promise<WhistleJsonValue | undefined>

dispose()

dispose(): Promise<void>;

Release the child mount and its resources.

Returns

Promise<void>

WorkbenchPlatformDestinationtype alias

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.

WorkbenchGillRequesttype alias

type WorkbenchGillRequest = typeof workbenchGillRequestSchema.Type;

Decoded Gill request for a surface in the host directory.

DesktopGillSelectiontype alias

type DesktopGillSelection = z.output<typeof desktopGillSelectionSchema>;

The identity of a Gill selected in a host-rendered settings view.

DesktopGillAdditiontype alias

type DesktopGillAddition = z.output<typeof desktopGillAdditionSchema>;

A decoded request to add a Gill placement.

WorkbenchDesktopSettingstype alias

type WorkbenchDesktopSettings = object;

A dashboard supplies its own arranger, not an endpoint for ordinary Apps.

Properties

readGill

readGill: (input) => Promise<z.output<typeof desktopGillSizesSchema>>;

Read the sizes currently assigned to this Gill in the dashboard layout.

Parameters

Parameter	Type
`input`	`DesktopGillSelection`

Returns

Promise<z.output<typeof desktopGillSizesSchema>>

addGill

addGill: (input) => Promise<void>;

Add a Gill at the requested size to the dashboard layout.

Parameters

Parameter	Type
`input`	`DesktopGillAddition`

Returns

Promise<void>

removeGill

removeGill: (input) => Promise<void>;

Remove this Gill from the dashboard layout.

Parameters

Parameter	Type
`input`	`DesktopGillSelection`

Returns

Promise<void>

WorkbenchDesktopRegistrationtype alias

type WorkbenchDesktopRegistration = object;

A registration lease; close it when the dashboard unmounts.

Methods

close()

close(): Promise<void>;

Release this host registration.

Returns

Promise<void>

WorkbenchGillWatchtype alias

type WorkbenchGillWatch = object;

A host-owned change subscription; close it when no longer visible.

Methods

close()

close(): Promise<void>;

Release this host registration.

Returns

Promise<void>

TeamComputertype alias

type TeamComputer = z.output<typeof teamComputerSchema>;

A decoded Team Computer inventory record.

workbenchGillRequestSchemaconstant

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.

desktopGillSelectionSchemaconstant

const desktopGillSelectionSchema: ZodObject<
  {
    surfaceId: ZodString;
    gillId: ZodString;
  },
  $strict
>;

The member chooses a declared Gill and size in host-rendered Settings.

desktopGillSizesSchemaconstant

const desktopGillSizesSchema: ZodArray<
  ZodEnum<{
    S: "S";
    M: "M";
    L: "L";
  }>
>;

The dashboard layout sizes currently assigned to one Gill.

desktopGillAdditionSchemaconstant

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.

desktopSettingsHandlerSchemaconstant

const desktopSettingsHandlerSchema: ZodPipe<
  ZodUnknown,
  ZodTransform<object & object, unknown>
>;

Shape of the arranger callbacks the shell supplies to its host.

appOpenRequestSchemaconstant

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.

teamComputerSchemaconstant

const teamComputerSchema: ZodObject<
  {
    computerId: ZodString;
    name: ZodString;
    createdAt: ZodNumber;
    updatedAt: ZodNumber;
  },
  $strict
>;

One Team Computer in a host’s inventory: the wire of computers().

teamComputerDirectorySchemaconstant

const teamComputerDirectorySchema: ZodObject<
  {
    computers: ZodArray<
      ZodObject<
        {
          computerId: ZodString;
          name: ZodString;
          createdAt: ZodNumber;
          updatedAt: ZodNumber;
        },
        $strict
      >
    >;
    nextOffset: ZodNullable<ZodNumber>;
  },
  $strict
>;

One page of a host’s Team Computer inventory.

createBrowserActionHandler()function

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

addressKey

Re-exports addressKey

appAddressSchema

Re-exports appAddressSchema

appAuthorityEnforcementSchema

Re-exports appAuthorityEnforcementSchema

appCatalogBrokerResultSchema

Re-exports appCatalogBrokerResultSchema

appCatalogEntrySchema

Re-exports appCatalogEntrySchema

appCatalogResponseSchema

Re-exports appCatalogResponseSchema

appDirectoryEntrySchema

Re-exports appDirectoryEntrySchema

appRoleSelectionSchema

Re-exports appRoleSelectionSchema

AppAddress

Re-exports AppAddress

AppAuthorityEnforcement

Re-exports AppAuthorityEnforcement

AppCatalog

Re-exports AppCatalog

AppDirectoryEntry

Re-exports AppDirectoryEntry

AppDirectoryGill

Re-exports AppDirectoryGill

ShellChord

Re-exports ShellChord

KeyEventFacts

Re-exports KeyEventFacts

parseChord

Re-exports parseChord

chordMatches

Re-exports chordMatches

LeaderKey

Re-exports LeaderKey

leaderKeys

Re-exports leaderKeys

leaderKeyMatches

Re-exports leaderKeyMatches

ShellKeyHost

Re-exports ShellKeyHost

installShellKeys

Re-exports installShellKeys

WindowLaunch

Re-exports WindowLaunch

WindowStatus

Re-exports WindowStatus

WindowHost

Re-exports WindowHost

WindowEvents

Re-exports WindowEvents

WindowProjection

Re-exports WindowProjection

WindowsProjection

Re-exports WindowsProjection

hasVisibleWindows

Re-exports hasVisibleWindows

WindowMount

Re-exports WindowMount

WindowManager

Re-exports WindowManager

WindowManagerOptions

Re-exports WindowManagerOptions

createWindowManager

Re-exports createWindowManager

nacre

Import

Exports

WorkbenchHostCclass

Implements

Constructors

Constructor

Parameters

Returns

Methods

team()

Returns

Implementation of

computers()

Parameters

Returns

Implementation of

directory()

Returns

Implementation of

requestGill()

Parameters

Returns

Implementation of

watchGillChanges()

Parameters

Returns

Implementation of

platformDestinations()

Returns

Implementation of

openPlatformDestination()

Parameters

Returns

Implementation of

settingsSections()

Returns

Implementation of

takeAppOpenRequest()

Returns

Implementation of

registerDesktopSettings()

Parameters

Returns

Implementation of

openSettings()

Parameters

Returns

Implementation of

memberAvatar()

Returns

Implementation of

watchSettingsChanges()

Parameters

Returns

Implementation of

[dispose]()

Returns

mount()

Parameters

Returns

Implementation of

reportAgentSessionSelection()

Parameters

Returns

Implementation of

TeamWorkbenchChildEventsTtype alias

TeamWorkbenchHostHandleTtype alias

Methods

team()

Returns

computers()

Parameters

Returns

directory()

Returns

requestGill()

Parameters

Returns

watchGillChanges()

WorkbenchHostclass

TeamWorkbenchChildEventstype alias

TeamWorkbenchHostHandletype alias

WorkbenchResolvedChildtype alias

WorkbenchChildSurfacetype alias

WorkbenchChildMountOptionstype alias

WorkbenchPreparedChildtype alias

WorkbenchHostServicestype alias

WorkbenchHostControlstype alias

WorkbenchWarningEventtype alias

WorkbenchWarningFieldstype alias

WorkbenchHostOptionstype alias

WorkbenchChildLaunchtype alias

WorkbenchCommandInvocationtype alias

WorkbenchChildEventstype alias

WorkbenchChildHandletype alias

WorkbenchPlatformDestinationtype alias

WorkbenchGillRequesttype alias

DesktopGillSelectiontype alias

DesktopGillAdditiontype alias

WorkbenchDesktopSettingstype alias