@ganeshdole/brainbox-widget 0.0.0-stage → 0.1.0

package/dist/lib/config.d.ts

@@ -0,0 +1,14 @@
+import type { TriggerMode } from "@ganeshdole/brainbox-shared";
+import type { Position } from "./position.ts";
+/** What the script tag asked for, read off its `data-*` attributes. */
+export interface WidgetConfig {
+    projectKey: string;
+    endpoint: string;
+    /** `data-mode="mount"` is the manual trigger: the host opens the widget from
+     *  its own element (`data-mount`) or `window.Brainbox.open()`. */
+    trigger: TriggerMode;
+    mount?: string;
+    position: Position;
+}
+/** Parse the widget config off the embedding <script> tag's data-* attributes. */
+export declare function readConfig(script: HTMLScriptElement | null): WidgetConfig | null;

package/dist/lib/multiband.d.ts

@@ -0,0 +1,31 @@
+/** Frequency-band loudness maths, adapted from ElevenLabs UI's `bar-visualizer`
+ *  (https://ui.elevenlabs.io/docs/components/bar-visualizer). Kept pure and
+ *  separate from the React hook so it is testable without an AudioContext. */
+/** A single FFT bin's dB value as a 0..1 level. The sqrt lifts quiet speech into
+ *  the visible range - a linear map leaves normal talking barely off the floor. */
+export declare function normalizeDb(value: number): number;
+/**
+ * Average `data` into `bands` buckets across the bin range [loPass, hiPass).
+ *
+ * Splitting the spectrum is what makes the meter read as a voice: each bar
+ * tracks its own slice of frequency, so they move independently instead of
+ * showing one overall level duplicated across the row.
+ */
+export declare function bandLevels(data: Readonly<Float32Array>, bands: number, loPass: number, hiPass: number): number[];
+/** True when any band moved enough to be worth a re-render. Called every frame,
+ *  so this is what keeps the meter off the render path while the room is quiet. */
+export declare function bandsChanged(next: readonly number[], prev: readonly number[], threshold?: number): boolean;
+/** A 0..1 level as a bar height percentage. */
+export declare function barHeight(level: number): number;
+/**
+ * One overall 0..1 level from a band set - recorded per tick to redraw the clip
+ * as a static envelope during playback.
+ *
+ * Peak, not mean: averaging across bands cancels out syllables (loud vowels sit
+ * in a couple of bands while the rest stay quiet), which flattens the saved
+ * envelope into a near-constant block. The peak keeps that punch.
+ */
+export declare function peakLevel(bands: readonly number[]): number;
+/** Average a whole clip's recorded levels into `count` buckets - the envelope
+ *  shown as a fixed number of bars once recording stops. */
+export declare function downsample(levels: readonly number[], count: number): number[];

package/dist/lib/position.d.ts

@@ -0,0 +1,3 @@
+export type Position = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+/** Tailwind anchor classes for a fixed element pinned to a viewport corner. */
+export declare function posClass(p: Position): string;

package/dist/lib/scroll-lock.d.ts

@@ -0,0 +1,19 @@
+/** Whether `key` pressed on `target` would scroll the page. In a text field the
+ *  same keys move the caret, and Space on a button presses it (the toolbar's,
+ *  for keyboard users), so those are left alone. */
+export declare function isScrollKey(key: string, target: EventTarget | null): boolean;
+/**
+ * Hold the host page still while the frozen shot is up.
+ *
+ * A `position: fixed` overlay covers the page but doesn't stop the wheel, a
+ * touch drag or the keyboard from scrolling it underneath. That isn't just
+ * cosmetic: marks are drawn in viewport coordinates over the shot, and the
+ * element under them (the region's selector) is read from the live page - a
+ * page that has scrolled since would name the wrong one.
+ *
+ * Scrolling is blocked at the input rather than with `overflow: hidden` on the
+ * root, which would drop the scrollbar and widen the viewport out from under
+ * the shot. A snap-back on `scroll` covers what can't be cancelled, like
+ * dragging a classic scrollbar. Returns the unlock.
+ */
+export declare function lockScroll(win?: Window): () => void;

package/dist/lib/shadow-css.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Prepare the widget's stylesheet for injection into the shadow root.
+ *
+ * Two things the browser will not do for us inside a shadow tree:
+ *
+ * 1. `:root` never matches, so the design-token layer has to be retargeted at
+ *    `:host`.
+ *
+ * 2. `@property` registration is **document-scoped**. Rules inside a shadow
+ *    root's `<style>` are parsed and then ignored, so every custom property
+ *    Tailwind registers there is left with no initial value.
+ *
+ *    That is not cosmetic. Tailwind v4 compiles transforms to
+ *    `translate: var(--tw-translate-x) var(--tw-translate-y)`; with
+ *    `--tw-translate-y` unregistered it resolves to the guaranteed-invalid
+ *    value, which makes the whole declaration invalid at computed-value time
+ *    and drops it. The result is `translate: none` - every `-translate-x-1/2`
+ *    in the widget silently did nothing, so anything centred that way sat half
+ *    its own width to the right.
+ *
+ *    Tailwind emits exactly the right fallback already, but behind an
+ *    `@supports` that only matches browsers *lacking* `@property`. Chrome has
+ *    it, so the guard is false - and Chrome still needs the fallback here.
+ *    Re-declaring each registered property's initial value on a universal
+ *    selector restores it.
+ */
+export declare function shadowCss(css: string): string;

package/dist/lib/shadow-host.d.ts

@@ -0,0 +1,12 @@
+/** The widget's foothold in the host page: one element for `<body>` with a
+ *  shadow root, and inside it the container the React tree renders into. */
+export interface ShadowHost {
+    /** The element for the host document. Hidden while screenshotting. */
+    element: HTMLElement;
+    /** Where to render. Carries the `.dark` class the stylesheet keys off. */
+    container: HTMLElement;
+}
+/** Build the shadow host with the widget stylesheet injected (ADR 0001: host
+ *  CSS cannot reach in, ours cannot leak out). Detached: the caller appends
+ *  `element` to `<body>` when it is ready to show it. */
+export declare function createShadowHost(css: string): ShadowHost;

package/dist/lib/time.d.ts

@@ -0,0 +1,2 @@
+/** Seconds as `m:ss` - shared by the record overlay and the voice note meter. */
+export declare function fmtDuration(total: number): string;

package/dist/lib/use-drawing.d.ts

@@ -0,0 +1,25 @@
+import { type Mark } from "@ganeshdole/brainbox-core";
+/** Tools that are drawn by dragging. `select` and `text` are stateful in ways
+ *  that belong to the surface using them, so they stay out of here. */
+export type DragTool = "box" | "arrow" | "pen";
+export declare function isDragTool(t: string): t is DragTool;
+export declare const nextMarkId: () => string;
+/**
+ * Drag-to-draw, shared by the two surfaces that need it: the markup step and
+ * the annotations drawn during a recording. Keeping it in one place is what
+ * stops the two from drifting into subtly different feels.
+ *
+ * The stroke in progress is mutated on a ref and flushed to state once per
+ * animation frame. A fast drag fires far more pointer events than the display
+ * refreshes, and re-rendering per sample is exactly what makes a drawing
+ * surface feel like it's lagging behind the cursor.
+ */
+export declare function useDrawing({ color, onCommit, }: {
+    color: string;
+    onCommit: (m: Mark) => void;
+}): {
+    draft: Mark | null;
+    begin: (tool: DragTool, e: React.PointerEvent) => void;
+    extend: (e: React.PointerEvent) => void;
+    finish: () => void;
+};

package/dist/lib/use-multiband.d.ts

@@ -0,0 +1,20 @@
+/** Live mic analysis, adapted from ElevenLabs UI's `bar-visualizer`
+ *  (https://ui.elevenlabs.io/docs/components/bar-visualizer). Changes: the
+ *  agent-state sequencer and demo mode are dropped (we only ever show a live
+ *  mic) and the maths moved to multiband.ts so it can be tested. */
+export interface MultibandOptions {
+    bands?: number;
+    /** FFT bin slice spread across the bars. */
+    loPass?: number;
+    hiPass?: number;
+    /** Sampling throttle - rAF fires far more often than the eye needs. */
+    updateInterval?: number;
+    fftSize?: number;
+}
+/**
+ * Per-band loudness of a live mic stream, 0..1 per band.
+ *
+ * The meter is decoration: if the browser gives us no AudioContext the hook
+ * stays flat and the recording carries on regardless.
+ */
+export declare function useMultibandVolume(stream: MediaStream | null, options?: MultibandOptions): number[];

package/dist/lib/widget-store.d.ts

@@ -0,0 +1,15 @@
+import type { Brainbox } from "@ganeshdole/brainbox-core";
+/** Whether the widget UI is open, shared between `<BrainboxWidget />` and
+ *  whoever wants to open it: a host button, `window.Brainbox.open()`. Core
+ *  has no idea of "open"; that is a UI matter, so it lives here. */
+export interface WidgetStore {
+    isOpen(): boolean;
+    subscribe(listener: () => void): () => void;
+    open(): void;
+    close(): void;
+}
+export declare function createWidgetStore(): WidgetStore;
+/** The store for an instance, created on first use. */
+export declare function widgetStore(brainbox: Brainbox): WidgetStore;
+/** For a tree with no instance yet: never open, and nothing to do. */
+export declare const NO_WIDGET: WidgetStore;

package/dist/mount.d.ts

@@ -0,0 +1,18 @@
+import { type BrainboxOptions, type Identity } from "@ganeshdole/brainbox-core";
+import type { TriggerMode } from "@ganeshdole/brainbox-shared";
+import type { Position } from "./lib/position.ts";
+export interface MountOptions extends BrainboxOptions {
+    trigger?: TriggerMode;
+    position?: Position;
+}
+/** The mounted widget, for a host with no React tree of its own. */
+export interface WidgetHandle {
+    open(): void;
+    close(): void;
+    identify(identity: Identity): void;
+    /** Unmount the UI, remove it from the page and destroy the instance. */
+    destroy(): void;
+}
+/** Put the widget on the page. This is what the script-tag bundle calls; a
+ *  React host should render `<BrainboxWidget />` instead. */
+export declare function mount({ trigger, position, ...options }: MountOptions): WidgetHandle;

package/dist/use-brainbox-widget.d.ts

@@ -0,0 +1,6 @@
+/** Open or close the widget from anywhere under the same provider. */
+export declare function useBrainboxWidget(): {
+    isOpen: boolean;
+    open(): void;
+    close(): void;
+};