@korso/shepherd-ui 0.1.1 → 0.2.1

package/dist/ShepherdRoot.d.ts

@@ -0,0 +1,9 @@
+export interface ShepherdRootProps {
+    /**
+     * The DIRECT Hub URL embedded in the agent install command (planning decision
+     * #2: the headless agent connects straight to the Hub, not the BFF). Defaults
+     * to the client's baseUrl, which is correct for self-host.
+     */
+    hubUrl?: string;
+}
+export declare function ShepherdRoot({ hubUrl }: ShepherdRootProps): import("react").JSX.Element;

package/dist/ShepherdRoot.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { Dashboard } from "./components/Dashboard.js";
+import { Workspaces } from "./config/Workspaces.js";
+import { ConnectAgent } from "./config/ConnectAgent.js";
+import { useShepherdClient } from "./context.js";
+import { describeError } from "./client.js";
+export function ShepherdRoot({ hubUrl }) {
+    const client = useShepherdClient();
+    const [load, setLoad] = useState({ status: "loading" });
+    const [selectedId, setSelectedId] = useState(null);
+    // Loads the workspace list and keeps the selection valid: a still-present
+    // selection is preserved (so a create/join refresh never yanks the user off
+    // their current workspace), otherwise it falls back to the first workspace.
+    const fetchWorkspaces = useCallback(async () => {
+        try {
+            const res = await client.listWorkspaces();
+            setLoad({ status: "ready", workspaces: res.workspaces });
+            setSelectedId((prev) => prev && res.workspaces.some((w) => w.id === prev)
+                ? prev
+                : (res.workspaces[0]?.id ?? null));
+        }
+        catch (err) {
+            setLoad({ status: "error", message: describeError(err) });
+        }
+    }, [client]);
+    useEffect(() => {
+        void fetchWorkspaces();
+    }, [fetchWorkspaces]);
+    const workspaces = load.status === "ready" ? load.workspaces : [];
+    const selected = workspaces.find((w) => w.id === selectedId) ?? null;
+    if (load.status === "loading") {
+        return (_jsx("div", { className: "shepherd-root", children: _jsx("p", { role: "status", children: "Loading\u2026" }) }));
+    }
+    if (load.status === "error") {
+        return (_jsx("div", { className: "shepherd-root", children: _jsx("p", { role: "alert", children: load.message }) }));
+    }
+    const hasWorkspace = workspaces.length > 0;
+    // The Config tab's content. Rendered by <Dashboard> in its `config` panel.
+    // ConnectAgent only appears once a workspace is selected (nothing to connect
+    // an agent to otherwise).
+    const configSection = (_jsxs("section", { className: "shepherd-config", "aria-labelledby": "config-heading", children: [_jsx("h2", { id: "config-heading", children: "Configuration" }), _jsx(Workspaces, { workspaces: workspaces, selected: selected, onChanged: () => {
+                    void fetchWorkspaces();
+                }, onSelect: setSelectedId }), selected && _jsx(ConnectAgent, { workspaceId: selected.id, hubUrl: hubUrl })] }));
+    return (_jsx("div", { className: "shepherd-root", children: _jsx(Dashboard, { workspaceId: selected?.id, config: configSection, hasWorkspace: hasWorkspace }) }));
+}

package/dist/client.d.ts

@@ -0,0 +1,107 @@
+import type { ListWorkspacesResponseT, CreateWorkspaceRequestT, CreateWorkspaceResponseT, MintTokenRequestT, MintTokenResponseT, ListTokensResponseT, CreateInviteRequestT, InviteResponseT, RedeemInviteResponseT, ListMembersResponseT, WorkspaceLandscapeResponseT, WorkspaceAnnounceRequestT, WorkspaceAnnounceResponseT } from "@shepherd/shared";
+/**
+ * The single error type surfaced by the client. A missing `status` means a
+ * transport failure (network error or request timeout); a present `status` is
+ * the upstream HTTP status of a non-2xx response. One class — distinguished by
+ * the optional `status` — keeps callers from having to branch on two error
+ * types just to tell "couldn't reach the hub" from "the hub said no".
+ */
+export declare class ShepherdClientError extends Error {
+    /** Upstream HTTP status for a non-2xx response; absent for transport errors. */
+    readonly status?: number;
+    /**
+     * @param message - Human-readable failure description.
+     * @param status - Upstream HTTP status, omitted for network/abort failures.
+     */
+    constructor(message: string, status?: number);
+}
+/**
+ * Maps any thrown value into a short, human-friendly message for the view layer.
+ * A {@link ShepherdClientError} (and any other `Error`) surfaces its own
+ * `message` — which already carries the hub's detail for non-2xx responses and a
+ * transport description otherwise — while a non-Error value degrades to a
+ * generic line rather than stringifying something unprintable.
+ *
+ * @param err - The caught value (typically from a client method rejection).
+ * @returns A display-ready message string.
+ */
+export declare function describeError(err: unknown): string;
+/**
+ * The typed Shepherd hub surface. The plural, workspace-scoped methods use the
+ * `/workspaces/:id/...` form (which works in both deployments: a bearer token
+ * resolves its own workspace and ignores `:id`, while a browser session
+ * validates membership of `:id`). The singular `getLandscape()`/`announce()`
+ * pair are the self-host aliases against the implicit single-workspace routes.
+ * Every response with a dedicated schema is Zod-parsed at the boundary so a
+ * contract drift throws `Invalid response schema` rather than flowing a
+ * malformed object into the view layer.
+ */
+export interface ShepherdClient {
+    /** The normalised (trailing-slash-stripped) hub base URL the client targets. */
+    readonly baseUrl: string;
+    /** GET the caller's workspaces, each tagged with the caller's role. */
+    listWorkspaces(): Promise<ListWorkspacesResponseT>;
+    /** POST a new workspace; the caller becomes its admin. */
+    createWorkspace(body: CreateWorkspaceRequestT): Promise<CreateWorkspaceResponseT>;
+    /** POST a new agent token; the raw `shp_` value is returned exactly once. */
+    mintToken(workspaceId: string, body: MintTokenRequestT): Promise<MintTokenResponseT>;
+    /** GET the workspace's token metadata (never the raw token). */
+    listTokens(workspaceId: string): Promise<ListTokensResponseT>;
+    /** DELETE (revoke) a token by id. */
+    revokeToken(workspaceId: string, tokenId: string): Promise<void>;
+    /** POST a new invite code for the workspace (admin only). */
+    createInvite(workspaceId: string, body: CreateInviteRequestT): Promise<InviteResponseT>;
+    /** POST to revoke an invite code (admin only). */
+    revokeInvite(workspaceId: string, code: string): Promise<void>;
+    /** POST to redeem an invite code, joining its workspace as a member. */
+    redeemInvite(code: string): Promise<RedeemInviteResponseT>;
+    /** GET the workspace's member roster. */
+    listMembers(workspaceId: string): Promise<ListMembersResponseT>;
+    /** DELETE (remove) a member by account id (admin only). */
+    removeMember(workspaceId: string, accountId: string): Promise<void>;
+    /** POST to leave the workspace. */
+    leave(workspaceId: string): Promise<void>;
+    /** GET a specific workspace's landscape (agents, tasks, announcements). */
+    landscape(workspaceId: string): Promise<WorkspaceLandscapeResponseT>;
+    /** POST an operator announcement to a specific workspace. */
+    announceTo(workspaceId: string, body: WorkspaceAnnounceRequestT): Promise<WorkspaceAnnounceResponseT>;
+    /** GET the unfiltered whole-workspace view (agents, tasks, announcements). */
+    getLandscape(): Promise<WorkspaceLandscapeResponseT>;
+    /** POST an operator announcement (broadcast or @targeted) to the workspace. */
+    announce(req: WorkspaceAnnounceRequestT): Promise<WorkspaceAnnounceResponseT>;
+}
+/**
+ * Construction options for {@link createShepherdClient}. Auth is supplied
+ * externally via `getAuthHeader` so the core client stays auth-agnostic — it
+ * never reads tokens, localStorage, or a BFF; it only merges whatever the host
+ * injects and notifies the host on a 401 via `onUnauthorized`.
+ */
+export interface ShepherdClientConfig {
+    /** Hub origin; a trailing slash is tolerated and normalised away. "" = same-origin. */
+    baseUrl: string;
+    /**
+     * Returns the credential for the next request, as either:
+     *   - a string  → sent as the `Authorization` header value (e.g. "Bearer …"),
+     *   - a header map → merged verbatim over the JSON content-type base, or
+     *   - undefined  → no auth header added (same-origin BFF supplies the cookie).
+     * May be sync or async (e.g. refreshing a short-lived token). Omit entirely
+     * for an unauthenticated/same-origin deployment.
+     */
+    getAuthHeader?: () => string | Record<string, string> | undefined | Promise<string | Record<string, string> | undefined>;
+    /** Invoked once when the hub responds 401, before the error is thrown. */
+    onUnauthorized?: () => void;
+    /** Per-request abort timeout in ms; defaults to {@link DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Builds a browser fetch client for the Shepherd hub. Each call wires up an
+ * AbortController timeout (cleared in `finally`), merges the injected auth
+ * headers over a JSON content-type base, and Zod-parses ONLY the response at
+ * the boundary — the request body is forwarded verbatim because the caller owns
+ * its input shape. void-returning methods (revoke/remove/leave) await the
+ * request and parse nothing.
+ *
+ * @param config - Base URL, optional injected auth, 401 hook, and timeout.
+ * @returns A {@link ShepherdClient}.
+ */
+export declare function createShepherdClient(config: ShepherdClientConfig): ShepherdClient;

package/dist/client.js

@@ -0,0 +1,238 @@
+import { ListWorkspacesResponse, CreateWorkspaceResponse, MintTokenResponse, ListTokensResponse, InviteResponse, RedeemInviteResponse, ListMembersResponse, WorkspaceLandscapeResponse, WorkspaceAnnounceResponse, } from "@shepherd/shared";
+/** Per-request abort fires after this many ms when no timeoutMs is configured. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * The single error type surfaced by the client. A missing `status` means a
+ * transport failure (network error or request timeout); a present `status` is
+ * the upstream HTTP status of a non-2xx response. One class — distinguished by
+ * the optional `status` — keeps callers from having to branch on two error
+ * types just to tell "couldn't reach the hub" from "the hub said no".
+ */
+export class ShepherdClientError extends Error {
+    /** Upstream HTTP status for a non-2xx response; absent for transport errors. */
+    status;
+    /**
+     * @param message - Human-readable failure description.
+     * @param status - Upstream HTTP status, omitted for network/abort failures.
+     */
+    constructor(message, status) {
+        super(message);
+        this.name = "ShepherdClientError";
+        if (status !== undefined) {
+            this.status = status;
+        }
+    }
+}
+/**
+ * Maps any thrown value into a short, human-friendly message for the view layer.
+ * A {@link ShepherdClientError} (and any other `Error`) surfaces its own
+ * `message` — which already carries the hub's detail for non-2xx responses and a
+ * transport description otherwise — while a non-Error value degrades to a
+ * generic line rather than stringifying something unprintable.
+ *
+ * @param err - The caught value (typically from a client method rejection).
+ * @returns A display-ready message string.
+ */
+export function describeError(err) {
+    return err instanceof Error ? err.message : "Something went wrong.";
+}
+/**
+ * Reads a best-effort `{ error: string }` message from a non-2xx response body
+ * so the thrown error carries the hub's own explanation. A non-JSON or bodyless
+ * response degrades to an empty string — the status code is still informative.
+ *
+ * @param res - The non-2xx response to inspect.
+ * @returns The upstream error string, or "" when none could be read.
+ */
+async function readErrorDetail(res) {
+    try {
+        const data = await res.json();
+        if (data !== null &&
+            typeof data === "object" &&
+            "error" in data &&
+            typeof data.error === "string") {
+            return data.error;
+        }
+    }
+    catch {
+        // Body wasn't JSON; the status code alone remains informative.
+    }
+    return "";
+}
+/**
+ * Builds a browser fetch client for the Shepherd hub. Each call wires up an
+ * AbortController timeout (cleared in `finally`), merges the injected auth
+ * headers over a JSON content-type base, and Zod-parses ONLY the response at
+ * the boundary — the request body is forwarded verbatim because the caller owns
+ * its input shape. void-returning methods (revoke/remove/leave) await the
+ * request and parse nothing.
+ *
+ * @param config - Base URL, optional injected auth, 401 hook, and timeout.
+ * @returns A {@link ShepherdClient}.
+ */
+export function createShepherdClient(config) {
+    // Strip a trailing slash so `${baseUrl}/workspace/...` never yields a double
+    // slash regardless of how the host configured the origin. An empty baseUrl
+    // stays "" so paths resolve root-relative (same-origin).
+    const baseUrl = config.baseUrl.replace(/\/$/, "");
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const enc = encodeURIComponent;
+    /**
+     * Performs one request, mapping transport failures to a status-less error,
+     * 401s to `onUnauthorized` + a 401 error, other non-2xx to a status error,
+     * and a 2xx body either through the supplied Zod schema or — when no schema
+     * is given (void endpoints) — to `undefined`.
+     */
+    async function request(method, path, opts = {}) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            const baseHeaders = {
+                "Content-Type": "application/json",
+            };
+            // Resolve getAuthHeader (sync or async) into a header record: a string is
+            // the Authorization value, a map merges verbatim, undefined adds nothing.
+            // Injected auth wins over the base, so a host may even override the
+            // content-type if it ever needs to. Built INSIDE the try so a rejecting
+            // (async) getAuthHeader is funneled through the catch and the finally
+            // still clears the abort timer — no leaked timer on an auth failure.
+            const resolved = await config.getAuthHeader?.();
+            const authHeaders = typeof resolved === "string"
+                ? { Authorization: resolved }
+                : resolved ?? {};
+            const init = {
+                method,
+                headers: { ...baseHeaders, ...authHeaders },
+                signal: controller.signal,
+            };
+            if (opts.body !== undefined) {
+                init.body = JSON.stringify(opts.body);
+            }
+            res = await fetch(`${baseUrl}${path}`, init);
+        }
+        catch (err) {
+            // Network error or abort/timeout: no HTTP status exists, so the error is
+            // thrown WITHOUT one to mark it a transport failure.
+            throw new ShepherdClientError(err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res.status === 401) {
+            config.onUnauthorized?.();
+            throw new ShepherdClientError("Unauthorized", 401);
+        }
+        if (!res.ok) {
+            const detail = await readErrorDetail(res);
+            throw new ShepherdClientError(detail !== ""
+                ? `HTTP ${res.status}: ${detail}`
+                : `HTTP ${res.status}`, res.status);
+        }
+        if (!opts.schema) {
+            // void endpoint: no dedicated response schema. Drain any body and resolve
+            // undefined — callers of these methods don't depend on the payload.
+            try {
+                await res.json();
+            }
+            catch {
+                // empty / non-JSON body is fine for a void endpoint.
+            }
+            // void endpoints are called as request<void>(...); the undefined resolve
+            // is the intended value, asserted to T since the no-schema branch is only
+            // reached for the void-typed callers.
+            return undefined;
+        }
+        const parsed = opts.schema.safeParse(await res.json());
+        if (!parsed.success) {
+            throw new ShepherdClientError("Invalid response schema");
+        }
+        return parsed.data;
+    }
+    return {
+        baseUrl,
+        // --- multi-workspace management surface ---------------------------------
+        listWorkspaces() {
+            return request("GET", "/workspaces", {
+                schema: ListWorkspacesResponse,
+            });
+        },
+        createWorkspace(body) {
+            return request("POST", "/workspaces", {
+                body,
+                schema: CreateWorkspaceResponse,
+            });
+        },
+        mintToken(workspaceId, body) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/tokens`, {
+                body,
+                schema: MintTokenResponse,
+            });
+        },
+        listTokens(workspaceId) {
+            return request("GET", `/workspaces/${enc(workspaceId)}/tokens`, {
+                schema: ListTokensResponse,
+            });
+        },
+        revokeToken(workspaceId, tokenId) {
+            return request("DELETE", `/workspaces/${enc(workspaceId)}/tokens/${enc(tokenId)}`);
+        },
+        createInvite(workspaceId, body) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/invites`, {
+                body,
+                schema: InviteResponse,
+            });
+        },
+        revokeInvite(workspaceId, code) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/invites/${enc(code)}/revoke`);
+        },
+        redeemInvite(code) {
+            return request("POST", `/invites/${enc(code)}/redeem`, {
+                schema: RedeemInviteResponse,
+            });
+        },
+        listMembers(workspaceId) {
+            return request("GET", `/workspaces/${enc(workspaceId)}/members`, {
+                schema: ListMembersResponse,
+            });
+        },
+        removeMember(workspaceId, accountId) {
+            return request("DELETE", `/workspaces/${enc(workspaceId)}/members/${enc(accountId)}`);
+        },
+        leave(workspaceId) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/leave`);
+        },
+        landscape(workspaceId) {
+            // WorkspaceLandscapeResponse's inferred type widens the announcement
+            // admin flags to optional, so it doesn't structurally match the declared
+            // ...ResponseT alias; an explicit cast is kept for just this schema.
+            return request("GET", `/workspaces/${enc(workspaceId)}/landscape`, {
+                schema: WorkspaceLandscapeResponse,
+            });
+        },
+        announceTo(workspaceId, body) {
+            // The request body is NOT validated here — the caller owns input shape;
+            // only the RESPONSE is parsed at the boundary.
+            return request("POST", `/workspaces/${enc(workspaceId)}/announce`, {
+                body,
+                schema: WorkspaceAnnounceResponse,
+            });
+        },
+        // --- self-host singular aliases (implicit single workspace) -------------
+        getLandscape() {
+            // See landscape() above: this schema's inferred type doesn't structurally
+            // match the ...ResponseT alias, so its explicit cast is kept.
+            return request("GET", "/workspace/landscape", {
+                schema: WorkspaceLandscapeResponse,
+            });
+        },
+        announce(req) {
+            // The request body is NOT validated here — the caller owns input shape;
+            // only the RESPONSE is parsed at the boundary.
+            return request("POST", "/workspace/announce", {
+                body: req,
+                schema: WorkspaceAnnounceResponse,
+            });
+        },
+    };
+}

package/dist/components/ActiveList.d.ts

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+import type { WorkspaceTaskT } from "@shepherd/shared";
+/** Props for {@link ActiveList}. */
+export interface ActiveListProps {
+    /** The board's tasks; only active ones in the selected repo are shown. */
+    tasks: WorkspaceTaskT[];
+    /** The server-clock "now" in epoch ms, for relative time labels. */
+    nowMs: number;
+    /** The selected repo, or `null`/`"__all__"` for all repos. */
+    selectedRepo: string | null;
+}
+/**
+ * The Active column. Ported from app.js `renderActive`. Filters tasks to active
+ * + selected-repo, groups them by agent via {@link groupActiveClaims}, then
+ * renders a {@link PlainCard} for a lone claim or a {@link GroupCard} otherwise.
+ * Shows an empty-state message when nothing is active. In All-repos mode each
+ * card carries a repo tag; in single-repo mode it does not.
+ *
+ * @param props - The tasks, the server "now", and the repo filter.
+ * @returns The active list element.
+ */
+export declare function ActiveList({ tasks, nowMs, selectedRepo, }: ActiveListProps): ReactElement;

package/dist/components/ActiveList.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatRelative, groupActiveClaims, matchesRepo, } from "../logic.js";
+import { Territory } from "./Territory.js";
+/** Stable identity for a claim across renders (the payload has no claim id). */
+const claimKey = (t) => `${t.agentName}|${t.repo}|${t.createdAt}`;
+/** Whether the board is showing all repos (so cards carry a repo tag). */
+const isAllRepos = (selected) => selected === null || selected === "__all__";
+/**
+ * One active claim's body: intent + territory + a "started N ago" meta line.
+ * Shared by the plain card and each row of a grouped card (app.js `claimBody`).
+ */
+function ClaimBody({ task, nowMs, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "task__intent", children: task.intent }), _jsx(Territory, { globs: task.pathGlobs }), _jsx("div", { className: "task__meta", children: `started ${formatRelative(task.createdAt, nowMs)}` })] }));
+}
+/**
+ * A lone agent/claim rendered as the classic single card (app.js `plainCard`):
+ * the agent, an optional model/program tag, a live dot, then the claim body.
+ */
+function PlainCard({ task, nowMs, allRepos, }) {
+    const tag = task.model || task.program;
+    return (_jsxs("div", { className: "task", children: [_jsxs("div", { className: "task__r1", children: [_jsx("span", { className: "task__who", children: task.agentName }), allRepos && _jsx("span", { className: "task__repo", children: task.repo }), tag && _jsx("span", { className: "task__tag", children: tag }), _jsx("span", { className: "livedot", title: "active" })] }), _jsx(ClaimBody, { task: task, nowMs: nowMs })] }));
+}
+/**
+ * An agent with multiple live claims rendered grouped (app.js `groupCard`): a
+ * header, one `.claim` per primary, and a collapsible `"+N narrower claim(s)"`
+ * fold for claims a broader sibling fully covers (folded, never hidden).
+ */
+function GroupCard({ group, nowMs, allRepos, }) {
+    const tag = group.model || group.program;
+    const total = group.primaries.length + group.narrower.length;
+    const n = group.narrower.length;
+    return (_jsxs("div", { className: "grp", children: [_jsxs("div", { className: "grp__head", children: [_jsx("span", { className: "grp__who", children: group.agentName }), allRepos && _jsx("span", { className: "task__repo", children: group.repo }), tag && _jsx("span", { className: "grp__tag", children: tag }), _jsx("span", { className: "grp__count", children: `· ${total} active` }), _jsx("span", { className: "grp__dot", title: "live" })] }), _jsx("div", { className: "claims", children: group.primaries.map((c) => (_jsx("div", { className: "claim", children: _jsx(ClaimBody, { task: c, nowMs: nowMs }) }, claimKey(c)))) }), n > 0 && (_jsxs("details", { className: "fold", children: [_jsxs("summary", { children: [_jsx("span", { className: "tw", children: "\u25B6" }), ` +${n} narrower claim${n > 1 ? "s" : ""}`] }), _jsx("div", { className: "fold__body", children: group.narrower.map((c) => (_jsxs("div", { className: "claim", children: [_jsx(ClaimBody, { task: c, nowMs: nowMs }), _jsx("div", { className: "covered", children: "\u2282 covered by a claim above" })] }, claimKey(c)))) })] }))] }));
+}
+/**
+ * The Active column. Ported from app.js `renderActive`. Filters tasks to active
+ * + selected-repo, groups them by agent via {@link groupActiveClaims}, then
+ * renders a {@link PlainCard} for a lone claim or a {@link GroupCard} otherwise.
+ * Shows an empty-state message when nothing is active. In All-repos mode each
+ * card carries a repo tag; in single-repo mode it does not.
+ *
+ * @param props - The tasks, the server "now", and the repo filter.
+ * @returns The active list element.
+ */
+export function ActiveList({ tasks, nowMs, selectedRepo, }) {
+    const allRepos = isAllRepos(selectedRepo);
+    const active = tasks.filter((t) => t.status === "active" && matchesRepo(t, selectedRepo));
+    if (active.length === 0) {
+        const msg = allRepos
+            ? "Nothing active right now."
+            : `Nothing active in ${selectedRepo}.`;
+        return (_jsx("div", { id: "active-list", children: _jsx("div", { className: "empty", children: msg }) }));
+    }
+    return (_jsx("div", { id: "active-list", children: groupActiveClaims(active).map((g) => {
+            const single = g.primaries.length === 1 && g.narrower.length === 0;
+            // Key on the group's newest claim — stable across polls per agent.
+            const key = claimKey(g.primaries.concat(g.narrower)[0]);
+            return single ? (_jsx(PlainCard, { task: g.primaries[0], nowMs: nowMs, allRepos: allRepos }, key)) : (_jsx(GroupCard, { group: g, nowMs: nowMs, allRepos: allRepos }, key));
+        }) }));
+}

package/dist/components/Chat.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+import type { WorkspaceAnnouncementT } from "@shepherd/shared";
+/** Props for {@link Chat}. */
+export interface ChatProps {
+    /** The workspace announcement feed, newest-first as the API returns it. */
+    announcements: WorkspaceAnnouncementT[];
+    /** The board's selected repo; `null`/`"__all__"` show every repo's messages. */
+    selectedRepo: string | null;
+    /** The server clock in epoch ms, so "N ago" matches the rest of the board. */
+    nowMs: number;
+}
+/**
+ * The group-chat view of the workspace announcement feed (the "Chat" tab).
+ *
+ * The API returns announcements newest-first, but a chat reads oldest -> newest
+ * top -> bottom, so the list is reversed before render; messages are filtered to
+ * the selected repo. Each row mirrors app.js `renderAnnouncements`: an avatar
+ * (initials + deterministic color), the sender, an optional "→ @target" /
+ * "→ admin" header, the relative time, and the body. Operator messages
+ * (`fromAdmin`) get `msg--me` (right-aligned); directed or to-admin messages get
+ * `msg--targeted`.
+ *
+ * The viewer stays pinned to the newest message UNLESS they have scrolled up to
+ * read history — measured against the scroll container before each re-render and
+ * re-applied in a layout effect so the write happens before paint (no flicker).
+ *
+ * @param props - The feed, the repo filter, and the server clock.
+ * @returns The scrollable chat element.
+ */
+export declare function Chat({ announcements, selectedRepo, nowMs }: ChatProps): ReactNode;

package/dist/components/Chat.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef } from "react";
+import { colorForName, formatRelative, initialsFor, matchesRepo, } from "../logic.js";
+/**
+ * How close (in px) to the bottom still counts as "pinned to the newest
+ * message". Ported verbatim from app.js `chatIsNearBottom` — a small slack so a
+ * reader who is essentially at the bottom keeps following new messages, while
+ * one who has scrolled up to read history is left where they are.
+ */
+const NEAR_BOTTOM_PX = 80;
+/**
+ * The group-chat view of the workspace announcement feed (the "Chat" tab).
+ *
+ * The API returns announcements newest-first, but a chat reads oldest -> newest
+ * top -> bottom, so the list is reversed before render; messages are filtered to
+ * the selected repo. Each row mirrors app.js `renderAnnouncements`: an avatar
+ * (initials + deterministic color), the sender, an optional "→ @target" /
+ * "→ admin" header, the relative time, and the body. Operator messages
+ * (`fromAdmin`) get `msg--me` (right-aligned); directed or to-admin messages get
+ * `msg--targeted`.
+ *
+ * The viewer stays pinned to the newest message UNLESS they have scrolled up to
+ * read history — measured against the scroll container before each re-render and
+ * re-applied in a layout effect so the write happens before paint (no flicker).
+ *
+ * @param props - The feed, the repo filter, and the server clock.
+ * @returns The scrollable chat element.
+ */
+export function Chat({ announcements, selectedRepo, nowMs }) {
+    const chatRef = useRef(null);
+    // Capture "were we near the bottom?" BEFORE React commits the new DOM, so the
+    // layout effect can decide whether to re-pin. A ref (not state) because it's a
+    // pre-paint measurement, never rendered.
+    const stickRef = useRef(true);
+    const c = chatRef.current;
+    if (c) {
+        stickRef.current = c.scrollHeight - c.scrollTop - c.clientHeight < NEAR_BOTTOM_PX;
+    }
+    // The API returns newest-first; a chat reads oldest -> newest, top -> bottom.
+    // Only show messages whose repo matches the current selection.
+    const messages = [...announcements]
+        .filter((a) => matchesRepo(a, selectedRepo))
+        .reverse();
+    // Keep the viewer pinned to the newest message unless they've scrolled up to
+    // read history. useLayoutEffect so the scroll write lands before paint.
+    useLayoutEffect(() => {
+        if (stickRef.current && chatRef.current) {
+            chatRef.current.scrollTop = chatRef.current.scrollHeight;
+        }
+    }, [messages.length]);
+    return (_jsx("div", { id: "chat", className: "chat", ref: chatRef, children: messages.length === 0 ? (_jsx("div", { className: "empty", children: "No announcements yet \u2014 agents will post here as they coordinate." })) : (messages.map((a, i) => {
+            const targeted = a.targetAgentName !== null || a.toAdmin;
+            const className = "msg" +
+                (targeted ? " msg--targeted" : "") +
+                (a.fromAdmin ? " msg--me" : "");
+            return (
+            // The feed has no stable id; index is acceptable because the list is
+            // append-only oldest->newest and rows are never reordered in place.
+            _jsxs("div", { className: className, children: [_jsx("div", { className: "msg__avatar", style: { background: colorForName(a.fromAgentName) }, children: initialsFor(a.fromAgentName) }), _jsxs("div", { className: "msg__body", children: [_jsxs("div", { className: "msg__head", children: [_jsx("span", { className: "msg__who", style: { color: colorForName(a.fromAgentName) }, children: a.fromAgentName }), a.fromHuman ? _jsx("span", { className: "msg__human", children: a.fromHuman }) : null, a.targetAgentName !== null ? (_jsx("span", { className: "msg__to", children: `→ @${a.targetAgentName}` })) : a.toAdmin ? (_jsx("span", { className: "msg__to", children: "\u2192 admin" })) : null, _jsx("span", { className: "msg__time", children: formatRelative(a.createdAt, nowMs) })] }), _jsx("div", { className: "msg__text", children: a.body })] })] }, i));
+        })) }));
+}

package/dist/components/Composer.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+import type { WorkspaceAgentT } from "@shepherd/shared";
+/** Props for {@link Composer}. */
+export interface ComposerProps {
+    /** Workspace agents; the live ones in the selected repo drive @-autocomplete. */
+    agents: WorkspaceAgentT[];
+    /** The board's selected repo; `null`/`"__all__"` broadcast to every repo. */
+    selectedRepo: string | null;
+    /**
+     * Workspace to post into. When given, submit goes through the plural
+     * `announceTo(id, …)` route; when omitted it uses the singular self-host
+     * `announce(…)` alias, so an unscoped composer is unchanged.
+     */
+    workspaceId?: string;
+    /** Invoked after a successful send so the host can refresh the feed. */
+    onSent: () => void | Promise<void>;
+}
+/**
+ * The operator's message composer (the "Chat" tab footer). A controlled input
+ * with an @-mention autocomplete and a send button, ported from app.js
+ * `setupComposer` + `renderPop`.
+ *
+ * As the operator types, the token immediately left of the caret is parsed; if
+ * it is an `@mention`, a `role="listbox"` of live agents in the selected repo
+ * opens. ArrowUp/ArrowDown move the highlight, Enter/Tab (or a mousedown on a
+ * row) accept it — inserting `"@Name "` — and Escape closes it. On submit a
+ * blank body is ignored; otherwise the first mention matching a known agent
+ * directs the message (`targetAgentName`) and the selected repo scopes a
+ * broadcast (`null` in All-repos mode). The send button is disabled in-flight;
+ * on success the input clears and `onSent` is awaited, on failure a
+ * "send failed — retry" status shows and the button re-enables. The client comes
+ * from context, keeping the composer auth-agnostic.
+ *
+ * @param props - The agents, repo filter, and post-send callback.
+ * @returns The composer element (autocomplete popup + form).
+ */
+export declare function Composer({ agents, selectedRepo, workspaceId, onSent }: ComposerProps): ReactNode;