@joewinke/jatui 0.9.1 → 0.11.0

package/dist/video/advisors/speaker-rate.js

@@ -0,0 +1,322 @@
+/**
+ * Per-speaker playback rate, measured rather than guessed. Ported verbatim
+ * from extension-library `lib/speaker-rate.js` (mos-5lzns.27).
+ *
+ * The manual version of this feature is a speed slider, and a speed slider is
+ * a chore: you nudge it up for the slow host, forget, and then the guest who
+ * talks at 200 wpm arrives sounding auctioned. The premise here is the one
+ * behind loudness matching, one sense over — the app can MEASURE the thing you
+ * were about to compensate for. Words per minute falls straight out of a
+ * diarised transcript (words in a segment, seconds of that segment, attributed
+ * to whoever was talking), so it can propose the rates that put everyone at one
+ * pace and let you keep or discard them. Nobody has to guess "is 1.2 too much
+ * for this one".
+ *
+ * Pure advisor, deliberately (src/lib/video/README.md doctrine): no DOM, no
+ * <video>, no settings reads, no motion (so nothing here for
+ * prefers-reduced-motion to reduce). It answers "how fast is each person
+ * talking, and what would even them out" and stops there — the component
+ * decides whether to apply any of it, and every function returns a safe
+ * neutral value rather than throwing when the data is missing or malformed,
+ * because half this library's videos have no diarisation at all.
+ *
+ *   speakerPace(transcript, speakers)
+ *     -> { bySpeaker: { name: { wpm, words, seconds } }, medianWpm }
+ *   suggestRates(pace, { targetWpm, min, max, step })  -> { name: rate }
+ *   rateAt(t, turns, rates, fallback)                  -> multiplier at time t
+ *   describeRates(pace, rates)                         -> ["Darren 168 wpm → 0.9x", …]
+ *
+ * Input shapes: segments/turns are the same duration-bearing objects the
+ * component already holds (VideoTranscriptSegment / VideoSpeakerTurn read
+ * structurally — `start`/`end` seconds, `text`, `speaker`/`name`, `ad`), so
+ * meeting and scribe data flows straight through. Field names are read with
+ * the extension's spellings (`start`/`end`/`text`/`speaker`/`name`/`ad`);
+ * mos-5lzns.32's wiring maps the component's `Sec`-suffixed props at the call
+ * site if they ever differ.
+ */
+// Under this many words a WPM is an artefact of segment boundaries rather than
+// a speaking style: "Right." alone on a four-second segment reads as 15 wpm,
+// and a three-word interjection inside someone else's sentence reads as 400.
+// Twenty words is roughly eight seconds of continuous speech — the shortest
+// sample that has ever looked like a pace instead of a coincidence.
+const MIN_WORDS = 20;
+// Within ±7% of target, do nothing at all. 1.05 is audible on music and
+// essentially inaudible on speech, so a rate that close buys nothing — and
+// since turns hand off every few seconds, a hair-trigger would have the pitch
+// stepping on every handoff. A rate that flickers 1.0 → 1.05 → 1.0 is worse
+// than no feature; leaving someone alone is a real answer.
+const DEADZONE = 0.07;
+const DEFAULTS = { min: 0.75, max: 1.5, step: 0.05 };
+// finite-or-null: the single gate every external number passes through, so
+// "0.9", undefined, NaN and {} all collapse to one thing callers can test
+function num(v) {
+    const n = typeof v === "number" ? v : parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+}
+function labelOf(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim();
+    return s || null;
+}
+// Whitespace tokens, and nothing cleverer. Stripping punctuation or filtering
+// "um" would make the number prettier and less true — WPM is only useful here
+// as a RATIO between two speakers counted the same way, and both of them say um.
+function countWords(text) {
+    if (typeof text !== "string")
+        return 0;
+    const s = text.trim();
+    return s ? s.split(/\s+/).length : 0;
+}
+function flattenTurns(turns) {
+    const list = [];
+    for (const t of turns) {
+        if (!t || typeof t !== "object")
+            continue;
+        const start = num(t.start);
+        const end = num(t.end);
+        if (start == null || end == null || end <= start)
+            continue;
+        list.push({
+            start,
+            end,
+            name: t.ad ? null : labelOf(t.name),
+        });
+    }
+    if (!list.length)
+        return [];
+    // hosts promise sorted input; sorting anyway costs O(n log n) once per array
+    // and takes the promise out of the contract, which is cheaper than a support
+    // thread about rates being off by one speaker
+    list.sort((a, b) => a.start - b.start);
+    const cuts = [];
+    for (const t of list)
+        cuts.push(t.start, t.end);
+    cuts.sort((a, b) => a - b);
+    const flat = [];
+    let ti = 0;
+    let open = [];
+    for (let i = 0; i < cuts.length - 1; i++) {
+        const a = cuts[i];
+        const b = cuts[i + 1];
+        if (b <= a)
+            continue; // duplicate boundary — zero-width slice, nothing to own
+        while (ti < list.length && list[ti].start <= a)
+            open.push(list[ti++]);
+        open = open.filter((t) => t.end > a); // bounded by overlap depth, not by n
+        if (!open.length)
+            continue;
+        let win = open[0];
+        for (const t of open)
+            if (t.start >= win.start)
+                win = t;
+        const prev = flat[flat.length - 1];
+        // merge across cut points: the interesting boundaries are handoffs, and a
+        // speaker interrupted-then-resumed should read as one stretch, not three
+        if (prev && prev.name === win.name && prev.end === a)
+            prev.end = b;
+        else
+            flat.push({ start: a, end: b, name: win.name });
+    }
+    return flat;
+}
+// rateAt runs on every timeupdate, so the flatten is memoised against the array
+// identity the host handed us. Fingerprinting length + endpoints catches the
+// realistic staleness (a fresh array from setSpeakers, a re-diarise); an
+// in-place edit that preserves both would go unseen, which is why the host
+// replaces this array rather than mutating it.
+const flatCache = new WeakMap();
+function prepared(turns) {
+    if (!Array.isArray(turns) || !turns.length)
+        return [];
+    const mark = turns.length +
+        ":" +
+        turns[0]?.start +
+        ":" +
+        turns[turns.length - 1]?.end;
+    const hit = flatCache.get(turns);
+    if (hit && hit.mark === mark)
+        return hit.flat;
+    const flat = flattenTurns(turns);
+    flatCache.set(turns, { mark, flat });
+    return flat;
+}
+// last slice starting at or before sec, then a coverage check — [start, end),
+// so a time landing exactly on a handoff belongs to the person taking over
+function segAt(flat, sec) {
+    let lo = 0;
+    let hi = flat.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (flat[mid].start <= sec) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    if (found < 0)
+        return null;
+    const seg = flat[found];
+    return sec < seg.end ? seg : null;
+}
+// Weighted by talk time, not a plain median of the speakers. Two speakers with
+// a plain median land on the midpoint and BOTH get resampled — the worst of the
+// three options, since the voice you hear most is the one you're least likely
+// to want altered. Weighted, the dominant speaker sits at the target and stays
+// at 1x, and the occasional guest is the one who moves. An exact tie splits the
+// difference so a two-hander doesn't arbitrarily crown whoever is slower.
+function weightedMedian(rows) {
+    const list = rows.slice().sort((a, b) => a.wpm - b.wpm);
+    const total = list.reduce((s, r) => s + r.seconds, 0);
+    if (!(total > 0))
+        return 0;
+    const half = total / 2;
+    let acc = 0;
+    for (let i = 0; i < list.length; i++) {
+        acc += list[i].seconds;
+        if (acc > half)
+            return list[i].wpm;
+        if (acc === half) {
+            const next = list[i + 1];
+            return next ? (list[i].wpm + next.wpm) / 2 : list[i].wpm;
+        }
+    }
+    return list[list.length - 1].wpm;
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+export function speakerPace(transcript, speakers) {
+    const empty = { bySpeaker: Object.create(null), medianWpm: 0 };
+    if (!Array.isArray(transcript) || !transcript.length)
+        return empty;
+    const flat = prepared(speakers);
+    const acc = new Map();
+    for (const seg of transcript) {
+        if (!seg || typeof seg !== "object")
+            continue;
+        const start = num(seg.start);
+        const end = num(seg.end);
+        if (start == null || end == null || end <= start)
+            continue;
+        const words = countWords(seg.text);
+        if (!words)
+            continue;
+        // Midpoint, not start: a segment straddling a handoff belongs to whoever
+        // did most of the talking in it, and with no per-word timings the midpoint
+        // is the cheapest honest proxy. Turns win over segment.speaker when both
+        // exist — the diarisation pass that produced the turns is the one that
+        // resolved LABEL → display name and marked the ads.
+        const covering = flat.length ? segAt(flat, (start + end) / 2) : null;
+        // covering with a null name is an ad read: known, and deliberately not a
+        // person. Falling through to seg.speaker here would file the sponsor's
+        // words under the host.
+        const name = covering
+            ? covering.name
+            : labelOf(seg.speaker);
+        if (!name)
+            continue;
+        const row = acc.get(name) || { words: 0, seconds: 0 };
+        row.words += words;
+        row.seconds += end - start;
+        acc.set(name, row);
+    }
+    // null-prototype: a speaker literally named "__proto__" (names are
+    // user-editable — the rename menu accepts anything) would otherwise assign
+    // to the object's prototype slot instead of creating a key, leaving
+    // bySpeaker self-inconsistent: readable by name, invisible to Object.keys
+    // (the empty return above is null-prototype for the same reason — both
+    // Object.create(null) sites are deliberate, not style)
+    const bySpeaker = Object.create(null);
+    const rows = [];
+    for (const [name, row] of acc) {
+        if (row.words < MIN_WORDS || !(row.seconds > 0))
+            continue;
+        const wpm = round1((row.words / row.seconds) * 60);
+        bySpeaker[name] = {
+            wpm,
+            words: row.words,
+            seconds: Math.round(row.seconds * 100) / 100,
+        };
+        rows.push({ wpm, seconds: row.seconds });
+    }
+    return {
+        bySpeaker,
+        medianWpm: rows.length ? round1(weightedMedian(rows)) : 0,
+    };
+}
+export function suggestRates(pace, opts) {
+    const out = {};
+    const by = pace && typeof pace === "object" ? pace.bySpeaker : null;
+    if (!by || typeof by !== "object")
+        return out;
+    const o = opts && typeof opts === "object" ? opts : {};
+    const target = num(o.targetWpm) ?? num(pace.medianWpm);
+    if (!(target !== null && target > 0))
+        return out;
+    const a = num(o.min) ?? DEFAULTS.min;
+    const b = num(o.max) ?? DEFAULTS.max;
+    const lo = Math.min(a, b);
+    const hi = Math.max(a, b); // an inverted range is a typo, not an instruction to return nothing
+    const step = num(o.step) ?? DEFAULTS.step;
+    for (const [name, p] of Object.entries(by)) {
+        const wpm = num(p && p.wpm);
+        if (wpm == null || wpm <= 0)
+            continue;
+        const raw = target / wpm;
+        if (Math.abs(raw - 1) <= DEADZONE && raw >= lo && raw <= hi) {
+            // exactly 1, not 0.9999 — the host compares against 1. Gated on the
+            // range: an unmodified 1 is only the right answer if 1 is a rate the
+            // caller actually allows. With min 1.2 it isn't, and returning it anyway
+            // silently broke the one promise this function makes about its output.
+            out[name] = 1;
+            continue;
+        }
+        // snap first, then clamp: snapping a clamped value can walk it back over
+        // the limit, and the limit is the promise the user actually set
+        const snapped = step > 0 ? Math.round(raw / step) * step : raw;
+        const rate = Math.round(Math.min(hi, Math.max(lo, snapped)) * 1000) / 1000;
+        out[name] = Math.abs(rate - 1) < 1e-9 ? 1 : rate;
+    }
+    return out;
+}
+export function rateAt(t, turns, rates, fallback = 1) {
+    const fb = num(fallback) ?? 1;
+    const sec = num(t);
+    if (sec == null)
+        return fb;
+    const flat = prepared(turns);
+    if (!flat.length)
+        return fb;
+    const seg = segAt(flat, sec);
+    // no turn covering t, or an ad read (name === null): nobody to match, so
+    // normal speed. Silence between turns is the one place a rate change would
+    // be inaudible anyway, and holding the last speaker's rate through it makes
+    // the next handoff land late.
+    if (!seg || !seg.name)
+        return fb;
+    const r = rates && typeof rates === "object"
+        ? num(rates[seg.name])
+        : null;
+    return r != null && r > 0 ? r : fb;
+}
+// Sorted by talk time because that's the order you think about the people in:
+// the host first, the guest who said four sentences last. Someone already on
+// pace still gets a line — seeing that they were measured and left alone is
+// the point, and a list that only shows the changed speakers reads like the
+// others were missed.
+export function describeRates(pace, rates) {
+    const by = pace && typeof pace === "object" ? pace.bySpeaker : null;
+    if (!by || typeof by !== "object")
+        return [];
+    const rows = Object.entries(by).filter(([, p]) => p && num(p.wpm) != null);
+    rows.sort((x, y) => (num(y[1].seconds) ?? 0) - (num(x[1].seconds) ?? 0) ||
+        x[0].localeCompare(y[0]));
+    return rows.map(([name, p]) => {
+        const wpm = Math.round(num(p.wpm));
+        const r = rates && typeof rates === "object" ? num(rates[name]) : null;
+        if (r == null || Math.abs(r - 1) < 1e-9)
+            return `${name} ${wpm} wpm · on pace`;
+        return `${name} ${wpm} wpm → ${+r.toFixed(2)}x`;
+    });
+}

package/dist/video/band/axis.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One time axis — the four-state arbitration (mos-5lzns.30).
+ *
+ * extension-library FEATURES.md §"One time axis": two widgets drawing "where
+ * you are" is a redundancy whose only product is the chance of them
+ * disagreeing, so the band — always on screen, already seeking — takes the
+ * job and the seek bar stands down. The band alone knows whether it has an
+ * envelope and whether it is zoomed, so it resolves the state and REPORTS it
+ * (`bandState` / `onBandChange`); whoever owns a bar reads the report.
+ *
+ * | hasWave | zoomed | axis       | Result                                                    |
+ * |---------|--------|------------|-----------------------------------------------------------|
+ * | yes     | no     | `band`     | Bar hidden. Band owns the axis and the light ribbon.      |
+ * | yes     | yes    | `overview` | Bar returns as the OVERVIEW, window drawn as a bracket.   |
+ * | no      | —      | `bar`      | Bar stays (no envelope ⇒ the bar is the position readout).|
+ * | —       | —      | `both`     | `oneAxis` off → both bars, permanently.                   |
+ *
+ * jatui divergence, deliberately: the "bar" here is the native `<video
+ * controls>` timeline, which a component cannot paint into — so the light
+ * ribbon always rides the band, and the zoomed overview is the band's own
+ * slim rail (drawn in the band's reserved top padding, so it appearing is
+ * never a layout shove). The native timeline can only be stood down where
+ * the engine exposes it (Chromium's ::-webkit-media-controls-timeline);
+ * elsewhere it stays and the band is simply the more precise of the two.
+ *
+ * DOM-free: node-testable under `npm run test:unit`.
+ */
+import { type BandWindow } from './window';
+export type BandAxis = 'band' | 'overview' | 'bar' | 'both';
+export interface BandState {
+    /** The band has an envelope (waveform peaks) to scrub on. */
+    hasWave: boolean;
+    /** The band is showing a window narrower than the whole video. */
+    zoomed: boolean;
+    /** The visible window, seconds. `viewEnd` is 0 until a duration is known. */
+    viewStart: number;
+    viewEnd: number;
+    /** The resolved four-state outcome — see the table above. */
+    axis: BandAxis;
+}
+export declare function resolveAxis(hasWave: boolean, zoomed: boolean, oneAxis: boolean): BandAxis;
+export declare function bandStateOf(hasWave: boolean, w: BandWindow, duration: number, oneAxis: boolean): BandState;
+/** The bar (native timeline) stands down only while the band owns the axis. */
+export declare function barHidden(axis: BandAxis): boolean;
+/**
+ * Report churn guard: the band repaints far more often than its state
+ * changes, so the reporter compares `hasWave|zoomed|viewStart|viewEnd|axis`
+ * and only calls out on a real change.
+ */
+export declare function bandSignature(s: BandState): string;
+/**
+ * Build a reporter that forwards only real changes, deferred through a
+ * microtask. The defer is not cosmetic (FEATURES.md failure mode "callback
+ * timing"): the player reports from inside its own mount/paint, before the
+ * host's reference to the component has finished initialising — a host
+ * callback that touches that reference synchronously would read undefined.
+ * `schedule` is injectable so tests can run it synchronously.
+ */
+export declare function createBandReporter(getCallback: () => ((s: BandState) => void) | undefined, schedule?: (fn: () => void) => void): (s: BandState) => void;
+/** The playhead line width in CSS px — shared by the band canvas and the overview rail. */
+export declare const PLAYHEAD_W = 1.5;
+/**
+ * The playhead's CENTRE x, in CSS px of a box `width` wide. Every widget that
+ * draws "where you are" goes through this one function, and both draw the
+ * line centred on it (x − PLAYHEAD_W/2), so two widgets sharing a box width
+ * agree to sub-pixel rounding — the ≤0.2px FEATURES.md measured, instead of
+ * the ~90px two independently-laid-out bars disagreed by.
+ */
+export declare function playheadX(sec: number, w: BandWindow, duration: number, width: number): number;
+/**
+ * The zoomed window as an outlined bracket on the whole-video overview, in
+ * fractions of the overview's width — an OUTLINE, not a fill, so the played
+ * bar underneath stays readable and marking a RANGE of the axis has
+ * different grammar from marking a POSITION. Null when not zoomed (nothing
+ * to bracket: the band IS the whole video). A 25–50s view of a 100s video is
+ * `{ left: 0.25, width: 0.25 }` — the extension harness's own case.
+ */
+export declare function overviewBracket(w: BandWindow, duration: number): {
+    left: number;
+    width: number;
+} | null;

package/dist/video/band/axis.js

@@ -0,0 +1,106 @@
+/**
+ * One time axis — the four-state arbitration (mos-5lzns.30).
+ *
+ * extension-library FEATURES.md §"One time axis": two widgets drawing "where
+ * you are" is a redundancy whose only product is the chance of them
+ * disagreeing, so the band — always on screen, already seeking — takes the
+ * job and the seek bar stands down. The band alone knows whether it has an
+ * envelope and whether it is zoomed, so it resolves the state and REPORTS it
+ * (`bandState` / `onBandChange`); whoever owns a bar reads the report.
+ *
+ * | hasWave | zoomed | axis       | Result                                                    |
+ * |---------|--------|------------|-----------------------------------------------------------|
+ * | yes     | no     | `band`     | Bar hidden. Band owns the axis and the light ribbon.      |
+ * | yes     | yes    | `overview` | Bar returns as the OVERVIEW, window drawn as a bracket.   |
+ * | no      | —      | `bar`      | Bar stays (no envelope ⇒ the bar is the position readout).|
+ * | —       | —      | `both`     | `oneAxis` off → both bars, permanently.                   |
+ *
+ * jatui divergence, deliberately: the "bar" here is the native `<video
+ * controls>` timeline, which a component cannot paint into — so the light
+ * ribbon always rides the band, and the zoomed overview is the band's own
+ * slim rail (drawn in the band's reserved top padding, so it appearing is
+ * never a layout shove). The native timeline can only be stood down where
+ * the engine exposes it (Chromium's ::-webkit-media-controls-timeline);
+ * elsewhere it stays and the band is simply the more precise of the two.
+ *
+ * DOM-free: node-testable under `npm run test:unit`.
+ */
+import { isZoomed, secToFrac, spanSec } from './window';
+export function resolveAxis(hasWave, zoomed, oneAxis) {
+    if (!oneAxis)
+        return 'both';
+    if (!hasWave)
+        return 'bar';
+    return zoomed ? 'overview' : 'band';
+}
+export function bandStateOf(hasWave, w, duration, oneAxis) {
+    const zoomed = isZoomed(w, duration);
+    return {
+        hasWave,
+        zoomed,
+        viewStart: w.start,
+        viewEnd: w.end,
+        axis: resolveAxis(hasWave, zoomed, oneAxis)
+    };
+}
+/** The bar (native timeline) stands down only while the band owns the axis. */
+export function barHidden(axis) {
+    return axis === 'band' || axis === 'overview';
+}
+/**
+ * Report churn guard: the band repaints far more often than its state
+ * changes, so the reporter compares `hasWave|zoomed|viewStart|viewEnd|axis`
+ * and only calls out on a real change.
+ */
+export function bandSignature(s) {
+    return `${s.hasWave}|${s.zoomed}|${s.viewStart}|${s.viewEnd}|${s.axis}`;
+}
+/**
+ * Build a reporter that forwards only real changes, deferred through a
+ * microtask. The defer is not cosmetic (FEATURES.md failure mode "callback
+ * timing"): the player reports from inside its own mount/paint, before the
+ * host's reference to the component has finished initialising — a host
+ * callback that touches that reference synchronously would read undefined.
+ * `schedule` is injectable so tests can run it synchronously.
+ */
+export function createBandReporter(getCallback, schedule = queueMicrotask) {
+    let last = '';
+    return (s) => {
+        const sig = bandSignature(s);
+        if (sig === last)
+            return;
+        last = sig;
+        const snapshot = { ...s };
+        schedule(() => getCallback()?.(snapshot));
+    };
+}
+// ── Playhead agreement ──────────────────────────────────────────────────────
+/** The playhead line width in CSS px — shared by the band canvas and the overview rail. */
+export const PLAYHEAD_W = 1.5;
+/**
+ * The playhead's CENTRE x, in CSS px of a box `width` wide. Every widget that
+ * draws "where you are" goes through this one function, and both draw the
+ * line centred on it (x − PLAYHEAD_W/2), so two widgets sharing a box width
+ * agree to sub-pixel rounding — the ≤0.2px FEATURES.md measured, instead of
+ * the ~90px two independently-laid-out bars disagreed by.
+ */
+export function playheadX(sec, w, duration, width) {
+    if (!(duration > 0) || !(width > 0))
+        return 0;
+    return Math.max(0, Math.min(1, secToFrac(w, duration, sec))) * width;
+}
+/**
+ * The zoomed window as an outlined bracket on the whole-video overview, in
+ * fractions of the overview's width — an OUTLINE, not a fill, so the played
+ * bar underneath stays readable and marking a RANGE of the axis has
+ * different grammar from marking a POSITION. Null when not zoomed (nothing
+ * to bracket: the band IS the whole video). A 25–50s view of a 100s video is
+ * `{ left: 0.25, width: 0.25 }` — the extension harness's own case.
+ */
+export function overviewBracket(w, duration) {
+    if (!(duration > 0) || !isZoomed(w, duration))
+        return null;
+    const left = Math.max(0, Math.min(1, w.start / duration));
+    const width = Math.max(0, Math.min(1 - left, spanSec(w, duration) / duration));
+    return { left, width };
+}

package/dist/video/band/drag.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Drag-to-scrub on the band (mos-5lzns.30 review). With one-axis on, the
+ * native timeline stands down whenever there is an envelope — so the band
+ * must scrub like the bar it replaced, not only seek on click.
+ *
+ * A pure state machine; the component owns pointer capture and the rAF
+ * throttle. Rules:
+ * · Only the pointer that started the drag moves it (a second finger is
+ *   ignored, not a teleport).
+ * · Within DRAG_SLOP_PX of the press it is still a CLICK — the band's click
+ *   path (transcript bias, comment hit) keeps working. Past it, it is a
+ *   scrub: seeks land exactly under the pointer, and the click that follows
+ *   the release is swallowed.
+ * · `pointercancel` (the browser took the gesture — a page scroll on touch)
+ *   restores the time the drag started from: a scrub you never finished
+ *   should not have moved you.
+ */
+export declare const DRAG_SLOP_PX = 3;
+export interface DragState {
+    pointerId: number;
+    startX: number;
+    /** Playback position when the press landed — restored on cancel. */
+    originSec: number;
+    moved: boolean;
+    /** Latest time under the pointer, awaiting the next frame's seek. */
+    pendingSec: number | null;
+}
+export declare function dragStart(pointerId: number, x: number, originSec: number): DragState;
+/** Returns the next state, or the same object when the event isn't this drag's. */
+export declare function dragMove(s: DragState | null, pointerId: number, x: number, sec: number): DragState | null;
+export interface DragOutcome {
+    /** Where to leave the playhead, or null to leave it alone (a plain click). */
+    seekSec: number | null;
+    /** True ⇒ swallow the click event the browser fires after this release. */
+    suppressClick: boolean;
+}
+export declare function dragEnd(s: DragState | null, pointerId: number, sec: number): DragOutcome;
+export declare function dragCancel(s: DragState | null, pointerId: number): DragOutcome;

package/dist/video/band/drag.js

@@ -0,0 +1,45 @@
+/**
+ * Drag-to-scrub on the band (mos-5lzns.30 review). With one-axis on, the
+ * native timeline stands down whenever there is an envelope — so the band
+ * must scrub like the bar it replaced, not only seek on click.
+ *
+ * A pure state machine; the component owns pointer capture and the rAF
+ * throttle. Rules:
+ * · Only the pointer that started the drag moves it (a second finger is
+ *   ignored, not a teleport).
+ * · Within DRAG_SLOP_PX of the press it is still a CLICK — the band's click
+ *   path (transcript bias, comment hit) keeps working. Past it, it is a
+ *   scrub: seeks land exactly under the pointer, and the click that follows
+ *   the release is swallowed.
+ * · `pointercancel` (the browser took the gesture — a page scroll on touch)
+ *   restores the time the drag started from: a scrub you never finished
+ *   should not have moved you.
+ */
+export const DRAG_SLOP_PX = 3;
+export function dragStart(pointerId, x, originSec) {
+    return { pointerId, startX: x, originSec, moved: false, pendingSec: null };
+}
+/** Returns the next state, or the same object when the event isn't this drag's. */
+export function dragMove(s, pointerId, x, sec) {
+    if (!s || s.pointerId !== pointerId)
+        return s;
+    const moved = s.moved || Math.abs(x - s.startX) > DRAG_SLOP_PX;
+    if (!moved)
+        return s;
+    return { ...s, moved, pendingSec: sec };
+}
+const NONE = { seekSec: null, suppressClick: false };
+export function dragEnd(s, pointerId, sec) {
+    if (!s || s.pointerId !== pointerId)
+        return NONE;
+    if (!s.moved)
+        return NONE;
+    return { seekSec: sec, suppressClick: true };
+}
+export function dragCancel(s, pointerId) {
+    if (!s || s.pointerId !== pointerId)
+        return NONE;
+    if (!s.moved)
+        return NONE;
+    return { seekSec: s.originSec, suppressClick: true };
+}

package/dist/video/band/luma.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The light track → the light ribbon (mos-5lzns.30).
+ *
+ * extension-library FEATURES.md §"The light track": the host scans each file
+ * once for brightness (ffmpeg signalstats YAVG, limited-range `(v − 16) / 219`)
+ * and stores it at 4 samples/second, the MAX per bucket (the worst instant
+ * in a quarter second is what hits your eye), as integers 0–99, alongside
+ * `duration`, `rate` and `flashes`. That sidecar is exactly `VideoLumaTrack`.
+ *
+ * The track pays for itself three times: predictive dimming and the strobe
+ * guard (night's — mos-5lzns.33 reads the same `luma` prop) and the RIBBON,
+ * which is the axis owner's drawing: an amber wash `v² × 0.55`, painted UNDER
+ * the envelope through the band's own zoom window, so it reads as a property
+ * of the timeline rather than a fourth bar and it zooms with everything else.
+ *
+ * The squared alpha is the point: mid-grey footage barely tints the band,
+ * a white-out glows. DOM-free; node-testable.
+ */
+import { type BandWindow } from './window';
+/** The sidecar, verbatim. `luma` values are integers 0–99 (the sidecar's own scale). */
+export interface VideoLumaTrack {
+    luma: number[];
+    /** Samples per second. Defaults to the sidecar's 4. */
+    rate?: number;
+    /** Seconds the track spans. Defaults to `luma.length / rate`. */
+    durationSec?: number;
+    /** Detected flash intervals `[startSec, endSec]` — read by night's strobe guard (.33). */
+    flashes?: Array<[number, number]>;
+}
+export declare const LUMA_SCALE = 99;
+export declare const LUMA_DEFAULT_RATE = 4;
+/** Fewer parsed samples than this and the host writes nothing — so a track this short is not a track. */
+export declare const LUMA_MIN_SAMPLES = 4;
+/** Ribbon alpha ceiling: `v² × RIBBON_ALPHA` (FEATURES.md, the amber wash). */
+export declare const RIBBON_ALPHA = 0.55;
+/** Gradient stops for a whole-video ribbon (FEATURES.md: 120). */
+export declare const RIBBON_STOPS = 120;
+export interface LumaSeries {
+    /** 0–1 per sample. */
+    values: number[];
+    rate: number;
+    durationSec: number;
+}
+/**
+ * Validate + normalise a track. Never throws; garbage in ⇒ null out (a
+ * missing ribbon, never a wrong one). A non-finite sample inherits the
+ * previous one — the host's own rule for empty buckets, so a gap never reads
+ * as pitch black.
+ */
+export declare function normalizeLuma(track: VideoLumaTrack | null | undefined): LumaSeries | null;
+/**
+ * Peak brightness over `[t0, t1]` — the max of every bucket the interval
+ * touches (the same max-not-mean reasoning as the scan). 0 outside the track.
+ */
+export declare function lumaPeak(s: LumaSeries, t0: number, t1: number): number;
+export declare function ribbonAlpha(v: number): number;
+/**
+ * Ribbon alphas for `cols` equal columns across the band's CURRENT window —
+ * column i covers `[fracToSec(i/cols), fracToSec((i+1)/cols)]`, so the ribbon
+ * maps through the same window as the peaks and zooms with them.
+ */
+export declare function ribbonColumns(s: LumaSeries, w: BandWindow, duration: number, cols: number): number[];