█████╗ ███╗ ██╗███╗ ██╗ ██████╗ ████████╗ █████╗ ██╗ ██╗██████╗ █████╗ ██╔══██╗████╗ ██║████╗ ██║██╔═══██╗╚══██╔══╝██╔══██╗██║ ██║██╔══██╗██╔══██╗ ███████║██╔██╗ ██║██╔██╗ ██║██║ ██║ ██║ ███████║██║ ██║██████╔╝███████║ ██╔══██║██║╚██╗██║██║╚██╗██║██║ ██║ ██║ ██╔══██║██║ ██║██╔══██╗██╔══██║ ██║ ██║██║ ╚████║██║ ╚████║╚██████╔╝ ██║ ██║ ██║╚██████╔╝██║ ██║██║ ██║ ╚═╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝
MARK THE EVIDENCE. KEEP THE CONTEXT. A local-first visual annotation workspace for the open web.
Annotaura adds an edge-mounted Margin Rail to ordinary web pages. Mark passages, draw evidence, add notes, build page-aware projects, and return to reading without covering the page with a conventional dashboard.
This is an original project with its own name, visual language, implementation, and product direction. It is inspired by the general web-annotation category, not copied from another extension.
- What it includes
- Privacy by design
- Quick start
- Install for testing
- User workflow
- Key commands
- Repository structure
- Public distribution
- Development and contribution
- Publishing a release
- Clean-session and alignment contract
- License
- Contact
| Area | Capability |
|---|---|
| Annotation | Select, pen, highlighter, text note, line, arrow, rectangle, ellipse, and numbered evidence stamp. |
| Editing | Move, duplicate, delete, undo, redo with disabled states, Browse mode, custom color picker, palette swatches, stroke width, opacity, and layers. |
| Projects | Page-aware local projects with title, domain, tags, annotation counts, and automatic saving. |
| Workspace | Archive search, Scratch Sheets, JSON import/export, backup, and local data erasure. |
| Shortcuts | Plain letters, Alt + letter, and Ctrl/⌘ + Alt + letter bindings. |
| Shortcut editor | Duplicate detection, real-time conflict warnings, one-click Swap with…, reset defaults, and local persistence. |
| Themes | Paper and Night modes with accessible state labels and reduced-motion support. |
| Compatibility | Shared WebExtensions source for Chrome, Edge, Brave, Opera, and Firefox. |
Annotaura is local-first. The extension does not send annotation content, page URLs, project metadata, or user-created notes to a remote service. Browser storage retains projects and preferences until the user exports or erases them.
The package requests only the permissions needed for its stated actions: activeTab, scripting, storage, downloads, and contextMenus. It cannot operate on browser-controlled pages such as chrome://, edge://, about:, extension stores, New Tab pages, or some internal PDF viewers.
Read the full policy in PRIVACY.md.
Use Node.js 20+ and pnpm 10+.
pnpm install
pnpm extension:build
pnpm extension:packageThe build creates these installable folders and release archives. The source packages use the clean-session lifecycle described later in this document; explicit saved projects remain available in browser storage and Workspace, while ordinary exit does not write the current unsaved canvas.
extension/dist/chromium/ # Chrome, Edge, Brave, Opera
extension/dist/firefox/ # Firefox
extension/dist/annotaura-chromium.zip
extension/dist/annotaura-firefox.zip
- Clone or download this repository.
- Run
pnpm installandpnpm extension:build. - Open the browser's extensions page:
chrome://extensions,edge://extensions, or the equivalent page. - Enable Developer mode.
- Choose Load unpacked.
- Select
extension/dist/chromium. - Open a normal
https://webpage and activate Annotaura from the toolbar.
- Run
pnpm installandpnpm extension:build. - Open
about:debugging#/runtime/this-firefox. - Choose Load Temporary Add-on….
- Select
extension/dist/firefox/manifest.json. - Open a normal webpage and activate Annotaura.
A temporary Firefox add-on is removed after a browser restart. A public Firefox release must be signed through Firefox Add-ons.
Activate Annotaura on a normal web page, choose a tool from the Margin Rail, and draw directly over the page. Open Menu → Margin controls to choose any color with the native color picker or use a palette swatch, then adjust Weight from 1–24 px; highlighter strokes automatically use a broader visual weight while preserving the selected base setting. Annotations are stored in document coordinates, so they remain anchored while the page scrolls; the surface refreshes its document size on scroll, resize, visual-viewport changes, and document resizes. Choose Browse when you want page interaction to pass through. Open Menu for templates, layers, exports, capture, Workspace, themes, and keyboard tools.
Use Undo and Redo in the Margin Rail, or press Ctrl/⌘ + Z and Ctrl/⌘ + Shift + Z (or Y) to correct drawing and highlighting mistakes. The controls disable themselves when no history is available, and a new drawing after undo starts a fresh branch. Open Keyboard shortcuts, then select Customize tool keys to edit a tool binding. Press a plain letter, Alt + letter, or Ctrl/⌘ + Alt + letter. If the combination already belongs to another tool, the editor immediately identifies the conflict and offers Swap with…. Z, Y, deletion, Escape, and browser activation retain their protected roles.
Press ? while Annotaura is active to open the shortcut reference. Press Esc to exit: the active unsaved canvas is cleared immediately and the surface is removed. Re-activating Annotaura starts a blank session. Use Save local, Export JSON, or Workspace tools when you explicitly want to preserve a project.
| Shortcut | Action |
|---|---|
? |
Open the shortcut reference |
S |
Select and reposition a mark |
P / H |
Pen / highlighter |
T |
Text note |
L / A |
Line / arrow |
R / O |
Rectangle / ellipse |
E / B |
Evidence stamp / Browse mode |
Ctrl or ⌘ + Z |
Undo |
Ctrl or ⌘ + Shift + Z or Y |
Redo |
Delete / Backspace |
Delete selected annotation |
Esc |
Cancel, close, or deselect |
extension/
├── src/
│ ├── background/ # MV3 service worker and browser coordination
│ ├── content/ # Shadow-DOM Margin Rail and SVG annotation surface
│ ├── workspace/ # Local archive and Scratch Sheet pages
│ ├── shared/ # Defaults and project helpers
│ ├── assets/ # Original Annotaura icons
│ └── manifest.*.json # Shared, Chromium, and Firefox metadata
└── dist/ # Generated browser packages (built, not committed)
scripts/build-extension.mjs # Cross-browser build
scripts/verify-extension.mjs # Package verification
This repository contains only the browser extension — there is no companion server, database, or hosted landing page. The extension has zero runtime dependencies; the only dev dependency is Prettier for formatting.
| Channel | Use |
|---|---|
| GitHub | Source code, documentation, issues, releases, checksums, and manual-install ZIPs. |
| Chrome Web Store | Public Chrome installation after developer registration, privacy disclosures, listing assets, and review. |
| Microsoft Edge Add-ons | Public Edge installation using the Chromium package and Microsoft's review process. |
| Firefox Add-ons | Signed Firefox distribution through AMO. |
Run pnpm extension:check for JavaScript syntax validation, pnpm extension:build to create both browser packages, and pnpm extension:verify to verify their manifests and required files. Contributions should preserve the local-first privacy model, avoid unnecessary permissions, and validate both Chromium and Firefox outputs.
See CONTRIBUTING.md, PRODUCT_SPEC.md, and ideas.md for project context.
Before publishing, create the required developer accounts: a Chrome Web Store developer account for Chrome, Edge Add-ons Partner Center access for Edge, and a Firefox Add-ons/AMO account for Firefox. Store review may also require a verified email, developer identity or payment verification, privacy disclosures, screenshots, an icon set, a support URL, and a public privacy-policy URL. Annotaura itself does not require an API key because annotation data is local-first.
For each future release, update the extension version in both generated manifest targets through extension/src/manifest.chromium.json and extension/src/manifest.firefox.json, update the release notes, run pnpm extension:check, pnpm extension:build, and pnpm extension:package, then inspect the generated ZIPs. Commit the source and tag the release, for example:
git add .
git commit -m "Release v1.1.0"
git tag -a v1.1.0 -m "Annotaura 1.1.0"
git push origin main --follow-tagsUpload extension/dist/annotaura-chromium.zip to the Chrome Web Store and Edge Add-ons portals, and upload extension/dist/annotaura-firefox.zip to Firefox Add-ons. Complete each portal's listing, privacy, permission, support, and review forms. After approval, link to the official store listings from this README and your GitHub Release notes. Existing users receive store-managed updates when the store accepts a higher version; GitHub/manual users must download the new ZIP and reload or reinstall it.
Annotaura deliberately separates temporary work from explicit saves. Pressing Esc exits and removes the active surface without persisting the current canvas. Re-activation starts blank. Save local, JSON export, and Workspace actions are explicit persistence paths. Annotation geometry is recorded in page document coordinates, and the SVG surface refreshes its dimensions on scroll, browser resize, visual-viewport resize, and document resize so marks stay attached to the corresponding page content during ordinary browsing.
Annotaura is licensed under the MIT License.
⭐ Star this repo if you found it useful ⭐
© 2026 Dev Thakur. All rights reserved.