BagMark 🎒

An advanced, lightweight extension for Firefox, Chrome, and Brave to quickly save bookmarks to customizable or date-organized folders with rich metadata and duplicate detection.

---

✨ Features

• 1-Click Right-Click Quick Save: Right-click any link or webpage background and select "Bag It (Save to BagMark)" to save directly into your default folder.
• Context Submenus for Custom Folders: Right-click submenu ("Bag It to ▸") dynamically lists your favorite / pinned bookmark folders.
• Chronological Date Organization: Optional auto-filing into year-month subfolders (e.g. BagMark / 2026-09 / ...), created on the fly.
• Rich Metadata Capture: Automatically records exact timestamps (dateAdded), originating webpage URL/title, and any highlighted quote/text excerpt into local storage.
• Duplicate Link Detection: Skips links already saved in the destination folder while allowing the same link in other collections. Compares both URLs without known tracking parameters, preserving meaningful query parameters, fragments, and path differences. Disable this in Settings to allow repeated links in the same folder.
• Interactive Popup Dashboard: Fast, search-as-you-type dashboard to filter bookmarks by title, URL, quote, or tags, with folder filters, relative time badges, and 1-click clipboard copy.
• Save Open Tabs: Expand Save open tabs in the popup, choose an existing folder or create a new subfolder, and save all web tabs from the current window in tab order. Tabs stay open, browser pages are skipped, and the result shows saved, skipped, and failed counts. The chosen folder is used directly, without automatic date subfolders.
• Options & Customization: Configure default folder name, toggle date-based subfolders, manage pinned submenu folders, and adjust alert notifications.
• Modern Stack: Built with TypeScript, Vite, Vitest, and Manifest V3.

---

🚀 Getting Started

Prerequisites

• Node.js (v18+)
• npm or pnpm
• Mozilla Firefox (v115+), Chrome (v123+), or Brave based on Chromium v123+

Installation & Development

1. Clone the repository:

   git clone https://github.com/sonuKumar03/bagmark.git
   cd bagmark

2. Install dependencies:

   npm install

3. Run tests:

   npm test

4. Build the extension:

   npm run build

5. Load in Firefox:

   • Open Firefox and navigate to about:debugging#/runtime/this-firefox.
   • Click "Load Temporary Add-on...".
   • Select dist/manifest.json from this project directory.
   • Right-click any link on the web to start bagging links!

Chrome & Brave

Both browsers use the same Chromium build:

npm run build:chromium

1. Open chrome://extensions in Chrome or brave://extensions in Brave.
2. Enable Developer mode.
3. Click Load unpacked and select the project's dist-chromium folder.
4. Pin BagMark to the toolbar, then right-click a webpage or link to save it.

Firefox builds remain in dist; Chromium builds go to dist-chromium so rebuilding one does not remove the other. After rebuilding, click Reload on the extension's card. The existing packaging and signing commands produce Firefox artifacts; Chrome and Brave use the unpacked Chromium folder for local testing.

---

📦 Distribution & Packaging

Local Packaging

To generate a local .zip bundle for manual testing or upload:

npm run package

The resulting zip will be created in web-ext-artifacts/.

Mozilla Reviewer Build Instructions

The source archive contains the original TypeScript, assets, build configuration, and npm lockfile. On Linux, macOS, or Windows, install Node.js 22 with its bundled npm, extract the archive, and run from its root:

npm ci
npm run build

The Firefox extension is generated in dist/. No credentials, environment variables, external services, or private dependencies are needed to reproduce this build. The release workflow uploads the source archive to Mozilla with the extension, for both listed and unlisted submissions.

🚀 Automated Releases & Mozilla AMO Signing

This repository is configured with a GitHub Actions workflow that automatically builds, tests, signs with Mozilla AMO, and publishes a GitHub Release when a git tag is pushed:

# 1. Tag a new version
git tag v1.0.3

# 2. Push tag to GitHub
git push origin v1.0.3

GitHub Actions will automatically:

1. Extract the version (1.0.3) and sync package.json & manifest.json.
2. Run test suites (npm test) and build the extension.
3. Sign the .xpi via Mozilla Add-ons (AMO) API using repository secrets (AMO_JWT_ISSUER, AMO_JWT_SECRET).
4. Publish a GitHub Release with the signed .xpi attached for 1-click install in Firefox.

---

🛠️ Project Structure

bagmark/
├── manifest.json              # Source Firefox MV3 manifest
├── package.json               # Dependencies & scripts
├── tsconfig.json              # Strict TypeScript configuration
├── vite.config.ts             # Vite multi-page build with manifest generation
├── public/assets/             # Brand icons (SVG & PNGs)
├── src/
│   ├── background/
│   │   └── index.ts           # Context menu management & save event handlers
│   ├── popup/                 # Interactive popup dashboard
│   │   ├── index.html
│   │   ├── popup.ts
│   │   └── popup.css
│   ├── options/               # Settings & folder picker page
│   │   ├── index.html
│   │   ├── options.ts
│   │   └── options.css
│   └── lib/                   # Core business logic modules
│       ├── types.ts           # TypeScript interfaces
│       ├── utils.ts           # Date formatters & URL normalizer
│       ├── storage.ts         # Metadata local storage manager
│       ├── config.ts          # Settings persistence
│       └── bookmarks.ts       # Cross-browser bookmark tree traversal & creation
└── tests/                     # Vitest automated test suite

---

📄 License

MIT © sonuKumar03