@fungi.computer/oyster 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,204 @@
+<!-- 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`\>
+
+---
+
+### 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.
+
+---
+
+### MountPlatformControls
+
+```ts
+type MountPlatformControls = (root, input) => Promise<ShellPlatformControls>;
+```
+
+Render the shell's own Settings into `root` for the host at `teamId`.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `root`    | `HTMLElement`                           |
+| `input`   | `Readonly`\<\{ `teamId`: `string`; \}\> |
+
+#### 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/shell/window-manager.md

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

package/docs/api/shell/workbench-directory.md

@@ -0,0 +1,119 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/workbench-directory
+
+# shell/workbench-directory
+
+## Type Aliases
+
+### WorkbenchDirectory
+
+```ts
+type WorkbenchDirectory = z.output<typeof workbenchDirectorySchema>;
+```
+
+One host's current desktop rows and actual role selections.
+
+## Variables
+
+### workbenchDirectorySchema
+
+```ts
+const workbenchDirectorySchema: ZodPipe<ZodObject<{
+  apps: ZodArray<ZodObject<{
+     address: ZodUnion<readonly [ZodObject<{
+        kind: ZodLiteral<...>;
+        appId: ZodString;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<...>;
+        installationId: ZodString;
+     }, $strict>]>;
+     installationId: ZodNullable<ZodString>;
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     icon: ZodOptional<ZodNullable<ZodString>>;
+     releaseId: ZodNullable<ZodString>;
+     authorityVersion: ZodNumber;
+     enforcement: ZodNullable<ZodObject<{
+        requestId: ZodString;
+        address: ZodUnion<readonly [..., ...]>;
+        authorityVersion: ZodNumber;
+        state: ZodEnum<{
+           unaffected: ...;
+           pending: ...;
+           applied: ...;
+           expired: ...;
+        }>;
+        outstanding: ZodNumber;
+     }, $strict>>;
+     handlers: ZodArray<ZodLiteral<"file.open">>;
+     roles: ZodArray<ZodString>;
+     declaredCapabilities: ZodArray<ZodString>;
+     calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
+     commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
+        id: ...;
+        title: ...;
+        category: ...;
+        description?: ...;
+        sigil?: ...;
+        projections?: ...;
+     }>[], unknown[]>>;
+     gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+     availability: ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+     }>;
+     surface: ZodNullable<ZodObject<{
+        stableRoute: ZodString;
+     }, $strict>>;
+     surfacePath: ZodString;
+     computer: ZodOptional<ZodObject<{
+        computerId: ZodString;
+        name: ZodString;
+     }, $strip>>;
+     computerPermission: ZodOptional<ZodNullable<ZodDiscriminatedUnion<[ZodObject<..., ...>, ZodObject<..., ...>], "kind">>>;
+  }, $strip>>;
+  computer: ZodOptional<ZodObject<{
+     computerId: ZodString;
+     name: ZodString;
+  }, $strip>>;
+  roles: ZodRecord<ZodString, ZodObject<{
+     surfaceId: ZodNullable<ZodString>;
+     chosen: ZodBoolean;
+  }, $strict>>;
+  needsUpdate: ZodOptional<ZodArray<ZodObject<{
+     installationId: ZodNullable<ZodString>;
+     appId: ZodNullable<ZodString>;
+     displayName: ZodString;
+  }, $strict>>>;
+}, $strip>, ZodTransform<{
+  apps: object[];
+  computer?: {
+     computerId: string;
+     name: string;
+  };
+  roles: Record<string, {
+     surfaceId: string | null;
+     chosen: boolean;
+  }>;
+  needsUpdate?: object[];
+}, {
+  apps: object[];
+  computer?: {
+     computerId: string;
+     name: string;
+  };
+  roles: Record<string, {
+     surfaceId: string | null;
+     chosen: boolean;
+  }>;
+  needsUpdate?: object[];
+}>>;
+```
+
+Desktop metadata shared by hosts; hosted administration stays in Settings.