@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/README.md

@@ -1,567 +1,950 @@
 # @signalcore/ui
 
-SignalCore's interface as React components: what an agent shows (`Surface`), what it asks the
-owner (`RequestCard`), and the two chats built from them (`AgentChat` for the people an agent
-serves, `BuilderChat` for the owner who shapes it), drawn exactly the way the product draws them.
-The web app uses this package, so what you embed is what we ship. For a page that is not React
-there is a `<signalcore-chat>` [widget](#the-widget).
-
-```sh
-npm install @signalcore/ui @signalcore/sdk
+SignalCore's agents inside your product, for the people they serve: your customers talk to the
+agent (`AgentChat`), call it (`VoiceCall`, with the orb), or meet it whole (`AgentSpace`: the
+chat, and the call one switch away), in your React pages or, without React, as
+`<signalcore-chat>`. Every piece looks like your product: your type, your colours, your CSS
+([Theming](#theming)). Every
+piece is built only on the public API (the HTTP routes and the conversation's socket,
+[v3/README.md](../README.md)) and its own hooks; nothing in the platform knows it exists. Our own
+app imports it like any host would; if a component ever needs a private import, the package is
+incomplete. Building and configuring an agent stays in our app and in your backend.
+
+## Install
+
+```bash
+npm install @signalcore/ui react react-dom     # pnpm add, yarn add alike
 ```
 
-Needs React 19. The styles are one CSS file. Besides the SDK, the only dependencies are the
-graph library of the agent's map (`@xyflow/react`, which only `@signalcore/ui/flow` imports, see
-[Windows](#windows-of-an-agent)) and the orb of the voice window (`orb-ui`, MIT, which only
-`@signalcore/ui/voice` loads).
+ESM with its types, one module per file (your bundler keeps what you use; a call's LiveKit loads
+with the first call), and one stylesheet. React 19.2 or later. In Next.js's App Router, draw the
+components from a client component (`"use client"`).
 
-```tsx
-import { Signalcore } from "@signalcore/sdk";
-import { RequestCard, SignalcoreProvider, Surface, useRunStream } from "@signalcore/ui";
-import "@signalcore/ui/styles.css";
-
-const client = new Signalcore({ apiKey });
-
-function Run({ runId }: { runId: string }) {
-  const run = useRunStream(runId);
-  return (
-    <>
-      {run.surfaces.map((surface) => (
-        <Surface key={surface.id} surface={surface} onAction={(action) => send(action)} />
-      ))}
-      {run.requests.map((card) => (
-        <RequestCard key={card.request_id} card={card} />
-      ))}
-    </>
-  );
-}
-
-<SignalcoreProvider client={client}>
-  <Run runId="run_..." />
-</SignalcoreProvider>;
-```
-
-## The two chats
-
-One renderer, two chats, split by who is talking (ADR 0009). Both reach the API through the
-provider's `client`, and both are made of parts a host can compose.
-
-**`AgentChat`** is the chat of the people an agent **serves**: their messages and the agent's, the
-agent's surfaces drawn inline (with their text twin where they cannot be), and a box to write in.
-It speaks to the agent as the person and can never change it.
+Browsers: Chrome and Edge 123, Firefox 120 and Safari 17.5 (macOS and iOS), and later; `widget.js`
+is built for them. These read `light-dark()`, which every default colour is. If your bundler lowers
+CSS for older ones (Vite's default `build.cssTarget` does), set it to these: lowered,
+`light-dark()` becomes a polyfill that ignores a `color-scheme` set anywhere its build did not
+see, and the colours come out invalid.
 
 ```tsx
-import { Signalcore } from "@signalcore/sdk";
-import { AgentChat, SignalcoreProvider } from "@signalcore/ui";
+import { AgentSpace, createClient } from "@signalcore/ui";
 import "@signalcore/ui/styles.css";
 
-// In the browser: a token your backend minted for this person (never a secret key).
-const client = new Signalcore({ endUserToken });
-
-<SignalcoreProvider client={client}>
-  <AgentChat agentId="agt_…" thread="order-7" placeholder="Ask about your order" />
-</SignalcoreProvider>;
-```
-
-| Prop              | What                                                                                                                                                                                                                                                                                                       |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agentId`         | The agent the person talks to.                                                                                                                                                                                                                                                                             |
-| `thread`          | The conversation to speak in; the agent remembers it. The API's default if none.                                                                                                                                                                                                                           |
-| `placeholder`     | The box's hint. `autoFocus` focuses it.                                                                                                                                                                                                                                                                    |
-| `onSurfaceAction` | Tells you what the person picked or submitted. The chat has already sent it.                                                                                                                                                                                                                               |
-| `loadHistory`     | `(thread) => Promise<ChatMessage[]>`. Without it the chat reads the caller's own conversation through `endUsers.myConversation` when the client has it (an end user's token or a publishable key do), and otherwise starts empty. `messagesFromConversation` turns the API's messages into `ChatMessage`s. |
-
-- A message is sent with `agents.invoke({ input, thread })`; a pick or a form on a surface goes
-  back as `agents.invoke({ action, thread })`, shown as what the person said ("Martes 10:00"). Only
-  the last thing said takes a pick: once the person answers, a surface is a record.
-- **It never shows an approval, a connection or a secret.** When the answer has `waiting_for`, the
-  run paused for the owner to confirm something: the person sees a quiet "waiting for a
-  confirmation", the chat follows the run (`useRunStream`) until it is done, and then shows what
-  arrived. The send button is not usable while a turn runs; the box stays free to write in.
-- Accessible: new words from the agent go to a live region, the box and the conversation are
-  labelled, and everything works from the keyboard (Enter sends, Shift+Enter breaks the line).
-
-**`BuilderChat`** is the chat of the owner who **shapes** the agent: their messages, what the
-builder says and does as it works (steps open to what came back), the surfaces it shows, the cards
-it asks them to answer in place, and what changed.
+const client = createClient({ baseUrl: "https://signalcore.ai/v1", getToken });
 
-```tsx
-<BuilderChat agentId="agt_…" sessionId={sessionId} onSession={setSessionId} />
+<AgentSpace client={client} agentId="agt_…" />;
 ```
 
-A turn streams as it happens and has a stop button (Esc too); answering a card tells the builder in
-the owner's words; reopening a conversation replays it with the cards still waiting. It needs a
-client with the builder's calls (`build.sessions`, `requests`), which `Signalcore` with an owner's
-key has. A host that draws the conversation its own way builds it from what `BuilderChat` is made
-of:
-
-- `useBuildSession({ agentId, sessionId, onSession, model, onEvent, onTurnEnd })` gives the
-  transcript, `loading`, `send` and `stop`;
-- `reduceTranscript` is the pure fold over the builder's events behind it (live and replayed
-  history give the same transcript);
-- `BuilderTranscript` draws the blocks, with `renderers` for the ones that are only content
-  (Markdown for the builder's words, a card that activates a change): the request cards and the
-  surfaces are always the platform's;
-- `StatusLine`, `Composer` (with slots for `tools` and `context`, and a held `value`), and
-  `describeStep` complete it.
-
-## Voice
-
-`VoiceWindow` is a conversation by voice with an agent (ADR 0011): an orb that listens, thinks and
-speaks, the state in words under it, and captions of what was heard and said. The person chooses
-it by pressing the button; the agent never starts it. It is its own entry, so a page that never
-speaks does not load the orb:
-
-```tsx
-import { SignalcoreProvider } from "@signalcore/ui";
-import { VoiceWindow } from "@signalcore/ui/voice";
-
-<SignalcoreProvider client={client}>
-  <VoiceWindow agentId="agt_…" thread="order-7" onSurfaces={(surfaces) => place(surfaces)} />
-</SignalcoreProvider>;
+In this repo the web app depends on it as `workspace:*` and reads its source through the
+exports' `@signalcore/source` condition (`v3/web`'s Vite and TypeScript set it), so nothing waits
+for a build. `pnpm build` writes `dist/` (`tsdown` for the library, Vite for `widget.js`);
+`pnpm widget` serves `widget.html` with the widget over the source, at
+`http://localhost:5176/widget.html?base=…&agent=…&key=…`.
+
+Every component, live, is documented at [signalcore.ai/ui](https://signalcore.ai/ui): Storybook
+over the source (`stories/`), on a demo API in the page, with each component's props read from
+its types and a toolbar for the language, the theme, `--sc-accent` and `--sc-radius`.
+`pnpm storybook` serves it at `http://localhost:6006`; `pnpm storybook:build` writes
+`storybook-static/`, which the API serves at `/ui` (`v3/api/app/webapp.py`).
+
+## Who the page speaks for
+
+`createClient` takes exactly one way to sign in (v3/README.md, Credentials):
+
+| Mode                    | Options                                        | Requests send                                                                                                       | The socket adds                                          |
+| ----------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| Our own app             | `{ baseUrl: "/api", credentials: "cookie" }`   | the session cookie, on the page's origin                                                                            | nothing                                                  |
+| A person, token given   | `{ baseUrl, token }`                           | `Authorization: Bearer <token>`                                                                                     | `?token=`                                                |
+| A person, token fetched | `{ baseUrl, getToken: () => Promise<string> }` | the same, asked of `getToken` when first needed and kept; on a 401 it is asked once more and the request sent again | `?token=`, a fresh one after a socket that couldn't open |
+| An anonymous visitor    | `{ baseUrl, publishableKey, visitorId? }`      | `Authorization: Bearer pk_…` and `SignalCore-Visitor: <id>`                                                         | `?token=pk_…&visitor=<id>`                               |
+
+`baseUrl` is the public API with its prefix (`https://signalcore.ai/v1`). Only our own app
+sends the browser's cookie; every other mode sends none (`credentials: "omit"`). A visitor without
+a `visitorId` is given one (32 random hex characters) kept in `localStorage` under
+`signalcore.visitor` (`VISITOR_KEY`), so they find their conversation on their next visit; where
+the page can keep nothing, the id lasts the page. The publishable key (`pk_…`, made in our app:
+one agent, the sites it may be used from) is public; the visitor id is all that makes a
+conversation theirs.
+
+A person's token is minted by your backend with a secret key that may `talk`, for one hour, naming
+who the person is in your product and the agents they may reach (`SignalCore-Org` when your key
+acts for an organization you manage). Your page asks your backend for it:
+
+```python
+# FastAPI, httpx: GET /signalcore/token for the person signed in to your product.
+import httpx
+
+SIGNALCORE = "https://signalcore.ai/v1"
+
+@app.get("/signalcore/token")
+async def signalcore_token(user = Depends(current_user)):
+    async with httpx.AsyncClient() as http:
+        answer = await http.post(
+            f"{SIGNALCORE}/tokens",
+            headers={"Authorization": f"Bearer {SECRET_KEY}"},
+            json={"agents": ["agt_…"], "external_id": user.id, "name": user.name, "email": user.email},
+        )
+    answer.raise_for_status()
+    return answer.json()  # {"token": "…", "expires_at": "…"}
 ```
 
-- Its turns are the chat's (`agents.invoke`, in the thread) with `modality: "voice"`, so the agent
-  keeps its answer short and puts the detail in a surface, which goes to `onSurfaces`: the window
-  draws none. Like the chat, it never shows an approval, a connection or a secret.
-- `useVoice({ agentId, thread, voice, lang, continuous, onTurn, onSurfaces })` is the loop behind
-  it (listen, send, think, speak, listen again) for a host that lays it out itself: `state`,
-  `level`, `transcript`, `captions`, `start`, `stop`, `mute`.
-- A `Voice` is how to listen and speak: `listen()` (an async iterable of what is said, interim
-  then final), `speak(text)`, their stops, and an observable `state` and `level`. `webSpeechVoice`
-  is the browser's own (`SpeechRecognition` and `speechSynthesis`) and the default; a provider's
-  transport comes behind the same interface. The level is the microphone's while listening and an
-  estimate from the words while speaking, since `speechSynthesis` has no audio to measure.
-- `Orb` is a replaceable primitive (`components={{ Orb }}`, props `state`, `level`, `size`,
-  `label`, `className`). The default is the `circle` theme of `orb-ui` in your tokens; under
-  `prefers-reduced-motion` it is a still disc in a ring whose outline says the state.
-- `useDictation({ lang, onFinal })` (from the core entry) dictates into a message box with the
-  same browser voice.
-
-## The widget
-
-`<signalcore-chat>` is `AgentChat` as a web component in a shadow root, for pages that are not
-React. One script, with React and the SDK bundled in (`dist/widget.js`, about 108 kB gzipped):
-
-```html
-<script src="https://signalcore.ai/app/widget.js"></script>
-
-<!-- An anonymous visitor: a publishable key, bound to the origins it lists. -->
-<signalcore-chat agent="agt_…" publishable-key="pk_live_…"></signalcore-chat>
-
-<!-- A person of your product: a token your backend minted for them. -->
-<signalcore-chat agent="agt_…" end-user-token="…" thread="order-7"></signalcore-chat>
+```ts
+// Any TypeScript server with fetch: the same, for the person signed in.
+export async function signalcoreToken(user: { id: string; name: string; email: string }) {
+  const answer = await fetch("https://signalcore.ai/v1/tokens", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.SIGNALCORE_SECRET_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      agents: ["agt_…"],
+      external_id: user.id,
+      name: user.name,
+      email: user.email,
+    }),
+  });
+  if (!answer.ok) throw new Error(`SignalCore refused the token: ${answer.status}`);
+  return (await answer.json()) as { token: string; expires_at: string };
+}
 ```
 
-| Attribute                        | What                                                                                                     |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `agent`, `thread`, `placeholder` | What `AgentChat` takes. `autofocus` focuses the box.                                                     |
-| `end-user-token`                 | The SDK's `endUserToken`.                                                                                |
-| `publishable-key`, `visitor-id`  | The SDK's `publishableKey` and `visitorId`. Without a `visitor-id` the widget keeps one in this browser. |
-| `base-url`                       | Where the API is (`https://signalcore.ai` by default).                                                   |
-| `locale`                         | `es` (the default) or `en`: the language of its words and dates. See [Words](#words).                    |
-
-The `client` property, set from JavaScript, wins over the attributes: give it any `UiClient` (an SDK
-client with other options, your own proxy). A secret key is not an option here, on purpose. The
-`messages` property, also from JavaScript, changes single words (see [Words](#words)).
-
-It draws in a shadow root with the package's styles inside, so the page and the widget do not
-touch. The page themes it from outside:
-
-- **Tokens.** `--sc-*` custom properties on the element or above it inherit in
-  (`signalcore-chat { --sc-accent: #b4532a; height: 600px }`), and so do the page's font and text
-  color. The element is `display: block; height: 32rem` until your CSS says otherwise.
-- **Dark mode.** The widget follows a `data-theme` of `light` or `dark` on itself or the nearest
-  ancestor (usually `<html>`), and `prefers-color-scheme` without one.
-- **Parts.** Every slot is a part: `signalcore-chat::part(root)`, `::part(composer)`,
-  `::part(message)` (and `::part(message--person)`, `::part(message--agent)`), and the rest of
-  `SLOTS`.
-- **Events.** `surface-action` (bubbles, composed) carries what the person picked in `detail`.
-
-**`<signalcore-space>`** is [`AgentSpace`](#the-shell-agentspace) in the same script, taking the
-same credentials: `<signalcore-space agent="agt_…" end-user-token="…" windows="flow" mode="text">`.
-`windows` lists the app's windows to open (the first takes the stage), `mode` is `text` or `voice`
-(the element writes the person's choice back and dispatches `mode-change`), and `viewer` is
-`end_user` (the default: a widget serves the people of your product) or `owner`, for a page that
-sets an owner's `client`. The script carries the conversation, the browser, the live stream and the
-pages the agent places, and neither the flow map nor the voice: those windows show what the agent
-said they show, and the voice stays on text. It is `display: block; height: 36rem` by default.
-
-If it cannot start (no agent, credentials that make no sense) it shows a quiet line and says why in
-the console. `pnpm build` produces `dist/widget.js` after the library; `import "@signalcore/ui/widget"`
-registers the element from a bundler instead. From JavaScript,
-`defineSignalcoreChat({ tag, createClient })` registers it under another tag, or with your own way
-of making the client.
-
-## What it draws
-
-**`Surface`** draws a surface of the `signalcore-basic.v1` catalog: cards, key-values, tables,
-charts, callouts, images, links, choice lists, slot pickers, forms, a live browser view and live
-streams. A
-surface is data, never code: it draws only catalog components (and the host's own, see
-[Components](#your-own-components)), resolves their bindings, and shows only `https://` addresses.
-
-- What the user does (a pick, a form, a button of your own component) calls
-  `onAction({ surface_id, name, data, label })`, the shape the API's `Action` expects. Without
-  `onAction` the surface is a record: nothing on it can be pressed.
-- **Every surface carries a text twin** (`fallback_text`). A surface whose payload is damaged, that
-  names a component nobody here knows (or one of yours that this page has not registered), or whose
-  drawing throws shows its text twin instead, and the rest of your page carries on.
-- The browser view frames a live page in a sandbox, only from an `https://` address.
-
-**`RequestCard`** draws what an agent needs from the owner: a question, a choice, an app to
-connect, a file, an approval, a secret, or the controls of its browser. These are the owner's
-decisions about safety, so the platform draws them and nobody else can: an agent cannot fake an
-"Aprobar" button because the catalog has no such component, and **a host cannot replace the card
-either**. It follows levels 1 to 4 of [Styling](#styling) (tokens, presets, `classNames`,
-`unstyled`) and takes `apps` to say how your apps look; the provider's `components` never reach it.
-
-Answering goes through the provider's `client` (`requests.resolve`; a secret goes to `vault.put`, a
-file to `documents.addFile`, an app is checked with `connections.refresh`). Without a client,
-`onResolve` is how the answer gets anywhere. Secrets and files never pass through your callbacks.
-
-**`useRunStream(runId)`** follows a run through `client.runs.stream` and gives you the events, the
-surfaces and the requests (as cards) it accumulates, and `status` (`connecting`, `streaming`,
-`paused`, `done`, `failed`). When the run pauses on a request it closes the stream and opens it
-again after the last event once the request is answered, wherever that happened. A host that never
-draws the cards passes `{ cards: false }`, and the API is not asked what they say.
-
-## Windows of an agent
-
-The chats show an agent talking; a window shows the agent itself, as its owner reads it. The web
-app's agent page and map are these two, drawn by the platform from facts and never generated. They
-are **owner windows**: they read the business's overview and the agent's package, so they need an
-owner's credential (`agents:read`), and an end user's token gets a `403`.
-
 ```tsx
-import { AutomationsWindow, SignalcoreProvider } from "@signalcore/ui";
-import { FlowWindow } from "@signalcore/ui/flow";
-
-<SignalcoreProvider client={client}>
-  <AutomationsWindow agentId="agt_..." onOpenFlow={showSteps} onAsk={tellTheBuilder} />
-  <div style={{ height: 480 }}>
-    <FlowWindow agentId="agt_..." onOpen={showPart} />
-  </div>
-</SignalcoreProvider>;
+// The page: a token whenever the client needs one.
+const client = createClient({
+  baseUrl: "https://signalcore.ai/v1",
+  getToken: async () => (await (await fetch("/signalcore/token")).json()).token,
+});
 ```
 
-- **`AutomationsWindow`** is what the agent does: a card for each channel it answers on and each
-  automation, with what a model wrote about the part over what the platform knows (when it runs,
-  its apps, its state, how the last run went). `focusedId`, `attention` and `building` follow the
-  builder to the automation it is working on. `AutomationCard`, `ScheduleMarks` and `AppMarks` are
-  its parts, exported for a page you lay out yourself.
-- **`FlowWindow`** is the agent as a map of its channels, automations, skills, actions, records and
-  apps, with a line for each call, read from its package. A part is picked with a press (`onSelect`,
-  `selectedId`) and opened with a second one or Enter (`onOpen`). It is in its own entry because
-  `@xyflow/react` and its stylesheet are not small: the core entry imports nothing from it, and a
-  test keeps it that way. `agentMap`, `relationsOf` and `kindOf` are exported from it as plain
-  functions.
-- **They fetch for themselves** when given `agentId` and the client has `agents.overview` (and
-  `agents.get` for the map's files); they say they are loading, or that they could not load. What
-  is passed as props (`overview`, `files`) is what is drawn, and nothing is asked. `apps` says how
-  your apps look, as in `RequestCard`.
-- They follow levels 1 to 4 of [Styling](#styling); their slots are `automations`, `automation`,
-  `schedule`, `app-marks`, `flow`, `flow__node` and `status`.
-
-## The shell: `AgentSpace`
-
-Everything a person sees of an agent is a window ([ADR 0011](../../docs/adr/0011-windows.md)), and
-`AgentSpace` is where they sit: a **stage** with the one that matters now, a **strip** of the open
-ones and a **dock** to talk from. The conversation is always one of them. The agent adds more as it
-works, placing a page of its own (`show` with a `window`: a generated window, a surface) or opening
-one of the app's (`open_window`: `automations`, `flow`, `voice`), and the person closes and reopens
-them.
-
-```tsx
-import { AgentSpace, AutomationsWindow, SignalcoreProvider } from "@signalcore/ui";
-import { FlowWindow } from "@signalcore/ui/flow";
-import { VoiceWindow } from "@signalcore/ui/voice";
-
-// Hoisted: a new object each render would draw the shell again for nothing.
-const windows = { automations: AutomationsWindow, flow: FlowWindow, voice: VoiceWindow };
-
-<SignalcoreProvider client={client} viewer="owner" windows={windows}>
-  <AgentSpace
-    agentId="agt_…"
-    thread="order-7"
-    windows={["automations"]}
-    renderVoice={(voice) => <VoiceWindow {...voice} />}
-  />
-</SignalcoreProvider>;
-```
+## AgentChat
 
-- **The registry** is the provider's `windows`: the component that draws each kind of default
-  window, laid over the package's own (`chat`, `browser`, `live`). `automations`, `flow` and
-  `voice` are yours to register, each from its own import, so a page that never shows the map does
-  not load its graph library. Every component takes the same props (`DefaultWindowProps`: the
-  agent, the thread, a label, the agent's words for the window, what the host opened it with), so
-  the windows of this package plug in as they are. A kind with none shows what the agent said the
-  window shows (the text twin), never an error.
-- **`viewer`** says who is looking, because the client does not: `"owner"` (the default) or
-  `"end_user"`. An end user's stage never opens the owner's windows (`END_USER_WINDOW_KINDS`:
-  `chat` and `voice`), whoever asks, the host or the agent.
-- **A pick on a generated window** goes back to the agent as the next turn, the way a pick in the
-  chat does, and the transcript says where a page went ("→ Opened in Sales") instead of drawing it
-  twice. A window the person closed stays closed until the agent puts something new in it. The
-  stage is rebuilt from the conversation's history when it opens, with no resource of its own.
-- **Voice** is the dock's `renderVoice`: when the person speaks, the dock is the voice and the
-  conversation collapses to captions. Without `renderVoice` there is no button for it.
-- **`useWindows`** is the state of the stage without the shell, for a host that lays windows out
-  itself: derived from facts (`place`, `restore`, `observe` a run's journal) and from what the
-  person does (`focus`, `close`, `reopen`). `WindowFrame`, `SurfaceWindow`, `Strip` and `Dock` are
-  the pieces the shell is made of; `renderStrip` and `renderDock` replace two of them.
-- Tab goes strip, stage, dock; Esc closes the window on the stage (never the conversation); under
-  720px of its own width the strip becomes tabs. Its slots are `space`, `strip`, `window`, `dock`
-  and `captions`, and `<signalcore-space>` is it as a web component (see [The widget](#the-widget)).
-
-## Live streams
-
-What a run shows as it happens (the browser it drives, a preview its code renders) is a live
-stream, and **`LiveView`** watches one: the pictures it sends, drawn on a canvas as they arrive.
+The conversation and its composer, for a conversation your page already has (one it started with
+`client.conversations.start(agentId)`, or one it kept):
 
 ```tsx
-<SignalcoreProvider client={client}>
-  <LiveView streamId="liv_..." aspect="16:9" input={false} onStatus={(status) => {}} />
-</SignalcoreProvider>
+<AgentChat client={client} conversationId="cnv_…" name="Lucía" onTool={onTool} />
 ```
 
-- **Where it comes from.** The `live` template (a `Live` component in a card) draws a `LiveView`,
-  and the `Browser` component and the hand-over card draw one when they name a `stream_id`, in
-  preference to the hosted browser's live URL and to screenshots. `client` needs `live.connect`,
-  which the SDK's `Signalcore` has (`client.live`); a host that reaches the API with a cookie
-  supplies it with `new Live({ baseUrl })` from `@signalcore/sdk`.
-- **The picture.** The canvas takes the stream's size from its first frame (`aspect` holds its shape
-  until then), shows the newest picture and never a queue, and has a role of `img` with a label
-  (`label`, "Vista en directo" by default, "Live view" in English). A quiet word says how it is
-  ("en directo", "reconectando", "terminado", "no disponible"; "live", "reconnecting", "ended",
-  "unavailable" in English). It does not animate for people who prefer reduced motion.
-- **Dropped connections** are opened again, after half a second and then twice as long up to ten
-  seconds. A stream that ended, or that the server refuses (not signed in, not allowed, no longer
-  there), is not. A stream that never answered is given up on after three tries: `onStatus` then
-  says `unavailable`, and the browser view goes back to its live URL or its screenshots.
-- **Input.** With `input`, once the stream says it takes input, the pointer (clicks, double clicks,
-  drags), the wheel and the keys go to the stream in its own pixels, and the canvas can be reached
-  with the keyboard: keys are sent only while it has the focus, Tab leaves it, and keys held when it
-  loses the focus are let go. Whether it is the person's turn is for the stream's producer to say; a
-  browser session takes input only while the agent has handed the controls over, which is when the
-  hand-over card turns `input` on.
-
-## Styling
-
-Five levels, from nothing to everything. Each one is optional, and each works without the next.
-
-**1. Inherit.** Dropped into any page it uses **your font, your text color and your color scheme**
-(`font-family: inherit`, `color: inherit`, tints of `currentColor` for lines and muted text). Dark
-mode follows `prefers-color-scheme`, and an ancestor with `data-theme="dark"` (or `"light"`)
-decides when you set it. This is the whole of the work for many pages.
-
-**2. Tokens.** Everything else is a `--sc-*` custom property with a default. Set what you want
-different, in CSS or through the provider, which writes them as inline custom properties on its
-own wrapper element:
-
-| Token                                           | What                                                        |
-| ----------------------------------------------- | ----------------------------------------------------------- |
-| `--sc-accent`, `--sc-accent-fg`                 | The owner acting: primary buttons, selection, links         |
-| `--sc-bg`, `--sc-surface`, `--sc-sunken`        | What it sits on, a card's face, a recessed area             |
-| `--sc-line`, `--sc-line-strong`                 | Borders                                                     |
-| `--sc-text`, `--sc-muted`, `--sc-subtle`        | Ink (default: your text color)                              |
-| `--sc-danger`, `--sc-ok`, `--sc-signal`         | State, each with a `-soft` tint                             |
-| `--sc-radius`, `--sc-density`                   | The corner of a card; how much room things take (1 is ours) |
-| `--sc-font`, `--sc-font-mono`, `--sc-font-size` | Default: your font; the reading size is 14px                |
+Its props, words and parts are below ([AgentChat](#agentchat-1)).
 
-```tsx
-<SignalcoreProvider theme={{ accent: "var(--primary)", radius: "var(--radius)", density: 0.9 }} />
-```
+## AgentSpace
 
-**3. Presets, found for you.** By default (`theme="auto"`) the provider asks your page's root for
-the variables of the design systems it knows and maps the tokens onto the first it finds:
-**shadcn** (`--primary`, `--background`, `--card`, `--border`, `--foreground`…), **Radix Themes**
-(`--accent-9`, `--color-background`, `--gray-6`…) and **Material 3** (`--md-sys-color-primary`,
-`--md-sys-color-surface`…). So in a shadcn app the surfaces already use your primary, your card and
-your radius, in light and in dark, with no configuration. A page that uses none keeps level 1.
+An agent in your page, whole, for your customers: the conversation and, when the agent has a
+voice (its face, `GET /agents/{id}/face`, says `voice.enabled`), two modes beside the
+composer's paperclip, **text** and **voice**, in one small segmented control.
 
-```tsx
-<SignalcoreProvider />                                         {/* auto */}
-<SignalcoreProvider theme="shadcn" />                          {/* skip the search: Radix needs this inside its <Theme> */}
-<SignalcoreProvider theme={{ accent: "var(--brand)" }} />      {/* over the detected system */}
-<SignalcoreProvider theme={{ preset: "material", radius: "4px" }} />
-<SignalcoreProvider theme="none" />                            {/* nothing mapped */}
-```
+- **Text** is the chat (`AgentChat`), as below.
+- **Voice** turns the same panel, at the same size, into the call (`VoiceCall`): the orb, what
+  the call is doing (connecting, listening, thinking, speaking), and what is being said, as
+  captions under the orb (the person's last words and the agent's answer as it comes, read live
+  from the call's own conversation). The modes stay at its foot. `POST /agents/{id}/calls` makes
+  the call and a conversation of its own, the person's.
+- **Back to text**: ending the call, or choosing text (which hangs up), comes back to writing:
+  once the agent took the call, in the call's conversation, where what was said shows (told
+  through `onConversation`, like one the space starts); after a call nobody took, where the
+  person was. A call that couldn't begin (no microphone, refused, nobody answering) stays to say
+  why, with a button to try again and the modes to go back.
 
-The search reads, and never writes: the tokens go on the provider's wrapper, not on your `:root`.
-It runs in the browser only (a server renders as if none were used, and the client then finds
-out), and again when `data-theme` or `class` on `<html>` changes. The tables of variables are in
-`src/presets.ts`; adding a system is adding a table.
+The modes are a radio group (`role="radiogroup"`, each mode a `radio` named by its glyph and its
+word): Tab reaches the mode that is on, the arrows (and Home, End) move to the other and choose
+it, and after a switch the keyboard stays on the modes, drawn anew where the person now is.
 
-**4. Class hooks.** Every element is a named slot with a stable BEM class and attributes:
-`sc-card`, `sc-card__title`, `sc-button sc-button--primary`, `data-sc="button"`,
-`data-sc-mod="primary sm"`. `classNames` adds yours by slot (the list is `SLOTS`), or by slot and
-modifier:
+There is no header by default: the space is the conversation, and your page says who the agent
+is. `header` draws the agent's face at the top (its mark in the tint it keeps, its name and
+role), or draw your own from `useAgentFace(client, agentId)`.
 
 ```tsx
-<SignalcoreProvider
-  classNames={{ card: "rounded-xl border bg-card", "button--primary": "bg-primary" }}
+<AgentSpace
+  client={client}
+  agentId="agt_…"
+  conversationId={kept} // optional: the person's conversation to go on with
+  onConversation={(id) => keep(id)} // hears the one it started
+  layout="compact" // or "full", a page's main column
+  header // optional: the agent's face at the top
+  steps="hidden" // optional: by default as the client speaks (AgentChat's `steps`)
+  messages={SPACE_MESSAGES_ES} // Spanish; English by default
+  locale={es} // from "@signalcore/ui/locale"
+  onTool={onTool}
+  onClose={close} // a close button, for a space held in a panel
 />
 ```
 
-**`unstyled`** leaves out the shipped styles (the elements and classes stay), for hosts that style
-everything through `classNames`, as a Tailwind-only app does. The wrapper is then a plain `div`;
-give it `classNames={{ ui: "contents" }}`. The shipped styles sit in a CSS layer (`signalcore`)
-and under the wrapper, so your own unlayered CSS wins without a fight over specificity. A host that
-has layers of its own (Tailwind v4's) says where ours go, before anything fills them, so its
-utilities win over our styles on what it draws around our parts:
-`@layer theme, base, signalcore, components, utilities;` first in its stylesheet, then
-`@import "tailwindcss";`. Layers declared later win, so without that line ours would.
-
-**5. Your own components.** `components` takes the primitives surfaces are built from, the
-catalog's components and components of your own, by name. See
-[Your own components](#your-own-components).
-
-**Patterns.** Where our components have two layouts, you choose; the defaults are the product's.
-They are classes like any other (`sc-table--compact`), and apply to our components only: a
-primitive you replace draws itself.
+Without `conversationId`, or once the one given is gone for the person (404, 403), it starts one
+and tells `onConversation`; a call the agent took is told the same way, as the conversation it
+goes on in. `onClose` draws a close in the face, or without it at the top's end, over the
+conversation. It takes `AgentChat`'s `classNames`, `components`, `suggestions`, `onError`,
+`steps` and `orb` (the call's), and goes one agent per mount (key it on the agent's id).
+`messages` (`SpaceMessages`, `SPACE_MESSAGES` in English, `SPACE_MESSAGES_ES`): `modes`
+(`{label, text, voice}`: the group's name and each mode's word), `again` (try a call that
+couldn't begin again), `close`, `agent` (its name when the face can't be read), `opening`,
+`failed`, `retry`, and `chat` and `voice`, `AgentChat`'s and `VoiceCall`'s own. Parts:
+`sc-space` (`--compact`, `--full`, `--voice`), `sc-space__face`, `sc-space__mark` (`--sky`,
+`--rose`, `--sand`), `sc-space__who`, `sc-space__name`, `sc-space__role`, `sc-space__close`,
+`sc-space__body`, `sc-space__voice`, `sc-space__foot`, `sc-space__modes`, `sc-space__mode`
+(`--text`, `--voice`; `aria-checked` on the one on), `sc-space__caption` (`--person`, `--agent`),
+`sc-space__status`.
 
-```tsx
-<SignalcoreProvider patterns={{ table: "compact", actions: "footer", card: "raised" }} />
-```
-
-| Pattern   | Values                             | What                                                        |
-| --------- | ---------------------------------- | ----------------------------------------------------------- |
-| `table`   | `comfortable` (default), `compact` | Rows with room, or close together for a lot of records      |
-| `actions` | `inline` (default), `footer`       | A form's button under its fields, or set apart on a line    |
-| `card`    | `flat` (default), `raised`         | A bordered area, or one that also lifts a hair off the page |
+## The widget
 
-## Words
+`<signalcore-chat>` for pages without React: one script, React and the stylesheet inside it,
+served by SignalCore beside its API (it follows each release; `@signalcore/ui/widget.js` from
+npm pins a version instead).
 
-Every word the components say themselves (buttons, statuses, card headings, the builder's step
-verbs, the times above a conversation) comes from a dictionary. Two ship with the package, Spanish
-(the default, as the product speaks) and English, and the provider picks one and lets you change
-single words:
+```html
+<script src="https://signalcore.ai/v1/widget.js"></script>
 
-```tsx
-<SignalcoreProvider locale="en" messages={{ send: "Post", verbs: { edit: "Change" } }} />
+<signalcore-chat
+  base-url="https://signalcore.ai/v1"
+  agent="agt_…"
+  publishable-key="pk_…"
+></signalcore-chat>
 ```
 
-- **`locale`** is `"es"` (default) or `"en"`. It decides the words and how dates and times are
-  written ("Hoy 10:32" and "12 oct" in Spanish, "Today 10:32 AM" and "Oct 12" in English).
-- **`messages`** is any part of the dictionary, laid over the locale's: a word you leave out stays
-  as it was. `Messages` is its type, and the key names are in `src/messages/types.ts`. Words that
-  carry a name or a number are functions (`connectWith: (app) => "Connect " + app`), and the
-  groups (`verbs`, what the builder is doing; `liveStatus`; `voiceStates`; and the windows'
-  `automations` and `flow`) can change one entry at a time, at any depth
-  (`{ flow: { verbs: { calls: "runs" } } }`). Define the object
-  outside the render, so the components are not drawn again for nothing.
-- **Another language.** The package has the two. For a third, give every word as `messages` (the
-  type makes sure none is missing) over the `locale` whose dates are closest.
-- **The widget** takes the language as an attribute and the words as a property:
+A web channel (SignalCore, the agent's page, Channels, Web) gives the shortest form: one line
+that puts the widget on the page itself, with the agent and the look the business set in its
+panel (or had the builder set), read by the key as it loads, so a change reaches every site
+without pasting again. `data-locale` and `data-theme` say what `locale` and `theme` would.
 
 ```html
-<signalcore-chat agent="agt_…" publishable-key="pk_live_…" locale="en"></signalcore-chat>
-<script>
-  document.querySelector("signalcore-chat").messages = { send: "Post" };
-</script>
+<script src="https://signalcore.ai/v1/widget.js" data-key="pk_…" async></script>
 ```
 
-- **Not components.** `describeStep` and `workingOn`, which a host that draws the builder's
-  conversation itself calls, are Spanish unless they are handed the words:
-  `describeStep(name, input, useMessages())`.
-
-## Your own components
-
-`components` on the provider takes your own components, by name. Three kinds:
+An element with a publishable key and no `agent` reads its web channel the same way; `contained`
+floats it within its own box instead of at the page's corner, and the `look` property puts a
+look over the channel's (SignalCore's preview).
+
+A round button at the page's corner opens the agent's space in a panel (the whole screen on a
+phone, where the space's own close is the way out); `mode="inline"` puts the space in the page's
+flow at the element's size (560px tall unless your CSS says). A visitor's conversation is kept in
+`localStorage` (`signalcore.conversation.<agent>`) for their next visit. In a bundled app,
+`import "@signalcore/ui/widget.js"` registers it the same way.
+
+| Attribute         | Says                                                                                                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `base-url`        | the public API, with `/v1`                                                                                                                                                                            |
+| `agent`           | the agent's id                                                                                                                                                                                        |
+| `publishable-key` | a visitor of your site (`pk_…`)                                                                                                                                                                       |
+| `token`           | instead, one of your people, by the token your backend minted (set it again when it is renewed)                                                                                                       |
+| `locale`          | `es` or `en`; else the page's `<html lang>`, else the browser's                                                                                                                                       |
+| `theme`           | `light` or `dark`; else the page's `color-scheme`, and where the page names none, dark when its text is light (a page made dark by its own classes)                                                   |
+| `mode`            | `inline`; floating by default                                                                                                                                                                         |
+| `header`          | draws the agent's face over the space (off by default)                                                                                                                                                |
+| `steps`           | `shown` or `hidden`; hidden by default (your page speaks for a person)                                                                                                                                |
+| `stylesheet`      | your own CSS for the widget: the CSS itself (anything with a `{`) or its address; adopted inside the shadow root, after ours. Also the element's `stylesheet` property                                |
+| `unstyled`        | our look's defaults drop away (grounds, lines, shadows, corners, every ink but the page's text), the layout stays: for a host that styles everything                                                  |
+| `shadow`          | `none`: no shadow root; the widget draws in the page (our stylesheet goes first in `<head>`, so your CSS wins), for a host whose global CSS should apply directly. Read once, as the element connects |
+
+By default the widget takes your page's type and ink: the font, the base size and the text colour
+the element inherits come through the shadow root and stand in for our defaults (read as it draws,
+and again whenever `<html>` or `<body>` change or the system's scheme does). Its colours are the
+[tokens](#theming), with neutral defaults: the accent is your text's colour unless you give one.
+Everything else is yours to style: the `--sc-*` tokens on the element or any ancestor, the
+[parts](#parts) by `::part(…)`, your own `stylesheet`, `unstyled`, or `shadow="none"`.
 
-- **Primitives** (`Button`, `Card`, `Table`, `Input`, `Select`, with typed props): every surface is
-  built from yours, so the catalog is drawn with your design system. They add nothing to the
-  catalog; a surface cannot name them. The cards that ask the owner to decide never use them.
-  `Orb`, the voice window's, is one too (see [Voice](#voice)).
-- **Catalog components** (`SlotPicker`): a surface that uses the name is drawn by your component,
-  given the properties the agent filled (bindings resolved), its `children` drawn, and `onAction`
-  to report what the user does. They are not checked: read them loosely.
-- **Components of your own** (`PropertyCard`): things of your product that an agent shows in your
-  design, with props the API checks. See below.
-
-```tsx
-<SignalcoreProvider components={{ Button: MyButton, SlotPicker: MySlots, PropertyCard }} />
+```html
+<style>
+  signalcore-chat {
+    --sc-accent: #0f766e;
+    --sc-accent-fg: #fff;
+    --sc-radius: 6px;
+    --sc-orb-color: #0f766e;
+  }
+  signalcore-chat::part(message-person) {
+    background: #0f766e;
+    color: #fff;
+  }
+</style>
+<signalcore-chat base-url="…" agent="agt_…" publishable-key="pk_…" stylesheet="/widget.css">
+</signalcore-chat>
 ```
 
-### A component of your own
-
-An agent can show a listing, a quote or a ticket as your product draws it, if SignalCore knows the
-component: its name, a schema for its props and a text twin. It is registered twice, in the page
-and with the API.
-
-**In the page**, a React component that takes the props and, when the user can answer it, reports
-with `onAction`:
+## Your own tools, run in the page
+
+A tool of yours declared `client` on the agent (`PUT /v1/agents/{id}/tools/{name}`) runs in the
+person's page: the socket sends `{"type": "tool", "id", "name", "input"}`, the chat calls
+`onTool`, and sends up `{"type": "tool_result", "id", "output"}` with what it resolved to
+(`null` for nothing) or `{"type": "tool_result", "id", "error"}` with the message it rejected
+with (an error is cut to the 2000 characters the API takes). Its step shows as working
+meanwhile, like any step (`messages.steps[name]` words it), and the reply as under way until the
+step is done or failed. Each call runs once; one told again while it waits (the socket opened
+anew: the API tells a person's page again every call still awaited) is answered again with what
+it gave, and the API's `tool` error for an answer no call waits on any more is let pass, never
+shown (noted in the console in development). With no `onTool`, each is refused with
+`messages.noTool` ("This page can't do that"; "Esta página no puede hacer eso" in
+`CHAT_MESSAGES_ES`), so a turn never waits on a page that can't run it; only the person's page
+answers it (the API refuses the business's socket, so our app reading the conversation fails
+nothing).
 
 ```tsx
-import { AgentChat, SignalcoreProvider, type HostAction } from "@signalcore/ui";
-
-interface PropertyCardProps {
-  address: string;
-  price: number;
-  onAction?: (action: HostAction) => void;
-}
-
-function PropertyCard({ address, price, onAction }: PropertyCardProps) {
-  const rate = (fit: boolean) =>
-    onAction?.({
-      name: "rate",
-      data: { address, fit },
-      label: `${fit ? "Good fit" : "Not a fit"}: ${address}`,
-    });
-  return (
-    <article>
-      <h3>{address}</h3>
-      <p>{price} €</p>
-      <button disabled={!onAction} onClick={() => rate(true)}>
-        Good fit
-      </button>
-      <button disabled={!onAction} onClick={() => rate(false)}>
-        Not a fit
-      </button>
-    </article>
-  );
-}
-
-<SignalcoreProvider components={{ PropertyCard }}>
-  <AgentChat agentId="agt_…" />
-</SignalcoreProvider>;
+const onTool = async ({ name, input }: ToolCall) => {
+  if (name === "open_record") {
+    router.push(`/records/${String(input.record)}`);
+    return { opened: true };
+  }
+  throw new Error(`This page has no ${name}`);
+};
 ```
 
-**With the API**, once for your organization: `client.ui.components.put(...)` in the SDKs takes the
-name, a JSON Schema for the props and the text twin (see the SDK's reference for its fields). The
-agent then uses the component in a surface with a node of its own kind:
+## Make it yours
+
+From least to most work:
+
+1. **Tokens**: the `--sc-*` custom properties (colours, type, corners, spacing, shadows, the
+   orb's colour) on `:root` or any ancestor, the same for the React components and the widget,
+   each with a neutral default that follows light and dark ([Theming](#theming)).
+2. **Words**: `messages` on every component (English by default; `CHAT_MESSAGES_ES`,
+   `VOICE_CALL_MESSAGES_ES`, `SPACE_MESSAGES_ES`, `KIT_MESSAGES_ES` in Spanish) and `locale` for the
+   calendars, days and numbers.
+3. **Parts**: in React, `classNames` adds your classes to every named part, by the part's own
+   class (and your stylesheet reaches those classes as it is); in the widget, `::part(…)` from
+   your page ([Parts](#parts)), or your own `stylesheet` inside it.
+4. **Bare**: in React, leave our stylesheet out; in the widget, `unstyled` keeps the layout and
+   drops our look, and `shadow="none"` lets your global CSS in.
+5. **Pieces**: `components={{ table: YourTable }}` draws a block of what the agent shows with
+   your component.
+6. **Headless**: the hooks under the components, to draw everything yourself:
+   `createClient`, `useConversation` (the conversation as the person sees it, `onTool` included),
+   `useLive` (the socket's frames, raw), `useCall` (a call without its drawing) and
+   `useAgentFace` (the agent's face). They are described below.
+
+## The client
+
+`createClient(options)`: where the API is and who calls it ([Who the page speaks
+for](#who-the-page-speaks-for)), and `fetch`, a host's own when the global one is not the right
+one. Errors are an `ApiError { status, detail, code }`. `client.who` is who the page speaks for,
+from its credentials: `"business"` (our app's cookie) or `"person"` (a token, a publishable key's
+visitor); the chat draws a yes the business decides by it, and shows a person none of the
+agent's steps (`steps`).
+
+| Method                                                                      | Does                                                                                                                                                                                                                                                     |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents.face(id)`                                                           | what a person may know of the agent (`GET /agents/{id}/face`): `AgentFace {id, name, role, icon, voice: {enabled}}`                                                                                                                                      |
+| `agents.about(id)`                                                          | what the agent says about itself (`about`, null until written; `about_at`, null once stale) and its `facts`                                                                                                                                              |
+| `agents.describe(id)`                                                       | has the agent write about itself anew (a model call, a few seconds); answers like `about`                                                                                                                                                                |
+| `agents.files(id)`                                                          | the agent's own files (`StoredFile`: `id, path, media_type, size, searchable, created_at`), by path                                                                                                                                                      |
+| `agents.putFile(id, path, blob, searchable)`                                | stores the blob's bytes under the path (replacing a file of that name), its type as the file's; `searchable` makes it knowledge `search_files` reads (text, Markdown, JSON, YAML, PDF). 50 MB at most, 5 GB per organization                             |
+| `agents.deleteFile(id, path)`                                               | removes one of the agent's own files                                                                                                                                                                                                                     |
+| `agents.memories(id)`                                                       | what the agent remembered (`MemoryFact`: `id, text, created_at`), newest first                                                                                                                                                                           |
+| `agents.forget(id, memoryId)`                                               | takes one memory from it                                                                                                                                                                                                                                 |
+| `agents.call(id)`                                                           | the owner's call with the agent from our app (`POST /agents/{id}/voice/token`, `/api` only): `CallToken {url, token, room, call_id, conversation_id}`, LiveKit's address and a token for the call's room, and the call's conversation (a test), made now |
+| `files.list()` · `files.put(path, blob, searchable)` · `files.delete(path)` | the organization's files, shared with every agent: the same three as the agent's own                                                                                                                                                                     |
+| `conversations.get(id)`                                                     | one conversation with its messages, who answers it (`handled_by`: `agent`, `person` or `nobody`) and every change of it (`handovers`); on a channel, `channel`, `contact` (`muted`) and each message's `author`, `delivery` and `decision`               |
+| `conversations.start(agentId)`                                              | a new conversation with an agent                                                                                                                                                                                                                         |
+| `conversations.call(agentId)`                                               | a call with the agent for whoever may talk to it, a person's as theirs (`POST /agents/{id}/calls`): a `CallToken`, what `VoiceCall`'s `connect` answers, with the call's own conversation, made now, where what is said lands                            |
+| `channels.list(agentId?)`                                                   | the organization's channels, or one agent's (`Channel`: `id, agent_id, kind, provider, name, external_id, status, detail, settings, created_at`), the disconnected ones too                                                                              |
+| `liveUrl(conversationId, { fresh? })`                                       | the socket's address, signed in (a promise): `ws:` beside `http:` and `wss:` beside `https:`, with `?token=` (and `&visitor=`) but in our app; `fresh` asks `getToken` for a new token first                                                             |
+
+## The frames
+
+What the socket says, read into `Frame` by `frameOf` (a kind it does not know is let pass):
+
+| Down                                                               | Means                                                                                                                                                                                             |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message {message}`                                                | a message stored: `{id, role, text, action, steps}`; a reply's `steps` carry what it called, what each drew, and `request` while one waits for the person's leave                                 |
+| `text {delta}`                                                     | a piece of the reply as it streams                                                                                                                                                                |
+| `ui {id, surface, awaits?}`                                        | a surface the agent showed, under the step's id; `awaits`: the turn stops until the person acts on it                                                                                             |
+| `step {id, action?, state, output?}`                               | an action running, then its state as it moves: `running`, `waiting`, `done`, `failed`                                                                                                             |
+| `request {id, action, input, decides}`                             | an action waits for a yes before it runs: the person's (`decides: "person"`, the turn stopped) or the business's (`"business"`, the turn went on; its people answer from the app)                 |
+| `tool {id, name, input}`                                           | the agent called one of the host's own tools, to run in the page (`onTool`); its step works meanwhile, and the turn waits for its `tool_result`. Told again on a socket that opens while it waits |
+| `handoff {reason}`                                                 | the agent handed the conversation to a person (`escalate`), and why; it stays quiet in it until released                                                                                          |
+| `holder {handled_by, handover}`                                    | who answers the conversation now (`agent`, `person`, `nobody`), after any change of it, and the change: `{holder, reason, by, title, at}`                                                         |
+| `decision {message_id, decision}`                                  | what was decided of a person's message, when it is stored or settles (`{kind, reason, automation, title, run_id}`), or `null` once cleared                                                        |
+| `done`                                                             | the turn is over: the reply is complete, or it stopped to wait                                                                                                                                    |
+| `stopped`                                                          | the person stopped the reply                                                                                                                                                                      |
+| `error {code, detail}`                                             | `code` for the host to word (`pending`: answer the surface first; `business`: that yes is the business's), `detail` for a log                                                                     |
+| `browser {open, url, title, control, reason, wait, width, height}` | the conversation's browser, whole, whenever it changes (`open: false` once it closed); `control` is who holds it, `reason` and `wait` the agent's hand-over                                       |
+| `browser.frame {jpeg, width, height}`                              | its screen as it paints (base64 JPEG); never stored, kept out of the state (`watchScreen`)                                                                                                        |
+
+Up: `say {text}`, `action {surface, name, data, label}` (what the person did on a surface, `label`
+the words shown for it), `stop`, `browser.control {to}` (take the browser, or give it back),
+`browser.input {event}` (the person's pointer, wheel, keys and pasted text, in the page's pixels,
+while they hold it) and `tool_result {id, output}` or `tool_result {id, error}` (what a host's
+tool gave back, `null` for nothing, or why it failed: `toolResultOf(id, settled)` makes either
+from how the call's promise settled).
+
+## The hooks
+
+- `useLive(client, conversationId, { onFrame, onOpen? })` → `{ open, send(frame) }`. The socket
+  itself: frames down to `onFrame`, `send` up, reconnecting on its own (1s, 2s, 4s, 8s, then
+  10s); `onOpen(again)` says when it is not the first time. A socket that couldn't open may have
+  carried a token that expired: the next try asks for a fresh one (`liveUrl`'s `fresh`), once
+  until one opens. The raw layer a host draws its own things over.
+- `useAgentFace(client, agentId)` → `{ face, loading, error }`: what a person may know of the
+  agent (`AgentFace`: its name, role, `icon` for `agentGlyph`, `voice.enabled`), read once per
+  agent; none while another agent's is read.
+- `useConversation(client, conversationId, { onError?, onHolder?, handover?, onTool? })` → the
+  conversation as the person sees it. `onTool(call)` runs the host's tools the agent calls in
+  the page and its answer goes up (each call once; one told again is answered again with what it
+  gave; the turn stays under way until its step settles); without it each is refused with
+  `NO_TOOL`. It answers `{ messages, draft, pending,
+awaiting, open, loading, error, say(text), act(action), stop(), browser,
+watchScreen(listener), control(to), input(event), holder, handovers }`. The history, read each
+  time the socket opens and kept live by its frames;
+  `pending` from the person's message to `done`, `stopped` or a turn error, `draft` the reply so
+  far. What `step`, `ui` and `request` frames say lands on the reply's steps, so a message is
+  the one place a step is drawn from, live or read back. `awaiting` is the step the turn waits
+  on: a surface to answer, or an action waiting for the person's leave (the step's `request`,
+  `decides: "person"`; `act` on its id with `approve` or `decline`); `say` is refused until they
+  act. A yes the business gives (`decides: "business"`) waits on its step and holds nothing; the
+  person's answer on one, refused `business`, puts it back as the business's. `onError(code)`
+  hears the socket's codes and `load` (the
+  history could not be read): the host words them, the hook shows no text; `tool` (an answer of
+  the page's no call waits on any more) is let pass. `holder` is who
+  answers it (null until the history lands) and `handovers` every change of it, read with the
+  history and kept live by `holder` frames (each kept once; one heard while a read was on its way
+  outlives it); `onHolder(holder, handover)` hears each such frame, for the host's own views of
+  it. `handover` is the last change the host knows of (one it made itself, as its request
+  answered): taken at once, kept once with the frame that tells it too (by its moment and holder),
+  so it shows with the socket down. A `decision` frame lands on its message (`null` clears it). One conversation per
+  mount: key the component on the id. On a channel (v3/CHANNELS.md) the reply runs on its own
+  time: what the person writes there (`author: contact`) and what a person of the business
+  writes (`operator`) are kept without touching the turn, which opens on the reply's first words
+  or step and closes on `done`; and while something of the business's is on its way (`queued`,
+  or `sent` less than a minute ago) the history is read again every 3 s, since where it got to
+  comes in no frame.
+
+## AgentChat
+
+`<AgentChat client conversationId name messages? classNames? components? onError? actions? suggestions? compose? look? steps? write? handovers? onHolder? handover? onTool? />`:
+the conversation, the reply streaming, and the composer (Enter sends, Shift+Enter breaks the
+line; while a reply is on its way the send button is a stop button, Esc stops too, and one quiet
+line over the composer says who is thinking, for how many seconds, and how to stop). The reply
+streams at a reading pace (`reveal.ts`: a few characters a frame, faster the further behind, never
+more than about a second behind the model), and goes on from there once it is stored. A reply
+draws its words as Markdown, then the steps it took as a compact list on a thin line (the
+action's glyph once done, a turning ring while it runs, a ring while it waits, a warning when it
+failed; the action's name; its output), then what each step drew, through `Surface`; a surface takes input while the
+turn waits on it, or while nothing runs and the agent showed it since the person last spoke. A
+step waiting for a yes whoever the page speaks for gives (its `request`, live or read back)
+draws a card headed by `approval`, with the sentence, the action's input and two buttons; on a
+person's page (`client.who`), one the business decides (`decides: "business"`) is a quiet line
+instead, `confirming` ("Waiting for the business to confirm"), never buttons. On a call, a person's message
+that says what they heard of the agent's last words (`heard`, when it wasn't what was stored)
+draws it: with no reply before it, the greeting the agent picked up with (never stored) as the
+agent's words, where it was said; after a reply they cut short, a quiet line under it quoting the
+last of what they heard (`cut(heard)`, `""` when nothing of it was). Where the agent handed the conversation to a person (an
+`escalate` step done, live or read back), one quiet line across the log says so, after the last
+reply of that turn. With `handovers` (a host of the business's) the log draws every change of
+who answers it instead, read and live, each a quiet line where it fell (the agent's own after the
+last reply of its turn), with why and when (`handover(holder, by, name)`, `by` a `HandoverBy`:
+`owner`, `agent`, `platform` or an `automation` by its title; the reason follows it); and under a
+person's message the agent let pass this time (its `decision` a `skip`), a quiet line says so,
+and why (`skipped`). `onHolder(holder, handover)` hears each change live, for the host's own
+views of who answers; `handover` (the host's last change, as its request answered) is drawn at
+once, whatever the socket says. The host picks the conversation;
+the chat has no list and starts none. `name` is the agent's, for the words that address it;
+`messages` are those words, English by default (`placeholder(name, fresh)`: `fresh` while nothing
+is said, `connecting`, `awaiting`, `thinking(name)`, `typing` (the line while it works, where steps
+are hidden), `working` and `writing` (the builder's line),
+`elapsed(seconds)`, `escape`, `cut(heard)`, `empty(name)`: the title of a conversation
+with nothing said, `intro(name)`: a line under it (none when empty), `send`, `stop`, `log`,
+`steps` by action name, `failed` (beside a failed step, in the builder's look), `approval` (the
+head of the approval card), `request(name, action)`, `allow`, `decline`, `confirming` (a person's line for a yes the
+business gives), `handedOff`: the handoff's line, `kit`: the words
+of the surfaces' controls); `locale` is the surfaces' language; `components` is how a block type
+draws (below);
+`actions` is a slot at the composer's left for the host's own controls; `suggestions` are a few
+things the person might say first, offered as quoted lines while nothing has been said (a click says
+one). `compose` (`ChatCompose { text, send, key }`) hands the chat a request from elsewhere on the
+page, such as a button beside it, taken once each time `key` changes (not the one the chat mounts
+with, so a chat mounted again never says it twice; another conversation does not take it either):
+with `send` it is said, once the socket is open (while a reply is on its way or the turn waits, it
+goes into the composer instead); without, it goes into the composer, focused with the caret at its
+end, for the person to finish.
+
+On a channel the person's messages are the contact's, at the right as anywhere; the business's
+side stays at the left: the agent's words with a quiet mark under them for where they got to
+(`delivery`: a clock while queued, a check once sent, two once delivered, two in the accent once
+read, the danger tone with the provider's reason once failed), and what a person of the business
+wrote apart from them, in a bubble of a breath of the accent with who wrote it (`business`)
+under it. The surfaces the agent showed went to the person there, so they only read here (an
+approval still takes the owner's answer), and the reply can't be stopped from here. `write(text,
+files)` takes what is written instead of the socket, for a person of the business answering on
+the channel (`POST /conversations/{id}/operator`): the composer says `write`, takes words and
+files whatever the turn is doing, and empties once the promise resolves; a rejection leaves them
+for the host to say why. The words for it: `write`, `business`, `delivery` by state,
+`undelivered(error)`.
+
+`steps` (`ChatSteps`) is whether the agent's steps show. By default it follows who the page
+speaks for (`client.who`): our app's cookie (`business`) sees them, as the work it is; a person
+or a visitor (`person`) sees none of them (no file searches, memories, tool calls or their raw
+outputs, which may be in English), only what the agent says and shows (its words, its surfaces,
+files, an approval of theirs, the business's line `confirming`) and, while the turn runs, one
+quiet line, `typing` ("Typing…", "Escribiendo…"), without the seconds or the key that stops it;
+nor how long the reply took. `steps="shown"` or `"hidden"` says it either way.
+
+`onTool(call)` runs the host's own tools the agent calls in the page ([Your own tools, run in
+the page](#your-own-tools-run-in-the-page)); without it each is refused with `noTool`, a word the
+agent reads and the person never sees.
+
+`look` is `agent` by default. `builder` is v2's builder chat (`sc-chat--builder`): on the page's
+ground (`--sc-bg`), the line over the composer says what it is doing (the step running by its
+name, `writing` while its words come, `working` otherwise) under the brand's light sweeping
+violet into orange, each block settles in as it comes, a step that returned something opens on it
+(`sc-chat__output`) with `failed` beside one that failed, the send is the brand's gradient and
+the stop the ink, the composer takes the focus, and Esc stops the turn from anywhere on the page.
+`console` adds `sc-chat--console`: the same as a console beside the work, the person's words as
+`❯` prompt lines and the composer as a prompt, in the mono face.
+
+## BrowserView
+
+`<BrowserView live name messages? classNames? />`: the browser the agent drives, live, while the
+conversation has one (`live` is `useConversation`'s; `AgentChat` docks it over its composer). Small
+while the agent works (its screen, who holds it, the address read only, the page's title), with
+`take` and an enlarge toggle; taken by the person, or handed over by the agent, it opens large and
+the screen takes their pointer, wheel, keys and paste. A hand-over shows its reason and `done`,
+which answers the turn's wait and gives the browser back; `giveBack` returns one they took. A
+hand-over whose browser closed meanwhile still shows `closed` and `done`, so the person can go on.
+Pictures come through `watchScreen` and are painted on a canvas, the latest only, at the page's
+size (the owner's own Chrome keeps the size of their window: the browser's `where` is `mine`, and
+who holds it says so). `messages` (`BROWSER_MESSAGES`, English): `agent(name)`,
+`agentMine(name)`, `person`, `take`, `giveBack`, `handedOver(name)`, `done`, `closed`, `expand`,
+`shrink`, `blank`, `screen(where)`.
+
+## VoiceCall
+
+`<VoiceCall connect name tint? orb? orbSize? endedBy? messages? classNames? onAnswer? onEnd? after? captions? />`: a call with
+an agent, the one a customer has on the phone, through LiveKit (`livekit-client`). The call starts
+when it mounts and ends when it unmounts (key it on the attempt for another). It opens the
+microphone first (no call is made for someone who can't be heard), then asks `connect()` where to
+join (`{url, token}`: our API's `client.conversations.call(agentId)` answers both, with the
+call's conversation; `client.agents.call(id)` for the owner's test), joins the room and publishes the microphone; the agent's voice plays as it comes,
+and the call is on once the agent joins (its time counts from then).
+
+What it draws, centred: the `Orb`, large (`orbSize`, 280 px; `orb`: `"wave"`, the default, or
+`"fluid-dots"`), named by what the call is doing (`orbOf(look)`): it rests while the line is
+found, moves with whoever speaks (the agent's voice while it speaks, the person's microphone
+while it listens, each read off `meter` on every frame it draws, so the call renders for neither),
+calms while the agent thinks, and fades and comes to rest once over. The shader paints its own
+colours, or the host's (`--sc-orb-color`); the agent's tint (`tint`: `agentTint(id)`) is the
+chrome's, worn by the still orb where there is no WebGL. Under it what the call is doing in a word (`connecting`;
+`listening`, `thinking`, `speaking`: what the agent says it is doing, LiveKit's `lk.agent.state`,
+or its voice for an agent that says nothing; `reconnecting`; `ended`), then who is being called,
+the time, or how it ended and how long it lasted; under that, while the call is on, `captions`:
+what is being said, as the host draws it (`AgentSpace` draws the call's conversation there); and
+the two controls a phone has, mute (filled with the ink while the microphone is off) and hang up
+(the one red thing), each with its word. Once over, `after` stands in their place: the host's
+offers (call again, go back to writing).
+
+It ends when the person hangs up; when the room closes under them (the agent's goodbye, or its
+longest time, which the room doesn't tell apart: `endedBy`, the API's word as `endedByReason`
+reads it, does); when the line drops (the network, or the agent leaving without closing the
+room); or, before it begins, when the microphone can't be used (refused, missing, held by
+another application, a browser that can't call), when `connect` fails, and when no agent joins
+within 20 s. Each says why in words, and what to do. `onAnswer()` hears once that the agent took
+the call; `onEnd(answered, problem)` hears once that it is over, whichever way (`answered`: the
+agent took it; `problem`: why it never began, a `CallProblem`, null for an end). Where the
+browser holds the agent's voice until a press, a button lets it play.
+
+Space mutes and unmutes from anywhere that isn't a field or a control of the page's own. Escape
+never hangs up: it is the key that closes things, pressed by reflex, and a call ended by accident
+can't be taken back, so ending one is the red button's alone; a host that holds the call in a
+panel keeps the panel open on Escape while the call is on (the root carries `sc-call--on`). Under
+reduced motion the orb draws one still frame per state, and the words say the rest.
+
+`messages` (`VOICE_CALL_MESSAGES`, English): `call(name)` (its name for screen readers), `states`
+by look, `calling(name)`, `ended` by who ended it (`person`, `agent(name)`, `limit`, `dropped`),
+`problems` by why it never began (`denied`, `nomic`, `inuse`, `unsupported`, `failed`,
+`unanswered`), each `{title(name), help}`, `mute`, `hangUp`, `keys`, `muted`, `hear(name)`.
+Parts: `sc-call` (`--connecting`, `--listening`, `--thinking`, `--speaking`, `--reconnecting`,
+`--ended`, `--problem`; `--sky`, `--rose`, `--sand`; `--on` while ringing or talking; `--muted`),
+`sc-call__stage`, `sc-call__orb` (on the orb; its own parts are the kit's `sc-orb…`, which
+`classNames` takes too), `sc-call__state`, `sc-call__line`, `sc-call__captions`,
+`sc-call__sound`, `sc-call__controls`, `sc-call__control`, `sc-call__mute`, `sc-call__hangup`,
+`sc-call__hint`, `sc-call__after`.
+
+`useCall(connect, { sink })` is the call without its drawing, for a host that draws its own:
+`{ state, meter, mute(muted?), hangUp(), hear() }`, the agent's voice playing from `sink` (an
+element of the host's). `state` is a `CallState` (`stage`, `answeredAt`, `agent`, `muted`,
+`end: {by, seconds}`, `problem`…), `lookOf(state)` its word, `orbOf(look)` the orb's state and
+whose loudness it follows (`"agent"`, `"person"` or none), `durationOf(seconds)` the time as a
+phone shows it ("0:07", "12:34", "1:02:03"), and `meter.agent()` and `meter.person()` each side's
+loudness now, from 0 to 1, to read every frame (an `Orb`'s `level` takes either as it is).
+
+## Orb
+
+`<Orb state level size? style? label className? />`: the shape a voice conversation with an
+agent takes, v2's: `state` is `idle` (at rest), `listening`, `thinking` or `speaking`; `level`
+how loud the microphone (listening) or the voice (speaking) is, 0 to 1, a number or a reader
+called on each frame drawn (a meter: the orb follows it with no render); `size` the diameter
+(200 px); `label` its name for screen readers. Two styles (`ORB_STYLES`, `OrbStyle`): `wave`,
+the default, the iOS voice waveform, and `fluid-dots`, six dots that merge and scatter. Both are
+the fragment shaders of siri-wave (MIT), kept verbatim but for the signal they are given (the
+level; the wave also the state's energy: 0 at rest, 0.5 thinking, 1 listening and speaking) and
+the host's colour, on one WebGL canvas. The shaders paint their own spectrum unless
+`--sc-orb-color` names a colour: then their light is painted in it, as bright as it was, so the
+orb is the host's (read off the canvas with each state, so a theme changed shows by the next).
+
+Each style is a module of its own, loaded when an orb of it is first drawn: a host that never
+calls loads none. The orb draws only while something moves: it eases the level and the energy
+toward where they go, its clock paced by the energy (slower at rest), asks for no frame while the
+tab is hidden, and stops three seconds after it comes to rest. Under `prefers-reduced-motion`
+there is no loop: one frame per state, at a fixed moment. The shaders paint light on a
+transparent canvas (what is near black is cut out) blended by exclusion with the surface under
+it: as painted on a dark surface, turned over on a light one, ink on paper (so it needs a
+surface painted under it, and fading it is fading the canvas: `opacity` on an ancestor
+isolates it). Where WebGL is
+missing, the shader doesn't compile or the context is lost, a still disc in a ring stands in, its
+outline saying the state (thin at rest, solid listening, dashed thinking, double speaking) in
+`--sc-orb-color`, else the signal (the agent's tint in a call). Parts (the kit's): `sc-orb` (`--idle`,
+`--listening`, `--thinking`, `--speaking`; `--still` under reduced motion and for the disc;
+`--loading` while its style loads), `sc-orb__ring`, `sc-orb__core`.
+
+## The kit
+
+The primitives everything the package draws is made of, each one BEM family in `styles.css`
+(tokens only), so a host styles each once and every place it appears follows:
+
+- `Card` (`sc-panel`; `sc-card` is the Ficha's), `List` and `Row` (`sc-list`, `sc-row`: a mark, a
+  title clamped to two lines, a quieter line, a detail at the right, a `trailing` slot for the
+  host's controls such as a `Switch` and a ⋯ `Button`; rows grouped in one hairline box, the
+  row pressable with `onPress`, `pressed` for the one picked, `quiet` for one paused), `Mark`
+  (`sc-mark`: what kind of thing a row is, bare, with nothing drawn behind it: a glyph in the
+  muted ink, a logo as it comes, an initial, or a photo, round for a person; it keeps its square
+  so rows line up), `MarkStack` (`sc-stack`: a few marks side by side and "+N"), `FileMark` (a
+  file's mark by its family, `familyOf(name, type)`: PDF, Word, Excel, PowerPoint, picture, video,
+  sound, text, archive; the common formats in their own tint), `Tag` (`sc-tag`: a short word on
+  how something stands, in its tone, no pill; a property every row has is said by the heading
+  the rows sit under, not by a word on each), `Stat`, `Note`, `Button`
+  (`primary`, `neutral`, `danger`, `ghost`; `sm`; a glyph alone; a link with `href`), `Switch`.
+- The form: `Field` (label, a quiet word when optional, help, error, all wired to the control by
+  id) and its controls, each controlled (`value`, `onChange`) and named by `labelledBy` or
+  `label`: `TextInput` (text, email, phone, url, with their icon and keyboard), `TextArea`
+  (grows), `NumberInput` (− and +, its unit), `SecretInput` (show and hide), `Checkbox`,
+  `DateField` (a calendar in a popover, react-day-picker; only the `dates` offered, between
+  `earliest` and `latest`), `TimeField` (the `times` as chips, else every half hour to search,
+  or one typed; `endOfDay`, an end of a stretch, offers and takes the day's end, "24:00", too), `DateTimeField`, `Choices` (few options as cards, or one bar when short),
+  `Chips` (several of few), `Combobox` (the ARIA combobox, one or several, searchable),
+  `RangeField` (a slider with its value over the thumb), `RatingField` (stars).
+
+`<KitProvider classNames? messages? locale?>` gives the primitives under it the host's classes
+(`KitPart`), words (`KIT_MESSAGES`, English; `automation` holds an automation's and its runs',
+`AUTOMATION_MESSAGES`) and language: `locale` is one of `@signalcore/ui/locale`
+(`import { es } from "@signalcore/ui/locale"`), which the calendar reads and whose `code`
+formats days, times, numbers and lists. Popovers render in a portal at the page's end carrying
+`sc`, so the tokens set on `:root` reach them; inside a host's dialog (`role="dialog"`), in the
+dialog, which a modal one needs to let the pointer and the focus reach them; inside an element
+marked `data-sc-portal`, in it (a shadow root's, where the page's end is outside its styles: the
+widget's).
+
+## Automation and RunView
+
+An agent's automation and one of its runs, as its owner reads them (v3/AUTOMATIONS.md), built
+from the kit and drawing only what they are given: the API's objects (`AutomationData`,
+`AutomationView`, `Run`, `RunRecord`, `RunStep`, `Trigger`, `AutomationStep`, `Use`, `Board`),
+the kit's words (`messages.automation`) and its locale's `code`. A host fetches, switches and
+routes; an agent shows one in a conversation as the `automation` block.
+
+`<Automation automation runs? onSwitch? switching? onOpenRun? openRun? apps? now? />`: one card.
+The head: what starts it as a 40px mark (a clock, a webhook, the app whose event it waits for),
+the title, when it runs in words with its next run ("Cada día laborable a las 9:00, próxima
+mañana"), and its state in a word (`active` in the success tone, `paused` quiet, `failing` in
+danger) with the host's switch when it gives `onSwitch` (held still while `switching`). Then the
+owner's sentence (`summary`), set apart; its steps, numbered, each with what it uses (an app's
+logo and name, "IA", "Agente", "Mensaje" for a message to a contact on a channel…); the table it
+moves (`board`), a `Stat` per value, four at most and "+N" after; and, given `runs`, its runs edge
+to edge, each with what started it as its mark (named by it), when, its line (a test's as what it would have done), why it
+failed in danger, a check once it went well; `onOpenRun` makes them pressable, `openRun` lights
+the one open. Nothing in it runs an automation.
+
+`<RunView run automation? onOpenConversation? apps? now? />`: one run. Its head (what started
+it as its mark, when; at its end how it stands and, under it, how long it took); its line; why it failed, in a `Note`; then what it
+did, step by step in the code's order on a rail, each call in words ("Buscó en Gmail",
+"Escribió un texto con IA", "Añadió una fila a Citas", "Abrió una conversación", "Avisó en la
+bandeja", "Envió un WhatsApp a +34…" by the channel the record says, its brand as the mark when
+the host draws brands; a test's writes as "Habría…"), the same call in a row once with "×N", a
+failed one in danger with its error; and, with `onOpenConversation`, the conversation it was
+asked in and those it opened. `automation` names its apps and its table and numbers its steps.
+
+`apps` (`AppDirectory`, as `AgentAbout` takes it) draws apps with the host's brands; without it
+an app shows the logo the API gives, or its initial. The pure helpers: `whenOf(trigger, words,
+code)` and `scheduleOf(cron, words, code)` (a trigger, a cron line, as a sentence; `timed` when
+it names the one time of day it runs), `lineOf(automation, now, words, code)` (the head's line),
+`momentOf`, `dayRefOf`, `timeOf`, `clockOf`, `tookOf`; `verbOf(tool)` (what a tool does, from its
+name), `callWords(step, words.calls, names)`, `groupsOf(steps, words.calls, names)` (a record's
+lines by step) and `namingOf(automation)`; and the cron reader under them, `parseCron`, `fires`,
+`occurrences` and `offsetOf`.
+
+## Surface
+
+`<Surface surface onAction active? answered? components? classNames? messages? locale? />` draws
+what the agent showed: a tree of blocks, one to one with the API's models in `blocks.ts`, each
+mapped onto the kit (a `card` is a `Card`, a `list` a `List` of `Row`s, a `stat` a `Stat`, a
+`button` a `Button`, a form's fields the kit's controls by `kind`: a select with up to 5
+options as cards, more as a combobox; a multiselect with up to 8 as chips, more as a combobox).
+`text` is Markdown: paragraphs, bold, italic, code, links, bullet lists. A block or a field kind
+it does not know leaves the surface to its `text` twin. `onAction` receives `{name, data,
+label}`: a button sends its action with `{}`, a choice `{option: id}`, a list `{item: id}`, a
+form its values by field name (words, a number, true or false, "YYYY-MM-DD", "HH:MM",
+"YYYY-MM-DDTHH:MM", option ids; what is left empty as null) under, when it asks one thing, that
+answer in words (the day, the slot, the options picked), else its submit's label. A form checks
+itself on submit (required, bounds, an email's, a phone's, an address's shape, the days and
+times offered), shows what is wrong under each field in the kit's words and focuses the first.
+`active` false closes the inputs; `answered` (what the person already did on it) draws its
+answer: the option, row or button picked, the form's values with "Sent" where the submit was.
+`components={{ table: TheirTable }}` draws a block type with the host's own component, given
+the block's fields, `active` and `onAction` (a container's `children` come drawn). The pure
+helpers `pressed`, `picked`, `chosen`, `filled`, `labelOf` and `problemOf` are what the blocks
+send and check. An `automation` block draws `Automation` from the `view` the API filled in, read
+only (no switch, its runs not pressable: the agent's page is where it is switched and opened);
+one whose `view` is null says quietly that it is no longer there. A `file` block (`FileBlock`)
+is a file the agent put in front of the person, compact: its kind's mark, its title over its name,
+its size; pressed, it opens whole in the host's viewer (`files.open`, the conversation's
+`FileHost`), where `FileView` draws it whatever its kind. A picture, a video or a sound plays where
+it is instead (`part="media"`, `sc-surface__media`), in the browser's own player, streamed from the
+address the host gives (`files.play`; the conversation's asks `client.conversations.play`, a link
+the API signs for an hour that needs no credential and answers `Range`); a picture pressed opens
+in the viewer, a player whose address ran out asks for a new one once, and a host that can't play
+it keeps the row. Until the API has filled in `file` it is only named, quietly.
+
+## AgentAbout
+
+`<AgentAbout client agentId name messages? classNames? controls? apps? locale? view? onViewChange? onOpenFile? onOpenConversation? />`: Qué puede, made to sit
+beside the conversation (it fits a page too). From the top: who it is about and, in its own words,
+a line or two of what it takes care of; **what it does on its own**, a row per automation, its
+mark what starts it (a glyph for a time or a call, the app's logo for its event), what it does then
+and when (`Cada día a las 8:00`), a paused one quieter; what it asks the person's leave for; then **what it works with**,
+six topics (`TOPICS`): apps (with their marks), tools (what it can do while it talks), knowledge
+(its files and the tables it reads or writes), learning (what it remembered), channels (where
+people write to it, and its devices), keys. Each topic is a row with its glyph, its name over a
+preview of what it holds and its count, quieter when it holds nothing; a row opens the topic in
+the same place, with the way back above it (the host's control on the title's line), a line saying
+what it is, and its rows: an app with its tools by name; every tool, its own code's and the ones
+every agent has under a heading each when it has both, the ones that are off quieter, saying so;
+what it knows by whose it is, its own under its name and the organization's under theirs (said
+once, by the heading), each file by its kind's mark, its name on one line, its folder under it
+(and that it is only kept, when `search_files` does not read it), its size at the right, then
+the tables with what it may do in them; what it learned with when it was kept; keys, its own and
+the organization's, with where they may go. Its channels are read whole when the topic opens (`channels.list(agentId)`, again after
+each `tools.refresh()`): WhatsApp, Instagram and SMS in that order, the disconnected last and
+quieter, each by its brand's mark (`apps.logo` with the kind as its provider) and name, its number
+or handle, the provider's word on it (`channelDetail`), and how it stands on a dot and a word
+(`channelStates`: amber while pending, the danger tone, with the reason under the row, on an
+error); a server without the list shows the facts' rows.
+
+The words are the model's (`describe`), written from the agent's folder, its automations and its
+apps: the summary, one line per automation tied to it by id (`does: [{automation, icon, text,
+when}]`; `automationsOf(about, facts)` pairs them, a new automation showing its title and kind
+until the words catch up) and what it asks leave for. Nobody asks for them: when they are
+missing or the agent changed since (`about_at` null, which a change to its folder, its grants or
+its automations does), the component has the agent write them again by itself, keeping the old
+ones in view with a quiet line; when they could not be read or written, a line in the warning
+tone and a button to try again.
+
+The component only reads. A host that lets its people change things draws its own controls
+through `controls` (`AboutControls`), each given `tools: { refresh() }`, which reads the facts
+again and has the agent rewrite its words when the change made them stale: `newAutomation(tools)`
+over what it does on its own, `automation(fact, tools)` at a card's right, `topic[topic](tools)`
+over an open topic, and `app`, `tool`, `file`, `table`, `memory`, `key` and `channel` (the API's
+`Channel`) at a row's right
+(answer `null` for a row that gets none, such as a shared file). Call `tools.refresh()` once a
+change is through. `onOpenFile(file)` opens a file pressed in what it knows.
+
+It goes one level in and back, in place, like a phone's settings: a topic or an automation from
+its home, a run from its automation. Each view opened from another has a bar that stays at the
+top as it scrolls: the way back, named for where it goes, and at its end the host's controls (an
+automation's are `controls.automation`, the same as on its row). An automation shows as
+`Automation`, flat on the panel, with its runs; a run as `RunView`; both read with `client`
+(`automations.get`, `runs.get`) and again every 3 s while a run is under way (`usePolled`). The
+rows of what it does on its own also say how each stands when it needs a look: a run under way,
+or its last one failed (`automations.list`). A move in slides from the side it lies on, a move
+back from the other, and each view comes back scrolled where it was left. Where it is lives in
+`view` (`AboutView`: `{kind: "home"}`, `{kind: "topic", topic}`, `{kind: "automation", name}`,
+`{kind: "run", name, run}`), the panel's own unless the host keeps it (in its address, say) and
+hears each move through `onViewChange`; `aboutBack(view)` is a step back, for a host's Escape.
+`onOpenConversation(id)` opens a conversation a run opened or was asked in.
+
+`messages` are the words, English by default (`loading`, `writing(name)`, `updating`, `refresh`:
+the try-again button, `asks`, `failed`, `does`, `noAutomations`, `paused`, `kinds`: what an
+automation waits for, `topics`, `empty` and `hints` by topic, `theirs(name)` and `organization`:
+over what is the agent's own and the organization's, `builtIn`: over the tools every agent has,
+`tables`: over the tables, `kept`: under a file nothing reads at a search, `off`, `can`: what it
+may do in a table, `title(name)`, `facts`: over the topics, `actions`: a shipped action's name in
+the owner's words (one of its own code, and any other nobody named, by `actionWords(name)`),
+`size(bytes)`, `ago(when)`, `runGone`: in place of a run no longer there, `channelNames` by kind,
+`channelStates` by status, `channelDetail(detail)`: the provider's word in the host's, `kit`: what
+the kit's pieces in it say, an automation and a run). The pure helpers
+`aboutState(about, aboutAt, loading)`, `automationsOf(about, facts)`, `TOPICS`, `namesOf(topic, facts, label)`, `countOf(topic, facts)`,
+`toolName(action)` (`Gmail.SendEmail` is "Send email"), `actionWords(name)` (`ver_hoja` is "Ver
+hoja", `gmail__GMAIL_SEND_EMAIL` "Send email (Gmail)"), `familyOf(name, type)`,
+`formatSize(bytes, locale?)` and `toneOf(status)` are what it draws from; `FileMark` is the mark
+it gives a file. The package draws its icons with `@phosphor-icons/react`.
+
+## FileView
+
+`<FileView blob name preview? messages? classNames? />`: one file to see and to save, whatever its
+kind: a bar with its kind, its size (a PDF's pages) and the button that saves it under its name,
+over the file as it reads. `preview` is what the API makes of it (`client.files.preview(at)`,
+`FilePreview` by `kind`; `at` is `FileAt`: the organization's `{path}`, an agent's own
+`{agentId, path}`, a conversation's `{conversationId, fileId}`): a spreadsheet as a grid, one
+sheet at a time, its columns kept in view and its sheets as tabs at its foot (how many of its rows
+are shown, when not all); a Word file as a document at a reading measure, its HTML kept again here
+to the API's allow-list (`cleanDocument`); a deck's slides one under another, each a card with its
+notes; Markdown drawn, plain words, a source in the mono face wrapped and never run; a PDF in the
+browser's own viewer; a picture whole, a video and a sound in the browser's players; `unknown`
+says it can't be shown, and saves it. Without `preview` it reads what the browser can of the bytes
+alone (words, a CSV, a PDF, a picture). It fills the height it is given and scrolls inside.
+`messages` (`FILE_MESSAGES`): `download`, `noPreview`, `noPreviewHint`, `truncated`, `file`,
+`size(bytes)`, `pages(count)`, `sheets`, `rows(shown, total)`, `emptySheet`, `slide(number)`,
+`notes`. Parts: `sc-file`, `sc-file__bar`, `sc-file__meta`, `sc-file__body`, `sc-file__text`,
+`sc-file__plain`, `sc-file__code`, `sc-file__sheet`, `sc-file__table`, `sc-file__tabs`,
+`sc-file__tab` (`aria-selected` on the one open), `sc-file__document`, `sc-file__slides`,
+`sc-file__slide`, `sc-file__notes`, `sc-file__frame`, `sc-file__image`, `sc-file__media`
+(`data-kind`), `sc-file__none`, `sc-file__note`.
+
+## AgentCard
+
+`<AgentCard id name role fields renderValue? classNames? />`: the Ficha as a page about the
+agent, one sheet centred at 600px. At the top the agent's mark (the glyph of its work alone,
+bare, in the tint `agentTint(id)` keeps for it everywhere) beside its name, its role under it;
+then its short fields as a quiet list of properties, each label beside its value; under a
+hairline, each `block` field (a long text) under a small heading at a reading measure. `name`, `role` and each of `fields` is a `CardField {key, label, value, placeholder?,
+block?}`; an empty value draws its placeholder, muted. The card draws text; a host that edits in
+place gives `renderValue(field)`, which draws its own control in the text's place (the band's two
+included) and may answer `undefined` to leave a field to the card. `agentTint(id)` is the pure
+helper under the mark: `sky`, `rose` or `sand` from the id, so a rename changes nothing.
+
+## Theming
+
+One vocabulary for every component, in React and in the widget: the `--sc-*` tokens, set on
+`:root`, on `<signalcore-chat>` or on any ancestor. Every visual decision of ours reads one of
+them; their defaults are neutral greys that follow the page's `color-scheme` (`light-dark()`),
+and in the widget the page's own type and text colour stand in for ours. There are no themes or
+presets: a host says what it is, once. Unset, a token keeps the default in the right column.
+
+| Token                                               | What it decides                                                                                                | Default                                                |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `--sc-font`                                         | the face                                                                                                       | the page's in the widget; `ui-sans-serif, system-ui`   |
+| `--sc-font-size`                                    | the base size; every other size is relative to it                                                              | the page's in the widget; `14px`                       |
+| `--sc-font-size-sm`                                 | a notch down: a step, a small button, a kit's details                                                          | base − 1px                                             |
+| `--sc-font-size-xs`                                 | quiet lines: the working line, a meta, a hint, the modes                                                       | base − 2px                                             |
+| `--sc-font-size-lg`                                 | a title: the empty chat's                                                                                      | base + 2px                                             |
+| `--sc-font-weight`                                  | the regular weight                                                                                             | the page's (inherited); 400 where a part resets it     |
+| `--sc-font-weight-medium`                           | names, buttons, the modes                                                                                      | `500`                                                  |
+| `--sc-font-weight-bold`                             | titles, the call's state                                                                                       | `600`                                                  |
+| `--sc-font-mono`                                    | code, the console                                                                                              | `ui-monospace, "SF Mono", Menlo`                       |
+| `--sc-line-height`                                  | the lines' height                                                                                              | `1.5`                                                  |
+| `--sc-fg`                                           | the ink                                                                                                        | the page's text in the widget; near black, near white  |
+| `--sc-muted`                                        | quieter ink: roles, hints, placeholders                                                                        | grey                                                   |
+| `--sc-subtle`                                       | quieter still: a meta, the builder's line                                                                      | lighter grey                                           |
+| `--sc-bg`                                           | the page's ground (the builder's), what sits on the main action                                                | off-white, near black                                  |
+| `--sc-surface`                                      | the panel, the chat, cards, the composer, the call                                                             | white, `#121212`                                       |
+| `--sc-sunken`                                       | a notch off the surface: code, a step's output                                                                 | a breath off it                                        |
+| `--sc-line`                                         | hairlines and borders                                                                                          | light grey, white at 12%                               |
+| `--sc-accent`                                       | the launcher, a step running, a picked option, the caret, focus                                                | the ink                                                |
+| `--sc-accent-fg`                                    | what sits on the accent (the launcher's glyph)                                                                 | the surface                                            |
+| `--sc-signal`                                       | the agent at work: the breathing dot, the still orb                                                            | the accent                                             |
+| `--sc-primary`, `--sc-on-primary`                   | the main action (send, a primary button, mute on) and its glyph                                                | the ink, `--sc-bg`                                     |
+| `--sc-bubble`, `--sc-bubble-fg`                     | the person's message, and its text                                                                             | the ink at 5% over the surface, the ink                |
+| `--sc-read`                                         | the two checks of a message the person read                                                                    | WhatsApp's blue, `#53bdeb`                             |
+| `--sc-success`, `--sc-warning`, `--sc-danger`       | the tones a note, a step, a field's error take                                                                 | green, amber, red                                      |
+| `--sc-danger-fg`                                    | what sits on the danger tone filled (hanging up)                                                               | white                                                  |
+| `--sc-sky`, `--sc-sand`, `--sc-rose`                | the agent's tints as inks (its mark in the face, the still orb in a call); the wash under each derives from it | blue, sand, rose                                       |
+| `--sc-brand-from`, `--sc-brand-to`, `--sc-on-brand` | the brand's gradient: the builder's sweeping light and its send (our app's)                                    | violet, orange, white                                  |
+| `--sc-focus`                                        | a field's focus ring                                                                                           | the accent at 40%                                      |
+| `--sc-orb-color`                                    | the orb: its shader's light, and the still orb's ink                                                           | the shaders' own spectrum; the still orb in the signal |
+| `--sc-radius`                                       | a box's corners (cards, the composer, the panel; inner corners derive from it)                                 | `12px`                                                 |
+| `--sc-radius-full`                                  | what is round: pills, round buttons, the launcher, the modes                                                   | `9999px`                                               |
+| `--sc-space`                                        | the spacing unit: every gap and padding of the chat, the space and the call is a multiple of it                | `4px`                                                  |
+| `--sc-shadow`                                       | what lifts a card off the page                                                                                 | a hair                                                 |
+| `--sc-shadow-raised`                                | what stands over the surface: the composer, the mode on                                                        | soft                                                   |
+| `--sc-shadow-overlay`                               | what floats over the page: a popover, the widget's panel and launcher                                          | deep                                                   |
+| `--sc-panel-width`, `--sc-panel-height`             | the widget's floating panel                                                                                    | `400px`, `640px` (within the screen)                   |
+| `--sc-launcher-size`, `--sc-launcher-offset`        | the widget's launcher, and how far from the page's corner it and the panel sit                                 | `56px`, `20px`                                         |
+
+In React, the same tokens on any ancestor, your classes on the parts (`classNames`) and your own
+drawing of a block (`components`):
 
-```json
-{
-  "id": "home",
-  "type": "host",
-  "component": "PropertyCard",
-  "props": { "address": "Calle Mayor 3", "price": 250000 }
-}
+```tsx
+<div
+  className="support"
+  style={{ "--sc-accent": "#0f766e", "--sc-font": "Inter" } as CSSProperties}
+>
+  <AgentSpace
+    client={client}
+    agentId="agt_…"
+    classNames={{ "sc-chat__composer": "support-composer", "sc-space__mode": "support-mode" }}
+    components={{ table: SupportTable }}
+  />
+</div>
 ```
 
-What your component is given, and what it can count on:
-
-- **`props`, exactly as the agent sent them.** The API validated them against the schema you
-  registered before it sent the surface, so you can rely on their shape. They are values: a
-  binding (`{ "path": … }`) is not looked up in them. There are no `children`.
-- **`onAction({ name, data, label })`**, to report what the user does. It goes back through the
-  surface's action path like a pick on a list: `AgentChat` sends it to the agent as what the
-  person said (`label`, "Good fit: Calle Mayor 3"), and `Surface` hands your `onAction` the
-  `{ surface_id, name, data, label }` the API's `Action` expects. It is `undefined` when the surface
-  takes no actions (it is a record of what was shown), so disable what answers. The node's props
-  cannot replace it.
-- **The text twin is already in the surface's `fallback_text`.** The API appends your component's
-  twin to the surface's, so where a surface cannot be drawn whole the user reads all of it in words,
-  never an empty box, and the rest of your page carries on. That happens when this page has not
-  registered the name (a development build says which in the console), when the props are not an
-  object, and when your component throws.
-- **A primitive's name is not yours to use.** A node cannot name `Button`, `Card`, `Table`, `Input`
-  or `Select`, and `RequestCard` never draws your components.
-
-## Your own client
-
-`client` is the part of the SDK the components call (`UiClient`): `Signalcore` has all of it. If you
-reach the API another way (a session cookie instead of a key), supply the same calls (for streams,
-`live: new Live({ baseUrl: location.origin })`).
+### Parts
+
+In the widget, the page styles what is inside its shadow root by `::part(…)`
+(`signalcore-chat::part(send) { … }`). An element may carry several names; since `::part()`
+takes no attribute selector, a state is a name of its own (`mode-selected`). The widget's own
+`stylesheet` reaches everything inside by class as well.
+
+| Part                                                                                                      | What it is                                                                               |
+| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `launcher`, `panel`                                                                                       | the round button at the corner, and the panel it opens (or the inline one)               |
+| `space`, `header`, `close`                                                                                | the agent's space, its face (with `header`), its close                                   |
+| `modes`, `mode`, `mode-text`, `mode-voice`, `mode-selected`                                               | the two modes beside the paperclip (and at the call's foot), each, the one on            |
+| `chat`, `transcript`, `empty`, `suggestion`                                                               | the chat, its scrolling log, a conversation's start, a thing to say first                |
+| `message`, `message-person`, `message-agent`, `message-business`                                          | a message, by who said it (the business's: a person of it, on a channel)                 |
+| `text`                                                                                                    | the agent's words (Markdown), in a reply or a surface                                    |
+| `files`                                                                                                   | the files sent with a message, or waiting over the composer                              |
+| `surface`                                                                                                 | a screen the agent shows                                                                 |
+| `approval`, `confirming`                                                                                  | a yes the person gives, and the line for one the business gives                          |
+| `status`                                                                                                  | the line while the agent works ("Typing…")                                               |
+| `composer`, `input`, `attach`, `actions`, `send`, `stop`                                                  | where the person writes: its field, the paperclip, the modes' slot, send, stop           |
+| `voice`, `call`, `orb`, `call-state`, `call-line`, `captions`                                             | the voice panel, the call in it, the orb, what the call is doing, its time, what is said |
+| `call-controls`, `mute`, `hang-up`, `call-after`                                                          | the call's controls, and what is offered once it is over                                 |
+| `card`, `stack`, `divider`, `fields`, `table`, `list`, `row`, `stat`, `image`, `choice`, `option`, `form` | the blocks of what the agent shows                                                       |
+| `note`, `note-info`, `note-success`, `note-warning`, `note-danger`                                        | a note, by its tone                                                                      |
+| `field`, `control`                                                                                        | a form's field, and the box of its control                                               |
+| `button`, `button-primary`, `button-neutral`, `button-danger`, `button-ghost`                             | a button, by its tone (with its own name too: `close`, `mute`, `hang-up`)                |
+
+In React the same elements carry the same `part` names (harmless outside a shadow root), and
+everything is reachable by its class: `classNames` adds the host's own classes to named parts,
+which are also the BEM classes they carry. The chat: `sc-chat` (`--builder`, `--console`), `sc-chat__log`, `sc-chat__message`,
+`sc-chat__message--person`, `sc-chat__message--agent`, `sc-chat__message--action`,
+`sc-chat__business` and `sc-chat__message--business` (what a person of the business wrote on a
+channel), `sc-chat__meta` (who wrote it, where it got to), `sc-chat__delivery` (`data-delivery`),
+`sc-chat__steps`, `sc-chat__step` (`--running`, `--waiting`, `--done`, `--failed`),
+`sc-chat__mark` (the step's glyph or state), `sc-chat__output` (what a step returned, in the
+builder's look), `sc-chat__text` (the agent's words),
+`sc-chat__request`, `sc-chat__confirming` (a person's line for a yes the business gives),
+`sc-chat__handoff` (the line where a person took over), `sc-chat__handover`
+(where who answers changed, its `time`), `sc-chat__decision` (a message let pass),
+`sc-chat__message--heard` (the greeting heard on a call), `sc-chat__cut` (where a reply on a call
+was cut short), `sc-chat__reply`,
+`sc-chat__status`, `sc-chat__empty`,
+`sc-chat__suggestion`, `sc-chat__composer`, `sc-chat__input`, `sc-chat__actions`,
+`sc-chat__send`, `sc-chat__stop`. A surface: `sc-surface`, `sc-surface__card`,
+`sc-surface__stack` (`--row`), `sc-surface__text`, `sc-surface__fields`, `sc-surface__table`,
+`sc-surface__note` (`--info`, `--success`, `--warning`, `--danger`), `sc-surface__button`
+(`--primary`, `--neutral`, `--danger`), `sc-surface__choice`, `sc-surface__option`,
+`sc-surface__form`, `sc-surface__field`, `sc-surface__submit`. Qué puede: `sc-about`,
+`sc-about__pane`, `sc-about__intro`, `sc-about__heading`, `sc-about__name` (the mark and the name, `data-tint`), `sc-about__lead`, `sc-about__updated`
+(the words that could not be read, and the button to try again), `sc-about__updating`,
+`sc-about__section`, `sc-about__label`, `sc-about__asks`, `sc-about__menu`, `sc-about__bar`
+(`sc-about__bar-end`: the host's controls), `sc-about__back`, `sc-about__automation`,
+`sc-about__run`, `sc-about__group`, `sc-about__title`, `sc-about__count`, `sc-about__tools` (the
+host's control on a topic's title line), `sc-about__hint`, `sc-about__subtitle` (over a part of
+a topic: whose, or what kind), `sc-about__file` (a file's row: its name and folder on a line
+each), `sc-about__memory`, `sc-about__detail` (a channel's provider's word),
+`sc-about__dot` (`data-tone`), `sc-about__state` (a channel's dot and word, `data-tone`),
+`sc-about__empty`, `sc-about__writing`. The card: `sc-card` (its tint: `--sky`, `--rose`,
+`--sand`), `sc-card__head`, `sc-card__mark` (the agent's mark, bare), `sc-card__who`,
+`sc-card__name`, `sc-card__role`, `sc-card__facts`, `sc-card__fact`, `sc-card__body`,
+`sc-card__row`, `sc-card__label`, `sc-card__value`, `sc-card__empty`. An
+automation: `sc-automation` (`--gone`: the block's quiet line for one not there),
+`sc-automation__head`, `sc-automation__heading`, `sc-automation__title`, `sc-automation__when`,
+`sc-automation__end` (the state's word and the switch), `sc-automation__dot`,
+`sc-automation__summary`, `sc-automation__section`, `sc-automation__label`,
+`sc-automation__steps`, `sc-automation__step`, `sc-automation__number`, `sc-automation__name`,
+`sc-automation__uses`, `sc-automation__use`, `sc-automation__board`, `sc-automation__more`,
+`sc-automation__runs`, `sc-automation__run--open`, `sc-automation__status` (a run's check),
+`sc-automation__empty`. A run: `sc-run`, `sc-run__head`, `sc-run__by` (what started it, its mark
+named by it), `sc-run__heading`, `sc-run__title`, `sc-run__meta` (when), `sc-run__end` (how it
+stands, `sc-run__took` under it), `sc-run__summary`, `sc-run__section`, `sc-run__label`, `sc-run__steps`,
+`sc-run__step`, `sc-run__number`, `sc-run__name`, `sc-run__calls`, `sc-run__call` (`--would`,
+`--failed`), `sc-run__count`, `sc-run__error`, `sc-run__live` (the dot of one still going),
+`sc-run__links`, `sc-run__empty`. The stylesheet is plain,
+unlayered CSS; a host whose utilities must win imports it into a layer under them
+(`@import "@signalcore/ui/styles.css" layer(components);`).
+
+Tests: `pnpm test` here, or `pnpm -r test` from `v3/`.