page/mount

Import

Import

import * as api from "@fungi.computer/oyster/page";

Exports

Kind	Export	Description
Cclass	OysterAgentBrowserHost	One page-wide selected Session, using only its reporting App’s admitted view.
Ttype alias	OysterAppOpenRouting	Role and App opens, routed by the embedding shell; the App never names a surface.
Ttype alias	OysterAppConfig	The host-admitted App configuration served by Oyster.
Ttype alias	OysterAppConnectionOptions	One isolated App connection, with the slots this host admitted for it.
constconstant	appSandbox	The sandbox every installed App frame runs in, shell-mounted or not.
constconstant	oysterAppConfigSchema	Current server-admitted configuration for one installed App page.
fnfunction	readOysterPageConfig()	Read the server-admitted configuration this page was served with.
fnfunction	applyOysterPageTheme()	Apply this host’s shared page styles and the person’s color theme.
fnfunction	oysterShellHandles()	The home installation’s own storage and methods, for the trusted shell the host composes into this document. They reach the same admitted routes an isolated App would, without a frame between the shell and its host.
fnfunction	mountOysterPage()	Mount one installed App’s own page: its sandboxed frame and nothing else. Desktop chrome (menus, palette, status) belongs to the trusted shell.
fnfunction	connectOysterApp()	Connect a child or home App using the same admitted Oyster slot handles.
fnfunction	oysterAppCapabilities()	Resolve only the slots admitted for this installation by its current host.
fnfunction	oysterStorageHandle()	The existing Agar storage wire, scoped to an admitted installation and owner.

OysterAgentBrowserHostCclass

One page-wide selected Session, using only its reporting App’s admitted view.

Constructors

Constructor

Signature

new OysterAgentBrowserHost(signal): OysterAgentBrowserHost;

End the selected connection with the page’s own lifetime.

Parameters

Parameter	Type
signal	AbortSignal

Returns

OysterAgentBrowserHost

Methods

release()

Signature

release(frame): void;

A departing or deselecting mount cannot close a different active mount.

Parameters

Parameter	Type
frame	HTMLIFrameElement

Returns

void

dispose()

Signature

dispose(): void;

Release the page’s current selection; later reports cannot reconnect it.

Returns

void

report()

Signature

report(
   frame,
   selection,
   capabilities,
   whistle
): Promise<void>;

Bind the reporting mount’s current command view to its explicitly selected Session.

Parameters

Parameter	Type
frame	HTMLIFrameElement
selection	| Readonly<{ agentId: string; sessionId: string; }> | null
capabilities	CapabilityDirectory
whistle	Pick<WhistleRuntime, "snapshot" | "execute">

Returns

Promise<void>

OysterAppOpenRoutingTtype alias

Signature

type OysterAppOpenRouting = Readonly<{
  open: Promise<void>;
  role: Promise<{
    displayName: z.ZodNullable<z.ZodString>;
  } | null>;
}>;

Role and App opens, routed by the embedding shell; the App never names a surface.

---

OysterAppConfigTtype alias

Signature

type OysterAppConfig = typeof oysterAppConfigSchema.Type;

The host-admitted App configuration served by Oyster.

---

OysterAppConnectionOptionsTtype alias

Signature

type OysterAppConnectionOptions = Readonly<{
  config: OysterAppConfig;
  agentBrowser: OysterAgentBrowserHost;
  agentCommands: Pick<WhistleRuntime, "snapshot" | "execute">;
  computerTarget?: string;
  frame: HTMLIFrameElement;
  signal: AbortSignal;
  handlers: AppHostHandlers;
  appOpen?: OysterAppOpenRouting;
  openRequest?: AppHostLaunch["context"]["value"]["openRequest"];
  surfaceId?: string;
  reservedChords: readonly AppHostReservedChord[];
  theme: string;
}>;

One isolated App connection, with the slots this host admitted for it.

appSandboxconstconstant

Signature

const appSandbox: "allow-scripts allow-modals allow-popups allow-forms" =
  "allow-scripts allow-modals allow-popups allow-forms";

The sandbox every installed App frame runs in, shell-mounted or not.

---

oysterAppConfigSchemaconstconstant

Signature

const oysterAppConfigSchema: Struct<{
  workbench: Boolean;
  shellModuleUrl: NullOr<String>;
  storage: Boolean;
  appsOpen: Boolean;
  computerId: NullOr<String>;
  authorityVersion: Int;
  commands: $Array<Codec<Readonly<{
     id: string;
     title: string;
     category: string;
     description?: string;
     sigil?: string;
     projections?: Readonly<{
        bindings?: ... & ...;
        agent?: ... & ...;
        help?: Readonly<...>;
        menu?: Readonly<...>;
        palette?: Readonly<...>;
        slash?: ... & ...;
     }>;
   }>, Readonly<{
     id: string;
     title: string;
     category: string;
     description?: string;
     sigil?: string;
     projections?: Readonly<{
        bindings?: ... & ...;
        agent?: ... & ...;
        help?: Readonly<...>;
        menu?: Readonly<...>;
        palette?: Readonly<...>;
        slash?: ... & ...;
     }>;
  }>, never, never>>;
  icon: NullOr<String>;
  roles: $Array<String>;
  installationId: String;
  appId: String;
  releaseId: String;
  uiUrl: String;
  backendUrl: String;
  methodsUrl: String;
  capabilities: $Array<Struct<{
     id: String;
     version: Number;
     base: String;
     methods: $Record<String, Union<readonly [Struct<{
        kind: Literal<...>;
        method: Literals<...>;
        path: String;
      }>, Struct<{
        kind: Literals<...>;
        method: Literals<...>;
        path: String;
     }>]>>;
  }>>;
}>;

Current server-admitted configuration for one installed App page.

readOysterPageConfig()fnfunction

Signature

function readOysterPageConfig(): object;

Read the server-admitted configuration this page was served with.

Returns

Name	Type	Default value	Description
workbench	boolean	Schema.Boolean	-
shellModuleUrl	string | null	-	The home shell Release’s own module, imported top-level; null if it ships none.
storage	boolean	Schema.Boolean	-
appsOpen	boolean	Schema.Boolean	The Release declares apps.open; only an embedding shell can serve it.
computerId	string | null	-	-
authorityVersion	number	Schema.Int	-
commands	readonly Readonly<{ id: string; title: string; category: string; description?: string; sigil?: string; projections?: Readonly<{ bindings?: Readonly<{ order?: …; }> & Readonly<{ values: …; }>; agent?: Readonly<{ order?: …; }> & Readonly<{ keybind?: …; }>; help?: Readonly<{ order?: … | …; }>; menu?: Readonly<{ order?: … | …; }>; palette?: Readonly<{ order?: … | …; }>; slash?: Readonly<{ order?: …; }> & Readonly<{ aliases: …; }>; }>; }>[]	-	-
icon	string | null	-	-
roles	readonly string[]	-	-
installationId	string	Schema.String	-
appId	string	Schema.String	-
releaseId	string	Schema.String	-
uiUrl	string	Schema.String	-
backendUrl	string	Schema.String	-
methodsUrl	string	Schema.String	-
capabilities	readonly object[]	-	-

---

applyOysterPageTheme()fnfunction

Signature

function applyOysterPageTheme(): "mocha" | "latte";

Apply this host’s shared page styles and the person’s color theme.

Returns

"mocha" | "latte"

---

oysterShellHandles()fnfunction

Signature

function oysterShellHandles(config): object;

The home installation’s own storage and methods, for the trusted shell the host composes into this document. They reach the same admitted routes an isolated App would, without a frame between the shell and its host.

Parameters

Parameter	Type	Description
config	{ workbench: boolean; shellModuleUrl: string | null; storage: boolean; appsOpen: boolean; computerId: string | null; authorityVersion: number; commands: readonly Readonly<{ id: string; title: string; category: string; description?: string; sigil?: string; projections?: Readonly<{ bindings?: Readonly<{ order?: …; }> & Readonly<{ values: …; }>; agent?: Readonly<{ order?: …; }> & Readonly<{ keybind?: …; }>; help?: Readonly<{ order?: … | …; }>; menu?: Readonly<{ order?: … | …; }>; palette?: Readonly<{ order?: … | …; }>; slash?: Readonly<{ order?: …; }> & Readonly<{ aliases: …; }>; }>; }>[]; icon: string | null; roles: readonly string[]; installationId: string; appId: string; releaseId: string; uiUrl: string; backendUrl: string; methodsUrl: string; capabilities: readonly object[]; }	-
config.workbench	boolean	-
config.shellModuleUrl	string | null	The home shell Release’s own module, imported top-level; null if it ships none.
config.storage	boolean	-
config.appsOpen	boolean	The Release declares apps.open; only an embedding shell can serve it.
config.computerId	string | null	-
config.authorityVersion	number	-
config.commands	readonly Readonly<{ id: string; title: string; category: string; description?: string; sigil?: string; projections?: Readonly<{ bindings?: Readonly<{ order?: …; }> & Readonly<{ values: …; }>; agent?: Readonly<{ order?: …; }> & Readonly<{ keybind?: …; }>; help?: Readonly<{ order?: … | …; }>; menu?: Readonly<{ order?: … | …; }>; palette?: Readonly<{ order?: … | …; }>; slash?: Readonly<{ order?: …; }> & Readonly<{ aliases: …; }>; }>; }>[]	-
config.icon	string | null	-
config.roles	readonly string[]	-
config.installationId	string	-
config.appId	string	-
config.releaseId	string	-
config.uiUrl	string	-
config.backendUrl	string	-
config.methodsUrl	string	-
config.capabilities	readonly object[]	-

Returns

object

Name	Type	Description
storage	| Readonly<{ read: Promise<{ value: Json; source: "member" | "team" | "none"; team: | { value: Json; revision: number; } | null; member: | { value: Json; revision: number; } | null; canWriteTeam: boolean; }>; write: Promise<{ revision: number; }>; reset: Promise<{ revision: number; }>; watch: Promise<AppStorageWatch>; }> | null	-
methods	object	-
call()	(method, input) => Promise<WhistleJsonValue>	Call the named method with JSON-encoded input; resolves with its JSON result.

---

mountOysterPage()fnfunction

Signature

function mountOysterPage(): Promise<AppHost>;

Mount one installed App’s own page: its sandboxed frame and nothing else. Desktop chrome (menus, palette, status) belongs to the trusted shell.

Returns

Promise<AppHost>

---

connectOysterApp()fnfunction

Signature

function connectOysterApp(options): Promise<AppHost>;

Connect a child or home App using the same admitted Oyster slot handles.

Parameters

Parameter	Type
options	OysterAppConnectionOptions

Returns

Promise<AppHost>

---

oysterAppCapabilities()fnfunction

Signature

function oysterAppCapabilities(options): Promise<readonly object[]>;

Resolve only the slots admitted for this installation by its current host.

Parameters

Parameter	Type
options	Pick<OysterAppConnectionOptions, "config" | "signal" | "appOpen" | "computerTarget">

Returns

Promise<readonly object[]>

---

oysterStorageHandle()fnfunction

Signature

function oysterStorageHandle(installationId): AppStorageWire;

The existing Agar storage wire, scoped to an admitted installation and owner.

Parameters

Parameter	Type
installationId	string

Returns

AppStorageWire