@absolutejs/voice 0.0.3 → 0.0.4

package/README.md

@@ -51,6 +51,56 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## HTMX
+
+Voice now mirrors the AI plugin's HTMX pattern with plugin-owned renderers and a plugin-owned fragment route.
+
+```ts
+import { voice, createVoiceMemoryStore } from '@absolutejs/voice';
+
+app.use(
+	voice({
+		path: '/voice/intake',
+		htmx: {
+			render: {
+				result: ({ result }) =>
+					result
+						? `<pre>${JSON.stringify(result, null, 2)}</pre>`
+						: '<p>No structured result yet.</p>'
+			}
+		},
+		onComplete: async () => {},
+		onTurn: async ({ turn }) => ({
+			assistantText: `You said: ${turn.text}`
+		}),
+		session: createVoiceMemoryStore(),
+		stt: deepgram({
+			apiKey: process.env.DEEPGRAM_API_KEY!,
+			model: 'nova-3'
+		})
+	})
+);
+```
+
+The plugin exposes `GET /voice/intake/htmx/session?sessionId=...` by default. That route returns HTMX out-of-band fragments for:
+
+- metrics
+- status
+- committed turns
+- assistant replies
+- structured result
+
+On the client, bind the browser voice stream to a hidden HTMX refresh element:
+
+```ts
+import { bindVoiceHTMX, createVoiceStream } from '@absolutejs/voice/client';
+
+const voice = createVoiceStream('/voice/intake');
+bindVoiceHTMX(voice, { element: '#voice-htmx-sync' });
+```
+
+That keeps HTMX pages declarative without inventing custom fragment endpoints for core voice session UI.
+
 ## Adapter Contract
 
 Adapters normalize vendor behavior into a core event model so the plugin never branches on vendor names.

package/dist/angular/voice-stream.service.d.ts

@@ -8,7 +8,7 @@ export declare class VoiceStreamService {
         isConnected: import("@angular/core").Signal<boolean>;
         partial: import("@angular/core").Signal<string>;
         sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
-        sessionId: import("@angular/core").Signal<string>;
+        sessionId: import("@angular/core").Signal<string | null>;
         status: import("@angular/core").Signal<import("..").VoiceSessionStatus | "idle">;
         turns: import("@angular/core").Signal<VoiceTurnRecord<TResult>[]>;
     };

package/dist/client/createVoiceStream.d.ts

@@ -1,14 +1,2 @@
-import type { VoiceConnectionOptions } from '../types';
-export declare const createVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => {
-    close(): void;
-    endTurn(): void;
-    readonly error: string | null;
-    readonly isConnected: boolean;
-    readonly partial: string;
-    readonly sessionId: string;
-    readonly status: import("..").VoiceSessionStatus | "idle";
-    readonly turns: import("..").VoiceTurnRecord<TResult>[];
-    readonly assistantTexts: string[];
-    sendAudio(audio: Uint8Array | ArrayBuffer): void;
-    subscribe(subscriber: () => void): () => void;
-};
+import type { VoiceConnectionOptions, VoiceStream } from '../types';
+export declare const createVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => VoiceStream<TResult>;

package/dist/client/htmx.d.ts

@@ -0,0 +1,2 @@
+import type { VoiceHTMXBindingOptions, VoiceStream } from '../types';
+export declare const bindVoiceHTMX: <TResult = unknown>(stream: VoiceStream<TResult>, options: VoiceHTMXBindingOptions) => () => void;

package/dist/client/index.d.ts

@@ -1,3 +1,4 @@
 export { createVoiceConnection } from './connection';
 export { createVoiceStream } from './createVoiceStream';
+export { bindVoiceHTMX } from './htmx';
 export { createMicrophoneCapture } from './microphone';

package/dist/client/index.js

@@ -447,6 +447,53 @@ var createVoiceStream = (path, options = {}) => {
     }
   };
 };
+// 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) => {
@@ -517,5 +564,6 @@ var createMicrophoneCapture = (options) => {
 export {
   createVoiceStream,
   createVoiceConnection,
-  createMicrophoneCapture
+  createMicrophoneCapture,
+  bindVoiceHTMX
 };

package/dist/htmx.d.ts

@@ -0,0 +1,6 @@
+import type { VoiceHTMXRenderConfig, VoiceHTMXRenderInput, VoiceHTMXTargets, VoiceSessionRecord } from './types';
+type ResolvedVoiceHTMXRenderConfig<TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Required<VoiceHTMXRenderConfig<TSession, TResult>>;
+export declare const resolveVoiceHTMXTargets: (custom?: Partial<VoiceHTMXTargets>) => VoiceHTMXTargets;
+export declare const resolveVoiceHTMXRenderers: <TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(custom?: VoiceHTMXRenderConfig<TSession, TResult>) => ResolvedVoiceHTMXRenderConfig<TSession, TResult>;
+export declare const buildVoiceHTMXResponse: <TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(input: VoiceHTMXRenderInput<TResult, TSession>, renderers: ResolvedVoiceHTMXRenderConfig<TSession, TResult>, targets: VoiceHTMXTargets) => string;
+export {};

package/dist/index.js

@@ -72,6 +72,124 @@ var __decorateElement = (array, flags, name, decorators, target, extra) => {
 // src/plugin.ts
 import { Elysia } from "elysia";
 
+// src/htmx.ts
+var DEFAULT_HTMX_TARGETS = {
+  assistant: "voice-htmx-assistant",
+  metrics: "voice-htmx-metrics",
+  result: "voice-htmx-result",
+  status: "voice-htmx-status",
+  turns: "voice-htmx-turns"
+};
+var escapeHtml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var stringifyResult = (result) => {
+  if (result === undefined) {
+    return "";
+  }
+  if (typeof result === "string") {
+    return result;
+  }
+  try {
+    return JSON.stringify(result, null, 2);
+  } catch {
+    return String(result);
+  }
+};
+var defaultEmptyState = (kind) => {
+  switch (kind) {
+    case "assistant":
+      return '<p class="empty-copy">No assistant messages yet.</p>';
+    case "metrics":
+      return '<p class="empty-copy">No active voice session yet.</p>';
+    case "result":
+      return '<p class="empty-copy">No structured result yet.</p>';
+    case "status":
+      return '<p class="empty-copy">Voice session is idle.</p>';
+    case "turns":
+      return '<p class="empty-copy">No turns committed yet.</p>';
+  }
+};
+var defaultMetrics = (input) => {
+  if (!input.sessionId) {
+    return defaultEmptyState("metrics");
+  }
+  return [
+    '<div class="voice-metric">',
+    '<span class="voice-metric-label">Session</span>',
+    `<span class="voice-metric-value">${escapeHtml(input.sessionId)}</span>`,
+    "</div>",
+    '<div class="voice-metric">',
+    '<span class="voice-metric-label">Status</span>',
+    `<span class="voice-metric-value">${escapeHtml(input.status)}</span>`,
+    "</div>",
+    '<div class="voice-metric">',
+    '<span class="voice-metric-label">Committed turns</span>',
+    `<span class="voice-metric-value">${String(input.turnCount)}</span>`,
+    "</div>"
+  ].join("");
+};
+var defaultStatus = (input) => [
+  '<div class="status-row">',
+  '<span class="label">Voice status</span>',
+  `<span class="value">${escapeHtml(input.status)}</span>`,
+  "</div>",
+  '<div class="status-row">',
+  '<span class="label">Partial transcript</span>',
+  `<span class="value">${escapeHtml(input.partial || "No live partial")}</span>`,
+  "</div>"
+].join("");
+var renderTurn = (turn) => [
+  '<article class="voice-turn">',
+  '<div class="voice-turn-header">',
+  `<strong>${escapeHtml(turn.text)}</strong>`,
+  `<span>${new Date(turn.committedAt).toLocaleString("en-US", {
+    dateStyle: "medium",
+    timeStyle: "short"
+  })}</span>`,
+  "</div>",
+  turn.assistantText ? [
+    '<div class="voice-assistant-label">Assistant</div>',
+    `<p class="voice-turn-text">${escapeHtml(turn.assistantText)}</p>`
+  ].join("") : "",
+  "</article>"
+].join("");
+var defaultTurns = (input) => input.turns.length === 0 ? defaultEmptyState("turns") : input.turns.map((turn) => renderTurn(turn)).join("");
+var defaultAssistant = (input) => input.assistantTexts.length === 0 ? defaultEmptyState("assistant") : input.assistantTexts.map((text, index) => [
+  '<article class="voice-assistant-item">',
+  `<div class="voice-assistant-label">Reply ${String(index + 1)}</div>`,
+  `<p class="voice-turn-text">${escapeHtml(text)}</p>`,
+  "</article>"
+].join("")).join("");
+var defaultResult = (input) => {
+  if (input.result === undefined) {
+    return defaultEmptyState("result");
+  }
+  return [
+    '<pre class="voice-code"><code>',
+    escapeHtml(stringifyResult(input.result)),
+    "</code></pre>"
+  ].join("");
+};
+var resolveVoiceHTMXTargets = (custom) => ({
+  ...DEFAULT_HTMX_TARGETS,
+  ...custom
+});
+var resolveVoiceHTMXRenderers = (custom) => ({
+  assistant: custom?.assistant ?? defaultAssistant,
+  emptyState: custom?.emptyState ?? defaultEmptyState,
+  metrics: custom?.metrics ?? defaultMetrics,
+  result: custom?.result ?? defaultResult,
+  status: custom?.status ?? defaultStatus,
+  turns: custom?.turns ?? defaultTurns
+});
+var renderOob = (id, html) => `<div id="${escapeHtml(id)}" hx-swap-oob="innerHTML">${html}</div>`;
+var buildVoiceHTMXResponse = (input, renderers, targets) => [
+  renderOob(targets.metrics, renderers.metrics(input)),
+  renderOob(targets.status, renderers.status(input)),
+  renderOob(targets.turns, renderers.turns(input)),
+  renderOob(targets.assistant, renderers.assistant(input)),
+  renderOob(targets.result, renderers.result(input))
+].join("");
+
 // src/logger.ts
 var noop = () => {};
 var createNoopLogger = () => ({
@@ -560,6 +678,33 @@ var voice = (config) => {
     logger: resolveLogger(config.logger),
     socketSessions: new WeakMap
   };
+  const htmxConfig = typeof config.htmx === "object" ? config.htmx : undefined;
+  const htmxRoute = htmxConfig?.route ?? `${config.path}/htmx/session`;
+  const htmxRenderers = resolveVoiceHTMXRenderers(htmxConfig?.render);
+  const htmxTargets = resolveVoiceHTMXTargets(htmxConfig?.targets);
+  const htmxRoutes = () => {
+    if (!config.htmx) {
+      return new Elysia;
+    }
+    return new Elysia().get(htmxRoute, async ({ query }) => {
+      const sessionId = typeof query.sessionId === "string" && query.sessionId.trim() ? query.sessionId.trim() : undefined;
+      const session = sessionId ? await config.session.get(sessionId) : undefined;
+      const result = session?.turns.toReversed().find((turn) => turn.result !== undefined)?.result;
+      const turns = session?.turns ?? [];
+      return new Response(buildVoiceHTMXResponse({
+        assistantTexts: session?.turns.flatMap((turn) => turn.assistantText ? [turn.assistantText] : []) ?? [],
+        partial: session?.currentTurn.partialText ?? "",
+        result,
+        session,
+        sessionId,
+        status: session?.status ?? "idle",
+        turnCount: turns.length,
+        turns
+      }, htmxRenderers, htmxTargets), {
+        headers: { "Content-Type": "text/html; charset=utf-8" }
+      });
+    });
+  };
   return new Elysia({ name: "absolutejs-voice" }).ws(config.path, {
     close: async (ws, code, reason) => {
       const sessionId = runtime.socketSessions.get(ws);
@@ -661,7 +806,7 @@ var voice = (config) => {
       runtime.activeSessions.set(sessionId, session);
       await session.connect(createSocketAdapter(ws));
     }
-  });
+  }).use(htmxRoutes());
 };
 // src/memoryStore.ts
 var createVoiceMemoryStore = () => {

package/dist/plugin.d.ts

@@ -25,7 +25,29 @@ export declare const voice: <TContext = unknown, TSession extends VoiceSessionRe
             response: {};
         };
     };
-}, {
+} | ({
+    [x: string]: {
+        subscribe: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {};
+        };
+    };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}), {
     derive: {};
     resolve: {};
     schema: {};
@@ -37,4 +59,10 @@ export declare const voice: <TContext = unknown, TSession extends VoiceSessionRe
     schema: {};
     standaloneSchema: {};
     response: {};
+} & {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
 }>;

package/dist/react/useVoiceStream.d.ts

@@ -7,7 +7,7 @@ export declare const useVoiceStream: <TResult = unknown>(path: string, options?:
     error: string | null;
     isConnected: boolean;
     partial: string;
-    sessionId: string;
+    sessionId: string | null;
     status: import("..").VoiceSessionStatus | "idle";
     turns: import("..").VoiceTurnRecord<TResult>[];
 };

package/dist/svelte/createVoiceStream.d.ts

@@ -1,14 +1,2 @@
 import type { VoiceConnectionOptions } from '../types';
-export declare const createVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => {
-    close(): void;
-    endTurn(): void;
-    readonly error: string | null;
-    readonly isConnected: boolean;
-    readonly partial: string;
-    readonly sessionId: string;
-    readonly status: import("..").VoiceSessionStatus | "idle";
-    readonly turns: import("..").VoiceTurnRecord<TResult>[];
-    readonly assistantTexts: string[];
-    sendAudio(audio: Uint8Array | ArrayBuffer): void;
-    subscribe(subscriber: () => void): () => void;
-};
+export declare const createVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => import("..").VoiceStream<TResult>;

package/dist/types.d.ts

@@ -208,6 +208,7 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
         silenceMs?: number;
     };
     logger?: VoiceLogger;
+    htmx?: boolean | VoiceHTMXConfig<TSession, TResult>;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
 export type CreateVoiceSessionOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     id: string;
@@ -280,6 +281,36 @@ export type VoiceConnectionOptions = {
     pingInterval?: number;
     sessionId?: string;
 };
+export type VoiceHTMXRenderInput<TResult = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
+    assistantTexts: string[];
+    partial: string;
+    result?: TResult;
+    session?: TSession;
+    sessionId?: string;
+    status: VoiceSessionStatus | 'idle';
+    turnCount: number;
+    turns: VoiceTurnRecord<TResult>[];
+};
+export type VoiceHTMXRenderConfig<TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    metrics?: (input: VoiceHTMXRenderInput<TResult, TSession>) => string;
+    status?: (input: VoiceHTMXRenderInput<TResult, TSession>) => string;
+    turns?: (input: VoiceHTMXRenderInput<TResult, TSession>) => string;
+    assistant?: (input: VoiceHTMXRenderInput<TResult, TSession>) => string;
+    result?: (input: VoiceHTMXRenderInput<TResult, TSession>) => string;
+    emptyState?: (kind: keyof VoiceHTMXTargets, input: VoiceHTMXRenderInput<TResult, TSession>) => string;
+};
+export type VoiceHTMXTargets = {
+    assistant: string;
+    metrics: string;
+    result: string;
+    status: string;
+    turns: string;
+};
+export type VoiceHTMXConfig<TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    render?: VoiceHTMXRenderConfig<TSession, TResult>;
+    route?: string;
+    targets?: Partial<VoiceHTMXTargets>;
+};
 export type VoiceStreamState<TResult = unknown> = {
     sessionId: string | null;
     status: VoiceSessionStatus | 'idle';
@@ -289,6 +320,25 @@ export type VoiceStreamState<TResult = unknown> = {
     error: string | null;
     isConnected: boolean;
 };
+export type VoiceStream<TResult = unknown> = {
+    close: () => void;
+    endTurn: () => void;
+    error: string | null;
+    isConnected: boolean;
+    partial: string;
+    sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
+    sessionId: string | null;
+    status: VoiceSessionStatus | 'idle';
+    subscribe: (subscriber: () => void) => () => void;
+    turns: VoiceTurnRecord<TResult>[];
+    assistantTexts: string[];
+};
+export type VoiceHTMXBindingOptions = {
+    element: Element | string;
+    eventName?: string;
+    route?: string;
+    sessionQueryParam?: string;
+};
 export type VoiceStoreAction<TResult = unknown> = {
     type: 'session';
     sessionId: string;

package/dist/vue/useVoiceStream.d.ts

@@ -7,7 +7,7 @@ export declare const useVoiceStream: <TResult = unknown>(path: string, options?:
     isConnected: import("vue").Ref<boolean, boolean>;
     partial: import("vue").Ref<string, string>;
     sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
-    sessionId: import("vue").Ref<string, string>;
+    sessionId: import("vue").Ref<string | null, string | null>;
     status: import("vue").Ref<import("..").VoiceSessionStatus | "idle", import("..").VoiceSessionStatus | "idle">;
     turns: import("vue").ShallowRef<VoiceTurnRecord<TResult>[], VoiceTurnRecord<TResult>[]>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",