@fungi.computer/oyster 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,332 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/app-directory
+
+# shell/app-directory
+
+## Type Aliases
+
+### AppAddress
+
+```ts
+type AppAddress = z.output<typeof appAddressSchema>;
+```
+
+Decoded address of a default App or an installation.
+
+---
+
+### AppAuthorityEnforcement
+
+```ts
+type AppAuthorityEnforcement = z.output<typeof appAuthorityEnforcementSchema>;
+```
+
+A host-reported authority change and its remaining work.
+
+---
+
+### AppDirectoryGill
+
+```ts
+type AppDirectoryGill = {
+  [
+    Field in keyof Schema.Schema.Type<typeof appDeclaredGillSchema>
+  ]: Schema.Schema.Type<typeof appDeclaredGillSchema>[Field];
+};
+```
+
+A Release-declared Gill carried by the host's App directory. The named mapped
+type keeps consumer declarations attached to this public contract.
+
+---
+
+### AppDirectoryEntry
+
+```ts
+type AppDirectoryEntry = z.output<typeof appDirectoryEntrySchema>;
+```
+
+An App directory row before host-specific permissions are attached.
+
+---
+
+### AppCatalog
+
+```ts
+type AppCatalog = z.output<typeof appCatalogResponseSchema>;
+```
+
+Parsed metadata returned by the read-only APPS.catalog binding.
+
+## Variables
+
+### appAddressSchema
+
+```ts
+const appAddressSchema: ZodUnion<
+  readonly [
+    ZodObject<
+      {
+        kind: ZodLiteral<"default">;
+        appId: ZodString;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        kind: ZodLiteral<"installation">;
+        installationId: ZodString;
+      },
+      $strict
+    >,
+  ]
+>;
+```
+
+An App address selects a host default or a specific installation.
+
+---
+
+### appAuthorityEnforcementSchema
+
+```ts
+const appAuthorityEnforcementSchema: ZodObject<
+  {
+    requestId: ZodString;
+    address: ZodUnion<
+      readonly [
+        ZodObject<
+          {
+            kind: ZodLiteral<"default">;
+            appId: ZodString;
+          },
+          $strict
+        >,
+        ZodObject<
+          {
+            kind: ZodLiteral<"installation">;
+            installationId: ZodString;
+          },
+          $strict
+        >,
+      ]
+    >;
+    authorityVersion: ZodNumber;
+    state: ZodEnum<{
+      pending: "pending";
+      expired: "expired";
+      unaffected: "unaffected";
+      applied: "applied";
+    }>;
+    outstanding: ZodNumber;
+  },
+  $strict
+>;
+```
+
+Host-reported progress of applying a revised App authority version.
+
+---
+
+### appDirectoryEntrySchema
+
+```ts
+const appDirectoryEntrySchema: ZodObject<{
+  address: ZodUnion<readonly [ZodObject<{
+     kind: ZodLiteral<"default">;
+     appId: ZodString;
+   }, $strict>, ZodObject<{
+     kind: ZodLiteral<"installation">;
+     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 [ZodObject<{
+        kind: ZodLiteral<"default">;
+        appId: ZodString;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<"installation">;
+        installationId: ZodString;
+     }, $strict>]>;
+     authorityVersion: ZodNumber;
+     state: ZodEnum<{
+        pending: "pending";
+        expired: "expired";
+        unaffected: "unaffected";
+        applied: "applied";
+     }>;
+     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: string;
+     title: string;
+     category: string;
+     description?: string;
+     sigil?: string;
+     projections?: Readonly<{
+        bindings?: ... | ...;
+        agent?: ... | ...;
+        help?: ... | ...;
+        menu?: ... | ...;
+        palette?: ... | ...;
+        slash?: ... | ...;
+     }>;
+  }>[], unknown[]>>;
+  gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+  availability: ZodEnum<{
+     unavailable: "unavailable";
+     available: "available";
+  }>;
+  surface: ZodNullable<ZodObject<{
+     stableRoute: ZodString;
+  }, $strict>>;
+  surfacePath: ZodString;
+}, $strict>;
+```
+
+Reusable App metadata supplied by an embedding host; it conveys no permissions.
+
+---
+
+### appRoleSelectionSchema
+
+```ts
+const appRoleSelectionSchema: ZodObject<
+  {
+    surfaceId: ZodNullable<ZodString>;
+    chosen: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+A host-resolved role selection; a surface address is not launch authority.
+
+---
+
+### appCatalogEntrySchema
+
+```ts
+const appCatalogEntrySchema: ZodObject<{
+  surfaceId: ZodString;
+  appId: ZodString;
+  displayName: ZodOptional<ZodString>;
+  gills: ZodArray<ZodObject<{
+     id: ZodString;
+     title: ZodString;
+     params: ZodOptional<ZodArray<ZodObject<{
+        key: ZodString;
+        label: ZodString;
+        kind: ZodEnum<...>;
+        required: ZodBoolean;
+        options: ZodOptional<...>;
+     }, $strict>> & ZodType<readonly object[], object[], $ZodTypeInternals<readonly object[], object[]>>>;
+     desktop: ZodOptional<ZodObject<{
+        sizes: ZodArray<ZodEnum<{
+           S: ...;
+           M: ...;
+           L: ...;
+        }>>;
+     }, $strict>>;
+  }, $strict>>;
+}, $strict>;
+```
+
+Read-only catalog metadata for one App, without host-specific role policy.
+
+---
+
+### appCatalogResponseSchema
+
+```ts
+const appCatalogResponseSchema: ZodObject<{
+  apps: ZodArray<ZodObject<{
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     gills: ZodArray<ZodObject<{
+        id: ZodString;
+        title: ZodString;
+        params: ZodOptional<ZodArray<...> & ZodType<..., ..., ...>>;
+        desktop: ZodOptional<ZodObject<{
+           sizes: ...;
+        }, $strict>>;
+     }, $strict>>;
+  }, $strict>>;
+  roles: ZodObject<{
+     inbox: ZodOptional<ZodObject<{
+        surfaceId: ZodNullable<ZodString>;
+        chosen: ZodBoolean;
+     }, $strict>>;
+  }, $strict>;
+}, $strict>;
+```
+
+Read-only desktop metadata; identities are surface addresses, never launch
+authority.
+
+---
+
+### appCatalogBrokerResultSchema
+
+```ts
+const appCatalogBrokerResultSchema: ZodUnion<readonly [ZodObject<{
+  apps: ZodArray<ZodObject<{
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     gills: ZodArray<ZodObject<{
+        id: ZodString;
+        title: ZodString;
+        params: ZodOptional<...>;
+        desktop: ZodOptional<...>;
+     }, $strict>>;
+  }, $strict>>;
+  roles: ZodObject<{
+     inbox: ZodOptional<ZodObject<{
+        surfaceId: ZodNullable<ZodString>;
+        chosen: ZodBoolean;
+     }, $strict>>;
+  }, $strict>;
+}, $strict>, ZodObject<{
+  error: ZodString;
+}, $strict>]>;
+```
+
+Complete APPS.catalog reply, including broker admission failures.
+
+## Functions
+
+### addressKey()
+
+```ts
+function addressKey(address): string;
+```
+
+Stable identity of one App address across directory and settings views.
+
+#### Parameters
+
+| Parameter | Type                                                                                                            |
+| --------- | --------------------------------------------------------------------------------------------------------------- |
+| `address` | \| \{ `kind`: `"default"`; `appId`: `string`; \} \| \{ `kind`: `"installation"`; `installationId`: `string`; \} |
+
+#### Returns
+
+`string`

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)