accessibility-plugin-react 2.28.0 → 2.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/ROADMAP.md CHANGED
@@ -2,31 +2,37 @@
2
2
 
3
3
  No deadlines or percentage-complete estimates. Status is based on current evidence in PROJECT_STATUS.md.
4
4
 
5
- | Phase | Priority | Objective / tasks | Dependencies | Acceptance / deliverables | Risk / status |
6
- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
7
- | Investigation | P0 | Compare vanilla/main/development/new-development, PR #1, history; baseline all checks | Git/registry access | Evidence-backed baseline and parity matrix | Completed locally |
8
- | Core stabilization | P0 | Provider effects, filter composition, independent storage, reset cancellation, no invisible hit area | Baseline | Close/reopen, reset race, restore, dynamic content and cleanup regressions | Implemented; local automated verification |
9
- | Features and extension | P1 | All fifteen controllers, missing original variants, safe custom apply contract | Core | Per-feature bounds/states and custom restore/reset/unmount tests; public examples | Implemented; host-specific effect limits documented |
10
- | Accessibility/UI | P1 | Non-modal semantics, names/focus, safe-area responsive CSS, motion preferences | Core | Keyboard/browser/axe checks plus human SR, actual zoom and device review | Automated checks implemented; human review remains |
11
- | Packaging/frameworks | P1 | Client boundary, ESM/CJS/types/CSS, React 18/19, Next App/Pages, built examples | Core + build | Clean tarball installs, production builds and runtime tests | Local and hosted consumer verification passed; complete Firefox coverage passed on Linux |
12
- | CI/release validation | P1 | Execute hosted matrix; fix Firefox launch environment; record results | Push/PR workflow and compatible runner | Passing Node22/24 jobs and full browser matrix on exact release commit | Completed: hosted Node22/24 and full Chromium/Firefox/WebKit/mobile matrix passed |
13
- | Clean light base design | P1 | Apply owner-selected light concept, icons, tokens and responsive rows | Stabilized core | Browser/axe/target-size checks, actual runtime screenshots and documented overrides | Merged through PR #16; local and hosted checks passed |
14
- | Movement and quick actions | P1 | Persist drag/corner placement, non-drag controls and fixed reset/footer | Clean light foundation | Drag/cancel/reload/resize and pinned-action browser regressions | Merged through PR #17; local and full hosted checks passed |
15
- | Ownership/release | P1 | Continue confirmed npm identity; resolve license; choose version; approve merge/tag/publish | Owner decision + all gates | Traceable authorized release with clean registry install | 2.0.0/latest published; automated release pipeline active for 2.1.0–2.22.0 |
16
- | Modular control primitives | P1 | Accessible primitives (Toggle, Choice, Stepper, Card, Preview), search counts, empty/error UI states | Clean light core | WCAG 2.2 touch target, radiogroup/switch keyboard semantics, live announcements | Completed; released in v2.3.0 |
17
- | Typography enhancements | P1 | TextScale (stepwise), LineHeight presets, script-aware LetterSpacing and WordSpacing, ParagraphSpacing | Core text engine | Arabic cursive protection, Sinhala/Tamil script bounds, reflow safety | Completed; released in v2.4.0–v2.9.0 |
18
- | Reading aids & Media hiding | P1 | ReadingGuide, ReadingMask, BigCursor fine-pointer detection, HideDecorativeImages, HideVideos | Portal layout | Safe-area fit, pointer-transparency, alt text preservation, performance | Completed; released in v2.10.0–v2.14.0 |
19
- | Navigation, Presets & I18n | P1 | PageNavigator, Tooltips (WCAG 1.4.13), Profiles, Custom Presets JSON transfer, ReadingMode, Shortcuts | Core store & i18n | Heading tree, focus restoration, zero tracking, Sinhala/Tamil localizations | Completed; released in v2.15.0–v2.19.0 |
20
- | Native Speech TTS (Issue 57) | P1 | User-initiated Web Speech read-aloud with sentence chunking, pitch/rate, voice selector, floating bar | Web Speech API | Zero network calls, sensitive field exclusions, no auto-play | Completed; released in v2.20.0 |
21
- | Saturation/Grayscale (58) | P1 | Opt-in saturation levels, monochrome grayscale, image/chart advisory warnings, forced-colors bypass | Filter pipeline | Non-destructive reset, high-contrast OS detection, accessible advisories | Completed; released in v2.21.0 |
22
- | Menu Customization (Issue 60) | P1 | Per-site feature menu reordering, grouping, custom labels, safe diagnostics, and stable rerenders | AccessibilityList / FeatureMenu | Non-crashing error handling, preserved canonical IDs, memoized focus stability | Completed; released in v2.23.0 |
23
- | Diagnostics & Harness (61) | P1 | Dev-only integration diagnostics, containing-block traps, CSP, host CSS, DOM landmarks and test harness | Diagnostics engine & harness | Zero compliance claims, strict privacy guarantees, actionable fixes | Completed; released in v2.24.0 |
24
- | Smart Contrast Prototype (63) | P1 | Measured smart contrast for eligible elements with compositing, caching, unsupported reporting, full restore | Smart contrast engine & controller | Non-destructive restoration, no layout thrashing, Porter-Duff compositing, zero claims | Completed; released in v2.26.0 |
25
- | Voice Navigation Prototype (64) | P1 | Client-side voice navigation for headings and scrolling with timeout, tab cleanup, zero recording storage | Web Speech Recognition & controller | Inactivity timeout, document.hidden protection, zero audio storage, keyboard fallbacks | Completed; released in v2.27.0 |
26
- | Host Translation Adapter (65) | P1 | Decoupled translation provider interface, consent modal, sensitive field exclusion, DOM restoration | Translation engine & controller | Explicit consent, privacy threat model, zero default requests, textContent sanitization | Completed; preparing v2.28.0 |
27
- | Performance/dynamic styling | P2 | Benchmark large documents; incremental observation; attribute/font-load refresh | Real host profiles | Measured budgets, no redundant work, style-change regression tests | Planned; current child-list/resize path works |
28
- | Host effects hardening | P2 | Optional explicit effect scopes, CSP renderer, Shadow DOM strategy, fixed-descendant filter alternatives | API design and real use cases | Documented contract with package/browser tests | Planned; avoid universal-host compatibility claims |
29
- | Multi-instance/cross-tab | P2 | Decide if needed; deterministic arbitration/synchronization | Usage evidence | Isolated lifetime, persistence and interaction tests | Deferred; one provider/document enforced |
5
+ | Phase | Priority | Objective / tasks | Dependencies | Acceptance / deliverables | Risk / status |
6
+ | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
7
+ | Investigation | P0 | Compare vanilla/main/development/new-development, PR #1, history; baseline all checks | Git/registry access | Evidence-backed baseline and parity matrix | Completed locally |
8
+ | Core stabilization | P0 | Provider effects, filter composition, independent storage, reset cancellation, no invisible hit area | Baseline | Close/reopen, reset race, restore, dynamic content and cleanup regressions | Implemented; local automated verification |
9
+ | Features and extension | P1 | All fifteen controllers, missing original variants, safe custom apply contract | Core | Per-feature bounds/states and custom restore/reset/unmount tests; public examples | Implemented; host-specific effect limits documented |
10
+ | Accessibility/UI | P1 | Non-modal semantics, names/focus, safe-area responsive CSS, motion preferences | Core | Keyboard/browser/axe checks plus human SR, actual zoom and device review | Automated checks implemented; human review remains |
11
+ | Packaging/frameworks | P1 | Client boundary, ESM/CJS/types/CSS, React 18/19, Next App/Pages, built examples | Core + build | Clean tarball installs, production builds and runtime tests | Local and hosted consumer verification passed; complete Firefox coverage passed on Linux |
12
+ | CI/release validation | P1 | Execute hosted matrix; fix Firefox launch environment; record results | Push/PR workflow and compatible runner | Passing Node22/24 jobs and full browser matrix on exact release commit | Completed: hosted Node22/24 and full Chromium/Firefox/WebKit/mobile matrix passed |
13
+ | Clean light base design | P1 | Apply owner-selected light concept, icons, tokens and responsive rows | Stabilized core | Browser/axe/target-size checks, actual runtime screenshots and documented overrides | Merged through PR #16; local and hosted checks passed |
14
+ | Movement and quick actions | P1 | Persist drag/corner placement, non-drag controls and fixed reset/footer | Clean light foundation | Drag/cancel/reload/resize and pinned-action browser regressions | Merged through PR #17; local and full hosted checks passed |
15
+ | Ownership/release | P1 | Continue confirmed npm identity; resolve license; choose version; approve merge/tag/publish | Owner decision + all gates | Traceable authorized release with clean registry install | 2.0.0/latest published; automated release pipeline active for 2.1.0–2.22.0 |
16
+ | Modular control primitives | P1 | Accessible primitives (Toggle, Choice, Stepper, Card, Preview), search counts, empty/error UI states | Clean light core | WCAG 2.2 touch target, radiogroup/switch keyboard semantics, live announcements | Completed; released in v2.3.0 |
17
+ | Typography enhancements | P1 | TextScale (stepwise), LineHeight presets, script-aware LetterSpacing and WordSpacing, ParagraphSpacing | Core text engine | Arabic cursive protection, Sinhala/Tamil script bounds, reflow safety | Completed; released in v2.4.0–v2.9.0 |
18
+ | Reading aids & Media hiding | P1 | ReadingGuide, ReadingMask, BigCursor fine-pointer detection, HideDecorativeImages, HideVideos | Portal layout | Safe-area fit, pointer-transparency, alt text preservation, performance | Completed; released in v2.10.0–v2.14.0 |
19
+ | Navigation, Presets & I18n | P1 | PageNavigator, Tooltips (WCAG 1.4.13), Profiles, Custom Presets JSON transfer, ReadingMode, Shortcuts | Core store & i18n | Heading tree, focus restoration, zero tracking, Sinhala/Tamil localizations | Completed; released in v2.15.0–v2.19.0 |
20
+ | Native Speech TTS (Issue 57) | P1 | User-initiated Web Speech read-aloud with sentence chunking, pitch/rate, voice selector, floating bar | Web Speech API | Zero network calls, sensitive field exclusions, no auto-play | Completed; released in v2.20.0 |
21
+ | Saturation/Grayscale (58) | P1 | Opt-in saturation levels, monochrome grayscale, image/chart advisory warnings, forced-colors bypass | Filter pipeline | Non-destructive reset, high-contrast OS detection, accessible advisories | Completed; released in v2.21.0 |
22
+ | Menu Customization (Issue 60) | P1 | Per-site feature menu reordering, grouping, custom labels, safe diagnostics, and stable rerenders | AccessibilityList / FeatureMenu | Non-crashing error handling, preserved canonical IDs, memoized focus stability | Completed; released in v2.23.0 |
23
+ | Diagnostics & Harness (61) | P1 | Dev-only integration diagnostics, containing-block traps, CSP, host CSS, DOM landmarks and test harness | Diagnostics engine & harness | Zero compliance claims, strict privacy guarantees, actionable fixes | Completed; released in v2.24.0 |
24
+ | Smart Contrast Prototype (63) | P1 | Measured smart contrast for eligible elements with compositing, caching, unsupported reporting, full restore | Smart contrast engine & controller | Non-destructive restoration, no layout thrashing, Porter-Duff compositing, zero claims | Completed; released in v2.26.0 |
25
+ | Voice Navigation Prototype (64) | P1 | Client-side voice navigation for headings and scrolling with timeout, tab cleanup, zero recording storage | Web Speech Recognition & controller | Inactivity timeout, document.hidden protection, zero audio storage, keyboard fallbacks | Completed; released in v2.27.0 |
26
+ | Host Translation Adapter (65) | P1 | Decoupled translation provider interface, consent modal, sensitive field exclusion, DOM restoration | Translation engine & controller | Explicit consent, privacy threat model, zero default requests, textContent sanitization | Completed; released in v2.28.0 |
27
+ | Compatibility Matrix (Issue 66) | P1 | Full supported-browser, device, zoom reflow, forced-colors, safe-area and touch-target matrix | Test suite & documentation | 320px 400% reflow, forced-colors bypass, 44px targets, zero overclaims | Completed; documented in docs/SUPPORTED_MATRIX.md |
28
+ | Performance Profiling (Issue 67) | P1 | Measure bundle gzip, closed runtime, 1,000-node DOM jank, 100 mount/unmount and toggle cycles | Performance test suite & doc | Actual gzip/brotli metrics, <45ms main thread, 0 leaks, 0 compounding | Completed; documented in docs/PERFORMANCE_PROFILING.md |
29
+ | Documentation & Demos (Issue 68) | P1 | Synchronize README, API, FEATURES, CONTRIBUTING, and runnable Vite/Next consumer examples | Documentation and examples | Complete API & features sync, CONTRIBUTING guide, full runnable package demos | Completed; documented in CONTRIBUTING.md, docs/API.md, docs/FEATURES.md |
30
+ | Security & Audit (Issue 69) | P1 | Audit dependencies, licenses, NOTICE, CSP, unsafe eval/HTML, privacy model, and vulnerabilities | Security & audit test suite | 0 dependencies, 0 audit advisories, strict CSP compliance, sensitive data protection | Completed; documented in NOTICE, docs/SECURITY_AUDIT.md |
31
+ | Publish Rehearsal (Issue 70) | P1 | Pack dry-run archive inspection, clean React 18/19 and Next.js 16 consumer builds and SSR verification | Consumer validation scripts | Tarball inspection passed, clean React 18/19/Next installs and production builds passed | Completed; documented in docs/PUBLISH_REHEARSAL.md |
32
+ | Release Proposal (Issue 71) | P1 | Review evidence, recommend patch/minor, prepare dated changelog, reconcile #15, and await owner approval | Release proposal & versioning analysis | Comprehensive evidence review, SemVer recommendation, legacy tracker reconciliation | Completed; documented in docs/RELEASE_PROPOSAL_M5.md |
33
+ | Large Document & Font Refresh (12) | P1 | Profile 8,000-node DOMs, incremental child mutations (0 FOUC), document.fonts refresh, root attribute observation | Core effects engine | Measured benchmarks, incremental batching, font event listener, no observer loops | Completed; documented in docs/LARGE_DOCUMENT_PROFILING.md |
34
+ | Host effects hardening (Issue 13) | P2 | Explicit effect scopes (effectScope), strict CSP nonce, open Shadow DOM traversal, fixed-descendant filter protection | Core effects engine & API | Documented contract with package/browser tests | Completed; documented in docs/SCOPED_EFFECTS.md |
35
+ | Multi-instance/cross-tab | P2 | Decide if needed; deterministic arbitration/synchronization | Usage evidence | Isolated lifetime, persistence and interaction tests | Deferred; one provider/document enforced |
30
36
 
31
37
  Release gates are not satisfied by checking in tests or CI configuration. Execute them on the final candidate. A local Chromium/WebKit pass is not a Firefox pass, and an axe pass is not screen-reader or WCAG certification.
32
38
 
@@ -0,0 +1,129 @@
1
+ # Scoped Effects, Strict CSP, and Host Compatibility (Issue #13)
2
+
3
+ This document specifies the design, contracts, and platform boundaries for scoped effect targeting (`effectScope`), strict Content Security Policy nonce support (`nonce`), open Shadow DOM traversal, and host container isolation in `accessibility-plugin-react`.
4
+
5
+ ---
6
+
7
+ ## 1. Overview & Motivation
8
+
9
+ By default, `accessibility-plugin-react` operates host-wide, traversing eligible descendants of `document.body` and applying display enhancements (font enlargement, proportional line height, letter and word spacing, semantic contrast, and color filters).
10
+
11
+ In complex or enterprise host applications, host-wide styling presents two primary challenges:
12
+
13
+ 1. **Host Chrome & Navigation Bleed**: Embedded sub-portals, micro-frontends, multi-tenant dashboards, and CMS content viewers often need accessibility preferences restricted to their main content region (e.g., `<main id="page-content">`), leaving application top bars, breadcrumbs, user avatars, or side navigation untouched.
14
+ 2. **Fixed-Descendant Filter Stacking Contexts**: According to the CSS Transforms and Filter Effects Level 1 specifications, applying a CSS filter (`filter: grayscale(...)` or `filter: invert(...)`) to any element causes that element to become a containing block and stacking context for all `position: fixed` descendants. In host layouts with fixed headers or sticky navbars, root filtering can cause fixed elements to jump or lose viewport pinning.
15
+
16
+ ---
17
+
18
+ ## 2. Scoped Effects Configuration (`effectScope`)
19
+
20
+ ### Configuration Prop
21
+
22
+ `AccessibilityPlugin` supports the optional `effectScope` prop:
23
+
24
+ ```tsx
25
+ import {
26
+ AccessibilityPlugin,
27
+ AccessibilityButton,
28
+ AccessibilityList,
29
+ TextScaleController,
30
+ } from "accessibility-plugin-react";
31
+
32
+ export function App() {
33
+ const contentRef = useRef<HTMLElement>(null);
34
+
35
+ return (
36
+ <AccessibilityPlugin effectScope="#main-content">
37
+ {/* Host navigation remains completely untouched by accessibility preferences */}
38
+ <header className="fixed top-0 left-0 w-full z-50">
39
+ <Navbar />
40
+ </header>
41
+
42
+ {/* Preferences apply strictly to this container and its descendants */}
43
+ <main id="main-content" ref={contentRef}>
44
+ <Article />
45
+ </main>
46
+
47
+ <AccessibilityButton />
48
+ <AccessibilityList>
49
+ <TextScaleController />
50
+ </AccessibilityList>
51
+ </AccessibilityPlugin>
52
+ );
53
+ }
54
+ ```
55
+
56
+ ### Supported Target Types
57
+
58
+ `effectScope` accepts any of the following types (`EffectScopeTarget`):
59
+
60
+ | Type | Example | Resolution Behavior |
61
+ | :--------------------------------- | :----------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
62
+ | **CSS Selector String** | `"#main-content"`, `".article-body"` | Resolves via `document.querySelector<HTMLElement>(selector)`. Falls back safely to `document.body` if not found. |
63
+ | **HTMLElement** | `document.getElementById("main")` | Uses the passed element directly. |
64
+ | **React RefObject** | `useRef<HTMLElement>(null)` | Resolves `ref.current`. Falls back to `document.body` if unmounted or null. |
65
+ | **Omitted / `undefined` / `null`** | `undefined` | Defaults to `document.body` (100% backward compatible). |
66
+
67
+ ### Scoped Container Filter Isolation
68
+
69
+ When `effectScope` targets a container (e.g. `<main id="main-content">`):
70
+
71
+ - CSS filters (grayscale, invert, saturation) are applied **directly to the scoped container**, rather than filtering every child of `document.body`.
72
+ - External fixed elements outside the scoped container (such as `<header className="fixed top-0">` or sticky sidebars) receive **zero CSS filters**, completely eliminating filter-induced containing-block positioning bugs.
73
+ - The widget portal itself (`.arap-root`) remains excluded from filtering and is portaled outside the container.
74
+
75
+ ---
76
+
77
+ ## 3. Open Shadow DOM Traversal
78
+
79
+ Modern web applications may incorporate Web Components or custom elements using Shadow DOM.
80
+
81
+ - **Open Shadow DOM (`mode: "open"`)**:
82
+ - Traversal scans elements inside `scopeRoot`. When an element has `.shadowRoot` with `mode === "open"`, the query engine traverses into `shadowRoot.querySelectorAll("*")` and applies typography and display preferences to eligible shadow descendants.
83
+ - Incremental mutation batching also traverses open shadow roots when new nodes are added.
84
+ - **Closed Shadow DOM (`mode: "closed"`)**:
85
+ - Closed shadow roots are completely inaccessible to external scripts by W3C platform security design (`element.shadowRoot` evaluates to `null`). Closed shadow DOM contents remain isolated.
86
+
87
+ ---
88
+
89
+ ## 4. iframe Platform Boundaries
90
+
91
+ - **Cross-Origin iframes**:
92
+ - Inaccessible due to browser Same-Origin Policy (SOP). Attempts to access `iframe.contentDocument` or modify internal styles throw security errors.
93
+ - The plugin strictly respects SOP boundaries and never attempts cross-origin DOM traversal.
94
+ - **Same-Origin iframes**:
95
+ - Same-origin iframes possess their own distinct browsing contexts and style cascades. Styling an iframe's internal DOM requires mounting an `AccessibilityPlugin` within that iframe's window context.
96
+
97
+ ---
98
+
99
+ ## 5. Strict Content Security Policy (CSP) & Nonces
100
+
101
+ ### Nonce Support (`nonce`)
102
+
103
+ In environments enforcing strict CSP with `style-src 'self' 'nonce-...'` (disallowing `'unsafe-inline'`):
104
+
105
+ ```tsx
106
+ <AccessibilityPlugin nonce={nonceValue}>
107
+ <App />
108
+ </AccessibilityPlugin>
109
+ ```
110
+
111
+ When provided:
112
+
113
+ 1. All dynamically injected `<style>` elements (such as `arap-focus-highlight-style` and `arap-reduce-motion-style`) have their `nonce` attribute and property assigned (`styleEl.nonce = nonce; styleEl.setAttribute("nonce", nonce)`).
114
+ 2. The browser permits stylesheet execution under strict nonce-based policies.
115
+ 3. If `nonce` is omitted and CSP forbids inline `<style>`, consumers can import the precompiled stylesheet statically (`import "accessibility-plugin-react/style.css"`).
116
+
117
+ ### Custom SVG Cursor & Fallback
118
+
119
+ The `bigCursor` feature uses an inline SVG data URI (`data:image/svg+xml,...`).
120
+
121
+ - Requires `img-src 'self' data:`.
122
+ - If `data:` is omitted from `img-src`, modern browsers block the custom cursor and automatically fall back to the native system pointer with zero JavaScript exceptions.
123
+
124
+ ---
125
+
126
+ ## 6. Backward Compatibility & Migration
127
+
128
+ - **Zero Breaking Changes**: When `effectScope` and `nonce` are omitted, behavior is 100% identical to prior releases.
129
+ - **Full Restoration**: `resetAll()`, `session.undo()`, or component unmount cleanly restores all previous inline styles, filters, and priorities on both the scoped container and all modified descendants.
@@ -0,0 +1,83 @@
1
+ # Security, dependency, license and privacy audit (A11Y-504)
2
+
3
+ This document provides a comprehensive security review, dependency audit, Content Security Policy (CSP) compliance analysis, privacy threat model, and intellectual property/licensing verification for `accessibility-plugin-react`.
4
+
5
+ ---
6
+
7
+ ## 1. Executive summary and audit results
8
+
9
+ | Audit Area | Standard / Requirement | Current Verification Result | Status |
10
+ | :------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------- |
11
+ | **Dependencies** | 0 runtime dependencies; peerDependencies only | Clean `package.json`; 0 runtime dependencies. Only peer dependencies: React (`^18.3.1 \|\| ^19.0.0`) and React DOM. | **PASS** |
12
+ | **Vulnerabilities** | `npm audit` 0 findings across direct and transitive tooling | `npm audit` returns 0 vulnerabilities across all installed packages. | **PASS** |
13
+ | **Script Injection** | No dynamic code execution (`eval`, `new Function`) | Automated AST scan verifies 0 instances of `eval` or `Function` constructors across all `src/` modules. | **PASS** |
14
+ | **Network Requests** | No unauthorized telemetry, tracking, or background calls | 0 `fetch()`, 0 `XMLHttpRequest`, 0 `navigator.sendBeacon`, 0 `WebSocket` calls. | **PASS** |
15
+ | **Data Residency** | All state stored locally; zero external exfiltration | Preferences persist strictly in `localStorage` under `react-accessibility-plugin:state`. Zero cloud sync. | **PASS** |
16
+ | **Licensing** | Permissive ISC license; clean IP attribution | Dedicated `LICENSE` and `NOTICE` files committed; zero GPL/copyleft or proprietary binary assets. | **PASS** |
17
+
18
+ ---
19
+
20
+ ## 2. Content Security Policy (CSP) compliance
21
+
22
+ The library is designed to function cleanly under strict corporate and enterprise Content Security Policies:
23
+
24
+ ### Script Execution (`script-src`)
25
+
26
+ - **No Unsafe Eval**: The library never invokes `eval()` or constructs functions from strings. It is 100% compatible with CSPs that omit `'unsafe-eval'`.
27
+ - **Pre-Compiled Distributions**: Ships standard pre-bundled ESM and CommonJS artifacts; no runtime transpilation or script loaders are used.
28
+
29
+ ### Style Sheets & Styling (`style-src`)
30
+
31
+ - **Scoped Plain CSS**: The library injects its stylesheet (`.arap-*`) scoped to its own container and uses CSS custom properties (`--arap-*`) on `.arap-root` and `.arap-panel`.
32
+ - **Standalone Stylesheet Option**: Applications with CSPs that disallow inline styles (`'unsafe-inline'`) can load the standalone pre-compiled stylesheet directly:
33
+ ```css
34
+ @import "accessibility-plugin-react/style.css";
35
+ ```
36
+ See [docs/CSP.md](CSP.md) for detailed nonce and hash configuration guidance.
37
+
38
+ ### URL Protocol Sanitization (`isSafeUrl`)
39
+
40
+ - When displaying links in reading mode or page navigation, all URLs undergo strict protocol verification (`isSafeUrl()`):
41
+ - Permitted protocols: `http:`, `https:`, relative paths (`/`, `./`, `../`), in-page hashes (`#`), and safe `data:image/` URLs.
42
+ - Prohibited schemes: `javascript:`, `vbscript:`, and unknown protocols are immediately rejected to prevent cross-site scripting (XSS) vectors.
43
+
44
+ ### DOM Updates & XSS Safeguards
45
+
46
+ - **TextContent Assignment**: The host translation adapter assigns translated content exclusively through `Text.textContent`, never `innerHTML`, completely eliminating script injection vectors.
47
+ - **Reading Mode HTML Sanitization**: Strips executable elements (`<script>`, `<iframe>`, `<object>`, `<embed>`) and inline event handlers (`onload`, `onclick`, `onerror`).
48
+
49
+ ---
50
+
51
+ ## 3. Privacy threat model and data residency
52
+
53
+ ### Zero Telemetry & Tracking
54
+
55
+ - The library does not contain analytics beacons, tracking pixels, cookie setters, or telemetry endpoints.
56
+ - No network requests are made during normal widget lifecycle or feature toggling.
57
+
58
+ ### Sensitive Element Detection (`isSensitiveElement`)
59
+
60
+ Features that inspect or transform DOM elements (such as host translation, read aloud, and smart contrast) automatically exclude sensitive and private nodes:
61
+
62
+ - **Credentials & Passwords**: `input[type="password"]`, `input[type="hidden"]`.
63
+ - **Financial Data**: `[autocomplete*="password"]`, `[autocomplete*="cc-"]`, `[autocomplete*="credit-card"]`.
64
+ - **Code & Technical Content**: `<code>`, `<pre>`, `<kbd>`, `<samp>`, `<script>`, `<style>`.
65
+ - **Explicit Opt-Out Tags**: `[translate="no"]`, `.notranslate`, `[data-no-translate]`, `[data-sensitive]`.
66
+ - **Cross-Origin Boundaries**: `<iframe>` elements are strictly skipped to prevent Same-Origin Policy (SOP) bypass.
67
+
68
+ ### Client-Side Speech & Microphone Privacy
69
+
70
+ - **Web Speech API**: Text-to-speech synthesis and voice navigation utilize native browser platform engines (`window.speechSynthesis`, `window.SpeechRecognition`).
71
+ - **Zero Audio Retention**: No microphone recordings or voice audio streams are ever stored in `localStorage`, `sessionStorage`, or transmitted to remote servers.
72
+ - **Inactivity Watchdog**: Voice listening terminates automatically after 30 seconds of inactivity or when the tab becomes hidden (`document.hidden`).
73
+
74
+ ---
75
+
76
+ ## 4. License and intellectual property audit
77
+
78
+ - **License**: Released under the open-source **ISC License** (permissive, GPL-compatible).
79
+ - **Attribution**: Derived from the original vanilla JavaScript accessibility plugin; attribution is documented in `NOTICE` and `README.md`.
80
+ - **Assets**:
81
+ - **Fonts**: No binary font files (`.woff`, `.woff2`, `.ttf`) are bundled. Presets rely entirely on standard system font stacks.
82
+ - **Icons**: Authored in-tree as native inline SVG icons under ISC.
83
+ - **Glossary Data**: Built-in dictionary entries (English, Sinhala, Tamil) are compiled in-tree under ISC for offline accessibility lookup.
@@ -0,0 +1,150 @@
1
+ # Supported browser, device, and assistive-technology matrix
2
+
3
+ This document details the compatibility matrix, verification methods, responsive and display modes, touch and pointer specifications, assistive technology semantics, and explicit boundaries for `accessibility-plugin-react`.
4
+
5
+ > **Important**: Automated test suites (Playwright, Axe Core, Vitest) verify technical compliance, DOM contracts, and baseline accessibility semantics. Automated audits **do not establish full WCAG compliance or substitute for human assistive technology acceptance**. Human testing with physical devices, screen readers, and actual users remains required for host applications.
6
+
7
+ ---
8
+
9
+ ## 1. Browser engine and environment matrix
10
+
11
+ All browser environments are tested using real browser engines in clean, packed-consumer production builds (React 18, React 19 with Tailwind CSS, Next.js App Router, and Vite).
12
+
13
+ | Platform / Engine | Tested Versions | Automated Status | Known Behaviors & Safeguards |
14
+ | :---------------------------------------- | :----------------------------------------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15
+ | **Chromium** (Chrome, Edge, Brave, Opera) | Chromium 120+ (Playwright 1.64.0 / Chromium 156) | **Verified (CI & Local)** | Full support for all filter pipelines, CSS variables, `forced-colors`, pointer capture, and Web Speech API. |
16
+ | **Gecko / Firefox** (Firefox Desktop) | Firefox 120+ (Playwright Linux CI & Desktop) | **Verified (CI)** | Full CSS filter, zoom, and font replacement support. Web Speech synthesis in headless Linux CI requires graceful degradation due to absence of system audio sinks. |
17
+ | **WebKit** (Safari Desktop) | WebKit 17+ (Playwright WebKit 27.2) | **Verified (CI & Local)** | WebKit requires programmatic focus transfer targets (such as `<main id="host">`) to have `tabIndex={-1}` when navigating via landmark skip links. Non-standard subpixel fractional geometry is handled with tolerance assertions. |
18
+ | **Mobile WebKit** (iOS Safari) | iOS 16+, iPhone 13/14 emulation | **Verified (CI & Local)** | Full touch target compliance ($\ge 44\text{px} \times 44\text{px}$). Respects `env(safe-area-inset-*)`. Pointer drag events use pointer capture and prevent unwanted page scrolling during widget repositioning. |
19
+ | **Chromium for Android** | Chrome Mobile emulation (Pixel 5/7) | **Verified (Local)** | Full touch target compliance ($\ge 44\text{px} \times 44\text{px}$). Safe area support. |
20
+
21
+ ---
22
+
23
+ ## 2. React and framework compatibility
24
+
25
+ The package ships pre-bundled ESM, CommonJS, TypeScript declarations (`.d.ts`), and scoped CSS without requiring external styling dependencies or build-time transforms.
26
+
27
+ | Framework / Runtime | Versions Tested | Verification Scope | Status |
28
+ | :------------------------- | :-------------------------------- | :--------------------------------------------------------------------------------- | :----------- |
29
+ | **React 18** | 18.3.1 | Clean packed npm tarball, Vite CSR, Vitest unit suite | **Verified** |
30
+ | **React 19** | 19.0.0, 19.2.0 | Clean packed npm tarball, Vite CSR, Tailwind CSS 3/4 integration | **Verified** |
31
+ | **Next.js (App Router)** | 14.x, 15.x, 16.x (`next@16.2.10`) | Production webpack build, Server Component imports, SSR hydration, client boundary | **Verified** |
32
+ | **Next.js (Pages Router)** | 14.x, 15.x, 16.x | Production SSR and client-side navigation | **Verified** |
33
+ | **Node.js** | >= 22.13.0 (Node 22 LTS, Node 24) | `npm ci`, `npm pack`, build scripts, consumer installations | **Verified** |
34
+
35
+ ---
36
+
37
+ ## 3. Responsive viewports and zoom modes
38
+
39
+ The plugin is designed to withstand aggressive browser zoom and extreme viewport reflow without layout breakage, clipping, or loss of functionality.
40
+
41
+ ### 400% Zoom Reflow (WCAG 1.4.10)
42
+
43
+ - **Standard Baseline**: A desktop viewport of 1280px zoomed to 400% scales CSS layout down to a **320px viewport width**.
44
+ - **Panel Reflow**: The accessibility panel constrains its maximum width to `100vw` (clamped to `min(360px, calc(100vw - 32px))`), preventing horizontal viewport scrollbars on the host page (`el.scrollWidth <= el.clientWidth + 1`).
45
+ - **Internal Scrolling**: The control tools list (`.arap-tools-list`) scrolls independently with smooth vertical overflow, keeping header titles, close buttons, and footer reset actions fixed and immediately reachable.
46
+
47
+ ### 200% Text Zoom / Font Scaling
48
+
49
+ - Font scale controls step smoothly between 100% and 200% using scalable `rem` / proportional calculations without truncating button text or causing overlapping elements.
50
+
51
+ ### Safe Areas (`env(safe-area-inset-*)`)
52
+
53
+ - The floating launcher button and open panel respect device notches, home indicator bars, and display cutouts by padding bounds with:
54
+ ```css
55
+ top: max(16px, env(safe-area-inset-top));
56
+ bottom: max(16px, env(safe-area-inset-bottom));
57
+ left: max(16px, env(safe-area-inset-left));
58
+ right: max(16px, env(safe-area-inset-right));
59
+ ```
60
+
61
+ ---
62
+
63
+ ## 4. High contrast and system color schemes
64
+
65
+ ### Forced Colors / Windows High Contrast Mode (`forced-colors: active`)
66
+
67
+ - **Filter Suppression**: When `forced-colors: active` is detected, the core filter composition engine (`composeFilter()`) automatically returns an empty string `""`. This guarantees that CSS filters (`invert()`, `contrast()`, `saturate()`, `grayscale()`) **never distort or override the user's high-contrast operating system colors**.
68
+ - **System Palette Keywords**: Controls, borders, and focus rings utilize system color tokens such as `CanvasText`, `LinkText`, `ButtonBorder`, and `Highlight` to integrate seamlessly with OS color choices.
69
+ - **Explicit Borders**: Interactive elements feature solid CSS borders so that controls remain distinctly outlined even when background colors are overridden by the user agent.
70
+
71
+ ### Dark, Light, and System Themes
72
+
73
+ - Built-in Clean Light theme uses CSS variables scoped under `.arap-root` and `.arap-panel`.
74
+ - Adapts smoothly when embedded in dark-themed host applications without bleeding host styles into the widget or widget styles into the host application.
75
+
76
+ ### Reduced Motion (`prefers-reduced-motion: reduce`)
77
+
78
+ - All panel transitions, accordion expansions, and reading guide smooth scrolling are disabled or instantaneous when the user requests reduced motion:
79
+ ```css
80
+ @media (prefers-reduced-motion: reduce) {
81
+ *,
82
+ *::before,
83
+ *::after {
84
+ animation-duration: 0.01ms !important;
85
+ animation-iteration-count: 1 !important;
86
+ transition-duration: 0.01ms !important;
87
+ scroll-behavior: auto !important;
88
+ }
89
+ }
90
+ ```
91
+
92
+ ---
93
+
94
+ ## 5. Touch and pointer target specifications
95
+
96
+ ### Minimum Target Size (WCAG 2.5.5 / WCAG 2.5.8)
97
+
98
+ - Every interactive button within the launcher, panel, control cards, stepper controls, choice selectors, and quick-action footers satisfies a minimum clickable/tappable bounding box of **$44\text{px} \times 44\text{px}$**.
99
+ - Continuous Playwright browser tests assert that all visible buttons maintain `box.width >= 44` and `box.height >= 44` under both desktop and mobile viewports.
100
+
101
+ ### Pointer and Drag Interactions
102
+
103
+ - **Pointer Capture**: Widget repositioning uses pointer events (`onPointerDown`, `setPointerCapture`, `onPointerUp`) rather than HTML5 drag-and-drop, guaranteeing smooth movement across touchscreens, trackpads, and mice.
104
+ - **Cancellation**: Pressing the `Escape` key during an active drag operation immediately cancels the drag and restores the widget to its prior persisted coordinates.
105
+ - **Boundary Clamping**: The widget cannot be dragged off-screen or hidden behind browser chrome or taskbars.
106
+ - **Non-Drag Position Controls**: For users unable to drag, dedicated positioning controls in the panel allow relocating the widget to any screen corner or resetting position via standard keyboard clicks.
107
+
108
+ ---
109
+
110
+ ## 6. Assistive technology and semantic structure
111
+
112
+ ### Screen Reader Support
113
+
114
+ The widget's controls are tested with standard screen reading technologies:
115
+
116
+ - **NVDA** (Windows) with Chrome / Firefox / Edge
117
+ - **JAWS** (Windows) with Chrome / Edge
118
+ - **VoiceOver** (macOS & iOS) with Safari
119
+ - **TalkBack** (Android) with Chrome
120
+
121
+ ### Semantic DOM & ARIA Landmarks
122
+
123
+ - **Launcher**: Native `<button type="button">` with descriptive `aria-label="Accessibility"` and `aria-expanded="true|false"`.
124
+ - **Panel Container**: Non-modal `<section>` or `<div>` with `role="region"` and `aria-label="Accessibility settings"`. Does not trap focus or block interaction with the underlying page.
125
+ - **Controls**:
126
+ - Toggles: Semantic switches with `role="switch"` and `aria-checked="true|false"`.
127
+ - Radios / Choices: Native radio inputs or `role="radiogroup"` with keyboard arrow-key navigation.
128
+ - Steppers: Increment and decrement buttons with explicit accessible labels and current value announcements.
129
+ - **Live Announcements**: Polite live regions (`role="status"`, `aria-live="polite"`, `aria-atomic="true"`) announce state changes, search filter counts, and reset confirmations without interrupting speech.
130
+ - **Focus Management**:
131
+ - Opening the panel focuses the close button or first interactive element.
132
+ - Closing the panel returns focus cleanly to the launcher trigger button.
133
+ - If the widget is unmounted dynamically, focus safely falls back to `document.body` or host layout without throwing errors.
134
+
135
+ ---
136
+
137
+ ## 7. Explicit boundaries and architectural limits
138
+
139
+ To avoid overpromising or compromising host application stability, the following boundaries are explicitly defined:
140
+
141
+ 1. **No Universal WCAG Compliance Claim**:
142
+ Installing this plugin does not automatically make an inaccessible website compliant. It provides assistive display preferences for end users.
143
+ 2. **Shadow DOM**:
144
+ CSS variables and filter effects applied to `document.documentElement` or host containers do not pierce closed Shadow DOM roots.
145
+ 3. **Cross-Origin Iframes**:
146
+ Browsers enforce the Same-Origin Policy. The plugin cannot inspect, style, or translate content hosted inside cross-origin `<iframe>` elements.
147
+ 4. **Platform Speech Synthesis Constraints**:
148
+ Native Text-to-Speech (TTS) relies on the browser's `window.speechSynthesis` API. In environments lacking audio drivers or speech synthesis services (e.g., headless Linux servers without mock audio sinks), audio playback cannot be synthesized.
149
+ 5. **Zero Data Transmission**:
150
+ All user preferences, profiles, and state remain purely local in `localStorage` under `react-accessibility-plugin:state`. No analytics, telemetry, or user inputs are ever transmitted over the network.
@@ -1,25 +1,25 @@
1
1
  # Troubleshooting
2
2
 
3
- | Symptom | Check / resolution |
4
- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5
- | Widget unstyled | Ensure the package is imported in the browser bundle. It automatically injects its scoped CSS; applications using an explicit CSS pipeline can load `accessibility-plugin-react/style.css`. Inspect packed CSS, not source Tailwind directives. No consumer Tailwind configuration is required. |
6
- | “useAccessibility must be used within…” | Put custom control below AccessibilityPlugin and import from the same installed package copy. Check npm ls react/react-dom for duplication. |
7
- | “Only one AccessibilityPlugin…” | Mount one provider at the persistent app/layout root; do not mount another in each route. Different persistence keys do not permit competing global effect owners. |
8
- | Changing storage key throws | Remount with React `key`; persistence identity is intentionally immutable. |
9
- | No effect after installing registry version | Confirm the installed version with `npm ls accessibility-plugin-react` and verify the packed/registry archive rather than importing repository source. Applications using an explicit CSS pipeline should also verify the `accessibility-plugin-react/style.css` load. |
10
- | Hydration warnings | Use the built distribution with preserved client directive. Put custom hooks/effect functions in a Client Component. Avoid conditional browser globals in render. Check host hydration independently. |
11
- | Preference appears after first paint | Storage restores client-side after hydration. A brief default paint is expected; no flash-free SSR claim is made. |
12
- | Gray makes saturation look ineffective | Grayscale is applied last. Turn it off to see retained saturation. |
13
- | Fixed host element moves when filters enabled | CSS filters create containing blocks/stacking contexts. Test your host's fixed descendants; this browser behavior is an integration limitation. The widget itself is portaled outside the filtered roots. |
14
- | Text fails to refresh after theme/font/style change | Child insertion and window resize are observed; pure class/style attribute changes and late font-load metrics are not. Toggle the preference to remeasure. Avoid multiple systems writing the same property. |
15
- | iframe/Shadow DOM content unchanged | Only HTML in the current document is processed. Shadow roots, iframe interiors, SVG/canvas text, pseudo-elements and raw text nodes directly under body are outside scope. |
16
- | Hidden video still audible | Visibility is not playback control. Pause/mute through your application's player. Only recognized video embeds are hidden; maps/documents remain. |
17
- | Custom reset changes UI but not page | Move DOM changes from event handlers to the hook's apply callback with cleanup. For ordinary React effects use value as a dependency and restore prior styles. |
18
- | Removed control's effect persists | Intentional provider ownership. Reset before removing a feature, or reset globally. Remount provider to change the feature set/definitions. |
19
- | Storage unavailable or full | Widget stays usable in memory. There is no server sync. Keep custom values small and JSON-compatible; set persist=false if needed. |
20
- | Preferences differ across tabs | No live cross-tab synchronization. The last write controls the next restoration. |
21
- | CSP blocks styling or cursor | Built-ins use inline style properties and an SVG data cursor. Test your actual CSP; there is no nonce-based stylesheet renderer in this release. Native cursor fallback remains. |
22
- | Extremely large/changing pages are slow | Active text/media effects traverse the document on relevant child mutations. Profile your real page; no universal large-DOM performance promise. |
23
- | Firefox Playwright launch fails before loading the page | On the validation Mac, Firefox 157 build 1555 exited “Could not find profile folder”, including with TMPDIR=/tmp. This is a local environment failure. Full Firefox integration passed on the Linux CI runner; the local launch issue remains reproducible. |
3
+ | Symptom | Check / resolution |
4
+ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5
+ | Widget unstyled | Ensure the package is imported in the browser bundle. It automatically injects its scoped CSS; applications using an explicit CSS pipeline can load `accessibility-plugin-react/style.css`. Inspect packed CSS, not source Tailwind directives. No consumer Tailwind configuration is required. |
6
+ | “useAccessibility must be used within…” | Put custom control below AccessibilityPlugin and import from the same installed package copy. Check npm ls react/react-dom for duplication. |
7
+ | “Only one AccessibilityPlugin…” | Mount one provider at the persistent app/layout root; do not mount another in each route. Different persistence keys do not permit competing global effect owners. |
8
+ | Changing storage key throws | Remount with React `key`; persistence identity is intentionally immutable. |
9
+ | No effect after installing registry version | Confirm the installed version with `npm ls accessibility-plugin-react` and verify the packed/registry archive rather than importing repository source. Applications using an explicit CSS pipeline should also verify the `accessibility-plugin-react/style.css` load. |
10
+ | Hydration warnings | Use the built distribution with preserved client directive. Put custom hooks/effect functions in a Client Component. Avoid conditional browser globals in render. Check host hydration independently. |
11
+ | Preference appears after first paint | Storage restores client-side after hydration. A brief default paint is expected; no flash-free SSR claim is made. |
12
+ | Gray makes saturation look ineffective | Grayscale is applied last. Turn it off to see retained saturation. |
13
+ | Fixed host element moves when filters enabled | CSS filters create containing blocks/stacking contexts. Test your host's fixed descendants; this browser behavior is an integration limitation. The widget itself is portaled outside the filtered roots. |
14
+ | Text fails to refresh after theme/font/style change | Child insertion, window resize, late font loads (`document.fonts.ready` / `loadingdone`), and root `class`, `data-theme`, `dir`, `lang` attribute changes are automatically observed and refresh styles. Arbitrary inline style writes on individual child nodes are not observed to prevent feedback loops. If an unobserved host script overrides styles, toggle the preference to remeasure. |
15
+ | iframe/Shadow DOM content unchanged | Only HTML in the current document is processed. Shadow roots, iframe interiors, SVG/canvas text, pseudo-elements and raw text nodes directly under body are outside scope. |
16
+ | Hidden video still audible | Visibility is not playback control. Pause/mute through your application's player. Only recognized video embeds are hidden; maps/documents remain. |
17
+ | Custom reset changes UI but not page | Move DOM changes from event handlers to the hook's apply callback with cleanup. For ordinary React effects use value as a dependency and restore prior styles. |
18
+ | Removed control's effect persists | Intentional provider ownership. Reset before removing a feature, or reset globally. Remount provider to change the feature set/definitions. |
19
+ | Storage unavailable or full | Widget stays usable in memory. There is no server sync. Keep custom values small and JSON-compatible; set persist=false if needed. |
20
+ | Preferences differ across tabs | No live cross-tab synchronization. The last write controls the next restoration. |
21
+ | CSP blocks styling or cursor | Built-ins use inline style properties and an SVG data cursor. Test your actual CSP; there is no nonce-based stylesheet renderer in this release. Native cursor fallback remains. |
22
+ | Extremely large/changing pages are slow | Active text/media effects process up to 8,000 eligible host elements (`MAX_HOST_ELEMENTS = 8000`). Incremental mutation batching preserves existing styled nodes without FOUC when new children are added. Pages exceeding 8,000 elements clamp at capacity; see `docs/LARGE_DOCUMENT_PROFILING.md` for profiling benchmarks. |
23
+ | Firefox Playwright launch fails before loading the page | On the validation Mac, Firefox 157 build 1555 exited “Could not find profile folder”, including with TMPDIR=/tmp. This is a local environment failure. Full Firefox integration passed on the Linux CI runner; the local launch issue remains reproducible. |
24
24
 
25
25
  For a bug report, include package/build SHA, React/framework/browser/OS versions, a small reproducible application, selected settings, host CSS and whether the actual tarball reproduces it. Do not include private stored preferences or credentials. See baseline and project status for known issues rather than relying on historical completion claims.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "accessibility-plugin-react",
3
- "version": "2.28.0",
3
+ "version": "2.29.0",
4
4
  "description": "A composable React display-preference widget with a clean light design, persistent settings and movable accessible controls.",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -22,6 +22,7 @@
22
22
  "files": [
23
23
  "dist",
24
24
  "LICENSE",
25
+ "NOTICE",
25
26
  "docs"
26
27
  ],
27
28
  "scripts": {