@belonguniverseai/react-sdk 0.1.0

package/dist/embed/voice/audio-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Audio utility functions for the voice call system.
+ *
+ * PCM16 / Float32 conversion and base64 <-> ArrayBuffer helpers, ported from
+ * belong-sdk-old/src/voice/audio-utils.ts under strict TS (no any/as/!).
+ */
+/**
+ * Converts Float32 audio samples to little-endian PCM16.
+ *
+ * Each sample is clamped to [-1, 1] then scaled to the signed 16-bit range
+ * (negative samples by 0x8000, non-negative by 0x7fff) and written
+ * little-endian into a fresh buffer.
+ *
+ * @param input - Float32 audio samples, typically in [-1, 1].
+ * @returns An ArrayBuffer of little-endian Int16 PCM samples.
+ */
+export declare function floatTo16BitPcm(input: Float32Array): ArrayBuffer;
+/**
+ * Converts PCM16 samples back to Float32 in the [-1, 1) range.
+ *
+ * @param input - Int16 PCM samples.
+ * @returns A Float32Array where each sample is divided by 32768.
+ */
+export declare function int16ToFloat32(input: Int16Array): Float32Array;
+/**
+ * Encodes the bytes of an ArrayBuffer as a base64 string.
+ *
+ * @param buf - The ArrayBuffer to encode.
+ * @returns The base64 representation of the buffer's bytes.
+ */
+export declare function arrayBufferToBase64(buf: ArrayBuffer): string;
+/**
+ * Decodes a base64 string into an ArrayBuffer.
+ *
+ * @param b64 - The base64 string to decode.
+ * @returns An ArrayBuffer containing the decoded bytes.
+ */
+export declare function base64ToArrayBuffer(b64: string): ArrayBuffer;

package/dist/embed/voice/deepgram-stt.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Deepgram Nova-3 streaming STT WebSocket client.
+ *
+ *   PCM16 (16 kHz mono)  ──▶  WebSocket(wss, ["bearer", token])  ──▶  Deepgram
+ *                        ◀──  Results frames (interim / is_final / speech_final)
+ *
+ * Three-level transcript accumulation (mirrors the legacy belong-sdk-old
+ * client):
+ *
+ *   1. interim          — `is_final === false`: emitted live via `onInterim`.
+ *   2. segment          — `is_final === true && speech_final === false`:
+ *                          a within-utterance boundary; pushed to a buffer.
+ *   3. utterance flush   — `is_final === true && speech_final === true`:
+ *                          the segment is buffered, then a `flushMs` debounce
+ *                          timer is (re)armed. When it fires the buffered
+ *                          segments are joined and emitted via `onFinal`.
+ *
+ * The debounce keeps a short pause from splitting one spoken request into
+ * multiple backend calls. `finalize()` is the push-to-talk release path: it
+ * sends Deepgram a `Finalize` so the still-buffered trailing audio (the last
+ * word or two) is transcribed and returned, then emits the COMPLETE utterance
+ * after a short grace — so a release never clips the end of speech.
+ * `forceFlush()` emits whatever is already buffered immediately (no Finalize
+ * round-trip); `discard()` drops the buffer without emitting (it is stale
+ * because the backend already consumed it).
+ *
+ * A 3 s keepalive frame is sent while the socket is open so Deepgram does not
+ * close an idle stream.
+ */
+/**
+ * After `finalize()` sends Deepgram a `Finalize` request, the trailing words
+ * the user just spoke arrive as one or more `is_final` frames a moment later.
+ * We wait this grace (re-armed on each finalize-induced final, so multiple
+ * frames coalesce) before emitting, so the last word is never dropped. Kept
+ * well under the bus-level anti-hang fallback so the grace always wins.
+ */
+export declare const FINALIZE_GRACE_MS = 400;
+export type SttCallbacks = {
+    readonly onInterim: (text: string) => void;
+    readonly onFinal: (text: string) => void;
+    readonly onOpen: () => void;
+    readonly onError: (e: Error) => void;
+    readonly onClose: () => void;
+};
+export type DeepgramStt = {
+    readonly sendAudio: (pcm: ArrayBuffer) => void;
+    readonly forceFlush: () => void;
+    readonly finalize: () => void;
+    readonly discard: () => void;
+    readonly close: () => void;
+};
+/**
+ * Create a Deepgram streaming STT client.
+ *
+ * @param opts.token - Bearer token for the `["bearer", token]` subprotocol.
+ * @param opts.wssUrl - Fully-formed Deepgram listen URL (model + params).
+ * @param opts.flushMs - Debounce window after a `speech_final` before the
+ *   buffered utterance is emitted via `onFinal`.
+ * @param opts.wsFactory - WebSocket constructor (injectable for tests).
+ *   Defaults to `(u, p) => new WebSocket(u, p)`.
+ * @returns A `DeepgramStt` handle: `sendAudio` / `forceFlush` / `discard` /
+ *   `close`.
+ */
+export declare function createDeepgramStt(opts: {
+    token: string;
+    wssUrl: string;
+    flushMs: number;
+    wsFactory?: (url: string, protocols?: string[]) => WebSocket;
+} & SttCallbacks): DeepgramStt;

package/dist/embed/voice/mic-capture.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Microphone capture → PCM16 frames.
+ *
+ *   getUserMedia (mono)  ──▶  AudioContext({ sampleRate: 16000 })
+ *                        ──▶  AudioWorklet "audio-forwarder"  (preferred)
+ *                        ──▶  ScriptProcessorNode             (fallback)
+ *                        ──▶  floatTo16BitPcm(...)            ──▶  onPcm(ArrayBuffer)
+ *
+ * The capture is a small handle with `start()` / `stop()`. `start()` opens
+ * the mic at 16 kHz mono and streams little-endian PCM16 frames to `onPcm`;
+ * any setup failure is delivered to `onError`. `stop()` tears every handle
+ * down and is idempotent — safe before `start()` and after a failed start.
+ *
+ * Browser globals are optional-narrowed with explicit `=== undefined` /
+ * `!== undefined` checks so this module imports cleanly in a non-browser
+ * (test) context; nothing browser-bound is touched until `start()`.
+ */
+export type MicCapture = {
+    readonly start: () => Promise<void>;
+    readonly stop: () => void;
+};
+/**
+ * Create a microphone capture handle.
+ *
+ * @param opts.onPcm - Called with each little-endian PCM16 frame (one mic
+ *   render quantum) as an `ArrayBuffer`.
+ * @param opts.onError - Called with an `Error` if the mic is unavailable or
+ *   `start()` fails. `"mic_unavailable"` means `getUserMedia` is missing.
+ * @returns A `MicCapture` with `start()` / `stop()`.
+ */
+export declare function createMicCapture(opts: {
+    onPcm: (pcm: ArrayBuffer) => void;
+    onError: (e: Error) => void;
+}): MicCapture;

package/dist/embed/voice/sentence-split.d.ts

@@ -0,0 +1,11 @@
+/** Split text into sentences for chunked TTS playback.
+ *
+ *  Boundary rule: a run of terminators (`.`/`!`/`?`) ends a sentence only when
+ *  it is at end-of-string, OR is followed by whitespace whose next non-space
+ *  char looks like a sentence start (uppercase / digit / quote / open-bracket —
+ *  NOT lowercase or a comma), AND the word ending at the terminator is not a
+ *  known abbreviation. This intentionally under-splits (e.g. "Node.js now."
+ *  stays whole) — perfect NLP is out of scope; this only feeds TTS chunking,
+ *  where slight over/under-split is fine as long as no empty chunks are emitted
+ *  and listed abbreviations never break a sentence. */
+export declare function splitSentences(text: string): string[];

package/dist/embed/voice/voice-http.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JSON content-type + the standard auth/telemetry headers for voice endpoints.
+ * Async because the component DI token getter is awaited per request (see
+ * `authHeaders`). The Bearer header is included only when a token resolves.
+ */
+export declare function voiceJsonHeaders(): Promise<Record<string, string>>;
+/** Absolute URL for a voice endpoint path (e.g. "/v1/voice/tts"). */
+export declare function voiceUrl(path: string): string;

package/dist/embed/voice/voice-token.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Mirrors the belong-cloud `/v1/voice/token` 200 body. `deepgramToken` /
+ * `elevenlabsToken` may be empty (per-provider mint — see header), so they are
+ * not `.min(1)`; `voiceId` is likewise empty when ElevenLabs is unconfigured.
+ */
+declare const voiceTokensSchema: z.ZodObject<{
+    deepgramToken: z.ZodString;
+    deepgramWssUrl: z.ZodString;
+    elevenlabsToken: z.ZodString;
+    voiceId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deepgramToken: string;
+    deepgramWssUrl: string;
+    elevenlabsToken: string;
+    voiceId: string;
+}, {
+    deepgramToken: string;
+    deepgramWssUrl: string;
+    elevenlabsToken: string;
+    voiceId: string;
+}>;
+export type VoiceTokens = z.infer<typeof voiceTokensSchema>;
+export type VoiceTokenResult = {
+    ok: true;
+    tokens: VoiceTokens;
+} | {
+    ok: false;
+    reason: "unconfigured" | "error";
+};
+/**
+ * Fetch the voice-token bundle, reusing a cached success within its TTL.
+ *
+ * Only successes are cached — `unconfigured` / `error` are returned without
+ * caching so a transient failure does not pin a bad state for 20 s.
+ */
+export declare const fetchVoiceTokens: () => Promise<VoiceTokenResult>;
+/** Test hook — clears the cached bundle. */
+export declare const __resetVoiceTokenCache: () => void;
+export {};

package/dist/embed/voice-bus.d.ts

@@ -0,0 +1,75 @@
+import { fetchVoiceTokens } from './voice/voice-token.ts';
+import { createDeepgramStt } from './voice/deepgram-stt.ts';
+import { createMicCapture } from './voice/mic-capture.ts';
+export type VoiceStatus = "idle" | "requesting" | "listening" | "transcribing" | "error";
+/**
+ * Capture state. `status` is the single source of truth; `interim` is the live
+ * (non-final) transcript surfaced to the overlay so the user sees their words
+ * appear while speaking. `interim` is `""` when there is no live transcript.
+ */
+export type VoiceState = {
+    readonly status: VoiceStatus;
+    readonly interim: string;
+    readonly errorMessage?: string;
+};
+export declare const peekVoiceState: () => VoiceState;
+export declare const subscribeVoiceState: (listener: () => void) => (() => void);
+export declare const peekVoiceConfigured: () => boolean;
+export declare const subscribeTranscript: (listener: (text: string) => void) => (() => void);
+/**
+ * Push a final transcript to subscribers. Exposed for the test hook
+ * (window.belong.__pushVoiceTranscript) AND used by the engine after a
+ * successful transcription.
+ */
+export declare const pushTranscript: (text: string) => void;
+export declare const isVoiceSupported: () => boolean;
+/**
+ * The engine builders, behind overridable references so unit tests can inject
+ * fakes WITHOUT a real WebSocket or AudioContext (`__setVoiceEngineFactories`).
+ * Production code only ever reads `engine.*`.
+ */
+type VoiceEngineFactories = {
+    fetchTokens: typeof fetchVoiceTokens;
+    createStt: typeof createDeepgramStt;
+    createMic: typeof createMicCapture;
+};
+/**
+ * Test-only: override one or more engine factories. Pass `null` to restore the
+ * real builders. Production code never calls this.
+ */
+export declare const __setVoiceEngineFactories: (overrides: Partial<VoiceEngineFactories> | null) => void;
+/**
+ * Read the latest live (non-final) interim transcript, "" when none. Sourced
+ * from the reactive state so it stays consistent with `peekVoiceState().interim`.
+ */
+export declare const peekVoiceInterim: () => string;
+/**
+ * Begin a push-to-talk capture: mint a voice token, open the streaming STT,
+ * then start the mic. No-op unless idle/error (a re-entrant start while
+ * requesting/listening is ignored).
+ */
+export declare const startCapture: () => void;
+/**
+ * Stop the mic and finalize the utterance. No-op unless listening. Rather than
+ * emitting whatever is buffered the instant the key is released (which clips
+ * the last word or two still being processed by Deepgram), `finalize()` asks
+ * Deepgram to transcribe its remaining buffered audio and return it; the
+ * complete final then arrives via the STT's `onFinal` (→ pushTranscript →
+ * idle). A fallback timer guarantees we never hang in `transcribing`.
+ */
+export declare const stopCapture: () => void;
+/** Abandon the current capture without transcribing. */
+export declare const cancelCapture: () => void;
+/**
+ * Back-compat toggle for callers that drive a single mic button: flip
+ * between start and stop based on the current status. Idle/error → start;
+ * listening → stop; transcribing/requesting → no-op.
+ */
+export declare const toggleVoiceCapture: () => void;
+/**
+ * Test-only: tear down every side effect (live stt/mic, pending timers) and
+ * reset to a clean idle store with no listeners. The engine is a module
+ * singleton, so unit tests must reset it in `beforeEach` to stay isolated.
+ */
+export declare const __resetVoiceForTest: () => void;
+export {};

package/dist/embed/voice-config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Voice configuration — module-level knobs shared by the capture engine
+ * (`voice-bus.ts`) and the TTS player (`voice-tts.ts`).
+ *
+ * The host sets these once at init (or via the public API):
+ *
+ *   • `apiBaseUrl`     — where `/v1/voice/*` lives (same origin as the rest
+ *                        of the backend RPC client). Default "" → same-origin
+ *                        relative fetch.
+ *   • `pushToTalkKey`  — a `KeyboardEvent.code` (default "ControlLeft") the
+ *                        dock binds for hold-to-talk. This is the HOST default;
+ *                        the end user may override it per browser via
+ *                        `voice-prefs.ts` (the dock binds the EFFECTIVE key
+ *                        from `getEffectivePushToTalkKey()`).
+ *   • `autoplayTts`    — whether assistant replies are spoken aloud by default.
+ *   • `voiceId`        — TTS voice id; "" means "let the backend default apply".
+ *   • `utteranceFlushMs` — how long (ms) to wait before flushing a buffered
+ *                          partial utterance to the backend. Default 1000.
+ *   • `callSilenceMs`  — silence window (ms) after which a live call turn ends.
+ *                        Default 3000.
+ *   • `ttsPlaybackRate` — client-side playback speed for spoken audio (filler +
+ *                         reply). Gemini's batch TTS has no rate knob, so we slow
+ *                         it on the element (pitch preserved). Default 0.9 (10%
+ *                         slower); sane range 0.5–1.5.
+ *   • `ttsChunkGapMs`  — minimum pause (ms) between sentence chunks in
+ *                        conversational playback, so consecutive sentences
+ *                        breathe like natural speech instead of running
+ *                        back-to-back. Default 350; 0 disables the pause.
+ *
+ * Plain module state mirrors `theme.ts`: no class, no DI — these are global
+ * UX preferences for the embedded dock, not domain state.
+ */
+export type VoiceConfigInput = {
+    readonly apiBaseUrl?: string;
+    readonly pushToTalkKey?: string;
+    readonly autoplayTts?: boolean;
+    readonly voiceId?: string;
+    readonly utteranceFlushMs?: number;
+    readonly callSilenceMs?: number;
+    readonly ttsPlaybackRate?: number;
+    readonly ttsChunkGapMs?: number;
+};
+/** Merge host-provided config; `undefined` fields leave the current value intact. */
+export declare const configureVoice: (input: VoiceConfigInput) => void;
+export declare const getVoiceApiBaseUrl: () => string;
+export declare const getPushToTalkKey: () => string;
+export declare const getAutoplayTtsDefault: () => boolean;
+export declare const getVoiceId: () => string;
+export declare const getUtteranceFlushMs: () => number;
+export declare const getCallSilenceMs: () => number;
+export declare const getTtsPlaybackRate: () => number;
+export declare const getTtsChunkGapMs: () => number;

package/dist/embed/voice-fillers.d.ts

@@ -0,0 +1,2 @@
+export declare function nextFillerPhrase(): string;
+export declare function __resetFillers(): void;

package/dist/embed/voice-prefs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * User voice preferences — the per-browser push-to-talk key override and the
+ * first-conversation voice hint flag.
+ *
+ *   Host default (voice-config `pushToTalkKey`)  ◀  user pref (localStorage)
+ *
+ * `voice-config.ts` carries the HOST's deployment-wide knobs (set once via
+ * `configureVoice`); this module layers the END USER's own choice on top, the
+ * same way `theme.ts` layers user prefs over the host theme. Components read
+ * the EFFECTIVE key (user pref if set, else host default) through a tiny
+ * external store (`subscribePushToTalkKey` / `peekPushToTalkKey`) so the
+ * settings UI, the composer tooltip, and the dock's key handler all rebind
+ * live when the user picks a new key.
+ *
+ * localStorage is a perimeter: the prefs bag is zod-validated on read and any
+ * junk (corrupted JSON, wrong shape, storage disabled) degrades to "no pref".
+ */
+/** `useSyncExternalStore` subscribe — fires on set/clear of the user key. */
+export declare const subscribePushToTalkKey: (listener: () => void) => (() => void);
+/** The user's own override, or `null` when the host default applies. */
+export declare const peekUserPushToTalkKey: () => string | null;
+/** The key the dock actually binds: user pref if set, else the host default. */
+export declare const getEffectivePushToTalkKey: () => string;
+/** `useSyncExternalStore` snapshot — the effective key (string, so stable). */
+export declare const peekPushToTalkKey: () => string;
+/** Persist a user-chosen `KeyboardEvent.code` and notify subscribers. */
+export declare const setUserPushToTalkKey: (code: string) => void;
+/** Drop the user override (back to the host default) and notify subscribers. */
+export declare const clearUserPushToTalkKey: () => void;
+/** True once the push-to-talk hint chip was dismissed (X or first capture). */
+export declare const readVoiceHintDismissed: () => boolean;
+/** Persist the hint dismissal so it never shows again in this browser. */
+export declare const dismissVoiceHint: () => void;
+/**
+ * The user's explicit speaker choice — `true`/`false` once they've toggled it,
+ * or `null` when they never have (the host `autoplayTts` default then applies).
+ * localStorage is a perimeter: only the two known string markers read as a
+ * decision; anything else (junk, storage disabled) degrades to "no choice".
+ */
+export declare const readPersistedTtsEnabled: () => boolean | null;
+/** Persist the user's speaker choice so it survives a reload. */
+export declare const setPersistedTtsEnabled: (enabled: boolean) => void;
+/** Drop the persisted speaker choice (back to the host default). Test-only. */
+export declare const clearPersistedTtsEnabled: () => void;
+/**
+ * Human label for a `KeyboardEvent.code`: "ControlLeft" → "Left Ctrl",
+ * "KeyA" → "A", "Digit7" → "7". Codes with no friendlier reading ("Space",
+ * "F1", unknown codes) pass through unchanged.
+ */
+export declare const formatKeyCode: (code: string) => string;
+/**
+ * Test-only: clear listeners and re-seed the user key from localStorage. The
+ * store is a module singleton, so unit tests reset it in `beforeEach`.
+ */
+export declare const __resetVoicePrefsForTest: () => void;

package/dist/embed/voice-tts.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Voice TTS player — autoplay of assistant replies via the BATCH `/v1/voice/tts`
+ * endpoint, played through an `HTMLAudioElement`, with barge-in cancel.
+ *
+ *   speak(text)  ──▶  POST /v1/voice/tts  ──▶  audio Blob (e.g. audio/wav)
+ *                ──▶  new Audio(objectURL).play()
+ *
+ * This is the BATCH path: the backend's working provider is Gemini, which is a
+ * single REST `:generateContent` call returning the whole clip — not a token
+ * stream — so the SDK fetches the full audio body and plays it as one clip
+ * rather than scheduling PCM chunks over a WebSocket. The public store API is
+ * unchanged (speak / stopSpeaking / toggle / setEnabled / isEnabled / peek /
+ * subscribe + the lazy `enabled` default).
+ *
+ * The player owns at most one in-flight clip: a fresh `speak()` cancels whatever
+ * is playing first (single active clip). `enabled` gates autoplay (the dock's
+ * speaker toggle); turning it off mid-clip cancels the current clip.
+ *
+ * Generation guard: each `speak()` bumps a monotonic `speakGeneration` and binds
+ * the fetch + audio-element lifecycle to the value it captured. A later `speak()`
+ * (or `stopSpeaking()`) bumps the generation again, so a superseded or cancelled
+ * clip's late events (a fetch that resolves after cancel, a stale `onended`)
+ * become no-ops and cannot flip the new clip's status.
+ *
+ * Failure is silent: a non-ok response (503 unconfigured / 502 provider error),
+ * a network error, or a blocked autoplay lands the player back in idle with no
+ * thrown error — voice simply does not play, exactly like a missing key today.
+ */
+export type TtsStatus = "idle" | "loading" | "speaking";
+export type TtsState = {
+    readonly status: TtsStatus;
+    readonly enabled: boolean;
+};
+export declare const peekTtsState: () => TtsState;
+export declare const subscribeTtsState: (listener: () => void) => (() => void);
+export declare const isTtsEnabled: () => boolean;
+export declare const setTtsEnabled: (value: boolean) => void;
+export declare const toggleTtsEnabled: () => void;
+/** Minimal player surface (kept stable so the chunk queue + tests don't change). */
+export type TtsAudio = {
+    play: () => Promise<void>;
+    pause: () => void;
+    onplay: (() => void) | null;
+    onended: (() => void) | null;
+    onerror: (() => void) | null;
+    currentTime: number;
+    /** Playback speed multiplier (Web Audio also shifts pitch); set before play(). */
+    playbackRate: number;
+};
+/** Seam for the network call so tests never hit the wire. */
+type FetchLike = typeof fetch;
+/** Seam for audio construction so tests never touch real Web Audio. */
+type AudioFactory = (data: ArrayBuffer) => TtsAudio;
+/** The slice of `AudioContext` the player needs — narrowed so tests inject a fake. */
+export type TtsAudioContext = {
+    readonly state: AudioContextState;
+    readonly destination: AudioNode;
+    resume: () => Promise<void>;
+    decodeAudioData: (data: ArrayBuffer) => Promise<AudioBuffer>;
+    createBufferSource: () => AudioBufferSourceNode;
+};
+type AudioContextFactory = () => TtsAudioContext | null;
+/**
+ * Resume the shared AudioContext from a user gesture (mic press / send) so the
+ * later, async TTS reply is allowed to play under the browser's autoplay
+ * policy. Safe + idempotent: a no-op when Web Audio is unavailable or the
+ * context is already running.
+ */
+export declare const unlockTtsPlayback: () => void;
+/** Cancel any in-flight clip (barge-in) and reset to idle. */
+export declare const stopSpeaking: () => void;
+/**
+ * Fetch TTS audio for `text` from the batch endpoint and play it. No-op when
+ * disabled or when the text is empty/whitespace. Never throws — any failure
+ * (unconfigured 503, provider 502, network, decode, blocked autoplay) lands the
+ * player back in idle.
+ */
+export declare const speak: (text: string) => void;
+/**
+ * Speak a long assistant reply conversationally: first condense it via
+ * `/v1/voice/spoken-summary`, then synthesize + play the result one sentence
+ * chunk at a time with one-ahead prefetch so the next chunk's audio is ready
+ * before the current one ends. No-op when disabled or empty. Never throws —
+ * a failed first chunk falls back to a single `speak()`; failed later chunks
+ * are skipped. Superseded by `stopSpeaking()` or a later speak via the shared
+ * generation guard (remaining chunks stop fetching/playing).
+ */
+export declare const speakConversational: (fullText: string) => Promise<void>;
+/**
+ * Test-only: inject a fake `fetch` and audio factory so unit tests exercise the
+ * store's status machine without a real network or `Audio` element. Pass `null`
+ * to reset to the real implementations.
+ */
+export declare const __setTtsFetch: (fake: FetchLike | null) => void;
+export declare const __setTtsAudioFactory: (fake: AudioFactory | null) => void;
+/** Test-only: inject a fake AudioContext (drives `unlockTtsPlayback` + the real
+ *  default factory's decode/play path). Pass `null` to restore the real one. */
+export declare const __setTtsAudioContextFactory: (fake: AudioContextFactory | null) => void;
+/** Test-only: cancel playback, reset the seed flag + store, drop listeners. */
+export declare const __resetTtsForTest: () => void;
+export {};

package/dist/embed/workspace-paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tiny pure helpers for splitting a workspace-relative path (`a/b/c.csv`) into
+ * its parts. Shared by the `@`-mention picker + chip and the at-mention parser
+ * so the "filename is everything after the last slash" rule lives in one place.
+ */
+/** The path segment after the last `/` (the filename). */
+export declare const basename: (path: string) => string;
+/** The directory portion before the last `/` (empty for a top-level file). */
+export declare const dirname: (path: string) => string;

package/dist/infrastructure/telemetry/session-span-processor.d.ts

@@ -0,0 +1,11 @@
+import { Span, SpanProcessor } from '@opentelemetry/sdk-trace-web';
+/** Span-attribute key; mirrors the `session.id` belong-cloud stamps server-side. */
+export declare const SESSION_ID_ATTRIBUTE = "session.id";
+export declare class SessionSpanProcessor implements SpanProcessor {
+    #private;
+    constructor(getActiveSessionId: () => string | null);
+    onStart(span: Span): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/infrastructure/telemetry/web-sdk.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Browser-side OpenTelemetry bootstrap. Called once from `embed/bootstrap.ts`
+ * (the single SDK init point shared by the dev server and the production embed)
+ * BEFORE any user code, so:
+ *   • document-load instrumentation captures paint timings
+ *   • fetch instrumentation patches window.fetch before React makes calls
+ *   • W3C traceparent gets injected on outbound requests
+ *   • every span is stamped with the active `session.id` (see options below)
+ *
+ * Exporter selection: with VITE_OTEL_EXPORTER_OTLP_ENDPOINT set, spans ship
+ * there (point it at the local Collector in docker-compose.otel.yml to reach
+ * Jaeger). With it unset we use a console exporter IN DEV ONLY — a production
+ * embed with no endpoint stays silent rather than spamming the host's console.
+ *
+ * The Collector MUST have CORS enabled for the browser to POST OTLP/HTTP
+ * (the included otel-collector-config.yaml does this).
+ */
+/** Options for {@link startWebTelemetry}. */
+type WebTelemetryOptions = {
+    /**
+     * Reads the current chat session id (or null). When supplied, every span is
+     * stamped with `session.id` so browser traces correlate with belong-cloud's
+     * server-side `session.id` spans + logs. Injected (not imported) to keep this
+     * module free of a `stream/` dependency — see {@link SessionSpanProcessor}.
+     */
+    getActiveSessionId?: () => string | null;
+};
+export declare function startWebTelemetry(options?: WebTelemetryOptions): void;
+export {};

package/dist/lib/belong.d.ts

@@ -0,0 +1,12 @@
+/** Belong brand palette (from the Belong brand kit). Ocean is the one accent. */
+export declare const BELONG: {
+    readonly deepSea: "#0F1B2E";
+    readonly ocean: "#2D6F66";
+    readonly coral: "#E06A4F";
+    readonly sun: "#D9A441";
+    readonly sand: "#F1E7D6";
+    readonly heather: "#6D5B8C";
+    readonly ink: "#1C2330";
+};
+/** First letter for an avatar, from a username (falls back to '?'). */
+export declare const avatarInitial: (name: string | null | undefined) => string;

package/dist/lib/tab-leadership.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Multi-tab same-session guard (plan 007 §C5).
+ *
+ * Two dock tabs open on ONE session can double-send and clobber the persisted
+ * `{ runId, lastEventId }` stream state. This module elects a single LEADER
+ * tab per session over a `BroadcastChannel` (`belong:session:<sessionId>`);
+ * follower tabs banner "open in another tab" and disable the composer.
+ *
+ * Protocol (all messages Zod-parsed at the perimeter — §4):
+ *   - on start every tab broadcasts a `claim` carrying `{ tabId, claimedAtMs }`
+ *   - seniority = the EARLIER claim; equal timestamps tie-break on tabId
+ *   - the leader heartbeats every ~5 s and re-asserts when a junior claims
+ *   - a tab that hears a senior claim/heartbeat becomes follower
+ *   - a follower takes over when no senior beat lands for ~12 s, or
+ *     immediately on the leader's `release` (stop / pagehide)
+ *
+ * Feature detection: no `BroadcastChannel` (older WebKit, jsdom) → guard
+ * disabled, the tab stays leader, zero behavior change.
+ */
+export type TabRole = "leader" | "follower";
+export declare const HEARTBEAT_INTERVAL_MS = 5000;
+export declare const TAKEOVER_TIMEOUT_MS = 12000;
+/** The narrow `BroadcastChannel` surface the guard uses (injectable for tests). */
+export type LeadershipChannel = {
+    postMessage: (message: unknown) => void;
+    close: () => void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+};
+export type TabLeadershipOptions = {
+    readonly sessionId: string;
+    /** Fired on every role CHANGE (the caller assumes "leader" until told). */
+    readonly onRoleChange: (role: TabRole) => void;
+    readonly heartbeatIntervalMs?: number;
+    readonly takeoverTimeoutMs?: number;
+    /** Channel seam; return `null` for "unsupported" (guard disabled). */
+    readonly createChannel?: (name: string) => LeadershipChannel | null;
+    /** Clock seam (§25). */
+    readonly nowMs?: () => number;
+};
+export type TabLeadershipHandle = {
+    readonly stop: () => void;
+};
+export declare const tabLeadershipChannelName: (sessionId: string) => string;
+export declare const startTabLeadership: (options: TabLeadershipOptions) => TabLeadershipHandle;

package/dist/lib/use-tab-leadership.d.ts

@@ -0,0 +1,8 @@
+import { TabRole } from './tab-leadership.ts';
+/**
+ * @param chatId The mount-time chat id — the persisted server session if one
+ *   was already known at mount, else a per-tab `belong-chat-<nanoid>`
+ *   placeholder. Used only as the channel key until the real server session id
+ *   is persisted.
+ */
+export declare const useTabLeadership: (chatId: string) => TabRole;

package/dist/lib/utils.d.ts

@@ -0,0 +1,9 @@
+import { ClassValue } from 'clsx';
+export declare const cn: (...inputs: ClassValue[]) => string;
+/**
+ * Compact "time ago" label for switcher / list rows — "just now", "5m ago",
+ * "3h ago", "2d ago", else a locale date. `nowMs` is injectable so the pure
+ * formatting is deterministic under test. Best-effort: an unparseable input
+ * yields "" (the row simply shows no timestamp).
+ */
+export declare const formatRelativeTime: (iso: string, nowMs?: number) => string;

package/dist/public-api.d.ts

@@ -0,0 +1,3 @@
+export type { BelongGlobal, BelongInitInput, BelongTheme, BelongThemeBrand, BelongThemeDensity, BelongThemeMode, BelongThemePalette, BelongThemeSide, PartialBelongTheme, RouteHandler, RouteHandlerResult, UiActionHandler, UiActionResult, } from './types/public.ts';
+export { SdkProviders } from './app/providers.tsx';
+export { createApiClient, setBelongToken } from './api/client.ts';

package/dist/routes/chat-attachment-chip.d.ts

@@ -0,0 +1,9 @@
+import { FileUIPart } from 'ai';
+export type AttachmentChipProps = {
+    readonly part: FileUIPart;
+    readonly renderKey: string;
+    readonly fileId: string | null;
+};
+export declare const AttachmentChip: ({ part, renderKey, fileId }: AttachmentChipProps) => import("react").JSX.Element;
+/** Read the server fileId threaded onto the part by uploadFilesWithParts. */
+export declare const fileIdFromPart: (part: FileUIPart) => string | null;