Darkument README

The project's README from github.com/AhmadHassan-BTed/Darkument. As one markdown file: README.md.

Darkument

A production-grade, Manifest V3 browser extension engineered for high-fidelity color inversion on PDFs and web documents.

Chrome Web Store Edge Addons Manifest V3 License: MIT


Darkument Promotional Banner

Core Purpose & Story

Bright, glaring screens pose a major challenge for late-night productivity, particularly when reading academic PDFs or reference sheets. Traditional dark mode extensions frequently break complex page layouts, consume significant CPU resources, or fail to render inside browser-embedded PDF viewer environments.

Designed and developed by Ahmad Hassan (B-Ted), Darkument offers a lightweight, high-performance solution. Built as a gift for students, researchers, and professionals working into the early hours, it converts harsh light into comfortable dark tones without altering structural CSS rules or tracking user activity.

Features

Architecture Overview

Darkument adheres to the modern Chrome Extension Manifest V3 standard, employing a decoupled background service worker and content script injection model.

flowchart TD
    subgraph Browser ["Browser Environment"]
        Action["Action Button / Badge UI"]
        Tabs["Tab Lifecycle Events"]
        DOM["Active Document DOM"]
    end

    subgraph ServiceWorker ["Service Worker (background.js)"]
        Tracker["volatile State Tracker (Map)"]
        Engine["Script Injection Handler"]
    end

    subgraph InjectedScript ["Injected Content Execution"]
        Overlay["Overlay <div> Element"]
        CSS["mix-blend-mode: difference"]
    end

    Action -->|onClicked| ServiceWorker
    Tabs -->|onUpdated / onRemoved| ServiceWorker
    ServiceWorker -->|Reads/Writes| Tracker
    ServiceWorker -->|chrome.scripting.executeScript| DOM
    DOM --> InjectedScript
    Overlay -->|GPU Blend Mode| CSS

Request Lifecycle & Data Flow

When the action button is toggled, the background script checks the volatile state map to determine the action required for the active tab.

sequenceDiagram
    autonumber
    actor User as User Action
    participant BG as Service Worker (background.js)
    participant State as volatile tabStates (Map)
    participant DOM as Active Tab DOM
    
    User->>BG: Click Extension Icon
    BG->>State: Query Tab ID State
    State-->>BG: Return Current State (Active/Inactive)
    
    alt Active (Currently Inverted)
        BG->>DOM: Execute script to fade out & remove #darkument-overlay
        BG->>State: Set Tab ID State to False
        BG->>User: Set badge to empty / Reset Icon
    else Inactive (Normal Mode)
        BG->>DOM: Execute script to create overlay & apply mix-blend-mode
        BG->>State: Set Tab ID State to True
        BG->>User: Set badge to "ON" / Set Active Icon
    end

Technical Working Mechanism

The "Difference" Strategy

Instead of parsing and modifying stylesheets, Darkument applies a Mathematical Overlay Strategy. The overlay elements are injected as direct children of the page body.

Pixel_Final = | 255 - Pixel_Original |

This negation transforms white pages to black and vice-versa, leaving medium grays and midtones relatively stable to preserve structural legibility.

PDF & Local Document Injection

Browsers render PDFs using internal HTML5 parsers (such as PDF.js). Because these documents are exposed within the standard web frame DOM, the service worker is able to inject negation overlays directly into local document frames once the user has allowed local file access.

Repository Structure

Darkument/
├── src/                  # Extension source code
│   ├── background.js     # Volatile state service worker
│   ├── manifest.json     # Manifest V3 extension configuration
│   ├── icons/            # Action and badge visual assets
│   └── pages/            # Onboarding and documentation views
│       ├── thankyou.html # Local file permissions guide
│       └── thankyou.js   # Dynamic permission listener
├── assets/               # Brand and web store promo banners
├── build/                # Production release ZIP artifacts
├── docs/                 # Architectural specifications
└── .github/              # Issue and support configurations

Installation

The extension can be installed directly from the Chrome Web Store: Download on Chrome Web Store

Microsoft Edge

The extension can be installed directly from Microsoft Edge Addons: Download on Microsoft Edge Addons

Manual Installation (Developer Mode)

  1. Download the latest source package from the Releases page.
  2. Open chrome://extensions or edge://extensions in the browser.
  3. Toggle Developer Mode on in the upper-right corner.
  4. Click Load Unpacked and select the /src directory of the project.

Development & Build Pipeline

Prerequisites

Package Configuration

Scripts are managed using the package configuration file:

Command Action Platform
npm run build Compiles the files from src/ into a release .zip archive inside build/ PowerShell
npm run clean Deletes any compiled .zip archives within the build/ folder Bash/PowerShell

Contributing

Contributions that optimize GPU rendering, expand compatibility, or enhance the accessibility features are highly valued.

  1. Fork the project.
  2. Create a feature branch (git checkout -b feature/AmazingFeature).
  3. Commit the changes (git commit -m 'feat: add some AmazingFeature').
  4. Push to the branch (git push origin feature/AmazingFeature).
  5. Open a Pull Request.

Designed and maintained by Ahmad Hassan (B-Ted)

Darkument (AhmadHassan-BTed/Darkument)

Searching Database…

754 ·GitHub
Darkument
What is this?Darkument is a browser extension that adds a native-feeling dark mode to web pages and PDFs, inverting colors to cut eye strain while keeping text and layouts intact.
Is this a Chrome extension or a system-wide dark mode tool?It's a Manifest V3 browser extension that runs inside the browser (Chrome, Edge, Opera), not an OS-level theme.
Do I need any accounts or extra software to use it?No accounts or keys are needed to use the extension; you only need Node.js if you want to build it from source yourself.
Does dark mode work on local PDF files right away?For local file:// PDFs you first need to grant the extension file-URL access in your browser's extension settings, and it currently targets Chromium-based browsers only (Chrome, Edge, Opera), not Firefox.
Does it track my browsing or document data?No, it runs entirely on-device with no network calls, trackers, or analytics.
How does the color inversion actually work under the hood?Instead of parsing and rewriting page stylesheets, it overlays a GPU-accelerated CSS blend-mode layer that mathematically negates colors, turning white into black while keeping midtones stable so layouts don't break.
If I toggle dark mode on one tab, does it change other open tabs?No, the toggle state is stored per tab in volatile memory, so inverting one document leaves every other active tab untouched.
Why build another dark mode extension instead of using an existing one?The author made it for students and researchers working late at night because typical dark mode extensions often break complex layouts, burn CPU, or simply don't work inside the browser's built-in PDF viewer.
What are similar projects?ScrollToPrompt, bilibili-digest, streamfirefly, open-sea-skin, darkreader, Youtube-Pro-Plus, ocr-it, integrity_baozi-
Which topics is it in?edge-extension, ux, dark-mode, privacy-first, chrome-extension, browser-extension, accessibility, pdf, offline, customization, browser, local-first
Creator
AhmadHassan-BTed
Size
3.2 MB
Stars
754
Updated
CommitJul 22
Age
5mo
Commits · 90 Days