@ganeshdole/brainbox-core 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,98 @@
-# 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-core
+
+The Brainbox capture engine. Plain TypeScript, runs in the browser, no React
+and no UI. It takes the screenshot, bakes the user's marks into it, records
+the session, keeps the last console errors, and hands the finished report to
+a `Transport`. Every Brainbox UI, including our own widget, is built on it.
+
+Use it directly when you are building your own feedback UI. If you want
+Brainbox's UI, see `@ganeshdole/brainbox-widget`; if you are in React, `@ganeshdole/brainbox-react`
+holds an instance for you.
+
+## Install
+
+Inside this monorepo the package is consumed from source:
+
+```json
+{ "dependencies": { "@ganeshdole/brainbox-core": "workspace:*" } }
+```
+
+Outside it, from npm:
+
+```sh
+npm install @ganeshdole/brainbox-core
+```
+
+`pnpm build` emits `dist/` (JS plus `.d.ts`); the published package's
+`exports` point at it (`publishConfig`).
+
+## Use
+
+```ts
+import { createBrainbox, brainboxTransport } from "@ganeshdole/brainbox-core";
+
+const brainbox = createBrainbox({
+  // Brainbox Cloud, or your own backend (see Transport below)
+  transport: brainboxTransport({ endpoint: "https://app.brainbox.sh/ingest", projectKey: "pk_..." }),
+  identity: { id: user.id, email: user.email },
+  onSubmitted: ({ id }) => console.log("filed", id),
+});
+
+// One report in progress. `exclude` is your own UI's root element, left out
+// of the screenshot.
+const draft = brainbox.draft({ exclude: panelEl });
+draft.subscribe(() => render(draft.getState()));
+
+draft.captureScreenshot();            // start rasterising the page now
+draft.markUp(marks);                  // the marks' bounds become the region; baked in the background
+await draft.submit({ text, audio });  // waits for the bake, then transport.send()
+draft.cancel();                       // drop everything; the draft can be used again
+
+brainbox.destroy();                   // restores console.error, cancels live drafts
+```
+
+A recording instead of a screenshot:
+
+```ts
+const rec = draft.startRecording({ onAutoStop: () => void rec.stop() });
+rec.annotations.show(mark);           // drawn into the page, so it shows in the replay
+rec.setMicMuted(true);
+await rec.stop();                     // attaches the session and voice, takes a thumbnail
+```
+
+`DraftState` is what a UI renders from: `screenshotUrl`, `screenshotPending`,
+`screenshotFailed`, `hasSession`, `hasVoice`. It is a new object on every
+change, so `useSyncExternalStore` and friends can compare by reference.
+
+## Transport
+
+Core does not know about project keys or endpoints. `brainboxTransport()`
+speaks the Brainbox backend's `/ingest` format. To send reports somewhere
+else, implement the one-method interface:
+
+```ts
+import type { Transport } from "@ganeshdole/brainbox-core";
+
+const mine: Transport = {
+  async send(report) {
+    const fd = new FormData();
+    fd.append("json", JSON.stringify({ text: report.text, region: report.region, metadata: report.metadata }));
+    if (report.screenshot) fd.append("screenshot", report.screenshot, "screenshot.png");
+    const res = await fetch("/api/feedback", { method: "POST", body: fd, headers: { Authorization: token } });
+    return { id: (await res.json()).id };
+  },
+};
+```
+
+`Report` carries `text`, `region`, `metadata` (`CapturedMetadata` from
+`@ganeshdole/brainbox-shared`), and the `screenshot`, `session` and `audio` blobs.
+
+## Rules
+
+- Importing does nothing. `createBrainbox()` is the only way in, and
+  `destroy()` undoes everything it set up.
+- No module-level state, so two instances on one page do not share buffers.
+  The one shared thing is the `console.error` hook, installed when the first
+  instance asks and removed when the last one goes.
+- Privacy defaults in recordings: inputs are masked; `.rr-block`, `.rr-mask`
+  and `.rr-ignore` on host elements are honoured.

package/dist/annotate.d.ts

@@ -0,0 +1,35 @@
+import { type Mark } from "./marks.ts";
+/** Marks drawn into the host page during a recording. One set per recording,
+ *  so cancelling one cannot wipe another's and nothing outlives `clear()`. */
+export interface Annotations {
+    /** Put a mark on the page. */
+    show(m: Mark): void;
+    /** Remove the most recent mark. Returns whether there was one to remove. */
+    undo(): boolean;
+    /** How many marks are currently on the page. */
+    count(): number;
+    /** The marks at least partly in view, oldest first, in viewport
+     *  coordinates - what a screenshot taken right now would show. */
+    inView(): Mark[];
+    /** Remove every mark immediately (cleared by the user, or the recording
+     *  stopped or was cancelled). */
+    clear(): void;
+}
+/**
+ * Marks go on the host page itself (NOT the shadow DOM).
+ *
+ * The shadow host is `rr-block`ed so the widget's own chrome stays out of
+ * recordings; putting the mark in the host document instead means rrweb sees
+ * it as ordinary mutations and it replays in the dashboard with no
+ * replay-side support at all.
+ *
+ * Marks are anchored to the **document**, not the viewport, and they stay
+ * until the user clears them. An earlier version expired them after three
+ * seconds, which was the wrong answer to a real problem: a viewport-anchored
+ * mark starts pointing at whatever slid underneath it the moment the page
+ * scrolls. Converting to document coordinates fixes that properly - the mark
+ * rides the content it was drawn on - so there's nothing left for a timer to
+ * protect against, and the user gets to keep an annotation on screen for as
+ * long as they're still talking about it.
+ */
+export declare function createAnnotations(): Annotations;

package/dist/annotate.js

@@ -0,0 +1,152 @@
+import { arrowHead, boundsOf, penPath, translateMark, FONT_STACK, STROKE_WIDTH, TEXT_HALO, TEXT_HALO_WIDTH, TEXT_SIZE, } from "./marks.js";
+const SVG_NS = "http://www.w3.org/2000/svg";
+/** `position` values that make an element a containing block for `absolute`
+ *  descendants. Anything else - including jsdom's empty string for an unset
+ *  property - leaves the document as the containing block. */
+const POSITIONED = new Set(["relative", "absolute", "fixed", "sticky"]);
+/** One mark as SVG built with the DOM API rather than React.
+ *  It has to live in the host document (see `showMark`), which React isn't
+ *  rendering, so this mirrors `MarkShape` node for node. */
+function shapeFor(m) {
+    const el = (tag, attrs) => {
+        const node = document.createElementNS(SVG_NS, tag);
+        for (const [k, v] of Object.entries(attrs))
+            node.setAttribute(k, String(v));
+        return node;
+    };
+    switch (m.kind) {
+        case "box":
+            return el("rect", {
+                x: m.x,
+                y: m.y,
+                width: m.width,
+                height: m.height,
+                fill: "none",
+                stroke: m.color,
+                "stroke-width": STROKE_WIDTH,
+            });
+        case "arrow": {
+            const [tip, left, right] = arrowHead(m);
+            const g = el("g", {});
+            g.appendChild(el("line", {
+                x1: m.x1,
+                y1: m.y1,
+                x2: m.x2,
+                y2: m.y2,
+                stroke: m.color,
+                "stroke-width": STROKE_WIDTH,
+                "stroke-linecap": "round",
+            }));
+            g.appendChild(el("polygon", {
+                points: `${tip.x},${tip.y} ${left.x},${left.y} ${right.x},${right.y}`,
+                fill: m.color,
+            }));
+            return g;
+        }
+        case "pen":
+            return el("path", {
+                d: penPath(m),
+                fill: "none",
+                stroke: m.color,
+                "stroke-width": STROKE_WIDTH,
+                "stroke-linecap": "round",
+                "stroke-linejoin": "round",
+            });
+        case "text": {
+            const t = el("text", {
+                x: m.x,
+                y: m.y,
+                fill: m.color,
+                stroke: TEXT_HALO,
+                "stroke-width": TEXT_HALO_WIDTH,
+                "paint-order": "stroke",
+                "font-size": TEXT_SIZE,
+                "font-weight": 700,
+                "font-family": FONT_STACK,
+            });
+            t.textContent = m.text;
+            return t;
+        }
+    }
+}
+/**
+ * Marks go on the host page itself (NOT the shadow DOM).
+ *
+ * The shadow host is `rr-block`ed so the widget's own chrome stays out of
+ * recordings; putting the mark in the host document instead means rrweb sees
+ * it as ordinary mutations and it replays in the dashboard with no
+ * replay-side support at all.
+ *
+ * Marks are anchored to the **document**, not the viewport, and they stay
+ * until the user clears them. An earlier version expired them after three
+ * seconds, which was the wrong answer to a real problem: a viewport-anchored
+ * mark starts pointing at whatever slid underneath it the moment the page
+ * scrolls. Converting to document coordinates fixes that properly - the mark
+ * rides the content it was drawn on - so there's nothing left for a timer to
+ * protect against, and the user gets to keep an annotation on screen for as
+ * long as they're still talking about it.
+ */
+export function createAnnotations() {
+    /** Marks currently on the page, oldest first, each with the element that
+     *  draws it and the mark itself in document coordinates. */
+    const live = [];
+    return {
+        show(m) {
+            const svg = document.createElementNS(SVG_NS, "svg");
+            svg.setAttribute("data-brainbox-highlight", "");
+            svg.setAttribute("aria-hidden", "true");
+            // Zero-sized with overflow visible: the shapes carry absolute document
+            // coordinates, so the container only has to establish the origin.
+            svg.setAttribute("style", "position:absolute;left:0;top:0;width:0;height:0;overflow:visible;" +
+                "pointer-events:none;z-index:2147483646;");
+            document.body.appendChild(svg);
+            // Measured while the container is still childless, so what comes back is
+            // its own 0x0 box rather than the ink bounds of a shape overflowing it.
+            const origin = originOffset(svg);
+            svg.appendChild(shapeFor(translateMark(m, window.scrollX - origin.x, window.scrollY - origin.y)));
+            live.push({ el: svg, mark: translateMark(m, window.scrollX, window.scrollY) });
+        },
+        undo() {
+            const last = live.pop();
+            last?.el.remove();
+            return !!last;
+        },
+        count: () => live.length,
+        inView() {
+            const w = window.innerWidth;
+            const h = window.innerHeight;
+            return live
+                .map(({ mark }) => translateMark(mark, -window.scrollX, -window.scrollY))
+                .filter((m) => {
+                const b = boundsOf(m);
+                return b.x < w && b.y < h && b.x + b.width > 0 && b.y + b.height > 0;
+            });
+        },
+        clear() {
+            for (const { el } of live)
+                el.remove();
+            live.length = 0;
+        },
+    };
+}
+/**
+ * How far the container's own origin sits from the document origin.
+ *
+ * `position:absolute` resolves against the nearest **positioned** ancestor, not
+ * the document. Usually nothing between the container and the root is
+ * positioned, the containing block is the document, and this is (0, 0) - but a
+ * host page with `body { position: relative }` (common enough to plan for) makes
+ * the body the containing block, and every mark lands offset by wherever the
+ * body's padding box starts. Measuring covers the margin, border and padding
+ * that put it there without having to enumerate them.
+ *
+ * Only the offset is corrected. A transformed `<body>` would also scale or
+ * rotate the marks, which no amount of translation fixes - and which the old
+ * `position:fixed` container got wrong too.
+ */
+function originOffset(container) {
+    if (!POSITIONED.has(getComputedStyle(document.body).position))
+        return { x: 0, y: 0 };
+    const r = container.getBoundingClientRect();
+    return { x: r.left + window.scrollX, y: r.top + window.scrollY };
+}

package/dist/audio.d.ts

@@ -0,0 +1,8 @@
+export interface AudioRecorder {
+    stop: () => Promise<Blob>;
+    /** The live mic stream, for a level meter. Analyse this rather than opening
+     *  the mic a second time. */
+    stream: MediaStream;
+}
+/** Start recording from the mic; resolve a handle whose stop() yields the Blob. */
+export declare function startAudioRecording(): Promise<AudioRecorder>;

package/dist/audio.js

@@ -0,0 +1,23 @@
+const MIME = "audio/webm";
+/** Start recording from the mic; resolve a handle whose stop() yields the Blob. */
+export async function startAudioRecording() {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    const supported = MediaRecorder.isTypeSupported(MIME);
+    const rec = new MediaRecorder(stream, supported ? { mimeType: MIME } : undefined);
+    const chunks = [];
+    rec.ondataavailable = (e) => {
+        if (e.data.size > 0)
+            chunks.push(e.data);
+    };
+    rec.start();
+    return {
+        stream,
+        stop: () => new Promise((resolve) => {
+            rec.onstop = () => {
+                stream.getTracks().forEach((t) => t.stop());
+                resolve(new Blob(chunks, { type: MIME }));
+            };
+            rec.stop();
+        }),
+    };
+}

package/dist/brainbox.d.ts

@@ -0,0 +1,19 @@
+import type { Identity } from "@ganeshdole/brainbox-shared";
+import { type Draft, type DraftOptions } from "./draft.ts";
+import type { SubmitResult, Transport } from "./transport.ts";
+export interface BrainboxOptions {
+    /** Where finished reports go. */
+    transport: Transport;
+    /** Who is filing. Can be set later with `identify()`. */
+    identity?: Identity;
+    /** Called after every successful submit. */
+    onSubmitted?: (result: SubmitResult) => void;
+}
+/** One embedded Brainbox. Collects console errors from the moment it is
+ *  created and hands out drafts; `destroy()` undoes all of it. */
+export interface Brainbox {
+    identify(identity: Identity): void;
+    draft(options?: DraftOptions): Draft;
+    destroy(): void;
+}
+export declare function createBrainbox({ transport, identity, onSubmitted }: BrainboxOptions): Brainbox;

package/dist/brainbox.js

@@ -0,0 +1,28 @@
+import { createDraft } from "./draft.js";
+import { captureErrors } from "./metadata.js";
+export function createBrainbox({ transport, identity, onSubmitted }) {
+    let who = identity;
+    const errors = captureErrors();
+    const drafts = new Set();
+    return {
+        identify(next) {
+            who = next;
+        },
+        draft(options) {
+            const draft = createDraft({
+                transport,
+                identity: () => who,
+                consoleErrors: () => errors.snapshot(),
+                onSubmitted,
+            }, options);
+            drafts.add(draft);
+            return draft;
+        },
+        destroy() {
+            for (const draft of drafts)
+                draft.cancel();
+            drafts.clear();
+            errors.stop();
+        },
+    };
+}

package/dist/capture.d.ts

@@ -0,0 +1,75 @@
+import { type Mark } from "./marks.ts";
+/** `@ganeshdole/brainbox-server`'s default screenshot cap. */
+export declare const SCREENSHOT_BUDGET_BYTES: number;
+export declare function captureScale(devicePixelRatio: number, documentPixels: number): number;
+export declare function overBudget(bytes: number, pixelWidth: number, cssWidth: number): boolean;
+/**
+ * A `filter` that drops everything outside the viewport.
+ *
+ * We rasterise the whole document and then crop to the viewport, so on a long
+ * page most of that work is discarded - a page 4x the viewport pays 4x for one
+ * screenshot, and the cost is CPU-bound cloning and per-node style resolution,
+ * not pixels. Off-screen elements cannot affect a viewport crop, so skipping
+ * them in the clone is free.
+ *
+ * The exception is escaping descendants: an absolutely positioned child is laid
+ * out against an ancestor, so pruning a parent by its own box could drop a child
+ * that was actually on screen. Ancestors of any escaping element are kept whole
+ * and everything else is judged on its own box.
+ *
+ * `exclude` (the UI's own host) is dropped from the clone outright, which is
+ * what keeps its chrome out of the shot - the live page never has to hide it.
+ */
+export declare function viewportFilter(exclude?: HTMLElement): (node: Node) => boolean;
+/** Whether a box can still affect a viewport-sized crop. Split out from the DOM
+ *  walk so the edge cases are unit-testable. */
+export declare function keepForViewport(r: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    width: number;
+    height: number;
+}, vw: number, vh: number): boolean;
+/** What to leave out of a screenshot. */
+export interface CaptureOptions {
+    /** Left out of the cloned page, so the UI's own chrome never appears in the
+     *  shot (ADR 0001). It stays visible on the live page throughout: hiding it
+     *  would blank the UI for the seconds a capture takes. */
+    exclude?: HTMLElement;
+}
+/** modern-screenshot skips cross-origin sheets it can't read (e.g. Google Fonts)
+ *  but fetches `@import`s, so re-declare them as imports to keep their fonts. */
+export declare function unreadableSheetImports(sheets: Iterable<{
+    href: string | null;
+    readonly cssRules: unknown;
+}>): string;
+export declare function withReadableFonts<T>(fn: () => Promise<T>, sheets?: Iterable<{
+    href: string | null;
+    readonly cssRules: unknown;
+}>): Promise<T>;
+/** Plain viewport shot - the frozen page the user marks up, and the
+ *  thumbnail/last-frame of a session recording. */
+export declare function captureViewport(options?: CaptureOptions): Promise<Blob>;
+/**
+ * Flatten the user's markup onto the frozen shot.
+ *
+ * This runs once, on the way out of the markup step, rather than on every
+ * stroke: the marks are vectors until here, so drawing stays instant and
+ * undoable and nothing has to re-rasterise the page. Mark coordinates are
+ * viewport CSS pixels, scaled to the shot's resolution.
+ */
+export declare function bakeMarks(shot: Blob, marks: Mark[]): Promise<Blob>;
+/**
+ * Which screenshot actually gets uploaded.
+ *
+ * Two sources disagree on purpose. `settled` is the last shot that resolved into
+ * state - what the composer is already showing - and `pending` is the freshest
+ * promise for one. Leaving the markup step swaps `pending` for the *baked* shot
+ * while `settled` still holds the plain capture taken before the user drew
+ * anything, so preferring `settled` would quietly upload the version with none
+ * of their markup on it. The promise wins whenever there is one; `settled` is
+ * the fallback for the flows that never had one (a recording's last frame) and
+ * for a capture that failed, where the plain shot is better than nothing.
+ */
+export declare function pickScreenshot(pending: Promise<Blob> | null, settled: Blob | null): Promise<Blob | null>;