feat: add BugDrop Sandbox

.github/workflows/ci.yml

@@ -184,6 +184,24 @@ jobs:
           echo "Preview worker not ready after 300s"
           exit 1
 
+      - name: Verify preview sandbox assets
+        env:
+          WORKER_ORIGIN: https://bugdrop-preview.neonwatty.workers.dev
+        run: |
+          check() {
+            local path="$1" expected="$2"
+            echo "Checking ${WORKER_ORIGIN}${path} for '${expected}'..."
+            body=$(curl -sSf "${WORKER_ORIGIN}${path}") || { echo "Fetch failed: $path"; exit 1; }
+            grep -q -- "$expected" <<<"$body" || { echo "Wrong content for $path (expected: $expected)"; exit 1; }
+          }
+          check /sandbox/                 'id="sandbox-form"'
+          check /sandbox/preview          'BugDrop Sandbox Preview'
+          check /sandbox/sandbox.css      'sandbox-shell'
+          check /sandbox/sandbox.js       'generateScriptTag'
+          check /sandbox/attribute-map.js 'data-repo'
+          check /sandbox/sanitizers.js    'sanitizeConfig'
+          check /widget.js                'bd-trigger'
+
       - name: Verify test venue is reachable
         run: |
           VENUE_URL="${PLAYWRIGHT_BASE_URL}"

.github/workflows/deploy.yml

@@ -64,3 +64,21 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Verify production sandbox assets
+        env:
+          WORKER_ORIGIN: https://bugdrop.neonwatty.workers.dev
+        run: |
+          check() {
+            local path="$1" expected="$2"
+            echo "Checking ${WORKER_ORIGIN}${path} for '${expected}'..."
+            body=$(curl -sSf "${WORKER_ORIGIN}${path}") || { echo "Fetch failed: $path"; exit 1; }
+            grep -q -- "$expected" <<<"$body" || { echo "Wrong content for $path (expected: $expected)"; exit 1; }
+          }
+          check /sandbox/                 'id="sandbox-form"'
+          check /sandbox/preview          'BugDrop Sandbox Preview'
+          check /sandbox/sandbox.css      'sandbox-shell'
+          check /sandbox/sandbox.js       'generateScriptTag'
+          check /sandbox/attribute-map.js 'data-repo'
+          check /sandbox/sanitizers.js    'sanitizeConfig'
+          check /widget.js                'bd-trigger'

README.md

@@ -4,6 +4,7 @@
 [![Version](https://img.shields.io/badge/version-1.11.0-14b8a6)](./CHANGELOG.md)
 [![Security Policy](https://img.shields.io/badge/Security-Policy-blue)](./SECURITY.md)
 [![Live Demo](https://img.shields.io/badge/Demo-Try_It_Live-ff9e64)](https://bugdrop-widget-test.vercel.app)
+[![Sandbox](https://img.shields.io/badge/Sandbox-Configure_Widget-7c3aed)](https://bugdrop.neonwatty.workers.dev/sandbox/)
 [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Install-2ea44f?logo=github)](https://github.com/marketplace/bugdrop-in-app-feedback-to-github-issues)
 [![Product Hunt](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1141615&theme=light&t=1778415221018)](https://www.producthunt.com/products/bugdrop-2?utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-bugdrop-2)
 
@@ -55,6 +56,8 @@ That's it! Users can now click the bug button to submit feedback as GitHub Issue
 
 See [full documentation](https://bugdrop.dev/docs/configuration) for all options including styling, submitter info, and dismissible button.
 
+Use the [BugDrop Sandbox](https://bugdrop.neonwatty.workers.dev/sandbox/) to preview settings, check GitHub App installation, test screenshot masking, and generate a script tag.
+
 ## Documentation
 
 - [Full Documentation](https://bugdrop.dev/docs)

docs/website/ci-testing.mdx

@@ -45,7 +45,7 @@ const EXPECTED = {
   requireEmail: false,
   buttonDismissible: false,
   showRestore: true,
-  welcomeMessage: "Report a bug or request a feature",
+  welcome: "once",
 };
 
 const URL = "https://your-site.com"; // Replace with your site URL
@@ -114,17 +114,21 @@ test.describe("BugDrop Widget", () => {
     expect(bgColor).toBeTruthy();
   });
 
-  test("displays correct welcome message", async ({ page }) => {
+  test("uses expected welcome behavior", async ({ page }) => {
     const btn = await shadowEl(page, "bug-drop-widget", ".floating-btn");
     await (btn as any).click();
 
-    const welcomeText = await page.evaluate(() => {
+    // The welcome modal carries the `.bd-welcome` class; the feedback form does not.
+    // For `welcome: "once"`, the welcome modal only appears on the first open per repo;
+    // the "seen" flag is stored under localStorage keys prefixed with `bugdrop_welcomed_`,
+    // so for a deterministic test add `await page.evaluate(() => localStorage.clear())`
+    // (or `localStorage.removeItem('bugdrop_welcomed_<owner>/<repo>')`) in beforeEach.
+    const welcomeVisible = await page.evaluate(() => {
       const host = document.querySelector("bug-drop-widget");
-      const welcome = host?.shadowRoot?.querySelector(".welcome-message, h2");
-      return welcome?.textContent?.trim();
+      return Boolean(host?.shadowRoot?.querySelector(".bd-welcome"));
     });
 
-    expect(welcomeText).toContain(EXPECTED.welcomeMessage);
+    expect(welcomeVisible).toBe(EXPECTED.welcome !== "never");
   });
 
   test("shows/hides name field based on config", async ({ page }) => {
@@ -249,7 +253,7 @@ The test suite covers three areas:
 - **Opens and closes the form** -- Clicks the button, verifies the form appears, then closes it
 - **Correct position** -- Validates the button is in the expected corner (bottom-right or bottom-left)
 - **Correct accent color** -- Checks the button's background color
-- **Welcome message** -- Opens the form and verifies the correct welcome text is displayed
+- **Welcome screen** -- Opens the form and verifies the expected welcome behavior
 - **Name/email field visibility** -- Confirms fields show or hide based on your configuration
 
 ### Accessibility Tests (WCAG AA)
@@ -272,7 +276,7 @@ const EXPECTED = {
   requireEmail: false,      // data-require-email
   buttonDismissible: false, // data-button-dismissible
   showRestore: true,        // data-show-restore
-  welcomeMessage: "Report a bug or request a feature", // data-welcome
+  welcome: "once",           // data-welcome
 };
 ```
 

docs/website/configuration.mdx

@@ -9,14 +9,14 @@ These attributes control the fundamental behavior of the widget.
 | Attribute | Default | Description |
 |-----------|---------|-------------|
 | `data-repo` | **(required)** | GitHub repository in `owner/repo` format |
-| `data-theme` | `"light"` | Widget theme: `"light"` or `"dark"` |
+| `data-theme` | `"auto"` | Widget theme: `"auto"`, `"light"`, or `"dark"` |
 | `data-position` | `"bottom-right"` | Button position: `"bottom-right"` or `"bottom-left"` |
 | `data-color` | `"#7c3aed"` | Primary accent color (any CSS color value) |
 | `data-icon` | *(default bug icon)* | Custom icon: URL to an image, `"none"` to hide, or omit for default |
 | `data-label` | `""` | Text label displayed next to the button icon |
 | `data-category-labels` | built-in labels | Self-hosted JSON mapping from built-in categories to GitHub labels |
 | `data-button` | `"true"` | Show the floating button: `"true"` or `"false"` |
-| `data-welcome` | `"Report a bug or request a feature"` | Welcome message displayed at the top of the form |
+| `data-welcome` | `"once"` | Welcome screen behavior: `"once"`, `"always"`, `"never"`, or `"false"` |
 
 ### Basic Example
 
@@ -27,19 +27,24 @@ These attributes control the fundamental behavior of the widget.
   data-theme="dark"
   data-position="bottom-left"
   data-color="#ef4444"
-  data-welcome="Found a bug? Let us know!"
+  data-welcome="always"
 ></script>
 ```
 
 ### Theme Options
 
 The `data-theme` attribute controls the overall color scheme of the widget:
 
-- **`light`** (default) -- White background with dark text. Suitable for most sites.
+- **`auto`** (default) -- Follows the user's system color scheme.
+- **`light`** -- White background with dark text. Suitable for most sites.
 - **`dark`** -- Dark background with light text. Ideal for sites with dark color schemes.
 
 ```html
-<!-- Light theme (default) -->
+<!-- Auto theme (default) -->
+<script src="https://bugdrop.neonwatty.workers.dev/widget.js"
+  data-repo="owner/repo" data-theme="auto"></script>
+
+<!-- Light theme -->
 <script src="https://bugdrop.neonwatty.workers.dev/widget.js"
   data-repo="owner/repo" data-theme="light"></script>
 
@@ -55,6 +60,24 @@ The `data-position` attribute controls where the floating button appears:
 - **`bottom-right`** (default) -- Fixed to the bottom-right corner
 - **`bottom-left`** -- Fixed to the bottom-left corner
 
+### Welcome Screen Options
+
+The `data-welcome` attribute controls when the built-in welcome screen appears:
+
+- **`once`** (default) -- Show the welcome screen once per repository, then skip it on future opens in the same browser.
+- **`always`** -- Show the welcome screen every time the user opens the widget.
+- **`never`** or **`false`** -- Skip the welcome screen and open the feedback form directly.
+
+```html
+<!-- Always show the welcome screen -->
+<script src="https://bugdrop.neonwatty.workers.dev/widget.js"
+  data-repo="owner/repo" data-welcome="always"></script>
+
+<!-- Skip the welcome screen -->
+<script src="https://bugdrop.neonwatty.workers.dev/widget.js"
+  data-repo="owner/repo" data-welcome="never"></script>
+```
+
 ## Submitter Information
 
 Control whether the feedback form collects the submitter's name and email address.
@@ -307,7 +330,7 @@ Here is a script tag using many configuration options together:
   data-theme="dark"
   data-position="bottom-left"
   data-color="#6366f1"
-  data-welcome="We'd love to hear from you!"
+  data-welcome="always"
   data-show-name="true"
   data-show-email="true"
   data-require-email="true"
@@ -318,7 +341,7 @@ Here is a script tag using many configuration options together:
 ></script>
 ```
 
-This configuration creates a dark-themed widget in the bottom-left corner with an indigo accent color, collects the submitter's name and email (email required), and shows a "Feedback" label on the button. The button is dismissible for 2 hours with a restore link.
+This configuration creates a dark-themed widget in the bottom-left corner with an indigo accent color, always shows the built-in welcome screen, collects the submitter's name and email (email required), and shows a "Feedback" label on the button. The button is dismissible for 2 hours with a restore link.
 
 ## Next Steps
 

docs/website/getting-started.mdx

@@ -50,6 +50,7 @@ That is it. No servers to run, no databases to manage, no user accounts required
 Ready to get started? Here is where to go next:
 
 - **[Installation](/docs/installation)** -- Step-by-step setup guide to add BugDrop to your site
+- **[Sandbox](https://bugdrop.neonwatty.workers.dev/sandbox/)** -- Preview settings, check installation, and generate your script tag
 - **[Configuration](/docs/configuration)** -- All widget attributes for customizing behavior
 - **[Styling](/docs/styling)** -- Theme your widget with colors, fonts, borders, and shadows
 - **[JavaScript API](/docs/javascript-api)** -- Programmatic control with `window.BugDrop`

docs/website/installation.mdx

@@ -65,12 +65,16 @@ You can add data attributes to customize the widget's appearance and behavior:
   data-theme="dark"
   data-position="bottom-left"
   data-color="#6366f1"
-  data-welcome="We'd love your feedback!"
+  data-welcome="always"
 ></script>
 ```
 
 See the [Configuration](/docs/configuration) and [Styling](/docs/styling) docs for all available attributes.
 
+### Try it in the Sandbox
+
+Use the [BugDrop Sandbox](https://bugdrop.neonwatty.workers.dev/sandbox/) to preview widget behavior, check GitHub App installation, test screenshot masking, and generate a script tag before adding BugDrop to your app.
+
 ## Protecting sensitive data
 
 If your page renders customer data, billing details, or any other content you do not
@@ -84,7 +88,7 @@ want to appear in submitted screenshots, mark those elements with `data-bugdrop-
 
 BugDrop covers each marked element with an opaque rectangle on the captured screenshot.
 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
 
@@ -174,6 +178,7 @@ You can also test by clicking the bug button and submitting a test report. Check
 
 ## Next Steps
 
+- [Try the Sandbox](https://bugdrop.neonwatty.workers.dev/sandbox/) to generate and test your script tag
 - [Configure the widget](/docs/configuration) with custom attributes
 - [Style the widget](/docs/styling) to match your site's design
 - [Use the JavaScript API](/docs/javascript-api) for advanced integrations