@namiml/web-sdk 3.4.0-dev.202605241634 → 3.4.0-dev.202605261547

package/dist/utils/tts.d.ts

@@ -1,88 +1,66 @@
 /**
- * Cross-platform text-to-speech for the Nami Web SDK.
+ * Text-to-speech for the Nami Web SDK.
  *
- * Targets:
- *   - VIZIO  → window.VIZIO.Chromevox.play(text)
- *   - Other CTV (Samsung Tizen, LG webOS, Xbox) → window.speechSynthesis
- *   - Browser (desktop / mobile / tablet) → no SDK-driven TTS; the OS screen
- *     reader (VoiceOver, TalkBack, NVDA/JAWS, Orca) reads the ARIA path
- *     directly. Firing `speechSynthesis` here would duplicate the
- *     announcement and cause overlapping audio.
- *   - Headless / no API available → no-op; callers should also set `aria-label`
- *     on the focused element so the platform screenreader picks it up via the
- *     ARIA path.
+ * Speech requests are SDK-controlled and must never break paywall rendering.
  *
- * Selection precedence on `speak()`:
- *   1. VIZIO Chromevox (when present and enabled by the user).
- *   2. `window.speechSynthesis` (CTV form factors only — Bowser
- *      `getPlatform().type === 'tv'`). Browsers rely on the ARIA path.
- *   3. No-op; the caller's ARIA label remains the final fallback.
- *
- * The CTV gate exists because no Web API reports OS-level screen-reader
- * state. On a CTV runtime (typically no integrated screen reader) we are
- * the AT path; on a browser, the OS AT already reads ARIA and our extra
- * utterance would duplicate it. See NAM-1102 for the full rationale.
- */
-/**
- * Attach platform-specific TTS event listeners. Idempotent. Currently only
- * VIZIO surfaces enable/disable events at runtime; other engines are queried
- * on demand inside `speak()`.
+ * 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';
+type TtsRequestPriority = 'low' | 'normal' | 'high';
+type SpeakOptions = {
+    interrupt?: boolean;
+    reason?: 'composite' | 'focus' | 'manual';
+    transactionId?: number;
+    element?: Element | null;
+    focusPath?: Element[];
+    focusedLabel?: string;
+    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 getEstimatedSpeechRestoreDelayMs(text: string): number;
+export declare function restoreCompositeAccessibilityAlignment(element?: Element, transactionId?: number, 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 isTtsSupported(): boolean;
+export declare function setTtsEnabled(enabled: boolean): void;
 export declare function attachTtsEventListeners(): void;
-/**
- * Set whether a page's media is currently producing audio. Toggled by
- * `VideoService` (`onplay`/`onpause`/`onended`). When set to `false`, any
- * deferred speech is flushed in this call.
- */
 export declare function setMediaPlaying(playing: boolean): void;
-/** Whether media is currently flagged as playing (test/debug helper). */
 export declare function isMediaPlaying(): boolean;
-/**
- * Cancel any in-flight or queued speech across every available engine.
- * Used implicitly by {@link speak} before starting a new utterance so that
- * a focus change mid-announcement interrupts the previous announcement
- * instead of letting it run concurrently. Also called when a page changes
- * and the previous announcement is no longer relevant.
- *
- * VIZIO Chromevox does not document a single cancel method across firmware
- * revisions, so we try the names that have appeared in the wild (`cancel`,
- * `stop`) and ignore any errors — silence on cancel is a strict improvement
- * over the overlap the user otherwise hears.
- */
+export declare function stopSpeech(preserveTransactionId?: number): void;
 export declare function cancelSpeech(): void;
-/**
- * Speak `text` via the highest-priority TTS engine available. Empty / falsy
- * input is a no-op. While media is playing the latest request is buffered
- * and flushed on `setMediaPlaying(false)`. Errors are swallowed — TTS should
- * never break the paywall.
- *
- * NOTE: This function does NOT cancel any in-flight speech on its own.
- * Cancellation is the caller's responsibility — call {@link cancelSpeech}
- * at semantic interaction boundaries (e.g. inside a focus-change handler)
- * rather than on every utterance. Cancelling unconditionally inside
- * `speak()` is destructive on some VIZIO Chromevox firmware revisions
- * where the cancel + play sequence aborts the very utterance we just
- * tried to start.
- */
+export declare function markTtsEngineUnavailable(engine?: TtsEngineName): void;
+export declare function speakText(text: string, options?: SpeakOptions): boolean;
 export declare function speak(text: string): void;
-import type { TPages } from '@namiml/sdk-core';
-/** Inform the screenreader subsystem which page is currently rendered.
- *  Resets the announced flag when the page actually changes. Safe to call
- *  on every render.
- *
- *  Comparison is by object identity, NOT by `page.name`. Every paywall in
- *  the `a_onboarding_flow` staging payload contains a single page named
- *  literally `'page1'` — comparing by name would let Page 2's first focus
- *  inherit Page 1's `pageAnnounced=true` state and silently drop the
- *  composite. Page objects are sourced from each paywall's own
- *  `template.pages` array, so reference equality cleanly distinguishes
- *  pages across paywalls. */
+export declare function diagnoseTtsEngine(text?: string): 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, renderedRoot?: ParentNode | null, includeControls?: boolean): string;
+export declare function speakInitialScreen(page: TPages | null | undefined, renderedRoot?: ParentNode | null): void;
+export declare function preparePrimaryCtaCompositeFocus(element: Element, context?: FocusEvent | FocusContext): boolean;
+export declare function attachFocusSpeechListeners(root?: Element | Document | DocumentFragment): () => void;
+export declare function detachFocusSpeechListeners(): void;
 export declare function setActivePage(page: TPages | null | undefined): void;
-/** Get the currently active page (or null if none). */
+export declare function setActivePageRenderRoot(root: ParentNode | null | undefined): void;
 export declare function getActivePage(): TPages | null;
-/** Whether the page-level composite has not yet been announced for the active page. */
 export declare function shouldAnnounceComposite(): boolean;
-/** Mark the active page as having had its composite announced. */
 export declare function markPageAnnounced(): void;
-/** Clear all screenreader state — called when the paywall closes. */
 export declare function resetScreenreaderState(): void;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@namiml/web-sdk",
   "type": "module",
-  "version": "3.4.0-dev.202605241634",
+  "version": "3.4.0-dev.202605261547",
   "source": "src/nami-web.ts",
   "description": "Subscription monetization infrastructure — drop-in SDK with no-code paywalls, onboarding flows, A/B testing for web",
   "scripts": {
@@ -100,7 +100,7 @@
   "dependencies": {
     "@lit-labs/ssr-dom-shim": "^1.2.1",
     "@lit/context": "^1.1.3",
-    "@namiml/sdk-core": "3.4.0-dev.202605241634",
+    "@namiml/sdk-core": "3.4.0-dev.202605261547",
     "bowser": "^2.11.0",
     "hls.js": "^1.5.18",
     "lit": "^3.3.1",