accessibility-plugin-react 2.18.0 → 2.28.1

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/dist/index.d.mts CHANGED
@@ -1,5 +1,129 @@
1
1
  import * as react from 'react';
2
- import { ReactNode, CSSProperties } from 'react';
2
+ import react__default, { ReactNode, CSSProperties } from 'react';
3
+
4
+ /**
5
+ * Per-site feature-menu customization, ordering, grouping, and validation.
6
+ *
7
+ * Implements A11Y-404:
8
+ * - Validate enabled IDs, order, groups, labels, profiles/statement visibility and suggested defaults
9
+ * - Warn if close, reset, or help becomes unreachable
10
+ * - Preserve canonical feature IDs
11
+ * - Diagnose invalid configuration without crashing the application
12
+ * - Ensure stable memoized rerenders
13
+ */
14
+ declare const KNOWN_FEATURE_IDS: readonly ["textScale", "fontSize", "lineHeight", "letterSpacing", "wordSpacing", "paragraphSpacing", "contrast", "contrastMode", "smartContrast", "saturation", "invertColors", "grayscale", "linkHighlight", "highlightFocus", "reduceMotion", "textAlign", "fontFamily", "hideImages", "hideVideos", "bigCursor", "readingMask", "readingGuide", "tooltips", "pageNavigator", "profiles", "presets", "readingMode", "keyboardShortcuts", "readAloud", "dictionary", "voiceNavigation", "translation", "reset"];
15
+ interface FeatureMenuItemConfig {
16
+ /** Feature identifier (canonical built-in ID or custom feature ID). */
17
+ id: string;
18
+ /** Whether the feature is visible and rendered in the menu. Defaults to true. */
19
+ enabled?: boolean;
20
+ /** Explicit display order weight (lower numbers appear first). */
21
+ order?: number;
22
+ /** Custom label override for this site. */
23
+ label?: string;
24
+ /** Custom description override for this site. */
25
+ description?: string;
26
+ /** Group / category identifier for grouping controls. */
27
+ group?: string;
28
+ /** Suggested default value on initial mount if not already saved. */
29
+ suggestedDefault?: unknown;
30
+ /** Custom props passed directly to the controller component. */
31
+ props?: Record<string, unknown>;
32
+ /** Optional custom React component to render instead of the standard controller. */
33
+ component?: unknown;
34
+ }
35
+ interface FeatureMenuGroupConfig {
36
+ /** Unique group identifier. */
37
+ id: string;
38
+ /** Accessible group title / heading text. */
39
+ title?: string;
40
+ /** Accessible group description or subtitle. */
41
+ description?: string;
42
+ /** Explicit display order for the group. */
43
+ order?: number;
44
+ /** Feature IDs or item configs explicitly assigned to this group. */
45
+ items?: (string | FeatureMenuItemConfig)[];
46
+ /** Whether the group can be collapsed (default: false). */
47
+ collapsible?: boolean;
48
+ /** Default collapsed state if collapsible. */
49
+ defaultExpanded?: boolean;
50
+ }
51
+ interface MenuCustomizationConfig {
52
+ /** List of feature items to render, order, or configure. */
53
+ items?: (string | FeatureMenuItemConfig)[];
54
+ /** Custom groups / sections for organized menu presentation. */
55
+ groups?: FeatureMenuGroupConfig[];
56
+ /** Visibility of Accessibility Profiles controller. Defaults to true. */
57
+ showProfiles?: boolean;
58
+ /** Visibility of site accessibility statement link. Defaults to true. */
59
+ showStatement?: boolean;
60
+ /** Visibility of the Reset All action button. Defaults to true. */
61
+ showReset?: boolean;
62
+ /** Visibility of keyboard shortcuts help controller. Defaults to true. */
63
+ showShortcutsHelp?: boolean;
64
+ /** Visibility of button position movement controls. Defaults to true. */
65
+ showPositionControls?: boolean;
66
+ /** Whether to render features organized into visual group sections. Defaults to false. */
67
+ grouped?: boolean;
68
+ /** Optional callback invoked with validation issues. */
69
+ diagnosticsCallback?: (issues: MenuValidationIssue[]) => void;
70
+ /** When true, logs diagnostics to console.warn in development mode. Defaults to true. */
71
+ enableLogging?: boolean;
72
+ }
73
+ interface MenuValidationIssue {
74
+ type: "error" | "warning" | "info";
75
+ code: "INVALID_CONFIG_TYPE" | "UNKNOWN_FEATURE_ID" | "DUPLICATE_FEATURE_ID" | "UNREACHABLE_RESET" | "UNREACHABLE_CLOSE" | "UNREACHABLE_HELP" | "INVALID_DEFAULT_VALUE" | "INVALID_GROUP_CONFIG" | "EMPTY_MENU";
76
+ message: string;
77
+ featureId?: string;
78
+ groupId?: string;
79
+ }
80
+ interface NormalizedMenuItem {
81
+ id: string;
82
+ enabled: boolean;
83
+ order: number;
84
+ label?: string;
85
+ description?: string;
86
+ group?: string;
87
+ suggestedDefault?: unknown;
88
+ props?: Record<string, unknown>;
89
+ component?: unknown;
90
+ }
91
+ interface NormalizedMenuGroup {
92
+ id: string;
93
+ title?: string;
94
+ description?: string;
95
+ order: number;
96
+ itemIds: string[];
97
+ collapsible?: boolean;
98
+ defaultExpanded?: boolean;
99
+ }
100
+ interface NormalizedMenuConfig {
101
+ items: NormalizedMenuItem[];
102
+ groups: NormalizedMenuGroup[];
103
+ showProfiles: boolean;
104
+ showStatement: boolean;
105
+ showReset: boolean;
106
+ showShortcutsHelp: boolean;
107
+ showPositionControls: boolean;
108
+ }
109
+ interface MenuValidationResult {
110
+ valid: boolean;
111
+ issues: MenuValidationIssue[];
112
+ normalizedConfig: NormalizedMenuConfig;
113
+ }
114
+ /** Built-in default groups for organized layout */
115
+ declare const DEFAULT_MENU_GROUPS: FeatureMenuGroupConfig[];
116
+ /** Mapping of built-in features to default groups */
117
+ declare const DEFAULT_FEATURE_GROUP_MAP: Record<string, string>;
118
+ /**
119
+ * Validates and normalizes a site menu configuration.
120
+ * Never throws exceptions; always produces a usable fallback configuration with diagnostic issues.
121
+ */
122
+ declare function validateMenuConfig(config: unknown): MenuValidationResult;
123
+ /**
124
+ * Creates a deterministic hash / signature of a menu configuration for memoization comparison.
125
+ */
126
+ declare function getMenuConfigSignature(config: MenuCustomizationConfig | undefined): string;
3
127
 
4
128
  type ContrastMode = "off" | "light" | "dark" | "high" | "invert";
5
129
  type ReaderMode = "off" | "guide" | "mask";
@@ -100,6 +224,10 @@ interface FeatureLocaleLabels {
100
224
  profiles?: string;
101
225
  presets?: string;
102
226
  readingMode?: string;
227
+ readAloud?: string;
228
+ saturation?: string;
229
+ grayscale?: string;
230
+ dictionary?: string;
103
231
  [key: string]: string | undefined;
104
232
  }
105
233
  interface LocaleStrings {
@@ -153,6 +281,83 @@ interface LocaleStrings {
153
281
  readingModeFailed?: string;
154
282
  formatReadingWords?: (words: number) => string;
155
283
  formatReadingTime?: (minutes: number) => string;
284
+ shortcutsTitle?: string;
285
+ shortcutsDescription?: string;
286
+ shortcutsOpen?: string;
287
+ shortcutsClose?: string;
288
+ shortcutsEnabledLabel?: string;
289
+ shortcutsSearchPlaceholder?: string;
290
+ shortcutsRemap?: string;
291
+ shortcutsReset?: string;
292
+ shortcutsPressKey?: string;
293
+ shortcutsCancel?: string;
294
+ shortcutToggleWidget?: string;
295
+ shortcutToggleWidgetDesc?: string;
296
+ shortcutResetAll?: string;
297
+ shortcutResetAllDesc?: string;
298
+ shortcutPageNavigator?: string;
299
+ shortcutPageNavigatorDesc?: string;
300
+ shortcutSkipToMain?: string;
301
+ shortcutSkipToMainDesc?: string;
302
+ shortcutReadingMode?: string;
303
+ shortcutReadingModeDesc?: string;
304
+ shortcutProfiles?: string;
305
+ shortcutProfilesDesc?: string;
306
+ shortcutPresets?: string;
307
+ shortcutPresetsDesc?: string;
308
+ shortcutHelp?: string;
309
+ shortcutHelpDesc?: string;
310
+ shortcutCloseDialog?: string;
311
+ shortcutCloseDialogDesc?: string;
312
+ pageNavigatorLinksTab?: string;
313
+ pageNavigatorLinksEmpty?: string;
314
+ pageNavigatorLinksAmbiguous?: string;
315
+ readAloudDescription?: string;
316
+ readAloudPlay?: string;
317
+ readAloudPlaySelection?: string;
318
+ readAloudPlayArticle?: string;
319
+ readAloudPause?: string;
320
+ readAloudResume?: string;
321
+ readAloudStop?: string;
322
+ readAloudRate?: string;
323
+ readAloudPitch?: string;
324
+ readAloudVoice?: string;
325
+ readAloudDefaultVoice?: string;
326
+ readAloudStatusReading?: string;
327
+ readAloudStatusPaused?: string;
328
+ readAloudStatusStopped?: string;
329
+ readAloudUnsupported?: string;
330
+ readAloudNoText?: string;
331
+ readAloudSensitiveSkipped?: string;
332
+ readAloudSpeed?: string;
333
+ shortcutReadAloud?: string;
334
+ shortcutReadAloudDesc?: string;
335
+ saturationOff?: string;
336
+ saturationLow?: string;
337
+ saturationHigh?: string;
338
+ saturationGrayscale?: string;
339
+ saturationLowWarning?: string;
340
+ saturationHighWarning?: string;
341
+ grayscaleWarning?: string;
342
+ forcedColorsActiveWarning?: string;
343
+ shortcutGrayscale?: string;
344
+ shortcutGrayscaleDesc?: string;
345
+ dictionaryTitle?: string;
346
+ dictionaryDescription?: string;
347
+ dictionarySearchPlaceholder?: string;
348
+ dictionaryLookupButton?: string;
349
+ dictionaryClearButton?: string;
350
+ dictionaryCloseDialog?: string;
351
+ dictionaryStatusSearching?: string;
352
+ dictionaryStatusFound?: (word: string) => string;
353
+ dictionaryStatusNotFound?: (word: string) => string;
354
+ dictionarySuggestionsTitle?: string;
355
+ dictionarySourceLocal?: string;
356
+ dictionarySourceProvider?: string;
357
+ dictionaryPartOfSpeech?: string;
358
+ dictionaryExampleLabel?: string;
359
+ shortcutDictionary?: string;
360
+ shortcutDictionaryDesc?: string;
156
361
  features?: FeatureLocaleLabels;
157
362
  }
158
363
  type SupportedLocale = "en" | "en-US" | "en-GB" | "si" | "si-LK" | "ta" | "ta-LK" | string;
@@ -167,6 +372,123 @@ declare function registerLocale(code: string, strings: LocaleStrings): void;
167
372
  declare function isRtlLocale(localeProp?: string): boolean;
168
373
  declare function resolveLocaleStrings(localeProp?: string): LocaleStrings;
169
374
 
375
+ type DiagnosticCategory = "provider" | "storage" | "csp" | "host-css" | "dom" | "boundaries" | "effects";
376
+ type DiagnosticSeverity = "error" | "warning" | "info";
377
+ interface DiagnosticIssue {
378
+ id: string;
379
+ category: DiagnosticCategory;
380
+ severity: DiagnosticSeverity;
381
+ title: string;
382
+ message: string;
383
+ recommendation: string;
384
+ target?: string;
385
+ docUrl?: string;
386
+ }
387
+ interface DiagnosticsSummary {
388
+ total: number;
389
+ errors: number;
390
+ warnings: number;
391
+ info: number;
392
+ }
393
+ interface DiagnosticsReport {
394
+ timestamp: number;
395
+ environment: "development" | "production" | "test";
396
+ disclaimer: string;
397
+ summary: DiagnosticsSummary;
398
+ issues: DiagnosticIssue[];
399
+ }
400
+ interface DiagnosticsConfig {
401
+ /** Force diagnostics to run even when NODE_ENV is production. Defaults to false. */
402
+ force?: boolean;
403
+ /** Whether to log diagnostic findings to the browser developer console. Defaults to true in dev. */
404
+ logToConsole?: boolean;
405
+ /** Specific categories to inspect. If omitted, all categories are checked. */
406
+ categories?: DiagnosticCategory[];
407
+ /** Callback invoked when a diagnostics run completes. */
408
+ onReport?: (report: DiagnosticsReport) => void;
409
+ /** Document root to inspect (defaults to global document). */
410
+ root?: Document | Element;
411
+ }
412
+ declare const DIAGNOSTICS_DISCLAIMER = "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.";
413
+ /**
414
+ * Validates single provider ownership and widget placement.
415
+ */
416
+ declare function checkProviderDiagnostics(root: Document | Element): DiagnosticIssue[];
417
+ /**
418
+ * Validates storage accessibility, quotas, and security boundaries.
419
+ */
420
+ declare function checkStorageDiagnostics(): DiagnosticIssue[];
421
+ /**
422
+ * Validates Content Security Policy (CSP) and style injection capability.
423
+ */
424
+ declare function checkCspDiagnostics(root: Document | Element): DiagnosticIssue[];
425
+ /**
426
+ * Validates host CSS conflicts: extreme z-indexes, overflow locks, preflight clashes.
427
+ */
428
+ declare function checkHostCssDiagnostics(root: Document | Element): DiagnosticIssue[];
429
+ /**
430
+ * Validates DOM landmarks, heading hierarchy, and image alt attributes.
431
+ * NEVER logs private data, auth tokens, or sensitive image sources.
432
+ */
433
+ declare function checkDomDiagnostics(root: Document | Element): DiagnosticIssue[];
434
+ /**
435
+ * Validates boundaries: iframes, shadow DOM, and portal mount points.
436
+ */
437
+ declare function checkBoundariesDiagnostics(root: Document | Element): DiagnosticIssue[];
438
+ /**
439
+ * Executes a full integration diagnostics audit.
440
+ * In production mode, returns an empty report with 0 issues unless force is true.
441
+ */
442
+ declare function runDiagnostics(config?: DiagnosticsConfig): DiagnosticsReport;
443
+
444
+ type AccessibilityEventType = "feature-change" | "feature-reset" | "panel-toggle" | "placement-change" | "profile-apply" | "preset-apply";
445
+ type EventTriggerSource = "ui" | "shortcut" | "profile" | "preset" | "reset" | "api";
446
+ interface BaseAccessibilityEvent {
447
+ type: AccessibilityEventType;
448
+ timestamp: number;
449
+ source: EventTriggerSource;
450
+ }
451
+ interface FeatureChangeEvent extends BaseAccessibilityEvent {
452
+ type: "feature-change";
453
+ featureId: string;
454
+ value: boolean | number | string;
455
+ previousValue?: boolean | number | string;
456
+ }
457
+ interface FeatureResetEvent extends BaseAccessibilityEvent {
458
+ type: "feature-reset";
459
+ clearedFeaturesCount: number;
460
+ }
461
+ interface PanelToggleEvent extends BaseAccessibilityEvent {
462
+ type: "panel-toggle";
463
+ isOpen: boolean;
464
+ }
465
+ interface PlacementChangeEvent extends BaseAccessibilityEvent {
466
+ type: "placement-change";
467
+ placement: "corner" | "point";
468
+ }
469
+ interface ProfileApplyEvent extends BaseAccessibilityEvent {
470
+ type: "profile-apply";
471
+ profileId: string;
472
+ }
473
+ interface PresetApplyEvent extends BaseAccessibilityEvent {
474
+ type: "preset-apply";
475
+ presetId: string;
476
+ }
477
+ type AccessibilityFeatureEvent = FeatureChangeEvent | FeatureResetEvent | PanelToggleEvent | PlacementChangeEvent | ProfileApplyEvent | PresetApplyEvent;
478
+ type FeatureEventListener = (event: AccessibilityFeatureEvent) => void;
479
+ /**
480
+ * Sanitizes and validates an event payload against a strict privacy allowlist.
481
+ * Guarantees that no private data, DOM text, user inputs, recordings, or transcripts
482
+ * can be inadvertently leaked into developer event streams.
483
+ */
484
+ declare function sanitizeFeatureEvent(rawEvent: AccessibilityFeatureEvent): AccessibilityFeatureEvent;
485
+ /**
486
+ * Safely emits a feature event to an optional subscriber callback.
487
+ * Exceptions thrown inside consumer listeners are caught and silenced
488
+ * to prevent breaking the application's runtime or accessibility plugin state.
489
+ */
490
+ declare function emitFeatureEvent(listener: FeatureEventListener | undefined, rawEvent: AccessibilityFeatureEvent): void;
491
+
170
492
  interface ToggleControlProps {
171
493
  id?: string;
172
494
  label: ReactNode;
@@ -344,6 +666,18 @@ interface AccessibilityPluginProps {
344
666
  statementUrl?: string;
345
667
  /** Oversized widget controls mode (>=48px touch targets, W-21). */
346
668
  largeControls?: boolean;
669
+ /**
670
+ * Development-only integration diagnostics (A11Y-405).
671
+ * Runs non-invasive checks for CSP, host CSS, portals, storage, and landmarks.
672
+ * Inactive in production unless explicitly forced.
673
+ */
674
+ diagnostics?: boolean | DiagnosticsConfig;
675
+ /**
676
+ * Optional privacy-safe feature event lifecycle callback (A11Y-406).
677
+ * Strictly local, opt-in, and disabled by default. Excludes page text, selections,
678
+ * inputs, transcripts, and identifiers.
679
+ */
680
+ onFeatureEvent?: FeatureEventListener;
347
681
  }
348
682
  interface AccessibilityButtonProps {
349
683
  /** Pointer dragging and Alt+Arrow movement. Defaults to true. */
@@ -360,7 +694,8 @@ interface AccessibilityListProps {
360
694
  footer?: ReactNode;
361
695
  /** Supporting panel text. Pass an empty string to omit it. */
362
696
  description?: string;
363
- children: ReactNode;
697
+ /** Explicit controller children or custom markup. Optional if menuConfig is supplied. */
698
+ children?: ReactNode;
364
699
  className?: string;
365
700
  style?: CSSProperties;
366
701
  title?: string;
@@ -371,9 +706,11 @@ interface AccessibilityListProps {
371
706
  largeControls?: boolean;
372
707
  /** Preferred UI language locale. */
373
708
  locale?: string;
709
+ /** Declarative per-site feature menu customization and reordering (A11Y-404). */
710
+ menuConfig?: MenuCustomizationConfig;
374
711
  }
375
712
 
376
- declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, }: AccessibilityPluginProps): react.JSX.Element;
713
+ declare function AccessibilityPlugin({ children, position, persistenceKey, persist, storage, locale, statementUrl, largeControls, diagnostics, onFeatureEvent, }: AccessibilityPluginProps): react.JSX.Element;
377
714
 
378
715
  declare function AccessibilityButton({ icon, draggable, title, description, className, style, largeControls, }: AccessibilityButtonProps): react.JSX.Element;
379
716
 
@@ -454,6 +791,9 @@ interface UseProfilesResult {
454
791
  declare function useProfiles(): UseProfilesResult;
455
792
 
456
793
  interface FontSizeControllerProps {
794
+ /** Optional custom label or title */
795
+ label?: string;
796
+ title?: string;
457
797
  /**
458
798
  * Optional custom scale steps (percentages or factors, e.g. [100, 112.5, 125, 150, 200] or [1.0, 1.125, 1.25, 1.5, 2.0]).
459
799
  * If provided, the stepper snaps to the nearest configured step.
@@ -464,7 +804,7 @@ interface FontSizeControllerProps {
464
804
  */
465
805
  stepScale?: boolean;
466
806
  }
467
- declare function FontSizeController({ steps: customSteps, stepScale, }?: FontSizeControllerProps): react.JSX.Element;
807
+ declare function FontSizeController({ label, title, steps: customSteps, stepScale, }?: FontSizeControllerProps): react.JSX.Element;
468
808
 
469
809
  interface TextScaleControllerProps {
470
810
  /**
@@ -607,11 +947,31 @@ declare function ContrastController(): react.JSX.Element;
607
947
 
608
948
  declare function ContrastModeController(): react.JSX.Element;
609
949
 
610
- declare function SaturationController(): react.JSX.Element;
950
+ declare function SmartContrastController(): react.JSX.Element;
951
+
952
+ interface SaturationControllerProps {
953
+ /** Optional custom title override */
954
+ title?: string;
955
+ /** Optional custom description */
956
+ description?: string;
957
+ /** Whether to include Grayscale mode option in the segmented control (defaults to true) */
958
+ includeGrayscale?: boolean;
959
+ /** Whether to display chart/image advisory warning when low/high/grayscale is selected (defaults to true) */
960
+ showAdvisory?: boolean;
961
+ }
962
+ declare function SaturationController({ title, description, includeGrayscale, showAdvisory, }?: SaturationControllerProps): react.JSX.Element;
611
963
 
612
964
  declare function InvertColorsController(): react.JSX.Element;
613
965
 
614
- declare function GrayscaleController(): react.JSX.Element;
966
+ interface GrayscaleControllerProps {
967
+ /** Optional custom title override */
968
+ title?: string;
969
+ /** Optional custom description */
970
+ description?: string;
971
+ /** Whether to display chart/image advisory warning when grayscale is enabled (defaults to true) */
972
+ showAdvisory?: boolean;
973
+ }
974
+ declare function GrayscaleController({ title, description, showAdvisory, }?: GrayscaleControllerProps): react.JSX.Element;
615
975
 
616
976
  declare function LinkHighlightController(): react.JSX.Element;
617
977
 
@@ -680,9 +1040,9 @@ interface PageNavigatorControllerProps {
680
1040
  closeOnNavigate?: boolean;
681
1041
  }
682
1042
  /**
683
- * Controller to explore and navigate the page's semantic outline (Headings H1-H6 and Landmarks).
1043
+ * Controller to explore and navigate the page's semantic outline (Headings H1-H6, Landmarks, and Links).
684
1044
  * Safely transfers focus and scrolls to elements with temporary tabindex cleanup.
685
- * Truthfully displays empty states when pages lack headings or landmarks.
1045
+ * Truthfully displays empty states when pages lack headings, landmarks, or links.
686
1046
  * Automatically synchronizes with dynamic DOM / SPA route changes without observer loops.
687
1047
  */
688
1048
  declare function PageNavigatorController({ className, label, description, closeOnNavigate, }: PageNavigatorControllerProps): react.JSX.Element;
@@ -701,6 +1061,16 @@ interface LandmarkItem {
701
1061
  label: string;
702
1062
  element: HTMLElement;
703
1063
  }
1064
+ interface LinkItem {
1065
+ id: string;
1066
+ text: string;
1067
+ href: string;
1068
+ target?: string;
1069
+ isExternal: boolean;
1070
+ isHash: boolean;
1071
+ isAmbiguous: boolean;
1072
+ element: HTMLElement;
1073
+ }
704
1074
  /**
705
1075
  * Discovers all visible headings (h1-h6 or role="heading") in true DOM tree order,
706
1076
  * strictly excluding elements within the plugin UI.
@@ -711,6 +1081,12 @@ declare function scanHeadings(root?: Document | Element): HeadingItem[];
711
1081
  * strictly excluding elements within the plugin UI.
712
1082
  */
713
1083
  declare function scanLandmarks(root?: Document | Element): LandmarkItem[];
1084
+ /**
1085
+ * Discovers all visible links (a[href] or [role='link']) in true DOM tree order,
1086
+ * strictly excluding elements within the plugin UI.
1087
+ * Identifies external destinations, hash jumps, and uninformative / ambiguous link text.
1088
+ */
1089
+ declare function scanLinks(root?: Document | Element): LinkItem[];
714
1090
  /**
715
1091
  * Safely scrolls to and focuses a target element.
716
1092
  * If the element is not naturally focusable, assigns a temporary tabindex="-1"
@@ -818,6 +1194,251 @@ interface ReadingModeControllerProps {
818
1194
  */
819
1195
  declare function ReadingModeController({ className, label, description, onActivate, onDeactivate, onError, }?: ReadingModeControllerProps): react.JSX.Element;
820
1196
 
1197
+ interface KeyboardShortcutsControllerProps {
1198
+ className?: string;
1199
+ label?: string;
1200
+ description?: string;
1201
+ }
1202
+ declare function KeyboardShortcutsController({ className, label, description, }: KeyboardShortcutsControllerProps): react.JSX.Element;
1203
+
1204
+ interface ReadAloudControllerProps {
1205
+ className?: string;
1206
+ label?: string;
1207
+ description?: string;
1208
+ onStart?: () => void;
1209
+ onEnd?: () => void;
1210
+ onError?: (error: Error) => void;
1211
+ }
1212
+ declare function ReadAloudController({ className, label, description, onStart, onEnd, onError, }?: ReadAloudControllerProps): react.JSX.Element;
1213
+
1214
+ /**
1215
+ * Dictionary provider interface, local curated dictionary, and sanitization policy.
1216
+ *
1217
+ * Implements A11Y-403:
1218
+ * - Explicit user action required (never auto-looks up on hover/focus)
1219
+ * - Zero network requests by default (100% offline static dictionary)
1220
+ * - Truthful unknown results (never hallucinates or fabricates definitions)
1221
+ * - Strict sanitization (strips HTML, limits length, rejects sensitive/token patterns)
1222
+ * - Rate-limited provider interface for custom backends
1223
+ * - Privacy protection (never sends whole-page DOM, cookies, or clipboard data)
1224
+ */
1225
+ interface DictionaryEntry {
1226
+ word: string;
1227
+ phonetic?: string;
1228
+ partOfSpeech?: string;
1229
+ definition: string;
1230
+ example?: string;
1231
+ source: "local" | "custom" | "provider";
1232
+ language?: string;
1233
+ }
1234
+ interface DictionaryLookupResult {
1235
+ found: boolean;
1236
+ term?: string;
1237
+ entry?: DictionaryEntry;
1238
+ suggestions?: string[];
1239
+ error?: string;
1240
+ }
1241
+ interface DictionaryProvider {
1242
+ id: string;
1243
+ name: string;
1244
+ lookup: (word: string, lang?: string) => Promise<DictionaryLookupResult>;
1245
+ allowedOrigins?: string[];
1246
+ rateLimitMs?: number;
1247
+ }
1248
+ /**
1249
+ * Built-in curated accessibility & web dictionary entries.
1250
+ * Guaranteed 100% offline with zero network requests.
1251
+ */
1252
+ declare const LOCAL_DICTIONARY_EN: Record<string, Omit<DictionaryEntry, "word" | "source">>;
1253
+ declare const LOCAL_DICTIONARY_SI: Record<string, Omit<DictionaryEntry, "word" | "source">>;
1254
+ declare const LOCAL_DICTIONARY_TA: Record<string, Omit<DictionaryEntry, "word" | "source">>;
1255
+ /**
1256
+ * Sanitizes and validates a lookup term.
1257
+ * Removes HTML tags, excess whitespace, and control characters.
1258
+ * Enforces length bounds (1 to 50 characters).
1259
+ */
1260
+ declare function sanitizeLookupTerm(term: unknown): {
1261
+ valid: boolean;
1262
+ sanitized: string;
1263
+ error?: string;
1264
+ };
1265
+ /**
1266
+ * Looks up a term in the built-in local static dictionary.
1267
+ * Guaranteed 100% offline, zero network requests, zero hallucination.
1268
+ */
1269
+ declare function lookupLocalDictionary(term: string, locale?: string): DictionaryLookupResult;
1270
+ /**
1271
+ * Executes a dictionary lookup using the configured provider or falling back to the local dictionary.
1272
+ * When provider is null or undefined (provider-off), performs zero network requests.
1273
+ */
1274
+ declare function lookupWord(term: string, options?: {
1275
+ locale?: string;
1276
+ provider?: DictionaryProvider | null;
1277
+ }): Promise<DictionaryLookupResult>;
1278
+
1279
+ interface DictionaryControllerProps {
1280
+ className?: string;
1281
+ label?: string;
1282
+ description?: string;
1283
+ provider?: DictionaryProvider | null;
1284
+ defaultOpen?: boolean;
1285
+ initialTerm?: string;
1286
+ }
1287
+ /**
1288
+ * Accessible dictionary modal controller.
1289
+ * Implements A11Y-403:
1290
+ * - Explicit user action lookup (never looks up automatically on hover or selection)
1291
+ * - Zero network requests by default (100% offline static dictionary fallback)
1292
+ * - Strict sanitization and sensitive data rejection
1293
+ * - Truthful unknown responses (never hallucinates definitions)
1294
+ * - Focus returns to trigger button after close
1295
+ * - Modal focus trapping with Escape key support
1296
+ */
1297
+ declare function DictionaryController({ className, label, description, provider, defaultOpen, initialTerm, }: DictionaryControllerProps): react.JSX.Element;
1298
+
1299
+ /**
1300
+ * Read-aloud Text-to-Speech (TTS) engine, content extraction, and lifecycle manager.
1301
+ *
1302
+ * Implements A11Y-401:
1303
+ * - Purely client-side Web Speech API integration (`speechSynthesis`).
1304
+ * - Zero network requests: no transcripts, recordings, or telemetry leave the package.
1305
+ * - Extracts readable text from selections, articles, or main content.
1306
+ * - Strictly excludes passwords, credit card inputs, hidden fields, and plugin UI.
1307
+ * - Chunks long text to prevent Chromium 15-second utterance lockup.
1308
+ * - Provides start, pause, resume, stop, voice selection, rate, and pitch controls.
1309
+ * - Automatically stops on Escape, unmount, visibilitychange, and page navigation.
1310
+ */
1311
+ interface ReadAloudOptions {
1312
+ rate?: number;
1313
+ pitch?: number;
1314
+ voiceUri?: string | null;
1315
+ lang?: string;
1316
+ onStart?: () => void;
1317
+ onEnd?: () => void;
1318
+ onPause?: () => void;
1319
+ onResume?: () => void;
1320
+ onError?: (error: Error) => void;
1321
+ onProgress?: (chunkIndex: number, totalChunks: number, chunkText: string) => void;
1322
+ }
1323
+ interface ReadAloudState {
1324
+ status: "idle" | "playing" | "paused" | "stopped" | "unsupported";
1325
+ currentChunkIndex: number;
1326
+ totalChunks: number;
1327
+ currentText: string;
1328
+ }
1329
+ declare const READ_ALOUD_EXCLUDED_SELECTORS: string[];
1330
+ /**
1331
+ * Checks whether the current environment supports Web Speech API speech synthesis.
1332
+ */
1333
+ declare function isSpeechSynthesisSupported(): boolean;
1334
+ /**
1335
+ * Retrieves the available speech synthesis voices in the current browser.
1336
+ */
1337
+ declare function getSpeechVoices(): SpeechSynthesisVoice[];
1338
+ /**
1339
+ * Subscribes to changes in available speech synthesis voices.
1340
+ */
1341
+ declare function subscribeSpeechVoices(callback: (voices: SpeechSynthesisVoice[]) => void): () => void;
1342
+ /**
1343
+ * Retrieves currently selected text on the page, ensuring it is not inside
1344
+ * sensitive form fields, passwords, or plugin UI.
1345
+ */
1346
+ declare function getActiveSelectionText(): string;
1347
+ /**
1348
+ * Extracts readable article or page text while strictly excluding sensitive,
1349
+ * hidden, form, and plugin elements.
1350
+ */
1351
+ declare function extractReadAloudText(options?: {
1352
+ root?: Element | Document;
1353
+ selectionOnly?: boolean;
1354
+ }): string;
1355
+ /**
1356
+ * Splits continuous text into natural sentence or punctuation chunks (~60-200 chars).
1357
+ * Prevents Web Speech API timeouts on long continuous utterances.
1358
+ */
1359
+ declare function splitTextIntoChunks(text: string, maxChunkLength?: number): string[];
1360
+ /**
1361
+ * Session manager controlling speech playback, queueing, pausing, and lifecycle cleanup.
1362
+ */
1363
+ declare class ReadAloudSession {
1364
+ private chunks;
1365
+ private currentChunkIndex;
1366
+ private status;
1367
+ private options;
1368
+ private listeners;
1369
+ private cleanupFns;
1370
+ private isDestroyed;
1371
+ constructor();
1372
+ getState(): ReadAloudState;
1373
+ subscribe(listener: (state: ReadAloudState) => void): () => void;
1374
+ private notify;
1375
+ speak(text: string, options?: ReadAloudOptions): void;
1376
+ private speakCurrentChunk;
1377
+ pause(): void;
1378
+ resume(): void;
1379
+ stop(): void;
1380
+ setRate(rate: number): void;
1381
+ setPitch(pitch: number): void;
1382
+ setVoice(voiceUri: string | null): void;
1383
+ destroy(): void;
1384
+ }
1385
+
1386
+ /**
1387
+ * Keyboard shortcuts registry, collision detection, and form protection.
1388
+ *
1389
+ * Implements A11Y-308:
1390
+ * - Discoverable, localized shortcut help
1391
+ * - Collision-checked remapping
1392
+ * - Never hijacks browser shortcuts (e.g. Ctrl+U, Ctrl+R, Ctrl+T, Ctrl+W, F5)
1393
+ * - Keeps global shortcuts disabled by default
1394
+ * - Form and route command protection: never intercepts keystrokes inside inputs or textareas
1395
+ * - Button alternatives provided for every shortcut
1396
+ */
1397
+ interface ShortcutDefinition {
1398
+ id: string;
1399
+ category: "widget" | "navigation" | "reading" | "tools";
1400
+ labelKey: string;
1401
+ descriptionKey: string;
1402
+ defaultKey: string;
1403
+ allowRemap: boolean;
1404
+ }
1405
+ declare const DEFAULT_SHORTCUTS: ShortcutDefinition[];
1406
+ /**
1407
+ * Standard reserved browser and OS shortcuts that must NEVER be hijacked or remapped to.
1408
+ * Specifically includes Ctrl+U (view source), Ctrl+R (reload), Ctrl+T (new tab), etc.
1409
+ */
1410
+ declare const RESERVED_BROWSER_SHORTCUTS: Set<string>;
1411
+ /**
1412
+ * Normalizes a key combination string into standard "Alt+Shift+Key" format.
1413
+ */
1414
+ declare function normalizeKeyCombo(combo: string): string;
1415
+ /**
1416
+ * Parses a native KeyboardEvent into a normalized key combo string.
1417
+ */
1418
+ declare function parseKeyboardEventToCombo(event: KeyboardEvent): string;
1419
+ /**
1420
+ * Checks whether a key event occurred inside a form field or editable text container.
1421
+ * Never hijacks keys when user is typing in forms, text inputs, search boxes, or contenteditable.
1422
+ */
1423
+ declare function isFormFieldOrEditable(target: EventTarget | null): boolean;
1424
+ interface ValidationResult {
1425
+ valid: boolean;
1426
+ error?: string;
1427
+ normalizedCombo?: string;
1428
+ }
1429
+ /**
1430
+ * Validates a proposed keyboard shortcut remapping against:
1431
+ * 1. Reserved browser and operating system shortcuts (especially Ctrl+U, Ctrl+R, etc.)
1432
+ * 2. Minimum modifier requirements (must have Alt or Ctrl+Alt to avoid intercepting normal typing)
1433
+ * 3. Collisions with other active accessibility plugin shortcuts
1434
+ */
1435
+ declare function validateShortcutRemap(shortcutId: string, newCombo: string, existingCustomShortcuts?: Record<string, string>): ValidationResult;
1436
+ /**
1437
+ * Resolves the active keyboard shortcut for an action ID by checking custom overrides first,
1438
+ * then falling back to defaults.
1439
+ */
1440
+ declare function resolveActiveShortcut(shortcutId: string, customShortcuts?: Record<string, string>): string;
1441
+
821
1442
  interface CustomPreset {
822
1443
  id: string;
823
1444
  name: string;
@@ -906,4 +1527,398 @@ interface UsePresetsResult {
906
1527
  */
907
1528
  declare function usePresets(): UsePresetsResult;
908
1529
 
909
- export { ALLOWED_PREFERENCE_KEYS, ALL_PROFILE_IDS, AccessibilityButton, type AccessibilityButtonProps, AccessibilityContext, type AccessibilityContextValue, AccessibilityList, type AccessibilityListProps, AccessibilityPlugin, type AccessibilityPluginProps, type AccessibilityPreferences, AccessibilityProfilesController, type AccessibilityState, AccessibleTooltipsController, type ActiveProfileState, type ArticleContent, 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_PREFERENCES, DEFAULT_READING_MASK_HEIGHT, DYSLEXIA_FONT_STACK, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, FONT_FAMILY_PRESETS, FONT_FAMILY_PROTECTED_SELECTOR, FeatureCard, type FeatureCardProps, type FeatureLocaleLabels, type FeatureOptions, type FeatureRegistration, type FeatureStatus, FocusHighlightController, FontFamilyController, type FontFamilyPreference, type FontFamilyPreset, FontSizeController, type FontSizeControllerProps, GrayscaleController, type HeadingItem, HeadingsNavigatorController, HideDecorativeImagesController, HideImagesController, type HideImagesControllerProps, HideVideosController, HighlightFocusController, type ImportResult, InvertColorsController, LEGIBLE_FONT_STACK, LINE_HEIGHT_RATIOS, LINE_HEIGHT_STEPS, type LandmarkItem, LetterSpacingController, type LetterSpacingControllerProps, LineHeightController, type LineHeightControllerProps, LinkHighlightController, type LocaleStrings, MAX_READING_MASK_HEIGHT, MIN_READING_MASK_HEIGHT, PROFILE_DEFINITIONS, PageNavigatorController, type PageNavigatorControllerProps, PageStructureController, ParagraphSpacingController, type ParagraphSpacingControllerProps, type PluginPosition, PresetsBackupController, PresetsController, type PresetsControllerProps, type PresetsExportV1, ProfileController, type ProfileDefinition, type ProfilePresetId, ProfilePreviewCard, type ProfilePreviewCardProps, ProfilesController, type ProfilesControllerProps, READING_MASK_HEIGHT_PRESETS, type ReaderMode, ReadingGuideController, type ReadingGuideControllerProps, ReadingMaskController, type ReadingMaskControllerProps, ReadingModeController, type ReadingModeControllerProps, ReduceMotionController, ResetController, SaturationController, type SaturationPreference, type ScriptSpacingConstraints, SearchCount, type SearchCountProps, SettingsImportExportController, SkipToMainLink, type SkipToMainLinkProps, StepperControl, type StepperControlProps, type StorageMode, type SupportedLocale, TEXT_ALIGN_BLOCK_SELECTOR, TEXT_SCALE_PROTECTED_SELECTOR, TEXT_SCALE_STEPS, TEXT_SPACING_EXCLUDED_SELECTOR, TextAlignController, type TextAlignPreference, TextScaleController, type TextScaleControllerProps, type TextScaleStep, ToggleControl, type ToggleControlProps, TooltipsController, type TooltipsControllerProps, type UsePresetsResult, type UseProfilesResult, type WidgetPlacement, WordSpacingController, type WordSpacingControllerProps, applyCustomPresetToStore, applyProfileToStore, countWords, createCustomPreset, createInitialPreferencesState, downloadJsonFile, enLocale, enableAccessibleTooltips, estimateReadingTime, exportPresetsToJson, extractArticleContent, findArticleCandidate, findMainLandmark, getAuthoredDescription, getProfileDefinition, getScriptSpacingConstraints, hasFinePointer, isEligibleDecorativeImage, isForcedColorsActive, isFunctionalOrMeaningfulImage, isProtectedFromContrast, isProtectedFromFontFamily, isProtectedFromTextAlign, isProtectedFromTextScale, isProtectedFromTextSpacing, isReducedMotionActive, isRtlLocale, isValidCustomPreset, mapFeaturesToProfileSettings, mapProfileSettingsToFeatures, navigateToElement, normalizePreferenceValue, normalizePreferences, nudgeReadingAid, positionTooltip, preferencesReducer, recordProfileOverride, registerLocale, resolveEffectivePreferences, resolveLocaleStrings, revertProfileFromStore, sanitizePreferences, scanHeadings, scanLandmarks, siLocale, subscribeFinePointer, subscribeForcedColors, subscribePageStructure, subscribeReducedMotion, taLocale, useAccessibility, usePresets, useProfiles, validateAndParseImport };
1530
+ interface FeatureMenuProps {
1531
+ /** Menu customization configuration. */
1532
+ config?: MenuCustomizationConfig;
1533
+ /** Whether to render items in categorized visual groups. Defaults to false (flat list). */
1534
+ grouped?: boolean;
1535
+ /** Custom wrapper CSS class. */
1536
+ className?: string;
1537
+ }
1538
+ /**
1539
+ * Renders a validated, ordered, and optionally grouped accessibility menu.
1540
+ * Implements A11Y-404:
1541
+ * - Diagnoses invalid configuration without crashing
1542
+ * - Guarantees stable rerenders with persistent keys
1543
+ * - Supports custom labels, ordering, and feature visibility
1544
+ */
1545
+ declare function FeatureMenu({ config, grouped, className, }: FeatureMenuProps): react__default.JSX.Element;
1546
+
1547
+ interface DiagnosticsHarnessProps {
1548
+ /** Optional diagnostics configuration overrides. */
1549
+ config?: DiagnosticsConfig;
1550
+ /** Force rendering even in production. Default is false. */
1551
+ force?: boolean;
1552
+ /** Whether the harness drawer starts open. Default is false. */
1553
+ defaultOpen?: boolean;
1554
+ /** Custom CSS class. */
1555
+ className?: string;
1556
+ }
1557
+ declare function DiagnosticsHarness({ config, force, defaultOpen, className, }: DiagnosticsHarnessProps): react__default.JSX.Element | null;
1558
+
1559
+ /**
1560
+ * React hook to retrieve integration diagnostics.
1561
+ * In production environments, returns an empty report unless `config.force` is true.
1562
+ */
1563
+ declare function useDiagnostics(config?: DiagnosticsConfig): DiagnosticsReport;
1564
+
1565
+ /**
1566
+ * Smart Contrast Research Prototype (A11Y-407).
1567
+ *
1568
+ * Implements measured contrast evaluation and assistance for eligible visible elements:
1569
+ * - Mathematical WCAG 2.1 relative luminance and contrast ratio algorithms
1570
+ * - Alpha compositing and ancestor backdrop resolution
1571
+ * - Fast batching: strictly separated read, compute, and write phases to prevent layout thrashing
1572
+ * - Detection and reporting of unsupported complex backdrops (gradients, background images, backdrop filters)
1573
+ * - Complete non-destructive restoration
1574
+ * - Strictly an opt-in research prototype: zero automatic WCAG compliance claims
1575
+ */
1576
+ declare const SMART_CONTRAST_DISCLAIMER = "Research prototype only. Smart contrast evaluates foreground and backdrop colors using WCAG 2.1 mathematical relative luminance algorithms. It does not replace manual accessibility inspection or guarantee legal/formal WCAG 2.1 AA/AAA compliance.";
1577
+ type SmartContrastLevel = "off" | "aa" | "aaa";
1578
+ type UnsupportedReason = "gradient" | "background-image" | "backdrop-filter" | "invisible" | "indeterminate";
1579
+ interface RgbColor {
1580
+ r: number;
1581
+ g: number;
1582
+ b: number;
1583
+ }
1584
+ interface RgbaColor extends RgbColor {
1585
+ a: number;
1586
+ }
1587
+ interface UnsupportedElementInfo {
1588
+ tag: string;
1589
+ id?: string;
1590
+ className?: string;
1591
+ reason: UnsupportedReason;
1592
+ textSnippet?: string;
1593
+ }
1594
+ interface SmartContrastReport {
1595
+ evaluatedCount: number;
1596
+ adjustedCount: number;
1597
+ sufficientCount: number;
1598
+ unsupportedCount: number;
1599
+ unsupportedElements: UnsupportedElementInfo[];
1600
+ durationMs: number;
1601
+ targetLevel: "aa" | "aaa";
1602
+ targetRatioNormal: number;
1603
+ targetRatioLarge: number;
1604
+ disclaimer: string;
1605
+ }
1606
+ interface SmartContrastOptions {
1607
+ /** Target WCAG contrast level: "aa" (4.5:1 normal / 3.0:1 large) or "aaa" (7.0:1 normal / 4.5:1 large). Defaults to "aa". */
1608
+ targetLevel?: "aa" | "aaa";
1609
+ /** Root container to evaluate. Defaults to document.body. */
1610
+ root?: HTMLElement;
1611
+ /** Maximum number of elements to process in a single pass to ensure 60fps responsiveness. Defaults to 2000. */
1612
+ maxElements?: number;
1613
+ }
1614
+ /** WCAG 2.1 target contrast thresholds */
1615
+ declare const TARGET_RATIOS: {
1616
+ readonly aa: {
1617
+ readonly normal: 4.5;
1618
+ readonly large: 3;
1619
+ };
1620
+ readonly aaa: {
1621
+ readonly normal: 7;
1622
+ readonly large: 4.5;
1623
+ };
1624
+ };
1625
+ /** High-contrast replacement tokens designed for clean-light & dark contrast palettes */
1626
+ declare const HIGH_CONTRAST_TOKENS: {
1627
+ readonly onLight: "#0f172a";
1628
+ readonly onDark: "#ffffff";
1629
+ };
1630
+ /**
1631
+ * Parses a CSS color string into an RGBA object.
1632
+ * Supports: rgb(), rgba(), hex (#rgb, #rgba, #rrggbb, #rrggbbaa), transparent, and standard named colors.
1633
+ */
1634
+ declare function parseColor(colorStr: string): RgbaColor | null;
1635
+ /**
1636
+ * Calculates WCAG 2.1 relative luminance for an sRGB color.
1637
+ * L = 0.2126 * R + 0.7152 * G + 0.0722 * B
1638
+ */
1639
+ declare function calculateRelativeLuminance(r: number, g: number, b: number): number;
1640
+ /**
1641
+ * Calculates contrast ratio between two relative luminances according to WCAG 2.1 specs.
1642
+ * Formula: (L1 + 0.05) / (L2 + 0.05), where L1 is lighter and L2 is darker.
1643
+ * Returns a value between 1.0 and 21.0.
1644
+ */
1645
+ declare function calculateContrastRatio(l1: number, l2: number): number;
1646
+ /**
1647
+ * Alpha composites a foreground layer over a background layer using standard Porter-Duff source-over blending.
1648
+ */
1649
+ declare function compositeRgba(fg: RgbaColor, bg: RgbaColor): RgbaColor;
1650
+ /**
1651
+ * Determines whether text qualifies as "large text" under WCAG 2.1 SC 1.4.3:
1652
+ * - At least 18pt (24px) normal, or
1653
+ * - At least 14pt (18.66px) bold (font-weight >= 700 or "bold").
1654
+ */
1655
+ declare function isLargeText(fontSizePx: number, fontWeight: string | number): boolean;
1656
+ interface BackdropResolution {
1657
+ backdrop: RgbaColor;
1658
+ isUnsupported: boolean;
1659
+ reason?: UnsupportedReason;
1660
+ }
1661
+ /**
1662
+ * Resolves the effective backdrop color beneath an element by traversing up the ancestor tree
1663
+ * and compositing semi-transparent layers. Detects unsupported complex backdrops.
1664
+ */
1665
+ declare function resolveEffectiveBackdrop(element: HTMLElement, computedMap?: Map<Element, CSSStyleDeclaration>): BackdropResolution;
1666
+ /**
1667
+ * Checks whether an element is eligible for smart contrast inspection.
1668
+ */
1669
+ declare function isEligibleForSmartContrast(element: Element): boolean;
1670
+ /**
1671
+ * Evaluates smart contrast for all eligible elements within root without modifying the DOM.
1672
+ * Implements strict batching to prevent layout thrashing.
1673
+ */
1674
+ declare function evaluateSmartContrast(options?: SmartContrastOptions): SmartContrastReport;
1675
+ interface AppliedSmartContrast {
1676
+ report: SmartContrastReport;
1677
+ undo: () => void;
1678
+ }
1679
+ /**
1680
+ * Evaluates and applies measured contrast adjustments to eligible elements.
1681
+ * Separates reads, computation, and batched writes to prevent layout thrashing.
1682
+ * Returns the audit report and an idempotent undo() restoration function.
1683
+ */
1684
+ declare function applySmartContrast(options?: SmartContrastOptions): AppliedSmartContrast;
1685
+
1686
+ /**
1687
+ * Voice Navigation Research Prototype
1688
+ *
1689
+ * Implements A11Y-408:
1690
+ * - Explicit, finite voice-command set: open/close widget, heading navigation, scrolling, stop, help.
1691
+ * - Strict user-initiated permission and consent.
1692
+ * - Prominent visual listening indicator and accessible live status announcements.
1693
+ * - Zero audio recording storage, zero transcript persistence, zero network transmission.
1694
+ * - Automatic inactivity timeout (30 seconds) and tab/unmount cleanup.
1695
+ * - No destructive host actions, no form inputs, no profile activation.
1696
+ * - Full accessible keyboard alternatives for all voice commands.
1697
+ */
1698
+ declare const VOICE_NAVIGATION_DISCLAIMER = "Voice navigation is an experimental research prototype. Audio is processed solely through your browser's native Web Speech API during active listening sessions. No audio streams, recordings, or transcripts are stored locally or transmitted to external servers. Destructive actions and profile modifications are strictly excluded.";
1699
+ type VoiceNavigationStatus = "idle" | "listening" | "processing" | "unsupported" | "denied" | "timeout" | "error";
1700
+ type VoiceCommandId = "open_widget" | "close_widget" | "next_heading" | "previous_heading" | "first_heading" | "scroll_down" | "scroll_up" | "scroll_top" | "scroll_bottom" | "stop_listening" | "help";
1701
+ interface VoiceCommandDefinition {
1702
+ id: VoiceCommandId;
1703
+ label: string;
1704
+ phrases: string[];
1705
+ description: string;
1706
+ category: "widget" | "navigation" | "scroll" | "system";
1707
+ }
1708
+ interface VoiceNavigationResult {
1709
+ commandId?: VoiceCommandId;
1710
+ rawTranscript: string;
1711
+ normalizedTranscript: string;
1712
+ matched: boolean;
1713
+ feedback: string;
1714
+ timestamp: number;
1715
+ }
1716
+ interface VoiceNavigationOptions {
1717
+ lang?: string;
1718
+ inactivityTimeoutMs?: number;
1719
+ onStatusChange?: (status: VoiceNavigationStatus) => void;
1720
+ onCommandRecognized?: (result: VoiceNavigationResult) => void;
1721
+ onError?: (error: Error | string) => void;
1722
+ onWidgetOpen?: () => void;
1723
+ onWidgetClose?: () => void;
1724
+ onAction?: (actionName: string, detail: Record<string, unknown>) => void;
1725
+ }
1726
+ declare const VOICE_COMMANDS: VoiceCommandDefinition[];
1727
+ /**
1728
+ * Checks whether native Web Speech Recognition API is supported in the current environment.
1729
+ */
1730
+ declare function isSpeechRecognitionSupported(): boolean;
1731
+ /**
1732
+ * Normalizes speech recognition transcript string for deterministic matching.
1733
+ */
1734
+ declare function normalizeTranscript(transcript: string): string;
1735
+ /**
1736
+ * Matches a transcript against the defined voice commands.
1737
+ */
1738
+ declare function matchVoiceCommand(rawTranscript: string): {
1739
+ command: VoiceCommandDefinition | null;
1740
+ normalized: string;
1741
+ };
1742
+ interface VoiceExecutionContext {
1743
+ onWidgetOpen?: () => void;
1744
+ onWidgetClose?: () => void;
1745
+ currentHeadingIndexRef?: {
1746
+ current: number;
1747
+ };
1748
+ onAction?: (actionName: string, detail: Record<string, unknown>) => void;
1749
+ }
1750
+ /**
1751
+ * Safely executes a matched voice command without destructive side-effects.
1752
+ */
1753
+ declare function executeVoiceCommand(commandId: VoiceCommandId, context?: VoiceExecutionContext): {
1754
+ success: boolean;
1755
+ feedback: string;
1756
+ };
1757
+ interface VoiceNavigationSession {
1758
+ start: () => void;
1759
+ stop: () => void;
1760
+ abort: () => void;
1761
+ destroy: () => void;
1762
+ getStatus: () => VoiceNavigationStatus;
1763
+ getLastResult: () => VoiceNavigationResult | null;
1764
+ }
1765
+ /**
1766
+ * Factory creating an active voice navigation session with lifecycle, timeout,
1767
+ * and privacy management.
1768
+ */
1769
+ declare function createVoiceNavigationSession(options?: VoiceNavigationOptions): VoiceNavigationSession;
1770
+
1771
+ interface VoiceNavigationControllerProps {
1772
+ className?: string;
1773
+ onCommandRecognized?: (result: VoiceNavigationResult) => void;
1774
+ onError?: (error: Error | string) => void;
1775
+ }
1776
+ declare function VoiceNavigationController({ className, onCommandRecognized, onError, }?: VoiceNavigationControllerProps): react.JSX.Element;
1777
+
1778
+ /**
1779
+ * Host-content translation adapter architecture, privacy threat model, and DOM sanitization.
1780
+ *
1781
+ * Implements A11Y-409:
1782
+ * - Distinct from widget UI localization (src/core/i18n/ statically localizes widget controls).
1783
+ * - Provider adapter interface with clear privacy/retention/origin boundaries.
1784
+ * - Explicit user consent required before sending text to external or custom providers.
1785
+ * - Zero network requests by default (no automatic translation or default requests).
1786
+ * - Strict exclusion of sensitive elements (passwords, auth tokens, credit cards, PII, hidden nodes).
1787
+ * - Iframe & cross-origin boundary enforcement (never traverses cross-origin frames).
1788
+ * - XSS & DOM injection prevention via strict textContent assignment and output sanitization.
1789
+ * - Complete teardown and instant restoration back to original host text.
1790
+ * - Non-destructive execution: zero medical/compliance claims.
1791
+ */
1792
+ type DataRetentionPolicy = "none" | "transient" | "logged" | "model-training";
1793
+ type TranslationConsentStatus = "unprompted" | "granted" | "denied" | "revoked";
1794
+ interface TranslationConsentRecord {
1795
+ status: TranslationConsentStatus;
1796
+ grantedAt?: number;
1797
+ providerId?: string;
1798
+ targetLanguage?: string;
1799
+ userAcknowledgedRisks: boolean;
1800
+ }
1801
+ interface TranslationRequest {
1802
+ texts: string[];
1803
+ sourceLanguage?: string;
1804
+ targetLanguage: string;
1805
+ signal?: AbortSignal;
1806
+ }
1807
+ interface TranslatedItem {
1808
+ original: string;
1809
+ translated: string;
1810
+ detectedSourceLanguage?: string;
1811
+ }
1812
+ interface TranslationResponse {
1813
+ translations: TranslatedItem[];
1814
+ providerId: string;
1815
+ timestamp: number;
1816
+ attribution?: string;
1817
+ }
1818
+ interface TranslationAdapter {
1819
+ id: string;
1820
+ name: string;
1821
+ description?: string;
1822
+ privacyPolicyUrl?: string;
1823
+ dataRetention?: DataRetentionPolicy;
1824
+ dataResidency?: string;
1825
+ allowedOrigins?: string[];
1826
+ supportedTargetLanguages: string[] | (() => Promise<string[]>);
1827
+ translate: (request: TranslationRequest) => Promise<TranslationResponse>;
1828
+ }
1829
+ interface TranslatableNode {
1830
+ node: Text;
1831
+ originalText: string;
1832
+ translatedText?: string;
1833
+ parentElement: Element;
1834
+ }
1835
+ interface TranslationSession {
1836
+ active: boolean;
1837
+ providerId: string;
1838
+ targetLanguage: string;
1839
+ translatedCount: number;
1840
+ restore: () => void;
1841
+ }
1842
+ declare const TRANSLATION_ERROR_CODES: {
1843
+ readonly CONSENT_REQUIRED: "CONSENT_REQUIRED";
1844
+ readonly NO_PROVIDER: "NO_PROVIDER";
1845
+ readonly UNSUPPORTED_LANGUAGE: "UNSUPPORTED_LANGUAGE";
1846
+ readonly EMPTY_REQUEST: "EMPTY_REQUEST";
1847
+ readonly NETWORK_ERROR: "NETWORK_ERROR";
1848
+ readonly CSP_BLOCKED: "CSP_BLOCKED";
1849
+ readonly RATE_LIMITED: "RATE_LIMITED";
1850
+ readonly SANITIZATION_FAILED: "SANITIZATION_FAILED";
1851
+ readonly SENSITIVE_CONTENT_BLOCKED: "SENSITIVE_CONTENT_BLOCKED";
1852
+ readonly DOM_MUTATION_ERROR: "DOM_MUTATION_ERROR";
1853
+ readonly ABORTED: "ABORTED";
1854
+ };
1855
+ type TranslationErrorCode = (typeof TRANSLATION_ERROR_CODES)[keyof typeof TRANSLATION_ERROR_CODES];
1856
+ declare class TranslationError extends Error {
1857
+ readonly code: TranslationErrorCode;
1858
+ readonly details?: unknown;
1859
+ constructor(code: TranslationErrorCode, message: string, details?: unknown);
1860
+ }
1861
+ /**
1862
+ * Standard disclaimer: machine-assisted translation is an assistive convenience,
1863
+ * not guaranteed for legal, medical, or WCAG compliance accuracy.
1864
+ */
1865
+ declare const TRANSLATION_DISCLAIMER = "Research Prototype: Host content translation is machine-assisted and provided for convenience only. It does not guarantee semantic accuracy, cultural fidelity, or legal/regulatory compliance. Content containing sensitive or personal information is excluded.";
1866
+ declare const MAX_NODES_PER_TRANSLATION_BATCH = 500;
1867
+ declare const MAX_TEXT_LENGTH_PER_NODE = 2000;
1868
+ /**
1869
+ * Evaluates whether an element or any of its ancestors represents sensitive,
1870
+ * protected, or non-translatable content.
1871
+ */
1872
+ declare function isSensitiveElement(element: Element | null): boolean;
1873
+ /**
1874
+ * Traverses DOM tree starting from root and collects translatable text nodes,
1875
+ * strictly skipping sensitive elements, widget elements, scripts, and iframes.
1876
+ */
1877
+ declare function extractTranslatableNodes(root: Element, maxNodes?: number): TranslatableNode[];
1878
+ /**
1879
+ * Sanitizes translated output strings to prevent XSS and control character injection.
1880
+ * Because nodes are applied via textContent, raw HTML is never parsed by the DOM,
1881
+ * but this removes control codes and null bytes.
1882
+ */
1883
+ declare function sanitizeTranslationOutput(raw: string): string;
1884
+ /**
1885
+ * Applies translated strings to translatable text nodes safely using textContent.
1886
+ * Returns an idempotent restore function that reverts all modified nodes to their original text.
1887
+ */
1888
+ declare function applyTranslations(nodes: TranslatableNode[], translations: string[]): () => void;
1889
+ /**
1890
+ * Creates an offline, mock translation adapter for development and testing.
1891
+ * Operates 100% locally with zero network requests.
1892
+ */
1893
+ declare function createOfflineMockTranslationAdapter(options?: {
1894
+ latencyMs?: number;
1895
+ prefix?: string;
1896
+ supportedLanguages?: string[];
1897
+ }): TranslationAdapter;
1898
+ /**
1899
+ * Coordinates end-to-end host content translation:
1900
+ * 1. Verifies user consent status (throws if unprompted, denied, or revoked).
1901
+ * 2. Checks target language support on provider.
1902
+ * 3. Extracts translatable DOM nodes skipping sensitive elements.
1903
+ * 4. Calls provider adapter.
1904
+ * 5. Applies translations to text nodes and returns a TranslationSession with full restore capability.
1905
+ */
1906
+ declare function translateHostContent(options: {
1907
+ rootElement?: Element;
1908
+ provider: TranslationAdapter;
1909
+ targetLanguage: string;
1910
+ sourceLanguage?: string;
1911
+ consentRecord: TranslationConsentRecord;
1912
+ signal?: AbortSignal;
1913
+ }): Promise<TranslationSession>;
1914
+
1915
+ interface TranslationControllerProps {
1916
+ className?: string;
1917
+ label?: string;
1918
+ description?: string;
1919
+ provider?: TranslationAdapter;
1920
+ defaultTargetLanguage?: string;
1921
+ }
1922
+ declare const TranslationController: react__default.FC<TranslationControllerProps>;
1923
+
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 };