[Epic] Agent UI as composable blocks — a first-party component library

[serge-ivo]

An agent's UI has exactly two settings today: take a whole built-in surface, or build everything yourself. Nothing in between. That canyon is why a Repo Coder — which owns one repo and is driven by its Lead — shipped with add-repo, a multi-repo list, and a duplicate way to drive an engine: declaring surfaces:["coding"] was the only way to get a terminal.

Surface options (ba415d4) patch the symptom. The cause is that surfaces are monolithic.

What an audit of the console found

The blocks are already generic, just not extractable. BoardTab literally declares GENERIC_COLUMNS and is mounted for every agent without a dedicated surface. TerminalView + render-terminal.ts (~110 LOC) have zero hooks, zero endpoints, zero router, zero context — fully controlled by props.

And they are already duplicated. The chat thread exists three times — InstanceDetail.tsx, CopilotView.tsx, AgentDetail.tsx — near line-for-line, including the same tool-call regex, the same voice pill, the same scroll-to-bottom threshold, plus CopyButton and playMessage defined twice each. There are five bespoke relative-time formatters, none using the SDK's formatTime. Two kanban boards. Two file lists. The console renders terminal output as an uncolorized <pre> while the coder colorizes it.

Every one of those is a block that wanted to be shared and had nowhere to live.

Proposed order (by extraction value)

1. Terminal — trivial, self-contained, ~110 LOC. Immediately upgrades the uncolorized <pre> on the Terminals page. Do this first.
2. ChatThread — biggest payoff: six separate duplications collapse. Needs ~200 lines lifted out of InstanceDetail and a renderMessageBody slot so the gloss layer stays out of the library.
3. RunList/Timeline — three components converge; props are already just {instanceId} and only lookup tables differ.
4. Board — one useNavigate to invert into onOpenItem, plus hoisting the apply-retry and BROWSER_TASK run form into props.
5. FileList + FilePreview — blocked only on relocating UploadJob.
6. Primitives that fall out: Modal, CopyButton, EmptyState, StatusPill — and delete the five time formatters.

There is a precedent to copy: agents/coder/web is already a workspace package with React as a peer dependency.

Blockers to settle first

• Theme tokens live only in the console (@theme in index.css). Every candidate block is saturated with bg-panel border-line text-accent. A package built outside the console emits classes with no definitions.
• Global CSS the components silently need: .msg-md, .chat-scroll, scrollbar-none.
• The Tailwind cross-package scan is a one-off hack — a literal @source "../../../agents/coder/web/src". Every new package needs another line, and no @source can ever cover a third-party bundle built outside this repo.
• alert()/confirm() inside candidate components must become injected confirm/toast.

The decision that shapes everything

See #187. Whether third-party surfaces consume React components or a DOM-mount API determines the library's entire public shape, so decide it before writing component code.

[serge-ivo]

Partially overtaken. The framing — "exactly two settings today: take a whole built-in surface, or build everything yourself. Nothing in between" — has an in-between now: capabilities.surfaceOptions. The Repo Coder example named in this issue is exactly what it fixed:

"surfaceOptions": { "coding": { "repos": "single", "drive": false, "copilot": false } }

which removes add-repo, the multi-repo list and the duplicate engine-driving path this issue cites as the motivating damage.

That does not invalidate the epic — per-surface option flags are a narrow escape hatch, not composable blocks, and each new option is still a monorepo change. But the opening argument should be updated, or the epic reads as unstarted when the first increment shipped.

[serge-ivo]

Related: #366 measures the atomic layer beneath the blocks in this epic, and #367 measures the console against ~/dev/stores/DESIGN-SYSTEM.md for the first time.

I filed #366 before reading this epic and docs/agent-ui-blocks.md, and have corrected it — its "the console has no component layer" framing was wrong (Page.tsx is an explicit single-source-of-truth primitive, and form inputs are centralised in index.css:71-88), and this epic's audit is both older and deeper than mine.

Two notes from re-verifying this epic's audit against HEAD, since it predates a lot of change:

• The chat thread is still 3× — InstanceDetail.tsx, AgentDetail.tsx, agents/coder/web/src/CopilotView.tsx. All three present, all three render a thread. Still true.
• Relative-time formatters: I find three, not five — agoShort (SettingsTab.tsx:30), ago (Terminals.tsx:15), timeAgo (coder/web/src/BuildsPanel.tsx:46). Either two were consolidated since this was written or they are named something my search missed. Worth a re-count when this is picked up rather than trusting the number in the body.

Sequencing suggestion: the atomic vocabulary (#366) is a prerequisite for step 2 here. Extracting ChatThread into sdk/ui-react while its buttons are still 14 bespoke shapes moves the inconsistency into the library, where every future consumer inherits it.

[serge-ivo]

Context: PAGS now owns its design system (decided 2026-08-07, #367 / workspace 358b029) — it no longer follows ~/dev/stores/DESIGN-SYSTEM.md.

This epic assumed a shared visual language it could build components against. That assumption is now explicitly false, and the dependency runs the other way: #367 must define the PAGS system before a component library can encode it. A first-party block library built on 14 undocumented button shapes (#366) would freeze the inconsistency into an API.

Suggested order: #367 (document what it is) → #366 (make the atomic layer conform) → #187 (compose blocks on a settled foundation).

Not blocking this epic on demand — it is first-party enablement, not marketplace work — but it is blocked on a definition that did not exist until today.

[serge-ivo]

Scoping this epic around the atomic layer, now that the atomic layer is real

Read-only pass. Measured against main @ 8c6f75b (2026-08-08 23:15), which is ten minutes after
#366's card commit landed (c36bf0d, 23:05), so everything below is against a tree #366 is still
actively changing. I have not touched #366's or #367's work and this comment is written to sit
above them, not beside them.

Constraint of record, first, because it changes what this epic is allowed to assume: PAGS is
deliberately out of the shared cross-store design system (decided 2026-08-07, ~/dev/stores
358b029), is dark-only, and keeps its own system in platform/DESIGN-SYSTEM.md — which now
exists (35KB, written descriptively). A component library here does not need a light theme, a
data-theme switch or a stores-theme key, and should not grow one. It also means there is no
external spec to conform to: the library IS the specification, which raises the stakes on getting
its public shape right and lowers them on matching anyone else.

---

1. What #187 means once #366 exists — it is not the same ticket it was

When this epic was filed, the framing was "the blocks are already generic, just not extractable".
#366 has since answered a different question — what does a control look like — and answered it
well: lib/control-classes.ts is a table, Button/Card/Badge are three components over it, and
DESIGN-SYSTEM.md §3 writes the vocabulary down.

But #366 put all of that in store/console/src/, which is not a package. So the vocabulary
exists and two of the three React trees in this repo cannot reach it. Measured now:

tree	raw <button>	<Button>	<Card>
store/console/src	206	70	48
agents/coder/web/src	88	1	0
store/admin/src	26	0	0

#366's own commit says so without being asked (2f5ec29):

eleven console files plus all of store/admin and agents/coder/web do not get BUTTON_SIZE's
floor until they migrate

They cannot migrate. agents/coder/web is a workspace package with React as a peer; importing
../../store/console/src/components/Button is not a thing it can do. store/admin is a separate
Vite app with its own @theme block held equal to the console's by test, and its own fourth card
implementation — lib/ui.tsx's Panel, hand-written rounded-xl p-4, which is not
cardClass()'s rounded-xl p-3 sm:p-4 and never will be while it lives there.

So the first thing this epic means today is narrower and more useful than "a component library":
it is the package boundary that lets #366 finish. That reframing is the main content of this
comment.

2. What composable blocks buy that today's console does not have — measured, not argued

Three things. The first is the one with dated evidence.

a) One fix reaches every surface. Today it demonstrably does not.

The same defect was fixed twice, three hours apart, on the same day:

• 334b491 — "fix(console): the message header reserves the corner its action buttons live in
  ([bug][mobile] Copy and Delete sit on top of the message timestamp — 42px of 110px covered in WebKit, and removing the year only recovers 30px #426)", 16:22 +1000. Measured in WebKit: Copy overlapped the timestamp by 18×16px, Delete by
  24×16px, 42 of a 110px stamp covered.
• ba6f16a — "fix(coder): the Co-pilot's Copy button stops covering the timestamp ([bug][mobile] The Co-pilot repeats #426's overlap — Copy covers 18px of the timestamp in WebKit, in a package the console e2e never renders #445)",
  19:23 +1000. Its own message: "the same three decisions and none of the fix".

And #389's 24px target floor swept the console and missed this package, recorded in the
duplicate's own comment:

// tap-target closes a live #389 omission: this was a 24×24 box on the surface #389 swept
everywhere BUT this package

The two CopyButton implementations — InstanceDetail.tsx:44 and CopilotView.tsx:40 — are
byte-identical except for their comments. I diffed them.

b) The two chat threads have silently diverged in FEATURES, not just in styling

This is worse than duplication and nobody has written it down. Both threads share the bubble class
string byte-for-byte (InstanceDetail.tsx:1134, CopilotView.tsx:402 — the same
group relative max-w-[90%] px-3 py-2 rounded-xl …), which is what makes the divergence invisible:

shipped for the Assistant thread	in CopilotView	in AgentDetail (trial chat)
DeleteTurnButton — delete a whole turn (#342)	✗	✗
FabricatedNotice + border-danger-line on a retracted answer (#406)	✗	✗
PlaybackIcon with play/stop/loading phases	✗ (bare Volume2, no phase)	✗
stampTitle — full local time + zone on hover (#345)	✗	✗
SpokenMessage / GlossedMessage (translation + transliteration)	✗	✗
SystemMessage	✗	✗

grep -rl across the three trees: each of those six is in store/console/src and in neither
other thread. A Coder user who has spent 107 messages in a Co-pilot session this week cannot delete a
turn, cannot see that an answer was retracted, and gets no playback state.

That is the honest answer to "what does the epic buy": not tidiness — feature parity that is
currently paid for per surface, and mostly not paid.

c) Surfaces stop being all-or-nothing

The original framing still stands and is unchanged: a Repo Coder shipped with add-repo and a
multi-repo list because surfaces:["coding"] was the only way to get a terminal. surfaceOptions
patches it. docs/agent-ui-blocks.md's DOM-factory decision is the durable answer — but note it is
not urgent: custom surfaces ship disabled (CUSTOM_SURFACES_ENABLED unset in production), so
there is no consumer waiting. Sequence it last, and let (a) and (b) drive the work.

3. The styling blocker, re-measured — it is smaller than the doc says

docs/agent-ui-blocks.md lists three blockers. Two have shrunk and one was overstated:

• "A package built outside the console emits classes with no definitions." The console already
  solves this for exactly this case: index.css:11 is @source "../../../agents/coder/web/src",
  with a comment explaining that it exists because coder-web's sm:flex classes silently vanished.
  One more @source line per consuming app covers a new workspace package. Verified mechanism,
  existing precedent, ~1 line.
• "No @source can ever cover a third-party bundle built outside this repo." True, and
  irrelevant to injected first-party blocks: a third-party bundle calling sdk.ui.terminal(el)
  authors none of our classes — ours come from our package, which IS scanned. The statement only
  binds the third party's own markup. Worth correcting in the doc, because as written it reads like
  a blocker on block 2 and it is not.
• Global CSS the components need (.msg-md, .chat-scroll, scrollbar-none) — still real, and
  still the thing that decides whether the package ships CSS or not. admin/src/index.css has no
  @source and no .msg-md, so an admin consuming ChatThread today would render unstyled
  markdown.

The token question has an answer #367 wants anyway. DESIGN-SYSTEM.md §6 lists as open: "The
store/admin palette is still a copy … a shared file is still the right end state, and nothing
holds the marketing :root blocks to either." A UI package that owns the @theme block and is
imported by both SPAs is that shared file. #187 and #367 want the same artefact for different
reasons; whoever builds it should close both.

4. Where it should live — a recommendation, with the alternative and why not

Recommendation: a private workspace package, packages/ui, React as a peer, exactly the shape
agents/coder/web already proves works. Contents, in order: the control-classes table +
Button/Card/Badge (Phase 0), then the composite blocks.

Alternative considered and rejected: put it in @proagentstore/sdk/ui-react. That subpath exists,
already has React as an optional peer, and packages/sdk/src/ui.ts's header states this as the plan.
Rejected on publishing cadence, not on architecture: the SDK is a published npm package third
parties pin, and console chrome changes several times a day right now (six commits touching these
files today alone). Every button-padding decision becoming a semver event on someone else's
dependency is a tax with no payer. The React-free-barrel rule is not the reason — ./ui-react is a
separate subpath and is safe.

This does not compromise the DOM-factory decision. agent-ui-blocks.md says the factory hangs off
ctx.sdk, and ctx.sdk is minted by the console (makeSdk(ctx) is listed as a prerequisite). So the
SDK need only declare the type of sdk.ui.*; the console injects the implementation from
packages/ui. No published package needs to contain console chrome, and no React identity crosses
the third-party boundary — the property that decision was made to protect.

Pure logic that is already shared should stay where it is: chat-message.ts (classifyMessage,
toolCallSummary, messageKey), terminal-render.ts, formatTime/formatDateTime are in the SDK
and are consumed by both trees today. The split that works is pure logic in the SDK, rendered
chrome in packages/ui.

5. The first three components

Not the epic's original order. Block 1 (terminal colorizer) shipped; the order below is re-derived
from what is measurably broken now.

1. The atomic layer itself — Button, Card, Badge, control-classes.ts.
Not a composite block, and that is the point: it is the cheapest possible first move (a file move
plus two @source lines), it unblocks the two-thirds of #366 that is currently unreachable, and it
is the only item here that is safe to do while #366 is mid-flight, because it changes location and
not content. It also gives store/admin's Panel somewhere to go.
Coordination: this is #366's file. It should move when #366 says it is stable, not before — the
call belongs to whoever is on #366.

2. ChatThread.
The biggest payoff and the one with the defect record in §2. Constraints, all of which are real:

• needs a renderMessageBody slot, so the gloss/translation layer stays in the console and does not
  drag use-gloss, Intl.Segmenter and 16 target languages into the package;
• needs onDeleteTurn / onPlay / onCopy as props, so DeleteTurnButton (which calls a
  console-owned endpoint) inverts rather than moves;
• needs .msg-md and .chat-scroll to travel with it, which is the decision in §3;
• must be extracted after Move the composer below the thread and show it only in text mode — the live dictation becomes the one surface above it #365 (composer inversion) and [standards][tracking] Split worst large files into testable modules #305 (InstanceDetail split), or it is
  extracted twice. InstanceDetail.tsx is 1,495 lines today, up from the 1,275 [design] The atomic layer under #187: 273 buttons in 14 shapes, 3 card geometries, 17 font sizes #366 quoted.

3. RunList/Timeline.
Cheapest composite. Three components converge, props are already {instanceId}, only lookup tables
differ. Take it before Board — Board needs one useNavigate inverted into onOpenItem plus the
apply-retry and BROWSER_TASK run form hoisted into props, which is a bigger surface for the same
class of win.

6. Phasing, and my recommendation on whether to start now

Recommendation: start Phase 0 now, do not start Phase 1 yet.

Phase	What	Start when	Why
0	Move the atomic layer to packages/ui; @source lines in both SPAs; make the @theme block a single file both SPAs import	When #366 declares the table stable — days, not weeks	A file move with no rendered change. Unblocks 114 controls in two trees that cannot migrate at all today, and closes a #367 §6 open item on the way.
1	ChatThread	After #365 and #305 land	Six duplications collapse and §2b's feature drift stops. Doing it before those two means doing it twice.
2	RunList/Timeline, then Board, then FileList/FilePreview	After Phase 1 proves the slot pattern	Each is mechanical once the first composite has settled how props/slots/teardown work.
3	makeSdk(ctx) + the sdk.ui.* DOM factory for third-party surfaces	Only when a third-party surface is actually wanted	CUSTOM_SURFACES_ENABLED is unset in production and the platform serves no third-party bundle. There is no consumer. Building the injection layer now is building for a user who does not exist.

The argument for starting now is not "the console is untidy". It is that #366 has produced a
vocabulary that two-thirds of the UI cannot speak, and every week that stands, the drift it was
built to stop keeps accruing in agents/coder/web — 88 hand-written buttons, and a documented
same-day double-fix to prove the cost is being paid in defects rather than in aesthetics.

The argument for waiting is that three tickets (#365, #305, #366) are all rewriting the same two
files right now, and adding a fourth would be the fourth agent in one file. Phase 0 is deliberately
chosen to be the one piece of this epic that does not touch those files.

7. Acceptance criteria for Phase 0 (the only phase I am proposing be picked up)

• packages/ui exists as a private workspace package, React >=18 as a peer (mirroring
  agents/coder/web/package.json), and exports Button, Card, Badge and the
  control-classes table.
• store/console, store/admin and agents/coder/web all import them from that package;
  store/console/src/components/{Button,Card,Badge}.tsx are deleted, not aliased.
• Both index.css files carry an @source for the new package; a rendered test asserts a
  <Button variant="primary"> produces a non-empty background-color in the admin build
  (the tree with no @source today, i.e. the one that would fail silently).
• The @theme token block exists once and is imported by both SPAs;
  designTokens.test.ts's console-vs-admin equality assertion becomes trivially true or is
  replaced by an assertion that both import the same file.
• store/admin/src/lib/ui.tsx's Panel either becomes <Card> or its divergence
  (p-4 vs p-3 sm:p-4) is stated in DESIGN-SYSTEM.md §6 as deliberate.
• No rendered change in the console: the existing e2e overflow/visual guards pass unmodified.

8. Regression risk, stated plainly

• Tailwind silent-nothing. The failure mode of a missing @source is not an error, it is an
  unstyled control — the exact failure index.css:11's comment records. The rendered-colour
  assertion above is the only thing that catches it; a typecheck will not.
• Token divergence during the move. [design] The console has never been measured against DESIGN-SYSTEM.md — no light theme, no theme mechanism, colour-named status tokens, and nothing lints store/ #367 already recorded that the pigment→intent rename made the
  two @theme copies diverge "for a few minutes and the equality test caught it". Do not delete that
  test until the single-file import replaces what it was guarding.
• agents/coder/web is a published-ish boundary in spirit — it is imported by the console at
  build time, and its typecheck script builds the SDK first. Adding a second workspace dependency
  to it changes that script's assumptions; check pnpm --filter @proagentstore/coder-web typecheck
  explicitly rather than relying on the root run.
• The one thing that would make this a bad trade: if packages/ui grows props for padding,
  radius or colour. Button/Card's current doc comments refuse those for a measured reason
  (Tailwind resolves same-property utilities by stylesheet order, not attribute order). That refusal
  must survive the move, or the library becomes a slower way to write 47 shapes.

9. Alternatives considered and rejected

• A lint that bans raw <button> outside the package. Rejected for now: 320 raw buttons across
  three trees with, today, nowhere for two-thirds of them to go. [design] The console has never been measured against DESIGN-SYSTEM.md — no light theme, no theme mechanism, colour-named status tokens, and nothing lints store/ #367 already established the
  general rule — "a lint with nowhere to put the fix is just 168 blocked PRs" — and [design] The atomic layer under #187: 273 buttons in 14 shapes, 3 card geometries, 17 font sizes #366's ratchet
  is the right instrument until Phase 0 lands. After Phase 0, a ratchet per tree is worth it.
• Copy the primitives into agents/coder/web and store/admin. It is the workspace's normal
  cross-store rule (vendor, don't depend) — but that rule is about store independence at
  runtime, and these three trees already build into one artefact and share one stylesheet.
  Vendoring inside a single build is just the duplication this epic is about, with a policy citation
  attached.
• Shadow DOM / iframe isolation for the blocks. Out of scope and actively harmful here — it
  breaks every Tailwind class an injected component relies on. Already recorded in
  agent-ui-blocks.md and [security] Custom surfaces are effectively inert in production, and their validation is client-side only #186; nothing has changed.
• Ship ChatThread first because it is the biggest win. Rejected on sequencing, not on value:
  Move the composer below the thread and show it only in text mode — the live dictation becomes the one surface above it #365 changes which controls exist in the composer and [standards][tracking] Split worst large files into testable modules #305 splits the file it lives in. Extracting
  now means extracting twice, and the second extraction lands in a package where more consumers have
  already inherited the first shape.

---

What I verified vs. inferred

Verified by reading the tree at 8c6f75b: every count in §1 and §2; the byte-identical
CopyButton pair (diffed); the six absent features (grep -rl per tree); the @source mechanism
and its comment; packages/sdk exports + peer deps; agents/coder/web/package.json's peer shape;
store/admin/src/lib/ui.tsx's Panel; the two commit messages quoted, by SHA and timestamp.

Inferred, not measured: that Phase 0 is a no-rendered-change move — it should be, because the
class strings are literal and unchanged, but nothing proves it until the e2e guards run against it.
And I did not measure any of this in a browser: §2's overlap figures are quoted from #426/#445's own
WebKit measurements, not re-taken.