SidePilot

CurrentVersion: 1.0.0

Chinese documentation: docs/README.zh-CN.md

SidePilot is a Chrome Manifest V3 extension that turns the Chrome side panel into a focused workspace for web previewing, page notes, quick captures, and frequently used bookmarks.

Features

• Open http and https links inside the Chrome side panel.
• Save frequently used pages as bookmarks and choose how each bookmark opens.
• Auto-save notes for the current page.
• Capture selected text from the current page into an inbox.
• Search, open, and delete saved notes and captures.
• Switch between mobile and desktop User-Agent modes.
• Diagnose blank pages, embedding failures, and Service Worker related loading problems.
• Use the interface in Simplified Chinese, Traditional Chinese, English, Japanese, French, German, Russian, Spanish, and Portuguese.

Install And Load

SidePilot is currently loaded as a local unpacked extension.

1. Install dependencies:

   npm install

2. Build the extension:

   npm run build

   On Windows, you can also run:

   update-dist.cmd

3. Open chrome://extensions/ in Chrome.

4. Enable Developer mode.

5. Click "Load unpacked".

6. Select the project's dist/ directory.

Load only dist/, not the repository root. The minimum supported Chrome version is 116.

Basic Usage

• Click the extension icon or press Alt+Z to open SidePilot.
• Drop a web link into the link preview area to open it in the side panel.
• Click the plus button in the bookmark rail to add a bookmark. You can enter only a link; SidePilot will fetch the title and icon automatically.
• Choose a bookmark open mode: side panel, No SW reload, main window, or independent window.
• Write page notes normally; SidePilot saves them automatically.
• Click "Save as item" to turn the current note into an inbox item.
• Select text on a web page, then use "Capture selection" or the context menu to save it to SidePilot.
• If a page stays blank, use "Diagnose" from the settings menu, then switch the bookmark open mode or open it in the main window.

On first launch, SidePilot seeds bookmarks for Google, Gmail, Keep, Outlook, Gemini, and ChatGPT. You can edit, delete, or reorder them.

Data And Privacy

SidePilot does not include a project-owned backend service. Bookmarks, notes, captures, page state, and icon cache data are stored in local browser extension storage.

When you open a page, fetch a page title, or fetch a favicon, Chrome sends requests to the target site. Diagnostics run only after you trigger them. Flows that need extra permissions, such as No SW reload or deeper diagnostics, ask through Chrome's permission prompt first.

Permissions

• sidePanel: shows the Chrome side panel.
• storage: stores bookmarks, notes, captures, page state, and icon cache data.
• scripting: reads selected text only when you trigger capture.
• contextMenus: adds the "Save selection to SidePilot" context menu item.
• declarativeNetRequestWithHostAccess: installs temporary rules for side-panel loading, User-Agent switching, and embedding compatibility.
• host_permissions: allows user-opened http and https pages to load, diagnose, and provide titles or icons.
• browsingData, declarativeNetRequestFeedback, webRequest: requested only when you trigger No SW reload or diagnostics that need them.

Troubleshooting

Chrome Reports Missing Scripts

Run npm run build or update-dist.cmd, then reload the extension in chrome://extensions/. Make sure the loaded directory is dist/.

A Page Is Blank In The Side Panel

Some websites block third-party embedding or depend on login state, redirects, or Service Workers. Use "Diagnose" first, then try "Open in main window", "Open in independent window", or set the bookmark to "No SW reload".

Keyboard Shortcut Conflict

Open SidePilot settings, choose "Keyboard shortcuts", and change Alt+Z in Chrome's extension shortcut page.

Developer Commands

npm install
npm run sync:version
npm run dev
npm run build
npm run verify

• npm run sync:version syncs manifest.json, package.json, package-lock.json, and README version lines from the root VERSION file.
• npm run dev starts TypeScript watch and the CRXJS/Vite development server.
• npm run build writes a loadable extension package to dist/.
• npm run verify runs type checks, packaging, manifest / locale / dist checks, and core rule regressions.
• requirements.txt records npm dependency constraints.

Only edit the root VERSION file by hand. npm run dev, npm run build, and npm run verify sync the generated version fields first.

Maintainer Entry Points

• manifest.json: Chrome MV3 configuration, permissions, shortcuts, Side Panel entry, and CSP.
• sidepanel.html / sidepanel.css: side panel document structure and styles.
• src/entry/sidepanel.ts: side panel UI, user interaction, and page state coordination.
• src/entry/service-worker.ts: Chrome background events, messages, DNR installation, diagnostics, and capture entrypoint.
• src/domain/: URL, navigation policy, DNR rule, and favicon domain rules.
• src/sidepanel/: bookmarks, notes, captures, icon cache, menus, permissions, and persistence boundaries.
• src/worker/: Service Worker message classification and Side Panel rule leases.
• src/infrastructure/: IndexedDB app-state repository.