@cubos/agent-sdk-react-dom 0.0.1136563

package/README.md

@@ -0,0 +1,265 @@
+# @cubos/agent-sdk-react-dom
+
+Ready-made React components for a Cubos Agent chat. Everything here renders DOM —
+that is the whole difference from [`@cubos/agent-sdk-react`](../sdk-react), which
+stays platform-neutral so its hooks also run in React Native.
+
+```sh
+bun add @cubos/agent-sdk-react-dom    # or npm / pnpm / yarn
+```
+
+Its dependencies are the markdown chain and `lucide-react` for the handful of
+icons a player needs. React is a peer.
+
+## Agent markdown
+
+```tsx
+import { AgentMarkdown } from "@cubos/agent-sdk-react-dom";
+
+<AgentMarkdown>{message.content}</AgentMarkdown>
+```
+
+That is the whole setup. GFM tables, fenced code with syntax highlighting, TeX,
+and a look that already works — **no stylesheet to import**.
+
+### The CSS takes care of itself
+
+The components import their own stylesheet. Your bundler resolves that the way
+it resolves any other import — Vite, Next, Rspack, webpack, Bun — and there is
+nothing for you to remember, no order to get right, no `styles.css` to hunt for
+in a README.
+
+Two properties make that safe to do in someone else's app:
+
+- **Nothing escapes.** Every selector is scoped to a class this package puts on
+  its own wrapper: `.cubos-agent-sdk-react-dom` for what every component here
+  shares, `.cubos-agent-sdk-react-dom--markdown` for this one's rules. The sheet
+  cannot touch anything it didn't draw.
+- **Nothing wins an argument.** The whole sheet sits in the `cubos-agent-sdk-react-dom`
+  cascade layer, and every selector is wrapped in `:where()`, which contributes
+  no specificity. A layer loses to unlayered CSS outright, and a bare `p {}`
+  beats a zero-specificity rule — so these are defaults, and yours are
+  decisions.
+
+**If your app puts its own CSS in layers** (Tailwind v4 does), name ours once so
+the order is explicit rather than accidental:
+
+```css
+/* Above your `@import`, since that is where a layer's position gets fixed. */
+@layer theme, base, cubos-agent-sdk-react-dom, components, utilities;
+
+@import "tailwindcss";
+```
+
+**After your reset, before your own classes.** A reset clears borders and
+margins on `*`; below it, these defaults would be erased along with the
+browser's. Above your components and utilities, and your app would have to fight
+this package to restyle anything.
+
+Theming is `--cubos-agent-sdk-react-dom-*`, on the package class — one block, and
+every component in here follows it:
+
+```css
+.cubos-agent-sdk-react-dom {
+  --cubos-agent-sdk-react-dom-border: var(--my-border);
+  --cubos-agent-sdk-react-dom-surface: var(--my-code-bg);
+  --cubos-agent-sdk-react-dom-keyword: var(--my-pink);
+}
+```
+
+Most of it you never touch: borders, muted text and code surfaces are mixed from
+`currentColor`, so the same sheet reads correctly on a white page, a dark one, or
+inside a coloured bubble. Only the six syntax colours are absolute, and they
+switch on `prefers-color-scheme` — if your app toggles dark mode itself, override
+those under whatever selector you use.
+
+The same tokens are a prop, for an app that themes in JavaScript or wants one
+instance to differ from the rest:
+
+```tsx
+<VoiceMessage colors={{ surface: "#0b57d0", border: "#8ab4f8" }} … />
+```
+
+They land as inline custom properties, which is the app speaking directly — it
+outranks every stylesheet, this package's included, without an `!important`
+anywhere.
+
+### Making it yours
+
+```tsx
+// Your design system, element by element. Anything you style here outranks the
+// packaged default for that element; anything you leave alone keeps it.
+<AgentMarkdown components={{ p: (props) => <p className="my-2" {...props} /> }}>
+  {text}
+</AgentMarkdown>
+```
+
+`components` is `react-markdown`'s map, merged over the defaults — so overriding
+`a` leaves the table scroller in place. `gfm`, `math` and `highlight` each turn
+their plugin off. That is the whole API: there is no `unstyled` flag, because
+with a scoped layer at zero specificity there is nothing to opt out of.
+
+### Two things worth knowing
+
+**Raw HTML is never rendered, and there is no option to allow it.** Message
+content is model output, which is untrusted input however friendly the agent.
+`rehype-raw` is deliberately absent: markdown in, elements out.
+
+**KaTeX's stylesheet is not bundled.** It ships fonts, and re-exporting a copy of
+those from here would double them in your bundle. If your agent writes TeX, add
+it once in your app:
+
+```ts
+import "katex/dist/katex.min.css";
+```
+
+Without it formulas still render, just unstyled. `math={false}` if the agent
+never writes any.
+
+## Voice messages
+
+```tsx
+import { VoiceMessage } from "@cubos/agent-sdk-react-dom";
+
+<VoiceMessage
+  loadBytes={(signal) => client.fetchAttachment(conversationId, message.id, attachment.id, signal)}
+  bytes={attachment.bytes}
+  transcript={message.content}
+/>
+```
+
+It **fills the width of whatever holds it** — how wide a voice message is, is
+the bubble's decision, not the player's. All it insists on is a floor, so a
+container with no width of its own doesn't collapse around a waveform that is
+absolutely positioned.
+
+Play/pause, a seek bar, the elapsed time, and the transcription folded away
+under a disclosure — collapsed by default, because the player is the message and
+the words are there when you want them. `defaultTranscriptOpen` starts it open.
+
+Three things it does that are easy to miss:
+
+- **The waveform is the clip's own.** It is read off the decoded samples — peak
+  amplitude per bucket, normalised — so a pause in the recording is a gap on
+  screen. Until the bytes are here there is nothing to read, and the track is a
+  plain progress bar rather than an invented pattern. A codec the browser can't
+  decode keeps that bar; it never breaks playback.
+- **Nothing is fetched until you press play.** A transcript often answers the
+  question, and a conversation full of voice notes should not pull every clip
+  down to render one screen.
+- **The seek control is a real `<input type="range">`,** for the keyboard and
+  the ARIA — painted by us, because the native thumb needs a vendor
+  pseudo-element and hiding it with `opacity` loses to Tailwind's preflight,
+  which sets `opacity: 1` on every `input` from a layer above this package's.
+- **It measures a `MediaRecorder` clip.** Those carry no duration in their
+  header, so browsers report `Infinity` until the file has been seeked through;
+  the component forces that measurement and rewinds, which is why the seek bar
+  has a range at all.
+
+`loadBytes` returns a `Blob` because the bytes usually sit behind a bearer
+token, which an `<audio src>` cannot carry. Every string is in `labels`:
+
+```tsx
+<VoiceMessage
+  loadBytes={…}
+  labels={{ play: "Tocar", pause: "Pausar", transcript: "Transcrição" }}
+/>
+```
+
+## Recording a voice message
+
+`useRecorder` is the other half of `VoiceMessage`: capture, as a `Blob` ready
+for `sendAudio`.
+
+```tsx
+const rec = useRecorder();
+
+{rec.state !== "unsupported" && (
+  <button onClick={() => (rec.state === "recording" ? finish() : rec.start())}>
+    {rec.state === "recording" ? `Gravando ${rec.seconds}s` : "Gravar"}
+  </button>
+)}
+
+async function finish() {
+  const clip = await rec.stop();     // null when nothing was captured
+  if (clip) await sendAudio(clip);
+}
+```
+
+Two things it owns, both silent when wrong:
+
+- **The container is probed, not chosen.** Chrome and Firefox record WebM;
+  Safari only ever produces MP4/AAC and *fails silently* when asked for WebM —
+  a clip that is simply never assembled.
+- **The stream is released on every exit path** — stop, cancel, unmount, a
+  failed permission. A live `MediaStream` keeps the browser's recording
+  indicator lit long after the UI has moved on, with nothing on screen to
+  explain it.
+
+`state` is `unsupported` where there is no `MediaRecorder` or no secure context
+(`getUserMedia` exists only in one), and it settles after mount rather than
+during render, so it is safe to render on a server. `cancel()` drops the take
+without assembling it; `error` carries a denied microphone, which is the failure
+worth putting in front of someone.
+
+## Keeping the transcript anchored
+
+`useTranscriptAnchor` is the scroll behaviour of a bottom-anchored transcript
+with none of its looks: it renders no element, sets no class, and hands you two
+refs.
+
+```tsx
+const { scrollRef, contentRef, onScroll, isAtBottom, scrollToEnd } =
+  useTranscriptAnchor({ tailKey: messages.at(-1)?.id, hasOlder, loadOlder });
+
+<div ref={scrollRef} onScroll={onScroll} className="overflow-auto">
+  <div ref={contentRef}>{items}</div>
+</div>;
+{!isAtBottom && <button onClick={scrollToEnd}>Ver o mais recente</button>}
+```
+
+`tailKey` is anything that changes when the tail grows — the last event's `seq`,
+the message count, whether a typing indicator is up. It is only a trigger; the
+value is never read. `loadOlder` resolves with **how many items it prepended**,
+which is what lets a page that came back empty release the anchor instead of
+freezing the viewport.
+
+Four behaviours, each of which was a bug in this repository before it was a
+rule:
+
+1. **Follow only if already following.** The intent is recorded when the reader
+   scrolls, never measured after an update — by then the content has grown, so
+   someone sitting exactly at the end is suddenly "far" from it by the height of
+   whatever just arrived.
+2. **Follow when the content grows, not when React re-renders.** A transcript
+   grows for reasons no state changed: an image decodes, a font swaps, a
+   disclosure opens, a card lays out a frame late. That is what `contentRef`
+   watches, and skipping it leaves the last few hundred pixels — the ones the
+   answer is written in — below the fold.
+3. **Hold the reader's place when paging backwards**, before paint, against a
+   height measured before the commit. The correction survives the renders that
+   happen *while* the page is in flight; consuming it on the first of them is
+   what drops the reader at the top of a page they never asked to jump to.
+4. **Keep pulling while the content is shorter than the viewport**, or a short
+   first page leaves a box that cannot scroll, and no scroll event ever fires to
+   ask for the rest.
+
+## What belongs in this package
+
+The bar is deliberately high, because a components package that answers every
+request becomes a chat UI nobody can restyle:
+
+1. It solves a problem of the **protocol** — markdown the model wrote, bytes
+   behind a bearer token, a clip that needs a player — or it is a **mechanic
+   that is invisible when right and wrong in the same way everywhere**, like a
+   transcript that has to follow the answer being written into it. Never a
+   question of product taste.
+2. There is one obviously right behaviour, or a security invariant worth keeping
+   in one place.
+3. Styling is delegated, not baked in.
+4. It was already written twice.
+
+Bubbles, composers and conversation lists fail (1): they are where products
+differ most, and `packages/demo` in the repository is the worked example to copy
+instead. Recording a voice note is the next candidate — the demo has it, and the
+question is only whether a recorder belongs next to a player.

package/dist/agent-markdown.d.ts

@@ -0,0 +1,53 @@
+import { type Components } from "react-markdown";
+import { type AgentColors, type SyntaxColors } from "./colors.js";
+import "./styles.css";
+export interface AgentMarkdownProps {
+    /** The markdown, as the agent wrote it — a `Message.content`, or a
+     * `markdown` block's `text`. */
+    children: string;
+    /** GitHub-flavoured markdown: tables, strikethrough, task lists, autolinks.
+     * Defaults to on. */
+    gfm?: boolean;
+    /** TeX through KaTeX (`$x$` inline, `$$…$$` in display). Defaults to on.
+     * **KaTeX's own stylesheet is not bundled** — add `import
+     * "katex/dist/katex.min.css"` to your app, or formulas render unstyled.
+     *
+     * Amounts are safe with this on: a `$` that reads as currency is escaped
+     * before the parser sees it, so "de R$ 524 a R$ 632" stays a sentence instead
+     * of becoming one formula. See `currency.ts` for what counts. */
+    math?: boolean;
+    /** Syntax highlighting for fenced code. Defaults to on. */
+    highlight?: boolean;
+    /**
+     * Element overrides, as `react-markdown` takes them. Merged over the
+     * defaults, so overriding `a` leaves the table scroller in place.
+     *
+     * This is the hook for an app with its own design system: pass
+     * `{ p: (props) => <p className="my-2" {...props} /> }` and style everything
+     * with your own classes.
+     */
+    components?: Components;
+    /** Overrides the palette for this block, as inline custom properties — the
+     * same tokens `styles.css` declares, without writing CSS. */
+    colors?: AgentColors & SyntaxColors;
+    /** Put on the wrapper, alongside this package's own classes. */
+    className?: string;
+}
+/**
+ * Markdown the way an agent writes it: GFM, fenced code with highlighting, and
+ * TeX — styled out of the box, with no stylesheet to import, and restyleable
+ * down to the element through `components`.
+ *
+ * ```tsx
+ * <AgentMarkdown>{message.content}</AgentMarkdown>
+ * ```
+ *
+ * **Raw HTML is never rendered.** `rehype-raw` is deliberately absent and there
+ * is no option to add it: this text is model output, which is untrusted input
+ * however friendly the agent. Markdown in, elements out.
+ *
+ * Memoised on its input — a live conversation re-renders the whole transcript
+ * whenever a message arrives, and re-parsing every bubble each time is work
+ * nobody sees.
+ */
+export declare const AgentMarkdown: import("react").MemoExoticComponent<({ children, gfm, math, highlight, components, colors, className, }: AgentMarkdownProps) => import("react").JSX.Element>;

package/dist/colors.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties } from "react";
+/** The colours every component here reads. Each is a `--cubos-agent-sdk-react-dom-*`
+ * custom property, so a stylesheet can set the same things — the prop exists so
+ * an app that themes in JS doesn't have to write CSS to do it. */
+export interface AgentColors {
+    /** Hairlines: table cells, code borders, the player's ring. */
+    border?: string;
+    /** Secondary text: quotes, the clock, "transcribing…". */
+    muted?: string;
+    /** Filled surfaces: code blocks, table headers, the play button. */
+    surface?: string;
+}
+/** Syntax colours, on top of the shared three. */
+export interface SyntaxColors {
+    comment?: string;
+    keyword?: string;
+    string?: string;
+    number?: string;
+    title?: string;
+    type?: string;
+}
+/** Inline custom properties — the app speaking directly, which outranks every
+ * stylesheet without anyone reaching for `!important`. */
+export declare function colorStyle(colors: Partial<AgentColors & SyntaxColors> | undefined): CSSProperties | undefined;

package/dist/currency.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Escapes every `$` that is currency, leaving TeX delimiters alone.
+ *
+ * Walks the text rather than running a regex over it, because the decision
+ * depends on context a regex cannot see: fenced blocks, inline code and `$$…$$`
+ * display maths all have to pass through untouched, or this would corrupt a
+ * code sample or break a formula the agent meant.
+ */
+export declare function escapeCurrency(markdown: string): string;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { AgentMarkdownProps } from "./agent-markdown.js";
+export { AgentMarkdown } from "./agent-markdown.js";
+export type { AgentColors, SyntaxColors } from "./colors.js";
+export type { RecordingWaveProps } from "./recording-wave.js";
+export { RecordingWave } from "./recording-wave.js";
+export type { RecorderState, UseRecorderResult } from "./use-recorder.js";
+export { useRecorder } from "./use-recorder.js";
+export type { UseTranscriptAnchorOptions, UseTranscriptAnchorResult, } from "./use-transcript-anchor.js";
+export { useTranscriptAnchor } from "./use-transcript-anchor.js";
+export type { VoiceMessageLabels, VoiceMessageProps } from "./voice-message.js";
+export { VoiceMessage } from "./voice-message.js";