@ganeshdole/brainbox-widget 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,28 @@
+O'Saasy License
+
+Copyright © 2026, Ganesh Dole.
+
+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:
+
+1. The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including
+any modified or derivative versions) to directly compete with the
+original Licensor by offering it to third parties as a hosted, managed,
+or Software-as-a-Service (SaaS) product or cloud service where the
+primary value of the service is the functionality of the Software itself.
+
+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

@@ -1,3 +1,94 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @ganeshdole/brainbox-widget
+
+Brainbox's own capture UI: the floating button, the markup step, the
+recorder, the composer. Built on `@ganeshdole/brainbox-core` and `@ganeshdole/brainbox-react`.
+Three ways in, one UI.
+
+## Script tag
+
+For a page with no build step. Paste before `</body>`:
+
+```html
+<script src="https://app.brainbox.sh/widget.js"
+        data-project="pk_..."
+        data-endpoint="https://app.brainbox.sh/ingest"></script>
+```
+
+| Attribute | Values | Default |
+|---|---|---|
+| `data-project` | your project key | required |
+| `data-endpoint` | where reports are POSTed | required |
+| `data-mode` | `float` (our button) or `mount` (your own trigger) | `float` |
+| `data-mount` | CSS selector of your trigger, with `data-mode="mount"` | |
+| `data-position` | `bottom-right`, `bottom-left`, `top-right`, `top-left` | `bottom-right` |
+
+The tag publishes `window.Brainbox` with `open()`, `start(mode)`, `close()` and
+`identify({ id, email })`, and fires a `brainbox:submitted` event on `window`
+(`event.detail.id`) after each report.
+
+## In a React app
+
+```sh
+npm install @ganeshdole/brainbox-widget @ganeshdole/brainbox-react @ganeshdole/brainbox-core
+```
+
+```tsx
+import { BrainboxProvider } from "@ganeshdole/brainbox-react";
+import { BrainboxWidget, useBrainboxWidget } from "@ganeshdole/brainbox-widget";
+
+<BrainboxProvider transport={transport} identity={user}>
+  <App />
+  <BrainboxWidget />                         {/* trigger="floating" | "manual", position */}
+</BrainboxProvider>
+
+function ReportProblemButton() {
+  const { open } = useBrainboxWidget();      // anywhere under the provider
+  return <button onClick={open}>Report a problem</button>;
+}
+```
+
+`open()` shows our chooser. If your own UI already offers the two choices,
+`start("screenshot")` or `start("record")` goes straight into one. Recording
+falls back to the chooser in a browser that cannot record (`canSessionRecord()`
+from `@ganeshdole/brainbox-core` tells you in advance).
+
+The widget renders into a shadow root appended to `<body>`, wherever it sits
+in your tree, so your styles cannot reach it and no ancestor's `overflow` or
+`transform` can trap its panels. Your React is used; the package does not
+bundle one. Clicks on the widget stop at its shadow host, so a menu your page
+closes on an outside click stays open while the user reports it (a listener in
+the capture phase still sees them).
+
+## Without React, from a bundler
+
+```ts
+import { mount } from "@ganeshdole/brainbox-widget";
+import { brainboxTransport } from "@ganeshdole/brainbox-core";
+
+const widget = mount({ transport: brainboxTransport({ endpoint, projectKey }), trigger: "manual" });
+widget.open();
+widget.identify({ id, email });
+widget.destroy();
+```
+
+## Where things live
+
+| Concern | Package |
+|---|---|
+| What gets captured and sent | `@ganeshdole/brainbox-core` |
+| Holding an instance in React | `@ganeshdole/brainbox-react` |
+| What the user sees | this package |
+
+Reports go wherever the `Transport` sends them. `brainboxTransport()` is
+Brainbox Cloud; see `@ganeshdole/brainbox-core` for pointing one at your own backend.
+
+## Build
+
+`pnpm build` emits `dist/widget.js` (the script-tag IIFE, everything bundled
+except the capture libraries), `dist/widget-capture.js` (rrweb and
+modern-screenshot, which `widget.js` loads from beside itself the first time the
+widget opens - serve the two files from the same folder), `dist/index.js` (an ES module of the library entry with React, `lucide-react`
+and the other `@ganeshdole/brainbox-*` packages external) and the `.d.ts` files. Inside
+the monorepo the package is consumed from source; the published package's
+`exports` point at `dist/` (`publishConfig`). `react` and `react-dom` are peer
+dependencies of the library; the IIFE still bundles them.

package/dist/App.d.ts

@@ -0,0 +1,10 @@
+import { type Brainbox } from "@ganeshdole/brainbox-core";
+import type { TriggerMode } from "@ganeshdole/brainbox-shared";
+import type { Position } from "./lib/position.ts";
+export declare function App({ brainbox, hostEl, trigger, position, }: {
+    brainbox: Brainbox;
+    /** The shadow host: left out of screenshots. */
+    hostEl: HTMLElement;
+    trigger: TriggerMode;
+    position: Position;
+}): import("react").JSX.Element;

package/dist/components/BarVisualizer.d.ts

@@ -0,0 +1,7 @@
+/** A row of level bars, themed with brainbox tokens rather than the shadcn ones
+ *  ElevenLabs UI's `bar-visualizer` ships with. `dimFrom` greys everything at or
+ *  past that index, which is how a recorded clip doubles as a playback scrubber. */
+export declare const BarRow: import("react").MemoExoticComponent<({ levels, dimFrom, }: {
+    levels: readonly number[];
+    dimFrom?: number;
+}) => import("react").JSX.Element>;

package/dist/components/Chooser.d.ts

@@ -0,0 +1,8 @@
+import { type Position } from "../lib/position.ts";
+export declare function Chooser({ position, canRecord, onScreenshot, onRecord, onCancel, }: {
+    position: Position;
+    canRecord: boolean;
+    onScreenshot: () => void;
+    onRecord: () => void;
+    onCancel: () => void;
+}): import("react").JSX.Element;

package/dist/components/Composer.d.ts

@@ -0,0 +1,13 @@
+import { type Position } from "../lib/position.ts";
+export declare function Composer({ screenshotUrl, videoUrl, sessionReady, voiceCaptured, capturePending, captureFailed, position, onCancel, onSubmit, }: {
+    screenshotUrl?: string;
+    videoUrl?: string;
+    sessionReady?: boolean;
+    voiceCaptured?: boolean;
+    /** Screenshot still rasterising - the composer opens without waiting for it. */
+    capturePending?: boolean;
+    captureFailed?: boolean;
+    position: Position;
+    onCancel: () => void;
+    onSubmit: (text: string, audio: Blob | null) => void;
+}): import("react").JSX.Element;

package/dist/components/Launcher.d.ts

@@ -0,0 +1,5 @@
+import { type Position } from "../lib/position.ts";
+export declare function Launcher({ position, onClick }: {
+    position: Position;
+    onClick: () => void;
+}): import("react").JSX.Element;

package/dist/components/MarkShape.d.ts

@@ -0,0 +1,20 @@
+import { type Mark } from "@ganeshdole/brainbox-core";
+/** One mark as SVG. Shared by the markup step and the in-recording overlay so
+ *  a box drawn in one looks identical in the other - and matches the bake,
+ *  which draws the same geometry onto a canvas. */
+export declare const MarkShape: import("react").MemoExoticComponent<({ mark }: {
+    mark: Mark;
+}) => import("react").JSX.Element>;
+/** The floating input a text mark is typed into, positioned so the text sits
+ *  where the baked glyphs will land. */
+export declare function MarkTextInput({ at, color, onChange, onCommit, onCancel, }: {
+    at: {
+        x: number;
+        y: number;
+        value: string;
+    };
+    color: string;
+    onChange: (value: string) => void;
+    onCommit: () => void;
+    onCancel: () => void;
+}): import("react").JSX.Element;

package/dist/components/MarkupOverlay.d.ts

@@ -0,0 +1,17 @@
+import { type Mark } from "@ganeshdole/brainbox-core";
+/**
+ * The markup step: the page is frozen and the end-user draws on it - boxes,
+ * arrows, freehand, text - before saying what's wrong.
+ *
+ * The screenshot is already rasterising when this mounts, so the marks are held
+ * as vectors here and baked onto the shot on the way out. Drawing never waits
+ * on the capture, and everything stays undoable right up to Done.
+ */
+export declare function MarkupOverlay({ frozenUrl, pending, failed, onDone, onCancel, }: {
+    /** The frozen page, once rasterised. Until then the live page shows through. */
+    frozenUrl?: string;
+    pending: boolean;
+    failed: boolean;
+    onDone: (marks: Mark[]) => void;
+    onCancel: () => void;
+}): import("react").JSX.Element;

package/dist/components/MarkupToolbar.d.ts

@@ -0,0 +1,13 @@
+import { type Tool } from "@ganeshdole/brainbox-core";
+export declare function MarkupToolbar({ tool, color, canUndo, canDelete, onTool, onColor, onUndo, onDelete, onCancel, onDone, }: {
+    tool: Tool;
+    color: string;
+    canUndo: boolean;
+    canDelete: boolean;
+    onTool: (t: Tool) => void;
+    onColor: (c: string) => void;
+    onUndo: () => void;
+    onDelete: () => void;
+    onCancel: () => void;
+    onDone: () => void;
+}): import("react").JSX.Element;

package/dist/components/RecordOverlay.d.ts

@@ -0,0 +1,8 @@
+import { type Annotations } from "@ganeshdole/brainbox-core";
+export declare function RecordOverlay({ annotations, onStop, micActive, onMuteChange, }: {
+    /** The recording's marks on the host page - drawn here, cleared by core. */
+    annotations: Annotations;
+    onStop: () => void;
+    micActive: () => boolean;
+    onMuteChange: (muted: boolean) => void;
+}): import("react").JSX.Element;

package/dist/components/Result.d.ts

@@ -0,0 +1,8 @@
+import { type Position } from "../lib/position.ts";
+export declare function Result({ kind, id, message, position, onClose, }: {
+    kind: "loading" | "success" | "error";
+    id?: string;
+    message?: string;
+    position: Position;
+    onClose?: () => void;
+}): import("react").JSX.Element;

package/dist/components/VoiceNote.d.ts

@@ -0,0 +1,6 @@
+/** Voice capture as the primary way to file a report: one big mic target, bars
+ *  that track the speaker's voice per frequency band, and playback before
+ *  sending - people won't submit audio they can't hear back. */
+export declare function VoiceNote({ onChange }: {
+    onChange: (b: Blob | null) => void;
+}): import("react").JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { BrainboxWidget, type BrainboxWidgetProps } from "./widget.tsx";
+export { useBrainboxWidget } from "./use-brainbox-widget.ts";
+export { mount, type MountOptions, type WidgetHandle } from "./mount.tsx";
+export type { Position } from "./lib/position.ts";
+export type { CaptureMode } from "./lib/widget-store.ts";
+export type { TriggerMode } from "@ganeshdole/brainbox-shared";