@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/internal/browser-bridge.js

@@ -0,0 +1,203 @@
+import { reportCatchFailure } from "../failure.js";
+/**
+ * WHY: focused iframe input must report focus and forward only host-declared
+ * reserved chords while retaining local event precedence (2026-08-27).
+ */
+import { Keymap } from "@opentui/keymap";
+import * as addons from "@opentui/keymap/addons";
+import { createHtmlKeymapHost, htmlEventMatchResolver, normalizeHtmlKeyName, } from "@opentui/keymap/html";
+import { callRpc } from "./result.js";
+import { parseFocus, parseReservedChords } from "./schemas.js";
+import { parseVoidResult } from "./schemas.js";
+export function createLocalBindingState() {
+    let bindings = [];
+    const listeners = new Set();
+    return {
+        get: () => bindings,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        update: (next) => {
+            bindings = next;
+            for (const listener of Array.from(listeners)) {
+                try {
+                    listener();
+                }
+                catch (cause) {
+                    console.warn("App binding subscriber failed", cause);
+                }
+            }
+        },
+    };
+}
+export function createReservedChordState(initial) {
+    let chords = parseReservedChords(initial);
+    const listeners = new Set();
+    return {
+        get: () => chords,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        update: (next) => {
+            chords = parseReservedChords(next);
+            for (const listener of Array.from(listeners)) {
+                try {
+                    listener();
+                }
+                catch (cause) {
+                    console.warn("Reserved chord subscriber failed", cause);
+                }
+            }
+        },
+    };
+}
+export function installBrowserBridge(options) {
+    let active = true;
+    let previous;
+    const documentElement = options.window.document.querySelector("html");
+    if (!documentElement)
+        return () => {
+            active = false;
+        };
+    const htmlHost = createHtmlKeymapHost(documentElement);
+    const keymap = new Keymap(htmlHost);
+    addons.registerDefaultKeys(keymap);
+    addons.registerModBindings(keymap);
+    keymap.prependEventMatchResolver(htmlEventMatchResolver);
+    const supervise = createSupervisor(options.onBroken);
+    let offReserved = registerReservedLayer(keymap, options.chords, options.remote, supervise);
+    const report = createFocusReporter(options, supervise, () => active, (focus) => {
+        previous = focus;
+    }, () => previous);
+    const offFocus = htmlHost.onFocusChange(() => {
+        queueMicrotask(report);
+    });
+    // A click on non-focusable App content focuses this document without a
+    // focusin, and the host cannot see a pointer inside the App's frame. The
+    // document's own focus changes are what tell the host the App is in use.
+    const reportDocumentFocus = () => {
+        queueMicrotask(report);
+    };
+    options.window.addEventListener("focus", reportDocumentFocus);
+    options.window.addEventListener("blur", reportDocumentFocus);
+    const bindings = options.bindings;
+    const editing = () => currentFocus(options.window.document, options.identity.surfaceId).editing;
+    let offLocal = bindings === undefined
+        ? () => undefined
+        : registerLocalLayer(keymap, bindings, editing);
+    const offBindingSubscription = bindings === undefined
+        ? () => undefined
+        : bindings.subscribe(() => {
+            offLocal();
+            offLocal = registerLocalLayer(keymap, bindings, editing);
+        });
+    const offChordSubscription = options.chords.subscribe(() => {
+        offReserved();
+        offReserved = registerReservedLayer(keymap, options.chords, options.remote, supervise);
+    });
+    queueMicrotask(report);
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        offFocus();
+        options.window.removeEventListener("focus", reportDocumentFocus);
+        options.window.removeEventListener("blur", reportDocumentFocus);
+        offChordSubscription();
+        offReserved();
+        offBindingSubscription();
+        offLocal();
+    };
+}
+function createFocusReporter(options, supervise, isActive, setPrevious, getPrevious) {
+    return () => {
+        if (!isActive())
+            return;
+        const focus = currentFocus(options.window.document, options.identity.surfaceId);
+        const previous = getPrevious();
+        if (focus.editing === previous?.editing &&
+            focus.surface === previous.surface)
+            return;
+        setPrevious(focus);
+        supervise(() => options.remote.reportFocus(focus));
+    };
+}
+function createSupervisor(onBroken) {
+    return (operation) => {
+        try {
+            void callRpc(operation(), parseVoidResult).catch((cause) => {
+                reportCatchFailure("browser-bridge.host-call", cause);
+                onBroken(cause);
+            });
+        }
+        catch (cause) {
+            reportCatchFailure("browser-bridge.host-call", cause);
+            onBroken(cause);
+        }
+    };
+}
+function currentFocus(document, surfaceId) {
+    const active = document.activeElement;
+    return parseFocus({
+        editing: Boolean(active?.matches("input, textarea, select, [contenteditable='true']") ===
+            true || active?.closest("[contenteditable='true']")),
+        surface: document.hasFocus() ? surfaceId : null,
+    });
+}
+/**
+ * The App layer: its own registered bindings, below the reserved layer.
+ * Text entry is a mode; bare keys yield to typing, modifier chords still run.
+ */
+function registerLocalLayer(keymap, bindings, editing) {
+    const values = bindings.get();
+    return keymap.registerLayer({
+        bindings: values.map((binding, index) => ({
+            cmd: `app/${String(index)}`,
+            key: binding.key,
+        })),
+        commands: values.map((binding, index) => ({
+            name: `app/${String(index)}`,
+            run: (context) => {
+                const event = context.event.originalEvent;
+                if (event?.defaultPrevented || event?.isComposing)
+                    return false;
+                if (isBareKey(binding.key) && editing())
+                    return false;
+                binding.run();
+                return undefined;
+            },
+        })),
+        priority: 500,
+    });
+}
+function isBareKey(binding) {
+    return !/(?:^|\+)(?:ctrl|control|super|meta|cmd|alt|option|mod)\+/iu.test(binding);
+}
+function registerReservedLayer(keymap, chords, remote, supervise) {
+    const values = chords.get();
+    return keymap.registerLayer({
+        bindings: values.map((chord) => ({
+            cmd: `reserved/${chord.id}`,
+            key: {
+                ctrl: chord.ctrlKey,
+                meta: chord.altKey,
+                name: normalizeHtmlKeyName(chord.key),
+                shift: chord.shiftKey,
+                super: chord.metaKey,
+            },
+        })),
+        commands: values.map((chord) => ({
+            name: `reserved/${chord.id}`,
+            run: (context) => {
+                const event = context.event.originalEvent;
+                if (event?.defaultPrevented || event?.isComposing)
+                    return false;
+                supervise(() => remote.invokeReservedChord(chord.id, event?.repeat ?? false));
+                return undefined;
+            },
+        })),
+        priority: 1000,
+    });
+}

package/dist/internal/capabilities.d.ts

@@ -0,0 +1,13 @@
+import type { CapabilityDirectory } from "../capabilities.js";
+import type { CapabilityGrantWire } from "./protocol.js";
+export type CapabilityDirectoryController = {
+    readonly directory: CapabilityDirectory;
+    replace(values: readonly CapabilityGrantWire[]): void;
+    disconnect(): void;
+};
+export declare function createCapabilityDirectory(values: readonly CapabilityGrantWire[]): CapabilityDirectoryController;
+export declare function disposeRpcValue(value: unknown): void;
+/** Own a Cap'n Web result until its decoded data has been copied. */
+export declare function ownedRpcValue<T extends Partial<Disposable>>(value: T): Readonly<{
+    value: T;
+}> & Disposable;

package/dist/internal/capabilities.js

@@ -0,0 +1,138 @@
+import { AppError } from "../errors.js";
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { parseCapabilityGrant } from "./schemas.js";
+import { createReadonlyStore } from "./store.js";
+export function createCapabilityDirectory(values) {
+    const grants = new Map();
+    const version = createReadonlyStore(0);
+    let disconnected = false;
+    const decode = (nextValues) => {
+        const next = new Map();
+        try {
+            for (const value of nextValues) {
+                const grant = parseCapabilityGrant(value);
+                const key = capabilityKey(grant.id, grant.version);
+                if (next.has(key)) {
+                    disposeRpcValue(grant.handle);
+                    throw new AppError("Duplicate capability grant", {
+                        code: "PROTOCOL",
+                        retryable: false,
+                    });
+                }
+                // Do not clone or freeze an object-capability handle.
+                next.set(key, grant.handle);
+            }
+        }
+        catch (cause) {
+            for (const handle of next.values())
+                disposeRpcValue(handle);
+            throw cause;
+        }
+        return next;
+    };
+    for (const [key, handle] of decode(values))
+        grants.set(key, handle);
+    const dispose = (handles) => {
+        for (const handle of handles)
+            disposeRpcValue(handle);
+    };
+    const find = (contract) => {
+        if (disconnected) {
+            throw new AppError("The app connection is disposed", {
+                code: "DISCONNECTED",
+                retryable: true,
+            });
+        }
+        const key = capabilityKey(contract.id, contract.version);
+        return grants.get(key);
+    };
+    const directory = Object.freeze({
+        get version() {
+            return version.get();
+        },
+        subscribe: (listener) => version.subscribe(listener),
+        has(contract) {
+            return Boolean(find(contract));
+        },
+        require(contract) {
+            const handle = find(contract);
+            if (!handle) {
+                throw new AppError("The capability is not granted", {
+                    code: "CAPABILITY_DENIED",
+                    retryable: false,
+                });
+            }
+            try {
+                return contract.schema.parse(handle);
+            }
+            catch (cause) {
+                throw new AppError("The capability interface is malformed", {
+                    cause,
+                    code: "PROTOCOL",
+                    retryable: false,
+                });
+            }
+        },
+    });
+    return {
+        directory,
+        replace(values) {
+            if (disconnected)
+                throw new AppError("The app connection is disposed", {
+                    code: "DISCONNECTED",
+                    retryable: true,
+                });
+            const next = decode(values);
+            const previous = [...grants.values()];
+            grants.clear();
+            for (const [key, handle] of next)
+                grants.set(key, handle);
+            dispose(previous.filter((handle) => ![...next.values()].includes(handle)));
+            version.update(version.get() + 1);
+        },
+        disconnect() {
+            if (disconnected)
+                return;
+            disconnected = true;
+            dispose(grants.values());
+            grants.clear();
+            version.update(version.get() + 1);
+        },
+    };
+}
+const rpcDisposalSchema = z.unknown().transform((value) => {
+    const result = z.instanceof(Object).safeParse(value);
+    if (!result.success)
+        return undefined;
+    const view = Object.create(result.data);
+    const fields = Schema.decodeUnknownSync(Schema.Struct({
+        [Symbol.dispose]: Schema.optional(Schema.instanceOf(Function)),
+    }))(view);
+    return { owner: result.data, dispose: fields[Symbol.dispose] };
+});
+export function disposeRpcValue(value) {
+    try {
+        const disposal = rpcDisposalSchema.parse(value);
+        if (disposal === undefined || disposedValues.has(disposal.owner))
+            return;
+        disposedValues.add(disposal.owner);
+        disposal.dispose?.call(disposal.owner);
+    }
+    catch (cause) {
+        console.warn("RPC value disposal failed", cause);
+    }
+}
+/** Own a Cap'n Web result until its decoded data has been copied. */
+export function ownedRpcValue(value) {
+    return {
+        value,
+        [Symbol.dispose]() {
+            disposeRpcValue(value);
+        },
+    };
+}
+const disposedValues = new WeakSet();
+function capabilityKey(id, version) {
+    return `${id}@${String(version)}`;
+}

package/dist/internal/commands.d.ts

@@ -0,0 +1,9 @@
+import { type RpcStub } from "@fungi.computer/capnweb";
+import type { AppCommands } from "../commands.js";
+import type { LocalBindingState } from "./browser-bridge.js";
+import type { AppHostRpc } from "./protocol.js";
+export type AppCommandsController = {
+    readonly commands: AppCommands;
+    dispose(): void;
+};
+export declare function createAppCommands(remote: RpcStub<AppHostRpc>, assertConnected: () => void, onFatal: () => void, bindings?: LocalBindingState): AppCommandsController;

package/dist/internal/commands.js

@@ -0,0 +1,257 @@
+import * as Predicate from "effect/Predicate";
+import { RpcTarget } from "@fungi.computer/capnweb";
+import { WhistleActionError } from "@fungi.computer/whistle";
+import { parseFailure } from "@fungi.computer/whistle/wire";
+import { AppError } from "../errors.js";
+import { callRpc, rpcFailure, rpcSuccess } from "./result.js";
+import { appInvocation, parseCommand, parseCommandId, parseCommandInvocation, parseCommandResult, parseRegisteredCommandResult, parseVoidResult, } from "./schemas.js";
+class CommandHandlerTarget extends RpcTarget {
+    #active = true;
+    #handler;
+    #requests = new Map();
+    constructor(handler) {
+        super();
+        this.#handler = handler;
+    }
+    cancel(requestId) {
+        try {
+            this.#requests.get(parseCommandId(requestId))?.abort();
+            return Promise.resolve(rpcSuccess(undefined));
+        }
+        catch (cause) {
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+    dispose() {
+        if (!this.#active)
+            return;
+        this.#active = false;
+        for (const controller of this.#requests.values())
+            controller.abort();
+        this.#requests.clear();
+    }
+    async invoke(value) {
+        try {
+            if (!this.#active)
+                throw new AppError("The command is disposed", {
+                    code: "DISCONNECTED",
+                    retryable: true,
+                });
+            const invocation = parseCommandInvocation(value);
+            if (this.#requests.has(invocation.requestId)) {
+                throw new AppError("Duplicate command request", {
+                    code: "PROTOCOL",
+                    retryable: false,
+                });
+            }
+            if (this.#requests.size >= 64) {
+                throw new AppError("Too many command requests", {
+                    code: "HOST_FAILURE",
+                    retryable: true,
+                });
+            }
+            const controller = new AbortController();
+            this.#requests.set(invocation.requestId, controller);
+            try {
+                const result = await this.#handler(appInvocation(invocation, controller.signal));
+                const parsed = parseCommandResult(result);
+                return rpcSuccess(parsed === undefined
+                    ? { status: "handled" }
+                    : { status: "handled", result: parsed });
+            }
+            finally {
+                this.#requests.delete(invocation.requestId);
+            }
+        }
+        catch (cause) {
+            if (cause instanceof WhistleActionError) {
+                try {
+                    const failureInput = {
+                        code: cause.code,
+                        message: cause.message,
+                        details: cause.details,
+                    };
+                    const failure = parseFailure(failureInput);
+                    return rpcSuccess({
+                        status: "failed",
+                        error: failure,
+                    });
+                }
+                catch (failureCause) {
+                    return rpcFailure(failureCause);
+                }
+            }
+            return rpcFailure(cause);
+        }
+    }
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+}
+/**
+ * Project the committed commands' single-chord bindings for the iframe's App
+ * layer. `<leader>` sequences belong to the shell, which reaches them through
+ * the reserved chord, so they are not matched here.
+ */
+function localBindings(registrations) {
+    const bindings = [];
+    for (const registration of registrations.values()) {
+        const { definition, handler } = registration;
+        if (registration.commandId === undefined)
+            continue;
+        // An unavailable command still owns its chord, so the browser default
+        // (e.g. Save Page) does not run in its place.
+        const available = definition.availability?.status !== "unavailable";
+        for (const key of definition.projections?.bindings?.values ?? []) {
+            if (key.trim().includes(" ") || key.startsWith("<"))
+                continue;
+            bindings.push({
+                key,
+                run: () => {
+                    if (!available)
+                        return;
+                    void Promise.resolve()
+                        .then(() => handler({
+                        origin: "keyboard",
+                        signal: new AbortController().signal,
+                    }))
+                        .catch((cause) => {
+                        console.warn("App key command failed", cause);
+                    });
+                },
+            });
+        }
+    }
+    return bindings;
+}
+export function createAppCommands(remote, assertConnected, onFatal, bindings) {
+    const registrations = new Map();
+    let disposed = false;
+    const publishBindings = () => {
+        bindings?.update(disposed ? [] : localBindings(registrations));
+    };
+    const reportFatal = (cause) => {
+        try {
+            onFatal();
+        }
+        catch (callbackError) {
+            console.warn("App command failure callback failed", callbackError, cause);
+        }
+    };
+    const supervise = (operation) => {
+        try {
+            void callRpc(operation(), parseVoidResult).catch((cause) => {
+                reportFatal(cause);
+            });
+        }
+        catch (cause) {
+            console.warn("App command RPC supervision failed", cause);
+            reportFatal(cause);
+        }
+    };
+    const unregister = (id) => {
+        const registration = registrations.get(id);
+        if (!registration)
+            return;
+        registrations.delete(id);
+        registration.target.dispose();
+        publishBindings();
+        const commandId = registration.commandId;
+        if (!disposed && commandId !== undefined) {
+            supervise(() => remote.unregisterCommand(commandId));
+        }
+    };
+    const commands = createCommandApi(remote, assertConnected, registrations, () => disposed, unregister, publishBindings);
+    return {
+        commands,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const registration of registrations.values())
+                registration.target[Symbol.dispose]();
+            registrations.clear();
+            publishBindings();
+        },
+    };
+}
+function claimRegistration(registrations, definition, handler, target) {
+    const id = definition.id;
+    if (registrations.size >= 128 || registrations.has(id)) {
+        target.dispose();
+        throw new AppError("Command registration is unavailable", {
+            code: "INVALID_ARGUMENT",
+            retryable: false,
+        });
+    }
+    const registration = {
+        commandId: undefined,
+        definition,
+        handler,
+        target,
+    };
+    registrations.set(id, registration);
+    let released = false;
+    return {
+        commit(commandId) {
+            if (released)
+                return;
+            registration.commandId = commandId;
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            if (registrations.get(id) === registration)
+                registrations.delete(id);
+            target.dispose();
+        },
+        target,
+    };
+}
+function createCommandApi(remote, assertConnected, registrations, isDisposed, unregister, committed) {
+    return Object.freeze({
+        async register(command, handler) {
+            assertConnected();
+            if (!Predicate.isFunction(handler)) {
+                throw new AppError("Command handler must be a function", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            }
+            const definition = parseCommand(command);
+            const target = new CommandHandlerTarget(handler);
+            const lease = claimRegistration(registrations, definition, handler, target);
+            try {
+                const registration = await registerRemoteCommand(remote, definition, lease.target);
+                if (isDisposed()) {
+                    await rejectDisposedRegistration(remote, registration.commandId, target);
+                }
+                lease.commit(registration.commandId);
+                committed();
+            }
+            catch (cause) {
+                lease.release();
+                throw cause;
+            }
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                unregister(definition.id);
+            };
+        },
+    });
+}
+async function registerRemoteCommand(remote, definition, target) {
+    return callRpc(remote.registerCommand(definition, target), parseRegisteredCommandResult);
+}
+async function rejectDisposedRegistration(remote, commandId, target) {
+    target.dispose();
+    await callRpc(remote.unregisterCommand(commandId), parseVoidResult);
+    throw new AppError("The command controller is disposed", {
+        code: "DISCONNECTED",
+        retryable: true,
+    });
+}

package/dist/internal/disconnect-host.d.ts

@@ -0,0 +1,7 @@
+import type { RpcStub } from "@fungi.computer/capnweb";
+import type { AppError } from "../errors.js";
+import type { AppClientRpc } from "./protocol.js";
+export declare function disconnectHost(error: AppError | undefined, assertLive: () => void, options: {
+    readonly client: RpcStub<AppClientRpc>;
+    readonly onGracefulDisconnect: () => Promise<void>;
+}, dispose: () => void): Promise<void>;

package/dist/internal/disconnect-host.js

@@ -0,0 +1,19 @@
+import { callRpc } from "./result.js";
+import { parseErrorData, parseVoidResult } from "./schemas.js";
+export async function disconnectHost(error, assertLive, options, dispose) {
+    assertLive();
+    try {
+        const data = error === undefined
+            ? undefined
+            : parseErrorData({
+                code: error.code,
+                message: error.message,
+                retryable: error.retryable,
+            });
+        await callRpc(options.client.disconnect(data), parseVoidResult);
+        await options.onGracefulDisconnect();
+    }
+    finally {
+        dispose();
+    }
+}

package/dist/internal/git-edit-tree.d.ts

@@ -0,0 +1,6 @@
+import type { GitFileChange } from "../git-commit.js";
+import type { MemoryFs } from "./memory-fs.js";
+/** Apply changes under one tree; null means the tree became empty. */
+export declare function editTree(fs: MemoryFs, oid: string | null, changes: readonly (GitFileChange & Readonly<{
+    parts: readonly string[];
+}>)[]): Promise<string | null>;