DOMgeist -- Local-First Page Audit Extension

DOMgeist audits the active Chrome tab locally. Built for developers.

No telemetry, no user accounts, no remote audit API, no cloud AI. Scan data stays in the browser unless you export it.

Scan Overview	Findings Detail	Grouped History
DOMgeist Lock	Settings & Permissions	JSON/CSV Export
Wireframe & Color Picker

Features

Scan Pipeline

The scan payload is normalized with Zod, processed in bounded analyzer modules, and rendered in the popup.

Accessibility, SEO, Security, Performance

The analyzer reports practical page findings across:

• Accessibility: headings, alt text, focusable hidden content, link text, ARIA references, SVG names, tabindex.
• Performance: LCP, CLS, observed resource weight, long tasks, image dimensions, lazy-loading opportunities, DOM size.
• Security: CSP, frame protection, referrer policy, permissions policy, COOP, cookie flags when permission is granted.
• SEO: title, meta description, canonical URL, Open Graph, Twitter Card metadata, robots intent, same-page anchors.
• Local AI: optional Ollama suggestion clusters from minimized scan summaries. Disabled by default and falls back to rules on timeout or invalid output. No cloud AI.

Public Technology Signals

Technology detection uses bounded local signals: main-world runtime probes, script/resource URL fingerprints, meta tags, headers when captured, and conservative DOM evidence. It does not download external script bodies or import a remote fingerprint database.

Permission-Gated Deep Capture

The base extension runs with minimal production permissions: activeTab, scripting, and storage. Header capture, cookie inventory, and downloads use optional permissions. The popup shows when a deeper module is unavailable rather than silently pretending data exists.

DOMgeist Lock

Saved scan history can be encrypted locally behind DOMgeist Lock. The lock uses browser storage plus Web Crypto-derived keys so protected history can be hidden without sending secrets to a server.

Grouped History Trends

Scan history is grouped by domain, sorted alphabetically, and rendered with a native SVG trend chart per domain. Exact URLs inside a domain become separate series, single-point histories render as dots, and the scan list remains visible below each group.

Export

Reports can be exported as JSON or CSV. JSON preserves the validated scan structure and integrity hash. CSV provides flat rows for spreadsheet review.

Restricted Page Handling

Browser-internal pages, extension gallery pages, unsupported schemes, missing permissions, navigation changes, target-tab closure, and scan timeouts are classified into structured failure reasons and shown as clear messages.

---

Architecture at a Glance

+----------------------------------------------------------+
|                   Browser Extension MV3                  |
|                    Chrome MV3 via WXT                    |
+------------------------+---------------------------------+
                         |
        +----------------v----------------+
        |          Popup UI               |
        |  React 19 + Radix + Zustand     |
        |  Scan results, history, export  |
        +----------------+----------------+
                         |
        +----------------v----------------+
        |       Background Service        |
        |  permission flow + scan routing |
        |  optional headers/cookies       |
        +----------------+----------------+
                         |
        +----------------v----------------+
        |   Content / Main-World Probe    |
        |  DOM snapshot + runtime signals |
        +----------------+----------------+
                         |
        +----------------v----------------+
        |        Analyzer Modules         |
        |  A11y / SEO / Performance       |
        |  Security / Storage / Tech      |
        +---------------------------------+

Scan flow:

1. Popup sends a typed scan request to the background service.
2. Background validates the active tab and permission state.
3. Content runtime captures a bounded page snapshot and public DOM signals.
4. Main-world probe samples safe runtime globals for technology detection.
5. Analyzer modules score findings and return a normalized response.
6. Popup stores history locally, renders grouped trends, and enables export.

Why Local-First

Page audits often touch sensitive URLs, markup, metadata, cookies, and storage keys. Keeping the analysis on-device makes the privacy claim verifiable in source code rather than promised by a service.

Performance Choices

• Native SVG history charts instead of a charting runtime dependency.
• TreeWalker-style bounded DOM collection in analyzer paths.
• Lazy-mounted heavier history and debug surfaces.
• Architecture guard for runtime dependencies, permissions, workflow gates, package artifacts, and forbidden build patterns.

Framework & Extension Features

Browser Extension

• Manifest V3 through WXT.
• Chrome MV3 build target.
• Optional permission flow for webRequest, cookies, and downloads.
• Production manifest verification for permissions, icons, and test-only commands.

React 19 + TypeScript

• Strict TypeScript.
• React popup UI with Radix Dialog, Dropdown Menu, and Collapsible primitives.
• Zustand for popup state.
• Dexie/IndexedDB for scan history.
• Web Crypto for lock-protected history.
• Vitest + React Testing Library for unit/component tests.
• Playwright for browser-extension E2E.

---

Project Structure

domgeist/
├── .github/
│   └── workflows/
│       └── deploy.yml                  # CI: lint, compile, coverage, builds, smoke, package checks
│
├── frontend/
│   ├── entrypoints/
│   │   ├── background.ts               # Runtime message router
│   │   ├── content.ts                  # Content-script bootstrap
│   │   └── popup/
│   │       ├── App.tsx                 # Popup app shell + dialog wiring
│   │       ├── PopupView.tsx           # Main scanner UI
│   │       ├── HistoryTrendChart.tsx   # Grouped native SVG history charts
│   │       ├── popup-store.ts          # Popup state store
│   │       └── style.css               # Dark/frosted UI system
│   ├── utils/
│   │   ├── a11y-analyzer.ts            # Accessibility rules
│   │   ├── performance-analyzer.ts     # Performance metrics and findings
│   │   ├── security-headers.ts         # Header analysis
│   │   ├── seo-analyzer.ts             # SEO metadata checks
│   │   ├── storage-audit.ts            # Cookies/storage summary
│   │   ├── technology-audit.ts         # Public technology fingerprints
│   │   ├── scan-service.ts             # Scan orchestration and failure classification
│   │   ├── history-store.ts            # IndexedDB scan history
│   │   ├── history-crypto.ts           # DOMgeist Lock encryption helpers
│   │   └── export-report.ts            # JSON/CSV export
│   ├── tests/                          # Vitest + React Testing Library
│   ├── e2e/                            # Playwright extension workflows
│   ├── smoke/                          # Package smoke checks
│   ├── scripts/                        # Architecture, package, and manifest guards
│   ├── public/icon/                    # DOMgeist icon assets
│   ├── wxt.config.ts                   # Manifest, targets, aliases, package excludes
│   └── package.json
│
├── BRAND.md                            # DOMgeist brand asset policy
├── LICENSE                             # GPL-3.0-only text
└── README.md

---

Tech Stack

Area	Technology
Extension framework	WXT 0.20, Manifest V3
Target	Chrome MV3
UI	React 19, Radix UI primitives, Tailwind CSS v4
Language	TypeScript strict mode
State	Zustand
Storage	Dexie + IndexedDB, browser storage
Validation	Zod
Export	JSON, CSV
Testing	Vitest, React Testing Library, Playwright
Packaging	WXT zip targets + custom artifact verification
CI	GitHub Actions + Codecov

---

Getting Started

Prerequisites

• Node.js 24+
• npm
• Chrome or another Chromium-based browser for local testing

Local Development

git clone git@github.com:vladyslavm-dev/domgeist.git
cd domgeist/frontend
npm install
npm run dev

WXT starts the extension development workflow.

Production Builds

npm run build:chrome   # Chrome unpacked build
npm run zip            # Chrome package

Build output is written to frontend/.output/.

---

Testing

Full Local Test Matrix

cd frontend
npm run compile
npm run lint
npm run guard:source-quality
npm run audit:architecture
npm run test
npm run test:e2e
npm run test:package

Unit And Component Tests

Vitest + React Testing Library cover analyzer rules, popup behavior, encrypted history, permission handling, export, scoring, storage, technology detection, and UI flows.

Current local suite: 213 tests.

Browser Extension E2E

Playwright runs the built Chrome extension against controlled fixtures and validates scan behavior, history, lock state, export, unsupported pages, rapid open/close cycles, and console cleanliness.

Current E2E suite: 22 tests.

Package And Architecture Gates

• audit:architecture checks required dependencies, forbidden packages, extension permissions, workflow gates, and forbidden bundle patterns.
• verify-e2e-manifests checks production vs E2E manifest permissions and action icons.
• verify-package-artifacts checks package artifacts for required and forbidden entries.
• guard:source-quality blocks tracked TODO/HACK/FIXME/temp comments.

---

CI/CD

GitHub Actions runs:

1. Dependency install.
2. ESLint.
3. TypeScript compile.
4. Source-quality guard.
5. Coverage tests.
6. Codecov upload.
7. Extension build.
8. Playwright E2E.
9. Architecture audit.
10. Package smoke and artifact verification.

---

License

DOMgeist source code is copyright (c) 2026 Vladyslav Marchenko and licensed under GPL-3.0-only. See LICENSE.

This repository contains the public DOMgeist 1.0.0 Chrome Web Store release. Future product features may be developed separately.

The DOMgeist name, logo, icon, screenshots, store listing assets, and visual identity are not licensed under the GPL. See BRAND.md.

---

Author

Vladyslav Marchenko

• GitHub: @vladyslavm-dev
• Website: vladyslavm.dev