@outcode/bug-reporter-web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OutCode Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @outcode/bug-reporter-web
+
+[![npm version](https://img.shields.io/npm/v/@outcode/bug-reporter-web.svg)](https://www.npmjs.com/package/@outcode/bug-reporter-web)
+[![npm downloads](https://img.shields.io/npm/dm/@outcode/bug-reporter-web.svg)](https://www.npmjs.com/package/@outcode/bug-reporter-web)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6.svg)](https://www.typescriptlang.org/)
+
+**In-app bug reporter for React (web).** Drop in a floating button — your users capture the current
+screen, annotate it (draw, arrow, box, blur, text), set a severity and type, and file a report to
+**ClickUp** or any custom backend. No backend code required to get started.
+
+> Part of the [OutCode Bug Reporter](https://github.com/OutCode-Software/bug-reporter) monorepo.
+> For React Native, see [`@outcode/bug-reporter-native`](https://www.npmjs.com/package/@outcode/bug-reporter-native).
+
+## Features
+
+- 🎯 **One component** — `<BugReporterButton />` runs the whole capture → annotate → form → done flow
+- ✏️ **Annotate** — pen, arrow, box, **blur/redact**, and text, flattened onto the screenshot
+- 🧭 **Auto-captured context** — route, browser, viewport, language, connection type, console errors… all consent-free
+- 🎨 **Themeable** — Indigo / Noir / Mint presets or your own tokens
+- 📡 **Offline retry queue**, **log/breadcrumb capture**, screenshot **size guard**
+- 🧩 **Pluggable backends** — ClickUp out of the box, or any `repository` / HTTP endpoint
+- 📦 Tree-shakeable ESM + CJS, fully typed
+
+## Install
+
+```bash
+npm install @outcode/bug-reporter-web @outcode/bug-reporter-core
+# peers:
+npm install react react-dom
+```
+
+`html2canvas` is bundled — no extra install needed.
+
+## Quick start
+
+```tsx
+import { BugReporterButton } from '@outcode/bug-reporter-web';
+import { ClickUpBugReporterRepository } from '@outcode/bug-reporter-core';
+
+export function App() {
+  return (
+    <>
+      {/* …your app… */}
+      <BugReporterButton
+        config={{
+          appName: 'My Web App',
+          appVersion: '1.0.0',
+          theme: 'indigo',
+          repository: new ClickUpBugReporterRepository({
+            apiKey: import.meta.env.VITE_CLICKUP_API_KEY,
+            problemListId: import.meta.env.VITE_CLICKUP_PROBLEM_LIST_ID,
+            suggestionListId: import.meta.env.VITE_CLICKUP_SUGGESTION_LIST_ID,
+          }),
+        }}
+      />
+    </>
+  );
+}
+```
+
+No ClickUp? Use the default HTTP backend instead: `config={{ appName, apiUrl: 'https://your-api/bug-report' }}`.
+
+> ⚠️ Don't ship a ClickUp API key in a public web bundle. Prefer the `apiUrl` path behind a server
+> proxy that holds the key; reserve direct-to-ClickUp for internal/trusted builds.
+
+## Configuration
+
+Full `BugReporterConfig` reference (theme, `screenshot` size guard, offline `storage`, `collectContext`,
+`collectDiagnostics`, `backendName`, …) lives in the
+[root README](https://github.com/OutCode-Software/bug-reporter#readme).
+
+## License
+
+MIT © OutCode Software

package/dist/index.d.mts

@@ -0,0 +1,136 @@
+import React from 'react';
+import { BugReporterConfig, AnnotationTool, ReportSeverity, ReportType, ScreenshotOptions, Annotation, ReportQueueStorage, BugReporterTheme } from '@outcode/bug-reporter-core';
+
+/**
+ * Bug reporter (web) — floating button + full capture→annotate→form→done flow,
+ * matching the OC-BugReporter design. Orchestrates the step state machine and
+ * hosts the themed overlays (annotate editor, slide-in form, success card).
+ */
+
+interface BugReporterButtonProps {
+    config: BugReporterConfig;
+    /** Accessible label for the floating button. */
+    label?: string;
+    /** Override styles for the floating button. */
+    style?: React.CSSProperties;
+}
+declare function BugReporterButton({ config, label, style }: BugReporterButtonProps): React.JSX.Element;
+
+/**
+ * Full-screen annotation editor (web) — ported from the OC-BugReporter design.
+ * Tools: pen, arrow, box, blur, text. Renders the captured screenshot fitted to
+ * the viewport with a live SVG/visual overlay and the AnnotateToolbar on top.
+ * On Continue, flattens annotations into a single PNG.
+ */
+
+interface AnnotateOverlayProps {
+    src: string;
+    onCancel: () => void;
+    /** Called with the flattened screenshot data URL and the annotation count. */
+    onContinue: (flattenedDataUrl: string, annotationCount: number) => void;
+}
+declare function AnnotateOverlay({ src, onCancel, onContinue }: AnnotateOverlayProps): React.JSX.Element;
+
+/**
+ * Annotation toolbar (web) — tools, color palette, undo/clear, Continue.
+ * Ported from the OC-BugReporter AnnotateToolbar design. Uses CSS vars from the
+ * reporter root for theming.
+ */
+
+interface AnnotateToolbarProps {
+    tool: AnnotationTool;
+    color: string;
+    onTool: (t: AnnotationTool) => void;
+    onColor: (c: string) => void;
+    onUndo: () => void;
+    onClear: () => void;
+    onContinue: () => void;
+}
+declare function AnnotateToolbar({ tool, color, onTool, onColor, onUndo, onClear, onContinue, }: AnnotateToolbarProps): React.JSX.Element;
+
+/**
+ * Bug report form (web) — ported from the OC-BugReporter BugReportForm design.
+ * Summary, description, severity, type, collapsible auto-captured context, and a
+ * "Filing to …" footer. Rendered as a right slide-in panel by the orchestrator.
+ */
+
+interface MetaRow {
+    label: string;
+    value: string;
+    flag?: 'err' | 'warn';
+}
+interface BugReportFormProps {
+    screenshotUrl?: string;
+    annotationCount: number;
+    title: string;
+    description: string;
+    severity: ReportSeverity;
+    type: ReportType;
+    meta: MetaRow[];
+    backendName: string;
+    submitting: boolean;
+    error?: string;
+    onTitle: (v: string) => void;
+    onDescription: (v: string) => void;
+    onSeverity: (s: ReportSeverity) => void;
+    onType: (t: ReportType) => void;
+    onBack: () => void;
+    onClose: () => void;
+    onEditAnnotations: () => void;
+    onSubmit: () => void;
+}
+declare function BugReportForm(props: BugReportFormProps): React.JSX.Element;
+
+/**
+ * Success card (web) — ported from the OC-BugReporter "Report filed" state.
+ */
+
+interface SuccessCardProps {
+    ticket?: string;
+    ticketTitle: string;
+    backendName: string;
+    onDone: () => void;
+}
+declare function SuccessCard({ ticket, ticketTitle, backendName, onDone }: SuccessCardProps): React.JSX.Element;
+
+/**
+ * Captures the current viewport (visible screen) as a PNG/JPEG data URL.
+ * Uses html2canvas; runs in browser only. Applies an optional size guard
+ * (maxWidth downscale + format/quality) so large/retina screens don't produce
+ * multi-megabyte uploads.
+ */
+
+/**
+ * Capture the visible viewport as a data URL (for display and for API base64).
+ */
+declare function captureViewport(options?: ScreenshotOptions): Promise<string | undefined>;
+/** Strip data URL prefix to get raw base64 for API. */
+declare function dataUrlToBase64(dataUrl: string): string;
+
+/**
+ * Composite annotations onto the screenshot, producing a single PNG data URL.
+ * Shapes are stored in display (stage) pixels; we scale them to the image's
+ * natural pixel size so the exported image is full resolution.
+ */
+
+declare function flattenAnnotations(src: string, shapes: Annotation[], dispW: number, dispH: number): Promise<string>;
+
+/**
+ * Default web storage adapter for the offline retry queue, backed by localStorage.
+ * Returns undefined in non-browser / storage-disabled environments (SSR, private
+ * mode with blocked storage), so callers can treat the queue as unavailable.
+ */
+
+declare function getDefaultWebStorage(): ReportQueueStorage | undefined;
+
+/**
+ * Web theme helpers — turn resolved theme tokens into CSS custom properties so
+ * the design's `var(--accent)` style strings work verbatim, and shared font stacks.
+ */
+
+/** CSS custom properties for a theme, to spread onto the reporter root element. */
+declare function cssVars(t: BugReporterTheme): Record<string, string>;
+/** Inject the reporter keyframes once. Safe no-op on the server. */
+declare function ensureKeyframes(): void;
+
+export { AnnotateOverlay, type AnnotateOverlayProps, AnnotateToolbar, BugReportForm, type BugReportFormProps, BugReporterButton, type BugReporterButtonProps, type MetaRow, SuccessCard, captureViewport, cssVars, dataUrlToBase64, ensureKeyframes, flattenAnnotations, getDefaultWebStorage };

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+import React from 'react';
+import { BugReporterConfig, AnnotationTool, ReportSeverity, ReportType, ScreenshotOptions, Annotation, ReportQueueStorage, BugReporterTheme } from '@outcode/bug-reporter-core';
+
+/**
+ * Bug reporter (web) — floating button + full capture→annotate→form→done flow,
+ * matching the OC-BugReporter design. Orchestrates the step state machine and
+ * hosts the themed overlays (annotate editor, slide-in form, success card).
+ */
+
+interface BugReporterButtonProps {
+    config: BugReporterConfig;
+    /** Accessible label for the floating button. */
+    label?: string;
+    /** Override styles for the floating button. */
+    style?: React.CSSProperties;
+}
+declare function BugReporterButton({ config, label, style }: BugReporterButtonProps): React.JSX.Element;
+
+/**
+ * Full-screen annotation editor (web) — ported from the OC-BugReporter design.
+ * Tools: pen, arrow, box, blur, text. Renders the captured screenshot fitted to
+ * the viewport with a live SVG/visual overlay and the AnnotateToolbar on top.
+ * On Continue, flattens annotations into a single PNG.
+ */
+
+interface AnnotateOverlayProps {
+    src: string;
+    onCancel: () => void;
+    /** Called with the flattened screenshot data URL and the annotation count. */
+    onContinue: (flattenedDataUrl: string, annotationCount: number) => void;
+}
+declare function AnnotateOverlay({ src, onCancel, onContinue }: AnnotateOverlayProps): React.JSX.Element;
+
+/**
+ * Annotation toolbar (web) — tools, color palette, undo/clear, Continue.
+ * Ported from the OC-BugReporter AnnotateToolbar design. Uses CSS vars from the
+ * reporter root for theming.
+ */
+
+interface AnnotateToolbarProps {
+    tool: AnnotationTool;
+    color: string;
+    onTool: (t: AnnotationTool) => void;
+    onColor: (c: string) => void;
+    onUndo: () => void;
+    onClear: () => void;
+    onContinue: () => void;
+}
+declare function AnnotateToolbar({ tool, color, onTool, onColor, onUndo, onClear, onContinue, }: AnnotateToolbarProps): React.JSX.Element;
+
+/**
+ * Bug report form (web) — ported from the OC-BugReporter BugReportForm design.
+ * Summary, description, severity, type, collapsible auto-captured context, and a
+ * "Filing to …" footer. Rendered as a right slide-in panel by the orchestrator.
+ */
+
+interface MetaRow {
+    label: string;
+    value: string;
+    flag?: 'err' | 'warn';
+}
+interface BugReportFormProps {
+    screenshotUrl?: string;
+    annotationCount: number;
+    title: string;
+    description: string;
+    severity: ReportSeverity;
+    type: ReportType;
+    meta: MetaRow[];
+    backendName: string;
+    submitting: boolean;
+    error?: string;
+    onTitle: (v: string) => void;
+    onDescription: (v: string) => void;
+    onSeverity: (s: ReportSeverity) => void;
+    onType: (t: ReportType) => void;
+    onBack: () => void;
+    onClose: () => void;
+    onEditAnnotations: () => void;
+    onSubmit: () => void;
+}
+declare function BugReportForm(props: BugReportFormProps): React.JSX.Element;
+
+/**
+ * Success card (web) — ported from the OC-BugReporter "Report filed" state.
+ */
+
+interface SuccessCardProps {
+    ticket?: string;
+    ticketTitle: string;
+    backendName: string;
+    onDone: () => void;
+}
+declare function SuccessCard({ ticket, ticketTitle, backendName, onDone }: SuccessCardProps): React.JSX.Element;
+
+/**
+ * Captures the current viewport (visible screen) as a PNG/JPEG data URL.
+ * Uses html2canvas; runs in browser only. Applies an optional size guard
+ * (maxWidth downscale + format/quality) so large/retina screens don't produce
+ * multi-megabyte uploads.
+ */
+
+/**
+ * Capture the visible viewport as a data URL (for display and for API base64).
+ */
+declare function captureViewport(options?: ScreenshotOptions): Promise<string | undefined>;
+/** Strip data URL prefix to get raw base64 for API. */
+declare function dataUrlToBase64(dataUrl: string): string;
+
+/**
+ * Composite annotations onto the screenshot, producing a single PNG data URL.
+ * Shapes are stored in display (stage) pixels; we scale them to the image's
+ * natural pixel size so the exported image is full resolution.
+ */
+
+declare function flattenAnnotations(src: string, shapes: Annotation[], dispW: number, dispH: number): Promise<string>;
+
+/**
+ * Default web storage adapter for the offline retry queue, backed by localStorage.
+ * Returns undefined in non-browser / storage-disabled environments (SSR, private
+ * mode with blocked storage), so callers can treat the queue as unavailable.
+ */
+
+declare function getDefaultWebStorage(): ReportQueueStorage | undefined;
+
+/**
+ * Web theme helpers — turn resolved theme tokens into CSS custom properties so
+ * the design's `var(--accent)` style strings work verbatim, and shared font stacks.
+ */
+
+/** CSS custom properties for a theme, to spread onto the reporter root element. */
+declare function cssVars(t: BugReporterTheme): Record<string, string>;
+/** Inject the reporter keyframes once. Safe no-op on the server. */
+declare function ensureKeyframes(): void;
+
+export { AnnotateOverlay, type AnnotateOverlayProps, AnnotateToolbar, BugReportForm, type BugReportFormProps, BugReporterButton, type BugReporterButtonProps, type MetaRow, SuccessCard, captureViewport, cssVars, dataUrlToBase64, ensureKeyframes, flattenAnnotations, getDefaultWebStorage };