@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/shell/keys.js

@@ -1,134 +0,0 @@
-/**
- * Single-chord and leader binding dispatch for the shell document. App frames
- * own their local key dispatch; reserved shell chords cross through the host.
- */
-/** Whistle binding prefix for a key pressed after the leader chord. */
-const leaderPrefix = "<leader> ";
-const keyNames = new Map([
-    ["arrowleft", "left"],
-    ["arrowright", "right"],
-    ["arrowup", "up"],
-    ["arrowdown", "down"],
-    ["esc", "escape"],
-    [" ", "space"],
-]);
-/** Normalize a DOM key or binding key name to the binding vocabulary. */
-function keyName(key) {
-    const lower = key.toLowerCase();
-    return keyNames.get(lower) ?? lower;
-}
-/**
- * Parse one single-chord binding. Sequences (including `<leader> x`) and
- * unknown modifiers return `null`; they are never matched as one chord.
- */
-export function parseChord(binding, mac) {
-    if (binding.trim().includes(" "))
-        return null;
-    const parts = binding.toLowerCase().split("+");
-    const key = parts.pop();
-    if (key === undefined || key.length === 0)
-        return null;
-    const chord = {
-        key: keyName(key),
-        alt: false,
-        ctrl: false,
-        meta: false,
-        shift: false,
-    };
-    for (const modifier of parts) {
-        if (modifier === "alt" || modifier === "option")
-            chord.alt = true;
-        else if (modifier === "ctrl" || modifier === "control")
-            chord.ctrl = true;
-        else if (modifier === "super" || modifier === "meta" || modifier === "cmd")
-            chord.meta = true;
-        else if (modifier === "shift")
-            chord.shift = true;
-        else if (modifier === "mod") {
-            if (mac)
-                chord.meta = true;
-            else
-                chord.ctrl = true;
-        }
-        else
-            return null;
-    }
-    return chord;
-}
-/** Whether one key event is exactly this chord. */
-export function chordMatches(event, chord) {
-    return (keyName(event.key) === chord.key &&
-        event.altKey === chord.alt &&
-        event.ctrlKey === chord.ctrl &&
-        event.metaKey === chord.meta &&
-        event.shiftKey === chord.shift);
-}
-/** The `<leader> x` rows of the active view, first binding per key. */
-export function leaderKeys(active) {
-    const seen = new Set();
-    const rows = [];
-    for (const row of active.bindings) {
-        if (!row.binding.startsWith(leaderPrefix))
-            continue;
-        const key = row.binding.slice(leaderPrefix.length).trim();
-        if (key.length === 0 || key.includes(" ") || seen.has(key))
-            continue;
-        seen.add(key);
-        rows.push({ ...row, key });
-    }
-    return rows;
-}
-/** Whether one key event (after the leader) selects this leader key. */
-export function leaderKeyMatches(event, key) {
-    if (event.altKey || event.ctrlKey || event.metaKey)
-        return false;
-    return event.key === key || keyName(event.key) === key;
-}
-/** Whether the event started in text entry, including inside shadow roots. */
-function isEditing(event) {
-    return event
-        .composedPath()
-        .some((node) => node instanceof HTMLElement &&
-        (node.isContentEditable ||
-            node.getAttribute("contenteditable") === "true" ||
-            node.matches("input, textarea, select")));
-}
-/**
- * Dispatch the active view's single-chord bindings from the shell document.
- * Text entry is a mode: while an input is focused only Ctrl/Cmd chords fire,
- * so Alt-arrows keep their word-navigation meaning.
- */
-export function installShellKeys(root, host, mac) {
-    let chords = [];
-    const refresh = () => {
-        chords = host.active().bindings.flatMap(({ binding, commandId }) => {
-            const chord = parseChord(binding, mac);
-            return chord === null ? [] : [{ commandId, chord }];
-        });
-    };
-    const onKeyDown = (event) => {
-        if (event.defaultPrevented || event.isComposing)
-            return;
-        const editing = isEditing(event);
-        const match = chords.find(({ chord }) => chordMatches(event, chord) && (!editing || chord.ctrl || chord.meta));
-        if (match === undefined)
-            return;
-        event.preventDefault();
-        void host
-            .execute(match.commandId, { origin: "keyboard" })
-            .catch((cause) => {
-            console.warn("Shell key command failed", cause);
-        });
-    };
-    refresh();
-    const unsubscribe = host.subscribe(refresh);
-    root.addEventListener("keydown", onKeyDown, { capture: true });
-    let cleaned = false;
-    return () => {
-        if (cleaned)
-            return;
-        cleaned = true;
-        unsubscribe();
-        root.removeEventListener("keydown", onKeyDown, { capture: true });
-    };
-}

package/dist/shell/shell-module.d.ts

@@ -1,55 +0,0 @@
-import type { AppStorage } from "@fungi.computer/agar/storage";
-import type { WhistleJsonValue } from "@fungi.computer/whistle";
-import type { TeamWorkbenchHostHandle } from "./workbench-contract.js";
-import type { WorkbenchHostControls } from "./workbench-host-types.js";
-/**
- * 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.
- */
-export type ShellMountInput = Readonly<{
-    workbench: TeamWorkbenchHostHandle;
-    storage: AppStorage;
-    methods: Readonly<{
-        /** Call one of the shell installation's declared backend methods. */
-        call(method: string, input: string): Promise<WhistleJsonValue>;
-    }>;
-}>;
-/**
- * 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.
- */
-export type MountShell = (root: HTMLElement, input: ShellMountInput) => Promise<() => 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.
- */
-export type ShellPlatformControls = Readonly<{
-    controls: WorkbenchHostControls;
-    /** A child App suggested desktop Settings for one of its surfaces. */
-    suggestDesktopSettings(surfaceId: string): void;
-    /** Remove the rendered Settings. */
-    dispose(): void;
-}>;
-/** Render the shell's own Settings into `root` for the host at `teamId`. */
-export type MountPlatformControls = (root: HTMLElement, input: Readonly<{
-    teamId: string;
-}>) => Promise<ShellPlatformControls>;
-/** What a host gets from a picked shell Release's module. */
-export type ShellModule = Readonly<{
-    mountShell: MountShell;
-    /** Absent when the shell renders no Settings of its own. */
-    mountPlatformControls: MountPlatformControls | null;
-}>;
-/** The picked shell's module could not be loaded or does not fit the contract. */
-export declare class ShellModuleError extends Error {
-    readonly name = "ShellModuleError";
-}
-/**
- * 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.
- */
-export declare function importShellModule(moduleUrl: URL, hostOrigin: string): Promise<ShellModule>;

package/dist/shell/shell-module.js

@@ -1,86 +0,0 @@
-import * as z from "zod";
-const unsubscribe = () => z.function({ input: [], output: z.void() });
-/** The module namespace a shell Release must export; built on first use,
- * since only a browser has `HTMLElement`. */
-const shellModuleSchema = () => z.object({
-    mountShell: z.function({
-        // The host supplies the input itself; the shell parses its own handles.
-        input: [z.instanceof(HTMLElement), z.unknown()],
-        output: z.promise(z.function({ input: [], output: z.void() })),
-    }),
-    mountPlatformControls: z
-        .function({
-        input: [
-            z.instanceof(HTMLElement),
-            z.object({ teamId: z.string() }).readonly(),
-        ],
-        output: z.promise(z.object({
-            controls: z.object({
-                sections: z.array(z.string()).readonly().optional(),
-                // The host passes the workbench's own values; the shell
-                // parses what it reads.
-                parseSettings: z.function({
-                    input: [z.unknown()],
-                    output: z.json(),
-                }),
-                openSettings: z.function({
-                    input: [z.unknown(), z.object({ restoreFocus: z.boolean() })],
-                    output: z.void(),
-                }),
-                subscribeSettingsClosed: z.function({
-                    input: [unsubscribe()],
-                    output: unsubscribe(),
-                }),
-                subscribeChanges: z.function({
-                    input: [unsubscribe()],
-                    output: unsubscribe(),
-                }),
-                attachDesktopSettings: z.function({
-                    input: [z.unknown()],
-                    output: unsubscribe(),
-                }),
-                requestAppAccess: z.function({
-                    input: [z.unknown(), z.unknown()],
-                    output: z.promise(z.enum(["granted", "declined", "customize"])),
-                }),
-            }),
-            suggestDesktopSettings: z.function({
-                input: [z.string()],
-                output: z.void(),
-            }),
-            dispose: unsubscribe(),
-        })),
-    })
-        .optional(),
-});
-/** The picked shell's module could not be loaded or does not fit the contract. */
-export class ShellModuleError extends Error {
-    name = "ShellModuleError";
-}
-/**
- * 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.
- */
-export async function importShellModule(moduleUrl, hostOrigin) {
-    if (moduleUrl.origin !== hostOrigin || moduleUrl.hash !== "")
-        throw new ShellModuleError("The shell module must come from this host");
-    let namespace;
-    try {
-        namespace = await import(/* @vite-ignore */ moduleUrl.href);
-    }
-    catch (cause) {
-        throw new ShellModuleError("The picked shell could not be loaded", {
-            cause,
-        });
-    }
-    const decoded = shellModuleSchema().safeParse(namespace);
-    if (!decoded.success)
-        throw new ShellModuleError("The picked shell does not export mountShell", {
-            cause: decoded.error,
-        });
-    return {
-        mountShell: decoded.data.mountShell,
-        mountPlatformControls: decoded.data.mountPlatformControls ?? null,
-    };
-}

package/dist/shell/window-manager.d.ts

@@ -1,128 +0,0 @@
-import { type AppNavigationActivation, type AppNavigationState, type AppStatusAction, type AppStatusItem } from "@fungi.computer/agar";
-/** Minimum identity required to own a window across mount generations. */
-export type WindowLaunch = Readonly<{
-    windowId: string;
-}>;
-/** Current presentation state of a managed window. */
-export type WindowStatus = "loading" | "ready" | "minimized" | "error";
-/** Mount operations supplied by the embedding host; selection and authority stay with it. */
-export type WindowHost<Launch extends WindowLaunch> = Readonly<{
-    /** Show or hide the current mount without disposing it. */
-    setVisibility: (visibility: "hidden" | "visible") => void | Promise<void>;
-    /** Reconfigure the mounted App without replacing its iframe or root. */
-    reconfigure: (launch: Launch, signal?: AbortSignal) => void | Promise<void>;
-    /** Ask the mounted App whether a user initiated close may discard work. */
-    requestClose?: () => boolean | Promise<boolean>;
-    /** Ask the mounted App to go back in its own history; `true` when it did. */
-    requestBack?: () => boolean | Promise<boolean>;
-    /** Deliver the person's use of a crumb or header command; `true` when the App acted. */
-    activateNavigation?: (activation: AppNavigationActivation) => boolean | Promise<boolean>;
-    /** Deliver the person's use of a status item; `true` when the App acted. */
-    activateStatus?: (action: AppStatusAction) => boolean | Promise<boolean>;
-    /** Release the current mount and its host resources. */
-    dispose: () => void | Promise<void>;
-}>;
-/** What a mounted App tells its window while it lives. */
-export type WindowEvents = Readonly<{
-    /** Open this generation's shell-owned Computer picker. */
-    onComputerChoice: () => Promise<void>;
-    /** The App's latest parsed navigation state; `null` withdraws it. */
-    onNavigationState: (state: AppNavigationState | null) => void;
-    /** The App's latest parsed status readouts; an empty list clears them. */
-    onStatusItems: (items: readonly AppStatusItem[]) => void;
-}>;
-/** Immutable snapshot of one window and its mount generation. */
-export type WindowProjection<Launch extends WindowLaunch, Container> = Readonly<{
-    windowId: string;
-    launch: Launch;
-    container: Container;
-    status: WindowStatus;
-    generation: number;
-    error?: unknown;
-    cleanupError?: unknown;
-    /** The ready App's navigation state; `null` while it reports none. */
-    navigation: AppNavigationState | null;
-    /** The App's status readouts for its window's status bar. */
-    statusItems: readonly AppStatusItem[];
-}>;
-/** Current ordered collection of managed window snapshots. */
-export type WindowsProjection<Launch extends WindowLaunch, Container> = Readonly<{
-    windows: readonly WindowProjection<Launch, Container>[];
-}>;
-/** Whether any projected App window is still visible in the workspace. */
-export declare function hasVisibleWindows<Launch extends WindowLaunch, Container>(projection: WindowsProjection<Launch, Container>): boolean;
-/** Create a host-owned mount in a container, observing cancellation and navigation. */
-export type WindowMount<Launch extends WindowLaunch, Container> = (container: Container, launch: Launch, signal: AbortSignal, events: WindowEvents) => WindowHost<Launch> | Promise<WindowHost<Launch>>;
-/** Own window lifetimes, visibility and serialized host mutations. */
-export type WindowManager<Launch extends WindowLaunch, Container> = Readonly<{
-    /** Open a window or restore the existing window with the same identity. */
-    open: (launch: Launch) => Promise<void>;
-    /** Notify the manager that a waiting container is attached. */
-    attach: (windowId: string) => void;
-    /** Hide one window without disposing its mount. */
-    minimize: (windowId: string) => Promise<void>;
-    /** Show an individually hidden window. */
-    restore: (windowId: string) => Promise<void>;
-    /** Hide visible Apps without closing them; preserve individually minimized Apps. */
-    hideAll: () => Promise<void>;
-    /** Restore surviving windows from the last Show desktop operation. */
-    restoreHidden: () => Promise<void>;
-    /** Consult the App before disposing and removing its window. */
-    close: (windowId: string) => Promise<void>;
-    /** Update a mounted window through the host after validation. */
-    reconfigure: (windowId: string, launch: Launch) => Promise<void>;
-    /**
-     * Reconfigure from the launch committed when the window's mutation queue
-     * reaches this change, so it never reapplies a stale snapshot over an
-     * earlier queued change.
-     */
-    update: (windowId: string, derive: (current: Launch) => Launch) => Promise<void>;
-    /** Consult the old App, dispose it, then create a new mount generation. */
-    replace: (windowId: string, launch: Launch) => Promise<void>;
-    /** Ask a ready window's App to go back; `false` when it cannot. */
-    back: (windowId: string) => Promise<boolean>;
-    /** Deliver a crumb or header command to a ready window's App; `false` when it cannot. */
-    activateNavigation: (windowId: string, activation: AppNavigationActivation) => Promise<boolean>;
-    /** Deliver a status item action to a ready window's App; `false` when it cannot. */
-    activateStatus: (windowId: string, action: AppStatusAction) => Promise<boolean>;
-    /** Register the current window generation's host-owned picker. */
-    registerComputerChoice: (windowId: string, handler: () => void) => () => void;
-    /** Dispose all surviving windows and release subscriptions. */
-    dispose: () => Promise<void>;
-    /** Read the current immutable window projection. */
-    read: () => WindowsProjection<Launch, Container>;
-    /** Observe projection changes until the returned disposer is called. */
-    subscribe: (listener: () => void) => () => void;
-}>;
-/** Host adapters used to create, attach and validate window mounts. */
-export type WindowManagerOptions<Launch extends WindowLaunch, Container> = Readonly<{
-    mount: WindowMount<Launch, Container>;
-    /** Create a container for a new window generation. */
-    createContainer: (launch: Launch) => Container;
-    /**
-     * A renderer may create a projection container before attaching it. Waiting
-     * here keeps iframe and Agar setup inside a real document tree.
-     */
-    waitForAttachment?: boolean;
-    /** Observe mount or mutation failures, including failures after retirement. */
-    onFailure?: (failure: Readonly<{
-        windowId: string;
-        generation: number | null;
-        phase: "mount" | "mutation";
-        cause: unknown;
-    }>) => void;
-    /** Report whether the renderer has attached a container. */
-    isAttached?: (container: Container) => boolean;
-    /** Reject an inadmissible launch change before it reaches the mounted host. */
-    validateReconfiguration?: (current: Launch, next: Launch) => void;
-    /**
-     * Whether `next` differs from `current` only in shell chrome the mounted
-     * App never sees. Such a change is committed without reconfiguring the App.
-     */
-    isChromeOnlyChange?: (current: Launch, next: Launch) => boolean;
-}>;
-/**
- * Owns App-window generations while leaving selection and App authority to the
- * caller. A stale mount is always disposed when it eventually resolves.
- */
-export declare function createWindowManager<Launch extends WindowLaunch, Container>(options: WindowManagerOptions<Launch, Container>): WindowManager<Launch, Container>;