@supernal/tts-widget 1.0.0

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@supernal/tts-widget",
+  "version": "1.0.0",
+  "description": "Embeddable TTS widget for blogs and websites",
+  "main": "./dist/widget.js",
+  "module": "./dist/widget.js",
+  "types": "./dist/widget.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/widget.d.ts",
+      "import": "./dist/widget.js",
+      "default": "./dist/widget.js"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js",
+      "default": "./dist/loader.js"
+    },
+    "./widget.js": {
+      "types": "./dist/widget.d.ts",
+      "import": "./dist/widget.js",
+      "default": "./dist/widget.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./widget.css": "./dist/widget.css",
+    "./dist/widget.css": "./dist/widget.css"
+  },
+  "files": [
+    "dist",
+    "src/react",
+    "README.md",
+    "MIGRATION.md",
+    "dist/supernal-tts-logo.svg"
+  ],
+  "scripts": {
+    "build": "npm run build:ts && npm run build:loader && npm run build:bundle && npm run build:css",
+    "build:ts": "tsc",
+    "build:loader": "esbuild src/loader.ts --bundle --minify --sourcemap --outfile=dist/loader.js --format=esm --external:none --define:__PACKAGE_VERSION__='\"1.3.1\"'",
+    "build:bundle": "esbuild src/widget.ts --bundle --minify --sourcemap --outfile=dist/widget.js --format=esm --external:none",
+    "build:css": "cp src/widget.css dist/widget.css",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "tts",
+    "text-to-speech",
+    "widget",
+    "audio",
+    "speech",
+    "supernal",
+    "accessibility",
+    "voice"
+  ],
+  "author": "Supernal Intelligence",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/supernalintelligence/supernal-nova.git",
+    "directory": "families/supernal-tts/packages/@supernal-tts/widget"
+  },
+  "homepage": "https://www.tts.supernal.ai",
+  "bugs": {
+    "url": "https://github.com/supernalintelligence/supernal-tts/issues"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/minimatch": "^5.1.2",
+    "@types/react": "^18.0.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/react/TTSInitializer.tsx

@@ -0,0 +1,163 @@
+/**
+ * TTSInitializer - React component for initializing Supernal TTS widget
+ *
+ * Usage:
+ *   import { TTSInitializer } from '@supernal/tts-widget/react';
+ *   import '@supernal/tts-widget/widget.css';
+ *
+ *   // In your root layout or _app.tsx
+ *   <TTSInitializer
+ *     apiUrl="https://www.tts.supernal.ai"
+ *     apiKey={process.env.NEXT_PUBLIC_TTS_API_KEY}
+ *     mode="auto"      // Try CDN, fallback to bundled (default)
+ *     version="major"  // Load latest v1.x.x (default)
+ *   />
+ */
+
+import * as React from 'react';
+import { useEffect, useState } from 'react';
+
+export interface TTSInitializerProps {
+  apiUrl?: string;
+  apiKey?: string;
+  provider?: string;
+  voice?: string;
+  speed?: number;  // Default speed for all widgets (1.0 = normal)
+  devMode?: boolean;
+  clientSideSpeed?: boolean;
+  showBranding?: boolean;
+
+  // New smart loader options
+  /**
+   * Loading mode:
+   * - 'auto': Try CDN, fallback to bundled (default, recommended)
+   * - 'cdn': Force CDN load, error if unavailable
+   * - 'bundled': Always use bundled version (CSP-safe)
+   */
+  mode?: 'auto' | 'cdn' | 'bundled';
+
+  /**
+   * Version strategy:
+   * - 'major': Load latest v1.x.x (default, recommended)
+   * - 'latest': Load absolute latest (risky)
+   * - '1.3.0': Pin to specific version
+   */
+  version?: 'major' | 'latest' | string;
+
+  /**
+   * CDN fetch timeout in milliseconds (default: 3000)
+   */
+  timeout?: number;
+
+  /**
+   * Callback when CDN load fails and fallback is used
+   */
+  onCdnFail?: (error: Error) => void;
+
+  /**
+   * Callback when CDN load succeeds
+   */
+  onCdnSuccess?: () => void;
+}
+
+export default function TTSInitializer({
+  apiUrl = 'https://www.tts.supernal.ai',
+  apiKey,
+  provider = 'openai',
+  voice = 'alloy',
+  speed = 1.0,
+  devMode,
+  clientSideSpeed = true,
+  showBranding = true,
+  mode = 'auto',
+  version = 'major',
+  timeout = 3000,
+  onCdnFail,
+  onCdnSuccess,
+}: TTSInitializerProps) {
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Only run on client side
+    if (typeof window === 'undefined') return;
+
+    let isMounted = true;
+
+    // Note: Users should import CSS separately:
+    // import '@supernal/tts-widget/widget.css';
+
+    // Load widget using smart loader
+    const loadWidget = async () => {
+      try {
+        const loaderModule = await import('../loader');
+        const { WidgetLoader } = loaderModule;
+
+        const widget = await WidgetLoader.load({
+          mode,
+          version,
+          timeout,
+          onCdnFail: (err) => {
+            console.warn('[TTS Widget] CDN load failed, using bundled version:', err.message);
+            onCdnFail?.(err);
+          },
+          onCdnSuccess: () => {
+            console.log('[TTS Widget] Successfully loaded from CDN');
+            onCdnSuccess?.();
+          },
+        });
+
+        // Only initialize if component is still mounted
+        if (!isMounted) return;
+
+        // Initialize widget if not already initialized
+        if (!(window as any).SupernalTTSInstance) {
+          widget.init({
+            apiUrl,
+            apiKey,
+            provider,
+            voice,
+            speed,
+            devMode,
+            clientSideSpeed,
+            showBranding,
+          });
+        }
+      } catch (err) {
+        if (!isMounted) return;
+
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        console.error('[TTS Widget] Failed to load:', errorMessage);
+        setError(errorMessage);
+      }
+    };
+
+    loadWidget();
+
+    // Cleanup function
+    return () => {
+      isMounted = false;
+      // Don't remove CSS or instance - they should persist across component unmounts
+    };
+  }, [apiUrl, apiKey, provider, voice, speed, devMode, clientSideSpeed, showBranding, mode, version, timeout]);
+
+  // Optionally render error state
+  if (error && devMode) {
+    return React.createElement('div', {
+      style: {
+        padding: '12px',
+        background: '#fee',
+        border: '1px solid #fcc',
+        borderRadius: '4px',
+        color: '#c33',
+        fontFamily: 'monospace',
+        fontSize: '12px',
+      }
+    }, [
+      React.createElement('strong', { key: 'title' }, 'TTS Widget Error: '),
+      error
+    ]);
+  }
+
+  return null; // This component doesn't render anything in production
+}
+

package/src/react/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Supernal TTS Widget - React Components
+ * 
+ * Provides React-specific components for easy integration
+ */
+
+export { default as TTSInitializer, type TTSInitializerProps } from './TTSInitializer';
+
+// Also provide default export for convenience
+export { default } from './TTSInitializer';
+