@phont-ai/subtitles 0.1.58 → 0.1.60

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { AnimationFetcher, PhontClient, LoginResponse, RegisterResponse, WordAnimationState } from '@phont-ai/subtitles-core';
 export { AnimationFetcher, LoginResponse, PhontClient, PhontClientOptions, PublishedAnimationResolver, RegisterResponse, VodMetadata, calculateAnimationState, createPublishedAnimationResolver, decodeAnimationUrl, subtitleManager } from '@phont-ai/subtitles-core';
-import React, { ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 
 interface PhontClientConfig {
     apiKey: string;
@@ -33,7 +34,7 @@ type EmotionAnimationUrls = Record<string, string>;
 /**
  * Provider component for animation config (URL-based system)
  */
-declare function AnimationConfigProvider({ children, customUrls, }: AnimationConfigProviderProps): React.JSX.Element;
+declare function AnimationConfigProvider({ children, customUrls, }: AnimationConfigProviderProps): React__default.JSX.Element;
 /**
  * Hook to access animation config
  */
@@ -45,7 +46,7 @@ declare function useAnimationConfig(): AnimationConfigContextValue;
  */
 
 interface PhontRootProps {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     /**
      * Phont Subtitles API origin (no trailing slash), e.g. `process.env.NEXT_PUBLIC_API_SUB_BASE_URL`.
      * When set, configures the published animation resolver to hit `{apiBaseUrl}/animations`.
@@ -57,7 +58,7 @@ interface PhontRootProps {
     /** Initial stylesheet name for resolver/emotion lookup (`default` | `children` in built-in registry) */
     defaultStylesheet?: string;
 }
-declare function PhontRoot({ children, apiBaseUrl, customEmotionUrls, defaultStylesheet, }: PhontRootProps): React.JSX.Element;
+declare function PhontRoot({ children, apiBaseUrl, customEmotionUrls, defaultStylesheet, }: PhontRootProps): React__default.JSX.Element;
 
 /**
  * React hook for the published animation resolver.
@@ -87,17 +88,24 @@ declare function configurePublishedAnimationFetcher(fetcher: AnimationFetcher):
  *
  * Returns a function: `(backendUrl, emotion) => resolvedUrl | null`
  *
- * Resolution order:
- *   1. backendUrl from segment (if truthy string)
- *   2. Published animation from API cache
- *   3. Hardcoded getAnimationUrlForEmotion from core
+ * Resolution order (Model A — backend is source of truth):
+ *   1. Per-segment `animation_url` from the backend. The backend embeds the
+ *      latest published URL for the segment's emotion at serialize time, so
+ *      this is the freshest and most specific value available.
+ *   2. Published animation from the `/animations` API cache. Legacy safety
+ *      net for old subtitles that didn't have `animation_url` baked in.
+ *   3. Hardcoded `getAnimationUrlForEmotion` from core.
+ *
+ * Note: only the query-string portion of the URL is read by the renderer.
+ * The URL origin (localhost vs. phont.ai vs. tenant subdomain) is
+ * irrelevant — animation URLs are parsed, not fetched.
  */
 declare function usePublishedAnimationResolver(): {
     /**
      * Resolve an animation URL.
      *
-     * Priority: published animation (always up-to-date) > baked-in segment URL > hardcoded mapping.
-     * Pass `stylesheetName` and `segmentEmotion` to look up the video's stylesheet first.
+     * Priority: per-segment `animation_url` > published cache > hardcoded mapping.
+     * Pass `stylesheetName` and `segmentEmotion` to control the published lookup.
      */
     resolve(backendUrl: string | undefined | null, emotion: string | null, opts?: {
         stylesheetName?: string | null;
@@ -117,63 +125,11 @@ interface StylesheetContextValue {
     isDefaultActive: boolean;
 }
 declare function StylesheetProvider({ children, defaultStylesheet, }: {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     defaultStylesheet?: string;
-}): React.JSX.Element;
+}): React__default.JSX.Element;
 declare function useStylesheet(): StylesheetContextValue;
 
-interface FontAxisConfig {
-    min: number;
-    max: number;
-    default: number;
-    cssProperty: string;
-    tag: string;
-    unit?: string;
-    description?: string;
-}
-interface OptionalAxisConfig {
-    min: number;
-    max: number;
-    default: number;
-    cssProperty: string;
-    tag: string;
-    description?: string;
-    usedBy?: string[];
-}
-interface VariableFontConfig {
-    name: string;
-    id: string;
-    family: string;
-    axes: {
-        weight: FontAxisConfig;
-        width: FontAxisConfig;
-    };
-    optionalAxes?: {
-        thinStroke?: OptionalAxisConfig;
-        ascenderHeight?: OptionalAxisConfig;
-    };
-    fallbacks?: string[];
-    loadCheck: string;
-    variationAxes?: string[];
-    mapping?: {
-        volume?: {
-            source?: string;
-            target?: string;
-            min: number;
-            max: number;
-            description?: string;
-        };
-        speechRate?: {
-            source?: string;
-            target?: string;
-            min: number;
-            max: number;
-            inverse?: boolean;
-            description?: string;
-        };
-    };
-}
-
 /**
  * PhontSubtitles Component
  *
@@ -191,12 +147,108 @@ interface PhontSubtitlesProps {
     isRTL?: boolean;
     phontClient?: PhontClient | null;
     className?: string;
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     subtitleAvailable?: boolean;
-    variableFontEnabled?: boolean;
-    variableFontConfig?: VariableFontConfig;
 }
-declare function PhontSubtitles({ vodId, currentTime, isPlaying, mode, language, maxExpression, threshold, isRTL, phontClient, className, style, subtitleAvailable, variableFontEnabled, variableFontConfig, }: PhontSubtitlesProps): React.JSX.Element | null;
+declare function PhontSubtitles({ vodId, currentTime, isPlaying, mode, language, maxExpression, threshold, isRTL, phontClient, className, style, subtitleAvailable, }: PhontSubtitlesProps): React__default.JSX.Element | null;
+
+declare function PhontSubtitlesWithUrlAnimations({ segment, currentTime, isPlaying, maxExpression, threshold, className, style, nextSegment, forceMobile, fontFallbackMode, disablePublishedAnimationFetch, }: {
+    segment: any;
+    currentTime: number;
+    isPlaying?: boolean;
+    maxExpression?: number;
+    threshold?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    nextSegment?: any;
+    forceMobile?: boolean;
+    fontFallbackMode?: boolean;
+    disablePublishedAnimationFetch?: boolean;
+}): React__default.JSX.Element;
+
+declare function useUrlAnimations({ segment, currentTime, maxExpression, threshold, nextSegmentStartTime, extendedEndTime, transparentUntilSpoken, disablePublishedAnimationFetch, stylesheetName: stylesheetNameProp, }: {
+    segment: any;
+    currentTime: number;
+    maxExpression?: number;
+    threshold?: number;
+    nextSegmentStartTime?: number | null;
+    extendedEndTime?: number | null;
+    transparentUntilSpoken?: boolean;
+    disablePublishedAnimationFetch?: boolean;
+    stylesheetName?: string | null;
+}): {
+    text: string;
+    words: never[];
+    emotion: string;
+    emotionIntensity: number;
+    fontFamily: string;
+    currentWordIndex: number;
+    startTime: number;
+    endTime: number;
+    isActive: boolean;
+    hasMergedSubtitles: boolean;
+    debug: {
+        segmentFontSize?: undefined;
+        finalWeight?: undefined;
+        mergedRange?: undefined;
+        currentTime?: undefined;
+        finalIsActive?: undefined;
+    };
+    extendedMergedEndTime?: undefined;
+} | {
+    text: string;
+    words: {
+        word: any;
+        start: any;
+        end: any;
+        animationEnd: any;
+        isActive: boolean;
+        emotion: string;
+        emotionIntensity: number;
+        fontFamily: string;
+        emphasisEffect: null;
+        strongEmphasis: null;
+        animationParameters: Record<string, any>;
+        effects: {
+            standardEmphasis: null;
+            strongEmphasis: null;
+        };
+        emotionCategory: string | null;
+        volume: any;
+    }[];
+    emotion: string;
+    emotionIntensity: number;
+    fontFamily: string;
+    currentWordIndex: number;
+    startTime: any;
+    endTime: any;
+    extendedMergedEndTime: any;
+    isActive: boolean;
+    hasMergedSubtitles: boolean;
+    debug: {
+        segmentFontSize: number;
+        finalWeight: number;
+        mergedRange: null;
+        currentTime: number;
+        finalIsActive: boolean;
+    };
+};
+
+declare function WordRenderer({ text, words, fontFamily, className, style, debugMode, currentTime, mergedSubtitleStart, mergedSubtitleEnd, mergedSubtitleExtendedEnd, hasMultipleSubtitles, fontFallbackMode, gts, }: {
+    text?: string;
+    words?: any[];
+    fontFamily?: string;
+    className?: string;
+    style?: React__default.CSSProperties;
+    debugMode?: boolean;
+    currentTime?: number;
+    mergedSubtitleStart?: number | null;
+    mergedSubtitleEnd?: number | null;
+    mergedSubtitleExtendedEnd?: number | null;
+    hasMultipleSubtitles?: boolean;
+    fontFallbackMode?: boolean;
+    gts?: number;
+}): React__default.JSX.Element | null;
 
 /**
  * SDK Authentication Hook
@@ -248,7 +300,7 @@ interface SDKAuthProps {
     apiBaseUrl?: string;
     onAuthenticated?: (client: any) => void;
 }
-declare function SDKAuth({ apiBaseUrl, onAuthenticated }: SDKAuthProps): React.JSX.Element;
+declare function SDKAuth({ apiBaseUrl, onAuthenticated }: SDKAuthProps): React__default.JSX.Element;
 
 /**
  * SDK Animation Hook
@@ -605,11 +657,11 @@ interface PhontVideoPlayerProps extends Omit<PhontSubtitlesProps, 'currentTime'
     /** Custom update interval in ms */
     updateInterval?: number;
     /** Children to render (your video player UI) */
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     /** Subtitle container className */
     subtitleClassName?: string;
     /** Subtitle container style */
-    subtitleStyle?: React.CSSProperties;
+    subtitleStyle?: React__default.CSSProperties;
 }
 /**
  * All-in-one component for video + PHONT subtitles.
@@ -617,7 +669,7 @@ interface PhontVideoPlayerProps extends Omit<PhontSubtitlesProps, 'currentTime'
  * Automatically syncs with your video player and renders subtitles.
  * Works with HTML5, Bitmovin, Shaka, Video.js, 3Q Video Player, or any custom adapter.
  */
-declare function PhontVideoPlayer(props: PhontVideoPlayerProps): React.JSX.Element;
+declare function PhontVideoPlayer(props: PhontVideoPlayerProps): React__default.JSX.Element;
 
 interface PositionConfig {
     bottomVh: number;
@@ -643,7 +695,7 @@ interface SoundbiteContainerProps {
     isPhontControlsOpen?: boolean;
     config?: Partial<PositionConfig>;
 }
-declare function SoundbiteContainer({ isVodMode, boxSize, width, height, bottomVh, intensity, hideWhenPanelsOpen, isMetaPanelOpen, isPhontControlsOpen, config }: SoundbiteContainerProps): React.JSX.Element | null;
+declare function SoundbiteContainer({ isVodMode, boxSize, width, height, bottomVh, intensity, hideWhenPanelsOpen, isMetaPanelOpen, isPhontControlsOpen, config }: SoundbiteContainerProps): React__default.JSX.Element | null;
 
 /**
  * PlayerTestSuite - Standalone Test Component
@@ -681,7 +733,7 @@ interface PlayerTestSuiteProps {
     threeqDataId?: string;
 }
 declare function PlayerTestSuite({ defaultVodId, // Default to Pooh_Compilation
-defaultPlayer, apiEndpoint, bitmovinLicenseKey: propBitmovinLicenseKey, threeqDataId, }: PlayerTestSuiteProps): React.JSX.Element;
+defaultPlayer, apiEndpoint, bitmovinLicenseKey: propBitmovinLicenseKey, threeqDataId, }: PlayerTestSuiteProps): React__default.JSX.Element;
 
 /**
  * Animation Mode Toggle Component
@@ -694,15 +746,45 @@ interface AnimationModeToggleProps {
     animationMode: AnimationMode;
     setAnimationMode: (mode: AnimationMode) => void;
 }
-declare function AnimationModeToggle({ animationMode, setAnimationMode, }: AnimationModeToggleProps): React.JSX.Element;
+declare function AnimationModeToggle({ animationMode, setAnimationMode, }: AnimationModeToggleProps): React__default.JSX.Element;
 
 /**
- * Phont Controls - Composition Component
- * SDK version - Aggregates all Phont subtitle controls (GTS, Translation, Mode, Toggles, Animation Config)
- * Matches app/components/phont-controls/PhontControls.jsx but with additional animation controls and settings panel
+ * Production Phont Controls — same UI as phont.ai /video fullscreen.
+ * Stage Content Manager fullscreen should import this from @phont-ai/subtitles.
  */
 
 interface PhontControlsProps {
+    isVisible?: boolean;
+    onPanelMouseEnter?: () => void;
+    onPanelMouseLeave?: () => void;
+    isLive?: boolean;
+    currentVideoId?: string | null;
+    gts: number;
+    setGTS: (value: number) => void;
+    threshold: number;
+    maxExpression: number;
+    subtitleLanguage?: string | null;
+    availableLanguages?: Record<string, string>;
+    currentSubtitleLanguage?: string | null;
+    handleLanguageChange?: (language: string | null) => void;
+    isTranslating?: boolean;
+    translatingToLanguage?: string | null;
+    translationProvider?: string | null;
+    translationModel?: string | null;
+    /** Accepted for API compat; production UI is word-by-word only. */
+    animationMode?: AnimationMode;
+    setAnimationMode?: (mode: AnimationMode) => void;
+    toggles: boolean[];
+    handleToggle: (index: number) => void;
+}
+declare function PhontControls({ isVisible, onPanelMouseEnter, onPanelMouseLeave, isLive, currentVideoId, gts, setGTS, threshold, maxExpression, subtitleLanguage, availableLanguages, currentSubtitleLanguage, handleLanguageChange, isTranslating, translatingToLanguage, translationProvider, translationModel, toggles, handleToggle, }: PhontControlsProps): React__default.JSX.Element | null;
+
+/**
+ * Dev-only Phont Controls — PlayerTestSuite / internal testing.
+ * Production integrators (Stage, html5 demo) should use PhontControls instead.
+ */
+
+interface PhontControlsDevProps {
     isVisible?: boolean;
     controlsVisible?: boolean;
     onControlsVisibilityChange?: (visible: boolean) => void;
@@ -742,7 +824,50 @@ interface PhontControlsProps {
     onLogout?: () => void;
     username?: string | null;
 }
-declare function PhontControls({ isVisible, controlsVisible: externalControlsVisible, onControlsVisibilityChange, isLive, currentVideoId, gts, setGTS, subtitleLanguage, availableLanguages, currentSubtitleLanguage, handleLanguageChange, isTranslating, translatingToLanguage, translationProvider, translationModel, animationMode, setAnimationMode, toggles, handleToggle, customAnimationUrl, setCustomAnimationUrl, emotionMappings, setEmotionMappings, showSettingsPanel, selectedPlayer, setSelectedPlayer, players, vodId, setVodId, vods, onLogout, username, }: PhontControlsProps): React.JSX.Element | null;
+declare function PhontControlsDev({ isVisible, controlsVisible: externalControlsVisible, onControlsVisibilityChange, isLive, currentVideoId, gts, setGTS, subtitleLanguage, availableLanguages, currentSubtitleLanguage, handleLanguageChange, isTranslating, translatingToLanguage, translationProvider, translationModel, animationMode, setAnimationMode, toggles, handleToggle, customAnimationUrl, setCustomAnimationUrl, emotionMappings, setEmotionMappings, showSettingsPanel, selectedPlayer, setSelectedPlayer, players, vodId, setVodId, vods, onLogout, username, }: PhontControlsDevProps): React__default.JSX.Element | null;
+
+/**
+ * GTS (Global Tone & Style) Utilities
+ * SDK version - calculates threshold and maxExpression from GTS value
+ * Matches the logic from app/context/GTSContext.js
+ */
+/**
+ * Calculate emotion threshold from GTS value
+ * Threshold: Uses RENDERING_CONTROL values (0.3 at GTS=0, 0.0 at GTS=1)
+ */
+declare function calculateThreshold(gts: number): number;
+/**
+ * Calculate max expression from GTS value
+ * Max Expression: M(G) = 0.20 + 0.80*G (20% at 0, 100% at 1)
+ */
+declare function calculateMaxExpression(gts: number): number;
+
+/** Default translation languages — same list as SDK integration demos. */
+declare const PHONT_DEFAULT_LANGUAGES: Record<string, string>;
+interface UsePhontVodControlsOptions {
+    vodId: string | null;
+    phontClient: PhontClient | null;
+    initialGts?: number;
+    closedCaptionsOn?: boolean;
+    availableLanguages?: Record<string, string>;
+}
+/**
+ * Wires GTS, translation, and CC toggles for VOD playback.
+ * Use with PhontSubtitles + PhontControls for Stage / integrator parity.
+ */
+declare function usePhontVodControls({ vodId, phontClient, initialGts, closedCaptionsOn, availableLanguages, }: UsePhontVodControlsOptions): {
+    gts: number;
+    setGTS: React.Dispatch<React.SetStateAction<number>>;
+    threshold: number;
+    maxExpression: number;
+    toggles: boolean[];
+    handleToggle: (index: number) => void;
+    subtitleLanguage: string | null;
+    handleLanguageChange: (lang: string | null) => void;
+    isTranslating: boolean;
+    translatingToLanguage: string | null;
+    availableLanguages: Record<string, string>;
+};
 
 /**
  * GTS (Global Tone & Style) Slider Component
@@ -756,7 +881,7 @@ interface GTSSliderProps {
     threshold: number;
     maxExpression: number;
 }
-declare function GTSSlider({ gts, setGTS, threshold, maxExpression }: GTSSliderProps): React.JSX.Element;
+declare function GTSSlider({ gts, setGTS, threshold, maxExpression }: GTSSliderProps): React__default.JSX.Element;
 
 /**
  * Translation Dropdown Component
@@ -774,7 +899,7 @@ interface TranslationDropdownProps {
     translationProvider?: string;
     translationModel?: string;
 }
-declare function TranslationDropdown({ subtitleLanguage, availableLanguages, currentSubtitleLanguage, onLanguageChange, isTranslating, translatingToLanguage, translationProvider, translationModel, }: TranslationDropdownProps): React.JSX.Element;
+declare function TranslationDropdown({ subtitleLanguage, availableLanguages, currentSubtitleLanguage, onLanguageChange, isTranslating, translatingToLanguage, translationProvider, translationModel, }: TranslationDropdownProps): React__default.JSX.Element;
 
 /**
  * Reusable Toggle Switch Component
@@ -787,7 +912,7 @@ interface ToggleSwitchProps {
     label: string;
     onToggle: () => void;
 }
-declare function ToggleSwitch({ isOn, label, onToggle }: ToggleSwitchProps): React.JSX.Element;
+declare function ToggleSwitch({ isOn, label, onToggle }: ToggleSwitchProps): React__default.JSX.Element;
 
 /**
  * Animation URL Config Component
@@ -800,6 +925,6 @@ interface AnimationUrlConfigProps {
     emotionMappings: Partial<EmotionAnimationUrls>;
     setEmotionMappings: (mappings: Partial<EmotionAnimationUrls>) => void;
 }
-declare function AnimationUrlConfig({ customAnimationUrl, setCustomAnimationUrl, emotionMappings, setEmotionMappings, }: AnimationUrlConfigProps): React.JSX.Element;
+declare function AnimationUrlConfig({ customAnimationUrl, setCustomAnimationUrl, emotionMappings, setEmotionMappings, }: AnimationUrlConfigProps): React__default.JSX.Element;
 
-export { AnimationConfigProvider, type AnimationConfigProviderProps, type AnimationMode, AnimationModeToggle, type AnimationModeToggleProps, AnimationUrlConfig, type AnimationUrlConfigProps, type BitmovinPlayer, BitmovinPlayerAdapter, type EmotionAnimationUrls, GTSSlider, type GTSSliderProps, HTML5VideoAdapter, type PhontClientConfig, PhontControls, type PhontControlsProps, PhontRoot, type PhontRootProps, PhontSubtitles, type PhontSubtitlesProps, PhontVideoPlayer, type PhontVideoPlayerProps, type PlayerAdapter, PlayerTestSuite, type PlayerTestSuiteProps, type PlayerType, SDKAuth, type SDKAuthProps, type SDKAuthState, type ShakaPlayer, ShakaPlayerAdapter, SoundbiteContainer, StylesheetProvider, type ThreeQPlayer, ThreeQPlayerAdapter, ToggleSwitch, type ToggleSwitchProps, TranslationDropdown, type TranslationDropdownProps, type UsePlayerSyncOptions, type UsePlayerSyncResult, type UseSDKAnimationOptions, type UseVideoPlayerOptions, type VideoJSPlayer, VideoJSPlayerAdapter, buildPhontAnimationRequestHeaders, configurePublishedAnimationFetcher, createPhontAnimationFetcher, useAnimationConfig, usePlayerSync, usePublishedAnimationResolver, useSDKAnimation, useSDKAuth, useStylesheet, useVideoPlayer };
+export { AnimationConfigProvider, type AnimationConfigProviderProps, type AnimationMode, AnimationModeToggle, type AnimationModeToggleProps, AnimationUrlConfig, type AnimationUrlConfigProps, type BitmovinPlayer, BitmovinPlayerAdapter, type EmotionAnimationUrls, GTSSlider, type GTSSliderProps, HTML5VideoAdapter, PHONT_DEFAULT_LANGUAGES, type PhontClientConfig, PhontControls, PhontControlsDev, type PhontControlsDevProps, type PhontControlsProps, PhontRoot, type PhontRootProps, PhontSubtitles, type PhontSubtitlesProps, PhontSubtitlesWithUrlAnimations, PhontVideoPlayer, type PhontVideoPlayerProps, type PlayerAdapter, PlayerTestSuite, type PlayerTestSuiteProps, type PlayerType, SDKAuth, type SDKAuthProps, type SDKAuthState, type ShakaPlayer, ShakaPlayerAdapter, SoundbiteContainer, StylesheetProvider, type ThreeQPlayer, ThreeQPlayerAdapter, ToggleSwitch, type ToggleSwitchProps, TranslationDropdown, type TranslationDropdownProps, type UsePhontVodControlsOptions, type UsePlayerSyncOptions, type UsePlayerSyncResult, type UseSDKAnimationOptions, type UseVideoPlayerOptions, type VideoJSPlayer, VideoJSPlayerAdapter, WordRenderer, buildPhontAnimationRequestHeaders, calculateMaxExpression, calculateThreshold, configurePublishedAnimationFetcher, createPhontAnimationFetcher, useAnimationConfig, usePhontVodControls, usePlayerSync, usePublishedAnimationResolver, useSDKAnimation, useSDKAuth, useStylesheet, useUrlAnimations, useVideoPlayer };