# Bug Ticket Flow TraceBug treats a recording cycle as a single **bug ticket**. Screenshots, voice notes, screen recording, and captured events accumulate in the ticket; nothing is downloaded until the user explicitly exports. This document explains the full step-by-step flow, what each surface does, and the options available at each step. > **v1.0 update β€” Sentry Mode is the recommended flow.** The traditional one-shot `startRecording β†’ stopRecording` flow still works, but for QA who need to file multiple bugs in one session, **arm Sentry mode once at the start and use πŸ“Έ Capture instead of stopping between bugs.** See [Sentry Mode](#sentry-mode-rolling-video-buffer) below. --- ## The classic flow (one bug per session) ``` startRecording() ↓ user reproduces the bug β€’ clicks, inputs, navigation, network, errors β†’ captured automatically β€’ toolbar Camera button β†’ screenshot added to ticket β€’ toolbar Region button β†’ drag-to-crop, added to ticket ↓ stopRecording() ──auto-opens──> Ticket-Review Modal ↓ review title + description review numbered screenshot gallery ↓ click an export action (GitHub / Jira) ↓ clipboard payload + every screenshot downloads (PNG, staggered 120ms) ``` --- ## Sentry Mode (rolling video buffer) The new default for video recording. Click **πŸ”΄ Record** once, file as many bug tickets as you want from the same screen-share. Inspired by NVIDIA Shadowplay / OBS replay buffer. ``` TraceBug.startVideoRecording() β†’ OS screen-picker β†’ HUD pill appears ↓ user reproduces bug A β€’ types comments in HUD β†’ timestamped to recording time β€’ toolbar Camera / Region β†’ screenshots added to ticket ↓ clicks πŸ“Έ Capture in HUD ──or── JS error fires + toast β†’ "Capture with video" ↓ captureRollingBuffer() ──opens──> Ticket-Review Modal (with embedded video) ↓ export β†’ screenshots + .webm download, ticket markdown copied ↓ recording is STILL RUNNING β€” comments reset for the next bug ↓ [ user finds bug B β†’ πŸ“Έ Capture again β†’ another ticket ] ↓ clicks ⏹ Stop β†’ if any captures were taken, ends silently if none, opens the modal with the full recording ``` ### What's in the HUD | Element | Behavior | |---|---| | Pulsing red dot + timer | Visual proof recording is active | | `N captured` chip | Increments on each `πŸ“Έ Capture`. Hidden in `mode: "standard"` | | Comment input | Type β†’ press Enter β†’ saved with current `offsetMs` to the active recording | | πŸ“Έ Capture button | Snapshots into a `VideoRecording`, opens ticket modal, recording continues | | ⏹ Stop button | Ends the screen-share. Smart modal-open behavior (see above) | ### Auto-capture on error When an unhandled JS error fires *and* a rolling session is armed, the existing error-detected toast switches its action label from `Capture bug` β†’ `Capture with video`. Clicking calls `captureRollingBuffer()` automatically β€” no need to spot the bug yourself. ### What gets attached to the ticket - The captured `.webm` (Blob URL, in-memory) - Comments (each: `{ offsetMs, text }`) cleared after each capture so each ticket gets its own - All screenshots taken since the modal was last closed - Auto-generated title, smart summary, root-cause hint, environment, console errors, network failures β€” same as classic flow The exporters (GitHub markdown / Jira / PDF) all gained a "Screen Recording" section listing the auto-downloaded `.webm` filename, duration, file size, and timestamped comments. The blob auto-downloads alongside screenshots on every export action. > **API:** `TraceBug.startVideoRecording({ mode: "rolling" })`, `TraceBug.captureRollingBuffer()`, `TraceBug.stopVideoRecording()`. Full reference: [api-reference.md β†’ Sentry Mode](api-reference.md#sentry-mode-rolling-video-buffer). --- ## Auto-Scanner (parallel detector path) Independent of the recording flow. Click **πŸ” Scan** to run six detectors and surface issues you might not have noticed: ``` TraceBug.scanPage() ↓ runs in parallel: a11y (axe-core), broken images, mixed content, console errors, failed requests, slow APIs ↓ issues panel opens with severity buckets (critical / serious / moderate / minor) ↓ per-issue actions: πŸ“ Locate β†’ scroll into view + 2.4s purple flash on the element File ticket β†’ pre-fills Quick Bug modal with issue title + description Dismiss β†’ hide for this session (in-memory only) ``` > **API:** [api-reference.md β†’ Auto-Scanner](api-reference.md#auto-scanner). Issues live in memory only; reload = fresh scan. --- ## Step 1 β€” Start ```js TraceBug.startRecording(); // alias for resumeRecording() ``` By default, recording is on after `TraceBug.init()`, so most users never need to call this. Use it after a `stopRecording()` to begin a new ticket. The session continues using the same `sessionId` β€” the "ticket" boundary is the recording window, not a new session. --- ## Step 2 β€” Capture While recording, the floating toolbar on the right edge of the page surfaces two screenshot actions: | Button | Tooltip | Behavior | |--------|---------|----------| | **Camera** | "Screenshot (Ctrl+Shift+S) β€” added to ticket" | Captures full viewport (uses `chrome.tabs.captureVisibleTab` in extension context, html2canvas otherwise). Adds to ticket. | | **Corner-square** | "Region Screenshot β€” drag to select, added to ticket" | Shows a fullscreen overlay; user drags a rectangle; cropped PNG (DPR-aware) is added to ticket. `Esc` cancels. | Toast confirms the addition: > Added to ticket Β· 3 screenshots The screenshots live in an in-memory ring buffer (cap: 50) accessible via `TraceBug.getScreenshots()`. **Nothing is written to disk at this stage.** Other capture surfaces during the same window: - **Click / input / navigation** β†’ tracked automatically by the SDK collectors - **Voice notes** β†’ `TraceBug.startVoiceRecording(...)` (Web Speech API, transcript only) - **Element annotations / draw mode** β†’ toolbar buttons; live alongside screenshots in the ticket --- ## Step 3 β€” Stop & review ```js TraceBug.stopRecording(); ``` This pauses event capture **and** auto-opens the ticket-review modal. (Equivalent to clicking the recording toggle in the toolbar.) The modal β€” header **"Bug Ticket β€” Review & Export"** β€” shows: | Region | Content | |--------|---------| | **Title** | Auto-generated from session context (`generateBugTitle`); editable | | **Description** | Auto-generated: root cause hint, summary, recent steps, error, failed network requests, environment; editable | | **Primary preview** | The first screenshot in the ticket, full-width | | **Thumbnail strip** | Numbered (1, 2, 3, …) thumbnails of every other screenshot. Click a thumbnail to swap it into the primary preview. | | **Header count** | "N screenshots attached Β· download/copy includes all screenshots" | Drafts auto-save to `localStorage` under `tracebug_last_bug_draft`; if you accidentally close the modal, the next open recovers the title + description. **Closing is deliberate.** A click on the dimmed background never closes the ticket (it shows a hint). βœ• or Esc on an unsaved ticket asks "Close this ticket?" (Keep editing / Close / Save and close); a saved or exported ticket closes at once, and so does a close triggered by code (a new session starting, opening a saved ticket). A closed, unsaved ticket is the latest session, so **Saved tickets** on the toolbar shows it at the top ("Unsaved Β· kept until your next capture") with **Reopen**. Only one is ever offered: the next capture replaces it. This adds no storage: it is the session that already exists, and the never-evict-saved-tickets rule is unchanged. e2e: `ticket-view`. --- ## Step 4 β€” Export The modal footer exposes the primary exports, with the rest under **More β–Ύ**: | Action | Output | |--------|--------| | **Export .html** | Self-contained interactive DOM replay (rrweb) β€” KB, not MB. The canonical artifact to hand a developer or an MCP-connected agent. | | **Export HAR** | Network capture as a standard HAR 1.2 file. | | **Fix with AI** | Builds the structured prompt and opens Claude / ChatGPT (or runs BYO-key analysis in the AI tab). | | **Open in GitHub** _(npm SDK, when `githubRepo` is set but no token is configured)_ | Opens a prefilled GitHub issue page in a new tab. | | **Send to GitHub** _(when a BYO-token GitHub integration is configured)_ | Files the issue directly β€” in the extension through its **Create an issue** window, where you pick the tracker, repository/team and labels (nothing leaves the browser until you click Create; the issue then opens in a new tab), or a direct API call in the SDK. Same button as above; the label switches to "Send to …" whenever this is the case. | | **Download .zip (attach to GitHub)** _(More)_ | The same replay `.html` wrapped in a `.zip` β€” GitHub issues accept `.zip` attachments by drag-and-drop but reject bare `.html`. The prefilled issue body includes a "drag the zip here" placeholder. | | **Download failing test (.spec.ts)** _(More)_ | A runnable Playwright spec that replays the session and asserts the captured failure is gone β€” red until the bug is fixed, green after. Also embedded in the `.html` export for the MCP `get_playwright_test` tool. | | **Export for AI (.html)** _(More)_ | Tiny (~5 KB) text-only HTML β€” paste/upload into a chat, no MCP needed. | | **Download report (.md)** _(More)_ | Compact markdown report. | | **Download screenshots** _(More)_ | Raw PNG(s) to attach alongside the `.md`. | | **Send to GitHub / Linear / Slack** _(More, when that provider's BYO token is configured)_ | Files a real issue/message with the configured token. Unconfigured, these read "Open in …" (Linear) or "Copy … Issue/Message" (GitHub/Slack) instead. | | **Copy for Jira** _(More)_ | Always copy-only β€” Jira's API is CORS-blocked for browser calls, so there's no live-send path for it. | The full replay `.html` is built for a human browser and the MCP reader; **Export for AI (.html)** / **`.md`** are the small, chat-safe artifacts for pasting into an AI chat. Toast shows the count: > βœ“ Copied as GitHub Issue Β· downloading 3 screenshots After a successful export, the modal closes after 300ms and the draft is cleared. --- ## Step 5 (optional) β€” Save Ticket (local, offline) **Save Ticket** in the modal footer persists the ticket in the browser's `localStorage` (`src/storage.ts`) β€” no account, no upload, no expiry. Saved tickets appear in the toolbar's **Saved Tickets** popover with thumbnail, event/screenshot counts, per-ticket size, an **Export** action (self-contained `.html` replay), and a two-click **Delete**. What gets saved: events (≀200), annotations, environment, error/repro metadata, priority, and up to 5 screenshots. Video is **not** persisted locally. The popover footer shows a storage meter: usage against the ~5 MB localStorage budget, plus an estimate of how many more tickets fit (based on the median size of your own saved tickets). **Known limitation:** the meter counts only TraceBug's data, but the ~5 MB quota is per-origin and shared with the host page's own localStorage β€” on sites that store a lot themselves, writes can fail earlier than the meter suggests. ### Storage invariants (do not break these) These rules are load-bearing for user trust β€” enforced in `src/storage.ts` and covered by `tests/storage.test.ts`: 1. **Saved tickets never disappear automatically.** No LRU eviction, no TTL, no silent cleanup. Only the ticket's own Delete button or "Clear All Data" removes them. Quota-pressure eviction and the `maxSessions` rotation only ever touch *unsaved* sessions. 2. **Save is verified before success is shown.** `markSessionSaved` confirms the write persisted; the UI never claims "Saved" on a failed write. 3. **Users are warned before degradation.** A `near_full` warning fires at ~90% usage β€” before saves start failing, not after. 4. **Degradation is always visible.** Every eviction / trim / refusal emits a `tracebug:storage-warning` event, surfaced as a toast. A screenshot-less fallback save is permanently marked on the ticket (`screenshotsDropped`) and shown on its card. 5. **Saved data is never corrupted to make room.** If storage is full of saved tickets, new writes are refused rather than partially overwriting what's on disk. 6. **Export always works offline.** The `.html` replay export from the saved list has no network dependency. > **Roadmap:** the single planned storage change is migrating saved tickets to IndexedDB (v2.0) β€” primarily to isolate long-term storage from the live recording pipeline's quota, secondarily for capacity. Feature additions (search, pins, archive, cleanup tools) wait for real-user feedback after that migration. > > **Migration trigger:** storage-pressure events are counted locally (never transmitted) β€” `TraceBug.getStorageStats()` returns per-code counts (`near_full`, `storage_full`, `unsaved_evicted`, `events_trimmed`, `screenshots_dropped`). When users report these filling up, start v2.0. --- ## Equivalents & shortcuts | Goal | Trigger | |------|---------| | Open the ticket-review modal anytime | `Ctrl+Shift+B`, the ⚑ toolbar button, or `TraceBug.quickCapture()` | | Stop recording without opening the modal | `TraceBug.pauseRecording()` (the silent variant) | | Resume recording without UI | `TraceBug.resumeRecording()` | | Get the screenshot list programmatically | `TraceBug.getScreenshots()` | | Clear all screenshots | "Clear All Data" in the toolbar settings, or `clearScreenshots()` | --- ## Programmatic API ```ts import TraceBug, { captureRegionScreenshot, getScreenshots } from "tracebug-sdk"; TraceBug.init({ projectId: "demo", githubRepo: "owner/repo" }); TraceBug.startRecording(); // during the bug repro: await TraceBug.takeScreenshot(); // full-viewport, added to ticket await TraceBug.takeRegionScreenshot(); // snipping-tool, added to ticket TraceBug.addNote({ text: "form spinner stuck", severity: "major" }); // review + export: TraceBug.stopRecording(); // opens the modal // ...user clicks "Copy as GitHub Issue"; markdown copied + 2 PNGs downloaded ``` If you want a fully headless export (no modal), use the existing report API: ```ts const report = TraceBug.generateReport(); const md = TraceBug.getGitHubIssue(); TraceBug.downloadPdf(); ``` The headless API does not bulk-download screenshots β€” that's a modal behavior. For headless bulk download: ```ts import { downloadAllScreenshots } from "tracebug-sdk"; downloadAllScreenshots(); ``` --- ## Why this flow? The previous behavior (instant download per screenshot) created two problems: 1. **Disk spam** β€” taking 5 screenshots in a repro flow dumped 5 files into Downloads before the user knew which ones mattered. 2. **No review window** β€” the user could not see the full set of captures before deciding which to attach to a ticket. The ticket flow keeps screenshots in memory until the user has reviewed them, then bundles the export. The cost is one extra click ("Stop") at the end of the repro; the win is a tidy Downloads folder and a single coherent ticket payload.