@fungi.computer/nacre 0.0.0-stage → 0.0.1

package/docs/api/command-host.md

@@ -0,0 +1,225 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/nacre**](README.md)
+
+---
+
+[@fungi.computer/nacre](README.md) / command-host
+
+# command-host
+
+## Type Aliases
+
+### AppCommandOptional
+
+```ts
+type AppCommandOptional<T> = T | undefined;
+```
+
+An optional field a declaration may carry as explicitly undefined.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+---
+
+### AppCommandDeclaration
+
+```ts
+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.
+
+---
+
+### AppSurfaceCommandMount
+
+```ts
+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.
+
+---
+
+### PaneCommands
+
+```ts
+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.
+
+---
+
+### PaneCommandMount
+
+```ts
+type PaneCommandMount = PaneCommands &
+  Readonly<{
+    dispose: () => void;
+  }>;
+```
+
+Closing a pane withdraws all its leases, presenters and subscriptions.
+
+---
+
+### AppSurfaceCommandHost
+
+```ts
+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.
+
+## Variables
+
+### appDirectorySourceId
+
+```ts
+const appDirectorySourceId: "app-directory" = "app-directory";
+```
+
+Whistle source of Release-advertised rows for Apps not yet mounted.
+
+## Functions
+
+### commandPaletteReservedChordForPlatform()
+
+```ts
+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()
+
+```ts
+function commandPaletteReservedChordForUserAgent(
+  userAgent,
+): AppHostReservedChord;
+```
+
+Select the shell command-palette chord from the embedding browser user agent.
+
+#### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `userAgent` | `string` |
+
+#### Returns
+
+`AppHostReservedChord`
+
+---
+
+### createAppSurfaceCommandHost()
+
+```ts
+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`](#appsurfacecommandhost)

package/docs/api/commands.md

@@ -0,0 +1,199 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/nacre**](README.md)
+
+---
+
+[@fungi.computer/nacre](README.md) / commands
+
+# commands
+
+## Type Aliases
+
+### ShellActions
+
+```ts
+type ShellActions = Readonly<{
+  openApp: () => void;
+  showKeys: () => void;
+  showCommandLine: () => void;
+  focusStep: (step) => void;
+  swapStep: (step) => void;
+  toggleZoom: () => void;
+  back?: () => void;
+}>;
+```
+
+The behavior supplied by either a browser or terminal workspace shell.
+
+## Variables
+
+### backBinding
+
+```ts
+const backBinding: "<leader>[" = "<leader>[";
+```
+
+The Back binding, also shown by the shell in window chrome.
+
+## Functions
+
+### shellCommands()
+
+```ts
+function shellCommands(actions): readonly Readonly<{
+  id: string;
+  title: string;
+  category: string;
+  description?: string;
+  projections?: {
+     bindings?: {
+        order?: number;
+        values: readonly string[];
+     };
+     agent?: {
+        keybind?: string;
+        order?: number;
+     };
+     help?: {
+        order?: number;
+     };
+     menu?: {
+        order?: number;
+     };
+     palette?: {
+        order?: number;
+     };
+     slash?: {
+        aliases: readonly string[];
+        consumesDraft?: boolean;
+        order?: number;
+        arguments?: {
+           hint: string;
+           words?: readonly ...[];
+           text?: {
+              field: ...;
+              arguments: ...;
+              requestIdField?: ...;
+           };
+        };
+     };
+  };
+  action?: {
+     inputSchema?: {
+      [key: string]:
+        | string
+        | number
+        | boolean
+        | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...[]
+        | {
+      [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...;
+      }
+        | null;
+     };
+     outputSchema?: {
+      [key: string]:
+        | string
+        | number
+        | boolean
+        | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...[]
+        | {
+      [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...;
+      }
+        | null;
+     };
+     presentation?:   | {
+        type: "action";
+      }
+        | {
+        type: "custom";
+        data: {
+         [key: string]:
+           | string
+           | number
+           | boolean
+           | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...[]
+           | {
+         [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...;
+         }
+           | null;
+        };
+      }
+        | {
+        type: "choice";
+        options: readonly object[];
+      }
+        | {
+        type: "form";
+        submitLabel?: string;
+      }
+        | {
+        type: "confirmation";
+        message: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+      };
+  };
+  availability?: () => WhistleAvailability;
+  handler: (input) => unknown;
+}>[];
+```
+
+Shared workspace declarations. Window moves have direct Alt chords and leader
+keys; global actions live behind the shell-owned leader.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `actions` | [`ShellActions`](#shellactions) |
+
+#### Returns
+
+readonly `Readonly`\<\{ `id`: `string`; `title`: `string`; `category`: `string`;
+`description?`: `string`; `projections?`: \{ `bindings?`: \{ `order?`: `number`;
+`values`: readonly `string`[]; \}; `agent?`: \{ `keybind?`: `string`; `order?`:
+`number`; \}; `help?`: \{ `order?`: `number`; \}; `menu?`: \{ `order?`:
+`number`; \}; `palette?`: \{ `order?`: `number`; \}; `slash?`: \{ `aliases`:
+readonly `string`[]; `consumesDraft?`: `boolean`; `order?`: `number`;
+`arguments?`: \{ `hint`: `string`; `words?`: readonly ...[]; `text?`: \{
+`field`: ...; `arguments`: ...; `requestIdField?`: ...; \}; \}; \}; \};
+`action?`: \{ `inputSchema?`: \{ \[`key`: `string`\]: \| `string` \| `number` \|
+`boolean` \| readonly string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| number \| boolean \| readonly (string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{
+\[`key`: `string`\]: string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| number \| boolean \| readonly (string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \|
+`null`; \}; `outputSchema?`: \{ \[`key`: `string`\]: \| `string` \| `number` \|
+`boolean` \| readonly string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| number \| boolean \| readonly (string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{
+\[`key`: `string`\]: string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| number \| boolean \| readonly (string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \|
+`null`; \}; `presentation?`: \| \{ `type`: `"action"`; \} \| \{ `type`:
+`"custom"`; `data`: \{ \[`key`: `string`\]: \| `string` \| `number` \| `boolean`
+\| readonly string \| number \| boolean \| readonly (string \| number \| boolean
+\| readonly (string \| number \| boolean \| readonly (string \| number \|
+boolean \| readonly (string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \|
+null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{ \[`key`:
+`string`\]: string \| number \| boolean \| readonly (string \| number \| boolean
+\| readonly (string \| number \| boolean \| readonly (string \| number \|
+boolean \| readonly (string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \|
+null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \| `null`; \}; \}
+\| \{ `type`: `"choice"`; `options`: readonly `object`[]; \} \| \{ `type`:
+`"form"`; `submitLabel?`: `string`; \} \| \{ `type`: `"confirmation"`;
+`message`: `string`; `confirmLabel?`: `string`; `cancelLabel?`: `string`; \};
+\}; `availability?`: () => `WhistleAvailability`; `handler`: (`input`) =>
+`unknown`; \}\>[]