feat: add manual browser testing for the built bundle

Adds test-manual/index.html that loads the locally built bundle (lib/buybutton.umd.js)
and renders real buy buttons from live stores. This enables reviewers to verify changes
don't break real-world rendering before merging.

Key details:
- Uses ShopifyBuy.UI.init() API (not onReady - that's buy-button-storefront wrapper)
- Tests 3 components: product, collection, product from different store
- Includes .catch() error handlers for visible failure feedback
- Excluded from npm publish via .npmignore
- Documents the difference between buy-button-js and buy-button-storefront APIs

This is an interim solution until automated browser testing (Playwright/Vitest) is added.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: AI (Pi/GLM 5.2 Fast (Fireworks) [1m]) <noreply@pi.dev>

Author: 3 people

.npmignore

@@ -10,4 +10,5 @@ test-output.xml
 lint-output.xml
 /errorShots
 /test/build
+/test-manual
 config.json

readme.md

@@ -45,6 +45,19 @@ pnpm run test-dev
 
 Will watch for changes and run test suite.
 
+### Manual Browser Testing
+
+To verify buy buttons render correctly in a real browser:
+
+```bash
+pnpm build
+pnpm serve
+# Open the URL the terminal prints on startup, e.g.:
+open http://localhost:8080/test-manual/
+```
+
+See [`test-manual/README.md`](./test-manual/README.md) for details.
+
 ## Documentation
 
 To run docs locally, install jekyll:

test-manual/README.md

@@ -0,0 +1,81 @@
+# Manual Browser Testing
+
+This directory contains a test page for manually verifying buy-button-js works correctly in a real browser environment.
+
+## Important: buy-button-js vs buy-button-storefront
+
+**This test page tests `buy-button-js` directly** — the core UI rendering library.
+
+The embed code merchants get from the Shopify admin loads `buy-button-storefront.min.js` (from CDN), which is a **different package** that wraps buy-button-js with tracking/analytics and provides a convenience API.
+
+| Package | API | Source |
+|---------|-----|--------|
+| `buy-button-js` (this repo) | `ShopifyBuy.UI.init(client)` | Local build (`lib/buybutton.umd.js`) |
+| `buy-button-storefront` (wrapper) | `ShopifyBuy.UI.onReady(client).then(...)` | CDN (`buy-button-storefront.min.js`) |
+
+If you're testing changes to buy-button-js, use this test page. The `onReady` API from merchant embed codes won't work here because that's added by the storefront wrapper.
+
+## Why Manual Testing?
+
+The unit test suite (794 tests) verifies component logic, but doesn't render actual buy buttons in a browser. This test page lets you:
+
+- Verify the built bundle loads correctly
+- See real buy buttons render with products from live stores
+- Test cart interactions, modals, and checkout flows
+- Confirm changes don't break visual rendering or API communication
+
+## Quick Start
+
+```bash
+# 1. Install dependencies (if not already done)
+pnpm install
+
+# 2. Build the package
+pnpm build
+
+# 3. Start the local server
+pnpm serve
+
+# 4. Open the URL the terminal prints on startup (e.g. localhost:8080/test-manual/)
+open http://localhost:8080/test-manual/
+```
+
+> **Note:** `localhost:8080` above is just an example. `http-server` picks the first available port (and moves to 8081, 8082, etc. if 8080 is taken), so use the URL printed in the terminal when you run `pnpm serve`.
+
+## What's Tested
+
+The test page includes several buy button configurations:
+
+| Test | Type | Store | Purpose |
+|------|------|-------|---------|
+| 1 | Product | kara-daviduik | Basic product with default styling |
+| 2 | Collection | kara-daviduik | Collection grid rendering |
+| 3 | Product | hydrogen-migration | Cross-store verification |
+
+## Expected Behavior
+
+When working correctly, you should see:
+
+1. ✅ Green "ShopifyBuy loaded successfully" status at the top
+2. Product images, titles, and prices rendered
+3. "Add to cart" buttons that open a cart drawer when clicked
+4. Cart drawer with working quantity controls and checkout button
+
+## Troubleshooting
+
+**"ShopifyBuy not loaded" error:**
+- Run `pnpm build` first
+- Check that `lib/buybutton.umd.js` exists
+
+**Products not rendering:**
+- Check browser console for API errors
+- Verify network requests to `*.myshopify.com` succeed
+- Some stores may have access restrictions
+
+**CORS errors:**
+- Use `pnpm serve` instead of opening the file directly
+- Or use a browser with relaxed local file security
+
+## Adding More Tests
+
+To test additional scenarios, add new `<div id="test-X">` elements and corresponding `ui.createComponent()` calls in the script section. Use your own store's domain and storefront access token.