@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/shell/command-host.md

@@ -0,0 +1,224 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/command-host
+
+# shell/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<{
+  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/shell/commands.md

@@ -0,0 +1,197 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/commands
+
+# shell/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[];
+        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`[]; `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`; \}\>[]

package/docs/api/shell/keys.md

@@ -0,0 +1,183 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/keys
+
+# shell/keys
+
+## Type Aliases
+
+### ShellChord
+
+```ts
+type ShellChord = Readonly<{
+  key: string;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+}>;
+```
+
+One physical chord parsed from a Whistle binding such as `alt+left`.
+
+---
+
+### KeyEventFacts
+
+```ts
+type KeyEventFacts = Pick<
+  KeyboardEvent,
+  "altKey" | "ctrlKey" | "key" | "metaKey" | "shiftKey"
+>;
+```
+
+Keyboard facts shared by DOM events and terminal adapters.
+
+---
+
+### LeaderKey
+
+```ts
+type LeaderKey = WhistleBindingProjection &
+  Readonly<{
+    key: string;
+  }>;
+```
+
+One key offered after the leader chord, with the command it runs.
+
+---
+
+### ShellKeyHost
+
+```ts
+type ShellKeyHost = Readonly<{
+  active: () => WhistleSnapshot;
+  subscribe: (listener) => () => void;
+  execute: (commandId, input) => Promise<WhistleExecutionOutcome>;
+}>;
+```
+
+The shell host operations the key dispatcher reads.
+
+## Functions
+
+### parseChord()
+
+```ts
+function parseChord(
+  binding,
+  mac,
+): Readonly<{
+  key: string;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+}> | null;
+```
+
+Parse one single-chord binding. Sequences (including `<leader> x`) and unknown
+modifiers return `null`; they are never matched as one chord.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `binding` | `string`  |
+| `mac`     | `boolean` |
+
+#### Returns
+
+\| `Readonly`\<\{ `key`: `string`; `alt`: `boolean`; `ctrl`: `boolean`; `meta`:
+`boolean`; `shift`: `boolean`; \}\> \| `null`
+
+---
+
+### chordMatches()
+
+```ts
+function chordMatches(event, chord): boolean;
+```
+
+Whether one key event is exactly this chord.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `event`   | [`KeyEventFacts`](#keyeventfacts) |
+| `chord`   | [`ShellChord`](#shellchord)       |
+
+#### Returns
+
+`boolean`
+
+---
+
+### leaderKeys()
+
+```ts
+function leaderKeys(active): readonly LeaderKey[];
+```
+
+The `<leader> x` rows of the active view, first binding per key.
+
+#### Parameters
+
+| Parameter | Type              |
+| --------- | ----------------- |
+| `active`  | `WhistleSnapshot` |
+
+#### Returns
+
+readonly [`LeaderKey`](#leaderkey)[]
+
+---
+
+### leaderKeyMatches()
+
+```ts
+function leaderKeyMatches(event, key): boolean;
+```
+
+Whether one key event (after the leader) selects this leader key.
+
+#### Parameters
+
+| Parameter | Type                                                                           |
+| --------- | ------------------------------------------------------------------------------ |
+| `event`   | `Pick`\<`KeyboardEvent`, `"altKey"` \| `"ctrlKey"` \| `"key"` \| `"metaKey"`\> |
+| `key`     | `string`                                                                       |
+
+#### Returns
+
+`boolean`
+
+---
+
+### installShellKeys()
+
+```ts
+function installShellKeys(root, host, mac): () => void;
+```
+
+Dispatch the active view's single-chord bindings from the shell document. Text
+entry is a mode: while an input is focused only Ctrl/Cmd chords fire, so
+Alt-arrows keep their word-navigation meaning.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `root`    | `HTMLElement`                   |
+| `host`    | [`ShellKeyHost`](#shellkeyhost) |
+| `mac`     | `boolean`                       |
+
+#### Returns
+
+() => `void`