@joewinke/jatui 0.8.6 → 0.9.1

package/dist/components/VideoPlayer.svelte.d.ts

@@ -1,49 +1,5 @@
-/** A model-authored marker: the video's structure. */
-export interface VideoChapter {
-    startSec: number;
-    title: string;
-    /** Optional captured still, shown in the band's hover card. */
-    thumbUrl?: string | null;
-}
-/** A diarized turn (or an ad read, `ad: true`). Structurally accepts meeting data. */
-export interface VideoSpeakerTurn {
-    startSec: number;
-    endSec: number;
-    speakerIdentity?: string | null;
-    speakerName?: string | null;
-    /** Explicit oklch hue (0–360). Omit to take the next palette colour. */
-    hue?: number | null;
-    /** Ad read — shares the lane but reads as not-a-person. */
-    ad?: boolean;
-}
-/** Transcript line. Structurally compatible with TranscriptPlayer's `TranscriptSegment`. */
-export interface VideoTranscriptSegment {
-    id: string;
-    startSec: number;
-    endSec: number;
-    speakerIdentity?: string | null;
-    speakerName?: string | null;
-    text: string;
-}
-/** A user-authored marker. Structurally compatible with `TranscriptBookmark`. */
-export interface VideoBookmark {
-    playbackSec: number;
-    label?: string | null;
-    note?: string | null;
-    participantName?: string | null;
-}
-/** Precomputed audio envelope. `peaks` are normalised against their own max. */
-export interface VideoWaveform {
-    peaks: number[];
-    /** Seconds the peaks span. Defaults to the video's duration. */
-    durationSec?: number;
-}
-/** Per-speaker totals. Structurally compatible with `TranscriptSpeakerTalkTime`. */
-export interface VideoSpeakerTalkTime {
-    speakerIdentity?: string | null;
-    speakerName?: string | null;
-    seconds: number;
-}
+export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime } from '../video/types';
+import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
@@ -93,6 +49,8 @@ type $$ComponentProps = {
     startAt?: number | null;
     transcriptPosition?: 'below' | 'side';
     transcriptMaxHeight?: string;
+    crossorigin?: 'anonymous' | 'use-credentials' | null;
+    syncUrlTime?: boolean;
     onTimeUpdate?: (video: HTMLVideoElement) => void;
     /** Present ⇒ the band grows an "add bookmark at current time" control. */
     onAddBookmark?: (playbackSec: number, label: string) => void;

package/dist/video/README.md

@@ -0,0 +1,53 @@
+# VideoPlayer internals — `src/lib/video/`
+
+The internal modules behind `components/VideoPlayer.svelte` (mos-5lzns.28 split).
+The component's **public props are frozen** — MOS consumes it, and the split
+exists precisely so the feature tasks below can land in parallel without
+colliding: **each module file is owned by exactly one task**; nobody edits a
+file they don't own, and everything converges through the component's existing
+props + callback surfaces.
+
+## Layout
+
+| File | Owner | Contents |
+|------|-------|----------|
+| `types.ts` | .28 (done) | The public data contracts — `VideoChapter`, `VideoSpeakerTurn`, `VideoTranscriptSegment`, `VideoBookmark`, `VideoWaveform`, `VideoSpeakerTalkTime`. Re-exported by the component, so `import type … from 'jatui'` is unchanged. |
+| `time.ts` | .28 (done) | Pure formatting: `formatTime`, `formatDuration`, `truncate`, `aspectRatioCss`. |
+| `model.ts` | .28 (done) | Speaker registry + identity colours + talk-time derivation + the sort normalisations. `ALL_KEY`/`UNKNOWN_KEY` live here. |
+| `band.ts` | .28 (done) — extended by **.30** | The timeline band: zoom window (`BandWindow`, `zoomAt`, `followPlayhead`), hit tests (`segmentAt`, `chapterAt`, `biasToSegmentStart`, `nearestBookmark`), and `paintBand` (canvas). .30 adds one-axis arbitration + the light ribbon; its state lives HERE. |
+| `keys.ts` | .28 (done) | The keyboard map — `PLAYER_KEYS` (the `?` overlay renders it), `chapterJump`, `FRAME_STEP_SEC`. Every key that exists is in the map; a key not in the map doesn't exist. |
+| `rate.ts` | .28 (done) — filled by **.32** | The rate composer contract (`composeRate`, deadband, clamp), the `SPEED_STEPS` staircase, `formatSpeedLabel`. .32 adds the speaker-pace and silence-map advisors — they never write `playbackRate`; they advise. |
+| `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |
+| `settings.ts` | shared — knobs added by .30–.34 | `coerce` (never throws, never junk) + `VIDEO_SETTINGS` registry. A knob lands WITH its reader. |
+| `audio.ts` | **.31** | Loudness matching, quiet listening, limiter — audio-graph contract is in the file header. |
+| `night.ts` | **.33** | Night dimming, bias light, predictive dimming (luma track), strobe guard. |
+| `presence.ts` | **.34** | Wind-down (Idle Detection), resume-at-sentence, FLIP open. |
+
+Sub-task map: **.30** scrubbing/one-axis/ribbon/markers → `band.ts` (+ its own
+paint layers); **.31** audio graph → `audio.ts`; **.32** rate composer →
+`rate.ts` advisors; **.33** night → `night.ts`; **.34** presence/wind-down →
+`presence.ts`.
+
+## The advisor doctrine (from extension-library FEATURES.md — keep it)
+
+1. **A disabled feature leaves no trace in the signal.** Not a residual
+   filter, not a half-faded gain ramp, not a stale CSS variable. Off means
+   the pixels and samples are exactly what they would have been.
+2. **Nothing acts without something the user can see.** Every automatic
+   correction has a visible surface (OSD, ribbon, meter, the fade that IS
+   the prompt).
+3. **Measuring code is an advisor; the component decides and applies.**
+   Modules under `src/lib/video/` read no settings and touch no `<video>`
+   (the audio graph builder is the one exception, and it takes a
+   MediaElementAudioSourceNode, never the element). Knobs arrive as an
+   `opts` argument; a bad argument returns a safe neutral value rather than
+   throwing. This is what keeps every module node-testable under
+   `npm run test:unit`.
+4. **The rate composer is the shape to follow** (`rate.ts`): `rate = base ×
+   speaker × silence`, advisors collapse to 1, the UI reports only `base`.
+
+## Testing
+
+Every pure module gets a `tests/unit/` node:test file (Node ≥ 22.18 strips
+types natively). Canvas/WAAPI work stays out of unit tests by construction —
+that's the point of the split.

package/dist/video/audio.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
+ * ("audio graph — loudness matching, quiet listening, limiter").
+ *
+ * What lands here (extension-library FEATURES.md §Loudness matching,
+ * §Quiet listening), as ADVISORS + an audio graph builder:
+ *
+ * · loudness matching — a gated RMS meter drives a slow gain rider toward a
+ *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
+ *   the meter mid-lesson; the correction is measured, not a strength slider.
+ * · quiet listening — loudness-compensated tone (two shelves + presence
+ *   peak + gentle compressor), amount rising as volume drops, a floor after
+ *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
+ *   clicks — a constant few ms of silence is the trade.
+ * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ *
+ * Module rules (README): no <video> access, no settings reads, no DOM. The
+ * graph builder is the one exception that may touch AudioContext — it takes
+ * a MediaElementAudioSourceNode the component creates, never the element.
+ * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
+ * ramp, no stale param (cancelScheduledValues before restoring). Off must be
+ * indistinguishable from never having run.
+ */
+/**
+ * Neutral advisor product — the multiplicative identity every composer and
+ * caller must get when audio correction is off or unmeasured. Exported so
+ * .31's rate-relevant advisors (if any) share the exact collapse value.
+ */
+export declare const AUDIO_NEUTRAL = 1;

package/dist/video/audio.js

@@ -0,0 +1,29 @@
+/**
+ * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
+ * ("audio graph — loudness matching, quiet listening, limiter").
+ *
+ * What lands here (extension-library FEATURES.md §Loudness matching,
+ * §Quiet listening), as ADVISORS + an audio graph builder:
+ *
+ * · loudness matching — a gated RMS meter drives a slow gain rider toward a
+ *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
+ *   the meter mid-lesson; the correction is measured, not a strength slider.
+ * · quiet listening — loudness-compensated tone (two shelves + presence
+ *   peak + gentle compressor), amount rising as volume drops, a floor after
+ *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
+ *   clicks — a constant few ms of silence is the trade.
+ * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ *
+ * Module rules (README): no <video> access, no settings reads, no DOM. The
+ * graph builder is the one exception that may touch AudioContext — it takes
+ * a MediaElementAudioSourceNode the component creates, never the element.
+ * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
+ * ramp, no stale param (cancelScheduledValues before restoring). Off must be
+ * indistinguishable from never having run.
+ */
+/**
+ * Neutral advisor product — the multiplicative identity every composer and
+ * caller must get when audio correction is off or unmeasured. Exported so
+ * .31's rate-relevant advisors (if any) share the exact collapse value.
+ */
+export const AUDIO_NEUTRAL = 1;

package/dist/video/band.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The timeline band (mos-5lzns.28 internal split) — one time axis for the
+ * waveform envelope, chapters, speakers and bookmarks.
+ *
+ * Ported from the VideoPlayer component's draw()/zoom window, which itself
+ * came from extension-library's player.js band. Design notes carried over:
+ *
+ * · ONE time axis. Every position — waveform bars, chapter flags, bookmarks,
+ *   the speaker lane, click/hover-to-seek — maps through the window's
+ *   secToFrac/fracToSec, so scroll-to-zoom is one piece of state everything
+ *   else respects for free.
+ * · ONE speaker surface. With a waveform, the envelope's own bars wear the
+ *   turn colours; the slim lane under it paints only as the no-waveform
+ *   fallback. Never two stacked time-parallel strips.
+ * · Chapter flags sit on the TOP edge, bookmark diamonds on the BOTTOM edge —
+ *   same idea (a marker on the timeline), different origin (the model's vs.
+ *   yours), so the two families are never confused at a glance.
+ *
+ * Everything here is DOM-free except `paintBand`/`prepareCanvas`, which take a
+ * canvas 2d context — no getDaisyUIColor calls inside; the component resolves
+ * theme colours and passes them in, so theme changes are a repaint, not a
+ * re-render of this module.
+ */
+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;
+/**
+ * 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
+ * there, though: on a sparse transcript the containing line could have begun
+ * minutes earlier, and biasing to it would fling the seek somewhere the user
+ * never clicked.
+ */
+export declare const DENSITY_WINDOW_SEC = 60;
+export declare function biasToSegmentStart(sec: number, segments: VideoTranscriptSegment[]): number;
+/** Last line starting at or before `sec` — segments are ascending. */
+export declare function segmentAt(sec: number, segments: VideoTranscriptSegment[]): VideoTranscriptSegment | null;
+export declare function chapterAt(sec: number, chapters: VideoChapter[]): number;
+export declare const BOOKMARK_HIT_PX = 6;
+export declare function nearestBookmark(xCss: number, width: number, bookmarks: VideoBookmark[], w: BandWindow, duration: number): VideoBookmark | null;
+/** Keep the (centre-anchored) hover card inside the band's own width. */
+export declare const CARD_HALF_PX = 90;
+export declare function clampCardX(x: number, width: number): number;
+export declare const RAIL_H = 10;
+export interface BandTurn {
+    startSec: number;
+    endSec: number;
+    key: string | null;
+    ad: boolean;
+}
+export interface BandPaintState {
+    currentTime: number;
+    duration: number;
+    /** Normalised 0–1 envelope; null ⇒ the flat rail fallback. */
+    peaks: number[] | null;
+    chapters: VideoChapter[];
+    bookmarks: VideoBookmark[];
+    turns: BandTurn[];
+    speakerColors: Map<string, string>;
+    /** With an envelope the bars carry the hues; the lane is the no-waveform fallback only. */
+    laneCarriesSpeakers: boolean;
+    highlightKey: string | null;
+    soloKey: string;
+    mutedKeys: Set<string>;
+    window: BandWindow;
+    hoverChapter: number;
+    /** Theme colours, resolved by the component via getDaisyUIColor. */
+    colors: {
+        accent: string;
+        neutral: string;
+        marker: string;
+    };
+}
+/**
+ * Size the canvas backing store for devicePixelRatio and return its 2d
+ * context with the transform applied — or null when there is nothing honest
+ * to paint into (no canvas, zero box, no context).
+ */
+export declare function prepareCanvas(canvas: HTMLCanvasElement): CanvasRenderingContext2D | null;
+/**
+ * Paint the band. Ported verbatim from the component's draw() — the alpha
+ * ladder, the chapter seam skip, the top-edge flags vs bottom-edge diamonds,
+ * the playhead. `W`/`H` are CSS pixels of the canvas box.
+ */
+export declare function paintBand(ctx: CanvasRenderingContext2D, W: number, H: number, s: BandPaintState): void;
+/** Turn → BandTurn for the paint state (resolved key, ad flag). */
+export declare function toBandTurns(turns: VideoSpeakerTurn[]): BandTurn[];
+export { ALL_KEY };

package/dist/video/band.js

@@ -0,0 +1,311 @@
+/**
+ * The timeline band (mos-5lzns.28 internal split) — one time axis for the
+ * waveform envelope, chapters, speakers and bookmarks.
+ *
+ * Ported from the VideoPlayer component's draw()/zoom window, which itself
+ * came from extension-library's player.js band. Design notes carried over:
+ *
+ * · ONE time axis. Every position — waveform bars, chapter flags, bookmarks,
+ *   the speaker lane, click/hover-to-seek — maps through the window's
+ *   secToFrac/fracToSec, so scroll-to-zoom is one piece of state everything
+ *   else respects for free.
+ * · ONE speaker surface. With a waveform, the envelope's own bars wear the
+ *   turn colours; the slim lane under it paints only as the no-waveform
+ *   fallback. Never two stacked time-parallel strips.
+ * · Chapter flags sit on the TOP edge, bookmark diamonds on the BOTTOM edge —
+ *   same idea (a marker on the timeline), different origin (the model's vs.
+ *   yours), so the two families are never confused at a glance.
+ *
+ * Everything here is DOM-free except `paintBand`/`prepareCanvas`, which take a
+ * canvas 2d context — no getDaisyUIColor calls inside; the component resolves
+ * theme colours and passes them in, so theme changes are a repaint, not a
+ * re-render of this module.
+ */
+import { ALL_KEY, filterDims, speakerKeyOf } from './model';
+/**
+ * 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 };
+}
+// ── Hit tests / position helpers ────────────────────────────────────────────
+/**
+ * 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
+ * there, though: on a sparse transcript the containing line could have begun
+ * minutes earlier, and biasing to it would fling the seek somewhere the user
+ * never clicked.
+ */
+export const DENSITY_WINDOW_SEC = 60;
+export function biasToSegmentStart(sec, segments) {
+    if (segments.length === 0)
+        return sec;
+    let nearby = 0;
+    for (const s of segments) {
+        if (Math.abs(s.startSec - sec) <= DENSITY_WINDOW_SEC / 2)
+            nearby++;
+    }
+    if (nearby <= 1)
+        return sec;
+    return segmentAt(sec, segments)?.startSec ?? sec;
+}
+/** Last line starting at or before `sec` — segments are ascending. */
+export function segmentAt(sec, segments) {
+    let best = null;
+    for (const s of segments) {
+        if (s.startSec <= sec)
+            best = s;
+        else
+            break;
+    }
+    return best;
+}
+export function chapterAt(sec, chapters) {
+    let idx = -1;
+    for (let i = 0; i < chapters.length; i++) {
+        if (chapters[i].startSec <= sec)
+            idx = i;
+        else
+            break;
+    }
+    return idx;
+}
+export const BOOKMARK_HIT_PX = 6;
+export function nearestBookmark(xCss, width, bookmarks, w, duration) {
+    if (bookmarks.length === 0 || !width)
+        return null;
+    let best = null;
+    let bestD = BOOKMARK_HIT_PX;
+    for (const b of bookmarks) {
+        const d = Math.abs(secToFrac(w, duration, b.playbackSec) * width - xCss);
+        if (d < bestD) {
+            bestD = d;
+            best = b;
+        }
+    }
+    return best;
+}
+/** Keep the (centre-anchored) hover card inside the band's own width. */
+export const CARD_HALF_PX = 90;
+export function clampCardX(x, width) {
+    return Math.max(Math.min(CARD_HALF_PX, width / 2), Math.min(x, width - CARD_HALF_PX));
+}
+// ── Canvas paint ────────────────────────────────────────────────────────────
+export const RAIL_H = 10; // no-waveform fallback: a flat rail instead of an envelope
+/**
+ * Size the canvas backing store for devicePixelRatio and return its 2d
+ * context with the transform applied — or null when there is nothing honest
+ * to paint into (no canvas, zero box, no context).
+ */
+export function prepareCanvas(canvas) {
+    const W = canvas.clientWidth;
+    const H = canvas.clientHeight;
+    if (!W || !H)
+        return null;
+    const dpr = window.devicePixelRatio || 1;
+    if (canvas.width !== Math.round(W * dpr) || canvas.height !== Math.round(H * dpr)) {
+        canvas.width = Math.round(W * dpr);
+        canvas.height = Math.round(H * dpr);
+    }
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        return null;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    return ctx;
+}
+function peakIdx(sec, dur, n) {
+    return Math.max(0, Math.min(n - 1, Math.floor((sec / dur) * n)));
+}
+/**
+ * Paint the band. Ported verbatim from the component's draw() — the alpha
+ * ladder, the chapter seam skip, the top-edge flags vs bottom-edge diamonds,
+ * the playhead. `W`/`H` are CSS pixels of the canvas box.
+ */
+export function paintBand(ctx, W, H, s) {
+    ctx.clearRect(0, 0, W, H);
+    const dur = s.duration;
+    const { accent, neutral, marker } = s.colors;
+    if (dur <= 0) {
+        // No duration yet — paint the empty rail so the band owns its space
+        // from the first frame and metadata arriving is never a layout shove.
+        ctx.globalAlpha = 0.2;
+        ctx.fillStyle = neutral;
+        ctx.fillRect(0, (H - RAIL_H) / 2, W, RAIL_H);
+        ctx.globalAlpha = 1;
+        return;
+    }
+    const p = s.peaks;
+    const withWave = !!p;
+    const n = p?.length ?? 0;
+    // The window is seeded by the duration effect; until then it is the whole
+    // video, so a first paint that races metadata still lands correctly.
+    const w = s.window;
+    const span = w.end - w.start || dur;
+    // Chapter boundaries in px — a column straddling one is skipped (the seam).
+    const bounds = s.chapters.slice(1).map((c) => secToFrac(w, dur, c.startSec) * W);
+    const GAP = 4;
+    const nowChapter = chapterAt(s.currentTime, s.chapters);
+    const visiblePeaks = withWave ? Math.max(1, Math.round((span / dur) * n)) : 0;
+    const step = withWave ? Math.max(1.5, W / visiblePeaks) : 2;
+    const cols = Math.max(1, Math.ceil(W / step));
+    const bw = Math.max(1, step - 1);
+    // Speaker sweep: columns advance monotonically in time and turns are
+    // sorted by start, so ONE pointer walks the turn list across the whole
+    // draw — never a per-column find(). Turns can overlap (an ad read inside
+    // a speaker's turn), so the sweep keeps a stack of open turns and the
+    // latest start wins, matching the lane's paint order.
+    let ti = 0;
+    const open = [];
+    for (let ci = 0; ci < cols; ci++) {
+        const x = ci * step;
+        if (bounds.some((b) => Math.abs(x + bw / 2 - b) < GAP))
+            continue;
+        const sec = fracToSec(w, dur, (x + step / 2) / W);
+        while (ti < s.turns.length && s.turns[ti].startSec <= sec)
+            open.push(s.turns[ti++]);
+        while (open.length && open[open.length - 1].endSec <= sec)
+            open.pop();
+        const turn = s.laneCarriesSpeakers ? null : (open[open.length - 1] ?? null);
+        const turnKey = turn && !turn.ad ? turn.key : null;
+        const ch = s.chapters.length ? chapterAt(sec, s.chapters) : -1;
+        const played = sec <= s.currentTime;
+        const hovered = ch >= 0 && ch === s.hoverChapter;
+        // Unplayed floor is 0.38 rather than player.js's 0.3: that value was
+        // tuned against the theater's near-black backdrop, and on a light
+        // theme's base-200 the envelope washed out at it.
+        let alpha;
+        if (played)
+            alpha = hovered ? 1 : 0.85;
+        else if (hovered)
+            alpha = 0.6;
+        else if (ch >= 0 && ch === nowChapter)
+            alpha = 0.52;
+        else
+            alpha = 0.38;
+        // Legend hover extends onto the envelope: the named speaker at full
+        // strength, everything else at 40% of its normal alpha — the
+        // played/unplayed ladder survives inside both halves.
+        if (s.highlightKey != null) {
+            if (turnKey === s.highlightKey)
+                alpha = played ? 1 : 0.8;
+            else
+                alpha *= 0.4;
+        }
+        else if (filterDims(turnKey, !!turn?.ad, s.soloKey, s.mutedKeys)) {
+            alpha *= 0.4;
+        }
+        ctx.globalAlpha = alpha;
+        if (turn?.ad)
+            ctx.fillStyle = marker;
+        else if (turnKey)
+            ctx.fillStyle = s.speakerColors.get(turnKey) ?? accent;
+        else
+            ctx.fillStyle = played ? accent : neutral;
+        const h = withWave ? Math.max(2, p[peakIdx(sec, dur, n)] * (H - 4)) : RAIL_H;
+        ctx.fillRect(x, withWave ? H - h : (H - RAIL_H) / 2, bw, h);
+    }
+    ctx.globalAlpha = 1;
+    // Boundary notches: a hairline in each seam plus a small accent flag on
+    // top — the flag reads as a UI marker even when the envelope is dense.
+    // Flags within a few px of each other collapse to one so a long video at
+    // full zoom-out never smears them into a solid bar.
+    ctx.globalAlpha = 0.4;
+    ctx.fillStyle = neutral;
+    for (const b of bounds)
+        ctx.fillRect(b - 1, 2, 2, H - 4);
+    ctx.globalAlpha = 0.95;
+    ctx.fillStyle = accent;
+    const FLAG_MERGE_PX = 6;
+    let lastFlagX = -Infinity;
+    for (const b of bounds) {
+        if (b - lastFlagX < FLAG_MERGE_PX)
+            continue;
+        lastFlagX = b;
+        ctx.beginPath();
+        ctx.moveTo(b - 3, 0);
+        ctx.lineTo(b + 3, 0);
+        ctx.lineTo(b, 4);
+        ctx.closePath();
+        ctx.fill();
+    }
+    // Bookmarks: diamonds pointing up from the BOTTOM edge — the mirror image
+    // of the chapter flags on top, so yours and the model's never blur together.
+    ctx.fillStyle = marker;
+    for (const b of s.bookmarks) {
+        const x = secToFrac(w, dur, b.playbackSec) * W;
+        if (x < -4 || x > W + 4)
+            continue;
+        ctx.beginPath();
+        ctx.moveTo(x, H);
+        ctx.lineTo(x - 3, H - 4);
+        ctx.lineTo(x, H - 8);
+        ctx.lineTo(x + 3, H - 4);
+        ctx.closePath();
+        ctx.fill();
+    }
+    // Playhead
+    ctx.globalAlpha = 0.9;
+    ctx.fillStyle = neutral;
+    ctx.fillRect(Math.max(0, Math.min(1, secToFrac(w, dur, s.currentTime))) * W - 0.5, 0, 1.5, H);
+    ctx.globalAlpha = 1;
+}
+/** Turn → BandTurn for the paint state (resolved key, ad flag). */
+export function toBandTurns(turns) {
+    return turns.map((t) => ({
+        startSec: t.startSec,
+        endSec: t.endSec,
+        key: t.ad ? null : speakerKeyOf(t),
+        ad: !!t.ad
+    }));
+}
+// Re-exports so the component (and sibling modules) have one band import site.
+export { ALL_KEY };

package/dist/video/deepLink.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `?t=` deep-link support for VideoPlayer (mos-5lzns.28).
+ *
+ * extension-library parity: every video there is addressable to the second —
+ * `?play=<file>&t=<sec>` — and "Continue on phone" builds exactly that link.
+ * In jatui the FILE is the host page's job (a route, a modal, a share token);
+ * the player owns the TIMESTAMP: `?t=` on the current URL.
+ *
+ * Opt-in via the `syncUrlTime` prop (default false — a component library must
+ * not rewrite the host page's URL history uninvited). When on:
+ *
+ * · READ — on mount, a `t` param seeds the start position (an explicit
+ *   `startAt` prop still wins: the host knows its own intent).
+ * · WRITE — during playback the URL is kept in step via
+ *   `history.replaceState` (never pushState — a timestamp is a position, not
+ *   a page; Back must mean "previous page", not "10 seconds ago"). Other
+ *   query params are preserved verbatim. Writes are throttled (TIMEUPDATE is
+ *   ~4Hz; rewriting the URL on every tick churns both the history machinery
+ *   and any devtools watching it) and floored to whole seconds — the link's
+ *   promise is "picks up at 1:23", not "1:22.87".
+ *
+ * Format accepts both `?t=90` and `?t=90s` (the extension writes the `s`
+ * suffix, YouTube-style). Garbage degrades to "no time", never a throw.
+ */
+/** Parse a `t` param value → seconds, or null. Accepts `90`, `90s`, `1:30`, `1:02:30`. */
+export declare function parseTimeParam(raw: string | null | undefined): number | null;
+/** Floor to whole seconds — the deep link promises second precision. */
+export declare function formatTimeParam(sec: number): string;
+/** Read the current `?t=` from a URL (or the document location). */
+export declare function readTimeParam(url?: string | URL | null): number | null;
+/**
+ * Rewrite the current URL's `t` param in place, preserving every other
+ * query param. Returns false when there was nothing to change (SSR, no
+ * history API, same second) so the caller can skip the replaceState.
+ */
+export declare function writeTimeParam(sec: number, url?: string | URL | null): boolean;
+/** Strip the `t` param (e.g. when the host unmounts the player opt-in). */
+export declare function clearTimeParam(url?: string | URL | null): boolean;
+/** Throttle for URL writes: at most one replaceState per WRITE_THROTTLE_MS. */
+export declare const WRITE_THROTTLE_MS = 2000;