delambo/core-web-vitals-annotations

1. Project type and runtime

- This is a Chrome Extension focused on analyzing and annotating Core Web Vitals on the currently open web page.

- It runs in two main browser-extension contexts: a content script injected into pages and a popup UI shown when the user clicks the extension icon.

2. Top-level architecture

- The repo is split into three functional areas:

- src/public: page-injected assets and logic

- src/popup: the extension popup UI

- src/background: the extension background script

- src/manifest.json ties these pieces together as a browser extension.

3. Page instrumentation layer

- src/public/contentScript.js is the main page-facing subsystem.

- Its job is to observe page behavior related to CLS and LCP, then overlay visual annotations directly on the webpage.

- src/public/contentScript.css provides the styling for those overlays so they appear on top of page content.

4. What the content script reports

- The extension highlights:

- CLS contributors: elements that shifted and contributed to layout instability

- LCP element: the largest contentful paint target, marked with a dashed purple outline

- The README indicates the script also tracks metric values and groups elements that shifted together, which implies the content script is both an observer and a renderer of diagnostic overlays.

5. Extension popup

- src/popup/index.js is the entry point for the popup panel.

- src/popup/popup.ejs defines the popup’s structure, and src/popup/styled.js contains the styling layer for the popup UI.

- The popup presents a grid of FID, LCP, and CLS values and includes a control to remove annotations from the page.

6. Data flow between popup and page

- The popup is not the source of the metrics; it is a viewer/controller over data collected elsewhere.

- The metrics and overlay state are likely shared through extension messaging and/or background-mediated state, because the popup must reflect page state and trigger actions like clearing annotations.

- The content script is the component closest to the page and therefore the component that actually owns the overlays.

7. Background script role

- src/background/index.js is the likely coordination point for extension-level events and communication.

- In a Chrome extension like this, the background layer commonly handles message routing, lifecycle persistence, and coordination between the popup and the content script.

- Architecturally, it is the boundary between transient UI interactions and page instrumentation state.

8. Manifest and extension wiring

- src/manifest.json defines the extension permissions, entry points, and which scripts run in which contexts.

- This manifest is the key boundary document: it determines what is injected into pages, what runs in the extension UI, and what background capabilities are available.

9. Performance-measurement focus

- The repo is explicitly centered on Core Web Vitals and related browser performance events:

- FID is user-initiated and may only appear after interaction

- CLS accumulates over time as layout shifts occur

- LCP is detected as the largest contentful paint element

- This means the architecture is event-driven rather than request/response based.

10. Rendering and visual semantics

- The overlay system uses color and shape to encode severity and metric type:

- CLS annotations are color-coded from lower to higher impact

- LCP uses a purple dashed outline

- Those are not just UI details; they are part of the architecture because they define the page-layer diagnostic model.

11. Build and tooling

- The project is built with a webpack-based setup, likely using Kyt (kyt.config.js).

- Babel (.babelrc) and ESLint (.eslintrc.js) indicate transpilation and linting support for the extension codebase.

- webpack.aliases.config.js suggests module aliasing to simplify imports across the popup, background, and public scripts.

12. Source organization boundary

- src/public/lodash.debounce-throttle.js and the presence of page instrumentation code indicate the repo includes utility code bundled with the content script, likely to reduce redundant event handling for scroll/layout activity.

- The separation between public, popup, and background is the most important architectural boundary in the repo.

13. Operational behavior

- The extension is designed to be opened on an active page, where the content script has already been monitoring or can begin monitoring page activity.

- The popup is effectively a dashboard for the currently active tab, while the content script is the measurement engine.

14. What an architecture diagram should show

- A browser page with injected content script + overlay CSS

- A separate popup UI opened from the extension icon

- A background script mediating extension communication/state

- The manifest as the configuration layer connecting all three

- The data path from page events → metrics collection → overlay rendering and popup display