qapture2 0.2.3 → 0.3.0

package/README.md

@@ -14,10 +14,15 @@ npm install qapture2
 
 ## Contents
 
+- [Breaking Changes (v0.3.0 "Graphite")](#breaking-changes-v030-graphite)
 - [Quick Start](#quick-start)
 - [Config Reference](#config-reference)
 - [Graded Risk Model](#graded-risk-model)
+- [Guided Walkthrough (Test-Along)](#guided-walkthrough-test-along)
+- [Severity, Status, and Copy as Agent Prompt](#severity-status-and-copy-as-agent-prompt)
 - [Export and AI Handoff](#export-and-ai-handoff)
+- [Runtime Context Capture](#runtime-context-capture)
+- [Notices and Undo](#notices-and-undo)
 - [CLI](#cli)
 - [Launcher Gating](#launcher-gating)
 - [Browser and SSR Support](#browser-and-ssr-support)
@@ -27,6 +32,38 @@ npm install qapture2
 
 ---
 
+## Breaking Changes (v0.3.0 "Graphite")
+
+**v0.3.0 is a breaking release.**
+
+- **Custom themes are removed.** The widget now ships one fixed, self-contained
+  dark design ("Graphite") — there is no more per-project colour override. A
+  `theme` key left in `qa.config` is no longer read; `validateConfig` ignores
+  it and pushes this exact warning:
+
+  > theme: custom themes were removed in Qapture 0.3.0 — the widget now ships
+  > one fixed, self-contained design. The "theme" key is ignored; remove it
+  > from your qa.config to silence this warning.
+
+  Delete the `theme` block from your config — see the updated
+  [`examples/minimal.config.ts`](./examples/minimal.config.ts) and
+  [`examples/stitch-and-sell.config.ts`](./examples/stitch-and-sell.config.ts),
+  both of which had their `theme` block removed entirely. The `QaTheme` type
+  is still exported so old config objects keep type-checking, but it is
+  `@deprecated` and has no runtime effect — see [`QaTheme`](#qatheme-deprecated).
+- **New:** a guided, step-by-step walkthrough over your journey ("test-along"),
+  severity + status on notes, a one-click "Copy as agent prompt", and an
+  undo-capable delete/clear system. See the sections below.
+- **New, and worth reading if you care about privacy:** an (on-by-default,
+  opt-out) runtime context capture that records recent console errors and
+  failed network calls into each note. See
+  [Runtime Context Capture](#runtime-context-capture) and
+  [SECURITY.md § Runtime context capture](./SECURITY.md#runtime-context-capture).
+
+Full details: [CHANGELOG.md](./CHANGELOG.md#030-graphite--unreleased).
+
+---
+
 ## Quick Start
 
 ### React (any)
@@ -118,7 +155,7 @@ All fields are optional. Passing an empty object (or no config at all) produces
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `namespace` | `string` | `'qapture'` | Prefix for IndexedDB (`${namespace}-db`) and localStorage keys (`${namespace}:*`). Use a unique value per project to avoid storage collisions on the same origin. |
-| `theme` | `Partial<QaTheme>` | See QaTheme defaults | Override any subset of the 9 colour tokens. Unspecified tokens keep their defaults. |
+| `theme` | `Partial<QaTheme>` (**deprecated, ignored**) | — | **Removed in v0.3.0.** `validateConfig` ignores this key (after pushing a warning) — the widget always renders the fixed Graphite design. Delete it from your config. See [Breaking Changes](#breaking-changes-v030-graphite). |
 | `brand` | `{ label?: string }` | `{ label: 'Qapture' }` | Panel heading label. |
 | `loginField` | `{ en: string; ar?: string }` | `{ en: 'Username', ar: 'اسم المستخدم' }` | Display label for the login column in the Credentials tab. |
 | `credentials` | `QaCredential[]` | `[]` | DEV/TEST/SEED login rows shown in the Credentials tab. |
@@ -128,22 +165,18 @@ All fields are optional. Passing an empty object (or no config at all) produces
 | `visible` | `boolean \| undefined` | `undefined` | `true` = always show; `false` = always hide; `undefined` = dev-only (hidden in production). |
 | `alwaysVisible` | `boolean` | `false` | When `true`, overrides `visible` and shows the panel even in production. |
 | `hotkey` | `string` | `'shift+alt+q'` | Keyboard shortcut that toggles the panel open/closed. |
+| `captureContext` | `boolean` | `true` | Whether to record ambient runtime context (recent console errors/warnings, uncaught errors, failed network calls, and an environment snapshot) into each note as it's captured. Set to `false` to disable entirely. See [Runtime Context Capture](#runtime-context-capture). |
 
-### `QaTheme`
-
-Nine CSS custom-property tokens (`--qa-*`) that control the widget chrome. All values are CSS color strings.
+### `QaTheme` (deprecated)
 
-| Token | Default | Role |
-|---|---|---|
-| `primary` | `#4f46e5` | Primary buttons, active states |
-| `primaryDark` | `#3730a3` | Hover / pressed states |
-| `accent` | `#7c3aed` | Highlights, badges |
-| `accentDark` | `#6d28d9` | Accent hover |
-| `sage` | `#6b7280` | Muted text, borders |
-| `cream` | `#f8fafc` | Panel background |
-| `mauve` | `#a78bfa` | Soft decorative surfaces |
-| `surface` | `#ffffff` | Cards, inputs |
-| `ink` | `#1f2937` | Body text |
+> **Removed in v0.3.0.** The widget no longer accepts a custom theme — it
+> ships one fixed, self-contained dark design ("Graphite") built into the
+> stylesheet itself. `QaTheme` and `QaConfig.theme` are still exported so
+> pre-0.3 config objects continue to type-check without edits, but both are
+> marked `@deprecated` and have **no effect** on the rendered UI. Nine colour
+> tokens (`primary`, `primaryDark`, `accent`, `accentDark`, `sage`, `cream`,
+> `mauve`, `surface`, `ink`) used to be overridable here; there is nothing to
+> configure in their place.
 
 ### `QaCredential`
 
@@ -230,15 +263,45 @@ When there are no red steps the score is vacuously Complete. The receiving agent
 
 ---
 
+## Guided Walkthrough (Test-Along)
+
+Ticking journey steps one at a time in the Guide tab works, but on a long journey it's easy to lose your place. **Test-along** turns the same `journey` config into a guided, step-by-step mode:
+
+1. Open the **Guide** tab and press **"Start walkthrough"** (`start_walkthrough`). The panel closes and is replaced by a compact bottom bar — the Notes/Logins/Guide panel is hidden while a walkthrough is active.
+2. The bar shows **"Step *n* of *m*"** (`step_of`), the current step's instructions (`what`), and — when the step defines one — its `expect` text (`expected_label`): what a pass actually looks like.
+3. **"Back" / "Next"** (`prev_step` / `next_step`) move between steps; the buttons are direction-aware (their chevrons flip in RTL).
+4. **"Pass" / "Fail"** (`mark_pass` / `mark_fail`) grade the current step. A pass adds the step to the same `guideChecked` set the Guide tab shows; a fail records it in a parallel `guideFailed` set (persisted the same way, under `${namespace}:guideFailed`) so a step can be visibly flagged red without losing its place in the checklist.
+5. **"Capture here"** (`capture_here`) starts a capture without leaving the walkthrough. Any note captured while test-along is active is **automatically linked** to the current step — no manual tagging, no picking a route from a dropdown.
+6. **"Exit"** (`exit_walkthrough`) closes the walkthrough and returns to the normal panel.
+
+Back in the Guide tab, each step shows an evidence badge — **"{n} attached"** (`evidence_n`) when notes are linked to it, or, if the step was marked Pass with nothing ever captured against it, **"ticked, no capture"** (`no_evidence`, shown in the warn tint) as a gentle nudge that a checked box isn't the same thing as an annotation the receiving agent can act on.
+
+---
+
+## Severity, Status, and Copy as Agent Prompt
+
+Every note (quick note or captured point) can now carry:
+
+- **Severity** — `bug` (default), `question`, or `polish` (`sev_bug` / `sev_question` / `sev_polish`), set from a chip row shown both on the quick-note form and on the capture-mode annotation card.
+- **Status** — `open` (default) or `verified` (`status_open` / `status_verified`), toggled with a single tap directly on each note's card in the Notes tab — useful for marking a point re-checked without deleting it.
+
+Both fields ride along into the export: each `## Point N` in `notes.md` gets a `Severity` and `Status` line (see [ZIP layout](#export-and-ai-handoff) below), and a note linked to a journey step (by test-along or by route match — see below) gets a `Journey step` line too.
+
+**Copy as agent prompt** (`copy_prompt`) puts a *single* note on the clipboard, rendered through the exact same Markdown template used for each point in the exported ZIP (`noteToMarkdown()`), including its runtime context block. Use it to hand one finding to a terminal agent without doing a full export. A `copied` / `copy_failed` toast confirms the result.
+
+Outside test-along, a captured note is also auto-linked to a journey step whenever the current route matches one: `matchRouteToSteps()` checks the page's route against every step's `path` (treating `:param` / `[param]` segments as wildcards), preferring an exact match over a parameterised one.
+
+---
+
 ## Export and AI Handoff
 
 ### The workflow
 
-1. **Capture** — click an element or drag a region on the live page. Qapture auto-screenshots the visible page, opens the note editor. Write a description; save.
-2. **Guide** — tick steps in the journey as you walk through them. The Guide tab tracks red-zone coverage and shows the current tier.
-3. **Export** — click Export in the panel. A `qa-notes-<timestamp>.zip` downloads to your machine. Give it a meaningful name.
+1. **Capture** — click an element or drag a region on the live page (or press "Capture here" mid-[walkthrough](#guided-walkthrough-test-along)). Qapture auto-screenshots the visible page and opens the note editor. Write a description, optionally set severity, save.
+2. **Guide** — tick steps in the journey as you walk through them, or run the guided [Test-Along](#guided-walkthrough-test-along) walkthrough instead. The Guide tab tracks red-zone coverage and shows the current tier.
+3. **Export** — click Export in the panel. A `qa-notes-<timestamp>.zip` downloads to your machine. Give it a meaningful name. (For a single finding, "Copy as agent prompt" on any note skips the ZIP entirely — see [above](#severity-status-and-copy-as-agent-prompt).)
 4. **Handoff** — drop the ZIP into your terminal coding agent's context. If you use Claude Code, the `.claude/skills/qapture/SKILL.md` the CLI generated (or the `AGENTS.md` snippet) primes the agent automatically when the ZIP is attached.
-5. **Agent acts** — the agent reads `notes.md`, internalises the preamble (project context, theme tokens, dev credentials, red-zone coverage, invariants), flags any uncovered RED steps, then works through each `## Point N` annotation: locates the code via the selector + screenshot, makes the change, verifies it in the running app, and produces a graded summary.
+5. **Agent acts** — the agent reads `notes.md`, internalises the preamble (project context, dev credentials, red-zone coverage, invariants), flags any uncovered RED steps, then works through each `## Point N` annotation: locates the code via the selector + screenshot, reads the severity/status/runtime-context evidence, makes the change, verifies it in the running app, and produces a graded summary.
 
 ### ZIP layout
 
@@ -260,7 +323,6 @@ qa-notes-<timestamp>.zip
 > one-liner
 
 ## Project       (name, stack, run commands)
-## Theme Tokens  (9-token colour table)
 ## Conventions   (numbered codebase rules)
 ## Login Context (DEV/TEST/SEED credentials table + warning)
 ## Coverage Report (red/amber/green totals + uncovered RED list)
@@ -274,22 +336,82 @@ qa-notes-<timestamp>.zip
 
 ## Point 1
 - **Page:** /some-route
-- **Selector:** `#element-id`
+- **Full URL:** https://…               (only when it differs from Page)
 - **When:** <timestamp>
+- **Severity:** bug                     (bug | question | polish)
+- **Status:** open                      (open | verified)
+- **Journey step:** buyer → /checkout   (when linked — test-along or route match)
+- **Target:** element
+- **Selector:** `#element-id`
 - **Screenshot:** screenshots/point-1.png
 
 Tester's note text...
 
+<details><summary>Runtime context at capture</summary>
+
+```
+viewport   1440×900 @2x
+language   en-US
+timezone   Asia/Baghdad
+online     true
+pageLoad   842ms
+userAgent  Mozilla/5.0 …
+
+events (3, most recent last):
+  [-2.1s] console.error: TypeError: Cannot read properties of undefined (reading 'total')
+  [-1.8s] POST https://example.com/api/checkout?… → 500 (340ms)
+  [-0.2s] uncaught: TypeError: Cannot read properties of undefined (reading 'total')
+```
+
+**Element forensics**
+
+```
+html    <button class="checkout-btn" disabled>Place order</button>
+display inline-flex
+…
+a11y    accessibleName=true tabReachable=true contrast=ok
+```
+
+</details>
+
 ---
 
 ## Point 2
 ...
 ```
 
+(The **Theme Tokens** section from pre-0.3.0 exports is gone — v0.3.0 has no per-project theme to embed. The runtime-context block is present only when [Runtime Context Capture](#runtime-context-capture) is enabled and something was recorded.)
+
 The preamble degrades gracefully — sections with no data are marked `(not provided)` rather than omitted, so the agent always receives the full structure.
 
 ---
 
+## Runtime Context Capture
+
+Every note (unless disabled) automatically carries a small slice of what the browser was doing right before it: recent `console.error`/`console.warn` calls, uncaught errors and unhandled promise rejections, and failed or slow `fetch`/`XMLHttpRequest` calls — plus a one-time environment snapshot (viewport, language, timezone, online state, page-load time, and, where available, JS heap size). It turns "the button does nothing" into "the button does nothing, and here's the console error and the 500 that happened at that moment" — see [`src/lib/contextBuffer.ts`](./src/lib/contextBuffer.ts).
+
+This is genuinely new privacy-relevant surface, and it is documented in full — including the exact guarantees (query strings redacted, bodies/headers/cookies/storage never touched, ring buffer capped at 75 events) — in **[SECURITY.md § Runtime context capture](./SECURITY.md#runtime-context-capture)**. Read it before shipping this to a tester on a real project.
+
+Disable it entirely with:
+
+```ts
+const config: QaConfig = {
+  captureContext: false,
+};
+```
+
+With this set, nothing is ever wrapped or recorded, and no runtime-context block appears in the export or in "Copy as agent prompt".
+
+---
+
+## Notices and Undo
+
+Deleting a note or clearing all notes is no longer instant and irreversible. Both actions remove the item from the UI immediately, but the real IndexedDB write is deferred 5 seconds behind a toast with an **Undo** (`undo`) button — press it inside that window and the note (or the whole list) comes back at its original position. Closing the tab, or the host app unmounting `<Qapture>`, flushes any pending deletes right away, so nothing is ever silently lost or silently resurrected after the fact.
+
+The same toast system (`notices`) reports a handful of other outcomes that previously had no UI to surface through: a full IndexedDB quota (`persist_failed`), export success/failure (`export_done` / `export_failed`), clipboard copy success/failure (`copied` / `copy_failed`), and a failed screenshot with a `retry` action. At most 3 toasts queue at once; a 4th drops the oldest.
+
+---
+
 ## CLI
 
 The CLI scaffolds `qa.config`, the agent skill, and `AGENTS.md` into any repository. It is **deterministic, AI-free, and network-free** — no model call, no network request, no `require()`-ing of target project files.
@@ -306,9 +428,8 @@ npx qapture2 version
 | Step | What happens |
 |---|---|
 | Route detection | Scans `src/`, `app/`, `pages/` for route files; generates journey lanes with placeholder `'green'` steps for you to grade |
-| Theme detection | Reads `tailwind.config.*` and CSS files for colour values |
 | Credential detection | Scans `.env.example` and seeder/seed files for test logins. **Never reads `.env`, `.env.local`, `.env.production`, or any real secrets file** — enforced by a hard blocklist |
-| `qa.config.js` / `.ts` | Generated based on detections; contains TODO comments for manual grading |
+| `qa.config.js` / `.ts` | Generated based on detections; contains TODO comments for manual grading. No `theme` block is emitted — v0.3.0 removed custom themes entirely (see [Breaking Changes](#breaking-changes-v030-graphite)) |
 | `qa.preamble.md` | Starter preamble file; fill with project context and paste into `config.preamble` |
 | `.claude/skills/qapture/SKILL.md` | Claude Code agent skill (always refreshed — this is a vendor artifact) |
 | `AGENTS.md` | Idempotent merge with sentinel guards; safe to run repeatedly |
@@ -371,6 +492,7 @@ The **hotkey** (default: `Shift+Alt+Q`) toggles the panel open/closed regardless
 
 - **Zero AI, zero network, zero keys.** No model is bundled; no API calls are made; no telemetry is collected.
 - **Data stays in the browser** until the tester explicitly exports a ZIP. Nothing is ever transmitted.
+- **Runtime context capture** (new in v0.3.0) records recent console/network events into each note for the receiving agent — query strings are redacted, bodies/headers/cookies/storage are never touched, and it can be disabled entirely with `captureContext: false`. See [Runtime Context Capture](#runtime-context-capture) and [SECURITY.md § Runtime context capture](./SECURITY.md#runtime-context-capture).
 - **Credentials are DEV/TEST/SEED only.** The `credentials` config field and the Login Context in the export are intended exclusively for non-production environments.
 - **The CLI never reads real secrets.** A hard path blocklist prevents the CLI from reading `.env`, `.env.local`, `.env.production`, certificate files, or any file under `/secrets/`, `/keys/`, `/credentials/`. Only `.env.example` and seeder files are scanned.