@gxp-dev/app-ui 0.1.6

package/src/composables/useStreamingAudio.ts

@@ -0,0 +1,308 @@
+/**
+ * Real-time audio streaming helpers — capture from the user's mic, push
+ * chunks to a server endpoint, and play back incoming audio frames. Used
+ * by the live voice features in the experience runtime.
+ */
+import { ref, onBeforeUnmount, type Ref } from 'vue'
+
+export interface UseStreamingAudioOptions {
+  /** Sample rate for the AudioContext. Defaults to 48000 (good for ASR/TTS). */
+  sampleRate?: number
+  /** When the mic level crosses this, the speech-detection callback fires. 0-100 scale. */
+  speechThreshold?: number
+  /** Minimum ms between speech-detection callback fires. */
+  speechDebounceMs?: number
+  /** Force AnalyserNode FFT size. */
+  fftSize?: number
+}
+
+export interface UseStreamingAudioReturn {
+  // Refs
+  audioContext: Ref<AudioContext | null>
+  analyser: Ref<AnalyserNode | null>
+  audioStream: Ref<MediaStream | null>
+  isCapturing: Ref<boolean>
+  isMuted: Ref<boolean>
+  /** Smoothed mic level on a 0-100 scale, updated each animation frame while capturing. */
+  audioLevel: Ref<number>
+
+  // Lifecycle
+  initialize: () => Promise<AudioContext>
+  startCapture: (constraints?: MediaTrackConstraints) => Promise<MediaStream>
+  stopCapture: () => void
+  toggleMute: () => void
+  cleanup: () => void
+
+  // Playback queue
+  /** Schedule a PCM16 chunk for sequential playback. */
+  playPCMChunk: (data: ArrayBuffer | Int16Array | string, sampleRate?: number) => void
+  /** Stop everything in the playback queue and reset the scheduler. */
+  interruptPlayback: () => void
+
+  // Analyser readers
+  getWaveformData: () => Uint8Array
+  getFrequencyData: () => Uint8Array
+
+  // Speech detection callback for barge-in
+  setSpeechDetectionCallback: (cb: ((level: number) => void) | null) => void
+}
+
+const base64ToBytes = (b64: string): Uint8Array => {
+  const binary = atob(b64)
+  const out = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)
+  return out
+}
+
+const int16ToFloat32 = (input: Int16Array): Float32Array => {
+  const out = new Float32Array(input.length)
+  for (let i = 0; i < input.length; i++) out[i] = input[i] / 32768
+  return out
+}
+
+/**
+ * Continuous-stream audio I/O primitive.
+ *
+ * Use cases:
+ *   - Real-time AI voice apps (Gemini Live, Realtime API, etc.) that emit PCM
+ *     chunks and need them stitched into seamless playback.
+ *   - Streaming TTS where audio arrives interleaved with other events.
+ *   - Any pipeline that needs simultaneous mic capture + analyser visualisation
+ *     + interruptible chunked playback.
+ *
+ * The playback path goes through a `MediaStreamDestination` + `<audio>` element
+ * so the browser's echo cancellation can use it as the AEC reference signal.
+ */
+export function useStreamingAudio(
+  options: UseStreamingAudioOptions = {},
+): UseStreamingAudioReturn {
+  const sampleRate = options.sampleRate ?? 48000
+  const speechThreshold = options.speechThreshold ?? 15
+  const speechDebounceMs = options.speechDebounceMs ?? 300
+  const fftSize = options.fftSize ?? 2048
+
+  const audioContext = ref<AudioContext | null>(null)
+  const analyser = ref<AnalyserNode | null>(null)
+  const audioStream = ref<MediaStream | null>(null)
+  const isCapturing = ref(false)
+  const isMuted = ref(false)
+  const audioLevel = ref(0)
+
+  let mediaStreamDestination: MediaStreamAudioDestinationNode | null = null
+  let playbackElement: HTMLAudioElement | null = null
+  let nextPlaybackTime = 0
+  const scheduledSources: Array<{ source: AudioBufferSourceNode; endTime: number }> = []
+
+  let speechDetectionCallback: ((level: number) => void) | null = null
+  let lastSpeechTime = 0
+  let levelRafId: number | null = null
+
+  const initialize = async (): Promise<AudioContext> => {
+    if (audioContext.value) return audioContext.value
+    const Ctor =
+      window.AudioContext ||
+      (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext
+    const ctx = new Ctor({ sampleRate })
+    audioContext.value = ctx
+
+    const a = ctx.createAnalyser()
+    a.fftSize = fftSize
+    a.smoothingTimeConstant = 0.8
+    analyser.value = a
+
+    mediaStreamDestination = ctx.createMediaStreamDestination()
+    playbackElement = document.createElement('audio')
+    playbackElement.srcObject = mediaStreamDestination.stream
+    playbackElement.autoplay = true
+    return ctx
+  }
+
+  const startLevelMonitoring = (): void => {
+    const a = analyser.value
+    if (!a) return
+    const buffer = new Uint8Array(a.frequencyBinCount)
+    const tick = (): void => {
+      if (!isCapturing.value || !analyser.value) {
+        levelRafId = null
+        return
+      }
+      analyser.value.getByteFrequencyData(buffer)
+      const average = buffer.reduce((sum, v) => sum + v, 0) / buffer.length
+      const level = Math.round((average / 255) * 100)
+      audioLevel.value = level
+
+      if (level > speechThreshold && speechDetectionCallback) {
+        const now = Date.now()
+        if (now - lastSpeechTime > speechDebounceMs) {
+          lastSpeechTime = now
+          speechDetectionCallback(level)
+        }
+      }
+      levelRafId = requestAnimationFrame(tick)
+    }
+    levelRafId = requestAnimationFrame(tick)
+  }
+
+  const startCapture = async (
+    constraints: MediaTrackConstraints = {},
+  ): Promise<MediaStream> => {
+    if (!audioContext.value) await initialize()
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+        sampleRate,
+        channelCount: 1,
+        ...constraints,
+      },
+    })
+    audioStream.value = stream
+    const source = audioContext.value!.createMediaStreamSource(stream)
+    source.connect(analyser.value!)
+    isCapturing.value = true
+    isMuted.value = false
+    startLevelMonitoring()
+    return stream
+  }
+
+  const stopCapture = (): void => {
+    if (audioStream.value) {
+      audioStream.value.getTracks().forEach((t) => t.stop())
+      audioStream.value = null
+    }
+    isCapturing.value = false
+    audioLevel.value = 0
+    if (levelRafId !== null) {
+      cancelAnimationFrame(levelRafId)
+      levelRafId = null
+    }
+  }
+
+  const toggleMute = (): void => {
+    if (!audioStream.value) return
+    const track = audioStream.value.getAudioTracks()[0]
+    if (!track) return
+    track.enabled = !track.enabled
+    isMuted.value = !track.enabled
+  }
+
+  const playPCMChunk = (
+    data: ArrayBuffer | Int16Array | string,
+    chunkSampleRate?: number,
+  ): void => {
+    const ctx = audioContext.value
+    if (!ctx) return
+
+    let int16: Int16Array
+    let rate = chunkSampleRate ?? sampleRate
+
+    if (typeof data === 'string') {
+      // Allow `"audio/pcm;rate=16000"`-style hints baked into the string when callers
+      // pass the raw base64. Otherwise we just decode the bytes.
+      const bytes = base64ToBytes(data)
+      int16 = new Int16Array(bytes.buffer)
+    } else if (data instanceof Int16Array) {
+      int16 = data
+    } else {
+      int16 = new Int16Array(data)
+    }
+
+    const float32 = int16ToFloat32(int16)
+    const buffer = ctx.createBuffer(1, float32.length, rate)
+    buffer.getChannelData(0).set(float32)
+
+    const currentTime = ctx.currentTime
+    if (nextPlaybackTime === 0 || nextPlaybackTime < currentTime) {
+      nextPlaybackTime = currentTime
+    }
+
+    const source = ctx.createBufferSource()
+    source.buffer = buffer
+    if (mediaStreamDestination) {
+      source.connect(mediaStreamDestination)
+    } else {
+      source.connect(ctx.destination)
+    }
+    source.start(nextPlaybackTime)
+
+    const info = { source, endTime: nextPlaybackTime + buffer.duration }
+    scheduledSources.push(info)
+    source.onended = () => {
+      const idx = scheduledSources.indexOf(info)
+      if (idx !== -1) scheduledSources.splice(idx, 1)
+    }
+
+    nextPlaybackTime += buffer.duration
+  }
+
+  const interruptPlayback = (): void => {
+    if (scheduledSources.length === 0) return
+    for (const info of scheduledSources) {
+      try {
+        info.source.stop()
+      } catch {
+        // already ended
+      }
+    }
+    scheduledSources.length = 0
+    nextPlaybackTime = 0
+  }
+
+  const getWaveformData = (): Uint8Array => {
+    if (!analyser.value) return new Uint8Array(0)
+    const buffer = new Uint8Array(analyser.value.frequencyBinCount)
+    analyser.value.getByteTimeDomainData(buffer)
+    return buffer
+  }
+
+  const getFrequencyData = (): Uint8Array => {
+    if (!analyser.value) return new Uint8Array(0)
+    const buffer = new Uint8Array(analyser.value.frequencyBinCount)
+    analyser.value.getByteFrequencyData(buffer)
+    return buffer
+  }
+
+  const setSpeechDetectionCallback = (cb: ((level: number) => void) | null): void => {
+    speechDetectionCallback = cb
+  }
+
+  const cleanup = (): void => {
+    stopCapture()
+    interruptPlayback()
+    if (playbackElement) {
+      playbackElement.srcObject = null
+      playbackElement = null
+    }
+    mediaStreamDestination = null
+    if (audioContext.value) {
+      audioContext.value.close().catch(() => {
+        // already closed
+      })
+      audioContext.value = null
+    }
+    analyser.value = null
+    speechDetectionCallback = null
+  }
+
+  onBeforeUnmount(cleanup)
+
+  return {
+    audioContext,
+    analyser,
+    audioStream,
+    isCapturing,
+    isMuted,
+    audioLevel,
+    initialize,
+    startCapture,
+    stopCapture,
+    toggleMute,
+    cleanup,
+    playPCMChunk,
+    interruptPlayback,
+    getWaveformData,
+    getFrequencyData,
+    setSpeechDetectionCallback,
+  }
+}

package/src/composables/useToast.stories.ts

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseToastDemo from './__demo__/UseToastDemo.vue'
+
+const meta = {
+  title: 'Composables/useToast',
+  component: UseToastDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:notification'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useToast()\` is a typed wrapper around [vue-sonner](https://vue-sonner.vercel.app/).
+Methods: \`success / error / warning / info / show / loading / dismiss /
+promise\`. Mount \`<Toaster />\` once at your app root for the toasts to
+appear.
+
+\`promise(p, { loading, success, error })\` is the most useful pattern — fires
+a loading toast immediately, replaces it with success or error when the
+promise settles.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Quick async feedback for user actions',
+        'Background events that need acknowledgement but no modal',
+        'Wrapping promise-based operations with automatic loading/success/error UX',
+      ],
+      whenNotToUse: [
+        'Persistent errors that must block the flow — use a dialog or banner',
+        'Form validation messages — show them inline',
+      ],
+      related: ['Sonner', 'useErrors'],
+    },
+  },
+} satisfies Meta<typeof UseToastDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Every variant is exposed as a button. The promise-based ones fire a 1.2s
+ * fake promise to show how loading toasts upgrade to success/error.
+ */
+export const AllVariants: Story = {}

package/src/composables/useToast.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { useToast } from './useToast'
+
+// Mock vue-sonner
+vi.mock('vue-sonner', () => {
+  const mockToast = Object.assign(vi.fn(() => 1), {
+    success: vi.fn(() => 1),
+    error: vi.fn(() => 1),
+    warning: vi.fn(() => 1),
+    info: vi.fn(() => 1),
+    loading: vi.fn(() => 1),
+    dismiss: vi.fn(),
+    promise: vi.fn(() => 1),
+  })
+  return { toast: mockToast }
+})
+
+describe('useToast', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should call toast.success with message and options', async () => {
+    const { toast } = await import('vue-sonner')
+    const { success } = useToast()
+
+    success('Success message', { duration: 3000 })
+
+    expect(toast.success).toHaveBeenCalledWith('Success message', { duration: 3000 })
+  })
+
+  it('should call toast.error with message and options', async () => {
+    const { toast } = await import('vue-sonner')
+    const { error } = useToast()
+
+    error('Error message', { duration: 5000 })
+
+    expect(toast.error).toHaveBeenCalledWith('Error message', { duration: 5000 })
+  })
+
+  it('should call toast.warning with message and options', async () => {
+    const { toast } = await import('vue-sonner')
+    const { warning } = useToast()
+
+    warning('Warning message')
+
+    expect(toast.warning).toHaveBeenCalledWith('Warning message', undefined)
+  })
+
+  it('should call toast.info with message and options', async () => {
+    const { toast } = await import('vue-sonner')
+    const { info } = useToast()
+
+    info('Info message', { duration: 2000 })
+
+    expect(toast.info).toHaveBeenCalledWith('Info message', { duration: 2000 })
+  })
+
+  it('should call toast with message and options for show method', async () => {
+    const { toast } = await import('vue-sonner')
+    const { show } = useToast()
+
+    show('Generic message', { duration: 4000 })
+
+    expect(toast).toHaveBeenCalledWith('Generic message', { duration: 4000 })
+  })
+
+  it('should call toast.loading with message and options', async () => {
+    const { toast } = await import('vue-sonner')
+    const { loading } = useToast()
+
+    loading('Loading...', { duration: 10000 })
+
+    expect(toast.loading).toHaveBeenCalledWith('Loading...', { duration: 10000 })
+  })
+
+  it('should call toast.dismiss with id', async () => {
+    const { toast } = await import('vue-sonner')
+    const { dismiss } = useToast()
+
+    dismiss(123)
+
+    expect(toast.dismiss).toHaveBeenCalledWith(123)
+  })
+
+  it('should call toast.dismiss without id to dismiss all', async () => {
+    const { toast } = await import('vue-sonner')
+    const { dismiss } = useToast()
+
+    dismiss()
+
+    expect(toast.dismiss).toHaveBeenCalledWith(undefined)
+  })
+
+  it('should call toast.promise with promise and messages', async () => {
+    const { toast } = await import('vue-sonner')
+    const { promise } = useToast()
+
+    const testPromise = Promise.resolve('data')
+    const messages = {
+      loading: 'Processing...',
+      success: 'Done!',
+      error: 'Failed!',
+    }
+
+    promise(testPromise, messages)
+
+    expect(toast.promise).toHaveBeenCalledWith(testPromise, messages)
+  })
+
+  it('should call toast.promise with function-based success/error messages', async () => {
+    const { toast } = await import('vue-sonner')
+    const { promise } = useToast()
+
+    const testPromise = Promise.resolve('data')
+    const messages = {
+      loading: 'Processing...',
+      success: (data: string) => `Success: ${data}`,
+      error: (err: unknown) => `Error: ${err}`,
+    }
+
+    promise(testPromise, messages)
+
+    expect(toast.promise).toHaveBeenCalledWith(testPromise, messages)
+  })
+
+  it('should return toast IDs from all methods', () => {
+    const toast = useToast()
+
+    expect(toast.success('Success')).toBe(1)
+    expect(toast.error('Error')).toBe(1)
+    expect(toast.warning('Warning')).toBe(1)
+    expect(toast.info('Info')).toBe(1)
+    expect(toast.show('Show')).toBe(1)
+    expect(toast.loading('Loading')).toBe(1)
+    expect(toast.promise(Promise.resolve(), { loading: '', success: '', error: '' })).toBe(1)
+  })
+})

package/src/composables/useToast.ts

@@ -0,0 +1,60 @@
+/**
+ * Convenience wrapper over `vue-sonner` providing standard `success` /
+ * `error` / `info` / `warning` toast variants with the platform's
+ * default styling. Drop `<Toaster />` at the app root once, then call
+ * from anywhere.
+ */
+import { toast, type ExternalToast } from 'vue-sonner'
+
+export interface ToastOptions extends ExternalToast {
+  /** Toast duration in milliseconds */
+  duration?: number
+}
+
+export interface UseToastReturn {
+  /** Show a success toast */
+  success: (message: string, options?: ToastOptions) => string | number
+  /** Show an error toast */
+  error: (message: string, options?: ToastOptions) => string | number
+  /** Show a warning toast */
+  warning: (message: string, options?: ToastOptions) => string | number
+  /** Show an info toast */
+  info: (message: string, options?: ToastOptions) => string | number
+  /** Show a generic toast */
+  show: (message: string, options?: ToastOptions) => string | number
+  /** Show a loading toast, returns ID for updating */
+  loading: (message: string, options?: ToastOptions) => string | number
+  /** Dismiss a toast by ID, or all toasts if no ID */
+  dismiss: (id?: string | number) => void
+  /** Show a promise-based toast */
+  promise: <T>(
+    promise: Promise<T>,
+    messages: { loading: string; success: string | ((data: T) => string); error: string | ((error: unknown) => string) },
+  ) => string | number
+}
+
+/**
+ * Composable for showing toast notifications via vue-sonner.
+ *
+ * Requires the `<Toaster />` component to be mounted in your app.
+ * Falls back to console logging if toast is unavailable.
+ *
+ * @example
+ * ```ts
+ * const { success, error } = useToast()
+ * success('Item saved!')
+ * error('Something went wrong')
+ * ```
+ */
+export function useToast(): UseToastReturn {
+  return {
+    success: (message, options?) => toast.success(message, options),
+    error: (message, options?) => toast.error(message, options),
+    warning: (message, options?) => toast.warning(message, options),
+    info: (message, options?) => toast.info(message, options),
+    show: (message, options?) => toast(message, options),
+    loading: (message, options?) => toast.loading(message, options),
+    dismiss: (id?) => toast.dismiss(id),
+    promise: (promise, messages) => toast.promise(promise, messages) as string | number,
+  }
+}

package/src/composables/useWebSocket.stories.ts

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseWebSocketDemo from './__demo__/UseWebSocketDemo.vue'
+
+const meta = {
+  title: 'Composables/useWebSocket',
+  component: UseWebSocketDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:realtime', 'pattern:websocket'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useWebSocket()\` is a generic WebSocket wrapper with **typed message
+routing**, auto-reconnect, and optional bearer-token auth.
+
+Pattern:
+
+\`\`\`ts
+const ws = useWebSocket()
+ws.on('message', (data) => /* handle */)
+ws.on('reaction-added', (data) => /* … */)
+await ws.connect('wss://api.example.com/ws', { token })
+ws.send('message', { content: 'hi' })
+\`\`\`
+
+Outgoing messages get JSON-serialized as \`{ type, data }\`; incoming
+messages are routed by their \`type\` field to registered handlers.
+
+Reactive refs: \`status\` (connecting | open | closing | closed | error),
+\`reconnectCount\`, \`lastError\`.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Real-time bi-directional comms (chat, live quiz, presence)',
+        'Server-pushed events with typed routing',
+        'You want auto-reconnect out of the box',
+      ],
+      whenNotToUse: [
+        'One-shot fetch / poll — use fetch / axios',
+        'WebRTC media — see useChatMedia',
+      ],
+      related: ['useChatMessages', 'useChatMedia'],
+    },
+  },
+} satisfies Meta<typeof UseWebSocketDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Connects to the public WebSocket echo service. Send a payload with
+ * \`send('echo', { content })\` — the echo server replies with the same
+ * payload, which the \`on('echo', …)\` handler logs.
+ *
+ * Public echo endpoints can rate-limit / refuse connections from Storybook
+ * iframes; if the connection fails, run Storybook in a top-level tab.
+ */
+export const EchoServer: Story = {}