Browser Extension

Structure

• Framework: Vue 3 + Vuetify, Pinia, vue-router (auto-generated routes).
• Build system: Vite 7 (separate bundles for popup/side panel, background, and content script).
• Scripts (see apps/extension/package.json):
  • dev, dev-firefox, dev:* – development server plus background/content bundles.
  • build, build-firefox – production build (emits apps/extension/extension/).
  • pack:zip, pack:crx, pack:xpi – distribution artifacts.
  • start:chromium, start:firefox – web-ext run with built assets.

Local Build & Load

pnpm --filter @source-taster/extension dev      # Chromium
pnpm --filter @source-taster/extension dev-firefox

• Dev mode creates apps/extension/extension/manifest.json and stub HTML files for HMR.
• Chrome/Edge: chrome://extensions → enable Developer Mode → “Load unpacked” → apps/extension/extension.
• Firefox: about:debugging#/runtime/this-firefox → “Load Temporary Add-on” → apps/extension/extension/manifest.json.

Production Build & Packaging

pnpm --filter @source-taster/extension build
pnpm --filter @source-taster/extension pack:zip   # Chrome Web Store
pnpm --filter @source-taster/extension pack:xpi   # Firefox Add-on (web-ext build)

• pack:crx produces a locally signed CRX (testing only, not for store upload).
• Version bumps happen via pnpm --filter @source-taster/extension release (bumpp). Keep the manifest version in sync with package.json.

Manifest (MV3)

• manifest_version: 3, icons in assets/icon*.png.
• Popup (dist/popup/index.html) and options (dist/options/index.html).
• Side panel:
  • Chromium: side_panel.default_path
  • Firefox: sidebar_action.default_panel
• Background script:
  • Chromium: service worker dist/background/index.mjs
  • Firefox: module script dist/background/index.mjs
• Permissions:
  • storage, activeTab, contextMenus, optional sidePanel (Chromium).
  • Host permissions: http://*/*, https://*/*.
• Content script: dist/contentScripts/index.global.js, styles dist/contentScripts/style.css.
• CSP: development allows Vite HMR (script-src self http://localhost:3303).
• default_locale: "en"; translations in src/locales/en.json and de.json.

The manifest is generated by scripts/prepare.ts (esno scripts/manifest.ts). Adjust it for new permissions or pages.

Features & Flows

• Context menus (background/main.ts)
  • check-bibliography: loads the side panel and pre-fills the selected text.
  • openSidePanel: toggles the side panel; disabled while the panel is visible.
• Side panel vs. popup: stored in browser.storage.sync (displayOption), managed by the options UI.
• WebExtension storage: useWebExtensionStorage wraps storage.local with cross-context synchronisation.
• PDF import: extractTextFromPdfFile (unpdf) parses PDFs into plain text.
• Verification workflow: useVerification orchestrates AnyStyle conversion → search → matching with optional early termination.
• Settings: Pinia store settings (WebExtension storage) uses DEFAULT_UI_SETTINGS from shared types.

Communication

• webext-bridge currently powers messaging in background/main.ts (e.g. side panel visibility updates).
• The side panel notifies the background script with SIDE_PANEL_OPENED/CLOSED so context menus stay in sync.

QA & Testing

• Lint: pnpm --filter @source-taster/extension lint
• Type check: pnpm --filter @source-taster/extension typecheck
• TODO: Add automated UI tests (Cypress or Playwright).

Release Checklist

1. Bump version (pnpm --filter @source-taster/extension release).
2. Build production assets (pnpm --filter @source-taster/extension build).
3. Generate store artifacts (pack:zip, pack:xpi).
4. Upload to Chrome Web Store / AMO.
5. Create a release tag (git tag vX.Y.Z, push) so GitHub Actions runs release.yml.

Security & Privacy

• The extension never stores API keys locally; everything is saved via /api/user/ai-secrets on the server (encrypted).
• All requests point to VITE_API_BASE_URL (env.ts, default http://localhost:8000).
• TODO: Revisit CSP and permissions whenever new providers or APIs are added.