{
  "schemaVersion": 1,
  "target": "react",
  "name": "terminal",
  "version": "0.1.0",
  "category": "ai-elements",
  "title": "Terminal",
  "description": "A command an agent runs with its plain text output streaming in, the exit code and duration, a copy button, and auto scroll that pauses when the reader scrolls up.",
  "tags": [
    "ai",
    "agent",
    "terminal",
    "command",
    "shell",
    "logs",
    "streaming"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [
    {
      "name": "agent-state",
      "version": "0.1.0"
    },
    {
      "name": "step-list",
      "version": "0.3.0"
    }
  ],
  "docsPath": "/components/terminal",
  "props": [
    {
      "name": "command",
      "type": "string",
      "description": "The command, shown after a $ prompt."
    },
    {
      "name": "output",
      "type": "string",
      "description": "Plain text output so far (no ANSI codes). Append to it while running."
    },
    {
      "name": "status",
      "type": "\"queued\" | \"running\" | \"success\" | \"error\"",
      "description": "Running shows the Working mark and a caret; the end states show Exit and the code."
    },
    {
      "name": "exitCode",
      "type": "number",
      "description": "Defaults to 0 on success and 1 on error."
    },
    {
      "name": "durationMs",
      "type": "number",
      "description": "Elapsed time, shown once the command ends."
    },
    {
      "name": "cwd",
      "type": "string",
      "description": "Working directory before the prompt."
    },
    {
      "name": "maxHeight",
      "type": "number",
      "default": "288",
      "description": "Output height in pixels before it scrolls."
    }
  ],
  "accessibility": [
    "The output is a focusable role log region, so keyboard users can scroll it and screen readers hear new lines politely.",
    "The status is a live region that reads Running, then Exit 0 or Exit 1; failure also turns the border and exit text red and swaps the glyph to an x.",
    "Auto scroll follows new output only while the reader is at the bottom; a Jump to latest button appears otherwise and scrolls instantly under reduced motion.",
    "The copy button is labelled Copy command and output and announces Copied. The caret blink and the Working mark hold still with reduced motion."
  ],
  "states": [
    "queued",
    "running",
    "success",
    "error"
  ],
  "files": [
    {
      "path": "agent/terminal.tsx",
      "content": "\"use client\";\n\nimport { type ComponentProps, useEffect, useLayoutEffect, useRef, useState } from \"react\";\nimport { AgentState } from \"./agent-state\";\nimport { StatusGlyph } from \"./step-list\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\n\nexport type TerminalStatus = \"queued\" | \"running\" | \"success\" | \"error\";\n\nexport interface TerminalProps extends Omit<ComponentProps<\"section\">, \"children\"> {\n  /** The command the agent runs, without the prompt. */\n  command: string;\n  /** Plain text output so far (no ANSI codes). Append to it while the command runs. */\n  output?: string;\n  status: TerminalStatus;\n  /** Exit code once the command ends. Defaults to 0 on success and 1 on error. */\n  exitCode?: number;\n  /** Elapsed time, shown once the command ends. */\n  durationMs?: number;\n  /** Working directory shown before the prompt. */\n  cwd?: string;\n  /** Output height before it scrolls, in pixels. */\n  maxHeight?: number;\n}\n\n/**\n * A command an agent runs, with its output streaming in. The output follows new lines until the\n * reader scrolls up, then a \"Jump to latest\" button brings them back. Shows the exit code,\n * duration, and a copy button once the command ends.\n */\nexport function Terminal({\n  command,\n  output = \"\",\n  status,\n  exitCode,\n  durationMs,\n  cwd,\n  maxHeight = 288,\n  className,\n  ...props\n}: TerminalProps) {\n  const running = status === \"running\";\n  const finished = status === \"success\" || status === \"error\";\n  const code = exitCode ?? (status === \"success\" ? 0 : 1);\n  const scroller = useRef<HTMLPreElement>(null);\n  const followingRef = useRef(true);\n  const [following, setFollowing] = useState(true);\n\n  useLayoutEffect(() => {\n    const element = scroller.current;\n    if (element && followingRef.current) element.scrollTop = element.scrollHeight;\n  }, [output]);\n\n  useEffect(() => {\n    const element = scroller.current;\n    if (!element) return;\n    const onScroll = () => {\n      const atBottom = element.scrollHeight - element.scrollTop - element.clientHeight < 16;\n      followingRef.current = atBottom;\n      setFollowing(atBottom);\n    };\n    element.addEventListener(\"scroll\", onScroll, { passive: true });\n    return () => element.removeEventListener(\"scroll\", onScroll);\n  }, []);\n\n  function jumpToLatest() {\n    const element = scroller.current;\n    if (!element) return;\n    followingRef.current = true;\n    setFollowing(true);\n    const reduce = window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches;\n    element.scrollTo({ top: element.scrollHeight, behavior: reduce ? \"auto\" : \"smooth\" });\n  }\n\n  return (\n    <section\n      aria-label={`Terminal: ${command}`}\n      aria-busy={running || undefined}\n      data-status={status}\n      className={cx(\n        \"overflow-hidden rounded-xl border bg-white text-left text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)]\",\n        \"transition-[border-color] duration-200 motion-reduce:transition-none\",\n        \"dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]\",\n        status === \"error\" ? \"border-red-500/35\" : \"border-zinc-950/10 dark:border-white/10\",\n        className,\n      )}\n      {...props}\n    >\n      <header className=\"flex flex-wrap items-start gap-x-3 gap-y-0.5 py-2.5 pr-2.5 pl-4\">\n        <p className=\"min-w-[min(100%,14rem)] flex-1 py-1 font-mono text-[13px] leading-5 [overflow-wrap:anywhere]\">\n          {cwd ? <span className=\"text-zinc-500\">{cwd} </span> : null}\n          <span aria-hidden=\"true\" className=\"text-zinc-400 select-none dark:text-zinc-600\">\n            ${\" \"}\n          </span>\n          <span className={status === \"queued\" ? \"text-zinc-500\" : \"text-zinc-950 dark:text-white\"}>{command}</span>\n        </p>\n        <div className=\"ml-auto flex shrink-0 items-center gap-2.5 pt-0.5\">\n          {finished && durationMs != null ? (\n            <span className={`font-mono text-xs text-zinc-500 tabular-nums transition-opacity duration-300 ${ease} starting:opacity-0 motion-reduce:transition-none`}>\n              {formatDuration(durationMs)}\n            </span>\n          ) : null}\n          {running ? (\n            <AgentState status size=\"sm\" activity=\"working\" label=\"Running\" />\n          ) : (\n            <span role=\"status\" className=\"inline-flex h-6 items-center gap-1.5 text-xs\">\n              <StatusGlyph key={status} kind={status === \"queued\" ? \"queued\" : status === \"success\" ? \"success\" : \"failed\"} />\n              <span\n                className={cx(\n                  \"font-mono tabular-nums\",\n                  status === \"error\" ? \"text-red-600 dark:text-red-400\" : status === \"queued\" ? \"text-zinc-500\" : \"text-zinc-600 dark:text-zinc-400\",\n                )}\n              >\n                {status === \"queued\" ? \"Queued\" : `Exit ${code}`}\n              </span>\n            </span>\n          )}\n          <CopyButton text={output ? `$ ${command}\\n${output}` : `$ ${command}`} label=\"Copy command and output\" />\n        </div>\n      </header>\n      {status !== \"queued\" ? (\n        <div className=\"relative border-t border-zinc-950/[0.07] dark:border-white/[0.08]\">\n          <pre\n            ref={scroller}\n            role=\"log\"\n            aria-label=\"Output\"\n            tabIndex={0}\n            className={cx(\n              \"overflow-auto px-4 py-3 font-mono text-xs leading-relaxed whitespace-pre-wrap text-zinc-700 [overflow-wrap:anywhere] dark:text-zinc-300\",\n              \"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500\",\n            )}\n            style={{ maxHeight }}\n          >\n            {output ? output : running ? <span className=\"text-zinc-500\">Waiting for output</span> : <span className=\"text-zinc-500\">No output</span>}\n            {running ? (\n              <span\n                aria-hidden=\"true\"\n                className=\"ml-px inline-block h-[1.1em] w-[0.55em] translate-y-[0.2em] bg-zinc-950/70 motion-safe:animate-pulse dark:bg-white/75\"\n              />\n            ) : null}\n          </pre>\n          {!following ? (\n            <button\n              type=\"button\"\n              onClick={jumpToLatest}\n              className={cx(\n                \"absolute bottom-2.5 left-1/2 inline-flex h-7 -translate-x-1/2 cursor-pointer items-center gap-1.5 rounded-full px-3 text-xs font-medium\",\n                \"border border-zinc-950/10 bg-white text-zinc-700 shadow-[0_4px_12px_-4px_rgb(0_0_0/0.18)] hover:text-zinc-950\",\n                \"dark:border-white/15 dark:bg-black dark:text-zinc-300 dark:shadow-[0_8px_24px_-8px_rgb(0_0_0/1)] dark:hover:text-white\",\n                `transition-[opacity,scale,color] duration-160 ${ease} starting:scale-96 starting:opacity-0 motion-reduce:transition-none`,\n                \"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n              )}\n            >\n              <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" className=\"size-3.5\">\n                <path d=\"M8 3.5v9m0 0-3.5-3.5M8 12.5l3.5-3.5\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n              </svg>\n              Jump to latest\n            </button>\n          ) : null}\n        </div>\n      ) : null}\n    </section>\n  );\n}\n\n/** An icon button that copies text and confirms with a check for 1.5s; the confirmation is announced. */\nfunction CopyButton({ text, label }: { text: string; label: string }) {\n  const [copied, setCopied] = useState(false);\n  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);\n  useEffect(() => () => clearTimeout(timer.current), []);\n\n  async function copy() {\n    try {\n      await navigator.clipboard.writeText(text);\n      setCopied(true);\n      clearTimeout(timer.current);\n      timer.current = setTimeout(() => setCopied(false), 1500);\n    } catch {\n      setCopied(false);\n    }\n  }\n\n  return (\n    <button\n      type=\"button\"\n      onClick={copy}\n      aria-label={label}\n      className={cx(\n        \"inline-flex size-7 cursor-pointer items-center justify-center rounded-md text-zinc-500\",\n        \"transition-[background-color,color,scale] duration-150 ease-out active:duration-100 motion-safe:active:scale-[0.97] motion-reduce:transition-none\",\n        \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n        \"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n      )}\n    >\n      <svg\n        key={copied ? \"copied\" : \"copy\"}\n        aria-hidden=\"true\"\n        viewBox=\"0 0 16 16\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        strokeWidth=\"1.5\"\n        strokeLinecap=\"round\"\n        strokeLinejoin=\"round\"\n        className={cx(\n          \"size-4 transition-[opacity,scale] duration-200 starting:scale-90 starting:opacity-0 motion-reduce:transition-none\",\n          ease,\n          copied && \"text-emerald-600 dark:text-emerald-400\",\n        )}\n      >\n        {copied ? (\n          <path d=\"m3.75 8.5 2.75 2.75 5.75-6.5\" />\n        ) : (\n          <>\n            <rect x=\"5.25\" y=\"5.25\" width=\"8\" height=\"8\" rx=\"1.75\" />\n            <path d=\"M10.75 5.25V3.5c0-.97-.78-1.75-1.75-1.75H3.5c-.97 0-1.75.78-1.75 1.75V9c0 .97.78 1.75 1.75 1.75h1.75\" />\n          </>\n        )}\n      </svg>\n      <span className=\"sr-only\" aria-live=\"polite\">\n        {copied ? \"Copied\" : \"\"}\n      </span>\n    </button>\n  );\n}\n\nfunction formatDuration(ms: number): string {\n  if (ms < 1000) return `${Math.round(ms)} ms`;\n  if (ms < 60_000) return `${(ms / 1000).toFixed(1)} s`;\n  const minutes = Math.floor(ms / 60_000);\n  return `${minutes}m ${Math.round((ms % 60_000) / 1000)}s`;\n}\n"
    }
  ],
  "example": {
    "content": "import { Terminal } from \"@/components/shaken/agent/terminal\";\n\nconst install = `Lockfile is up to date, resolution step is skipped\nProgress: resolved 412, reused 409, downloaded 3, added 3, done\n\ndependencies:\n+ zod 3.24.1\n\nDone in 2.3s using pnpm v10.4.1`;\n\nconst typecheck = `src/billing/proration.ts:58:11 - error TS2322: Type 'number | undefined' is not assignable to type 'number'.\n\n58     const days: number = period.days;\n             ~~~~\n\nFound 1 error in src/billing/proration.ts:58`;\n\nexport default function TerminalExample() {\n  return (\n    <div className=\"grid w-full max-w-xl gap-3\">\n      <Terminal command=\"pnpm add zod\" cwd=\"~/acme/web\" status=\"success\" output={install} durationMs={2310} />\n      <Terminal command=\"pnpm tsc --noEmit\" cwd=\"~/acme/web\" status=\"error\" exitCode={2} output={typecheck} durationMs={6840} />\n    </div>\n  );\n}\n"
  }
}
