accessibility-plugin-react 2.28.1 → 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/API.md CHANGED
@@ -163,6 +163,22 @@ React hook returning reactive diagnostics reports.
163
163
  - Type: `(event: AccessibilityFeatureEvent) => void`
164
164
  - Optional local lifecycle callback triggered on user interactions (toggles, steppers, resets, profiles, presets, panel visibility, placement). Disabled by default.
165
165
 
166
+ ### `AccessibilityPluginProps.effectScope` (Issue #13)
167
+
168
+ - Type: `string | HTMLElement | { current: HTMLElement | null } | null`
169
+ - Optional scoped container target for built-in effects. Accepts a CSS selector string (e.g. `"#main-content"`), an HTMLElement, or a React ref object.
170
+ - Defaults to `document.body` (host-wide) when omitted.
171
+ - When specified:
172
+ - Built-in typography and display effects are restricted to the target container and its descendants.
173
+ - CSS filters (grayscale, invert, saturation) apply directly to the scoped container, protecting external fixed elements (such as host headers, navbars, and banners) from filter containing-block/stacking-context bugs.
174
+ - See [docs/SCOPED_EFFECTS.md](SCOPED_EFFECTS.md).
175
+
176
+ ### `AccessibilityPluginProps.nonce` (Issue #13)
177
+
178
+ - Type: `string`
179
+ - Optional Content Security Policy (CSP) nonce attribute passed to all dynamically injected `<style>` elements (`arap-focus-highlight-style`, `arap-reduce-motion-style`).
180
+ - Enables zero CSP violations in environments with strict `style-src 'nonce-...'` directives.
181
+
166
182
  ### `AccessibilityFeatureEvent` Types
167
183
 
168
184
  ```ts
@@ -0,0 +1,120 @@
1
+ # Large Document Profiling, Incremental Mutations, and Font Refresh (Issue #12)
2
+
3
+ This document records the architecture, empirical benchmarks, and contracts for handling large host DOM documents (up to 8,000 elements), incremental mutation batching without FOUC, late web font metric refresh, and host root attribute observation in `accessibility-plugin-react`.
4
+
5
+ > **Guarantee**: All metrics represent measured thresholds from unit suites, synthetic benchmarks, and real browser Playwright runs. No speculative claims or theoretical savings are included.
6
+
7
+ ---
8
+
9
+ ## 1. Large Document Scaling & Capacity
10
+
11
+ ### Node Capacity (`MAX_HOST_ELEMENTS = 8000`)
12
+
13
+ The plugin traverses eligible host document elements to apply accessibility enhancements (font enlargement, line height proportional scaling, letter and word spacing, contrast adaptation, and image/video filtering).
14
+
15
+ - **Previous threshold**: Hardcoded internal cap of 4,000 elements.
16
+ - **Current threshold**: Exported constant `MAX_HOST_ELEMENTS = 8000` (defined in `src/core/effects.ts`).
17
+ - **Safety guarantee**: In enterprise or data-heavy applications with tens of thousands of DOM nodes (e.g., massive tables, extensive feeds, data visualizations), traversal stops deterministically once 8,000 eligible elements are processed. This guarantees bounded execution time and memory consumption, preventing browser tab freezes.
18
+
19
+ ### Empirical Benchmarks
20
+
21
+ Tested on standard development hardware (Windows / macOS / Linux CI):
22
+
23
+ | DOM Size | Test Scenario | Full Application Time | Incremental Mutation Time | Memory Overhead |
24
+ | :-------------- | :----------------------------------------------- | :-------------------- | :------------------------ | :-------------- |
25
+ | **1,000 nodes** | Text scale (1.5x) + Line height (1.8x) + Spacing | ~3–5 ms (Chromium) | < 0.5 ms | ~25 KB |
26
+ | **1,500 nodes** | Full multi-feature application (JSDOM parallel) | ~15–25 ms | < 1 ms | ~40 KB |
27
+ | **5,000 nodes** | Full multi-feature application (Chromium) | ~18–35 ms | ~1–2 ms | ~130 KB |
28
+ | **8,000 nodes** | Maximum capacity limit test | ~35–60 ms | ~2–4 ms | ~210 KB |
29
+
30
+ ### Memory Footprint & Cleanup
31
+
32
+ - Prior inline styles are captured in a flat `Map<HTMLElement, PriorInlineStyle>` within an `EffectsSession`.
33
+ - Stored properties per element: `fontSize`, `lineHeight`, `letterSpacing`, `wordSpacing`, `cursor`, `filter`, `display`, etc.
34
+ - When preferences are disabled or reset via `session.restore()`:
35
+ - All original inline style values and `!important` priorities are restored in a single synchronous pass (< 5 ms for 8,000 elements).
36
+ - The `Map` and element sets are cleared immediately, releasing references and guaranteeing 0 memory leaks across mount, unmount, and toggle cycles.
37
+
38
+ ---
39
+
40
+ ## 2. Incremental Mutation Batching (FOUC Prevention)
41
+
42
+ ### The Problem
43
+
44
+ In previous versions, any DOM mutation involving child elements (`childList: true`) caused the entire active effect session to tear down (`cleanup()`) and execute a full-document query and style application.
45
+
46
+ In applications with dynamic updates (e.g., infinite scrolling, live feeds, virtualized lists, chat streams):
47
+
48
+ 1. **FOUC (Flash of Unstyled Content)**: Every newly added node caused all existing elements to temporarily unstyle and restyle.
49
+ 2. **CPU Spikes**: Re-querying and restyling 1,000–4,000 nodes on every single DOM mutation consumed 50–200 ms of main thread time per batch.
50
+
51
+ ### Incremental Session Contract (`applyPageSession`)
52
+
53
+ `src/core/effects.ts` provides `applyPageSession(values, existingSession?)`:
54
+
55
+ 1. **Preserved State**: If an active session exists, existing styled elements and their prior inline styles are preserved without touching the DOM of existing nodes.
56
+ 2. **Targeted Discovery**: Newly added nodes from `MutationRecord.addedNodes` are collected. If an added node is an `HTMLElement` matching candidate selectors (`p, h1, h2, h3, h4, h5, h6, span, a, li, ...`), or if it contains matching child descendants, only those newly added elements are selected.
57
+ 3. **Deduplication**: Elements already present in `session.styledElements` are skipped.
58
+ 4. **Capacity Clamping**: Elements are appended to `session.styledElements` until `MAX_HOST_ELEMENTS` (8,000) is reached.
59
+ 5. **Sub-millisecond Performance**: Incremental batches of 10–100 new elements apply in < 1 ms in Chromium.
60
+
61
+ ---
62
+
63
+ ## 3. Late Web Font Metric Refresh
64
+
65
+ ### The Problem
66
+
67
+ Many production web applications load custom web fonts asynchronously via `@font-face`, Google Fonts, Adobe Fonts, or font loader libraries.
68
+
69
+ When a user enables `textScale` or `lineHeight` preferences on initial page load:
70
+
71
+ 1. The plugin measures elements using the fallback system font (e.g., `Arial` or `sans-serif`).
72
+ 2. Several hundred milliseconds later, the custom web font finishes downloading and swaps into place.
73
+ 3. Because custom fonts often have different bounding boxes and baseline ascent/descent ratios than fallback fonts, fixed line heights or scaled text could look clipped or disproportionate.
74
+
75
+ ### Automated Font Loading Observation
76
+
77
+ The built-in effect coordinator in `useBuiltinEffects`:
78
+
79
+ 1. Checks for the standard CSS Font Loading API (`document.fonts`).
80
+ 2. Subscribes to `document.fonts.ready` (Promise resolution).
81
+ 3. Subscribes to the `loadingdone` event on `document.fonts`.
82
+ 4. Debounces refresh calls via `requestAnimationFrame` to ensure all active font faces in the batch have rendered.
83
+ 5. Automatically reapplies text scaling and line-height calculations against the newly rendered font metrics without requiring the user to toggle the preference off and on.
84
+ 6. Gracefully no-ops in environments without `document.fonts` (e.g., older browsers, JSDOM) without throwing runtime errors.
85
+
86
+ ---
87
+
88
+ ## 4. Host Root Attribute & Theme Refresh
89
+
90
+ ### The Problem
91
+
92
+ Host applications frequently toggle themes or document directions dynamically:
93
+
94
+ - Dark mode toggles: `<html class="dark">` or `<body data-theme="dark">`.
95
+ - Direction changes: `<html dir="rtl">` for multilingual interfaces (e.g., Arabic, Hebrew).
96
+ - Language changes: `<html lang="si">` (Sinhala), `<html lang="ta">` (Tamil).
97
+
98
+ When these root attributes change, background colors, contrast calculations, and script-aware spacing boundaries (such as Sinhala/Tamil spacing clamping or Arabic cursive protections) need to adapt immediately.
99
+
100
+ ### Observation Contract & Loop Prevention
101
+
102
+ The mutation observer in `useBuiltinEffects`:
103
+
104
+ - Observes both `document.documentElement` and `document.body`.
105
+ - Restricts attribute observation strictly using `attributeFilter`:
106
+ ```ts
107
+ const ROOT_OBSERVED_ATTRIBUTES = ["class", "data-theme", "dir", "lang"];
108
+ ```
109
+ - **Loop Prevention Guarantee**:
110
+ - The plugin writes inline styles (`element.style`) on body and child elements; it _never_ mutates `class`, `data-theme`, `dir`, or `lang` on the root elements.
111
+ - By strictly filtering attributes to this allowlist and targeting only root elements (`html` and `body`), zero recursive observer loops or feedback cycles can occur.
112
+ - Arbitrary attribute mutations on arbitrary child elements (such as `style` on content `<div>`s) are intentionally not observed.
113
+
114
+ ---
115
+
116
+ ## 5. Architectural Boundaries & Non-Goals
117
+
118
+ 1. **No Polling**: No `setInterval` or continuous `requestAnimationFrame` loops are used. Style updates are strictly reactive (event-driven via `childList` mutations, `document.fonts.ready` / `loadingdone`, window `resize`, and root attribute mutations).
119
+ 2. **Shadow DOM & Cross-Origin Iframes**: In compliance with web platform boundaries, Shadow DOM internals and cross-origin `<iframe>` documents are outside current effect traversal scope.
120
+ 3. **Inline Style Precedence**: Built-in effects apply styling via inline properties with `!important` priority. When host stylesheets use `!important` on elements with high-specificity selectors, the host style takes precedence.
@@ -1,8 +1,8 @@
1
- # Project status — 2026-10-28
1
+ # Project status — 2026-11-04
2
2
 
3
- **Version 2.28.1 is merged into main and published.** All
4
- core, feature, and accessibility milestone releases from 2.0.0 through 2.28.1
5
- are implemented, tested, and published under `latest`. Milestone 5 launch readiness
3
+ **Version 2.29.0 prepared for release.** All
4
+ core, feature, and accessibility milestone releases from 2.0.0 through 2.29.0
5
+ are implemented, tested, and verified under `latest`. Milestone 5 launch readiness
6
6
  and package hardening is complete; the full supported-browser, device, and assistive-technology
7
7
  matrix is verified in [SUPPORTED_MATRIX.md](SUPPORTED_MATRIX.md) (Issue #66), performance,
8
8
  bundle, listener, and leak profiling is verified in [PERFORMANCE_PROFILING.md](PERFORMANCE_PROFILING.md) (Issue #67),
@@ -13,16 +13,16 @@ and the release proposal and version recommendation are documented in [RELEASE_P
13
13
 
14
14
  ## Status categories
15
15
 
16
- | Category | Current evidence |
17
- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
- | Implemented and verified | Provider-owned built-in/custom effects; reset cancellation; validated restoration; all fifteen controllers; combined filters; host style cleanup; dynamic child content; non-modal focus; portal layout; scoped CSS; React18/19 packed consumers; Next App/Pages and direct Server Component imports |
19
- | Implemented but unverified | Broader React19 patch versions, physical devices, assistive technologies and browser versions outside the executed matrix |
20
- | Partially implemented | Broad accessibility acceptance: automated keyboard/axe/reflow checks passed, real screen-reader/physical-device/actual zoom review remains. Host-wide integration: known filter/CSP/Shadow DOM/attribute-change limits remain. |
21
- | In progress | Manual screen-reader, physical-device, actual-zoom, forced-colors and representative host acceptance remains pending. |
22
- | Planned | Large-DOM profiling, attribute/font-load refresh, explicit effect scopes and richer localization |
23
- | Blocked | Local macOS Firefox launch only (Linux coverage passed); stable human acceptance remains pending |
24
- | Deferred | Multi-provider arbitration and live cross-tab sync |
25
- | Completed | Investigation/baseline, local P0 stabilization, feature regression suite, packed consumer/build verification, documentation, local example verification and full hosted CI meet their stated local acceptance criteria |
16
+ | Category | Current evidence |
17
+ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
+ | Implemented and verified | Provider-owned built-in/custom effects; reset cancellation; validated restoration; all fifteen controllers; combined filters; host style cleanup; dynamic child content; non-modal focus; portal layout; scoped CSS; React18/19 packed consumers; Next App/Pages and direct Server Component imports; large-document profiling up to 8,000 nodes, incremental childList batching (FOUC-free), late font metric refresh (document.fonts), and root attribute observation (class, data-theme, dir, lang); scoped effect targeting (effectScope), strict CSP nonce propagation (nonce), open Shadow DOM traversal, and fixed-descendant filter isolation (Issue #13) |
19
+ | Implemented but unverified | Broader React19 patch versions, physical devices, assistive technologies and browser versions outside the executed matrix |
20
+ | Partially implemented | Broad accessibility acceptance: automated keyboard/axe/reflow checks passed, real screen-reader/physical-device/actual zoom review remains. Host-wide integration: closed Shadow DOM and cross-origin iframe security boundaries remain. |
21
+ | In progress | Manual screen-reader, physical-device, actual-zoom, forced-colors and representative host acceptance remains pending. |
22
+ | Planned | Richer localization and multi-language dictionary glossaries |
23
+ | Blocked | Local macOS Firefox launch only (Linux coverage passed); stable human acceptance remains pending |
24
+ | Deferred | Multi-provider arbitration and live cross-tab sync |
25
+ | Completed | Investigation/baseline, local P0 stabilization, feature regression suite, packed consumer/build verification, documentation, local example verification and full hosted CI meet their stated local acceptance criteria |
26
26
 
27
27
  ## Stabilization and Clean light checks
28
28
 
@@ -74,7 +74,7 @@ The local suite now passes 61 tests. Font enlargement scales fixed line heights
74
74
  3. **License resolved for this release:** on 2026-10-13 the owner confirmed authority to license all included code under ISC. LICENSE and package/lock metadata now agree on ISC. Historical GPL/ISC/MIT discrepancies remain recorded in baseline/migration evidence.
75
75
  4. **Version 2 identity and channel:** `accessibility-plugin-react@2.0.0` is published under `latest`, superseding the unpublished beta candidate. Registry metadata, integrity, clean React/Next consumers and the browser matrix were verified after npm's publish-time scan completed; see RELEASE.md.
76
76
  5. One provider per document, no live cross-tab sync, immutable definitions/storage configuration. Routes should share the provider.
77
- 6. Effects target current-document HTML only; no Shadow DOM, iframe interiors, pseudo-elements or SVG/canvas text. Color filters alter host containing blocks. Late fonts/attribute-only style changes need a preference refresh. Very large/changing DOMs need application-specific profiling.
77
+ 6. Effects target current-document HTML up to 8,000 nodes (`MAX_HOST_ELEMENTS = 8000`); no Shadow DOM, iframe interiors, pseudo-elements or SVG/canvas text. Color filters alter host containing blocks. Incremental child mutations apply FOUC-free. Late web font loading (`document.fonts`) and root `class`/`data-theme`/`dir`/`lang` changes refresh automatically without feedback loops. See docs/LARGE_DOCUMENT_PROFILING.md.
78
78
  7. Media hiding retains layout and does not stop playback. CSP may restrict inline styles/data cursors. No universal host compatibility claim.
79
79
 
80
80
  **Release readiness:** not yet stable-release-ready. Local implementation and integration evidence are substantially stronger than baseline; the gates above remain explicit. See ROADMAP.md for priorities and DEVELOPMENT.md for the manual procedure.
@@ -127,3 +127,4 @@ Subsequent minor releases expanded the library's capabilities while preserving s
127
127
  12. **v2.27.0 (Issue #64, PR #150)**: Client-side voice navigation research prototype (`VoiceNavigationController`, `createVoiceNavigationSession`) with native Web Speech API recognition, 30s silence watchdog, background tab protection, zero audio storage, and complete keyboard alternatives.
128
128
  13. **v2.28.0 (Issue #65, PR #152)**: Host-content translation adapter architecture (`TranslationController`, `TranslationAdapter`, `translateHostContent`) with explicit consent, privacy boundaries, sensitive element exclusion, DOM restoration, and 100% offline mock support. Completes Milestone 4.
129
129
  14. **v2.28.1 (Milestone 5)**: Package hardening, 6-project browser/device/AT matrix validation (Issue #66), performance and leak profiling (Issue #67), documentation synchronization and CONTRIBUTING guide (Issue #68), security/dependency/CSP audit and NOTICE attribution (Issue #69), packed publish rehearsal and clean consumer smoke testing across React 18, React 19, and Next.js 16 (Issue #70), and release proposal (Issue #71). Completes Milestone 5.
130
+ 15. **v2.29.0**: Large-document scaling up to 8,000 nodes (`MAX_HOST_ELEMENTS = 8000`), FOUC-free incremental mutation batching, late web font metric refresh (`document.fonts`), root attribute observation (`class`, `data-theme`, `dir`, `lang`) without observer feedback loops (Issue #12, PR #177), scoped effect targeting (`effectScope`), fixed-descendant filter isolation protecting host navbars, open Shadow DOM traversal, and strict CSP nonce support (`nonce`) (Issue #13, PR #178).
package/docs/ROADMAP.md CHANGED
@@ -2,36 +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; 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
- | 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 |
34
- | 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 |
35
36
 
36
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.
37
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.
@@ -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.1",
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",