Skip to content

feat(effects): design scoped effects, strict CSP nonces, and host compatibility (#13) #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
prabothcharith merged 1 commit into from
Nov 4, 2026
Merged

feat(effects): design scoped effects, strict CSP nonces, and host compatibility (#13) #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,16 @@

## Unreleased

- Design scoped effects, strict CSP nonce support, and stronger host compatibility (closes #13).
- Add `effectScope` prop to `AccessibilityPlugin` supporting CSS selector strings, HTMLElements, or React ref objects to restrict built-in effects strictly to designated host containers.
- Apply CSS filters (grayscale, invert, saturation) directly to the scoped container, completely protecting external fixed headers, navbars, and banners from filter containing-block/stacking-context positioning issues.
- Add open Shadow DOM traversal (`mode === "open"`), allowing accessibility enhancements to reach Web Component internals.
- Add `nonce` prop to `AccessibilityPlugin` and propagate nonce attributes to dynamically injected style elements (`arap-focus-highlight-style`, `arap-reduce-motion-style`) for strict CSP compliance.
- Export `resolveEffectScope`, `type EffectScopeTarget`, and `type ApplyPageOptions` from `src/index.ts`.
- Add `docs/SCOPED_EFFECTS.md` detailing architecture, container targeting, Shadow DOM traversal, iframe boundaries, and CSP nonces.
- Update `docs/API.md`, `docs/ROADMAP.md`, and `docs/PROJECT_STATUS.md`.
- Add 11 unit and integration tests in `tests/scopedEffects.test.tsx` and real browser Playwright test in `tests/browser/widget.spec.ts`.

- Profile large documents, add incremental mutation batching, late web font metric refresh, and root attribute observation (closes #12).
- Increase eligible element capacity cap from 4,000 to 8,000 nodes (`MAX_HOST_ELEMENTS = 8000`).
- Add incremental `childList` mutation batching in `applyPageSession`, preserving existing styled nodes and styling newly added candidate subtrees without flash of unstyled content (FOUC) or full-document teardowns.
Expand Down
16 changes: 16 additions & 0 deletions docs/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,22 @@ React hook returning reactive diagnostics reports.
- Type: `(event: AccessibilityFeatureEvent) => void`
- Optional local lifecycle callback triggered on user interactions (toggles, steppers, resets, profiles, presets, panel visibility, placement). Disabled by default.

### `AccessibilityPluginProps.effectScope` (Issue #13)

- Type: `string | HTMLElement | { current: HTMLElement | null } | null`
- Optional scoped container target for built-in effects. Accepts a CSS selector string (e.g. `"#main-content"`), an HTMLElement, or a React ref object.
- Defaults to `document.body` (host-wide) when omitted.
- When specified:
- Built-in typography and display effects are restricted to the target container and its descendants.
- CSS filters (grayscale, invert, saturation) apply directly to the scoped container, protecting external fixed elements (such as host headers, navbars, and banners) from filter containing-block/stacking-context bugs.
- See [docs/SCOPED_EFFECTS.md](SCOPED_EFFECTS.md).

### `AccessibilityPluginProps.nonce` (Issue #13)

- Type: `string`
- Optional Content Security Policy (CSP) nonce attribute passed to all dynamically injected `<style>` elements (`arap-focus-highlight-style`, `arap-reduce-motion-style`).
- Enables zero CSP violations in environments with strict `style-src 'nonce-...'` directives.

### `AccessibilityFeatureEvent` Types

```ts
Expand Down
20 changes: 10 additions & 10 deletions docs/PROJECT_STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,16 @@ and the release proposal and version recommendation are documented in [RELEASE_P

## Status categories

| Category | Current evidence |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Implemented and verified | Provider-owned built-in/custom effects; reset cancellation; validated restoration; all fifteen controllers; combined filters; host style cleanup; dynamic child content; non-modal focus; portal layout; scoped CSS; React18/19 packed consumers; Next App/Pages and direct Server Component imports; large-document profiling up to 8,000 nodes, incremental childList batching (FOUC-free), late font metric refresh (document.fonts), and root attribute observation (class, data-theme, dir, lang) |
| Implemented but unverified | Broader React19 patch versions, physical devices, assistive technologies and browser versions outside the executed matrix |
| Partially implemented | Broad accessibility acceptance: automated keyboard/axe/reflow checks passed, real screen-reader/physical-device/actual zoom review remains. Host-wide integration: known filter/CSP/Shadow DOM limits remain. |
| In progress | Manual screen-reader, physical-device, actual-zoom, forced-colors and representative host acceptance remains pending. |
| Planned | Explicit effect scopes (Issue #13), CSP renderer, Shadow DOM strategy, and richer localization |
| Blocked | Local macOS Firefox launch only (Linux coverage passed); stable human acceptance remains pending |
| Deferred | Multi-provider arbitration and live cross-tab sync |
| Completed | Investigation/baseline, local P0 stabilization, feature regression suite, packed consumer/build verification, documentation, local example verification and full hosted CI meet their stated local acceptance criteria |
| Category | Current evidence |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Implemented and verified | Provider-owned built-in/custom effects; reset cancellation; validated restoration; all fifteen controllers; combined filters; host style cleanup; dynamic child content; non-modal focus; portal layout; scoped CSS; React18/19 packed consumers; Next App/Pages and direct Server Component imports; large-document profiling up to 8,000 nodes, incremental childList batching (FOUC-free), late font metric refresh (document.fonts), and root attribute observation (class, data-theme, dir, lang); scoped effect targeting (effectScope), strict CSP nonce propagation (nonce), open Shadow DOM traversal, and fixed-descendant filter isolation (Issue #13) |
| Implemented but unverified | Broader React19 patch versions, physical devices, assistive technologies and browser versions outside the executed matrix |
| Partially implemented | Broad accessibility acceptance: automated keyboard/axe/reflow checks passed, real screen-reader/physical-device/actual zoom review remains. Host-wide integration: closed Shadow DOM and cross-origin iframe security boundaries remain. |
| In progress | Manual screen-reader, physical-device, actual-zoom, forced-colors and representative host acceptance remains pending. |
| Planned | Richer localization and multi-language dictionary glossaries |
| Blocked | Local macOS Firefox launch only (Linux coverage passed); stable human acceptance remains pending |
| Deferred | Multi-provider arbitration and live cross-tab sync |
| Completed | Investigation/baseline, local P0 stabilization, feature regression suite, packed consumer/build verification, documentation, local example verification and full hosted CI meet their stated local acceptance criteria |

## Stabilization and Clean light checks

Expand Down
Loading