@launchsecure/launch-beacon 0.0.1

package/README.md

@@ -0,0 +1,148 @@
+# @launchsecure/launch-beacon
+
+Generic, vanilla, framework-agnostic Web Component for in-app user feedback. Captures a written description, severity, viewport screenshot with auto-numbered element pins, and per-pin element data (HTML, CSS selector, computed styles, framework component name when available).
+
+Drop into any web app — React, Vue, Angular, Svelte, plain HTML, server-rendered. Works in any framework because it's a real Web Component, not a library wrapper.
+
+## Install
+
+```bash
+npm install @launchsecure/launch-beacon
+# or
+pnpm add @launchsecure/launch-beacon
+```
+
+Or via `<script>` tag (UMD build):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@launchsecure/launch-beacon@0/dist/beacon.umd.js" defer></script>
+```
+
+## Quick start
+
+```html
+<launchkit-beacon
+  endpoint="/api/feedback"
+  position="bottom-right"
+></launchkit-beacon>
+```
+
+That's it. A floating "Feedback" button appears bottom-right. Clicking it opens the form.
+
+## Configuration
+
+### Declarative (HTML attributes)
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `endpoint` | required | URL to POST the feedback payload to |
+| `position` | `bottom-right` | `bottom-right` \| `bottom-left` \| `hidden` (use `hidden` if providing your own trigger via slot) |
+| `theme` | `auto` | `auto` \| `light` \| `dark` |
+| `severities` | `bug,idea,ux,a11y` | Comma-separated list of severity options |
+
+### Programmatic (for dynamic config / auth headers)
+
+```js
+const widget = document.querySelector('launchkit-beacon');
+widget.config = {
+  endpoint: '/api/feedback',
+  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+  context: () => ({ orgSlug, projectSlug }),
+};
+```
+
+`headers` and `context` may be objects or functions (called at submit time).
+
+### Programmatic methods
+
+```js
+widget.open();              // open form drawer
+widget.openWithPicker();    // open and jump straight into element-pick mode
+widget.close();
+```
+
+### Events (for wrappers / observers)
+
+```js
+widget.addEventListener('beacon-before-submit', (e) => {
+  // mutate or enrich payload
+  e.detail.payload.context.sessionId = mySessionId;
+  // or cancel
+  // e.preventDefault();
+});
+
+widget.addEventListener('beacon-after-submit', (e) => {
+  console.log('submitted', e.detail.response);
+});
+```
+
+### Slots
+
+Override the default trigger button:
+
+```html
+<launchkit-beacon endpoint="/api/feedback" position="hidden">
+  <button slot="trigger">Send feedback</button>
+</launchkit-beacon>
+```
+
+### Theming
+
+```css
+launchkit-beacon {
+  --beacon-accent: #0ea5e9;
+  --beacon-bg: #ffffff;
+  --beacon-fg: #0f172a;
+  --beacon-radius: 12px;
+  --beacon-z-index: 9999;
+}
+```
+
+## Payload shape
+
+Beacon POSTs JSON to your `endpoint`:
+
+```ts
+type FeedbackPayload = {
+  description: string;
+  severity: 'bug' | 'idea' | 'ux' | 'a11y';
+  screenshot?: { dataUrl: string; mime: 'image/jpeg' };
+  metadata: {
+    url: string; referrer?: string;
+    userAgent: string;
+    uaData?: { brand: string; mobile: boolean; platform: string };
+    viewport: { w: number; h: number; dpr: number };
+    screen: { w: number; h: number };
+    timezone: string; locale: string; theme?: 'light' | 'dark';
+    capturedAt: string;
+  };
+  pins: Array<{
+    number: number;
+    note?: string;
+    selector: string;
+    tagName: string; id: string | null; classList: string[];
+    outerHTML: string;            // truncated to 5KB
+    parentOuterHTML?: string;     // truncated to 1KB
+    computedStyles: Record<string, string>;  // ~30 useful properties
+    boundingRect: { x: number; y: number; w: number; h: number };
+    framework?: { lib: 'react'|'vue'|'angular'|'svelte'|null; name?: string };
+  }>;
+  context?: Record<string, unknown>;
+};
+```
+
+Your endpoint's response is forwarded into the `beacon-after-submit` event.
+
+## Honest limitations
+
+- **Cross-origin iframes are opaque.** Same-Origin Policy hard-blocks DOM access into them. The picker can highlight the iframe boundary but not its contents.
+- **Framework component names are best-effort.** In production builds with minification, names are usually stripped (`t.A` instead of `LoginButton`). We probe and include when available; you'll get `null` otherwise.
+- **No source-file/line capture.** Would require source maps + a server-side resolver — out of scope for v1.
+- **No "which CSS rule produced this property" data.** `getMatchedCSSRules()` was removed from all major browsers.
+- **html-to-image quirks** apply: cross-origin `<img>` tags need `crossorigin="anonymous"`, custom `@font-face` fonts need same-origin URLs, video frames render blank, animated GIFs frozen at first frame.
+
+For most in-app feedback use cases, what we capture is plenty: outerHTML, selector, computed styles, bounding rect, and an annotated viewport screenshot.
+
+## License
+
+MIT