@fungi.computer/tourtois 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# Tourtois (`@fungi.computer/tourtois`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tourtois is the desktop for your Apps: a launcher, tiled or floating windows,
+menus and settings.
+
+![The Tourtois desktop with three Apps tiled: Bonsai's network graph and repositories, Grove, and Shed's terminal](docs/media/desktop.png)
+
+Tourtois is the shell of [Oyster](https://github.com/fungi-computer/oyster), the
+open App host that runs on your own Cloudflare account. When you sign in to an
+Oyster, Tourtois is what you see, and every other App opens inside it.
+
+## What you can do
+
+- Launch Apps from the **Launcher** on the desktop or from the top bar.
+- Arrange windows **Tiled** or **Floating** from the **Layout** menu: drag,
+  resize, zoom one window, minimize it and bring it back. A minimized App keeps
+  running, so restoring it never reloads it.
+- Use the focused App's own menus in the top bar.
+- Keep small live views of Apps on the desktop, such as Grove's inbox, and
+  **Arrange desktop** to add, move, resize and remove them.
+- Open **System Settings…** from the mushroom menu for App permissions, keys and
+  agent connectors.
+- On a phone, Apps open as a full-screen sheet over the desktop, and **Show
+  desktop** brings it back without losing unsaved work.
+
+<img alt="Tourtois on a phone in the light theme: Grove's inbox above the Launcher" src="docs/media/desktop-phone.png" width="300">
+
+Tourtois is a trusted shell. Every other App runs in its own sandboxed,
+cross-origin frame, but Tourtois runs in the host's own page with your
+permissions there. Pick a shell you trust: it can do anything you can on that
+host.
+
+## Get it
+
+Tourtois installs with the other starter Apps, first of all. On a deployed
+Oyster (see the
+[Oyster quick start](https://github.com/fungi-computer/oyster#quick-start-deploy-your-own-oyster)),
+run:
+
+```sh
+export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
+export OYSTER_OWNER_KEY=<your owner key>
+npx oyster install-apps
+```
+
+The installer clones this repository and the six others, seeds each on your
+Oyster with `git push`, builds them on your Computer and installs them. Sign in
+at `$OYSTER_URL/login` with the owner key and your Oyster opens on Tourtois. Run
+`install-apps` again to update; each App keeps its data.
+
+## Change it
+
+Every installed App is also a template you can fork on your own Oyster,
+including the desktop. Fork Tourtois into a Bonsai repository and clone it with
+ordinary `git`:
+
+```sh
+curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"appId":"app_tourtois","name":"my-tourtois"}' \
+  $OYSTER_URL/apps/bonsai/methods/apps.fork
+git -c http.extraHeader="Authorization: Bearer $OYSTER_OWNER_KEY" \
+  clone $OYSTER_URL/git/bonsai/my-tourtois.git
+```
+
+The reply names your fork's App id and repository. Push your edits, open the
+repository in Bonsai and choose **Settings**, then **Build & install** with that
+App id and your commit as `git:<sha>`. Install the Release at `tourtois` to
+replace the desktop. Building alone never changes what you see; only the install
+does.
+
+To work from GitHub instead, fork this repository and point the installer at
+your forks with `--repositories <base URL>` and `--ref <branch or tag>`. The
+installer reads all seven starter Apps from that base, so fork them under one
+account.
+
+## How a host mounts it
+
+A Tourtois Release ships `shell.js` beside its `index.html`. The host imports
+that module from its own origin and calls
+`mountShell(root, { workbench, storage, methods })`, which renders the desktop
+into the host's page with the host's workbench, Tourtois's own storage and its
+methods. Tourtois's code loads as one lazy chunk behind that module, so no host
+bundles it, and a fork mounts the same way.
+
+Tourtois asks the host to mount each App in that App's own sandboxed frame,
+under its own installation, Release and permissions. Settings pages are supplied
+by the host too: Tourtois offers a page only when the host backs it.
+
+## Agent tools
+
+Agents can arrange your desktop. Through Oyster's MCP endpoint, or at
+`POST $OYSTER_URL/apps/tourtois/methods/<name>` with a key (see
+[Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp)),
+they call:
+
+| Method                                                             | What it does                                                    |
+| ------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `layout.get` / `widgets.available`                                 | Reads the desktop and the live views Apps offer.                |
+| `layout.place` / `layout.move` / `layout.resize` / `layout.remove` | Changes one item on the desktop.                                |
+| `layout.launcher` / `layout.set` / `layout.reset`                  | Pins or hides launcher Apps, replaces the layout, or resets it. |
+
+Each change names the revision it is based on, and a stale revision is refused
+rather than overwriting a newer arrangement. In a connected browser, an agent's
+change shows **Your Agent arranged the desktop** with **Undo** for ten seconds.
+
+## Build and check
+
+Tourtois is React and TypeScript. Windows and tiling come from
+[Maosaico](https://github.com/fungi-computer/maosaico) and the controls from
+[Caps](https://github.com/fungi-computer/caps).
+
+```sh
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+[src/AppWorkbench.tsx](src/AppWorkbench.tsx) composes the App list, windows and
+layout. [src/shell-module.ts](src/shell-module.ts) is the `mountShell` entry,
+[src/platform-controls.tsx](src/platform-controls.tsx) the Settings window, and
+[src/settings-sections.ts](src/settings-sections.ts) the Settings pages a host
+can supply. The agent tools are in [backend/methods.ts](backend/methods.ts), and
+[package.json](package.json) declares what the shell asks of its host.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/AgentMcpServers.d.ts

@@ -0,0 +1,34 @@
+import * as z from "zod";
+/** Every Agent with its connected MCP servers. */
+export declare const agentMcpServersViewSchema: z.ZodObject<{
+    agents: z.ZodArray<z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        servers: z.ZodArray<z.ZodObject<{
+            serverId: z.ZodString;
+            name: z.ZodString;
+            url: z.ZodString;
+            hasBearer: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentMcpServersView = z.output<typeof agentMcpServersViewSchema>;
+/** What the owner submits to connect one server. */
+export type AgentMcpServerDraft = Readonly<{
+    name: string;
+    url: string;
+    bearer: string | null;
+}>;
+/** The host's owner-direct custody for Agent MCP servers. */
+export type AgentMcpServersPort = Readonly<{
+    list(): Promise<AgentMcpServersView>;
+    add(agentId: string, draft: AgentMcpServerDraft): Promise<void>;
+    remove(agentId: string, serverId: string): Promise<void>;
+}>;
+/**
+ * The Connectors settings on a standalone host: connect a remote MCP server to
+ * an Agent. Its tools become `env.mcp.<name>.<tool>()` in that Agent's code.
+ */
+export declare function AgentMcpServers({ port }: {
+    port: AgentMcpServersPort;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/AgentMcpServers.js

@@ -0,0 +1,124 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { SectionHeading } from "@fungi.computer/caps/blocks/section-heading";
+import { ActionRow } from "@fungi.computer/caps/components/action-row";
+import { Badge } from "@fungi.computer/caps/components/badge";
+import { Button } from "@fungi.computer/caps/components/button";
+import { DataList, DataListHeading, DataRow, } from "@fungi.computer/caps/components/data-list";
+import { FormFooter } from "@fungi.computer/caps/components/field";
+import { SchemaForm, field, useSchemaForm } from "@fungi.computer/caps/form";
+import { Sigil } from "@fungi.computer/sigils";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Fragment, useMemo, useState } from "react";
+import * as z from "zod";
+/** One connected MCP server as the host lists it; the token never comes back. */
+const agentMcpServerSchema = z.strictObject({
+    serverId: z.string().min(1),
+    name: z.string().min(1),
+    url: z.string().min(1),
+    hasBearer: z.boolean(),
+});
+/** Every Agent with its connected MCP servers. */
+export const agentMcpServersViewSchema = z.strictObject({
+    agents: z.array(z.strictObject({
+        agentId: z.string().min(1),
+        name: z.string(),
+        servers: z.array(agentMcpServerSchema),
+    })),
+});
+const queryKey = ["tourtois", "agent-mcp-servers"];
+/**
+ * The Connectors settings on a standalone host: connect a remote MCP server to
+ * an Agent. Its tools become `env.mcp.<name>.<tool>()` in that Agent's code.
+ */
+export function AgentMcpServers({ port }) {
+    const client = useQueryClient();
+    const view = useQuery({ queryKey, queryFn: () => port.list() });
+    const refresh = () => client.invalidateQueries({ queryKey });
+    const remove = useMutation({
+        mutationFn: (input) => port.remove(input.agentId, input.serverId),
+        onSuccess: refresh,
+    });
+    const agents = view.data?.agents ?? [];
+    // A fresh form after each connected server, so the token field empties.
+    const [formKey, setFormKey] = useState(0);
+    return (_jsxs("section", { className: "tourtois-settings-content tourtois-connectors", "aria-label": "Connectors", children: [_jsx(SectionHeading, { children: "Connectors" }), _jsxs("p", { className: "tourtois-settings-lede", children: ["Connect a remote MCP server to an Agent. Its tools become", " ", _jsx("code", { children: "env.mcp.<name>" }), " in that Agent's code. A token stays with the Agent and is never shown again."] }), view.isPending ? _jsx("p", { children: "Loading MCP servers\u2026" }) : null, view.isError ? (_jsxs("div", { role: "status", children: [_jsx("p", { children: "MCP servers could not be loaded." }), _jsx(Button, { size: "sm", onClick: () => void view.refetch(), children: "Retry" })] })) : null, view.isSuccess && agents.length === 0 ? (_jsx("p", { children: "Create an Agent first, then connect MCP servers to it." })) : null, agents.length > 0 ? (_jsxs(_Fragment, { children: [_jsx(DataList, { "aria-label": "Agent MCP servers", children: agents.map((agent) => (_jsxs(Fragment, { children: [_jsx(DataListHeading, { children: agent.name }), agent.servers.length === 0 ? (_jsx(DataRow, { children: "No MCP servers." })) : null, agent.servers.map((server) => (_jsx(DataRow, { className: "p-0", children: _jsx(ActionRow, { icon: _jsx(Sigil, { name: "connected" }), label: _jsxs(_Fragment, { children: [server.name, " ", _jsx(Badge, { size: "sm", variant: "quiet", children: "MCP" })] }), description: server.url, trailing: _jsxs(_Fragment, { children: [server.hasBearer ? (_jsx(Badge, { size: "sm", variant: "quiet", children: "Token saved" })) : null, _jsx(Button, { size: "sm", variant: "ghost", "aria-label": `Remove ${server.name} from ${agent.name}`, disabled: remove.isPending, onClick: () => {
+                                                        remove.mutate({
+                                                            agentId: agent.agentId,
+                                                            serverId: server.serverId,
+                                                        });
+                                                    }, children: "Remove" })] }) }) }, server.serverId)))] }, agent.agentId))) }), remove.isError ? (_jsx("p", { role: "alert", children: "The MCP server could not be removed." })) : null, _jsx(AddMcpServer, { agents: agents, onAdd: async (agentId, draft) => {
+                            await port.add(agentId, draft);
+                            await refresh();
+                            setFormKey((current) => current + 1);
+                        } }, formKey)] })) : null] }));
+}
+function AddMcpServer({ agents, onAdd, }) {
+    const schema = useMemo(() => z.object({
+        agentId: z.string().meta(field({
+            label: "Agent",
+            kind: "select",
+            options: Object.fromEntries(agents.map((agent) => [agent.agentId, agent.name])),
+        })),
+        name: z
+            .string()
+            .regex(/^[a-z][a-z0-9_]{0,31}$/u, "Lowercase letters, digits and _, starting with a letter")
+            .meta(field({
+            label: "Name",
+            help: "The Agent calls its tools as env.mcp.<name>.",
+            maxLength: 32,
+            placeholder: "linear",
+        })),
+        url: z
+            .string()
+            .max(2_048)
+            .refine((value) => URL.canParse(value) && new URL(value).protocol === "https:", "Use the server's https:// address")
+            .meta(field({
+            label: "Server URL",
+            kind: "url",
+            placeholder: "https://mcp.example.com/mcp",
+        })),
+        bearer: z
+            .string()
+            .max(4_096)
+            .meta(field({
+            label: "Bearer token",
+            help: "Only if the server asks for one.",
+            optional: true,
+            kind: "secret",
+        })),
+    }), [agents]);
+    const add = useMutation({
+        mutationFn: (input) => onAdd(input.agentId, input.draft),
+    });
+    const model = useSchemaForm({
+        schema,
+        defaultValues: {
+            agentId: agents[0]?.agentId ?? "",
+            name: "",
+            url: "",
+            bearer: "",
+        },
+        onSubmit: async (value) => {
+            try {
+                await add.mutateAsync({
+                    agentId: value.agentId,
+                    draft: {
+                        name: value.name,
+                        url: value.url,
+                        bearer: value.bearer.length === 0 ? null : value.bearer,
+                    },
+                });
+                return { kind: "saved" };
+            }
+            catch (cause) {
+                return {
+                    kind: "refused",
+                    error: cause instanceof Error
+                        ? cause.message
+                        : "The MCP server could not be connected.",
+                };
+            }
+        },
+    });
+    return (_jsx(SchemaForm, { model: model, "aria-label": "Add MCP server", disabled: add.isPending, footer: _jsx(FormFooter, { error: model.error, children: _jsx(Button, { type: "submit", children: add.isPending ? "Connecting…" : "Add MCP server" }) }) }));
+}

package/dist/AppAccessConsent.d.ts

@@ -0,0 +1,23 @@
+import type { AgentAccessOperation, AppPermissionOutcome, ComputerAccessOperation } from "@fungi.computer/agar";
+import type { AppAgentPermission, AppComputerPermission } from "@fungi.computer/oyster/shell/app-directory";
+export declare const consentableAgentOperations: (requested: readonly AgentAccessOperation[], declared: readonly string[]) => readonly AgentAccessOperation[];
+export declare const consentableComputerOperations: (requested: readonly ComputerAccessOperation[], declared: readonly string[]) => readonly ComputerAccessOperation[];
+/** The all-Team-Agents grant that adds `offered` to the current policy. */
+export declare function consentedAgentPermission(current: AppAgentPermission, offered: readonly AgentAccessOperation[]): AppAgentPermission | "covered" | "customize";
+/**
+ * The all-Team-Computers grant that adds `offered`. An empty selection is no
+ * access; a real Computer selection is the owner's choice and never widened.
+ */
+export declare function consentedComputerPermission(current: AppComputerPermission | null, offered: readonly ComputerAccessOperation[]): AppComputerPermission | "covered" | "customize";
+export type AppAccessRequest = Readonly<{
+    appName: string;
+    agents: readonly AgentAccessOperation[];
+    computers: readonly ComputerAccessOperation[];
+    /** Save the grant through the owner's own authority; resolves false when it failed. */
+    allow: () => Promise<boolean>;
+    settle: (outcome: AppPermissionOutcome) => void;
+}>;
+/** One-click host consent for the rights a default App declared. */
+export declare function AppAccessConsent({ request, }: {
+    request: AppAccessRequest | null;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/AppAccessConsent.js

@@ -0,0 +1,122 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "@fungi.computer/caps/components/button";
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogTitle, } from "@fungi.computer/caps/components/dialog";
+import { WindowFrame, WindowHeader, } from "@fungi.computer/caps/components/window";
+import { useState } from "react";
+const directoryOperations = ["agent.list"];
+const sessionOperations = ["agent.read", "agent.send", "agent.manage"];
+const agentOperations = [
+    "agent.list",
+    "agent.manage",
+    "agent.read",
+    "agent.send",
+];
+const computerOperations = [
+    "computer.list",
+    "computer.readFile",
+    "computer.writeFile",
+    "computer.execute",
+];
+/** What the trusted host may offer: the request bounded by the declared ceiling. */
+function consentableOperations(known, requested, declared) {
+    return known.filter((operation) => requested.includes(operation) && declared.includes(operation));
+}
+export const consentableAgentOperations = (requested, declared) => consentableOperations(agentOperations, requested, declared);
+export const consentableComputerOperations = (requested, declared) => consentableOperations(computerOperations, requested, declared);
+/** The all-Team-Agents grant that adds `offered` to the current policy. */
+export function consentedAgentPermission(current, offered) {
+    if (current.kind === "selected-agents")
+        return "customize";
+    const currentOperations = [
+        ...current.directoryOperations,
+        ...current.sessionOperations,
+    ];
+    if (offered.every((operation) => currentOperations.includes(operation)))
+        return "covered";
+    const granted = new Set([...currentOperations, ...offered]);
+    return {
+        kind: "all-team-agents",
+        directoryOperations: directoryOperations.filter((operation) => granted.has(operation)),
+        sessionOperations: sessionOperations.filter((operation) => granted.has(operation)),
+    };
+}
+/**
+ * The all-Team-Computers grant that adds `offered`. An empty selection is no
+ * access; a real Computer selection is the owner's choice and never widened.
+ */
+export function consentedComputerPermission(current, offered) {
+    if (current?.kind === "selected-computers" && current.computers.length > 0)
+        return "customize";
+    const currentOperations = current?.kind === "all-team-computers" ? current.operations : [];
+    if (offered.every((operation) => currentOperations.includes(operation)))
+        return "covered";
+    const granted = new Set([...currentOperations, ...offered]);
+    return {
+        kind: "all-team-computers",
+        operations: computerOperations.filter((operation) => granted.has(operation)),
+    };
+}
+/** Sentence variants following "<App> can" in the consent description. */
+const rightNames = {
+    "agent.list": "see your Agents",
+    "agent.manage": "create and manage Agents and their sessions",
+    "agent.read": "read their conversations",
+    "agent.send": "send messages",
+    "computer.list": "see your Computers",
+    "computer.readFile": "read their files",
+    "computer.writeFile": "change their files",
+    "computer.execute": "run commands on them",
+};
+const describe = (offered) => {
+    const rights = [...agentOperations, ...computerOperations]
+        .filter((operation) => offered.includes(operation))
+        .map((operation) => rightNames[operation]);
+    const last = rights.at(-1) ?? "";
+    return rights.length < 2
+        ? last
+        : `${rights.slice(0, -1).join(", ")} and ${last}`;
+};
+const resources = (request, agent, computer) => [
+    request.agents.length > 0 ? agent : null,
+    request.computers.length > 0 ? computer : null,
+]
+    .filter((resource) => resource !== null)
+    .join(" and ");
+/** One-click host consent for the rights a default App declared. */
+export function AppAccessConsent({ request, }) {
+    const [saving, setSaving] = useState(false);
+    const [failed, setFailed] = useState(false);
+    const settle = (outcome) => {
+        setSaving(false);
+        setFailed(false);
+        request?.settle(outcome);
+    };
+    return (_jsx(Dialog, { open: request !== null, onOpenChange: (next) => {
+            if (!next && !saving)
+                settle("declined");
+        }, children: _jsxs(DialogContent, { render: _jsx(WindowFrame, { floating: true }), keepMounted: false, className: "tourtois-app-consent", children: [_jsx(WindowHeader, { title: "App access" }), _jsxs("div", { className: "tourtois-app-consent-body", children: [_jsx(DialogTitle, { children: request
+                                ? `Let ${request.appName} work with your ${resources(request, "Agents", "Computers")}?`
+                                : "" }), _jsx(DialogDescription, { children: request
+                                ? `${request.appName} can ${describe([...request.agents, ...request.computers])} for every ${resources(request, "Agent", "Computer")} in this Oyster. You can change this later in System Settings.`
+                                : "" }), failed ? (_jsx("p", { role: "alert", children: "Access could not be saved. Try again." })) : null, _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "ghost", disabled: saving, onClick: () => {
+                                        settle("customize");
+                                    }, children: "Customize\u2026" }), _jsx(Button, { variant: "ghost", disabled: saving, onClick: () => {
+                                        settle("declined");
+                                    }, children: "Not now" }), _jsx(Button, { disabled: saving || request === null, onClick: () => {
+                                        if (request === null)
+                                            return;
+                                        setSaving(true);
+                                        setFailed(false);
+                                        void request.allow().then((saved) => {
+                                            if (saved)
+                                                settle("granted");
+                                            else {
+                                                setSaving(false);
+                                                setFailed(true);
+                                            }
+                                        }, () => {
+                                            setSaving(false);
+                                            setFailed(true);
+                                        });
+                                    }, children: saving ? "Allowing…" : "Allow" })] })] })] }) }));
+}

package/dist/AppCallPermissions.d.ts

@@ -0,0 +1,9 @@
+import type { AppDeclaration } from "@fungi.computer/puffball/app";
+/** The declared deputy ceiling, shown identically on both hosts; this grants nothing. */
+export declare function AppCallPermissions({ calls, apps, }: {
+    calls: AppDeclaration["calls"];
+    apps: readonly {
+        appId: string;
+        displayName?: string | undefined;
+    }[];
+}): React.JSX.Element | null;

package/dist/AppCallPermissions.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DataList, DataListHeading, DataRow, } from "@fungi.computer/caps/components/data-list";
+const methodLabels = new Map([
+    ["files.tree", "browse files"],
+    ["files.list", "list files"],
+    ["files.read", "read files"],
+    ["commits.list", "read commits"],
+    ["rebuildCopies", "refresh file views"],
+    ["files.save", "save files"],
+    ["files.sync", "sync files"],
+    ["files.discard", "discard edits"],
+]);
+/** The declared deputy ceiling, shown identically on both hosts; this grants nothing. */
+export function AppCallPermissions({ calls, apps, }) {
+    if (!calls?.length)
+        return null;
+    return (_jsxs("section", { "aria-label": "Calls to other Apps", children: [_jsx(DataListHeading, { level: 3, children: "Other Apps" }), _jsx(DataList, { density: "compact", children: calls.map((call) => (_jsx(DataRow, { children: _jsxs("span", { children: ["Can use", " ", apps.find((app) => app.appId === call.appId)?.displayName ??
+                                call.appId, ":", " ", call.methods
+                                .map((method) => methodLabels.get(method) ?? method)
+                                .join(", ")] }) }, call.appId))) }), _jsx("p", { className: "mt-1 text-xs", children: "Calls use your permissions in the other App. Renamed target methods need approval again." })] }));
+}

package/dist/AppDesktopSettings.d.ts

@@ -0,0 +1,11 @@
+import type { WorkbenchDesktopSettings } from "@fungi.computer/oyster/shell/workbench";
+import type { AppDirectoryEntry, AppDirectoryGill } from "@fungi.computer/oyster/shell/app-directory";
+export type AppDesktopSettingsApp = Pick<AppDirectoryEntry, "surfaceId" | "availability"> & Readonly<{
+    gills: readonly AppDirectoryGill[];
+}>;
+/** Suggestions only: the member chooses, then the admitted dashboard arranges. */
+export declare function AppDesktopSettings({ app, desktop, consentReadyAt, }: {
+    app: AppDesktopSettingsApp;
+    desktop: WorkbenchDesktopSettings;
+    consentReadyAt?: number;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/AppDesktopSettings.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DataListHeading } from "@fungi.computer/caps/components/data-list";
+import { useEffect, useRef, useState } from "react";
+import { AppError } from "@fungi.computer/agar";
+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";
+const sizeLabels = { S: "Small", M: "Medium", L: "Large" };
+function GillOption({ app, gill, desktop, consentReadyAt, }) {
+    const sizes = gill.desktop?.sizes ?? [];
+    const [size, setSize] = useState(sizes[0] ?? "S");
+    const [saved, setSaved] = useState(null);
+    const [pending, setPending] = useState(false);
+    const busy = useRef(false);
+    const [consentReady, setConsentReady] = useState(Date.now() >= consentReadyAt);
+    useEffect(() => {
+        setConsentReady(Date.now() >= consentReadyAt);
+        const timer = window.setTimeout(() => {
+            setConsentReady(true);
+        }, Math.max(0, consentReadyAt - Date.now()));
+        return () => {
+            window.clearTimeout(timer);
+        };
+    }, [consentReadyAt]);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let retired = false;
+        setSaved(null);
+        void Promise.resolve()
+            .then(() => desktop.readGill({ surfaceId: app.surfaceId, gillId: gill.id }))
+            .then((value) => {
+            if (!retired)
+                setSaved(value);
+        })
+            .catch((cause) => {
+            console.error("Desktop Gill saved state could not be read", {
+                surfaceId: app.surfaceId,
+                gillId: gill.id,
+                cause,
+            });
+            if (!retired)
+                setError("Your desktop could not be read. Reopen Settings to try again.");
+            return { kind: "failed", cause };
+        });
+        return () => {
+            retired = true;
+        };
+    }, [app.surfaceId, gill.id, desktop]);
+    const onDesktop = !!saved?.length;
+    const change = async () => {
+        if (busy.current || saved === null || Date.now() < consentReadyAt)
+            return { kind: "busy" };
+        busy.current = true;
+        setPending(true);
+        setError(null);
+        const selection = { surfaceId: app.surfaceId, gillId: gill.id };
+        try {
+            if (onDesktop)
+                await desktop.removeGill(selection);
+            else
+                await desktop.addGill({ ...selection, size });
+            setSaved(await desktop.readGill(selection));
+            return { kind: "confirmed" };
+        }
+        catch (cause) {
+            console.error("Desktop Gill member change failed", {
+                ...selection,
+                cause,
+            });
+            setError(cause instanceof AppError
+                ? cause.message
+                : "The widget could not be changed. Reopen Settings to try again.");
+            // A refusal may mean another tab changed the saved layout. Never keep an optimistic membership flag.
+            setSaved(null);
+            return { kind: "failed", cause };
+        }
+        finally {
+            busy.current = false;
+            setPending(false);
+        }
+    };
+    return (_jsxs(DataRow, { style: { gridTemplateColumns: "minmax(0, 1fr)" }, children: [_jsxs("div", { children: [_jsx("strong", { children: gill.title }), _jsxs("p", { children: [saved === null && !error && "Reading your desktop…", saved !== null && onDesktop && (_jsxs("span", { role: "status", children: ["On your desktop \u00B7", " ", saved.map((value) => sizeLabels[value]).join(", ")] })), saved !== null &&
+                                !onDesktop &&
+                                "Choose a size, then add this widget to your desktop.", error ? _jsx("span", { role: "alert", children: error }) : null] })] }), _jsxs("div", { className: "flex flex-wrap items-center gap-2", style: { gridRow: 2, gridColumn: "1 / -1" }, children: [!onDesktop ? (_jsx("div", { style: { width: "7rem", flex: "0 0 auto" }, children: _jsx(Select, { "aria-label": `Size for ${gill.title}`, value: size, disabled: pending || saved === null || !consentReady, onChange: (event) => {
+                                const next = sizes.find((value) => value === event.currentTarget.value);
+                                if (next)
+                                    setSize(next);
+                            }, children: sizes.map((value) => (_jsx("option", { value: value, children: sizeLabels[value] }, value))) }) })) : null, _jsx(Button, { size: "sm", variant: "secondary", loading: pending, disabled: pending || saved === null || !consentReady, onClick: (event) => {
+                            if (event.detail > 1)
+                                return;
+                            void change();
+                        }, children: onDesktop ? "Remove from desktop" : "Add to desktop" })] })] }));
+}
+/** Suggestions only: the member chooses, then the admitted dashboard arranges. */
+export function AppDesktopSettings({ app, desktop, consentReadyAt = 0, }) {
+    const gills = app.availability === "available"
+        ? app.gills.filter((gill) => gill.desktop)
+        : [];
+    return (_jsxs("section", { "aria-label": "Desktop widgets", children: [_jsx(DataListHeading, { level: 3, children: "Desktop widgets" }), _jsx("p", { children: "Add this App\u2019s widgets to your personal desktop. Your Team default stays unchanged." }), gills.length ? (_jsx(DataList, { "aria-label": "Available desktop widgets", children: gills.map((gill) => (_jsx(GillOption, { app: app, gill: gill, desktop: desktop, consentReadyAt: consentReadyAt }, gill.id))) })) : (_jsx("p", { children: app.availability === "available"
+                    ? "This App offers no desktop widgets."
+                    : "This App is unavailable. Its widgets cannot be added." }))] }));
+}

package/dist/AppPane.d.ts

@@ -0,0 +1,37 @@
+import { type AppStatusAction } from "@fungi.computer/agar";
+import { createAppWindowManager, type AppWindowProjection } from "./app-windows.js";
+import { type AppDirectoryApp } from "./app-launch.js";
+/** The focused window's App-level settings; its Computer lives in its status bar. */
+export declare function FocusedWindowControls({ app, onOpenSettings, onOpenPermissions, projection, }: {
+    app: AppDirectoryApp | undefined;
+    onOpenSettings: () => void;
+    onOpenPermissions: () => void;
+    projection: AppWindowProjection;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function AppPane({ projection, icon, manager, onError, index, focusWindow, afterHide, onBack, onSelectComputer, }: {
+    projection: AppWindowProjection;
+    icon: string | null | undefined;
+    manager: ReturnType<typeof createAppWindowManager>;
+    onError: (message: string) => void;
+    index: number;
+    focusWindow: (id: string) => void;
+    afterHide: (id: string) => void;
+    onBack: (id: string) => void;
+    /** The person chose another of this window's offered Computers. */
+    onSelectComputer: (windowId: string, computerId: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * One window's status bar, owned by the shell like its title bar: the
+ * window's Computer first (only the person changes it, here), then the items
+ * the App declared as data. The shell renders every item with Caps pieces and
+ * hands the person's use back to the App. A window with neither has no bar.
+ */
+export declare function WindowStatusBar({ projection, onSelectComputer, onAction, surface, computerPickerOpen, onComputerPickerOpenChange, }: {
+    projection: AppWindowProjection;
+    onSelectComputer: (computerId: string) => void;
+    onAction: (action: AppStatusAction) => void;
+    /** The App's own surface, which UI opened from the bar is placed against. */
+    surface?: () => HTMLElement | null;
+    computerPickerOpen?: boolean;
+    onComputerPickerOpenChange?: (open: boolean) => void;
+}): import("react/jsx-runtime").JSX.Element | null;