How om-prakash-verma/snapsaver works
1. What this repo is
SnapGallery is a Chrome Extension Manifest V3 project. Its architecture is split across three browser execution contexts: page-injected content scripts, a background service worker, and extension pages for the side panel downloader and options UI.
2. Primary user-facing surface
The main product surface is the downloader side panel (views/downloader.html + src/downloader/*). This is where discovered media is listed, grouped, filtered, selected, and downloaded. The options page (views/options.html + src/options/*) is a separate configuration boundary for extension preferences.
3. Page scraping boundary
All page inspection happens in src/content-script/*. This layer is responsible for extracting media from the active tab’s DOM and styles, including standard elements, CSS-driven assets, file-type detection, URL mapping, regex-based parsing, and media dispatch back to the extension UI. This code must operate inside the page context and stay isolated from extension-only APIs.
4. Media discovery pipeline
The downloader-side logic in src/downloader/find-media.ts and related modules consumes media data coming from the content script, tracks it per tab, and coordinates refreshes when new content appears. The README’s focus on dynamic observation matches the architecture’s use of DOM mutation-driven scraping for SPA/infinite-scroll pages.
5. Background orchestration
src/background/background.ts is the central extension coordinator. It likely handles lifecycle events, context menu actions, tab/side-panel wiring, and message routing between contexts. In MV3 terms, this is the place where browser-level events are converted into extension actions.
6. Message-driven integration
Cross-context communication is explicit in the type layer (src/types/message-event-name.enum.ts, tab-data.type.ts, found-media.type.ts, etc.) and the listener modules (src/downloader/message-listeners.ts, src/downloader/send-media-listener.ts, src/content-script/send_media.ts). The architecture is event-driven rather than shared-memory based: page script extracts data, background relays/coordinates, side panel renders state.
7. Media normalization and metadata
Several modules indicate a normalization stage before rendering: mappers-fn.ts, extractors-fn.ts, filters-fn.ts, media-types.ts, and media-display.ts. This is where raw page URLs become structured media records with consistent type, source, and display metadata suitable for grouping and filtering.
8. Filtering subsystem
Filtering is a distinct subsystem in both the downloader UI and content processing layers. The UI-side filter modules under src/downloader/filters/* correspond to rendered controls, while the content-script-side filter helpers apply constraints to discovered media. The architecture keeps extraction separate from user filtering so the same media set can be re-rendered under different criteria without rescanning the page.
9. Per-tab and persistent state
State is split between transient per-tab tracking (src/media-in-tabs.ts, src/downloader/tab-info.ts) and persistent extension storage (src/storage/*). chrome.storage.sync is used for durable settings and theme/preferences, while tab-scoped data keeps the downloader aligned with the active page and navigation changes.
10. Download and file handling
Download-specific behavior lives in src/utils/download-functions.ts and related helpers. Supporting utilities like crc32.ts suggest deduplication or stable identity for assets, while yt-restriction.ts enforces special-case guardrails for restricted sites. This keeps policy checks and file transfer logic outside the rendering layer.
11. UI composition
The downloader UI is modularized into accordion, filter, top-container, button, and info components under src/downloader/* and css/downloader/*. This points to a componentized, state-driven panel where media groups are expanded/collapsed, filtered, and acted on without page reloads.
12. Options, theme, and presentation
Global appearance and preferences are centralized through src/theme.ts, src/popup-dimensions.ts, and src/options/main.ts, with corresponding CSS files for themes, radio/checkbox controls, and page-specific styling. Styling is separated from logic, and the options page is its own isolated settings surface.
13. Shared platform utilities
Common browser and DOM abstractions live in src/utils/* and src/types/*. chrome-api.ts likely wraps extension API calls, while DOM helpers and shared types keep the background, content script, and UI layers aligned on contracts and reduce duplicated browser-specific code.
14. Build and packaging boundary
Webpack and TypeScript are the build-time architecture layer (webpack.config.js, tsconfig.json, package.json). The repo ships as a compiled extension with HTML views, CSS assets, icons, and images, so the runtime application is assembled from multiple entry points rather than a single app bundle.
Main entry points: background.ts Background · webpack.config.js Build config · content-script Content script · downloader Downloader UI
Components 19
Browser runtime
Extension execution contexts and user-facing surfaces.
- Background · Central MV3 coordinator for lifecycle, routing, and extension events.
src/background/background.ts - Content script · Runs in page context to inspect DOM, styles, and visible media.
src/content-script - Downloader UI · Main discovery, grouping, filtering, and download interface.
src/downloader - Options UI · Extension preferences and appearance configuration surface.
src/options/main.ts - HTML views · Extension pages that mount the downloader, options, and changelog surfaces.
views - Extractors · Finds standard elements and CSS-driven assets from the active page.
src/content-script/extractors-fn.ts - Mappers · Converts raw page URLs and attributes into structured media records.
src/content-script/mappers-fn.ts - Page filters · Applies page-side constraints and regex-based matching during discovery.
src/content-script/filters-fn.ts - Send media · Dispatches discovered media from the page context to extension listeners.
src/content-script/send_media.ts - Find media · Tracks discovered media per tab and coordinates refreshes in the downloader.
src/downloader/find-media.ts - Message listeners · Receives and interprets extension messages for the downloader state flow.
src/downloader/message-listeners.ts - UI filters · Downloader-side filter controls and selection logic for the rendered media set.
src/downloader/filters - Media groups · Renders grouped, collapsible media results with thumbnails and controls.
src/downloader/accordion.ts
Data model
Shared types, state, and normalization boundaries.
- Storage · Wraps durable settings and sync-backed extension preferences.
src/storage - Tab state · Keeps per-tab discovery and active-page context aligned.
src/media-in-tabs.ts - Shared types · Message names, found-media records, tab data, and shared extension contracts.
src/types - Media model · Shared media metadata, display, and file-type classification logic.
src/downloader/media-types.ts - Utilities · Chrome API wrapper, DOM helpers, download logic, CRC, and site restrictions.
src/utils
Build
Packaging and compile-time structure.
- Build config · TypeScript and Webpack compile the multi-entry extension bundle.
webpack.config.js
Connections 22
- Content script → Extractors: scans · Page context locates candidate media from DOM and styles.
- Extractors → Mappers: normalizes · Raw assets are converted into structured media records.
- Mappers → Page filters: classifies · Regex and type rules refine discovered media during scraping.
- Content script → Send media: dispatches · Scraped media is sent back to extension listeners.
- Send media → Background: messages · Cross-context events reach the background coordinator.
- Background → Message listeners: routes · Background events are forwarded into downloader state handling.
- Message listeners → Find media: updates · Incoming media updates per-tab discovery state.
- Find media → Media groups: renders · Tracked media is grouped for the side panel UI.
- Find media → UI filters: filters · UI filtering changes the visible media set.
- UI filters → Media groups: refines · Filtered results are presented as collapsible groups.
- Background → Storage: reads/writes · Extension lifecycle and preferences use durable storage.
- Downloader UI → Tab state: tracks · Downloader keeps per-tab discovery aligned with navigation.
- Content script → Shared types: shares contracts · Message and media schemas align page and extension contexts.
- Downloader UI → Media model: formats · Downloader presentation uses shared media metadata and display rules.
- Options UI → Storage: configures · Settings UI persists user preferences and theme state.
- Utilities → Background: supports · Common wrappers and helpers back background orchestration.
- HTML views → Downloader UI: hosts · Downloader HTML mounts the side panel application.
- HTML views → Options UI: hosts · Options HTML mounts the settings application.
- Build config → Background: bundles · Webpack/TypeScript produce the service worker entry.
- Build config → Content script: bundles · Webpack/TypeScript produce the page-injected script.
- Build config → Downloader UI: bundles · Webpack/TypeScript produce the side panel UI.
- Build config → Options UI: bundles · Webpack/TypeScript produce the options page.