@joewinke/jatui 0.9.0 → 0.10.0

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[];

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;