@backbay/glia 0.2.0-alpha.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Backbay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,492 @@
+# @backbay/glia
+
+> An open-source standard and component library for building agent-native web applications.
+
+[![npm version](https://img.shields.io/npm/v/@backbay/glia.svg)](https://www.npmjs.com/package/@backbay/glia)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## The Problem
+
+The web has no standard for AI agent interaction:
+
+| Layer | Human Web | Agent Web (Missing) |
+|-------|-----------|---------------------|
+| Discovery | `sitemap.xml`, `robots.txt` | What can an agent *do* here? |
+| Execution | Click, type, scroll | How does an agent *reliably* act? |
+| Feedback | Visual UI, loading states | How does an agent know it *worked*? |
+
+## The Solution
+
+**bb-ui** provides two parallel pillars:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                          glia                               │
+├─────────────────────────────┬───────────────────────────────┤
+│       glia-protocol         │       glia-components         │
+│  (Discovery + Execution)    │    (Agentic UI Primitives)    │
+├─────────────────────────────┼───────────────────────────────┤
+│  • glia-manifest.json       │  • <GliaProvider>             │
+│  • data-glia-* attributes   │  • <SyncDocument>             │
+│  • Capability schemas       │  • <AgentPanel>               │
+│  • Entity extraction        │  • <PlaySession>              │
+│  • Safety constraints       │  • useSync, useAgentRun       │
+└─────────────────────────────┴───────────────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install @backbay/glia
+# or
+bun add @backbay/glia
+```
+
+## Styles (Required for UI)
+
+`glia` ships a prebuilt stylesheet that includes:
+- Theme CSS variables
+- Primitives/component styling
+
+Import it once near your app entrypoint:
+
+```ts
+import "@backbay/glia/styles.css";
+```
+
+## Quick Start
+
+### Level 1: Add a Manifest (5 minutes)
+
+Create `public/bb-manifest.json`:
+
+```json
+{
+  "version": "1.0",
+  "name": "My App",
+  "description": "A sample agent-native application",
+  "capabilities": [
+    {
+      "id": "search-products",
+      "type": "query",
+      "description": "Search for products by keyword",
+      "selector": "[data-bb-action='search']",
+      "inputs": [
+        { "name": "query", "type": "string", "required": true }
+      ]
+    }
+  ]
+}
+```
+
+### Level 2: Add DOM Annotations (10 minutes)
+
+```tsx
+<button
+  data-bb-action="search"
+  data-bb-description="Search for products"
+>
+  Search
+</button>
+
+<div data-bb-entity="product" data-bb-entity-id="123">
+  <span data-bb-field="name">Widget Pro</span>
+  <span data-bb-field="price">$99</span>
+</div>
+```
+
+### Level 3: Full Integration (30 minutes)
+
+```tsx
+import { GliaProvider, SyncDocument, useAgentRun } from "@backbay/glia";
+
+const agents = [
+  { id: "default-agent", name: "Default Agent", costPerRun: 0.01 },
+];
+
+function App() {
+  return (
+    <GliaProvider config={{ apiBaseUrl: "/api/agent" }} agents={agents}>
+      <MyAgentApp />
+    </GliaProvider>
+  );
+}
+
+function MyAgentApp() {
+  const { start, status, cost } = useAgentRun();
+
+  return (
+    <SyncDocument
+      documentId="my-document"
+      endpoint="/api/docs"
+      initialContent={{ content: "" }}
+      onConflict={(local, remote, resolve) => (
+        <ConflictResolver local={local} remote={remote} onResolve={resolve} />
+      )}
+    >
+      {({ content, setContent, status: syncStatus, pendingChanges }) => (
+        <div>
+          <Editor
+            content={content?.content ?? ""}
+            onChange={(next) => setContent({ content: next })}
+          />
+          <button
+            onClick={() => start("default-agent", `Summarize:\n\n${content?.content ?? ""}`)}
+            disabled={status === "running"}
+          >
+            Summarize{cost != null ? ` ($${cost.toFixed(3)})` : ""}
+          </button>
+          {syncStatus === "pending" && <div>Saving… ({pendingChanges})</div>}
+        </div>
+      )}
+    </SyncDocument>
+  );
+}
+```
+
+## Exports
+
+The package provides multiple entry points for tree-shaking:
+
+```tsx
+// Everything
+import { GliaProvider, useSync, findAction } from '@backbay/glia';
+
+// Core-only (avoids heavier optional modules)
+import { GliaProvider, useSync, findAction } from '@backbay/glia/core';
+
+// Protocol only (discovery + DOM utilities)
+import { GliaManifestSchema, findAction, extractEntity } from '@backbay/glia/protocol';
+
+// Hooks only
+import { useSync, useAgentRun, useRunStream } from '@backbay/glia/hooks';
+
+// Components only
+import { GliaProvider, SyncDocument, AgentPanel } from '@backbay/glia/components';
+
+// Workspace (agent-composable UI)
+import { WorkspaceRenderer, getRegistry } from '@backbay/glia/workspace';
+
+// UI Primitives
+import { GlowButton, GlassPanel, Graph3D } from '@backbay/glia/primitives';
+
+// Theme system
+import { UiThemeProvider, useColorTokens } from '@backbay/glia/theme';
+
+// Emotion system
+import { useEmotion, EmotionController, computeVisualState, ANCHOR_STATES } from '@backbay/glia/emotion';
+```
+
+## Core Concepts
+
+### 1. Progressive Enhancement
+
+Works at any adoption level:
+- **Level 0**: No glia → Agents use vision/DOM heuristics
+- **Level 1**: Manifest only → Agents know what's possible
+- **Level 2**: Manifest + DOM annotations → Agents can reliably execute
+- **Level 3**: Full glia-components → Rich agentic experiences
+
+### 2. Agents Are Metered Services
+
+Every agent interaction has:
+- **Cost**: USD estimate, token count
+- **Latency**: Expected response time
+- **Risk**: Low/medium/high classification
+
+### 3. Offline-First, Conflict-Aware
+
+Local state is canonical until sync completes. Conflicts surface explicitly with resolution options: `keep_local`, `use_remote`, `create_copy`.
+
+### 4. Human-in-the-Loop by Default
+
+High-risk actions require human confirmation with timeout behavior.
+
+## API Reference
+
+### Protocol
+
+#### `GliaManifestSchema`
+Zod schema for validating manifest files.
+
+```tsx
+import { GliaManifestSchema } from '@backbay/glia/protocol';
+
+const result = GliaManifestSchema.safeParse(manifestData);
+if (result.success) {
+  console.log(result.data.capabilities);
+}
+```
+
+#### `findAction(selector: string)`
+Find an action element in the DOM.
+
+```tsx
+import { findAction } from '@backbay/glia/protocol';
+
+const button = findAction('search-products');
+button?.click();
+```
+
+#### `extractEntity(element: Element)`
+Extract structured entity data from annotated DOM.
+
+```tsx
+import { extractEntity } from '@backbay/glia/protocol';
+
+const productEl = document.querySelector('[data-bb-entity="product"]');
+const product = extractEntity(productEl);
+// { type: 'product', id: '123', fields: { name: 'Widget', price: '$99' } }
+```
+
+### Backend API Contract (Hooks)
+
+Hooks read `apiBaseUrl` from `BBProvider` and expect a JSON API:
+
+- `useAgentRun`: `POST {apiBaseUrl}/runs` → `{ output: string, cost?: number, tokenCount?: number }`
+- `useRunStream`: `GET {apiBaseUrl}/runs/:runId` and/or `GET {apiBaseUrl}/runs/:runId/events` (SSE) → `{ status, output?, error? }`
+- `usePlaySession`: `POST {apiBaseUrl}/play-sessions` + `DELETE {apiBaseUrl}/play-sessions/:id` + a WebSocket at `.../play-sessions/:id/ws` (JSON-RPC)
+
+### Hooks
+
+#### `useSync<T>(options)`
+Offline-first data sync with conflict detection.
+
+```tsx
+const { data, setData, forceSave, status, conflict } = useSync<Document>({
+  key: "doc-123",
+  endpoint: "/api/docs/123",
+  debounce: 1000,
+  onConflict: (c) => console.log("Conflict", c),
+});
+```
+
+#### `useAgentRun()`
+Execute an agent run (API-backed) with cost tracking.
+
+```tsx
+const { start, status, latency, cost, cancel } = useAgentRun();
+
+await start("default-agent", `Summarize:\n\n${content}`);
+console.log(`Cost: $${cost ?? 0}, Latency: ${latency ?? 0}ms`);
+```
+
+#### `useRunStream(runId: string)`
+Stream run status updates in real-time.
+
+```tsx
+const { status, run, latestEvent, isConnected } = useRunStream(runId);
+```
+
+### Components
+
+#### `<GliaProvider>`
+Root provider for agent context.
+
+```tsx
+<GliaProvider config={{ apiBaseUrl: "/api/agent" }} agents={agents}>
+  {children}
+</GliaProvider>
+```
+
+#### `<SyncDocument>`
+Render-prop component for synced documents.
+
+```tsx
+<SyncDocument
+  documentId="my-doc"
+  endpoint="/api/docs"
+>
+  {({ content, setContent }) => <Editor content={content} onChange={setContent} />}
+</SyncDocument>
+```
+
+### Workspace
+
+#### `WorkspaceRenderer`
+Render agent-composed UI from a WorkspaceSpec.
+
+```tsx
+import { WorkspaceRenderer } from '@backbay/glia/workspace';
+
+const spec: WorkspaceSpec = {
+  id: 'dashboard',
+  name: 'Agent Dashboard',
+  layout: {
+    type: 'split',
+    direction: 'horizontal',
+    children: [
+      { type: 'panel', component: 'agent-panel' },
+      { type: 'panel', component: 'chat-view' }
+    ]
+  }
+};
+
+<WorkspaceRenderer spec={spec} />
+```
+
+## Emotion System
+
+The emotion system provides a psychologically-grounded dimensional model for AI agent emotional expression, based on Russell's Circumplex Model of Affect.
+
+### The AVO Model
+
+Three continuous dimensions (0-1 range):
+
+| Dimension | Low (0) | High (1) | Visual Effect |
+|-----------|---------|----------|---------------|
+| **Arousal** | Dormant | Intense | Animation speed, particles |
+| **Valence** | Distressed | Elated | Color warmth, stability |
+| **Openness** | Receptive | Expressive | Particle flow direction |
+
+### Quick Start
+
+```typescript
+import { useEmotion } from '@backbay/glia/emotion';
+
+function MyAgent() {
+  const { dimensions, visualState, goTo, emit } = useEmotion({
+    initialAnchor: 'idle',
+  });
+
+  // Respond to events
+  const onUserInput = () => emit({ type: 'input_received' });
+  const onComplete = () => goTo('satisfied');
+
+  return <GlyphObject visualState={visualState} />;
+}
+```
+
+### Anchor States
+
+Pre-defined emotional configurations:
+- **Rest**: `dormant`, `idle`
+- **Receptive**: `attentive`, `curious`, `listening`
+- **Processing**: `thinking`, `contemplating`, `focused`
+- **Expressive**: `responding`, `explaining`, `enthusiastic`
+- **Completion**: `satisfied`, `proud`
+- **Negative**: `uncertain`, `concerned`, `struggling`, `alarmed`, `error`
+- **Recovery**: `recovering`, `relieved`
+
+### API Reference
+
+#### `useEmotion(options)`
+React hook for emotion state management.
+
+```tsx
+const { dimensions, visualState, goTo, emit } = useEmotion({
+  initialAnchor: 'idle',
+  transitionDuration: 800,
+});
+```
+
+#### `EmotionController`
+Class-based controller for non-React usage.
+
+```tsx
+import { EmotionController } from '@backbay/glia';
+
+const controller = new EmotionController({ initialAnchor: 'idle' });
+controller.goTo('thinking');
+const state = controller.getVisualState();
+```
+
+#### `computeVisualState(avo)`
+Convert AVO dimensions to visual properties.
+
+```tsx
+import { computeVisualState } from '@backbay/glia';
+
+const visual = computeVisualState({ arousal: 0.7, valence: 0.8, openness: 0.5 });
+// { animationSpeed, colorTemperature, particleIntensity, ... }
+```
+
+#### `ANCHOR_STATES`
+Predefined anchor state coordinates.
+
+```tsx
+import { ANCHOR_STATES } from '@backbay/glia';
+
+console.log(ANCHOR_STATES.thinking);
+// { arousal: 0.6, valence: 0.5, openness: 0.3 }
+```
+
+See `docs/specs/glyph-emotion-system.md` for full specification.
+
+## ClusterHero
+
+A cinematic landing page component for cluster branding with video backgrounds, atmospheric effects, and scroll-triggered sections.
+
+### Basic Usage
+
+```tsx
+import { ClusterHero, ClusterHeroPage } from '@backbay/glia/components';
+
+// Just the hero section (100vh)
+<ClusterHero cluster="alexandria" />
+
+// Full landing page with scroll sections
+<ClusterHeroPage clusterId="baia" />
+```
+
+### Available Clusters
+
+| Cluster | Accent Color | Tagline | Atmosphere |
+|---------|-------------|---------|------------|
+| `alexandria` | Gold (#C9A227) | "Where knowledge compounds" | Dust motes + godrays |
+| `alpha` | Silver (#E8E8E8) | "The origin of everything" | Volumetric fog |
+| `opus` | Copper (#B87333) | "Craft that endures" | Dust motes + bloom |
+| `baia` | Sun gold (#D4AF37) | "Where ambition rests" | Godrays + caustics |
+
+### Components
+
+- `ClusterHero` - Hero section only
+- `ClusterHeroPage` - Full page with sections
+- `FeatureCardsSection` - Feature grid
+- `ClusterStatsSection` - Animated stats
+- `CTASection` - Call to action
+
+### Customization
+
+The component uses existing glia atmosphere primitives:
+- `DustMotesLayer`
+- `VolumetricLight`
+- `FogLayer`
+
+Video assets should be placed at paths defined in the cluster config.
+
+## DOM Annotations Reference
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `data-bb-action` | Action trigger | `data-bb-action="submit-order"` |
+| `data-bb-entity` | Entity container | `data-bb-entity="product"` |
+| `data-bb-entity-id` | Entity identifier | `data-bb-entity-id="sku-123"` |
+| `data-bb-field` | Entity field | `data-bb-field="price"` |
+| `data-bb-state` | Current state | `data-bb-state="loading"` |
+| `data-bb-input` | Input binding | `data-bb-input="search-query"` |
+| `data-bb-description` | Human/LLM description | `data-bb-description="Add to cart"` |
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  GliaManifest,
+  Capability,
+  EntitySchema,
+  WorkspaceSpec,
+  LayoutNode,
+  AgentId,
+  RunId,
+} from '@backbay/glia';
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT

package/dist/audio/hooks/index.d.ts

@@ -0,0 +1,15 @@
+export { useAudioPlayer } from './useAudioPlayer.js';
+export type { UseAudioPlayerOptions, UseAudioPlayerReturn } from './useAudioPlayer.js';
+export { useBargeIn } from './useBargeIn.js';
+export type { UseBargeInOptions, UseBargeInReturn } from './useBargeIn.js';
+export { useSpeechSynthesis } from './useSpeechSynthesis.js';
+export type { UseSpeechSynthesisOptions, UseSpeechSynthesisReturn, SpeakOptions } from './useSpeechSynthesis.js';
+export { useAudioOverlay } from './useAudioOverlay.js';
+export type { UseAudioOverlayOptions, UseAudioOverlayReturn, OverlaySpeakOptions } from './useAudioOverlay.js';
+export { useHybridSpeech } from './useHybridSpeech.js';
+export type { UseHybridSpeechOptions, UseHybridSpeechReturn } from './useHybridSpeech.js';
+export { useRunSpeechCues, DEFAULT_RUN_SPEECH_CUES } from './useRunSpeechCues.js';
+export type { UseRunSpeechCuesOptions, RunSpeechCueMap } from './useRunSpeechCues.js';
+export { useCognitionSpeech } from './useCognitionSpeech.js';
+export type { UseCognitionSpeechOptions, SpeakWithCognitionOptions, UseCognitionSpeechReturn, } from './useCognitionSpeech.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audio/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEjH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE/G,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE1F,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAClF,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC"}

package/dist/audio/hooks/index.js

@@ -0,0 +1,7 @@
+export { useAudioPlayer } from './useAudioPlayer.js';
+export { useBargeIn } from './useBargeIn.js';
+export { useSpeechSynthesis } from './useSpeechSynthesis.js';
+export { useAudioOverlay } from './useAudioOverlay.js';
+export { useHybridSpeech } from './useHybridSpeech.js';
+export { useRunSpeechCues, DEFAULT_RUN_SPEECH_CUES } from './useRunSpeechCues.js';
+export { useCognitionSpeech } from './useCognitionSpeech.js';

package/dist/audio/hooks/useAudioOverlay.d.ts

@@ -0,0 +1,43 @@
+import type { AVO } from '../../emotion/types.js';
+import type { AudioPlannerSignals } from '../planner.js';
+import { type OverlayPhraseLibrary, type OverlayToken } from '../overlay.js';
+import type { AudioPolicy, AudioProof, AudioVerifier, SpeechSynthesisProvider, VoiceCatalog } from '../types.js';
+import { type SpeakOptions } from './useSpeechSynthesis.js';
+export interface UseAudioOverlayOptions {
+    provider: SpeechSynthesisProvider;
+    verifier?: AudioVerifier;
+    voices: VoiceCatalog;
+    policy: AudioPolicy;
+    signals?: AudioPlannerSignals;
+    defaults?: {
+        voiceId?: string;
+        groundedVoiceTag?: string;
+        defaultVoiceTag?: string;
+        temperature?: number;
+    };
+    phrases?: Partial<OverlayPhraseLibrary>;
+    bargeIn?: {
+        stream: MediaStream | null;
+        threshold?: number;
+        hangoverMs?: number;
+    };
+    volume?: number;
+    verificationMode?: 'before_playback' | 'after_playback' | 'never';
+    onProof?: (proof: AudioProof) => void;
+    onBargeIn?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface OverlaySpeakOptions extends SpeakOptions {
+    targetAffect?: AVO;
+}
+export interface UseAudioOverlayReturn {
+    isSynthesizing: boolean;
+    isSpeaking: boolean;
+    error: string | null;
+    lastProof: AudioProof | null;
+    speakToken: (token: OverlayToken, options?: OverlaySpeakOptions) => Promise<void>;
+    speakText: (text: string, options?: OverlaySpeakOptions) => Promise<void>;
+    cancel: () => void;
+}
+export declare function useAudioOverlay(options: UseAudioOverlayOptions): UseAudioOverlayReturn;
+//# sourceMappingURL=useAudioOverlay.d.ts.map

package/dist/audio/hooks/useAudioOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAudioOverlay.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useAudioOverlay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAqB,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,YAAY,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAMhF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAEzB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IAEpB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAE9B,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF,OAAO,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAExC,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IAEF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAElE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,YAAY,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7B,UAAU,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAmEtF"}

package/dist/audio/hooks/useAudioOverlay.js

@@ -0,0 +1,48 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { pickOverlayPhrase } from '../overlay.js';
+import { useSpeechSynthesis } from './useSpeechSynthesis.js';
+// =============================================================================
+// Hook
+// =============================================================================
+export function useAudioOverlay(options) {
+    const { provider, verifier, voices, policy, signals, defaults, phrases, bargeIn, volume, verificationMode, onProof, onBargeIn, onError, } = options;
+    const phraseIndexRef = useRef(0);
+    const overlayDefaults = useMemo(() => {
+        return {
+            ...defaults,
+            // Default to low temperature so overlay cues are stable and “assistant-like”.
+            temperature: defaults?.temperature ?? 0.2,
+        };
+    }, [defaults]);
+    const speech = useSpeechSynthesis({
+        provider,
+        verifier,
+        voices,
+        policy,
+        signals,
+        defaults: overlayDefaults,
+        bargeIn,
+        volume,
+        verificationMode,
+        onProof,
+        onBargeIn,
+        onError,
+    });
+    const speakToken = useCallback(async (token, overlaySpeakOptions) => {
+        const idx = phraseIndexRef.current++;
+        const text = pickOverlayPhrase({ token, library: phrases, index: idx });
+        await speech.speak(text, overlaySpeakOptions);
+    }, [speech, phrases]);
+    const speakText = useCallback(async (text, overlaySpeakOptions) => {
+        await speech.speak(text, overlaySpeakOptions);
+    }, [speech]);
+    return {
+        isSynthesizing: speech.isSynthesizing,
+        isSpeaking: speech.isSpeaking,
+        error: speech.error,
+        lastProof: speech.lastProof,
+        speakToken,
+        speakText,
+        cancel: speech.cancel,
+    };
+}

package/dist/audio/hooks/useAudioPlayer.d.ts

@@ -0,0 +1,14 @@
+export interface UseAudioPlayerOptions {
+    volume?: number;
+    onEnded?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface UseAudioPlayerReturn {
+    isPlaying: boolean;
+    error: string | null;
+    play: (source: Blob | string) => Promise<void>;
+    stop: () => void;
+    audioElement: HTMLAudioElement | null;
+}
+export declare function useAudioPlayer(options?: UseAudioPlayerOptions): UseAudioPlayerReturn;
+//# sourceMappingURL=useAudioPlayer.d.ts.map

package/dist/audio/hooks/useAudioPlayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAudioPlayer.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useAudioPlayer.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvC;AAMD,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,oBAAoB,CA2GxF"}