From 6ddabf74d3d99044b3da5f8eca3e2903335b80bb Mon Sep 17 00:00:00 2001 From: praboth charith - GBS - CLI Date: Wed, 4 Nov 2026 10:30:08 +0530 Subject: [PATCH] feat(effects): design scoped effects, strict CSP nonces, and host compatibility (#13) --- CHANGELOG.md | 10 ++ docs/API.md | 16 ++ docs/PROJECT_STATUS.md | 20 +-- docs/ROADMAP.md | 62 ++++---- docs/SCOPED_EFFECTS.md | 129 ++++++++++++++++ src/core/AccessibilityPlugin.tsx | 8 +- src/core/effects.ts | 189 ++++++++++++++++++++--- src/core/types.ts | 13 ++ src/index.ts | 3 + tests/browser/Fixture.jsx | 3 + tests/browser/widget.spec.ts | 77 ++++++++++ tests/scopedEffects.test.tsx | 256 +++++++++++++++++++++++++++++++ 12 files changed, 723 insertions(+), 63 deletions(-) create mode 100644 docs/SCOPED_EFFECTS.md create mode 100644 tests/scopedEffects.test.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index 59532d4..d701dc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/docs/API.md b/docs/API.md index af2cd2c..a39378a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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 `