@joewinke/jatui 0.31.2 → 0.33.0

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

@@ -1,4 +1,5 @@
 export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime } from '../video/types';
+export type { RailChapter, RailChapterStatus } from '../video/chapterRail';
 export type { BandAxis, BandState } from '../video/band/axis';
 export type { VideoLumaTrack } from '../video/band/luma';
 export type { VideoMarker } from '../video/band/markers';
@@ -8,6 +9,58 @@ export type { VideoAdSpan, RateReport } from '../video/rate';
 export type { WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource } from '../video/presence';
 export type { ResumePoint } from '../video/advisors/resume-point';
 export type { VideoSettingsStore, SettingValue, SettingSpec } from '../video/settings';
+/**
+     * VideoPlayer — one video surface for everything, from a bare mp4 to a
+     * fully-analysed recording.
+     *
+     * Marries two prior implementations rather than inventing a third:
+     *
+     *  1. extension-library's framework-agnostic `mountPlayer` (player.js) —
+     *     the timeline band: waveform envelope as the scrubber, chapters as
+     *     structure inside it, diarized speaker colouring, bookmark diamonds,
+     *     scroll-to-zoom, hover card with "what's being said here".
+     *  2. jatui's TranscriptPlayer — the transcript pane: click a line to seek,
+     *     active line auto-scroll, solo-speaker playback, talk-time bars.
+     *
+     * EVERY intelligence prop is optional. A bare `<VideoPlayer {src} />` still
+     * gets the band (a real scrubber with hover-time, click-to-seek, keyboard
+     * seek), wheel volume and the keyboard map; chapters, speakers, waveform,
+     * transcript, bookmarks and talk-time each light up their own pane as the
+     * data exists. Nothing shifts layout when data arrives late (diarization is
+     * slow) — the band's slots are reserved from the first frame.
+     *
+     * ── Design notes carried over from player.js ────────────────────────────
+     * · ONE time axis. Every position — waveform bars, chapter flags, bookmarks,
+     *   the speaker lane, click/hover-to-seek — maps through the band window's
+     *   secToFrac/fracToSec (video/band.ts), 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.
+     * · The wheel means different things in different regions, and each region is
+     *   its own hover target so nothing is ambiguous: over the video it's volume
+     *   (shift = seek, alt = speed); over the band it's zoom.
+     * · The keyboard map (video/keys.ts) is the single source the keydown
+     *   handler and the `?` overlay both read — a key that exists is documented,
+     *   a documented key exists.
+     *
+     * Internals live in `src/lib/video/` (band / keys / rate / deepLink /
+     * settings + types/time/model; audio, night and presence are contracts for
+     * mos-5lzns.31/.33/.34 — see that directory's README for the ownership map
+     * and the advisor doctrine).
+     *
+     * Deliberately NOT ported: player.js's trim region (in/out handles). That's
+     * clip-editing, not playback, and belongs in an editor component.
+     *
+     * Theming is token-only — DaisyUI semantic vars for chrome, resolved at
+     * runtime via `getDaisyUIColor` for the canvas, repainted on theme change.
+     * Speaker hues follow TranscriptPlayer's oklch palette (data-driven identity
+     * colour, cycled per speaker — not brand colour).
+     */
+import { type Snippet } from 'svelte';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
@@ -20,6 +73,23 @@ import type { ResumePoint } from '../video/advisors/resume-point';
 import { type SettingValue, type VideoSettingsStore } from '../video/settings';
 type $$ComponentProps = {
     src: string;
+    /**
+     * What the media IS. `'audio'` (a podcast, a call recording, a brief)
+     * renders NO stage: there is no picture to frame, so the player is the
+     * band (the one timeline) plus its transport row. The media element
+     * still plays, just never shows. `aspect`/`poster` are ignored. Default
+     * `'video'`.
+     */
+    kind?: 'video' | 'audio';
+    /**
+     * Who owns play/pause, time and volume. `'native'` keeps the browser's
+     * `<video controls>` bar (which carries its own timeline next to the
+     * band). `'band'` drops the native controls and puts a transport row
+     * on the band instead: play/pause, `current / total`, speed, mute +
+     * volume, and fullscreen for video. One timeline, one set of controls.
+     * Default: `'band'` for `kind="audio"`, `'native'` for video.
+     */
+    transport?: 'native' | 'band';
     poster?: string | null;
     /**
      * Aspect ratio for the video stage — presentation-primitive prop (PRD).
@@ -58,6 +128,33 @@ type $$ComponentProps = {
      */
     captionsDefault?: boolean;
     chapters?: VideoChapter[];
+    /**
+     * mos-777hj — the live chapter rail. `'side'` (with chapters present)
+     * renders a sticky chapter pane beside the main column at ≥64rem — one
+     * row per chapter with time, title, status dot and summary, the active
+     * row tracking the playhead (aria-current, auto-scroll), a progress
+     * fill inside the active row and a played check behind the playhead —
+     * and a horizontal chip strip under the player below 64rem. Rows seek
+     * to the chapter and play; the active row carries the replay affordance
+     * (clicking it again replays from its start). Keyboard: listNav j/k to
+     * move, Enter to play, while the rail holds focus. Default `'off'` —
+     * the rail is opt-in and leaves the player exactly as it was.
+     */
+    chapterRail?: 'side' | 'off';
+    /**
+     * Fires when the viewer picks a chapter (row click / Enter / replay):
+     * the host pins its own view (e.g. a per-chapter visual panel) — the
+     * rail itself always keeps time-tracking the playhead.
+     */
+    onChapterSelect?: (chapter: VideoChapter, index: number) => void;
+    /**
+     * Optional snippet rendered between the stage and the transcript — the
+     * host's own content in the player's main column (e.g. a "now
+     * discussing" panel bound to the active chapter). Designed for
+     * `transcriptPosition: 'below'`; beside a side transcript it renders
+     * under the stage in the stage's column.
+     */
+    belowStage?: Snippet;
     speakers?: VideoSpeakerTurn[];
     transcript?: VideoTranscriptSegment[];
     bookmarks?: VideoBookmark[];
@@ -321,6 +418,7 @@ type $$ComponentProps = {
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {
     bandState: () => BandState;
+    seekToTime: (sec: number) => void;
 }, "night" | "nightDepth">;
 type VideoPlayer = ReturnType<typeof VideoPlayer>;
 export default VideoPlayer;

package/dist/video/README.md

@@ -11,7 +11,8 @@ props + callback surfaces.
 
 | 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. |
+| `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. .777hj adds `VideoChapter.endSec/summary/status` (all optional — the band ignores them). |
+| `chapterRail.ts` | **mos-777hj** | The opt-in `chapterRail: 'side'` pane's pure state: `railChapters(chapters, duration, t)` derives row ends (explicit `endSec` → next start → duration), the played check and the 0–1 progress fill for the row containing `t`; `activeRailIndex` is the row-highlight index. The component owns the DOM: sticky right column ≥64rem (chip strip below), rows seek+play on click, replay affordance on the active row, listNav j/k+Enter (the root keydown handler skips events from inside the rail), `onChapterSelect` for host-side pinning, `belowStage` snippet slot between stage and transcript, `seekToTime()` instance export for host deep links. |
 | `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. |

package/dist/video/chapterRail.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Chapter rail state (mos-777hj) — the pure half of VideoPlayer's opt-in
+ * `chapterRail: 'side'` pane: one row per chapter (title, time, status dot,
+ * summary), the active row tracking the playhead, a progress fill inside the
+ * active row and a played check once the playhead moves past a chapter's end.
+ *
+ * The component owns the DOM (rows, click-to-seek-and-play, listNav, sticky
+ * column, small-screen chip strip); everything derivable from
+ * (chapters, duration, playhead) lives HERE so it is node-testable under
+ * `npm run test:unit` — same discipline as band.ts / transcriptWindow.ts.
+ *
+ * Chapter ends: a chapter without an explicit `endSec` runs to the NEXT
+ * chapter's start; the last one runs to the media duration when known. With
+ * no duration and no following chapter the chapter is open-ended — its row
+ * simply never shows a played check or progress (division guards to 0).
+ */
+import type { VideoChapter } from './types';
+/** Dot tones, resolved to DaisyUI semantic vars by the component's CSS. */
+export type RailChapterStatus = 'info' | 'success' | 'warning' | 'error';
+/** A chapter as the rail renders it: end derived when absent. */
+export interface RailChapter {
+    startSec: number;
+    endSec: number;
+    title: string;
+    summary: string | null;
+    status: RailChapterStatus | null;
+    /** True once the playhead has moved past this chapter's end. */
+    played: boolean;
+    /** 0..1 fill for the row containing `t`; exactly 0 for every other row. */
+    progress: number;
+}
+/**
+ * The rail's rows for one playhead instant. `chapters` must be sorted by
+ * startSec (the component passes its `sortedChapters`); entries with a
+ * non-finite start are dropped, mirroring sortChapters' own filter.
+ *
+ * `t` before the first chapter (or exactly on it) marks that first chapter
+ * active with progress from its own start; there is no "before the program"
+ * row — the program starts at its first chapter.
+ */
+export declare function railChapters(chapters: VideoChapter[], durationSec: number | null, t: number): RailChapter[];
+/**
+ * Index of the row containing `t` (the LAST chapter whose startSec <= t), or
+ * -1 when `t` sits before every chapter / the list is empty. The component
+ * uses this for the row highlight, aria-current and the auto-scroll.
+ */
+export declare function activeRailIndex(chapters: {
+    startSec: number;
+}[], t: number): number;

package/dist/video/chapterRail.js

@@ -0,0 +1,79 @@
+/**
+ * Chapter rail state (mos-777hj) — the pure half of VideoPlayer's opt-in
+ * `chapterRail: 'side'` pane: one row per chapter (title, time, status dot,
+ * summary), the active row tracking the playhead, a progress fill inside the
+ * active row and a played check once the playhead moves past a chapter's end.
+ *
+ * The component owns the DOM (rows, click-to-seek-and-play, listNav, sticky
+ * column, small-screen chip strip); everything derivable from
+ * (chapters, duration, playhead) lives HERE so it is node-testable under
+ * `npm run test:unit` — same discipline as band.ts / transcriptWindow.ts.
+ *
+ * Chapter ends: a chapter without an explicit `endSec` runs to the NEXT
+ * chapter's start; the last one runs to the media duration when known. With
+ * no duration and no following chapter the chapter is open-ended — its row
+ * simply never shows a played check or progress (division guards to 0).
+ */
+const STATUS_VALUES = ['info', 'success', 'warning', 'error'];
+function statusOf(value) {
+    return value != null && STATUS_VALUES.includes(value)
+        ? value
+        : null;
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+/**
+ * The rail's rows for one playhead instant. `chapters` must be sorted by
+ * startSec (the component passes its `sortedChapters`); entries with a
+ * non-finite start are dropped, mirroring sortChapters' own filter.
+ *
+ * `t` before the first chapter (or exactly on it) marks that first chapter
+ * active with progress from its own start; there is no "before the program"
+ * row — the program starts at its first chapter.
+ */
+export function railChapters(chapters, durationSec, t) {
+    const rows = [];
+    for (let i = 0; i < chapters.length; i++) {
+        const c = chapters[i];
+        if (!c || !Number.isFinite(c.startSec) || c.startSec < 0)
+            continue;
+        const next = chapters[i + 1];
+        let end = c.endSec;
+        if (end == null || !Number.isFinite(end) || end <= c.startSec) {
+            end = next && Number.isFinite(next.startSec) ? next.startSec : durationSec;
+        }
+        if (end == null || !Number.isFinite(end) || end < c.startSec)
+            end = c.startSec;
+        const active = t >= c.startSec && (i === chapters.length - 1 || t < chapters[i + 1].startSec);
+        const span = end - c.startSec;
+        const progress = active && span > 0 ? clamp01((t - c.startSec) / span) : 0;
+        rows.push({
+            startSec: c.startSec,
+            endSec: end,
+            title: c.title,
+            summary: c.summary ?? null,
+            status: statusOf(c.status),
+            played: t >= end && end > c.startSec,
+            progress
+        });
+    }
+    return rows;
+}
+/**
+ * Index of the row containing `t` (the LAST chapter whose startSec <= t), or
+ * -1 when `t` sits before every chapter / the list is empty. The component
+ * uses this for the row highlight, aria-current and the auto-scroll.
+ */
+export function activeRailIndex(chapters, t) {
+    let idx = -1;
+    for (let i = 0; i < chapters.length; i++) {
+        if (chapters[i].startSec <= t)
+            idx = i;
+        else
+            break;
+    }
+    return idx;
+}

package/dist/video/keys.d.ts

@@ -20,7 +20,7 @@ export interface PlayerKeyRow {
      * Availability gate: the row is only advertised (and the key only bound)
      * when the feature's data exists. Undefined ⇒ always active.
      */
-    when?: 'chapters' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings';
+    when?: 'chapters' | 'rail' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings';
 }
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export declare const PLAYER_KEYS: PlayerKeyRow[];

package/dist/video/keys.js

@@ -23,6 +23,9 @@ export const PLAYER_KEYS = [
     { keys: 'Backspace', description: 'Reset speed to 1×' },
     { keys: '< / >', description: 'Frame step (pauses; ~1/30s per press)' },
     { keys: '[ / ]', description: 'Previous / next chapter', when: 'chapters' },
+    // mos-777hj — the rail's own listNav motions, active only while the rail
+    // holds focus (the same keys drive seek/play-pause everywhere else).
+    { keys: 'j / k / Enter', description: 'Chapter rail: move / play chapter', when: 'rail' },
     // Shift+[ / Shift+] — the chapter keys' shifted twins, so "structure"
     // and "people's reactions to it" sit under one hand (mos-5lzns.30).
     { keys: '{ / }', description: 'Previous / next comment', when: 'comments' },

package/dist/video/types.d.ts

@@ -17,6 +17,16 @@ export interface VideoChapter {
     title: string;
     /** Optional captured still, shown in the band's hover card. */
     thumbUrl?: string | null;
+    /**
+     * Chapter end, seconds. Absent (mos-777hj rail) the chapter runs to the
+     * NEXT chapter's start — or the media duration for the last one. The rail
+     * uses it for the played check and the progress fill; the band ignores it.
+     */
+    endSec?: number | null;
+    /** One-line summary shown under the title in the chapter rail. */
+    summary?: string | null;
+    /** Rail status dot tone (DaisyUI semantic) — null renders no dot. */
+    status?: 'info' | 'success' | 'warning' | 'error' | null;
 }
 /** A diarized turn (or an ad read, `ad: true`). Structurally accepts meeting data. */
 export interface VideoSpeakerTurn {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.31.2",
+  "version": "0.33.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",