@fungi.computer/nacre 0.0.0-stage → 0.0.2

package/docs/api/keys.md

@@ -0,0 +1,183 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/nacre**](README.md)
+
+---
+
+[@fungi.computer/nacre](README.md) / keys
+
+# 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 single-keystroke `<leader>x` rows, 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-module.md

@@ -0,0 +1,233 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/nacre**](README.md)
+
+---
+
+[@fungi.computer/nacre](README.md) / shell-module
+
+# 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";
+```
+
+Always 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`\>
+
+---
+
+### ShellPlatformControls
+
+```ts
+type ShellPlatformControls = Readonly<{
+  controls: WorkbenchHostControls;
+  suggestDesktopSettings: void;
+  dispose: void;
+}>;
+```
+
+Settings a shell renders for a host that has none of its own, such as a
+standalone Oyster: the shell draws them into `root`, and the host hands
+`controls` to its workbench so Apps and the dashboard can open them.
+
+---
+
+### RequestShellAppAccess
+
+```ts
+type RequestShellAppAccess = (
+  target,
+  request,
+  dialog,
+) => Promise<AppPermissionOutcome>;
+```
+
+A host's App-access flow. The host owns admission, current grants and saving;
+the shell renders the prompt and navigates its own Settings.
+
+#### Parameters
+
+| Parameter | Type                                                                                                     |
+| --------- | -------------------------------------------------------------------------------------------------------- |
+| `target`  | `Parameters`\<[`WorkbenchHostControls`](index.md#workbenchhostcontrols)\[`"requestAppAccess"`\]\>\[`0`\] |
+| `request` | `AppPermissionRequest`                                                                                   |
+| `dialog`  | `Readonly`\<\{ `ask`: `Promise`\<`AppPermissionOutcome`\>; `customize`: `"customize"`; \}\>              |
+
+#### Returns
+
+`Promise`\<`AppPermissionOutcome`\>
+
+---
+
+### MountPlatformControls
+
+```ts
+type MountPlatformControls = (root, input) => Promise<ShellPlatformControls>;
+```
+
+Render the shell's own Settings using the embedding host's access authority.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `root`    | `HTMLElement`                                                                                                                                                                                       |
+| `input`   | `Readonly`\<\{ `teamId`: `string`; `keysWire`: `Pick`\<`KeyWire`\<`string`\>, `"issue"` \| `"revoke"` \| `"summary"`\>; `requestAppAccess`: [`RequestShellAppAccess`](#requestshellappaccess); \}\> |
+
+#### Returns
+
+`Promise`\<[`ShellPlatformControls`](#shellplatformcontrols)\>
+
+---
+
+### ShellModule
+
+```ts
+type ShellModule = Readonly<{
+  mountShell: MountShell;
+  mountPlatformControls: MountPlatformControls | null;
+}>;
+```
+
+What a host gets from a picked shell Release's module.
+
+## Functions
+
+### importShellModule()
+
+```ts
+function importShellModule(
+  moduleUrl,
+  hostOrigin,
+): Promise<
+  Readonly<{
+    mountShell: MountShell;
+    mountPlatformControls: MountPlatformControls | null;
+  }>
+>;
+```
+
+Import the picked shell Release's module from the host's own origin and check
+that it exports `mountShell`, and `mountPlatformControls` when it offers its own
+Settings. The host never bundles a shell.
+
+#### Parameters
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `moduleUrl`  | `URL`    |
+| `hostOrigin` | `string` |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `mountShell`: [`MountShell`](#mountshell);
+`mountPlatformControls`: [`MountPlatformControls`](#mountplatformcontrols) \|
+`null`; \}\>\>

package/docs/api/window-manager.md

@@ -0,0 +1,269 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/nacre**](README.md)
+
+---
+
+[@fungi.computer/nacre](README.md) / window-manager
+
+# window-manager
+
+## Type Aliases
+
+### WindowLaunch
+
+```ts
+type WindowLaunch = Readonly<{
+  windowId: string;
+}>;
+```
+
+Minimum identity required to own a window across mount generations.
+
+---
+
+### WindowStatus
+
+```ts
+type WindowStatus = "loading" | "ready" | "minimized" | "error";
+```
+
+Current presentation state of a managed window.
+
+---
+
+### WindowHost
+
+```ts
+type WindowHost<Launch> = Readonly<{
+  setVisibility: (visibility) => void | Promise<void>;
+  reconfigure: (launch, signal?) => void | Promise<void>;
+  requestClose?: () => boolean | Promise<boolean>;
+  requestBack?: () => boolean | Promise<boolean>;
+  activateNavigation?: (activation) => boolean | Promise<boolean>;
+  activateStatus?: (action) => boolean | Promise<boolean>;
+  dispose: () => void | Promise<void>;
+}>;
+```
+
+Mount operations supplied by the embedding host; selection and authority stay
+with it.
+
+#### Type Parameters
+
+| Type Parameter                                     |
+| -------------------------------------------------- |
+| `Launch` _extends_ [`WindowLaunch`](#windowlaunch) |
+
+---
+
+### WindowEvents
+
+```ts
+type WindowEvents = Readonly<{
+  onComputerChoice: () => Promise<void>;
+  onNavigationState: (state) => void;
+  onStatusItems: (items) => void;
+}>;
+```
+
+What a mounted App tells its window while it lives.
+
+---
+
+### WindowProjection
+
+```ts
+type WindowProjection<Launch, Container> = Readonly<{
+  windowId: string;
+  launch: Launch;
+  container: Container;
+  status: WindowStatus;
+  generation: number;
+  error?: unknown;
+  cleanupError?: unknown;
+  navigation: AppNavigationState | null;
+  statusItems: readonly AppStatusItem[];
+}>;
+```
+
+Immutable snapshot of one window and its mount generation.
+
+#### Type Parameters
+
+| Type Parameter                                     |
+| -------------------------------------------------- |
+| `Launch` _extends_ [`WindowLaunch`](#windowlaunch) |
+| `Container`                                        |
+
+---
+
+### WindowsProjection
+
+```ts
+type WindowsProjection<Launch, Container> = Readonly<{
+  windows: readonly WindowProjection<Launch, Container>[];
+}>;
+```
+
+Current ordered collection of managed window snapshots.
+
+#### Type Parameters
+
+| Type Parameter                                     |
+| -------------------------------------------------- |
+| `Launch` _extends_ [`WindowLaunch`](#windowlaunch) |
+| `Container`                                        |
+
+---
+
+### WindowMount
+
+```ts
+type WindowMount<Launch, Container> = (
+  container,
+  launch,
+  signal,
+  events,
+) => WindowHost<Launch> | Promise<WindowHost<Launch>>;
+```
+
+Create a host-owned mount in a container, observing cancellation and navigation.
+
+#### Type Parameters
+
+| Type Parameter                                     |
+| -------------------------------------------------- |
+| `Launch` _extends_ [`WindowLaunch`](#windowlaunch) |
+| `Container`                                        |
+
+#### Parameters
+
+| Parameter   | Type                            |
+| ----------- | ------------------------------- |
+| `container` | `Container`                     |
+| `launch`    | `Launch`                        |
+| `signal`    | `AbortSignal`                   |
+| `events`    | [`WindowEvents`](#windowevents) |
+
+#### Returns
+
+\| [`WindowHost`](#windowhost)\<`Launch`\> \|
+`Promise`\<[`WindowHost`](#windowhost)\<`Launch`\>\>
+
+---
+
+### WindowManager
+
+```ts
+type WindowManager<Launch, Container> = Readonly<{
+  open: (launch) => Promise<void>;
+  attach: (windowId) => void;
+  minimize: (windowId) => Promise<void>;
+  restore: (windowId) => Promise<void>;
+  hideAll: () => Promise<void>;
+  restoreHidden: () => Promise<void>;
+  close: (windowId) => Promise<void>;
+  reconfigure: (windowId, launch) => Promise<void>;
+  update: (windowId, derive) => Promise<void>;
+  replace: (windowId, launch) => Promise<void>;
+  back: (windowId) => Promise<boolean>;
+  activateNavigation: (windowId, activation) => Promise<boolean>;
+  activateStatus: (windowId, action) => Promise<boolean>;
+  registerComputerChoice: (windowId, handler) => () => void;
+  dispose: () => Promise<void>;
+  read: () => WindowsProjection<Launch, Container>;
+  subscribe: (listener) => () => void;
+}>;
+```
+
+Own window lifetimes, visibility and serialized host mutations.
+
+#### Type Parameters
+
+| Type Parameter                                     |
+| -------------------------------------------------- |
+| `Launch` _extends_ [`WindowLaunch`](#windowlaunch) |
+| `Container`                                        |
+
+---
+
+### WindowManagerOptions
+
+```ts
+type WindowManagerOptions<Launch, Container> = Readonly<{
+  mount: WindowMount<Launch, Container>;
+  createContainer: (launch) => Container;
+  waitForAttachment?: boolean;
+  onFailure?: (failure) => void;
+  isAttached?: (container) => boolean;
+  validateReconfiguration?: (current, next) => void;
+  isChromeOnlyChange?: (current, next) => boolean;
+}>;
+```
+
+Host adapters used to create, attach and validate window mounts.
+
+#### Type Parameters
+
+| Type Parameter                                     |
+| -------------------------------------------------- |
+| `Launch` _extends_ [`WindowLaunch`](#windowlaunch) |
+| `Container`                                        |
+
+## Functions
+
+### hasVisibleWindows()
+
+```ts
+function hasVisibleWindows<Launch, Container>(projection): boolean;
+```
+
+Whether any projected App window is still visible in the workspace.
+
+#### Type Parameters
+
+| Type Parameter                                               |
+| ------------------------------------------------------------ |
+| `Launch` _extends_ `Readonly`\<\{ `windowId`: `string`; \}\> |
+| `Container`                                                  |
+
+#### Parameters
+
+| Parameter    | Type                                                               |
+| ------------ | ------------------------------------------------------------------ |
+| `projection` | [`WindowsProjection`](#windowsprojection)\<`Launch`, `Container`\> |
+
+#### Returns
+
+`boolean`
+
+---
+
+### createWindowManager()
+
+```ts
+function createWindowManager<Launch, Container>(
+  options,
+): WindowManager<Launch, Container>;
+```
+
+Owns App-window generations while leaving selection and App authority to the
+caller. A stale mount is always disposed when it eventually resolves.
+
+#### Type Parameters
+
+| Type Parameter                                               |
+| ------------------------------------------------------------ |
+| `Launch` _extends_ `Readonly`\<\{ `windowId`: `string`; \}\> |
+| `Container`                                                  |
+
+#### Parameters
+
+| Parameter | Type                                                                     |
+| --------- | ------------------------------------------------------------------------ |
+| `options` | [`WindowManagerOptions`](#windowmanageroptions)\<`Launch`, `Container`\> |
+
+#### Returns
+
+[`WindowManager`](#windowmanager)\<`Launch`, `Container`\>