@fungi.computer/nacre 0.0.0-stage → 0.0.2

package/dist/keys.d.ts

@@ -0,0 +1,47 @@
+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<{
+    /** The key's normalized name, such as left or escape. */
+    key: string;
+    /** Whether Alt (Option) must be held. */
+    alt: boolean;
+    /** Whether Control must be held. */
+    ctrl: boolean;
+    /** Whether Meta (Command or Super) must be held. */
+    meta: boolean;
+    /** Whether Shift must be held. */
+    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<{
+    /** The key pressed after the leader chord. */
+    key: string;
+}>;
+/** The single-keystroke `<leader>x` rows, 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;

package/dist/keys.js

@@ -0,0 +1,136 @@
+/**
+ * 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 keySegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+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;
+}
+const modifierFields = new Map([
+    ["alt", "alt"],
+    ["option", "alt"],
+    ["ctrl", "ctrl"],
+    ["control", "ctrl"],
+    ["super", "meta"],
+    ["meta", "meta"],
+    ["cmd", "meta"],
+    ["shift", "shift"],
+    ["mod", "platform"],
+]);
+/**
+ * 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.startsWith(leaderPrefix) || 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) {
+        const field = modifierFields.get(modifier);
+        if (field === undefined)
+            return null;
+        const resolved = field === "platform" ? (mac ? "meta" : "ctrl") : field;
+        chord[resolved] = true;
+    }
+    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 single-keystroke `<leader>x` rows, 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);
+        const segments = keySegmenter.segment(key)[Symbol.iterator]();
+        if (segments.next().done || !segments.next().done || 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-module.d.ts

@@ -0,0 +1,98 @@
+import type { AgentAccessOperation, AppPermissionOutcome, AppPermissionRequest, ComputerAccessOperation } from "@fungi.computer/agar";
+import type { AppStorage } from "@fungi.computer/agar/storage";
+import type { KeyWire } from "@fungi.computer/ear-tag/keys";
+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<{
+    /** The workbench the shell drives for the Team that was picked. */
+    workbench: TeamWorkbenchHostHandle;
+    /** The shell installation's own desktop storage. */
+    storage: AppStorage;
+    /** The shell installation's backend methods. */
+    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<{
+    /** The Settings controls the host hands to its workbench. */
+    controls: WorkbenchHostControls;
+    /** A child App suggested desktop Settings for one of its surfaces. */
+    suggestDesktopSettings(surfaceId: string): void;
+    /** Remove the rendered Settings. */
+    dispose(): void;
+}>;
+/**
+ * A host's App-access flow. The host owns admission, current grants and saving;
+ * the shell renders the prompt and navigates its own Settings.
+ */
+export type RequestShellAppAccess = (
+/** Current child surface and its host-admitted window Computer. */
+target: Parameters<WorkbenchHostControls["requestAppAccess"]>[0], 
+/** Rights requested through the App SDK. */
+request: AppPermissionRequest, 
+/** Shell-owned presentation, with no grant authority of its own. */
+dialog: Readonly<{
+    /** Ask the member and settle only after the host's save succeeds. */
+    ask(request: Readonly<{
+        /** Display name supplied by the host's verified installation. */
+        appName: string;
+        /** Agent operations to present. */
+        agents: readonly AgentAccessOperation[];
+        /** Computer operations to present. */
+        computers: readonly ComputerAccessOperation[];
+        /** A host refusal is visible and cannot be converted into an Allow. */
+        refusal?: Readonly<{
+            code: string;
+            message: string;
+        }>;
+        /** Commit through the host; false means refusal, rejection permits retry. */
+        allow(): Promise<boolean>;
+    }>): Promise<AppPermissionOutcome>;
+    /** Open this installation's Settings, or the App chooser for null. */
+    customize(installationId: string | null): "customize";
+}>) => Promise<AppPermissionOutcome>;
+/** Render the shell's own Settings using the embedding host's access authority. */
+export type MountPlatformControls = (root: HTMLElement, input: Readonly<{
+    /** Identity used to scope this host's Settings data. */
+    teamId: string;
+    /** Host-owned key decoders; the shell never imports the host implementation. */
+    keysWire: Pick<KeyWire<string>, "issue" | "revoke" | "summary">;
+    /** Host-owned approval flow; a shell never decides or writes its own grant. */
+    requestAppAccess: RequestShellAppAccess;
+}>) => Promise<ShellPlatformControls>;
+/** What a host gets from a picked shell Release's module. */
+export type ShellModule = Readonly<{
+    /** Render the shell into a root element. */
+    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 {
+    /** Always ShellModuleError. */
+    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-module.js

@@ -0,0 +1,90 @@
+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),
+            // As with mountShell, the trusted host supplies its own input and
+            // callback handles. Decode the picked shell's exports and results,
+            // not the embedding host's already-typed values.
+            z.unknown(),
+        ],
+        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 {
+    /** Always ShellModuleError. */
+    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/window-manager.d.ts

@@ -0,0 +1,159 @@
+import { type AppNavigationActivation, type AppNavigationState, type AppStatusAction, type AppStatusItem } from "@fungi.computer/agar";
+/**
+ * Shared window lifetime owner for browser and terminal shells.
+ *
+ * This module knows how a window is mounted and disposed. It deliberately does
+ * not know how an App is selected, admitted, or transported; those decisions
+ * are made by the owner issuing the launch descriptor.
+ */
+/** Existing cold-document bound, also used as one total preparation budget. */
+export declare const APP_SURFACE_DOCUMENT_TIMEOUT_MS = 30000;
+/**
+ * Shell-only preparation retry. No document, connection or mounted operation
+ * belongs inside `prepare`. Each fetch receives the interruptible attempt's
+ * signal; the absolute budget covers both requests and backoff, never resets,
+ * and is released as soon as preparation succeeds.
+ */
+export declare function prepareWithDeliveryRetry<A>(prepare: (signal: AbortSignal) => Promise<A>, signal: AbortSignal, onPending: () => void): Promise<A>;
+/** Minimum identity required to own a window across mount generations. */
+export type WindowLaunch = Readonly<{
+    /** The id that owns the window across its mount generations. */
+    windowId: string;
+}>;
+/** Current presentation state of a managed window. */
+export type WindowStatus = "loading" | "getting-ready" | "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<{
+    /** Preparation is waiting for delivery; no App operation is being retried. */
+    onDeliveryPending?: () => void;
+    /** 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<{
+    /** The id of the window. */
+    windowId: string;
+    /** The launch descriptor the window currently has. */
+    launch: Launch;
+    /** The container the window's App is mounted in. */
+    container: Container;
+    /** Whether the window is loading, ready, minimized or failed. */
+    status: WindowStatus;
+    /**
+     * Which mount of the window this is; it grows each time the App is mounted
+     * afresh.
+     */
+    generation: number;
+    /** The failure that put the window in the error state, if any. */
+    error?: unknown;
+    /** A failure from releasing the earlier mount, if any. */
+    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<{
+    /** The managed windows, in order. */
+    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<{
+    /** Create the App's mount inside a window's container. */
+    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>;