accessibility-plugin-react 2.28.0 → 2.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/NOTICE ADDED
@@ -0,0 +1,24 @@
1
+ accessibility-plugin-react
2
+ Copyright (c) 2026 Praboth Charith
3
+
4
+ This product is licensed under the ISC License. See the LICENSE file for details.
5
+
6
+ Attribution & Upstream Project:
7
+ This package is a composable React implementation developed from the architectural
8
+ foundation of the original vanilla JavaScript accessibility plugin maintained at:
9
+ https://github.com/prabothcharith/accessibility-plugin
10
+
11
+ Third-Party Assets & Licensure:
12
+ - Zero Runtime Dependencies: This library has no runtime dependencies outside of
13
+ peer dependencies on React and React DOM.
14
+ - Fonts: No third-party binary font files (.woff, .woff2, .ttf) are bundled. All font
15
+ presets utilize client-system font stacks (e.g. system-ui, -apple-system, sans-serif)
16
+ with fallback declarations.
17
+ - Icons: All decorative icons are authored directly as inline SVG elements under the
18
+ package's ISC License.
19
+ - Dictionaries: Built-in glossaries (English, Sinhala, Tamil) are compiled in-tree
20
+ under the ISC License for client-side offline dictionary lookup with zero external
21
+ network dependencies.
22
+ - Speech & Audio: Voice navigation and text-to-speech read-aloud functionality utilize
23
+ native browser platform APIs (window.speechSynthesis, window.SpeechRecognition)
24
+ with zero remote speech services or binary audio assets.
package/README.md CHANGED
@@ -305,6 +305,7 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
305
305
  - [Migration from v1 and development baselines](docs/MIGRATION.md)
306
306
  - [Architecture and lifecycle decisions](docs/ARCHITECTURE.md)
307
307
  - [Development and testing](docs/DEVELOPMENT.md)
308
+ - [Contributing guidelines](CONTRIBUTING.md)
308
309
  - [Per-site feature-menu customization](docs/MENU_CUSTOMIZATION.md)
309
310
  - [Development-only integration diagnostics and test harness](docs/DIAGNOSTICS.md)
310
311
  - [Optional privacy-safe feature event callbacks](docs/PRIVACY_AND_EVENTS.md)
@@ -312,6 +313,11 @@ See [troubleshooting](docs/TROUBLESHOOTING.md) before filing an issue.
312
313
  - [Design foundation](docs/DESIGN.md)
313
314
  - [Troubleshooting](docs/TROUBLESHOOTING.md)
314
315
  - [Project status and verification evidence](docs/PROJECT_STATUS.md)
316
+ - [Supported browser, device, and AT matrix](docs/SUPPORTED_MATRIX.md)
317
+ - [Performance, bundle, listener and leak profiling](docs/PERFORMANCE_PROFILING.md)
318
+ - [Security, dependency, license and privacy audit](docs/SECURITY_AUDIT.md)
319
+ - [Packed publish rehearsal and consumer smoke test](docs/PUBLISH_REHEARSAL.md)
320
+ - [Milestone 5 release proposal and version recommendation](docs/RELEASE_PROPOSAL_M5.md)
315
321
  - [Release procedure](docs/RELEASE.md)
316
322
  - [Changelog](CHANGELOG.md)
317
323
 
package/dist/index.d.mts CHANGED
@@ -641,6 +641,10 @@ interface AccessibilityContextValue {
641
641
  locale?: string;
642
642
  statementUrl?: string;
643
643
  largeControls?: boolean;
644
+ effectScope?: string | HTMLElement | {
645
+ current: HTMLElement | null;
646
+ } | null;
647
+ nonce?: string;
644
648
  }
645
649
  type WidgetPlacement = {
646
650
  kind: "corner";
@@ -678,6 +682,19 @@ interface AccessibilityPluginProps {
678
682
  * inputs, transcripts, and identifiers.
679
683
  */
680
684
  onFeatureEvent?: FeatureEventListener;
685
+ /**
686
+ * Optional scoped container target for built-in effects (Issue #13).
687
+ * Can be a CSS selector string (e.g. '#main-content'), an HTMLElement,
688
+ * or a React ref object. Defaults to document.body when omitted.
689
+ */
690
+ effectScope?: string | HTMLElement | {
691
+ current: HTMLElement | null;
692
+ } | null;
693
+ /**
694
+ * Optional Content Security Policy (CSP) nonce attribute passed to any
695
+ * dynamically injected <style> tags (Issue #13).
696
+ */
697
+ nonce?: string;
681
698
  }
682
699
  interface AccessibilityButtonProps {
683
700
  /** Pointer dragging and Alt+Arrow movement. Defaults to true. */
@@ -710,7 +727,7 @@ interface AccessibilityListProps {
710
727
  menuConfig?: MenuCustomizationConfig;
711
728
  }
712
729
 
713
- declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, diagnostics, onFeatureEvent, }: AccessibilityPluginProps): react.JSX.Element;
730
+ declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, diagnostics, onFeatureEvent, effectScope, nonce, }: AccessibilityPluginProps): react.JSX.Element;
714
731
 
715
732
  declare function AccessibilityButton({ icon, draggable, title, description, className, style, largeControls, }: AccessibilityButtonProps): react.JSX.Element;
716
733
 
@@ -843,6 +860,7 @@ declare const MIN_READING_MASK_HEIGHT = 40;
843
860
  declare const MAX_READING_MASK_HEIGHT = 400;
844
861
  declare const READING_MASK_HEIGHT_PRESETS: readonly [60, 100, 160, 240];
845
862
 
863
+ declare const MAX_HOST_ELEMENTS = 8000;
846
864
  /** Detects whether the user's operating system has forced colors / high contrast active. */
847
865
  declare function isForcedColorsActive(): boolean;
848
866
  declare function subscribeForcedColors(callback: () => void): () => void;
@@ -897,6 +915,22 @@ declare function isFunctionalOrMeaningfulImage(el: Element): boolean;
897
915
  * (empty alt="", role="presentation", role="none", aria-hidden="true", or decorative class/attribute).
898
916
  */
899
917
  declare function isEligibleDecorativeImage(el: Element): boolean;
918
+ type EffectScopeTarget = string | HTMLElement | {
919
+ current: HTMLElement | null;
920
+ } | null | undefined;
921
+ interface ApplyPageOptions {
922
+ effectScope?: EffectScopeTarget;
923
+ nonce?: string;
924
+ }
925
+ interface EffectsSession {
926
+ undo: () => void;
927
+ applyIncremental: (addedNodes: HTMLElement[]) => void;
928
+ styledCount: () => number;
929
+ targetRoot?: HTMLElement | null;
930
+ }
931
+ declare function resolveEffectScope(scope: EffectScopeTarget): HTMLElement | null;
932
+ declare function applyPageSession(values: Record<string, unknown>, optionsOrScope?: EffectScopeTarget | ApplyPageOptions): EffectsSession;
933
+ declare function applyPage(values: Record<string, unknown>, optionsOrScope?: EffectScopeTarget | ApplyPageOptions): () => void;
900
934
  declare function nudgeReadingAid(feature: "readingGuide" | "readingMask", delta: number): void;
901
935
  /**
902
936
  * Extracts authored accessible description from an element.
@@ -1921,4 +1955,4 @@ interface TranslationControllerProps {
1921
1955
  }
1922
1956
  declare const TranslationController: react__default.FC<TranslationControllerProps>;
1923
1957
 
1924
- export { ALLOWED_PREFERENCE_KEYS, ALL_PROFILE_IDS, AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, type AccessibilityEventType, type AccessibilityFeatureEvent, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, AccessibilityProfilesController, type AccessibilityState, AccessibleTooltipsController, type ActiveProfileState, type AppliedSmartContrast, type ArticleContent, type BackdropResolution, type BaseAccessibilityEvent, BigCursorController, type BigCursorControllerProps, CONTRAST_MODES, CONTRAST_PALETTES, CONTRAST_PROTECTED_SELECTOR, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, ContrastModeController, type ContrastModeValue, type ContrastPalette, type CursorSizePreference, type CustomPreset, CustomPresetsController, DEFAULT_FEATURE_GROUP_MAP, DEFAULT_MENU_GROUPS, DEFAULT_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DEFAULT_SHORTCUTS, DIAGNOSTICS_DISCLAIMER, DYSLEXIA_FONT_STACK, type DataRetentionPolicy, type DiagnosticCategory, type DiagnosticIssue, type DiagnosticSeverity, type DiagnosticsConfig, DiagnosticsHarness, type DiagnosticsHarnessProps, type DiagnosticsReport, type DiagnosticsSummary, DictionaryController, type DictionaryControllerProps, type DictionaryEntry, type DictionaryLookupResult, type DictionaryProvider, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type EventTriggerSource, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureChangeEvent, type FeatureEventListener, type FeatureLocaleLabels, FeatureMenu, type FeatureMenuGroupConfig, type FeatureMenuItemConfig, type FeatureMenuProps, type FeatureOptions, type FeatureRegistration, type FeatureResetEvent, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, type GrayscaleControllerProps, HIGH_CONTRAST_TOKENS, type HeadingItem, HeadingsNavigatorController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, type ImportResult, InvertColorsController, KNOWN_FEATURE_IDS, KeyboardShortcutsController, type KeyboardShortcutsControllerProps, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LOCAL_DICTIONARY_EN, LOCAL_DICTIONARY_SI, LOCAL_DICTIONARY_TA, type LandmarkItem, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LinkItem, type LocaleStrings, MAX_NODES_PER_TRANSLATION_BATCH, MAX_READING_MASK_HEIGHT, MAX_TEXT_LENGTH_PER_NODE, MIN_READING_MASK_HEIGHT, type MenuCustomizationConfig, type MenuValidationIssue, type MenuValidationResult, type NormalizedMenuConfig, type NormalizedMenuGroup, type NormalizedMenuItem, PROFILE_DEFINITIONS, PageNavigatorController, type PageNavigatorControllerProps, PageStructureController, type PanelToggleEvent, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PlacementChangeEvent, type PluginPosition, type PresetApplyEvent, PresetsBackupController, PresetsController, type PresetsControllerProps, type PresetsExportV1, type ProfileApplyEvent, ProfileController, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, ProfilesController, type ProfilesControllerProps, READING_MASK_HEIGHT_PRESETS, READ_ALOUD_EXCLUDED_SELECTORS, RESERVED_BROWSER_SHORTCUTS, ReadAloudController, type ReadAloudControllerProps, type ReadAloudOptions, ReadAloudSession, type ReadAloudState, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReadingModeController, type ReadingModeControllerProps, ReduceMotionController, ResetController, type RgbColor, type RgbaColor, SMART_CONTRAST_DISCLAIMER, SaturationController, type SaturationControllerProps, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SettingsImportExportController, type ShortcutDefinition, SkipToMainLink, type SkipToMainLinkProps, SmartContrastController, type SmartContrastLevel, type SmartContrastOptions, type SmartContrastReport, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TARGET_RATIOS, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TRANSLATION_DISCLAIMER, TRANSLATION_ERROR_CODES, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type TranslatableNode, type TranslatedItem, type TranslationAdapter, type TranslationConsentRecord, type TranslationConsentStatus, TranslationController, type TranslationControllerProps, TranslationError, type TranslationErrorCode, type TranslationRequest, type TranslationResponse, type TranslationSession, type UnsupportedElementInfo, type UnsupportedReason, type UsePresetsResult, type UseProfilesResult, VOICE_COMMANDS, VOICE_NAVIGATION_DISCLAIMER, type ValidationResult, type VoiceCommandDefinition, type VoiceCommandId, type VoiceExecutionContext, VoiceNavigationController, type VoiceNavigationControllerProps, type VoiceNavigationOptions, type VoiceNavigationResult, type VoiceNavigationSession, type VoiceNavigationStatus, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, applyCustomPresetToStore, applyProfileToStore, applySmartContrast, applyTranslations, calculateContrastRatio, calculateRelativeLuminance, checkBoundariesDiagnostics, checkCspDiagnostics, checkDomDiagnostics, checkHostCssDiagnostics, checkProviderDiagnostics, checkStorageDiagnostics, compositeRgba, countWords, createCustomPreset, createInitialPreferencesState, createOfflineMockTranslationAdapter, createVoiceNavigationSession, downloadJsonFile, emitFeatureEvent, enLocale, enableAccessibleTooltips, estimateReadingTime, evaluateSmartContrast, executeVoiceCommand, exportPresetsToJson, extractArticleContent, extractReadAloudText, extractTranslatableNodes, findArticleCandidate, findMainLandmark, getActiveSelectionText, getAuthoredDescription, getMenuConfigSignature, getProfileDefinition, getScriptSpacingConstraints, getSpeechVoices, hasFinePointer, isEligibleDecorativeImage, isEligibleForSmartContrast, isForcedColorsActive, isFormFieldOrEditable, isFunctionalOrMeaningfulImage, isLargeText, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, isSensitiveElement, isSpeechRecognitionSupported, isSpeechSynthesisSupported, isValidCustomPreset, lookupLocalDictionary, lookupWord, mapFeaturesToProfileSettings, mapProfileSettingsToFeatures, matchVoiceCommand, navigateToElement, normalizeKeyCombo, normalizePreferenceValue, normalizePreferences, normalizeTranscript, nudgeReadingAid, parseColor, parseKeyboardEventToCombo, positionTooltip, preferencesReducer, recordProfileOverride, registerLocale, resolveActiveShortcut, resolveEffectiveBackdrop, resolveEffectivePreferences, resolveLocaleStrings, revertProfileFromStore, runDiagnostics, sanitizeFeatureEvent, sanitizeLookupTerm, sanitizePreferences, sanitizeTranslationOutput, scanHeadings, scanLandmarks, scanLinks, siLocale, splitTextIntoChunks, subscribeFinePointer, subscribeForcedColors, subscribePageStructure, subscribeReducedMotion, subscribeSpeechVoices, taLocale, translateHostContent, useAccessibility, useDiagnostics, usePresets, useProfiles, validateAndParseImport, validateMenuConfig, validateShortcutRemap };
1958
+ export { ALLOWED_PREFERENCE_KEYS, ALL_PROFILE_IDS, AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, type AccessibilityEventType, type AccessibilityFeatureEvent, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, AccessibilityProfilesController, type AccessibilityState, AccessibleTooltipsController, type ActiveProfileState, type AppliedSmartContrast, type ApplyPageOptions, type ArticleContent, type BackdropResolution, type BaseAccessibilityEvent, BigCursorController, type BigCursorControllerProps, CONTRAST_MODES, CONTRAST_PALETTES, CONTRAST_PROTECTED_SELECTOR, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, ContrastModeController, type ContrastModeValue, type ContrastPalette, type CursorSizePreference, type CustomPreset, CustomPresetsController, DEFAULT_FEATURE_GROUP_MAP, DEFAULT_MENU_GROUPS, DEFAULT_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DEFAULT_SHORTCUTS, DIAGNOSTICS_DISCLAIMER, DYSLEXIA_FONT_STACK, type DataRetentionPolicy, type DiagnosticCategory, type DiagnosticIssue, type DiagnosticSeverity, type DiagnosticsConfig, DiagnosticsHarness, type DiagnosticsHarnessProps, type DiagnosticsReport, type DiagnosticsSummary, DictionaryController, type DictionaryControllerProps, type DictionaryEntry, type DictionaryLookupResult, type DictionaryProvider, type EffectScopeTarget, type EffectsSession, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type EventTriggerSource, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureChangeEvent, type FeatureEventListener, type FeatureLocaleLabels, FeatureMenu, type FeatureMenuGroupConfig, type FeatureMenuItemConfig, type FeatureMenuProps, type FeatureOptions, type FeatureRegistration, type FeatureResetEvent, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, type GrayscaleControllerProps, HIGH_CONTRAST_TOKENS, type HeadingItem, HeadingsNavigatorController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, type ImportResult, InvertColorsController, KNOWN_FEATURE_IDS, KeyboardShortcutsController, type KeyboardShortcutsControllerProps, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LOCAL_DICTIONARY_EN, LOCAL_DICTIONARY_SI, LOCAL_DICTIONARY_TA, type LandmarkItem, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LinkItem, type LocaleStrings, MAX_HOST_ELEMENTS, MAX_NODES_PER_TRANSLATION_BATCH, MAX_READING_MASK_HEIGHT, MAX_TEXT_LENGTH_PER_NODE, MIN_READING_MASK_HEIGHT, type MenuCustomizationConfig, type MenuValidationIssue, type MenuValidationResult, type NormalizedMenuConfig, type NormalizedMenuGroup, type NormalizedMenuItem, PROFILE_DEFINITIONS, PageNavigatorController, type PageNavigatorControllerProps, PageStructureController, type PanelToggleEvent, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PlacementChangeEvent, type PluginPosition, type PresetApplyEvent, PresetsBackupController, PresetsController, type PresetsControllerProps, type PresetsExportV1, type ProfileApplyEvent, ProfileController, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, ProfilesController, type ProfilesControllerProps, READING_MASK_HEIGHT_PRESETS, READ_ALOUD_EXCLUDED_SELECTORS, RESERVED_BROWSER_SHORTCUTS, ReadAloudController, type ReadAloudControllerProps, type ReadAloudOptions, ReadAloudSession, type ReadAloudState, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReadingModeController, type ReadingModeControllerProps, ReduceMotionController, ResetController, type RgbColor, type RgbaColor, SMART_CONTRAST_DISCLAIMER, SaturationController, type SaturationControllerProps, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SettingsImportExportController, type ShortcutDefinition, SkipToMainLink, type SkipToMainLinkProps, SmartContrastController, type SmartContrastLevel, type SmartContrastOptions, type SmartContrastReport, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TARGET_RATIOS, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TRANSLATION_DISCLAIMER, TRANSLATION_ERROR_CODES, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type TranslatableNode, type TranslatedItem, type TranslationAdapter, type TranslationConsentRecord, type TranslationConsentStatus, TranslationController, type TranslationControllerProps, TranslationError, type TranslationErrorCode, type TranslationRequest, type TranslationResponse, type TranslationSession, type UnsupportedElementInfo, type UnsupportedReason, type UsePresetsResult, type UseProfilesResult, VOICE_COMMANDS, VOICE_NAVIGATION_DISCLAIMER, type ValidationResult, type VoiceCommandDefinition, type VoiceCommandId, type VoiceExecutionContext, VoiceNavigationController, type VoiceNavigationControllerProps, type VoiceNavigationOptions, type VoiceNavigationResult, type VoiceNavigationSession, type VoiceNavigationStatus, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, applyCustomPresetToStore, applyPage, applyPageSession, applyProfileToStore, applySmartContrast, applyTranslations, calculateContrastRatio, calculateRelativeLuminance, checkBoundariesDiagnostics, checkCspDiagnostics, checkDomDiagnostics, checkHostCssDiagnostics, checkProviderDiagnostics, checkStorageDiagnostics, compositeRgba, countWords, createCustomPreset, createInitialPreferencesState, createOfflineMockTranslationAdapter, createVoiceNavigationSession, downloadJsonFile, emitFeatureEvent, enLocale, enableAccessibleTooltips, estimateReadingTime, evaluateSmartContrast, executeVoiceCommand, exportPresetsToJson, extractArticleContent, extractReadAloudText, extractTranslatableNodes, findArticleCandidate, findMainLandmark, getActiveSelectionText, getAuthoredDescription, getMenuConfigSignature, getProfileDefinition, getScriptSpacingConstraints, getSpeechVoices, hasFinePointer, isEligibleDecorativeImage, isEligibleForSmartContrast, isForcedColorsActive, isFormFieldOrEditable, isFunctionalOrMeaningfulImage, isLargeText, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, isSensitiveElement, isSpeechRecognitionSupported, isSpeechSynthesisSupported, isValidCustomPreset, lookupLocalDictionary, lookupWord, mapFeaturesToProfileSettings, mapProfileSettingsToFeatures, matchVoiceCommand, navigateToElement, normalizeKeyCombo, normalizePreferenceValue, normalizePreferences, normalizeTranscript, nudgeReadingAid, parseColor, parseKeyboardEventToCombo, positionTooltip, preferencesReducer, recordProfileOverride, registerLocale, resolveActiveShortcut, resolveEffectScope, resolveEffectiveBackdrop, resolveEffectivePreferences, resolveLocaleStrings, revertProfileFromStore, runDiagnostics, sanitizeFeatureEvent, sanitizeLookupTerm, sanitizePreferences, sanitizeTranslationOutput, scanHeadings, scanLandmarks, scanLinks, siLocale, splitTextIntoChunks, subscribeFinePointer, subscribeForcedColors, subscribePageStructure, subscribeReducedMotion, subscribeSpeechVoices, taLocale, translateHostContent, useAccessibility, useDiagnostics, usePresets, useProfiles, validateAndParseImport, validateMenuConfig, validateShortcutRemap };
package/dist/index.d.ts CHANGED
@@ -641,6 +641,10 @@ interface AccessibilityContextValue {
641
641
  locale?: string;
642
642
  statementUrl?: string;
643
643
  largeControls?: boolean;
644
+ effectScope?: string | HTMLElement | {
645
+ current: HTMLElement | null;
646
+ } | null;
647
+ nonce?: string;
644
648
  }
645
649
  type WidgetPlacement = {
646
650
  kind: "corner";
@@ -678,6 +682,19 @@ interface AccessibilityPluginProps {
678
682
  * inputs, transcripts, and identifiers.
679
683
  */
680
684
  onFeatureEvent?: FeatureEventListener;
685
+ /**
686
+ * Optional scoped container target for built-in effects (Issue #13).
687
+ * Can be a CSS selector string (e.g. '#main-content'), an HTMLElement,
688
+ * or a React ref object. Defaults to document.body when omitted.
689
+ */
690
+ effectScope?: string | HTMLElement | {
691
+ current: HTMLElement | null;
692
+ } | null;
693
+ /**
694
+ * Optional Content Security Policy (CSP) nonce attribute passed to any
695
+ * dynamically injected <style> tags (Issue #13).
696
+ */
697
+ nonce?: string;
681
698
  }
682
699
  interface AccessibilityButtonProps {
683
700
  /** Pointer dragging and Alt+Arrow movement. Defaults to true. */
@@ -710,7 +727,7 @@ interface AccessibilityListProps {
710
727
  menuConfig?: MenuCustomizationConfig;
711
728
  }
712
729
 
713
- declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, diagnostics, onFeatureEvent, }: AccessibilityPluginProps): react.JSX.Element;
730
+ declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, diagnostics, onFeatureEvent, effectScope, nonce, }: AccessibilityPluginProps): react.JSX.Element;
714
731
 
715
732
  declare function AccessibilityButton({ icon, draggable, title, description, className, style, largeControls, }: AccessibilityButtonProps): react.JSX.Element;
716
733
 
@@ -843,6 +860,7 @@ declare const MIN_READING_MASK_HEIGHT = 40;
843
860
  declare const MAX_READING_MASK_HEIGHT = 400;
844
861
  declare const READING_MASK_HEIGHT_PRESETS: readonly [60, 100, 160, 240];
845
862
 
863
+ declare const MAX_HOST_ELEMENTS = 8000;
846
864
  /** Detects whether the user's operating system has forced colors / high contrast active. */
847
865
  declare function isForcedColorsActive(): boolean;
848
866
  declare function subscribeForcedColors(callback: () => void): () => void;
@@ -897,6 +915,22 @@ declare function isFunctionalOrMeaningfulImage(el: Element): boolean;
897
915
  * (empty alt="", role="presentation", role="none", aria-hidden="true", or decorative class/attribute).
898
916
  */
899
917
  declare function isEligibleDecorativeImage(el: Element): boolean;
918
+ type EffectScopeTarget = string | HTMLElement | {
919
+ current: HTMLElement | null;
920
+ } | null | undefined;
921
+ interface ApplyPageOptions {
922
+ effectScope?: EffectScopeTarget;
923
+ nonce?: string;
924
+ }
925
+ interface EffectsSession {
926
+ undo: () => void;
927
+ applyIncremental: (addedNodes: HTMLElement[]) => void;
928
+ styledCount: () => number;
929
+ targetRoot?: HTMLElement | null;
930
+ }
931
+ declare function resolveEffectScope(scope: EffectScopeTarget): HTMLElement | null;
932
+ declare function applyPageSession(values: Record<string, unknown>, optionsOrScope?: EffectScopeTarget | ApplyPageOptions): EffectsSession;
933
+ declare function applyPage(values: Record<string, unknown>, optionsOrScope?: EffectScopeTarget | ApplyPageOptions): () => void;
900
934
  declare function nudgeReadingAid(feature: "readingGuide" | "readingMask", delta: number): void;
901
935
  /**
902
936
  * Extracts authored accessible description from an element.
@@ -1921,4 +1955,4 @@ interface TranslationControllerProps {
1921
1955
  }
1922
1956
  declare const TranslationController: react__default.FC<TranslationControllerProps>;
1923
1957
 
1924
- export { ALLOWED_PREFERENCE_KEYS, ALL_PROFILE_IDS, AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, type AccessibilityEventType, type AccessibilityFeatureEvent, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, AccessibilityProfilesController, type AccessibilityState, AccessibleTooltipsController, type ActiveProfileState, type AppliedSmartContrast, type ArticleContent, type BackdropResolution, type BaseAccessibilityEvent, BigCursorController, type BigCursorControllerProps, CONTRAST_MODES, CONTRAST_PALETTES, CONTRAST_PROTECTED_SELECTOR, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, ContrastModeController, type ContrastModeValue, type ContrastPalette, type CursorSizePreference, type CustomPreset, CustomPresetsController, DEFAULT_FEATURE_GROUP_MAP, DEFAULT_MENU_GROUPS, DEFAULT_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DEFAULT_SHORTCUTS, DIAGNOSTICS_DISCLAIMER, DYSLEXIA_FONT_STACK, type DataRetentionPolicy, type DiagnosticCategory, type DiagnosticIssue, type DiagnosticSeverity, type DiagnosticsConfig, DiagnosticsHarness, type DiagnosticsHarnessProps, type DiagnosticsReport, type DiagnosticsSummary, DictionaryController, type DictionaryControllerProps, type DictionaryEntry, type DictionaryLookupResult, type DictionaryProvider, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type EventTriggerSource, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureChangeEvent, type FeatureEventListener, type FeatureLocaleLabels, FeatureMenu, type FeatureMenuGroupConfig, type FeatureMenuItemConfig, type FeatureMenuProps, type FeatureOptions, type FeatureRegistration, type FeatureResetEvent, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, type GrayscaleControllerProps, HIGH_CONTRAST_TOKENS, type HeadingItem, HeadingsNavigatorController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, type ImportResult, InvertColorsController, KNOWN_FEATURE_IDS, KeyboardShortcutsController, type KeyboardShortcutsControllerProps, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LOCAL_DICTIONARY_EN, LOCAL_DICTIONARY_SI, LOCAL_DICTIONARY_TA, type LandmarkItem, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LinkItem, type LocaleStrings, MAX_NODES_PER_TRANSLATION_BATCH, MAX_READING_MASK_HEIGHT, MAX_TEXT_LENGTH_PER_NODE, MIN_READING_MASK_HEIGHT, type MenuCustomizationConfig, type MenuValidationIssue, type MenuValidationResult, type NormalizedMenuConfig, type NormalizedMenuGroup, type NormalizedMenuItem, PROFILE_DEFINITIONS, PageNavigatorController, type PageNavigatorControllerProps, PageStructureController, type PanelToggleEvent, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PlacementChangeEvent, type PluginPosition, type PresetApplyEvent, PresetsBackupController, PresetsController, type PresetsControllerProps, type PresetsExportV1, type ProfileApplyEvent, ProfileController, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, ProfilesController, type ProfilesControllerProps, READING_MASK_HEIGHT_PRESETS, READ_ALOUD_EXCLUDED_SELECTORS, RESERVED_BROWSER_SHORTCUTS, ReadAloudController, type ReadAloudControllerProps, type ReadAloudOptions, ReadAloudSession, type ReadAloudState, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReadingModeController, type ReadingModeControllerProps, ReduceMotionController, ResetController, type RgbColor, type RgbaColor, SMART_CONTRAST_DISCLAIMER, SaturationController, type SaturationControllerProps, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SettingsImportExportController, type ShortcutDefinition, SkipToMainLink, type SkipToMainLinkProps, SmartContrastController, type SmartContrastLevel, type SmartContrastOptions, type SmartContrastReport, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TARGET_RATIOS, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TRANSLATION_DISCLAIMER, TRANSLATION_ERROR_CODES, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type TranslatableNode, type TranslatedItem, type TranslationAdapter, type TranslationConsentRecord, type TranslationConsentStatus, TranslationController, type TranslationControllerProps, TranslationError, type TranslationErrorCode, type TranslationRequest, type TranslationResponse, type TranslationSession, type UnsupportedElementInfo, type UnsupportedReason, type UsePresetsResult, type UseProfilesResult, VOICE_COMMANDS, VOICE_NAVIGATION_DISCLAIMER, type ValidationResult, type VoiceCommandDefinition, type VoiceCommandId, type VoiceExecutionContext, VoiceNavigationController, type VoiceNavigationControllerProps, type VoiceNavigationOptions, type VoiceNavigationResult, type VoiceNavigationSession, type VoiceNavigationStatus, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, applyCustomPresetToStore, applyProfileToStore, applySmartContrast, applyTranslations, calculateContrastRatio, calculateRelativeLuminance, checkBoundariesDiagnostics, checkCspDiagnostics, checkDomDiagnostics, checkHostCssDiagnostics, checkProviderDiagnostics, checkStorageDiagnostics, compositeRgba, countWords, createCustomPreset, createInitialPreferencesState, createOfflineMockTranslationAdapter, createVoiceNavigationSession, downloadJsonFile, emitFeatureEvent, enLocale, enableAccessibleTooltips, estimateReadingTime, evaluateSmartContrast, executeVoiceCommand, exportPresetsToJson, extractArticleContent, extractReadAloudText, extractTranslatableNodes, findArticleCandidate, findMainLandmark, getActiveSelectionText, getAuthoredDescription, getMenuConfigSignature, getProfileDefinition, getScriptSpacingConstraints, getSpeechVoices, hasFinePointer, isEligibleDecorativeImage, isEligibleForSmartContrast, isForcedColorsActive, isFormFieldOrEditable, isFunctionalOrMeaningfulImage, isLargeText, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, isSensitiveElement, isSpeechRecognitionSupported, isSpeechSynthesisSupported, isValidCustomPreset, lookupLocalDictionary, lookupWord, mapFeaturesToProfileSettings, mapProfileSettingsToFeatures, matchVoiceCommand, navigateToElement, normalizeKeyCombo, normalizePreferenceValue, normalizePreferences, normalizeTranscript, nudgeReadingAid, parseColor, parseKeyboardEventToCombo, positionTooltip, preferencesReducer, recordProfileOverride, registerLocale, resolveActiveShortcut, resolveEffectiveBackdrop, resolveEffectivePreferences, resolveLocaleStrings, revertProfileFromStore, runDiagnostics, sanitizeFeatureEvent, sanitizeLookupTerm, sanitizePreferences, sanitizeTranslationOutput, scanHeadings, scanLandmarks, scanLinks, siLocale, splitTextIntoChunks, subscribeFinePointer, subscribeForcedColors, subscribePageStructure, subscribeReducedMotion, subscribeSpeechVoices, taLocale, translateHostContent, useAccessibility, useDiagnostics, usePresets, useProfiles, validateAndParseImport, validateMenuConfig, validateShortcutRemap };
1958
+ export { ALLOWED_PREFERENCE_KEYS, ALL_PROFILE_IDS, AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, type AccessibilityEventType, type AccessibilityFeatureEvent, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, AccessibilityProfilesController, type AccessibilityState, AccessibleTooltipsController, type ActiveProfileState, type AppliedSmartContrast, type ApplyPageOptions, type ArticleContent, type BackdropResolution, type BaseAccessibilityEvent, BigCursorController, type BigCursorControllerProps, CONTRAST_MODES, CONTRAST_PALETTES, CONTRAST_PROTECTED_SELECTOR, ChoiceControl, type ChoiceControlProps, type ChoiceGroup, type ChoiceOption, ContrastController, type ContrastMode, ContrastModeController, type ContrastModeValue, type ContrastPalette, type CursorSizePreference, type CustomPreset, CustomPresetsController, DEFAULT_FEATURE_GROUP_MAP, DEFAULT_MENU_GROUPS, DEFAULT_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DEFAULT_SHORTCUTS, DIAGNOSTICS_DISCLAIMER, DYSLEXIA_FONT_STACK, type DataRetentionPolicy, type DiagnosticCategory, type DiagnosticIssue, type DiagnosticSeverity, type DiagnosticsConfig, DiagnosticsHarness, type DiagnosticsHarnessProps, type DiagnosticsReport, type DiagnosticsSummary, DictionaryController, type DictionaryControllerProps, type DictionaryEntry, type DictionaryLookupResult, type DictionaryProvider, type EffectScopeTarget, type EffectsSession, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type EventTriggerSource, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureChangeEvent, type FeatureEventListener, type FeatureLocaleLabels, FeatureMenu, type FeatureMenuGroupConfig, type FeatureMenuItemConfig, type FeatureMenuProps, type FeatureOptions, type FeatureRegistration, type FeatureResetEvent, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, type GrayscaleControllerProps, HIGH_CONTRAST_TOKENS, type HeadingItem, HeadingsNavigatorController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, type ImportResult, InvertColorsController, KNOWN_FEATURE_IDS, KeyboardShortcutsController, type KeyboardShortcutsControllerProps, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, LOCAL_DICTIONARY_EN, LOCAL_DICTIONARY_SI, LOCAL_DICTIONARY_TA, type LandmarkItem, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LinkItem, type LocaleStrings, MAX_HOST_ELEMENTS, MAX_NODES_PER_TRANSLATION_BATCH, MAX_READING_MASK_HEIGHT, MAX_TEXT_LENGTH_PER_NODE, MIN_READING_MASK_HEIGHT, type MenuCustomizationConfig, type MenuValidationIssue, type MenuValidationResult, type NormalizedMenuConfig, type NormalizedMenuGroup, type NormalizedMenuItem, PROFILE_DEFINITIONS, PageNavigatorController, type PageNavigatorControllerProps, PageStructureController, type PanelToggleEvent, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PlacementChangeEvent, type PluginPosition, type PresetApplyEvent, PresetsBackupController, PresetsController, type PresetsControllerProps, type PresetsExportV1, type ProfileApplyEvent, ProfileController, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, ProfilesController, type ProfilesControllerProps, READING_MASK_HEIGHT_PRESETS, READ_ALOUD_EXCLUDED_SELECTORS, RESERVED_BROWSER_SHORTCUTS, ReadAloudController, type ReadAloudControllerProps, type ReadAloudOptions, ReadAloudSession, type ReadAloudState, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReadingModeController, type ReadingModeControllerProps, ReduceMotionController, ResetController, type RgbColor, type RgbaColor, SMART_CONTRAST_DISCLAIMER, SaturationController, type SaturationControllerProps, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SettingsImportExportController, type ShortcutDefinition, SkipToMainLink, type SkipToMainLinkProps, SmartContrastController, type SmartContrastLevel, type SmartContrastOptions, type SmartContrastReport, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TARGET_RATIOS, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TRANSLATION_DISCLAIMER, TRANSLATION_ERROR_CODES, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type TranslatableNode, type TranslatedItem, type TranslationAdapter, type TranslationConsentRecord, type TranslationConsentStatus, TranslationController, type TranslationControllerProps, TranslationError, type TranslationErrorCode, type TranslationRequest, type TranslationResponse, type TranslationSession, type UnsupportedElementInfo, type UnsupportedReason, type UsePresetsResult, type UseProfilesResult, VOICE_COMMANDS, VOICE_NAVIGATION_DISCLAIMER, type ValidationResult, type VoiceCommandDefinition, type VoiceCommandId, type VoiceExecutionContext, VoiceNavigationController, type VoiceNavigationControllerProps, type VoiceNavigationOptions, type VoiceNavigationResult, type VoiceNavigationSession, type VoiceNavigationStatus, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, applyCustomPresetToStore, applyPage, applyPageSession, applyProfileToStore, applySmartContrast, applyTranslations, calculateContrastRatio, calculateRelativeLuminance, checkBoundariesDiagnostics, checkCspDiagnostics, checkDomDiagnostics, checkHostCssDiagnostics, checkProviderDiagnostics, checkStorageDiagnostics, compositeRgba, countWords, createCustomPreset, createInitialPreferencesState, createOfflineMockTranslationAdapter, createVoiceNavigationSession, downloadJsonFile, emitFeatureEvent, enLocale, enableAccessibleTooltips, estimateReadingTime, evaluateSmartContrast, executeVoiceCommand, exportPresetsToJson, extractArticleContent, extractReadAloudText, extractTranslatableNodes, findArticleCandidate, findMainLandmark, getActiveSelectionText, getAuthoredDescription, getMenuConfigSignature, getProfileDefinition, getScriptSpacingConstraints, getSpeechVoices, hasFinePointer, isEligibleDecorativeImage, isEligibleForSmartContrast, isForcedColorsActive, isFormFieldOrEditable, isFunctionalOrMeaningfulImage, isLargeText, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, isSensitiveElement, isSpeechRecognitionSupported, isSpeechSynthesisSupported, isValidCustomPreset, lookupLocalDictionary, lookupWord, mapFeaturesToProfileSettings, mapProfileSettingsToFeatures, matchVoiceCommand, navigateToElement, normalizeKeyCombo, normalizePreferenceValue, normalizePreferences, normalizeTranscript, nudgeReadingAid, parseColor, parseKeyboardEventToCombo, positionTooltip, preferencesReducer, recordProfileOverride, registerLocale, resolveActiveShortcut, resolveEffectScope, resolveEffectiveBackdrop, resolveEffectivePreferences, resolveLocaleStrings, revertProfileFromStore, runDiagnostics, sanitizeFeatureEvent, sanitizeLookupTerm, sanitizePreferences, sanitizeTranslationOutput, scanHeadings, scanLandmarks, scanLinks, siLocale, splitTextIntoChunks, subscribeFinePointer, subscribeForcedColors, subscribePageStructure, subscribeReducedMotion, subscribeSpeechVoices, taLocale, translateHostContent, useAccessibility, useDiagnostics, usePresets, useProfiles, validateAndParseImport, validateMenuConfig, validateShortcutRemap };