create-theokit 1.21.0 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/surfaces/tui/README-surface.md.tmpl

@@ -24,3 +24,48 @@ npm run dev                      # tsx tui/main.tsx
 ```
 
 Type a message + Enter; Esc to quit. The agent lives in `agents/chat.ts` (edit its model / system prompt).
+
+## Architecture (System Design)
+
+The TUI surface is a small React (Ink) app with ONE composition root and three presentational pieces.
+
+### Component tree
+
+```
+tui/main.tsx                       render(<App/>, { exitOnCtrlC: false })
+└─ tui/App.tsx                     COMPOSITION ROOT — owns useAgent + state + key routing
+   ├─ components/Banner.tsx        welcome box (wordmark · model · cwd · tips) — presentational
+   ├─ <AgentTimeline/>             the conversation (from @theokit/tui)
+   ├─ components/UsagePanel.tsx    /usage: ContextWindowBar · TokenUsageChart · CostMeter — prop-driven
+   ├─ components/Demos.tsx         /plan /ask /select /progress showcase — DELETABLE (see below)
+   └─ <ChatComposer/> | <PermissionPrompt/>   the input area (composer, or a gated-tool approval card)
+```
+
+### Data flow
+
+```
+you type ─▶ App.handleSubmit ─▶ agent.send() ─▶ InProcessTransport ─▶ streamAgentTurnInProcess (theokit)
+                                                                              │  UIMessageStream
+useAgent().thread ◀───────────────────────────────────────────────────────────┘
+   │  messagesToAgentEvents (ai-free projection, M46)          readTurnUsage
+   ▼                                                                │
+<AgentTimeline/>                                            lastUsage ─▶ footer + <UsagePanel/>
+```
+
+### Layer boundaries
+
+| Layer | Owns | The surface imports it as |
+|---|---|---|
+| `shared/agent.ts` | branding (name · model label · greeting · contextWindow) — **single source of truth** | `AGENT` (Banner + App) |
+| `agents/chat.ts` | the agent's model + system prompt (persona) | `chatAgent` (the transport) |
+| `server/` (via `theokit`) | the in-process runtime (`streamAgentTurnInProcess`) | one import |
+| `tui/` | the terminal surface (this folder) | — |
+
+The surface never imports `ai` — `@theokit/tui` renders the conversation structurally; only theokit's runtime touches the stream.
+
+### Extension points
+
+- **Restyle** → `tui/theme.ts` (accent, banner wordmark/copy, spinner words, placeholder) — one file, no component edits.
+- **Rebrand** → `shared/agent.ts` (name · greeting · model label · contextWindow).
+- **Change behavior** → `agents/chat.ts` (model + system prompt).
+- **Delete the demos** → remove `tui/components/Demos.tsx`, the `<DemoSurface>` branch in `App.tsx`, the 4 demo entries in the `<ChatComposer commands>` list, and the `/plan|/ask|/select|/progress` cases in `handleSubmit`. Everything else keeps working.

package/templates/surfaces/tui/tui/App.tsx.tmpl

@@ -1,7 +1,5 @@
-import { homedir } from 'node:os'
-
-import { Box, Text, useApp, useInput } from 'ink'
-import { type ReactElement, useState } from 'react'
+import { Text, useApp, useInput } from 'ink'
+import { type ReactElement, useCallback, useState } from 'react'
 import {
   AgentStreaming,
   AgentTimeline,
@@ -14,8 +12,10 @@ import {
   Notice,
   PermissionPrompt,
   readTurnUsage,
+  Stack,
   StatusFooter,
   TheoTUIProvider,
+  Toast,
   useTurnElapsed,
   type UIMessageLike,
 } from '@theokit/tui'
@@ -24,23 +24,14 @@ import { streamAgentTurnInProcess } from 'theokit/server/agent'
 
 import * as chatAgent from '../agents/chat.js'
 import { AGENT } from '../shared/agent.js'
-// Everything visual (accent, banner wordmark + copy, spinner words, placeholder) lives in ONE file —
-// edit `tui/theme.ts` to restyle; this component never needs touching for a rebrand.
-import {
-  ACCENT,
-  BANNER_TIPS,
-  BANNER_WHATS_NEW,
-  LOGO,
-  PLACEHOLDER,
-  THEME,
-  THINKING_PHRASES,
-  WIDE_COLS,
-} from './theme.js'
+// Composed from `tui/components/*`; restyle everything in the ONE file `tui/theme.ts`.
+import { Banner } from './components/Banner.js'
+import { DemoSurface, type Mode, type ToastPayload } from './components/Demos.js'
+import { UsagePanel } from './components/UsagePanel.js'
+import { PLACEHOLDER, THEME, THINKING_PHRASES } from './theme.js'
 
-/** Shown in the status bar (from `shared/agent.ts`). */
+/** Model label (footer) — from `shared/agent.ts`, the single branding source. */
 const MODEL = AGENT.model
-/** cwd with the home dir tildeified (`~/…`), so the banner line stays short. */
-const CWD = process.cwd().replace(homedir(), '~')
 /** Compact token count for the footer: `128000 → 128k`, `12300 → 12.3k`, `462 → 462`. */
 const fmtK = (n: number): string =>
   n >= 1000 ? `${(Math.round(n / 100) / 10).toString().replace(/\.0$/, '')}k` : `${n}`
@@ -56,113 +47,32 @@ const GREETING: UIMessageLike = {
 const apiKey = (): string =>
   process.env.OPENROUTER_API_KEY ?? process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? ''
 
-/**
- * The terminal surface, composed from `@theokit/tui` the way a Claude Code / OpenCode / Codex CLI is:
- * `WelcomeBanner` header, a scrolling `<AgentTimeline>` (assistant turns rendered as Markdown + fenced code,
- * tool calls as collapsible cards, thinking rows — the Claude-Code render), a live `<AgentStreaming>` spinner,
- * a bordered `<ChatComposer>`, and a persistent `<AppStatusBar>` footer. Driven by the unified `useAgent`
- * hook (M41).
- *
- * The conversation comes from `useAgent().thread` (M46), projected to the timeline's `AgentEvent[]` by the
- * ai-free `messagesToAgentEvents` — so this terminal surface never imports the `ai` SDK. Prepend the greeting.
- */
+// The unified in-process transport (M41): each turn drives the agent through `streamAgentTurnInProcess`.
 const transport = new InProcessTransport({
   run: (input) => streamAgentTurnInProcess(chatAgent, apiKey(), input),
 })
 
-/** The app name — `{{name}}` is substituted at scaffold time. */
-const APP_NAME = '{{name}}'
-
-/**
- * The Claude-Code welcome box: a full-width rounded accent border with margins on every side. On a wide
- * terminal it lays out two columns — left is the `Theo` wordmark + a `✻` welcome line + model + cwd; right
- * is the getting-started tips + what's new. Below `WIDE_COLS` it collapses to a single column.
- */
-function Banner(): ReactElement {
-  const cols = process.stdout.columns ?? 80
-  const wide = cols >= WIDE_COLS
-  return (
-    <Box
-      // Full width, with a one-cell margin on every side.
-      width={cols - 2}
-      marginX={1}
-      marginY={1}
-      paddingX={2}
-      paddingY={1}
-      borderStyle="round"
-      borderColor={ACCENT}
-      flexDirection="row"
-    >
-      {/* Fixed-width left column (fits the 34-wide wordmark) so a long cwd truncates instead of pushing
-          the right column off-screen — the box stays full width, the content stays grouped on the left. */}
-      <Box flexDirection="column" width={38} flexShrink={0}>
-        <Text color={ACCENT}>{LOGO}</Text>
-        <Box marginTop={1} flexDirection="column">
-          <Text color={ACCENT} bold wrap="truncate-end">
-            ✻ Welcome to {APP_NAME}
-          </Text>
-          <Text dimColor wrap="truncate-end">
-            {MODEL}
-          </Text>
-          <Text dimColor wrap="truncate-start">
-            cwd: {CWD}
-          </Text>
-        </Box>
-      </Box>
-      {wide ? (
-        <Box flexDirection="column" flexShrink={0} marginLeft={4}>
-          <Text color={ACCENT} bold>
-            Tips for getting started
-          </Text>
-          <Box marginTop={1} flexDirection="column">
-            {BANNER_TIPS.map((tip) => (
-              <Text key={tip} dimColor>
-                {tip}
-              </Text>
-            ))}
-          </Box>
-          <Box marginTop={1} flexDirection="column">
-            <Text color={ACCENT} bold>
-              What&apos;s new
-            </Text>
-            <Box marginTop={1} flexDirection="column">
-              {BANNER_WHATS_NEW.map((line) => (
-                <Text key={line} dimColor>
-                  {line}
-                </Text>
-              ))}
-            </Box>
-          </Box>
-        </Box>
-      ) : null}
-    </Box>
-  )
-}
-
+/** The surface's composition root: owns state (`useAgent` M41 + mode) and composes the components under `<Stack>`. */
 export function App(): ReactElement {
   const agent = useAgent<{ message: string }>(transport)
   const streaming = agent.status === 'streaming'
   const elapsed = useTurnElapsed(streaming)
   const { exit } = useApp()
   const [showHelp, setShowHelp] = useState(false)
-  // Ctrl+C is a two-step quit (Claude Code): the first press arms the exit + shows a hint, the second
-  // quits. Any other key disarms. `render(<App/>, { exitOnCtrlC: false })` in main.tsx hands us Ctrl+C.
+  // Ctrl+C is a two-step quit (Claude Code): first press arms + hints, second quits; any other key disarms.
   const [exitArmed, setExitArmed] = useState(false)
-  // Approval ids already decided — the `approval-requested` part is a STANDALONE gate that never flips to
-  // a resolved state (it is keyed by its own id, distinct from the tool call), so we remember settled ids
-  // to hide the prompt once answered instead of re-showing it forever.
+  // Settled approval ids — the gate never flips to resolved, so we hide answered prompts by id.
   const [settledApprovals, setSettledApprovals] = useState<readonly string[]>([])
-
-  // The store owns the conversation (M46) — prepend the warm greeting and project to timeline events.
+  // Composer mode (`chat` = composer; others swap it for a `<DemoSurface>`), `/usage` toggle, `<Toast>`.
+  const [mode, setMode] = useState<Mode>('chat')
+  const [showUsage, setShowUsage] = useState(false)
+  const [toast, setToast] = useState<ToastPayload | null>(null)
+  // Stable so the `/progress` timer effect (in ProgressDemo) never restarts on an unrelated re-render.
+  const backToChat = useCallback(() => setMode('chat'), [])
+
+  // Derived from the store (M46): timeline events (greeting prepended), the last turn's usage, HITL approval.
   const events = messagesToAgentEvents([GREETING, ...agent.thread])
-
-  // The last turn's usage (readTurnUsage reads the totals the agent stream rides on each assistant
-  // message's metadata) drives the streaming token count + the footer's context usage. Undefined until
-  // the first turn reports usage.
   const lastUsage = agent.thread.map(readTurnUsage).filter((u) => u !== undefined).at(-1)
-
-  // Human-in-the-loop: a gated tool (`send_notification`) pauses the run awaiting a decision. When one is
-  // pending (and not already settled) we show the approval prompt IN PLACE OF the composer and settle it.
   const rawApproval = findPendingApproval(agent.thread)
   const pendingApproval =
     rawApproval && !settledApprovals.includes(rawApproval.approvalId) ? rawApproval : undefined
@@ -172,13 +82,15 @@ export function App(): ReactElement {
     void agent.approve(approvalId, { approved })
   }
 
-  // Global keys. While a gated tool awaits approval, the `<PermissionPrompt>` owns the keys (↑/↓/Enter/Esc)
-  // — stay out of its way. Otherwise: Esc cancels a running turn / closes help; Ctrl+C cancels a turn, else
-  // arms → quits on a second press. The ChatComposer owns editing keys (/, @, !, ?, ↑↓, emacs chords).
+  const inDemoInput = mode === 'plan' || mode === 'ask' || mode === 'select'
+
+  // Global keys — skipped while a gated tool / interactive demo owns input. Esc backs out; Ctrl+C cancels/quits.
   useInput((input, key) => {
-    if (pendingApproval) return
+    if (pendingApproval || inDemoInput) return
     if (key.escape) {
-      if (showHelp) setShowHelp(false)
+      if (mode === 'progress') setMode('chat')
+      else if (showUsage) setShowUsage(false)
+      else if (showHelp) setShowHelp(false)
       else if (streaming) agent.abort()
       return
     }
@@ -197,43 +109,65 @@ export function App(): ReactElement {
   const handleSubmit = (text: string): void => {
     const trimmed = text.trim()
     if (trimmed.length === 0) return
-    if (trimmed === '/clear') {
-      agent.reset()
-      return
-    }
-    if (trimmed === '/help') {
-      setShowHelp((h) => !h)
-      return
+    switch (trimmed) {
+      case '/clear':
+        agent.reset()
+        return
+      case '/help':
+        setShowHelp((h) => !h)
+        return
+      case '/usage':
+        setShowUsage((u) => !u)
+        return
+      case '/plan':
+        setMode('plan')
+        return
+      case '/ask':
+        setMode('ask')
+        return
+      case '/select':
+        setMode('select')
+        return
+      case '/progress':
+        setMode('progress')
+        return
+      default:
+        agent.send({ message: trimmed })
     }
-    agent.send({ message: trimmed })
   }
 
   return (
     <TheoTUIProvider theme={THEME}>
-      {/* InkInputProvider bridges Ink's stdin to @theokit/tui's interactive surfaces (PermissionPrompt's
-          numbered choice menu) so they receive keys under plain Ink — the ChatComposer keeps Ink's own hooks. */}
+      {/* InkInputProvider bridges Ink stdin to the interactive surfaces; `Stack` gives the Claude-Code cadence. */}
       <InkInputProvider>
-        <Box flexDirection="column">
-        <Banner />
-
-        <AgentTimeline events={events} />
-
-        {streaming ? (
-          <AgentStreaming
-            phrases={THINKING_PHRASES}
-            shimmer
-            elapsedSeconds={elapsed}
-            tokens={lastUsage?.totalTokens}
-            tokenDirection="down"
-            showCancelHint
-          />
-        ) : null}
-        {agent.error ? <Notice variant="error">{agent.error.message}</Notice> : null}
-
-        {showHelp ? <KeyboardHelp shortcuts={DEFAULT_COMPOSER_SHORTCUTS} /> : null}
-
-        {/* A one-line top margin separates the input (or the approval prompt) from the conversation above. */}
-        <Box marginTop={1} flexDirection="column">
+        <Stack gap={1}>
+          <Banner />
+
+          <AgentTimeline events={events} />
+
+          {streaming ? (
+            <AgentStreaming
+              phrases={THINKING_PHRASES}
+              shimmer
+              elapsedSeconds={elapsed}
+              tokens={lastUsage?.totalTokens}
+              tokenDirection="down"
+              showCancelHint
+            />
+          ) : null}
+          {agent.error ? <Notice variant="error">{agent.error.message}</Notice> : null}
+          {/* `/usage` — the observability panel, from the last turn's real usage. */}
+          {showUsage && lastUsage ? (
+            <UsagePanel usage={lastUsage} contextWindow={AGENT.contextWindow} />
+          ) : null}
+          {/* A transient outcome banner (a demo answered, a task finished). Auto-dismisses after 5s. */}
+          {toast ? (
+            <Toast message={toast.message} variant={toast.variant} onDismiss={() => setToast(null)} />
+          ) : null}
+
+          {showHelp ? <KeyboardHelp shortcuts={DEFAULT_COMPOSER_SHORTCUTS} /> : null}
+
+          {/* The input area: a gated tool's approval card, a demo surface, or the composer. */}
           {pendingApproval ? (
             <PermissionPrompt
               toolType="Tool call"
@@ -244,12 +178,18 @@ export function App(): ReactElement {
                   : undefined
               }
               onDecision={(decision) => {
-                // PermissionPrompt's default choices are `yes`/`no` (Esc → the last one, `no`, the safe
-                // default). Only `yes` approves. Settle (remembering the id so the standalone gate part
-                // stops re-showing) and forward the decision to the client.
+                // Default choices are `yes`/`no` (Esc → `no`, the safe default); only `yes` approves.
                 settleApproval(pendingApproval.approvalId, decision === 'yes')
               }}
             />
+          ) : mode !== 'chat' ? (
+            <DemoSurface
+              mode={mode}
+              elapsed={elapsed}
+              tokens={lastUsage?.totalTokens}
+              onComplete={backToChat}
+              onToast={setToast}
+            />
           ) : (
             <ChatComposer
               placeholder={PLACEHOLDER}
@@ -258,27 +198,30 @@ export function App(): ReactElement {
               commands={[
                 { name: 'clear', description: 'clear the conversation' },
                 { name: 'help', description: 'toggle the keyboard shortcuts panel' },
+                { name: 'usage', description: 'toggle the token-usage panel' },
+                { name: 'plan', description: 'demo: plan approval card' },
+                { name: 'ask', description: 'demo: question prompt' },
+                { name: 'select', description: 'demo: multi-select list' },
+                { name: 'progress', description: 'demo: multi-step progress' },
               ]}
               onHelpToggle={() => setShowHelp((h) => !h)}
               onSubmit={handleSubmit}
             />
           )}
-        </Box>
 
-        {/* Claude Code's two-line footer: top-left the model, top-right the context usage; bottom the
-            shortcuts hint. `StatusFooter` justifies the top row to the terminal edges. */}
-        <StatusFooter
-          left={<Text>{MODEL}</Text>}
-          right={
-            lastUsage ? (
-              <Text>
-                {fmtK(lastUsage.inputTokens)}/{fmtK(AGENT.contextWindow)} context
-              </Text>
-            ) : undefined
-          }
-          hint="? for shortcuts"
-        />
-        </Box>
+          {/* Claude Code's two-line footer: model (left) · context usage (right) · shortcuts hint (bottom). */}
+          <StatusFooter
+            left={<Text>{MODEL}</Text>}
+            right={
+              lastUsage ? (
+                <Text>
+                  {fmtK(lastUsage.inputTokens)}/{fmtK(AGENT.contextWindow)} context
+                </Text>
+              ) : undefined
+            }
+            hint="? for shortcuts"
+          />
+        </Stack>
       </InkInputProvider>
     </TheoTUIProvider>
   )

package/templates/surfaces/tui/tui/components/Banner.tsx.tmpl

@@ -0,0 +1,81 @@
+import { homedir } from 'node:os'
+
+import { Box, Text } from 'ink'
+import { type ReactElement } from 'react'
+
+import { AGENT } from '../../shared/agent.js'
+// The banner reads its visual tokens from the ONE restyle file — edit `tui/theme.ts` to rebrand.
+import { ACCENT, BANNER_TIPS, BANNER_WHATS_NEW, LOGO, WIDE_COLS } from '../theme.js'
+
+/** The app name — `{{name}}` is substituted at scaffold time. */
+const APP_NAME = '{{name}}'
+/** Model display label (from `shared/agent.ts` — the single branding source). */
+const MODEL = AGENT.model
+/** cwd with the home dir tildeified (`~/…`), so the banner line stays short. */
+const CWD = process.cwd().replace(homedir(), '~')
+
+/**
+ * The Claude-Code welcome box: a full-width rounded accent border with margins on every side. On a wide
+ * terminal it lays out two columns — left is the `Theo` wordmark + a `✻` welcome line + model + cwd; right
+ * is the getting-started tips + what's new. Below `WIDE_COLS` it collapses to a single column.
+ */
+export function Banner(): ReactElement {
+  const cols = process.stdout.columns ?? 80
+  const wide = cols >= WIDE_COLS
+  return (
+    <Box
+      // Full width, with a one-cell margin on every side.
+      width={cols - 2}
+      marginX={1}
+      marginY={1}
+      paddingX={2}
+      paddingY={1}
+      borderStyle="round"
+      borderColor={ACCENT}
+      flexDirection="row"
+    >
+      {/* Fixed-width left column (fits the 34-wide wordmark) so a long cwd truncates instead of pushing
+          the right column off-screen — the box stays full width, the content stays grouped on the left. */}
+      <Box flexDirection="column" width={38} flexShrink={0}>
+        <Text color={ACCENT}>{LOGO}</Text>
+        <Box marginTop={1} flexDirection="column">
+          <Text color={ACCENT} bold wrap="truncate-end">
+            ✻ Welcome to {APP_NAME}
+          </Text>
+          <Text dimColor wrap="truncate-end">
+            {MODEL}
+          </Text>
+          <Text dimColor wrap="truncate-start">
+            cwd: {CWD}
+          </Text>
+        </Box>
+      </Box>
+      {wide ? (
+        <Box flexDirection="column" flexShrink={0} marginLeft={4}>
+          <Text color={ACCENT} bold>
+            Tips for getting started
+          </Text>
+          <Box marginTop={1} flexDirection="column">
+            {BANNER_TIPS.map((tip) => (
+              <Text key={tip} dimColor>
+                {tip}
+              </Text>
+            ))}
+          </Box>
+          <Box marginTop={1} flexDirection="column">
+            <Text color={ACCENT} bold>
+              What&apos;s new
+            </Text>
+            <Box marginTop={1} flexDirection="column">
+              {BANNER_WHATS_NEW.map((line) => (
+                <Text key={line} dimColor>
+                  {line}
+                </Text>
+              ))}
+            </Box>
+          </Box>
+        </Box>
+      ) : null}
+    </Box>
+  )
+}

package/templates/surfaces/tui/tui/components/Demos.tsx.tmpl

@@ -0,0 +1,179 @@
+import { Box, Text } from 'ink'
+import { type ReactElement, useEffect, useState } from 'react'
+import {
+  MultiStepProgress,
+  PlanApproval,
+  ProgressActivity,
+  ProgressBar,
+  QuestionPrompt,
+  SelectList,
+  type SelectListItem,
+  type TodoItem,
+} from '@theokit/tui'
+
+/**
+ * ────────────────────────────────────────────────────────────────────────────────────────────────
+ *  tui/components/Demos.tsx — the slash-command showcase.
+ *
+ *  A live tour of the interactive `@theokit/tui@0.40.0` surfaces, reachable from the composer:
+ *    /plan     → PlanApproval      /ask      → QuestionPrompt
+ *    /select   → SelectList        /progress → MultiStepProgress + ProgressActivity + ProgressBar
+ *
+ *  Everything demo-only lives HERE — to drop the showcase from your app, delete this file and the
+ *  `<DemoSurface>` branch + the `/plan|/ask|/select|/progress` cases in `App.tsx`.
+ * ────────────────────────────────────────────────────────────────────────────────────────────────
+ */
+
+/** The composer mode — `chat` shows the composer; the others swap it for a live demo surface. */
+export type Mode = 'chat' | 'plan' | 'ask' | 'select' | 'progress'
+
+/** A transient outcome the app surfaces as a `<Toast>`. */
+export interface ToastPayload {
+  message: string
+  variant: 'info' | 'success' | 'error'
+}
+
+const DEMO_PLAN = [
+  '## Proposed plan',
+  '',
+  '1. Scaffold the `reports` route',
+  '2. Add the `generateReport` server action',
+  '3. Stream results into the dashboard',
+].join('\n')
+
+const DEMO_ASK_OPTIONS: readonly SelectListItem[] = [
+  { value: 'python', label: 'Python (FastAPI)', description: 'polyglot service via --backend python' },
+  { value: 'node', label: 'Node (Hono)', description: 'fetch-handler service' },
+  { value: 'none', label: 'TypeScript only', description: 'no external backend' },
+]
+
+const DEMO_SELECT_ITEMS: readonly SelectListItem[] = [
+  { value: 'auth', label: 'Auth', description: 'sessions + requireAuth' },
+  { value: 'db', label: 'Database', description: 'SQLite by default' },
+  { value: 'ws', label: 'WebSocket', description: 'realtime channel' },
+  { value: 'deploy', label: 'Deploy', description: 'TheoCloud target' },
+]
+
+const DEMO_STEP_LABELS = ['Plan', 'Generate', 'Validate', 'Ship'] as const
+
+/**
+ * The `/progress` demo owns its OWN step counter + 700ms timer (an implementation detail, not app state).
+ * It advances one step per tick, then calls `onComplete` (back to chat) + `onToast`. `onComplete`/`onToast`
+ * must be stable (the parent passes a `useCallback` + the stable `setToast`) so the timer effect re-runs on
+ * `step` only — never restarting mid-run on an unrelated parent re-render.
+ */
+function ProgressDemo({
+  elapsed,
+  tokens,
+  onComplete,
+  onToast,
+}: {
+  elapsed: number
+  tokens: number | undefined
+  onComplete: () => void
+  onToast: (t: ToastPayload) => void
+}): ReactElement {
+  const [step, setStep] = useState(0)
+
+  useEffect(() => {
+    if (step >= DEMO_STEP_LABELS.length) {
+      const done = setTimeout(() => {
+        onComplete()
+        onToast({ message: 'Task complete', variant: 'success' })
+      }, 600)
+      return () => clearTimeout(done)
+    }
+    const tick = setTimeout(() => setStep((s) => s + 1), 700)
+    return () => clearTimeout(tick)
+  }, [step, onComplete, onToast])
+
+  const steps: readonly TodoItem[] = DEMO_STEP_LABELS.map((label, i) => ({
+    id: label,
+    label,
+    status: i < step ? 'done' : i === step ? 'active' : 'pending',
+  }))
+  const percent = Math.min(100, Math.round((step / DEMO_STEP_LABELS.length) * 100))
+
+  return (
+    <Box flexDirection="column">
+      <MultiStepProgress steps={steps} current={step} groupLabel="Demo task" />
+      <ProgressActivity
+        label="Working…"
+        percent={percent}
+        elapsedSeconds={elapsed}
+        tokens={tokens}
+        tokenDirection="up"
+      />
+      <ProgressBar percent={percent} />
+      <Text dimColor>esc to exit</Text>
+    </Box>
+  )
+}
+
+/**
+ * Renders the demo surface for a non-`chat` `mode`, IN PLACE OF the composer. Each interactive demo
+ * completes back to chat via `onComplete` and reports its outcome via `onToast`.
+ */
+export function DemoSurface({
+  mode,
+  elapsed,
+  tokens,
+  onComplete,
+  onToast,
+}: {
+  mode: Exclude<Mode, 'chat'>
+  elapsed: number
+  tokens: number | undefined
+  onComplete: () => void
+  onToast: (t: ToastPayload) => void
+}): ReactElement {
+  switch (mode) {
+    case 'plan':
+      return (
+        <PlanApproval
+          plan={DEMO_PLAN}
+          onDecision={(d) => {
+            onComplete()
+            onToast({
+              message:
+                d.kind === 'approve'
+                  ? 'Plan approved'
+                  : `Revision requested${d.feedback ? `: ${d.feedback}` : ''}`,
+              variant: 'success',
+            })
+          }}
+        />
+      )
+    case 'ask':
+      return (
+        <QuestionPrompt
+          header="Backend"
+          question="Which backend should the app ship next to?"
+          options={DEMO_ASK_OPTIONS}
+          allowFreeText
+          onAnswer={(a) => {
+            onComplete()
+            onToast({
+              message: `Answered: ${a.values.join(', ')}${a.text ? ` (${a.text})` : ''}`,
+              variant: 'info',
+            })
+          }}
+        />
+      )
+    case 'select':
+      return (
+        <SelectList
+          items={DEMO_SELECT_ITEMS}
+          multi
+          onSubmit={(values) => {
+            onComplete()
+            onToast({ message: `Selected: ${values.join(', ') || '(none)'}`, variant: 'info' })
+          }}
+        />
+      )
+    case 'progress':
+      return (
+        <ProgressDemo elapsed={elapsed} tokens={tokens} onComplete={onComplete} onToast={onToast} />
+      )
+  }
+}

package/templates/surfaces/tui/tui/components/UsagePanel.tsx.tmpl

@@ -0,0 +1,37 @@
+import { Box } from 'ink'
+import { type ReactElement } from 'react'
+import {
+  ContextWindowBar,
+  CostMeter,
+  type TokenCategory,
+  TokenUsageChart,
+  type TurnUsage,
+} from '@theokit/tui'
+
+/**
+ * The `/usage` observability panel, built from the last turn's REAL usage (never fabricated). `ContextWindowBar`
+ * shows the context fill (`used/limit`), `TokenUsageChart` the per-category breakdown, `CostMeter` the session
+ * cost — the last only when the turn actually reported one. Toggle it with `/usage` in the composer.
+ */
+export function UsagePanel({
+  usage,
+  contextWindow,
+}: {
+  usage: TurnUsage
+  contextWindow: number
+}): ReactElement {
+  // Only PRESENT categories render in the chart — build the map from whatever the turn actually reported.
+  const chart: Partial<Record<TokenCategory, number>> = {
+    input: usage.inputTokens,
+    output: usage.outputTokens,
+    ...(usage.cacheReadTokens !== undefined ? { cached: usage.cacheReadTokens } : {}),
+    ...(usage.reasoningTokens !== undefined ? { reasoning: usage.reasoningTokens } : {}),
+  }
+  return (
+    <Box flexDirection="column">
+      <ContextWindowBar usedTokens={usage.inputTokens} limitTokens={contextWindow} />
+      <TokenUsageChart usage={chart} />
+      {usage.cost !== undefined ? <CostMeter costUsd={usage.cost} /> : null}
+    </Box>
+  )
+}