accessibility-plugin-react 2.17.0 → 2.28.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/docs/API.md CHANGED
@@ -4,26 +4,31 @@ All exports are named from `accessibility-plugin-react`. JavaScript consumers re
4
4
 
5
5
  ## Components
6
6
 
7
- | Component | Props |
8
- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | 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 |
10
- | 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` |
11
- | AccessibilityList | `footer?: ReactNode` extra fixed actions; `children: ReactNode` required; `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` |
12
- | 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` |
13
- | ToggleControl | `label: ReactNode` required; `checked: boolean` required; `onChange: (checked: boolean) => void` required; `disabled?: boolean`; `unavailable?: boolean`; `unavailableReason?: string`; `largeControls?: boolean` |
14
- | ChoiceControl | `label: string` required; `value: T` required; `options?: ChoiceOption<T>[]`; `groups?: ChoiceGroup<T>[]`; `onChange: (value: T) => void` required; `disabled?: boolean`; `largeControls?: boolean` |
15
- | 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` |
16
- | ProfilePreviewCard | `profile: ProfileDefinition` required; `isActive: boolean` required; `onApply: (profile: ProfileDefinition) => void` required; `onRevert: () => void` required; `largeControls?: boolean` |
17
- | 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. |
18
- | 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. |
19
- | 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. |
20
- | 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). |
21
- | WordSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–10px, step 1). Excludes tables, code blocks, controls, and widget UI. |
22
- | ParagraphSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–32px, step 4). Increases bottom margin on `p` and `[role="paragraph"]`. |
23
- | 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. |
24
- | 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. |
25
- | 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. |
26
- | 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. |
7
+ | Component | Props |
8
+ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | 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 |
10
+ | 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` |
11
+ | 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` |
12
+ | 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. |
13
+ | 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` |
14
+ | ToggleControl | `label: ReactNode` required; `checked: boolean` required; `onChange: (checked: boolean) => void` required; `disabled?: boolean`; `unavailable?: boolean`; `unavailableReason?: string`; `largeControls?: boolean` |
15
+ | ChoiceControl | `label: string` required; `value: T` required; `options?: ChoiceOption<T>[]`; `groups?: ChoiceGroup<T>[]`; `onChange: (value: T) => void` required; `disabled?: boolean`; `largeControls?: boolean` |
16
+ | 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` |
17
+ | ProfilePreviewCard | `profile: ProfileDefinition` required; `isActive: boolean` required; `onApply: (profile: ProfileDefinition) => void` required; `onRevert: () => void` required; `largeControls?: boolean` |
18
+ | 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. |
19
+ | 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. |
20
+ | 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. |
21
+ | 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). |
22
+ | WordSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–10px, step 1). Excludes tables, code blocks, controls, and widget UI. |
23
+ | ParagraphSpacingController | Optional `min`, `max`, `step`, `steps` (default 0–32px, step 4). Increases bottom margin on `p` and `[role="paragraph"]`. |
24
+ | 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. |
25
+ | 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. |
26
+ | 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. |
27
+ | 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. |
28
+ | 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. |
29
+ | 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. |
30
+ | 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. |
31
+ | 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. |
27
32
 
28
33
  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 `<AccessibilityPlugin key={newKey} persistenceKey={newKey}>` when switching storage identity.
29
34
 
@@ -51,11 +56,11 @@ Definitions/defaults are immutable for the provider lifetime; the first register
51
56
 
52
57
  `FeatureRegistration` is `FeatureOptions<unknown>` 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.
53
58
 
54
- Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions<T>`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption<T>`, `ChoiceGroup<T>`, `StepperControlProps`, `FeatureCardProps`, `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`, `ProfilesControllerProps`, `ActiveProfileState`, `UseProfilesResult`, `AccessibilityPreferences`, `ContrastMode`, `CursorSizePreference`, `FontFamilyPreference`, `ProfileDefinition`, `ProfilePresetId`, `ReaderMode`, `SaturationPreference`, `StorageMode`, `TextAlignPreference`, `LocaleStrings`, `SupportedLocale`, `FeatureLocaleLabels`, `PresetsControllerProps`, `CustomPreset`, `PresetsExportV1`, `ImportResult`, `UsePresetsResult`.
59
+ Exported types: `AccessibilityPluginProps`, `AccessibilityButtonProps`, `AccessibilityListProps`, `AccessibilityState`, `AccessibilityContextValue`, `PluginPosition`, `WidgetPlacement`, `FeatureOptions<T>`, `FeatureRegistration`, `ToggleControlProps`, `ChoiceControlProps`, `ChoiceOption<T>`, `ChoiceGroup<T>`, `StepperControlProps`, `FeatureCardProps`, `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`.
55
60
 
56
- Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`, `LinkHighlightController`, `HighlightFocusController`, `FocusHighlightController`, `ReduceMotionController`, `HideImagesController`, `HideDecorativeImagesController`, `BigCursorController`, `ReadingMaskController`, `ReadingGuideController`, `TooltipsController`, `AccessibleTooltipsController`, `PageNavigatorController`, `HeadingsNavigatorController`, `PageStructureController`, `ProfilesController`, `ProfileController`, `AccessibilityProfilesController`, `PresetsController`, `CustomPresetsController`, `SettingsImportExportController`, `PresetsBackupController`, `SkipToMainLink`.
61
+ Exported control components: `ToggleControl`, `ChoiceControl`, `StepperControl`, `FeatureCard`, `SearchCount`, `EmptyState`, `ErrorState`, `ProfilePreviewCard`, `FontSizeController`, `TextScaleController`, `LineHeightController`, `LetterSpacingController`, `WordSpacingController`, `ParagraphSpacingController`, `FontFamilyController`, `TextAlignController`, `ContrastController`, `ContrastModeController`, `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`.
57
62
 
58
- Exported typography, contrast, reading aids, tooltips, and reflow 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`, `navigateToElement`, `subscribePageStructure`, `useProfiles`, `ALL_PROFILE_IDS`, `getProfileDefinition`, `mapProfileSettingsToFeatures`, `mapFeaturesToProfileSettings`, `applyProfileToStore`, `revertProfileFromStore`, `recordProfileOverride`, `usePresets`, `createCustomPreset`, `isValidCustomPreset`, `exportPresetsToJson`, `downloadJsonFile`, `validateAndParseImport`, `applyCustomPresetToStore`, `sanitizePreferences`, `ALLOWED_PREFERENCE_KEYS`, `CONTRAST_PROTECTED_SELECTOR`, `isProtectedFromContrast`, `CONTRAST_PALETTES`, `findMainLandmark`.
63
+ 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`.
59
64
 
60
65
  Exported preference and profile utilities: `DEFAULT_PREFERENCES`, `PROFILE_DEFINITIONS`, `normalizePreferences`, `normalizePreferenceValue`, `resolveEffectivePreferences`, `preferencesReducer`, `createInitialPreferencesState`.
61
66
 
@@ -109,3 +114,168 @@ Coordinates are clamped on resizing and account for the trigger's measured dimen
109
114
  Only `.arap-tools` scrolls. The heading, Close, “Move button” and fixed action area stay accessible. A ResetController placed anywhere inside AccessibilityList (including nested composition) renders its button in that area without changing its effect ownership. It remains opt-in; no reset button is injected when it is omitted. Keyboard users can Tab from Close to “Jump to quick actions”, then activate it to focus reset/the first footer action. An open movement menu consumes Escape before the panel does.
110
115
 
111
116
  Use `footer` for additional fixed actions. Keep actions concise and independently keyboard accessible. `draggable={false}` disables pointer/Alt+arrow movement on the trigger; the panel's explicit movement controls remain available. Consumer inline positioning styles override library geometry and should be tested with movement.
117
+
118
+ ## Integration Diagnostics and Harness (A11Y-405)
119
+
120
+ ### `AccessibilityPluginProps.diagnostics`
121
+
122
+ - Type: `boolean | DiagnosticsConfig`
123
+ - In development (`NODE_ENV === "development"`), when set to `true` or configured via `DiagnosticsConfig`, executes integration diagnostics on mount and logs findings to the developer console.
124
+
125
+ ### `<DiagnosticsHarness />`
126
+
127
+ Floating developer panel component for inspecting diagnostics findings:
128
+
129
+ ```tsx
130
+ import { DiagnosticsHarness } from "accessibility-plugin-react";
131
+
132
+ <DiagnosticsHarness
133
+ force={false} // Set to true to force display even in production
134
+ defaultOpen={false} // Whether drawer starts open
135
+ config={{ categories: ["provider", "host-css", "csp", "dom"] }}
136
+ />;
137
+ ```
138
+
139
+ ### `runDiagnostics(config?: DiagnosticsConfig): DiagnosticsReport`
140
+
141
+ Synchronous diagnostics runner returning a structured report:
142
+
143
+ ```ts
144
+ interface DiagnosticsReport {
145
+ timestamp: number;
146
+ environment: "development" | "production" | "test";
147
+ disclaimer: string;
148
+ summary: { total: number; errors: number; warnings: number; info: number };
149
+ issues: DiagnosticIssue[];
150
+ }
151
+ ```
152
+
153
+ ### `useDiagnostics(config?: DiagnosticsConfig): DiagnosticsReport`
154
+
155
+ React hook returning reactive diagnostics reports.
156
+
157
+ ## Privacy-Safe Feature Event Callbacks (A11Y-406)
158
+
159
+ ### `AccessibilityPluginProps.onFeatureEvent`
160
+
161
+ - Type: `(event: AccessibilityFeatureEvent) => void`
162
+ - Optional local lifecycle callback triggered on user interactions (toggles, steppers, resets, profiles, presets, panel visibility, placement). Disabled by default.
163
+
164
+ ### `AccessibilityFeatureEvent` Types
165
+
166
+ ```ts
167
+ type AccessibilityFeatureEvent =
168
+ | FeatureChangeEvent
169
+ | FeatureResetEvent
170
+ | PanelToggleEvent
171
+ | PlacementChangeEvent
172
+ | ProfileApplyEvent
173
+ | PresetApplyEvent;
174
+ ```
175
+
176
+ ### `sanitizeFeatureEvent(raw: AccessibilityFeatureEvent): AccessibilityFeatureEvent`
177
+
178
+ Sanitizes and freezes event payloads against an allowlist, stripping forbidden or private fields.
179
+
180
+ ## Smart Contrast Research Prototype (A11Y-407)
181
+
182
+ ### `<SmartContrastController />`
183
+
184
+ Opt-in research prototype controller providing measured contrast evaluation and enhancement:
185
+
186
+ - Segmented buttons: `Original` (`off`), `AA (4.5:1)` (`aa`), `AAA (7.0:1)` (`aaa`).
187
+ - Displays live statistics (elements evaluated, adjusted, sufficient, unsupported).
188
+ - Inspectable unsupported elements list detailing skipped items (gradients, background images, backdrop filters).
189
+ - Prototype badge and `SMART_CONTRAST_DISCLAIMER` notice.
190
+ - Yields to operating system `forced-colors: active`.
191
+
192
+ ### `evaluateSmartContrast(options?: SmartContrastOptions): SmartContrastReport`
193
+
194
+ Evaluates contrast ratios across all eligible text elements without mutating the DOM:
195
+
196
+ - `targetLevel`: `"aa"` (default) or `"aaa"`.
197
+ - `root`: Root element container (defaults to `document.body`).
198
+ - `maxElements`: Evaluation cap (default: 2000).
199
+
200
+ ### `applySmartContrast(options?: SmartContrastOptions): AppliedSmartContrast`
201
+
202
+ Batched evaluation and non-destructive application of high-contrast replacement colors:
203
+
204
+ - Returns `{ report: SmartContrastReport, undo: () => void }`.
205
+ - `undo()` completely restores original styles and priorities; idempotent and clean.
206
+
207
+ ### Core Mathematical Functions
208
+
209
+ - `calculateRelativeLuminance(r: number, g: number, b: number): number`: Computes WCAG 2.1 relative luminance with sRGB linearization ($0.0$–$1.0$).
210
+ - `calculateContrastRatio(l1: number, l2: number): number`: Computes WCAG 2.1 contrast ratio $(L_1 + 0.05) / (L_2 + 0.05)$ ($1.0$–$21.0$).
211
+ - `compositeRgba(fg: RgbaColor, bg: RgbaColor): RgbaColor`: Porter-Duff source-over alpha blending.
212
+ - `parseColor(colorStr: string): RgbaColor | null`: CSS color string parser with LRU memoization.
213
+ - `resolveEffectiveBackdrop(element: HTMLElement): BackdropResolution`: Resolves effective background color by climbing ancestor chain, detecting unsupported gradients, background images, and backdrop filters.
214
+ - `SMART_CONTRAST_DISCLAIMER`: Constant string disclaimer emphasizing prototype status and zero automatic WCAG compliance claims.
215
+
216
+ ## Voice Navigation Research Prototype (A11Y-408)
217
+
218
+ ### `<VoiceNavigationController />`
219
+
220
+ Opt-in research prototype controller enabling browser-native speech commands:
221
+
222
+ - Start/Stop toggle button with pulsating microphone indicator.
223
+ - Polite live status region (`aria-live="polite"`) announcing active listening and recognized commands.
224
+ - 30-second silence watchdog timeout and background tab (`document.hidden`) protection.
225
+ - Collapsible supported commands cheat sheet detailing spoken phrases.
226
+ - Fully operational accessible keyboard fallback buttons ("Next Heading", "Prev Heading", "Scroll Down", "Scroll Up", "Scroll Top", "Scroll Bottom").
227
+ - Prototype badge and `VOICE_NAVIGATION_DISCLAIMER` notice.
228
+
229
+ ### `isSpeechRecognitionSupported(): boolean`
230
+
231
+ Returns whether native Web Speech Recognition (`SpeechRecognition` or `webkitSpeechRecognition`) is available in the current browser.
232
+
233
+ ### `createVoiceNavigationSession(options?: VoiceNavigationOptions): VoiceNavigationSession`
234
+
235
+ Creates a managed speech recognition session with lifecycle, timeout, and privacy management:
236
+
237
+ - `start()`: Initiates speech recognition session.
238
+ - `stop()`: Halts session cleanly.
239
+ - `abort()`: Aborts session immediately.
240
+ - `destroy()`: Removes all event listeners, watchdog timers, and references.
241
+ - `getStatus(): VoiceNavigationStatus`: Current status (`idle`, `listening`, `processing`, `unsupported`, `denied`, `timeout`, `error`).
242
+ - `getLastResult(): VoiceNavigationResult | null`: Transient last recognized command and feedback.
243
+
244
+ ### `matchVoiceCommand(transcript: string): { command: VoiceCommandDefinition | null; normalized: string }`
245
+
246
+ Matches a raw speech transcript against the supported command vocabulary with punctuation stripping and multi-word phrase boundary checking.
247
+
248
+ ### `executeVoiceCommand(commandId: VoiceCommandId, context?: VoiceExecutionContext): { success: boolean; feedback: string }`
249
+
250
+ Executes a voice command safely without destructive operations, respecting user reduced motion preferences (`prefers-reduced-motion`).
251
+
252
+ ### Constants
253
+
254
+ - `VOICE_COMMANDS`: Array of supported `VoiceCommandDefinition` objects (`open_widget`, `close_widget`, `next_heading`, `previous_heading`, `first_heading`, `scroll_down`, `scroll_up`, `scroll_top`, `scroll_bottom`, `stop_listening`, `help`).
255
+ - `VOICE_NAVIGATION_DISCLAIMER`: Constant string disclaimer stating voice commands are experimental with zero audio/transcript storage.
256
+
257
+ ## Host-Content Translation Adapter Architecture (A11Y-409)
258
+
259
+ ### `<TranslationController />`
260
+
261
+ Opt-in research prototype controller enabling host application content translation:
262
+
263
+ - Prototype badge and `TRANSLATION_DISCLAIMER` notice.
264
+ - Adapter metadata display: active provider name, data retention policy, data residency location, and privacy policy link.
265
+ - Explicit user consent banner and modal: requires user acknowledgment before transmitting any host document text.
266
+ - Target language dropdown selector with standard language options.
267
+ - Translate Page button with loading indicator.
268
+ - Restore Original button immediately reverting translated text nodes back to original host strings.
269
+ - Revoke Translation Consent button reverting translations and returning to unconsented state.
270
+ - Screen-reader live status updates (`aria-live="polite"`).
271
+
272
+ ### Core Functions & Interfaces
273
+
274
+ - `isSensitiveElement(element: Element | null): boolean`: Evaluates whether an element or ancestor contains sensitive data (passwords, auth tokens, financial fields, PII inputs, code blocks, media elements, iframes, opt-out tags, or the widget UI).
275
+ - `extractTranslatableNodes(root: Element, maxNodes?: number): TranslatableNode[]`: Traverses DOM tree starting from root and collects translatable text nodes, strictly skipping sensitive elements.
276
+ - `sanitizeTranslationOutput(raw: string): string`: Sanitizes translated strings, stripping control characters and null bytes.
277
+ - `applyTranslations(nodes: TranslatableNode[], translations: string[]): () => void`: Safely assigns translated strings to text nodes via `textContent` and returns an idempotent restore callback.
278
+ - `createOfflineMockTranslationAdapter(options?): TranslationAdapter`: Creates a local offline mock translation adapter operating with zero network requests.
279
+ - `translateHostContent(options): Promise<TranslationSession>`: Coordinates end-to-end translation, enforcing consent, provider language support, sensitive element exclusion, and DOM restoration.
280
+ - `TRANSLATION_DISCLAIMER`: Constant string disclaimer emphasizing prototype status and zero official WCAG compliance claims.
281
+ - `TRANSLATION_ERROR_CODES`: Standard error code constants (`CONSENT_REQUIRED`, `NO_PROVIDER`, `UNSUPPORTED_LANGUAGE`, `NETWORK_ERROR`, `CSP_BLOCKED`, `RATE_LIMITED`, `SANITIZATION_FAILED`, `SENSITIVE_CONTENT_BLOCKED`, `DOM_MUTATION_ERROR`, `ABORTED`).
@@ -58,7 +58,7 @@ completed. Closing a child issue does not replace the milestone exit review.
58
58
  - [ ] [M1 — Safe core, accessible widget UI and stable state #23](https://github.com/prabothcharith/accessibility-react/issues/23) — Build the typed state, storage, effects, accessible widget shell, examples and CI needed for a safe foundation.
59
59
  - [x] [M2 — Core visual and typographic adjustments #24](https://github.com/prabothcharith/accessibility-react/issues/24) — Add reversible text, spacing, font, contrast, focus, motion and decorative-image preferences with fixture evidence.
60
60
  - [ ] [M3 — Reading support, profiles and localization #25](https://github.com/prabothcharith/accessibility-react/issues/25) — Add reading aids, semantic navigation, profiles, custom presets, import/export and reviewed regional localization.
61
- - [ ] [M4 — Opt-in advanced and browser-dependent controls #26](https://github.com/prabothcharith/accessibility-react/issues/26) — Isolate TTS, dictionary, color, diagnostics, callbacks, smart contrast, voice and translation work behind safe opt-in boundaries.
61
+ - [x] [M4 — Opt-in advanced and browser-dependent controls #26](https://github.com/prabothcharith/accessibility-react/issues/26) — Isolate TTS, dictionary, color, diagnostics, callbacks, smart contrast, voice and translation work behind safe opt-in boundaries.
62
62
  - [ ] [M5 — Launch readiness and package hardening #27](https://github.com/prabothcharith/accessibility-react/issues/27) — Complete browser/AT, performance, documentation, security, licensing and packed-archive validation, then prepare a release proposal.
63
63
 
64
64
  ### M0 — Audit and compatibility safety net
@@ -99,20 +99,20 @@ completed. Closing a child issue does not replace the milestone exit review.
99
99
  - [x] [A11Y-304 — Eight profiles and deterministic override model #52](https://github.com/prabothcharith/accessibility-react/issues/52) — Implement eight neutral editable profiles with previews, atomic application, explicit override layering and no implicit speech or microphone activation.
100
100
  - [x] [A11Y-305 — Custom saved presets and settings import/export #53](https://github.com/prabothcharith/accessibility-react/issues/53) — Add named custom presets and validated versioned JSON import/export that excludes personal content and handles malformed data clearly.
101
101
  - [x] [A11Y-306 — Sinhala and Tamil locale packs with accessibility review #54](https://github.com/prabothcharith/accessibility-react/issues/54) — Add reviewed Sinhala and Tamil widget locale packs and verify glyphs, long labels, search, announcements, fallback and assistive use.
102
- - [ ] [A11Y-307 — Non-destructive reading mode proof of concept #55](https://github.com/prabothcharith/accessibility-react/issues/55) — Prototype safe article-focused reading mode without rewriting host DOM, losing content, breaking focus or sending content externally.
103
- - [ ] [A11Y-308 — Keyboard shortcut help, remapping and link explorer #56](https://github.com/prabothcharith/accessibility-react/issues/56) — Add discoverable shortcut and heading-navigation help, collision-safe remapping and link exploration without hijacking browser or host commands.
102
+ - [x] [A11Y-307 — Non-destructive reading mode proof of concept #55](https://github.com/prabothcharith/accessibility-react/issues/55) — Prototype safe article-focused reading mode without rewriting host DOM, losing content, breaking focus or sending content externally.
103
+ - [x] [A11Y-308 — Keyboard shortcut help, remapping and link explorer #56](https://github.com/prabothcharith/accessibility-react/issues/56) — Add discoverable shortcut and heading-navigation help, collision-safe remapping and link exploration without hijacking browser or host commands.
104
104
 
105
105
  ### M4 — Advanced and experimental controls
106
106
 
107
- - [ ] [A11Y-401 — Read-aloud TTS with voice, rate and stop controls #57](https://github.com/prabothcharith/accessibility-react/issues/57) — Add user-initiated read-aloud with voice/rate/pitch/language, pause/resume/stop, sensitive-content exclusions and lifecycle cleanup.
108
- - [ ] [A11Y-402 — Saturation and grayscale modes #58](https://github.com/prabothcharith/accessibility-react/issues/58) — Add opt-in saturation and grayscale modes with chart/image warnings, forced-color protection, browser coverage and exact reset.
109
- - [ ] [A11Y-403 — Dictionary provider interface and local fallback #59](https://github.com/prabothcharith/accessibility-react/issues/59) — Define local and optional remote dictionary providers with explicit consent, origin/rate/sanitization rules, private-data protection and truthful unknown results.
110
- - [ ] [A11Y-404 — Per-site feature-menu customization and reorder #60](https://github.com/prabothcharith/accessibility-react/issues/60) — Add validated feature visibility, ordering, grouping, labels and default customization while keeping close, reset and help reachable.
111
- - [ ] [A11Y-405 — Development-only integration diagnostics and harness #61](https://github.com/prabothcharith/accessibility-react/issues/61) — Build development-only diagnostics and fixtures for supported features, effect ownership, storage, host CSS, CSP, portals, iframes and dynamic content.
112
- - [ ] [A11Y-406 — Optional privacy-safe feature event callbacks #62](https://github.com/prabothcharith/accessibility-react/issues/62) — Add disabled-by-default local lifecycle callbacks with reviewed payloads that exclude page text, inputs, identifiers, transcripts and recordings.
113
- - [ ] [A11Y-407 — Smart contrast research prototype #63](https://github.com/prabothcharith/accessibility-react/issues/63) — Research measured smart contrast for eligible elements with compositing, caching, unsupported reporting, performance evidence and full restoration.
114
- - [ ] [A11Y-408 — Voice navigation research prototype #64](https://github.com/prabothcharith/accessibility-react/issues/64) — Research a small voice-command set with permission, visible listening, timeout, cleanup, privacy disclosure and keyboard alternatives.
115
- - [ ] [A11Y-409 — Host-content translation adapter architecture #65](https://github.com/prabothcharith/accessibility-react/issues/65) — Design an explicit host-translation provider boundary with consent, origin/privacy documentation, sanitization and cross-origin limitations.
107
+ - [x] [A11Y-401 — Read-aloud TTS with voice, rate and stop controls #57](https://github.com/prabothcharith/accessibility-react/issues/57) — Add user-initiated read-aloud with voice/rate/pitch/language, pause/resume/stop, sensitive-content exclusions and lifecycle cleanup.
108
+ - [x] [A11Y-402 — Saturation and grayscale modes #58](https://github.com/prabothcharith/accessibility-react/issues/58) — Add opt-in saturation and grayscale modes with chart/image warnings, forced-color protection, browser coverage and exact reset.
109
+ - [x] [A11Y-403 — Dictionary provider interface and local fallback #59](https://github.com/prabothcharith/accessibility-react/issues/59) — Define local and optional remote dictionary providers with explicit consent, origin/rate/sanitization rules, private-data protection and truthful unknown results.
110
+ - [x] [A11Y-404 — Per-site feature-menu customization and reorder #60](https://github.com/prabothcharith/accessibility-react/issues/60) — Add validated feature visibility, ordering, grouping, labels and default customization while keeping close, reset and help reachable.
111
+ - [x] [A11Y-405 — Development-only integration diagnostics and harness #61](https://github.com/prabothcharith/accessibility-react/issues/61) — Build development-only diagnostics and fixtures for supported features, effect ownership, storage, host CSS, CSP, portals, iframes and dynamic content.
112
+ - [x] [A11Y-406 — Optional privacy-safe feature event callbacks #62](https://github.com/prabothcharith/accessibility-react/issues/62) — Add disabled-by-default local lifecycle callbacks with reviewed payloads that exclude page text, inputs, identifiers, transcripts and recordings.
113
+ - [x] [A11Y-407 — Smart contrast research prototype #63](https://github.com/prabothcharith/accessibility-react/issues/63) — Research measured smart contrast for eligible elements with compositing, caching, unsupported reporting, performance evidence and full restoration.
114
+ - [x] [A11Y-408 — Voice navigation research prototype #64](https://github.com/prabothcharith/accessibility-react/issues/64) — Research a small voice-command set with permission, visible listening, timeout, cleanup, privacy disclosure and keyboard alternatives.
115
+ - [x] [A11Y-409 — Host-content translation adapter architecture #65](https://github.com/prabothcharith/accessibility-react/issues/65) — Design an explicit host-translation provider boundary with consent, origin/privacy documentation, sanitization and cross-origin limitations.
116
116
 
117
117
  ### M5 — Launch readiness and package hardening
118
118
 
@@ -314,15 +314,15 @@ translation.
314
314
  Work through [M4 #26](https://github.com/prabothcharith/accessibility-react/issues/26).
315
315
  These are not automatically stable release features:
316
316
 
317
- 1. **A11Y-401, issue #57:** read-aloud TTS.
318
- 2. **A11Y-402, issue #58:** saturation and grayscale.
319
- 3. **A11Y-403, issue #59:** dictionary interface and local fallback.
317
+ 1. **A11Y-401, issue #57:** read-aloud TTS (Completed).
318
+ 2. **A11Y-402, issue #58:** saturation and grayscale (Completed).
319
+ 3. **A11Y-403, issue #59:** dictionary interface and local fallback (Completed).
320
320
  4. **A11Y-404, issue #60:** per-site feature menu customization.
321
321
  5. **A11Y-405, issue #61:** development-only diagnostics and test harness.
322
322
  6. **A11Y-406, issue #62:** privacy-safe opt-in event callbacks.
323
323
  7. **A11Y-407, issue #63:** measured smart-contrast research prototype.
324
- 8. **A11Y-408, issue #64:** voice-navigation research prototype.
325
- 9. **A11Y-409, issue #65:** host-content translation adapter architecture.
324
+ 8. **A11Y-408, issue #64:** voice-navigation research prototype (Completed).
325
+ 9. **A11Y-409, issue #65:** host-content translation adapter architecture (Completed).
326
326
 
327
327
  Each browser-dependent or privacy-sensitive feature requires an explicit
328
328
  support matrix, security/privacy review, stop/disable behavior, a safe
@@ -0,0 +1,119 @@
1
+ # Integration Diagnostics and Test Harness (A11Y-405)
2
+
3
+ The `accessibility-plugin-react` library includes a built-in, development-only diagnostics engine and inspection harness designed to detect host environment conflicts, CSS containing block traps, Content Security Policy restrictions, and accessibility landmark health.
4
+
5
+ ## Core Principles
6
+
7
+ 1. **Development-Only by Default**:
8
+ Diagnostics routines are inert in production builds (`process.env.NODE_ENV === "production"`). They return an empty report with 0 issues unless explicitly forced via `{ force: true }`.
9
+ 2. **Zero Compliance Claims**:
10
+ Automated integration diagnostics evaluate DOM structure, CSP, storage, and host CSS boundaries. They **do not certify WCAG 2.1/2.2 AA compliance** and cannot replace manual keyboard navigation, screen-reader testing (NVDA, VoiceOver), or physical device evaluation.
11
+ Every report carries the standard disclaimer:
12
+ > _"Automated diagnostics evaluate host environment compatibility, DOM landmarks, and CSS boundaries. They do not constitute official WCAG 2.1/2.2 AA certification and cannot substitute for manual keyboard and screen-reader auditing."_
13
+ 3. **Strict Privacy Safety**:
14
+ Diagnostics never collect, log, or transmit private data, form inputs, session tokens, user IDs, or URLs with query strings. Images lacking `alt` attributes are reported by count and sanitized CSS selectors without exposing sensitive URLs or credentials.
15
+
16
+ ---
17
+
18
+ ## Diagnostic Categories
19
+
20
+ | Category | Checks Performed | Severity |
21
+ | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
22
+ | **`provider`** | Multi-provider detection; verifies the document has only one `AccessibilityPlugin` owner. Detects containing-block traps (ancestors with `filter`, `transform`, `perspective`, or `backdrop-filter` breaking `position: fixed`). | `warning` / `error` |
23
+ | **`storage`** | Tests `localStorage` and `sessionStorage` accessibility, quota boundaries, and sandbox restrictions. Diagnoses in-memory fallback mode. | `warning` / `info` |
24
+ | **`csp`** | Tests dynamic stylesheet `<style>` injection and CSS custom property manipulation against restrictive Content Security Policy (`style-src`). | `warning` / `error` |
25
+ | **`host-css`** | Detects extreme `z-index >= 2,147,483,000` that could obscure widget controls; detects root scroll locks (`overflow: hidden` on both `html` and `body`). | `warning` |
26
+ | **`dom`** | Checks for `<main>` landmark presence; verifies `<h1>` page heading; checks for skipped heading levels (e.g. `<h1>` to `<h3>`); scans content images lacking an `alt` attribute. | `warning` / `info` |
27
+ | **`boundaries`** | Detects embedded `<iframe>` elements (noting cross-origin isolation); detects custom elements with `ShadowRoot`; validates portal mount point. | `info` / `warning` |
28
+
29
+ ---
30
+
31
+ ## Usage
32
+
33
+ ### 1. Enabling Diagnostics on `AccessibilityPlugin`
34
+
35
+ Pass the `diagnostics` prop to `AccessibilityPlugin` in your root or development layout:
36
+
37
+ ```tsx
38
+ import { AccessibilityPlugin } from "accessibility-plugin-react";
39
+
40
+ // Enable console logging in development:
41
+ <AccessibilityPlugin diagnostics={true}>
42
+ <App />
43
+ </AccessibilityPlugin>
44
+
45
+ // Or configure custom options:
46
+ <AccessibilityPlugin
47
+ diagnostics={{
48
+ logToConsole: true,
49
+ categories: ["host-css", "csp", "dom"],
50
+ onReport: (report) => {
51
+ console.log(`Diagnostics completed with ${report.summary.total} findings.`);
52
+ },
53
+ }}
54
+ >
55
+ <App />
56
+ </AccessibilityPlugin>
57
+ ```
58
+
59
+ ### 2. Developer Inspection UI: `<DiagnosticsHarness />`
60
+
61
+ The `DiagnosticsHarness` provides an accessible, floating drawer UI for developers to inspect detected issues, switch categories, view actionable fix recommendations, and re-run audits:
62
+
63
+ ```tsx
64
+ import { DiagnosticsHarness } from "accessibility-plugin-react";
65
+
66
+ function RootLayout({ children }: { children: React.ReactNode }) {
67
+ return (
68
+ <>
69
+ {children}
70
+ {process.env.NODE_ENV !== "production" && <DiagnosticsHarness />}
71
+ </>
72
+ );
73
+ }
74
+ ```
75
+
76
+ ### 3. Programmatic API: `runDiagnostics` and `useDiagnostics`
77
+
78
+ ```ts
79
+ import { runDiagnostics, useDiagnostics } from "accessibility-plugin-react";
80
+
81
+ // Run synchronously:
82
+ const report = runDiagnostics({
83
+ force: true, // Bypass production check if testing
84
+ categories: ["provider", "host-css", "storage"],
85
+ });
86
+
87
+ console.log(report.summary.total);
88
+ console.log(report.issues);
89
+
90
+ // Or via React hook:
91
+ function DevToolbar() {
92
+ const report = useDiagnostics();
93
+ return <div>Active integration issues: {report.summary.total}</div>;
94
+ }
95
+ ```
96
+
97
+ ---
98
+
99
+ ## Actionable Diagnostics Reference
100
+
101
+ ### `provider-fixed-position-trap` (Error)
102
+
103
+ - **Problem**: The accessibility widget was rendered inside a container with CSS `transform`, `filter`, or `perspective`. CSS specification states these properties create a new containing block for `position: fixed` descendants, pinning the widget relative to the container rather than the browser viewport.
104
+ - **Fix**: Render `AccessibilityPlugin` or its `WidgetPortal` directly as a child of `document.body` outside transformed wrappers.
105
+
106
+ ### `csp-style-injection-restricted` (Warning / Error)
107
+
108
+ - **Problem**: Content Security Policy restricts dynamic inline `<style>` injection (`style-src`).
109
+ - **Fix**: Ensure your CSP header allows `'self'` and `'unsafe-inline'`, or serve plugin styles using external `<link rel="stylesheet" href="...">`.
110
+
111
+ ### `host-css-extreme-z-index` (Warning)
112
+
113
+ - **Problem**: Host elements define `z-index >= 2,147,483,000`, obscuring the accessibility launcher button (z-index `2,147,483,001`).
114
+ - **Fix**: Constrain host application z-index layers below `2,147,483,000`.
115
+
116
+ ### `dom-missing-main-landmark` (Warning)
117
+
118
+ - **Problem**: The document lacks a `<main>` or `[role="main"]` landmark.
119
+ - **Fix**: Wrap main page content in a semantic `<main>` tag.