voice-ring 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,554 @@
+import { CanvasHTMLAttributes } from 'react';
+import { CSSProperties } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+
+export declare const ACCENT_COLORS: Record<VoiceOrbAccent, OrbTint>;
+
+/**
+ * An AnalyserNode fed by `stream`, plus the function that tears it down.
+ * Returns null when the browser has no Web Audio or the stream carries no
+ * audio track.
+ */
+export declare function acquireAnalyser(stream: MediaStream): AnalyserLease | null;
+
+export declare interface AnalyserLease {
+    analyser: AnalyserNode;
+    release: () => void;
+}
+
+declare interface Dot {
+    x: number;
+    y: number;
+    z: number;
+    r: number;
+    /** Ink value: 0 = darkest ink on paper. Mirrored on dark themes. */
+    white: number;
+    a?: number;
+}
+
+/** Soft, slightly desaturated hues that sit well beside gray ink. */
+export declare const EMOTION_COLORS: Record<VoiceOrbEmotion, OrbTint>;
+
+declare interface FollowerConfig {
+    sensitivity: number;
+    threshold: number;
+    attack: number;
+    release: number;
+    idle: number;
+    /** The voice clock runs at 1 + driveGain × level. */
+    driveGain: number;
+    /** Waiting pace: with no voice and no work the clocks run at this share of the tuned speed. */
+    calm: number;
+    /** Orb seconds per real second: the type's tuned speed × the `speed` prop. */
+    rate: number;
+    /** Working on what was heard: sources are ignored and the processing motion eases in. */
+    processing: boolean;
+    /** Where the source says the voice is, −1 left … 1 right (0 when unknown). */
+    direction: number;
+}
+
+/**
+ * How a luminous frame is lit. Its strokes are painted as light rather
+ * than ink — a conic spectrum around the orb, bloomed in soft passes, with
+ * chromatic fringes and specular hot spots — and everything the painter
+ * needs is here, so a port can draw it too (an AngularGradient in SwiftUI).
+ */
+declare interface FrameLight {
+    /** Orb centre and rest radius, CSS px. */
+    cx: number;
+    cy: number;
+    r: number;
+    /** The spectrum: `[offset 0–1, r, g, b]` stops around the orb… */
+    stops: Array<[number, number, number, number]>;
+    /** …starting at this angle, radians clockwise from +x. */
+    angle: number;
+    /** Overall brightness, ~0.6 at rest to ~1.3 in full voice. */
+    intensity: number;
+    /** Strength of the soft halo around the rings, 0 for none. */
+    halo: number;
+    /** Specular hot spots, white light pooled where it touches the rings. */
+    spec: Array<{
+        x: number;
+        y: number;
+        r: number;
+        a: number;
+    }>;
+    /** Chromatic fringe offset, as a share of `r`. */
+    fringe: number;
+}
+
+/**
+ * The page's shared AudioContext, created on first use. Call it from a
+ * user gesture (the microphone button) where you can: Safari only lets a
+ * context start inside one. It is resumed on every call, so a context the
+ * browser suspended in the background picks up again.
+ */
+export declare function getAudioContext(): AudioContext | null;
+
+/**
+ * Web Audio plumbing shared by every VoiceOrb instance.
+ *
+ * One AudioContext for the page, one MediaStreamAudioSourceNode per stream
+ * (reference-counted, so several orbs can listen to the same microphone),
+ * and one AnalyserNode per instance. Nothing is connected to the
+ * destination, so the audio is analysed but never played back.
+ */
+/** True when this browser can analyse audio at all. */
+export declare function isAudioSupported(): boolean;
+
+/** How strongly the orb leans, each as a share of its radius at full pan. */
+declare interface LeanAmounts {
+    /** The whole orb drifts toward the voice. */
+    move: number;
+    /** The near side is drawn out further than the far side — a stretch. */
+    pull: number;
+    /** The near flank bulges, strongest at the equator. */
+    deform: number;
+    /** Pressing on at the screen's edge, it squashes against it: 0 never … 1 most. */
+    squash?: number;
+    /** Pressing on at the edge, it is refracted into it as through glass: 0 none … 1 … 2 most. */
+    lens?: number;
+    /** The lens draws it out toward the edge (distortion): 0 none … 1 … 2. */
+    stretch?: number;
+    /** The lens parts red from blue (chromatic aberration): 0 none … 1 … 2. */
+    split?: number;
+    /** The lens blurs it, more the nearer the edge: 0 none … 1 … 2. */
+    blur?: number;
+    /** It bounces as it meets the edge: 0 none … 1 … 2. */
+    bounce?: number;
+}
+
+export declare type MicrophoneState = 'idle' | 'requesting' | 'live' | 'denied' | 'unsupported' | 'error';
+
+/** Where a leaning orb meets the screen's edge, and how hard it presses. */
+declare interface OrbContact {
+    /** -1 the left edge, 1 the right. */
+    side: number;
+    /** The edge, CSS px: marks stop here. */
+    x: number;
+    /** The stretch of the face that meets it, top and bottom. */
+    y0: number;
+    y1: number;
+    /** How deep into the orb the squash reaches. */
+    depth: number;
+    /** 0 just touching … 1 pressing hard. */
+    press: number;
+    /** The refraction into the edge, for the painter; none when it is off. */
+    lens?: OrbLens;
+}
+
+/**
+ * One rendered instant: a complete, final set of draw instructions.
+ * Strokes paint first, then `dots` in array order (already z-sorted
+ * far → near), so nodes sit on top of the lines they ride.
+ */
+declare interface OrbFrame {
+    dots: Dot[];
+    strokes: Stroke[];
+    /** Present on luminous types: paint the strokes as coloured light. */
+    light?: FrameLight;
+    /** Paint the dots as squares, `r` their half side: pixels, not points. */
+    square?: boolean;
+    /** Set by the lean while the orb presses on the screen's edge. */
+    contact?: OrbContact;
+}
+
+/**
+ * The lens a pressing orb is refracted through, CSS px. A zone back from
+ * the edge it begins; toward the edge it draws the image out across the
+ * gap the orb rests short by, opens it taller by `flare`, parts red from
+ * blue by `split` and blurs it by `blur`, each at full strength at the edge.
+ */
+declare interface OrbLens {
+    zone: number;
+    gap: number;
+    flare: number;
+    split: number;
+    blur: number;
+    /** The height the flare opens from. */
+    cy: number;
+}
+
+/**
+ * Theme mode, resolved exactly as thinking-orbs does: `auto` (default)
+ * reads an ancestor `data-theme` / `.dark` / `.light`, then
+ * `prefers-color-scheme`, live. `dark` draws light ink, `light` dark ink.
+ */
+export declare type OrbTheme = 'auto' | 'dark' | 'light';
+
+/** Optional ink tint, resolved to an RGB triple (0–255 each). */
+declare interface OrbTint {
+    r: number;
+    g: number;
+    b: number;
+}
+
+declare interface Preset {
+    /** Orb seconds per real second, on both clocks. */
+    speed: number;
+    /** The voice clock runs at 1 + driveGain × level. */
+    driveGain: number;
+    /** Input gain tuned for the type, under the `sensitivity` prop. Default 1. */
+    gain?: number;
+    /** The type's rise time, when the `attack` prop is not set. Default 0.06 s. */
+    attack?: number;
+    /** The type's mark size, when the `dotSize` prop is not set. Default 1. */
+    dotSize?: number;
+    /** How much a voice speeds the type up, when the `voiceSpeed` prop is not set. Default 1. */
+    voiceSpeed?: number;
+    /** The type's own lean, where the `direction…` props are not set. Default LEAN_DEFAULTS. */
+    lean?: Partial<LeanAmounts>;
+    /** CSS px the lean stops short of the screen's edge, when `directionMargin` is not set. Default 32. */
+    margin?: number;
+    /** Knobs at the 200px design. */
+    opts: TypeOpts;
+    /** Count knobs → the exponent each takes of the size × density scale. */
+    counts: Record<string, number>;
+}
+
+export declare const PRESETS: Record<VoiceOrbType, Preset>;
+
+declare interface Resolved {
+    frame: TypeFrame;
+    speed: number;
+    driveGain: number;
+    gain: number;
+    opts: TypeOpts;
+}
+
+/** Resolve a type at a size, with the density and dot-size multipliers. */
+export declare function resolvePreset(type: VoiceOrbType, size: number, dots?: number, dotSize?: number): Resolved;
+
+export declare const SPECTRUM_N = 16;
+
+/** A polyline in screen space whose opacity varies point to point. */
+declare interface Stroke {
+    /** Flat `[x0, y0, x1, y1, …]` in CSS px. */
+    pts: number[];
+    /** Opacity per point — depth fades the far side of a line. */
+    a: number[];
+    /** Ink value, same convention as `Dot.white`. */
+    white: number;
+    /** Width in CSS px. */
+    w: number;
+    closed?: boolean;
+}
+
+/**
+ * Geometry for one instant: pure math over (size, t, voice, opts), no
+ * rendering surface and no theme. `t` is the ambient clock (spin, sway);
+ * `voice.drive` is the clock a voice speeds up.
+ */
+export declare type TypeFrame = (size: number, t: number, voice: VoiceInput, opts: TypeOpts) => OrbFrame;
+
+/** Type knobs. Numbers only, so a preset survives JSON and native ports. */
+export declare interface TypeOpts {
+    [key: string]: number | undefined;
+}
+
+/**
+ * Microphone access for VoiceOrb.
+ *
+ * ```tsx
+ * const mic = useMicrophone();
+ * <button onClick={mic.start}>Listen</button>
+ * <VoiceOrb type="orbit" stream={mic.stream} />
+ * ```
+ *
+ * The stream is stopped on unmount, and when the browser ends the track
+ * (device unplugged, permission revoked) the state falls back to 'idle'.
+ */
+export declare function useMicrophone(options?: UseMicrophoneOptions): UseMicrophoneResult;
+
+export declare interface UseMicrophoneOptions {
+    /**
+     * Extra `getUserMedia` audio constraints. The defaults turn the browser's
+     * voice processing off (echo cancellation, noise suppression, auto gain)
+     * so the orb sees the real dynamics of the voice rather than a levelled
+     * signal; pass `{}` to keep the browser defaults.
+     */
+    constraints?: MediaTrackConstraints;
+    /** Ask for the microphone on mount rather than waiting for `start()`. */
+    autoStart?: boolean;
+}
+
+export declare interface UseMicrophoneResult {
+    /** The live stream to hand to `<VoiceOrb stream={…}>`, or null. */
+    stream: MediaStream | null;
+    state: MicrophoneState;
+    /** The error behind a 'denied' / 'error' state, if any. */
+    error: Error | null;
+    /** True when this browser can capture audio at all. */
+    supported: boolean;
+    /** Request the microphone. Call it from a click so Safari lets audio start. */
+    start: () => Promise<MediaStream | null>;
+    /** Stop every track and drop the stream. */
+    stop: () => void;
+}
+
+export declare const VOICE_ORB_TYPES: readonly VoiceOrbType[];
+
+export declare class VoiceFollower {
+    /** Real seconds this orb has run: onsets and breathing keep time on it. */
+    clock: number;
+    /** The ambient clock (spin, sway) in orb seconds. */
+    t: number;
+    /** The voice clock, in orb seconds. */
+    drive: number;
+    private level;
+    private bands;
+    private spectrum;
+    private floor;
+    /** The voice alone on the soft envelope — what wakes the clocks. */
+    private heard;
+    private proc;
+    private spin;
+    private pan;
+    private panVel;
+    private raw;
+    private timeBuf;
+    private freqBuf;
+    private out;
+    /** Read an analyser: RMS loudness, three voice bands and the spectrum. */
+    readAnalyser(analyser: AnalyserNode, sensitivity: number, dt: number): void;
+    /**
+     * Read a plain level. There is no spectrum behind it, so the bands and
+     * slots are given a little independent life — slow, out-of-phase drifts
+     * scaled by the level, with two formant-like humps wandering the
+     * spectrum — so a level-driven orb still moves like a voice.
+     */
+    readLevel(level: number, sensitivity: number): void;
+    /** Nothing to read: let every envelope settle. */
+    readSilence(): void;
+    /** Advance by `dt` real seconds. `still` (reduced motion) holds the clocks. */
+    step(dt: number, cfg: FollowerConfig, still: boolean): VoiceInput;
+}
+
+/**
+ * What the voice is doing at one instant, already gated, saturated and
+ * smoothed — every value can go straight into geometry. The follower in
+ * `voice.ts` builds it from a microphone, any AnalyserNode or a plain
+ * level; a custom renderer can just as well build it by hand.
+ */
+export declare interface VoiceInput {
+    /** Loudness envelope, 0–1, with the idle breathing folded in. */
+    level: number;
+    /** Low / mid / high envelopes, 0–1: chest, vowels, sibilance. */
+    bands: [number, number, number];
+    /** `level` on a slow envelope (~0.35 s up, ~0.9 s down): for shape and
+     *  amplitude, which read as mechanical if they pump with every syllable. */
+    soft: number;
+    /** `bands` on the same slow envelope. */
+    softBands: [number, number, number];
+    /** Log-spaced spectrum envelope, low → high, 0–1 per slot. */
+    spectrum: ArrayLike<number>;
+    /**
+     * The voice clock, in seconds: it runs at 1 + gain × level, so motion
+     * driven by it speeds up while someone speaks and settles after — with
+     * no jump, since it is integrated rather than multiplied.
+     */
+    drive: number;
+    /**
+     * How far into the processing state, 0–1, eased: the orb is working on
+     * what it heard. Sources are ignored meanwhile; each type answers with
+     * its own working motion (a contraction, a sweep, a beat).
+     */
+    processing: number;
+    /**
+     * Processing's turn, in radians, for motion that goes round while the orb
+     * works (a spinning spectrum, a sweeping highlight). It is integrated, so
+     * it speeds up and slows down with the eased blend instead of jumping,
+     * and once processing ends it settles back to the nearest whole turn.
+     */
+    spin: number;
+    /**
+     * Where the voice comes from, −1 left … 1 right, smoothed: it follows the
+     * source while a voice is heard and drifts back to centre in silence.
+     */
+    pan: number;
+}
+
+export declare function VoiceOrb({ type, state, size, stream, analyser, level, sensitivity, threshold, attack, release, idle, calm, voiceSpeed: voiceSpeedProp, emotion, emotionColors, saturation, accent, gradientAngle, gradientSpin, neutral, colorBrightness, colorHue, gradientStart, gradientWidth, direction, directionMove, directionPull, directionDeform, directionSquash, directionLens, directionStretch, directionSplit, directionBlur, directionBounce, directionMargin: marginProp, directionBounds, theme, speed, paused, color, dots, dotSize: dotSizeProp, opts: optsOverride, frame: customFrame, onLevel, style, 'aria-label': ariaLabel, ...rest }: VoiceOrbProps): JSX_2.Element;
+
+/** Colourful mode's accents: the same three hues, by colour. */
+export declare type VoiceOrbAccent = 'green' | 'red' | 'blue';
+
+export declare type VoiceOrbEmotion = 'positive' | 'negative' | 'calm';
+
+/** Props for the VoiceOrb React component. */
+export declare interface VoiceOrbProps extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'style'> {
+    /** Which orb. @default 'orbit' */
+    type?: VoiceOrbType;
+    /** Conversation state; changes ease, never cut. @default 'listening' */
+    state?: VoiceOrbState;
+    /** Rendered size in CSS px; any size, designed at 200. @default 160 */
+    size?: number;
+    /**
+     * A live audio stream — usually `useMicrophone().stream`. The orb opens
+     * its own analyser on it (shared with any other orb on the same stream)
+     * and wins over `analyser` and `level`.
+     */
+    stream?: MediaStream | null;
+    /**
+     * Any AnalyserNode you already have: the assistant's voice playing
+     * through an `<audio>` element or a WebRTC track, say. Wins over `level`.
+     */
+    analyser?: AnalyserNode | null;
+    /**
+     * Drive it yourself, 0–1. A number for occasional changes, or a getter
+     * sampled every frame without re-rendering your tree.
+     */
+    level?: number | (() => number);
+    /** Input gain — raise for quiet sources. @default 0.85 */
+    sensitivity?: number;
+    /** Noise gate: below this the orb hears silence. @default 0.04 */
+    threshold?: number;
+    /** Seconds to rise. @default 0.06 (0.16 for `pixel`) */
+    attack?: number;
+    /** Seconds to settle. @default 0.32 */
+    release?: number;
+    /** Breathing kept under the voice, so silence never looks dead; 0 for none. @default 0.1 */
+    idle?: number;
+    /**
+     * Waiting pace: with no voice and nothing processing, the clocks run at
+     * this share of the tuned speed — low for a calm, slow orb. @default 0.4
+     */
+    calm?: number;
+    /** How much a voice speeds the motion up, as a multiplier on the type's tuning. @default 1 (0.9 for `aura`) */
+    voiceSpeed?: number;
+    /**
+     * An emotion detected in the voice — `positive` (green), `negative`
+     * (red) or `calm` (blue). Its colour drifts through the orb in soft
+     * patches, near marks taking it most; it eases in, crossfades between
+     * emotions and fades out on `null`. Detection is yours to supply.
+     * @default null
+     */
+    emotion?: VoiceOrbEmotion | null;
+    /** Override any emotion's colour as an RGB triple (0–255). */
+    emotionColors?: Partial<Record<VoiceOrbEmotion, OrbTint>>;
+    /**
+     * Colourful mode, for the ink types (orbit, sash, signal, swell, pixel): a
+     * two-colour gradient across the orb, from the neutral ink into one
+     * colour, every mark keeping its depth shading. The colour is the
+     * `emotion`'s when one is set, else `accent`; with neither the orb stays
+     * neutral. `saturation` is how strong the colour gets: 0 never, 1 the
+     * colour itself, up to 2 purer and deeper still. Aura keeps its own spectrum.
+     * @default 2
+     */
+    saturation?: number;
+    /** Colourful mode: a fixed colour for the gradient, shown even without an emotion. @default null */
+    accent?: VoiceOrbAccent | null;
+    /** Colourful mode: which way the gradient runs, in degrees — 0 left → right, 90 top → bottom. @default 99 */
+    gradientAngle?: number;
+    /** Colourful mode: how fast the gradient turns, degrees per second; 0 holds it still. @default 12 */
+    gradientSpin?: number;
+    /**
+     * Where the voice comes from, −1 left … 1 right — a number, or a getter
+     * sampled every frame. While a voice is heard the orb leans that way (it
+     * drifts, is pulled out and bulges on the near side) and settles back to
+     * centre in silence. Supply it from a stereo estimate (the SwiftUI port
+     * reads the iPhone's stereo mics) or drive it yourself.
+     */
+    direction?: number | (() => number);
+    /**
+     * Lean: how far the orb drifts toward the voice, as a share of its radius.
+     * Every `direction…` amount left unset takes the type's own; `aura`
+     * barely drifts but leans, bulges a touch, never squashes, and meets the
+     * edge through a softer lens. @default 2 (aura 0.21)
+     */
+    directionMove?: number;
+    /** Lean: how far its near side is pulled out beyond the far side. @default 0.7 (aura 0.36) */
+    directionPull?: number;
+    /** Lean: how much the near flank bulges. @default 0.1 (aura 0.28) */
+    directionDeform?: number;
+    /** Lean: pressing on at the screen's edge, how much the orb squashes against it, 0–1. @default 0.5 (aura 0) */
+    directionSquash?: number;
+    /**
+     * Lean: pressing on at the screen's edge, how strongly the orb is refracted
+     * into it, as through glass — it rests short of the edge and its near side
+     * is drawn out across the gap, its colours parted and blurred toward the
+     * edge. 0 none … 1 … 2 most. @default 0.67 (aura 0.49)
+     */
+    directionLens?: number;
+    /** Lean: how far the edge lens draws the orb out toward the edge (distortion), 0–2. @default 1 (aura 1.04) */
+    directionStretch?: number;
+    /** Lean: how far the edge lens parts red from blue (chromatic aberration), 0–2. @default 1 (aura 1.01) */
+    directionSplit?: number;
+    /** Lean: how much the edge lens blurs, more the nearer the edge, 0–2. @default 1 (aura 1.24) */
+    directionBlur?: number;
+    /** Lean: how much the orb bounces as it meets the edge, 0–2. @default 1 (aura 0.92) */
+    directionBounce?: number;
+    /** Lean: CSS px the orb stops short of the screen's edge. @default 32 */
+    directionMargin?: number;
+    /**
+     * Lean: an element whose left and right edges the orb leans up to instead
+     * of the screen's — a card or a panel it lives in (a ref). Clip that
+     * element (`overflow: hidden`) so the glow past the margin is cut there.
+     */
+    directionBounds?: {
+        readonly current: Element | null;
+    };
+    /**
+     * Colourful mode: how neutral the gradient's start is — 1 begins in the
+     * plain monochrome ink and gathers the accent toward the far side, 0
+     * covers the orb in the accent end to end. @default 1
+     */
+    neutral?: number;
+    /** Colourful mode: the colour's brightness, a multiplier on its lightness. @default 1.02 */
+    colorBrightness?: number;
+    /** Colourful mode: degrees to turn the colour's hue. @default 0 */
+    colorHue?: number;
+    /** Colourful mode: where across the orb (0–1) the colour begins to come in. @default 0.1 */
+    gradientStart?: number;
+    /** Colourful mode: how far across the orb (0–1) the colour takes to arrive in full. @default 0.6 */
+    gradientWidth?: number;
+    /** Theme mode; `auto` detects from the host project. @default 'auto' */
+    theme?: OrbTheme;
+    /** Speed multiplier on the type's tuned clocks. @default 1 */
+    speed?: number;
+    /** Freeze on the current frame. @default false */
+    paused?: boolean;
+    /** Optional ink tint — `#rgb`, `#rrggbb` or `rgb()`; depth shading is kept on it. */
+    color?: string;
+    /** Density multiplier on the type's dot / line counts. @default 1 */
+    dots?: number;
+    /** Multiplier on every dot radius. @default 1 (0.55 for `pixel`) */
+    dotSize?: number;
+    /** Advanced: raw type knobs merged over the resolved preset, last. */
+    opts?: TypeOpts;
+    /** Escape hatch: replace the type's geometry, same contract as `TYPE_FRAMES`. */
+    frame?: TypeFrame;
+    /** Called every frame with the shaped level, 0–1 — for a meter or a label. */
+    onLevel?: (level: number) => void;
+    style?: CSSProperties;
+}
+
+/**
+ * The conversation state:
+ * - `idle`       — waiting for someone to talk: sources ignored, a calm, very slow drift
+ * - `listening`  — the user's turn: follows the source (usually the microphone)
+ * - `speaking`   — the assistant's turn: follows the source (usually its playback)
+ * - `processing` — working on what was heard: sources ignored, each type's working motion
+ *
+ * Listening and speaking draw the same way; the source is what differs.
+ * Without a voice, either one settles into the same calm pace as `idle`.
+ */
+export declare type VoiceOrbState = 'idle' | 'listening' | 'speaking' | 'processing';
+
+/**
+ * The six orb types:
+ * - `orbit`   — particles on tilted orbits in perspective; a voice zooms it toward you
+ * - `sash`    — an undulating band of dotted lanes; a voice deepens the wave
+ * - `signal`  — a wireframe of great circles; a voice deforms it like a skin
+ * - `swell`   — a halftone sphere of drifting clouds; a voice bulges its surface
+ * - `pixel`   — a ball of square pixels, halftone shaded; a voice bulges it and lights it in rings
+ * - `aura`    — signal's rings drawn in light: a blooming spectrum; a voice bends and brightens it
+ */
+export declare type VoiceOrbType = 'orbit' | 'sash' | 'signal' | 'swell' | 'pixel' | 'aura';
+
+/** A voice-reactive ring of light: VoiceOrb with `type="aura"` fixed. */
+export declare function VoiceRing(props: VoiceRingProps): JSX_2.Element;
+
+export declare type VoiceRingProps = Omit<VoiceOrbProps, 'type' | 'frame'>;
+
+export { }