Components

Every component derives its GPUI element id and its semantic assertion id from one caller-supplied Ident, reads the theme from the application context, and publishes a semantic node during prepaint. Builders are RenderOnce; anything that must survive a frame is a view.

No component holds a word a reader reads. Text this library authors — Copy, Try again, No rows, Next page — is named by a gpui_kit::strings::StringKey and read from the installed catalogue at render time, the same way a colour is read from the theme. A host that installs nothing gets the English compiled into the binary; a host that installs some entries gets its own words for those and English for the rest, so a label is never blank. Text the caller supplied is shown verbatim and outranks the catalogue: a refusal's reason, a column header, a month's name, and an explicit handle_label are the host's, not the library's.

cargo run -p xtask -- strings check, which runs inside gate, fails when a component grows a literal a reader could read.

Controls

In-content controls share the token-backed control material: an opaque fill, quiet definition hairline and one-pixel top inset highlight. Focus/invalid states add halos; selection is tonal fill. Knobs reuse Elevation::Raised. This family is distinct from floating Liquid Glass surfaces. Small through medium action controls use Radius::Control; large controls use capsules.

In-content fields and Select triggers share StyledExt::control_surface: surface.control, interactive.controlHairline, and a top inset interactive.controlHighlight. Invalid halos and ring-mode field focus append without replacing the highlight. effect.fieldFocus: "fill" instead focuses editable fields with surface.controlHover and no focus halo; disabled focus is suppressed and invalidity takes precedence. Select and button focus are unchanged. This material is opaque, not Liquid Glass. Owned TextArea frames (including MentionInput's editor) share the same field material and state policy without adopting single-line layout. Frame::Host continues to contribute no fill, border, padding, or halo of its own. Theme::control_shadows(Elevation::Raised) reuses the elevation authority for knobs instead of adding another shadow token. Segmented strips have equal widths and neutral selected text unless a segment explicitly supplies tint; Xs–Md use Control corners and Lg uses capsules. Switches retain accent on-state tracks, with a definition edge and a Raised knob shadow.

Default/Secondary buttons use this bordered control family (Control corners for Xs–Md, capsule for Lg). The ground hint still permits a neutral wash where the authored control step cannot separate from its parent. On Button, Variant::White now means on-media: color.onMediaBackground, color.onMediaForeground, and color.onMediaHairline, not an opaque white pill and not a second Glass surface. Its glyph and loading mark use the same foreground as its label, including under a light theme.

FocusRing appends its halo to the existing material shadows. A pressed button combines its fill and travel with Pressable::pressable_with; Reduce motion removes travel without removing the pressed colour report.

Badge::new(value).count() is a formatted-data mark, not a status: Caption type, tabular OpenType figures, a fine control hairline, and no status wash. The caller supplies the formatted value; an identified count publishes Role::Text and that value rather than a severity. In-content Tabs use a Sunken hairline track and a raised control face for the selected tab; badge values use the count form. Tabs::capsules() retains its floating Regular Liquid material and caller-owned selection contract.

Sensitive text remains one editor

PasswordInput and OneTimeCodeInput do not duplicate editing. Each owns one TextInput entity, one focus handle, one selection, one caret, and one input method composition. Password reveal is visual transient state. One-time-code slots are visual policy over the same editor, with hit testing and input-method bounds mapped across the complete segmented surface.

Both controls return the typed value only to their caller and emit caller-owned change/submit events whose Debug output is redacted. Deterministic semantics, GPUI's AccessKit values and text runs, clipboard copy/cut, and component Debug carry no credential or code. auth-sign-in and auth-verification demonstrate composition with Card, FormField, Callout, and generic caller-supplied actions. They define no account, provider, network, or credential policy.

TextArea::autosize(min_rows, max_rows) is the bounded variant of the same editor. It measures shaped visual rows, grows only within the caller's bounds, and falls back to scrolling at the maximum, so IME, selection, and undo state remain attached to one editor rather than a replacement field.

Display

The card is the container, and there is one of it

For a caption over media, use surface(ident, theme, OverlaySurface::MEDIA_CAPTION) -> GlassSurface. This recipe owns Clear optics, dimmed transmission, Card radius and no shadow. The styleable frame supports .absolute().left_0().right_0().bottom_0() with an internal flex layout: its parent determines width and its contents determine height; callers do not need an explicit pixel width or a bare Glass wrapper. Clear content inherits light foreground independently of appearance. Prefer inherited text or the on-media roles, not text colours captured from an outer light theme. Reduced transparency resolves to dark Frosted with light content. See the media-caption exhibit for both appearances and the reduced state.

A card is a surface that groups content, so it owns the whole vocabulary of one: a media band flush to its edges, a CardHeader with a title, an optional subtitle and an optional control, body content, a footer, and divided to put a rule between adjacent regions and between body rows. A caller reaching for a card gets all of it or none of it, and never a rectangle it has to finish by hand.

That last sentence is the point of the component rather than a description of it. Before it existed, Card offered a radius, a surface and a click, thirty nine source files each drew the rest themselves, and no two of them agreed: agent/* padded by Space::Md and cast a shadow, game/* drew a hairline and cast none, and the component itself padded by Space::Lg. Three answers to one question is not a style; it is the absence of one. A container that cannot carry a title is a container every caller has to escape.

variant names how the card separates itself from what is behind it:

The colour step is doing the separating in all three cases: a theme that meets the surface separation floor in docs/token-model.md has already made the boundary legible, and a variant chooses the second piece of evidence on top of it. This is why a card carries no line by default. The library reserves lines for what they alone can say — focus, invalidity, a drop target — and divided is the deliberate exception, because it draws a line between two pieces of content on one surface rather than around the surface.

selected is a wash and nothing else, painted inside, so choosing a card moves nothing around it and adds no second geometry beside the fill. disabled publishes the refusal, changes the text tone, and installs no handler at all; it does not fade the card out from under the reader, because unavailable is a fact to be read and not a thing to be hidden. A card that is itself one action drops its header's control, since two targets inside one target is a click whose outcome depends on which pixel it landed on.

ListRow carries leading and trailing slots rather than relying on child order, so a list of rows lines its text up whether or not a given row has an icon or a badge. A row takes the press response and not the hover lift: a row that rose would leave the card it belongs to.

A component that is already a card but owns a richer semantic node than a grouping — ApprovalPrompt is a form — cannot be wrapped in one, so the shell itself is the shared piece: StyledExt::card_surface(theme, variant) is the single definition of what a card is made of, and Card is a caller-facing composition on top of it. That is the whole of the fix. Transcript evidence is deliberately not a card: ToolCall is a caption-sized row, while media and durable results remain the places where an agent transcript earns a card surface.

Agent experience

The presentation layer is not an agent runtime. It consumes an observed AgentRunSnapshot, displays waiting/refused/failed/cancelled as distinct facts, and reports caller-owned actions. AgentRunSnapshot::issues() remains the source of structural validation: components never repair duplicate identities or dangling topology into a different run.

Semantic visual effects

AgentVisualEvent reports facts such as AgentSpawned, DelegationStarted, HandoffCommitted, ResultAggregated, AgentSucceeded, AgentRefused, AgentFailed, and RewardGranted. It carries stable event, surface, target, and optional origin identities; it cannot name a particle system, colour, shader, duration, or animation recipe.

EffectPlanner normalizes those events together with generic EffectEvents. It chooses a semantic EffectRecipe and one of Static, Animated, or replay-suppressed presentation. The installed EffectPolicy has four complete quality tiers — Off, Essential, Balanced, and Cinematic — plus global and per-surface frame budgets for events, emitters, particles, and animated area. Reduced motion and exhausted budgets choose the static recipe; they do not erase feedback. Stable event identity seeds deterministic rendering and a bounded, per-surface replay history prevents reconnects or rebuilt trees from replaying a celebration.

The planner is the policy boundary, not a particle renderer. Components and agent runtimes provide semantic events. EffectParticles consumes the plan and fills a caller-bounded layer with one deterministic CPU-sampled, atlas-backed sprite batch. It owns cue topology, theme colors, RTL trace direction, elapsed time, frame scheduling, and the smaller fixed constellation used for Static. Particle tints stay semantic but are reinforced toward the active text tone, so tiny marks retain a contrast floor across the standard light/dark surfaces; an active reduced-motion preference also converts an already-running plan immediately. sample_at exists only for deterministic replay, scrubbers, and captures. Suppressed plans and zero-emitter recipes paint nothing. Because the layer is decorative, the target status/control remains the semantic feedback and the layer adds no hitbox or accessibility node. This keeps graceful degradation and performance policy out of every downstream chatbot, persona, or game surface.

CinematicEffect consumes the same plan and upgrades it through a semantic CinematicRecipe: Box owns the product-neutral asset slot, duration, poster sample, directional RTL rule, deterministic timeline, localized semantics, and particle fallback. The host resolves a slot to DotLottieAsset bytes and prepares a DotLottieClip; no public type accepts a URL, path, filename, third-party runtime value, shader, expression, or arbitrary program. Playback and state-machine integration use caller-owned DotLottiePlayback facts and typed DotLottieRequest intents. The optional dotlottie feature provides RasterDotLottieAdapter; core contracts and unavailable/invalid-asset fallbacks compile without it. The adapter rejects archives outside bounded encoded/expanded size, compression, entry, canvas, frame, duration, animation, state-machine, embedded-image-count, source-dimension, or aggregate image-pixel limits, sanitizes every admitted entry and inspects image headers before decoding, and returns complete RGBA frames through RenderImage.

Persona presentation follows the same boundary. Audio capture, recognition, playback, portrait download, model expression inference, and dialogue progression are host capabilities. Box accepts only resolved assets and typed facts, then owns the reusable visual mapping, deterministic sampling, accessibility semantics, RTL order, and fallback treatment.

Game experience

GameFraction and AbilityCharges reject non-finite, out-of-range, zero-maximum, and above-maximum facts rather than clamping them into plausible telemetry. The game module deliberately owns no combat formula, inventory, quest progression, reward outcome, save data, asset transport, input mapping, or game engine. A host supplies those facts and handles the typed requests; the components own the state-to-visual mapping, topology validation, semantic ids, responsive wrapping, locale hooks, RTL, motion, and graceful effect degradation that a downstream chatbot or game surface should not have to recreate.

Navigation

Sidebar layout and state ownership

Give the rail a bounded height. Its ScrollArea owns the navigation viewport, and GPUI's reveal_on_focus brings keyboard targets into view without moving the header or footer. In a content-sized layout such as a settings-page slot, use fit_height() instead; the surrounding page then owns vertical bounds. Use fill_width() inside a caller-owned SplitPane for drag resizing; the host keeps the split ratio and persists it if appropriate. The default expanded width remains 240px; collapsed width remains 52px.

on_collapse adds a control that requests a new collapsed value. It does not automatically accept a resize or impose a responsive breakpoint. Branches start open and retain local expansion unless expanded_ids is supplied; in that mode on_toggle only requests changes, including when the host refuses them. The disclosure control and the destination link are separate actions.

Collapsed rails show top-level destinations only. A branch opens a flyout with its own parent destination ({sidebar}.{item}.destination) and descendants; Escape restores the trigger's focus. Item ids must be unique across the whole rail. Descendants now publish their actual parent and retain arbitrary depth instead of silently dropping grandchildren. A disabled ancestor disables its descendants. Resource trees should still use Tree, not page navigation.

Up/Down and Home/End move focus, logical Left/Right disclose branches, and Enter/Space invoke the focused action. None of these movements changes active: only a new caller-owned value does. As with other Kit controls, the host binds Tab/Shift-Tab to GPUI's focus_next/focus_prev; the flyout handles its own contained Tab traversal. Long labels use ellipsis and full-name help; missing leading assets use a document glyph; compact badges use a status dot while preserving their full semantic value. Branch disclosure and flyout arrival are immediate; only the existing glyph FLIP transition is animated.

The wizard moves nothing

Wizard reports Step, Back, Next, and Finish; which step is current stays with the caller, exactly as Tabs never switches its own tab. Only completed steps are revisitable by default, and a step nobody may jump to installs no handler. Blocked and Failed carry the host's reason and publish it as a child node, because a step that has gone grey for a reason nobody states is a dead end.

Undo history owns no undo stack

UndoHistory neither records changes nor restores them. The caller supplies durable entry identities, their order, the current entry, and any refusal to restore one; on_jump reports only the requested identity. Times are already formatted by the caller because locale and time-zone policy do not belong in a navigation component. An unavailable revision stays visible with its reason and installs no action.

An unknown page count is not a page count

PageTotal::Known and PageTotal::Unknown { has_next } are different facts. A host that paginates a cursor knows only whether one more page exists, so that is all the control claims: it offers next and previous, states "Page 9" with no total, and publishes no value on the container. Rendering an invented last page would be a number nobody counted.

Layout

A titlebar asks; the window decides

DesktopTitlebar consumes the title and optional subtitle while reading the window's current maximized state and available platform controls. Clicking a caption control reports a DesktopTitlebarEvent; it does not mutate or remove the window. A host that accepts Close calls Window::request_close, which preserves the window's on_window_should_close refusal path. On Windows the maximize button keeps WindowControlArea::Max, so the operating system still owns Snap Layout; ordinary elements mounted in the titlebar are WindowControlArea::Client and remain clickable instead of becoming drag handles.

A layout the host can write down

SplitLayout is data, not view state. This crate takes no serialization dependency, so instead of a derived Serialize the layout converts losslessly to and from a flat Vec<SplitRecord> of plain fields through to_records and from_records, which a host persists with whatever format it already uses. from_records reports why a set of records is not a tree — no root, two roots, a duplicate id, a missing parent, a split without exactly two children, records the root does not reach — rather than silently building something else.

A reported SplitChange is still only a request. SplitLayout::applied exists for the host that accepts every change and wants one call to make; a host that judges them applies the ones it accepts with with_ratio and with_collapsed.

The dock moves nothing

Which panels a region holds, which one is on top, whether a region is collapsed, and how much room it takes are all the caller's. DockEvent names what the typist asked for and the arrangement on screen stays as it was, so a host that refuses a move keeps showing the layout that still holds. A move names the panel the dragged one should sit in front of, never an index: an index stops meaning anything the moment the host applies the move.

What the dock deliberately cannot do: a region holding no panels is not drawn, so it cannot be dropped onto; a panel is drawn in exactly one region, with no split inside a region and no floating panel; and a collapsed region shows a rail whose glyphs report both the selection and the request to expand without applying either. A panel the host cannot show keeps its tab and states the reason where its content would be, because a panel that vanished would read as one the workspace never had.

DockTree is the recursive contract for hosts whose arrangement is not the fixed left/centre/right/bottom shell. Its caller-owned DockTopology nests stable tab stacks under horizontal and vertical split nodes, converts losslessly to and from plain DockRecord fields, and preserves empty stacks as real merge targets. The renderer delegates every divider to SplitTree, every tab order to Tabs, and every move to the shared DnD system. A centre drop reports a stable stack and neighbour; an edge drop reports DockPlacement::{Left,Right,Top,Bottom} but invents no split or stack id. The host applies, normalizes, persists, or refuses that structural change.

A status bar never invents reassurance

Every fact in the strip belongs to the host, so an item with no state carries no state rather than a green dot nobody asked for. StatusItem::tracking reads AsyncValue straight: a value whose refresh is in flight or has failed while a value is still held is drawn with its last verified text and the word stale beside it, and publishes stale as its value. It is never drawn as current. A progress item with neither a fraction nor a count is drawn as an unknown extent rather than as a ring that happens to be part full.

A recorder that cannot bind escape

KeybindingRecorder reports gpui::Keystroke::unparse, which is exactly what gpui::Keystroke::parse reads and what Kbd splits, so a captured binding is usable without translation. Escape ends recording without capturing: that is how everything else in this library abandons something in flight, and a recorder that swallowed it would leave the typist inside a field that eats every key. The cost is stated rather than hidden — escape cannot be bound unless the caller turns allow_escape on and provides its own way out. A conflict is never the recorder's judgement: it has no keymap to consult, so it renders the reason the host found and nothing else.

KeymapEditor is the coordination above that primitive rather than another settings-row skin. It filters the command facts the caller supplied, keeps at most one recorder active across all visible rows, and reports stable command-and-binding identities with add, remove, and reset intents. Capturing does not change the effective bindings on screen. If the host refuses an intent, it leaves its supplied state unchanged; if it marks a command refused, the row keeps its bindings and reason but installs no actions. Conflict and provenance remain caller statements, never conclusions drawn by the component.

A scrollbar that is absent means there is nothing more

A viewport can mean two different things: the content fits, or there is more off screen. ScrollArea publishes a Scrollbar node only in the second case, carrying how far the content reaches and how far it has been scrolled. A test therefore tells the two apart from the tree, rather than guessing from what happens to be visible.

Both the divider's travel and the scrollbar's reach are extents only layout knows, so they are measured during prepaint and published by the following frame. Tests deliver that frame themselves with Harness::advance.

Toolbar overflow is declared, not measured

A truthful overflow would have to know how wide every item is before deciding which ones fit, but GPUI measures after the element tree is built and a toolbar child is an AnyElement that can be consumed exactly once — so a builder cannot measure a child and then still move it into a menu. Guessing at widths would produce a bar claiming to have dropped items it in fact drew.

So the caller declares the cut with Toolbar::overflow_after, and the toolbar guarantees the part it can: an item past the cut is moved, never dropped. It becomes a row in the overflow Menu keeping its identity, its label, and its refusal, and the trigger publishes how many items went there. With no menu to move them into, every item is drawn inline, because losing an action is never the better failure.

Data

Only rendered rows are published

A virtualized surface holds a viewport, not a data set. A row outside the viewport is never laid out, has no bounds, and publishes no semantic node, so a snapshot describes what is on screen and nothing else. The container node carries the total in value: a test asserts that the list holds a thousand items and drew twelve, rather than pretending the other nine hundred and eighty-eight are addressable.

Virtualization needs a bounded viewport. List, Table, Tree, TreeGrid and DataGrid each take a visible_rows bound and draw only the rows that fit; without one they size themselves to their content and every row is laid out. That is the right answer for a settings summary and the wrong one for a hundred thousand log lines.

Two of the four have a second condition. Table virtualizes only when it is given a row source — Table::rows_from(count, closure) — because Table::rows hands it elements the caller has already built, and an element can be laid out once while a uniform_list needs to build a row twice in a frame: once to measure the height, once to draw. rows_from is offered alongside rows rather than replacing it, so a table of six settings does not have to be written as a closure over an index. Tree flattens the hierarchy to the rows a reader could see and virtualizes that, so what it draws follows what is open; flattening still walks the whole hierarchy each frame, which is data rather than elements.

A Tree reports the number of rows it disclosed in value, which keeps three absences apart: a node under a shut branch is not disclosed, a disclosed node past the edge of the viewport is counted but not drawn, and a node that is not in the data at all is neither. A bounded tree can draw a node whose parent has scrolled off the top; the node still names the parent it has, so a walk down from the tree will not reach it and a test should name it instead.

List, Tree and DataGrid move the selection with the keyboard over the whole collection, not over the rows that happen to be drawn, and scroll what they report into view. Table reports only what is clicked, so a caller that moves the selection somewhere the viewport has never drawn brings it into view itself with data::reveal_row, naming the table's body as <table ident>.body.

Table or DataGrid

Both are column-oriented and both report rather than apply. The difference is what they are handed:

• Table takes rows, or a source. Handed rows, the caller builds every cell before the table sees it and the whole set is laid out. Handed a source through rows_from, it survives a large collection but gains nothing else: no selection over an incompletely loaded set, no opened rows, no editing, and no keyboard. Reach for it for a settings summary, a short run list, a preview of a result set.
• DataGrid takes a closure. It asks for one row at a time and only for the rows the viewport holds, which is what lets it carry twelve thousand rows and also what makes column resizing, reordering, selection over an incompletely loaded set, opened rows, and cell editing worth its weight. Reach for it for the administrative surface: the thing with a header, a selection, a bulk bar, and more rows than fit.

If a surface would work as either, pick Table. It is smaller, and a grid's machinery costs something even when nothing uses it.

Table now keeps the same vacancy contract as DataGrid: a first load with no rows is busy, a successful empty query is empty, and a refresh failure keeps any rows that are still true and states the refusal above them. Row rules default on for Table and stay off for DataGrid.

Wide DataGrid behavior and remaining limits

Header, body, and summary scroll as one horizontal surface. The virtualized body keeps its independent vertical handle, but no second horizontal position is synchronized. GridColumn::pinned places columns in one frozen leading group: left in an LTR interface, right in RTL. The group keeps its clipping, hit targets, and accessibility bounds at that reading edge while moving columns pass beneath it. Keyboard focus reveals a moving header or editable cell inside the unobscured viewport rather than behind the frozen group.

It does not measure a column to its content. A double click on a resize handle reports a fit request through on_fit and stops. The grid can only measure the rows it drew, and a width fitted to fourteen of twelve thousand rows is a guess wearing a measurement's clothes; the host owns the data and can answer properly.

An opened row declares where it sits. A virtualized body reserves room by counting fixed-height slots, so it has to know where an opened row is before it has drawn it — hence Expanded { id, index }. The index is layout arithmetic and never reaches an id.

Tab moves within the row. Tab commits the open cell and names the next editable column in the same row. When a row's editable columns are exhausted the edit simply commits: the row below may never have been drawn, and the grid will not build a row nobody asked to see in order to guess where a caret goes.

Select all is two different claims

A header checkbox over a virtualized grid can only speak for the rows the host has handed over. DataGrid keeps the two apart:

• the box publishes both numbers, as "<selected> of <loaded> loaded, <total> total", and reports SelectionChange::Loaded — never anything wider;
• SelectionChange::Everything is only ever reported by a control that says that is what it does, which is BulkBar's "Select all N".

So a typist who selects everything on screen is told they selected forty rows and offered twelve thousand as a separate, named step, rather than being quietly credited with rows nobody has loaded.

Cells are quiet by default. A table of two hundred rows and six columns would bury every other assertion target under twelve hundred nodes that repeat what the row already says, so a cell publishes a Cell node only where the caller marks it with Cell::published, under the id <row id>.<column key>. A sortable header publishes a Button carrying its current direction in value; a header that does not sort publishes a Cell and installs no handler.

Date and time

This crate owns no calendar

There is no calendar system, no time-zone database, no locale, and no notion of today anywhere in these four components. Day and MonthKey are opaque integers the adapter mints; the components carry them, compare them, and hand them back, and nothing here ever adds a day to a date. An adapter that answers None to today, to shift_month, or to days_in is answering, not failing, and each of those has a rendered consequence rather than a guess: a calendar with no month to show says so instead of opening on one it chose. The trait a host implements, method by method, is in docs/datetime.md.

The reference calendar the scenes and tests run on is behind the fixtures cargo feature, off by default, so a host cannot reach a half-correct calendar from the component path.

Content

Developer data stays caller-owned

LogStream and DiffView both flatten caller-owned data into the crate's one fixed-height virtualized List. Only viewport rows are laid out and published; the list node still reports the complete row count. That keeps a large already-materialized log or diff viewport-cheap, but it is not lazy loading: building a frame still walks the caller's entries or hierarchy. Fixed rows also mean long content is clipped instead of wrapped or horizontally scrolled.

LogStream keeps only follow/paused and scroll position. Its mounted messages participate in GPUI's pointer document selection; a selection crossing virtualized rows reports itself incomplete, while the existing stable-entry copy intent remains the route to a whole caller-owned entry. DiffView applies the same rule to mounted code sides and reports file, hunk and line actions but has no apply operation. Neither component opens files, starts a process, searches text, computes a diff or classifies syntax.

A document is drawn, never obeyed

Markdown renders text nobody in the application wrote, so it does nothing that text asks for. Raw HTML is drawn as the literal characters somebody typed, marked unrendered html, because interpreting it would let a document reach outside its own text and dropping it would let a document hide its own contents from the reader. A link states its destination in hover help and in its node's value before it is taken, and taking it reports LinkClicked; this crate opens nothing. An image is never fetched — the crate has no network — so it is drawn as a placeholder naming its alt text and its source and reported once as ImageRequested, and a host that holds the bytes supplies an element through Markdown::image. A fenced block publishes its info string exactly as written, plain text when there is none, and is coloured only from spans the host computed. docs/content.md is the whole posture.

max_lines cuts to a line count and says how many lines it left out, offering them by name rather than behind a fade: a gradient over the last line says something was cut without saying how much.

A failure stays on screen

MessageList keeps Sending, Sent, Delivered, Read, and Failed { reason } apart as five renderings, because collapsing the middle three into one tick says less than the host knows and folding the last into any of them says something untrue. A failed message keeps its place and its full text, states the host's reason word for word, and gains one control that reports the retry. Nothing is resent and nothing is removed.

Whether consecutive messages from one author are one turn is group_consecutive, declared by the caller for the same reason Toolbar::overflow_after is. Following a new message happens only while the reader is already at the bottom; when it does not follow it publishes the count — 3 new messages for arrivals, 3 more messages for what has always been below — which is ScrollArea's "content continues past the view" rule on a surface that grows downward. Times are strings the host already wrote, as in Timeline, and an unrecorded author is unknown rather than blank.

Nothing is fetched, and nothing is played

ImageViewer extends Markdown's posture to a whole frame. The crate has no network and no asset resolution, so an image arrives from ImageViewer::image or not at all; a host that answers None gets a frame naming the source rather than a grey rectangle, and one ImageRequested per image rather than one per frame. Natural dimensions are a caller input, and an image nobody measured reads Size unknown and refuses the fit and zoom controls, because a scale is a ratio against a size and reporting the box the picture was drawn in would invent the fact the host declined to give. Zooming happens at the pointer, against the frame measured during prepaint, and a pan is clamped so the picture cannot be dragged off its own edge. Stepping past the last image is refused and the position is published — 2 of 2 — rather than wrapping silently.

TransportBar plays nothing. Every control reports: PlayRequested, PauseRequested, SeekPreview on every move of a scrub and SeekRequested once on release, VolumeRequested, MuteToggled, SpeedRequested, and Stepped. The head is drawn where the caller says it is, so a refused seek keeps the position that still holds. A duration nobody knows is TransportDuration::Unknown, which is PageTotal::Unknown for a timeline: the scrubber then shows elapsed, says the total is unknown, and draws no fraction at all. Buffered ranges are the host's and are drawn as their own band; a host that supplies none gets no band and no node. Elapsed and remaining are strings the host wrote, the rule Timeline and MessageList keep, and buffering while playing is a state of its own — a stalled transport says it is waiting, and still offers the control that would stop it, because nothing has stopped. docs/content.md states the whole posture.

Media

Native playback lands behind the component seam

GPUI draws images, and on macOS composites a CVPixelBuffer through its surface element. GPUI itself still has no decoder, audio device or frame pump, so the player components remain written against MediaTransport — origin, snapshot, and apply. PlatformMediaTransport implements that seam without changing the components: AVFoundation supplies macOS audio/video and an AVPlayerLayer-backed NSView; Media Foundation supplies Windows audio/video and renders to a child HWND. The GPUI platform_view element hosts the video view and retains its native player until delayed detach is complete.

Create the transport on the UI thread, retain it, call load, and rebuild the owning GPUI view when subscribe signals a native change. Native callbacks may arrive on a media thread, so the subscriber must marshal invalidation to the GPUI foreground executor rather than call UI APIs inside the callback. A video player supplies the transport's frame explicitly, preserving the component's existing truthful rule:

# use gpui_kit::prelude::*;
let playback = PlatformMediaTransport::video();
playback.load(MediaSource::file("walkthrough.mp4"))?;
let frame = playback.clone();
let player = VideoPlayer::new("walkthrough")
    .transport(playback.shared())
    .frame(move |_, _| frame.frame());
# Ok::<_, NativeMediaError>(player)

The native service covers ordinary unprotected files and streams supported by the installed operating system codecs. It does not claim DRM, custom network policy, playlists, track/subtitle selection, output-device routing, capture, or Linux/Web playback.

A control asks the transport and reports what came back: MediaEvent::Applied, Refused with a stable MediaErrorKind and the backend's own sentence, or Unsupported. Consumers branch on the kind rather than parsing platform text. The transport's MediaCapabilities independently decides whether seek, volume, and rate controls exist or accept input. The next frame draws the transport's snapshot, which is what makes a refused seek leave the head where it was. FixtureTransport takes commands and advances no clock, so a scene renders the same bytes on every run; it reports MediaOrigin::Fixture and every surface publishes and draws that.

A model is read inside a fence

ModelScene::parse accepts glTF 2.0 in both containers, buffers that are inside the file — the GLB binary chunk and data: base64 URIs — triangle primitives with a VEC3 FLOAT POSITION accessor, unsigned byte, short or int indices, and node hierarchy by matrix or by translation, rotation and scale. Any other URI is refused, because resolving one is I/O and this crate performs none. Materials, textures, animation, skins, morph targets, sparse accessors and non-triangle primitives are refused rather than approximated, and ModelBounds caps bytes, nodes, depth, primitives, vertices and triangles with every cap checked while reading rather than after allocating. A refusal names what the document asked for and what was allowed, so a caller raises a bound on purpose instead of guessing.

Interaction

List, Tree, and Tabs also take part in drag and drop, through reorderable, accepts, and on_reorder or on_move. The contract they all share — what a drop reports, what a drag publishes, what the host has to do — is in docs/interaction.md.

Overlay

Glass optical parameters share one surface model

Glass and GlassGroup expose thickness, refractive_index and backdrop_depth; glass-optics reviews them independently over a ruled fixture. Thickness is a profile height before the refraction multiplier. Set Glass::refraction(1.0) to use the height directly. Zero thickness follows the bounded bevel. Index 1 removes bending and Fresnel reflection. Background depth is distance to a screen-space optical plane, not a physical air gap. Blur still controls scattering independently; reduced transparency ignores optical overrides. See docs/compatibility.md for model limits and backend coverage.

Glass reports focus inside its material

Glass::focused(bool) and the GlassSurface::focused(bool) builder returned by overlay::surface report caller-owned focus. They do not acquire focus or install keyboard handlers. The interactive.focus colour paints an inward edge at effect.focusRingWidth, after content and along the same fitted rounded rectangle as the glass. It replaces the optical hairline, adds no halo, and changes no layout, clipping or hit target.

The report is identical for Regular, Clear (including dimmed), Frosted, reduce-transparency and admission-budget fallback. Opaque content controls continue to use Theme::focus_ring_on; glass callers use .focused(focused) instead of wrapping the material in that halo. Do not apply both treatments. The glass exhibit shows focused pills in both themes, reduced transparency, and the rejected budget surface R. The headless pixel test checks the inward edge after child painting, its token width, rounded corners and absence of an external halo, including both Glass and GlassSurface paths.

What a copy button can honestly claim

gpui::App::write_to_clipboard returns (). There is no Result, no error, and no callback, so a tick shown because that call returned would be a tick shown because a function with no failure mode did not fail. The one piece of evidence GPUI offers is read_from_clipboard, so CopyButton writes, reads back, and compares; a read that comes back empty or holding something else is reported as a failure with invalid set on a published Status node.

The gap that leaves is stated rather than papered over: a platform where the write lands in a clipboard this process can read but no other application can see would be indistinguishable from success. Nothing in GPUI's surface can tell those apart. A host that knows better supplies its own copier, which returns a Result, and whose failure text is shown verbatim.

The confirmation times out; the refusal does not, for the same reason a Toast reporting a failure does not.

A hover card the pointer can reach

A tooltip may vanish the instant the pointer leaves, because nobody was ever going to point at it. A hover card holds a link, a button, or text to read, and between the trigger and the card there is a gap the surface does not cover. So the card tracks two facts rather than one — pointer over the trigger, pointer over the card — and leaving both starts a countdown that entering either cancels. Only a countdown that runs out closes it, which is what makes the diagonal trip across the gap winnable.

Opening has its own countdown for the opposite reason: a pointer crossing a row of triggers on its way somewhere else opens none of them. Both durations are caller-settable and neither is a token, because they are reaction times rather than paint.

Failures do not time out

A notification that reports a failure — Tone::Danger or Tone::Warning — stays until it is dismissed. A failure the typist never saw is a failure that was never reported, so no timer is allowed to hide one. Every other tone times out after motion.durationMs.toast, and a pointer resting on a toast pauses its timer so nothing disappears mid-sentence.

The stack has a cap. When it overflows, the oldest toast that both times out and can be dismissed leaves first; a persistent one is never evicted to make room, and when nothing may be evicted the cap yields rather than swallow a report.

A field says what is wrong without taking back what it said

FormField takes a caller-owned ValidationState: Pending, Validating, Invalid { reason }, or Valid. Validating is a muted busy status, never red; invalid shows the caller's reason and publishes invalid; pending and valid add no invented success or failure sentence. The description and an invalid reason are shown together because they answer different questions — what the field is for, and what went wrong this time. When both repeat the same sentence word for word, only the invalid reason is drawn.

NumberInput and TagInput extend the same rule to what the host holds. A number outside the range stays on screen exactly as it is, published invalid; a tag the field will not take leaves the typed text in place and says why. Neither silently corrects the caller, because a value nobody chose is a value nobody can trust.

A settings row withholds the control, not just the colour

A setting decided by policy, and a setting that belongs to a section which does not apply on this machine, are both shown with their value and with a line saying so. Neither renders the control the caller passed: dimming a live switch leaves something on screen that can be operated to no effect. The section states the reason once above its rows rather than once per row.

The timeline does not know what time it is

Timeline takes times and day headings as finished strings. Turning an instant into words is calendar, time-zone and locale work, which this crate does not do: the date components push the same work out to a DateAdapter rather than guessing at it, and a timeline entry's wording is pushed out one step further, to whoever already holds the clock. An entry with no known time is neither floated to the top nor dropped to the bottom: it says its time is unknown and publishes time unknown as its value.

Agent run

A conversation is not the unit an agent application shows; a run made of steps is. These three are that vocabulary, and every one of them exists because a plainer component would have to collapse two facts into one.

GraphNode does not compress execution into a success flag. Pending, Idle, Queued, Starting, Running, Waiting, Blocked, Succeeded, Partial, Failed, Refused, Cancelling, Cancelled, TimedOut, and Unavailable remain distinct semantic values. Related states may share a theme tone, but wording, a static glyph, busy state, and invalid state preserve the distinction when colour or motion is unavailable. Every routed edge remains a named semantic group in Inspect and Arrange modes; Edit changes that same stable target into the disconnect action rather than making topology disappear from non-editable semantic trees.

GraphNode has four typography levels: the title uses label size with strong weight, while the muted kind uses caption size on the same label-height header line; ports use caption type in their own rows; note(text) uses muted caption type inside a Faint wash of the node colour, Control rounding, and body padding; the metric strip uses caption type with spacing.sm between figures. Header and port rows and body sections use spacing.xs gaps. Every size and explicit line height scales with the node zoom. NodeMetric::new(label, value) stays bare; .labelled() shows a muted label, a spacing.xs gap, and a normal-colour value. The strip wraps whole figures, including their visible labels. External NodeMetric struct literals must supply the new labelled: bool field; constructor callers keep the existing bare appearance.

Notes grow with their shaped text up to four lines by default; note_lines(n) changes the limit (zero means one). GPUI line clamping supplies the ellipsis, including for bilingual text, while the node-id.note Text semantic description keeps the full display-safe caller text. Compact nodes omit the body entirely. Before prepaint, graph geometry estimates wrapped note rows including both inset layers; actual measured geometry replaces this estimate.

Both thumbnail and content slots install ThemeOverlay(theme.scaled(zoom)). This scales tokens read by descendants during rendering, not arbitrary pixel styles already built by the caller, nor image pixels or inherited text styles. A descendant that reads cx.theme().radius(Radius::Control) inside that overlay must use that radius directly, without multiplying by viewport zoom again. A raw image built outside the overlay with a captured unscaled radius still needs its explicit zoom multiplication. Images must keep their own rounded style: GPUI's overflow_hidden content mask is rectangular, so the thumbnail wrapper's radius does not round its children. Moving an image into a render-time theme-reading component is what makes removing the caller multiplier correct, not removing the image's radius.

A refusal is not an absence and not an error

ToolCallState is five states, not a flag beside a result: PendingApproval, Running, Succeeded, Failed, and Refused. The last two are the pair that gets collapsed everywhere else, and they say different things. A failure blames the tool for something it did and carries the host's error; a refusal is a decision somebody made before anything ran, and carries the host's reason. A third thing is neither: ToolOutput::Silent is a call that ran, succeeded, and returned nothing. Each publishes its own name in value and renders its own consequence, and a refused card publishes no elapsed time at all, because nothing ran to take any.

An elapsed time is a string the caller already wrote — the rule Timeline and TransportBar keep — and a duration nobody stated is Elapsed::Unknown, which says so rather than reading as zero.

A body publishes its shape, never its text

Arguments and results are somebody else's data and may be a credential, so a ToolBody node carries only the measurement: 2 of 4 lines shown when the caller set max_lines, and 4 lines when it did not. The same sentence is drawn beside the block, so the cut is stated where it happens rather than implied by a fade, and it is stated whether or not anything was cut, so "there is more" is read off the same line every time.

A step's state is Pending, Running, Done, Failed, or Skipped, and the last two carry the host's own words: a step that never ran and a step that ran and failed are different sentences, published under different names.

Three states, and no Option to lose one in

Reasoning::Present, Reasoning::Withheld, and Reasoning::Absent. An Option<String> cannot hold this: its None would have to stand for both "the provider withheld it" and "there was none", and a block that says nothing was produced when in fact it was withheld states something nobody established. So the type has three variants, no conversion from Option, and a required reason on Withheld — whoever withheld it has to say so, and the words are shown verbatim. Only Present can be opened: the other two install no toggle handler at all and publish Text rather than Button, and an open block renders its body while a closed one renders none, the rule Accordion keeps. Reasoning that exists and is empty is still Present.

Permission and cost

The two places in an agent application where a careless interface misleads somebody about something that matters: what it is allowed to do, and what it is spending.

The default is refusal

ApprovalPrompt is arranged so that nothing makes approving easier than declining by accident. The keyboard lands on decline when the prompt appears, the way Dialog opens a destructive confirmation on cancel; return acts on whichever control holds the keyboard, so a return key pressed at rest declines and approving with the keyboard costs a deliberate tab first; and escape declines, which is both what escape does everywhere else here and the safe direction. The request is stated specifically — the constructor takes what is about to happen, and there is no way to describe it as a category — with the exact path, command, or host beside it in a DescriptionList.

Declined, Expired, and Superseded are three states, not one. Nobody answering in time is not a refusal, and a request a later one replaced is neither; each publishes its own name and its own sentence, and a host that supersedes a prompt says so through the component rather than by removing it, so the reader finds out why the controls went away.

An unscoped "always" does not exist

AlwaysScope has no variant meaning "always, everywhere". It is the session, or one named tool, one named path, or one named host, and the wording on the control is derived from the variant — so a control offering a standing permission without saying what the permission covers is not something a caller can construct.

Not applicable is not denied

A PermissionMatrix cell is Allowed, Denied, Ask, or NotApplicable. "This tool has no network to reach" and "this tool is refused the network" are different sentences, and collapsing the first into the second invents a refusal nobody made. NotApplicable has no next state, so it installs no handler even in an editable matrix; a matrix given no on_change is read-only, publishes Cell rather than Button, and installs nothing anywhere.

Provenance is carried, never derived. Deciding which rule won is policy evaluation over a rule set the host owns — the same kind of fact the date components take from a DateAdapter — so a cell renders the PermissionSource it was handed, either naming the broader rule it came from in the host's own words or saying it was set here, and computes nothing.

An estimate says so wherever it appears

Quantity has no constructor that takes a bare number: Quantity::measured and Quantity::estimated name the basis in the same call, so a number reaches a screen with the fact that it was estimated attached or it does not reach a screen. The label is in the drawn text, in the mark beside it, and in the node's published value, because a reader who saw the number labelled on one surface and bare on another would trust the wrong one.

Reading::Unavailable is a state rather than a quantity: nothing about it is drawn as a number and no proportion is computed from it. Limit::Unknown is the same refusal one level up — a proportion of an unknown total is invented, so ContextGauge draws no fill and publishes no range, exactly as ProgressBar refuses to claim a position for work whose extent is unknown. It does not fall back to the indeterminate sweep either: the sweep means "in flight", and a reading of what has been used so far is not in flight.

A refresh that failed keeps its value: CostLine::stale takes a LastVerified rather than a flag, so a value cannot be marked stale without saying when it was from.

Numbers are the caller's. Currency, token counts, grouping, and where a unit sits are locale work this crate does not do, so a Quantity carries the caller's already-formatted wording and, separately, the bare number — which is used for one thing only, the proportion against a known limit. Nothing here turns a number into text.

Structured data

This crate parses nothing

JsonValue and Schema are plain shapes a host converts into, for the same reason SplitLayout converts to records instead of deriving Serialize: product-neutral infrastructure must not decide which parsing crate an application depends on. A number is carried as the text the document wrote, because f64 cannot hold every integer JSON can write and cannot tell 1.10 from 1.1, and this crate formats no numbers. An object is a list of pairs, because JSON documents have an order and may repeat a key, and a map would silently reorder the first and drop the second.

JsonView does not build on Tree. A tree node is one label; a JSON row is a key and a typed value with different treatments, and there is no Slot here to put a second column into one. It virtualizes over the same uniform_list primitive List and DataGrid use, so it inherits the rule rather than the component: only rendered rows publish nodes, and the container carries how many rows are currently disclosed.

Withheld, null, empty, and absent

Four facts, four renderings. A key the document does not hold produces no row. null is a row reading null. An empty object is a row reading {} that offers no disclosure, so it can never be mistaken for a branch that is merely shut. A subtree the caller withheld is a row marked withheld beside a description of its shape.

The secret never reaches the component: a caller replaces the subtree with JsonValue::Redacted, which carries a shape and no content, so no rendering path and no export can leak it. The published value is withheld and nothing else — not even the shape, which is drawn and never recorded.

A form that cannot draw a field says so

This is the rule SchemaForm exists to keep. A host converting a schema it does not fully understand puts SchemaKind::Unrenderable in place of the field with its own reason; the form refuses a few shapes itself, such as a choice among no choices. Either way the field keeps its place, its label, and its required mark, states the reason where the control would have been, and is still reported by SchemaForm::values as FieldValue::Unrenderable. A required one publishes unrenderable, required and makes validate answer no however much else is filled in.

A form that quietly dropped an argument it did not understand would send an invalid call and let the reader be blamed for it.

Validation has three sources and they stay apart. validate marks required and range-invalid fields, which is all the form can judge on its own. set_field_validation(path, state) advances a caller-owned check on one field; set_validation(state) advances a check or refusal about the complete form. A field's Pending or Validating state blocks validate from approving a submission but never paints invalid chrome. A whole-form refusal is shown once and makes the form invalid without copying the reason or red chrome onto every field. Field validation setters return false for a path the current form does not hold, so an asynchronous answer for a removed repeated item cannot become an invisible submission blocker. set_error remains shorthand for an invalid field state in the host's own words.

Conditional visibility has the same ownership boundary. The host evaluates its product rules and advances set_field_visibility(path, state); the form does not grow a predicate language or infer conditions from values. Visible participates normally. Hidden { submission: Omit } removes the field or subtree from submission_values, while Hidden { submission: Include } preserves every held value beneath it. Both hidden forms disappear from the semantic and visual trees and skip field validation, because a refusal on a control nobody can reach would be an invisible blocker. A host refusal about a hidden value belongs in whole-form validation, where it can be read.

values remains the complete inventory, including hidden and unrenderable fields, so changing a condition never destroys caller data. A hidden object or repeating-list parent governs its whole subtree; child configuration becomes effective again when that parent is visible. Repeated child visibility follows the stable item entity across reorders just as field validation does, while submission_values always exports current indexed paths.

Files keep the same boundary. The form owns its drop target, selected rows, maximum count, removal, and FilesRequested event. The installed SchemaFilePolicy decides whether a complete candidate selection is admissible and supplies display names; the host opens the platform picker and returns paths through set_files. A repeating List needs no host policy: it creates nested forms with monotonic visual identity, routes indexed field validation to the stable child form, reports indexed values and errors, and applies the same date/file adapter requirements recursively.

Five connection states, and an answer that was empty

ServerState is Connected, Connecting, Disconnected, Failed, and Disabled. The last two are the pair that gets collapsed elsewhere and they say different things: something broke, against nobody wanted it. A failure keeps the host's reason on screen and offers exactly one control, which reports a retry and retries nothing. A connection the reader turned off is refused rather than dimmed — nothing on its row installs a handler.

Catalog::Offers holding an empty list is an answer; Catalog::Unasked is the absence of a question. Rendering the second as the first tells somebody their server is useless when the truth is that the application has not asked yet. Asking and Unavailable are the two remaining states, and each is drawn as itself.

Nothing here names a protocol or a vendor. A connected thing is a server, what it offers are tools, skills and resources, and an offering's id carries the server that offers it, because two servers may offer the same name.

What every component agrees on

These hold across the families above, so a habit learned on one component transfers to the next.

Identity. A constructor takes impl Into<Ident> and derives every child id from it with Ident::child. A part with no business identity — a loader cell, a skeleton row — gets indexed_element_id and publishes nothing. Purely decorative display components (Badge, Card, ListRow, Divider, Avatar, StatusLine, Callout, Kbd) take no Ident and publish a node only when the caller gives them one with .id(..), so an ornamental badge does not bury the assertion target next to it.

Refusal. Anything that can be refused implements Disableable. A refused control installs no handler — not a handler that returns early — so it cannot fire even if a host mis-routes an event, and it publishes disabled: true. Dimming alone is not a refusal.

Size. Anything with a size implements Sizable and takes every metric — height, horizontal padding, gap, font size, glyph size — from one step of control.* in the token document. A sm button and a sm select are the same height because they read the same row of the same table; nothing hard-codes a height beside it.

Selection. Anything that can present itself as the current choice implements Selectable.

Reading direction. LayoutDirection is a global a host sets with set_layout_direction, and components read it during render through ActiveDirection exactly as they read the theme. It defaults to left to right, so a host that never sets one renders what it always did. Components spell edges logically — row_reading, ps/pe, ms/me, border_s/border_e, text_start/text_end — wherever the edge means "where reading begins", and keep saying left and right where the edge is genuinely about the screen: the gutter of a vertical scroll region, a dock region, a split pane's axis. A horizontal arrow key that means previous or next swaps with the direction; one that means "toward an edge", and every vertical arrow, does not. Whether a glyph turns around is a property of the drawing, carried by Icon::mirroring in the asset catalog, so a chevron flips and a checkmark does not.

Focus. Every interactive element is reachable with tab and wears the same ring, from effect.focusRingWidth and effect.focusRingAlpha in the focus colour, applied through FocusRing::focus_ring. The ring is a shadow rather than a border, so focus never reflows what is around it, and it is a different treatment from selection on purpose: focus says where the next keystroke goes, selection says which answer is current. Selection is a neutral wash and nothing else, so the two never wear one appearance: focus is a halo around the shape, selection is the shape's own fill.

What a node's value means

value carries the one fact a node reports about itself that a reader would otherwise have to measure off the pixels:

• a control that holds something publishes what it holds — the committed text of an input, the label of the chosen option, a divider's ratio, a scrollbar's position and reach, a progress position;
• a container publishes how much it holds, as a count — a list's total, a toolbar's item count, the number of pages, the number of rows an ellipsis stands for, the tags in a field against its limit;
• a state carrier publishes the name of the state rather than its colour — a toast's tone, a header's sort direction, which of empty, unstarted, unavailable, or failed an empty state names;
• a refused row publishes the host's reason for refusing it.

value never repeats a label, a role, or a position in a list; the node's text carries the name, and bounds carry the geometry.

What a component owns

A component holds hover, focus, open, and animation state. It never holds the answer: a value, a selection, and a list all belong to the caller. A host that refuses a change simply does not apply it, and the control keeps showing what is still true. This is why Select reports the option that was picked instead of moving its own checkmark.

Validation

Every component appears in gpui_kit::scenes, which xtask headless check renders offscreen in every bundled theme and crates/gpui-kit/tests/it/scenes.rs audits headlessly. Behaviour is asserted through simulated key and mouse input against the published semantic tree, in crates/gpui-kit/tests/it/.

The catalog is in two tiers, and the difference is what "appears in" means. Almost every rendering is an exhibit: it is about one component, it lives in crates/gpui-kit/src/scenes/<family>.rs next to the other renderings of that family, and it is where a reader is sent to review that component's states. xtask api check fails when a public component has no exhibit, so a component cannot be added and left unseen, and it fails when an exhibit claims a component its own source never builds, so a component cannot be covered by a picture of something else that happens to mount it.

The remaining three are compositions — motion-flip, motion-state, and reading-direction — built the way a product would build them, because components interact in ways none of them shows alone. A composition is nobody's coverage: Shows::Composition says so, and the scenes list on a component in docs/api-index.json therefore names only the exhibits, which is the honest answer to "where do I go to look at this".