Darkument README

项目的 README,来自 github.com/AhmadHassan-BTed/Darkument。合并为一个 markdown 文件: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)

正在搜索数据库…

这是什么?Darkument 是一款浏览器扩展程序,可以为网页和 PDF 添加接近原生效果的深色模式,通过反转颜色来减轻眼睛疲劳,同时保持文字和版式不变。
这是 Chrome 扩展程序,还是系统级的深色模式工具?它是一个 Manifest V3 浏览器扩展程序,运行在浏览器内部(Chrome、Edge、Opera),而不是操作系统级别的主题。
使用它需要注册账号或安装其他软件吗?使用扩展程序不需要账号或密钥;只有当你想自己从源代码构建时,才需要安装 Node.js。
本地 PDF 文件能直接使用深色模式吗?对于本地 file:// PDF,你需要先在浏览器的扩展程序设置中授予该扩展访问文件 URL 的权限。目前它仅支持基于 Chromium 的浏览器(Chrome、Edge、Opera),暂不支持 Firefox。
它会追踪我的浏览记录或文档数据吗?不会,它完全在本地设备上运行,没有网络请求、追踪器或数据分析。
颜色反转的底层原理到底是什么?它不解析也不改写页面的样式表,而是叠加一层由 GPU 加速的 CSS 混合模式图层,通过数学方法对颜色取反,把白色变成黑色,同时保持中间色调稳定,从而避免版式错乱。
如果我在一个标签页中开启深色模式,会影响其他已打开的标签页吗?不会,开关状态按标签页保存在临时内存中,因此反转一个文档不会影响其他任何活动标签页。
为什么要再做一个深色模式扩展,而不直接用现成的?作者为熬夜学习和做研究的学生及研究人员开发了它,因为常见的深色模式扩展往往会破坏复杂版式、占用大量 CPU,或者根本无法在浏览器内置的 PDF 阅读器中使用。
大小
3.2 MB
星标
4K
更新
提交Jul 22
时长
6个月
提交 · 90 天