@joewinke/jatui 0.9.1 → 0.11.0

package/dist/video/band/luma.js

@@ -0,0 +1,97 @@
+/**
+ * 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 { fracToSec, spanSec } from './window';
+export const LUMA_SCALE = 99;
+export 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 const LUMA_MIN_SAMPLES = 4;
+/** Ribbon alpha ceiling: `v² × RIBBON_ALPHA` (FEATURES.md, the amber wash). */
+export const RIBBON_ALPHA = 0.55;
+/** Gradient stops for a whole-video ribbon (FEATURES.md: 120). */
+export const RIBBON_STOPS = 120;
+/**
+ * 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 function normalizeLuma(track) {
+    const raw = track?.luma;
+    if (!Array.isArray(raw) || raw.length < LUMA_MIN_SAMPLES)
+        return null;
+    const rate = typeof track?.rate === 'number' && Number.isFinite(track.rate) && track.rate > 0
+        ? track.rate
+        : LUMA_DEFAULT_RATE;
+    const values = new Array(raw.length);
+    let prev = 0;
+    let anyFinite = false;
+    for (let i = 0; i < raw.length; i++) {
+        const v = raw[i];
+        if (typeof v === 'number' && Number.isFinite(v)) {
+            prev = Math.max(0, Math.min(1, v / LUMA_SCALE));
+            anyFinite = true;
+        }
+        values[i] = prev;
+    }
+    if (!anyFinite)
+        return null;
+    const d = track?.durationSec;
+    const durationSec = typeof d === 'number' && Number.isFinite(d) && d > 0 ? d : raw.length / rate;
+    return { values, rate, durationSec };
+}
+/**
+ * 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 function lumaPeak(s, t0, t1) {
+    if (t1 < t0)
+        [t0, t1] = [t1, t0];
+    if (t1 < 0 || t0 > s.durationSec)
+        return 0;
+    const n = s.values.length;
+    const i0 = Math.max(0, Math.min(n - 1, Math.floor(t0 * s.rate)));
+    // End-exclusive: an interval ending exactly on a bucket edge does not
+    // reach into the next bucket (adjacent columns must not both claim it).
+    const i1 = Math.max(i0, Math.min(n - 1, Math.ceil(t1 * s.rate) - 1));
+    let m = 0;
+    for (let i = i0; i <= i1; i++)
+        if (s.values[i] > m)
+            m = s.values[i];
+    return m;
+}
+export function ribbonAlpha(v) {
+    const c = Math.max(0, Math.min(1, v));
+    return c * c * RIBBON_ALPHA;
+}
+/**
+ * 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 function ribbonColumns(s, w, duration, cols) {
+    const out = [];
+    if (!(duration > 0) || cols <= 0 || !(spanSec(w, duration) > 0))
+        return out;
+    for (let i = 0; i < cols; i++) {
+        const t0 = fracToSec(w, duration, i / cols);
+        const t1 = fracToSec(w, duration, (i + 1) / cols);
+        out.push(ribbonAlpha(lumaPeak(s, t0, t1)));
+    }
+    return out;
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Social markers on the band — timestamped comments and a like heatmap
+ * (mos-5lzns.30's own brief; not an extension capability).
+ *
+ * The band already carries two marker families, told apart by EDGE and
+ * SHAPE: chapter flags (the model's) are triangles on the top edge, bookmark
+ * diamonds (yours) on the bottom edge. Social markers are other people's, so
+ * they get their own grammar rather than borrowing either:
+ *
+ * · comments — small round dots riding just under the chapter flags; hover
+ *   shows the comment, click seeks to its exact second (no transcript
+ *   bias — a comment is ABOUT that instant).
+ * · likes — never individual glyphs (a hundred likes would be a hundred
+ *   dots). They fold into a heat strip along the bottom edge, under the
+ *   bookmark diamonds, normalised to the window's own peak so "where did
+ *   people react" reads at any zoom.
+ *
+ * DOM-free; node-testable.
+ */
+import { type BandWindow } from './window';
+export interface VideoMarker {
+    atSec: number;
+    kind: 'comment' | 'like';
+    id?: string | null;
+    /** Comment body (comments only). */
+    text?: string | null;
+    author?: string | null;
+    /** Likes only: how many reactions this entry stands for (pre-aggregated hosts). Default 1. */
+    weight?: number | null;
+}
+export declare const MARKER_HIT_PX = 6;
+/** Under `(pointer: coarse)` a fingertip needs a target, not a 6px sliver. */
+export declare const MARKER_HIT_PX_COARSE = 14;
+/** Comment dots closer than this collapse to one (the chapter-flag merge rule). */
+export declare const COMMENT_MERGE_PX = 6;
+/** Heat bins are this many CSS px wide. */
+export declare const HEAT_BIN_PX = 3;
+/** Drop junk (non-finite / negative times, unknown kinds) and sort ascending. */
+export declare function sortMarkers(markers: VideoMarker[] | null | undefined): VideoMarker[];
+export declare function splitMarkers(sorted: VideoMarker[]): {
+    comments: VideoMarker[];
+    likes: VideoMarker[];
+};
+export interface CommentCluster {
+    x: number;
+    markers: VideoMarker[];
+}
+/**
+ * Comment dots in the visible window, x in CSS px, with neighbours closer
+ * than COMMENT_MERGE_PX collapsed (a long video at full zoom-out must not
+ * smear them into a bar). Expects ascending input.
+ */
+export declare function commentClusters(comments: VideoMarker[], w: BandWindow, duration: number, width: number): CommentCluster[];
+/** The comment cluster under the pointer, or null. */
+export declare function commentAt(xCss: number, clusters: CommentCluster[], hitPx?: number): CommentCluster | null;
+/**
+ * Like density across the visible window in `bins` equal bins, smoothed
+ * with a [1,2,1] kernel (a reaction lands a beat after the moment) and
+ * normalised to 0–1 against the window's own peak. All zeros when there is
+ * nothing to show.
+ */
+export declare function likeHeat(likes: VideoMarker[], w: BandWindow, duration: number, bins: number): number[];
+/**
+ * Previous / next comment relative to the playhead — the keyboard path to
+ * markers that are otherwise pointer-only. Same graces as the chapter jump
+ * (keys.ts): `next` skips 0.25s ahead so a press on a comment's own second
+ * doesn't stick; `previous` looks 0.75s back so it reaches the one BEFORE
+ * the comment you are sitting on. Comments sharing an instant come back
+ * together (a cluster is announced as one). Expects ascending input.
+ */
+export declare function commentJump(current: number, comments: VideoMarker[], direction: 1 | -1): VideoMarker[] | null;
+/** One line for a screen reader: who, when, what — and how many more. */
+export declare function describeComments(group: VideoMarker[], formatAt: (sec: number) => string): string;

package/dist/video/band/markers.js

@@ -0,0 +1,146 @@
+/**
+ * Social markers on the band — timestamped comments and a like heatmap
+ * (mos-5lzns.30's own brief; not an extension capability).
+ *
+ * The band already carries two marker families, told apart by EDGE and
+ * SHAPE: chapter flags (the model's) are triangles on the top edge, bookmark
+ * diamonds (yours) on the bottom edge. Social markers are other people's, so
+ * they get their own grammar rather than borrowing either:
+ *
+ * · comments — small round dots riding just under the chapter flags; hover
+ *   shows the comment, click seeks to its exact second (no transcript
+ *   bias — a comment is ABOUT that instant).
+ * · likes — never individual glyphs (a hundred likes would be a hundred
+ *   dots). They fold into a heat strip along the bottom edge, under the
+ *   bookmark diamonds, normalised to the window's own peak so "where did
+ *   people react" reads at any zoom.
+ *
+ * DOM-free; node-testable.
+ */
+import { secToFrac, spanSec } from './window';
+export const MARKER_HIT_PX = 6;
+/** Under `(pointer: coarse)` a fingertip needs a target, not a 6px sliver. */
+export const MARKER_HIT_PX_COARSE = 14;
+/** Comment dots closer than this collapse to one (the chapter-flag merge rule). */
+export const COMMENT_MERGE_PX = 6;
+/** Heat bins are this many CSS px wide. */
+export const HEAT_BIN_PX = 3;
+/** Drop junk (non-finite / negative times, unknown kinds) and sort ascending. */
+export function sortMarkers(markers) {
+    if (!Array.isArray(markers))
+        return [];
+    return markers
+        .filter((m) => m != null &&
+        typeof m.atSec === 'number' &&
+        Number.isFinite(m.atSec) &&
+        m.atSec >= 0 &&
+        (m.kind === 'comment' || m.kind === 'like'))
+        .slice()
+        .sort((a, b) => a.atSec - b.atSec);
+}
+export function splitMarkers(sorted) {
+    const comments = [];
+    const likes = [];
+    for (const m of sorted)
+        (m.kind === 'comment' ? comments : likes).push(m);
+    return { comments, likes };
+}
+/**
+ * Comment dots in the visible window, x in CSS px, with neighbours closer
+ * than COMMENT_MERGE_PX collapsed (a long video at full zoom-out must not
+ * smear them into a bar). Expects ascending input.
+ */
+export function commentClusters(comments, w, duration, width) {
+    const out = [];
+    if (!(duration > 0) || !(width > 0))
+        return out;
+    for (const m of comments) {
+        const x = secToFrac(w, duration, m.atSec) * width;
+        if (x < -4 || x > width + 4)
+            continue;
+        const last = out[out.length - 1];
+        if (last && x - last.x < COMMENT_MERGE_PX)
+            last.markers.push(m);
+        else
+            out.push({ x, markers: [m] });
+    }
+    return out;
+}
+/** The comment cluster under the pointer, or null. */
+export function commentAt(xCss, clusters, hitPx = MARKER_HIT_PX) {
+    let best = null;
+    let bestD = hitPx;
+    for (const c of clusters) {
+        const d = Math.abs(c.x - xCss);
+        if (d < bestD) {
+            bestD = d;
+            best = c;
+        }
+    }
+    return best;
+}
+function likeWeight(m) {
+    const w = m.weight;
+    return typeof w === 'number' && Number.isFinite(w) && w > 0 ? w : 1;
+}
+/**
+ * Like density across the visible window in `bins` equal bins, smoothed
+ * with a [1,2,1] kernel (a reaction lands a beat after the moment) and
+ * normalised to 0–1 against the window's own peak. All zeros when there is
+ * nothing to show.
+ */
+export function likeHeat(likes, w, duration, bins) {
+    const n = Math.max(0, Math.floor(bins));
+    const raw = new Array(n).fill(0);
+    if (!n || !(duration > 0) || !(spanSec(w, duration) > 0))
+        return raw;
+    for (const m of likes) {
+        const f = secToFrac(w, duration, m.atSec);
+        if (f < 0 || f > 1)
+            continue;
+        raw[Math.min(n - 1, Math.floor(f * n))] += likeWeight(m);
+    }
+    const out = new Array(n).fill(0);
+    let max = 0;
+    for (let i = 0; i < n; i++) {
+        const v = 2 * raw[i] + (raw[i - 1] ?? 0) + (raw[i + 1] ?? 0);
+        out[i] = v;
+        if (v > max)
+            max = v;
+    }
+    return max > 0 ? out.map((v) => v / max) : out;
+}
+/**
+ * Previous / next comment relative to the playhead — the keyboard path to
+ * markers that are otherwise pointer-only. Same graces as the chapter jump
+ * (keys.ts): `next` skips 0.25s ahead so a press on a comment's own second
+ * doesn't stick; `previous` looks 0.75s back so it reaches the one BEFORE
+ * the comment you are sitting on. Comments sharing an instant come back
+ * together (a cluster is announced as one). Expects ascending input.
+ */
+export function commentJump(current, comments, direction) {
+    let hit;
+    if (direction === 1)
+        hit = comments.find((c) => c.atSec > current + 0.25);
+    else
+        for (const c of comments) {
+            if (c.atSec < current - 0.75)
+                hit = c;
+            else
+                break;
+        }
+    if (!hit)
+        return null;
+    const at = hit.atSec;
+    return comments.filter((c) => Math.abs(c.atSec - at) < 0.5);
+}
+/** One line for a screen reader: who, when, what — and how many more. */
+export function describeComments(group, formatAt) {
+    if (group.length === 0)
+        return '';
+    const first = group[0];
+    const who = first.author ? `Comment by ${first.author}` : 'Comment';
+    const body = first.text ? `: ${first.text}` : '';
+    const more = group.length > 1 ? ` (+${group.length - 1} more)` : '';
+    return `${who} at ${formatAt(first.atSec)}${body}${more}`;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Per-instance memo slots for the band's derived layers (mos-5lzns.30
+ * review). The band repaints on every timeupdate, but the ribbon columns,
+ * like heat and comment clusters depend only on (window, width, data) — so
+ * they are recomputed when one of THOSE changes, never per playhead tick.
+ * Deps compare by identity (`Object.is`), so data props must be replaced,
+ * not mutated in place — the component's own convention already.
+ */
+export interface MemoSlot<T> {
+    deps: unknown[] | null;
+    value: T | undefined;
+}
+export declare function memoSlot<T>(): MemoSlot<T>;
+export declare function memo<T>(slot: MemoSlot<T>, deps: unknown[], compute: () => T): T;
+/** The band's three derived layers, one cache per player instance. */
+export interface BandLayerCache {
+    ribbon: MemoSlot<number[]>;
+    heat: MemoSlot<number[]>;
+    clusters: MemoSlot<import('./markers').CommentCluster[]>;
+}
+export declare function createBandLayerCache(): BandLayerCache;

package/dist/video/band/memo.js

@@ -0,0 +1,15 @@
+export function memoSlot() {
+    return { deps: null, value: undefined };
+}
+export function memo(slot, deps, compute) {
+    const prev = slot.deps;
+    if (prev && prev.length === deps.length && prev.every((d, i) => Object.is(d, deps[i]))) {
+        return slot.value;
+    }
+    slot.deps = deps;
+    slot.value = compute();
+    return slot.value;
+}
+export function createBandLayerCache() {
+    return { ribbon: memoSlot(), heat: memoSlot(), clusters: memoSlot() };
+}

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

@@ -0,0 +1,35 @@
+/**
+ * The band's zoom window — ONE mapping every position computation goes
+ * through (mos-5lzns.30 moved it here from band.ts so the band/ paint layers
+ * — axis, luma ribbon, markers — can share it without an import cycle;
+ * band.ts re-exports everything, so existing import sites are unchanged).
+ */
+export interface BandWindow {
+    start: number;
+    end: number;
+}
+/**
+ * The visible window in seconds. Falls back to the whole video until the
+ * duration effect has seeded `end`, so a first paint that races metadata
+ * still maps positions correctly instead of collapsing to zero.
+ */
+export declare function spanSec(w: BandWindow, duration: number): number;
+export declare function isZoomed(w: BandWindow, duration: number): boolean;
+export declare function resetWindow(duration: number): BandWindow;
+export declare function secToFrac(w: BandWindow, duration: number, sec: number): number;
+export declare function fracToSec(w: BandWindow, duration: number, frac: number): number;
+/**
+ * Scroll to zoom, centred on the cursor — the DAW/mpv convention: the point
+ * under the pointer stays fixed while the window resizes around it, so
+ * scrolling repeatedly walks you inward on exactly the spot you're pointing
+ * at. `deltaY < 0` zooms in.
+ */
+export declare const ZOOM_FACTOR = 1.3;
+export declare const MIN_WINDOW_SEC = 3;
+export declare function zoomAt(w: BandWindow, duration: number, cursorSec: number, deltaY: number): BandWindow;
+/**
+ * Zoomed in and playback walked past the edge of the window — follow it, or
+ * you'd watch a frozen slice of waveform while the video plays on. Returns
+ * null when no follow is needed.
+ */
+export declare function followPlayhead(w: BandWindow, duration: number, t: number): BandWindow | null;

package/dist/video/band/window.js

@@ -0,0 +1,61 @@
+/**
+ * The band's zoom window — ONE mapping every position computation goes
+ * through (mos-5lzns.30 moved it here from band.ts so the band/ paint layers
+ * — axis, luma ribbon, markers — can share it without an import cycle;
+ * band.ts re-exports everything, so existing import sites are unchanged).
+ */
+/**
+ * The visible window in seconds. Falls back to the whole video until the
+ * duration effect has seeded `end`, so a first paint that races metadata
+ * still maps positions correctly instead of collapsing to zero.
+ */
+export function spanSec(w, duration) {
+    return w.end > w.start ? w.end - w.start : duration;
+}
+export function isZoomed(w, duration) {
+    return w.end > 0 && spanSec(w, duration) < duration - 0.01;
+}
+export function resetWindow(duration) {
+    return { start: 0, end: duration };
+}
+export function secToFrac(w, duration, sec) {
+    const span = spanSec(w, duration);
+    return span > 0 ? (sec - w.start) / span : 0;
+}
+export function fracToSec(w, duration, frac) {
+    return w.start + frac * spanSec(w, duration);
+}
+/**
+ * Scroll to zoom, centred on the cursor — the DAW/mpv convention: the point
+ * under the pointer stays fixed while the window resizes around it, so
+ * scrolling repeatedly walks you inward on exactly the spot you're pointing
+ * at. `deltaY < 0` zooms in.
+ */
+export const ZOOM_FACTOR = 1.3;
+export const MIN_WINDOW_SEC = 3;
+export function zoomAt(w, duration, cursorSec, deltaY) {
+    if (!duration)
+        return w;
+    if (w.end <= 0)
+        w = resetWindow(duration);
+    const span = spanSec(w, duration);
+    let newSpan = deltaY < 0 ? span / ZOOM_FACTOR : span * ZOOM_FACTOR;
+    newSpan = Math.min(duration, Math.max(MIN_WINDOW_SEC, newSpan));
+    const frac = span > 0 ? (cursorSec - w.start) / span : 0.5;
+    const start = Math.max(0, Math.min(cursorSec - frac * newSpan, duration - newSpan));
+    return { start, end: start + newSpan };
+}
+/**
+ * Zoomed in and playback walked past the edge of the window — follow it, or
+ * you'd watch a frozen slice of waveform while the video plays on. Returns
+ * null when no follow is needed.
+ */
+export function followPlayhead(w, duration, t) {
+    if (!isZoomed(w, duration))
+        return null;
+    if (t >= w.start && t <= w.end)
+        return null;
+    const span = spanSec(w, duration);
+    const start = Math.max(0, Math.min(t - span / 2, Math.max(0, duration - span)));
+    return { start, end: start + span };
+}

package/dist/video/band.d.ts

@@ -23,35 +23,11 @@
  */
 import { ALL_KEY } from './model';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment } from './types';
-export interface BandWindow {
-    start: number;
-    end: number;
-}
-/**
- * The visible window in seconds. Falls back to the whole video until the
- * duration effect has seeded `end`, so a first paint that races metadata
- * still maps positions correctly instead of collapsing to zero.
- */
-export declare function spanSec(w: BandWindow, duration: number): number;
-export declare function isZoomed(w: BandWindow, duration: number): boolean;
-export declare function resetWindow(duration: number): BandWindow;
-export declare function secToFrac(w: BandWindow, duration: number, sec: number): number;
-export declare function fracToSec(w: BandWindow, duration: number, frac: number): number;
-/**
- * Scroll to zoom, centred on the cursor — the DAW/mpv convention: the point
- * under the pointer stays fixed while the window resizes around it, so
- * scrolling repeatedly walks you inward on exactly the spot you're pointing
- * at. `deltaY < 0` zooms in.
- */
-export declare const ZOOM_FACTOR = 1.3;
-export declare const MIN_WINDOW_SEC = 3;
-export declare function zoomAt(w: BandWindow, duration: number, cursorSec: number, deltaY: number): BandWindow;
-/**
- * Zoomed in and playback walked past the edge of the window — follow it, or
- * you'd watch a frozen slice of waveform while the video plays on. Returns
- * null when no follow is needed.
- */
-export declare function followPlayhead(w: BandWindow, duration: number, t: number): BandWindow | null;
+import { type BandWindow } from './band/window';
+import { type LumaSeries } from './band/luma';
+import { type VideoMarker } from './band/markers';
+import { type BandLayerCache } from './band/memo';
+export { fracToSec, followPlayhead, isZoomed, MIN_WINDOW_SEC, resetWindow, secToFrac, spanSec, ZOOM_FACTOR, zoomAt, type BandWindow } from './band/window';
 /**
  * Click-to-seek biases toward the START of the spoken line under the click —
  * nobody wants to land mid-sentence. Only when the transcript is dense right
@@ -92,13 +68,37 @@ export interface BandPaintState {
     mutedKeys: Set<string>;
     window: BandWindow;
     hoverChapter: number;
+    /** Normalised light track (band/luma.ts); null ⇒ no ribbon. */
+    luma?: LumaSeries | null;
+    /** Social markers, ascending (band/markers.ts). */
+    comments?: VideoMarker[];
+    likes?: VideoMarker[];
+    /**
+     * Memo slots for the ribbon / heat / cluster arrays (band/memo.ts). With
+     * one, those layers recompute only when (window, width, data) change —
+     * not on every playhead repaint. Without one, computed fresh each paint.
+     */
+    cache?: BandLayerCache;
     /** Theme colours, resolved by the component via getDaisyUIColor. */
     colors: {
         accent: string;
         neutral: string;
         marker: string;
+        /** The light ribbon's wash (FEATURES.md: amber). Defaults to `marker`. */
+        ribbon?: string;
+        /** Comment dots. Defaults to `accent`. */
+        comment?: string;
+        /** Like heat strip. Defaults to `accent`. */
+        like?: string;
+        /** Outline behind comment dots so they read over a dense envelope. */
+        surface?: string;
     };
 }
+/** Like heat strip height, px, along the band's bottom edge (under the bookmark diamonds). */
+export declare const HEAT_H = 3;
+/** Comment dot radius and centre line (just under the chapter flags, which occupy y 0–4). */
+export declare const COMMENT_R = 2.5;
+export declare const COMMENT_Y = 7.5;
 /**
  * Size the canvas backing store for devicePixelRatio and return its 2d
  * context with the transform applied — or null when there is nothing honest
@@ -114,3 +114,9 @@ export declare function paintBand(ctx: CanvasRenderingContext2D, W: number, H: n
 /** Turn → BandTurn for the paint state (resolved key, ad flag). */
 export declare function toBandTurns(turns: VideoSpeakerTurn[]): BandTurn[];
 export { ALL_KEY };
+/**
+ * Comment clusters for this window/width — memoised when a cache is given.
+ * The component's hit test calls this with the SAME cache as the paint, so a
+ * mousemove never re-clusters what the last repaint already did.
+ */
+export declare function bandClusters(comments: VideoMarker[], w: BandWindow, duration: number, width: number, cache?: BandLayerCache): import("./band/markers").CommentCluster[];