@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/page/mount.d.ts

@@ -0,0 +1,163 @@
+import { type AppOpenInput, type AppRoleChoice } from "@fungi.computer/agar/apps";
+import * as Schema from "effect/Schema";
+import { type AppHost, type AppHostLaunch, type AppHostHandlers } from "@fungi.computer/agar/host";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+/** Current server-admitted configuration for one installed App page. */
+export declare const oysterAppConfigSchema: Schema.Struct<{
+    readonly workbench: Schema.Boolean;
+    /** The home shell Release's own module, imported top-level; null if it ships none. */
+    readonly shellModuleUrl: Schema.NullOr<Schema.String>;
+    readonly storage: Schema.Boolean;
+    /** The Release declares `apps.open`; only an embedding shell can serve it. */
+    readonly appsOpen: Schema.Boolean;
+    readonly computerId: Schema.NullOr<Schema.String>;
+    readonly authorityVersion: Schema.Int;
+    readonly commands: Schema.$Array<Schema.Codec<Readonly<{
+        id: string;
+        title: string;
+        category: string;
+        description?: string | undefined;
+        sigil?: string | undefined;
+        projections?: Readonly<{
+            bindings?: (Readonly<{
+                order?: number | undefined;
+            }> & Readonly<{
+                values: readonly string[];
+            }>) | undefined;
+            agent?: (Readonly<{
+                order?: number | undefined;
+            }> & Readonly<{
+                keybind?: string | undefined;
+            }>) | undefined;
+            help?: Readonly<{
+                order
+                /** Role and App opens, routed by the embedding shell; the App never names a surface. */
+                ? /** Role and App opens, routed by the embedding shell; the App never names a surface. */: number | undefined;
+            }> | undefined;
+            menu?: Readonly<{
+                order?: number | undefined;
+            }> | undefined;
+            palette?: Readonly<{
+                order?: number | undefined;
+            }> | undefined;
+            slash?: (Readonly<{
+                order?: number | undefined;
+            }> & Readonly<{
+                aliases: readonly string[];
+            }>) | undefined;
+        }> | undefined;
+    }>, Readonly<{
+        id: string;
+        title: string;
+        category: string;
+        description?: string | undefined;
+        sigil?: string | undefined;
+        projections?: Readonly<{
+            bindings?: (Readonly<{
+                order?: number | undefined;
+            }> & Readonly<{
+                values: readonly string[];
+            }>) | undefined;
+            agent?: (Readonly<{
+                order?: number | undefined;
+            }> & Readonly<{
+                keybind?: string | undefined;
+            }>) | undefined;
+            help?: Readonly<{
+                order
+                /** Role and App opens, routed by the embedding shell; the App never names a surface. */
+                ? /** Role and App opens, routed by the embedding shell; the App never names a surface. */: number | undefined;
+            }> | undefined;
+            menu?: Readonly<{
+                order?: number | undefined;
+            }> | undefined;
+            palette?: Readonly<{
+                order?: number | undefined;
+            }> | undefined;
+            slash?: (Readonly<{
+                order?: number | undefined;
+            }> & Readonly<{
+                aliases: readonly string[];
+            }>) | undefined;
+        }> | undefined;
+    }>, never, never>>;
+    readonly icon: Schema.NullOr<Schema.String>;
+    readonly roles: Schema.$Array<Schema.String>;
+    readonly installationId: Schema.String;
+    readonly appId: Schema.String;
+    readonly releaseId: Schema.String;
+    readonly uiUrl: Schema.String;
+    readonly backendUrl: Schema.String;
+    readonly methodsUrl: Schema.String;
+    readonly capabilities: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly version: Schema.Number;
+        readonly base: Schema.String;
+        readonly methods: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"transport">;
+            readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "ANY"]>;
+            readonly path: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["json", "read", "write"]>;
+            readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]>;
+            readonly path: Schema.String;
+        }>]>>;
+    }>>;
+}>;
+/** Role and App opens, routed by the embedding shell; the App never names a surface. */
+export type OysterAppOpenRouting = Readonly<{
+    /** Open the declared intent through the App the Team chose for its role. */
+    open(input: AppOpenInput): Promise<void>;
+    /** Which App that role's open would reach, or null when none fills it. */
+    role(role: string): Promise<AppRoleChoice>;
+}>;
+/** Read the server-admitted configuration this page was served with. */
+export declare function readOysterPageConfig(): OysterAppConfig;
+/** Apply this host's shared page styles and the person's color theme. */
+export declare function applyOysterPageTheme(): "mocha" | "latte";
+/**
+ * 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.
+ */
+export declare function oysterShellHandles(config: OysterAppConfig): {
+    storage: Readonly<{
+        read(key: string): Promise<import("@fungi.computer/agar").ResolvedAppStorage>;
+        write(input: import("@fungi.computer/agar").AppStorageWrite): Promise<{
+            revision: number;
+        }>;
+        reset(input: import("@fungi.computer/agar").AppStorageReset): Promise<{
+            revision: number;
+        }>;
+        watch(key: string): Promise<import("@fungi.computer/agar").AppStorageWatch>;
+    }> | null;
+    methods: {
+        call(method: string, input: string): Promise<WhistleJsonValue>;
+    };
+};
+/**
+ * Mount one installed App's own page: its sandboxed frame and nothing else.
+ * Desktop chrome (menus, palette, status) belongs to the trusted shell.
+ */
+export declare function mountOysterPage(): Promise<AppHost>;
+/** The host-admitted App configuration served by Oyster. */
+export type OysterAppConfig = typeof oysterAppConfigSchema.Type;
+/** One isolated App connection, with the slots this host admitted for it. */
+export type OysterAppConnectionOptions = Readonly<{
+    config: OysterAppConfig;
+    frame: HTMLIFrameElement;
+    signal: AbortSignal;
+    handlers: AppHostHandlers;
+    /** Present only where a shell can route opens; used when the Release declares `apps.open`. */
+    appOpen?: OysterAppOpenRouting;
+    openRequest?: AppHostLaunch["context"]["value"]["openRequest"];
+    surfaceId?: string;
+    reservedChords: readonly import("@fungi.computer/agar/host").AppHostReservedChord[];
+    theme: string;
+}>;
+/** Connect a child or home App using the same admitted Oyster slot handles. */
+export declare function connectOysterApp(options: OysterAppConnectionOptions): Promise<AppHost>;
+export { oysterStorageHandle } from "./storage.js";
+export { appSandbox } from "../app-sandbox.js";
+/** Resolve only the slots admitted for this installation by its current host. */
+export declare function oysterAppCapabilities(options: Pick<OysterAppConnectionOptions, "config" | "signal" | "appOpen">): Promise<AppHostLaunch["capabilities"]>;

package/dist/page/mount.js

@@ -0,0 +1,390 @@
+import { appOpenInputSchema, appsCall, appsOpen, } from "@fungi.computer/agar/apps";
+import { appApiMethodNameSchema } from "@fungi.computer/puffball/app";
+import { appIdSchema } from "@fungi.computer/puffball/effect";
+import { createBrowserActionHandler } from "../shell/browser-actions.js";
+import { createAppSurfaceCommandHost } from "../shell/command-host.js";
+// App page: mounts one installed App's sandboxed frame and gives it the
+// capabilities this Oyster host provides. Bundled into `shellScript`.
+import { RpcTarget } from "@fungi.computer/capnweb";
+import { createPageLifetime } from "./lifetime.js";
+import * as Schema from "effect/Schema";
+import { AppError } from "@fungi.computer/agar";
+import { appStorage } from "@fungi.computer/agar/storage";
+import { oysterStorageHandle } from "./storage.js";
+import { appBackend, appMethods } from "@fungi.computer/agar/backend";
+import { computerList, computerPorts, computerProcesses, computerReadFile, computerTerminal, computerWriteFile, } from "@fungi.computer/agar/computer";
+import { agentList, agentManage, agentSessionRead, agentSessionWrite, } from "@fungi.computer/agar/agents";
+import { mediaGeneration } from "@fungi.computer/agar/media";
+import { MediaGeneration, mediaGenerationDescriptionSchema, } from "@fungi.computer/agar/media-json";
+import { registeredCapabilityHandle, } from "./capabilities.js";
+import { capabilityDescriptorSchema } from "../capability-descriptor.js";
+import { connectAppHost, } from "@fungi.computer/agar/host";
+import { parseJsonValue } from "@fungi.computer/whistle/wire";
+import { appDeclaredCommandSchema } from "@fungi.computer/puffball/app";
+import { TerminalCapability } from "./terminal.js";
+import { ComputerPortsHandle, ComputerProcessesHandle, } from "./computer-handles.js";
+/** Current server-admitted configuration for one installed App page. */
+export const oysterAppConfigSchema = Schema.Struct({
+    workbench: Schema.Boolean,
+    /** The home shell Release's own module, imported top-level; null if it ships none. */
+    shellModuleUrl: Schema.NullOr(Schema.String),
+    storage: Schema.Boolean,
+    /** The Release declares `apps.open`; only an embedding shell can serve it. */
+    appsOpen: Schema.Boolean,
+    computerId: Schema.NullOr(Schema.String),
+    authorityVersion: Schema.Int,
+    commands: Schema.Array(appDeclaredCommandSchema),
+    icon: Schema.NullOr(Schema.String),
+    roles: Schema.Array(Schema.String),
+    installationId: Schema.String,
+    appId: Schema.String,
+    releaseId: Schema.String,
+    uiUrl: Schema.String,
+    backendUrl: Schema.String,
+    methodsUrl: Schema.String,
+    capabilities: Schema.Array(capabilityDescriptorSchema),
+});
+async function answer(response) {
+    if (response.status === 401 || response.status === 403)
+        throw new AppError("App permission was denied", {
+            code: "CAPABILITY_DENIED",
+            retryable: false,
+        });
+    if (!response.ok)
+        throw new AppError("App backend request failed", {
+            code: "HOST_FAILURE",
+            retryable: response.status >= 500,
+        });
+    return parseJsonValue(await response.json());
+}
+/** The App's typed methods, reached through this host's method route. */
+class Methods extends RpcTarget {
+    #url;
+    constructor(url) {
+        super();
+        this.#url = url;
+    }
+    async call(method, input) {
+        const name = Schema.decodeUnknownSync(Schema.String.check(Schema.isPattern(/^[A-Za-z][A-Za-z0-9_.]{0,79}$/u)))(method);
+        const body = Schema.decodeUnknownSync(Schema.String)(input);
+        return answer(await fetch(`${this.#url}${name}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+        }));
+    }
+}
+/** A member-only declared deputy; identity and approval are rechecked by the host route. */
+class Calls extends RpcTarget {
+    base;
+    signal;
+    constructor(base, signal) {
+        super();
+        this.base = base;
+        this.signal = signal;
+    }
+    async call(appId, method, input) {
+        const target = Schema.decodeUnknownSync(appIdSchema)(appId);
+        const name = Schema.decodeUnknownSync(appApiMethodNameSchema)(method);
+        const body = Schema.decodeUnknownSync(Schema.String)(input);
+        if (new TextEncoder().encode(body).byteLength > 64 * 1024)
+            throw new AppError("App method input is too large", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))(body);
+        return answer(await fetch(`${this.base}${encodeURIComponent(target)}/${encodeURIComponent(name)}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+            signal: this.signal,
+        }));
+    }
+}
+/** A declared `apps.open` reaches the embedding shell's own role routing. */
+class AppOpen extends RpcTarget {
+    routing;
+    constructor(routing) {
+        super();
+        this.routing = routing;
+    }
+    open(value) {
+        return this.routing.open(Schema.decodeUnknownSync(appOpenInputSchema, {
+            onExcessProperty: "error",
+        })(value));
+    }
+    role(value) {
+        const { role } = Schema.decodeUnknownSync(appOpenInputSchema.members[0], {
+            onExcessProperty: "error",
+        })({ role: value, intent: { kind: "navigate", params: [] } });
+        return this.routing.role(role);
+    }
+}
+/** The App's backend, reached through this host's admitted backend route. */
+class Backend extends RpcTarget {
+    #url;
+    constructor(url) {
+        super();
+        this.#url = url;
+    }
+    async request(input) {
+        const body = Schema.decodeUnknownSync(Schema.String)(input);
+        const response = await fetch(this.#url, {
+            method: "PUT",
+            headers: { "Content-Type": "text/plain" },
+            body,
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+        });
+        return answer(response);
+    }
+}
+const denied = () => Promise.reject(new AppError("This Oyster host does not provide that action", {
+    code: "CAPABILITY_DENIED",
+    retryable: false,
+}));
+function terminalSelection(config) {
+    const descriptor = config.capabilities.find((capability) => capability.id === computerTerminal.id &&
+        capability.version === computerTerminal.version);
+    const method = descriptor?.methods.open;
+    return {
+        computerId: config.computerId,
+        terminalUrl: descriptor !== undefined && method?.kind === "transport"
+            ? `${descriptor.base}${method.path}`
+            : null,
+    };
+}
+/** Read the server-admitted configuration this page was served with. */
+export function readOysterPageConfig() {
+    const configElement = document.getElementById("oyster-config");
+    if (configElement === null)
+        throw new Error("Oyster page config is missing");
+    return Schema.decodeUnknownSync(Schema.fromJsonString(oysterAppConfigSchema))(configElement.textContent);
+}
+/** Apply this host's shared page styles and the person's color theme. */
+export function applyOysterPageTheme() {
+    const dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    const theme = dark ? "mocha" : "latte";
+    document.documentElement.dataset.theme = theme;
+    const style = document.createElement("style");
+    style.textContent = OYSTER_SHELL_STYLES;
+    document.head.append(style);
+    return theme;
+}
+/**
+ * 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.
+ */
+export function oysterShellHandles(config) {
+    return {
+        storage: config.storage
+            ? appStorage.schema.parse(oysterStorageHandle(config.installationId))
+            : null,
+        methods: appMethods.schema.parse(new Methods(config.methodsUrl)),
+    };
+}
+/**
+ * Mount one installed App's own page: its sandboxed frame and nothing else.
+ * Desktop chrome (menus, palette, status) belongs to the trusted shell.
+ */
+export async function mountOysterPage() {
+    const frame = document.getElementById("oyster-app");
+    if (!(frame instanceof HTMLIFrameElement) || frame.contentWindow === null)
+        throw new Error("Oyster App frame is missing");
+    const config = readOysterPageConfig();
+    const lifetime = createPageLifetime(window);
+    const theme = applyOysterPageTheme();
+    // The App's commands are still admitted against its Release declaration.
+    const commands = createAppSurfaceCommandHost();
+    const mount = commands.mount(config.installationId, config.commands);
+    lifetime.own(() => {
+        commands.dispose();
+    });
+    return connectOysterApp({
+        config,
+        frame,
+        signal: lifetime.signal,
+        reservedChords: [],
+        theme,
+        handlers: {
+            ...mount.handlers,
+            reportStatus: () => Promise.resolve(),
+            openNavigation: denied,
+            reportFocus: () => Promise.resolve(),
+            reportAgentSessionSelection: () => Promise.resolve(),
+            showToast: () => Promise.resolve(),
+            onDisconnect: () => {
+                lifetime.dispose();
+                return Promise.resolve();
+            },
+        },
+    });
+}
+/** Connect a child or home App using the same admitted Oyster slot handles. */
+export async function connectOysterApp(options) {
+    const { config, frame } = options;
+    if (frame.contentWindow === null)
+        throw new Error("App frame is unavailable");
+    const capabilities = await oysterAppCapabilities(options);
+    const host = await connectAppHost({
+        appWindow: frame.contentWindow,
+        expectedAppOrigin: "null",
+        hostWindow: window,
+        signal: options.signal,
+        launch: {
+            identity: {
+                appId: config.appId,
+                releaseId: config.releaseId,
+                surfaceId: options.surfaceId ?? config.installationId,
+            },
+            capabilities,
+            context: {
+                version: 1,
+                value: {
+                    computerId: config.computerId,
+                    focus: { editing: false, surface: null },
+                    openRequest: options.openRequest ?? null,
+                    visibility: "visible",
+                },
+            },
+            lifecycle: { version: 1, value: "connected" },
+            reservedChords: { version: 0, value: options.reservedChords },
+            theme: { version: 1, value: options.theme },
+        },
+        handlers: {
+            ...options.handlers,
+            requestBrowserAction: createBrowserActionHandler({
+                frame,
+                hostWindow: window,
+                signal: options.signal,
+            }),
+        },
+    });
+    if (options.signal.aborted)
+        host.dispose();
+    else
+        options.signal.addEventListener("abort", () => {
+            host.dispose();
+        }, { once: true });
+    return host;
+}
+export { oysterStorageHandle } from "./storage.js";
+export { appSandbox } from "../app-sandbox.js";
+/** Resolve only the slots admitted for this installation by its current host. */
+export async function oysterAppCapabilities(options) {
+    const { config } = options;
+    const contracts = [
+        { contract: computerList },
+        {
+            contract: computerPorts,
+            createHandle: (call) => new ComputerPortsHandle(call),
+        },
+        {
+            contract: computerProcesses,
+            createHandle: (call) => new ComputerProcessesHandle(call),
+        },
+        { contract: computerReadFile },
+        { contract: computerWriteFile },
+        {
+            contract: computerTerminal,
+            createHandle: (_call, transport) => {
+                const selected = terminalSelection(config);
+                if (selected.terminalUrl === null)
+                    throw new AppError("Computer terminal is unavailable", {
+                        code: "CAPABILITY_DENIED",
+                        retryable: false,
+                    });
+                let leaseExpiresAt = 0;
+                return new TerminalCapability((input) => transport("open", input), {
+                    computerId: config.computerId,
+                    terminalUrl: selected.terminalUrl,
+                    hostWindow: window,
+                    mountSignal: options.signal,
+                    ensureAccess: Object.assign(async (signal) => {
+                        const response = await fetch(`/apps/${encodeURIComponent(config.installationId)}/`, {
+                            headers: { Accept: "application/json" },
+                            credentials: "same-origin",
+                            cache: "no-store",
+                            redirect: "error",
+                            signal,
+                        });
+                        const current = Schema.decodeUnknownSync(oysterAppConfigSchema)(await answer(response));
+                        if (current.installationId !== config.installationId ||
+                            current.releaseId !== config.releaseId ||
+                            current.authorityVersion !== config.authorityVersion)
+                            throw new AppError("App admission changed. Reopen the App.", {
+                                code: "CAPABILITY_DENIED",
+                                retryable: false,
+                            });
+                        leaseExpiresAt = Date.now() + 60_000;
+                        return terminalSelection(current);
+                    }, { leaseExpiresAt: () => leaseExpiresAt }),
+                });
+            },
+        },
+        { contract: agentList },
+        { contract: agentManage },
+        { contract: agentSessionRead },
+        { contract: agentSessionWrite },
+        {
+            contract: mediaGeneration,
+            createHandle: async (call) => {
+                const description = Schema.decodeUnknownSync(mediaGenerationDescriptionSchema, {
+                    onExcessProperty: "error",
+                })(await call("describe"));
+                return new MediaGeneration(call, description.computerId);
+            },
+        },
+    ];
+    const unknownCapabilities = [];
+    const capabilities = await Promise.all(config.capabilities.flatMap((descriptor) => {
+        if (descriptor.id === appsCall.id &&
+            descriptor.version === appsCall.version) {
+            const base = `/apps/${encodeURIComponent(config.installationId)}/calls/`;
+            if (descriptor.base !== base)
+                throw new AppError("App call route does not match this installation", {
+                    code: "PROTOCOL",
+                    retryable: false,
+                });
+            return [
+                Promise.resolve({
+                    ...appsCall,
+                    handle: new Calls(base, options.signal),
+                }),
+            ];
+        }
+        const registration = contracts.find(({ contract }) => contract.id === descriptor.id &&
+            contract.version === descriptor.version);
+        if (registration === undefined) {
+            unknownCapabilities.push(`${descriptor.id}@${String(descriptor.version)}`);
+            return [];
+        }
+        return [
+            registeredCapabilityHandle(registration, descriptor, config.installationId).then((handle) => ({ ...registration.contract, handle })),
+        ];
+    }));
+    if (unknownCapabilities.length > 0)
+        document.body.dataset.oysterCapability = unknownCapabilities.join(", ");
+    const resolved = [
+        { ...appBackend, handle: new Backend(config.backendUrl) },
+        { ...appMethods, handle: new Methods(config.methodsUrl) },
+        ...capabilities,
+        ...(config.appsOpen && options.appOpen
+            ? [{ ...appsOpen, handle: new AppOpen(options.appOpen) }]
+            : []),
+    ];
+    if (config.storage)
+        resolved.push({
+            ...appStorage,
+            handle: oysterStorageHandle(config.installationId),
+        });
+    return resolved;
+}

package/dist/page/storage.d.ts

@@ -0,0 +1,3 @@
+import { type AppStorageWire } from "@fungi.computer/agar/storage";
+/** The existing Agar storage wire, scoped to an admitted installation and owner. */
+export declare function oysterStorageHandle(installationId: string): AppStorageWire;

package/dist/page/storage.js

@@ -0,0 +1,82 @@
+import { RpcTarget } from "@fungi.computer/capnweb";
+import * as Schema from "effect/Schema";
+import { AppError } from "@fungi.computer/agar";
+import { appStorageKeyNameSchema, appStorageWriteSchema, appStorageResetSchema, appStorageReadResultSchema, appStorageMutationResultSchema, } from "@fungi.computer/agar/storage";
+const NativeTarget = RpcTarget;
+function path(installationId, operation) {
+    return `/api/workbench/storage/${encodeURIComponent(installationId)}/${operation}`;
+}
+async function reply(response) {
+    if (!response.ok)
+        throw new AppError("App storage is unavailable", {
+            code: response.status === 401 || response.status === 403
+                ? "CAPABILITY_DENIED"
+                : "HOST_FAILURE",
+            retryable: response.status >= 500,
+        });
+    return Schema.decodeUnknownSync(Schema.Json)(await response.json());
+}
+class StorageEvents extends NativeTarget {
+    url;
+    #abort = new AbortController();
+    constructor(url) {
+        super();
+        this.url = url;
+    }
+    fetch(request) {
+        return fetch(this.url, {
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+            signal: AbortSignal.any([request.signal, this.#abort.signal]),
+        });
+    }
+    close() {
+        this.#abort.abort();
+        return Promise.resolve();
+    }
+    [Symbol.dispose]() {
+        this.#abort.abort();
+    }
+}
+class Storage extends NativeTarget {
+    installationId;
+    constructor(installationId) {
+        super();
+        this.installationId = installationId;
+    }
+    async read(raw) {
+        const key = Schema.decodeUnknownSync(appStorageKeyNameSchema)(raw);
+        return Schema.decodeUnknownSync(appStorageReadResultSchema)(await reply(await fetch(`${path(this.installationId, "read")}?${new URLSearchParams({ key })}`, { credentials: "same-origin", cache: "no-store", redirect: "error" })));
+    }
+    async write(raw) {
+        const input = Schema.decodeUnknownSync(appStorageWriteSchema, {
+            onExcessProperty: "error",
+        })(raw);
+        return Schema.decodeUnknownSync(appStorageMutationResultSchema)(await this.mutate("write", input));
+    }
+    async reset(raw) {
+        const input = Schema.decodeUnknownSync(appStorageResetSchema, {
+            onExcessProperty: "error",
+        })(raw);
+        return Schema.decodeUnknownSync(appStorageMutationResultSchema)(await this.mutate("reset", input));
+    }
+    async mutate(operation, input) {
+        return reply(await fetch(path(this.installationId, operation), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+        }));
+    }
+    openEvents(raw) {
+        const key = Schema.decodeUnknownSync(appStorageKeyNameSchema)(raw);
+        return Promise.resolve(new StorageEvents(`${path(this.installationId, "events")}?${new URLSearchParams({ key })}`));
+    }
+}
+/** The existing Agar storage wire, scoped to an admitted installation and owner. */
+export function oysterStorageHandle(installationId) {
+    return new Storage(installationId);
+}

package/dist/page/terminal.d.ts

@@ -0,0 +1,5 @@
+import { ComputerTerminalHost, type ComputerTerminalConnect, type ComputerTerminalHostOptions } from "../computer-terminal.js";
+/** Bind the shared terminal protocol to Oyster's admitted transport factory. */
+export declare class TerminalCapability extends ComputerTerminalHost {
+    constructor(connect: (input: Parameters<ComputerTerminalConnect>[1]) => WebSocket, options: Omit<ComputerTerminalHostOptions, "connect">);
+}

package/dist/page/terminal.js

@@ -0,0 +1,7 @@
+import { ComputerTerminalHost, } from "../computer-terminal.js";
+/** Bind the shared terminal protocol to Oyster's admitted transport factory. */
+export class TerminalCapability extends ComputerTerminalHost {
+    constructor(connect, options) {
+        super({ ...options, connect: (_url, input) => connect(input) });
+    }
+}

package/dist/page/window-launch.d.ts

@@ -0,0 +1,18 @@
+import type { AppOpenRequest } from "@fungi.computer/agar";
+/**
+ * A window's current launch target: the open request and Computer its child
+ * App should see. `reconfigure` moves this forward as the window is handed a
+ * new file; a later restore (`setVisibility`) must read the latest target
+ * here, never the window's first open request.
+ */
+export type WindowLaunchTarget = Readonly<{
+    openRequest: AppOpenRequest | null;
+    computerId: string | null;
+}>;
+export type WindowLaunchTracker = Readonly<{
+    current: () => WindowLaunchTarget;
+    advance: (next: WindowLaunchTarget) => void;
+}>;
+/** One window's launch history: starts at its first open, moves forward on
+ * every `reconfigure`, and never resets on its own. */
+export declare function createWindowLaunchTracker(initial: WindowLaunchTarget): WindowLaunchTracker;