@pie-players/tts-client-server 0.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# @pie-players/tts-client-server
+
+## 0.2.0
+
+### Minor Changes
+
+- 8584a3f: Initial 0.1.0 release of PIE section player and dependencies
+
+  This release includes:
+
+  ## New Packages
+
+  ### Section Player
+
+  - **@pie-players/pie-section-player** - QTI 3.0 compliant section player with support for passages, rubric blocks, page/item modes, and comprehensive tooling integration
+
+  ### Player Variants
+
+  - **@pie-players/pie-esm-player** - ESM-based player for modern module loading
+  - **@pie-players/pie-fixed-player** - Fixed player for static content
+  - **@pie-players/pie-iife-player** - IIFE player for bundle-based loading
+  - **@pie-players/pie-inline-player** - Inline player for embedded scenarios
+
+  ### Tools
+
+  - **@pie-players/pie-section-tools-toolbar** - Section-level toolbar for assessment tools
+  - **@pie-players/pie-tool-answer-eliminator** - Answer elimination tool with element-level state tracking
+  - **@pie-players/pie-tool-tts-inline** - Inline text-to-speech controls
+
+  ### Core Libraries
+
+  - **@pie-players/pie-assessment-toolkit** - Core toolkit with tool coordination, TTS services, and accessibility features
+  - **@pie-players/pie-players-shared** - Shared types and utilities
+  - **@pie-players/tts-client-server** - Client-side TTS provider for server API integration
+  - **@pie-players/pie-calculator-desmos** - Desmos calculator provider for graphing and scientific calculators
+
+  ## Publishing Fixes
+
+  All packages now properly configured for npm publishing:
+
+  - ✅ ESM-only format (no UMD mixing)
+  - ✅ CDN fields (unpkg/jsdelivr) for browser loading
+  - ✅ Correct exports configuration
+  - ✅ Public access configured
+  - ✅ TypeScript declarations included
+
+  ## Features
+
+  ### Section Player
+
+  - QTI 3.0 section structure support
+  - Passage handling with deduplication
+  - Rubric blocks (stimulus, instructions, rubric classes)
+  - Page mode (all items visible) and item mode (one at a time)
+  - Multiple layout options (split-panel, vertical)
+  - Session management and restoration
+  - Comprehensive event system
+
+  ### Assessment Toolkit
+
+  - Tool coordination system
+  - TTS integration (Browser and Polly providers)
+  - Answer eliminator with element-level state
+  - Accessibility catalog support
+  - Highlight coordination
+
+  ### Element Loading
+
+  - Multiple player types (ESM, IIFE, Fixed, Inline)
+  - Element pre-loading optimization
+  - Import map support
+  - Local ESM CDN for testing
+
+  ## Development Tools
+
+  - Local ESM CDN plugin for testing packages before publishing
+  - Section-demos app with UI toggles for different player modes
+  - Comprehensive testing infrastructure

package/README.md

@@ -0,0 +1,219 @@
+# @pie-players/tts-client-server
+
+Client-side TTS provider that calls a server API for synthesis with speech marks support.
+
+## Overview
+
+This package provides a browser-side TTS provider that offloads synthesis to a server API. The server handles provider selection (AWS Polly, Google Cloud TTS, etc.) and credential management, while the client plays audio and coordinates word highlighting.
+
+## Features
+
+- ✅ **Server-Side Synthesis** - Keeps credentials secure on server
+- ✅ **Speech Marks** - Precise word-level timing from server
+- ✅ **Multiple Providers** - Server can use Polly, Google, ElevenLabs, etc.
+- ✅ **Word Highlighting** - 50ms polling for smooth synchronization
+- ✅ **Audio Playback** - HTMLAudioElement with pause/resume
+- ✅ **Blob URLs** - Efficient memory management
+
+## Installation
+
+```bash
+npm install @pie-players/tts-client-server
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { ServerTTSProvider } from '@pie-players/tts-client-server';
+import { TTSService } from '@pie-players/pie-assessment-toolkit';
+
+const provider = new ServerTTSProvider();
+
+const ttsService = new TTSService();
+await ttsService.initialize(provider, {
+  apiEndpoint: '/api/tts',  // Your SvelteKit API route
+  provider: 'polly',         // Server-side provider to use
+  voiceId: 'Joanna',
+  language: 'en-US',
+});
+```
+
+### With Authentication
+
+```typescript
+await ttsService.initialize(provider, {
+  apiEndpoint: '/api/tts',
+  provider: 'polly',
+  authToken: 'your-jwt-token',
+  organizationId: 'org-123',
+});
+```
+
+### Speak with Word Highlighting
+
+```typescript
+// The provider automatically coordinates word highlighting
+await ttsService.speak('Hello world, this is a test.', {
+  contentElement: document.getElementById('content'),
+});
+```
+
+## API Requirements
+
+The server API must implement two endpoints:
+
+### POST `/api/tts/synthesize`
+
+**Request:**
+```json
+{
+  "text": "Hello world",
+  "provider": "polly",
+  "voice": "Joanna",
+  "language": "en-US",
+  "rate": 1.0,
+  "includeSpeechMarks": true
+}
+```
+
+**Response:**
+```json
+{
+  "audio": "base64-encoded-audio",
+  "contentType": "audio/mpeg",
+  "speechMarks": [
+    { "time": 0, "type": "word", "start": 0, "end": 5, "value": "Hello" },
+    { "time": 340, "type": "word", "start": 6, "end": 11, "value": "world" }
+  ],
+  "metadata": {
+    "providerId": "aws-polly",
+    "voice": "Joanna",
+    "duration": 1.5,
+    "charCount": 11,
+    "cached": false
+  }
+}
+```
+
+### GET `/api/tts/voices`
+
+**Response:**
+```json
+{
+  "voices": [
+    {
+      "id": "Joanna",
+      "name": "Joanna",
+      "language": "English",
+      "languageCode": "en-US",
+      "gender": "female",
+      "quality": "neural"
+    }
+  ]
+}
+```
+
+## SvelteKit Implementation Example
+
+See the implementation guide in [tts-server-api-architecture.md](../../docs/tts-server-api-architecture.md).
+
+Example route structure:
+```
+apps/example/src/routes/api/tts/
+├── synthesize/+server.ts
+└── voices/+server.ts
+```
+
+## Configuration
+
+### ServerTTSProviderConfig
+
+```typescript
+interface ServerTTSProviderConfig {
+  apiEndpoint: string;        // API base URL (required)
+  provider?: string;          // Server provider ('polly', 'google', etc.)
+  authToken?: string;         // JWT or API key
+  organizationId?: string;    // For multi-tenant setups
+  headers?: Record<string, string>;  // Custom headers
+  voiceId?: string;           // Voice ID
+  language?: string;          // Language code
+  rate?: number;              // Speech rate (0.25-4.0)
+  volume?: number;            // Volume (0-1)
+}
+```
+
+## How It Works
+
+1. **Client calls** `speak(text)`
+2. **Provider POSTs** to `/api/tts/synthesize` with text
+3. **Server synthesizes** using provider (Polly, Google, etc.)
+4. **Server returns** base64 audio + speech marks
+5. **Client converts** base64 to Blob URL
+6. **Client plays** audio via HTMLAudioElement
+7. **Client polls** audio time every 50ms
+8. **Client fires** word boundary callbacks at correct times
+9. **TTSService** highlights words in DOM
+
+## Word Highlighting Synchronization
+
+The provider uses a polling-based approach for reliable synchronization:
+
+```typescript
+// Every 50ms, check current audio time
+const currentTime = audio.currentTime * 1000; // Convert to ms
+
+// Find words that should be highlighted
+for (const timing of wordTimings) {
+  if (currentTime >= timing.time) {
+    onWordBoundary('', timing.charIndex);
+  }
+}
+```
+
+This is **much more reliable** than browser's `onboundary` events (which are broken in Safari and unreliable in Chrome).
+
+## Memory Management
+
+The provider automatically manages Blob URLs:
+
+- Creates Blob URL from base64 audio
+- Plays audio from Blob URL
+- Revokes Blob URL when done (frees memory)
+- Cleans up on stop/error
+
+## Error Handling
+
+```typescript
+try {
+  await ttsService.speak('Hello world');
+} catch (error) {
+  console.error('TTS failed:', error.message);
+  // Fallback to browser TTS or show error
+}
+```
+
+## Browser Compatibility
+
+- ✅ Chrome/Edge (latest)
+- ✅ Firefox (latest)
+- ✅ Safari (latest)
+- ✅ Mobile browsers
+
+Requires:
+- `HTMLAudioElement` API
+- `fetch` API
+- `URL.createObjectURL`
+- `atob` for base64 decoding
+
+## Performance
+
+- **Audio caching:** Server-side (Redis)
+- **Blob URLs:** Efficient memory usage
+- **50ms polling:** Smooth highlighting without jank
+- **Parallel requests:** Audio + marks fetched together
+
+## License
+
+MIT

package/dist/ServerTTSProvider.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ServerTTSProvider - Client-side TTS provider that calls server API
+ *
+ * Provides high-quality TTS by calling a server-side API that uses
+ * providers like AWS Polly, Google Cloud TTS, etc.
+ * Returns audio with precise word-level timing (speech marks).
+ */
+import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, TTSProviderCapabilities } from "@pie-players/pie-tts";
+/**
+ * Configuration for ServerTTSProvider
+ */
+export interface ServerTTSProviderConfig extends TTSConfig {
+    /** API endpoint base URL (e.g., '/api/tts' or 'https://api.example.com/tts') */
+    apiEndpoint: string;
+    /** Provider to use on server ('polly', 'google', 'elevenlabs', etc.) */
+    provider?: string;
+    /** Authentication token or API key */
+    authToken?: string;
+    /** Custom headers for API requests */
+    headers?: Record<string, string>;
+    /** Language code */
+    language?: string;
+    /** Volume level 0-1 */
+    volume?: number;
+    /**
+     * Validate API endpoint availability during initialization (slower but safer)
+     *
+     * @extension Performance vs safety tradeoff
+     * @default false (fast initialization, fail on first synthesis if unavailable)
+     * @note When true, adds 100-500ms to initialization time
+     */
+    validateEndpoint?: boolean;
+}
+/**
+ * Server TTS Provider
+ *
+ * Client-side provider that calls a server API for TTS synthesis.
+ * The server handles provider selection (Polly, Google, etc.) and credential management.
+ */
+export declare class ServerTTSProvider implements ITTSProvider {
+    readonly providerId = "server-tts";
+    readonly providerName = "Server TTS";
+    readonly version = "1.0.0";
+    private config;
+    /**
+     * Initialize the server TTS provider.
+     *
+     * This is designed to be fast by default (no API calls).
+     * Set validateEndpoint: true in config to test API availability during initialization.
+     *
+     * @performance Default: <10ms, With validation: 100-500ms
+     */
+    initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
+    /**
+     * Test if API endpoint is available (with timeout).
+     *
+     * @performance 100-500ms depending on network
+     */
+    private testAPIAvailability;
+    supportsFeature(feature: TTSFeature): boolean;
+    getCapabilities(): TTSProviderCapabilities;
+    destroy(): void;
+}
+//# sourceMappingURL=ServerTTSProvider.d.ts.map

package/dist/ServerTTSProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerTTSProvider.d.ts","sourceRoot":"","sources":["../src/ServerTTSProvider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACX,YAAY,EACZ,0BAA0B,EAC1B,SAAS,EACT,UAAU,EACV,uBAAuB,EACvB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,SAAS;IACzD,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IAEpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC3B;AAiXD;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACrD,QAAQ,CAAC,UAAU,gBAAgB;IACnC,QAAQ,CAAC,YAAY,gBAAgB;IACrC,QAAQ,CAAC,OAAO,WAAW;IAE3B,OAAO,CAAC,MAAM,CAAwC;IAEtD;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAsBxE;;;;OAIG;YACW,mBAAmB;IAiCjC,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO;IAgB7C,eAAe,IAAI,uBAAuB;IAY1C,OAAO,IAAI,IAAI;CAGf"}