refactor: split capture flow into focused modules and harden mask failures

Extract the screenshot/redaction pipeline from src/widget/index.ts into
four focused modules: screenshot-options, capture-loading, annotation-flow,
and capture-flow. Adds new public/test fixture and unit coverage.

Type design:
- ScreenshotChoice is now a discriminated union with consistent `kind`
  tags and an exhaustiveness check at the call site.
- CaptureWithLoadingResult is { kind: 'ok' | 'skipped' | 'cancelled' }
  so callers stop overloading `null`.
- Internal ChosenCaptureResult is { captured | empty | returnToForm },
  removing illegal-state combinations (e.g. screenshot + returnToForm).

Mask failure safety:
- New MaskApplicationError class is thrown from canvas/image failures
  inside applyMaskToImage so callers can distinguish them from raw
  capture errors.
- capture-loading shows a distinct "Privacy masking failed" modal that
  refuses to retry and only offers Skip / Cancel — previously a mask
  failure was indistinguishable from a generic capture failure and a
  "Skip Screenshot" click could silently submit with no image while
  the user thought capture had failed.

UI helper:
- redactionNoteHtml in ui.ts replaces four near-identical inline-styled
  HTML strings across screenshot-options and annotation-flow.

Author: neonwatty

docs/website/security.mdx

@@ -78,20 +78,26 @@ BugDrop is built with a privacy-first approach:
 
 ### Screenshot masking
 
-You can mark sensitive elements so BugDrop visually covers them in supported screenshot modes. Add the `data-bugdrop-mask` attribute to any element you want covered:
+You can mark sensitive elements so BugDrop visually covers them in supported screenshot modes. Add `data-bugdrop-redact` or `data-bugdrop-mask` to any element you want covered:
 
 ```html
-<input type="email" data-bugdrop-mask />
+<input type="email" data-bugdrop-redact />
 
 <div data-bugdrop-mask>
   <span>Customer name</span>
   <span>customer@example.com</span>
 </div>
 ```
 
-When a user submits feedback, BugDrop paints an opaque rectangle over each tagged
-element's bounding box on the captured PNG before showing the user the annotator
-preview. The user sees what is masked and can audit it before submitting.
+Supported explicit attributes are `data-bugdrop-redact`, `data-bd-redact`,
+`data-bugdrop-redacted`, and `data-bugdrop-mask`.
+
+When a user submits feedback, BugDrop plans redactions from matching DOM
+elements, then paints an opaque rectangle over each target's measured bounding
+box on supported captured PNGs. In manual screenshot flows, the masked image is
+shown in the annotator preview so the user can audit it before submitting. In
+automatic screenshot mode, BugDrop applies supported masks but submits without
+showing the preview step.
 
 Masking is best-effort visual coverage, not a data-loss-prevention or security
 boundary. Users should still review screenshots before submitting when the manual
@@ -108,8 +114,14 @@ prevents gaps from CSS `gap` or non-masked siblings inside a masked container.
 
 **Known limitations:**
 
-- Elements inside Shadow DOM and cross-origin iframes are not traversed in this
-  iteration.
+- Elements inside open Shadow DOM are traversed when the browser exposes the
+  shadow root. Closed Shadow DOM cannot be traversed; mark the host element if
+  the whole custom control should be covered.
+- Iframe contents are not traversed. Mark the iframe element itself if the whole
+  embedded frame should be visually covered.
+- BugDrop does not inspect pixels or text inside canvas, image, video, plugin,
+  or iframe content. Mark the containing DOM element if that entire region should
+  be visually covered.
 - Mask rectangles are collected at the start of capture. If the page reflows or reveals
   sensitive elements between collection and the moment `html-to-image` finishes
   rendering, the mask may not cover the final pixels. Keep masked content stable during

e2e/widget.spec.ts

@@ -3252,7 +3252,7 @@ test.describe('Screenshot Crash Prevention (#67)', () => {
   });
 
   test('remembers complex-page skip after element capture failure skip', async ({ page }) => {
-    await trackFeedbackSubmissions(page);
+    const payloads = await trackFeedbackPayloads(page);
     await mockHtmlToImage(page, "function() { return Promise.reject(new Error('mock failure')); }");
     await page.goto('/test/complex-dom.html?nodes=12000');
 
@@ -3271,13 +3271,36 @@ test.describe('Screenshot Crash Prevention (#67)', () => {
     await expect(host.locator('css=.bd-error-message__text')).toBeVisible({ timeout: 5000 });
     await host.locator('css=[data-action="skip"]').click();
     await expect(host.locator('css=.bd-success-icon')).toBeVisible({ timeout: 5000 });
+    expect(payloads).toHaveLength(1);
+    expect((payloads[0].metadata as { elementSelector?: string }).elementSelector).toContain('h1');
 
     await host.locator('css=.bd-close').click();
     await host.locator('css=.bd-trigger').click();
     await expect(host.locator('css=#title')).toBeVisible({ timeout: 5000 });
     await expect(host.locator('css=#include-screenshot')).not.toBeChecked();
   });
 
+  test('does not remember complex-page skip after element picker cancellation', async ({
+    page,
+  }) => {
+    const payloads = await trackFeedbackPayloads(page);
+    await page.goto('/test/complex-dom.html?nodes=12000');
+
+    const host = await navigateToScreenshotOptions(page);
+    await host.locator('css=[data-action="element"]').click();
+    await expect(page.locator('#bugdrop-element-picker-tooltip')).toBeVisible({ timeout: 5000 });
+    await page.keyboard.press('Escape');
+
+    await expect(host.locator('css=.bd-success-icon')).toBeVisible({ timeout: 5000 });
+    expect(payloads).toHaveLength(1);
+    expect(payloads[0].screenshot).toBeNull();
+
+    await host.locator('css=.bd-close').click();
+    await host.locator('css=.bd-trigger').click();
+    await expect(host.locator('css=#title')).toBeVisible({ timeout: 5000 });
+    await expect(host.locator('css=#include-screenshot')).toBeChecked();
+  });
+
   test('shows all buttons on pages below 10k nodes', async ({ page }) => {
     await mockHtmlToImage(page, spyToPng());
     await page.goto('/test/complex-dom.html?nodes=4000');
@@ -4318,6 +4341,57 @@ test.describe('Screenshot Masking', () => {
     expect(await pixelAt(page, screenshot, cx, cy)).toEqual([0, 0, 0, 255]);
   });
 
+  test('full-page capture masks transformed redaction targets', async ({ page }) => {
+    const { screenshot, pixelRatio } = await submitFeedbackWithFullPageCapture(
+      page,
+      '/test/masking-layout-edge.html'
+    );
+
+    const rect = await docRectOf(page, '#transformed-mask');
+    const cx = Math.floor((rect.x + rect.w / 2) * pixelRatio);
+    const cy = Math.floor((rect.y + rect.h / 2) * pixelRatio);
+
+    expect(await pixelAt(page, screenshot, cx, cy)).toEqual([0, 0, 0, 255]);
+  });
+
+  test('full-page capture masks sticky redaction targets after scrolling', async ({ page }) => {
+    await page.addInitScript(() => {
+      window.addEventListener('DOMContentLoaded', () => {
+        requestAnimationFrame(() => window.scrollTo(0, 420));
+      });
+    });
+
+    const { screenshot, pixelRatio } = await submitFeedbackWithFullPageCapture(
+      page,
+      '/test/masking-layout-edge.html'
+    );
+
+    const rect = await docRectOf(page, '#sticky-mask');
+    const cx = Math.floor((rect.x + rect.w / 2) * pixelRatio);
+    const cy = Math.floor((rect.y + rect.h / 2) * pixelRatio);
+
+    expect(await pixelAt(page, screenshot, cx, cy)).toEqual([0, 0, 0, 255]);
+  });
+
+  test('full-page capture masks fixed redaction targets after scrolling', async ({ page }) => {
+    await page.addInitScript(() => {
+      window.addEventListener('DOMContentLoaded', () => {
+        requestAnimationFrame(() => window.scrollTo(0, 420));
+      });
+    });
+
+    const { screenshot, pixelRatio } = await submitFeedbackWithFullPageCapture(
+      page,
+      '/test/masking-layout-edge.html'
+    );
+
+    const rect = await docRectOf(page, '#fixed-mask');
+    const cx = Math.floor((rect.x + rect.w / 2) * pixelRatio);
+    const cy = Math.floor((rect.y + rect.h / 2) * pixelRatio);
+
+    expect(await pixelAt(page, screenshot, cx, cy)).toEqual([0, 0, 0, 255]);
+  });
+
   // Walk the element-picker flow and capture the chosen element.
   //
   // `selector` identifies the element to click in the picker.  Because the picker

public/test/masking-layout-edge.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>BugDrop - Masking Layout Edge Cases</title>
+    <style>
+      body {
+        margin: 0;
+        min-height: 1800px;
+        padding: 24px;
+        font-family: system-ui, sans-serif;
+        background: #f8fafc;
+      }
+
+      .spacer {
+        height: 360px;
+      }
+
+      .panel {
+        width: 260px;
+        min-height: 56px;
+        margin: 24px 0;
+        padding: 18px;
+        border: 1px solid #94a3b8;
+        border-radius: 4px;
+        background: #fee2e2;
+        color: #7f1d1d;
+        font-weight: 700;
+      }
+
+      #transformed-mask {
+        transform: translate(48px, 24px) rotate(1deg);
+      }
+
+      #sticky-mask {
+        position: sticky;
+        top: 16px;
+        background: #fde68a;
+      }
+
+      #fixed-mask {
+        position: fixed;
+        right: 32px;
+        top: 96px;
+        width: 220px;
+        background: #bfdbfe;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Masking Layout Edge Cases</h1>
+    <p>Fixture used by Playwright for transformed and sticky redaction geometry.</p>
+
+    <div id="transformed-mask" class="panel" data-bugdrop-redact>
+      transformed private account id
+    </div>
+
+    <div class="spacer"></div>
+
+    <div id="sticky-mask" class="panel" data-bugdrop-redact>sticky private session id</div>
+
+    <div class="spacer"></div>
+
+    <div id="fixed-mask" class="panel" data-bugdrop-redact>fixed private token</div>
+
+    <script src="/widget.js" data-repo="test-org/test-repo" data-screenshot="optional"></script>
+  </body>
+</html>

src/widget/annotation-flow.ts

@@ -0,0 +1,89 @@
+import { createAnnotator, type Tool } from './annotator';
+import { createModal, redactionNoteHtml } from './ui';
+
+export function showAnnotationStep(
+  root: HTMLElement,
+  screenshot: string,
+  redactionCount = 0,
+  opts?: { redactionUnavailable?: boolean }
+): Promise<string | 'retake' | 'cancel'> {
+  return new Promise(resolve => {
+    let redactionNote = '';
+    if (opts?.redactionUnavailable) {
+      redactionNote = redactionNoteHtml(
+        'This browser viewport capture could not apply automatic private-field masks. Review and cover any sensitive areas before sending.'
+      );
+    } else if (redactionCount > 0) {
+      redactionNote = redactionNoteHtml(
+        `${redactionCount} private ${redactionCount === 1 ? 'item was' : 'items were'} marked for redaction in this screenshot. Review before sending.`
+      );
+    }
+    const modal = createModal(
+      root,
+      'Review Screenshot',
+      `
+        ${redactionNote}
+        <p style="margin: 0 0 12px; color: var(--bd-text-secondary); font-size: 13px;">
+          Check that no sensitive information is visible before sending. Cover sensitive areas before submitting. Redactions are baked into the uploaded image.
+        </p>
+        <div class="bd-tools">
+          <button class="bd-tool active" data-tool="draw">✏️ Draw</button>
+          <button class="bd-tool" data-tool="arrow">➡️ Arrow</button>
+          <button class="bd-tool" data-tool="rect">▢ Rectangle</button>
+          <button class="bd-tool" data-tool="redact">Redact</button>
+          <button class="bd-tool" data-action="undo">↶ Undo</button>
+        </div>
+        <div id="annotation-canvas" class="bd-annotation-stage"></div>
+        <div class="bd-actions">
+          <button class="bd-btn bd-btn-secondary" data-action="retake">Retake</button>
+          <button class="bd-btn bd-btn-primary" data-action="done">Submit Feedback</button>
+        </div>
+      `,
+      false,
+      'bd-modal--annotator'
+    );
+
+    const canvasContainer = modal.querySelector('#annotation-canvas') as HTMLElement;
+    const annotator = createAnnotator(canvasContainer, screenshot);
+
+    const toolButtons = modal.querySelectorAll('[data-tool]');
+    toolButtons.forEach(btn => {
+      btn.addEventListener('click', e => {
+        const target = e.currentTarget as HTMLElement;
+        const tool = target.dataset.tool;
+
+        if (tool) {
+          toolButtons.forEach(b => b.classList.remove('active'));
+          target.classList.add('active');
+          annotator.setTool(tool as Tool);
+        }
+      });
+    });
+
+    const undoBtn = modal.querySelector('[data-action="undo"]') as HTMLElement | null;
+    undoBtn?.addEventListener('click', () => annotator.undo());
+
+    const closeBtn = modal.querySelector('.bd-close') as HTMLElement;
+    const retakeBtn = modal.querySelector('[data-action="retake"]') as HTMLElement;
+    const doneBtn = modal.querySelector('[data-action="done"]') as HTMLElement;
+
+    closeBtn?.addEventListener('click', () => {
+      annotator.destroy();
+      modal.remove();
+      resolve('cancel');
+    });
+
+    retakeBtn?.addEventListener('click', () => {
+      annotator.destroy();
+      modal.remove();
+      resolve('retake');
+    });
+
+    doneBtn?.addEventListener('click', () => {
+      const annotated = annotator.getImageData();
+      annotator.destroy();
+      modal.remove();
+      resolve(annotated);
+    });
+  });
+}