accessibility-plugin-react 2.0.0 → 2.0.2

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.
@@ -0,0 +1,456 @@
1
+ # Build and release plan
2
+
3
+ This document is the execution guide for the accessibility feature-release
4
+ program. It turns the approved master plan and the GitHub issue hierarchy into
5
+ a repeatable sequence for implementation, review, validation and release.
6
+
7
+ The package is an existing product. The first responsibility of every change
8
+ is to preserve the current public contract and host-application behavior.
9
+ The feature list in the roadmap is not evidence that a capability already
10
+ exists.
11
+
12
+ ## Current baseline
13
+
14
+ The repository currently contains the v2 provider-owned architecture,
15
+ compound components, fifteen controllers, persistent preferences, widget
16
+ movement, fixed actions, scoped CSS, React 18/19 packed consumers and Next.js
17
+ consumer coverage. Consult [PROJECT_STATUS.md](./PROJECT_STATUS.md),
18
+ [ARCHITECTURE.md](./ARCHITECTURE.md) and [API.md](./API.md) before changing
19
+ behavior.
20
+
21
+ The current release track and the feature program are separate:
22
+
23
+ 1. **2.0.1 documentation patch:** validate the already-prepared package
24
+ metadata and archive, then publish only through the authorized release
25
+ procedure in [RELEASE.md](./RELEASE.md).
26
+ 2. **Feature-release program:** begin with the repository audit in M0, then
27
+ implement M1 through M5 in dependency order. Do not describe proposed
28
+ capabilities as shipped until their acceptance evidence exists.
29
+
30
+ The master tracker is
31
+ [issue #21](https://github.com/prabothcharith/accessibility-react/issues/21).
32
+ Its milestone issues are:
33
+
34
+ | Milestone | Parent issue | Purpose |
35
+ | --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |
36
+ | M0 | [#22](https://github.com/prabothcharith/accessibility-react/issues/22) | Establish repository, package and compatibility reality |
37
+ | M1 | [#23](https://github.com/prabothcharith/accessibility-react/issues/23) | Build safe core state, effects and accessible widget UI |
38
+ | M2 | [#24](https://github.com/prabothcharith/accessibility-react/issues/24) | Add stable visual and typographic preferences |
39
+ | M3 | [#25](https://github.com/prabothcharith/accessibility-react/issues/25) | Add reading support, profiles and localization |
40
+ | M4 | [#26](https://github.com/prabothcharith/accessibility-react/issues/26) | Isolate advanced, browser-dependent and experimental controls |
41
+ | M5 | [#27](https://github.com/prabothcharith/accessibility-react/issues/27) | Complete launch evidence and prepare a release proposal |
42
+
43
+ Each milestone contains the numbered A11Y child issues. Work must be tracked in
44
+ those issues rather than in an unbounded feature branch or a single large
45
+ change.
46
+
47
+ ## Issue execution checklist
48
+
49
+ Use this checklist together with the nested issue view in
50
+ [issue #21](https://github.com/prabothcharith/accessibility-react/issues/21).
51
+ Check an item only after its issue acceptance criteria and evidence have been
52
+ completed. Closing a child issue does not replace the milestone exit review.
53
+
54
+ ### Program and milestones
55
+
56
+ - [ ] [Master feature-release program #21](https://github.com/prabothcharith/accessibility-react/issues/21) — Coordinate the complete feature-release program, enforce scope and guardrails, and accept milestone evidence without treating planned work as shipped.
57
+ - [ ] [M0 — Repository audit and compatibility safety net #22](https://github.com/prabothcharith/accessibility-react/issues/22) — Establish the real repository/package baseline, protect compatibility, and finish the M0 evidence gate before feature coding.
58
+ - [ ] [M1 — Safe core, accessible widget UI and stable state #23](https://github.com/prabothcharith/accessibility-react/issues/23) — Build the typed state, storage, effects, accessible widget shell, examples and CI needed for a safe foundation.
59
+ - [ ] [M2 — Core visual and typographic adjustments #24](https://github.com/prabothcharith/accessibility-react/issues/24) — Add reversible text, spacing, font, contrast, focus, motion and decorative-image preferences with fixture evidence.
60
+ - [ ] [M3 — Reading support, profiles and localization #25](https://github.com/prabothcharith/accessibility-react/issues/25) — Add reading aids, semantic navigation, profiles, custom presets, import/export and reviewed regional localization.
61
+ - [ ] [M4 — Opt-in advanced and browser-dependent controls #26](https://github.com/prabothcharith/accessibility-react/issues/26) — Isolate TTS, dictionary, color, diagnostics, callbacks, smart contrast, voice and translation work behind safe opt-in boundaries.
62
+ - [ ] [M5 — Launch readiness and package hardening #27](https://github.com/prabothcharith/accessibility-react/issues/27) — Complete browser/AT, performance, documentation, security, licensing and packed-archive validation, then prepare a release proposal.
63
+
64
+ ### M0 — Audit and compatibility safety net
65
+
66
+ - [ ] [A11Y-000 — Repository, published package, API and license audit #28](https://github.com/prabothcharith/accessibility-react/issues/28) — Audit package metadata, published exports, dependencies, CSS/types, build, tests, CI, license, storage and security; document actual behavior in `BASELINE_AUDIT.md`.
67
+ - [ ] [A11Y-001 — Current consumer fixture and baseline screenshots #29](https://github.com/prabothcharith/accessibility-react/issues/29) — Build a clean current-API React/TypeScript consumer, verify SSR/Next support where applicable, and capture baseline screenshots and interaction evidence.
68
+ - [ ] [A11Y-002 — Regression tests for existing public behavior #30](https://github.com/prabothcharith/accessibility-react/issues/30) — Add regression tests for existing exports, props, hooks, CSS/storage contracts, reset, cleanup, Strict Mode, dynamic content and host-style preservation.
69
+ - [ ] [A11Y-003 — Technical design decision record and migration plan #31](https://github.com/prabothcharith/accessibility-react/issues/31) — Record the source-grounded architecture, compatibility matrix, migration risks, dependency graph, branch sequence and owner decisions needed for M1.
70
+
71
+ ### M1 — Safe core and accessible widget
72
+
73
+ - [ ] [A11Y-101 — Typed preferences registry and state reducer #32](https://github.com/prabothcharith/accessibility-react/issues/32) — Implement typed preference definitions, validation, defaults, stable feature IDs and reducer logic for effective settings and profile overrides.
74
+ - [ ] [A11Y-102 — Scoped effect manager and cleanup lifecycle #33](https://github.com/prabothcharith/accessibility-react/issues/33) — Implement provider-owned idempotent effect apply/dispose lifecycle with scoped styles, listener cleanup, widget exclusion and Strict Mode safety.
75
+ - [ ] [A11Y-103 — Versioned storage, reset, migration and no-storage fallback #34](https://github.com/prabothcharith/accessibility-react/issues/34) — Implement versioned `none`/session/local storage, migrations, validation, reset of owned keys, blocked-storage handling and temporary no-remember mode.
76
+ - [ ] [A11Y-104 — Accessible launcher and non-modal widget panel #35](https://github.com/prabothcharith/accessibility-react/issues/35) — Build the keyboard and screen-reader accessible non-modal launcher/panel with visible focus, Escape, focus restoration, responsive layout and stable scrolling.
77
+ - [ ] [A11Y-105 — Feature cards and state/value UI #36](https://github.com/prabothcharith/accessibility-react/issues/36) — Build reusable native feature controls for toggles, choices, sliders, search, values, statuses, errors, unsupported states and profile previews.
78
+ - [ ] [A11Y-106 — Position, oversized controls, statement link and help #37](https://github.com/prabothcharith/accessibility-react/issues/37) — Implement position and non-drag movement, oversized controls, safe-area actions, conditional statement link and help while reconciling existing positioning work.
79
+ - [ ] [A11Y-107 — Base locale infrastructure and English strings #38](https://github.com/prabothcharith/accessibility-react/issues/38) — Add typed English locale strings, configured/html-language fallback, BCP 47 and RTL handling, announcements and safe missing-key behavior.
80
+ - [ ] [A11Y-108 — Vite and Next.js App Router consumer integrations #39](https://github.com/prabothcharith/accessibility-react/issues/39) — Provide Vite and Next.js App Router consumers and verify hydration, portals, React peer versions, CSS, declarations, themes and CSP guidance.
81
+ - [ ] [A11Y-109 — CI for typecheck, lint, unit, axe and browser smoke #40](https://github.com/prabothcharith/accessibility-react/issues/40) — Establish CI for typecheck, lint, unit/integration, relevant axe checks, packed browser smoke and supported browser jobs without publication credentials.
82
+
83
+ ### M2 — Stable visual and typographic features
84
+
85
+ - [ ] [A11Y-201 — Bigger text and reflow-safe scaling #41](https://github.com/prabothcharith/accessibility-react/issues/41) — Add stepwise 1x–2x text scaling through reflow-safe scoped styles without nested compounding, clipping or changes to protected controls.
86
+ - [ ] [A11Y-202 — Letter, word, paragraph spacing and line height #42](https://github.com/prabothcharith/accessibility-react/issues/42) — Add independent letter, word and paragraph spacing plus line-height options with script-aware limits and restoration tests.
87
+ - [ ] [A11Y-203 — Text alignment, legible fonts and language fallback #43](https://github.com/prabothcharith/accessibility-react/issues/43) — Add scoped text alignment and legally distributable readable font choices with Sinhala/Tamil fallbacks while protecting icons, code and symbols.
88
+ - [ ] [A11Y-204 — Contrast modes and native forced-color protection #44](https://github.com/prabothcharith/accessibility-react/issues/44) — Add targeted original/light/dark/high/invert contrast modes that preserve host content and respect forced colors and other native settings.
89
+ - [ ] [A11Y-205 — Link highlighting and focus visibility #45](https://github.com/prabothcharith/accessibility-react/issues/45) — Add non-color-only link cues and stronger focus visibility without removing native indicators or creating unsafe skip links.
90
+ - [ ] [A11Y-206 — Reduce motion and best-effort media controls #46](https://github.com/prabothcharith/accessibility-react/issues/46) — Add reduced-motion CSS, tracked Web Animations pausing and explicit media controls while documenting GIF and cross-origin limitations.
91
+ - [ ] [A11Y-207 — Decorative image handling #47](https://github.com/prabothcharith/accessibility-react/issues/47) — Hide only eligible decorative imagery and keep functional, meaningful, CAPTCHA, chart, map and QR content available.
92
+ - [ ] [A11Y-208 — Visual regression and performance sweep #48](https://github.com/prabothcharith/accessibility-react/issues/48) — Run cross-feature visual, restoration, repeated-toggle, route, zoom, forced-color, reduced-motion and performance regression sweeps.
93
+
94
+ ### M3 — Reading support, profiles and localization
95
+
96
+ - [ ] [A11Y-301 — Cursor enlargement, reading mask and reading guide #49](https://github.com/prabothcharith/accessibility-react/issues/49) — Add capability-aware large cursor, pointer-transparent reading guide and adjustable reading mask with keyboard/touch alternatives and cleanup.
97
+ - [ ] [A11Y-302 — Accessible tooltips from authored descriptions #50](https://github.com/prabothcharith/accessibility-react/issues/50) — Show keyboard/pointer tooltips only from authored accessible descriptions, with Escape dismissal, safe positioning and no private-field disclosure.
98
+ - [ ] [A11Y-303 — Page headings and landmarks navigator #51](https://github.com/prabothcharith/accessibility-react/issues/51) — Build a read-only headings/landmarks navigator that scrolls and focuses safely, updates dynamic routes and never invents semantics.
99
+ - [ ] [A11Y-304 — Eight profiles and deterministic override model #52](https://github.com/prabothcharith/accessibility-react/issues/52) — Implement eight neutral editable profiles with previews, atomic application, explicit override layering and no implicit speech or microphone activation.
100
+ - [ ] [A11Y-305 — Custom saved presets and settings import/export #53](https://github.com/prabothcharith/accessibility-react/issues/53) — Add named custom presets and validated versioned JSON import/export that excludes personal content and handles malformed data clearly.
101
+ - [ ] [A11Y-306 — Sinhala and Tamil locale packs with accessibility review #54](https://github.com/prabothcharith/accessibility-react/issues/54) — Add reviewed Sinhala and Tamil widget locale packs and verify glyphs, long labels, search, announcements, fallback and assistive use.
102
+ - [ ] [A11Y-307 — Non-destructive reading mode proof of concept #55](https://github.com/prabothcharith/accessibility-react/issues/55) — Prototype safe article-focused reading mode without rewriting host DOM, losing content, breaking focus or sending content externally.
103
+ - [ ] [A11Y-308 — Keyboard shortcut help, remapping and link explorer #56](https://github.com/prabothcharith/accessibility-react/issues/56) — Add discoverable shortcut and heading-navigation help, collision-safe remapping and link exploration without hijacking browser or host commands.
104
+
105
+ ### M4 — Advanced and experimental controls
106
+
107
+ - [ ] [A11Y-401 — Read-aloud TTS with voice, rate and stop controls #57](https://github.com/prabothcharith/accessibility-react/issues/57) — Add user-initiated read-aloud with voice/rate/pitch/language, pause/resume/stop, sensitive-content exclusions and lifecycle cleanup.
108
+ - [ ] [A11Y-402 — Saturation and grayscale modes #58](https://github.com/prabothcharith/accessibility-react/issues/58) — Add opt-in saturation and grayscale modes with chart/image warnings, forced-color protection, browser coverage and exact reset.
109
+ - [ ] [A11Y-403 — Dictionary provider interface and local fallback #59](https://github.com/prabothcharith/accessibility-react/issues/59) — Define local and optional remote dictionary providers with explicit consent, origin/rate/sanitization rules, private-data protection and truthful unknown results.
110
+ - [ ] [A11Y-404 — Per-site feature-menu customization and reorder #60](https://github.com/prabothcharith/accessibility-react/issues/60) — Add validated feature visibility, ordering, grouping, labels and default customization while keeping close, reset and help reachable.
111
+ - [ ] [A11Y-405 — Development-only integration diagnostics and harness #61](https://github.com/prabothcharith/accessibility-react/issues/61) — Build development-only diagnostics and fixtures for supported features, effect ownership, storage, host CSS, CSP, portals, iframes and dynamic content.
112
+ - [ ] [A11Y-406 — Optional privacy-safe feature event callbacks #62](https://github.com/prabothcharith/accessibility-react/issues/62) — Add disabled-by-default local lifecycle callbacks with reviewed payloads that exclude page text, inputs, identifiers, transcripts and recordings.
113
+ - [ ] [A11Y-407 — Smart contrast research prototype #63](https://github.com/prabothcharith/accessibility-react/issues/63) — Research measured smart contrast for eligible elements with compositing, caching, unsupported reporting, performance evidence and full restoration.
114
+ - [ ] [A11Y-408 — Voice navigation research prototype #64](https://github.com/prabothcharith/accessibility-react/issues/64) — Research a small voice-command set with permission, visible listening, timeout, cleanup, privacy disclosure and keyboard alternatives.
115
+ - [ ] [A11Y-409 — Host-content translation adapter architecture #65](https://github.com/prabothcharith/accessibility-react/issues/65) — Design an explicit host-translation provider boundary with consent, origin/privacy documentation, sanitization and cross-origin limitations.
116
+
117
+ ### M5 — Launch readiness and package hardening
118
+
119
+ - [ ] [A11Y-501 — Full supported-browser, device and assistive-technology matrix #66](https://github.com/prabothcharith/accessibility-react/issues/66) — Run the full browser, device, keyboard, screen-reader, zoom, touch, forced-color, reduced-motion and representative-host acceptance matrix.
120
+ - [ ] [A11Y-502 — Performance, bundle, listener and leak profiling #67](https://github.com/prabothcharith/accessibility-react/issues/67) — Measure bundle size, runtime response, memory, listeners, observers, mount/unmount cycles, large-DOM behavior and feature-toggle jank.
121
+ - [ ] [A11Y-503 — Documentation website and interactive examples #68](https://github.com/prabothcharith/accessibility-react/issues/68) — Synchronize README, API, features, testing, privacy, limitations, migration, contributing docs and interactive packed examples.
122
+ - [ ] [A11Y-504 — Dependency, license and security audit #69](https://github.com/prabothcharith/accessibility-react/issues/69) — Audit dependencies, licenses, archive contents, CSP, unsafe rendering, external domains, privacy behavior and vulnerabilities.
123
+ - [ ] [A11Y-505 — Packed publish rehearsal and clean consumer smoke test #70](https://github.com/prabothcharith/accessibility-react/issues/70) — Inspect and install the exact tarball in clean React 18, React 19 and Next.js consumers, verifying exports, types, CSS, SSR and builds.
124
+ - [ ] [A11Y-506 — Version recommendation, changelog and owner-approved release proposal #71](https://github.com/prabothcharith/accessibility-react/issues/71) — Review evidence, recommend patch/minor/major, prepare changelog/migration/release PR and request separate owner approval for merge, tag and publication.
125
+
126
+ ### Existing release and follow-up trackers
127
+
128
+ - [ ] [Screen-reader accessibility acceptance #6](https://github.com/prabothcharith/accessibility-react/issues/6) — Complete manual screen-reader acceptance for the launcher, panel, controls, announcements, focus, reset and hidden states.
129
+ - [ ] [Physical devices, actual zoom and visual accessibility #7](https://github.com/prabothcharith/accessibility-react/issues/7) — Verify physical touch devices, safe areas, actual browser zoom, large text, responsive layout and visual accessibility modes.
130
+ - [ ] [Representative host-application acceptance #8](https://github.com/prabothcharith/accessibility-react/issues/8) — Test representative host applications with fixed overlays, forms, media, route changes, dynamic content and host CSS.
131
+ - [ ] [Final release candidate validation #10](https://github.com/prabothcharith/accessibility-react/issues/10) — Validate the final release candidate with the exact archive, full test matrix, audit, package inspection and release evidence.
132
+ - [ ] [Approved package publication and registry verification #11](https://github.com/prabothcharith/accessibility-react/issues/11) — Publish only the owner-approved archive through the authorized workflow, then verify registry metadata, integrity, tags and clean consumers.
133
+ - [ ] [Large-document profiling and late font/style refresh #12](https://github.com/prabothcharith/accessibility-react/issues/12) — Profile large documents and verify late font/style changes refresh effects without redundant work or stale computed styles.
134
+ - [ ] [Scoped effects and stronger host compatibility #13](https://github.com/prabothcharith/accessibility-react/issues/13) — Design and test explicit effect scopes, CSP behavior, fixed-descendant alternatives, Shadow DOM boundaries and iframe limitations.
135
+ - [ ] [Localization and widget positioning controls #14](https://github.com/prabothcharith/accessibility-react/issues/14) — Improve control labels/localization and optional positioning while preserving keyboard/touch parity, safe areas, zoom and hit testing.
136
+ - [ ] [First stable release tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15) — Coordinate the existing stable-release acceptance children and publish only after all release gates and owner approvals are complete.
137
+
138
+ ## Operating rules
139
+
140
+ ### Before changing code
141
+
142
+ 1. Read this document, the target issue, [PROJECT_STATUS.md](./PROJECT_STATUS.md),
143
+ [ROADMAP.md](./ROADMAP.md), [ARCHITECTURE.md](./ARCHITECTURE.md),
144
+ [API.md](./API.md) and [DEVELOPMENT.md](./DEVELOPMENT.md).
145
+ 2. Inspect the current implementation and tests for the affected behavior.
146
+ 3. Identify existing exports, storage keys, CSS contracts, effect ownership and
147
+ host properties that must remain compatible.
148
+ 4. Write a small reproducer or regression test before changing lifecycle or
149
+ effect behavior.
150
+ 5. Confirm issue dependencies are complete. Do not start a child issue whose
151
+ parent milestone or required architectural child is not ready.
152
+ 6. Create a focused branch from the current authorized base:
153
+
154
+ ```text
155
+ codex/a11y-<issue-id>-<short-name>
156
+ ```
157
+
158
+ Do not work directly on `main`, force-push, amend an existing commit, or
159
+ publish from a feature branch.
160
+
161
+ ### While implementing
162
+
163
+ - Core owns state, storage, persistence and effect lifetimes. Controllers render
164
+ controls and request state changes; they do not restore provider-owned
165
+ effects.
166
+ - Effects must be scoped, idempotent and reversible on update, disable, reset,
167
+ provider unmount and remount.
168
+ - Preserve authored host styles and priorities. Do not use broad DOM rewrites,
169
+ unsafe HTML, document-wide filters, changing every `tabindex`, or mutations
170
+ of React-owned nodes.
171
+ - Keep one provider per document. Keep widget DOM outside host filters and
172
+ application layout.
173
+ - Use native controls, visible focus, accurate names/values/pressed states,
174
+ non-modal semantics, safe-area handling, RTL support and approximately 44px
175
+ targets where practical.
176
+ - Respect browser zoom, forced colors, reduced motion, native assistive
177
+ technology, forms, CAPTCHA, charts, media, portals, Shadow DOM and
178
+ cross-origin boundaries.
179
+ - No network calls, telemetry, microphone activation, recording, transcript
180
+ storage, remote dictionary, host translation or remotely generated content
181
+ changes by default.
182
+ - Add documentation and a changelog entry for every observable public or UX
183
+ change. Add migration guidance for every changed contract.
184
+
185
+ ### Before closing a child issue
186
+
187
+ The issue comment or pull request must record:
188
+
189
+ - issue ID, branch and pull request;
190
+ - existing behavior verified;
191
+ - files and public API changed;
192
+ - unit, integration and browser tests added;
193
+ - exact commands and actual results;
194
+ - browser, zoom, keyboard and assistive-technology evidence applicable to the
195
+ change;
196
+ - reset, unmount, remount, route-change and unsupported-state behavior;
197
+ - performance, bundle, security and privacy impact;
198
+ - known limitations and environment failures;
199
+ - breaking-change status and owner decisions required next.
200
+
201
+ Do not report a test, browser, performance or accessibility result that was not
202
+ actually run.
203
+
204
+ ## Step-by-step implementation sequence
205
+
206
+ ## Step 0 — Establish a clean working baseline
207
+
208
+ Run from a clean checkout using Node `>=22.13` and npm:
209
+
210
+ ```sh
211
+ npm ci
212
+ npm run validate
213
+ npm run pack:check
214
+ npm run test:consumers
215
+ npx playwright install --with-deps chromium firefox webkit
216
+ npm run test:browser
217
+ ```
218
+
219
+ Record the exact commit, Node/npm versions, operating system, browser versions,
220
+ warnings, failures and generated artifacts. Separate unavailable environment
221
+ coverage from product failures. Do not fix unrelated baseline failures in the
222
+ same change.
223
+
224
+ ## Step 1 — Complete M0: audit and compatibility safety net
225
+
226
+ Work through [M0 #22](https://github.com/prabothcharith/accessibility-react/issues/22)
227
+ in this order:
228
+
229
+ 1. **A11Y-000, issue #28:** audit package metadata, published versions,
230
+ exports, peer dependencies, CSS/type packaging, build scripts, CI, tests,
231
+ license evidence and storage/API contracts. Produce
232
+ `docs/BASELINE_AUDIT.md`.
233
+ 2. **A11Y-001, issue #29:** build a minimal current-API React/TypeScript
234
+ consumer and verify SSR/Next behavior where advertised. Capture baseline
235
+ screenshots and keyboard, persistence, responsive and route-change results.
236
+ 3. **A11Y-002, issue #30:** add regression coverage for current exports,
237
+ props, hooks, CSS, storage, reset, restore, disable, unmount, repeated mount,
238
+ Strict Mode, dynamic content and host-style preservation.
239
+ 4. **A11Y-003, issue #31:** record the architecture decision, compatibility
240
+ matrix, migration plan, branch sequence and unresolved owner decisions.
241
+
242
+ M0 is a blocking gate. No feature implementation starts until the current
243
+ contract is known and protected by evidence.
244
+
245
+ ## Step 2 — Complete M1: safe core and accessible widget
246
+
247
+ Work through [M1 #23](https://github.com/prabothcharith/accessibility-react/issues/23).
248
+ The recommended dependency order is:
249
+
250
+ 1. **A11Y-101, issue #32:** typed preferences registry and reducer.
251
+ 2. **A11Y-102, issue #33:** provider-owned scoped effect manager and cleanup.
252
+ 3. **A11Y-103, issue #34:** versioned storage, migration, reset and
253
+ `none`/session/local persistence behavior.
254
+ 4. **A11Y-104, issue #35:** accessible launcher and non-modal panel.
255
+ 5. **A11Y-105, issue #36:** feature cards and value/state controls.
256
+ 6. **A11Y-106, issue #37:** placement, large controls, statement link and help.
257
+ 7. **A11Y-107, issue #38:** English locale infrastructure and fallback.
258
+ 8. **A11Y-108, issue #39:** Vite and Next.js consumer examples.
259
+ 9. **A11Y-109, issue #40:** CI typecheck, lint, unit, axe and browser smoke.
260
+
261
+ M1 exit requirements:
262
+
263
+ - existing public exports remain compatible;
264
+ - the widget opens and closes with keyboard and assistive technology;
265
+ - focus is visible, restored and never trapped incorrectly;
266
+ - state, storage, reset and effect cleanup are deterministic;
267
+ - examples build from the documented public API;
268
+ - automated checks are supplemented by manual review and are not described as
269
+ WCAG certification.
270
+
271
+ ## Step 3 — Complete M2: stable visual and typographic features
272
+
273
+ Work through [M2 #24](https://github.com/prabothcharith/accessibility-react/issues/24).
274
+ The independent feature branches may be parallelized after M1, but changes to
275
+ the shared schema and effect manager must be coordinated.
276
+
277
+ 1. **A11Y-201, issue #41:** bigger text with reflow-safe scaling.
278
+ 2. **A11Y-202, issue #42:** letter, word and paragraph spacing plus line height.
279
+ 3. **A11Y-203, issue #43:** alignment, legible fonts and language fallback.
280
+ 4. **A11Y-204, issue #44:** contrast modes with forced-color protection.
281
+ 5. **A11Y-205, issue #45:** link highlighting and focus visibility.
282
+ 6. **A11Y-206, issue #46:** reduce motion and best-effort media controls.
283
+ 7. **A11Y-207, issue #47:** decorative-image handling.
284
+ 8. **A11Y-208, issue #48:** visual regression and performance sweep.
285
+
286
+ Every feature must prove its supported scope, unsupported cases, restoration
287
+ of original host behavior and behavior at 200% zoom. M2 is only a release
288
+ candidate milestone; publication requires a separate owner decision.
289
+
290
+ ## Step 4 — Complete M3: reading, profiles and localization
291
+
292
+ Work through [M3 #25](https://github.com/prabothcharith/accessibility-react/issues/25).
293
+ The semantic navigator may proceed after M1; the remaining presentation work
294
+ depends on M2.
295
+
296
+ 1. **A11Y-301, issue #49:** cursor enlargement, reading mask and guide.
297
+ 2. **A11Y-302, issue #50:** tooltips from authored descriptions only.
298
+ 3. **A11Y-303, issue #51:** headings and landmarks navigator.
299
+ 4. **A11Y-304, issue #52:** eight neutral, editable profiles and deterministic
300
+ overrides.
301
+ 5. **A11Y-305, issue #53:** custom saved presets and validated import/export.
302
+ 6. **A11Y-306, issue #54:** reviewed Sinhala and Tamil locale packs.
303
+ 7. **A11Y-307, issue #55:** non-destructive reading-mode proof of concept.
304
+ 8. **A11Y-308, issue #56:** shortcut help, collision-safe remapping and link
305
+ explorer.
306
+
307
+ No profile may silently enable speech or microphone access, imply medical
308
+ efficacy, change keyboard order or undo independent user choices. Localization
309
+ must cover widget strings only; it must not become implicit host-content
310
+ translation.
311
+
312
+ ## Step 5 — Complete M4: opt-in advanced and experimental controls
313
+
314
+ Work through [M4 #26](https://github.com/prabothcharith/accessibility-react/issues/26).
315
+ These are not automatically stable release features:
316
+
317
+ 1. **A11Y-401, issue #57:** read-aloud TTS.
318
+ 2. **A11Y-402, issue #58:** saturation and grayscale.
319
+ 3. **A11Y-403, issue #59:** dictionary interface and local fallback.
320
+ 4. **A11Y-404, issue #60:** per-site feature menu customization.
321
+ 5. **A11Y-405, issue #61:** development-only diagnostics and test harness.
322
+ 6. **A11Y-406, issue #62:** privacy-safe opt-in event callbacks.
323
+ 7. **A11Y-407, issue #63:** measured smart-contrast research prototype.
324
+ 8. **A11Y-408, issue #64:** voice-navigation research prototype.
325
+ 9. **A11Y-409, issue #65:** host-content translation adapter architecture.
326
+
327
+ Each browser-dependent or privacy-sensitive feature requires an explicit
328
+ support matrix, security/privacy review, stop/disable behavior, a safe
329
+ unsupported state and an owner decision before promotion. Research prototypes
330
+ must not be presented as compliance or production support.
331
+
332
+ ## Step 6 — Complete M5: launch readiness
333
+
334
+ Work through [M5 #27](https://github.com/prabothcharith/accessibility-react/issues/27):
335
+
336
+ 1. **A11Y-501, issue #66:** complete Chromium, Firefox and WebKit, keyboard,
337
+ screen-reader, physical-device, touch, safe-area, zoom, forced-color,
338
+ reduced-motion and representative host testing.
339
+ 2. **A11Y-502, issue #67:** measure bundle, runtime, responsiveness, memory,
340
+ listeners, observers and repeated mount/unmount behavior.
341
+ 3. **A11Y-503, issue #68:** synchronize README, API, feature, testing, privacy,
342
+ limitations, migration, contributing docs and interactive examples.
343
+ 4. **A11Y-504, issue #69:** complete dependency, license, CSP, security and
344
+ privacy review.
345
+ 5. **A11Y-505, issue #70:** inspect and test the exact packed archive in clean
346
+ React 18, React 19 and Next.js consumers.
347
+ 6. **A11Y-506, issue #71:** recommend the semantic version, prepare changelog
348
+ and release proposal, and request owner approval.
349
+
350
+ The existing release tracker [#15](https://github.com/prabothcharith/accessibility-react/issues/15)
351
+ and its manual acceptance children remain authoritative for already-identified
352
+ release checks. Reuse their evidence; do not create duplicate claims.
353
+
354
+ ## Testing requirements
355
+
356
+ ### Unit and integration coverage
357
+
358
+ Each behavior change requires tests for:
359
+
360
+ - valid, invalid, boundary and unsupported values;
361
+ - apply, update, disable, reset, unmount and remount;
362
+ - React Strict Mode and repeated registration;
363
+ - storage restore, migration, corruption, blocked storage and no-storage mode;
364
+ - host styles and priorities that existed before activation;
365
+ - dynamic content, route changes and widget exclusion;
366
+ - focus, keyboard activation, accessible names and status announcements.
367
+
368
+ ### Browser coverage
369
+
370
+ Use packed consumer fixtures for browser validation. Cover forms, tables,
371
+ dashboards, long articles, media players, accordions, overlays, RTL content,
372
+ custom host CSS, late font loading and dynamically inserted content.
373
+
374
+ Automated axe checks are useful for the tested widget DOM but do not establish
375
+ host-site conformance, screen-reader behavior or legal compliance.
376
+
377
+ ### Manual acceptance
378
+
379
+ Record platform and version for:
380
+
381
+ - keyboard-only operation, focus return and absence of traps;
382
+ - NVDA with Firefox/Chrome, VoiceOver with Safari and TalkBack with Chrome
383
+ where available;
384
+ - browser zoom at 200% and 400%, not only viewport resizing;
385
+ - physical touch, landscape, safe areas and large system fonts;
386
+ - light/dark themes, forced colors, reduced motion and custom host CSS;
387
+ - sticky/fixed overlays, forms, media, route navigation and dynamic content;
388
+ - reset, unmount, reload, blocked storage and corrupted preferences.
389
+
390
+ ## Version and release procedure
391
+
392
+ ### Version decision
393
+
394
+ - **Patch:** fixes with no intentional public behavior or default change.
395
+ - **Minor:** backward-compatible capabilities or optional exports.
396
+ - **Major:** changed/deleted exports, defaults, storage semantics or CSS contract.
397
+
398
+ The version decision must be based on the audited current API, not the number
399
+ of files changed. A migration document is required for a breaking release.
400
+
401
+ ### Candidate validation
402
+
403
+ Run the smallest relevant checks during development, then the full candidate
404
+ sequence:
405
+
406
+ ```sh
407
+ npm ci
408
+ npm run validate
409
+ npm run format:check
410
+ npm run pack:check
411
+ npm run test:consumers
412
+ npx playwright install --with-deps chromium firefox webkit
413
+ npm run test:browser
414
+ npm audit
415
+ npm pack --dry-run
416
+ ```
417
+
418
+ Inspect the actual archive for package name/version, exports, ESM/CJS,
419
+ declarations, CSS, README, license and source-map policy. Install that exact
420
+ archive in clean consumer applications; source imports alone are insufficient.
421
+
422
+ ### Authorization and publication
423
+
424
+ 1. Open the release PR with the exact candidate commit and evidence.
425
+ 2. Obtain owner approval for the version, merge and release contents.
426
+ 3. Run the manual workflow in dry-run mode and inspect its archive/checksum
427
+ results.
428
+ 4. Configure and verify the approved npm trusted publisher.
429
+ 5. Only after explicit publication authorization, run the real workflow.
430
+ 6. Verify the registry version, `latest` tag, integrity, exports, CSS,
431
+ declarations and clean registry consumers.
432
+ 7. Create a Git tag or GitHub release only if separately authorized.
433
+ 8. Update [PROJECT_STATUS.md](./PROJECT_STATUS.md), [ROADMAP.md](./ROADMAP.md),
434
+ [RELEASE.md](./RELEASE.md) and [CHANGELOG.md](../CHANGELOG.md) with actual
435
+ results and remaining limitations.
436
+
437
+ Publication is never implied by a successful local build, a passing dry run,
438
+ or a prepared archive. Do not put credentials in the repository or in issue
439
+ comments.
440
+
441
+ ## Completion checklist
442
+
443
+ - [ ] The relevant issue and dependency children are complete.
444
+ - [ ] Existing public API and storage/CSS contracts were verified.
445
+ - [ ] Tests cover the feature, reset, cleanup, unsupported state and host
446
+ integration.
447
+ - [ ] Packed React and Next consumers pass.
448
+ - [ ] Browser, zoom, keyboard and applicable assistive-technology evidence is
449
+ recorded.
450
+ - [ ] Privacy, security, license and performance impact is documented.
451
+ - [ ] User-facing documentation and changelog are updated.
452
+ - [ ] Known limitations are visible and no automatic WCAG claim is made.
453
+ - [ ] The candidate version and publication actions have explicit owner
454
+ approval.
455
+ - [ ] Registry and release artifacts are verified after publication, if
456
+ publication was authorized.
@@ -18,7 +18,7 @@ npm run test:browser
18
18
 
19
19
  For a PR under review, check out its head branch instead and record the tested commit. Main contains the merged stabilization and Clean light foundation; PR #17 adds movement and fixed actions.
20
20
 
21
- `validate` runs typecheck, lint, unit tests and JS/declaration/CSS build. `test:consumers` builds, packs and installs the archive in `.consumers/react18`, `.consumers/react19` and `.consumers/next`, checks ESM/CJS and declarations/SSR, and produces application production builds. Consumers use explicitly selected framework versions; generated install locks reside in disposable `.consumers`. Network access is required for installation, not widget runtime. Browser tests start local ports 4311/4312/4313 and close their servers afterward. Avoid using these ports for unrelated processes. `CI` disables server reuse and is a test-runner environment flag, not a library setting.
21
+ `validate` runs typecheck, lint, unit tests and JS/declaration/CSS build. `test:consumers` builds, packs and installs the archive in `.consumers/react18`, `.consumers/react19` and `.consumers/next`, checks ESM/CJS and declarations/SSR, and produces application production builds. Consumers use explicitly selected framework versions; generated install locks reside in disposable `.consumers`. Network access is required for installation, not widget runtime. Browser tests start local ports 7311/7312/7313 and close their servers afterward. Avoid using these ports for unrelated processes. `CI` disables server reuse and is a test-runner environment flag, not a library setting.
22
22
 
23
23
  `npm run example` serves the two built-package examples through Vite after `npm run build`. `npm run dev` watches the library JS bundle; run build:css after editing CSS. `npm run test:watch` is useful locally. `npm pack` produces the actual package archive. Never validate only source imports and call it release-ready.
24
24
 
@@ -63,7 +63,7 @@ react-accessibility-plugin-spec.md historical requirements
63
63
 
64
64
  Write a reproducer before/alongside a lifecycle fix. Verify reset, restore, disable, provider unmount, repeated mount and Strict Mode. Check interactions with other active preferences and pre-existing host styles. Keep fake timers in storage tests; do not put unawaited assertions in timeout callbacks. Browser CSS numeric comparisons should tolerate subpixel serialization differences, not weaken functional bounds.
65
65
 
66
- CI has read-only repository permissions. It runs validation on Node 22 and 24 and packed/browser consumers on Ubuntu 24.04 using Node24-based action releases. Validation CI has no publishing privileges. A separate manually dispatched publish.yml validates and publishes an owner-selected version through npm OIDC; it defaults to dry-run, uses no npm token, and verifies registry consumers. See RELEASE.md for trusted-publisher setup and the required main-branch workflow. A workflow file is implemented but not “CI passing” until a real hosted run succeeds.
66
+ CI has read-only repository permissions. It runs validation on Node 22 and 24 and packed/browser consumers on Ubuntu 24.04 using Node24-based action releases. Validation CI has no publishing privileges. A separate `publish.yml` workflow triggers on push to `main` (when a PR is merged) to validate and publish new versions through npm OIDC (safely skipping if the version is already published), and supports manual dispatch with dry-run inspection. See RELEASE.md for trusted-publisher setup and workflow details.
67
67
 
68
68
  ## Manual accessibility acceptance checklist
69
69
 
package/docs/HANDOVER.md CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  ## Executive summary
4
4
 
5
- Stabilized the existing compound-component library rather than rebuilding from the empty default branch. All fifteen built-ins and the generic custom-feature hook remain. Effects now belong to the provider and survive closing/unmounting controls; reset/cleanup/persistence are coordinated. Built distribution has been exercised in independent React and Next applications. Stabilization and the Clean light design are merged into main. Remembered movement and fixed quick actions are in [PR #17](https://github.com/prabothcharith/accessibility-react/pull/17). Local and hosted validation are recorded for their respective snapshots; no stable release has been published or certified.
5
+ Stabilized the existing compound-component library rather than rebuilding from the empty default branch. All fifteen built-ins and the generic custom-feature hook remain. Effects now belong to the provider and survive closing/unmounting controls; reset/cleanup/persistence are coordinated. Built distribution has been exercised in independent React and Next applications. Stabilization, Clean light, remembered movement/fixed actions and the version 2 release workflow are merged into main. `accessibility-plugin-react@2.0.0` is published under `latest`; automated and registry-consumer checks do not constitute accessibility certification.
6
6
 
7
7
  ## Repository and baseline
8
8
 
9
- Repository: prabothcharith/accessibility-react. Historical stabilization branch: codex/stabilize-accessibility from origin/new-development (6dfbd44). Stabilization reached main through PR #3 at 2893b6c; Clean light reached main through PR #16 at 15e9465. Current follow-up branch: codex/movable-quick-actions, based on that merged main. Original checkout development (7aef17c) was clean. Compared main, development, new-development, merged PR #1 and vanilla plugin at 47f44c5. Read the historical specification and commit summary; their unsupported current-completion claims are now marked historical. Baseline and parity evidence are in BASELINE.md and FEATURES.md.
9
+ Repository: prabothcharith/accessibility-react. Historical stabilization branch: codex/stabilize-accessibility from origin/new-development (6dfbd44). Stabilization reached main through PR #3 at 2893b6c; Clean light reached main through PR #16 at 15e9465. Current main includes movement through PR #17 at aa72aa5 and the npm identity/ISC/version 2 workflow through PR #18 at 1d4ab1c. Original checkout development (7aef17c) was clean. Compared main, development, new-development, merged PR #1 and vanilla plugin at 47f44c5. Read the historical specification and commit summary; their unsupported current-completion claims are now marked historical. Baseline and parity evidence are in BASELINE.md and FEATURES.md.
10
10
 
11
11
  Baseline defects included controller-owned lifetime, overwriting filters, fixed invisible hit areas, shared debounce/reset races, false modal semantics, unnamed toggles, global Tailwind resets, ineffective custom DOM examples, missing shipped client directive and incorrect repository metadata. Initial lint failed seven checks; nominal 24 tests did not await three persistence assertions; audit reported 15 findings.
12
12
 
@@ -38,11 +38,11 @@ Created AGENTS.md, LICENSE, CHANGELOG.md and maintained docs: ARCHITECTURE, FEAT
38
38
 
39
39
  ## Remaining work and authorization
40
40
 
41
- P1: review PR #17 and its hosted checks; complete human accessibility and host-integration acceptance; record the approved ISC/beta decision; run final candidate validation. Then choose an approved release version and obtain tag/npm publication authorization. Track the release in [Project #18](https://github.com/users/prabothcharith/projects/18) and [release tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15). P2: profile large dynamic hosts, improve style/font-change refresh and explicit scopes, then localization/cross-tab work.
41
+ P1: complete human accessibility and representative host-integration acceptance, then decide separately whether to create a Git tag/GitHub release. npm publication and clean registry-consumer verification are complete. Track the remaining release work in [Project #18](https://github.com/users/prabothcharith/projects/18) and [release tracker #15](https://github.com/prabothcharith/accessibility-react/issues/15). P2: profile large dynamic hosts, improve style/font-change refresh and explicit scopes, then localization/cross-tab work.
42
42
 
43
43
  Current limits include one provider/document, host filter containing-block behavior, no Shadow DOM/iframe interior/pseudo-element effects, no auto-pause for hidden video and CSP considerations. These are documented implementation boundaries, not hidden workarounds.
44
44
 
45
- [PR #2](https://github.com/prabothcharith/accessibility-react/pull/2) merged into new-development and [PR #3](https://github.com/prabothcharith/accessibility-react/pull/3) merged stabilization into main. [Final stabilization validation](https://github.com/prabothcharith/accessibility-react/actions/runs/38328538388) on a020352 passed hosted Node22/24 with 61 unit tests, all packed consumers and the full browser matrix (37 passed, five intentional skips). [PR #16](https://github.com/prabothcharith/accessibility-react/pull/16) subsequently merged the Clean light foundation. PR #17 contains movement and fixed actions; it has not merged. Stable release acceptance remains open. No npm publication or release tag has occurred.
45
+ [PR #2](https://github.com/prabothcharith/accessibility-react/pull/2) merged into new-development and [PR #3](https://github.com/prabothcharith/accessibility-react/pull/3) merged stabilization into main. [Final stabilization validation](https://github.com/prabothcharith/accessibility-react/actions/runs/38328538388) on a020352 passed hosted Node22/24 with 61 unit tests, all packed consumers and the full browser matrix (37 passed, five intentional skips). [PR #16](https://github.com/prabothcharith/accessibility-react/pull/16) merged the Clean light foundation. PR #17 merged movement and fixed actions; PR #18 merged npm version 2 and the publishing workflow. Version 2 is published; human acceptance and any Git release/tag remain open.
46
46
 
47
47
  ## Historical stabilization file inventory
48
48
 
@@ -4,17 +4,21 @@
4
4
 
5
5
  Development: Node.js 22.13 or newer, npm, Git. Library peers: React/React DOM 18.3.1 or 19.x. Keep React and React DOM on the same version. There are no application environment variables, API keys, backend services or mandatory network access at runtime. Storage is optional (`persist={false}`).
6
6
 
7
- The owner selected the existing registry identity `accessibility-plugin-react`. The registry currently has 1.0.0; the owner approved 2.0.0 under the latest tag. The API changes require migration (see MIGRATION.md). For version 2, use `npm install accessibility-plugin-react@2`; plain `npm install accessibility-plugin-react` selects the registry's latest tag. For this checkout:
7
+ The package identity is `accessibility-plugin-react`. Version 2 is the current
8
+ major line and `latest` is the stable distribution tag. The API changes from
9
+ the historical 1.x package require migration (see MIGRATION.md). Install the
10
+ current release with `npm install accessibility-plugin-react`, or pin the
11
+ major line with `npm install accessibility-plugin-react@2`. For this checkout:
8
12
 
9
13
  ```sh
10
14
  npm ci
11
15
  npm run build
12
16
  npm pack
13
17
  # From an independent application:
14
- npm install /absolute/path/to/accessibility-plugin-react-2.0.0.tgz
18
+ npm install /absolute/path/to/accessibility-plugin-react-2.0.1.tgz
15
19
  ```
16
20
 
17
- Import `accessibility-plugin-react/style.css` once near the app entry. Do not add the library to a Tailwind content scan. No shadcn, icon or Motion dependency is needed. See README for complete React/Vite JSX.
21
+ Importing `accessibility-plugin-react` automatically injects its scoped CSS in browser environments. The standalone `accessibility-plugin-react/style.css` export remains available for explicit stylesheet pipelines. Do not add the library to a Tailwind content scan. No shadcn, icon or Motion dependency is needed. See README for complete React/Vite JSX.
18
22
 
19
23
  ## Next.js App Router
20
24
 
@@ -48,7 +52,6 @@ export default function Preferences() {
48
52
  ```tsx
49
53
  // app/layout.tsx
50
54
  import type { ReactNode } from "react";
51
- import "accessibility-plugin-react/style.css";
52
55
  import Preferences from "./preferences";
53
56
  export default function RootLayout({ children }: { children: ReactNode }) {
54
57
  return (
@@ -69,7 +72,6 @@ Mount the widget in the persistent root layout, not each route. Do not place doc
69
72
  ```tsx
70
73
  // pages/_app.tsx
71
74
  import type { AppProps } from "next/app";
72
- import "accessibility-plugin-react/style.css";
73
75
  import Preferences from "../components/preferences"; // same component as above
74
76
  export default function App({ Component, pageProps }: AppProps) {
75
77
  return (