@absolutejs/voice 0.0.16 → 0.0.17

package/dist/client/htmxBootstrap.d.ts

@@ -0,0 +1 @@
+export declare const initVoiceHTMX: () => void;

package/dist/client/htmxBootstrap.js

@@ -0,0 +1,888 @@
+// src/client/actions.ts
+var normalizeErrorMessage = (value) => {
+  if (typeof value === "string" && value.trim()) {
+    return value;
+  }
+  if (value instanceof Error && value.message.trim()) {
+    return value.message;
+  }
+  if (value && typeof value === "object") {
+    const record = value;
+    for (const key of ["message", "reason", "description"]) {
+      const candidate = record[key];
+      if (typeof candidate === "string" && candidate.trim()) {
+        return candidate;
+      }
+    }
+    if ("error" in record) {
+      return normalizeErrorMessage(record.error);
+    }
+    if ("cause" in record) {
+      return normalizeErrorMessage(record.cause);
+    }
+    try {
+      return JSON.stringify(value);
+    } catch {}
+  }
+  return "Unexpected error";
+};
+var serverMessageToAction = (message) => {
+  switch (message.type) {
+    case "assistant":
+      return {
+        text: message.text,
+        type: "assistant"
+      };
+    case "complete":
+      return {
+        sessionId: message.sessionId,
+        type: "complete"
+      };
+    case "error":
+      return {
+        message: normalizeErrorMessage(message.message),
+        type: "error"
+      };
+    case "final":
+      return {
+        transcript: message.transcript,
+        type: "final"
+      };
+    case "partial":
+      return {
+        transcript: message.transcript,
+        type: "partial"
+      };
+    case "session":
+      return {
+        sessionId: message.sessionId,
+        status: message.status,
+        type: "session"
+      };
+    case "turn":
+      return {
+        turn: message.turn,
+        type: "turn"
+      };
+    default:
+      return null;
+  }
+};
+
+// src/client/connection.ts
+var WS_OPEN = 1;
+var WS_CLOSED = 3;
+var WS_NORMAL_CLOSURE = 1000;
+var DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
+var DEFAULT_PING_INTERVAL = 30000;
+var RECONNECT_DELAY_MS = 500;
+var noop = () => {};
+var noopUnsubscribe = () => noop;
+var NOOP_CONNECTION = {
+  close: noop,
+  endTurn: noop,
+  getReadyState: () => WS_CLOSED,
+  getSessionId: () => "",
+  send: noop,
+  sendAudio: noop,
+  subscribe: noopUnsubscribe
+};
+var createSessionId = () => crypto.randomUUID();
+var buildWsUrl = (path, sessionId) => {
+  const { hostname, port, protocol } = window.location;
+  const wsProtocol = protocol === "https:" ? "wss:" : "ws:";
+  const portSuffix = port ? `:${port}` : "";
+  const url = new URL(`${wsProtocol}//${hostname}${portSuffix}${path}`);
+  url.searchParams.set("sessionId", sessionId);
+  return url.toString();
+};
+var isVoiceServerMessage = (value) => {
+  if (!value || typeof value !== "object" || !("type" in value)) {
+    return false;
+  }
+  switch (value.type) {
+    case "assistant":
+    case "complete":
+    case "error":
+    case "final":
+    case "partial":
+    case "pong":
+    case "session":
+    case "turn":
+      return true;
+    default:
+      return false;
+  }
+};
+var parseServerMessage = (event) => {
+  if (typeof event.data !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(event.data);
+    return isVoiceServerMessage(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+var createVoiceConnection = (path, options = {}) => {
+  if (typeof window === "undefined") {
+    return NOOP_CONNECTION;
+  }
+  const listeners = new Set;
+  const shouldReconnect = options.reconnect !== false;
+  const maxReconnectAttempts = options.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+  const pingInterval = options.pingInterval ?? DEFAULT_PING_INTERVAL;
+  const state = {
+    isConnected: false,
+    pendingMessages: [],
+    pingInterval: null,
+    reconnectAttempts: 0,
+    reconnectTimeout: null,
+    sessionId: options.sessionId ?? createSessionId(),
+    ws: null
+  };
+  const clearTimers = () => {
+    if (state.pingInterval) {
+      clearInterval(state.pingInterval);
+      state.pingInterval = null;
+    }
+    if (state.reconnectTimeout) {
+      clearTimeout(state.reconnectTimeout);
+      state.reconnectTimeout = null;
+    }
+  };
+  const flushPendingMessages = () => {
+    if (state.ws?.readyState !== WS_OPEN) {
+      return;
+    }
+    while (state.pendingMessages.length > 0) {
+      const next = state.pendingMessages.shift();
+      if (next !== undefined) {
+        state.ws.send(next);
+      }
+    }
+  };
+  const scheduleReconnect = () => {
+    state.reconnectAttempts += 1;
+    state.reconnectTimeout = setTimeout(() => {
+      if (state.reconnectAttempts > maxReconnectAttempts) {
+        return;
+      }
+      connect();
+    }, RECONNECT_DELAY_MS);
+  };
+  const connect = () => {
+    const ws = new WebSocket(buildWsUrl(path, state.sessionId));
+    ws.binaryType = "arraybuffer";
+    ws.onopen = () => {
+      state.isConnected = true;
+      state.reconnectAttempts = 0;
+      flushPendingMessages();
+      listeners.forEach((listener) => listener({
+        sessionId: state.sessionId,
+        status: "active",
+        type: "session"
+      }));
+      state.pingInterval = setInterval(() => {
+        if (ws.readyState === WS_OPEN) {
+          ws.send(JSON.stringify({ type: "ping" }));
+        }
+      }, pingInterval);
+    };
+    ws.onmessage = (event) => {
+      const parsed = parseServerMessage(event);
+      if (!parsed) {
+        return;
+      }
+      if (parsed.type === "session") {
+        state.sessionId = parsed.sessionId;
+      }
+      listeners.forEach((listener) => listener(parsed));
+    };
+    ws.onclose = (event) => {
+      state.isConnected = false;
+      clearTimers();
+      const reconnectable = shouldReconnect && event.code !== WS_NORMAL_CLOSURE && state.reconnectAttempts < maxReconnectAttempts;
+      if (reconnectable) {
+        scheduleReconnect();
+      }
+    };
+    state.ws = ws;
+  };
+  const sendSerialized = (value) => {
+    if (state.ws?.readyState === WS_OPEN) {
+      state.ws.send(value);
+      return;
+    }
+    state.pendingMessages.push(value);
+  };
+  const send = (message) => {
+    sendSerialized(JSON.stringify(message));
+  };
+  const sendAudio = (audio) => {
+    sendSerialized(audio);
+  };
+  const endTurn = () => {
+    send({ type: "end_turn" });
+  };
+  const close = () => {
+    clearTimers();
+    if (state.ws) {
+      state.ws.close(WS_NORMAL_CLOSURE);
+      state.ws = null;
+    }
+    state.isConnected = false;
+    listeners.clear();
+  };
+  const subscribe = (callback) => {
+    listeners.add(callback);
+    return () => {
+      listeners.delete(callback);
+    };
+  };
+  connect();
+  return {
+    close,
+    endTurn,
+    getReadyState: () => state.ws?.readyState ?? WS_CLOSED,
+    getSessionId: () => state.sessionId,
+    send,
+    sendAudio,
+    subscribe
+  };
+};
+
+// src/client/store.ts
+var createInitialState = () => ({
+  assistantTexts: [],
+  error: null,
+  isConnected: false,
+  partial: "",
+  sessionId: null,
+  status: "idle",
+  turns: []
+});
+var createVoiceStreamStore = () => {
+  let state = createInitialState();
+  const subscribers = new Set;
+  const notify = () => {
+    subscribers.forEach((subscriber) => subscriber());
+  };
+  const dispatch = (action) => {
+    switch (action.type) {
+      case "assistant":
+        state = {
+          ...state,
+          assistantTexts: [...state.assistantTexts, action.text]
+        };
+        break;
+      case "complete":
+        state = {
+          ...state,
+          sessionId: action.sessionId,
+          status: "completed"
+        };
+        break;
+      case "connected":
+        state = {
+          ...state,
+          isConnected: true
+        };
+        break;
+      case "disconnected":
+        state = {
+          ...state,
+          isConnected: false
+        };
+        break;
+      case "error":
+        state = {
+          ...state,
+          error: action.message
+        };
+        break;
+      case "final":
+        state = {
+          ...state,
+          partial: action.transcript.text,
+          turns: state.turns.map((turn) => turn)
+        };
+        break;
+      case "partial":
+        state = {
+          ...state,
+          partial: action.transcript.text
+        };
+        break;
+      case "session":
+        state = {
+          ...state,
+          error: null,
+          isConnected: action.status === "active",
+          sessionId: action.sessionId,
+          status: action.status
+        };
+        break;
+      case "turn":
+        state = {
+          ...state,
+          partial: "",
+          turns: [...state.turns, action.turn]
+        };
+        break;
+    }
+    notify();
+  };
+  return {
+    dispatch,
+    getServerSnapshot: () => state,
+    getSnapshot: () => state,
+    subscribe: (subscriber) => {
+      subscribers.add(subscriber);
+      return () => {
+        subscribers.delete(subscriber);
+      };
+    }
+  };
+};
+
+// src/client/createVoiceStream.ts
+var createVoiceStream = (path, options = {}) => {
+  const connection = createVoiceConnection(path, options);
+  const store = createVoiceStreamStore();
+  const subscribers = new Set;
+  const notify = () => {
+    subscribers.forEach((subscriber) => subscriber());
+  };
+  const unsubscribeConnection = connection.subscribe((message) => {
+    const action = serverMessageToAction(message);
+    if (action) {
+      store.dispatch(action);
+      notify();
+    }
+  });
+  return {
+    close() {
+      unsubscribeConnection();
+      connection.close();
+      store.dispatch({ type: "disconnected" });
+      notify();
+    },
+    endTurn() {
+      connection.endTurn();
+    },
+    get error() {
+      return store.getSnapshot().error;
+    },
+    getServerSnapshot() {
+      return store.getServerSnapshot();
+    },
+    getSnapshot() {
+      return store.getSnapshot();
+    },
+    get isConnected() {
+      return store.getSnapshot().isConnected;
+    },
+    get partial() {
+      return store.getSnapshot().partial;
+    },
+    get sessionId() {
+      return connection.getSessionId();
+    },
+    get status() {
+      return store.getSnapshot().status;
+    },
+    get turns() {
+      return store.getSnapshot().turns;
+    },
+    get assistantTexts() {
+      return store.getSnapshot().assistantTexts;
+    },
+    sendAudio(audio) {
+      connection.sendAudio(audio);
+    },
+    subscribe(subscriber) {
+      subscribers.add(subscriber);
+      return () => {
+        subscribers.delete(subscriber);
+      };
+    }
+  };
+};
+
+// src/client/htmx.ts
+var DEFAULT_EVENT_NAME = "voice-refresh";
+var DEFAULT_QUERY_PARAM = "sessionId";
+var resolveElement = (input) => {
+  if (typeof input !== "string") {
+    return input;
+  }
+  return document.querySelector(input);
+};
+var buildRoute = (element, route, queryParam, sessionId) => {
+  const baseRoute = route ?? element.getAttribute("hx-get") ?? "";
+  if (!baseRoute) {
+    return "";
+  }
+  const url = new URL(baseRoute, window.location.origin);
+  if (sessionId) {
+    url.searchParams.set(queryParam, sessionId);
+  } else {
+    url.searchParams.delete(queryParam);
+  }
+  return `${url.pathname}${url.search}${url.hash}`;
+};
+var bindVoiceHTMX = (stream, options) => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {};
+  }
+  const element = resolveElement(options.element);
+  if (!element) {
+    return () => {};
+  }
+  const eventName = options.eventName ?? DEFAULT_EVENT_NAME;
+  const queryParam = options.sessionQueryParam ?? DEFAULT_QUERY_PARAM;
+  const sync = () => {
+    const htmxWindow = window;
+    const nextRoute = buildRoute(element, options.route, queryParam, stream.sessionId);
+    if (nextRoute) {
+      element.setAttribute("hx-get", nextRoute);
+    }
+    htmxWindow.htmx?.process?.(element);
+    htmxWindow.htmx?.trigger?.(element, eventName);
+  };
+  const unsubscribe = stream.subscribe(sync);
+  sync();
+  return () => {
+    unsubscribe();
+  };
+};
+
+// src/client/microphone.ts
+var clampSample = (value) => Math.max(-1, Math.min(1, value));
+var floatTo16BitPCM = (input) => {
+  const output = new Int16Array(input.length);
+  for (let index = 0;index < input.length; index += 1) {
+    const sample = clampSample(input[index] ?? 0);
+    output[index] = sample < 0 ? sample * 32768 : sample * 32767;
+  }
+  return new Uint8Array(output.buffer);
+};
+var downsampleBuffer = (input, sourceRate, targetRate) => {
+  if (sourceRate === targetRate) {
+    return input;
+  }
+  const ratio = sourceRate / targetRate;
+  const length = Math.round(input.length / ratio);
+  const output = new Float32Array(length);
+  let offsetResult = 0;
+  let offsetBuffer = 0;
+  while (offsetResult < output.length) {
+    const nextOffsetBuffer = Math.round((offsetResult + 1) * ratio);
+    let accum = 0;
+    let count = 0;
+    for (let index = offsetBuffer;index < nextOffsetBuffer && index < input.length; index += 1) {
+      accum += input[index] ?? 0;
+      count += 1;
+    }
+    output[offsetResult] = count > 0 ? accum / count : 0;
+    offsetResult += 1;
+    offsetBuffer = nextOffsetBuffer;
+  }
+  return output;
+};
+var createMicrophoneCapture = (options) => {
+  let audioContext = null;
+  let sourceNode = null;
+  let processorNode = null;
+  let mediaStream = null;
+  const start = async () => {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) {
+      throw new Error("Browser microphone capture requires navigator.mediaDevices.getUserMedia.");
+    }
+    const AudioContextCtor = (typeof window !== "undefined" ? window.AudioContext ?? window.webkitAudioContext : undefined) ?? AudioContext;
+    if (!AudioContextCtor) {
+      throw new Error("Browser microphone capture requires AudioContext support.");
+    }
+    mediaStream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        channelCount: options.channelCount ?? 1
+      }
+    });
+    audioContext = new AudioContextCtor;
+    sourceNode = audioContext.createMediaStreamSource(mediaStream);
+    processorNode = audioContext.createScriptProcessor(4096, 1, 1);
+    processorNode.onaudioprocess = (event) => {
+      const channel = event.inputBuffer.getChannelData(0);
+      const downsampled = downsampleBuffer(channel, audioContext?.sampleRate ?? 48000, options.sampleRateHz ?? 16000);
+      options.onAudio(floatTo16BitPCM(downsampled));
+    };
+    sourceNode.connect(processorNode);
+    processorNode.connect(audioContext.destination);
+  };
+  const stop = () => {
+    processorNode?.disconnect();
+    sourceNode?.disconnect();
+    mediaStream?.getTracks().forEach((track) => track.stop());
+    audioContext?.close();
+    audioContext = null;
+    mediaStream = null;
+    processorNode = null;
+    sourceNode = null;
+  };
+  return { start, stop };
+};
+
+// src/client/htmxBootstrap.ts
+var VOICE_WAVE_POINTS = 48;
+var VOICE_WAVE_WIDTH = 320;
+var VOICE_WAVE_HEIGHT = 88;
+var DEFAULT_GUIDED_LABEL = "Guided test";
+var DEFAULT_GENERAL_LABEL = "General recording";
+var DEFAULT_IDLE_LEAD = "Pick a mode to begin the demo.";
+var DEFAULT_GUIDED_LEAD = "I can walk you through a short guided voice test.";
+var DEFAULT_GENERAL_LEAD = "I can capture one freeform recording and confirm that it landed.";
+var DEFAULT_IDLE_PROMPT = "Choose a mode to begin. Guided test asks follow-up prompts. General recording just captures what you say.";
+var DEFAULT_GENERAL_IDLE_PROMPT = "Click Start general recording to capture one freeform answer.";
+var DEFAULT_GENERAL_LIVE_PROMPT = "Speak freely. When you pause, the recording will be captured.";
+var DEFAULT_GENERAL_COMPLETE_PROMPT = "Recording saved. Start again if you want another capture.";
+var DEFAULT_GUIDED_COMPLETE_PROMPT = "Guided test complete. Review the saved summary below.";
+var DEFAULT_GUIDED_OVERFLOW_PROMPT = "All prompts are covered. You can stop the microphone or keep speaking for extra detail.";
+var DEFAULT_MIC_IDLE = "Ready. Start guided test or general recording to begin.";
+var DEFAULT_MIC_LIVE = "Live. Answer the prompt, then click Stop microphone when finished.";
+var DEFAULT_GUIDED_PROMPTS = [
+  "Start with a quick introduction about who you are.",
+  "Now describe what you are trying to do or test.",
+  "Finish with any detail that feels blocked, risky, or unclear."
+];
+var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+var escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var readErrorField = (value, key) => {
+  const candidate = value[key];
+  if (typeof candidate === "string" && candidate.trim()) {
+    return candidate;
+  }
+  return null;
+};
+var formatErrorMessage = (error) => {
+  if (typeof error === "string" && error.trim()) {
+    return error;
+  }
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  if (error && typeof error === "object") {
+    const record = error;
+    const direct = readErrorField(record, "message") ?? readErrorField(record, "reason") ?? readErrorField(record, "description");
+    if (direct) {
+      return direct;
+    }
+    if ("error" in record) {
+      return formatErrorMessage(record.error);
+    }
+    if ("cause" in record) {
+      return formatErrorMessage(record.cause);
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {}
+  }
+  return "Unexpected error";
+};
+var createInitialVoiceWaveLevels = (count = VOICE_WAVE_POINTS) => Array.from({ length: count }, () => 0);
+var pushVoiceWaveLevel = (levels, nextLevel, count = VOICE_WAVE_POINTS) => {
+  const next = levels.slice(-(count - 1));
+  next.push(clamp(nextLevel, 0, 1));
+  while (next.length < count) {
+    next.unshift(0);
+  }
+  return next;
+};
+var createVoiceWavePath = (levels, width = VOICE_WAVE_WIDTH, height = VOICE_WAVE_HEIGHT) => {
+  const samples = levels.length > 1 ? levels : createInitialVoiceWaveLevels(VOICE_WAVE_POINTS);
+  const step = width / (samples.length - 1);
+  const center = height / 2;
+  const maxAmplitude = height * 0.34;
+  const peakLevel = Math.max(...samples, 0);
+  if (peakLevel <= 0.015) {
+    return `M 0 ${center} L ${width} ${center}`;
+  }
+  const points = samples.map((level, index) => {
+    const phase = index * 0.76;
+    const wobble = Math.sin(phase) * 0.78 + Math.sin(phase * 0.41) * 0.22;
+    const amplitude = level * maxAmplitude;
+    const x = step * index;
+    const y = clamp(center + wobble * amplitude, 8, height - 8);
+    return { x, y };
+  });
+  if (points.length === 0) {
+    return `M 0 ${center} L ${width} ${center}`;
+  }
+  let path = `M ${points[0]?.x ?? 0} ${points[0]?.y ?? center}`;
+  for (let index = 1;index < points.length; index += 1) {
+    const previous = points[index - 1];
+    const current = points[index];
+    if (!previous || !current) {
+      continue;
+    }
+    const controlX = (previous.x + current.x) / 2;
+    path += ` Q ${controlX} ${previous.y} ${current.x} ${current.y}`;
+  }
+  return path;
+};
+var getPcmLevel = (audio) => {
+  const bytes = audio instanceof Uint8Array ? audio : new Uint8Array(audio);
+  if (bytes.byteLength < 2) {
+    return 0;
+  }
+  const samples = new Int16Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 2));
+  if (samples.length === 0) {
+    return 0;
+  }
+  let sumSquares = 0;
+  for (const sample of samples) {
+    const normalized = sample / 32768;
+    sumSquares += normalized * normalized;
+  }
+  const rms = Math.sqrt(sumSquares / samples.length);
+  return clamp(rms * 5.5, 0, 1);
+};
+var parsePromptList = (value) => {
+  if (!value) {
+    return DEFAULT_GUIDED_PROMPTS;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    if (Array.isArray(parsed)) {
+      const prompts = parsed.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean);
+      if (prompts.length > 0) {
+        return prompts;
+      }
+    }
+  } catch {}
+  return DEFAULT_GUIDED_PROMPTS;
+};
+var requireElement = (root, selector, ctor, name) => {
+  const value = selector ? document.querySelector(selector) : null;
+  if (value instanceof ctor) {
+    return value;
+  }
+  const fallback = root.querySelector(`#${name}`);
+  if (fallback instanceof ctor) {
+    return fallback;
+  }
+  throw new Error(`Voice HTMX bootstrap could not find the required element "${name}".`);
+};
+var resolveLeadMessage = (input) => {
+  if (!input.mode) {
+    return DEFAULT_IDLE_LEAD;
+  }
+  if (!input.hasStarted) {
+    return input.mode === "guided" ? DEFAULT_GUIDED_LEAD : DEFAULT_GENERAL_LEAD;
+  }
+  if (input.status === "completed") {
+    return input.mode === "guided" ? DEFAULT_GUIDED_COMPLETE_PROMPT : DEFAULT_GENERAL_COMPLETE_PROMPT;
+  }
+  if (input.mode === "general") {
+    return DEFAULT_GENERAL_LIVE_PROMPT;
+  }
+  return input.guidedPrompts[input.turnCount] ?? DEFAULT_GUIDED_OVERFLOW_PROMPT;
+};
+var resolvePromptMessage = (input) => {
+  if (!input.mode) {
+    return DEFAULT_IDLE_PROMPT;
+  }
+  if (input.status === "completed") {
+    return input.mode === "guided" ? DEFAULT_GUIDED_COMPLETE_PROMPT : DEFAULT_GENERAL_COMPLETE_PROMPT;
+  }
+  if (!input.hasStarted) {
+    return input.mode === "guided" ? `Click Start guided test to begin. First prompt: ${input.guidedPrompts[0] ?? "Answer the first prompt."}` : DEFAULT_GENERAL_IDLE_PROMPT;
+  }
+  if (input.mode === "general") {
+    return input.turnCount === 0 ? DEFAULT_GENERAL_LIVE_PROMPT : DEFAULT_GENERAL_COMPLETE_PROMPT;
+  }
+  return input.guidedPrompts[input.turnCount] ?? DEFAULT_GUIDED_OVERFLOW_PROMPT;
+};
+var createDemoMicrophone = (onAudio, onLevel) => {
+  let capture = null;
+  return {
+    start: async () => {
+      if (capture) {
+        return;
+      }
+      const nextCapture = createMicrophoneCapture({
+        onAudio: (audio) => {
+          onLevel(getPcmLevel(audio));
+          onAudio(audio);
+        },
+        sampleRateHz: 16000
+      });
+      capture = nextCapture;
+      try {
+        await capture.start();
+      } catch (error) {
+        capture = null;
+        throw error;
+      }
+    },
+    stop: () => {
+      capture?.stop();
+      capture = null;
+      onLevel(0);
+    }
+  };
+};
+var initVoiceHTMXRoot = (root) => {
+  const guidedPath = root.dataset.voiceGuidedPath;
+  const generalPath = root.dataset.voiceGeneralPath;
+  if (!guidedPath || !generalPath) {
+    throw new Error("Voice HTMX bootstrap requires data-voice-guided-path and data-voice-general-path.");
+  }
+  const guidedPrompts = parsePromptList(root.dataset.voiceGuidedPrompts);
+  const guidedLabel = root.dataset.voiceGuidedLabel ?? DEFAULT_GUIDED_LABEL;
+  const generalLabel = root.dataset.voiceGeneralLabel ?? DEFAULT_GENERAL_LABEL;
+  const syncElement = requireElement(document, root.dataset.voiceSync, HTMLElement, "voice-htmx-sync");
+  const connectionMetric = requireElement(root, root.dataset.voiceConnection, HTMLElement, "metric-connection");
+  const errorStatus = requireElement(root, root.dataset.voiceError, HTMLElement, "status-error");
+  const microphoneStatus = requireElement(root, root.dataset.voiceMicrophone, HTMLElement, "status-mic");
+  const promptStatus = requireElement(root, root.dataset.voicePrompt, HTMLElement, "status-prompt");
+  const chatList = requireElement(root, root.dataset.voiceChat, HTMLElement, "chat-list");
+  const startGuidedButton = requireElement(root, root.dataset.voiceStartGuided, HTMLButtonElement, "start-guided");
+  const startGeneralButton = requireElement(root, root.dataset.voiceStartGeneral, HTMLButtonElement, "start-general");
+  const stopButton = requireElement(root, root.dataset.voiceStop, HTMLButtonElement, "stop-mic");
+  const voiceMonitor = requireElement(root, root.dataset.voiceMonitor, HTMLElement, "voice-monitor");
+  const voiceMonitorCopy = requireElement(root, root.dataset.voiceMonitorCopy, HTMLElement, "voice-monitor-copy");
+  const voiceWaveGlow = requireElement(root, root.dataset.voiceWaveGlow, SVGPathElement, "voice-wave-glow");
+  const voiceWavePath = requireElement(root, root.dataset.voiceWavePath, SVGPathElement, "voice-wave-path");
+  const guidedVoice = createVoiceStream(guidedPath);
+  const generalVoice = createVoiceStream(generalPath);
+  const stopGuidedBinding = bindVoiceHTMX(guidedVoice, { element: syncElement });
+  const stopGeneralBinding = bindVoiceHTMX(generalVoice, {
+    element: syncElement
+  });
+  let activeMode = null;
+  let hasStartedModes = {
+    general: false,
+    guided: false
+  };
+  let isCapturing = false;
+  let micError = null;
+  let waveLevels = createInitialVoiceWaveLevels();
+  const currentVoice = () => activeMode === "general" ? generalVoice : guidedVoice;
+  const renderWave = () => {
+    const path = createVoiceWavePath(waveLevels);
+    voiceWaveGlow.setAttribute("d", path);
+    voiceWavePath.setAttribute("d", path);
+    voiceMonitorCopy.innerHTML = `<span class="voice-live-dot"></span>${isCapturing ? "Microphone live" : "Microphone idle"}`;
+    voiceMonitorCopy.classList.toggle("is-live", isCapturing);
+    voiceMonitor.classList.toggle("is-live", isCapturing);
+  };
+  const render = () => {
+    const voice = currentVoice();
+    const hasStarted = (activeMode ? hasStartedModes[activeMode] : false) || voice.turns.length > 0;
+    const status = voice.status;
+    connectionMetric.textContent = voice.isConnected ? "Connected" : "Waiting";
+    errorStatus.textContent = micError || voice.error || "None";
+    microphoneStatus.textContent = isCapturing ? DEFAULT_MIC_LIVE : DEFAULT_MIC_IDLE;
+    promptStatus.textContent = resolvePromptMessage({
+      guidedPrompts,
+      hasStarted,
+      mode: activeMode,
+      status,
+      turnCount: voice.turns.length
+    });
+    startGuidedButton.hidden = isCapturing;
+    startGeneralButton.hidden = isCapturing;
+    stopButton.hidden = !isCapturing;
+    chatList.innerHTML = `<article class="voice-chat-message assistant">
+  <div class="voice-chat-role">${escapeHtml(activeMode === "general" ? generalLabel : activeMode === "guided" ? guidedLabel : "Voice demo")}</div>
+  <p class="voice-turn-text">${escapeHtml(resolveLeadMessage({
+      generalLabel,
+      guidedLabel,
+      guidedPrompts,
+      hasStarted,
+      mode: activeMode,
+      status,
+      turnCount: voice.turns.length
+    }))}</p>
+</article>${voice.turns.map((turn) => `<div class="voice-chat-stack">
+  <article class="voice-chat-message user">
+    <div class="voice-chat-role">You</div>
+    <p class="voice-turn-text">${escapeHtml(turn.text)}</p>
+  </article>
+  ${turn.assistantText ? `<article class="voice-chat-message assistant">
+    <div class="voice-chat-role">${escapeHtml(activeMode === "general" ? generalLabel : activeMode === "guided" ? guidedLabel : "Guide")}</div>
+    <p class="voice-turn-text">${escapeHtml(turn.assistantText)}</p>
+  </article>` : ""}
+</div>`).join("")}${voice.partial ? `<article class="voice-chat-message user pending">
+  <div class="voice-chat-role">Speaking</div>
+  <p class="voice-turn-text">${escapeHtml(voice.partial)}</p>
+</article>` : ""}`;
+    renderWave();
+  };
+  const microphone = createDemoMicrophone((audio) => currentVoice().sendAudio(audio), (level) => {
+    waveLevels = pushVoiceWaveLevel(waveLevels, level);
+    renderWave();
+  });
+  const stopMic = () => {
+    microphone.stop();
+    isCapturing = false;
+    micError = null;
+    waveLevels = createInitialVoiceWaveLevels();
+    render();
+  };
+  const startMode = async (mode) => {
+    activeMode = mode;
+    hasStartedModes = {
+      ...hasStartedModes,
+      [mode]: true
+    };
+    try {
+      await microphone.start();
+      micError = null;
+      isCapturing = true;
+      render();
+    } catch (error) {
+      microphone.stop();
+      isCapturing = false;
+      waveLevels = createInitialVoiceWaveLevels();
+      micError = formatErrorMessage(error);
+      render();
+    }
+  };
+  guidedVoice.subscribe(render);
+  generalVoice.subscribe(render);
+  startGuidedButton.addEventListener("click", () => {
+    startMode("guided");
+  });
+  startGeneralButton.addEventListener("click", () => {
+    startMode("general");
+  });
+  stopButton.addEventListener("click", () => {
+    stopMic();
+  });
+  window.addEventListener("beforeunload", () => {
+    microphone.stop();
+    stopGuidedBinding();
+    stopGeneralBinding();
+    guidedVoice.close();
+    generalVoice.close();
+  });
+  render();
+};
+var initVoiceHTMX = () => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
+  }
+  const roots = Array.from(document.querySelectorAll("[data-voice-htmx]"));
+  for (const root of roots) {
+    if (root instanceof HTMLElement) {
+      initVoiceHTMXRoot(root);
+    }
+  }
+};
+initVoiceHTMX();
+export {
+  initVoiceHTMX
+};

package/dist/index.js

@@ -71,6 +71,7 @@ var __decorateElement = (array, flags, name, decorators, target, extra) => {
 
 // src/plugin.ts
 import { Elysia } from "elysia";
+import { resolve } from "path";
 
 // src/htmx.ts
 var DEFAULT_HTMX_TARGETS = {
@@ -680,6 +681,51 @@ var createVoiceSession = (options) => {
 };
 
 // src/plugin.ts
+var HTMX_BOOTSTRAP_DIST_CANDIDATES = [
+  resolve(import.meta.dir, "client", "htmxBootstrap.js"),
+  resolve(import.meta.dir, "..", "dist", "client", "htmxBootstrap.js")
+];
+var HTMX_BOOTSTRAP_SOURCE_CANDIDATES = [
+  resolve(import.meta.dir, "client", "htmxBootstrap.ts"),
+  resolve(import.meta.dir, "..", "src", "client", "htmxBootstrap.ts")
+];
+var loadHTMXBootstrap = (() => {
+  let cached = null;
+  return () => {
+    if (cached) {
+      return cached;
+    }
+    cached = (async () => {
+      for (const candidate of HTMX_BOOTSTRAP_DIST_CANDIDATES) {
+        const asset = Bun.file(candidate);
+        if (await asset.exists()) {
+          return await asset.text();
+        }
+      }
+      for (const candidate of HTMX_BOOTSTRAP_SOURCE_CANDIDATES) {
+        const asset = Bun.file(candidate);
+        if (!await asset.exists()) {
+          continue;
+        }
+        const build = await Bun.build({
+          entrypoints: [candidate],
+          format: "esm",
+          minify: true,
+          target: "browser"
+        });
+        if (!build.success || build.outputs.length === 0) {
+          const log = build.logs.map((entry) => entry.message).join(`
+`);
+          throw new Error(`Failed to build the voice HTMX bootstrap bundle.${log ? `
+${log}` : ""}`);
+        }
+        return await build.outputs[0].text();
+      }
+      throw new Error("Unable to locate the voice HTMX bootstrap client.");
+    })();
+    return cached;
+  };
+})();
 var isArrayBufferView = (value) => typeof value === "object" && value !== null && ArrayBuffer.isView(value);
 var isVoiceClientMessage = (value) => {
   if (!value || typeof value !== "object" || !("type" in value)) {
@@ -755,6 +801,7 @@ var voice = (config) => {
   const onTurn = normalizeOnTurn(config.onTurn);
   const htmxOptions = config.htmx && typeof config.htmx === "object" ? config.htmx : undefined;
   const htmxRoute = htmxOptions?.route ?? `${config.path}/htmx/session`;
+  const htmxBootstrapRoute = htmxOptions?.bootstrapRoute ?? `${config.path}/htmx/bootstrap.js`;
   const htmxRenderers = resolveVoiceHTMXRenderers(config.htmx && config.htmx !== true ? config.htmx : undefined);
   const htmxTargets = resolveVoiceHTMXTargets(htmxOptions?.targets);
   const htmxRoutes = () => {
@@ -778,7 +825,11 @@ var voice = (config) => {
       }, htmxRenderers, htmxTargets), {
         headers: { "Content-Type": "text/html; charset=utf-8" }
       });
-    });
+    }).get(htmxBootstrapRoute, async () => new Response(await loadHTMXBootstrap(), {
+      headers: {
+        "Content-Type": "application/javascript; charset=utf-8"
+      }
+    }));
   };
   return new Elysia({ name: "absolutejs-voice" }).ws(config.path, {
     close: async (ws, code, reason) => {

package/dist/plugin.d.ts

@@ -47,6 +47,18 @@ export declare const voice: <TContext = unknown, TSession extends VoiceSessionRe
             };
         };
     };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
 }), {
     derive: {};
     resolve: {};

package/dist/types.d.ts

@@ -315,6 +315,7 @@ export type VoiceHTMXTargets = {
     turns: string;
 };
 export type VoiceHTMXOptions<TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceHTMXRenderConfig<TSession, TResult> & {
+    bootstrapRoute?: string;
     route?: string;
     targets?: Partial<VoiceHTMXTargets>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.16",
+	"version": "0.0.17",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",
@@ -15,7 +15,7 @@
 	"license": "CC BY-NC 4.0",
 	"author": "Alex Kahn",
 	"scripts": {
-		"build": "rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute && tsc --emitDeclarationOnly --project tsconfig.json",
+		"build": "rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json",
 		"format": "prettier --write \"./**/*.{js,jsx,ts,tsx,json,md}\"",
 		"lint": "eslint ./src",
 		"release": "bun run format && bun run build && bun publish",