@loopbacktools/app 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bison Labs Limited
+
+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,85 @@
-# Temporary Holding Version
+# @loopbacktools/app
 
-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.
+The [Loopback](https://github.com/LoopBackTools/loopback) app: the inbox, routed by path, with its
+header, the page on connecting an agent, and the reload when Loopback is updated under it. Every
+Loopback deployment renders the same app and supplies only what differs: who is signed in, which
+workspaces they can open, and any pages of its own. The deployment this repository ships,
+`apps/loopback`, is one short entry file built on it.
+
+```sh
+pnpm add @loopbacktools/app @loopbacktools/inbox @loopbacktools/sdk @cloudflare/kumo @effect/atom-react effect react react-dom react-router
+```
+
+## Composing it
+
+```tsx
+import { RegistryProvider } from "@effect/atom-react";
+import { createLoopbackApp, followSystemTheme } from "@loopbacktools/app";
+import { make } from "@loopbacktools/sdk";
+import { useMemo } from "react";
+import { createRoot } from "react-dom/client";
+
+const App = createLoopbackApp({
+	session: {
+		// Who is signed in: undefined while loading, null for nobody.
+		useSignedIn: () => {
+			const user = useYourSession();
+			return user === undefined ? undefined : user === null ? null : { name: user.email, signOut };
+		},
+		// Shown at /sign-in; once someone is signed in, the app sends them on to `next`.
+		SignIn: ({ next }) => <YourSignIn returnTo={next} />,
+	},
+	workspaces: {
+		useList: () => useYourWorkspaces(), // [{ id, name }], or undefined while loading
+		useClient: (workspace) =>
+			useMemo(
+				() => make({ baseUrl: location.origin, token: () => tokenFor(workspace) }),
+				[workspace],
+			),
+		create: async () => createYourWorkspace(), // optional: the new one's id
+	},
+	extensions: {
+		pages: [{ path: "/account", Page: Account, signedIn: true }],
+		accountMenu: [{ label: "Your account", to: "/account" }],
+		workspaceMenu: (workspace) => [{ label: "Members", to: `/w/${workspace}/members` }],
+		Banner: ({ workspace }) => <YourBanner workspace={workspace} />,
+	},
+});
+
+followSystemTheme();
+createRoot(document.getElementById("root")!).render(
+	<RegistryProvider>
+		<App />
+	</RegistryProvider>,
+);
+```
+
+Every port is a React hook or a component, so a deployment reads its session and workspaces however
+it keeps them. The app imports no sign-in library; a test keeps it that way.
+
+## What it serves
+
+- `/w/:workspace` and `/w/:workspace/asks/:id`: a workspace's inbox, through the client
+  `useClient` gives for it. The server's links to asks are of this form.
+- `/w/:workspace/connect`: how to connect an agent. Whether agents sign in with OAuth or send a token
+  comes from the server itself.
+- `/sign-in`: the deployment's own sign-in page.
+- `/`: the workspace the person prefers (`usePreferred`), or their first. An old link, `/#/<id>`, is
+  followed to that ask.
+- The deployment's pages. They stand alone, without the inbox's header; `Page` and `Section` give
+  them the app's look.
+
+The workspace menu appears where there is more than one workspace, a way to make one, or items of the
+deployment's own. With no account items and no name to show, signing out is a button of its own, and
+with nothing to sign out of, there is none.
+
+## Styling
+
+Beside the inbox's, in your stylesheet:
+
+```css
+@import "@loopbacktools/inbox/styles.css";
+@import "@loopbacktools/app/styles.css";
+```
+
+MIT licensed.

package/dist/src/app.d.ts

@@ -0,0 +1,8 @@
+import { type ComponentType } from "react";
+import type { LoopbackAppOptions } from "./ports.ts";
+/**
+ * The Loopback app, for a deployment to render: its inbox, a page on connecting agents, and the
+ * deployment's own pages, routed by path. Render it inside a `RegistryProvider`, as the inbox needs.
+ * The deployment's hooks are bound here, once: the app's pages call the same ones on every render.
+ */
+export declare const createLoopbackApp: (options: LoopbackAppOptions) => ComponentType;

package/dist/src/app.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, ClipboardText, Empty, LinkButton, LinkProvider, Loader, Text, } from "@cloudflare/kumo";
+import { useAtomValue } from "@effect/atom-react";
+import { Inbox, InboxProvider } from "@loopbacktools/inbox";
+import { Plus, Tray } from "@phosphor-icons/react";
+import { AsyncResult, Atom } from "effect/reactivity";
+import { createContext, forwardRef, use, useCallback, } from "react";
+import { BrowserRouter, Link, Navigate, Route, Routes, useLocation, useNavigate, useParams, useSearchParams, } from "react-router";
+import { Header } from "./header.js";
+import { Page, Section } from "./page.js";
+import { askInOldLink, safeNext, workspacePath } from "./paths.js";
+function Waiting() {
+    return (_jsx("main", { className: "flex h-full items-center justify-center", children: _jsx(Loader, {}) }));
+}
+/** Kumo's links, followed by the app's router rather than by loading the page again. */
+const RouterLink = forwardRef(({ href, to, ...rest }, ref) => _jsx(Link, { ref: ref, to: href ?? to ?? "", ...rest }));
+const SignedInContext = createContext(null);
+/** Who is signed in, for a page behind `SignedIn`. */
+const useSignedInHere = () => {
+    const signedIn = use(SignedInContext);
+    if (signedIn === null)
+        throw new Error("Only a page for someone signed in knows who they are.");
+    return signedIn;
+};
+/** A workspace that isn't the person's: they may have been removed, or the link is wrong. */
+function NotTheirs() {
+    return (_jsx("main", { className: "flex h-full items-center justify-center p-4", children: _jsx(Empty, { icon: _jsx(Tray, { size: 32 }), title: "Not one of your workspaces", description: "You may have been removed from it, or the link is wrong.", contents: _jsx(LinkButton, { href: "/", variant: "secondary", children: "Go to your inbox" }) }) }));
+}
+/** How agents sign in to a client's deployment, as its server says. */
+const agentSignInAtom = Atom.family((client) => Atom.make(client.agentSignIn));
+/** How to connect an agent to a workspace, as the server says its agents sign in. */
+function Connect({ workspace, client, }) {
+    const signIn = useAtomValue(agentSignInAtom(client));
+    if (AsyncResult.isInitial(signIn))
+        return _jsx(Waiting, {});
+    const mcp = `${window.location.origin}/mcp`;
+    const oauth = AsyncResult.isSuccess(signIn) && signIn.value === "oauth";
+    return (_jsxs(Page, { back: { to: workspacePath(workspace), label: "Back to the inbox" }, title: "Connect an agent", description: oauth
+            ? "Agents connect to Loopback over MCP and sign in as you. When one connects, you pick the workspace it asks in."
+            : "Agents connect to Loopback over MCP, sending this deployment's token.", children: [_jsxs(Section, { title: "Claude Code", children: [_jsx(ClipboardText, { text: oauth
+                            ? `claude mcp add --transport http loopback ${mcp}`
+                            : `claude mcp add --transport http loopback ${mcp} --header "Authorization: Bearer $LOOPBACK_TOKEN"` }), _jsx(Text, { variant: "secondary", size: "sm", children: oauth
+                            ? "Then run /mcp in Claude Code and sign in when it asks."
+                            : "With the token in LOOPBACK_TOKEN, in the shell you run it from." })] }), _jsxs(Section, { title: "Any other MCP client", children: [_jsx(ClipboardText, { text: mcp }), _jsx(Text, { variant: "secondary", size: "sm", children: oauth
+                            ? "Add it as a remote server over streamable HTTP. It signs in with OAuth."
+                            : "Add it as a remote server over streamable HTTP, with the header Authorization: Bearer and the token." })] })] }));
+}
+const noPreference = () => undefined;
+/**
+ * The Loopback app, for a deployment to render: its inbox, a page on connecting agents, and the
+ * deployment's own pages, routed by path. Render it inside a `RegistryProvider`, as the inbox needs.
+ * The deployment's hooks are bound here, once: the app's pages call the same ones on every render.
+ */
+export const createLoopbackApp = (options) => {
+    const { SignIn } = options.session;
+    const useSignedIn = options.session.useSignedIn;
+    const useList = options.workspaces.useList;
+    const usePreferred = options.workspaces.usePreferred ?? noPreference;
+    const useClient = options.workspaces.useClient;
+    const { create } = options.workspaces;
+    const { pages = [], workspaceMenu, accountMenu = [], Banner } = options.extensions ?? {};
+    /** A page for someone signed in; anyone else is sent to sign in, and brought back after. */
+    function SignedIn({ children }) {
+        const signedIn = useSignedIn();
+        const location = useLocation();
+        if (signedIn === undefined)
+            return _jsx(Waiting, {});
+        if (signedIn === null) {
+            const next = `${location.pathname}${location.search}${location.hash}`;
+            return _jsx(Navigate, { to: `/sign-in?next=${encodeURIComponent(next)}`, replace: true });
+        }
+        return _jsx(SignedInContext, { value: signedIn, children: children });
+    }
+    /** The deployment's sign-in page, until the person is signed in; then where they were going. */
+    function SignInPage() {
+        const signedIn = useSignedIn();
+        const [search] = useSearchParams();
+        const next = safeNext(search.get("next"));
+        if (signedIn === undefined)
+            return _jsx(Waiting, {});
+        if (signedIn !== null)
+            return _jsx(Navigate, { to: next, replace: true });
+        return _jsx(SignIn, { next: next });
+    }
+    /**
+     * The app's front door: the workspace the person prefers, or their first, and the ask an old link
+     * names in it. Someone in no workspace is offered a new one, where the deployment makes them.
+     */
+    function Home() {
+        const navigate = useNavigate();
+        const location = useLocation();
+        const list = useList();
+        const preferred = usePreferred();
+        if (list === undefined)
+            return _jsx(Waiting, {});
+        const workspace = list.find((candidate) => candidate.id === preferred)?.id ?? list[0]?.id;
+        if (workspace !== undefined) {
+            return _jsx(Navigate, { to: workspacePath(workspace, askInOldLink(location.hash)), replace: true });
+        }
+        return (_jsx("main", { className: "flex h-full items-center justify-center p-4", children: _jsx(Empty, { icon: _jsx(Tray, { size: 32 }), title: "You're not in a workspace", description: create === undefined
+                    ? "Ask someone to invite you to theirs."
+                    : "Make one to connect your agents to, or ask someone to invite you to theirs.", contents: create === undefined ? undefined : (_jsx(Button, { variant: "primary", icon: _jsx(Plus, {}), onClick: () => void create().then(async (id) => {
+                        if (id !== undefined)
+                            await navigate(workspacePath(id));
+                    }), children: "New workspace" })) }) }));
+    }
+    /**
+     * One workspace's inbox, live, through the client the deployment gives for it. Another workspace
+     * is another client, so switching reconnects to that one.
+     */
+    function WorkspaceInbox({ workspace, list, }) {
+        const signedIn = useSignedInHere();
+        const client = useClient(workspace);
+        const { askId } = useParams();
+        const navigate = useNavigate();
+        const onSelect = useCallback((id) => void navigate(workspacePath(workspace, id ?? undefined)), [navigate, workspace]);
+        const hrefFor = useCallback((id) => workspacePath(workspace, id), [workspace]);
+        return (_jsx(InboxProvider, { client: client, children: _jsxs("div", { className: "flex h-full flex-col", children: [_jsx(Header, { workspace: workspace, signedIn: signedIn, workspaces: list, workspaceItems: workspaceMenu?.(workspace) ?? [], accountItems: accountMenu, create: create }), Banner === undefined ? null : _jsx(Banner, { workspace: workspace }), _jsx(Inbox, { selectedId: askId ?? null, onSelect: onSelect, hrefFor: hrefFor })] }) }));
+    }
+    function ConnectPage({ workspace }) {
+        return _jsx(Connect, { workspace: workspace, client: useClient(workspace) });
+    }
+    /** A page of one of the person's workspaces, or a page saying it isn't one of theirs. */
+    function Theirs({ page }) {
+        const { workspace = "" } = useParams();
+        const list = useList();
+        if (list === undefined)
+            return _jsx(Waiting, {});
+        if (!list.some((candidate) => candidate.id === workspace))
+            return _jsx(NotTheirs, {});
+        return page === "inbox" ? (_jsx(WorkspaceInbox, { workspace: workspace, list: list })) : (_jsx(ConnectPage, { workspace: workspace }));
+    }
+    return function LoopbackApp() {
+        return (_jsx(BrowserRouter, { children: _jsx(LinkProvider, { component: RouterLink, children: _jsxs(Routes, { children: [_jsx(Route, { path: "/sign-in", element: _jsx(SignInPage, {}) }), _jsx(Route, { path: "/w/:workspace", element: _jsx(SignedIn, { children: _jsx(Theirs, { page: "inbox" }) }) }), _jsx(Route, { path: "/w/:workspace/asks/:askId", element: _jsx(SignedIn, { children: _jsx(Theirs, { page: "inbox" }) }) }), _jsx(Route, { path: "/w/:workspace/connect", element: _jsx(SignedIn, { children: _jsx(Theirs, { page: "connect" }) }) }), pages.map(({ path, Page: Shown, signedIn }) => (_jsx(Route, { path: path, element: signedIn ? (_jsx(SignedIn, { children: _jsx(Shown, {}) })) : (_jsx(Shown, {})) }, path))), _jsx(Route, { path: "*", element: _jsx(SignedIn, { children: _jsx(Home, {}) }) })] }) }) }));
+    };
+};

package/dist/src/header.d.ts

@@ -0,0 +1,11 @@
+import type { MenuItem, SignedIn, WorkspaceSummary } from "./ports.ts";
+/** The bar above a workspace's inbox. */
+export declare function Header({ workspace, signedIn, workspaces, workspaceItems, accountItems, create, }: {
+    readonly workspace: string;
+    readonly signedIn: SignedIn;
+    /** Every workspace the person can open. */
+    readonly workspaces: readonly WorkspaceSummary[];
+    readonly workspaceItems: readonly MenuItem[];
+    readonly accountItems: readonly MenuItem[];
+    readonly create: (() => Promise<string | undefined>) | undefined;
+}): import("react").JSX.Element;

package/dist/src/header.js

@@ -0,0 +1,67 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, DropdownMenu, LinkButton, Text } from "@cloudflare/kumo";
+import { useAttention, useInbox, useNotifications } from "@loopbacktools/inbox";
+import { Bell, BellSlash, CaretDown, Check, Plugs, Plus, SignOut } from "@phosphor-icons/react";
+import { useCallback } from "react";
+import { Link, useNavigate } from "react-router";
+import { connectPath, workspacePath } from "./paths.js";
+const CONNECTION = {
+    connecting: { label: "Connecting", tone: "bg-kumo-line" },
+    live: { label: "Live", tone: "bg-kumo-success" },
+    reconnecting: { label: "Reconnecting", tone: "bg-kumo-warning" },
+};
+/** Goes where a menu item goes, or does what it does. */
+const useChoose = () => {
+    const navigate = useNavigate();
+    return (item) => {
+        if (item.to !== undefined)
+            void navigate(item.to);
+        void item.onSelect?.();
+    };
+};
+/**
+ * The workspace open, and the way to the others: only where there is more than one, or a way to make
+ * one, or the deployment has items of its own for it.
+ */
+function WorkspaceMenu({ workspace, list, items, create, }) {
+    const navigate = useNavigate();
+    const choose = useChoose();
+    if (list.length < 2 && create === undefined && items.length === 0)
+        return null;
+    const current = list.find((candidate) => candidate.id === workspace);
+    const make = async () => {
+        const id = await create?.();
+        if (id !== undefined)
+            await navigate(workspacePath(id));
+    };
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenu.Trigger, { children: _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(CaretDown, {}), children: current?.name ?? "Workspace" }) }), _jsxs(DropdownMenu.Content, { children: [list.map((candidate) => (_jsx(DropdownMenu.Item, { icon: candidate.id === workspace ? Check : undefined, onClick: () => void navigate(workspacePath(candidate.id)), children: candidate.name }, candidate.id))), items.length > 0 || create !== undefined ? _jsx(DropdownMenu.Separator, {}) : null, items.map((item) => (_jsx(DropdownMenu.Item, { icon: item.icon, onClick: () => choose(item), children: item.label }, item.label))), create === undefined ? null : (_jsx(DropdownMenu.Item, { icon: Plus, onClick: () => void make(), children: "New workspace" }))] })] }));
+}
+/**
+ * The person signed in: a menu of the deployment's items and signing out. With no items and no name
+ * to show, signing out is a button of its own, and with nothing to sign out of either, there is none.
+ */
+function AccountMenu({ signedIn, items, }) {
+    const navigate = useNavigate();
+    const choose = useChoose();
+    const { name, signOut } = signedIn;
+    const leave = signOut === undefined
+        ? undefined
+        : async () => {
+            await signOut();
+            await navigate("/");
+        };
+    if (items.length === 0 && name === undefined) {
+        return leave === undefined ? null : (_jsx(Button, { variant: "ghost", size: "sm", onClick: () => void leave(), children: "Sign out" }));
+    }
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenu.Trigger, { children: _jsx(Button, { variant: "ghost", size: "sm", children: name ?? "Account" }) }), _jsxs(DropdownMenu.Content, { children: [items.map((item) => (_jsx(DropdownMenu.Item, { icon: item.icon, onClick: () => choose(item), children: item.label }, item.label))), leave === undefined ? null : (_jsxs(_Fragment, { children: [items.length > 0 ? _jsx(DropdownMenu.Separator, {}) : null, _jsx(DropdownMenu.Item, { icon: SignOut, onClick: () => void leave(), children: "Sign out" })] }))] })] }));
+}
+/** The bar above a workspace's inbox. */
+export function Header({ workspace, signedIn, workspaces, workspaceItems, accountItems, create, }) {
+    const navigate = useNavigate();
+    const inbox = useInbox();
+    const notifications = useNotifications();
+    const open = useCallback((askId) => void navigate(workspacePath(workspace, askId)), [navigate, workspace]);
+    useAttention(inbox, notifications.enabled, open);
+    const connection = CONNECTION[inbox.status];
+    return (_jsxs("header", { className: "flex items-center gap-2 border-b border-kumo-line bg-kumo-base px-4 py-2", children: [_jsxs(Link, { to: workspacePath(workspace), className: "flex items-center gap-2", children: [_jsx("img", { src: "/favicon.svg", alt: "", className: "size-6" }), _jsx(Text, { bold: true, children: "Loopback" })] }), _jsx(WorkspaceMenu, { workspace: workspace, list: workspaces, items: workspaceItems, create: create }), _jsxs("span", { className: "inline-flex items-center gap-1.5 text-xs text-kumo-subtle", children: [_jsx("span", { className: `size-2 rounded-full ${connection.tone}` }), connection.label] }), _jsxs("span", { className: "ml-auto flex items-center gap-1", children: [_jsx(LinkButton, { href: connectPath(workspace), variant: "ghost", size: "sm", icon: _jsx(Plugs, {}), children: "Connect an agent" }), notifications.supported ? (_jsx(Button, { variant: "ghost", size: "sm", shape: "square", "aria-label": notifications.enabled ? "Turn notifications off" : "Notify me when an agent asks", icon: notifications.enabled ? _jsx(Bell, {}) : _jsx(BellSlash, {}), onClick: () => void notifications.toggle() })) : null, _jsx(AccountMenu, { signedIn: signedIn, items: accountItems })] })] }));
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { createLoopbackApp } from "./app.tsx";
+export { Page, Section } from "./page.tsx";
+export { connectPath, workspacePath } from "./paths.ts";
+export type { ExtensionPage, Extensions, LoopbackAppOptions, MenuItem, Session, SignedIn, Workspaces, WorkspaceSummary, } from "./ports.ts";
+export { followSystemTheme } from "./theme.ts";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { createLoopbackApp } from "./app.js";
+export { Page, Section } from "./page.js";
+export { connectPath, workspacePath } from "./paths.js";
+export { followSystemTheme } from "./theme.js";

package/dist/src/page.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+/** A page of its own, off the inbox: a way back, a heading, and its sections. */
+export declare function Page({ back, title, description, children, }: {
+    readonly back: {
+        readonly to: string;
+        readonly label: string;
+    };
+    readonly title: string;
+    readonly description?: string;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/** One part of a page: a card with a heading. A dangerous one is bordered in red. */
+export declare function Section({ title, description, danger, children, }: {
+    readonly title: string;
+    readonly description?: string | undefined;
+    readonly danger?: boolean;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;

package/dist/src/page.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from "@cloudflare/kumo";
+import { Link } from "react-router";
+/** A page of its own, off the inbox: a way back, a heading, and its sections. */
+export function Page({ back, title, description, children, }) {
+    return (_jsxs("main", { className: "mx-auto flex max-w-2xl flex-col gap-6 px-4 py-10", children: [_jsxs(Link, { to: back.to, className: "text-sm text-kumo-subtle", children: ["\u2190 ", back.label] }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Text, { variant: "heading", as: "h1", children: title }), description === undefined ? null : _jsx(Text, { variant: "secondary", children: description })] }), children] }));
+}
+/** One part of a page: a card with a heading. A dangerous one is bordered in red. */
+export function Section({ title, description, danger = false, children, }) {
+    return (_jsxs("section", { className: `flex flex-col gap-4 rounded-xl border bg-kumo-elevated p-5 ${danger ? "border-kumo-danger" : "border-kumo-line"}`, children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx(Text, { bold: true, children: title }), description === undefined ? null : (_jsx(Text, { variant: "secondary", size: "sm", children: description }))] }), children] }));
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,11 @@
+/** Where a workspace's inbox, or one ask in it, is in the app. */
+export declare const workspacePath: (workspace: string, askId?: string) => string;
+/** Where the page on connecting an agent to a workspace is. */
+export declare const connectPath: (workspace: string) => string;
+/**
+ * Where to send someone once they have signed in: a path in this app, never another site, so a link
+ * to the sign-in page can't be made to send people elsewhere.
+ */
+export declare const safeNext: (next: string | null) => string;
+/** The ask an old link names, from before links had paths: `/#/<id>`. */
+export declare const askInOldLink: (hash: string) => string | undefined;

package/dist/src/paths.js

@@ -0,0 +1,16 @@
+/** Where a workspace's inbox, or one ask in it, is in the app. */
+export const workspacePath = (workspace, askId) => `/w/${encodeURIComponent(workspace)}${askId === undefined ? "" : `/asks/${encodeURIComponent(askId)}`}`;
+/** Where the page on connecting an agent to a workspace is. */
+export const connectPath = (workspace) => `${workspacePath(workspace)}/connect`;
+/**
+ * Where to send someone once they have signed in: a path in this app, never another site, so a link
+ * to the sign-in page can't be made to send people elsewhere.
+ */
+export const safeNext = (next) => next !== null && next.startsWith("/") && !next.startsWith("//") && !next.startsWith("/\\")
+    ? next
+    : "/";
+/** The ask an old link names, from before links had paths: `/#/<id>`. */
+export const askInOldLink = (hash) => {
+    const id = /^#\/(.+)$/.exec(hash)?.[1];
+    return id === undefined ? undefined : decodeURIComponent(id);
+};

package/dist/src/ports.d.ts

@@ -0,0 +1,73 @@
+import type { LoopbackApi } from "@loopbacktools/sdk";
+import type { Icon } from "@phosphor-icons/react";
+import type { ComponentType } from "react";
+/** Someone signed in, as the app shows them. */
+export interface SignedIn {
+    /** How to show them, such as their name or email address, when the deployment knows. */
+    readonly name?: string;
+    /** Signs them out, where there is something to sign out of. */
+    readonly signOut?: () => void | Promise<void>;
+}
+export interface Session {
+    /**
+     * Who is signed in: `undefined` while that is being found out, `null` when nobody is. A React
+     * hook, so the deployment can read its own session however it keeps it.
+     */
+    readonly useSignedIn: () => SignedIn | null | undefined;
+    /**
+     * The page for someone not signed in, at `/sign-in`. Once they are, the app sends them on to
+     * `next`, the path they were going to.
+     */
+    readonly SignIn: ComponentType<{
+        readonly next: string;
+    }>;
+}
+/** A workspace someone can open: one Loopback space. */
+export interface WorkspaceSummary {
+    readonly id: string;
+    readonly name: string;
+}
+export interface Workspaces {
+    /** The workspaces the person signed in can open: `undefined` while loading. A React hook. */
+    readonly useList: () => readonly WorkspaceSummary[] | undefined;
+    /** Which of them the app opens first: the one they used last, say. A React hook. */
+    readonly usePreferred?: () => string | undefined;
+    /**
+     * The client for one workspace, carrying a credential for it. A React hook, giving back the same
+     * client for as long as the workspace stays open.
+     */
+    readonly useClient: (workspace: string) => LoopbackApi;
+    /** Makes a new workspace: its id, or `undefined` when none was made. */
+    readonly create?: () => Promise<string | undefined>;
+}
+/** An entry in one of the app's menus: somewhere to go, or something to do. */
+export interface MenuItem {
+    readonly label: string;
+    readonly icon?: Icon;
+    readonly to?: string;
+    readonly onSelect?: () => void | Promise<void>;
+}
+/** A page of the deployment's own. It stands alone, without the inbox's header: see `Page`. */
+export interface ExtensionPage {
+    /** Where it is, as a route path: `/account`, or `/w/:workspace/settings`. */
+    readonly path: string;
+    readonly Page: ComponentType;
+    /** Whether it is for someone signed in; anyone else is sent to sign in, and back. */
+    readonly signedIn: boolean;
+}
+export interface Extensions {
+    readonly pages?: readonly ExtensionPage[];
+    /** Items for a workspace's menu, below the workspaces. */
+    readonly workspaceMenu?: (workspace: string) => readonly MenuItem[];
+    /** Items for the menu of the person signed in, above signing out. */
+    readonly accountMenu?: readonly MenuItem[];
+    /** Shown above a workspace's inbox. */
+    readonly Banner?: ComponentType<{
+        readonly workspace: string;
+    }>;
+}
+export interface LoopbackAppOptions {
+    readonly session: Session;
+    readonly workspaces: Workspaces;
+    readonly extensions?: Extensions;
+}

package/dist/src/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/src/theme.d.ts

@@ -0,0 +1,2 @@
+/** Kumo themes by `data-mode` on the root element, so it follows the system's light or dark setting. */
+export declare const followSystemTheme: () => void;

package/dist/src/theme.js

@@ -0,0 +1,7 @@
+/** Kumo themes by `data-mode` on the root element, so it follows the system's light or dark setting. */
+export const followSystemTheme = () => {
+    const dark = window.matchMedia("(prefers-color-scheme: dark)");
+    const apply = () => document.documentElement.setAttribute("data-mode", dark.matches ? "dark" : "light");
+    apply();
+    dark.addEventListener("change", apply);
+};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@loopbacktools/app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "The Loopback app: the inbox, routed, with its header and pages, for a deployment to compose with its own sign-in and workspaces.",
+  "homepage": "https://github.com/LoopBackTools/loopback/tree/main/packages/app#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoopBackTools/loopback.git",
+    "directory": "packages/app"
+  },
+  "files": [
+    "dist",
+    "src",
+    "styles.css"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@phosphor-icons/react": "2.1.10"
+  },
+  "devDependencies": {
+    "@cloudflare/kumo": "2.15.0",
+    "@effect/atom-react": "4.0.6",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.8",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "effect": "4.0.6",
+    "es-module-lexer": "3.0.4",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-router": "8.3.0",
+    "typescript": "7.0.2",
+    "vite": "8.3.5",
+    "vitest": "5.0.5",
+    "@loopbacktools/inbox": "0.4.0",
+    "@loopbacktools/sdk": "0.4.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/kumo": "^2.15.0",
+    "@effect/atom-react": "^4.0.6",
+    "effect": "^4.0.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router": "^8.3.0",
+    "@loopbacktools/inbox": "^0.4.0",
+    "@loopbacktools/sdk": "^0.4.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
+  }
 }

package/src/app.tsx

@@ -0,0 +1,326 @@
+import {
+	Button,
+	ClipboardText,
+	Empty,
+	type LinkComponentProps,
+	LinkButton,
+	LinkProvider,
+	Loader,
+	Text,
+} from "@cloudflare/kumo";
+import { useAtomValue } from "@effect/atom-react";
+import { Inbox, InboxProvider } from "@loopbacktools/inbox";
+import type { LoopbackApi } from "@loopbacktools/sdk";
+import { Plus, Tray } from "@phosphor-icons/react";
+import { AsyncResult, Atom } from "effect/reactivity";
+import {
+	type ComponentType,
+	createContext,
+	forwardRef,
+	type ReactNode,
+	use,
+	useCallback,
+} from "react";
+import {
+	BrowserRouter,
+	Link,
+	Navigate,
+	Route,
+	Routes,
+	useLocation,
+	useNavigate,
+	useParams,
+	useSearchParams,
+} from "react-router";
+import { Header } from "./header.tsx";
+import { Page, Section } from "./page.tsx";
+import { askInOldLink, safeNext, workspacePath } from "./paths.ts";
+import type { LoopbackAppOptions, SignedIn as Signed } from "./ports.ts";
+
+function Waiting() {
+	return (
+		<main className="flex h-full items-center justify-center">
+			<Loader />
+		</main>
+	);
+}
+
+/** Kumo's links, followed by the app's router rather than by loading the page again. */
+const RouterLink = forwardRef<HTMLAnchorElement, LinkComponentProps>(
+	({ href, to, ...rest }, ref) => <Link ref={ref} to={href ?? to ?? ""} {...rest} />,
+);
+
+const SignedInContext = createContext<Signed | null>(null);
+
+/** Who is signed in, for a page behind `SignedIn`. */
+const useSignedInHere = (): Signed => {
+	const signedIn = use(SignedInContext);
+	if (signedIn === null) throw new Error("Only a page for someone signed in knows who they are.");
+	return signedIn;
+};
+
+/** A workspace that isn't the person's: they may have been removed, or the link is wrong. */
+function NotTheirs() {
+	return (
+		<main className="flex h-full items-center justify-center p-4">
+			<Empty
+				icon={<Tray size={32} />}
+				title="Not one of your workspaces"
+				description="You may have been removed from it, or the link is wrong."
+				contents={
+					<LinkButton href="/" variant="secondary">
+						Go to your inbox
+					</LinkButton>
+				}
+			/>
+		</main>
+	);
+}
+
+/** How agents sign in to a client's deployment, as its server says. */
+const agentSignInAtom = Atom.family((client: LoopbackApi) => Atom.make(client.agentSignIn));
+
+/** How to connect an agent to a workspace, as the server says its agents sign in. */
+function Connect({
+	workspace,
+	client,
+}: {
+	readonly workspace: string;
+	readonly client: LoopbackApi;
+}) {
+	const signIn = useAtomValue(agentSignInAtom(client));
+	if (AsyncResult.isInitial(signIn)) return <Waiting />;
+	const mcp = `${window.location.origin}/mcp`;
+	const oauth = AsyncResult.isSuccess(signIn) && signIn.value === "oauth";
+	return (
+		<Page
+			back={{ to: workspacePath(workspace), label: "Back to the inbox" }}
+			title="Connect an agent"
+			description={
+				oauth
+					? "Agents connect to Loopback over MCP and sign in as you. When one connects, you pick the workspace it asks in."
+					: "Agents connect to Loopback over MCP, sending this deployment's token."
+			}
+		>
+			<Section title="Claude Code">
+				<ClipboardText
+					text={
+						oauth
+							? `claude mcp add --transport http loopback ${mcp}`
+							: `claude mcp add --transport http loopback ${mcp} --header "Authorization: Bearer $LOOPBACK_TOKEN"`
+					}
+				/>
+				<Text variant="secondary" size="sm">
+					{oauth
+						? "Then run /mcp in Claude Code and sign in when it asks."
+						: "With the token in LOOPBACK_TOKEN, in the shell you run it from."}
+				</Text>
+			</Section>
+			<Section title="Any other MCP client">
+				<ClipboardText text={mcp} />
+				<Text variant="secondary" size="sm">
+					{oauth
+						? "Add it as a remote server over streamable HTTP. It signs in with OAuth."
+						: "Add it as a remote server over streamable HTTP, with the header Authorization: Bearer and the token."}
+				</Text>
+			</Section>
+		</Page>
+	);
+}
+
+const noPreference = (): string | undefined => undefined;
+
+/**
+ * The Loopback app, for a deployment to render: its inbox, a page on connecting agents, and the
+ * deployment's own pages, routed by path. Render it inside a `RegistryProvider`, as the inbox needs.
+ * The deployment's hooks are bound here, once: the app's pages call the same ones on every render.
+ */
+export const createLoopbackApp = (options: LoopbackAppOptions): ComponentType => {
+	const { SignIn } = options.session;
+	const useSignedIn = options.session.useSignedIn;
+	const useList = options.workspaces.useList;
+	const usePreferred = options.workspaces.usePreferred ?? noPreference;
+	const useClient = options.workspaces.useClient;
+	const { create } = options.workspaces;
+	const { pages = [], workspaceMenu, accountMenu = [], Banner } = options.extensions ?? {};
+
+	/** A page for someone signed in; anyone else is sent to sign in, and brought back after. */
+	function SignedIn({ children }: { readonly children: ReactNode }) {
+		const signedIn = useSignedIn();
+		const location = useLocation();
+		if (signedIn === undefined) return <Waiting />;
+		if (signedIn === null) {
+			const next = `${location.pathname}${location.search}${location.hash}`;
+			return <Navigate to={`/sign-in?next=${encodeURIComponent(next)}`} replace />;
+		}
+		return <SignedInContext value={signedIn}>{children}</SignedInContext>;
+	}
+
+	/** The deployment's sign-in page, until the person is signed in; then where they were going. */
+	function SignInPage() {
+		const signedIn = useSignedIn();
+		const [search] = useSearchParams();
+		const next = safeNext(search.get("next"));
+		if (signedIn === undefined) return <Waiting />;
+		if (signedIn !== null) return <Navigate to={next} replace />;
+		return <SignIn next={next} />;
+	}
+
+	/**
+	 * The app's front door: the workspace the person prefers, or their first, and the ask an old link
+	 * names in it. Someone in no workspace is offered a new one, where the deployment makes them.
+	 */
+	function Home() {
+		const navigate = useNavigate();
+		const location = useLocation();
+		const list = useList();
+		const preferred = usePreferred();
+		if (list === undefined) return <Waiting />;
+		const workspace = list.find((candidate) => candidate.id === preferred)?.id ?? list[0]?.id;
+		if (workspace !== undefined) {
+			return <Navigate to={workspacePath(workspace, askInOldLink(location.hash))} replace />;
+		}
+		return (
+			<main className="flex h-full items-center justify-center p-4">
+				<Empty
+					icon={<Tray size={32} />}
+					title="You're not in a workspace"
+					description={
+						create === undefined
+							? "Ask someone to invite you to theirs."
+							: "Make one to connect your agents to, or ask someone to invite you to theirs."
+					}
+					contents={
+						create === undefined ? undefined : (
+							<Button
+								variant="primary"
+								icon={<Plus />}
+								onClick={() =>
+									void create().then(async (id) => {
+										if (id !== undefined) await navigate(workspacePath(id));
+									})
+								}
+							>
+								New workspace
+							</Button>
+						)
+					}
+				/>
+			</main>
+		);
+	}
+
+	/**
+	 * One workspace's inbox, live, through the client the deployment gives for it. Another workspace
+	 * is another client, so switching reconnects to that one.
+	 */
+	function WorkspaceInbox({
+		workspace,
+		list,
+	}: {
+		readonly workspace: string;
+		readonly list: readonly { readonly id: string; readonly name: string }[];
+	}) {
+		const signedIn = useSignedInHere();
+		const client = useClient(workspace);
+		const { askId } = useParams();
+		const navigate = useNavigate();
+		const onSelect = useCallback(
+			(id: string | null) => void navigate(workspacePath(workspace, id ?? undefined)),
+			[navigate, workspace],
+		);
+		const hrefFor = useCallback((id: string) => workspacePath(workspace, id), [workspace]);
+		return (
+			<InboxProvider client={client}>
+				<div className="flex h-full flex-col">
+					<Header
+						workspace={workspace}
+						signedIn={signedIn}
+						workspaces={list}
+						workspaceItems={workspaceMenu?.(workspace) ?? []}
+						accountItems={accountMenu}
+						create={create}
+					/>
+					{Banner === undefined ? null : <Banner workspace={workspace} />}
+					<Inbox selectedId={askId ?? null} onSelect={onSelect} hrefFor={hrefFor} />
+				</div>
+			</InboxProvider>
+		);
+	}
+
+	function ConnectPage({ workspace }: { readonly workspace: string }) {
+		return <Connect workspace={workspace} client={useClient(workspace)} />;
+	}
+
+	/** A page of one of the person's workspaces, or a page saying it isn't one of theirs. */
+	function Theirs({ page }: { readonly page: "inbox" | "connect" }) {
+		const { workspace = "" } = useParams();
+		const list = useList();
+		if (list === undefined) return <Waiting />;
+		if (!list.some((candidate) => candidate.id === workspace)) return <NotTheirs />;
+		return page === "inbox" ? (
+			<WorkspaceInbox workspace={workspace} list={list} />
+		) : (
+			<ConnectPage workspace={workspace} />
+		);
+	}
+
+	return function LoopbackApp() {
+		return (
+			<BrowserRouter>
+				<LinkProvider component={RouterLink}>
+					<Routes>
+						<Route path="/sign-in" element={<SignInPage />} />
+						<Route
+							path="/w/:workspace"
+							element={
+								<SignedIn>
+									<Theirs page="inbox" />
+								</SignedIn>
+							}
+						/>
+						<Route
+							path="/w/:workspace/asks/:askId"
+							element={
+								<SignedIn>
+									<Theirs page="inbox" />
+								</SignedIn>
+							}
+						/>
+						<Route
+							path="/w/:workspace/connect"
+							element={
+								<SignedIn>
+									<Theirs page="connect" />
+								</SignedIn>
+							}
+						/>
+						{pages.map(({ path, Page: Shown, signedIn }) => (
+							<Route
+								key={path}
+								path={path}
+								element={
+									signedIn ? (
+										<SignedIn>
+											<Shown />
+										</SignedIn>
+									) : (
+										<Shown />
+									)
+								}
+							/>
+						))}
+						<Route
+							path="*"
+							element={
+								<SignedIn>
+									<Home />
+								</SignedIn>
+							}
+						/>
+					</Routes>
+				</LinkProvider>
+			</BrowserRouter>
+		);
+	};
+};

package/src/header.tsx

@@ -0,0 +1,196 @@
+import { Button, DropdownMenu, LinkButton, Text } from "@cloudflare/kumo";
+import { useAttention, useInbox, useNotifications } from "@loopbacktools/inbox";
+import { Bell, BellSlash, CaretDown, Check, Plugs, Plus, SignOut } from "@phosphor-icons/react";
+import { useCallback } from "react";
+import { Link, useNavigate } from "react-router";
+import { connectPath, workspacePath } from "./paths.ts";
+import type { MenuItem, SignedIn, WorkspaceSummary } from "./ports.ts";
+
+const CONNECTION = {
+	connecting: { label: "Connecting", tone: "bg-kumo-line" },
+	live: { label: "Live", tone: "bg-kumo-success" },
+	reconnecting: { label: "Reconnecting", tone: "bg-kumo-warning" },
+} as const;
+
+/** Goes where a menu item goes, or does what it does. */
+const useChoose = () => {
+	const navigate = useNavigate();
+	return (item: MenuItem) => {
+		if (item.to !== undefined) void navigate(item.to);
+		void item.onSelect?.();
+	};
+};
+
+/**
+ * The workspace open, and the way to the others: only where there is more than one, or a way to make
+ * one, or the deployment has items of its own for it.
+ */
+function WorkspaceMenu({
+	workspace,
+	list,
+	items,
+	create,
+}: {
+	readonly workspace: string;
+	readonly list: readonly WorkspaceSummary[];
+	readonly items: readonly MenuItem[];
+	readonly create: (() => Promise<string | undefined>) | undefined;
+}) {
+	const navigate = useNavigate();
+	const choose = useChoose();
+	if (list.length < 2 && create === undefined && items.length === 0) return null;
+	const current = list.find((candidate) => candidate.id === workspace);
+	const make = async () => {
+		const id = await create?.();
+		if (id !== undefined) await navigate(workspacePath(id));
+	};
+	return (
+		<DropdownMenu>
+			<DropdownMenu.Trigger>
+				<Button variant="ghost" size="sm" icon={<CaretDown />}>
+					{current?.name ?? "Workspace"}
+				</Button>
+			</DropdownMenu.Trigger>
+			<DropdownMenu.Content>
+				{list.map((candidate) => (
+					<DropdownMenu.Item
+						key={candidate.id}
+						icon={candidate.id === workspace ? Check : undefined}
+						onClick={() => void navigate(workspacePath(candidate.id))}
+					>
+						{candidate.name}
+					</DropdownMenu.Item>
+				))}
+				{items.length > 0 || create !== undefined ? <DropdownMenu.Separator /> : null}
+				{items.map((item) => (
+					<DropdownMenu.Item key={item.label} icon={item.icon} onClick={() => choose(item)}>
+						{item.label}
+					</DropdownMenu.Item>
+				))}
+				{create === undefined ? null : (
+					<DropdownMenu.Item icon={Plus} onClick={() => void make()}>
+						New workspace
+					</DropdownMenu.Item>
+				)}
+			</DropdownMenu.Content>
+		</DropdownMenu>
+	);
+}
+
+/**
+ * The person signed in: a menu of the deployment's items and signing out. With no items and no name
+ * to show, signing out is a button of its own, and with nothing to sign out of either, there is none.
+ */
+function AccountMenu({
+	signedIn,
+	items,
+}: {
+	readonly signedIn: SignedIn;
+	readonly items: readonly MenuItem[];
+}) {
+	const navigate = useNavigate();
+	const choose = useChoose();
+	const { name, signOut } = signedIn;
+	const leave =
+		signOut === undefined
+			? undefined
+			: async () => {
+					await signOut();
+					await navigate("/");
+				};
+	if (items.length === 0 && name === undefined) {
+		return leave === undefined ? null : (
+			<Button variant="ghost" size="sm" onClick={() => void leave()}>
+				Sign out
+			</Button>
+		);
+	}
+	return (
+		<DropdownMenu>
+			<DropdownMenu.Trigger>
+				<Button variant="ghost" size="sm">
+					{name ?? "Account"}
+				</Button>
+			</DropdownMenu.Trigger>
+			<DropdownMenu.Content>
+				{items.map((item) => (
+					<DropdownMenu.Item key={item.label} icon={item.icon} onClick={() => choose(item)}>
+						{item.label}
+					</DropdownMenu.Item>
+				))}
+				{leave === undefined ? null : (
+					<>
+						{items.length > 0 ? <DropdownMenu.Separator /> : null}
+						<DropdownMenu.Item icon={SignOut} onClick={() => void leave()}>
+							Sign out
+						</DropdownMenu.Item>
+					</>
+				)}
+			</DropdownMenu.Content>
+		</DropdownMenu>
+	);
+}
+
+/** The bar above a workspace's inbox. */
+export function Header({
+	workspace,
+	signedIn,
+	workspaces,
+	workspaceItems,
+	accountItems,
+	create,
+}: {
+	readonly workspace: string;
+	readonly signedIn: SignedIn;
+	/** Every workspace the person can open. */
+	readonly workspaces: readonly WorkspaceSummary[];
+	readonly workspaceItems: readonly MenuItem[];
+	readonly accountItems: readonly MenuItem[];
+	readonly create: (() => Promise<string | undefined>) | undefined;
+}) {
+	const navigate = useNavigate();
+	const inbox = useInbox();
+	const notifications = useNotifications();
+	const open = useCallback(
+		(askId: string) => void navigate(workspacePath(workspace, askId)),
+		[navigate, workspace],
+	);
+	useAttention(inbox, notifications.enabled, open);
+	const connection = CONNECTION[inbox.status];
+	return (
+		<header className="flex items-center gap-2 border-b border-kumo-line bg-kumo-base px-4 py-2">
+			<Link to={workspacePath(workspace)} className="flex items-center gap-2">
+				<img src="/favicon.svg" alt="" className="size-6" />
+				<Text bold>Loopback</Text>
+			</Link>
+			<WorkspaceMenu
+				workspace={workspace}
+				list={workspaces}
+				items={workspaceItems}
+				create={create}
+			/>
+			<span className="inline-flex items-center gap-1.5 text-xs text-kumo-subtle">
+				<span className={`size-2 rounded-full ${connection.tone}`} />
+				{connection.label}
+			</span>
+			<span className="ml-auto flex items-center gap-1">
+				<LinkButton href={connectPath(workspace)} variant="ghost" size="sm" icon={<Plugs />}>
+					Connect an agent
+				</LinkButton>
+				{notifications.supported ? (
+					<Button
+						variant="ghost"
+						size="sm"
+						shape="square"
+						aria-label={
+							notifications.enabled ? "Turn notifications off" : "Notify me when an agent asks"
+						}
+						icon={notifications.enabled ? <Bell /> : <BellSlash />}
+						onClick={() => void notifications.toggle()}
+					/>
+				) : null}
+				<AccountMenu signedIn={signedIn} items={accountItems} />
+			</span>
+		</header>
+	);
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { createLoopbackApp } from "./app.tsx";
+export { Page, Section } from "./page.tsx";
+export { connectPath, workspacePath } from "./paths.ts";
+export type {
+	ExtensionPage,
+	Extensions,
+	LoopbackAppOptions,
+	MenuItem,
+	Session,
+	SignedIn,
+	Workspaces,
+	WorkspaceSummary,
+} from "./ports.ts";
+export { followSystemTheme } from "./theme.ts";

package/src/page.tsx

@@ -0,0 +1,62 @@
+import { Text } from "@cloudflare/kumo";
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+
+/** A page of its own, off the inbox: a way back, a heading, and its sections. */
+export function Page({
+	back,
+	title,
+	description,
+	children,
+}: {
+	readonly back: { readonly to: string; readonly label: string };
+	readonly title: string;
+	readonly description?: string;
+	readonly children: ReactNode;
+}) {
+	return (
+		<main className="mx-auto flex max-w-2xl flex-col gap-6 px-4 py-10">
+			<Link to={back.to} className="text-sm text-kumo-subtle">
+				← {back.label}
+			</Link>
+			<div className="flex flex-col gap-2">
+				<Text variant="heading" as="h1">
+					{title}
+				</Text>
+				{description === undefined ? null : <Text variant="secondary">{description}</Text>}
+			</div>
+			{children}
+		</main>
+	);
+}
+
+/** One part of a page: a card with a heading. A dangerous one is bordered in red. */
+export function Section({
+	title,
+	description,
+	danger = false,
+	children,
+}: {
+	readonly title: string;
+	readonly description?: string | undefined;
+	readonly danger?: boolean;
+	readonly children: ReactNode;
+}) {
+	return (
+		<section
+			className={`flex flex-col gap-4 rounded-xl border bg-kumo-elevated p-5 ${
+				danger ? "border-kumo-danger" : "border-kumo-line"
+			}`}
+		>
+			<div className="flex flex-col gap-1">
+				<Text bold>{title}</Text>
+				{description === undefined ? null : (
+					<Text variant="secondary" size="sm">
+						{description}
+					</Text>
+				)}
+			</div>
+			{children}
+		</section>
+	);
+}

package/src/paths.ts

@@ -0,0 +1,21 @@
+/** Where a workspace's inbox, or one ask in it, is in the app. */
+export const workspacePath = (workspace: string, askId?: string): string =>
+	`/w/${encodeURIComponent(workspace)}${askId === undefined ? "" : `/asks/${encodeURIComponent(askId)}`}`;
+
+/** Where the page on connecting an agent to a workspace is. */
+export const connectPath = (workspace: string): string => `${workspacePath(workspace)}/connect`;
+
+/**
+ * Where to send someone once they have signed in: a path in this app, never another site, so a link
+ * to the sign-in page can't be made to send people elsewhere.
+ */
+export const safeNext = (next: string | null): string =>
+	next !== null && next.startsWith("/") && !next.startsWith("//") && !next.startsWith("/\\")
+		? next
+		: "/";
+
+/** The ask an old link names, from before links had paths: `/#/<id>`. */
+export const askInOldLink = (hash: string): string | undefined => {
+	const id = /^#\/(.+)$/.exec(hash)?.[1];
+	return id === undefined ? undefined : decodeURIComponent(id);
+};

package/src/ports.ts

@@ -0,0 +1,81 @@
+import type { LoopbackApi } from "@loopbacktools/sdk";
+import type { Icon } from "@phosphor-icons/react";
+import type { ComponentType } from "react";
+
+// What the app needs from the deployment it runs in, and nothing more: who is signed in, which
+// workspaces they can open, and anything of the deployment's own. Each deployment fills these in,
+// in a short entry file of its own. See docs/design/one-app.md.
+
+/** Someone signed in, as the app shows them. */
+export interface SignedIn {
+	/** How to show them, such as their name or email address, when the deployment knows. */
+	readonly name?: string;
+	/** Signs them out, where there is something to sign out of. */
+	readonly signOut?: () => void | Promise<void>;
+}
+
+export interface Session {
+	/**
+	 * Who is signed in: `undefined` while that is being found out, `null` when nobody is. A React
+	 * hook, so the deployment can read its own session however it keeps it.
+	 */
+	readonly useSignedIn: () => SignedIn | null | undefined;
+	/**
+	 * The page for someone not signed in, at `/sign-in`. Once they are, the app sends them on to
+	 * `next`, the path they were going to.
+	 */
+	readonly SignIn: ComponentType<{ readonly next: string }>;
+}
+
+/** A workspace someone can open: one Loopback space. */
+export interface WorkspaceSummary {
+	readonly id: string;
+	readonly name: string;
+}
+
+export interface Workspaces {
+	/** The workspaces the person signed in can open: `undefined` while loading. A React hook. */
+	readonly useList: () => readonly WorkspaceSummary[] | undefined;
+	/** Which of them the app opens first: the one they used last, say. A React hook. */
+	readonly usePreferred?: () => string | undefined;
+	/**
+	 * The client for one workspace, carrying a credential for it. A React hook, giving back the same
+	 * client for as long as the workspace stays open.
+	 */
+	readonly useClient: (workspace: string) => LoopbackApi;
+	/** Makes a new workspace: its id, or `undefined` when none was made. */
+	readonly create?: () => Promise<string | undefined>;
+}
+
+/** An entry in one of the app's menus: somewhere to go, or something to do. */
+export interface MenuItem {
+	readonly label: string;
+	readonly icon?: Icon;
+	readonly to?: string;
+	readonly onSelect?: () => void | Promise<void>;
+}
+
+/** A page of the deployment's own. It stands alone, without the inbox's header: see `Page`. */
+export interface ExtensionPage {
+	/** Where it is, as a route path: `/account`, or `/w/:workspace/settings`. */
+	readonly path: string;
+	readonly Page: ComponentType;
+	/** Whether it is for someone signed in; anyone else is sent to sign in, and back. */
+	readonly signedIn: boolean;
+}
+
+export interface Extensions {
+	readonly pages?: readonly ExtensionPage[];
+	/** Items for a workspace's menu, below the workspaces. */
+	readonly workspaceMenu?: (workspace: string) => readonly MenuItem[];
+	/** Items for the menu of the person signed in, above signing out. */
+	readonly accountMenu?: readonly MenuItem[];
+	/** Shown above a workspace's inbox. */
+	readonly Banner?: ComponentType<{ readonly workspace: string }>;
+}
+
+export interface LoopbackAppOptions {
+	readonly session: Session;
+	readonly workspaces: Workspaces;
+	readonly extensions?: Extensions;
+}

package/src/theme.ts

@@ -0,0 +1,8 @@
+/** Kumo themes by `data-mode` on the root element, so it follows the system's light or dark setting. */
+export const followSystemTheme = (): void => {
+	const dark = window.matchMedia("(prefers-color-scheme: dark)");
+	const apply = () =>
+		document.documentElement.setAttribute("data-mode", dark.matches ? "dark" : "light");
+	apply();
+	dark.addEventListener("change", apply);
+};

package/styles.css

@@ -0,0 +1,5 @@
+/*
+ * The app's styles. Import this after Tailwind and Kumo's theme, beside the inbox's: it has Tailwind
+ * generate the utilities the app's own pages use.
+ */
+@source "./src";