Skip to content

DESIGN.md

Latest commit

 

History

History
90 lines (76 loc) · 3.07 KB

DESIGN.md

File metadata and controls

90 lines (76 loc) · 3.07 KB
Raw

Anchor

Last verified against code: 2026-04-04

Anchor is a Manifest V3 Chrome extension that blocks distracting sites unless the live page content clearly matches one of the user's allowed topics.

Current Source Layout

Anchor/
├── AGENTS.md -> CLAUDE.md
├── CLAUDE.md
├── DESIGN.md
├── HARNESS_PLAN.md
├── docs/
├── scripts/
├── tests/
└── src/
    ├── background/service-worker.js
    ├── blocked/Blocked.jsx
    ├── content/content-script.js
    ├── options/Options.jsx
    ├── popup/Popup.jsx
    └── shared/
        ├── constants.js
        ├── domain-utils.js
        ├── llm.js
        ├── review-utils.js
        └── storage.js

Blocking Model

  • The service worker decides whether a URL is blocked.
  • The content script handles live-page readiness and DOM snapshot extraction.
  • The blocked page only renders stored review state; it does not perform the review itself.
  • The replay harness in scripts/replay-harness.mjs is the supported debugging surface for capturing extension logs, final DOM state, and screenshots.

Key Behaviors

  • Full-page navigations are observed through tabs.onUpdated.
  • SPA navigations are observed in the content script via:
    • history API hooks
    • popstate
    • Navigation API when available
  • The content script waits for:
    • stable non-empty title
    • enough visible content
    • strong text or main-content evidence
    • meaningful change from a baseline snapshot for SPA transitions
  • LargestContentfulPaint is recorded for diagnostics, but it is not the primary readiness trigger.
  • The service worker can request a timeout-rescue snapshot if normal submission stalls.
  • strict_block and exact_block both force redirect through the background worker so SPA navigations cannot bypass the blocked page.

Review Outcomes

  • allow
    • overlay cleared, approval TTL stored
  • blocked
    • reason stored, tab redirected to blocked page
  • strict_block
    • redirected immediately without LLM review
  • exact_block
    • redirected immediately when an exact blocked URL matches
  • error / no-key
    • stored as blocked-page state with an explanatory reason

Harness And Validation

  • HARNESS_PLAN.md
    • repo-specific harness-engineering plan and current operating guidance
  • scripts/replay-harness.mjs
    • CDP replay harness with:
      • launch mode using an ephemeral debugger port discovered through DevToolsActivePort
      • attach-only WebSocket mode for manually launched Chrome on 127.0.0.1:9222
  • scripts/assert-replay-artifacts.mjs
    • validates replay artifact completeness, final-state captures, and screenshot presence for the latest or specified harness run
  • scripts/doc-check.mjs
    • fails when docs reference removed files or stale paths

Docs

  • docs/architecture.md
    • current runtime pieces and responsibilities
  • docs/runtime-flows.md
    • navigation and review flows
  • docs/known-failures.md
    • current failure modes and mitigations
  • docs/test-matrix.md
    • cases for harness replay and regression coverage