How ThemeSwitcher Works: Architecture & Performance

1. The Problem with Naive Inversion

Many basic dark mode extensions rely on a simple CSS rule: filter: invert(1) hue-rotate(180deg). While this can make a white page dark quickly, it introduces major visual defects:

• Images, profile photos, and videos appear as eerie negatives.
• Contrast ratios can drop severely below WCAG accessibility thresholds.
• Shadows, borders, and UI depth cues are completely inverted.
• Modern Single Page Applications (SPAs) often glitch when navigating between views.

2. Document-Start Injection & Zero White Flashes

A common frustration with browser extensions is the dreaded "white flash" — a split second of blinding bright light while the page loads before the extension styles kick in.

ThemeSwitcher solves this by running at document_start. Before the browser paints the first pixel of the DOM, ThemeSwitcher injects core CSS custom properties onto the :root element and declares color-scheme: dark !important. The browser immediately applies dark background defaults to the canvas, rendering the initial paint in soothing dark tones.

3. Batched DOM Scanning & Layout Preservation

To style complex web applications without degrading browser performance, ThemeSwitcher enforces a strict separation of DOM read and write operations:

1. Read Pass: The engine measures computed styles (background color luminance, border colors, and text luminance) across visible elements without mutating the DOM.
2. Write Pass: Changes are applied in a single coordinated frame via requestAnimationFrame, setting data attributes like data-force-dark-surface="strong" or data-force-dark-text="true".
3. Mutation Tracking: A targeted MutationObserver observes newly added nodes and attribute changes, batching updates to prevent layout thrashing or dropped frames.

4. Saturation-Aware PDF Pixel Conversion

Standard browser PDF viewers render documents inside an internal plugin that extensions cannot easily customize without breaking graphics.

ThemeSwitcher includes a dedicated, offline Dark Document Viewer. When opened, it loads the PDF into a sandboxed HTML5 canvas using bundled PDF.js. Rather than inverting everything indiscriminately, the canvas engine executes a saturation-aware pixel algorithm:

• High-brightness, low-saturation pixels (white or near-white backgrounds) are converted to deep dark tones.
• High-saturation pixels (colored charts, graphs, diagrams, and colored text) preserve their original hue and chromatic intensity.
• Text contrast is boosted automatically to ensure maximum legibility.

5. Complete Offline Privacy

Unlike cloud-based converters, ThemeSwitcher makes zero external network requests.

• No analytics or telemetry trackers are bundled.
• Your browsing history and site URLs never leave your machine.
• Site preferences are stored using Google Chrome’s built-in chrome.storage.sync API, encrypted and synchronized through your personal Google Account.
• The source code is 100% open under the MIT License for public auditing.