@runtypelabs/persona 3.34.1 → 3.36.0

package/dist/voice-worklet-player.d.ts

@@ -0,0 +1,215 @@
+/** A unit of speech handed to a {@link SpeechEngine}. */
+interface SpeechRequest {
+    /** Plain text to speak. The widget strips Markdown before calling the engine. */
+    text: string;
+    /** Preferred voice identifier (engine-specific; browser = voice name). */
+    voice?: string;
+    /** Speech rate (engine-specific range; browser: 0.1–10, default 1). */
+    rate?: number;
+    /** Speech pitch (engine-specific range; browser: 0–2, default 1). */
+    pitch?: number;
+}
+/** Lifecycle callbacks a {@link SpeechEngine} invokes during playback. */
+interface SpeechCallbacks {
+    /** Audio has started playing. */
+    onStart?: () => void;
+    /** Playback finished naturally (or was canceled). */
+    onEnd?: () => void;
+    /** Playback failed. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Pluggable text-to-speech engine behind the "Read aloud" message action.
+ *
+ * The widget ships a browser Web Speech API engine by default. Provide a hosted
+ * engine (Runtype TTS, ElevenLabs, a server proxy, …) by implementing this
+ * interface and returning it from {@link TextToSpeechConfig.createEngine}; a
+ * server engine can stream audio into the realtime voice
+ * {@link VoicePlaybackEngine}.
+ */
+interface SpeechEngine {
+    /** Stable identifier, e.g. `"browser"`, `"runtype"`, or a custom id. */
+    readonly id: string;
+    /**
+     * Whether {@link pause}/{@link resume} are supported. When `false`, the UI
+     * offers play/stop only (tapping a playing message stops it).
+     */
+    readonly supportsPause: boolean;
+    /** Begin speaking. Drives the lifecycle through `callbacks`. */
+    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
+    /** Pause playback (no-op if unsupported). */
+    pause(): void;
+    /** Resume paused playback (no-op if unsupported). */
+    resume(): void;
+    /** Stop playback and discard any queued audio. */
+    stop(): void;
+    /** Optional teardown of engine resources. */
+    destroy?(): void;
+}
+/**
+ * Streaming PCM playback engine used by the realtime voice provider.
+ *
+ * The provider feeds raw PCM16 LE mono @ 24kHz (WAV header already stripped)
+ * via `enqueue`, signals end-of-reply with `markStreamEnd`, and learns when
+ * playback has fully drained via `onFinished`. The default implementation is
+ * `AudioPlaybackManager`; an optional jitter-buffered AudioWorklet engine ships
+ * from `@runtypelabs/persona/voice-worklet-player` and can be injected via the
+ * `runtype.createPlaybackEngine` config hook.
+ */
+interface VoicePlaybackEngine {
+    /** Enqueue a raw PCM16 LE mono @ 24kHz chunk (no WAV header). */
+    enqueue(pcm: Uint8Array): void;
+    /** Signal that no more chunks will arrive for the current reply. */
+    markStreamEnd(): void;
+    /** Immediately stop playback and discard queued audio. */
+    flush(): void;
+    /** Register a callback fired once all queued audio has finished playing. */
+    onFinished(callback: () => void): void;
+    /** Release all audio resources. */
+    destroy(): Promise<void> | void;
+}
+/**
+ * A {@link VoicePlaybackEngine} that also supports pause/resume. Returned by
+ * `createPcmStreamPlayer` (`@runtypelabs/persona/voice-worklet-player`): a
+ * jitter-buffered AudioWorklet player for raw PCM16 / 24 kHz / mono streams.
+ * Reuse it inside a hosted {@link SpeechEngine} to get gapless playback with a
+ * configurable prebuffer and graceful underrun handling — feed each streamed
+ * chunk to {@link VoicePlaybackEngine.enqueue} and the worklet does the rest.
+ */
+interface PcmStreamPlayer extends VoicePlaybackEngine {
+    /** Pause playback; the audio clock suspends and {@link resume} continues in place. */
+    pause(): void;
+    /** Resume playback after {@link pause}. */
+    resume(): void;
+    /**
+     * Register a callback fired once audible playback actually begins — i.e. the
+     * prebuffer waterline filled and the first sample reached the output. Use this
+     * (rather than "first chunk enqueued") to flip a UI from loading to playing, so
+     * the spinner holds through the prebuffer. Fires once per playback session
+     * (cleared by {@link VoicePlaybackEngine.flush}); a mid-reply underrun re-buffer
+     * does not re-fire it.
+     */
+    onStarted(callback: () => void): void;
+}
+
+interface PcmStreamPlayerOptions {
+    /**
+     * Audio (ms) to buffer before the first sample, and to re-buffer after an
+     * underrun. Higher = smoother on bursty/jittery streams, at the cost of a
+     * slightly later first sound (latency ↔ smoothness). Default 150 — good for
+     * realtime, server-paced audio; HTTP-pulled TTS often wants ~400–600.
+     */
+    prebufferMs?: number;
+}
+/**
+ * Create a jitter-buffered AudioWorklet PCM player with pause/resume.
+ *
+ * Feed it raw PCM16 / 24 kHz / mono via `enqueue()`; it handles prebuffering,
+ * gapless playback, and graceful underrun. Reuse it inside a hosted
+ * {@link SpeechEngine} so streamed TTS plays smoothly:
+ *
+ * @example
+ * import { createPcmStreamPlayer } from '@runtypelabs/persona/voice-worklet-player'
+ * const player = await createPcmStreamPlayer({ prebufferMs: 500 })
+ * // for each streamed chunk: player.enqueue(pcmChunk)
+ * player.markStreamEnd()
+ */
+declare function createPcmStreamPlayer(options?: PcmStreamPlayerOptions): Promise<PcmStreamPlayer>;
+/**
+ * Realtime-named alias of {@link createPcmStreamPlayer} (default prebuffer),
+ * typed as a plain {@link VoicePlaybackEngine}. Pass it to the realtime voice
+ * provider's `createPlaybackEngine`:
+ *
+ * @example
+ * import { createWorkletPlaybackEngine } from '@runtypelabs/persona/voice-worklet-player'
+ *
+ * initAgentWidget({ config: { voiceRecognition: { enabled: true, provider: {
+ *   type: 'runtype',
+ *   runtype: { agentId, createPlaybackEngine: createWorkletPlaybackEngine },
+ * } } } })
+ */
+declare function createWorkletPlaybackEngine(): Promise<VoicePlaybackEngine>;
+
+interface RuntypeSpeechEngineOptions {
+    /**
+     * Runtype API host, e.g. `https://api.runtype.com` (typically the widget's
+     * `apiUrl`). A trailing slash is tolerated.
+     */
+    host: string;
+    /** Agent whose configured voice synthesizes the text. */
+    agentId: string;
+    /** Browser-safe client token — the same one the chat widget uses. */
+    clientToken: string;
+    /**
+     * Default voice id, used when a `SpeechRequest` doesn't carry its own. When
+     * omitted the agent's configured voice is used.
+     */
+    voice?: string;
+    /**
+     * Audio (ms) the player buffers before the first sample and after an
+     * underrun. Runtype streams steadily, so the default (200) keeps first sound
+     * close to time-to-first-byte while still riding out small hiccups. Applies to
+     * the default {@link AudioPlaybackManager}; a custom `createPlaybackEngine` is
+     * responsible for its own prebuffer.
+     */
+    prebufferMs?: number;
+    /**
+     * Factory for the streaming PCM player. Defaults to the in-bundle, main-thread
+     * {@link AudioPlaybackManager} (with `prebufferMs`). Pass `createPcmStreamPlayer`
+     * from `@runtypelabs/persona/voice-worklet-player` for the jitter-buffered
+     * AudioWorklet player (it then ships in your bundle, not Persona's). May be
+     * async — it is resolved on first playback, inside the user gesture.
+     */
+    createPlaybackEngine?: () => PcmStreamPlayer | Promise<PcmStreamPlayer>;
+    /**
+     * Optional hook for surfacing fetch/stream failures (a missing endpoint, an
+     * expired token, an upstream 4xx) to a log or telemetry. The widget itself
+     * only returns the read-aloud button to idle (or, with a fallback engine,
+     * silently switches to the browser voice), so without this the reason is
+     * invisible.
+     */
+    onError?: (error: Error) => void;
+}
+/** Streaming `SpeechEngine` backed by Runtype's `/v1/agents/:id/speak`. */
+declare class RuntypeSpeechEngine implements SpeechEngine {
+    private readonly opts;
+    readonly id = "runtype-tts";
+    readonly supportsPause = true;
+    private player;
+    private playerPromise;
+    private generation;
+    constructor(opts: RuntypeSpeechEngineOptions);
+    private ensurePlayer;
+    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
+    private run;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    destroy(): void;
+}
+
+interface FallbackSpeechEngineOptions {
+    /**
+     * Called once when the primary engine fails before audio starts and the
+     * fallback takes over — so a silent downgrade is still observable in dev/
+     * telemetry even though the user keeps hearing speech.
+     */
+    onFallback?: (error: Error) => void;
+}
+/** A `SpeechEngine` that falls back from `primary` to `fallback` per utterance. */
+declare class FallbackSpeechEngine implements SpeechEngine {
+    private readonly primary;
+    private readonly fallback;
+    private readonly options;
+    readonly id = "fallback";
+    private active;
+    constructor(primary: SpeechEngine, fallback: SpeechEngine, options?: FallbackSpeechEngineOptions);
+    get supportsPause(): boolean;
+    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    destroy(): void;
+}
+
+export { FallbackSpeechEngine, type FallbackSpeechEngineOptions, type PcmStreamPlayer, type PcmStreamPlayerOptions, RuntypeSpeechEngine, type RuntypeSpeechEngineOptions, type VoicePlaybackEngine, createPcmStreamPlayer, createWorkletPlaybackEngine };

package/dist/voice-worklet-player.js

@@ -0,0 +1,80 @@
+var P=`
+class PersonaPcmPlayerProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super()
+    const opts = (options && options.processorOptions) || {}
+    this.waterline = opts.waterlineSamples > 0 ? opts.waterlineSamples : 3600
+    this.chunks = []
+    this.readOffset = 0
+    this.buffered = 0
+    this.waiting = true
+    // 'drained' must mean "the reply finished playing", not "momentary
+    // underrun": a jitter gap empties the buffer mid-reply too, and firing
+    // there would flap the UI status and race the audio_end handler. Only
+    // report drained once eos has been signalled.
+    this.eosSeen = false
+    // Fire 'started' once, when the prebuffer first releases into playback, so a
+    // consumer can flip UI from loading\u2192playing only when audio is truly audible.
+    // A mid-reply underrun re-buffers (waiting=true) but must NOT re-signal.
+    this.startedSignaled = false
+    this.port.onmessage = (e) => {
+      const msg = e.data
+      if (msg.type === 'push') {
+        this.eosSeen = false
+        this.chunks.push(msg.samples)
+        this.buffered += msg.samples.length
+        if (this.waiting && this.buffered >= this.waterline) {
+          this.waiting = false
+          this.signalStarted()
+        }
+      } else if (msg.type === 'eos') {
+        this.eosSeen = true
+        if (this.waiting && this.buffered > 0) {
+          this.waiting = false
+          this.signalStarted()
+        }
+        if (this.buffered === 0) {
+          this.eosSeen = false
+          this.port.postMessage({ type: 'drained' })
+        }
+      } else if (msg.type === 'clear') {
+        this.chunks = []
+        this.readOffset = 0
+        this.buffered = 0
+        this.waiting = true
+        this.eosSeen = false
+        this.startedSignaled = false
+      }
+    }
+  }
+  signalStarted() {
+    if (!this.startedSignaled) {
+      this.startedSignaled = true
+      this.port.postMessage({ type: 'started' })
+    }
+  }
+  process(inputs, outputs) {
+    const out = outputs[0][0]
+    if (!out || this.waiting) return true // outputs are pre-zeroed: silence
+    let i = 0
+    while (i < out.length && this.buffered > 0) {
+      const chunk = this.chunks[0]
+      out[i++] = chunk[this.readOffset++]
+      this.buffered--
+      if (this.readOffset >= chunk.length) {
+        this.chunks.shift()
+        this.readOffset = 0
+      }
+    }
+    if (this.buffered === 0) {
+      this.waiting = true // mid-reply underrun: re-buffer silently
+      if (this.eosSeen) {
+        this.eosSeen = false
+        this.port.postMessage({ type: 'drained' })
+      }
+    }
+    return true
+  }
+}
+registerProcessor('persona-pcm-player', PersonaPcmPlayerProcessor)
+`;function b(o){let e=o.length>>1,t=new Float32Array(e),r=new DataView(o.buffer,o.byteOffset,o.byteLength);for(let s=0;s<e;s++)t[s]=r.getInt16(s*2,!0)/32768;return t}async function v(o={}){var f;let e=(f=o.prebufferMs)!=null?f:150,t=Math.max(1,Math.round(24e3*e/1e3)),r=window.AudioContext||window.webkitAudioContext,s=new r({sampleRate:24e3});s.state==="suspended"&&await s.resume().catch(()=>{});let a=URL.createObjectURL(new Blob([P],{type:"application/javascript"}));try{await s.audioWorklet.addModule(a)}catch(u){throw s.close().catch(()=>{}),u}finally{URL.revokeObjectURL(a)}let i=new AudioWorkletNode(s,"persona-pcm-player",{numberOfInputs:0,numberOfOutputs:1,outputChannelCount:[1],processorOptions:{waterlineSamples:t}});i.connect(s.destination);let p=[],h=[],l=null;return i.port.onmessage=u=>{var d;let n=(d=u.data)==null?void 0:d.type;if(n==="started"){let c=h.slice();h=[],c.forEach(y=>y())}else if(n==="drained"){let c=p.slice();p=[],c.forEach(y=>y())}},{enqueue(u){let n=u;if(l){let c=new Uint8Array(l.length+u.length);c.set(l),c.set(u,l.length),n=c,l=null}if(n.length%2!==0&&(l=new Uint8Array([n[n.length-1]]),n=n.subarray(0,n.length-1)),n.length===0)return;let d=b(n);d.length!==0&&i.port.postMessage({type:"push",samples:d},[d.buffer])},markStreamEnd(){i.port.postMessage({type:"eos"})},flush(){l=null,p=[],h=[],i.port.postMessage({type:"clear"})},onFinished(u){p.push(u)},onStarted(u){h.push(u)},pause(){s.state==="running"&&s.suspend()},resume(){s.state==="suspended"&&s.resume()},destroy(){i.port.onmessage=null;try{i.disconnect()}catch{}return s.close().catch(()=>{})}}}function w(){return v()}var m=class{constructor(e=24e3,t={}){this.ctx=null;this.nextStartTime=0;this.activeSources=[];this.finishedCallbacks=[];this.startedCallbacks=[];this.playing=!1;this.streamEnded=!1;this.pendingCount=0;this.started=!1;this.userPaused=!1;this.pendingBuffers=[];this.pendingSamples=0;this.remainder=null;var s;this.sampleRate=e;let r=Math.max(0,(s=t.prebufferMs)!=null?s:0);this.waterlineSamples=Math.round(e*r/1e3),this.buffering=this.waterlineSamples>0}ensureContext(){if(!this.ctx){let t=typeof window!="undefined"?window:void 0;if(!t)throw new Error("AudioPlaybackManager requires a browser environment");let r=t.AudioContext||t.webkitAudioContext;this.ctx=new r({sampleRate:this.sampleRate})}let e=this.ctx;return e.state==="suspended"&&!this.userPaused&&e.resume(),e}enqueue(e){if(e.length===0)return;let t=e;if(this.remainder){let s=new Uint8Array(this.remainder.length+e.length);s.set(this.remainder),s.set(e,this.remainder.length),t=s,this.remainder=null}if(t.length%2!==0&&(this.remainder=new Uint8Array([t[t.length-1]]),t=t.subarray(0,t.length-1)),t.length===0)return;let r=this.pcmToFloat32(t);r.length!==0&&(this.buffering?(this.pendingBuffers.push(r),this.pendingSamples+=r.length,this.pendingSamples>=this.waterlineSamples&&this.releaseBuffer()):this.scheduleSamples(r))}markStreamEnd(){this.pendingBuffers.length>0&&this.releaseBuffer(),this.streamEnded=!0,this.checkFinished()}flush(){for(let e of this.activeSources)try{e.stop(),e.disconnect()}catch{}this.activeSources=[],this.pendingCount=0,this.nextStartTime=0,this.playing=!1,this.streamEnded=!1,this.finishedCallbacks=[],this.startedCallbacks=[],this.remainder=null,this.pendingBuffers=[],this.pendingSamples=0,this.buffering=this.waterlineSamples>0,this.started=!1}isPlaying(){return this.playing}onFinished(e){this.finishedCallbacks.push(e)}onStarted(e){this.startedCallbacks.push(e)}pause(){this.userPaused=!0,this.ctx&&this.ctx.state==="running"&&this.ctx.suspend()}resume(){this.userPaused=!1,this.ctx&&this.ctx.state==="suspended"&&this.ctx.resume()}async destroy(){this.flush(),this.ctx&&(await this.ctx.close(),this.ctx=null)}releaseBuffer(){this.buffering=!1;let e=this.pendingBuffers;this.pendingBuffers=[],this.pendingSamples=0;for(let t of e)this.scheduleSamples(t)}scheduleSamples(e){if(e.length===0)return;let t=this.ensureContext(),r=t.createBuffer(1,e.length,this.sampleRate);r.getChannelData(0).set(e);let s=t.createBufferSource();s.buffer=r,s.connect(t.destination);let a=t.currentTime;if(this.nextStartTime===0?this.nextStartTime=a:this.nextStartTime<a&&(this.nextStartTime=a,this.waterlineSamples>0&&(this.buffering=!0)),s.start(this.nextStartTime),this.nextStartTime+=r.duration,this.activeSources.push(s),this.pendingCount++,this.playing=!0,!this.started){this.started=!0;let i=this.startedCallbacks.slice();this.startedCallbacks=[];for(let p of i)p()}s.onended=()=>{let i=this.activeSources.indexOf(s);i!==-1&&this.activeSources.splice(i,1),this.pendingCount--,this.checkFinished()}}checkFinished(){if(this.streamEnded&&this.pendingCount<=0&&this.pendingBuffers.length===0){this.playing=!1,this.streamEnded=!1;let e=this.finishedCallbacks.slice();this.finishedCallbacks=[];for(let t of e)t()}}pcmToFloat32(e){let t=Math.floor(e.length/2),r=new Float32Array(t),s=new DataView(e.buffer,e.byteOffset,e.byteLength);for(let a=0;a<t;a++){let i=s.getInt16(a*2,!0);r[a]=i/32768}return r}};function E(o){return o.replace(/\/+$/,"")}var g=class{constructor(e){this.opts=e;this.id="runtype-tts";this.supportsPause=!0;this.player=null;this.playerPromise=null;this.generation=0}ensurePlayer(){var e,t;return(t=this.playerPromise)!=null?t:this.playerPromise=Promise.resolve(this.opts.createPlaybackEngine?this.opts.createPlaybackEngine():new m(24e3,{prebufferMs:(e=this.opts.prebufferMs)!=null?e:200})).then(r=>this.player=r)}speak(e,t){let r=++this.generation;this.run(r,e,t)}async run(e,t,r){var s,a,i,p;try{let h=await this.ensurePlayer();if(e!==this.generation)return;h.flush(),h.resume(),h.onStarted(()=>{var n;e===this.generation&&((n=r.onStart)==null||n.call(r))}),h.onFinished(()=>{var n;e===this.generation&&((n=r.onEnd)==null||n.call(r))});let l=`${E(this.opts.host)}/v1/agents/${encodeURIComponent(this.opts.agentId)}/speak`,f=await fetch(l,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.opts.clientToken}`},body:JSON.stringify({text:t.text,voice:(s=t.voice)!=null?s:this.opts.voice,format:"pcm"})});if(e!==this.generation)return;if(!f.ok||!f.body)throw new Error(await x(f));let u=f.body.getReader();for(;;){let{done:n,value:d}=await u.read();if(e!==this.generation){await u.cancel().catch(()=>{});return}if(n)break;d&&d.byteLength>0&&h.enqueue(d)}h.markStreamEnd()}catch(h){if(e!==this.generation)return;let l=h instanceof Error?h:new Error(String(h));(i=(a=this.opts).onError)==null||i.call(a,l),(p=r.onError)==null||p.call(r,l)}}pause(){var e;(e=this.player)==null||e.pause()}resume(){var e;(e=this.player)==null||e.resume()}stop(){var e;this.generation++,(e=this.player)==null||e.flush()}destroy(){var e;this.generation++,(e=this.player)==null||e.destroy(),this.player=null,this.playerPromise=null}};async function x(o){var e,t;try{let r=await o.json();return r.detail?`${(e=r.error)!=null?e:`Runtype TTS ${o.status}`}: ${r.detail}`:(t=r.error)!=null?t:`Runtype TTS request failed (${o.status})`}catch{return`Runtype TTS request failed (${o.status})`}}var S=class{constructor(e,t,r={}){this.primary=e;this.fallback=t;this.options=r;this.id="fallback";this.active=e}get supportsPause(){return this.active.supportsPause}speak(e,t){this.active=this.primary;let r=!1;this.primary.speak(e,{onStart:()=>{var s;r=!0,(s=t.onStart)==null||s.call(t)},onEnd:()=>{var s;return(s=t.onEnd)==null?void 0:s.call(t)},onError:s=>{var a,i,p;if(r){(a=t.onError)==null||a.call(t,s);return}(p=(i=this.options).onFallback)==null||p.call(i,s),this.active=this.fallback,this.fallback.speak(e,t)}})}pause(){this.active.pause()}resume(){this.active.resume()}stop(){this.active.stop()}destroy(){var e,t,r,s;(t=(e=this.primary).destroy)==null||t.call(e),(s=(r=this.fallback).destroy)==null||s.call(r)}};export{S as FallbackSpeechEngine,g as RuntypeSpeechEngine,v as createPcmStreamPlayer,w as createWorkletPlaybackEngine};

package/dist/widget.css

@@ -1027,7 +1027,7 @@
   opacity: 1;
 }
 
-/* Hide tooltips on touch devices — hover doesn't exist, and they cause clipping issues */
+/* Hide tooltips on touch devices: hover doesn't exist, and they cause clipping issues */
 @media (hover: none), (max-width: 500px) {
   .persona-send-button-wrapper:hover .persona-send-button-tooltip,
   .persona-send-button-wrapper:focus-within .persona-send-button-tooltip {
@@ -1144,7 +1144,7 @@
   animation: persona-voice-processing-spin 1.2s linear infinite;
 }
 
-/* Voice speaking animation (gentle pulse — slower/subtler than recording) */
+/* Voice speaking animation (gentle pulse: slower/subtler than recording) */
 @keyframes persona-voice-speaking-pulse {
   0%, 100% { opacity: 1; transform: scale(1); }
   50% { opacity: 0.85; transform: scale(1.03); }
@@ -1759,7 +1759,7 @@
   animation: persona-message-actions-fade-in 0.3s ease-out forwards;
 }
 
-/* ask_user_question — collapsed answered state.
+/* ask_user_question: collapsed answered state.
  * When the user picks an option, the interactive card is replaced with a
  * plain assistant bubble showing the question text. A short fade + slight
  * upward slide sells the "card resolved into history" feel.
@@ -1948,6 +1948,18 @@
   opacity: 0.9;
 }
 
+/* Read-aloud loading state: spin the loader icon while audio is prepared
+   (near-instant for browser TTS; visible for a hosted/server engine fetch). */
+.persona-message-action-btn.persona-message-action-loading svg {
+  animation: persona-voice-processing-spin 1s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .persona-message-action-btn.persona-message-action-loading svg {
+    animation: none;
+  }
+}
+
 /* Vote pop animation */
 @keyframes persona-vote-pop {
   0% { transform: scale(1); }
@@ -2228,7 +2240,7 @@
   background-color: var(--cw-container, #f8fafc);
 }
 
-/* Collapsed live preview blocks — match expanded content's 1px border-top with transparent border */
+/* Collapsed live preview blocks: match expanded content's 1px border-top with transparent border */
 [data-persona-root] [data-persona-collapsed-preview] {
   border-top: 1px solid transparent;
 }
@@ -2380,7 +2392,7 @@
 }
 
 /* ============================================
-   Visibility (Tailwind parity — prefix persona-)
+   Visibility (Tailwind parity: prefix persona-)
    Shipped widget.css is hand-maintained; these utilities are used in TS but not generated by Tailwind at build time.
    ============================================ */
 [data-persona-root] .persona-hidden {
@@ -2402,7 +2414,7 @@
   gap: var(--persona-artifact-split-gap, 0.5rem);
 }
 
-/* Document toolbar preset — optional layout vars: --persona-artifact-doc-toolbar-icon-color, etc. */
+/* Document toolbar preset: optional layout vars: --persona-artifact-doc-toolbar-icon-color, etc. */
 [data-persona-root] .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn {
   display: inline-flex;
   align-items: center;
@@ -2495,7 +2507,7 @@
 
 /* ── Composable button utilities ── */
 
-/* Icon button — base for all icon-only buttons created by createIconButton() */
+/* Icon button: base for all icon-only buttons created by createIconButton() */
 [data-persona-root] .persona-icon-btn {
   display: inline-flex;
   align-items: center;
@@ -2525,7 +2537,7 @@
   border-color: var(--persona-icon-btn-active-border, var(--persona-border, #e5e7eb));
 }
 
-/* Label button — icon + text button created by createLabelButton() */
+/* Label button: icon + text button created by createLabelButton() */
 [data-persona-root] .persona-label-btn {
   display: inline-flex;
   align-items: center;
@@ -2644,7 +2656,7 @@
   outline-offset: 2px;
 }
 
-/* Toggle group — mutually exclusive button set created by createToggleGroup() */
+/* Toggle group: mutually exclusive button set created by createToggleGroup() */
 [data-persona-root] .persona-toggle-group {
   display: inline-flex;
   gap: var(--persona-toggle-group-gap, 0);
@@ -2664,7 +2676,7 @@
   border-bottom-right-radius: var(--persona-toggle-group-radius, var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem)));
 }
 
-/* Combo button — label + chevron with dropdown */
+/* Combo button: label + chevron with dropdown */
 [data-persona-root] .persona-combo-btn {
   font-size: var(--persona-combo-btn-font-size, 0.8125rem);
   font-weight: var(--persona-combo-btn-font-weight, 600);
@@ -2758,7 +2770,7 @@
   }
 }
 
-/* paneBorderRadius — works on any paneAppearance; overflow clips content to rounded shape */
+/* paneBorderRadius: works on any paneAppearance; overflow clips content to rounded shape */
 [data-persona-root] .persona-artifact-pane {
   border-radius: var(--persona-artifact-pane-radius, 0);
   overflow: hidden;
@@ -2769,7 +2781,7 @@
   );
 }
 
-/* paneAppearance: 'seamless' — flush with chat, no border/shadow/gap */
+/* paneAppearance: 'seamless': flush with chat, no border/shadow/gap */
 /* `position: relative` for resizer overlay; gap 0; positioning is applied in ui.ts */
 [data-persona-root].persona-artifact-appearance-seamless .persona-artifact-split-root {
   position: relative;
@@ -2787,7 +2799,7 @@
   );
 }
 
-/* layout.paneBorder / paneBorderLeft — theme overrides (after appearance defaults) */
+/* layout.paneBorder / paneBorderLeft: theme overrides (after appearance defaults) */
 [data-persona-root].persona-artifact-border-full .persona-artifact-pane {
   border: var(--persona-artifact-pane-border) !important;
 }
@@ -2869,7 +2881,7 @@
 }
 
 /* ============================================================
-   Stream animations — reveal effects for assistant message text
+   Stream animations: reveal effects for assistant message text
    while streaming. Opt-in via `features.streamAnimation.type`.
    Units are staggered via `--char-index` / `--word-index`
    (set inline on each wrapper span). Timing is configured via
@@ -2879,7 +2891,7 @@
 
 /* Per-char/per-word spans need to be inline-block so `transform` works for
    the rise/fade animations. Each span animates from the moment it is first
-   added to the DOM — streaming itself provides the visible stagger, so the
+   added to the DOM: streaming itself provides the visible stagger, so the
    CSS animation has no per-index delay. An index-based delay would compound
    with the stream's arrival cadence and leave later chars permanently hidden. */
 [data-persona-root] .persona-stream-char,
@@ -2925,7 +2937,7 @@
     ease-out both;
 }
 
-/* The following animations live in subpath plugin modules — their CSS is
+/* The following animations live in subpath plugin modules: their CSS is
    injected by the plugin when activated, not by the core stylesheet:
    - `wipe`        → @runtypelabs/persona/animations/wipe
    - `glyph-cycle` → @runtypelabs/persona/animations/glyph-cycle */
@@ -2955,6 +2967,13 @@
   animation: persona-stream-blink 1s steps(1) infinite;
 }
 
+/* ---------- inline timestamp (trails the last line of message text) ---------- */
+[data-persona-root] .persona-timestamp-inline {
+  display: inline-block;
+  margin-left: 0.5rem;
+  white-space: nowrap;
+}
+
 /* ---------- skeleton placeholder (pre-first-token) ---------- */
 @keyframes persona-stream-skeleton-shimmer {
   0%   { background-position: 200% 0; }
@@ -3002,7 +3021,7 @@
 }
 
 /* ========================================================================
- * ask_user_question — built-in answer-pill sheet
+ * ask_user_question: built-in answer-pill sheet
  * Slides in over the composer when the assistant invokes `ask_user_question`.
  * Overridable via `config.features.askUserQuestion.styles`.
  * ======================================================================== */
@@ -3011,7 +3030,7 @@
   display: none !important;
 }
 
-/* In-transcript stub — small "Awaiting…" chip. */
+/* In-transcript stub: small "Awaiting…" chip. */
 [data-persona-root] .persona-ask-stub {
   padding: 0.35rem 0.7rem;
   border-radius: 999px;
@@ -3025,7 +3044,7 @@
   font-weight: 500;
 }
 
-/* Sheet container — absolute inside composerOverlay. */
+/* Sheet container: absolute inside composerOverlay. */
 [data-persona-root] .persona-ask-sheet {
   position: absolute;
   left: 0.75rem;
@@ -3053,7 +3072,7 @@
   pointer-events: none;
 }
 
-/* Header row — question + close button */
+/* Header row: question + close button */
 [data-persona-root] .persona-ask-sheet-header {
   margin-bottom: 0.55rem;
 }
@@ -3094,7 +3113,7 @@
   display: none;
 }
 
-/* Option list — stacked one per row by default ("rows" layout). The "pills"
+/* Option list: stacked one per row by default ("rows" layout). The "pills"
    layout opt-in switches to horizontal wrap with compact pills; see also
    horizontalPillsAskPlugin example for a custom variant. */
 [data-persona-root] .persona-ask-pills {
@@ -3111,7 +3130,7 @@
   gap: 0.4rem;
 }
 
-/* Pills layout opt-in — horizontal wrap, auto-width compact pills. */
+/* Pills layout opt-in: horizontal wrap, auto-width compact pills. */
 [data-persona-root] .persona-ask-sheet--pills .persona-ask-pills:not(.persona-ask-pills--rows) {
   flex-direction: row;
   flex-wrap: wrap;
@@ -3188,7 +3207,7 @@
   100% { background-position: -100% 50%; }
 }
 
-/* Row layout — full-width stacked rows with always-visible description
+/* Row layout: full-width stacked rows with always-visible description
    and a right-edge affordance (number badge for single-select, check for
    multi-select). Layered on top of .persona-ask-pill base styles. */
 [data-persona-root] .persona-ask-row {
@@ -3291,7 +3310,7 @@
   height: 3rem;
 }
 
-/* Other row (rows mode) — composite row that contains the free-text input
+/* Other row (rows mode): composite row that contains the free-text input
  * directly. The input fills the row body; the badge sits on the right. */
 [data-persona-root] .persona-ask-row--other {
   cursor: text;
@@ -3358,7 +3377,7 @@
   cursor: not-allowed;
 }
 
-/* Nav row — Back / Skip / Next-or-Submit buttons for grouped payloads. */
+/* Nav row: Back / Skip / Next-or-Submit buttons for grouped payloads. */
 [data-persona-root] .persona-ask-nav-back,
 [data-persona-root] .persona-ask-nav-skip {
   padding: 0.45rem 0.85rem;
@@ -3416,11 +3435,11 @@
  * `applyComposerBarGeometry()` in ui.ts. The pill composer
  * (`pill-composer-builder.ts`) ships with its own clean className
  * (`persona-pill-composer`, no `persona-flex-col` / `persona-rounded-2xl`
- * baggage), so layout CSS does not need to fight utility classes — no
+ * baggage), so layout CSS does not need to fight utility classes: no
  * !important. The pill is the visible element in both collapsed and
  * expanded states; only the panel above it appears/disappears.
  *
- * Avoid `transform: scale(...)` on the wrapper — it breaks the textarea
+ * Avoid `transform: scale(...)` on the wrapper: it breaks the textarea
  * caret/IME.
  * ======================================================================= */
 .persona-widget-wrapper[data-persona-composer-bar] {
@@ -3446,14 +3465,14 @@
  * so `top/left/transform` resolve to their auto/none defaults) to its
  * expanded position. The default `transform 220ms ease` transition would
  * interpolate `none → translate(...)` and visibly slide the wrapper from
- * its static-default origin toward its target — diagonally for modal,
+ * its static-default origin toward its target: diagonally for modal,
  * horizontally from the right for anchored. Neither mode is morphing
  * something the user can see (the wrapper is invisible when collapsed
  * because the pill lives in pillRoot, not the wrapper), so the slide
  * is pure motion noise. Disable geometry transitions for both; the
  * container's opacity fade-in keyframe is the reveal.
  *
- * Fullscreen intentionally keeps its geometry transition — that's the
+ * Fullscreen intentionally keeps its geometry transition: that's the
  * one mode where the wrapper genuinely morphs (empty → full viewport),
  * and the staggered fade-in cascade below is built to mask the
  * outer-edge/inner-content desync during that morph. */
@@ -3489,7 +3508,7 @@
   padding: 4px 0;
 }
 
-/* Responsive default width for the collapsed pill — applied only when
+/* Responsive default width for the collapsed pill: applied only when
  * `applyComposerBarGeometry()` leaves the wrapper's inline width empty
  * (i.e., the user did NOT set `composerBar.collapsedMaxWidth`). Inline
  * width from a user config still wins via specificity (inline > class). */
@@ -3543,8 +3562,7 @@
  * In composer-bar mode the pill (`footer`) and peek banner live in a
  * viewport-fixed sibling of the wrapper, NOT inside the wrapper. Reason:
  * modal mode applies `transform: translate(-50%, -50%)` to the wrapper,
- * which establishes a containing block for `position: fixed` descendants —
- * a fixed pill inside a transformed wrapper would be positioned relative
+ * which establishes a containing block for `position: fixed` descendants: * a fixed pill inside a transformed wrapper would be positioned relative
  * to the wrapper, not the viewport.
  *
  * Bottom offset and (optionally) width are written inline by ui.ts based
@@ -3574,7 +3592,7 @@
   }
 }
 
-/* Container hidden when the chat is collapsed — only the pill is visible. */
+/* Container hidden when the chat is collapsed: only the pill is visible. */
 [data-persona-composer-bar][data-state="collapsed"] .persona-widget-container {
   display: none;
 }
@@ -3614,7 +3632,7 @@
     transform 150ms ease,
     background-color 150ms ease;
   text-align: left;
-  /* Full-width row that matches the pill below — text takes the middle
+  /* Full-width row that matches the pill below: text takes the middle
    * (flex: 1 1 auto) and the chevron pins to the right edge. */
   width: 100%;
   align-self: stretch;
@@ -3700,7 +3718,7 @@
  * (including the area behind the fixed pill) so messages scroll under the
  * pill. The body itself drops its bottom padding so its background extends
  * to the viewport edge; reachability for the last bubble comes from
- * padding-bottom on the messages wrapper (body's last child) — that
+ * padding-bottom on the messages wrapper (body's last child): that
  * pushes the final message above the pill area rather than hiding it
  * behind. */
 .persona-widget-wrapper[data-persona-composer-bar][data-expanded-size="fullscreen"] .persona-widget-body {
@@ -3726,7 +3744,7 @@
  *   so the box appears to materialize as it grows rather than snap into
  *   existence at frame 0.
  * - Body content (intro card, messages, composer overlay) fades in AFTER
- *   the geometry has settled — `animation-delay: 220ms` plus
+ *   the geometry has settled: `animation-delay: 220ms` plus
  *   `animation-fill-mode: both` keeps it at opacity 0 during the morph.
  *
  * Because `[data-state="collapsed"] .persona-widget-container { display: