@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/dist/Chat/useChatComposerTokens.js

@@ -0,0 +1,229 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useChatComposerTokens.ts
+ * @input Uses React refs, state, DOM APIs
+ * @output Exports useChatComposerTokens hook for inline token management
+ * @position Utility hook — extracted from ChatComposerInput
+ *
+ * Manages inline token chips in a contentEditable element:
+ * - Insert tokens (badge or custom render) at cursor position
+ * - Backspace handling near tokens (removes token + trailing NBSP)
+ * - Paste handling near tokens (prevents broken state)
+ * - Portal tracking for React rendering inside DOM-created spans
+ * - Serialization awareness (data-astryx-token attributes)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /packages/core/src/Chat/ChatComposerInput.tsx (consumer)
+ */
+import { useCallback, useState } from 'react';
+import { ensureCaretInside, insertTextAtCursor } from "./chatComposerSelection.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Type guard: does this token use the custom render path? */
+export function isCustomToken(token) {
+  return 'render' in token && typeof token.render === 'function';
+}
+
+/** Check if a node is inside or is a token span. */
+function isInsideToken(node) {
+  let current = node;
+  while (current) {
+    if (current instanceof HTMLElement && current.hasAttribute('data-astryx-token')) {
+      return current;
+    }
+    current = current.parentNode;
+  }
+  return null;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useChatComposerTokens({
+  editableRef,
+  onEmitChange
+}) {
+  const [tokenPortals, setTokenPortals] = useState([]);
+
+  // --- Insert token at cursor ---
+  const insertToken = useCallback(token => {
+    const editable = editableRef.current;
+    if (!editable) {
+      return;
+    }
+
+    // Place a caret at the end of the editable if there's no Range
+    // inside it (programmatic focus does not create one).
+    const selection = ensureCaretInside(editable);
+    if (!selection || selection.rangeCount === 0) {
+      return;
+    }
+    const range = selection.getRangeAt(0);
+
+    // Create a non-editable container — React will portal the Badge into it
+    const span = document.createElement('span');
+    const id = `token-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    span.setAttribute('data-astryx-token', '');
+    span.setAttribute('data-astryx-token-value', token.value);
+    span.setAttribute('data-astryx-token-id', id);
+    span.contentEditable = 'false';
+    span.style.display = 'inline-flex';
+    span.style.verticalAlign = 'baseline';
+    range.deleteContents();
+    range.insertNode(span);
+
+    // Add a non-breaking space after the token and move cursor there
+    const space = document.createTextNode('\u00A0');
+    span.after(space);
+    const newRange = document.createRange();
+    newRange.setStartAfter(space);
+    newRange.collapse(true);
+    selection.removeAllRanges();
+    selection.addRange(newRange);
+
+    // Register for portal rendering
+    setTokenPortals(prev => [...prev, {
+      id,
+      span,
+      token
+    }]);
+    return id;
+  }, [editableRef]);
+
+  // --- Backspace near tokens ---
+  const handleKeyDown = useCallback(e => {
+    if (e.key !== 'Backspace') {
+      return false;
+    }
+    const selection = window.getSelection();
+    if (!selection || !selection.isCollapsed || selection.rangeCount === 0) {
+      return false;
+    }
+    const range = selection.getRangeAt(0);
+    const {
+      startContainer,
+      startOffset
+    } = range;
+
+    // Case 1: Cursor at start of text node right after a token —
+    // let the browser handle it (it will select/delete the token)
+    if (startContainer.nodeType === Node.TEXT_NODE && startOffset === 0 && startContainer.previousSibling instanceof HTMLElement && startContainer.previousSibling.hasAttribute('data-astryx-token')) {
+      return false;
+    }
+
+    // Case 2: Cursor in or after the trailing NBSP — remove both
+    // the NBSP and the token in one action
+    if (startContainer.nodeType === Node.TEXT_NODE && startContainer.textContent === '\u00A0' && startOffset <= 1 && startContainer.previousSibling instanceof HTMLElement && startContainer.previousSibling.hasAttribute('data-astryx-token')) {
+      e.preventDefault();
+      const tokenSpan = startContainer.previousSibling;
+      const parent = startContainer.parentNode;
+      if (parent) {
+        parent.removeChild(startContainer);
+        parent.removeChild(tokenSpan);
+      }
+      onEmitChange();
+      return true;
+    }
+    return false;
+  }, [onEmitChange]);
+
+  // --- Paste near tokens ---
+  const handlePaste = useCallback(e => {
+    const editable = editableRef.current;
+    if (!editable) {
+      return false;
+    }
+    const selection = ensureCaretInside(editable);
+    if (!selection || selection.rangeCount === 0) {
+      return false;
+    }
+    const range = selection.getRangeAt(0);
+
+    // If selection overlaps a token, collapse to after the token
+    // and insert there instead of breaking the token
+    const tokenEl = isInsideToken(range.startContainer);
+    if (tokenEl) {
+      e.preventDefault();
+      const text = e.clipboardData.getData('text/plain');
+
+      // Move cursor after the token's trailing space
+      const space = tokenEl.nextSibling;
+      const newRange = document.createRange();
+      if (space && space.nodeType === Node.TEXT_NODE) {
+        newRange.setStartAfter(space);
+      } else {
+        newRange.setStartAfter(tokenEl);
+      }
+      newRange.collapse(true);
+      selection.removeAllRanges();
+      selection.addRange(newRange);
+      insertTextAtCursor(editable, text);
+      onEmitChange();
+      return true;
+    }
+    return false;
+  }, [editableRef, onEmitChange]);
+
+  // --- Expand token (replace with text) ---
+  const expandToken = useCallback(id => {
+    const editable = editableRef.current;
+    if (!editable) {
+      return;
+    }
+    const portal = tokenPortals.find(p => p.id === id);
+    if (!portal) {
+      return;
+    }
+    const {
+      span
+    } = portal;
+    const value = span.getAttribute('data-astryx-token-value') ?? '';
+    const textNode = document.createTextNode(value);
+
+    // Remove the trailing NBSP if present
+    const next = span.nextSibling;
+    if (next?.nodeType === Node.TEXT_NODE && next.textContent === '\u00A0') {
+      next.remove();
+    }
+    span.replaceWith(textNode);
+
+    // Place cursor at end of inserted text
+    const selection = window.getSelection();
+    if (selection) {
+      const range = document.createRange();
+      range.setStartAfter(textNode);
+      range.collapse(true);
+      selection.removeAllRanges();
+      selection.addRange(range);
+    }
+
+    // Remove from portals
+    setTokenPortals(prev => prev.filter(p => p.id !== id));
+    onEmitChange();
+  }, [editableRef, tokenPortals, onEmitChange]);
+
+  // --- Cleanup orphaned portals ---
+  const cleanupPortals = useCallback(() => {
+    setTokenPortals(prev => prev.filter(p => editableRef.current?.contains(p.span)));
+  }, [editableRef]);
+  return {
+    tokenPortals,
+    expandToken,
+    insertToken,
+    handleKeyDown,
+    handlePaste,
+    cleanupPortals
+  };
+}

package/dist/Chat/useChatDictation.d.ts

@@ -0,0 +1,56 @@
+import type { ChatComposerInputHandle } from './ChatComposerInput';
+export interface UseChatDictationOptions {
+    /** BCP-47 language tag. @default navigator.language */
+    lang?: string;
+    /** Whether recognition continues until explicitly stopped. @default true */
+    continuous?: boolean;
+    /** Whether interim results are reported. @default true */
+    interimResults?: boolean;
+    /** Transform transcript text before it's reported. Applied before CAPS LOCK. */
+    transformTranscript?: (transcript: string) => string;
+    /** Called on each transcript result (interim or final). */
+    onTranscript?: (transcript: string, isFinal: boolean) => void;
+    /** Called when a final result is produced. */
+    onResult?: (transcript: string) => void;
+    /** Called when a recognition error occurs. */
+    onError?: (error: {
+        error: string;
+        message?: string;
+    }) => void;
+    /** Called when recognition starts. */
+    onStart?: () => void;
+    /** Called when recognition ends. */
+    onEnd?: () => void;
+    /** Play subtle audio cues on start/stop. @default false */
+    hasSounds?: boolean;
+    /** Shared AudioContext — uses an internal lazy singleton by default. */
+    audioContext?: AudioContext;
+    /** Ref to ChatComposerInput. If provided, manages interim ghost text in the input. */
+    inputRef?: React.RefObject<ChatComposerInputHandle | null>;
+}
+export interface UseChatDictationReturn {
+    /** Whether the browser supports SpeechRecognition. */
+    isSupported: boolean;
+    /** Whether recognition is currently active. */
+    isListening: boolean;
+    /** Whether speech is currently being detected. */
+    isSpeaking: boolean;
+    /** Real-time microphone volume level, 0 to 1. Updates ~60fps while listening. */
+    volume: number;
+    /** Frequency band levels (low to high), each 0-1. Updates ~60fps while listening. */
+    bands: number[];
+    /** Raw (uncalibrated) band levels for debugging. */
+    rawBands: number[];
+    /** The current interim transcript text. */
+    interimTranscript: string;
+    /** Start speech recognition. */
+    start: () => void;
+    /** Stop speech recognition gracefully (waits for final result). */
+    stop: () => void;
+    /** Abort speech recognition immediately. */
+    abort: () => void;
+    /** Toggle between start and stop. */
+    toggle: () => void;
+}
+export declare function useChatDictation(options?: UseChatDictationOptions): UseChatDictationReturn;
+//# sourceMappingURL=useChatDictation.d.ts.map

package/dist/Chat/useChatDictation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatDictation.d.ts","sourceRoot":"","sources":["../../src/Chat/useChatDictation.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAOjE,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD,2DAA2D;IAC3D,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IAC7D,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wEAAwE;IACxE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,WAAW,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,mEAAmE;IACnE,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,qCAAqC;IACrC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAgMD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CA4NxB"}

package/dist/Chat/useChatDictation.js

@@ -0,0 +1,380 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useChatDictation.ts
+ * @input Uses useSpeechRecognition, AudioContext, ChatComposerInputHandle
+ * @output Exports useChatDictation — full dictation hook for ChatComposer
+ * @position Utility hook — the ONE hook consumers call for voice-to-text input
+ *
+ * Wraps useSpeechRecognition and adds AudioContext (volume, frequency bands,
+ * noise floor calibration), audio feedback sounds, CAPS LOCK (sustained volume
+ * → uppercase), and optional interim text DOM management for ChatComposerInput.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { useSpeechRecognition } from "./useSpeechRecognition.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+// =============================================================================
+// Volume analyser
+// =============================================================================
+
+async function createVolumeAnalyser(getCtx) {
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: true
+    });
+    const audioContext = getCtx();
+    const source = audioContext.createMediaStreamSource(stream);
+    const analyser = audioContext.createAnalyser();
+    analyser.fftSize = 256;
+    analyser.smoothingTimeConstant = 0.5;
+    source.connect(analyser);
+    const dataArray = new Uint8Array(analyser.frequencyBinCount);
+    const noiseFloor = new Float32Array(analyser.frequencyBinCount);
+    let calibrationSamples = 0;
+    const CALIBRATION_FRAMES = 60;
+    function calibrate() {
+      analyser.getByteFrequencyData(dataArray);
+      calibrationSamples++;
+      for (let i = 0; i < dataArray.length; i++) {
+        const val = dataArray[i] / 255;
+        if (val > noiseFloor[i]) {
+          noiseFloor[i] = val;
+        }
+      }
+    }
+    function getCleanBin(i) {
+      const raw = dataArray[i] / 255;
+      if (calibrationSamples < CALIBRATION_FRAMES) {
+        return 0;
+      }
+      return Math.max(0, raw - noiseFloor[i] * 1.1);
+    }
+    return {
+      calibrate,
+      getVolume: () => {
+        analyser.getByteFrequencyData(dataArray);
+        if (calibrationSamples < CALIBRATION_FRAMES) {
+          calibrate();
+        }
+        let sum = 0;
+        for (let i = 0; i < dataArray.length; i++) {
+          sum += getCleanBin(i);
+        }
+        return sum / dataArray.length;
+      },
+      getBands: count => {
+        analyser.getByteFrequencyData(dataArray);
+        if (calibrationSamples < CALIBRATION_FRAMES) {
+          calibrate();
+        }
+        const bands = [];
+        const binCount = dataArray.length;
+        const voiceSplits = [3, 6, 11, 18, binCount];
+        const splits = count <= voiceSplits.length ? voiceSplits.slice(0, count) : voiceSplits;
+        let start = 1;
+        for (let b = 0; b < splits.length; b++) {
+          const end = splits[b];
+          let sum = 0;
+          for (let i = start; i < end; i++) {
+            sum += getCleanBin(i);
+          }
+          bands.push(sum / (end - start));
+          start = end;
+        }
+        return bands;
+      },
+      getRawBands: count => {
+        analyser.getByteFrequencyData(dataArray);
+        const bands = [];
+        const binCount = dataArray.length;
+        const voiceSplits = [3, 6, 11, 18, binCount];
+        const splits = count <= voiceSplits.length ? voiceSplits.slice(0, count) : voiceSplits;
+        let start = 1;
+        for (let b = 0; b < splits.length; b++) {
+          const end = splits[b];
+          let sum = 0;
+          for (let i = start; i < end; i++) {
+            sum += dataArray[i] / 255;
+          }
+          bands.push(sum / (end - start));
+          start = end;
+        }
+        return bands;
+      },
+      cleanup: () => {
+        source.disconnect();
+        for (const track of stream.getTracks()) {
+          track.stop();
+        }
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// Audio feedback
+// =============================================================================
+
+let _sharedAudioCtx = null;
+function getDefaultAudioContext() {
+  if (!_sharedAudioCtx || _sharedAudioCtx.state === 'closed') {
+    _sharedAudioCtx = new AudioContext();
+  }
+  if (_sharedAudioCtx.state === 'suspended') {
+    void _sharedAudioCtx.resume();
+  }
+  return _sharedAudioCtx;
+}
+const isIOS = typeof navigator !== 'undefined' && /iPad|iPhone|iPod/.test(navigator.userAgent);
+function playPlop(freq, delay, getCtx, volume = 0.25) {
+  try {
+    const ctx = getCtx();
+    const now = ctx.currentTime;
+    const dur = freq < 200 ? 0.18 : 0.06;
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    osc.type = 'sine';
+    osc.frequency.setValueAtTime(freq * 1.3, now + delay);
+    osc.frequency.exponentialRampToValueAtTime(freq, now + delay + 0.01);
+    osc.frequency.exponentialRampToValueAtTime(freq * 0.93, now + delay + dur);
+    gain.gain.setValueAtTime(0.001, now);
+    gain.gain.setValueAtTime(volume, now + delay);
+    gain.gain.exponentialRampToValueAtTime(volume * 0.2, now + delay + dur * 0.12);
+    gain.gain.exponentialRampToValueAtTime(0.001, now + delay + dur);
+    osc.connect(gain);
+    gain.connect(ctx.destination);
+    osc.start(now + delay);
+    osc.stop(now + delay + dur);
+  } catch {
+    // Audio playback is best-effort
+  }
+}
+function playStartSound(getCtx) {
+  if (isIOS) {
+    return;
+  }
+  playPlop(392, 0, getCtx);
+  playPlop(523, 0.07, getCtx);
+}
+function playStopSound(getCtx) {
+  if (isIOS) {
+    return;
+  }
+  playPlop(523, 0, getCtx);
+  playPlop(392, 0.07, getCtx);
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useChatDictation(options = {}) {
+  const {
+    lang,
+    continuous,
+    interimResults,
+    transformTranscript: userTransform,
+    onTranscript: onTranscriptProp,
+    onResult: onResultProp,
+    onError,
+    onStart: onStartProp,
+    onEnd: onEndProp,
+    hasSounds = false,
+    audioContext: externalAudioContext,
+    inputRef
+  } = options;
+  const getAudioContext = useCallback(() => externalAudioContext ?? getDefaultAudioContext(), [externalAudioContext]);
+  const [volume, setVolume] = useState(0);
+  const [bands, setBands] = useState([0, 0, 0, 0, 0]);
+  const [rawBands, setRawBands] = useState([0, 0, 0, 0, 0]);
+  const volumeHistoryRef = useRef([]);
+  const getAudioContextRef = useRef(getAudioContext);
+  getAudioContextRef.current = getAudioContext;
+  const analyserRef = useRef(null);
+  const rafRef = useRef(0);
+  const interimSpanRef = useRef(null);
+  const callbacksRef = useRef({
+    onTranscriptProp,
+    onResultProp,
+    onStartProp,
+    onEndProp
+  });
+  callbacksRef.current = {
+    onTranscriptProp,
+    onResultProp,
+    onStartProp,
+    onEndProp
+  };
+  const startVolumePolling = useCallback(() => {
+    const poll = () => {
+      const analyser = analyserRef.current;
+      if (analyser) {
+        const vol = analyser.getVolume();
+        setVolume(vol);
+        const hist = volumeHistoryRef.current;
+        hist.push(vol);
+        if (hist.length > 30) {
+          hist.shift();
+        }
+        setBands(analyser.getBands(5));
+        setRawBands(analyser.getRawBands(5));
+      }
+      rafRef.current = requestAnimationFrame(poll);
+    };
+    rafRef.current = requestAnimationFrame(poll);
+  }, []);
+  const stopVolumePolling = useCallback(() => {
+    cancelAnimationFrame(rafRef.current);
+    setVolume(0);
+    setBands([0, 0, 0, 0, 0]);
+    setRawBands([0, 0, 0, 0, 0]);
+    volumeHistoryRef.current = [];
+    analyserRef.current?.cleanup();
+    analyserRef.current = null;
+  }, []);
+  const getEditable = useCallback(() => {
+    const active = document.activeElement;
+    if (active?.getAttribute('contenteditable') === 'true') {
+      return active;
+    }
+    return document.querySelector('.astryx-chat-composer-input [contenteditable="true"], [role="textbox"][contenteditable="true"]');
+  }, []);
+  const insertInterimSpan = useCallback(() => {
+    const editable = getEditable();
+    if (!editable) {
+      return;
+    }
+    const span = document.createElement('span');
+    span.setAttribute('data-astryx-dictation-interim', '');
+    span.contentEditable = 'false';
+    span.style.color = 'var(--color-text-disabled, #999)';
+    span.style.fontStyle = 'italic';
+    span.style.opacity = '0.7';
+    span.style.pointerEvents = 'none';
+    editable.appendChild(span);
+    interimSpanRef.current = span;
+    editable.dispatchEvent(new Event('input', {
+      bubbles: true
+    }));
+  }, [getEditable]);
+  const removeInterimSpan = useCallback(() => {
+    const span = interimSpanRef.current;
+    if (span?.isConnected) {
+      try {
+        span.remove();
+      } catch {
+        /* Already removed */
+      }
+    }
+    interimSpanRef.current = null;
+  }, []);
+  const transformTranscript = useCallback(text => {
+    let t = text;
+    if (userTransform) {
+      t = userTransform(t);
+    }
+    const hist = volumeHistoryRef.current;
+    const avgVolume = hist.length > 0 ? hist.reduce((a, b) => a + b, 0) / hist.length : 0;
+    if (avgVolume >= 0.15 && hist.length >= 10) {
+      t = t.toUpperCase();
+    }
+    return t;
+  }, [userTransform]);
+  useEffect(() => {
+    return () => {
+      analyserRef.current?.cleanup();
+      analyserRef.current = null;
+      cancelAnimationFrame(rafRef.current);
+    };
+  }, []);
+  const speech = useSpeechRecognition({
+    lang,
+    continuous,
+    interimResults,
+    transformTranscript,
+    onTranscript: (transcript, isFinal) => {
+      if (inputRef) {
+        if (isFinal) {
+          removeInterimSpan();
+          const handle = inputRef.current;
+          if (handle) {
+            handle.focus();
+            handle.insertText(transcript + ' ');
+          }
+          callbacksRef.current.onResultProp?.(transcript);
+          insertInterimSpan();
+        } else {
+          const span = interimSpanRef.current;
+          if (span) {
+            span.textContent = transcript;
+          } else {
+            insertInterimSpan();
+            if (interimSpanRef.current) {
+              interimSpanRef.current.textContent = transcript;
+            }
+          }
+        }
+      }
+      callbacksRef.current.onTranscriptProp?.(transcript, isFinal);
+    },
+    onResult: inputRef ? undefined : onResultProp,
+    onError,
+    onStart: () => {
+      if (hasSounds) {
+        playStartSound(getAudioContextRef.current);
+      }
+      void createVolumeAnalyser(getAudioContextRef.current).then(analyser => {
+        if (analyser) {
+          analyserRef.current = analyser;
+          startVolumePolling();
+        }
+      });
+      if (inputRef) {
+        insertInterimSpan();
+      }
+      callbacksRef.current.onStartProp?.();
+    },
+    onEnd: () => {
+      stopVolumePolling();
+      if (hasSounds) {
+        playStopSound(getAudioContextRef.current);
+      }
+      if (inputRef) {
+        removeInterimSpan();
+        const editable = getEditable();
+        if (editable) {
+          editable.dispatchEvent(new Event('input', {
+            bubbles: true
+          }));
+        }
+      }
+      callbacksRef.current.onEndProp?.();
+    }
+  });
+  const speechAbort = speech.abort;
+  const wrappedAbort = useCallback(() => {
+    speechAbort();
+    stopVolumePolling();
+  }, [speechAbort, stopVolumePolling]);
+  return {
+    isSupported: speech.isSupported,
+    isListening: speech.isListening,
+    isSpeaking: speech.isSpeaking,
+    interimTranscript: speech.interimTranscript,
+    volume,
+    bands,
+    rawBands,
+    start: speech.start,
+    stop: speech.stop,
+    abort: wrappedAbort,
+    toggle: speech.toggle
+  };
+}

package/dist/Chat/useChatNewMessages.d.ts

@@ -0,0 +1,25 @@
+export interface UseChatNewMessagesOptions {
+    /**
+     * Whether the scroll is currently locked (following content).
+     * When locked, new messages don't flag — the user is already at the bottom.
+     */
+    isLocked: boolean;
+    /**
+     * Called on every content height change (new message or streaming growth).
+     * Use to trigger scroll-if-locked in the scroll hook.
+     */
+    onResize?: () => void;
+}
+export interface UseChatNewMessagesReturn {
+    /** Whether new messages arrived while the scroll was unlocked. */
+    hasNewMessages: boolean;
+    /** Dismiss the new messages flag. */
+    dismiss: () => void;
+    /**
+     * Callback ref to attach to the content element.
+     * Handles late mount — observer attaches whenever the element appears.
+     */
+    contentRef: (el: HTMLElement | null) => void;
+}
+export declare function useChatNewMessages({ isLocked, onResize, }: UseChatNewMessagesOptions): UseChatNewMessagesReturn;
+//# sourceMappingURL=useChatNewMessages.d.ts.map

package/dist/Chat/useChatNewMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatNewMessages.d.ts","sourceRoot":"","sources":["../../src/Chat/useChatNewMessages.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,cAAc,EAAE,OAAO,CAAC;IAExB,qCAAqC;IACrC,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9C;AAMD,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,QAAQ,GACT,EAAE,yBAAyB,GAAG,wBAAwB,CAkEtD"}