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

package/dist/utils/tts.d.ts

@@ -1,83 +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) + desktop browsers
- *            → window.speechSynthesis.speak(SpeechSynthesisUtterance)
- *   - 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 as a last resort.
+ * 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` (most other modern browsers including the
- *      Chromium-based CTV runtimes).
- *   3. No-op; the caller's ARIA label remains the final fallback.
- *
- * Replaces the original `vizio-tts.ts` which only covered VIZIO and silently
- * dropped speech requests on every other platform.
- */
-/**
- * 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.202605201800",
+  "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": {
@@ -38,8 +38,7 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.map",
-    "CHANGELOG.md"
+    "!dist/**/*.map"
   ],
   "keywords": [
     "in-app-purchase",
@@ -101,7 +100,7 @@
   "dependencies": {
     "@lit-labs/ssr-dom-shim": "^1.2.1",
     "@lit/context": "^1.1.3",
-    "@namiml/sdk-core": "3.4.0-dev.202605201800",
+    "@namiml/sdk-core": "3.4.0-dev.202605261547",
     "bowser": "^2.11.0",
     "hls.js": "^1.5.18",
     "lit": "^3.3.1",

package/CHANGELOG.md

@@ -1,400 +0,0 @@
-# Changelog - Web SDK
-
-## Unreleased
-
-### Bug Fixes
-- Recognize Xbox controller B button (`BrowserBack`, `XF86Back`, keyCode 166) as the paywall Back key, so onboarding flows no longer reload the host SPA on Xbox UWP / Edge WebView. Back is still routed through the campaign's `__remoteback__` action — if no action is configured on the current flow step, the event is swallowed (no-op) the same as before, just without the browser falling through to `history.back`. (NAM-79)
-
-### New Features
-- Support `modal` page presentation style: centered overlay with dim backdrop, internal scrolling capped at 85vh, 90vw on phone and 50vw on tablet/desktop/TV. Backdrop click and Escape dismiss the modal. (NAM-62)
-
-## 1.7.8
-**Release Date:** February 17, 2026
-
-### Bug Fixes
-- Fix rendering of components with 0 height or width
-- Fix CTV button focus display
-- Clear uninterpolated Smart Text variables
-- Make sure background image is fullscreen when scrolling
-
-### New Features
-- Support Segment Picker form component
-- Support Countdown Timer component
-- Support Progress Bar component
-- Support new flow function setTags
-- Support listening for user tag updates in Flow
-
-### Enhancements
-- Allow branching in flows based on set/notSet operators
-- Support TTS on Vizio devices
-- Support active and inactive drop shadow styling on segment picker
-- Support paywall conditions based on product subscription duration
-
-## 1.7.7
-**Release Date:** December 17, 2025
-
-### Bug Fixes
-- Ensure page-changed event escapes shadow DOM when CustomEvent polyfill is present
-
-## 1.7.6
-
-**Release Date:** December 16, 2025
-
-### Bug Fixes
-- Fix padding issues in toggle and list components
-- Fix gradient background issue
-
-### New Features
-- Add radio and standard toggle button components
-
-### Enhancements
-- Support disabled button properties
-
-## 1.7.5
-**Release Date:** November 19, 2025
-
-### Enhancements
-- Support using launch context custom attributes in flow analytics
-- Initial support for a progress indicator component
-
-### Bug Fixes
-- Resolve an issue where a user's signed in state wasn't reflected on the paywall properly
-- Resolve an issue with content padding on certain components
-- Resolve an ssue where CMS settings for video player audio playback was not honored
-
-## 1.7.4
-**Release Date:** October 30, 2025
-
-### Bug Fixes
-- Fix an issue where if device registration failed, user was stuck in anonymous mode
-
-### Enhancements
-- Support for legacy browsers
-
-## 1.7.3
-**Release Date:** October 13, 2025
-
-### Bug Fixes
-- Fix issue with hidden components not being hidden
-- Fix issue with deeplink handler
-- Fix issue preventing black bar and double scrolling in certain situations
-
-### Enhancements
-- Swipe and animation improements
-- Support for custom carousel indicators
-- Add support for launch id to group flow transitions
-- Add support for disabled field on toggle switch
-- Add `NamiCampaignManager.isFlow` for checking if a placement is a flow or not
-
-## 1.7.2
-**Release Date:** September 17, 2025
-
-### Enhancements
-- Improve handling of device creation failures and latency
-- Add `disableCampaignUpdates` namiCommand
-- Add forced A/B testing via `splitPosition` namiCommand
-- Standardize `NamiPaywallManager.emitter`
-- Support smart variables derived from URL query parameters and related analytics
-
-### Bug Fixes
-- Fix CTV scaling and spacing issues
-- Styling improvements
-
-## 1.7.1
-**Release Date:** September 3, 2025
-
-### Enhancements
-- Add `NamiFlowManager.pause` method
-- Add component animations (pulse/wave)
-
-### Bug Fixes
-- Completed Flows will no longer call registered paywall close handlers
-
-## 1.7.0
-**Release Date:** August 27, 2025
-
-### Enhancements
-- Add new components (Form container, Toggle switch, Radio button)
-- Support Flow Smart Text Variables
-- Support Flow animations / transitions
-- Smart TV Back button support
-- Support for buy / select sku Flow handoffs
-
-### Bug Fixes
-- QR Code component (scaling and non-hex colors)
-
-## 1.6.4  
-**Release Date:** August 6, 2025
-
-### Enhancements
-- Improved directional navigation support for TV and custom Nami components
-- Pass launch context in flows for better paywall context handling
-
-### Bug Fixes
-- Prevent scrolling on TV form factor (Content and Background containers)
-- Fix for handling unexpected SKU smart text variables
-
-## 1.6.3  
-**Release Date:** July 29, 2025
-
-### Enhancements
-- Improved television layout scaling for various viewport sizes
-
-## 1.6.2  
-**Release Date:** July 28, 2025
-
-### New Features
-- `Nami.sdkVersion` method to get the internal SDK version
-- Support for QR Code components
-- On Device Segment Selection for A/B testing
-- Support Base64, Gzipped Initial Configurations
-- Support Fully Uppercase Text Components
-
-### Enhancements
-- Paywall actions will now trigger if no flow action for a button is defined
-
-### Bug Fixes
-- Dynamic widths on Responsive Grid components
-
-## 1.6.1  
-**Release Date:** July 13, 2025
-
-### Improvements
-- Fix type exports in declaration files
-
-## 1.6.0  
-**Release Date:** July 10, 2025
-
-### New Features
-- Introduced `NamiFlowManager` for orchestrating multi-page flows
-  - `NamiFlowManager.registerStepHandoff`: callback when a flow is handed off
-  - `NamiFlowManager.registerEventHandler`: callback for flow analytics
-  - `NamiFlowManager.resume`: resume a handed-off flow
-
-### UI Enhancements
-- Default Focused Buttons
-- Blur Properties
-
-### Accessibility
-- Screenreader support for videos
-- Screenreader hints added
-
-### Performance
-- Better support handling multiple `Nami.configure` calls
-- General stability fixes
-
-## 1.5.12  
-**Release Date:** July 30, 2025
-
-### Bug Fixes
-- Fix race condition when local storage fails
-
-## 1.5.11  
-**Release Date:** June 18, 2025
-
-### Enhancements
-- Performance improvements for form factor lookups
-
-### Bug Fixes
-- Fix uninterpolated smart text
-- Fix fallback to in-memory storage on localStorage write failures
-
-## 1.5.10  
-**Release Date:** May 22, 2025
-
-### Enhancements
-- Support focused styling on buttons and toggle
-- Support tab key focus for collapsible component
-- Support alt tags on images
-
-### Bug Fixes
-- Fix toggle switch not preserving state on re-render
-- Fix additional spacing in text list items
-- Fix issue with screenreader and collapsed content
-
-## 1.5.9  
-**Release Date:** April 2, 2025
-
-### Bug Fixes
-- Resolve incorrect downscaling on 720p TV devices
-
-## 1.5.8  
-**Release Date:** April 1, 2025
-
-### Bug Fixes
-- Resolve issue where toggle component event was firing twice
-- Fix toggle switch state re-rendering due to parent page
-- Remove additional unintended spacing
-
-## 1.5.7  
-**Release Date:** February 20, 2025
-
-### Bug Fixes
-- Resolve additional type issue encountered with certain initial config files
-
-## 1.5.6  
-**Release Date:** February 19, 2025
-
-### Bug Fixes
-- Resolve type issue encountered with certain initial config files
-
-## 1.5.5  
-**Release Date:** January 16, 2025
-
-### Enhancements
-- Add optional `purchaseChannel` to `NamiConfiguration` to pass through to `NamiPaywallEvent` analytics
-
-## 1.5.4  
-**Release Date:** November 29, 2024
-
-### Bug Fixes
-- Resolve issue with TV focus on containers and product buttons on first load
-
-## 1.5.3  
-**Release Date:** November 21, 2024
-
-### Bug Fixes
-- Fix collapse component caret icon not updating when expanded
-
-### Enhancements
-- Support scaling on TV devices (720p, 1080p, 4K, and 8K)
-
-## 1.5.2  
-**Release Date:** October 24, 2024
-
-### Bug Fixes
-- Fix wrong campaign rule used for placement labels
-- Fix initial config campaign rule mapping
-- Fix background video fullscreen on mobile
-- Fix focus events on connected TV
-- Fix login/logout state handling
-- Fix display of free trials and promotional offers
-- Fix multiple UI issues in carousel and stack components
-
-## 1.5.1  
-**Release Date:** October 2, 2024
-
-### Enhancements
-- Add `TOGGLE_CHANGE` and `PAGE_CHANGE` paywall events
-
-### Bug Fixes
-- Fix carousel component swiper
-- Fix flex alignment issues
-- Fix Safari rendering for hero video
-
-## 1.5.0  
-**Release Date:** September 26, 2024
-
-### New Features
-- Advanced video feature support
-- Carousel component support
-
-### Enhancements
-- Improve fallback data handling
-- Support repeatable lists inside collapse components
-- Support vertical alignment in product container
-- Align `removeAllListeners` behavior with RN SDK
-
-### Bug Fixes
-- Fix segment picker cursor behavior
-- Fix hidden component visibility
-- Fix responsive grid spacing and scrolling
-- Fix background video gradient and position
-
-## 1.4.0  
-**Release Date:** September 5, 2024
-
-### New Features
-- HLS support in Video component
-- Responsive Grid component support
-- `NamiCustomerManager.deviceId` added
-- `NamiCustomerManager.registerJourneyStateHandler` and `journeyState` (subscription management)
-- `NamiEntitlementManager.clearProvisionalEntitlementGrants` (subscription management)
-
-### Enhancements
-- Pass product groups to paywall via campaign launch
-
-### Bug Fixes
-- Find product by ID instead of name
-- Fix spacing in text component
-
-### Improvements
-- Update type definitions across paywall manager and customer manager APIs
-
-## 1.3.2  
-**Release Date:** August 14, 2024
-
-### Bug Fixes
-- Conditional component rendering based on product entitlement and product groups
-
-## 1.3.1  
-**Release Date:** August 12, 2024
-
-### Bug Fixes
-- Fix `SHOW_PAYWALL` event being triggered as `UNKNOWN`
-
-## 1.3.0  
-**Release Date:** August 12, 2024
-
-### New Features
-- `NamiEntitlementManager` to manage entitlements
-  - `active`, `isEntitlementActive`, `refresh`, `registerActiveEntitlementsHandler`
-- `NamiEntitlement` object model
-- Hidden component support
-- New components: Video and collapsible
-- Timeout and error handling improvements
-
-### Bug Fixes
-- Typing improvements across SDKs
-- ECMAScript 2021 support
-
-### Breaking Changes
-- `appPlatformId` renamed to `appPlatformID` in `NamiConfiguration`
-- `NamiPaywallManager.buySkuComplete` interface simplified
-
-## 1.2.0  
-**Release Date:** July 26, 2024
-
-### New Features
-- `NamiCampaignManager.launch`: supports `paywallLaunchContext`
-- `NamiPaywallManager.buySKUCancel` and `buySKUComplete`
-- Paywall impression and conversion reporting
-- Faster paywall render time
-
-### Bug Fixes
-- Consistent typing and API alignment across SDKs
-
-## 1.1.0  
-**Release Date:** June 24, 2024
-
-### New Features
-- `NamiCustomerManager.setAnonymousMode`
-- `NamiCampaignManager.launch` with `paywallActionHandler`
-- `NamiPaywallManager.registerBuySkuHandler`
-
-### Bug Fixes
-- Lit component compatibility and SSR fixes
-- Subscription pricing rendering fixes
-- Custom API host connectivity fixes
-- Icon display improvements
-
-### Known Issues
-- `buySkuComplete`, `buySkuCancel` not fully implemented
-- Impression/conversion reporting and launch context not implemented
-
-## 1.0.0  
-**Release Date:** June 13, 2024
-
-### New Features
-- Core SDK: `Nami`, `Nami.configure`, `NamiConfiguration`, `NamiLanguageCodes`
-- `NamiCampaignManager` for campaign management
-- `NamiCustomerManager` for customer state and attributes
-- `NamiPaywallManager` for paywall and event handler management
-
-### Known Issues
-- Paywall event callbacks not firing
-- `buySkuComplete`, `buySkuCancel`, and `setAnonymousMode` partially implemented
-- Impression/conversion reporting and launch context not yet available
-
-### Additional Notes
-Refer to the documentation for detailed usage instructions and integration examples.