@fungi.computer/tourtois 0.0.0-stage → 0.1.0

package/dist/desktop/gill-param-picker.js

@@ -0,0 +1,145 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import {} from "@fungi.computer/gills";
+import { Button } from "@fungi.computer/caps/components/button";
+import { Dialog, DialogContent, DialogHeader, DialogTitle, } from "@fungi.computer/caps/components/dialog";
+import { Field, Form, FormFooter } from "@fungi.computer/caps/components/field";
+import { Input } from "@fungi.computer/caps/components/input";
+import { Select } from "@fungi.computer/caps/components/select";
+import { validDesktopGillParams } from "../desktop-layout.js";
+/** Chooses placement context through the Gill's own declaration and host inventory. */
+export function GillParamPicker({ gill, initialParams = {}, computers, transport, editing, onSave, onClose, }) {
+    const [values, setValues] = useState({
+        ...initialParams,
+    });
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState(null);
+    const declared = gill.params ?? [];
+    return (_jsx(Dialog, { open: true, onOpenChange: (open) => {
+            if (!open && !saving)
+                onClose();
+        }, children: _jsxs(DialogContent, { className: "tourtois-gill-param-dialog", children: [_jsx(DialogHeader, { children: _jsxs(DialogTitle, { children: [editing ? "Configure" : "Place", " ", gill.title] }) }), _jsxs(Form, { busy: saving, onSubmit: (event) => {
+                        event.preventDefault();
+                        if (!validDesktopGillParams(values, declared))
+                            return;
+                        setSaving(true);
+                        void onSave(values)
+                            .then((accepted) => {
+                            if (accepted)
+                                onClose();
+                            else
+                                setError("Your widget could not be saved. Try again.");
+                        })
+                            .catch((cause) => {
+                            console.error("Gill placement could not be confirmed", cause);
+                            setError("Your widget placement could not be confirmed.");
+                        })
+                            .finally(() => {
+                            setSaving(false);
+                        });
+                    }, children: [declared.map((param, index) => {
+                            const previous = declared.slice(0, index);
+                            const context = Object.fromEntries(previous.flatMap((param) => {
+                                const value = values[param.key];
+                                return value ? [[param.key, value]] : [];
+                            }));
+                            return (_jsx(ParameterChoice, { surfaceId: gill.surfaceId, viewId: gill.gillId, param: param, params: context, ready: previous.every((param) => !param.required || Boolean(values[param.key])), value: values[param.key] ?? "", computers: computers, transport: transport, onChange: (value) => {
+                                    setValues((before) => {
+                                        const next = Object.fromEntries(declared.slice(0, index).flatMap((param) => {
+                                            const value = before[param.key];
+                                            return value ? [[param.key, value]] : [];
+                                        }));
+                                        if (value)
+                                            next[param.key] = value;
+                                        return next;
+                                    });
+                                } }, `${param.key}:${JSON.stringify(context)}`));
+                        }), _jsxs(FormFooter, { error: error, children: [_jsx(Button, { type: "button", variant: "ghost", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "submit", disabled: !validDesktopGillParams(values, declared), children: editing ? "Save widget" : "Place widget" })] })] })] }) }));
+}
+function ParameterChoice({ surfaceId, viewId, param, params, ready, value, computers, transport, onChange, }) {
+    const [reply, setReply] = useState(null);
+    const [error, setError] = useState(null);
+    const [after, setAfter] = useState();
+    const [loading, setLoading] = useState(false);
+    const [retry, setRetry] = useState(0);
+    const latestParams = useRef(params);
+    latestParams.current = params;
+    const contextKey = JSON.stringify(params);
+    useEffect(() => {
+        if (!ready || param.options === undefined || param.kind === "computer") {
+            setReply(null);
+            return;
+        }
+        let retired = false;
+        setLoading(true);
+        setError(null);
+        let request = {
+            surfaceId,
+            viewId,
+            options: param.key,
+            params: latestParams.current,
+        };
+        if (after !== undefined)
+            request = { ...request, after };
+        void transport
+            .requestGill(request)
+            .then((reply) => {
+            if (retired)
+                return;
+            if (!("options" in reply))
+                throw new Error(reply.state === "error"
+                    ? reply.error
+                    : "The widget returned rows instead of choices.");
+            setReply(reply);
+        })
+            .catch((cause) => {
+            if (retired)
+                return;
+            console.error("Gill choices could not be read", {
+                surfaceId,
+                viewId,
+                parameter: param.key,
+                cause,
+            });
+            setReply(null);
+            setError(`Choices for ${param.label} could not be loaded.`);
+        })
+            .finally(() => {
+            if (!retired)
+                setLoading(false);
+        });
+        return () => {
+            retired = true;
+        };
+    }, [
+        surfaceId,
+        viewId,
+        param.key,
+        param.kind,
+        param.options,
+        contextKey,
+        ready,
+        after,
+        retry,
+        transport,
+    ]);
+    const choices = param.kind === "computer"
+        ? computers.map((computer) => ({
+            value: computer.computerId,
+            label: computer.name,
+        }))
+        : (reply?.options ?? []);
+    return (_jsxs("div", { children: [_jsx(Field, { label: param.label, required: param.required, optional: !param.required, error: error, children: param.kind === "computer" || param.options !== undefined ? (_jsxs(Select, { "aria-label": param.label, value: value, disabled: !ready || loading, onChange: (event) => {
+                        onChange(event.currentTarget.value);
+                    }, children: [_jsx("option", { value: "", children: loading ? "Loading choices…" : `Choose a ${param.kind}` }), value && !choices.some((choice) => choice.value === value) ? (_jsx("option", { value: value, children: value })) : null, choices.map((choice) => (_jsx("option", { value: choice.value, children: choice.label }, choice.value)))] })) : (_jsx(Input, { "aria-label": param.label, value: value, maxLength: 256, disabled: !ready, onChange: (event) => {
+                        onChange(event.currentTarget.value);
+                    } })) }), reply?.next !== undefined ? (_jsx(Button, { type: "button", size: "sm", variant: "ghost", disabled: loading, onClick: () => {
+                    setAfter(reply.next);
+                }, children: "More choices" })) : null, error ? (_jsx(Button, { type: "button", size: "sm", variant: "ghost", onClick: () => {
+                    setRetry((value) => value + 1);
+                }, children: "Retry choices" })) : null, ready &&
+                !loading &&
+                !error &&
+                (param.kind === "computer" || param.options !== undefined) &&
+                choices.length === 0 ? (_jsxs("p", { role: "status", children: ["No ", param.kind, " choices available."] })) : null] }));
+}

package/dist/desktop/launcher-gill.d.ts

@@ -0,0 +1,20 @@
+import type { AppGridItem } from "@fungi.computer/caps/blocks/launcher-grid";
+import type { AppBarItem } from "@fungi.computer/caps/blocks/app-bar";
+import type { AppGillDesktopSize } from "@fungi.computer/gills";
+/** Trusted shell Gill. Defaults to the same complete launchable set/order as the AppBar. */
+export declare function LauncherGill({ items, size, onAllApps, loading, unavailable, onRetry, warnings, preferences, onPreference, editHandle, onContentHeight, }: {
+    items: readonly AppBarItem[];
+    size?: AppGillDesktopSize;
+    onAllApps: () => void;
+    loading?: boolean;
+    unavailable?: boolean;
+    onRetry?: () => void;
+    warnings?: readonly AppGridItem[];
+    preferences: Readonly<{
+        pinned: readonly string[];
+        hidden: readonly string[];
+    }>;
+    onPreference: (id: string, state: "Pinned" | "Shown" | "Hidden") => void;
+    onContentHeight?: ((height: number) => void) | undefined;
+    editHandle?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/desktop/launcher-gill.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { AppGrid } from "@fungi.computer/caps/blocks/launcher-grid";
+import { Button } from "@fungi.computer/caps/components/button";
+import { DataList, DataRow } from "@fungi.computer/caps/components/data-list";
+import { Select } from "@fungi.computer/caps/components/select";
+import { EmptyState } from "@fungi.computer/caps/blocks/empty-state";
+import { Sigil } from "@fungi.computer/sigils";
+import { GillFrame } from "./gill-frame.js";
+/** Trusted shell Gill. Defaults to the same complete launchable set/order as the AppBar. */
+export function LauncherGill({ items, size = "M", onAllApps, loading = false, unavailable = false, onRetry, warnings = [], preferences, onPreference, editHandle, onContentHeight, }) {
+    const [editing, setEditing] = useState(false);
+    const stateFor = (id) => preferences.hidden.includes(id)
+        ? "Hidden"
+        : preferences.pinned.includes(id)
+            ? "Pinned"
+            : "Shown";
+    const shown = items.filter((item) => stateFor(item.id) !== "Hidden");
+    const ordered = [
+        ...shown.filter((item) => stateFor(item.id) === "Pinned"),
+        ...shown.filter((item) => stateFor(item.id) !== "Pinned"),
+    ];
+    const tiles = ordered.map((item) => ({
+        id: item.id,
+        label: item.label,
+        icon: item.icon,
+        onSelect: item.onSelect,
+    }));
+    const ready = !loading && !unavailable;
+    return (_jsxs(GillFrame, { title: "Launcher", size: size, onContentHeight: onContentHeight, editHandle: editHandle ?? (_jsx(_Fragment, { children: _jsx(Button, { size: "sm", variant: "ghost", "aria-expanded": editing, onClick: () => {
+                    setEditing(!editing);
+                }, children: editing ? "Done" : "Edit launcher" }) })), children: [loading ? _jsx("p", { role: "status", children: "Loading Apps\u2026" }) : null, unavailable ? (_jsxs("p", { role: "alert", children: ["App directory unavailable.", " ", onRetry ? (_jsx(Button, { size: "sm", variant: "ghost", onClick: onRetry, children: "Retry" })) : null] })) : null, ready ? (_jsxs(_Fragment, { children: [items.length === 0 ? (_jsx(EmptyState, { variant: "hint", title: "No Apps available", description: "Installed launchable Apps appear here." })) : null, items.length > 0 && shown.length === 0 ? (_jsx("p", { children: "No Apps shown. Edit the launcher to show them again." })) : null, _jsx(AppGrid, { "aria-label": "Team Apps", items: [
+                            ...tiles,
+                            ...warnings,
+                            {
+                                id: "all-apps",
+                                label: "All Apps ›",
+                                icon: _jsx(Sigil, { name: "allApps" }),
+                                onSelect: onAllApps,
+                            },
+                        ], size: "lg" }), editing ? (_jsx(DataList, { "aria-label": "Launcher preferences", children: items.map((item) => (_jsx(DataRow, { children: _jsxs("div", { className: "tourtois-launcher-preference", children: [_jsx("span", { "aria-hidden": "true", className: "grid size-6 place-items-center [&_svg]:size-full", children: item.icon ?? _jsx(Sigil, { name: "installApps" }) }), _jsx("div", { className: "tourtois-launcher-preference-identity", children: _jsx("span", { children: item.label }) }), _jsxs(Select, { "aria-label": `Launcher state for ${item.label}`, value: stateFor(item.id), onChange: (event) => {
+                                            const value = event.currentTarget.value;
+                                            if (value !== "Pinned" &&
+                                                value !== "Shown" &&
+                                                value !== "Hidden")
+                                                return;
+                                            onPreference(item.id, value);
+                                        }, children: [_jsx("option", { value: "Shown", children: "Shown" }), _jsx("option", { value: "Pinned", children: "Pinned" }), _jsx("option", { value: "Hidden", children: "Hidden" })] })] }) }, item.id))) })) : null] })) : null] }));
+}

package/dist/desktop/own-launchers.d.ts

@@ -0,0 +1,9 @@
+/** Launchers rendered by Tourtois itself; host pages have their own published list. */
+export declare const tourtoisLaunchers: readonly [{
+    readonly id: "settings-default-apps";
+    readonly label: "Default Apps";
+    readonly icon: "installApps";
+    readonly location: {
+        readonly category: "defaults";
+    };
+}];

package/dist/desktop/own-launchers.js

@@ -0,0 +1,9 @@
+/** Launchers rendered by Tourtois itself; host pages have their own published list. */
+export const tourtoisLaunchers = [
+    {
+        id: "settings-default-apps",
+        label: "Default Apps",
+        icon: "installApps",
+        location: { category: "defaults" },
+    },
+];

package/dist/desktop/row-gill.d.ts

@@ -0,0 +1,24 @@
+import type { AppBarItem } from "@fungi.computer/caps/blocks/app-bar";
+import { type ReactNode } from "react";
+import { type GillResponse } from "@fungi.computer/gills";
+import type { TeamWorkbenchHostHandle } from "@fungi.computer/oyster/shell/workbench";
+import type { AppDeclaredGill, AppGillDesktopSize } from "@fungi.computer/gills";
+export type DesktopGillTransport = Pick<TeamWorkbenchHostHandle, "requestGill" | "watchGillChanges">;
+/** The host admits reads; opening a row navigates inside its App. */
+export declare function RowGill({ surfaceId, appHeader, declaration, params, size, paused, transport, onOpen, onConfigure, launch, editHandle, onContentHeight, }: {
+    surfaceId: string;
+    appHeader: Readonly<{
+        name: string;
+        icon: ReactNode;
+    }>;
+    declaration: AppDeclaredGill;
+    params?: Readonly<Record<string, string>> | undefined;
+    size: AppGillDesktopSize;
+    paused: boolean;
+    transport: DesktopGillTransport;
+    onOpen: (target: NonNullable<GillResponse["rows"][number]["open"]>) => void;
+    onConfigure?: (() => void) | undefined;
+    launch?: Pick<AppBarItem, "label" | "onSelect"> | undefined;
+    onContentHeight?: ((height: number) => void) | undefined;
+    editHandle?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/desktop/row-gill.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Badge } from "@fungi.computer/caps/components/badge";
+import { useEffect, useState } from "react";
+import { decodeDeclaredGillResponse, } from "@fungi.computer/gills";
+import { DataList, DataRow } from "@fungi.computer/caps/components/data-list";
+import { ActionRow } from "@fungi.computer/caps/components/action-row";
+import { Button } from "@fungi.computer/caps/components/button";
+import { EmptyState } from "@fungi.computer/caps/blocks/empty-state";
+import { Status } from "@fungi.computer/caps/components/status";
+import { GillFrame } from "./gill-frame.js";
+function detail(row) {
+    return row.tone === "error" && row.detail ? (_jsx(Badge, { size: "sm", variant: "quiet", tone: "error", children: row.detail })) : (row.detail);
+}
+function rowStatus(row) {
+    return row.status ? (_jsx(Status, { size: "compact", label: row.status.label, tone: row.status.tone })) : null;
+}
+/** The host admits reads; opening a row navigates inside its App. */
+export function RowGill({ surfaceId, appHeader, declaration, params, size, paused, transport, onOpen, onConfigure, launch, editHandle, onContentHeight, }) {
+    const [response, setResponse] = useState(null);
+    const [error, setError] = useState(null);
+    const [pages, setPages] = useState([
+        undefined,
+    ]);
+    const after = pages[pages.length - 1];
+    const [retry, setRetry] = useState(0);
+    useEffect(() => {
+        if (paused)
+            return;
+        let closed = false;
+        const retired = () => closed;
+        let stop;
+        let loading;
+        let dirty = false;
+        let permanentlyUnavailable = false;
+        const refresh = () => {
+            if (permanentlyUnavailable || retired())
+                return Promise.resolve();
+            dirty = true;
+            if (loading)
+                return loading;
+            loading = (async () => {
+                while (dirty && !retired() && !permanentlyUnavailable) {
+                    dirty = false;
+                    const reply = await transport.requestGill({
+                        surfaceId,
+                        viewId: declaration.id,
+                        params,
+                        after,
+                    });
+                    if ("options" in reply)
+                        throw new Error("Expected Gill rows, received options");
+                    const next = decodeDeclaredGillResponse(reply, declaration);
+                    if (retired())
+                        return;
+                    setResponse(next);
+                    setError(null);
+                    if (next.state === "error" &&
+                        next.reason === "exec_isolation_required") {
+                        permanentlyUnavailable = true;
+                        const close = stop;
+                        stop = undefined;
+                        await close?.().catch((cause) => {
+                            console.error("Desktop Gill observation close failed", {
+                                surfaceId,
+                                viewId: declaration.id,
+                                cause,
+                            });
+                        });
+                    }
+                }
+            })()
+                .catch((cause) => {
+                console.error("Desktop Gill read failed", {
+                    surfaceId,
+                    viewId: declaration.id,
+                    cause,
+                });
+                if (!retired())
+                    setError("This widget could not be refreshed.");
+            })
+                .finally(() => {
+                loading = undefined;
+            });
+            return loading;
+        };
+        void (async () => {
+            const watch = await transport.watchGillChanges({ surfaceId, viewId: declaration.id }, refresh);
+            if (retired()) {
+                await watch.close();
+                return;
+            }
+            stop = () => watch.close();
+            await refresh();
+        })().catch((cause) => {
+            console.error("Desktop Gill observation failed", {
+                surfaceId,
+                viewId: declaration.id,
+                cause,
+            });
+            if (!retired())
+                setError("This widget is unavailable.");
+        });
+        return () => {
+            closed = true;
+            void stop?.().catch((cause) => {
+                console.error("Desktop Gill observation close failed", {
+                    surfaceId,
+                    viewId: declaration.id,
+                    cause,
+                });
+            });
+        };
+    }, [after, declaration, params, paused, retry, surfaceId, transport]);
+    const recovery = response?.state === "error" ? response.recovery : undefined;
+    const recoveryParam = recovery?.kind === "configure"
+        ? declaration.params?.find((param) => param.key === recovery.param)
+        : undefined;
+    const opensApp = recovery?.kind === "open" ||
+        (recovery === undefined &&
+            response?.state === "error" &&
+            response.reason === "exec_isolation_required");
+    return (_jsxs(GillFrame, { title: response?.title ?? declaration.title, appHeader: appHeader, size: size, onContentHeight: onContentHeight, editHandle: editHandle, children: [error ? (_jsxs("p", { role: "alert", children: [error, " ", _jsx(Button, { size: "sm", variant: "ghost", onClick: () => {
+                            setRetry((value) => value + 1);
+                        }, children: "Retry" })] })) : null, !response && !error ? (_jsxs("p", { role: "status", children: ["Loading ", declaration.title, "\u2026"] })) : null, response?.state === "error" ? (_jsxs("div", { children: [_jsx("p", { role: "alert", children: response.reason === "exec_isolation_required" && launch
+                            ? `${response.title} isn't available on this preview. Open ${launch.label}.`
+                            : response.error }), recoveryParam && onConfigure ? (_jsxs(Button, { size: "sm", variant: "primary", onClick: onConfigure, children: ["Choose ", recoveryParam.label] })) : null, opensApp && launch ? (_jsxs(Button, { size: "sm", variant: "primary", onClick: () => {
+                            launch.onSelect();
+                        }, children: ["Open ", launch.label] })) : null] })) : null, response?.state === "empty" ? (_jsx(EmptyState, { variant: "hint", title: `No ${response.title} items yet`, description: `${response.title} items appear here when available.` })) : null, response?.state === "full" ? (_jsx(DataList, { "aria-label": `${response.title} rows`, density: "compact", children: response.rows.map((row) => (_jsx(DataRow, { children: row.open ? (_jsx(ActionRow, { density: "compact", label: row.title, description: detail(row), trailing: rowStatus(row), "aria-label": `Open: ${row.title}`, onClick: () => {
+                            if (row.open)
+                                onOpen(row.open);
+                        } })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "tourtois-gill-text-row", children: [_jsx("span", { children: row.title }), row.detail ? _jsx("small", { children: detail(row) }) : null] }), rowStatus(row)] })) }, row.id))) })) : null, pages.length > 1 ? (_jsx(Button, { size: "sm", variant: "ghost", disabled: paused, onClick: () => {
+                    setPages((current) => current.slice(0, -1));
+                }, children: "Previous page" })) : null, response && response.state !== "error" && response.next !== undefined ? (_jsx(Button, { size: "sm", variant: "ghost", disabled: paused, onClick: () => {
+                    setPages((current) => [...current, response.next]);
+                }, children: "Next page" })) : null] }));
+}

package/dist/desktop-api.d.ts

@@ -0,0 +1,63 @@
+import * as z from "zod";
+import type { appMethods } from "@fungi.computer/agar/backend";
+export declare const desktopSnapshotSchema: z.ZodObject<{
+    layout: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            surfaceId: z.ZodString;
+            gillId: z.ZodString;
+            size: z.ZodEnum<{
+                S: "S";
+                M: "M";
+                L: "L";
+            }>;
+            col: z.ZodNumber;
+            row: z.ZodNumber;
+            params: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>;
+        launcher: z.ZodObject<{
+            pinned: z.ZodArray<z.ZodString>;
+            hidden: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    source: z.ZodEnum<{
+        none: "none";
+        member: "member";
+        team: "team";
+    }>;
+    memberRevision: z.ZodNullable<z.ZodNumber>;
+    teamRevision: z.ZodNullable<z.ZodNumber>;
+    canWriteTeam: z.ZodBoolean;
+    notice: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const desktopWidgetsSchema: z.ZodObject<{
+    widgets: z.ZodArray<z.ZodObject<{
+        surfaceId: z.ZodString;
+        gillId: z.ZodString;
+        title: z.ZodString;
+        sizes: z.ZodArray<z.ZodEnum<{
+            S: "S";
+            M: "M";
+            L: "L";
+        }>>;
+        kind: z.ZodEnum<{
+            app: "app";
+            launcher: "launcher";
+        }>;
+        params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            kind: z.ZodEnum<{
+                computer: "computer";
+                repository: "repository";
+                branch: "branch";
+            }>;
+            required: z.ZodBoolean;
+            options: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DesktopMethods = z.output<typeof appMethods.schema>;
+export type DesktopSnapshot = z.output<typeof desktopSnapshotSchema>;
+export type DesktopMutation = "layout.place" | "layout.move" | "layout.resize" | "layout.remove" | "layout.launcher" | "layout.set" | "layout.reset";

package/dist/desktop-api.js

@@ -0,0 +1,31 @@
+import * as z from "zod";
+import { desktopArrangeSchema, desktopLayoutSchema } from "./desktop-layout.js";
+import * as Schema from "effect/Schema";
+import { appGillParamsSchema } from "@fungi.computer/gills";
+export const desktopSnapshotSchema = z.strictObject({
+    layout: desktopLayoutSchema,
+    source: z.enum(["member", "team", "none"]),
+    memberRevision: desktopArrangeSchema.shape.basedOn,
+    teamRevision: desktopArrangeSchema.shape.basedOn,
+    canWriteTeam: z.boolean(),
+    notice: z.string().nullable(),
+});
+export const desktopWidgetsSchema = z.strictObject({
+    widgets: z.array(z.strictObject({
+        surfaceId: z.string().min(1),
+        gillId: z.string().min(1),
+        title: z.string(),
+        sizes: z.array(z.enum(["S", "M", "L"])),
+        kind: z.enum(["app", "launcher"]),
+        params: z
+            .array(z.strictObject({
+            key: z.string(),
+            label: z.string(),
+            kind: z.enum(["computer", "repository", "branch"]),
+            required: z.boolean(),
+            options: z.string().optional(),
+        }))
+            .refine((value) => Schema.is(appGillParamsSchema)(value))
+            .optional(),
+    })),
+});

package/dist/desktop-client.d.ts

@@ -0,0 +1,19 @@
+import type { AppStorage } from "@fungi.computer/agar/storage";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import { type DesktopMethods, type DesktopMutation, type DesktopSnapshot } from "./desktop-api.js";
+import { type DesktopArrangeResult, type DesktopGill } from "./desktop-layout.js";
+export type DesktopLayoutClient = Readonly<{
+    get: () => DesktopSnapshot & {
+        widgets: readonly DesktopGill[];
+        refreshFailure: Error | null;
+    };
+    subscribe: (listener: () => void) => () => void;
+    refresh: () => Promise<void>;
+    mutate: (method: DesktopMutation, input: WhistleJsonValue) => Promise<DesktopArrangeResult>;
+    close: () => void;
+}>;
+/** Watch invalidations only; the backend owns resolution, catalog and every write. */
+export declare function createDesktopLayoutClient({ storage, methods, }: {
+    storage: Pick<AppStorage, "watch">;
+    methods: DesktopMethods;
+}): Promise<DesktopLayoutClient>;

package/dist/desktop-client.js

@@ -0,0 +1,127 @@
+import { AppError } from "@fungi.computer/agar/errors";
+import { desktopSnapshotSchema, desktopWidgetsSchema, } from "./desktop-api.js";
+import { desktopArrangeResultSchema, } from "./desktop-layout.js";
+/** Watch invalidations only; the backend owns resolution, catalog and every write. */
+export async function createDesktopLayoutClient({ storage, methods, }) {
+    const watch = await storage.watch("desktop");
+    const listeners = new Set();
+    let snapshot;
+    let closed = false;
+    const isClosed = () => closed;
+    let dirty = false;
+    let pending;
+    let retirePending;
+    const publishRefreshFailure = (cause) => {
+        if (isClosed() || snapshot === undefined)
+            return;
+        const previous = snapshot.refreshFailure;
+        if (previous !== null &&
+            (previous === cause ||
+                (!(previous instanceof AppError) && previous.cause === cause)))
+            return;
+        snapshot = {
+            ...snapshot,
+            refreshFailure: cause instanceof AppError
+                ? cause
+                : new Error("Your desktop could not be refreshed.", { cause }),
+        };
+        for (const notify of listeners)
+            notify();
+    };
+    const refresh = () => {
+        if (isClosed())
+            return Promise.resolve();
+        dirty = true;
+        if (pending)
+            return pending;
+        const attempt = { retired: false };
+        const isRetired = () => attempt.retired;
+        let timer;
+        const interrupted = new Promise((resolve, reject) => {
+            retirePending = () => {
+                attempt.retired = true;
+                resolve();
+            };
+            // Bound the entire shared refresh, including coalesced invalidations.
+            timer = setTimeout(() => {
+                attempt.retired = true;
+                reject(new AppError("Your desktop read timed out. Try refreshing again.", {
+                    code: "TIMEOUT",
+                    retryable: true,
+                }));
+            }, 10_000);
+        });
+        const reading = (async () => {
+            while (dirty && !isClosed() && !isRetired()) {
+                dirty = false;
+                const [layout, widgets] = await Promise.all([
+                    methods
+                        .call("layout.get", "{}")
+                        .then((value) => desktopSnapshotSchema.parse(value)),
+                    methods
+                        .call("widgets.available", "{}")
+                        .then((value) => desktopWidgetsSchema.parse(value)),
+                ]);
+                if (isClosed() || isRetired())
+                    return;
+                snapshot = {
+                    ...layout,
+                    widgets: widgets.widgets,
+                    refreshFailure: null,
+                };
+                for (const notify of listeners)
+                    notify();
+            }
+        })();
+        pending = Promise.race([reading, interrupted])
+            .finally(() => {
+            clearTimeout(timer);
+            retirePending = undefined;
+            pending = undefined;
+        })
+            .catch((cause) => {
+            publishRefreshFailure(cause);
+            throw cause;
+        });
+        return pending;
+    };
+    const unsubscribe = watch.subscribe(() => {
+        // Handle watcher failures through the same idempotent state publisher.
+        void refresh().catch(publishRefreshFailure);
+    });
+    const close = () => {
+        closed = true;
+        retirePending?.();
+        unsubscribe();
+        watch.close();
+        listeners.clear();
+    };
+    try {
+        await refresh();
+    }
+    catch (cause) {
+        close();
+        throw cause;
+    }
+    return {
+        get: () => {
+            if (snapshot === undefined)
+                throw new Error("The desktop has not loaded.");
+            return snapshot;
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        async mutate(method, input) {
+            const result = desktopArrangeResultSchema.parse(await methods.call(method, JSON.stringify(input)));
+            if (result.kind === "accepted" || result.code === "conflict")
+                await refresh();
+            return result;
+        },
+        close,
+    };
+}