accessibility-plugin-react 1.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,43 @@
1
+ # Architecture
2
+
3
+ ## Ownership and lifecycle
4
+
5
+ `AccessibilityPlugin` owns a generic preference store, feature definitions, effect coordination and panel state. `useAccessibility<T>(key, defaultValue, options?)` registers a definition after commit and returns shared state. Registration is immediately visible to subsequent mount effects, so custom controls may synchronize their state there. Registration survives control unmount until the provider is removed; changing routes or hiding UI therefore does not clear a selected preference. Omit a controller from the initial composition to omit that feature. A stored built-in value has no effect until its key is registered. To intentionally remove an already registered preference, reset it before removing its control or remount the provider with an appropriate storage key.
6
+
7
+ `AccessibilityButton` and `AccessibilityList` render portals under `document.body`. Their roots have no fixed dimensions; only visible trigger/panel boxes receive pointer events. Application content remains in normal flow, whether it is a provider child or sibling. `hidden` removes closed panel controls from display and accessibility navigation while keeping their React lifecycles alive. No application content is moved into the floating container.
8
+
9
+ The panel uses disclosure-style `aria-expanded`/`aria-controls` on the trigger and a named non-modal region. Opening focuses the region, closing restores focus. It neither traps focus nor makes the page inert. This supports adjusting and immediately trying preferences. See [WAI disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/). The historical modal requirement was deliberately replaced because the application stays interactive.
10
+
11
+ ## Preference store
12
+
13
+ `preferenceStore.ts` uses `useSyncExternalStore` with a stable empty server snapshot and cached client snapshot. SSR does not access DOM or storage; hydration attaches to the same initial markup and then restores preferences. A brief default-state paint is possible and is not described as flash-free.
14
+
15
+ State is a JSON-compatible key/value record. `featureSchema.ts` checks built-in bounds, enums and booleans. Custom primitives receive type validation; structured values should supply a validator. Reserved prototype keys are rejected. Version 1 storage is `{ version: 1, features: {...} }`; the old unversioned record is readable, unknown envelope versions and invalid root shapes are ignored. Individual invalid values fall back to defaults without crashing effects.
16
+
17
+ Each provider owns its own 200ms trailing writer. An update replaces its pending snapshot; reset cancels it and removes the key immediately. `pagehide` and provider teardown flush pending user changes. Storage exceptions are swallowed because preferences must work without persistent storage. No cross-tab synchronization; last actual write wins across tabs. No telemetry, network calls, cookies or server-held preferences.
18
+
19
+ Persistence key and enabled state are immutable for a mounted provider; remount with `key` when changing them. One provider per document is explicitly enforced by a WeakMap ownership check. This avoids inconsistent global effect arbitration. Strict Mode setup/cleanup is supported. Separate browser documents may each have a provider.
20
+
21
+ ## Effect engine
22
+
23
+ Controllers render UI only. The provider computes registered built-in values and calls `useBuiltinEffects`; custom `apply` callbacks run in provider-owned `CustomEffect` children.
24
+
25
+ Built-in effects snapshot only properties they write, including inline priority. Disabling/reset/unmount restores those properties; if the host has since written a different value, cleanup leaves that host change alone. Do not have host code and custom features continuously compete for the same CSS property.
26
+
27
+ Text sizing measures all eligible HTML elements before writing. Font size scales computed pixels and their measured line heights together to prevent fixed-pixel lines from overlapping; the line-height setting additionally scales computed line height (normal uses a 1.2× font-size approximation). This handles explicit pixel fonts as well as rem and em layouts without nested multiplication. Letter spacing and alignment override eligible descendants. Detached nodes are restored and released on the next mutation refresh. The observer watches child-list changes and batches each delivered mutation batch; resize also recalculates. Attribute-only theme/style changes and late-loaded font metrics are limitations: toggle the relevant preference to refresh. Shadow roots and iframe documents are outside scope.
28
+
29
+ Color filters compose in the order **host filter → contrast → saturation → invert → grayscale**. Numeric contrast and named palettes share one setting. Grayscale logically removes saturation color differences, but saturation remains selected and resumes when grayscale is disabled. Filter only body child content roots, excluding widget/reading-aid nodes. Transparent roots receive a reversible background from the body's computed background (white fallback) so inversion includes the surface. Filtering creates CSS stacking contexts and containing blocks inside host roots; fixed descendants may need application-specific integration.
30
+
31
+ Reading aids are separate pointer-transparent, aria-hidden overlays, lower than the widget. Pointer movement and focused host elements move them; no motion transitions. Media hiding uses visibility to retain geometry; video hiding does not pause playback or mute sound.
32
+
33
+ ## Decisions retained and changed
34
+
35
+ Retain compound JSX composition, all named controllers, generic hook, npm, TypeScript, tsup, React peers, static CSS. Add optional provider-owned custom effects without breaking the two-argument hook.
36
+
37
+ Replace controller-owned mutations and shared debounce; these failed lifecycle guarantees. Remove Tailwind build/reset machinery: authored CSS uses no utility generation, so a scoped static copy is simpler and avoids leaking preflight into consumers. Preserve the historical CSS source filename to keep history understandable. No runtime dependencies beyond React peers. Preserve both CSS export paths.
38
+
39
+ The selected branch is already a different API/package identity from `development`; do not claim old `tools`/`trigger` APIs remain compatible. See migration notes. Movement uses pointer capture with an activation threshold, normalized persisted coordinates and explicit keyboard/click alternatives. The panel has a fixed header/action area and a separate scrollable tools region. ResetController portals its button to the action host through an internal context; its public composition and provider reset contract remain.
40
+
41
+ ## Placement ownership
42
+
43
+ The provider validates and stores widget placement in its existing preference store under a reserved internal key. Display reset preserves that key, while position reset removes it. Preview coordinates are local to the trigger during a drag; only a completed drag saves them. Pointer cancellation/lost capture discard the preview. Viewport and trigger-size observers keep geometry bounded without writing new coordinates during resize. Persist=false applies to both placement and display state. Panel open state remains transient.
@@ -0,0 +1,48 @@
1
+ # Investigation baseline — 2026-10-12
2
+
3
+ Working branch: `codex/stabilize-accessibility`, based on `origin/new-development` at `6dfbd44`. Initial checkout was clean `development` at `7aef17c`. Remote refs fetched before selection.
4
+
5
+ ## History and foundation
6
+
7
+ - `main` (`4aedffc`): only .gitignore. Not an implementation foundation.
8
+ - `development` (`7aef17c`): monolithic provider with seven tools, Motion dragging, color palettes, Vite distribution. PR #1 merged 2025-12-03 repairs CSS, declarations and changes children to application content. Its claims are historical, not current verification.
9
+ - `new-development`: September 2026 commits introduce generic state, compound composition, fifteen controllers, tsup and tests. Strongest match to requested architecture, but effect ownership and packaging are defective.
10
+ - GitHub issues endpoint returned only merged PR #1, no separate issues. No tags or CI in selected branch. Read PR body and merged diff, specification, commit summary, examples, source, configuration and tests.
11
+ - Original `accessibility-plugin` cloned read-only into `/tmp/accessibility-vanilla-reference`. Its GPL-3.0 LICENSE agrees with selected branch metadata/specification. Both original package.json and older React declare ISC despite the original GPL license file; retain selected GPL declaration and original license text, require owner review before release, do not silently relicense.
12
+
13
+ ## Executed baseline
14
+
15
+ Node 22.14.0, npm 11.21.0, macOS. `npm ci`: success, 332 packages; audit 15 development dependency vulnerabilities (5 moderate, 8 high, 2 critical). `npm run typecheck`: pass. `npm run lint`: FAIL, seven unused identifiers. `npm test`: reports 24 passing, but three storage assertions are unawaited timer callbacks. `npm run build`: pass with warnings that use-client directives were removed; confirmed dist/index.mjs starts with import. `npm pack --dry-run`: 9 files, CSS and declarations present, LICENSE absent.
16
+
17
+ ## Findings and priorities
18
+
19
+ | Priority | Finding | Evidence |
20
+ | -------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
21
+ | P0 | Closing panel removes selected effects; restoration waits for opening | AccessibilityList returns null; controller unmount cleanups |
22
+ | P0 | Filters erase each other | applyFilter/clearFilter overwrite root filter in four controllers |
23
+ | P0 | Invisible fixed widget intercepts host interaction | provider full-height 380px region, unused panelStyle |
24
+ | P0 | Shared debounce and reset can resurrect settings | storage.ts module timer; clearState does not cancel |
25
+ | P0 | Next client boundary stripped from built distribution | build warning and inspected first line |
26
+ | P1 | Invalid storage unvalidated; restoration/save race | loadState accepts JSON arrays/primitives; provider mount saves empty state |
27
+ | P1 | False modal semantics and incomplete focus handling | aria-modal without inert background; disabled controls included in trap |
28
+ | P1 | Global CSS reset leaks; widget inherits root filters | @tailwind base; effects target html |
29
+ | P1 | Toggle buttons unnamed; empty default trigger | labels unassociated; required icon |
30
+ | P1 | Reading mask covers reading area instead of exposing it | dark 80px strip at pointer |
31
+ | P1 | Host inline styles destroyed on disable/unmount | removeProperty instead of restoration |
32
+ | P1 | Generic custom examples do not restore/reset DOM effects | direct mutations inside onClick |
33
+ | P1 | Dynamic content, Strict Mode, hydration, mobile, package consumers untested | tests only source imports/jsdom |
34
+ | P1 | Incorrect repo metadata, unbounded peers, absent license file | package.json |
35
+ | P2 | Link palette variants and reduced contrast lost; left alignment cannot override host | original styles vs controllers |
36
+ | P2 | Dependency security/maintenance debt | npm audit; ESLint 8 deprecated |
37
+ | P2 | Historical claims inaccurate | COMMIT_SUMMARY claims outside click and SSR safety without implementation evidence |
38
+
39
+ Confirmed building blocks: generic state hook, controller composition, native stepper/segment buttons, dual JS/declaration output. Partially implemented: all effects, persistence, focus, position styling. Missing: persistent engine, browser tests, CI, packaged consumer verification, release documentation. Legacy drag is intentionally evaluated after core correctness.
40
+
41
+ ## Implementation sequence
42
+
43
+ 1. Provider-owned effects, schema validation, isolated persistence and deterministic single-document ownership.
44
+ 2. Repair built-ins and custom effect contract; restore useful original variants.
45
+ 3. Non-modal panel, portal isolation, responsive scoped CSS and keyboard/focus behavior.
46
+ 4. Validate packed ESM/CJS/types/CSS, React 18/19, SSR/hydration, Vite and Next consumers.
47
+ 5. Regression/browser/axe checks and CI.
48
+ 6. Accurate documentation, migration, release checklist and handover; no publishing or merge.
@@ -0,0 +1,101 @@
1
+ # Custom feature development
2
+
3
+ A consumer can implement a normal React component in its own application and place it beside built-in controllers. No private imports, fork or registration configuration is required.
4
+
5
+ ## A complete JavaScript example
6
+
7
+ ```jsx
8
+ import { useAccessibility } from "accessibility-plugin-react";
9
+
10
+ export function OutlineFeature() {
11
+ const { value, setValue } = useAccessibility("example:outline", false, {
12
+ apply(enabled) {
13
+ if (!enabled) return;
14
+ const previous = document.body.style.outline;
15
+ document.body.style.outline = "3px solid blue";
16
+ return () => {
17
+ document.body.style.outline = previous;
18
+ };
19
+ },
20
+ });
21
+ return (
22
+ <div className="arap-feature">
23
+ <button
24
+ type="button"
25
+ className="arap-segment"
26
+ aria-pressed={value}
27
+ onClick={() => setValue(!value)}
28
+ >
29
+ Page outline
30
+ </button>
31
+ </div>
32
+ );
33
+ }
34
+ ```
35
+
36
+ Include `<OutlineFeature />` inside `<AccessibilityList>`. `apply` runs on restored state without clicking the control; reset reverts to false and runs cleanup. Closing or removing the control does not remove the chosen effect. Provider unmount does. The example changes a property the built-in engine does not own.
37
+
38
+ Use a validator for nullable or union state when the default does not represent all allowed types; the hook validates restored values before mount effects can initialize defaults.
39
+
40
+ ## Structured TypeScript state
41
+
42
+ ```tsx
43
+ import {
44
+ useAccessibility,
45
+ type FeatureOptions,
46
+ } from "accessibility-plugin-react";
47
+ type Preference = { enabled: boolean; color: string };
48
+ const options: FeatureOptions<Preference> = {
49
+ validate(value): value is Preference {
50
+ if (!value || typeof value !== "object") return false;
51
+ const candidate = value as Partial<Preference>;
52
+ return (
53
+ typeof candidate.enabled === "boolean" &&
54
+ ["#164e63", "#1d4ed8"].includes(candidate.color ?? "")
55
+ );
56
+ },
57
+ apply(value) {
58
+ if (!value.enabled) return;
59
+ const previous = document.body.style.outline;
60
+ document.body.style.outline = `3px solid ${value.color}`;
61
+ return () => {
62
+ document.body.style.outline = previous;
63
+ };
64
+ },
65
+ };
66
+ export function CustomOutline() {
67
+ const { value, setValue, reset } = useAccessibility<Preference>(
68
+ "example:custom-outline",
69
+ { enabled: false, color: "#164e63" },
70
+ options,
71
+ );
72
+ return (
73
+ <div className="arap-feature">
74
+ <button
75
+ type="button"
76
+ aria-pressed={value.enabled}
77
+ onClick={() => setValue({ ...value, enabled: !value.enabled })}
78
+ >
79
+ Outline
80
+ </button>
81
+ <button type="button" onClick={reset}>
82
+ Reset outline
83
+ </button>
84
+ </div>
85
+ );
86
+ }
87
+ ```
88
+
89
+ ## Contract
90
+
91
+ - Use stable namespaced keys and JSON-compatible defaults. Built-in keys are reserved. First definition wins; keep definitions/defaults stable and avoid prop-dependent captured callbacks. Remount the provider when changing the definition itself.
92
+ - `apply` may return cleanup. Cleanup runs before reapplying a changed value and on provider removal. It must restore every owned DOM property/listener/node, be idempotent under Strict Mode and not undo unrelated host updates.
93
+ - The provider applies default values too; default effects should usually do nothing. Never use an event handler as the only place that applies DOM changes.
94
+ - If a custom effect needs dynamic route targets, attach a correctly cleaned observer/listener or apply to a stable application root. Provider ownership does not automatically rerun arbitrary custom callbacks when unrelated DOM changes.
95
+ - Avoid writing `filter` on html/body or properties already owned by built-ins. There is no public custom filter-composition API; use a separate target or an independent feature rather than racing the built-in engine.
96
+ - Custom code is trusted application code: validators are not a security sandbox, and thrown apply errors propagate to the app's React error boundary. No HTML strings from persisted values should be inserted.
97
+ - Use native named buttons, `aria-pressed` for toggles, grouped labels for segments, visible focus and understandable values. Decorative icons should be hidden from assistive technology.
98
+
99
+ The original two-argument hook still works with ordinary React effects. Such effects stay active when the built-in list is hidden because its children remain mounted, but they end when the custom control actually unmounts. Prefer the third argument when effects must survive actual control removal.
100
+
101
+ See `examples/custom-feature/main.tsx`, unit custom lifecycle tests and the packed browser fixture for executable examples.
package/docs/DESIGN.md ADDED
@@ -0,0 +1,39 @@
1
+ # Clean light design foundation
2
+
3
+ The owner selected the Clean light concept on 2026-10-13. It establishes the default appearance for future widget work: white surfaces, ink text, restrained blue accents, clear spacing, subtle dividers and consistent outline icons.
4
+
5
+ ## Principles implemented
6
+
7
+ - 400px maximum panel width, rounded border and soft shadow. The panel fits narrow screens, safe areas and existing four placements.
8
+ - Strong heading with optional supporting description; the close control keeps its accessible name and 44px target.
9
+ - Compact label/value rows on desktop. Steppers stack below labels on small screens so neither labels nor targets are squeezed.
10
+ - Cohesive decorative SVG icons. Existing names and native controls remain the semantic interface.
11
+ - Segmented controls use explicit checks and pressed states. Toggle targets are 44px high with a smaller visual track; their selected knob also displays a check.
12
+ - A fixed blue reset action, a non-drag movement menu and clear keyboard focus, with reduced-motion and forced-colors styles.
13
+ - Scoped CSS palette variables enable future themes without a styling-framework dependency or host reset. See API.md for variables and the optional panel description.
14
+
15
+ ## Reference versus implementation
16
+
17
+ The generated image is a visual reference, not a specification for reducing features. All fifteen controllers, contrast levels, link palettes and separate image/video controls remain. No nonfunctional chevrons, new nested menus or combined media preference were introduced. Consumers continue choosing tools and ordering them through JSX. The public two-argument hook, storage and effect ownership are unchanged.
18
+
19
+ Default controller names and the panel title remain compatible. The basic example opts into the shorter title “Accessibility”; the default remains “Accessibility settings”. Passing `description=""` removes the supporting text.
20
+
21
+ ## Validation
22
+
23
+ Local source/test type checking, zero-warning lint, 66 unit tests, JS/declaration/CSS build and packed React18/React19/Next consumer checks passed. Browser checks passed in Chromium (including React19/Tailwind and Next), desktop WebKit and mobile WebKit: 46 passed, four intentional Next-only skips. Narrow-layout coverage verifies no horizontal overflow and minimum 44×44px button targets in every placement. Axe reported no findings in tested light/dark widget scopes. Hosted Firefox validation is recorded in the pull request checks; local Firefox remains unavailable as documented in PROJECT_STATUS.md.
24
+
25
+ The consumer script clears disposable Next build caches before verification: repacking the same unreleased version can otherwise retain stale dependency bundles. This corrects validation, not feature behavior.
26
+
27
+ Actual built-example screenshots were captured and visually inspected at 1280×900 and 320×700. These are runtime images, not generated mockups:
28
+
29
+ ![Clean light desktop widget](assets/movable-desktop.png)
30
+
31
+ ![Clean light at 320px](assets/quick-actions-mobile.png)
32
+
33
+ Human screen-reader, physical-device, actual zoom and forced-colors acceptance still apply to this design. Automated checks do not establish WCAG certification.
34
+
35
+ ## Quick access and remembered placement
36
+
37
+ The header and footer stay fixed while tools scroll. ResetController uses the action bar even inside nested JSX; additional actions use AccessibilityList footer. The trigger supports dragging, Alt+arrow keys, click arrows and a corner picker, with persistent placement and separate placement reset. Short screens use a compact shell; the trigger temporarily hides while the panel is open so it cannot cover actions. See API.md for the full contract.
38
+
39
+ ![Movement controls on mobile](assets/position-menu.png)
@@ -0,0 +1,91 @@
1
+ # Development, quality and release
2
+
3
+ ## Clean checkout
4
+
5
+ Use Node >=22.13 and npm. The committed package-lock is the library dependency source of truth. No application environment variables or services are required.
6
+
7
+ ```sh
8
+ git switch main
9
+ git pull --ff-only origin main
10
+ git switch -c codex/your-feature
11
+ npm ci
12
+ npm run validate
13
+ npm run pack:check
14
+ npm run test:consumers
15
+ npx playwright install --with-deps chromium firefox webkit
16
+ npm run test:browser
17
+ ```
18
+
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
+
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
+
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
+
25
+ ## Directory map
26
+
27
+ ```text
28
+ src/
29
+ index.ts public exports
30
+ core/
31
+ AccessibilityPlugin.tsx ownership, definitions, composition
32
+ AccessibilityContext.ts shared context
33
+ preferenceStore.ts external snapshot, SSR/hydration and writes
34
+ storage.ts schema envelope and isolated writer
35
+ featureSchema.ts defaults and value validation
36
+ effects.ts host effects and custom effect lifetimes
37
+ useAccessibility.ts consumer hook
38
+ AccessibilityButton.tsx trigger
39
+ AccessibilityList.tsx non-modal region and focus
40
+ WidgetPortal.tsx client-only body portal boundary
41
+ widgetPlacement.ts validated placement and viewport geometry
42
+ PositionControls.tsx non-drag movement alternatives
43
+ PanelActionsContext.ts fixed-action portal host
44
+ FeatureIcon.tsx decorative control icons
45
+ types.ts public contracts
46
+ features/*Controller.tsx fifteen opt-in native controls
47
+ styles/tailwind.css scoped plain CSS (historical filename)
48
+ tests/
49
+ *.test.ts(x) regressions for effects/provider/storage
50
+ helpers.tsx, setup.ts fixtures and DOM matchers
51
+ browser/ packed consumer app, host CSS, Playwright tests
52
+ scripts/ CSS build, archive checks, clean consumer setup
53
+ examples/ basic and custom feature demos
54
+ .github/workflows/ci.yml unit/build/package and browser integration jobs
55
+ docs/ maintained architecture/API/status/guides
56
+ AGENTS.md future-agent entry point
57
+ LICENSE owner-approved ISC license text
58
+ COMMIT_SUMMARY.md historical claims; not present verification
59
+ react-accessibility-plugin-spec.md historical requirements
60
+ ```
61
+
62
+ ## Test expectations
63
+
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
+
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.
67
+
68
+ ## Manual accessibility acceptance checklist
69
+
70
+ These checks require a human/tester; mark results and platform/version in PROJECT_STATUS.md. Use [WCAG 2.2 quick reference](https://www.w3.org/WAI/WCAG22/quickref/) and [WAI disclosure guidance](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/).
71
+
72
+ 1. Keyboard only: reach trigger, open with Enter and Space, verify focus is visibly on the panel, visit every control, exercise both stepper bounds, leave the non-modal panel with Tab, return, close using Escape/Close and confirm focus. Ensure no trap and no unexpected scrolling/focus loss when route content changes.
73
+ 2. Screen readers: VoiceOver/Safari on macOS and iOS; NVDA/Firefox or Chrome on Windows. Verify trigger name/expanded state, named region, group names, pressed states, numeric announcements, hidden panel exclusion and reset state announcements. Check verbosity with multiple outputs changing together.
74
+ 3. Browser zoom at 200% and 400% (actual browser zoom, not just resizing). Verify text, focus indicators, scroll access and control reflow. A 320px viewport test is supporting evidence, not complete zoom verification.
75
+ 4. Physical touch devices: safe areas, landscape, large system fonts, scroll inside panel without swallowing host gestures, taps on closed-widget-adjacent content. Playwright device emulation does not substitute for physical touch testing.
76
+ 5. Light/dark/custom global CSS, forced colors/high contrast, reduced motion. Check active/inactive/focus contrast and visible selection without color alone.
77
+ 6. Host integration: sticky/fixed overlays, complex forms, embedded media, route navigation, dynamically inserted content and font loading. Confirm each selected setting improves intended content without concealing important controls. Video hiding does not stop playback.
78
+ 7. Inspect reset/unmount restoration, rapid reload storage, blocked storage and corrupted saved data. Test a custom feature's restored and removed-control effects.
79
+
80
+ Automated axe results cover the tested widget DOM and criteria tags; they neither certify the host nor cover all assistive-technology behavior.
81
+
82
+ ## Release procedure (manual, owner-authorized)
83
+
84
+ 1. Resolve package identity and historical license conflict with the owner; keep evidence and update migration/license docs if an authorized decision changes anything.
85
+ 2. Complete all P1 release gates in ROADMAP.md, including real screen readers/devices/zoom, Firefox and hosted CI. No known P0 defects may remain.
86
+ 3. Choose a semantic version based on the final public contract. Do not silently reuse the unreleased 0.1.0 archive as a claimed registry release. Add dated release notes and supported/verified matrix.
87
+ 4. Run `npm ci`, `npm run validate`, `npm run test:consumers`, full Playwright matrix, `npm audit`, and inspect `npm pack --dry-run` plus actual archive. Review source maps/docs/license disclosure.
88
+ 5. Review branch diff and open a PR through the normal repository workflow. Obtain owner approval for merge, tag and npm publication separately as appropriate. Build artifacts locally are not authorization to publish.
89
+ 6. Only after explicit publication authorization: authenticate with the owner's approved npm publishing method, publish the reviewed archive/version, verify registry exports/CSS/types by clean registry installation, then create authorized release/tag with matching commit. Do not claim success until verified.
90
+
91
+ No credentials are needed for local development. Never persist secrets in preference state, fixtures or source control.
@@ -0,0 +1,49 @@
1
+ # Features and parity
2
+
3
+ All features are opt-in via controllers, use native buttons, support Enter/Space and ordinary Tab order, and expose pressed/disabled state or a polite numeric output. Defaults leave the host unchanged. Values persist once changed and return to defaults on Reset All. Effects persist when controls/panel disappear and are cleaned on provider removal. Widget portals are excluded. The engine restores prior inline properties and priorities instead of simply deleting them.
4
+
5
+ | Controller / key | Default; states and bounds | Host behavior / edge cases |
6
+ | --------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7
+ | FontSizeController / fontSize | 100; 50–200%, step 10 | Scales each computed HTML element font size and line height together. Stops at bounds; not a substitute for browser zoom. |
8
+ | LineHeightController / lineHeight | 100; 50–200%, step 10 | Scales existing computed line height, multiplied by active font scale. Normal line height uses 1.2× font approximation. |
9
+ | LetterSpacingController / letterSpacing | 0; 0–10px, step 1 | Nonzero value sets spacing on HTML descendants. Zero restores host. |
10
+ | ContrastController / contrast | 0; 0/1/2/3, reduced, yellow-on-black, white-on-black, blue-on-yellow | Off, 1.25×, 1.5×, 2×; reduced=0.5×. Named palettes set foreground/background instead of contrast filter. Palette doesn't guarantee contrast of all rendered content. |
11
+ | SaturationController / saturation | 0; 0/1/2 | Off, 0.2×, 2× saturation. Composes with other filters. |
12
+ | InvertColorsController / invertColors | false; boolean | Adds invert(1), includes content images. |
13
+ | GrayscaleController / grayscale | false; boolean | Adds grayscale(1); saturation cannot restore color while this is active. |
14
+ | LinkHighlightController / linkHighlight | false; false/true/yellow-on-black/blue-on-yellow/black-on-white | True uses dark text on pale yellow; palette buttons restore the original variants. Underlines a[href]. Toggle turns selected palette off. |
15
+ | TextAlignController / textAlign | default; default/left/center/right/justify | Default restores host; left really forces left, including in RTL content. Justification can reduce readability for some users. |
16
+ | HideImagesController / hideImages | false; boolean | Hides img/picture with visibility:hidden and removes CSS background images from HTML elements. Layout retained. SVG/canvas/pseudo-element imagery not hidden. |
17
+ | HideVideosController / hideVideos | false; boolean | Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio. |
18
+ | BigCursorController / bigCursor | false; boolean | 40px high-contrast pointer via SVG cursor with native fallback. Host CSS cursor effects are restored. No effect on touch-only hardware. |
19
+ | ReadingMaskController / readingMask | false; boolean | Transparent 100px reading window; surrounding screen dimmed. Follows pointer or host focus. |
20
+ | ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border follows pointer or host focus. Can coexist with mask. |
21
+ | ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
22
+
23
+ ## Original JavaScript and branch comparison
24
+
25
+ Reference: vanilla `47f44c5` (`accessibility-menu.js`, package 1.2.2); older React `7aef17c`; newer baseline `6dfbd44`. “Present” is source evidence, not proof of correctness. See baseline for defects.
26
+
27
+ | Original behavior | Older React | Newer baseline | Stabilized behavior |
28
+ | ------------------------------------- | --------------------------- | --------------------------------------- | --------------------------------------------------------------- |
29
+ | Invert + grayscale | Exclusive contrast enum | Independent but overwrite | Independent, composable |
30
+ | Low 20% / high 200% saturation | Exclusive modes | 50% / 200%, overwrite | Restore original 20% / 200% |
31
+ | Contrast 0.5 / 1.5 / 2 | Replaced by named palettes | 1.25 / 1.5 / 2 | Preserve newer levels, add reduced 0.5 and older palettes |
32
+ | 3 link palettes | One highlighting toggle | One toggle | Default toggle plus all 3 original palettes |
33
+ | Font size 1.3/1.5/1.8rem on html | Root scale | 50–200% on html | Fine-grained computed font scaling, including px fonts |
34
+ | Line height 1.5/1.8/2 on descendants | Root inherited value | Root percent | Scale actual computed line height across descendants |
35
+ | Letter spacing .1/.2/.3rem | em slider | 0–10px root | 0–10px descendant override |
36
+ | Left/center/right text alignment | Includes initial | Left is “off” | Explicit default plus left/center/right/justify |
37
+ | Hide img / video with display:none | Images only | Images/videos plus some embeds | Both; retain layout, restrict video embeds |
38
+ | Circle cursor enlarges on link hover | Big cursor | Static circle CSS cursor | Large contrast pointer; decorative hover enlargement replaced |
39
+ | Reading mask clear center | Guide only | Dark strip obscures center | Clear center restored |
40
+ | Quarter-width guide + triangle | Guide | Full-width line | Full-width line; native cursor retained |
41
+ | Reset classes, sizes, counters | Fixed state reset | Generic reset, stale timer | Generic reset, cancellation and effect restoration |
42
+ | Four user-selected placements, saved | Draggable trigger | Position prop, broken panel positioning | Persisted free drag, four corners, Alt+arrow and click controls |
43
+ | Save on beforeunload, unguarded parse | No localStorage persistence | Debounced but shared timer | Versioned/validated, per-owner debounce, pagehide/unmount flush |
44
+
45
+ Widget placement is now a persisted preference with pointer dragging and non-drag alternatives. The initial position prop remains a fallback. Original cursor decoration remains deferred, not counted as visual parity. Original combinations enumerated CSS selectors; centralized composition avoids that unmaintainable combinatorial model. Original click-only div controls are replaced with native named buttons.
46
+
47
+ ## Verification mapping
48
+
49
+ `tests/features.test.tsx`: stepper bounds, palettes, all alignment states, boolean effects, combined filters, native host restoration and dynamic routes. `tests/plugin.test.tsx`: custom lifecycle, restoration, invalid data, focus, Strict Mode, SSR, hydration, singleton enforcement. `tests/storage.test.ts`: deterministic timers, errors and schema envelopes. `tests/browser/widget.spec.ts`: actual compiled CSS, packed consumers, visibility, pointer interaction, geometry, keyboard and axe. See project status for executed results and manual gaps.
@@ -0,0 +1,143 @@
1
+ # Engineering handover — 2026-10-13
2
+
3
+ ## Executive summary
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, 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
+
7
+ ## Repository and baseline
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 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
+
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
+
13
+ ## Architecture and implementation
14
+
15
+ - Cached external preference store provides SSR-safe snapshots and isolated storage writer. Schema validation rejects malformed/obsolete storage, bounds invalid built-ins and protects reserved/prototype-like keys.
16
+ - Provider owns registered effects and cleanup. Validated nullable/union custom state restores before mount effects can initialize fallback values. Custom useAccessibility third argument adds apply/validate; original two-argument contract remains. Single-document ownership avoids conflicting global providers.
17
+ - Built-in engine composes host/contrast/saturation/invert/grayscale and restores prior inline styles/priorities. It responds to inserted/removed content and resize, measures text before writing, scales fixed line heights with fonts to prevent overlap, and excludes widget portals.
18
+ - Trigger/list are body portals, preventing host filters and invisible fixed wrapper hit areas. The list is non-modal with focus/return/Escape behavior and native controls. CSS is scoped, responsive, safe-area-aware and reduced-motion-friendly.
19
+ - Restored original reduced contrast/link palettes and older React color palettes. Corrected transparent reading mask. Added explicit default alignment, names, numeric announcements and default trigger icon. Historical stabilization deferred dragging and documented original visual differences; the current movement follow-up implements dragging with keyboard/click alternatives.
20
+
21
+ ## Package and compatibility
22
+
23
+ Retained tsup, ESM/CJS, React peers and named compound exports. Preserved use-client boundary in distribution; matched .d.mts/.d.ts conditional exports. Both CSS entry paths work. No runtime design-system dependencies. Replaced unnecessary Tailwind build/reset pipeline with copied authored CSS. Corrected repository URL, bounded React18/19 peers and included existing GPL text. Historical stabilization metadata was 0.1.0. The owner has now selected the existing npm identity accessibility-plugin-react; codex/npm-v2-release prepares a proposed 2.0.0-beta.1 candidate with updated imports and packed consumers. The owner approved ISC for all included code and the 2.0.0-beta.1 beta channel; npm maintainer authentication is verified; see RELEASE.md.
24
+
25
+ ## Verification and accessibility
26
+
27
+ See PROJECT_STATUS.md for the exact current matrix. The stabilization/Clean light snapshots passed source/test/config typecheck, zero-warning lint, 61 unit regressions, build, package inspection and audit. Independent packed React18.3.1 and React19.2.0/Tailwind consumers passed ESM/CJS/declarations/SSR/build. Next16.2.10 App/Pages/direct server imports passed production build and runtime checks. Corrected non-Firefox browser suite: 31 passed, four intentional Next-only skips. Axe found zero violations in tested widget scopes; real keyboard interaction and geometry were exercised. Both built examples ran with zero page errors and desktop/mobile screenshots were visually inspected.
28
+
29
+ Firefox's profile-folder launch failure is an environment blocker, not a passing check. Human screen-reader, physical-device, actual zoom and forced-colors acceptance remains pending. Hosted Node22/24 checks and packed consumer builds passed. The first full browser run had 36 passes, five intentional skips and one Firefox rounding assertion failure; the assertion was corrected and [the full rerun](https://github.com/prabothcharith/accessibility-react/actions/runs/38327577761) passed: 37 browser tests and five intentional skips, including complete Linux Firefox coverage. No WCAG compliance or universal host compatibility is claimed.
30
+
31
+ The [merged Clean light main run](https://github.com/prabothcharith/accessibility-react/actions/runs/38353340223) passed all jobs on 15e9465. Movement source d5e21df in PR #17 has local validation of 66 unit tests, packed React18/React19/Next consumers and 46 browser passes with four intentional Next-only skips. Its hosted checks must be read from PR #17; earlier green runs do not validate the movement commit.
32
+
33
+ ## Stabilization change inventory
34
+
35
+ Updated core provider/context/hook/storage/types/button/list, all controller files (ResetController formatting only), public types, CSS, package/lock, tsup/Vitest, unit tests and examples. Added preferenceStore, featureSchema, effects and WidgetPortal; packed consumer fixtures/scripts, Playwright, TypeScript test config, flat ESLint, CI and example index. Removed obsolete ESLint config, unused Tailwind config and unused unsafe DOM mutation utilities; their history remains in Git.
36
+
37
+ Created AGENTS.md, LICENSE, CHANGELOG.md and maintained docs: ARCHITECTURE, FEATURES, API, INSTALLATION, CUSTOM_FEATURES, DEVELOPMENT, TROUBLESHOOTING, PROJECT_STATUS, ROADMAP, MIGRATION, BASELINE and this HANDOVER. Added actual desktop/mobile example screenshots. README and historical document notices now direct readers to verified current guidance.
38
+
39
+ ## Remaining work and authorization
40
+
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
+
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
+
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
+
47
+ ## Historical stabilization file inventory
48
+
49
+ This inventory describes the original stabilization changes. Subsequent Clean light and movement additions are documented in DESIGN.md and their PR diffs.
50
+
51
+ ### Added
52
+
53
+ ```text
54
+ .github/workflows/ci.yml
55
+ AGENTS.md
56
+ CHANGELOG.md
57
+ LICENSE
58
+ docs/API.md
59
+ docs/ARCHITECTURE.md
60
+ docs/BASELINE.md
61
+ docs/CUSTOM_FEATURES.md
62
+ docs/DEVELOPMENT.md
63
+ docs/FEATURES.md
64
+ docs/HANDOVER.md
65
+ docs/INSTALLATION.md
66
+ docs/MIGRATION.md
67
+ docs/PROJECT_STATUS.md
68
+ docs/ROADMAP.md
69
+ docs/TROUBLESHOOTING.md
70
+ docs/assets/widget-desktop.png
71
+ docs/assets/widget-mobile.png
72
+ eslint.config.mjs
73
+ examples/index.html
74
+ playwright.config.ts
75
+ scripts/build-css.mjs
76
+ scripts/check-package.mjs
77
+ scripts/prepare-consumers.mjs
78
+ src/core/WidgetPortal.tsx
79
+ src/core/effects.ts
80
+ src/core/featureSchema.ts
81
+ src/core/preferenceStore.ts
82
+ tests/browser/Fixture.jsx
83
+ tests/browser/host.css
84
+ tests/browser/widget.spec.ts
85
+ tests/helpers.tsx
86
+ tsconfig.tests.json
87
+ ```
88
+
89
+ ### Modified
90
+
91
+ ```text
92
+ .gitignore
93
+ COMMIT_SUMMARY.md
94
+ README.md
95
+ examples/basic-usage/index.html
96
+ examples/basic-usage/main.tsx
97
+ examples/custom-feature/index.html
98
+ examples/custom-feature/main.tsx
99
+ package-lock.json
100
+ package.json
101
+ react-accessibility-plugin-spec.md
102
+ src/core/AccessibilityButton.tsx
103
+ src/core/AccessibilityContext.ts
104
+ src/core/AccessibilityList.tsx
105
+ src/core/AccessibilityPlugin.tsx
106
+ src/core/storage.ts
107
+ src/core/types.ts
108
+ src/core/useAccessibility.ts
109
+ src/features/BigCursorController.tsx
110
+ src/features/ContrastController.tsx
111
+ src/features/FontSizeController.tsx
112
+ src/features/GrayscaleController.tsx
113
+ src/features/HideImagesController.tsx
114
+ src/features/HideVideosController.tsx
115
+ src/features/InvertColorsController.tsx
116
+ src/features/LetterSpacingController.tsx
117
+ src/features/LineHeightController.tsx
118
+ src/features/LinkHighlightController.tsx
119
+ src/features/ReadingGuideController.tsx
120
+ src/features/ReadingMaskController.tsx
121
+ src/features/ResetController.tsx
122
+ src/features/SaturationController.tsx
123
+ src/features/TextAlignController.tsx
124
+ src/index.ts
125
+ src/styles/tailwind.css
126
+ tests/features.test.tsx
127
+ tests/plugin.test.tsx
128
+ tests/storage.test.ts
129
+ tsup.config.ts
130
+ vitest.config.ts
131
+ ```
132
+
133
+ ### Removed
134
+
135
+ ```text
136
+ .eslintrc.json
137
+ src/utils/dom.ts
138
+ tailwind.config.ts
139
+ ```
140
+
141
+ ## Version 2 release instruction
142
+
143
+ The owner subsequently selected accessibility-plugin-react@2.0.0 under latest, superseding the unpublished beta candidate. ISC remains approved. Publication is authorized; manual accessibility acceptance remains pending. See RELEASE.md for final archive and registry status.