@fungi.computer/oyster 0.2.0 → 0.3.1

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

@@ -1,224 +0,0 @@
-<!-- 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

@@ -1,197 +0,0 @@
-<!-- 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

@@ -1,183 +0,0 @@
-<!-- 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`