# Decisions — LexAI

> Lightweight ADRs. One entry per material decision: what, why, what was rejected, when. Newest at top. Supersede rather than rewrite.

## Log

### D-2026-03-06-01 — BYO-LLM-key, no backend

- **Status:** accepted
- **Context:** Hosted writing assistants cost a subscription and route user text through a third party. Target users already hold LLM API keys.
- **Decision:** No LexAI server. The background service worker calls the user's chosen provider (OpenAI/Anthropic/Groq/OpenRouter) directly with the user's key.
- **Alternatives considered:** A thin proxy backend (rejected: adds cost, privacy surface, and an account system); on-device browser AI only (rejected: too limited across providers — noted as a Proofly reference pattern).
- **Consequences:** Zero server cost and strong privacy story; shifts key handling and CORS entirely into the extension; no server-side rate limiting or abuse controls.
- **Verification:** Manual — confirm no network calls leave the extension except to the selected provider endpoint.
- **Owner / date:** Phase 1, 2026-03-06

### D-2026-03-06-02 — Inline styles, no Tailwind

- **Status:** accepted
- **Context:** Content-script UI must not be broken by host-page CSS; WXT PostCSS/Tailwind integration was not wired.
- **Decision:** Style all UI with inline style objects (`Object.assign(el.style, …)` / `style={{…}}`), using a dark Catppuccin-ish palette.
- **Alternatives considered:** Tailwind (left in devDependencies but inactive); shadow DOM + stylesheet (deferred — see D-...-03).
- **Consequences:** Reliable rendering on any host page; palette/button styles get duplicated across content/Options/Popup (refactor tracked in TASKS #5).
- **Verification:** Visual check on multiple sites.
- **Owner / date:** Phase 1, 2026-03-06

### D-2026-03-06-03 — No shadow DOM; `data-lexai` guard instead

- **Status:** accepted
- **Context:** Injected toolbar/modal could collide with host-page styles or re-trigger LexAI's own handlers.
- **Decision:** Inject directly into `document.body`; mark every LexAI node `data-lexai="true"` and skip events whose target is `closest('[data-lexai="true"]')`; use max `z-index` (2147483647).
- **Alternatives considered:** Shadow DOM (rejected for now: added complexity; revisit if style isolation issues appear).
- **Consequences:** Simple and working; weaker isolation than shadow DOM; highly customized editors (e.g. Google Docs) may not accept programmatic replace.
- **Verification:** Manual across textarea/input/contenteditable sites.
- **Owner / date:** Phase 1, 2026-03-06

### D-2026-03-06-04 — Eager selection snapshot before async

- **Status:** accepted
- **Context:** Focus shifts to the toolbar and the live selection is gone by the time an async provider response returns.
- **Decision:** Capture the active element + selection offsets eagerly (on `mouseup` and on button `mousedown`) and snapshot before any `await`; Replace uses the snapshot. Handle both textarea/input (`selectionStart/End`) and contenteditable/DOM (`Range` API).
- **Alternatives considered:** Re-reading selection after the response (rejected: selection no longer exists).
- **Consequences:** Replace works reliably; the pattern is fragile — editing content.ts must preserve snapshot-before-await. Zero automated coverage today (TASKS #10).
- **Owner / date:** Phase 1, 2026-03-06

### D-2026-03-06-05 — Dual `ANALYZE_TEXT` message shapes; `return true` listener

- **Status:** accepted
- **Context:** Content script/popup send `{ payload: {...} }`; other call sites send flat `{ text, action, style }`. Async responses need the message channel held open.
- **Decision:** The handler accepts both shapes; the `onMessage` listener returns `true`. `fix` normalizes to `grammar`.
- **Consequences:** Flexible but must be preserved in both forms; removing `return true` silently breaks all responses.
- **Owner / date:** Phase 1, 2026-03-06

### D-2026-xx-xx-06 — tweetnacl secretbox for the API key (obfuscation, not protection)

- **Status:** accepted — flagged for revisit
- **Context:** Storing the raw key in `chrome.storage.local` looked bad; added tweetnacl `secretbox` encryption (`apiKeyEnc` + `encKey`).
- **Decision:** Prefer the encrypted path; keep plaintext `apiKey` as back-compat until a migration exists.
- **Known weakness:** `encKey` is stored next to `apiKeyEnc`, so anyone who can read storage can decrypt. This is obfuscation, not protection (RECOMMENDATIONS #2).
- **Alternatives to consider:** derive the key from `chrome.storage.session` / WebCrypto / a user passphrase; and be honest in the UI ("stored locally, obscured"). Tracked in TASKS #2.
- **Owner / date:** post-Phase 1

### D-2026-03-06-07 — Gitea CI + Chrome Web Store deploy

- **Status:** accepted
- **Context:** Project hosts CI on Gitea, not GitHub Actions.
- **Decision:** `.gitea/workflows/ci.yml` (typecheck→test→build→zip to registry) and `deploy-chrome.yml` (on `v*.*.*` tag → CWS). Telegram notifications. Version must match in `package.json` and `wxt.config.ts`.
- **Known weakness:** workflows `git clone` into `/tmp` and set `http.sslVerify false` (RECOMMENDATIONS #17). Revisit for speed/security.
- **Owner / date:** Phase 1, 2026-03-06

### D-2026-08-12-08 — CHANGELOG.md drives Gitea release notes

- **Status:** accepted
- **Context:** Releases previously shipped a hardcoded release body (`## LexAI ${VERSION}` + generic install steps) that never said what actually changed in that version.
- **Decision:** Release notes live in `CHANGELOG.md` (Keep a Changelog format, Semantic Versioning). `.gitea/workflows/release.yml` extracts the section matching the pushed tag's version and uses it as the Gitea release body, with a generic fallback if no matching section exists. A version bump is not considered done until `CHANGELOG.md` has that version's section.
- **Alternatives considered:** Auto-generating notes from commit messages (rejected: commit history is not curated for user-facing wording); keeping the hardcoded body (rejected: uninformative to installers).
- **Consequences:** Every version bump now requires a `CHANGELOG.md` entry alongside the `package.json` bump; the release workflow degrades gracefully (generic body + logged warning) if that entry is missed rather than failing the release.
- **Verification:** `release.yml` reviewed by an independent critic; P2 findings fixed. Confirmed locally that the section-extraction logic matches `## [1.1.0]` and stops at the next `## [` heading.
- **Owner / date:** 2026-08-12

## Open / proposed

### D-PROPOSED — Narrow host permissions from `<all_urls>`

- **Status:** proposed (decide before serious Web Store push)
- **Context:** Content script injects into every frame of every site, including banking/email/internal apps; also the #1 CWS review slowdown (RECOMMENDATIONS #1).
- **Options:** `activeTab` + on-demand injection, or a user-configurable allowlist.
- **Verification:** confirm actions still work after narrowing; measure review outcome.