@cubos/agent-sdk-react-dom 0.0.1136563

package/dist/styles.css

@@ -0,0 +1,496 @@
+/* Styles for `@cubos/agent-sdk-react-dom`.
+ *
+ * Imported by the components themselves, so a bundler picks this up and the
+ * consumer imports nothing. Two properties make that safe to do in someone
+ * else's app:
+ *
+ *   1. **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
+ *      shares, `.cubos-agent-sdk-react-dom--<name>` for one component's own rules.
+ *   2. **Nothing wins an argument.** Everything sits in the `cubos-agent-sdk-react-dom`
+ *      cascade layer and every selector is wrapped in `:where()`, which
+ *      contributes no specificity. Unlayered app CSS beats a layer outright,
+ *      and a bare `p {}` beats a zero-specificity rule — so these are defaults,
+ *      not decisions. Nobody needs `!important` to restyle this package, which
+ *      is the point: an app forced to shout at its dependency has already lost
+ *      the argument, because `!important` inverts layer order and it would then
+ *      be shouting at itself too.
+ *
+ * An app that puts its own CSS in layers should say where this one goes, once,
+ * above its own `@import`:
+ *
+ *     @layer theme, base, cubos-agent-sdk-react-dom, components, utilities;
+ *
+ * Above the reset, so a `*` rule clearing borders and margins doesn't erase
+ * these defaults; below everything the app writes itself, so its own classes
+ * still win without anyone reaching for `!important`.
+ *
+ * Colours are `--cubos-agent-sdk-react-dom-*` custom properties. Surfaces mix from
+ * `currentColor`, so the same sheet reads correctly on a light page, a dark one
+ * or inside a coloured bubble; only the syntax palette is absolute, and an app
+ * that toggles theme itself overrides those six.
+ */
+
+@layer cubos-agent-sdk-react-dom {
+  :where(.cubos-agent-sdk-react-dom) {
+    --cubos-agent-sdk-react-dom-border: color-mix(in srgb, currentColor 18%, transparent);
+    --cubos-agent-sdk-react-dom-muted: color-mix(in srgb, currentColor 65%, transparent);
+    --cubos-agent-sdk-react-dom-surface: color-mix(in srgb, currentColor 6%, transparent);
+    --cubos-agent-sdk-react-dom-comment: #5c6570;
+    --cubos-agent-sdk-react-dom-keyword: #b2144b;
+    --cubos-agent-sdk-react-dom-string: #0a5a2f;
+    --cubos-agent-sdk-react-dom-number: #0550ae;
+    --cubos-agent-sdk-react-dom-title: #6639ba;
+    --cubos-agent-sdk-react-dom-type: #8a4600;
+    --cubos-agent-sdk-react-dom-mono:
+      ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :where(.cubos-agent-sdk-react-dom) {
+      --cubos-agent-sdk-react-dom-comment: #9aa4ae;
+      --cubos-agent-sdk-react-dom-keyword: #ff9492;
+      --cubos-agent-sdk-react-dom-string: #8ddb8c;
+      --cubos-agent-sdk-react-dom-number: #91cbff;
+      --cubos-agent-sdk-react-dom-title: #d2a8ff;
+      --cubos-agent-sdk-react-dom-type: #ffb757;
+    }
+  }
+
+  /* ── AgentMarkdown ─────────────────────────────────────────────────── */
+
+  /* The container may set `pre-wrap` so plain text keeps its line breaks. Once
+     parsed, the source newlines are already structure, and honouring them too
+     doubles every gap. A match on the child beats the parent's inherited value,
+     which is why zero specificity is enough here. */
+  :where(.cubos-agent-sdk-react-dom--markdown) {
+    white-space: normal;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(p, ul, ol, blockquote, pre) {
+    margin: 0.75em 0;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(h1, h2, h3, h4) {
+    margin: 1.2em 0 0.5em;
+    font-weight: 600;
+    line-height: 1.3;
+  }
+
+  /* An agent writing `# Title` means a section of its answer, not a page title;
+     at document scale it would shout over everything around it. */
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(h1) {
+    font-size: 1.3em;
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(h2) {
+    font-size: 1.15em;
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(h3, h4) {
+    font-size: 1em;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(ul, ol) {
+    padding-left: 1.4em;
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(li) {
+    margin: 0.25em 0;
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(li) > :where(p) {
+    margin: 0.25em 0;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(a) {
+    color: inherit;
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(blockquote) {
+    padding-left: 0.9em;
+    border-left: 2px solid var(--cubos-agent-sdk-react-dom-border);
+    color: var(--cubos-agent-sdk-react-dom-muted);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(hr) {
+    height: 0;
+    margin: 1.2em 0;
+    border: 0;
+    border-top: 1px solid var(--cubos-agent-sdk-react-dom-border);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(code) {
+    font-family: var(--cubos-agent-sdk-react-dom-mono);
+    font-size: 0.875em;
+  }
+
+  /* Inline only — the `pre >` rule below resets it for blocks, which carry
+     their own padding and must not draw a second box per line. Same
+     specificity, so order is what separates them. */
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(:not(pre)) > :where(code) {
+    padding: 0.15em 0.35em;
+    border-radius: 0.3rem;
+    background: var(--cubos-agent-sdk-react-dom-surface);
+    border: 1px solid var(--cubos-agent-sdk-react-dom-border);
+    white-space: break-spaces;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(pre) {
+    overflow-x: auto;
+    padding: 0.75rem 0.9rem;
+    border-radius: 0.6rem;
+    background: var(--cubos-agent-sdk-react-dom-surface);
+    border: 1px solid var(--cubos-agent-sdk-react-dom-border);
+    /* A long line scrolls; wrapping code changes what it means to read it. */
+    white-space: pre;
+    -webkit-overflow-scrolling: touch;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(pre) > :where(code) {
+    padding: 0;
+    background: none;
+    border: 0;
+    font-size: 0.85em;
+    line-height: 1.55;
+  }
+
+  /* Scrolled rather than shrunk: a wide table on a phone moves sideways instead
+     of squeezing every column into two characters. The scroller is a wrapper,
+     so the table stays a table — `display: block` on a `<table>` breaks row
+     layout. */
+  :where(.cubos-agent-sdk-react-dom__table) {
+    overflow-x: auto;
+    margin: 0.75em 0;
+    -webkit-overflow-scrolling: touch;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(table) {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.95em;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(th, td) {
+    padding: 0.4em 0.7em;
+    border: 1px solid var(--cubos-agent-sdk-react-dom-border);
+    text-align: left;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(thead) {
+    background: var(--cubos-agent-sdk-react-dom-surface);
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(th) {
+    font-weight: 600;
+  }
+
+  /* KaTeX ships its own sizes; a display formula only needs room and a way out
+     when it is wider than the column. */
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(.katex-display) {
+    margin: 0.9em 0;
+    padding: 0.2em 0;
+    overflow-x: auto;
+    overflow-y: hidden;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(.hljs-comment, .hljs-quote) {
+    color: var(--cubos-agent-sdk-react-dom-comment);
+    font-style: italic;
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown)
+    :where(.hljs-keyword, .hljs-selector-tag, .hljs-literal, .hljs-doctag, .hljs-name, .hljs-tag) {
+    color: var(--cubos-agent-sdk-react-dom-keyword);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown)
+    :where(.hljs-string, .hljs-regexp, .hljs-addition, .hljs-attribute) {
+    color: var(--cubos-agent-sdk-react-dom-string);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown)
+    :where(
+      .hljs-number,
+      .hljs-attr,
+      .hljs-variable,
+      .hljs-template-variable,
+      .hljs-selector-attr,
+      .hljs-property
+    ) {
+    color: var(--cubos-agent-sdk-react-dom-number);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown)
+    :where(.hljs-title, .hljs-section, .hljs-selector-id, .hljs-selector-class) {
+    color: var(--cubos-agent-sdk-react-dom-title);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown)
+    :where(.hljs-built_in, .hljs-type, .hljs-symbol, .hljs-bullet, .hljs-params) {
+    color: var(--cubos-agent-sdk-react-dom-type);
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(.hljs-meta, .hljs-deletion) {
+    color: var(--cubos-agent-sdk-react-dom-meta, var(--cubos-agent-sdk-react-dom-comment));
+  }
+
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(.hljs-emphasis) {
+    font-style: italic;
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) :where(.hljs-strong) {
+    font-weight: 600;
+  }
+
+  /* A reply is one block of prose: the gap around it belongs to whatever
+     contains it. Last on purpose — everything here has the same specificity, so
+     only order decides. */
+  :where(.cubos-agent-sdk-react-dom--markdown) > :first-child {
+    margin-top: 0;
+  }
+  :where(.cubos-agent-sdk-react-dom--markdown) > :last-child {
+    margin-bottom: 0;
+  }
+
+  /* ── VoiceMessage ──────────────────────────────────────────────────── */
+
+  /* Takes the width of whatever holds it — the container decides how wide a
+     voice message is, and a bubble that caps itself caps the player with it. */
+  :where(.cubos-agent-sdk-react-dom--voice) {
+    display: flex;
+    flex-direction: column;
+    gap: 0.35rem;
+    width: 100%;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-row) {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+  }
+
+  /* Bare hit target — everything visible is on the span inside it. A reset owns
+     `button`, and in an app that loads this sheet before its own (no layer
+     statement, nothing to order it by) the reset would win. No reset claims a
+     `span`. */
+  :where(.cubos-agent-sdk-react-dom__voice-play) {
+    flex: none;
+    padding: 0;
+    border: 0;
+    background: none;
+    color: inherit;
+    cursor: pointer;
+  }
+
+  /* An inset shadow rather than a border: a reset that clears `border` on `*`
+     would take the ring with it in an app that puts this layer below its own
+     base. The shadow is nobody's reset. */
+  :where(.cubos-agent-sdk-react-dom__voice-face) {
+    display: grid;
+    place-items: center;
+    width: 2rem;
+    height: 2rem;
+    border-radius: 50%;
+    background: var(--cubos-agent-sdk-react-dom-surface);
+    box-shadow: inset 0 0 0 1px var(--cubos-agent-sdk-react-dom-border);
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-play):disabled {
+    cursor: default;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-play):disabled
+    :where(.cubos-agent-sdk-react-dom__voice-face) {
+    opacity: 0.5;
+  }
+
+  /* The bars and the slider share one box: the slider sits on top, invisible
+     but hit-testable, so dragging the waveform seeks and a keyboard still gets
+     a real control. */
+  /* The floor is what keeps the player usable in a container that has no width
+     of its own: the waveform is absolutely positioned, so intrinsic sizing
+     measures the track as empty and a shrink-to-fit bubble would close around
+     it. 8rem still leaves the whole row inside the narrowest phone bubble. */
+  :where(.cubos-agent-sdk-react-dom__voice-track) {
+    position: relative;
+    flex: 1;
+    min-width: 8rem;
+    height: 1.75rem;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-wave) {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    gap: 2px;
+    pointer-events: none;
+  }
+
+  /* Before the clip is decoded there is no shape to draw, so the track is a
+     plain progress bar rather than an invented waveform. */
+  :where(.cubos-agent-sdk-react-dom__voice-line) {
+    position: absolute;
+    inset: 50% 0 auto;
+    height: 3px;
+    transform: translateY(-50%);
+    border-radius: 999px;
+    background: var(--cubos-agent-sdk-react-dom-border);
+    overflow: hidden;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-line-fill) {
+    display: block;
+    height: 100%;
+    border-radius: inherit;
+    background: currentColor;
+    opacity: 0.75;
+  }
+
+  /* The live meter. Shares the played waveform's bar language so a recording
+     in progress and the message it becomes read as the same object. */
+  :where(.cubos-agent-sdk-react-dom__meter) {
+    display: flex;
+    flex: 1;
+    align-items: center;
+    gap: 2px;
+    height: 1.5rem;
+    /* Same reason as the player's track: absolutely nothing here has an
+       intrinsic width, and a shrink-to-fit parent would close around it. */
+    min-width: 4rem;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__meter-bar) {
+    flex: 1;
+    min-width: 2px;
+    border-radius: 1px;
+    background: currentColor;
+    opacity: 0.75;
+    /* The reading arrives every 50ms; the eye wants a line, not a strobe. */
+    transition: height 90ms linear;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where(.cubos-agent-sdk-react-dom__meter-bar) {
+      transition: none;
+    }
+  }
+
+  /* Nothing is arriving. Drawn as absence rather than as alarm — the sentence
+     beside it is the app's, and two red things saying one thing is noise. */
+  :where(.cubos-agent-sdk-react-dom__meter--silent .cubos-agent-sdk-react-dom__meter-bar) {
+    opacity: 0.3;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-bar) {
+    flex: 1;
+    min-width: 2px;
+    border-radius: 1px;
+    background: var(--cubos-agent-sdk-react-dom-border);
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-bar--played) {
+    background: currentColor;
+    opacity: 0.75;
+  }
+
+  /* Interaction only — the playhead below is drawn by us. The control stays a
+     real range input for the keyboard, the pointer and the ARIA; what it must
+     not do is paint. */
+  :where(.cubos-agent-sdk-react-dom__voice-seek) {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    margin: 0;
+    appearance: none;
+    -webkit-appearance: none;
+    background: none;
+    cursor: pointer;
+  }
+
+  /* The only two rules here that carry specificity, and neither has a choice:
+     a vendor pseudo-element inside `:where()` is dropped by the engine.
+     Hiding the thumb through `opacity` on the input instead does not survive
+     Tailwind, whose preflight sets `opacity: 1` on every `input` from a layer
+     that outranks this one. */
+  .cubos-agent-sdk-react-dom__voice-seek::-webkit-slider-thumb {
+    appearance: none;
+    -webkit-appearance: none;
+    width: 0.55rem;
+    height: 0.55rem;
+    border: none;
+    background: transparent;
+  }
+
+  .cubos-agent-sdk-react-dom__voice-seek::-moz-range-thumb {
+    width: 0.55rem;
+    height: 0.55rem;
+    border: none;
+    background: transparent;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-seek):disabled {
+    cursor: default;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-head) {
+    position: absolute;
+    top: 50%;
+    width: 0.55rem;
+    height: 0.55rem;
+    border-radius: 50%;
+    background: currentColor;
+    transform: translate(-50%, -50%);
+    pointer-events: none;
+  }
+
+  /* The ring belongs on the track, since the control itself is transparent. */
+  :where(.cubos-agent-sdk-react-dom__voice-play:focus-visible)
+  :where(.cubos-agent-sdk-react-dom__voice-face) {
+    outline: 2px solid color-mix(in srgb, currentColor 45%, transparent);
+    outline-offset: 2px;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-track:has(:focus-visible)) {
+    outline: 2px solid color-mix(in srgb, currentColor 45%, transparent);
+    outline-offset: 2px;
+    border-radius: 0.2rem;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-time) {
+    flex: none;
+    font-size: 0.8em;
+    font-variant-numeric: tabular-nums;
+    color: var(--cubos-agent-sdk-react-dom-muted);
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-disclosure) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.3rem;
+    align-self: flex-start;
+    padding: 0;
+    border: 0;
+    background: none;
+    color: var(--cubos-agent-sdk-react-dom-muted);
+    font: inherit;
+    font-size: 0.8em;
+    cursor: pointer;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-transcript) {
+    margin: 0;
+    font-size: 0.95em;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-pending) {
+    margin: 0;
+    font-size: 0.8em;
+    color: var(--cubos-agent-sdk-react-dom-muted);
+    font-style: italic;
+  }
+
+  :where(.cubos-agent-sdk-react-dom__voice-error) {
+    margin: 0;
+    font-size: 0.8em;
+    color: var(--cubos-agent-sdk-react-dom-muted);
+  }
+}

package/dist/use-recorder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `unsupported` is settled after mount, never during render: the check reads
+ * `navigator`, and a server render has none.
+ */
+export type RecorderState = "idle" | "requesting" | "recording" | "unsupported";
+export interface UseRecorderResult {
+    state: RecorderState;
+    /** Seconds elapsed in the current take, for a live timer. */
+    seconds: number;
+    /**
+     * The microphone's signal over the last couple of seconds, oldest first and
+     * already scaled 0..1 for drawing. Fixed length, so it is a window that
+     * scrolls rather than a list that grows — pass it to `RecordingWave`.
+     *
+     * All zeros before anything is heard, which is the same thing a muted device
+     * produces: `silent` is what tells those apart, because two seconds of flat
+     * bars is ambiguous and a sentence is not.
+     */
+    levels: number[];
+    /**
+     * Nothing above the noise floor for long enough that it is worth saying so.
+     *
+     * A muted microphone records perfectly: the clip arrives, the transcription
+     * comes back empty, and the agent answers a message nobody managed to send.
+     * The only moment that is cheap to fix is while the person is still talking.
+     */
+    silent: boolean;
+    /** Denied permission, no microphone, or a MediaRecorder failure. */
+    error: Error | null;
+    start: () => Promise<void>;
+    /** Resolves with the clip, or null if nothing was captured. */
+    stop: () => Promise<Blob | null>;
+    /** Drops the take and releases the microphone. */
+    cancel: () => void;
+}
+/**
+ * One meter reading from a chunk of time-domain samples.
+ *
+ * RMS rather than peak: peak jumps on a single click and reads as speech, and
+ * what the meter is for is telling "someone is talking" from "nothing is
+ * arriving". Bytes are unsigned with silence at 128, which is the format
+ * `getByteTimeDomainData` writes.
+ */
+export declare function levelOf(samples: Uint8Array): number;
+/**
+ * Microphone capture as a Blob, ready for `sendAudio`.
+ *
+ * The stream is released on every exit path — stop, cancel, unmount, a failure
+ * — because a live `MediaStream` keeps the browser's recording indicator lit
+ * long after the UI has moved on, and nothing on screen explains why.
+ *
+ * The container is probed rather than chosen: Chrome and Firefox record WebM,
+ * Safari only ever produces MP4/AAC, and asking Safari for WebM fails silently
+ * instead of raising — a clip that is simply never assembled.
+ */
+export declare function useRecorder(): UseRecorderResult;

package/dist/use-transcript-anchor.d.ts

@@ -0,0 +1,67 @@
+import { type RefObject } from "react";
+export interface UseTranscriptAnchorOptions {
+    /**
+     * Anything that changes when the tail grows — the last event's `seq`, the
+     * message count, whether the typing indicator is up. Only a trigger; the
+     * value is never read.
+     */
+    tailKey: unknown;
+    /** There is older history to page in when the reader scrolls up. */
+    hasOlder?: boolean;
+    /**
+     * Fetches the previous page; resolves with how many items were prepended.
+     * Zero releases the anchor, so a page that came back empty does not freeze
+     * the viewport.
+     */
+    loadOlder?: () => Promise<number>;
+    /**
+     * How close to the end still counts as being at it, in pixels. Small on
+     * purpose: this reads as intent, not as a zone in which scrolling up is
+     * ignored.
+     */
+    atBottomPx?: number;
+    /** How close to the top counts as asking for more. */
+    loadOlderPx?: number;
+}
+export interface UseTranscriptAnchorResult {
+    /**
+     * The scrolling box. Yours to style — this attaches no class and renders no
+     * element.
+     */
+    scrollRef: RefObject<HTMLDivElement | null>;
+    /**
+     * Hang it on whatever wraps the items. A callback ref, so it holds however
+     * the caller mounts and unmounts that wrapper.
+     */
+    contentRef: (node: HTMLElement | null) => void;
+    onScroll: () => void;
+    /** Whether the viewport is at the end — for a "jump to latest" affordance. */
+    isAtBottom: boolean;
+    scrollToEnd: () => void;
+}
+/**
+ * The scroll behaviour of a bottom-anchored transcript, without any of its
+ * looks: it owns no element, adds no class, and renders nothing. You write the
+ * markup and hang two refs off it.
+ *
+ * Four behaviours, each of which was a bug 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, cards lay out a frame late. Keyed on props alone, the
+ *    scroll runs against the height at commit time and 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.** Prepending grows the
+ *    content upward while `scrollTop` stays put, which reads as the viewport
+ *    jumping. The correction runs before paint, against a height measured
+ *    *before* the commit — and on every commit, because prepending is the one
+ *    change that leaves the tail, and so `tailKey`, untouched.
+ * 4. **Keep pulling while the content is shorter than the viewport.** A short
+ *    first page can leave the box unscrollable, and then no scroll event ever
+ *    fires to ask for the rest.
+ */
+export declare function useTranscriptAnchor(options: UseTranscriptAnchorOptions): UseTranscriptAnchorResult;

package/dist/voice-message.d.ts

@@ -0,0 +1,53 @@
+import { type AgentColors } from "./colors.js";
+import "./styles.css";
+export interface VoiceMessageLabels {
+    play: string;
+    pause: string;
+    /** The disclosure that opens the transcript. */
+    transcript: string;
+    /** Shown in place of the transcript while STT is still running. */
+    transcribing: string;
+    /** Shown when STT finished and heard nothing — a silent recording. */
+    noSpeech: string;
+    loadFailed: string;
+}
+export interface VoiceMessageProps {
+    /**
+     * Fetches the clip, once, on first play. A `Blob` rather than a URL because
+     * the bytes usually sit behind a bearer token, which an `<audio src>` cannot
+     * carry.
+     */
+    loadBytes: (signal: AbortSignal) => Promise<Blob>;
+    /**
+     * The words, once the agent's STT model has produced them.
+     *
+     * The three states are distinct and a client has all three: absent while STT
+     * is still running, the empty string once it finished and heard nothing, and
+     * the text otherwise. Reading empty as "not yet" is what left a silent
+     * recording saying "Transcribing…" for good — `Message.transcribed` in
+     * `@cubos/agent-sdk` is the flag that tells them apart.
+     */
+    transcript?: string;
+    /** Size of the clip, shown until it has been loaded and measured. */
+    bytes?: number;
+    /** Open the transcript from the start. Collapsed by default — the player is
+     * the message; the words are there when you want them. */
+    defaultTranscriptOpen?: boolean;
+    labels?: Partial<VoiceMessageLabels>;
+    /** Overrides the palette for this player, as inline custom properties — the
+     * same tokens `styles.css` declares, without writing CSS. */
+    colors?: AgentColors;
+    className?: string;
+}
+/**
+ * A voice message: play control, waveform, elapsed time, and the transcription
+ * folded away underneath — the shape Slack and WhatsApp made familiar.
+ *
+ * The clip is fetched when the player scrolls into view, and the waveform is
+ * drawn from it before anyone presses anything. Not on mount: a long
+ * conversation would pull down every recording in it, most of which nobody will
+ * ever open. Not on first play either — that left the player showing a file
+ * size where its shape should be, and the shape is most of what a voice message
+ * says at a glance.
+ */
+export declare function VoiceMessage({ loadBytes, transcript, bytes, defaultTranscriptOpen, labels, colors, className, }: VoiceMessageProps): import("react").JSX.Element;