How ainoob/noobox works
1. What this repo is
- NooBox is a Chrome extension for image-centric workflows: reverse image search, image extraction, auto-refresh, and HTML5 video control.
- It is structured to support both Manifest V2 and Manifest V3, with shared base manifests and environment-specific overrides.
2. Top-level architecture
- The extension is split into four main runtime surfaces:
- Background logic for orchestration and browser-level actions.
- Content scripts that run inside web pages and can inspect or manipulate page DOM/media.
- Popup UI for user interaction and settings.
- Search result pages that present aggregated reverse-image-search output in a dedicated extension tab.
3. Primary user flows
- Users can start searches via multiple entry points: popup upload, drag/drop, right-click/context actions, screenshot search, or page-based image detection.
- The request typically moves from content script or popup → background → external search engines, then results are shown in the search-result UI and often persisted in history.
4. Background subsystem
- src/background is the central coordinator.
- It contains modules for:
- Image search orchestration (imageSearch/*)
- Engine tab / URL management (engineTabs.ts, engineUrls.ts)
- Auto refresh (autoRefresh.ts)
- Video control (videoControl.ts)
- Options and messaging (options.ts, main.ts)
- This layer is responsible for browser-wide side effects like tab creation, navigation, and cross-context coordination.
5. Reverse-image-search engine adapters
- Each supported engine has its own adapter in both background and content-script layers:
- Bing, Google, Yandex, Baidu, TinEye, SauceNAO, IQDB, Ascii2D.
- The background adapters implement the search workflow and result normalization; the content-script engine files provide page-specific extraction or interaction logic where needed.
- This is a key architectural boundary: engine-specific quirks are isolated per provider, while higher-level UI and orchestration stay generic.
6. Content-script responsibilities
- src/contentScript is page-local automation and extraction code.
- It handles:
- Image extraction from the current page (extractImages.js)
- Screenshot-based search (screenshotSearch.js)
- Search-by-image interactions (searchByImage.ts)
- Video control hooks (videoControl.js)
- Because content scripts operate inside arbitrary sites, they bridge the extension with page DOM/media without requiring the background page to inspect the webpage directly.
7. Popup UI
- src/popup contains the extension’s primary control panel.
- It includes:
- Overview/dashboard
- Upload/search entry points
- Auto-refresh controls
- Video control controls
- Image search history
- Options and about pages
- State is handled through dedicated stores under src/popup/stores, which keeps UI state separate from browser orchestration logic.
8. Search-result experience
- src/searchResult is a dedicated extension page for viewing reverse-search output.
- It is composed of a header, action bar, engine selector, and result content area.
- searchResultStore drives the page state, making it distinct from the popup: the popup is for initiating actions, while this page is for reviewing and managing aggregated results.
9. Persistence and shared state
- src/dao and src/utils/db.ts provide IndexedDB-backed persistence.
- The main persisted domain appears to be image search history and possibly related records for recall in the popup/search-result flows.
- src/shared/stores/optionsStore.ts provides cross-UI access to extension options, indicating that settings are shared between popup, background, and result pages.
10. Debugging and development support
- There is a small standalone debug-server/ used in development/debug scenarios, with simple JSON/HTML storage helpers.
- The repo also includes src/debug/commandClient.ts, index.debug.ts, and manifest debug overrides, suggesting a controlled debug mode for extension development.
- Build/verification is handled by webpack and supporting tooling in tools/, with separate checks for production manifest generation.
11. Internationalization and assets
- UI text is localized through src/_locales with English, Japanese, Simplified Chinese, and Traditional Chinese bundles.
- Static assets such as engine logos and third-party CSS live under src/images and thirdParty/, supporting the extension UI and result presentation.
12. Important architectural boundaries
- Web page context vs extension context: content scripts handle page access; background handles privileged browser actions.
- Initiation vs presentation: popup/content scripts start work; search-result pages present aggregated outcomes.
- Engine-specific vs engine-agnostic logic: each search provider has its own adapter, but the user-facing flows are unified.
- Persistent history vs transient search state: IndexedDB-backed history survives sessions, while stores manage ephemeral UI state.
Main entry points: main.ts Main orchestration · imageSearch Search orchestration · popup.tsx Popup entry · searchResult.tsx Result entry
Components 29
Background
Privileged orchestration and browser-side coordination
- Background entry · Wires the background runtime for MV2/MV3.
src/background/index.ts - Main orchestration · Central background message handling and workflow coordination.
src/background/main.ts - Search orchestration · Background image-search control flow and provider dispatch.
src/background/imageSearch - Engine tabs · Creates and manages tabs used by reverse-image-search engines.
src/background/engineTabs.ts - Engine URLs · Builds and normalizes engine-specific navigation URLs.
src/background/engineUrls.ts - Options · Background access to extension options and shared preferences.
src/background/options.ts - Auto refresh · Implements page/tab auto-refresh behavior.
src/background/autoRefresh.ts - Video control · Coordinates browser-level video control actions.
src/background/videoControl.ts - Google debugger · Engine-specific debugging support for Google flows.
src/background/googleDebugger.ts
Content scripts
Page-local extraction and automation
- Extract images · Finds images in the current page DOM.
src/contentScript/extractImages.js - Screenshot search · Captures page content for screenshot-based search.
src/contentScript/screenshotSearch.js - Search by image · Page-side entry for image search interactions.
src/contentScript/searchByImage.ts - Video hooks · Injects page-local video control hooks.
src/contentScript/videoControl.js - Engine scripts · Page-specific provider logic for individual reverse-image-search engines.
src/contentScript/engines
UI
Popup and dedicated result page
- Popup entry · Popup UI bootstrap and routing.
src/popup/popup.tsx - Overview · Primary popup surface for starting searches and quick controls.
src/popup/overview.tsx - Search history · Popup view for recalling past image searches.
src/popup/imageSearchHistory.tsx - Options page · Popup-accessible settings surface.
src/popup/options.tsx - Result entry · Bootstrap for the dedicated search-result page.
src/searchResult/searchResult.tsx - Result content · Aggregated reverse-search result presentation.
src/searchResult/content/content.tsx - Result header · Header actions, engine selection, and result summary.
src/searchResult/header.tsx - Result state · State container for the search-result page.
src/searchResult/stores/searchResultStore.ts
Data
Persistence and shared state
- Search history DAO · IndexedDB-backed storage for image search records.
src/dao/imageSearchDao.ts - Options store · Cross-surface access to extension options.
src/shared/stores/optionsStore.ts - IndexedDB helper · Low-level database access wrapper.
src/utils/db.ts
Dev/support
Debug and build support
- Debug server · Standalone development/debug backend.
debug-server/server.js - Command client · Client-side bridge to the debug server.
src/debug/commandClient.ts - MV2 base · Base manifest definition for Manifest V2.
manifest/v2/base.json - MV3 base · Base manifest definition for Manifest V3.
manifest/v3/base.json
Connections 32
- MV2 base → Background entry: loads · Manifest V2 wires the extension runtime.
- MV3 base → Background entry: loads · Manifest V3 wires the extension runtime.
- Background entry → Main orchestration: starts · Background entry hands control to orchestration.
- Main orchestration → Search orchestration: dispatches · Routes reverse-image-search workflows.
- Main orchestration → Engine tabs: opens tabs · Creates and manages search-engine tabs.
- Main orchestration → Engine URLs: builds urls · Uses engine URL construction for navigation.
- Main orchestration → Options: reads options · Consumes shared extension settings.
- Main orchestration → Auto refresh: controls · Coordinates browser auto-refresh behavior.
- Main orchestration → Video control: controls · Coordinates global video control actions.
- Search orchestration → Engine tabs: uses · Search flow creates provider tabs.
- Search orchestration → Engine URLs: uses · Search flow generates provider-specific URLs.
- Search orchestration → Search history DAO: persists · Stores search history and related records.
- Search orchestration → Google debugger: debugs · Google-specific inspection support.
- Search by image → Main orchestration: messages · Page-local actions delegate to the background.
- Extract images → Main orchestration: messages · Extraction results are forwarded to background workflows.
- Screenshot search → Main orchestration: messages · Screenshot search requests are delegated.
- Video hooks → Video control: syncs · Page hooks integrate with background control logic.
- Engine scripts → Search orchestration: engine quirks · Provider-specific page automation supports search orchestration.
- Popup entry → Overview: routes · Popup bootstraps the main dashboard view.
- Popup entry → Search history: routes · Popup can open search history.
- Popup entry → Options page: routes · Popup can open settings.
- Overview → Main orchestration: starts work · Popup entry points initiate browser-side actions.
- Overview → Options store: reads · Overview uses shared settings state.
- Search history → Search history DAO: reads · History UI loads persisted search records.
- Result entry → Result header: composes · Dedicated result page includes header controls.
- Result entry → Result content: composes · Dedicated result page includes result content.
- Result entry → Result state: uses · Page state is driven by a local store.
- Result header → Result state: controls · Header actions mutate result-page state.
- Result content → Search history DAO: reads · Result management can consult persisted history.
- Result content → Options store: reads · Presentation respects shared extension options.
- Options store → Options: syncs · Options are shared across extension surfaces.
- Command client → Debug server: connects · Debug client talks to the standalone server.