@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/shell/workbench-host.js

@@ -1,352 +0,0 @@
-import * as Schema from "effect/Schema";
-import { AppError, parseAppStatusAction } from "@fungi.computer/agar";
-import { parseJsonValue } from "@fungi.computer/whistle/wire";
-import { desktopSettingsHandlerSchema, } from "./workbench-model.js";
-import { createAppSurfaceCommandHost, } from "./command-host.js";
-/** A dashboard may keep this many child Apps mounted at once. */
-const maxChildren = 32;
-const nonBlank = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(2_048)));
-const visibilitySchema = Schema.Literals(["hidden", "visible"]);
-// A dashboard presents a child's commands to people; it never acts as the
-// child's Agent.
-const commandInvocationSchema = Schema.Struct({
-    commandId: nonBlank,
-    origin: Schema.Literals([
-        "keyboard",
-        "palette",
-        "menu",
-        "browser",
-        "programmatic",
-        "slash",
-        "terminal",
-    ]),
-});
-/**
- * Forward a child's Release-validated commands and reserved chords to the
- * dashboard that presents them. Validation stays here, against the child's
- * own Release declaration, so the dashboard can never widen them.
- */
-function forwardCommands(log, validated, events, current) {
-    const present = (commands) => events.onCommands?.(commands) ?? Promise.resolve();
-    const handlers = {
-        registerCommands: async (input) => {
-            const contribution = await validated.handlers.registerCommands(input);
-            current.invoke = input.invoke;
-            await present(input.commands);
-            return {
-                update: (commands) => {
-                    contribution.update(commands);
-                    void present(commands).catch((cause) => {
-                        log("team_workbench_commands_failed", {
-                            stage: "update",
-                            cause,
-                        });
-                    });
-                },
-                dispose: () => {
-                    contribution.dispose();
-                    if (current.invoke === input.invoke)
-                        current.invoke = undefined;
-                    void present([]).catch((cause) => {
-                        log("team_workbench_commands_failed", {
-                            stage: "dispose",
-                            cause,
-                        });
-                    });
-                },
-            };
-        },
-        invokeReservedChord: async (input) => {
-            if (events.onReservedChord === undefined)
-                throw new Error("App reserved chord is unavailable");
-            await events.onReservedChord(input);
-        },
-    };
-    return Object.freeze({
-        handlers: Object.freeze(handlers),
-        dispose: validated.dispose,
-    });
-}
-/**
- * One mounted child App, proxying to its real host-owned mount. The shell
- * holds this bounded handle; the host's lease machinery stays behind it.
- */
-class MountedChildHandle {
-    surface;
-    commands;
-    reconfigureCurrent;
-    release;
-    #disposed = false;
-    constructor(surface, commands, reconfigureCurrent, release) {
-        this.surface = surface;
-        this.commands = commands;
-        this.reconfigureCurrent = reconfigureCurrent;
-        this.release = release;
-    }
-    async setVisibility(visibility) {
-        if (this.#disposed)
-            return;
-        await this.surface.setVisibility(Schema.decodeUnknownSync(visibilitySchema)(visibility));
-    }
-    async reconfigure(launch) {
-        if (this.#disposed)
-            return;
-        await this.reconfigureCurrent(launch);
-    }
-    async requestClose() {
-        if (this.#disposed)
-            return true;
-        return this.surface.requestClose();
-    }
-    async requestBack() {
-        if (this.#disposed)
-            return false;
-        return this.surface.requestBack();
-    }
-    async activateStatus(action) {
-        if (this.#disposed)
-            return false;
-        // The shell relays the person's click; parse it at the host's edge.
-        return this.surface.activateStatus(parseAppStatusAction(action));
-    }
-    async activateNavigation(activation) {
-        if (this.#disposed)
-            return false;
-        return this.surface.activateNavigation(activation);
-    }
-    async invokeCommand(commandId, input) {
-        const invoke = this.commands.invoke;
-        if (this.#disposed || invoke === undefined)
-            throw new AppError("That App command is unavailable", {
-                code: "CAPABILITY_DENIED",
-                retryable: false,
-            });
-        const parsed = Schema.decodeUnknownSync(commandInvocationSchema)({
-            commandId,
-            origin: input.origin,
-        });
-        return invoke(parsed.commandId, input.arguments === undefined
-            ? { origin: parsed.origin }
-            : { arguments: parseJsonValue(input.arguments), origin: parsed.origin });
-    }
-    async dispose() {
-        if (this.#disposed)
-            return;
-        this.#disposed = true;
-        await this.release();
-    }
-    [Symbol.dispose]() {
-        void this.dispose();
-    }
-}
-class DesktopSettingsRegistration {
-    detach;
-    constructor(detach) {
-        this.detach = detach;
-    }
-    close() {
-        this.detach();
-        return Promise.resolve();
-    }
-    [Symbol.dispose]() {
-        this.detach();
-    }
-}
-/**
- * Child-window, command and callback lifetime for the trusted shell the host
- * composes into its own document. Each child mounts inside the window slot
- * the shell hands it, so the browser moves, clips and stacks it with that
- * window; the host never positions a child itself.
- */
-export class WorkbenchHost {
-    #hostWindow;
-    #options;
-    #commands = createAppSurfaceCommandHost();
-    #children = new Set();
-    #releases = [];
-    #desktopSettingsClose;
-    #settingsClose;
-    #finishSettings;
-    constructor(options) {
-        this.#hostWindow = options.hostWindow;
-        this.#options = options;
-    }
-    team() {
-        return this.#options.services.team();
-    }
-    computers(input) {
-        return this.#options.services.computers(input);
-    }
-    directory() {
-        return this.#options.services.directory();
-    }
-    requestGill(input) {
-        return this.#options.services.requestGill(input);
-    }
-    watchGillChanges(...input) {
-        return this.#options.services.watchGillChanges(...input);
-    }
-    async platformDestinations() {
-        return (await this.#options.platform.destinations()).map(({ id, label }) => ({ id, label }));
-    }
-    async openPlatformDestination(id) {
-        const parsed = Schema.decodeUnknownSync(nonBlank)(id);
-        const offered = await this.#options.platform.destinations();
-        if (!offered.some((destination) => destination.id === parsed))
-            throw new AppError("That destination is unavailable", {
-                code: "INVALID_ARGUMENT",
-                retryable: false,
-            });
-        this.#options.platform.open(parsed);
-    }
-    /** Describe the actual controls without offering unsupported Settings. */
-    settingsSections() {
-        const controls = this.#options.platform.controls;
-        return Promise.resolve(controls.sections?.slice() ?? null);
-    }
-    takeAppOpenRequest() {
-        return Promise.resolve(this.#options.platform.takeAppOpenRequest());
-    }
-    registerDesktopSettings(handler) {
-        return Promise.resolve().then(() => {
-            let parsed;
-            try {
-                parsed = desktopSettingsHandlerSchema.parse(handler);
-            }
-            catch (cause) {
-                throw new AppError("Desktop settings registration is invalid", {
-                    code: "INVALID_ARGUMENT",
-                    retryable: false,
-                    cause,
-                });
-            }
-            this.#desktopSettingsClose?.();
-            const detach = this.#options.platform.controls.attachDesktopSettings(parsed);
-            let closed = false;
-            const close = () => {
-                if (closed)
-                    return;
-                closed = true;
-                detach();
-                if (this.#desktopSettingsClose === close)
-                    this.#desktopSettingsClose = undefined;
-            };
-            this.#desktopSettingsClose = close;
-            return new DesktopSettingsRegistration(close);
-        });
-    }
-    async openSettings(location) {
-        const parsed = this.#options.platform.controls.parseSettings(location);
-        const controls = this.#options.platform.controls;
-        if (this.#settingsClose !== undefined) {
-            const closed = this.#settingsClose;
-            controls.openSettings(parsed, { restoreFocus: false });
-            return closed;
-        }
-        const closed = new Promise((resolve) => {
-            const unsubscribe = controls.subscribeSettingsClosed(() => this.#finishSettings?.());
-            this.#finishSettings = () => {
-                unsubscribe();
-                this.#settingsClose = undefined;
-                this.#finishSettings = undefined;
-                resolve();
-            };
-        });
-        this.#settingsClose = closed;
-        // The shell restores its own invoker once Settings close; returning
-        // focus here would race that restoration.
-        controls.openSettings(parsed, { restoreFocus: false });
-        return closed;
-    }
-    memberAvatar() {
-        return this.#options.services.memberAvatar();
-    }
-    watchSettingsChanges(onChanged) {
-        const unsubscribe = this.#options.platform.controls.subscribeChanges(() => {
-            void onChanged().catch((cause) => {
-                this.#options.log("team_workbench_settings_notification_failed", {
-                    cause,
-                });
-            });
-        });
-        this.#releases.push(unsubscribe);
-        return Promise.resolve();
-    }
-    /** The shell unmounted: stop notifying its callbacks. */
-    [Symbol.dispose]() {
-        this.#finishSettings?.();
-        this.#desktopSettingsClose?.();
-        this.#options.services.dispose();
-        for (const release of this.#releases.splice(0))
-            release();
-    }
-    async mount(container, input, events) {
-        const request = this.#options.resolveLaunch(input);
-        const mountId = request.launch.windowId;
-        if (this.#children.has(mountId))
-            throw new AppError("That App window is already open", {
-                code: "INVALID_ARGUMENT",
-                retryable: false,
-            });
-        if (this.#children.size >= maxChildren)
-            throw new AppError("Too many Apps are open", {
-                code: "INVALID_ARGUMENT",
-                retryable: false,
-            });
-        this.#children.add(mountId);
-        let prepared;
-        let commandMount;
-        const childCommands = { invoke: undefined };
-        const release = async () => {
-            try {
-                commandMount?.dispose();
-                if (prepared)
-                    await prepared.dispose();
-            }
-            finally {
-                this.#children.delete(mountId);
-            }
-        };
-        try {
-            prepared = await this.#options.prepareChild(request.launch);
-            commandMount = forwardCommands(this.#options.log, this.#commands.mount(mountId, prepared.commands), events, childCommands);
-            const surface = await prepared.mount({
-                container,
-                hostWindow: this.#hostWindow,
-                ...(request.title === undefined ? undefined : { title: request.title }),
-                commands: commandMount,
-                events,
-                onDesktopSettings: (surfaceId) => this.#options.services.suggestDesktopSettings(surfaceId),
-                onPermissionRequest: (permission) => this.#options.platform.controls.requestAppAccess({
-                    surfaceId: request.launch.surfaceId,
-                    title: request.title ?? request.launch.appId,
-                }, permission),
-            });
-            const reconfigureCurrent = async (next) => {
-                const nextRequest = this.#options.resolveLaunch(next);
-                if (nextRequest.launch.appId !== request.launch.appId ||
-                    nextRequest.launch.releaseId !== request.launch.releaseId ||
-                    nextRequest.launch.surfaceId !== request.launch.surfaceId)
-                    throw new Error("App identity cannot change during reconfiguration");
-                await surface.reconfigure(nextRequest.launch);
-            };
-            return new MountedChildHandle(surface, childCommands, reconfigureCurrent, async () => {
-                try {
-                    surface.dispose();
-                }
-                finally {
-                    await release();
-                }
-            });
-        }
-        catch (error) {
-            await release();
-            throw error;
-        }
-    }
-    reportAgentSessionSelection(windowId, selection) {
-        const parsed = Schema.decodeUnknownSync(nonBlank)(windowId);
-        this.#options.reportAgentSessionSelection(parsed, selection);
-        return Promise.resolve();
-    }
-}

package/dist/shell/workbench-model.d.ts

@@ -1,194 +0,0 @@
-import * as z from "zod";
-import * as Schema from "effect/Schema";
-import type { AppCommand, AppOpenRequest, FileNavigationInput, AppNavigationActivation, AppNavigationState, AppStatusAction, AppStatusItem } from "@fungi.computer/agar";
-import type { AppOpenInput, AppRoleChoice } from "@fungi.computer/agar/apps";
-import type { WhistleExecutionOrigin, WhistleJsonValue } from "@fungi.computer/whistle";
-/** A request to resolve and mount one child App, by its own identity. */
-export type WorkbenchChildLaunch = Readonly<{
-    windowId: string;
-    appId: string;
-    releaseId: string;
-    surfaceId: string;
-    href: string;
-    title?: string;
-    openRequest: AppOpenRequest | null;
-}>;
-/** One invocation of a mounted child's own Release-declared command. */
-export type WorkbenchCommandInvocation = Readonly<{
-    arguments?: WhistleJsonValue;
-    origin: WhistleExecutionOrigin;
-}>;
-/**
- * Events a mounted child raises toward its dashboard. A child's permission
- * requests never reach the dashboard: the host asks the person itself. The
- * host validates a
- * child's commands against that child's own Release declaration before
- * forwarding them, so the dashboard can present them but never widen them.
- */
-export type WorkbenchChildEvents = Readonly<{
-    /** Ask this window's shell to open its existing Computer picker. */
-    onComputerChoice?: () => Promise<void>;
-    /** Ask the embedding host to follow a file navigation request. */
-    onNavigation?: (input: FileNavigationInput) => Promise<void>;
-    /** Ask the embedding host to open an App through its own admission policy. */
-    onAppOpen?: (input: AppOpenInput) => Promise<void>;
-    /** Ask the embedding host which App its role routing would open for a role. */
-    onAppRole?: (role: string) => Promise<AppRoleChoice>;
-    /** Report a changed child selection; the host returns whether it handled it. */
-    onSelectionChanged?: () => Promise<boolean>;
-    /**
-     * Replace the child's presented command set; an empty list clears it. Run
-     * one through the child's handle with `invokeCommand`.
-     */
-    onCommands?: (commands: readonly AppCommand[]) => Promise<void>;
-    /** A reserved shell chord (the command palette) pressed inside the child. */
-    onReservedChord?: (input: Readonly<{
-        id: string;
-        repeat: boolean;
-    }>) => Promise<void>;
-    /** The child gained (`true`) or lost (`false`) input focus. */
-    onFocus?: (focused: boolean) => Promise<void>;
-    /**
-     * The child's latest parsed navigation state; `null` once it disconnects.
-     * The dashboard shows a Back affordance from it.
-     */
-    onNavigationState?: (state: AppNavigationState | null) => Promise<void>;
-    /** The child's latest status readouts; an empty list once it disconnects. */
-    onStatusItems?: (items: readonly AppStatusItem[]) => Promise<void>;
-}>;
-/** One mounted child App; every method proxies to its real host-owned mount. */
-export type WorkbenchChildHandle = {
-    /** Show or hide the mounted child without changing its identity. */
-    setVisibility(visibility: "hidden" | "visible"): Promise<void>;
-    /** Update the launch descriptor of the existing mount. */
-    reconfigure(launch: WorkbenchChildLaunch): Promise<void>;
-    /** Ask whether the child permits a user-initiated close. */
-    requestClose(): Promise<boolean>;
-    /** Ask the child to go back one step in its own history; `true` when it did. */
-    requestBack(): Promise<boolean>;
-    /** Deliver the person's use of a child's status item; `true` when it acted. */
-    activateStatus(action: AppStatusAction): Promise<boolean>;
-    /** Deliver the person's use of a child's crumb or header command; `true` when it acted. */
-    activateNavigation(activation: AppNavigationActivation): Promise<boolean>;
-    /** Run one of the child's currently presented commands. */
-    invokeCommand(commandId: string, input: WorkbenchCommandInvocation): Promise<WhistleJsonValue | undefined>;
-    /** Release the child mount and its resources. */
-    dispose(): Promise<void>;
-};
-/**
- * A platform destination the host offers the dashboard, such as opening
- * a host settings page. The host owns the labels and the navigation;
- * the dashboard only presents them and asks the host to follow one.
- */
-export type WorkbenchPlatformDestination = Readonly<{
-    id: string;
-    label: string;
-}>;
-/** A declared Gill request addressed to one host-selected App surface. */
-export declare const workbenchGillRequestSchema: Schema.Struct<{
-    readonly viewId: Schema.String;
-    readonly params: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
-    readonly after: Schema.optional<Schema.String>;
-    readonly options: Schema.optional<Schema.String>;
-    readonly surfaceId: Schema.String;
-}>;
-/** Decoded Gill request for a surface in the host directory. */
-export type WorkbenchGillRequest = typeof workbenchGillRequestSchema.Type;
-/** The member chooses a declared Gill and size in host-rendered Settings. */
-export declare const desktopGillSelectionSchema: z.ZodObject<{
-    surfaceId: z.ZodString;
-    gillId: z.ZodString;
-}, z.core.$strict>;
-/** The identity of a Gill selected in a host-rendered settings view. */
-export type DesktopGillSelection = z.output<typeof desktopGillSelectionSchema>;
-/** The dashboard layout sizes currently assigned to one Gill. */
-export declare const desktopGillSizesSchema: z.ZodArray<z.ZodEnum<{
-    S: "S";
-    M: "M";
-    L: "L";
-}>>;
-/** A selected Gill and the layout size requested for a new placement. */
-export declare const desktopGillAdditionSchema: z.ZodObject<{
-    surfaceId: z.ZodString;
-    gillId: z.ZodString;
-    size: z.ZodEnum<{
-        S: "S";
-        M: "M";
-        L: "L";
-    }>;
-}, z.core.$strict>;
-/** A decoded request to add a Gill placement. */
-export type DesktopGillAddition = z.output<typeof desktopGillAdditionSchema>;
-/** A dashboard supplies its own arranger, not an endpoint for ordinary Apps. */
-export type WorkbenchDesktopSettings = {
-    /** Read the sizes currently assigned to this Gill in the dashboard layout. */
-    readGill: (input: DesktopGillSelection) => Promise<z.output<typeof desktopGillSizesSchema>>;
-    /** Add a Gill at the requested size to the dashboard layout. */
-    addGill: (input: DesktopGillAddition) => Promise<void>;
-    /** Remove this Gill from the dashboard layout. */
-    removeGill: (input: DesktopGillSelection) => Promise<void>;
-};
-/** Shape of the arranger callbacks the shell supplies to its host. */
-export declare const desktopSettingsHandlerSchema: z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
-    readGill: z.core.$InferOuterFunctionType<z.core.$ZodTuple<readonly [z.ZodObject<{
-        surfaceId: z.ZodString;
-        gillId: z.ZodString;
-    }, z.core.$strict>], z.core.$ZodFunctionOut>, z.ZodPromise<z.ZodPipe<z.ZodUnknown, z.ZodTransform<("S" | "M" | "L")[], unknown>>>>;
-    addGill: z.core.$InferOuterFunctionType<z.core.$ZodTuple<readonly [z.ZodObject<{
-        surfaceId: z.ZodString;
-        gillId: z.ZodString;
-        size: z.ZodEnum<{
-            S: "S";
-            M: "M";
-            L: "L";
-        }>;
-    }, z.core.$strict>], z.core.$ZodFunctionOut>, z.ZodPromise<z.ZodPipe<z.ZodUnknown, z.ZodTransform<void, unknown>>>>;
-    removeGill: z.core.$InferOuterFunctionType<z.core.$ZodTuple<readonly [z.ZodObject<{
-        surfaceId: z.ZodString;
-        gillId: z.ZodString;
-    }, z.core.$strict>], z.core.$ZodFunctionOut>, z.ZodPromise<z.ZodPipe<z.ZodUnknown, z.ZodTransform<void, unknown>>>>;
-} & {
-    [Symbol.dispose](): void;
-}, unknown>>;
-/** A registration lease; close it when the dashboard unmounts. */
-export type WorkbenchDesktopRegistration = {
-    /** Release this host registration. */
-    close(): Promise<void>;
-};
-/** A host-owned change subscription; close it when no longer visible. */
-export type WorkbenchGillWatch = {
-    /** Release this host registration. */
-    close(): Promise<void>;
-};
-/** Runtime check for an App-open handoff arriving across an untrusted boundary. */
-export declare const appOpenRequestSchema: Schema.Union<readonly [Schema.Struct<{
-    readonly kind: Schema.Literal<"compose">;
-    readonly requestId: Schema.String;
-    readonly text: Schema.String;
-}>, Schema.Struct<{
-    readonly kind: Schema.Literal<"navigate">;
-    readonly requestId: Schema.String;
-    readonly params: Schema.$Array<Schema.Struct<{
-        readonly key: Schema.String;
-        readonly value: Schema.String;
-    }>>;
-}>]>;
-/** One Team Computer in a host's inventory: the wire of `computers()`. */
-export declare const teamComputerSchema: z.ZodObject<{
-    computerId: z.ZodString;
-    name: z.ZodString;
-    createdAt: z.ZodNumber;
-    updatedAt: z.ZodNumber;
-}, z.core.$strict>;
-/** A decoded Team Computer inventory record. */
-export type TeamComputer = z.output<typeof teamComputerSchema>;
-/** One page of a host's Team Computer inventory. */
-export declare const teamComputerDirectorySchema: z.ZodObject<{
-    computers: z.ZodArray<z.ZodObject<{
-        computerId: z.ZodString;
-        name: z.ZodString;
-        createdAt: z.ZodNumber;
-        updatedAt: z.ZodNumber;
-    }, z.core.$strict>>;
-    nextOffset: z.ZodNullable<z.ZodNumber>;
-}, z.core.$strict>;

package/dist/shell/workbench-model.js

@@ -1,53 +0,0 @@
-import { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcVoid, } from "@fungi.computer/agar/rpc";
-import * as z from "zod";
-import * as Schema from "effect/Schema";
-import { gillRequestSchema } from "@fungi.computer/gills";
-/** A declared Gill request addressed to one host-selected App surface. */
-export const workbenchGillRequestSchema = Schema.Struct({
-    surfaceId: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(513)),
-    ...gillRequestSchema.fields,
-});
-/** The member chooses a declared Gill and size in host-rendered Settings. */
-export const desktopGillSelectionSchema = z.strictObject({
-    surfaceId: z.string().min(1).max(256),
-    gillId: z.string().min(1).max(80),
-});
-/** The dashboard layout sizes currently assigned to one Gill. */
-export const desktopGillSizesSchema = z.array(z.enum(["S", "M", "L"])).max(24);
-/** A selected Gill and the layout size requested for a new placement. */
-export const desktopGillAdditionSchema = desktopGillSelectionSchema.extend({
-    size: z.enum(["S", "M", "L"]),
-});
-/** Shape of the arranger callbacks the shell supplies to its host. */
-export const desktopSettingsHandlerSchema = rpcHandleSchema({
-    readGill: rpcMethod(rpcDataSchema(desktopGillSizesSchema)).input([
-        desktopGillSelectionSchema,
-    ]),
-    addGill: rpcVoid.input([desktopGillAdditionSchema]),
-    removeGill: rpcVoid.input([desktopGillSelectionSchema]),
-});
-/** Runtime check for an App-open handoff arriving across an untrusted boundary. */
-export const appOpenRequestSchema = Schema.Union([
-    Schema.Struct({
-        kind: Schema.Literal("compose"),
-        requestId: Schema.String,
-        text: Schema.String,
-    }),
-    Schema.Struct({
-        kind: Schema.Literal("navigate"),
-        requestId: Schema.String,
-        params: Schema.Array(Schema.Struct({ key: Schema.String, value: Schema.String })),
-    }),
-]);
-/** One Team Computer in a host's inventory: the wire of `computers()`. */
-export const teamComputerSchema = z.strictObject({
-    computerId: z.string().min(1),
-    name: z.string().min(1).max(256),
-    createdAt: z.number().int().nonnegative(),
-    updatedAt: z.number().int().nonnegative(),
-});
-/** One page of a host's Team Computer inventory. */
-export const teamComputerDirectorySchema = z.strictObject({
-    computers: z.array(teamComputerSchema),
-    nextOffset: z.number().int().nonnegative().nullable(),
-});

package/dist/shell/workbench.d.ts

@@ -1,4 +0,0 @@
-export * from "./workbench-model.js";
-export type { TeamWorkbenchHostHandle, TeamWorkbenchChildEvents, } from "./workbench-contract.js";
-export { WorkbenchHost } from "./workbench-host.js";
-export type * from "./workbench-host-types.js";

package/dist/shell/workbench.js

@@ -1,2 +0,0 @@
-export * from "./workbench-model.js";
-export { WorkbenchHost } from "./workbench-host.js";