command-host

Import

Import

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

Exports

Kind	Export	Description
Ttype alias	AppCommandOptional	An optional field a declaration may carry as explicitly undefined.
Ttype alias	AppCommandDeclaration	The digest-covered command rows a mounted App’s Release declares, as the host receives them. Oyster compares and projects them; the Release declaration grammar stays with its owner, which hands rows of this shape.
Ttype alias	AppSurfaceCommandMount	The command side of one mounted App’s host handlers.
Ttype alias	PaneCommands	Commands owned by one pane, projected to globals plus its focus scope.
Ttype alias	PaneCommandMount	Closing a pane withdraws all its leases, presenters and subscriptions.
Ttype alias	AppSurfaceCommandHost	The shell-owned Whistle graph and its focused menu projection.
constconstant	appDirectorySourceId	Whistle source of Release-advertised rows for Apps not yet mounted.
fnfunction	commandPaletteReservedChordForPlatform()	Select the shell command-palette chord for a Mac or non-Mac keyboard.
fnfunction	commandPaletteReservedChordForUserAgent()	Select the shell command-palette chord from the embedding browser user agent.
fnfunction	createAppSurfaceCommandHost()	Own one shell’s Whistle runtime for mounted Apps and local panes. The embedding host supplies verified Release declarations and decides which App or pane has focus.

AppCommandOptionalTtype alias

Signature

type AppCommandOptional<T> = T | undefined;

An optional field a declaration may carry as explicitly undefined.

Type Parameters

Type Parameter
T

---

AppCommandDeclarationTtype alias

Signature

type AppCommandDeclaration = Readonly<{
  id: string;
  title: string;
  category: string;
  description?: AppCommandOptional<string>;
  projections?: AppCommandOptional<
    Readonly<{
      bindings?: AppCommandOptional<
        Readonly<{
          order?: AppCommandOptional<number>;
          values: readonly string[];
        }>
      >;
      agent?: AppCommandOptional<
        Readonly<{
          order?: AppCommandOptional<number>;
          keybind?: AppCommandOptional<string>;
        }>
      >;
      help?: AppCommandOptional<
        Readonly<{
          order?: AppCommandOptional<number>;
        }>
      >;
      menu?: AppCommandOptional<
        Readonly<{
          order?: AppCommandOptional<number>;
        }>
      >;
      palette?: AppCommandOptional<
        Readonly<{
          order?: AppCommandOptional<number>;
        }>
      >;
      slash?: AppCommandOptional<
        Readonly<{
          order?: AppCommandOptional<number>;
          aliases: readonly string[];
        }>
      >;
    }>
  >;
}>;

The digest-covered command rows a mounted App’s Release declares, as the host receives them. Oyster compares and projects them; the Release declaration grammar stays with its owner, which hands rows of this shape.

---

AppSurfaceCommandMountTtype alias

Signature

type AppSurfaceCommandMount = Readonly<{
  agentCommands: Pick<WhistleRuntime, "snapshot" | "execute">;
  handlers: Pick<AppHostHandlers, "registerCommands" | "invokeReservedChord">;
  dispose: () => void;
}>;

The command side of one mounted App’s host handlers.

---

PaneCommandsTtype alias

Signature

type PaneCommands = Readonly<{
  commandId: (id) => string;
  contribute: (commands) => WhistleContributionLease;
  execute: WhistleRuntime["execute"];
  snapshot: WhistleRuntime["snapshot"];
  subscribe: WhistleRuntime["subscribe"];
  present: WhistleRuntime["present"];
}>;

Commands owned by one pane, projected to globals plus its focus scope.

---

PaneCommandMountTtype alias

Signature

type PaneCommandMount = PaneCommands &
  Readonly<{
    dispose: () => void;
  }>;

Closing a pane withdraws all its leases, presenters and subscriptions.

---

AppSurfaceCommandHostTtype alias

Signature

type AppSurfaceCommandHost = Readonly<{
  mountPane: (paneId) => PaneCommandMount;
  mount: (mountId, declarations) => AppSurfaceCommandMount;
  focus: (mountId) => void;
  registerShellCommands: (commands) => () => void;
  registerDirectoryCommands: (commands, run) => () => void;
  menu: () => readonly WhistleMenuProjection[];
  active: () => WhistleSnapshot;
  execute: (commandId, input) => Promise<WhistleExecutionOutcome>;
  snapshot: () => WhistleSnapshot;
  subscribe: (listener) => () => void;
  dispose: () => void;
}>;

The shell-owned Whistle graph and its focused menu projection.

appDirectorySourceIdconstconstant

Signature

const appDirectorySourceId: "app-directory" = "app-directory";

Whistle source of Release-advertised rows for Apps not yet mounted.

commandPaletteReservedChordForPlatform()fnfunction

Signature

function commandPaletteReservedChordForPlatform(mac): AppHostReservedChord;

Select the shell command-palette chord for a Mac or non-Mac keyboard.

Parameters

Parameter	Type
mac	boolean

Returns

AppHostReservedChord

---

commandPaletteReservedChordForUserAgent()fnfunction

Signature

function commandPaletteReservedChordForUserAgent(
  userAgent,
): AppHostReservedChord;

Select the shell command-palette chord from the embedding browser user agent.

Parameters

Parameter	Type
userAgent	string

Returns

AppHostReservedChord

---

createAppSurfaceCommandHost()fnfunction

Signature

function createAppSurfaceCommandHost(whistle?): AppSurfaceCommandHost;

Own one shell’s Whistle runtime for mounted Apps and local panes. The embedding host supplies verified Release declarations and decides which App or pane has focus.

Agar invokes registerCommands once for the aggregate command set of a mount. The adapter keeps that aggregate as one Whistle generation, so an Agar update replaces the generation atomically and disposal releases only that App. Command handlers remain the App’s callback; the shell only adds the Whistle identity and routes focused menu execution to it.

Parameters

Parameter	Type
whistle	WhistleRuntime

Returns

AppSurfaceCommandHost