@fungi.computer/oyster 0.0.0-stage → 0.0.1

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`

package/docs/api/shell/shell-module.md

@@ -0,0 +1,143 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/shell-module
+
+# shell/shell-module
+
+## Classes
+
+### ShellModuleError
+
+The picked shell's module could not be loaded or does not fit the contract.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ShellModuleError(message?): ShellModuleError;
+```
+
+###### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `message?` | `string` |
+
+###### Returns
+
+[`ShellModuleError`](#shellmoduleerror)
+
+###### Inherited from
+
+```ts
+Error.constructor;
+```
+
+##### Constructor
+
+```ts
+new ShellModuleError(message?, options?): ShellModuleError;
+```
+
+###### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `message?` | `string`       |
+| `options?` | `ErrorOptions` |
+
+###### Returns
+
+[`ShellModuleError`](#shellmoduleerror)
+
+###### Inherited from
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "ShellModuleError" = "ShellModuleError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+## Type Aliases
+
+### ShellMountInput
+
+```ts
+type ShellMountInput = Readonly<{
+  workbench: TeamWorkbenchHostHandle;
+  storage: AppStorage;
+  methods: Readonly<{
+    call: Promise<WhistleJsonValue>;
+  }>;
+}>;
+```
+
+What a host hands the shell a Team picked. The host composes that shell into its
+own top-level document, so it runs with the host's escalated permissions: the
+workbench mounts each child App in its sandboxed frame, and `storage`/`methods`
+are the shell installation's own desktop data.
+
+---
+
+### MountShell
+
+```ts
+type MountShell = (root, input) => Promise<() => void>;
+```
+
+Render the shell into `root`; resolves once it is mounted, with the function
+that removes it again. The shell loads its own code and styles.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `root`    | `HTMLElement`                         |
+| `input`   | [`ShellMountInput`](#shellmountinput) |
+
+#### Returns
+
+`Promise`\<() => `void`\>
+
+## Functions
+
+### importShellModule()
+
+```ts
+function importShellModule(moduleUrl, hostOrigin): Promise<MountShell>;
+```
+
+Import the picked shell Release's module from the host's own origin and check
+that it exports `mountShell`. The host never bundles a shell.
+
+#### Parameters
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `moduleUrl`  | `URL`    |
+| `hostOrigin` | `string` |
+
+#### Returns
+
+`Promise`\<[`MountShell`](#mountshell)\>