Live line
A step running now: its words shimmer, its time counts beside them, and both settle in one frame when it ends.
import { Elapsed } from "@arcadia/ui"import { Collapsible, CollapsibleHeader, Elapsed } from "@arcadia/ui";
function Trail() {
const run = useRun(5200, 2600);
const think = useRun(3400, 3000);
const done = run.until !== undefined;
return (
<div {...sx("cmp-stream", cmp.stream)}>
<Collapsible step tone={think.until !== undefined ? "muted" : "neutral"} loading={think.until === undefined} expandable={false}>
<CollapsibleHeader action={think.until !== undefined ? "Thought for" : "Thinking"} details={think.until !== undefined ? `${Math.max(1, Math.round((think.until - think.since) / 1000))}s` : undefined}
figure={think.until === undefined ? <Elapsed since={think.since} /> : undefined} />
</Collapsible>
<Collapsible step tone="muted" expandable={false}>
<CollapsibleHeader action="Read" details="src/math.ts" figure="120 lines" />
</Collapsible>
<Collapsible step tone={done ? "muted" : "neutral"} loading={!done} expandable={false}>
<CollapsibleHeader action={done ? "Ran" : "Running"} details="Math tests" figure={<Elapsed since={run.since} until={run.until} />} />
</Collapsible>
</div>
);
}import { Collapsible, CollapsibleHeader, Elapsed } from "@arcadia/ui";
function Usage() {
const startedAt = Date.now();
return (
<Collapsible step loading>
<CollapsibleHeader action="Searching the web" details="update channels" figure={<Elapsed since={startedAt} />} />
</Collapsible>
);
}A step running now is one line: its verb is the kit's Shimmer (a live Collapsible's loading), and its time is an Elapsed in the line's figure, a small step after its words, in the line's own text style, --text-3 and tabular figures, counting from the step's start. A long line fades its words and keeps the time whole beside them. When the step ends, the caller hands the past tense and until in the same render: the label stops shimmering and the time stops in one frame. Nothing rolls, so a trail where many lines end at once stays still.
Every Elapsed reads one shared clock: a tick a second for all of them, a minute apart while nobody is at the window, none while it is hidden.
Examples
An agent's work, folded
While an agent works, its conversation shows what it writes and, under the last of that, one line: the current step, shimmering, with its one clock beside it.
The clamp test fails on a reversed range. Swapping the bounds first keeps every call site as it is.
import { useState } from "react";
import {
Collapsible, CollapsibleHeader, CollapsiblePanel, Elapsed,
} from "@arcadia/ui";
function Folded({ open: initial = false }: { open?: boolean }) {
const [since] = useState(() => Date.now() - 6000);
const [open, setOpen] = useState(initial);
return (
<div {...sx("cmp-stream", cmp.stream)}>
<Collapsible loading open={open} onOpenChange={setOpen}>
<CollapsibleHeader action="Thinking" figure={<Elapsed since={since} />} />
<CollapsiblePanel>
<Work live />
</CollapsiblePanel>
</Collapsible>
</div>
);
}Its thinking and every action are the line's panel, closed until the caret opens it; the caret shows under the pointer and on keyboard focus, and stands at rest where nothing can hover.
Opened
The panel holds the steps in order and stays open as more arrive, and the step at work is the line itself: inside, it shows only its body (a thought's words, a command's output), never a second line with the same words, chevron and clock.
The clamp test fails on a reversed range. Swapping the bounds first keeps every call site as it is.
<Folded open />Only the line moves; what needs the person (a question, a permission, a failure that stopped the work) is never inside.
Still
Work that a later message closed is one still line that names what it hides, in kinds and counts.
import { Collapsible, CollapsibleHeader, CollapsiblePanel } from "@arcadia/ui";
<div {...sx("cmp-stream", cmp.stream)}>
<Collapsible tone="muted">
<CollapsibleHeader action="Read a file," details="ran a command, thought" />
<CollapsiblePanel>
<Work />
</CollapsiblePanel>
</Collapsible>
</div>Moving or still, the line stands --stream-gap-work under the message text, 5% more than --stream-gap, so nothing shifts when the work ends.
A time measured elsewhere
ms shows a time the caller keeps on its own clock (a run that paused), and format writes it its own way. It never ticks.
import { Collapsible, CollapsibleHeader, Elapsed } from "@arcadia/ui";
<div {...sx("cmp-stream", cmp.stream)}>
<Collapsible step tone="muted" expandable={false}>
<CollapsibleHeader action="Ran" details="Totals test" figure={<Elapsed ms={1200} format={(ms) => `${(ms / 1000).toFixed(1)}s`} />} />
</Collapsible>
</div>The readout is plain text with no live region, so a screen reader is not told every second. Announce the change of step from the status container instead. Under reduced motion the sweep stops and the label rests in its tone colour; the time keeps counting, since it is the value, not a movement.
Elapsed
since- number
- When the step began, in epoch ms: the readout counts from here once a second.
until- number
- When it ended: the time stops here, in the same frame its line settles. Omit while it runs.
ms- number
- A time the caller measured on its own clock (paused spans left out): shown as given, never ticking.
format- (ms: number) => string
- Writes the time. Default
fmtMs: "4s", "1m 12s". rootStyle- RootStyle
- A component's typed override prop:
Layoutand its documented knobs, each the references it takes or another kit knob of its kind; anything else is a type error at the call site (STYLEX.md).
Rest props go to HTMLAttributes<HTMLSpanElement>.