From 705376dbeb7536902f7a0d2898a3b6db65c78378 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 19 May 2026 16:09:40 +0000 Subject: [PATCH 1/2] docs: sync documentation from bugdrop repo --- src/content/docs/configuration.mdx | 25 +++++++++-- src/content/docs/faq.mdx | 7 ++-- src/content/docs/installation.mdx | 8 ++-- src/content/docs/security.mdx | 66 ++++++++++++++++-------------- 4 files changed, 63 insertions(+), 43 deletions(-) diff --git a/src/content/docs/configuration.mdx b/src/content/docs/configuration.mdx index d5bf4ea..6296ee6 100644 --- a/src/content/docs/configuration.mdx +++ b/src/content/docs/configuration.mdx @@ -297,9 +297,28 @@ Supported attributes: - `data-bugdrop-redacted` - `data-bugdrop-mask` -This is best-effort visual masking, not a data-loss-prevention or security boundary. BugDrop can only mask content it can measure in the page DOM. Unmarked sensitive information can still appear, and browser rendering limits can apply to canvas, image, video, iframe, SVG, shadow DOM, pseudo-element, and highly custom control content. - -Selected-area screenshots are rendered to the selected dimensions and masks are translated into that crop, but the capture still runs client-side against the page DOM. Avoid screenshots entirely for pages where client-side screenshot rendering is unacceptable. +This is visual masking, not a data-loss-prevention or security boundary. +BugDrop can only mask content it can measure in the page DOM. Unmarked +sensitive information can still appear, and browser rendering limits can apply +to canvas, image, video, iframe, SVG, shadow DOM, pseudo-element, and highly +custom control content. + +Masking works in full-page, selected-element, selected-area, and automatic +screenshot modes when BugDrop renders the page through its DOM screenshot path. +For selected-area captures, mask rectangles are translated into the selected +crop. For selected-element captures with surrounding context enabled, masks are +computed relative to the captured context element. + +| Capture path | Automatic DOM masks | User preview | Manual redact tool | Limitation warning | Notes | +| --- | --- | --- | --- | --- | --- | +| Full page | Yes | Yes | Yes | Yes | Uses DOM screenshot rendering unless the page is too complex | +| Selected element | Yes | Yes | Yes | Yes | Masks are relative to the captured element or surrounding context | +| Selected area | Yes | Yes | Yes | Yes, scoped to the crop | Masks outside the selected crop are ignored | +| Automatic screenshot | Yes | No | No | No in the current UI | Use only when marked sensitive regions are stable and supported | +| Native viewport fallback | No | Yes | Yes | Existing unavailable-mask warning | Used for very complex pages; users must review manually | + +Disable screenshots or use `data-screenshot="optional"` on pages where sensitive +pixels cannot be reliably enclosed by DOM boxes. ```html diff --git a/src/content/docs/faq.mdx b/src/content/docs/faq.mdx index 60c06e6..94ae350 100644 --- a/src/content/docs/faq.mdx +++ b/src/content/docs/faq.mdx @@ -208,16 +208,15 @@ If the widget appears but submissions fail: 1. **Check the GitHub App** -- Make sure it is installed on the correct repository with Issues and Contents permissions 2. **Check rate limits** -- You may have hit the per-IP or per-repository rate limit -3. **Check CSP** -- If your site uses a strict Content Security Policy, make sure `https://bugdrop.neonwatty.workers.dev` is allowed in `connect-src` so the browser can submit feedback to the Worker API -4. **Check the console** -- Look for error messages in the browser developer console -5. **Check the network tab** -- Inspect the API request to see the response status and body +3. **Check the console** -- Look for error messages in the browser developer console +4. **Check the network tab** -- Inspect the API request to see the response status and body ### Screenshots are not being uploaded If issues are created but without screenshots: 1. **Check branch protection** -- The GitHub App needs permission to push to the `bugdrop-screenshots` branch. See the [Installation](/docs/installation) page for details on branch protection configuration. -2. **Check CSP** -- Make sure your Content Security Policy allows the BugDrop widget script in `script-src` and feedback submission in `connect-src`. +2. **Check CSP** -- Make sure your Content Security Policy allows the BugDrop widget script. 3. **Cross-origin content** -- Browser screenshot rendering cannot capture cross-origin iframes or images loaded without CORS headers. These elements may appear blank in the screenshot. ### Can I use BugDrop on a static site? diff --git a/src/content/docs/installation.mdx b/src/content/docs/installation.mdx index d279b0b..57f49a4 100644 --- a/src/content/docs/installation.mdx +++ b/src/content/docs/installation.mdx @@ -85,7 +85,7 @@ BugDrop to visually cover in supported screenshot modes, mark those elements wit BugDrop covers each marked element with an opaque rectangle on supported captured screenshots. Password inputs and credit-card autocomplete fields are masked automatically. See -[Screenshot masking](/docs/security#screenshot-masking) on the Security page for details. +[Screenshot masking](/security#screenshot-masking) on the Security page for details. ## Step 3: You Are Done @@ -111,12 +111,10 @@ The BugDrop script tag should **not** include the `async` or `defer` attributes. If your site uses a Content Security Policy, allow the BugDrop worker domain in your CSP directives: ``` -Content-Security-Policy: - script-src 'self' https://bugdrop.neonwatty.workers.dev; - connect-src 'self' https://bugdrop.neonwatty.workers.dev; +Content-Security-Policy: script-src 'self' https://bugdrop.neonwatty.workers.dev; ``` -`script-src` lets the widget load. `connect-src` lets the browser submit feedback to the BugDrop Worker API. +If you have a strict CSP, make sure the BugDrop worker domain is included in your `script-src` directive. ### Branch Protection and the Screenshots Branch diff --git a/src/content/docs/security.mdx b/src/content/docs/security.mdx index c6c202f..191e369 100644 --- a/src/content/docs/security.mdx +++ b/src/content/docs/security.mdx @@ -78,7 +78,9 @@ 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 `data-bugdrop-redact` or `data-bugdrop-mask` to any element you want covered: +BugDrop supports developer-configured visual masking for screenshots. Add +`data-bugdrop-redact` or `data-bugdrop-mask` to any DOM element that should be +covered: ```html @@ -92,46 +94,48 @@ You can mark sensitive elements so BugDrop visually covers them in supported scr 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. +For supported DOM-rendered captures, when masking succeeds, BugDrop records the +geometry of matching DOM elements, renders the screenshot, then paints opaque +rectangles over those measured boxes in the PNG. The submitted image contains +the black rectangles. If masking fails, BugDrop discards the screenshot instead +of uploading it. The original page DOM is not mutated. -Masking is best-effort visual coverage, not a data-loss-prevention or security -boundary. Users should still review screenshots before submitting when the manual -screenshot flow is enabled. +Masking is visual coverage, not data-loss prevention. BugDrop does not inspect +text or pixels to discover secrets. Developers must mark the sensitive regions +they control, and users should review manual screenshots before submitting. **Inheritance.** When an ancestor has `data-bugdrop-mask`, the entire ancestor box is masked as a single rectangle. Descendants do not get individual rectangles — this prevents gaps from CSS `gap` or non-masked siblings inside a masked container. -**Built-in defaults.** These are always masked, with or without an explicit attribute: +**Built-in defaults.** In supported DOM-rendered screenshot paths, BugDrop +automatically masks these with or without an explicit attribute: - `input[type="password"]` - Any input with `autocomplete="cc-number"`, `cc-csc`, or `cc-exp` -**Known limitations:** - -- 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 - the brief capture window. -- **Viewport capture fallback (very complex pages):** When the page exceeds the - full-page DOM-complexity threshold, BugDrop falls back to a screen-recording - capture (via the browser's `getDisplayMedia` API). That path captures the - visible viewport directly and does not apply element masks. If you rely on - masking, ensure the user is not capturing through this fallback when sensitive - elements are visible. +These defaults do not apply to native viewport capture or skipped/failed +screenshot paths. + +| Surface | Behavior | Recommended control | +| --- | --- | --- | +| Regular DOM elements | Marked element box is covered | Mark the smallest stable container that fully encloses the sensitive content | +| Password and credit-card inputs | Covered automatically | No extra attribute required, but explicit marks are fine | +| Open Shadow DOM | Traversed when the browser exposes `shadowRoot` | Mark inner controls or the host | +| Closed Shadow DOM | Not traversed | Mark the host custom element | +| Iframes | Iframe internals are not traversed | Mark the iframe element if the whole embedded frame is sensitive | +| Canvas, image, SVG, video | Internal pixels are not inspected | Mark the element or a containing wrapper | +| Pseudo-elements and highly custom controls | Generated pixels are not inspected separately | Mark a stable wrapper around the whole control | +| Native viewport capture fallback | Element masks cannot be applied | Avoid viewport fallback on pages that require masking | + +If a marked region includes embedded, media, or pixel-rendered content, BugDrop +covers the marked element box and warns the user in manual screenshot review +flows that it cannot inspect the internal pixels. Automatic screenshot mode +still applies supported masks, but it submits without showing a review step. + +Mask rectangles are measured at capture start. If the page reflows or reveals +sensitive elements after that measurement but before rendering finishes, a mask +can become stale. Keep sensitive marked regions stable during capture. The only network requests BugDrop makes are: From b3590dece173b4c753fd532fb2b1a8b0d9c68596 Mon Sep 17 00:00:00 2001 From: neonwatty Date: Tue, 19 May 2026 10:09:04 -0700 Subject: [PATCH 2/2] docs: preserve CSP and docs links --- src/content/docs/faq.mdx | 7 ++++--- src/content/docs/installation.mdx | 8 +++++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/content/docs/faq.mdx b/src/content/docs/faq.mdx index 94ae350..60c06e6 100644 --- a/src/content/docs/faq.mdx +++ b/src/content/docs/faq.mdx @@ -208,15 +208,16 @@ If the widget appears but submissions fail: 1. **Check the GitHub App** -- Make sure it is installed on the correct repository with Issues and Contents permissions 2. **Check rate limits** -- You may have hit the per-IP or per-repository rate limit -3. **Check the console** -- Look for error messages in the browser developer console -4. **Check the network tab** -- Inspect the API request to see the response status and body +3. **Check CSP** -- If your site uses a strict Content Security Policy, make sure `https://bugdrop.neonwatty.workers.dev` is allowed in `connect-src` so the browser can submit feedback to the Worker API +4. **Check the console** -- Look for error messages in the browser developer console +5. **Check the network tab** -- Inspect the API request to see the response status and body ### Screenshots are not being uploaded If issues are created but without screenshots: 1. **Check branch protection** -- The GitHub App needs permission to push to the `bugdrop-screenshots` branch. See the [Installation](/docs/installation) page for details on branch protection configuration. -2. **Check CSP** -- Make sure your Content Security Policy allows the BugDrop widget script. +2. **Check CSP** -- Make sure your Content Security Policy allows the BugDrop widget script in `script-src` and feedback submission in `connect-src`. 3. **Cross-origin content** -- Browser screenshot rendering cannot capture cross-origin iframes or images loaded without CORS headers. These elements may appear blank in the screenshot. ### Can I use BugDrop on a static site? diff --git a/src/content/docs/installation.mdx b/src/content/docs/installation.mdx index 57f49a4..d279b0b 100644 --- a/src/content/docs/installation.mdx +++ b/src/content/docs/installation.mdx @@ -85,7 +85,7 @@ BugDrop to visually cover in supported screenshot modes, mark those elements wit BugDrop covers each marked element with an opaque rectangle on supported captured screenshots. Password inputs and credit-card autocomplete fields are masked automatically. See -[Screenshot masking](/security#screenshot-masking) on the Security page for details. +[Screenshot masking](/docs/security#screenshot-masking) on the Security page for details. ## Step 3: You Are Done @@ -111,10 +111,12 @@ The BugDrop script tag should **not** include the `async` or `defer` attributes. If your site uses a Content Security Policy, allow the BugDrop worker domain in your CSP directives: ``` -Content-Security-Policy: script-src 'self' https://bugdrop.neonwatty.workers.dev; +Content-Security-Policy: + script-src 'self' https://bugdrop.neonwatty.workers.dev; + connect-src 'self' https://bugdrop.neonwatty.workers.dev; ``` -If you have a strict CSP, make sure the BugDrop worker domain is included in your `script-src` directive. +`script-src` lets the widget load. `connect-src` lets the browser submit feedback to the BugDrop Worker API. ### Branch Protection and the Screenshots Branch