division-ds 0.4.0 → 0.4.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Division DS: instructions for coding agents
 
-A React 19 + Tailwind 4 + Radix design system: 74 components, tokens in three layers, light and
+A React 19 + Tailwind 4 + Radix design system: 75 components, tokens in three layers, light and
 dark themes, WCAG 2.2 AA. This file is the entry point. It is short on purpose; everything it
 points to is generated from the code, so it is current.
 
@@ -51,7 +51,7 @@ installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rul
 `.claude/skills/` (Claude Code).
 
 An agent that supports MCP can have the docs and the same checks as tools instead:
-`claude mcp add division-ds -- npx -y division-ds@0.3.1 mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.4.0 mcp` (`list_components`, `get_component`,
 `search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
 `get_review_checklist`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Checks a project that uses Division DS components (raw colours, invented tokens, touching buttons, unknown props), and serves the docs and the same checks to agents over MCP.",
   "license": "MIT",
   "author": "Victor Ilioiu",

package/public/docs/components/terminal.md

@@ -0,0 +1,405 @@
+# Terminal
+
+> A live terminal session in the page, built on xterm.js. It renders the output you write to it and reports what the person types. It knows nothing about the connection: your app owns that.
+
+- **Best for:** A live, interactive process that needs real terminal behaviour: colour, cursor movement, full-screen programs.
+- **Not for:** Static code or a finished log: use CodeBlock. A conversation shown as messages: use ChatThread.
+- Organism. Source: `src/components/organisms/terminal/Terminal.tsx`
+- Rendered docs page: `/components/terminal`
+
+## Import
+
+```tsx
+import { Terminal } from 'src/components/organisms/terminal/Terminal'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file. An install has no index barrels: import each component from its own file, never from `components/molecules`.
+
+## Requires
+
+- Import it from its own file and load the screen that uses it with React.lazy. It adds about 100 kB of JavaScript after gzip (about 380 kB before) and 1 kB of CSS, so it is not in the organisms barrel.
+- A height. It is 24rem by default; set another with className (h-[32rem]), or flex-1 inside a column.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. What this session is ("Build agent"). Names the terminal, its input and its status announcements. |
+| `status` | `'connecting' \| 'live' \| 'reconnecting' \| 'exited' \| 'error'` |  | Required. connecting and reconnecting are info, live is ok, exited is neutral for code 0 and hostile otherwise, error is hostile. Buffered output stays visible in all of them. |
+| `exitCode` | `number` |  | With status exited: shown beside the word, and a non-zero code turns it hostile. |
+| `statusMessage` | `string` |  | Detail beside the status, and announced with it: the reason for an error, the attempt while reconnecting. |
+| `readOnly` | `boolean` | `false` | Blocks input and never fires onData. Selecting and copying keep working, and Tab and Escape leave the terminal as they do anywhere else. |
+| `announceOutput` | `boolean` | `false` | Reads output aloud through xterm’s live region, up to 20 lines at a time. For a single session a screen reader user is working in. Leave it off when several terminals share a page. |
+| `onData` | `(data: string) => void` |  | What the person typed or pasted, plus the replies a program asks the terminal for. Send it to the process. |
+| `onResize` | `(size: { cols: number; rows: number }) => void` |  | The new grid size, debounced by 100ms and only when cols or rows changed. It fires once after mounting. |
+| `scrollback` | `number` | `5000` | Lines kept above the screen. xterm’s own default is 1000, which a busy agent passes in seconds. |
+| `className` | `string` |  | Merged onto the frame. Set the height here. |
+| `ref` | `Ref<TerminalHandle>` |  | The handle with the four methods below. |
+| `write (TerminalHandle)` | `(data: string \| Uint8Array, callback?: () => void) => void` |  | Sends output to the terminal, without a React render. The callback runs when it has been parsed: use it for flow control, because xterm throws data away past 50 MB waiting. |
+| `clear (TerminalHandle)` | `() => void` |  | Clears the screen and the scrollback, keeping the line the cursor is on. |
+| `focus (TerminalHandle)` | `() => void` |  | Moves keyboard focus into the terminal. |
+| `fit (TerminalHandle)` | `() => void` |  | Fits the grid to the frame now. Resizing already does this. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type TerminalStatus = 'connecting' | 'live' | 'reconnecting' | 'exited' | 'error'
+```
+
+```ts
+export type TerminalHandle = {
+  /** Sends output to the terminal, without a React render. The callback runs once it is parsed: use it for flow control. */
+  write(data: string | Uint8Array, callback?: () => void): void
+  /** Clears the screen and the scrollback, keeping the cursor's line. */
+  clear(): void
+  /** Moves keyboard focus into the terminal. */
+  focus(): void
+  /** Fits the grid to the container now. Resizing already does this; use it after a change no resize reports. */
+  fit(): void
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Connecting
+
+```tsx
+<Terminal label="Build agent" status="connecting" className="h-40 max-w-3xl" />
+```
+
+### Live, with a simulated stream
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+const STREAM = ['compiling', 'linking', 'checking types', 'running tests', 'writing bundle']
+
+function LiveDemo() {
+  const term = useRef<TerminalHandle>(null)
+  const [streaming, setStreaming] = useState(false)
+
+  useEffect(() => {
+    term.current?.write(`${TRANSCRIPT}Type here, or start the stream.\r\n$ `)
+  }, [])
+
+  useEffect(() => {
+    if (!streaming) return
+    let line = 0
+    const timer = window.setInterval(() => {
+      const step = STREAM[line % STREAM.length]
+      const code = 31 + (line % 6)
+      term.current?.write(`${paint(code, `[${String(line + 1).padStart(3, '0')}]`)} ${step}\r\n`)
+      line += 1
+      if (line === 40) setStreaming(false)
+    }, 120)
+    return () => window.clearInterval(timer)
+  }, [streaming])
+
+  return (
+    <div className="flex max-w-3xl flex-col gap-3">
+      <Terminal
+        ref={term}
+        label="Sample build"
+        status="live"
+        className="h-80"
+        onData={data => term.current?.write(data === '\r' ? '\r\n$ ' : data)}
+      />
+      <div className="flex flex-wrap gap-3">
+        <Button variant="secondary" onClick={() => setStreaming(on => !on)}>{streaming ? 'Stop the stream' : 'Start the stream'}</Button>
+        <Button variant="secondary" onClick={() => term.current?.clear()}>Clear</Button>
+      </div>
+    </div>
+  )
+}
+
+<LiveDemo />
+```
+
+### Read only: select and copy, but no typing
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
+  const term = useRef<TerminalHandle>(null)
+  useEffect(() => term.current?.write(TRANSCRIPT), [])
+  return <Terminal ref={term} className="h-64 max-w-3xl" {...props} />
+}
+
+<SampleTerminal label="Deploy log" status="live" readOnly />
+```
+
+### Reconnecting, with the output kept
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
+  const term = useRef<TerminalHandle>(null)
+  useEffect(() => term.current?.write(TRANSCRIPT), [])
+  return <Terminal ref={term} className="h-64 max-w-3xl" {...props} />
+}
+
+<SampleTerminal label="Test agent" status="reconnecting" statusMessage="Attempt 2 of 5" />
+```
+
+### Exited with code 0
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
+  const term = useRef<TerminalHandle>(null)
+  useEffect(() => term.current?.write(TRANSCRIPT), [])
+  return <Terminal ref={term} className="h-64 max-w-3xl" {...props} />
+}
+
+<SampleTerminal label="Migration" status="exited" exitCode={0} readOnly />
+```
+
+### Exited with an error code
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
+  const term = useRef<TerminalHandle>(null)
+  useEffect(() => term.current?.write(TRANSCRIPT), [])
+  return <Terminal ref={term} className="h-64 max-w-3xl" {...props} />
+}
+
+<SampleTerminal label="Type check" status="exited" exitCode={2} readOnly />
+```
+
+### Connection error
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
+  const term = useRef<TerminalHandle>(null)
+  useEffect(() => term.current?.write(TRANSCRIPT), [])
+  return <Terminal ref={term} className="h-64 max-w-3xl" {...props} />
+}
+
+<SampleTerminal label="Review agent" status="error" statusMessage="The connection was refused." readOnly />
+```
+
+### Switching theme updates the colours and keeps the buffer
+
+```tsx
+const ESC = '\u001b'
+
+const paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`
+
+const COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]
+  .map(code => paint(code, `${code} `.padEnd(4)))
+  .join('')
+
+const TRANSCRIPT = [
+  paint(1, 'Sample session, written by this page'),
+  '┌──────────────────────────────┐',
+  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,
+  '└──────────────────────────────┘',
+  COLOURS,
+  'Docs at https://example.com/terminal',
+  '',
+].join('\r\n')
+
+function SampleTerminal(props: Omit<TerminalProps, 'ref'>) {
+  const term = useRef<TerminalHandle>(null)
+  useEffect(() => term.current?.write(TRANSCRIPT), [])
+  return <Terminal ref={term} className="h-64 max-w-3xl" {...props} />
+}
+
+<div className="flex max-w-3xl flex-col gap-3">
+  <SampleTerminal label="Theme check" status="live" readOnly />
+  <div className="flex flex-wrap gap-3">
+    <Button variant="secondary" onClick={() => setTheme('light')}>Light theme</Button>
+    <Button variant="secondary" onClick={() => setTheme('dark')}>Dark theme</Button>
+  </div>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | From the page, moves into the terminal. Inside it, goes to the program, unless readOnly is set, when it moves on. |
+| `Ctrl` `Shift` `L` | Moves focus out of the terminal to the next tab stop. Tab and Escape belong to the program, so this is the way out. |
+| `Ctrl` `C` | With text selected, copies it and clears the selection. With nothing selected, goes to the program as an interrupt. |
+| `Ctrl` `Shift` `C` | Copies the selection and keeps it. |
+| `Ctrl` `V` | Pastes. Ctrl+Shift+V does the same. A program that wants a literal Ctrl+V does not get it. |
+
+## Do
+
+- Give each terminal a label that says which session it is, so a page of them can be told apart.
+- Set readOnly when nobody can usefully type: a finished process, a session someone else owns.
+- Say why in statusMessage when status is error.
+- Use write’s callback to pause the source when output arrives faster than the page can draw it.
+
+## Don't
+
+- Don’t import it from the organisms barrel, and don’t load it on a screen that does not show it.
+- Don’t put a terminal inside another bordered panel; it brings its own frame.
+- Don’t keep output in React state to pass down. Write it through the ref.
+- Don’t expect the status to block input by itself: set readOnly when a process has exited.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Terminal label="Agent" status="live" output={text} />
+```
+
+Right:
+
+```tsx
+const term = useRef<TerminalHandle>(null)
+const socket = useRef<WebSocket>(null)
+const [status, setStatus] = useState<TerminalStatus>('connecting')
+
+useEffect(() => {
+  const ws = new WebSocket(url)
+  ws.binaryType = 'arraybuffer'
+  socket.current = ws
+  ws.onopen = () => setStatus('live')
+  ws.onmessage = event =>
+    term.current?.write(typeof event.data === 'string' ? event.data : new Uint8Array(event.data))
+  ws.onclose = () => setStatus('reconnecting')
+  return () => ws.close()
+}, [url])
+
+<Terminal
+  ref={term}
+  label="Build agent"
+  status={status}
+  onData={data => socket.current?.send(data)}
+  onResize={size => socket.current?.send(JSON.stringify({ type: 'resize', ...size }))}
+/>
+```
+
+Output goes through the ref, so a fast stream never re-renders React. The connection lives in your app, not in the component.
+
+Wrong:
+
+```tsx
+<Suspense fallback={null}><LazyTerminal ref={term} ... /></Suspense>  // with the socket in this component's effect
+```
+
+Right:
+
+```tsx
+const Screen = lazy(() => import('./AgentScreen'))  // AgentScreen imports Terminal directly and owns the socket
+```
+
+If only the Terminal is lazy, your effect runs while the ref is still empty and the first output is lost. Lazy-load the screen that holds both.
+
+## Anatomy
+
+- **Frame**: A Panel on surface.base, which is the surface all sixteen ANSI colours are measured on. It shows the focus ring while the terminal has focus.
+- **Title bar**: The label, the status Badge with a word and a tone, a Read only Badge when set, statusMessage, and the shortcut that leaves the terminal.
+- **Status announcement**: A visually hidden status region. It says only the label and the status, so a screen reader hears changes and not output.
+- **Grid**: xterm.js in the mono font, fitted to the frame. Colours are read from tokens at runtime and updated when the theme changes, keeping the buffer.
+- **Screen reader rows**: xterm’s accessibility tree: the visible rows as a list a screen reader can browse. Scrolling the terminal changes which rows it holds.

package/public/manifest/components.json

@@ -12041,6 +12041,242 @@
         }
       ],
       "closed": true
+    },
+    {
+      "name": "Terminal",
+      "title": "Terminal",
+      "tier": "organisms",
+      "slug": "terminal",
+      "summary": "A live terminal session in the page, built on xterm.js. It renders the output you write to it and reports what the person types. It knows nothing about the connection: your app owns that.",
+      "useWhen": "A live, interactive process that needs real terminal behaviour: colour, cursor movement, full-screen programs.",
+      "notFor": "Static code or a finished log: use CodeBlock. A conversation shown as messages: use ChatThread.",
+      "source": "src/components/organisms/terminal/Terminal.tsx",
+      "docs": "/docs/components/terminal.md",
+      "imports": [
+        {
+          "names": [
+            "Terminal"
+          ],
+          "from": "src/components/organisms/terminal/Terminal"
+        }
+      ],
+      "requires": [
+        "Import it from its own file and load the screen that uses it with React.lazy. It adds about 100 kB of JavaScript after gzip (about 380 kB before) and 1 kB of CSS, so it is not in the organisms barrel.",
+        "A height. It is 24rem by default; set another with className (h-[32rem]), or flex-1 inside a column."
+      ],
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "description": "Required. What this session is (\"Build agent\"). Names the terminal, its input and its status announcements."
+        },
+        {
+          "name": "status",
+          "type": "'connecting' | 'live' | 'reconnecting' | 'exited' | 'error'",
+          "description": "Required. connecting and reconnecting are info, live is ok, exited is neutral for code 0 and hostile otherwise, error is hostile. Buffered output stays visible in all of them."
+        },
+        {
+          "name": "exitCode",
+          "type": "number",
+          "description": "With status exited: shown beside the word, and a non-zero code turns it hostile."
+        },
+        {
+          "name": "statusMessage",
+          "type": "string",
+          "description": "Detail beside the status, and announced with it: the reason for an error, the attempt while reconnecting."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "default": "false",
+          "description": "Blocks input and never fires onData. Selecting and copying keep working, and Tab and Escape leave the terminal as they do anywhere else."
+        },
+        {
+          "name": "announceOutput",
+          "type": "boolean",
+          "default": "false",
+          "description": "Reads output aloud through xterm’s live region, up to 20 lines at a time. For a single session a screen reader user is working in. Leave it off when several terminals share a page."
+        },
+        {
+          "name": "onData",
+          "type": "(data: string) => void",
+          "description": "What the person typed or pasted, plus the replies a program asks the terminal for. Send it to the process."
+        },
+        {
+          "name": "onResize",
+          "type": "(size: { cols: number; rows: number }) => void",
+          "description": "The new grid size, debounced by 100ms and only when cols or rows changed. It fires once after mounting."
+        },
+        {
+          "name": "scrollback",
+          "type": "number",
+          "default": "5000",
+          "description": "Lines kept above the screen. xterm’s own default is 1000, which a busy agent passes in seconds."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Merged onto the frame. Set the height here."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<TerminalHandle>",
+          "description": "The handle with the four methods below."
+        },
+        {
+          "name": "write (TerminalHandle)",
+          "type": "(data: string | Uint8Array, callback?: () => void) => void",
+          "description": "Sends output to the terminal, without a React render. The callback runs when it has been parsed: use it for flow control, because xterm throws data away past 50 MB waiting."
+        },
+        {
+          "name": "clear (TerminalHandle)",
+          "type": "() => void",
+          "description": "Clears the screen and the scrollback, keeping the line the cursor is on."
+        },
+        {
+          "name": "focus (TerminalHandle)",
+          "type": "() => void",
+          "description": "Moves keyboard focus into the terminal."
+        },
+        {
+          "name": "fit (TerminalHandle)",
+          "type": "() => void",
+          "description": "Fits the grid to the frame now. Resizing already does this."
+        }
+      ],
+      "api": [
+        {
+          "name": "TerminalStatus",
+          "kind": "type",
+          "code": "export type TerminalStatus = 'connecting' | 'live' | 'reconnecting' | 'exited' | 'error'",
+          "from": "src/components/organisms/terminal/Terminal"
+        },
+        {
+          "name": "TerminalHandle",
+          "kind": "type",
+          "code": "export type TerminalHandle = {\n  /** Sends output to the terminal, without a React render. The callback runs once it is parsed: use it for flow control. */\n  write(data: string | Uint8Array, callback?: () => void): void\n  /** Clears the screen and the scrollback, keeping the cursor's line. */\n  clear(): void\n  /** Moves keyboard focus into the terminal. */\n  focus(): void\n  /** Fits the grid to the container now. Resizing already does this; use it after a change no resize reports. */\n  fit(): void\n}",
+          "from": "src/components/organisms/terminal/Terminal"
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "Tab"
+          ],
+          "does": "From the page, moves into the terminal. Inside it, goes to the program, unless readOnly is set, when it moves on."
+        },
+        {
+          "keys": [
+            "Ctrl",
+            "Shift",
+            "L"
+          ],
+          "does": "Moves focus out of the terminal to the next tab stop. Tab and Escape belong to the program, so this is the way out."
+        },
+        {
+          "keys": [
+            "Ctrl",
+            "C"
+          ],
+          "does": "With text selected, copies it and clears the selection. With nothing selected, goes to the program as an interrupt."
+        },
+        {
+          "keys": [
+            "Ctrl",
+            "Shift",
+            "C"
+          ],
+          "does": "Copies the selection and keeps it."
+        },
+        {
+          "keys": [
+            "Ctrl",
+            "V"
+          ],
+          "does": "Pastes. Ctrl+Shift+V does the same. A program that wants a literal Ctrl+V does not get it."
+        }
+      ],
+      "dos": [
+        "Give each terminal a label that says which session it is, so a page of them can be told apart.",
+        "Set readOnly when nobody can usefully type: a finished process, a session someone else owns.",
+        "Say why in statusMessage when status is error.",
+        "Use write’s callback to pause the source when output arrives faster than the page can draw it."
+      ],
+      "donts": [
+        "Don’t import it from the organisms barrel, and don’t load it on a screen that does not show it.",
+        "Don’t put a terminal inside another bordered panel; it brings its own frame.",
+        "Don’t keep output in React state to pass down. Write it through the ref.",
+        "Don’t expect the status to block input by itself: set readOnly when a process has exited."
+      ],
+      "pitfalls": [
+        {
+          "wrong": "<Terminal label=\"Agent\" status=\"live\" output={text} />",
+          "right": "const term = useRef<TerminalHandle>(null)\nconst socket = useRef<WebSocket>(null)\nconst [status, setStatus] = useState<TerminalStatus>('connecting')\n\nuseEffect(() => {\n  const ws = new WebSocket(url)\n  ws.binaryType = 'arraybuffer'\n  socket.current = ws\n  ws.onopen = () => setStatus('live')\n  ws.onmessage = event =>\n    term.current?.write(typeof event.data === 'string' ? event.data : new Uint8Array(event.data))\n  ws.onclose = () => setStatus('reconnecting')\n  return () => ws.close()\n}, [url])\n\n<Terminal\n  ref={term}\n  label=\"Build agent\"\n  status={status}\n  onData={data => socket.current?.send(data)}\n  onResize={size => socket.current?.send(JSON.stringify({ type: 'resize', ...size }))}\n/>",
+          "why": "Output goes through the ref, so a fast stream never re-renders React. The connection lives in your app, not in the component."
+        },
+        {
+          "wrong": "<Suspense fallback={null}><LazyTerminal ref={term} ... /></Suspense>  // with the socket in this component's effect",
+          "right": "const Screen = lazy(() => import('./AgentScreen'))  // AgentScreen imports Terminal directly and owns the socket",
+          "why": "If only the Terminal is lazy, your effect runs while the ref is still empty and the first output is lost. Lazy-load the screen that holds both."
+        }
+      ],
+      "anatomy": [
+        {
+          "part": "Frame",
+          "description": "A Panel on surface.base, which is the surface all sixteen ANSI colours are measured on. It shows the focus ring while the terminal has focus."
+        },
+        {
+          "part": "Title bar",
+          "description": "The label, the status Badge with a word and a tone, a Read only Badge when set, statusMessage, and the shortcut that leaves the terminal."
+        },
+        {
+          "part": "Status announcement",
+          "description": "A visually hidden status region. It says only the label and the status, so a screen reader hears changes and not output."
+        },
+        {
+          "part": "Grid",
+          "description": "xterm.js in the mono font, fitted to the frame. Colours are read from tokens at runtime and updated when the theme changes, keeping the buffer."
+        },
+        {
+          "part": "Screen reader rows",
+          "description": "xterm’s accessibility tree: the visible rows as a list a screen reader can browse. Scrolling the terminal changes which rows it holds."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Connecting",
+          "source": "<Terminal label=\"Build agent\" status=\"connecting\" className=\"h-40 max-w-3xl\" />"
+        },
+        {
+          "caption": "Live, with a simulated stream",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nconst STREAM = ['compiling', 'linking', 'checking types', 'running tests', 'writing bundle']\n\nfunction LiveDemo() {\n  const term = useRef<TerminalHandle>(null)\n  const [streaming, setStreaming] = useState(false)\n\n  useEffect(() => {\n    term.current?.write(`${TRANSCRIPT}Type here, or start the stream.\\r\\n$ `)\n  }, [])\n\n  useEffect(() => {\n    if (!streaming) return\n    let line = 0\n    const timer = window.setInterval(() => {\n      const step = STREAM[line % STREAM.length]\n      const code = 31 + (line % 6)\n      term.current?.write(`${paint(code, `[${String(line + 1).padStart(3, '0')}]`)} ${step}\\r\\n`)\n      line += 1\n      if (line === 40) setStreaming(false)\n    }, 120)\n    return () => window.clearInterval(timer)\n  }, [streaming])\n\n  return (\n    <div className=\"flex max-w-3xl flex-col gap-3\">\n      <Terminal\n        ref={term}\n        label=\"Sample build\"\n        status=\"live\"\n        className=\"h-80\"\n        onData={data => term.current?.write(data === '\\r' ? '\\r\\n$ ' : data)}\n      />\n      <div className=\"flex flex-wrap gap-3\">\n        <Button variant=\"secondary\" onClick={() => setStreaming(on => !on)}>{streaming ? 'Stop the stream' : 'Start the stream'}</Button>\n        <Button variant=\"secondary\" onClick={() => term.current?.clear()}>Clear</Button>\n      </div>\n    </div>\n  )\n}\n\n<LiveDemo />"
+        },
+        {
+          "caption": "Read only: select and copy, but no typing",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nfunction SampleTerminal(props: Omit<TerminalProps, 'ref'>) {\n  const term = useRef<TerminalHandle>(null)\n  useEffect(() => term.current?.write(TRANSCRIPT), [])\n  return <Terminal ref={term} className=\"h-64 max-w-3xl\" {...props} />\n}\n\n<SampleTerminal label=\"Deploy log\" status=\"live\" readOnly />"
+        },
+        {
+          "caption": "Reconnecting, with the output kept",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nfunction SampleTerminal(props: Omit<TerminalProps, 'ref'>) {\n  const term = useRef<TerminalHandle>(null)\n  useEffect(() => term.current?.write(TRANSCRIPT), [])\n  return <Terminal ref={term} className=\"h-64 max-w-3xl\" {...props} />\n}\n\n<SampleTerminal label=\"Test agent\" status=\"reconnecting\" statusMessage=\"Attempt 2 of 5\" />"
+        },
+        {
+          "caption": "Exited with code 0",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nfunction SampleTerminal(props: Omit<TerminalProps, 'ref'>) {\n  const term = useRef<TerminalHandle>(null)\n  useEffect(() => term.current?.write(TRANSCRIPT), [])\n  return <Terminal ref={term} className=\"h-64 max-w-3xl\" {...props} />\n}\n\n<SampleTerminal label=\"Migration\" status=\"exited\" exitCode={0} readOnly />"
+        },
+        {
+          "caption": "Exited with an error code",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nfunction SampleTerminal(props: Omit<TerminalProps, 'ref'>) {\n  const term = useRef<TerminalHandle>(null)\n  useEffect(() => term.current?.write(TRANSCRIPT), [])\n  return <Terminal ref={term} className=\"h-64 max-w-3xl\" {...props} />\n}\n\n<SampleTerminal label=\"Type check\" status=\"exited\" exitCode={2} readOnly />"
+        },
+        {
+          "caption": "Connection error",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nfunction SampleTerminal(props: Omit<TerminalProps, 'ref'>) {\n  const term = useRef<TerminalHandle>(null)\n  useEffect(() => term.current?.write(TRANSCRIPT), [])\n  return <Terminal ref={term} className=\"h-64 max-w-3xl\" {...props} />\n}\n\n<SampleTerminal label=\"Review agent\" status=\"error\" statusMessage=\"The connection was refused.\" readOnly />"
+        },
+        {
+          "caption": "Switching theme updates the colours and keeps the buffer",
+          "source": "const ESC = '\\u001b'\n\nconst paint = (code: number, text: string) => `${ESC}[${code}m${text}${ESC}[0m`\n\nconst COLOURS = [31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97]\n  .map(code => paint(code, `${code} `.padEnd(4)))\n  .join('')\n\nconst TRANSCRIPT = [\n  paint(1, 'Sample session, written by this page'),\n  '┌──────────────────────────────┐',\n  `│ ${paint(32, '✔')} tests passed   宽字符 🚀   │`,\n  '└──────────────────────────────┘',\n  COLOURS,\n  'Docs at https://example.com/terminal',\n  '',\n].join('\\r\\n')\n\nfunction SampleTerminal(props: Omit<TerminalProps, 'ref'>) {\n  const term = useRef<TerminalHandle>(null)\n  useEffect(() => term.current?.write(TRANSCRIPT), [])\n  return <Terminal ref={term} className=\"h-64 max-w-3xl\" {...props} />\n}\n\n<div className=\"flex max-w-3xl flex-col gap-3\">\n  <SampleTerminal label=\"Theme check\" status=\"live\" readOnly />\n  <div className=\"flex flex-wrap gap-3\">\n    <Button variant=\"secondary\" onClick={() => setTheme('light')}>Light theme</Button>\n    <Button variant=\"secondary\" onClick={() => setTheme('dark')}>Dark theme</Button>\n  </div>\n</div>"
+        }
+      ],
+      "closed": true
     }
   ]
 }

package/public/manifest/tokens.json

@@ -845,6 +845,174 @@
         "light": "Second chart series. 5.09:1 on surface.base, 5.41:1 on surface.raised, 5.52:1 nested. Never text. There is no third: the other hues are status colours."
       }
     },
+    {
+      "name": "--color-terminal-black",
+      "layer": "semantic",
+      "value": {
+        "dark": "#7b8592",
+        "light": "#3a4049"
+      },
+      "use": "ANSI black in the Terminal component's output. Terminal applies it; never use it outside a terminal.",
+      "measured": {
+        "dark": "Not literal black: ANSI black must stay readable on this page, so it is a grey here.",
+        "light": "Not literal black: ANSI black must stay readable on this page, so it is a grey here."
+      }
+    },
+    {
+      "name": "--color-terminal-red",
+      "layer": "semantic",
+      "value": {
+        "dark": "#ff6b5e",
+        "light": "#b3261e"
+      },
+      "use": "ANSI red in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-green",
+      "layer": "semantic",
+      "value": {
+        "dark": "#3ddc84",
+        "light": "#14713d"
+      },
+      "use": "ANSI green in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-yellow",
+      "layer": "semantic",
+      "value": {
+        "dark": "#e8b931",
+        "light": "#7a5a00"
+      },
+      "use": "ANSI yellow in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-blue",
+      "layer": "semantic",
+      "value": {
+        "dark": "#5aa7ff",
+        "light": "#0057c2"
+      },
+      "use": "ANSI blue in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-magenta",
+      "layer": "semantic",
+      "value": {
+        "dark": "#d98cf0",
+        "light": "#8a2bb0"
+      },
+      "use": "ANSI magenta in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-cyan",
+      "layer": "semantic",
+      "value": {
+        "dark": "#3fd0d8",
+        "light": "#00696f"
+      },
+      "use": "ANSI cyan in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-white",
+      "layer": "semantic",
+      "value": {
+        "dark": "#c4ccd6",
+        "light": "#5c636d"
+      },
+      "use": "ANSI white in the Terminal component's output. Terminal applies it; never use it outside a terminal.",
+      "measured": {
+        "dark": "Not literal white: ANSI white must stay readable on this page, so it is a grey here.",
+        "light": "Not literal white: ANSI white must stay readable on this page, so it is a grey here."
+      }
+    },
+    {
+      "name": "--color-terminal-bright-black",
+      "layer": "semantic",
+      "value": {
+        "dark": "#98a2af",
+        "light": "#646b75"
+      },
+      "use": "ANSI bright black in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-red",
+      "layer": "semantic",
+      "value": {
+        "dark": "#ff9288",
+        "light": "#8f1c16"
+      },
+      "use": "ANSI bright red in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-green",
+      "layer": "semantic",
+      "value": {
+        "dark": "#7debaa",
+        "light": "#0e5a30"
+      },
+      "use": "ANSI bright green in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-yellow",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f5d36a",
+        "light": "#5f4600"
+      },
+      "use": "ANSI bright yellow in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-blue",
+      "layer": "semantic",
+      "value": {
+        "dark": "#8cc2ff",
+        "light": "#00459c"
+      },
+      "use": "ANSI bright blue in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-magenta",
+      "layer": "semantic",
+      "value": {
+        "dark": "#e8b3f7",
+        "light": "#6e1f8e"
+      },
+      "use": "ANSI bright magenta in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-cyan",
+      "layer": "semantic",
+      "value": {
+        "dark": "#7fe4ea",
+        "light": "#005257"
+      },
+      "use": "ANSI bright cyan in the Terminal component's output. Terminal applies it; never use it outside a terminal."
+    },
+    {
+      "name": "--color-terminal-bright-white",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f4f7fa",
+        "light": "#16191e"
+      },
+      "use": "ANSI bright white in the Terminal component's output. Terminal applies it; never use it outside a terminal.",
+      "measured": {
+        "light": "Inverted on purpose in the light theme: the strongest ink, not a pale colour."
+      }
+    },
+    {
+      "name": "--color-terminal-selection",
+      "layer": "semantic",
+      "value": {
+        "dark": "rgba(90, 167, 255, 0.58)",
+        "light": "rgba(0, 99, 213, 0.72)"
+      },
+      "use": "The selected text wash in the Terminal component. Terminal applies it.",
+      "measured": {
+        "dark": "A wash over surface.base: at least 3:1 against the page and text.primary at 4.5:1 on it. Gated.",
+        "light": "A wash over surface.base: at least 3:1 against the page and text.primary at 4.5:1 on it. Gated."
+      }
+    },
     {
       "name": "--component-control-height-sm",
       "layer": "component",

package/scripts/lib/component-props.mjs

@@ -62,7 +62,16 @@ export function publicExports(root, tier) {
       entry[isType ? 'types' : 'values'].push(element.name.text)
     }
   }
-  return bySlug
+  return { ...bySlug, ...OUTSIDE_BARREL[tier] }
+}
+
+/** Components deliberately not re-exported by their tier's barrel, because a barrel import would
+ *  put a heavy library in every screen that imports the barrel. They are still public: their docs
+ *  page gives the direct import. */
+const OUTSIDE_BARREL = {
+  organisms: {
+    terminal: { values: ['Terminal'], types: ['TerminalHandle', 'TerminalProps', 'TerminalStatus'], from: ['./terminal/Terminal'] },
+  },
 }
 
 /** What a folder's files export, read from the type checker:

package/skills/division-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: division-ds
-description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 74 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
+description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 75 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
 ---
 
 # Division DS