@signalcore/ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SignalCore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,567 @@
-# Temporary Holding Version
+# @signalcore/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+```
+
+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).
+
+```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.
+
+```tsx
+import { Signalcore } from "@signalcore/sdk";
+import { AgentChat, SignalcoreProvider } 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.
+
+```tsx
+<BuilderChat agentId="agt_…" sessionId={sessionId} onSession={setSessionId} />
+```
+
+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>;
+```
+
+- 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>
+```
+
+| 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>;
+```
+
+- **`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>;
+```
+
+- **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.
+
+```tsx
+<SignalcoreProvider client={client}>
+  <LiveView streamId="liv_..." aspect="16:9" input={false} onStatus={(status) => {}} />
+</SignalcoreProvider>
+```
+
+- **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                |
+
+```tsx
+<SignalcoreProvider theme={{ accent: "var(--primary)", radius: "var(--radius)", density: 0.9 }} />
+```
+
+**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.
+
+```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 */}
+```
+
+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.
+
+**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:
+
+```tsx
+<SignalcoreProvider
+  classNames={{ card: "rounded-xl border bg-card", "button--primary": "bg-primary" }}
+/>
+```
+
+**`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.
+
+```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 |
+
+## Words
+
+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:
+
+```tsx
+<SignalcoreProvider locale="en" messages={{ send: "Post", verbs: { edit: "Change" } }} />
+```
+
+- **`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:
+
+```html
+<signalcore-chat agent="agt_…" publishable-key="pk_live_…" locale="en"></signalcore-chat>
+<script>
+  document.querySelector("signalcore-chat").messages = { send: "Post" };
+</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:
+
+- **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 }} />
+```
+
+### 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`:
+
+```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>;
+```
+
+**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:
+
+```json
+{
+  "id": "home",
+  "type": "host",
+  "component": "PropertyCard",
+  "props": { "address": "Calle Mayor 3", "price": 250000 }
+}
+```
+
+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 })`).