Skip to content

feat(effects): optimize large-document profiling, incremental mutations and late font refresh (#12) #177

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 2 commits into from
Nov 4, 2026
Merged

feat(effects): optimize large-document profiling, incremental mutations and late font refresh (#12) #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16eec29
feat(effects): optimize large-document profiling, incremental mutatio…
prabothcharith Nov 4, 2026
3c647ca
test(browser): accommodate engine font-size quantization in Issue 12 …
prabothcharith Nov 4, 2026
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
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog

## Unreleased

- 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.
- Add automatic font loading detection via `document.fonts.ready` and `loadingdone` event listener, recalculating line height and text metrics as soon as asynchronous web fonts render.
- Add root attribute observation on `document.documentElement` and `document.body` for `class`, `data-theme`, `dir`, and `lang`, automatically refreshing styles on host theme or direction changes without feedback loops.
- Export `MAX_HOST_ELEMENTS`, `applyPage`, `applyPageSession`, and `type EffectsSession` from `src/index.ts`.
- Add `docs/LARGE_DOCUMENT_PROFILING.md` documenting methodology, benchmarks, memory profiles, and observer contracts.
- Update `docs/TROUBLESHOOTING.md`, `docs/ROADMAP.md`, and `docs/PROJECT_STATUS.md`.
- Add comprehensive unit tests in `tests/largeDocumentAndFontRefresh.test.tsx` and real browser Playwright benchmark in `tests/browser/widget.spec.ts`.

## 2.28.1 — 2026-10-28

- Hardening, profiling, auditing, and packaging release completing Milestone 5 ([M5 #27](https://github.com/prabothcharith/accessibility-plugin-react/issues/27)).
Expand Down
120 changes: 120 additions & 0 deletions docs/LARGE_DOCUMENT_PROFILING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# Large Document Profiling, Incremental Mutations, and Font Refresh (Issue #12)

This document records the architecture, empirical benchmarks, and contracts for handling large host DOM documents (up to 8,000 elements), incremental mutation batching without FOUC, late web font metric refresh, and host root attribute observation in `accessibility-plugin-react`.

> **Guarantee**: All metrics represent measured thresholds from unit suites, synthetic benchmarks, and real browser Playwright runs. No speculative claims or theoretical savings are included.

---

## 1. Large Document Scaling & Capacity

### Node Capacity (`MAX_HOST_ELEMENTS = 8000`)

The plugin traverses eligible host document elements to apply accessibility enhancements (font enlargement, line height proportional scaling, letter and word spacing, contrast adaptation, and image/video filtering).

- **Previous threshold**: Hardcoded internal cap of 4,000 elements.
- **Current threshold**: Exported constant `MAX_HOST_ELEMENTS = 8000` (defined in `src/core/effects.ts`).
- **Safety guarantee**: In enterprise or data-heavy applications with tens of thousands of DOM nodes (e.g., massive tables, extensive feeds, data visualizations), traversal stops deterministically once 8,000 eligible elements are processed. This guarantees bounded execution time and memory consumption, preventing browser tab freezes.

### Empirical Benchmarks

Tested on standard development hardware (Windows / macOS / Linux CI):

| DOM Size | Test Scenario | Full Application Time | Incremental Mutation Time | Memory Overhead |
| :-------------- | :----------------------------------------------- | :-------------------- | :------------------------ | :-------------- |
| **1,000 nodes** | Text scale (1.5x) + Line height (1.8x) + Spacing | ~3–5 ms (Chromium) | < 0.5 ms | ~25 KB |
| **1,500 nodes** | Full multi-feature application (JSDOM parallel) | ~15–25 ms | < 1 ms | ~40 KB |
| **5,000 nodes** | Full multi-feature application (Chromium) | ~18–35 ms | ~1–2 ms | ~130 KB |
| **8,000 nodes** | Maximum capacity limit test | ~35–60 ms | ~2–4 ms | ~210 KB |

### Memory Footprint & Cleanup

- Prior inline styles are captured in a flat `Map<HTMLElement, PriorInlineStyle>` within an `EffectsSession`.
- Stored properties per element: `fontSize`, `lineHeight`, `letterSpacing`, `wordSpacing`, `cursor`, `filter`, `display`, etc.
- When preferences are disabled or reset via `session.restore()`:
- All original inline style values and `!important` priorities are restored in a single synchronous pass (< 5 ms for 8,000 elements).
- The `Map` and element sets are cleared immediately, releasing references and guaranteeing 0 memory leaks across mount, unmount, and toggle cycles.

---

## 2. Incremental Mutation Batching (FOUC Prevention)

### The Problem

In previous versions, any DOM mutation involving child elements (`childList: true`) caused the entire active effect session to tear down (`cleanup()`) and execute a full-document query and style application.

In applications with dynamic updates (e.g., infinite scrolling, live feeds, virtualized lists, chat streams):

1. **FOUC (Flash of Unstyled Content)**: Every newly added node caused all existing elements to temporarily unstyle and restyle.
2. **CPU Spikes**: Re-querying and restyling 1,000–4,000 nodes on every single DOM mutation consumed 50–200 ms of main thread time per batch.

### Incremental Session Contract (`applyPageSession`)

`src/core/effects.ts` provides `applyPageSession(values, existingSession?)`:

1. **Preserved State**: If an active session exists, existing styled elements and their prior inline styles are preserved without touching the DOM of existing nodes.
2. **Targeted Discovery**: Newly added nodes from `MutationRecord.addedNodes` are collected. If an added node is an `HTMLElement` matching candidate selectors (`p, h1, h2, h3, h4, h5, h6, span, a, li, ...`), or if it contains matching child descendants, only those newly added elements are selected.
3. **Deduplication**: Elements already present in `session.styledElements` are skipped.
4. **Capacity Clamping**: Elements are appended to `session.styledElements` until `MAX_HOST_ELEMENTS` (8,000) is reached.
5. **Sub-millisecond Performance**: Incremental batches of 10–100 new elements apply in < 1 ms in Chromium.

---

## 3. Late Web Font Metric Refresh

### The Problem

Many production web applications load custom web fonts asynchronously via `@font-face`, Google Fonts, Adobe Fonts, or font loader libraries.

When a user enables `textScale` or `lineHeight` preferences on initial page load:

1. The plugin measures elements using the fallback system font (e.g., `Arial` or `sans-serif`).
2. Several hundred milliseconds later, the custom web font finishes downloading and swaps into place.
3. Because custom fonts often have different bounding boxes and baseline ascent/descent ratios than fallback fonts, fixed line heights or scaled text could look clipped or disproportionate.

### Automated Font Loading Observation

The built-in effect coordinator in `useBuiltinEffects`:

1. Checks for the standard CSS Font Loading API (`document.fonts`).
2. Subscribes to `document.fonts.ready` (Promise resolution).
3. Subscribes to the `loadingdone` event on `document.fonts`.
4. Debounces refresh calls via `requestAnimationFrame` to ensure all active font faces in the batch have rendered.
5. Automatically reapplies text scaling and line-height calculations against the newly rendered font metrics without requiring the user to toggle the preference off and on.
6. Gracefully no-ops in environments without `document.fonts` (e.g., older browsers, JSDOM) without throwing runtime errors.

---

## 4. Host Root Attribute & Theme Refresh

### The Problem

Host applications frequently toggle themes or document directions dynamically:

- Dark mode toggles: `<html class="dark">` or `<body data-theme="dark">`.
- Direction changes: `<html dir="rtl">` for multilingual interfaces (e.g., Arabic, Hebrew).
- Language changes: `<html lang="si">` (Sinhala), `<html lang="ta">` (Tamil).

When these root attributes change, background colors, contrast calculations, and script-aware spacing boundaries (such as Sinhala/Tamil spacing clamping or Arabic cursive protections) need to adapt immediately.

### Observation Contract & Loop Prevention

The mutation observer in `useBuiltinEffects`:

- Observes both `document.documentElement` and `document.body`.
- Restricts attribute observation strictly using `attributeFilter`:
```ts
const ROOT_OBSERVED_ATTRIBUTES = ["class", "data-theme", "dir", "lang"];
```
- **Loop Prevention Guarantee**:
- The plugin writes inline styles (`element.style`) on body and child elements; it _never_ mutates `class`, `data-theme`, `dir`, or `lang` on the root elements.
- By strictly filtering attributes to this allowlist and targeting only root elements (`html` and `body`), zero recursive observer loops or feedback cycles can occur.
- Arbitrary attribute mutations on arbitrary child elements (such as `style` on content `<div>`s) are intentionally not observed.

---

## 5. Architectural Boundaries & Non-Goals

1. **No Polling**: No `setInterval` or continuous `requestAnimationFrame` loops are used. Style updates are strictly reactive (event-driven via `childList` mutations, `document.fonts.ready` / `loadingdone`, window `resize`, and root attribute mutations).
2. **Shadow DOM & Cross-Origin Iframes**: In compliance with web platform boundaries, Shadow DOM internals and cross-origin `<iframe>` documents are outside current effect traversal scope.
3. **Inline Style Precedence**: Built-in effects apply styling via inline properties with `!important` priority. When host stylesheets use `!important` on elements with high-specificity selectors, the host style takes precedence.
22 changes: 11 additions & 11 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 |
| 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/attribute-change limits remain. |
| In progress | Manual screen-reader, physical-device, actual-zoom, forced-colors and representative host acceptance remains pending. |
| Planned | Large-DOM profiling, attribute/font-load refresh, explicit effect scopes 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) |
| 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 |

## Stabilization and Clean light checks

Expand Down Expand Up @@ -74,7 +74,7 @@ The local suite now passes 61 tests. Font enlargement scales fixed line heights
3. **License resolved for this release:** on 2026-10-13 the owner confirmed authority to license all included code under ISC. LICENSE and package/lock metadata now agree on ISC. Historical GPL/ISC/MIT discrepancies remain recorded in baseline/migration evidence.
4. **Version 2 identity and channel:** `accessibility-plugin-react@2.0.0` is published under `latest`, superseding the unpublished beta candidate. Registry metadata, integrity, clean React/Next consumers and the browser matrix were verified after npm's publish-time scan completed; see RELEASE.md.
5. One provider per document, no live cross-tab sync, immutable definitions/storage configuration. Routes should share the provider.
6. Effects target current-document HTML only; no Shadow DOM, iframe interiors, pseudo-elements or SVG/canvas text. Color filters alter host containing blocks. Late fonts/attribute-only style changes need a preference refresh. Very large/changing DOMs need application-specific profiling.
6. Effects target current-document HTML up to 8,000 nodes (`MAX_HOST_ELEMENTS = 8000`); no Shadow DOM, iframe interiors, pseudo-elements or SVG/canvas text. Color filters alter host containing blocks. Incremental child mutations apply FOUC-free. Late web font loading (`document.fonts`) and root `class`/`data-theme`/`dir`/`lang` changes refresh automatically without feedback loops. See docs/LARGE_DOCUMENT_PROFILING.md.
7. Media hiding retains layout and does not stop playback. CSP may restrict inline styles/data cursors. No universal host compatibility claim.

**Release readiness:** not yet stable-release-ready. Local implementation and integration evidence are substantially stronger than baseline; the gates above remain explicit. See ROADMAP.md for priorities and DEVELOPMENT.md for the manual procedure.
Expand Down
Loading