@namiml/web-sdk/dist/utils/tts.d.ts

Subscription monetization infrastructure — drop-in SDK with no-code paywalls, onboarding flows, A/B testing for web

/**
 * Text-to-speech for the Nami Web SDK.
 *
 * Speech requests are SDK-controlled and must never break paywall rendering.
 *
 * The feature layer below is platform neutral: it builds initial paywall
 * composites, speaks focused labels, gates speech during media playback, and
 * cleans up on navigation. Actual speech is owned by explicit engine adapters
 * where a programmable engine is reliable. Some TV runtimes also speak focused
 * controls through system accessibility; for those runtimes the SDK aligns
 * labels and lets the platform own focus speech instead of starting a second
 * programmable utterance for the same focus event.
 */
import { type TComponent, type TPages } from '@namiml/sdk-core';
import type { PaywallContextProvider } from '../components/ContextProvider';
type TtsRequestPriority = 'low' | 'normal' | 'high';
type SpeakReason = 'composite' | 'focus' | 'manual';
type SpeakOptions = {
    interrupt?: boolean;
    reason?: SpeakReason;
    transactionId?: number;
    element?: Element | null;
    focusPath?: Element[];
    priority?: TtsRequestPriority;
};
export type FocusContext = {
    composedPath?: EventTarget[];
    target?: EventTarget | null;
    currentTarget?: EventTarget | null;
    relatedTarget?: EventTarget | null;
};
export type TtsEngineName = 'webos-luna-tts' | 'web-speech' | 'vizio-chromevox';
export declare function setTtsDebugEnabled(enabled: boolean): void;
export declare function hasActiveCompositeAccessibilityAlignment(element: Element): boolean;
export declare const hasActiveWebOsLunaCompositeLabelAlignment: typeof hasActiveCompositeAccessibilityAlignment;
export declare function restoreCompositeAccessibilityAlignment(element?: Element, reason?: string, force?: boolean): void;
export declare const restoreWebOsLunaCompositeLabelAlignment: typeof restoreCompositeAccessibilityAlignment;
export declare function scheduleCompositeAccessibilityAlignmentRestoreAfterBlur(element: Element, relatedTarget?: EventTarget | null): void;
export declare const scheduleWebOsLunaCompositeLabelAlignmentRestoreAfterBlur: typeof scheduleCompositeAccessibilityAlignmentRestoreAfterBlur;
export declare function getEstimatedSpeechRestoreDelayMs(text: string): number;
export declare function isTtsSupported(): boolean;
export declare function setTtsEnabled(enabled: boolean): void;
export declare function attachTtsEventListeners(): void;
export declare function setMediaPlaying(playing: boolean): void;
export declare function isMediaPlaying(): boolean;
export declare function markTtsEngineUnavailable(engine?: TtsEngineName): void;
export declare function stopSpeech(preserveTransactionId?: number, allowVizioEmptyFallback?: boolean): void;
export declare function cancelSpeech(): void;
export declare function speakText(text: string, options?: SpeakOptions): boolean;
export declare function focusEventReadsLabel(): boolean;
export declare function getSpeechLabelFromElement(element: Element | null | undefined): string;
export declare function getSpeechLabelFromComponent(component: TComponent | null | undefined): string;
export declare function applySpeechAttributes(element: Element, label: string): void;
export declare function buildInitialScreenSpeech(page: TPages | null | undefined): string;
export declare function setActivePage(page: TPages | null, contextProvider?: PaywallContextProvider | null): void;
export declare function setActivePageRenderRoot(root: ParentNode | null): void;
/**
 * Legacy export kept for existing call sites. Delegates to the page-first
 * initial composite flow.
 */
export declare function preparePrimaryCtaCompositeFocus(element: Element, context?: FocusContext | Event | null): boolean;
export declare function handleFocusedElementForSpeech(element: Element | null | undefined, context?: FocusContext | Event | null): boolean;
export declare function attachFocusSpeechListeners(root?: Element | Document | DocumentFragment): () => void;
export declare function detachFocusSpeechListeners(): void;
export declare function resetScreenreaderState(): void;
export declare function resetTtsStateForTests(): void;
export {};