@spunto/design-system 0.32.1 → 0.34.0

package/README.md

@@ -304,9 +304,10 @@ review. Every surface that shows one:
   an organization as a messaging app's list: search, state chips whose counts ignore
   the filter, grouped rows. Fully controlled. Sized by `pointer-coarse`, not width.
 - **`TaskCockpit`** / **`TaskCockpitMobile`** — one conversation, as a **layout**: top
-  bar + Accept/Drop, the Session/Diff switch, and where each slot goes. The panels are
-  slots filled with the package's own components (`session`/`diff` are render
-  functions receiving the switch to draw in their header). The phone one is its own
+  bar + Accept/Drop, the Session/Diff/Terminal switch, and where each slot goes. The
+  panels are slots filled with the package's own components (`session`/`diff`/`terminal`
+  are render functions receiving the switch to draw in their header; an omitted slot is
+  no tab). The phone one is its own
   screen — a `visualViewport`-sized layer, details in a sheet, Drop at the bottom.
 - **`TaskEventStream`** — the agent session (RFC 0020): prose first, tool calls folded
   into runs ("read 8 files · ran 3 commands"), the session-wide tool stack in a sheet,
@@ -315,6 +316,9 @@ review. Every surface that shows one:
 - **`TaskDiffPanel`** — the branch's diff: summary as a prop, each file's patch through
   `loadPatch` (a promise; the component owns per-file loading state), intra-line
   highlighting, and a sentence for every reason it could not be read.
+- **`TaskTerminalPanel`** — the frame of the Terminal tab: the header with the switch,
+  optional `actions`, and a dark surface for the app's own shell (the socket is the
+  app's), or a sentence saying why there is none. No composer under it.
 - **`TaskDetails`** (`sidebar` | `sheet`) with **`TaskMachine`**, **`TaskBoot`**,
   `TaskSessionUsage`, `TaskPullRequest`, `TaskCommandLog` — the facts about a task, in
   one order, instead of two hand-kept copies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/tasks/event-stream.tsx

@@ -381,10 +381,17 @@ function useTimeline(events: TaskEvent[]) {
     let lastMessage = ""
 
     for (const event of events) {
-      if (event.type === "raw" || event.type === "usage" || event.type === "session.title") {
+      if (
+        event.type === "raw" ||
+        event.type === "usage" ||
+        event.type === "session.title" ||
+        event.type === "session.background"
+      ) {
         // `usage` is a fact about the whole session, not a moment in it — the sidebar shows it.
         // `session.title` is the same kind of fact: the name the session gave itself, already
-        // read at the top of the page as the task's own title.
+        // read at the top of the page as the task's own title. `session.background` too: what
+        // the harness still runs behind the turn, which the task's state already accounts for —
+        // the call that started it is on the timeline as a tool call.
         if (event.type === "raw") raw.push(event)
         continue
       }

package/src/components/tasks/index.ts

@@ -79,6 +79,8 @@ export {
 // ── Side panels ─────────────────────────────────────────────────────────────────────────────
 export { TaskDiffPanel } from "./diff-panel"
 export type { TaskDiffPanelProps } from "./diff-panel"
+export { TaskTerminalPanel } from "./terminal-panel"
+export type { TaskTerminalPanelProps } from "./terminal-panel"
 export { TaskPullRequest } from "./pull-request"
 export { TaskSessionUsage, formatCost, formatTokens } from "./session-usage"
 export { TaskCommandLog } from "./command-log"

package/src/components/tasks/task-cockpit-mobile.tsx

@@ -23,7 +23,7 @@ import { CheckCircle2Icon, ChevronLeftIcon, Loader2Icon, SlidersHorizontalIcon,
 import { cn, formatRelativeTime } from "../../utils"
 import { useOverlayContainer } from "../spunto-provider"
 import type { LinkRender } from "../workers/worker-card"
-import { TaskPanelTabs, useCockpitView, type TaskCockpitProps } from "./task-cockpit"
+import { useCockpitPanels, type TaskCockpitProps } from "./task-cockpit"
 import { TaskDetailsSheetContext } from "./task-details"
 import { TaskStateIcon, taskPendingActionConfig, taskStateStyle, useElapsed } from "./task-state"
 import { TaskTitle } from "./task-title"
@@ -173,6 +173,7 @@ export function TaskCockpitMobile({
   onViewChange,
   session,
   diff,
+  terminal,
   composer,
   details,
   fullscreen = true,
@@ -181,12 +182,11 @@ export function TaskCockpitMobile({
   const vp = useVisualViewport(fullscreen)
   const container = useOverlayContainer()
   const [detailsOpen, setDetailsOpen] = useState(false)
-  const [view, setView] = useCockpitView(viewProp, onViewChange)
+  const { view, panel } = useCockpitPanels({ view: viewProp, onViewChange, session, diff, terminal })
   const Link = render?.link ?? defaultLink
 
   const action = task ? (pendingAction !== undefined ? pendingAction : (task.pendingAction ?? null)) : null
   const since = task ? (pendingSince !== undefined ? pendingSince : (task.pendingSince ?? null)) : null
-  const tabs = diff ? <TaskPanelTabs view={view} onChange={setView} /> : null
 
   const back = onBack ? (
     <button type="button" onClick={onBack} aria-label="Back" className={NAV_BUTTON}>
@@ -260,8 +260,8 @@ export function TaskCockpitMobile({
         )
       ) : (
         <>
-          {view === "diff" && diff ? diff(tabs) : session(tabs)}
-          {composer && <div style={{ paddingBottom: fullscreen && vp.keyboard === 0 ? "env(safe-area-inset-bottom)" : 0 }}>{composer}</div>}
+          {panel()}
+          {composer && view !== "terminal" && <div style={{ paddingBottom: fullscreen && vp.keyboard === 0 ? "env(safe-area-inset-bottom)" : 0 }}>{composer}</div>}
         </>
       )}
 

package/src/components/tasks/task-cockpit.tsx

@@ -12,11 +12,12 @@
 //
 //   session  → `TaskEventStream`       diff     → `TaskDiffPanel`
 //   composer → `TaskComposer`          details  → `TaskDetails` (with a `TaskMachine` inside)
+//   terminal → `TaskTerminalPanel` (around the app's own shell)
 //
 // — and the cockpit owns the chrome between them: the top bar and its two actions, the
-// Session/Diff switch, and where each slot goes as the box narrows. `session` and `diff` are
-// render functions because the switch is drawn *inside* their header strip (two strips of chrome
-// above a transcript is one too many).
+// Session/Diff/Terminal switch, and where each slot goes as the box narrows. `session`, `diff` and
+// `terminal` are render functions because the switch is drawn *inside* their header strip (two
+// strips of chrome above a transcript is one too many).
 //
 // It claims no page chrome of its own — it fills its parent — which is what lets the same code
 // live at its own URL and on the right-hand side of the org-wide conversation list. On a phone,
@@ -33,7 +34,9 @@ import { TaskStateBadge, isLiveTaskState } from "./task-state"
 import { TaskTitle } from "./task-title"
 import type { TaskItem, TaskPendingAction } from "./types"
 
-export type TaskCockpitView = "session" | "diff"
+export type TaskCockpitView = "session" | "diff" | "terminal"
+
+const VIEW_ORDER: readonly TaskCockpitView[] = ["session", "diff", "terminal"]
 
 export interface TaskCockpitProps {
   /** `undefined`/`null` → the loading line, or the not-found message once `loading` is false. */
@@ -59,15 +62,25 @@ export interface TaskCockpitProps {
   backHref?: string
   render?: { link?: LinkRender }
 
-  /** Controlled Session/Diff switch. Uncontrolled (starting on `session`) when omitted. */
+  /** Controlled Session/Diff/Terminal switch. Uncontrolled (starting on `session`) when omitted. */
   view?: TaskCockpitView
   onViewChange?: (view: TaskCockpitView) => void
 
-  /** The session panel. Receives the Session/Diff switch to draw in its header. */
+  /** The session panel. Receives the switch to draw in its header. */
   session: (tabs: ReactNode) => ReactNode
-  /** The diff panel. Omitted → no switch, the session alone. */
+  /** The diff panel. Omitted → no Diff tab. */
   diff?: (tabs: ReactNode) => ReactNode
-  /** Under both panels: answering the agent is something a reviewer does *because* of the diff. */
+  /**
+   * A shell on the task's machine — typically a `TaskTerminalPanel` around the app's own terminal,
+   * since the socket behind it is the app's. Omitted → no Terminal tab (a task with no machine has
+   * nothing to open one on). With neither `diff` nor `terminal`, no switch at all: the session alone.
+   */
+  terminal?: (tabs: ReactNode) => ReactNode
+  /**
+   * Under the session and the diff: answering the agent is something a reviewer does *because* of
+   * the diff. Not under the terminal — it has a keyboard of its own, and two places to type,
+   * stacked, is one too many.
+   */
   composer?: ReactNode
   /** The side column. */
   details?: ReactNode
@@ -81,22 +94,25 @@ const defaultLink: LinkRender = ({ href, className, children }) => (
 )
 
 /**
- * The two ways of looking at a task, in the strip each panel already owns. A tab rather than a
- * second column: "what it did" and "what is different now" are two frames of mind, and splitting
- * the width would make both unreadable in a sidebar-sized column.
+ * The ways of looking at a task, in the strip each panel already owns. A tab rather than a second
+ * column: "what it did", "what is different now" and "let me look myself" are three frames of
+ * mind, and splitting the width would make each unreadable in a sidebar-sized column.
  */
 export function TaskPanelTabs({
   view,
   onChange,
+  views = ["session", "diff"],
   className,
 }: {
   view: TaskCockpitView
   onChange: (view: TaskCockpitView) => void
+  /** Which tabs to draw, in this order. Defaults to Session/Diff. */
+  views?: readonly TaskCockpitView[]
   className?: string
 }) {
   return (
     <div role="tablist" className={cn("flex shrink-0 items-center gap-0.5 rounded-md bg-muted/60 p-0.5", className)}>
-      {(["session", "diff"] as const).map((value) => (
+      {views.map((value) => (
         <button
           key={value}
           type="button"
@@ -115,7 +131,28 @@ export function TaskPanelTabs({
   )
 }
 
-/** The view state, controlled or not — shared with `TaskCockpitMobile`. @internal */
+/**
+ * The panels this cockpit has, the switch between them, and the one to draw — shared with
+ * `TaskCockpitMobile`. A view whose slot went away (the machine was released while its terminal
+ * was open) falls back to the session rather than to an empty box. @internal
+ */
+export function useCockpitPanels({
+  view: viewProp,
+  onViewChange,
+  session,
+  diff,
+  terminal,
+}: Pick<TaskCockpitProps, "view" | "onViewChange" | "session" | "diff" | "terminal">) {
+  const [view, setView] = useCockpitView(viewProp, onViewChange)
+  const slots: Record<TaskCockpitView, ((tabs: ReactNode) => ReactNode) | undefined> = { session, diff, terminal }
+  const views = VIEW_ORDER.filter((v) => slots[v])
+  const current = slots[view] ? view : "session"
+  const tabs = views.length > 1 ? <TaskPanelTabs view={current} onChange={setView} views={views} /> : null
+  // A thunk, not the element: the cockpit asks for it only once there is a task to draw.
+  return { view: current, panel: () => (slots[current] ?? session)(tabs) }
+}
+
+/** The view state, controlled or not. @internal */
 export function useCockpitView(view: TaskCockpitView | undefined, onViewChange: ((view: TaskCockpitView) => void) | undefined) {
   const [local, setLocal] = useState<TaskCockpitView>("session")
   const current = view ?? local
@@ -141,11 +178,12 @@ export function TaskCockpit({
   onViewChange,
   session,
   diff,
+  terminal,
   composer,
   details,
   className,
 }: TaskCockpitProps) {
-  const [view, setView] = useCockpitView(viewProp, onViewChange)
+  const { view, panel } = useCockpitPanels({ view: viewProp, onViewChange, session, diff, terminal })
   const Link = render?.link ?? defaultLink
 
   if (!task) {
@@ -171,7 +209,6 @@ export function TaskCockpit({
   const since = pendingSince !== undefined ? pendingSince : (task.pendingSince ?? null)
   const busy = action !== null
   const live = isLiveTaskState(task.state)
-  const tabs = diff ? <TaskPanelTabs view={view} onChange={setView} /> : null
 
   return (
     <div className={cn("@container flex min-h-0 flex-1 flex-col overflow-hidden", className)}>
@@ -226,8 +263,8 @@ export function TaskCockpit({
             column holds long mono lines and <pre> blocks. Without it the column refuses to shrink
             and pushes the details column past the edge, where `overflow-hidden` clips it. */}
         <div className="flex min-h-[280px] min-w-0 flex-1 flex-col border-border @min-[42rem]:border-r">
-          {view === "diff" && diff ? diff(tabs) : session(tabs)}
-          {composer}
+          {panel()}
+          {view !== "terminal" && composer}
         </div>
 
         {details && (

package/src/components/tasks/tasks.test.tsx

@@ -5,6 +5,7 @@
  * The timeline itself is virtualized and measures real layout, which jsdom does not have; what it
  * draws is covered by the pure functions it folds events with.
  */
+import type { ReactNode } from "react"
 import { describe, it, expect, vi } from "vitest"
 import { render, screen, fireEvent } from "@testing-library/react"
 
@@ -337,3 +338,47 @@ describe("TaskTitle", () => {
     expect(onTitleChange).toHaveBeenCalledWith("Safari 18 login")
   })
 })
+
+describe("TaskCockpit panels", () => {
+  const panel = (name: string) => (tabs: ReactNode) => (
+    <div>
+      {tabs}
+      <p>{name} panel</p>
+    </div>
+  )
+
+  it("draws no switch with the session alone", () => {
+    render(<TaskCockpit task={task()} session={panel("session")} />)
+    expect(screen.queryByRole("tablist")).toBeNull()
+  })
+
+  it("offers only the tabs it has a panel for, in a fixed order", () => {
+    render(<TaskCockpit task={task()} session={panel("session")} terminal={panel("terminal")} />)
+    expect(screen.getAllByRole("tab").map((t) => t.textContent)).toEqual(["session", "terminal"])
+  })
+
+  it("switches to the terminal, and leaves the composer behind", () => {
+    render(
+      <TaskCockpit
+        task={task()}
+        session={panel("session")}
+        diff={panel("diff")}
+        terminal={panel("terminal")}
+        composer={<p>composer</p>}
+      />,
+    )
+    expect(screen.getAllByRole("tab").map((t) => t.textContent)).toEqual(["session", "diff", "terminal"])
+    fireEvent.click(screen.getByRole("tab", { name: "terminal" }))
+    expect(screen.getByText("terminal panel")).toBeTruthy()
+    expect(screen.queryByText("composer")).toBeNull()
+    fireEvent.click(screen.getByRole("tab", { name: "diff" }))
+    expect(screen.getByText("composer")).toBeTruthy()
+  })
+
+  it("falls back to the session when the open view's panel goes away", () => {
+    const { rerender } = render(<TaskCockpit task={task()} view="terminal" session={panel("session")} terminal={panel("terminal")} />)
+    expect(screen.getByText("terminal panel")).toBeTruthy()
+    rerender(<TaskCockpit task={task()} view="terminal" session={panel("session")} />)
+    expect(screen.getByText("session panel")).toBeTruthy()
+  })
+})

package/src/components/tasks/terminal-panel.tsx

@@ -0,0 +1,51 @@
+"use client"
+
+// A shell on the task's machine, in the cockpit's third tab.
+//
+// The frame only: the header strip every cockpit panel owns (so the Session/Diff/Terminal switch
+// sits where it sits on the other two), and a dark box under it. What goes in the box is the
+// app's — a pty at the other end of a socket, persistent sessions, a clipboard — none of which a
+// design system can open. Without it, the box says why there is nothing to type into.
+//
+// Same surface as `TerminalPanel` (#09090b), so the switch from a light transcript to a shell
+// reads as "a terminal", not as a broken theme.
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+export interface TaskTerminalPanelProps {
+  /** The Session/Diff/Terminal switch, from the cockpit's render function. */
+  tabs?: ReactNode
+  /** Right of the switch — a way out to the full worker page, a full-screen button on a phone. */
+  actions?: ReactNode
+  /** The shell. Omitted → `placeholder`, on the same dark surface. */
+  children?: ReactNode
+  /** Why there is no shell (yet). */
+  placeholder?: ReactNode
+  className?: string
+}
+
+export function TaskTerminalPanel({
+  tabs,
+  actions,
+  children,
+  placeholder = "The machine is not running — there is nothing to open a shell on.",
+  className,
+}: TaskTerminalPanelProps) {
+  return (
+    <div className={cn("flex min-h-0 flex-1 flex-col", className)}>
+      <div className="flex shrink-0 items-center gap-2 border-b border-border bg-card px-4 py-2">
+        {tabs ?? <h2 className="text-xs font-medium">Terminal</h2>}
+        {actions && <div className="ml-auto flex shrink-0 items-center gap-2">{actions}</div>}
+      </div>
+      <div className="flex min-h-0 flex-1 flex-col bg-[#09090b]">
+        {children ?? (
+          <div className="flex flex-1 items-center justify-center px-6 text-center">
+            <p className="max-w-sm font-mono text-xs text-[#71717a]">{placeholder}</p>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/tasks/types.ts

@@ -56,7 +56,7 @@ export interface TaskConversation extends TaskItem {
 export interface TaskEvent {
   seq: number
   ts: string
-  /** `message` | `thinking` | `plan` | `tool.call` | `tool.result` | `session.started` | `session.ended` | `usage` | `session.title` | `raw` … */
+  /** `message` | `thinking` | `plan` | `tool.call` | `tool.result` | `session.started` | `session.ended` | `usage` | `session.title` | `session.background` | `raw` … */
   type: string
   payload: Record<string, unknown>
 }