How ghoulishg/organicsearchresultshighlighter works
1. What this repo is
- This is a Chrome/Chromium extension called Organic Results Highlighter.
- Its architecture is split between a page-injected content script that operates inside Google/Bing search result pages and a popup UI that lets the user configure behavior.
2. Primary runtime surfaces
- manifest.json is the central boundary definition: it declares which pages the extension runs on, which scripts/styles are injected, and what local storage/extension permissions are needed.
- The extension has two main execution contexts:
- Search tab context: content.js + content.css
- Extension popup context: popup.html + popup.js + popup.css
3. Content script subsystem
- content.js is the main automation engine.
- It detects organic search results on Google and Bing, applies highlight classes/styles, and keeps working as the page changes.
- Because it runs inside the page, it is the boundary between the extension and third-party DOMs; all search-engine-specific selector logic lives here.
4. Dynamic page monitoring
- The extension is built for live search result pages, not static HTML.
- A debounced MutationObserver watches for DOM updates caused by infinite scroll, AJAX loading, and result re-rendering.
- That observer is the main data flow trigger: when search results change, the script re-scans the page and updates highlights without requiring a refresh.
5. Selector-based detection model
- The repo emphasizes CSS selector configuration as the core abstraction for identifying organic results.
- Default selectors are tuned for Google/Bing, and the advanced settings allow users to override them if markup changes.
- This means the detection layer is intentionally decoupled from the popup UI and stored configuration, so selector updates can be applied without redeploying code.
6. Noise filtering and scope control
- The content script does not blindly style every result-looking element.
- It explicitly filters out ads, sidebars, auxiliary panels, “People Also Ask,” and nested sub-elements to avoid false positives.
- Architecturally, this is the extension’s main correctness boundary: it distinguishes “organic result cards” from surrounding search-page chrome.
7. Styling subsystem
- content.css contains the visual treatment for highlighted results, including soft pastel backgrounds and any pulse/verification animation.
- This keeps presentation separate from detection logic: content.js decides *what* to style, while content.css defines *how* it looks.
8. Popup/settings subsystem
- popup.html defines the user-facing control surface.
- popup.js manages theme selection, live counter display, verification scan actions, and advanced selector edits.
- popup.css provides the glassmorphism-themed UI and theme styling.
- This popup is the control plane for the extension; it does not process search pages directly, but it changes the content script’s behavior through shared state.
9. Persistent configuration and state
- The readme indicates settings are stored locally in chrome.storage.local.
- That storage is the bridge between the popup and content script: popup writes preferences, content script reads them when deciding selectors, themes, and other options.
- The architecture is privacy-preserving because there is no backend, no network sync, and no external API dependency.
10. Live count and verification flow
- The live highlight counter and verification scan are feedback mechanisms layered on top of the detection pipeline.
- The count is derived from the current set of highlighted DOM nodes.
- Verification briefly pulses the styled elements so the user can confirm the selector set is matching the intended page regions.
11. Assets and packaging
- icons/ contains the extension artwork used by Chrome.
- generate_icons.ps1 is a build-time utility for producing those assets; it is not part of the runtime architecture.
- The repo otherwise stays intentionally lightweight and vanilla—no external libraries or backend services.
12. Overall data flow
- User opens a Google/Bing results page → Chrome injects content.js and content.css per manifest.json → content script scans DOM and highlights organic results → MutationObserver keeps the highlights current → user opens the popup to switch themes or adjust selectors → popup writes settings to local storage → content script reads those settings and updates its matching/styling behavior.
13. Key architectural boundary to diagram
- The most important boundary is extension code vs. third-party search-page DOM.
- Everything else is internal orchestration around that boundary: popup configuration, local persistence, and CSS presentation.
- There is no server component, so the architecture is fully client-side and browser-contained.
Main entry points: popup.js Popup logic · content.js Content script · manifest.json Manifest · popup.html Popup shell
Components 16
Extension runtime
Chrome extension surfaces and shared state
- Manifest · Defines permissions, injections, and page matches for the extension.
manifest.json - Local storage · Shared local state used to persist settings between popup and content script.
Search tab
Injected logic running inside Google/Bing result pages
- Search DOM · Google/Bing result pages that the extension reads and modifies through injected scripts.
- Content script · Scans search pages, detects organic results, applies highlights, and keeps them updated.
content.js - Selector logic · Search-engine-specific selectors and filtering rules for organic results versus ads and page chrome.
- DOM observer · Debounced mutation monitoring that rescans the page when results change.
- Noise filters · Excludes ads, sidebars, people-also-ask blocks, and nested sub-elements from highlighting.
- Highlighting · Marks matched organic result cards in the page DOM.
- Content styles · Visual treatment for highlighted results and verification pulse effects.
content.css
Popup UI
User-facing configuration and feedback controls
- Popup shell · Popup interface structure for extension controls and status.
popup.html - Popup logic · Handles theme selection, live counters, verification scans, and selector edits.
popup.js - Popup styles · Glassmorphism and theme styling for the popup interface.
popup.css - Themes · User-selected visual modes that affect the popup and highlight presentation.
- Live counter · Derived count of currently highlighted organic results.
- Verification scan · Triggers a pulse/flash on matched results so the user can confirm selector accuracy.
Assets
Packaging and icon assets
- Icons · Chrome extension artwork bundled for browser presentation.
icons
Connections 20
- Manifest → Content script: injects · Manifest declares content script injection on supported search pages.
- Manifest → Content styles: injects · Manifest loads page styles with the content script.
- Manifest → Popup shell: opens · Manifest defines the extension action popup surface.
- Manifest → Icons: packages · Manifest references bundled extension artwork.
- Manifest → Local storage: permits · Manifest grants access to local extension storage.
- Content script → Search DOM: runs in · Content script executes inside the search result page DOM.
- Content script → Selector logic: uses · Detection depends on search-engine-specific selectors and heuristics.
- Content script → Noise filters: excludes · Filtering logic removes ads and non-organic page regions.
- Content script → DOM observer: watches · MutationObserver drives rescans when the page updates.
- DOM observer → Highlighting: triggers · DOM changes cause highlight recalculation and refresh.
- Selector logic → Highlighting: matches · Organic result matches are turned into highlighted cards.
- Noise filters → Highlighting: narrows · Scope control ensures only intended result cards are styled.
- Highlighting → Content styles: styled by · Visual treatment is defined separately from detection logic.
- Popup shell → Popup logic: drives · Popup markup is wired to interaction logic.
- Popup logic → Popup styles: styled by · Popup logic operates within the themed popup UI.
- Popup logic → Local storage: reads/writes · Popup persists theme, selectors, and user preferences locally.
- Popup logic → Themes: selects · User theme choice updates popup and highlight presentation.
- Popup logic → Live counter: derives · Popup shows the current number of highlighted results.
- Popup logic → Verification scan: triggers · Verification action asks content script to pulse matched elements.
- Local storage → Content script: feeds · Content script reads stored settings to adapt matching and styling.