diff --git a/CHANGELOG.md b/CHANGELOG.md index dddd355..e20b6a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 2.31.0 — 2026-11-20 + +- Overhaul HTML and CSS-based image hiding (`HideImagesController` default `mode="all"` and dedicated `HideDecorativeImagesController` `mode="decorative"`): + - Hide all non-protected host `` (including non-empty `alt` and missing `alt`), ``, ``, ``, and explicitly decorative `` elements in `HideImagesController` (`mode="all"`), while preserving strict decorative-only filtering on `HideDecorativeImagesController` and ``. + - Export `HIDE_IMAGES_MODES`, `HideImagesMode`, and `HideImagesValue` from `accessibility-plugin-react` and update `builtins.hideImages` schema validation to accept `boolean | "all" | "decorative"`. + - Fix CSS image hiding across `background-image`, `background` shorthand, CSS variables (`var(...)`), `image-set()` / `-webkit-image-set()` / `cross-fade()`, `list-style-image`, element `content: url(...)`, `document.documentElement`/`document.body` host roots, and `::before`/`::after` pseudo-elements (via CSP-nonce-aware `#arap-hide-images-style`, `ShadowRoot` styles, and stylesheet rule scanning) while preserving pure CSS gradients. + - Eliminate false-positive CSS container exclusions on landmarks (`
`, `role="banner"`) and word substrings (`.paragraph`, `.typography`, `.photography`, `.roadmap`, `.sitemap`, `.charter`, `.aftermath`, `.faqRow`) via word-boundary token matching, while keeping widget UI, `[data-arap-ignore]`/`[data-arap-exempt]`, buttons/controls, icon-only links, CAPTCHAs, charts, maps, QR/barcodes, and math protected. + - Handle dynamic `style`, `class`, and media-attribute mutations incrementally via `applyMediaIncremental()` with `observer.takeRecords()` feedback-loop protection and memoized effect options in `AccessibilityPlugin`. + ## 2.30.1 — 2026-11-18 - Fix decorative image classification inside `
` and add client-side Google Translate adapter (#201): diff --git a/docs/API.md b/docs/API.md index b28a61e..5a2c490 100644 --- a/docs/API.md +++ b/docs/API.md @@ -4,35 +4,36 @@ All exports are named from `accessibility-plugin-react`. JavaScript consumers re ## Components -| Component | Props | -| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| AccessibilityPlugin | `children: ReactNode` required; `position?: 'left' \| 'right' \| 'top' \| 'bottom'` default right; `persistenceKey?: string` default `react-accessibility-plugin:state`; `persist?: boolean` default true; `storage?: 'local' \| 'session' \| 'none'` default local; `locale?: string`; `statementUrl?: string`; `largeControls?: boolean` default false | -| AccessibilityButton | `draggable?: boolean` default true (pointer/Alt+arrow movement); `icon?: ReactNode` default inline accessibility SVG; `title?: string` accessible name, default Accessibility; `description?: string` supplementary accessible description; `className?: string`; `style?: CSSProperties`; `largeControls?: boolean` | -| AccessibilityList | `footer?: ReactNode` extra fixed actions; `children?: ReactNode` optional; `menuConfig?: MenuCustomizationConfig` optional; `title?: string` visible heading and region name, default Accessibility settings; `description?: string` default Adjust your reading experience; `closeLabel?: string` default Close; `statementUrl?: string`; `largeControls?: boolean`; `locale?: string`; `className?: string`; `style?: CSSProperties` | -| FeatureMenu | `config?: MenuCustomizationConfig`; `grouped?: boolean` default false; `className?: string`. Renders an ordered, validated, and optionally grouped accessibility menu with non-crashing diagnostics and stable rerenders. See docs/MENU_CUSTOMIZATION.md. | -| FeatureCard | `title: ReactNode` required; `children: ReactNode` required; `featureKey?: string`; `icon?: ReactNode`; `description?: ReactNode`; `statusBadge?: string`; `status?: 'idle' \| 'active' \| 'error' \| 'unavailable' \| 'permission-required'`; `errorMessage?: string`; `unavailableMessage?: string`; `permissionMessage?: string`; `onRequestPermission?: () => void`; `largeControls?: boolean` | -| FeatureGroup | `title: string` required; `id?: string`; `description?: string`; `badge?: string`; `collapsible?: boolean` default false; `defaultExpanded?: boolean` default true; `expanded?: boolean`; `onExpandedChange?: (expanded: boolean) => void`; `children: ReactNode` | -| ModalDialog | `isOpen: boolean` required; `onClose: () => void` required; `title: string` required; `subtitle?: string`; `icon?: ReactNode`; `closeLabel?: string`; `size?: 'md' \| 'lg' \| 'full'`; `trapFocus?: boolean`; `lockScroll?: boolean`; `footer?: ReactNode`; `children: ReactNode` | -| ToggleControl | `label: ReactNode` required; `checked: boolean` required; `onChange: (checked: boolean) => void` required; `disabled?: boolean`; `unavailable?: boolean`; `unavailableReason?: string`; `largeControls?: boolean` | -| ChoiceControl | `label: string` required; `value: T` required; `options?: ChoiceOption[]`; `groups?: ChoiceGroup[]`; `onChange: (value: T) => void` required; `disabled?: boolean`; `largeControls?: boolean` | -| StepperControl | `label: string` required; `value: number` required; `min: number`; `max: number`; `step: number`; `unit?: string` default '%'; `showSlider?: boolean`; `formatValue?: (val: number) => string`; `onChange: (value: number) => void` required; `disabled?: boolean`; `largeControls?: boolean` | -| ProfilePreviewCard | `profile: ProfileDefinition` required; `isActive: boolean` required; `onApply: (profile: ProfileDefinition) => void` required; `onRevert: () => void` required; `largeControls?: boolean` | -| TextScaleController | `steps?: readonly number[]` default `[1.0, 1.125, 1.25, 1.5, 2.0]`; `label?: string` default `Bigger Text`. Stepped text scaling without transforms. | -| FontSizeController | Optional `stepScale?: boolean` (snaps to WCAG 1x–2x reflow steps); `steps?: readonly number[]` (custom steps); or omitted for continuous 10% steps. Protects forms, code, and icons. | -| LineHeightController | Optional `stepPresets?: boolean` (snaps to WCAG 1.0x, 1.5x, 1.75x, 2.0x); `steps?: readonly number[]` (custom steps); or omitted for 10% steps. Excludes tables, code, and controls. | -| LetterSpacingController | Optional `min`, `max`, `step`, `steps`. Excludes tables and code blocks; respects language-aware limits (disables on cursive/Arabic, clamps <=1px on Indic/Sinhala/Tamil). | -| WordSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–10px, step 1). Excludes tables, code blocks, controls, and widget UI. | -| ParagraphSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–32px, step 4). Increases bottom margin on `p` and `[role="paragraph"]`. | -| PageNavigatorController | Optional `title?: string`, `headingsLabel?: string`, `landmarksLabel?: string`, `searchPlaceholder?: string`, `largeControls?: boolean`. Interactive headings and landmarks navigator with safe focus and live updates. Aliases: `HeadingsNavigatorController`, `PageStructureController`. See docs/PAGE_NAVIGATOR.md. | -| ProfilesController | Optional `label?: string`, `description?: string`, `largeControls?: boolean`, `onProfileChange?: (id) => void`. Previews, applies, and reverts eight neutral presets with deterministic override model. Aliases: `ProfileController`, `AccessibilityProfilesController`. See docs/PROFILES.md. | -| PresetsController | Optional `className?: string`, `label?: string`, `description?: string`, `largeControls?: boolean`. Saves named custom presets and handles versioned JSON import/export with privacy exclusions. Aliases: `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`. See docs/PRESETS.md. | -| ReadAloudController | Optional `className?: string`, `label?: string`, `description?: string`, `onStart?: () => void`, `onEnd?: () => void`, `onError?: (error: Error) => void`. User-initiated client-side text-to-speech read-aloud via Web Speech API (`speechSynthesis`). See docs/READ_ALOUD.md. | -| DictionaryController | Optional `className?: string`, `label?: string`, `description?: string`, `provider?: DictionaryProvider | null`, `defaultOpen?: boolean`, `initialTerm?: string`. Accessible dictionary lookup dialog with zero network requests by default, local glossaries, and sanitization. See docs/DICTIONARY.md. | -| VoiceNavigationController | Optional `className?: string`, `label?: string`, `description?: string`. Opt-in research prototype controller enabling browser-native speech commands with inactivity watchdog and keyboard fallback buttons. See docs/VOICE_NAVIGATION.md. | -| TranslationController | Optional `className?: string`, `label?: string`, `description?: string`, `provider?: TranslationAdapter`, `defaultTargetLanguage?: string`. Host-content translation adapter prototype with explicit consent, privacy boundaries, sensitive element exclusion, and DOM restoration. See docs/TRANSLATION.md. | -| SmartContrastController | Optional `className?: string`, `label?: string`, `description?: string`, `options?: SmartContrastOptions`. Measured smart contrast research prototype with relative luminance, alpha compositing, live statistics, and non-destructive restoration. See docs/SMART_CONTRAST.md. | -| DiagnosticsHarness | Optional `config?: DiagnosticsConfig`, `visible?: boolean`, `className?: string`. Development-only integration diagnostics harness inspecting containing-block traps, CSP, host CSS, and accessibility landmarks. See docs/DIAGNOSTICS.md. | -| All other controllers in FEATURES.md | Pick/omit in JSX. For custom labels or behavior, compose a control with useAccessibility or the modular control primitives. | +| Component | Props | +| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| AccessibilityPlugin | `children: ReactNode` required; `position?: 'left' \| 'right' \| 'top' \| 'bottom'` default right; `persistenceKey?: string` default `react-accessibility-plugin:state`; `persist?: boolean` default true; `storage?: 'local' \| 'session' \| 'none'` default local; `locale?: string`; `statementUrl?: string`; `largeControls?: boolean` default false | +| AccessibilityButton | `draggable?: boolean` default true (pointer/Alt+arrow movement); `icon?: ReactNode` default inline accessibility SVG; `title?: string` accessible name, default Accessibility; `description?: string` supplementary accessible description; `className?: string`; `style?: CSSProperties`; `largeControls?: boolean` | +| AccessibilityList | `footer?: ReactNode` extra fixed actions; `children?: ReactNode` optional; `menuConfig?: MenuCustomizationConfig` optional; `title?: string` visible heading and region name, default Accessibility settings; `description?: string` default Adjust your reading experience; `closeLabel?: string` default Close; `statementUrl?: string`; `largeControls?: boolean`; `locale?: string`; `className?: string`; `style?: CSSProperties` | +| FeatureMenu | `config?: MenuCustomizationConfig`; `grouped?: boolean` default false; `className?: string`. Renders an ordered, validated, and optionally grouped accessibility menu with non-crashing diagnostics and stable rerenders. See docs/MENU_CUSTOMIZATION.md. | +| FeatureCard | `title: ReactNode` required; `children: ReactNode` required; `featureKey?: string`; `icon?: ReactNode`; `description?: ReactNode`; `statusBadge?: string`; `status?: 'idle' \| 'active' \| 'error' \| 'unavailable' \| 'permission-required'`; `errorMessage?: string`; `unavailableMessage?: string`; `permissionMessage?: string`; `onRequestPermission?: () => void`; `largeControls?: boolean` | +| FeatureGroup | `title: string` required; `id?: string`; `description?: string`; `badge?: string`; `collapsible?: boolean` default false; `defaultExpanded?: boolean` default true; `expanded?: boolean`; `onExpandedChange?: (expanded: boolean) => void`; `children: ReactNode` | +| ModalDialog | `isOpen: boolean` required; `onClose: () => void` required; `title: string` required; `subtitle?: string`; `icon?: ReactNode`; `closeLabel?: string`; `size?: 'md' \| 'lg' \| 'full'`; `trapFocus?: boolean`; `lockScroll?: boolean`; `footer?: ReactNode`; `children: ReactNode` | +| ToggleControl | `label: ReactNode` required; `checked: boolean` required; `onChange: (checked: boolean) => void` required; `disabled?: boolean`; `unavailable?: boolean`; `unavailableReason?: string`; `largeControls?: boolean` | +| ChoiceControl | `label: string` required; `value: T` required; `options?: ChoiceOption[]`; `groups?: ChoiceGroup[]`; `onChange: (value: T) => void` required; `disabled?: boolean`; `largeControls?: boolean` | +| StepperControl | `label: string` required; `value: number` required; `min: number`; `max: number`; `step: number`; `unit?: string` default '%'; `showSlider?: boolean`; `formatValue?: (val: number) => string`; `onChange: (value: number) => void` required; `disabled?: boolean`; `largeControls?: boolean` | +| ProfilePreviewCard | `profile: ProfileDefinition` required; `isActive: boolean` required; `onApply: (profile: ProfileDefinition) => void` required; `onRevert: () => void` required; `largeControls?: boolean` | +| TextScaleController | `steps?: readonly number[]` default `[1.0, 1.125, 1.25, 1.5, 2.0]`; `label?: string` default `Bigger Text`. Stepped text scaling without transforms. | +| FontSizeController | Optional `stepScale?: boolean` (snaps to WCAG 1x–2x reflow steps); `steps?: readonly number[]` (custom steps); or omitted for continuous 10% steps. Protects forms, code, and icons. | +| LineHeightController | Optional `stepPresets?: boolean` (snaps to WCAG 1.0x, 1.5x, 1.75x, 2.0x); `steps?: readonly number[]` (custom steps); or omitted for 10% steps. Excludes tables, code, and controls. | +| LetterSpacingController | Optional `min`, `max`, `step`, `steps`. Excludes tables and code blocks; respects language-aware limits (disables on cursive/Arabic, clamps <=1px on Indic/Sinhala/Tamil). | +| WordSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–10px, step 1). Excludes tables, code blocks, controls, and widget UI. | +| ParagraphSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–32px, step 4). Increases bottom margin on `p` and `[role="paragraph"]`. | +| PageNavigatorController | Optional `title?: string`, `headingsLabel?: string`, `landmarksLabel?: string`, `searchPlaceholder?: string`, `largeControls?: boolean`. Interactive headings and landmarks navigator with safe focus and live updates. Aliases: `HeadingsNavigatorController`, `PageStructureController`. See docs/PAGE_NAVIGATOR.md. | +| ProfilesController | Optional `label?: string`, `description?: string`, `largeControls?: boolean`, `onProfileChange?: (id) => void`. Previews, applies, and reverts eight neutral presets with deterministic override model. Aliases: `ProfileController`, `AccessibilityProfilesController`. See docs/PROFILES.md. | +| PresetsController | Optional `className?: string`, `label?: string`, `description?: string`, `largeControls?: boolean`. Saves named custom presets and handles versioned JSON import/export with privacy exclusions. Aliases: `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`. See docs/PRESETS.md. | +| ReadAloudController | Optional `className?: string`, `label?: string`, `description?: string`, `onStart?: () => void`, `onEnd?: () => void`, `onError?: (error: Error) => void`. User-initiated client-side text-to-speech read-aloud via Web Speech API (`speechSynthesis`). See docs/READ_ALOUD.md. | +| DictionaryController | Optional `className?: string`, `label?: string`, `description?: string`, `provider?: DictionaryProvider | null`, `defaultOpen?: boolean`, `initialTerm?: string`. Accessible dictionary lookup dialog with zero network requests by default, local glossaries, and sanitization. See docs/DICTIONARY.md. | +| VoiceNavigationController | Optional `className?: string`, `label?: string`, `description?: string`. Opt-in research prototype controller enabling browser-native speech commands with inactivity watchdog and keyboard fallback buttons. See docs/VOICE_NAVIGATION.md. | +| TranslationController | Optional `className?: string`, `label?: string`, `description?: string`, `provider?: TranslationAdapter`, `defaultTargetLanguage?: string`. Host-content translation adapter prototype with explicit consent, privacy boundaries, sensitive element exclusion, and DOM restoration. See docs/TRANSLATION.md. | +| SmartContrastController | Optional `className?: string`, `label?: string`, `description?: string`, `options?: SmartContrastOptions`. Measured smart contrast research prototype with relative luminance, alpha compositing, live statistics, and non-destructive restoration. See docs/SMART_CONTRAST.md. | +| DiagnosticsHarness | Optional `config?: DiagnosticsConfig`, `visible?: boolean`, `className?: string`. Development-only integration diagnostics harness inspecting containing-block traps, CSP, host CSS, and accessibility landmarks. See docs/DIAGNOSTICS.md. | +| HideImagesController / HideDecorativeImagesController | `HideImagesControllerProps`: optional `label?: string` (`"Hide Images"` / `"Hide Decorative Images"`) and `mode?: "all" \| "decorative"` (`HideImagesController` defaults to `"all"`; `HideDecorativeImagesController` defaults to `"decorative"`). See docs/DECORATIVE_IMAGES.md. | +| All other controllers in FEATURES.md | Pick/omit in JSX. For custom labels or behavior, compose a control with useAccessibility or the modular control primitives. | Use one button/list pair per provider and one provider per document. UI IDs use React `useId`; do not target the old fixed `arap-panel` ID. Plugin children can include ordinary app content, but mounting the widget as a sibling makes intent clearer. Persistence configuration is fixed at mount; use `` when switching storage identity. @@ -60,11 +61,11 @@ Definitions/defaults are immutable for the provider lifetime; the first register `FeatureRegistration` is `FeatureOptions` plus `defaultValue: unknown`. Use the generic hook instead of manually casting callbacks. Legacy `registerReset(key, fn)` / `unregisterReset(key)` remain available; callbacks run before global state is cleared. They are not the primary effect lifecycle API. Callback owners must unregister their callback on teardown. -Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption`, `ChoiceGroup`, `StepperControlProps`, `FeatureCardProps`, `FeatureGroupProps`, `ModalDialogProps`, `FeatureStatus`, `SearchCountProps`, `EmptyStateProps`, `ErrorStateProps`, `ProfilePreviewCardProps`, `FontSizeControllerProps`, `TextScaleControllerProps`, `TextScaleStep`, `FontFamilyPreset`, `ContrastModeValue`, `ContrastPalette`, `LineHeightControllerProps`, `LetterSpacingControllerProps`, `WordSpacingControllerProps`, `ParagraphSpacingControllerProps`, `ScriptSpacingConstraints`, `SkipToMainLinkProps`, `HideImagesControllerProps`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `TooltipsControllerProps`, `PageNavigatorControllerProps`, `HeadingItem`, `LandmarkItem`, `LinkItem`, `ProfilesControllerProps`, `ActiveProfileState`, `UseProfilesResult`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`, `SupportedLocale`, `FeatureLocaleLabels`, `PresetsControllerProps`, `CustomPreset`, `PresetsExportV1`, `ImportResult`, `UsePresetsResult`, `ReadingModeControllerProps`, `ArticleContent`, `KeyboardShortcutsControllerProps`, `ShortcutDefinition`, `ValidationResult`, `ReadAloudControllerProps`, `ReadAloudOptions`, `ReadAloudState`, `SaturationControllerProps`, `GrayscaleControllerProps`, `DictionaryControllerProps`, `DictionaryEntry`, `DictionaryLookupResult`, `DictionaryProvider`, `FeatureMenuProps`, `FeatureMenuItemConfig`, `FeatureMenuGroupConfig`, `MenuCustomizationConfig`, `MenuValidationIssue`, `MenuValidationResult`, `NormalizedMenuConfig`, `NormalizedMenuItem`, `NormalizedMenuGroup`, `VoiceNavigationControllerProps`, `VoiceNavigationStatus`, `VoiceCommandId`, `VoiceCommandDefinition`, `VoiceNavigationResult`, `VoiceNavigationOptions`, `VoiceNavigationSession`, `VoiceExecutionContext`, `TranslationControllerProps`, `TranslationAdapter`, `TranslationRequest`, `TranslationResponse`, `TranslatedItem`, `DataRetentionPolicy`, `TranslationConsentStatus`, `TranslationConsentRecord`, `TranslatableNode`, `TranslationSession`, `TranslationErrorCode`, `SmartContrastLevel`, `UnsupportedReason`, `RgbColor`, `RgbaColor`, `UnsupportedElementInfo`, `SmartContrastReport`, `SmartContrastOptions`, `AppliedSmartContrast`, `BackdropResolution`, `DiagnosticsHarnessProps`, `DiagnosticCategory`, `DiagnosticIssue`, `DiagnosticSeverity`, `DiagnosticsConfig`, `DiagnosticsReport`, `DiagnosticsSummary`, `AccessibilityEventType`, `EventTriggerSource`, `BaseAccessibilityEvent`, `FeatureChangeEvent`, `FeatureResetEvent`, `PanelToggleEvent`, `PlacementChangeEvent`, `ProfileApplyEvent`, `PresetApplyEvent`, `AccessibilityFeatureEvent`, `FeatureEventListener`. +Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption`, `ChoiceGroup`, `StepperControlProps`, `FeatureCardProps`, `FeatureGroupProps`, `ModalDialogProps`, `FeatureStatus`, `SearchCountProps`, `EmptyStateProps`, `ErrorStateProps`, `ProfilePreviewCardProps`, `FontSizeControllerProps`, `TextScaleControllerProps`, `TextScaleStep`, `FontFamilyPreset`, `ContrastModeValue`, `ContrastPalette`, `LineHeightControllerProps`, `LetterSpacingControllerProps`, `WordSpacingControllerProps`, `ParagraphSpacingControllerProps`, `ScriptSpacingConstraints`, `SkipToMainLinkProps`, `HideImagesControllerProps`, `HideImagesMode`, `HideImagesValue`, `BigCursorControllerProps`, `ReadingMaskControllerProps`, `ReadingGuideControllerProps`, `TooltipsControllerProps`, `PageNavigatorControllerProps`, `HeadingItem`, `LandmarkItem`, `LinkItem`, `ProfilesControllerProps`, `ActiveProfileState`, `UseProfilesResult`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`, `SupportedLocale`, `FeatureLocaleLabels`, `PresetsControllerProps`, `CustomPreset`, `PresetsExportV1`, `ImportResult`, `UsePresetsResult`, `ReadingModeControllerProps`, `ArticleContent`, `KeyboardShortcutsControllerProps`, `ShortcutDefinition`, `ValidationResult`, `ReadAloudControllerProps`, `ReadAloudOptions`, `ReadAloudState`, `SaturationControllerProps`, `GrayscaleControllerProps`, `DictionaryControllerProps`, `DictionaryEntry`, `DictionaryLookupResult`, `DictionaryProvider`, `FeatureMenuProps`, `FeatureMenuItemConfig`, `FeatureMenuGroupConfig`, `MenuCustomizationConfig`, `MenuValidationIssue`, `MenuValidationResult`, `NormalizedMenuConfig`, `NormalizedMenuItem`, `NormalizedMenuGroup`, `VoiceNavigationControllerProps`, `VoiceNavigationStatus`, `VoiceCommandId`, `VoiceCommandDefinition`, `VoiceNavigationResult`, `VoiceNavigationOptions`, `VoiceNavigationSession`, `VoiceExecutionContext`, `TranslationControllerProps`, `TranslationAdapter`, `TranslationRequest`, `TranslationResponse`, `TranslatedItem`, `DataRetentionPolicy`, `TranslationConsentStatus`, `TranslationConsentRecord`, `TranslatableNode`, `TranslationSession`, `TranslationErrorCode`, `SmartContrastLevel`, `UnsupportedReason`, `RgbColor`, `RgbaColor`, `UnsupportedElementInfo`, `SmartContrastReport`, `SmartContrastOptions`, `AppliedSmartContrast`, `BackdropResolution`, `DiagnosticsHarnessProps`, `DiagnosticCategory`, `DiagnosticIssue`, `DiagnosticSeverity`, `DiagnosticsConfig`, `DiagnosticsReport`, `DiagnosticsSummary`, `AccessibilityEventType`, `EventTriggerSource`, `BaseAccessibilityEvent`, `FeatureChangeEvent`, `FeatureResetEvent`, `PanelToggleEvent`, `PlacementChangeEvent`, `ProfileApplyEvent`, `PresetApplyEvent`, `AccessibilityFeatureEvent`, `FeatureEventListener`. Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `FeatureGroup`, `ModalDialog`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`, `SmartContrastController`, `LinkHighlightController`, `HighlightFocusController`, `FocusHighlightController`, `ReduceMotionController`, `HideImagesController`, `HideDecorativeImagesController`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `TooltipsController`, `AccessibleTooltipsController`, `PageNavigatorController`, `HeadingsNavigatorController`, `PageStructureController`, `ProfilesController`, `ProfileController`, `AccessibilityProfilesController`, `PresetsController`, `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`, `ReadingModeController`, `KeyboardShortcutsController`, `ReadAloudController`, `DictionaryController`, `VoiceNavigationController`, `TranslationController`, `FeatureMenu`, `SkipToMainLink`, `DiagnosticsHarness`. -Exported typography, contrast, reading aids, tooltips, reading mode, read aloud, reflow, and menu customization utilities: `TEXT_SCALE_STEPS`, `TEXT_SCALE_PROTECTED_SELECTOR`, `isProtectedFromTextScale`, `LINE_HEIGHT_STEPS`, `LINE_HEIGHT_RATIOS`, `TEXT_SPACING_EXCLUDED_SELECTOR`, `isProtectedFromTextSpacing`, `getScriptSpacingConstraints`, `FONT_FAMILY_PRESETS`, `LEGIBLE_FONT_STACK`, `DYSLEXIA_FONT_STACK`, `FONT_FAMILY_PROTECTED_SELECTOR`, `isProtectedFromFontFamily`, `TEXT_ALIGN_BLOCK_SELECTOR`, `isProtectedFromTextAlign`, `CONTRAST_MODES`, `isForcedColorsActive`, `subscribeForcedColors`, `isReducedMotionActive`, `subscribeReducedMotion`, `isEligibleDecorativeImage`, `isFunctionalOrMeaningfulImage`, `hasFinePointer`, `subscribeFinePointer`, `nudgeReadingAid`, `DEFAULT_READING_MASK_HEIGHT`, `MIN_READING_MASK_HEIGHT`, `MAX_READING_MASK_HEIGHT`, `READING_MASK_HEIGHT_PRESETS`, `getAuthoredDescription`, `positionTooltip`, `enableAccessibleTooltips`, `scanHeadings`, `scanLandmarks`, `scanLinks`, `navigateToElement`, `subscribePageStructure`, `useProfiles`, `ALL_PROFILE_IDS`, `getProfileDefinition`, `mapProfileSettingsToFeatures`, `mapFeaturesToProfileSettings`, `applyProfileToStore`, `revertProfileFromStore`, `recordProfileOverride`, `usePresets`, `createCustomPreset`, `isValidCustomPreset`, `exportPresetsToJson`, `downloadJsonFile`, `validateAndParseImport`, `applyCustomPresetToStore`, `sanitizePreferences`, `ALLOWED_PREFERENCE_KEYS`, `extractArticleContent`, `findArticleCandidate`, `countWords`, `estimateReadingTime`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`, `DEFAULT_SHORTCUTS`, `RESERVED_BROWSER_SHORTCUTS`, `normalizeKeyCombo`, `parseKeyboardEventToCombo`, `isFormFieldOrEditable`, `validateShortcutRemap`, `resolveActiveShortcut`, `isSpeechSynthesisSupported`, `getSpeechVoices`, `subscribeSpeechVoices`, `getActiveSelectionText`, `extractReadAloudText`, `splitTextIntoChunks`, `ReadAloudSession`, `READ_ALOUD_EXCLUDED_SELECTORS`, `sanitizeLookupTerm`, `lookupLocalDictionary`, `lookupWord`, `LOCAL_DICTIONARY_EN`, `LOCAL_DICTIONARY_SI`, `LOCAL_DICTIONARY_TA`, `validateMenuConfig`, `getMenuConfigSignature`, `KNOWN_FEATURE_IDS`, `DEFAULT_MENU_GROUPS`, `DEFAULT_FEATURE_GROUP_MAP`, `SMART_CONTRAST_DISCLAIMER`, `TARGET_RATIOS`, `HIGH_CONTRAST_TOKENS`, `parseColor`, `calculateRelativeLuminance`, `calculateContrastRatio`, `compositeRgba`, `isLargeText`, `resolveEffectiveBackdrop`, `isEligibleForSmartContrast`, `evaluateSmartContrast`, `applySmartContrast`, `VOICE_COMMANDS`, `VOICE_NAVIGATION_DISCLAIMER`, `isSpeechRecognitionSupported`, `normalizeTranscript`, `matchVoiceCommand`, `executeVoiceCommand`, `createVoiceNavigationSession`, `TRANSLATION_ERROR_CODES`, `TRANSLATION_DISCLAIMER`, `MAX_NODES_PER_TRANSLATION_BATCH`, `MAX_TEXT_LENGTH_PER_NODE`, `isSensitiveElement`, `extractTranslatableNodes`, `sanitizeTranslationOutput`, `applyTranslations`, `createOfflineMockTranslationAdapter`, `translateHostContent`, `TranslationError`, `runDiagnostics`, `checkProviderDiagnostics`, `checkStorageDiagnostics`, `checkCspDiagnostics`, `checkHostCssDiagnostics`, `checkDomDiagnostics`, `checkBoundariesDiagnostics`, `DIAGNOSTICS_DISCLAIMER`, `useDiagnostics`, `sanitizeFeatureEvent`, `emitFeatureEvent`. +Exported typography, contrast, reading aids, tooltips, reading mode, read aloud, reflow, and menu customization utilities: `TEXT_SCALE_STEPS`, `TEXT_SCALE_PROTECTED_SELECTOR`, `isProtectedFromTextScale`, `HIDE_IMAGES_MODES`, `LINE_HEIGHT_STEPS`, `LINE_HEIGHT_RATIOS`, `TEXT_SPACING_EXCLUDED_SELECTOR`, `isProtectedFromTextSpacing`, `getScriptSpacingConstraints`, `FONT_FAMILY_PRESETS`, `LEGIBLE_FONT_STACK`, `DYSLEXIA_FONT_STACK`, `FONT_FAMILY_PROTECTED_SELECTOR`, `isProtectedFromFontFamily`, `TEXT_ALIGN_BLOCK_SELECTOR`, `isProtectedFromTextAlign`, `CONTRAST_MODES`, `isForcedColorsActive`, `subscribeForcedColors`, `isReducedMotionActive`, `subscribeReducedMotion`, `isEligibleDecorativeImage`, `isFunctionalOrMeaningfulImage`, `hasFinePointer`, `subscribeFinePointer`, `nudgeReadingAid`, `DEFAULT_READING_MASK_HEIGHT`, `MIN_READING_MASK_HEIGHT`, `MAX_READING_MASK_HEIGHT`, `READING_MASK_HEIGHT_PRESETS`, `getAuthoredDescription`, `positionTooltip`, `enableAccessibleTooltips`, `scanHeadings`, `scanLandmarks`, `scanLinks`, `navigateToElement`, `subscribePageStructure`, `useProfiles`, `ALL_PROFILE_IDS`, `getProfileDefinition`, `mapProfileSettingsToFeatures`, `mapFeaturesToProfileSettings`, `applyProfileToStore`, `revertProfileFromStore`, `recordProfileOverride`, `usePresets`, `createCustomPreset`, `isValidCustomPreset`, `exportPresetsToJson`, `downloadJsonFile`, `validateAndParseImport`, `applyCustomPresetToStore`, `sanitizePreferences`, `ALLOWED_PREFERENCE_KEYS`, `extractArticleContent`, `findArticleCandidate`, `countWords`, `estimateReadingTime`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`, `DEFAULT_SHORTCUTS`, `RESERVED_BROWSER_SHORTCUTS`, `normalizeKeyCombo`, `parseKeyboardEventToCombo`, `isFormFieldOrEditable`, `validateShortcutRemap`, `resolveActiveShortcut`, `isSpeechSynthesisSupported`, `getSpeechVoices`, `subscribeSpeechVoices`, `getActiveSelectionText`, `extractReadAloudText`, `splitTextIntoChunks`, `ReadAloudSession`, `READ_ALOUD_EXCLUDED_SELECTORS`, `sanitizeLookupTerm`, `lookupLocalDictionary`, `lookupWord`, `LOCAL_DICTIONARY_EN`, `LOCAL_DICTIONARY_SI`, `LOCAL_DICTIONARY_TA`, `validateMenuConfig`, `getMenuConfigSignature`, `KNOWN_FEATURE_IDS`, `DEFAULT_MENU_GROUPS`, `DEFAULT_FEATURE_GROUP_MAP`, `SMART_CONTRAST_DISCLAIMER`, `TARGET_RATIOS`, `HIGH_CONTRAST_TOKENS`, `parseColor`, `calculateRelativeLuminance`, `calculateContrastRatio`, `compositeRgba`, `isLargeText`, `resolveEffectiveBackdrop`, `isEligibleForSmartContrast`, `evaluateSmartContrast`, `applySmartContrast`, `VOICE_COMMANDS`, `VOICE_NAVIGATION_DISCLAIMER`, `isSpeechRecognitionSupported`, `normalizeTranscript`, `matchVoiceCommand`, `executeVoiceCommand`, `createVoiceNavigationSession`, `TRANSLATION_ERROR_CODES`, `TRANSLATION_DISCLAIMER`, `MAX_NODES_PER_TRANSLATION_BATCH`, `MAX_TEXT_LENGTH_PER_NODE`, `isSensitiveElement`, `extractTranslatableNodes`, `sanitizeTranslationOutput`, `applyTranslations`, `createOfflineMockTranslationAdapter`, `translateHostContent`, `TranslationError`, `runDiagnostics`, `checkProviderDiagnostics`, `checkStorageDiagnostics`, `checkCspDiagnostics`, `checkHostCssDiagnostics`, `checkDomDiagnostics`, `checkBoundariesDiagnostics`, `DIAGNOSTICS_DISCLAIMER`, `useDiagnostics`, `sanitizeFeatureEvent`, `emitFeatureEvent`. Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`. @@ -178,7 +179,7 @@ React hook returning reactive diagnostics reports. ### `AccessibilityPluginProps.nonce` (Issue #13) - Type: `string` -- Optional Content Security Policy (CSP) nonce attribute passed to all dynamically injected `
` (including non-empty `alt` and missing `alt`), ``, ``, ``, and explicitly decorative `` elements. + - Hides all CSS-based images across host elements (including `html`/`body` in host-wide scope), covering `background-image`, `background` shorthand, CSS custom properties (`var(...)`), `image-set()`, `list-style-image`, element `content: url(...)`, and `::before` / `::after` pseudo-element images (`background-image` and `content: url(...)`). + - Preserves pure CSS gradients (`linear-gradient`, `radial-gradient`, etc.), widget UI, `[data-arap-ignore]` / `[data-arap-exempt]` regions, `` elements, meaningful `` elements, linked images, and informative CSS `role="img"` containers. +3. **Never fabricate alt text**: The plugin never mutates, synthesizes, or generates AI/heuristic `alt` text or accessible names. It strictly acts as a client-side display-preference modifier. -5. **Scoped CSS Background Images**: - CSS background images are only stripped from non-functional, non-meaningful layout containers. Buttons, links, CAPTCHA, charts, and maps retain their background graphics. -6. **Idempotent and Reversible Lifecycle**: - Every visual override is tracked inline with priority preservation and completely restored upon toggle-off, reset, or plugin unmount. +4. **Word-boundary token matching (zero false positives)**: + Protection selectors split camelCase and match protected tokens (`captcha`, `chart`/`graph`/`diagram`, `map`, `qr`/`barcode`, `math`) on token boundaries so ordinary class names such as `.paragraph`, `.typography`, `.photography`, `.roadmap`, `.sitemap`, `.charter`, or `.aftermath` are never mistakenly excluded. +5. **Idempotent, dynamic, and reversible lifecycle**: + Inline style overrides, dynamic `