/**
 * MixVisualizer — the scrolling Mix waveform background (Phase 9, 8.K Wave 2).
 *
 * What this renders: a *windowed* slice of a mix's loudness profile, scrolling
 * bottom-to-top, coupled to playback position. New audio enters at the bottom,
 * already-played audio exits off the top, and the "now" playhead sits at a fixed
 * line (vertical centre by default). This is a read-only, ambient lava-lamp
 * background — there is no seek, no click handling, no write-back to playback.
 *
 * Rendering tech: HTML5 Canvas 2D. This is the industry-standard, well-documented
 * choice for a single flowing gradient waveform: createLinearGradient gives us the
 * theme gradient directly, and layered translucent draws give the glassy look
 * without any exotic tricks. Canvas 2D holds 60fps comfortably here because each
 * frame draws one filled path of a few hundred points, not a per-pixel shader.
 * (If this ever fails the 60fps budget at the glassy treatment, the textbook next
 * step is WebGL — but we are nowhere near needing it, so we stay on Canvas 2D.)
 *
 * The Blazor component owns the canvas element and the inputs (datum, playback,
 * zoom, theme); this module owns the requestAnimationFrame loop and all the
 * drawing/scroll/zoom math. The component drives it through the small handle
 * returned by `create`.
 */

// ── Tuning anchors (see spec §B). These are the load-bearing constants. ──────────

/**
 * Hard anchor: at maximum zoom the window shows exactly one quarter note at
 * 180 BPM = 60 / 180 s = 0.333 s of audio, top to bottom. This is a fixed
 * requirement, not a tunable.
 */
export const MIN_VISIBLE_SECONDS = 60 / 180; // 0.3333… s — quarter note @ 180 BPM

/** Slow end of the zoom range — how much of the mix is visible at minimum zoom. Tunable. */
export const MAX_VISIBLE_SECONDS = 30;

/** Default opening window when a mix is first opened. Tunable. */
export const DEFAULT_VISIBLE_SECONDS = 10;

/**
 * Where the "now" line sits within the window, as a fraction from the top.
 * 0.5 = vertical centre (default): a short lead-in below, a short trail-out above.
 * Tunable.
 */
const NOW_ANCHOR_FROM_TOP = 0.5;

/** Background opacity of the whole ribbon — keeps it a backdrop, not a chart. */
const RIBBON_OPACITY = 0.22;

// ── Theme: the gradient stop colours, read live from the active MudBlazor palette. ─
//
// We do NOT take colours from Blazor: canvas createLinearGradient stop colours must be concrete
// CSS colour strings (it does not resolve `var(--…)`). Instead the module reads the computed
// `--mud-palette-*` custom properties straight off the canvas element, which inherits them from the
// page. The bespoke light/dark themes ("Charleston in the Day" / "Lowcountry Summer Nights") swap
// those vars when dark mode toggles, so re-reading them re-themes the gradient with no reload. The
// component just calls `refreshTheme()` after a dark-mode change.

interface ResolvedTheme {
    /** Colour at the "now" line (brightest). Concrete CSS colour. */
    accent: string;
    /** Colour at the window edges (dimmer). Concrete CSS colour. */
    edge: string;
}

/** Read a CSS custom property off an element, falling back if it is empty/undefined. */
function readVar(el: Element, name: string, fallback: string): string {
    const v = getComputedStyle(el).getPropertyValue(name).trim();
    return v.length > 0 ? v : fallback;
}

// ── Datum: the pre-downloaded loudness profile (spec §F). ────────────────────────

interface Datum {
    /** Loudness samples, each already normalized to [0, 1]. */
    samples: Float32Array;
    /** Total mix duration in seconds — needed to map time <-> sample index. */
    durationSeconds: number;
    /**
     * samplesPerSecond = samples.length / durationSeconds. Wave 1 made the sample
     * count duration-derived (~333/s), so this is NOT a fixed 2048/duration — we
     * always compute it from the actual datum length.
     */
    samplesPerSecond: number;
}

interface Playback {
    /** Current playback head in seconds. */
    positionSeconds: number;
    /** Whether audio is actively playing — gates the rAF loop so a paused mix stays cool. */
    isPlaying: boolean;
}

export interface MixVisualizerHandle {
    setDatum(samplesBase64: string, durationSeconds: number): void;
    setPlayback(positionSeconds: number, isPlaying: boolean): void;
    setZoom(visibleSeconds: number): void;
    /** Re-read the palette CSS vars off the canvas (call after a dark-mode toggle). */
    refreshTheme(): void;
    dispose(): void;
}

/**
 * Decode the base64 loudness datum (bytes [0,255]) into normalized [0,1] floats.
 * Done once per datum, off the animation path.
 */
function decodeSamples(base64: string): Float32Array {
    const binary = atob(base64);
    const out = new Float32Array(binary.length);
    for (let i = 0; i < binary.length; i++) {
        out[i] = binary.charCodeAt(i) / 255; // [0,255] -> [0,1]
    }
    return out;
}

export function create(canvas: HTMLCanvasElement): MixVisualizerHandle {
    const maybeCtx = canvas.getContext('2d');
    if (!maybeCtx) {
        // No 2D context (extremely old/headless engine): hand back a no-op handle so
        // the component still functions as a plain backdrop.
        return {
            setDatum() {},
            setPlayback() {},
            setZoom() {},
            refreshTheme() {},
            dispose() {},
        };
    }
    // Non-null binding so the closures below (draw/frame) keep the narrowing.
    const ctx: CanvasRenderingContext2D = maybeCtx;

    // ── Mutable state, fed by the component through the handle. ──────────────────
    let datum: Datum | null = null;
    let playback: Playback = { positionSeconds: 0, isPlaying: false };
    let visibleSeconds = DEFAULT_VISIBLE_SECONDS;

    /** Resolve the gradient stops from the live palette vars on the canvas. */
    function readTheme(): ResolvedTheme {
        return {
            // Brightest stop at the "now" line — the bespoke themes' primary accent.
            accent: readVar(canvas, '--mud-palette-primary', '#b08d57'),
            // Dim stop at the edges — the surface/background colour so the ribbon fades into the page.
            edge: readVar(canvas, '--mud-palette-surface', '#1a1a1a'),
        };
    }

    let theme: ResolvedTheme = readTheme();

    let rafId: number | null = null;
    let disposed = false;

    // Backing-store size in device pixels, tracked so we only resize the canvas
    // (which clears it) when the CSS box actually changed.
    let cssWidth = 0;
    let cssHeight = 0;
    let dpr = 1;

    // ── ResizeObserver: one-shot redraw when the container changes while idle. ────
    //
    // While the rAF loop is running (playing), syncCanvasSize() catches resizes each
    // frame. While idle (paused/stopped), we use a ResizeObserver instead — it fires
    // only when the element actually changes size, which is far cheaper than a 60fps
    // tick. On each observation we do a single one-shot redraw.
    const resizeObserver = new ResizeObserver(() => {
        if (!playback.isPlaying && !disposed) {
            // Loop is not running; draw one still frame reflecting the new size.
            redrawOnce();
        }
        // If the loop IS running, syncCanvasSize() inside frame() will catch it next
        // tick — no action needed here.
    });
    resizeObserver.observe(canvas);

    /**
     * Sync the canvas backing store to its CSS size × devicePixelRatio so the draw
     * is crisp on HiDPI without blurring. Returns true if a resize happened.
     */
    function syncCanvasSize(): boolean {
        const rect = canvas.getBoundingClientRect();
        const nextDpr = window.devicePixelRatio || 1;
        // Cap DPR at 2: beyond that the extra pixels cost frame time for no visible
        // gain on a soft glassy backdrop (graceful-degrade lever, spec §E).
        const effectiveDpr = Math.min(nextDpr, 2);
        if (rect.width === cssWidth && rect.height === cssHeight && effectiveDpr === dpr) {
            return false;
        }
        cssWidth = rect.width;
        cssHeight = rect.height;
        dpr = effectiveDpr;
        canvas.width = Math.max(1, Math.round(cssWidth * dpr));
        canvas.height = Math.max(1, Math.round(cssHeight * dpr));
        return true;
    }

    /**
     * THE SCROLL + ZOOM MATH (spec §A, §B). Read this top to bottom to follow how
     * a quarter-note-@-180-BPM becomes 0.333 s becomes N samples becomes pixels.
     *
     * Coordinate model:
     *   - The canvas is `cssHeight` px tall (we draw in CSS px; the ctx is scaled by
     *     dpr so 1 unit == 1 CSS px).
     *   - The "now" line is a fixed screen Y: nowY = cssHeight * NOW_ANCHOR_FROM_TOP.
     *   - Audio flows UP: time increases downward in the data, but newer audio is
     *     drawn lower and scrolls up past the now line. So:
     *       * audio BELOW the now line (screen Y > nowY) is the lead-in (not yet played)
     *       * audio ABOVE the now line (screen Y < nowY) is the trail-out (just played)
     *
     * Zoom -> time-span -> pixels:
     *   - `visibleSeconds` is the entire window's time span, top to bottom. At max
     *     zoom this is MIN_VISIBLE_SECONDS (0.333 s); at min zoom MAX_VISIBLE_SECONDS.
     *   - pixelsPerSecond = cssHeight / visibleSeconds. Smaller visibleSeconds =>
     *     more px per second => the same audio sweeps the window faster at a fixed
     *     playback rate. That IS the Guitar-Hero coupling: apparent scroll speed
     *     falls straight out of the zoom, with no separate speed control.
     *
     * Time at a given screen Y:
     *   - At nowY the time is playback.positionSeconds.
     *   - Moving DOWN by 1 px adds (1 / pixelsPerSecond) seconds (future audio).
     *   - So:  timeAt(y) = now + (y - nowY) / pixelsPerSecond
     *
     * Sample at a given time (spec §F mapping, BucketCount-driven, never fixed-2048):
     *   - sampleIndex = round(time * samplesPerSecond), where
     *     samplesPerSecond = datum.samples.length / datum.durationSeconds.
     *   - Out-of-range indices (before 0 or past the end) draw as zero amplitude,
     *     which is what gives the "scrolls in from empty / out to empty" behaviour
     *     at the very start and end of the mix (spec §A) with no special-casing.
     */
    function draw(): void {
        const w = cssWidth;
        const h = cssHeight;
        ctx.setTransform(dpr, 0, 0, dpr, 0, 0); // draw in CSS px, crisp on HiDPI
        ctx.clearRect(0, 0, w, h);

        if (!datum || h <= 0 || w <= 0) return;

        const now = playback.positionSeconds;
        const nowY = h * NOW_ANCHOR_FROM_TOP;
        const pixelsPerSecond = h / visibleSeconds;
        const samplesPerSecond = datum.samplesPerSecond;
        const sampleCount = datum.samples.length;

        // We draw one screen row per pixel of height (a few hundred points) — smooth
        // at every zoom with no stair-stepping, cheap enough for 60fps.
        const centreX = w / 2;
        // Max half-width of the ribbon (mirrored silhouette), with a small margin.
        const maxHalfWidth = (w / 2) * 0.92;

        // Build the mirrored closed path: down the right edge (top->bottom), then back
        // up the left edge (bottom->top). amplitude maps loudness [0,1] to half-width.
        ctx.beginPath();

        // Right edge, top to bottom.
        for (let y = 0; y <= h; y++) {
            const t = now + (y - nowY) / pixelsPerSecond; // time at this screen row
            const amp = sampleAt(t);
            const x = centreX + amp * maxHalfWidth;
            if (y === 0) ctx.moveTo(x, y);
            else ctx.lineTo(x, y);
        }
        // Left edge, bottom to top (mirror).
        for (let y = h; y >= 0; y--) {
            const t = now + (y - nowY) / pixelsPerSecond;
            const amp = sampleAt(t);
            const x = centreX - amp * maxHalfWidth;
            ctx.lineTo(x, y);
        }
        ctx.closePath();

        // ── Glassy gradient fill (spec §C). ─────────────────────────────────────
        // Vertical gradient brightest at the now line, dimming toward both edges —
        // this is the optional luminosity cue that reinforces the playhead without a
        // hard played/unplayed boundary. Stops come from the live MudBlazor palette.
        const grad = ctx.createLinearGradient(0, 0, 0, h);
        const nowStop = clamp01(nowY / h);
        grad.addColorStop(0, theme.edge);          // top edge (trail-out), dim
        grad.addColorStop(nowStop, theme.accent);  // the "now" line, brightest
        grad.addColorStop(1, theme.edge);          // bottom edge (lead-in), dim

        // Two layered draws give the frosted/lit-glass depth: a soft wide glow under
        // a crisper core, both translucent. No backdrop-filter needed on the canvas
        // itself (the CSS layer adds blur); this is pure standard 2D compositing.
        ctx.globalCompositeOperation = 'source-over';

        // Soft luminous halo.
        ctx.globalAlpha = RIBBON_OPACITY * 0.6;
        ctx.shadowColor = theme.accent;
        ctx.shadowBlur = 24 * dpr;
        ctx.fillStyle = grad;
        ctx.fill();

        // Crisp core on top, no shadow.
        ctx.shadowBlur = 0;
        ctx.globalAlpha = RIBBON_OPACITY;
        ctx.fillStyle = grad;
        ctx.fill();

        ctx.globalAlpha = 1;
    }

    /** Loudness at an absolute mix time, or 0 outside the mix (drives scroll-in/out from empty). */
    function sampleAt(timeSeconds: number): number {
        if (!datum) return 0;
        if (timeSeconds < 0 || timeSeconds >= datum.durationSeconds) return 0;
        const idx = Math.round(timeSeconds * datum.samplesPerSecond);
        if (idx < 0 || idx >= datum.samples.length) return 0;
        return datum.samples[idx];
    }

    function clamp01(v: number): number {
        return v < 0 ? 0 : v > 1 ? 1 : v;
    }

    // ── rAF loop lifecycle (spec §E: cool when paused/backgrounded). ─────────────
    //
    // DESIGN: The loop runs ONLY while playing. When paused or stopped, no frames
    // are scheduled. The still slice stays correct via one-shot redraws triggered by
    // the handle methods (setZoom, refreshTheme, setDatum) and by ResizeObserver.
    //
    // Start/stop contract:
    //   startLoop()  — schedules the first frame if not already running. Safe to call
    //                   redundantly; the rafId guard prevents double-loops.
    //   stopLoop()   — cancels any pending frame. The current frame callback will see
    //                   playback.isPlaying === false and will NOT reschedule itself, so
    //                   this is belt-and-suspenders for the dispose() path.
    //   redrawOnce() — draw one still frame synchronously (no rAF scheduling). Used
    //                   by setZoom/refreshTheme/setDatum/ResizeObserver while idle.

    /**
     * Draw one still frame immediately, without scheduling a new rAF. Syncs the
     * canvas size first so zoom/theme/datum/resize changes are reflected correctly
     * even when the loop is not running.
     */
    function redrawOnce(): void {
        if (disposed) return;
        syncCanvasSize();
        draw();
    }

    /**
     * Start the rAF loop. No-op if already running or disposed — the rafId guard
     * ensures at most one loop is live at any time.
     */
    function startLoop(): void {
        if (disposed || rafId !== null) return;
        rafId = requestAnimationFrame(frame);
    }

    /**
     * Stop the rAF loop. Safe to call when already stopped.
     */
    function stopLoop(): void {
        if (rafId !== null) {
            cancelAnimationFrame(rafId);
            rafId = null;
        }
    }

    /**
     * The animation loop. Runs only while playing. Each frame:
     *   1. Syncs the canvas backing-store size (cheap no-op when nothing changed).
     *   2. Redraws the scrolling waveform with the current playback position.
     *   3. Reschedules itself — unless playback has stopped since this frame was
     *      queued, in which case it draws one final still frame and exits the loop.
     *
     * A backgrounded tab gets rAF throttled by the browser automatically. On top of
     * that, the loop does not run at all when paused — so a foregrounded-but-paused
     * mix burns no rAF budget (spec §E acceptance criterion).
     */
    function frame(): void {
        if (disposed) {
            rafId = null;
            return;
        }

        syncCanvasSize();
        draw();

        if (playback.isPlaying) {
            // Still playing — schedule the next frame.
            rafId = requestAnimationFrame(frame);
        } else {
            // Playback stopped between the time this frame was queued and now.
            // We already drew the final still frame above; exit the loop.
            rafId = null;
        }
    }

    // Kick off one still frame on creation so the canvas is not blank while idle
    // before the first play command arrives.
    redrawOnce();

    return {
        setDatum(samplesBase64: string, durationSeconds: number): void {
            if (durationSeconds <= 0 || !samplesBase64) {
                datum = null;
                return;
            }
            const samples = decodeSamples(samplesBase64);
            datum = {
                samples,
                durationSeconds,
                // samplesPerSecond from the ACTUAL datum length — never assume 2048.
                samplesPerSecond: samples.length / durationSeconds,
            };
            // New datum changes what is drawn — refresh the still slice immediately.
            // If playing, the running loop will pick it up on the next frame automatically.
            if (!playback.isPlaying) redrawOnce();
        },

        setPlayback(positionSeconds: number, isPlaying: boolean): void {
            const wasPlaying = playback.isPlaying;
            playback = { positionSeconds, isPlaying };

            if (isPlaying && !wasPlaying) {
                // Transition: paused/stopped → playing. Start the rAF loop.
                startLoop();
            } else if (!isPlaying && wasPlaying) {
                // Transition: playing → paused/stopped. The current in-flight frame
                // will draw the final still position and exit the loop on its own
                // (frame() checks playback.isPlaying before rescheduling). We do NOT
                // call stopLoop() here — that would cancel the in-flight frame before
                // it draws, leaving a stale or blank canvas. Let the frame run out.
            }
            // If isPlaying unchanged (position-only update), the running loop (if any)
            // will redraw on the next frame automatically; no action needed.
        },

        setZoom(seconds: number): void {
            // Clamp into the supported span so a stray value can't break the math.
            visibleSeconds = Math.min(MAX_VISIBLE_SECONDS, Math.max(MIN_VISIBLE_SECONDS, seconds));
            // Zoom changes the still slice — redraw immediately when idle.
            // If playing, the running loop will pick up the new value on the next frame.
            if (!playback.isPlaying) redrawOnce();
        },

        refreshTheme(): void {
            theme = readTheme();
            // Theme change is immediately visible — redraw the still slice when idle.
            // If playing, the running loop will pick up the new theme on the next frame.
            if (!playback.isPlaying) redrawOnce();
        },

        dispose(): void {
            disposed = true;
            stopLoop();
            resizeObserver.disconnect();
        },
    };
}