@fungi.computer/oyster 0.2.0 → 0.3.1

package/dist/shell/command-host.js

@@ -1,502 +0,0 @@
-import { AppError } from "@fungi.computer/agar/errors";
-import { createWhistle, scopeSnapshot, } from "@fungi.computer/whistle";
-const emptyMenu = Object.freeze([]);
-const commandPaletteReservedChord = Object.freeze({
-    altKey: false,
-    ctrlKey: false,
-    id: "shell:show-command-palette",
-    key: "k",
-    metaKey: true,
-    shiftKey: false,
-});
-/** Select the shell command-palette chord for a Mac or non-Mac keyboard. */
-export function commandPaletteReservedChordForPlatform(mac) {
-    return Object.freeze({
-        ...commandPaletteReservedChord,
-        ctrlKey: !mac,
-        metaKey: mac,
-    });
-}
-/** Select the shell command-palette chord from the embedding browser user agent. */
-export function commandPaletteReservedChordForUserAgent(userAgent) {
-    return commandPaletteReservedChordForPlatform(/Mac|iPhone|iPad/u.test(userAgent));
-}
-/** Whistle source of Release-advertised rows for Apps not yet mounted. */
-export const appDirectorySourceId = "app-directory";
-/** Bindings an App may never claim: the leader chord crosses every iframe. */
-const reservedBindings = new Set([
-    "super+k",
-    "meta+k",
-    "cmd+k",
-    "mod+k",
-    "ctrl+k",
-    "control+k",
-]);
-function sameValues(left, right) {
-    return left === undefined || right === undefined
-        ? left === right
-        : left.length === right.length &&
-            left.every((value, index) => value === right[index]);
-}
-function matchesBindings(actual, declared) {
-    return (actual?.bindings?.order === declared?.bindings?.order &&
-        sameValues(actual?.bindings?.values, declared?.bindings?.values));
-}
-function matchesSlash(actual, declared) {
-    return (actual?.slash?.order === declared?.slash?.order &&
-        sameValues(actual?.slash?.aliases, declared?.slash?.aliases));
-}
-function matchesAgent(actual, declared) {
-    return (actual?.agent?.order === declared?.agent?.order &&
-        actual?.agent?.keybind === declared?.agent?.keybind);
-}
-function matchesHelp(actual, declared) {
-    return actual?.help?.order === declared?.help?.order;
-}
-function matchesMenu(actual, declared) {
-    return actual?.menu?.order === declared?.menu?.order;
-}
-function matchesPalette(actual, declared) {
-    return actual?.palette?.order === declared?.palette?.order;
-}
-function matchesDeclaration(command, declaration) {
-    const actual = command.projections;
-    const declared = declaration.projections;
-    return (command.id === declaration.id &&
-        command.title === declaration.title &&
-        command.category === declaration.category &&
-        command.description === declaration.description &&
-        matchesBindings(actual, declared) &&
-        matchesAgent(actual, declared) &&
-        matchesHelp(actual, declared) &&
-        matchesMenu(actual, declared) &&
-        matchesPalette(actual, declared) &&
-        matchesSlash(actual, declared));
-}
-/**
- * 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.
- */
-export function createAppSurfaceCommandHost(whistle = createWhistle()) {
-    const mounts = new Map();
-    const panes = new Map();
-    const listeners = new Set();
-    let focusedMount = null;
-    let activeSnapshot = scopeSnapshot(whistle.snapshot(), null);
-    let focusedMenu = emptyMenu;
-    let shellContribution;
-    let directoryContribution;
-    let disposed = false;
-    let disposePresenter;
-    const refreshPresenter = () => {
-        disposePresenter?.();
-        disposePresenter = undefined;
-        if (disposed)
-            return;
-        const presenter = focusedMount === null
-            ? undefined
-            : panes.get(focusedMount)?.presenters.at(-1)?.presenter;
-        if (presenter !== undefined)
-            disposePresenter = whistle.present(presenter);
-    };
-    const publish = () => {
-        for (const listener of listeners)
-            listener();
-    };
-    // One atomic recomputation per graph or focus change: subscribers never see
-    // two Apps active at once.
-    const refreshMenu = () => {
-        activeSnapshot = scopeSnapshot(whistle.snapshot(), focusedMount);
-        for (const [id, pane] of panes) {
-            if (pane.disposed)
-                continue;
-            pane.snapshot = scopeSnapshot(whistle.snapshot(), id);
-            for (const listener of pane.listeners)
-                listener();
-        }
-        focusedMenu =
-            focusedMount === null
-                ? emptyMenu
-                : Object.freeze(activeSnapshot.menu.filter((command) => command.scope === focusedMount));
-        publish();
-    };
-    const unsubscribeWhistle = whistle.subscribe(refreshMenu);
-    const assertLive = () => {
-        if (disposed)
-            throw new Error("App command host is disposed");
-    };
-    const contributionFor = (mount, input, commands) => {
-        for (const command of commands) {
-            const declaration = mount.declarations.get(command.id);
-            if (declaration === undefined ||
-                !matchesDeclaration(command, declaration))
-                throw new AppError(`App command ${command.id} does not match its Release declaration`, { code: "COMMAND_NOT_DECLARED", retryable: false });
-            for (const binding of command.projections?.bindings?.values ?? [])
-                if (reservedBindings.has(binding.trim().toLowerCase()))
-                    throw new Error("App commands cannot bind the reserved leader chord");
-        }
-        return {
-            sourceId: mount.id,
-            namespace: encodeURIComponent(mount.id),
-            scope: mount.id,
-            commands: commands.map((command) => {
-                // Agar carries a static availability fact; Whistle evaluates availability
-                // through its existing function-shaped runtime contract.
-                const { availability, projections, description, action, ...metadata } = command;
-                const converted = {
-                    ...metadata,
-                    handler: (execution) => {
-                        const invocation = {
-                            origin: execution.origin,
-                        };
-                        if (execution.arguments !== undefined)
-                            Object.assign(invocation, { arguments: execution.arguments });
-                        if (execution.signal !== undefined)
-                            Object.assign(invocation, { signal: execution.signal });
-                        return input.invoke(command.id, invocation);
-                    },
-                };
-                if (availability !== undefined)
-                    Object.assign(converted, { availability: () => availability });
-                // Whistle's optional fields reject explicit undefined; copy only present ones.
-                if (projections !== undefined)
-                    Object.assign(converted, { projections });
-                if (description !== undefined)
-                    Object.assign(converted, { description });
-                if (action !== undefined)
-                    Object.assign(converted, { action });
-                return converted;
-            }),
-        };
-    };
-    const mount = (mountId, declarations) => {
-        assertLive();
-        if (mountId.trim().length === 0)
-            throw new Error("App command mount ID must not be blank");
-        if (mounts.has(mountId) || panes.has(mountId))
-            throw new Error("App command mount ID is already active");
-        const state = {
-            id: mountId,
-            declarations: new Map(declarations.map((command) => [command.id, command])),
-            disposed: false,
-            contribution: undefined,
-        };
-        mounts.set(mountId, state);
-        const registerCommands = (input) => Promise.resolve().then(() => {
-            assertLive();
-            if (state.disposed)
-                throw new Error("App command mount is disposed");
-            if (state.contribution !== undefined)
-                throw new Error("App command mount already registered commands");
-            const lease = whistle.contribute(contributionFor(state, input, input.commands));
-            let active = true;
-            const contribution = {
-                update: (commands) => {
-                    if (!active || state.disposed || disposed)
-                        return;
-                    lease.update(contributionFor(state, input, commands).commands);
-                },
-                dispose: () => {
-                    if (!active)
-                        return;
-                    active = false;
-                    lease.dispose();
-                    if (state.contribution === contribution)
-                        state.contribution = undefined;
-                },
-            };
-            state.contribution = contribution;
-            return contribution;
-        });
-        const invokeReservedChord = async (input) => {
-            assertLive();
-            if (state.disposed || input.id !== commandPaletteReservedChord.id)
-                throw new Error("App reserved chord is unavailable");
-            if (input.repeat)
-                return;
-            const outcome = await execute(input.id, { origin: "browser" });
-            if (outcome.status !== "handled")
-                throw new Error("App reserved chord could not run");
-        };
-        return Object.freeze({
-            handlers: Object.freeze({ registerCommands, invokeReservedChord }),
-            dispose: () => {
-                if (state.disposed)
-                    return;
-                state.disposed = true;
-                state.contribution?.dispose();
-                state.contribution = undefined;
-                mounts.delete(state.id);
-                if (focusedMount === state.id) {
-                    focusedMount = null;
-                    refreshMenu();
-                }
-            },
-        });
-    };
-    const mountPane = (paneId) => {
-        assertLive();
-        if (paneId.trim().length === 0)
-            throw new Error("Pane command mount ID must not be blank");
-        if (mounts.has(paneId) || panes.has(paneId))
-            throw new Error("Pane command mount ID is already active");
-        const namespace = `pane-${encodeURIComponent(paneId)}`;
-        const ownedCommands = new Map();
-        const state = {
-            disposed: false,
-            snapshot: scopeSnapshot(whistle.snapshot(), paneId),
-            leases: new Set(),
-            listeners: new Set(),
-            presenters: [],
-            dispose: () => {
-                if (state.disposed)
-                    return;
-                state.disposed = true;
-                state.listeners.clear();
-                state.presenters.length = 0;
-                for (const lease of state.leases)
-                    lease.dispose();
-                state.leases.clear();
-                ownedCommands.clear();
-                state.snapshot = scopeSnapshot(whistle.snapshot(), paneId);
-                panes.delete(paneId);
-                if (focusedMount === paneId) {
-                    focusedMount = null;
-                    refreshMenu();
-                }
-                refreshPresenter();
-            },
-        };
-        panes.set(paneId, state);
-        const assertPaneLive = () => {
-            assertLive();
-            if (state.disposed)
-                throw new Error("Pane command mount is disposed");
-        };
-        const checkBindings = (commands) => {
-            for (const command of commands)
-                for (const binding of command.projections?.bindings?.values ?? [])
-                    if (reservedBindings.has(binding.trim().toLowerCase()))
-                        throw new Error("Pane commands cannot bind the reserved leader chord");
-        };
-        return Object.freeze({
-            commandId: (id) => `${namespace}:${id}`,
-            contribute: (commands) => {
-                assertPaneLive();
-                checkBindings(commands);
-                const underlying = whistle.contribute({
-                    sourceId: `pane:${paneId}`,
-                    namespace,
-                    scope: paneId,
-                    commands,
-                });
-                let active = true;
-                const lease = Object.freeze({
-                    update: (replacement) => {
-                        if (!active || state.disposed || disposed)
-                            return;
-                        checkBindings(replacement);
-                        underlying.update(replacement);
-                        ownedCommands.set(lease, new Set(replacement.map((command) => `${namespace}:${command.id}`)));
-                    },
-                    dispose: () => {
-                        if (!active)
-                            return;
-                        active = false;
-                        state.leases.delete(lease);
-                        ownedCommands.delete(lease);
-                        underlying.dispose();
-                    },
-                });
-                state.leases.add(lease);
-                ownedCommands.set(lease, new Set(commands.map((command) => `${namespace}:${command.id}`)));
-                return lease;
-            },
-            execute: (commandId, input) => {
-                const snapshot = state.snapshot;
-                const rows = input.origin === "agent"
-                    ? [snapshot.agent]
-                    : [
-                        snapshot.bindings,
-                        snapshot.palette,
-                        snapshot.slash,
-                        snapshot.help,
-                        snapshot.menu,
-                        snapshot.agent,
-                    ];
-                // A catalog action can be callable from an admitted row without a menu
-                // or palette projection. Its contribution still belongs to this pane.
-                const owned = input.origin !== "agent" &&
-                    [...ownedCommands.values()].some((ids) => ids.has(commandId));
-                const admitted = owned ||
-                    rows.some((projection) => projection.some((row) => row.commandId === commandId));
-                const human = input.origin !== "programmatic" && input.origin !== "agent";
-                if (state.disposed ||
-                    disposed ||
-                    !admitted ||
-                    (human && focusedMount !== paneId))
-                    return Promise.resolve({ status: "missing" });
-                return whistle.execute(commandId, input);
-            },
-            snapshot: () => state.snapshot,
-            subscribe: (listener) => {
-                if (state.disposed || disposed)
-                    return () => undefined;
-                state.listeners.add(listener);
-                return () => {
-                    state.listeners.delete(listener);
-                };
-            },
-            present: (presenter) => {
-                assertPaneLive();
-                const entry = { presenter };
-                state.presenters.push(entry);
-                refreshPresenter();
-                return () => {
-                    const index = state.presenters.indexOf(entry);
-                    if (index === -1)
-                        return;
-                    state.presenters.splice(index, 1);
-                    refreshPresenter();
-                };
-            },
-            dispose: state.dispose,
-        });
-    };
-    const focus = (mountId) => {
-        const state = mountId === null
-            ? undefined
-            : (mounts.get(mountId) ?? panes.get(mountId));
-        const nextFocus = mountId !== null && state !== undefined && !state.disposed
-            ? mountId
-            : null;
-        if (focusedMount === nextFocus)
-            return;
-        focusedMount = nextFocus;
-        refreshPresenter();
-        refreshMenu();
-    };
-    const registerShellCommands = (commands) => {
-        assertLive();
-        shellContribution?.dispose();
-        const contribution = whistle.contribute({
-            sourceId: "shell",
-            namespace: "shell",
-            commands,
-        });
-        shellContribution = contribution;
-        let active = true;
-        return () => {
-            if (!active)
-                return;
-            active = false;
-            contribution.dispose();
-            if (shellContribution === contribution)
-                shellContribution = undefined;
-        };
-    };
-    const registerDirectoryCommands = (rows, run) => {
-        assertLive();
-        directoryContribution?.dispose();
-        const contribution = whistle.contribute({
-            sourceId: appDirectorySourceId,
-            namespace: "app-directory",
-            commands: rows.flatMap(({ surfaceId, appTitle, command }) => {
-                const palette = command.projections?.palette;
-                if (palette === undefined)
-                    return [];
-                const projected = {
-                    id: `${encodeURIComponent(surfaceId)}-${encodeURIComponent(command.id)}`,
-                    title: command.title,
-                    category: `${appTitle} · ${command.category}`,
-                    projections: {
-                        palette: palette.order === undefined ? {} : { order: palette.order },
-                    },
-                    handler: () => run(surfaceId, command.id),
-                };
-                return command.description === undefined
-                    ? [projected]
-                    : [{ ...projected, description: command.description }];
-            }),
-        });
-        directoryContribution = contribution;
-        let active = true;
-        return () => {
-            if (!active)
-                return;
-            active = false;
-            contribution.dispose();
-            if (directoryContribution === contribution)
-                directoryContribution = undefined;
-        };
-    };
-    const menu = () => focusedMenu;
-    const isActive = (commandId) => {
-        const { bindings, palette, slash, help, menu: rows } = activeSnapshot;
-        return [bindings, palette, slash, help, rows].some((projection) => projection.some((row) => row.commandId === commandId));
-    };
-    const execute = async (commandId, input) => {
-        if (input.origin === "agent" &&
-            !whistle
-                .snapshot()
-                .agent.some((command) => command.commandId === commandId))
-            return { status: "missing" };
-        if (input.origin !== "programmatic" &&
-            input.origin !== "agent" &&
-            !isActive(commandId))
-            return { status: "missing" };
-        return whistle.execute(commandId, input);
-    };
-    const dispose = () => {
-        if (disposed)
-            return;
-        disposed = true;
-        disposePresenter?.();
-        disposePresenter = undefined;
-        for (const pane of panes.values())
-            pane.dispose();
-        for (const state of mounts.values()) {
-            state.disposed = true;
-            state.contribution?.dispose();
-            state.contribution = undefined;
-        }
-        shellContribution?.dispose();
-        shellContribution = undefined;
-        directoryContribution?.dispose();
-        directoryContribution = undefined;
-        mounts.clear();
-        focusedMount = null;
-        focusedMenu = emptyMenu;
-        whistle.close();
-        activeSnapshot = whistle.snapshot();
-        unsubscribeWhistle();
-        listeners.clear();
-    };
-    return Object.freeze({
-        mount,
-        mountPane,
-        focus,
-        registerShellCommands,
-        registerDirectoryCommands,
-        menu,
-        active: () => activeSnapshot,
-        execute,
-        snapshot: whistle.snapshot,
-        subscribe: (listener) => {
-            if (disposed)
-                return () => undefined;
-            listeners.add(listener);
-            return () => {
-                listeners.delete(listener);
-            };
-        },
-        dispose,
-    });
-}

package/dist/shell/commands.d.ts

@@ -1,25 +0,0 @@
-import type { WhistleCommand } from "@fungi.computer/whistle";
-/** The Back binding, also shown by the shell in window chrome. */
-export declare const backBinding = "<leader> [";
-/** The behavior supplied by either a browser or terminal workspace shell. */
-export type ShellActions = Readonly<{
-    /** Show the host-owned App picker. */
-    openApp: () => void;
-    /** Show the active command and key reference. */
-    showKeys: () => void;
-    /** Show the focused window command search. */
-    showCommandLine: () => void;
-    /** Move focus to the previous or next window. */
-    focusStep: (step: -1 | 1) => void;
-    /** Swap the focused window with its previous or next neighbor. */
-    swapStep: (step: -1 | 1) => void;
-    /** Toggle the focused window between normal and zoomed presentation. */
-    toggleZoom: () => void;
-    /** Ask the focused view to go back in its own history. */
-    back?: () => void;
-}>;
-/**
- * Shared workspace declarations. Window moves have direct Alt chords and
- * leader keys; global actions live behind the shell-owned leader.
- */
-export declare function shellCommands(actions: ShellActions): readonly WhistleCommand<never>[];

package/dist/shell/commands.js

@@ -1,78 +0,0 @@
-/** The Back binding, also shown by the shell in window chrome. */
-export const backBinding = "<leader> [";
-/**
- * Shared workspace declarations. Window moves have direct Alt chords and
- * leader keys; global actions live behind the shell-owned leader.
- */
-export function shellCommands(actions) {
-    const windowCommand = (id, title, keys, order, run) => ({
-        id,
-        title,
-        category: "Window",
-        projections: {
-            bindings: { values: keys, order },
-            palette: { order: 10 + order },
-            help: { order },
-        },
-        handler: () => {
-            run();
-        },
-    });
-    return [
-        {
-            id: "open-app",
-            title: "Open App",
-            category: "Apps",
-            description: "Show available Apps.",
-            projections: {
-                bindings: { values: ["<leader> o"], order: 0 },
-                palette: { order: 0 },
-            },
-            handler: () => {
-                actions.openApp();
-            },
-        },
-        {
-            id: "show-command-palette",
-            title: "Show keys",
-            category: "System",
-            description: "Show the keys and commands available here.",
-            projections: { bindings: { values: ["mod+k"], order: 0 } },
-            handler: () => {
-                actions.showKeys();
-            },
-        },
-        {
-            id: "command-line",
-            title: "Command line",
-            category: "System",
-            description: "Search the focused window's commands.",
-            projections: { bindings: { values: ["<leader> :"], order: 1 } },
-            handler: () => {
-                actions.showCommandLine();
-            },
-        },
-        windowCommand("focus-previous", "Focus previous window", ["alt+left", "<leader> h"], 2, () => {
-            actions.focusStep(-1);
-        }),
-        windowCommand("focus-next", "Focus next window", ["alt+right", "<leader> l"], 3, () => {
-            actions.focusStep(1);
-        }),
-        windowCommand("swap-previous", "Swap window left", ["alt+shift+left", "<leader> {"], 4, () => {
-            actions.swapStep(-1);
-        }),
-        windowCommand("swap-next", "Swap window right", ["alt+shift+right", "<leader> }"], 5, () => {
-            actions.swapStep(1);
-        }),
-        windowCommand("zoom", "Zoom window", ["alt+enter", "<leader> z"], 6, () => {
-            actions.toggleZoom();
-        }),
-        // Alt+Left focuses the previous window. The leader crosses App iframes;
-        // Cmd+[ is the Mac browser Back chord while the shell has focus.
-        ...(actions.back === undefined
-            ? []
-            : [
-                windowCommand("back", "Back", [backBinding, "cmd+["], 7, actions.back),
-            ]),
-    ];
-}

package/dist/shell/index.d.ts

@@ -1,8 +0,0 @@
-/** Client-side tools for embedding and arranging Apps in a host-owned shell. */
-export * from "./workbench.js";
-export * from "./command-host.js";
-export * from "./keys.js";
-export * from "./commands.js";
-export * from "./window-manager.js";
-export * from "./app-directory.js";
-export { createBrowserActionHandler } from "./browser-actions.js";

package/dist/shell/index.js

@@ -1,8 +0,0 @@
-/** Client-side tools for embedding and arranging Apps in a host-owned shell. */
-export * from "./workbench.js";
-export * from "./command-host.js";
-export * from "./keys.js";
-export * from "./commands.js";
-export * from "./window-manager.js";
-export * from "./app-directory.js";
-export { createBrowserActionHandler } from "./browser-actions.js";

package/dist/shell/keys.d.ts

@@ -1,41 +0,0 @@
-import type { WhistleBindingProjection, WhistleExecutionInput, WhistleExecutionOutcome, WhistleSnapshot } from "@fungi.computer/whistle";
-/** One physical chord parsed from a Whistle binding such as `alt+left`. */
-export type ShellChord = Readonly<{
-    key: string;
-    alt: boolean;
-    ctrl: boolean;
-    meta: boolean;
-    shift: boolean;
-}>;
-/** Keyboard facts shared by DOM events and terminal adapters. */
-export type KeyEventFacts = Pick<KeyboardEvent, "altKey" | "ctrlKey" | "key" | "metaKey" | "shiftKey">;
-/**
- * Parse one single-chord binding. Sequences (including `<leader> x`) and
- * unknown modifiers return `null`; they are never matched as one chord.
- */
-export declare function parseChord(binding: string, mac: boolean): ShellChord | null;
-/** Whether one key event is exactly this chord. */
-export declare function chordMatches(event: KeyEventFacts, chord: ShellChord): boolean;
-/** One key offered after the leader chord, with the command it runs. */
-export type LeaderKey = WhistleBindingProjection & Readonly<{
-    key: string;
-}>;
-/** The `<leader> x` rows of the active view, first binding per key. */
-export declare function leaderKeys(active: WhistleSnapshot): readonly LeaderKey[];
-/** Whether one key event (after the leader) selects this leader key. */
-export declare function leaderKeyMatches(event: Pick<KeyboardEvent, "altKey" | "ctrlKey" | "key" | "metaKey">, key: string): boolean;
-/** The shell host operations the key dispatcher reads. */
-export type ShellKeyHost = Readonly<{
-    /** Read the commands currently available to the focused view. */
-    active: () => WhistleSnapshot;
-    /** Observe command changes; call the returned disposer to stop listening. */
-    subscribe: (listener: () => void) => () => void;
-    /** Run a command through the host with the original input origin. */
-    execute: (commandId: string, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
-}>;
-/**
- * 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 declare function installShellKeys(root: HTMLElement, host: ShellKeyHost, mac: boolean): () => void;