# KeyPilot — extension sources

Product overview and the generated default key map live in the repository [`README.md`](../README.md). This file is the development map for code under `extension/`.

## Build

From the repository root:

```bash
npm run build
```

Or from this directory: `node build.js`.

That regenerates `content-bundled.js`, `frame-agent-bundled.js`, `pages/docs-bundled.js`, and `pages/settings-bundled.js`. Edit `src/` (and `background.js`); do not edit the bundled outputs. Settings and Docs are loaded from those page bundles when opened, not from the eager content script.

Optional:

- `npm run build:macro-builder` — enable the Macro Builder UI
- `npm run build:minify` — also write minified content (not for Opera review packages)

Reload the unpacked extension after each build.

## Project layout

```
keypilot-chrome-extension/
├── README.md                 # Product docs + generated key mappings
├── package.json              # Build/audit scripts and dependencies
├── refs/                     # Internal architecture and store-checklists
├── scripts/                  # Docs screenshot capture, etc.
└── extension/                # Load this folder as the unpacked extension
    ├── manifest.json
    ├── background.js         # MV3 service worker (ES module)
    ├── early-inject.js       # document_start cursor/shell
    ├── content-bundled.js    # Generated from src/content-script.js
    ├── frame-agent-bundled.js
    ├── build.js
    ├── build-side-effects.js
    ├── popup.html / popup.js
    ├── src/
    │   ├── content-script.js
    │   ├── keypilot.js
    │   ├── config/           # constants, layouts, function library
    │   ├── modules/
    │   ├── ui/
    │   ├── utils/            # includes debug.js (release-gated logging)
    │   └── messaging/
    ├── pages/                # Settings, guide, new tab, docs, popovers
    ├── userdocs/             # In-product markdown topics
    ├── themes/
    ├── icons/
    └── styles/popup.css
```

`extension/src/` is the source of truth for content-script behavior. `docs/`, `tests/`, `test-pages/`, and `src/utils/logger.js` from older trees are gone; in-product help is `userdocs/`, and verbose logging is `src/utils/debug.js` plus Settings → About → Debug logging.

## Debug logging

Store/release builds keep debug **off**. Enable **Settings → About → Debug logging** to restore verbose `console.log` / `console.debug` / `console.info` in the service worker and page consoles. Warnings and errors are never gated. Compile-time `FEATURE_FLAGS` debug HUDs stay false unless you change them in `src/config/constants.js`.

## Release cadence (dependencies)

Before each store package:

1. `npm run audit` (production dependencies; currently `markdown-it`, `query-selector-shadow-dom`, `terser`)
2. `npm outdated` and bump if there is a security fix or a required API change
3. Record the audit date, npm audit summary, and any upgrades in the release record

See `refs/OPERA_GX_PUBLICATION_CHECKLIST.md` Phase 4.

## License

MIT — see the repository README. Add a `LICENSE` file before store submission if one is still missing at the repo root.
