@rightkit/video-ui 0.0.0-stage → 0.1.0

package/dist/editor/ColourInspector.js

@@ -0,0 +1,341 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Colour section of the clip Inspector. Controls edit a local draft and call the
+ * engine on pointer-up, key-up or blur; discrete edits (add, remove, reset,
+ * select) commit at once. Scopes are the luma waveform and vectorscope at `atMs`.
+ */
+import { Button, Input, SegmentedControl, Select } from "@rightkit/react-shell/react";
+import { useEffect, useRef, useState } from "react";
+import { assetUrl } from "../lib/asset.js";
+import { errorMessage } from "../lib/engine.js";
+import { HDR_UNAVAILABLE_NOTICE } from "../hooks/useHdrToSdr.js";
+import { colourGet, colourScopes, colourSet, playbackRefreshFinishing, } from "../lib/media.js";
+const MAX_POINTS = 16;
+const MAX_HSL = 6;
+/** Minimum x gap kept between neighbouring curve points. */
+const EPS = 0.001;
+const KEY_STEP = 0.01;
+const NEUTRAL_GRADE = {};
+const NEUTRAL_WHEELS = { lift: [0, 0, 0], gamma: [1, 1, 1], gain: [1, 1, 1] };
+const WHEELS = [
+    { key: "lift", label: "Lift", min: -0.5, max: 0.5 },
+    { key: "gamma", label: "Gamma", min: 0.2, max: 5 },
+    { key: "gain", label: "Gain", min: 0, max: 4 },
+];
+const CHANNELS = [
+    { key: "r", label: "R" },
+    { key: "g", label: "G" },
+    { key: "b", label: "B" },
+];
+const CURVE_TABS = [
+    { value: "master", label: "Master" },
+    { value: "r", label: "R" },
+    { value: "g", label: "G" },
+    { value: "b", label: "B" },
+];
+const CURVE_NAMES = { master: "Master", r: "Red", g: "Green", b: "Blue" };
+const HSL_RANGES = [
+    { value: "reds", label: "Reds" },
+    { value: "yellows", label: "Yellows" },
+    { value: "greens", label: "Greens" },
+    { value: "cyans", label: "Cyans" },
+    { value: "blues", label: "Blues" },
+    { value: "magentas", label: "Magentas" },
+];
+const SCOPE_TABS = [
+    { value: "graded", label: "Graded" },
+    { value: "source", label: "Source" },
+];
+const clamp = (v, lo, hi) => Math.min(Math.max(v, lo), hi);
+const mean = (rgb) => (rgb[0] + rgb[1] + rgb[2]) / 3;
+function withChannel(rgb, i, v) {
+    return [i === 0 ? v : rgb[0], i === 1 ? v : rgb[1], i === 2 ? v : rgb[2]];
+}
+function shiftRgb(rgb, d, lo, hi) {
+    return [clamp(rgb[0] + d, lo, hi), clamp(rgb[1] + d, lo, hi), clamp(rgb[2] + d, lo, hi)];
+}
+/** The grade persisted for this clip (or the project); null when none is set. */
+function storedOf(s, sourceId, toProject) {
+    return toProject ? s.grade : (s.by_source[sourceId] ?? null);
+}
+function writeWheel(g, k, rgb) {
+    const wheels = { ...(g.wheels ?? NEUTRAL_WHEELS) };
+    wheels[k] = rgb;
+    return { ...g, wheels };
+}
+function curveOf(g, ch) {
+    return g.curves?.[ch] ?? [];
+}
+function withCurve(g, ch, pts) {
+    const curves = { ...g.curves };
+    if (pts.length === 0)
+        delete curves[ch];
+    else
+        curves[ch] = pts;
+    return { ...g, curves };
+}
+/** Allowed x range for point `i`, keeping it strictly between its neighbours. */
+function curveBounds(pts, i) {
+    const prev = pts[i - 1];
+    const next = pts[i + 1];
+    return [prev ? prev.x + EPS : 0, next ? next.x - EPS : 1];
+}
+/** Client coordinates to curve space: x 0..1 left to right, y 0..1 bottom to top. */
+function curvePoint(box, clientX, clientY) {
+    const r = box.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+        return { x: 0, y: 0 };
+    return {
+        x: clamp((clientX - r.left) / r.width, 0, 1),
+        y: clamp(1 - (clientY - r.top) / r.height, 0, 1),
+    };
+}
+/** Applies a successful `colour.set` reply to the persisted table. */
+function applySaved(prev, sourceId, toProject, r) {
+    if (toProject)
+        return { ...prev, grade: r.grade };
+    const by_source = { ...prev.by_source };
+    if (r.grade)
+        by_source[sourceId] = r.grade;
+    else
+        delete by_source[sourceId];
+    return { ...prev, by_source };
+}
+function SliderRow({ label, name, testId, min, max, step, value, digits = 2, onInput, onCommit, }) {
+    return (_jsxs("label", { className: "colour-row", children: [_jsx("span", { className: "colour-row__label", children: label }), _jsx(Input, { type: "range", className: "colour-row__range", "aria-label": name, "data-testid": testId, min: min, max: max, step: step, value: value, onChange: (e) => onInput(Number(e.target.value)), onPointerUp: onCommit, onKeyUp: onCommit, onBlur: onCommit }), _jsx("output", { className: "colour-row__value", children: value.toFixed(digits) })] }));
+}
+export function ColourInspector({ dir, sourceId, atMs }) {
+    const [state, setState] = useState(null);
+    const [project, setProject] = useState(false);
+    const [draft, setDraft] = useState(NEUTRAL_GRADE);
+    const [channel, setChannel] = useState("master");
+    const [graded, setGraded] = useState(true);
+    const [scopes, setScopes] = useState(null);
+    const [scopeTick, setScopeTick] = useState(0);
+    const [actionError, setActionError] = useState(null);
+    const [scopeError, setScopeError] = useState(null);
+    /** Synchronous copy of `draft` so pointer and key handlers never read a stale grade. */
+    const draftRef = useRef(NEUTRAL_GRADE);
+    /** JSON of the grade persisted for the current edit target; a commit must differ from it. */
+    const savedKey = useRef("null");
+    /** Bumped per commit and per mode switch; only the newest reply updates draft bookkeeping. */
+    const seqRef = useRef(0);
+    /** Index of the curve point being dragged, if any. */
+    const dragRef = useRef(null);
+    // Load the grade table when the clip's source or project changes.
+    useEffect(() => {
+        let cancelled = false;
+        seqRef.current += 1;
+        setState(null);
+        setActionError(null);
+        colourGet({ dir })
+            .then((r) => {
+            if (cancelled)
+                return;
+            const editable = storedOf(r, sourceId, false) ?? NEUTRAL_GRADE;
+            draftRef.current = editable;
+            setDraft(editable);
+            savedKey.current = JSON.stringify(storedOf(r, sourceId, false));
+            setProject(false);
+            setState(r);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setActionError(errorMessage(e));
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [dir, sourceId]);
+    // Scopes for the clip frame at `atMs`; debounced so trims and scrubs do not flood the engine.
+    useEffect(() => {
+        let cancelled = false;
+        const timer = window.setTimeout(() => {
+            colourScopes({ dir, source: sourceId, at_ms: atMs, graded })
+                .then((r) => {
+                if (cancelled)
+                    return;
+                setScopes(r);
+                setScopeError(null);
+            })
+                .catch((e) => {
+                if (!cancelled)
+                    setScopeError(errorMessage(e));
+            });
+        }, 250);
+        return () => {
+            cancelled = true;
+            window.clearTimeout(timer);
+        };
+    }, [dir, sourceId, atMs, graded, scopeTick]);
+    const setGrade = (next) => {
+        draftRef.current = next;
+        setDraft(next);
+    };
+    const send = (grade, toProject) => {
+        const key = JSON.stringify(grade);
+        if (key === savedKey.current)
+            return;
+        const seq = ++seqRef.current;
+        setActionError(null);
+        colourSet({ dir, source: toProject ? undefined : sourceId, grade })
+            .then((r) => {
+            // Every reply is the persisted truth for its own target, so it always lands.
+            setState((prev) => (prev ? applySaved(prev, sourceId, toProject, r) : prev));
+            // The preview decodes through the saved grade; rebuild it so it shows this one.
+            void playbackRefreshFinishing(dir).catch(() => undefined);
+            if (seq !== seqRef.current)
+                return;
+            savedKey.current = JSON.stringify(r.grade);
+            if (!toProject && r.grade === null)
+                setGrade(NEUTRAL_GRADE);
+            setScopeTick((t) => t + 1);
+        })
+            .catch((e) => {
+            if (seq === seqRef.current)
+                setActionError(errorMessage(e));
+        });
+    };
+    const commitDraft = () => send(draftRef.current, project);
+    const commitNow = (next) => {
+        setGrade(next);
+        send(next, project);
+    };
+    const setMode = (toProject) => {
+        if (!state || toProject === project)
+            return;
+        seqRef.current += 1;
+        setActionError(null);
+        setProject(toProject);
+        setGrade(storedOf(state, sourceId, toProject) ?? NEUTRAL_GRADE);
+        savedKey.current = JSON.stringify(storedOf(state, sourceId, toProject));
+    };
+    // Wheels: the master moves all three channels by the same delta.
+    const wheelInput = (k, i, v) => {
+        const g = draftRef.current;
+        setGrade(writeWheel(g, k, withChannel((g.wheels ?? NEUTRAL_WHEELS)[k], i, v)));
+    };
+    const wheelMasterInput = (def, v) => {
+        const g = draftRef.current;
+        const rgb = (g.wheels ?? NEUTRAL_WHEELS)[def.key];
+        setGrade(writeWheel(g, def.key, shiftRgb(rgb, v - mean(rgb), def.min, def.max)));
+    };
+    const wheelReset = (k) => commitNow(writeWheel(draftRef.current, k, NEUTRAL_WHEELS[k]));
+    // Curves: click empty space to add, drag to move, double-click / Delete to remove.
+    const onCurveDown = (e) => {
+        const g = draftRef.current;
+        const pts = curveOf(g, channel);
+        if (pts.length >= MAX_POINTS)
+            return;
+        const p = curvePoint(e.currentTarget, e.clientX, e.clientY);
+        const next = [...pts, p].sort((a, b) => a.x - b.x);
+        dragRef.current = next.indexOf(p);
+        e.currentTarget.setPointerCapture(e.pointerId);
+        setGrade(withCurve(g, channel, next));
+    };
+    const onCurveMove = (e) => {
+        const i = dragRef.current;
+        if (i === null)
+            return;
+        const g = draftRef.current;
+        const pts = curveOf(g, channel);
+        const p = curvePoint(e.currentTarget, e.clientX, e.clientY);
+        const [lo, hi] = curveBounds(pts, i);
+        const moved = pts.map((q, j) => (j === i ? { x: clamp(p.x, lo, hi), y: p.y } : q));
+        setGrade(withCurve(g, channel, moved));
+    };
+    const onCurveUp = () => {
+        if (dragRef.current === null)
+            return;
+        dragRef.current = null;
+        commitDraft();
+    };
+    const removePoint = (i) => {
+        const g = draftRef.current;
+        commitNow(withCurve(g, channel, curveOf(g, channel).filter((_, j) => j !== i)));
+    };
+    const addPoint = () => {
+        const g = draftRef.current;
+        const pts = curveOf(g, channel);
+        if (pts.length >= MAX_POINTS)
+            return;
+        // Place the point on the identity diagonal at the middle of the widest gap.
+        const xs = [0, ...pts.map((p) => p.x), 1];
+        let x = 0.5;
+        let widest = -1;
+        xs.forEach((a, k) => {
+            const b = xs[k + 1];
+            if (b === undefined || b - a <= widest)
+                return;
+            widest = b - a;
+            x = (a + b) / 2;
+        });
+        commitNow(withCurve(g, channel, [...pts, { x, y: x }].sort((a, b) => a.x - b.x)));
+    };
+    const onPointKey = (i, e) => {
+        if (e.key === "Delete" || e.key === "Backspace") {
+            e.preventDefault();
+            removePoint(i);
+            return;
+        }
+        const dx = e.key === "ArrowLeft" ? -KEY_STEP : e.key === "ArrowRight" ? KEY_STEP : 0;
+        const dy = e.key === "ArrowDown" ? -KEY_STEP : e.key === "ArrowUp" ? KEY_STEP : 0;
+        if (dx === 0 && dy === 0)
+            return;
+        e.preventDefault();
+        const g = draftRef.current;
+        const pts = curveOf(g, channel);
+        const at = pts[i];
+        if (!at)
+            return;
+        const [lo, hi] = curveBounds(pts, i);
+        const moved = pts.map((p, j) => j === i ? { x: clamp(at.x + dx, lo, hi), y: clamp(at.y + dy, 0, 1) } : p);
+        setGrade(withCurve(g, channel, moved));
+    };
+    // HSL secondaries.
+    const patchHsl = (i, patch, commit) => {
+        const g = draftRef.current;
+        const list = (g.hsl ?? []).map((h, j) => (j === i ? { ...h, ...patch } : h));
+        if (commit)
+            commitNow({ ...g, hsl: list });
+        else
+            setGrade({ ...g, hsl: list });
+    };
+    const addHsl = () => {
+        const g = draftRef.current;
+        const list = g.hsl ?? [];
+        if (list.length >= MAX_HSL)
+            return;
+        const used = new Set(list.map((h) => h.range));
+        const range = HSL_RANGES.find((r) => !used.has(r.value))?.value ?? "reds";
+        commitNow({ ...g, hsl: [...list, { range, hue_shift: 0, saturation: 0, lightness: 0, strength: 1 }] });
+    };
+    const removeHsl = (i) => {
+        const g = draftRef.current;
+        commitNow({ ...g, hsl: (g.hsl ?? []).filter((_, j) => j !== i) });
+    };
+    const stored = state ? storedOf(state, sourceId, false) : null;
+    const hasOwn = stored !== null;
+    const error = actionError ?? scopeError;
+    const wheels = draft.wheels ?? NEUTRAL_WHEELS;
+    const sat = draft.saturation ?? 1;
+    const hsl = draft.hsl ?? [];
+    const points = curveOf(draft, channel);
+    const curvePolyline = points.map((p) => `${p.x * 100},${(1 - p.y) * 100}`).join(" ");
+    return (_jsxs("section", { className: "colour-section", "aria-label": "Colour", "data-testid": "colour-section", children: [_jsx("h3", { className: "colour-section__title", children: "Colour" }), state?.capabilities?.hdr_to_sdr === false && (_jsx("p", { className: "cr-muted colour-status", "data-testid": "colour-hdr-notice", children: HDR_UNAVAILABLE_NOTICE })), state === null && actionError === null && _jsx("p", { className: "cr-muted colour-status", children: "Loading colour\u2026" }), state !== null && (_jsxs(_Fragment, { children: [_jsx("p", { className: "cr-muted colour-source", children: project
+                            ? "Editing the project grade."
+                            : hasOwn
+                                ? "This clip uses its own grade."
+                                : "This clip uses the project grade." }), _jsxs("div", { className: "colour-actions", children: [hasOwn && !project && (_jsx(Button, { size: "sm", variant: "secondary", "data-testid": "colour-use-project", onClick: () => send(null, false), children: "Use project grade" })), _jsx(Button, { size: "sm", variant: "ghost", "aria-pressed": project, onClick: () => setMode(!project), children: "Edit project grade" })] }), _jsxs("div", { className: "colour-group", children: [_jsx("h4", { className: "colour-group__title", children: "Wheels" }), WHEELS.map((def) => {
+                                const rgb = wheels[def.key];
+                                return (_jsxs("div", { className: "colour-wheel", children: [_jsxs("div", { className: "colour-wheel__head", children: [_jsx("span", { className: "colour-wheel__name", children: def.label }), _jsx(Button, { size: "sm", variant: "ghost", onClick: () => wheelReset(def.key), children: "Reset" })] }), _jsx(SliderRow, { label: "Master", name: `${def.label} master`, testId: `colour-${def.key}-master`, min: def.min, max: def.max, step: 0.01, value: mean(rgb), onInput: (v) => wheelMasterInput(def, v), onCommit: commitDraft }), CHANNELS.map((c, i) => (_jsx(SliderRow, { label: c.label, name: `${def.label} ${c.label}`, testId: `colour-${def.key}-${c.key}`, min: def.min, max: def.max, step: 0.01, value: rgb[i], onInput: (v) => wheelInput(def.key, i, v), onCommit: commitDraft }, c.key)))] }, def.key));
+                            })] }), _jsxs("div", { className: "colour-group", children: [_jsx("h4", { className: "colour-group__title", children: "Curves" }), _jsx(SegmentedControl, { label: "Curve channel", value: channel, options: CURVE_TABS, onChange: setChannel }), _jsxs("svg", { className: "colour-curve", viewBox: "0 0 100 100", role: "group", "aria-label": `${CURVE_NAMES[channel]} curve`, "data-testid": "colour-curve", onPointerDown: onCurveDown, onPointerMove: onCurveMove, onPointerUp: onCurveUp, onPointerCancel: onCurveUp, children: [_jsx("rect", { className: "colour-curve__hit", x: "0", y: "0", width: "100", height: "100", fill: "transparent" }), _jsx("line", { className: "colour-curve__identity", x1: "0", y1: "100", x2: "100", y2: "0" }), points.length > 0 && _jsx("polyline", { className: "colour-curve__line", fill: "none", points: curvePolyline }), points.map((p, i) => (_jsx("circle", { className: "colour-curve__point", cx: p.x * 100, cy: (1 - p.y) * 100, r: 2.5, tabIndex: 0, role: "slider", "aria-label": `${CURVE_NAMES[channel]} point ${i + 1} of ${points.length}`, "aria-valuetext": `input ${p.x.toFixed(2)}, output ${p.y.toFixed(2)}`, onPointerDown: (e) => {
+                                            e.stopPropagation();
+                                            dragRef.current = i;
+                                            e.currentTarget.setPointerCapture(e.pointerId);
+                                        }, onKeyDown: (e) => onPointKey(i, e), onKeyUp: commitDraft, onBlur: commitDraft, onDoubleClick: () => removePoint(i) }, i)))] }), _jsxs("div", { className: "colour-actions", children: [_jsx(Button, { size: "sm", variant: "secondary", disabled: points.length >= MAX_POINTS, onClick: addPoint, children: "Add point" }), _jsx(Button, { size: "sm", variant: "ghost", disabled: points.length === 0, onClick: () => commitNow(withCurve(draftRef.current, channel, [])), children: "Reset curve" })] })] }), _jsxs("div", { className: "colour-group", children: [_jsxs("div", { className: "colour-group__head", children: [_jsx("h4", { className: "colour-group__title", children: "HSL secondary" }), _jsx(Button, { size: "sm", variant: "secondary", disabled: hsl.length >= MAX_HSL, onClick: addHsl, children: "Add secondary" })] }), hsl.map((h, i) => (_jsxs("div", { className: "colour-hsl", children: [_jsxs("div", { className: "colour-hsl__head", children: [_jsx(Select, { label: `Secondary ${i + 1} range`, value: h.range, options: HSL_RANGES, onChange: (value) => {
+                                                    const r = HSL_RANGES.find((x) => x.value === value);
+                                                    if (r)
+                                                        patchHsl(i, { range: r.value }, true);
+                                                } }), _jsx(Button, { size: "sm", variant: "ghost", "aria-label": `Remove secondary ${i + 1}`, onClick: () => removeHsl(i), children: "Remove" })] }), _jsx(SliderRow, { label: "Hue shift", name: `Secondary ${i + 1} hue shift`, min: -180, max: 180, step: 1, value: h.hue_shift, digits: 0, onInput: (v) => patchHsl(i, { hue_shift: v }, false), onCommit: commitDraft }), _jsx(SliderRow, { label: "Saturation", name: `Secondary ${i + 1} saturation`, min: -1, max: 1, step: 0.01, value: h.saturation, onInput: (v) => patchHsl(i, { saturation: v }, false), onCommit: commitDraft }), _jsx(SliderRow, { label: "Lightness", name: `Secondary ${i + 1} lightness`, min: -1, max: 1, step: 0.01, value: h.lightness, onInput: (v) => patchHsl(i, { lightness: v }, false), onCommit: commitDraft }), _jsx(SliderRow, { label: "Strength", name: `Secondary ${i + 1} strength`, min: 0, max: 1, step: 0.01, value: h.strength, onInput: (v) => patchHsl(i, { strength: v }, false), onCommit: commitDraft })] }, i)))] }), _jsxs("div", { className: "colour-group", children: [_jsx("h4", { className: "colour-group__title", children: "Saturation" }), _jsx(SliderRow, { label: "Saturation", name: "Saturation", testId: "colour-saturation", min: 0, max: 2, step: 0.01, value: sat, onInput: (v) => setGrade({ ...draftRef.current, saturation: v }), onCommit: commitDraft })] })] })), _jsxs("div", { className: "colour-group", children: [_jsxs("div", { className: "colour-group__head", children: [_jsx("h4", { className: "colour-group__title", children: "Scopes" }), _jsx(SegmentedControl, { label: "Scope grade", value: graded ? "graded" : "source", options: SCOPE_TABS, onChange: (v) => setGraded(v === "graded") })] }), _jsx("div", { className: "colour-scope__box colour-scope__box--wide", children: scopes ? (_jsx("img", { className: "colour-scope__img", src: assetUrl(scopes.waveform), alt: "Luma waveform", "data-testid": "colour-scope-waveform" })) : (_jsx("span", { className: "cr-muted colour-status", children: "Loading scopes\u2026" })) }), _jsx("div", { className: "colour-scope__box colour-scope__box--square", children: scopes ? (_jsx("img", { className: "colour-scope__img", src: assetUrl(scopes.vectorscope), alt: "Vectorscope", "data-testid": "colour-scope-vectorscope" })) : (_jsx("span", { className: "cr-muted colour-status", children: "Loading scopes\u2026" })) }), scopes && (_jsxs("dl", { className: "colour-stats", children: [_jsxs("div", { children: [_jsx("dt", { children: "Y min" }), _jsx("dd", { children: scopes.stats.y_min.toFixed(2) })] }), _jsxs("div", { children: [_jsx("dt", { children: "Y max" }), _jsx("dd", { children: scopes.stats.y_max.toFixed(2) })] }), _jsxs("div", { children: [_jsx("dt", { children: "Y avg" }), _jsx("dd", { children: scopes.stats.y_avg.toFixed(2) })] }), _jsxs("div", { children: [_jsx("dt", { children: "Sat max" }), _jsx("dd", { children: scopes.stats.sat_max.toFixed(2) })] })] })), scopes && (scopes.clipped.high || scopes.clipped.low) && (_jsxs("div", { className: "colour-clipping", "data-testid": "colour-clipping", role: "status", children: [scopes.clipped.high && _jsx("span", { children: "Clipping: highlights" }), scopes.clipped.low && _jsx("span", { children: "Clipping: shadows" })] }))] }), error !== null && (_jsx("p", { role: "alert", className: "colour-error", "data-testid": "colour-error", children: error }))] }));
+}

package/dist/editor/Inspector.d.ts

@@ -0,0 +1,15 @@
+import type { EditorModel } from "./model.js";
+import { type CapabilityReport } from "./capabilities.js";
+import type { EditSession } from "./adapter.js";
+export declare function Inspector({ model, selection, session, caps, dir, playheadS, onCommitted, onError, }: {
+    model: EditorModel;
+    selection: ReadonlySet<string>;
+    session: EditSession;
+    caps: CapabilityReport | null;
+    /** Project dir for the media.waveform call. */
+    dir: string;
+    /** Timeline playhead in seconds; drives the colour scope sample frame. */
+    playheadS?: number;
+    onCommitted: () => void;
+    onError: (message: string) => void;
+}): import("react").JSX.Element | null;

package/dist/editor/Inspector.js

@@ -0,0 +1,202 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Selection inspector: continuous controls preview locally and commit once on
+ * release/blur through `useInspectorGestureTransaction` (adapted from
+ * hyperframes). Every control maps to a real `cutright_timeline::Action` or is
+ * rendered disabled with the capability reason.
+ */
+import { Checkbox, Field, Input } from "@rightkit/react-shell/react";
+import { errorText } from "./adapter.js";
+import { useEffect, useMemo, useState } from "react";
+import { engineCall } from "../lib/engine.js";
+import { decimatePeaks, loudnessToOpacity } from "./vendor/hyperframes/audioWaveformPeaks.js";
+import { ticksToSeconds } from "../lib/project.js";
+import { useInspectorGestureDraft } from "./vendor/hyperframes/useInspectorGestureTransaction.js";
+import { editTitle, linkNarration, setGain, setMute, positionTitle, swapTake, setUnder, trimAudioClip, trimClip, trimTitle, unlinkNarration, } from "./actions.js";
+import { supports, unsupported } from "./capabilities.js";
+import { ColourInspector } from "./ColourInspector.js";
+export function Inspector({ model, selection, session, caps, dir, playheadS, onCommitted, onError, }) {
+    const clip = useMemo(() => {
+        for (const id of selection) {
+            const hit = model.lanes.flatMap((l) => l.clips).find((c) => c.id === id);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }, [model, selection]);
+    const commit = async (actions) => {
+        try {
+            await session.apply(actions.filter(Boolean), "Inspector edit");
+            onCommitted();
+        }
+        catch (e) {
+            onError(errorText(e));
+            onCommitted();
+        }
+    };
+    if (selection.size === 0) {
+        return (_jsx("p", { className: "cr-muted", style: { margin: 0, fontSize: 12 }, children: "Select a clip on the timeline to edit its trim, audio, or title." }));
+    }
+    if (selection.size > 1) {
+        return (_jsxs("p", { className: "cr-muted", style: { margin: 0, fontSize: 12 }, children: [selection.size, " clips selected \u2014 drag to move together; inspect edits one clip."] }));
+    }
+    if (!clip)
+        return null;
+    return (_jsxs("div", { className: "fe-inspect", "aria-label": "Clip inspector", children: [clip.ref.kind === "video" && (_jsx(VideoInspector, { clip: clip, model: model, commit: commit, caps: caps, dir: dir, playheadS: playheadS }, `${clip.id}:${model.revisionCursor}`)), clip.ref.kind === "audio" && (_jsx(AudioInspector, { clip: clip, model: model, commit: commit, caps: caps, dir: dir }, `${clip.id}:${model.revisionCursor}`)), clip.ref.kind === "title" && (_jsx(TitleInspector, { clip: clip, model: model, commit: commit, caps: caps }, `${clip.id}:${model.revisionCursor}`))] }));
+}
+function SecondsInput({ label, seconds, onCommit, }) {
+    const { draft, setDraft, transaction } = useInspectorGestureDraft({
+        sourceValue: seconds,
+        onPreview: () => undefined,
+        onCommit: (v) => onCommit(v),
+    });
+    return (_jsx(Field, { label: label, children: (ids) => (_jsx(Input, { ...ids, inputMode: "decimal", value: String(draft.toFixed(2)), onFocus: () => transaction.begin(), onChange: (e) => {
+                const v = Number(e.target.value);
+                if (Number.isFinite(v)) {
+                    setDraft(v);
+                    transaction.preview(v);
+                }
+            }, onBlur: () => transaction.settle(), onKeyDown: (e) => {
+                if (e.key === "Enter")
+                    transaction.settle();
+                if (e.key === "Escape")
+                    transaction.cancel();
+            } })) }));
+}
+function VideoInspector({ clip, model, commit, caps, dir, playheadS, }) {
+    if (clip.ref.kind !== "video")
+        return null;
+    const clipIndex = clip.ref.index;
+    const inS = ticksToSeconds(clip.ref.clip.source_in);
+    const outS = ticksToSeconds(clip.ref.clip.source_out);
+    // Source time under the playhead when it is inside this clip; otherwise source-in.
+    const scopeS = playheadS !== undefined && playheadS >= clip.start && playheadS <= clip.start + clip.duration
+        ? Math.min(outS, Math.max(inS, inS + (playheadS - clip.start)))
+        : inS;
+    const srcDur = model.sourceDurationS.get(clip.ref.clip.source) ?? outS;
+    const [take, setTake] = useState(clip.ref.clip.source);
+    const [takeIn, setTakeIn] = useState(inS);
+    const [takeOut, setTakeOut] = useState(outS);
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "fe-inspect__row", children: [_jsx(SecondsInput, { label: "Source in (s)", seconds: inS, onCommit: (v) => void commit([trimClip(clip.id, Math.max(0, Math.min(v, outS - 0.016)), outS)]) }), _jsx(SecondsInput, { label: "Source out (s)", seconds: outS, onCommit: (v) => void commit([trimClip(clip.id, inS, Math.min(srcDur, Math.max(v, inS + 0.016)))]) }), _jsx(Field, { label: "Track position", children: (ids) => (_jsxs("span", { ...ids, style: { fontSize: 13 }, children: ["clip ", clipIndex + 1, " \u00B7 ", clip.start.toFixed(2), "s\u2013", (clip.start + clip.duration).toFixed(2), "s"] })) })] }), _jsx(GatedRow, { cap: "edit.split", caps: caps, label: "Split clip" }), _jsx(GatedRow, { cap: "edit.slip", caps: caps, label: "Slip source range" }), _jsx(Field, { label: "Clip gain (dB)", children: () => (_jsx(SecondsInput, { label: "Gain", seconds: (model.corrections.audio[clip.id]?.gain ?? 0) / 1000, onCommit: (v) => void commit([setGain(clip.id, v)]) })) }), _jsx(MuteControl, { clipId: clip.id, model: model, commit: commit }), _jsx(Field, { label: "Alternate take", children: (ids) => (_jsx("select", { ...ids, className: "rk-input cr-select", value: take, "aria-label": "Alternate take source", onChange: (e) => setTake(e.target.value), children: model.sources.filter((s) => s.info.video).map((s) => _jsx("option", { value: s.info.id, children: s.name ?? s.info.id.slice(0, 8) }, s.info.id)) })) }), _jsx(SecondsInput, { label: "Take in (s)", seconds: takeIn, onCommit: setTakeIn }), _jsx(SecondsInput, { label: "Take out (s)", seconds: takeOut, onCommit: setTakeOut }), _jsx("button", { type: "button", className: "rk-button", onClick: () => void commit([swapTake(clip.id, take, takeIn, takeOut)]), children: "Use this take" }), _jsx(ColourInspector, { dir: dir, sourceId: clip.ref.clip.source, atMs: Math.round(scopeS * 1000) })] }));
+}
+/**
+ * Per-clip waveform over the source's decoded peaks. Rendered only when the
+ * engine advertises `media.waveform`; otherwise the gate reason shows.
+ */
+function Waveform({ dir, source, inS, outS, srcDurS, }) {
+    const [peaks, setPeaks] = useState(null);
+    const [err, setErr] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        setPeaks(null);
+        setErr(null);
+        engineCall("media.waveform", { dir, source, bars: 600 })
+            .then((r) => !cancelled && setPeaks(r.peaks ?? []))
+            .catch((e) => !cancelled && setErr(errorText(e)));
+        return () => {
+            cancelled = true;
+        };
+    }, [dir, source]);
+    if (err)
+        return _jsx("span", { className: "cr-muted", style: { fontSize: 12 }, children: err });
+    if (!peaks)
+        return _jsx("span", { className: "cr-muted", style: { fontSize: 12 }, children: "Loading peaks\u2026" });
+    const dur = srcDurS > 0 ? srcDurS : 1;
+    const bars = decimatePeaks(peaks, inS / dur, outS / dur, 96);
+    return (_jsx("div", { role: "img", "aria-label": "Clip waveform", style: { display: "flex", height: 32, alignItems: "flex-end", gap: 1 }, children: bars.map((p, i) => (_jsx("div", { style: {
+                width: 4,
+                borderRadius: 2,
+                height: `${Math.max(8, p * 100)}%`,
+                background: "var(--rk-accent)",
+                opacity: loudnessToOpacity(p),
+            } }, i))) }));
+}
+function AudioInspector({ clip, model, commit, caps, dir, }) {
+    if (clip.ref.kind !== "audio")
+        return null;
+    const c = clip.ref.clip;
+    const gainDb = c.gain / 1000;
+    const under = c.under;
+    const videoTargets = model.lanes
+        .filter((l) => l.kind === "video")
+        .flatMap((l) => l.clips);
+    const [duckDb, setDuckDb] = useState(12);
+    const { draft, setDraft, transaction } = useInspectorGestureDraft({
+        sourceValue: gainDb,
+        onPreview: () => undefined,
+        onCommit: (v) => void commit([setGain(clip.id, v)]),
+    });
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "fe-inspect", children: [_jsx(MuteControl, { clipId: clip.id, model: model, commit: commit }), _jsx(Field, { label: `Gain ${draft.toFixed(1)} dB`, children: (ids) => (_jsx(Input, { ...ids, type: "range", min: -60, max: 12, step: 0.5, value: draft, "aria-label": "Clip gain", className: "fe-inspect__range", onPointerDown: () => transaction.begin(), onChange: (e) => {
+                                const v = Number(e.target.value);
+                                setDraft(v);
+                                transaction.preview(v);
+                            }, onPointerUp: () => transaction.settle(), onKeyDown: (e) => {
+                                if (e.key === "ArrowLeft" || e.key === "ArrowRight") {
+                                    transaction.begin();
+                                    const v = draft + (e.key === "ArrowRight" ? 0.5 : -0.5);
+                                    setDraft(v);
+                                    transaction.preview(v);
+                                    transaction.settle();
+                                }
+                            } })) }), _jsx(Field, { label: "Audio underneath", children: (ids) => (_jsxs("select", { ...ids, className: "rk-input cr-select", value: under.mode, "aria-label": "Under audio mode", onChange: (e) => {
+                                const mode = e.target.value;
+                                const next = mode === "mute" ? { mode: "mute" }
+                                    : mode === "duck" ? { mode: "duck", amount: Math.round(duckDb * 1000) }
+                                        : { mode: "keep" };
+                                void commit([setUnder(clip.id, next)]);
+                            }, children: [_jsx("option", { value: "keep", children: "Keep" }), _jsx("option", { value: "duck", children: "Duck" }), _jsx("option", { value: "mute", children: "Mute" })] })) }), under.mode === "duck" && (_jsx(Field, { label: "Duck amount (dB)", children: (ids) => (_jsx(Input, { ...ids, inputMode: "decimal", value: duckDb, onChange: (e) => setDuckDb(Number(e.target.value) || 0), onBlur: () => void commit([setUnder(clip.id, { mode: "duck", amount: Math.round(duckDb * 1000) })]) })) })), _jsx(Field, { label: "Linked video clip", children: (ids) => (_jsxs("select", { ...ids, className: "rk-input cr-select", value: c.link ?? "", "aria-label": "Linked video clip", onChange: (e) => {
+                                const v = e.target.value;
+                                void commit(v ? [linkNarration(clip.id, v)] : [unlinkNarration(clip.id)]);
+                            }, children: [_jsx("option", { value: "", children: "None" }), videoTargets.map((v) => (_jsx("option", { value: v.id, children: v.label }, v.id)))] })) })] }), _jsxs("div", { className: "fe-inspect__row", children: [_jsx(SecondsInput, { label: "Trim in (s)", seconds: ticksToSeconds(c.trim_in), onCommit: (v) => void commit([
+                            trimAudioClip(clip.id, Math.max(0, Math.min(v, ticksToSeconds(c.trim_out) - 0.016)), ticksToSeconds(c.trim_out)),
+                        ]) }), _jsx(SecondsInput, { label: "Trim out (s)", seconds: ticksToSeconds(c.trim_out), onCommit: (v) => void commit([
+                            trimAudioClip(clip.id, ticksToSeconds(c.trim_in), Math.max(v, ticksToSeconds(c.trim_in) + 0.016)),
+                        ]) }), _jsx(Field, { label: "Waveform", children: () => (supports("media.waveform", caps) ? (_jsx(Waveform, { dir: dir, source: c.source, inS: ticksToSeconds(c.trim_in), outS: ticksToSeconds(c.trim_out), srcDurS: model.sourceDurationS.get(c.source) ?? ticksToSeconds(c.trim_out) })) : (_jsx("span", { className: "cr-muted", style: { fontSize: 12 }, children: unsupported("media.waveform").reason }))) })] })] }));
+}
+function TitleInspector({ clip, model, commit, caps, }) {
+    void caps;
+    if (clip.ref.kind !== "title")
+        return null;
+    const c = clip.ref.clip;
+    const [template, setTemplate] = useState(c.template);
+    const fadeIn = c.fade_in_frames ?? 0;
+    const fadeOut = c.fade_out_frames ?? 0;
+    const text = template.template === "lower_third" ? template.title : template.text;
+    return (_jsxs("div", { className: "fe-inspect", children: [_jsx(Field, { label: "Template", children: (ids) => (_jsxs("select", { ...ids, className: "rk-input cr-select", value: template.template, "aria-label": "Title template", onChange: (e) => {
+                        const kind = e.target.value;
+                        const next = kind === "lower_third"
+                            ? { template: "lower_third", title: text }
+                            : kind === "centered"
+                                ? { template: "centered", text }
+                                : { template: "caption", text };
+                        setTemplate(next);
+                        void commit([
+                            editTitle(clip.id, next, fadeIn, fadeOut),
+                        ]);
+                    }, children: [_jsx("option", { value: "lower_third", children: "Lower third" }), _jsx("option", { value: "centered", children: "Centered" }), _jsx("option", { value: "caption", children: "Caption" })] })) }), _jsx(Field, { label: "Text", children: (ids) => (_jsx(Input, { ...ids, value: text, maxLength: 160, "aria-label": "Title text", onChange: (e) => {
+                        const t = e.target.value;
+                        setTemplate(template.template === "lower_third"
+                            ? { ...template, title: t }
+                            : { ...template, text: t });
+                    }, onBlur: () => void commit([
+                        editTitle(clip.id, template, fadeIn, fadeOut),
+                    ]) })) }), template.template === "lower_third" && (_jsx(Field, { label: "Subtitle", children: (ids) => (_jsx(Input, { ...ids, value: template.subtitle ?? "", maxLength: 160, "aria-label": "Title subtitle", onChange: (e) => setTemplate({ ...template, subtitle: e.target.value || undefined }), onBlur: () => void commit([
+                        editTitle(clip.id, template, fadeIn, fadeOut),
+                    ]) })) })), _jsx(SecondsInput, { label: "Horizontal position (%)", seconds: (model.corrections.positions[clip.id]?.x ?? 500) / 10, onCommit: (v) => void commit([positionTitle(clip.id, v * 10, model.corrections.positions[clip.id]?.y ?? 500)]) }), _jsx(SecondsInput, { label: "Vertical position (%)", seconds: (model.corrections.positions[clip.id]?.y ?? 500) / 10, onCommit: (v) => void commit([positionTitle(clip.id, model.corrections.positions[clip.id]?.x ?? 500, v * 10)]) }), _jsxs("div", { className: "fe-inspect__row", children: [_jsx(SecondsInput, { label: "Start (s)", seconds: c.start_frame / model.fps, onCommit: (v) => void commit([trimTitle(clip.id, v * model.fps, c.frames)]) }), _jsx(SecondsInput, { label: "Duration (s)", seconds: c.frames / model.fps, onCommit: (v) => void commit([trimTitle(clip.id, c.start_frame, Math.max(1, v * model.fps))]) }), _jsx(SecondsInput, { label: "Fade in (s)", seconds: fadeIn / model.fps, onCommit: (v) => void commit([editTitle(clip.id, template, Math.max(0, v * model.fps), fadeOut)]) }), _jsx(SecondsInput, { label: "Fade out (s)", seconds: fadeOut / model.fps, onCommit: (v) => void commit([editTitle(clip.id, template, fadeIn, Math.max(0, v * model.fps))]) })] })] }));
+}
+function GatedRow({ cap, caps, label, }) {
+    if (supports(cap, caps))
+        return null;
+    const u = unsupported(cap);
+    return (_jsxs("div", { className: "rk-card", style: {
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+            gap: "var(--s2)",
+            padding: "var(--s2) var(--s3)",
+            borderStyle: "dashed",
+        }, children: [_jsx("span", { className: "cr-muted", style: { fontSize: 12 }, children: label }), _jsx("span", { className: "cr-muted", style: { fontSize: 10 }, title: u.reason, children: "Not supported by this engine" })] }));
+}
+function MuteControl({ clipId, model, commit }) {
+    return _jsx(Checkbox, { label: "Mute clip audio", checked: model.corrections.audio[clipId]?.muted ?? false, onChange: (checked) => void commit([setMute(clipId, checked)]) });
+}

package/dist/editor/Timeline.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Finished-edit timeline (docs/design/app-ui.md §3.4): ruler, playhead,
+ * selectable clips with trim/move/slip gestures in Edit mode, navigation-only
+ * in Review mode. All pointer geometry is transient — the canonical timeline
+ * updates only when `session.apply` commits a planned action and the host
+ * refreshes `project.show`.
+ *
+ * Lanes follow the spec order: Footage, Titles, Captions (timeline-mapped
+ * cues), Voice (waveform), Music, B-roll when a second video track exists.
+ * Clip thumbnails come from `media.thumbnail`, waveforms from
+ * `media.waveform` — both behind real engine data, never placeholders.
+ *
+ * Visual structure adapted from hyperframes' separable TimelineRuler pattern,
+ * retargeted at the design tokens. The clip menu is the shell's ContextMenu.
+ */
+import { type MenuItem } from "@rightkit/react-shell/react";
+import { type CaptionCue } from "../lib/media.js";
+import type { EditorClip, EditorModel } from "./model.js";
+import { type CapabilityReport } from "./capabilities.js";
+import type { EditSession } from "./adapter.js";
+export type PreviewSeek = (revisionCursor: number, timeS: number) => void;
+export declare function Timeline({ model, session, caps, busy, mode, cues, dir, playheadS, onPlayhead, onCommitted, onSeek, onSelect, onMenuAction, }: {
+    model: EditorModel;
+    session: EditSession;
+    caps: CapabilityReport | null;
+    busy: boolean;
+    /** `review` = navigate only (click/scrub to seek). `edit` = full gestures. */
+    mode: "review" | "edit";
+    /** Timeline-mapped caption cues (output timebase). */
+    cues: CaptionCue[];
+    /** Project dir for thumbnail/waveform calls. */
+    dir: string;
+    playheadS: number;
+    onPlayhead: (timeS: number) => void;
+    onCommitted: () => void;
+    onSeek: PreviewSeek;
+    onSelect: (ids: ReadonlySet<string>) => void;
+    onMenuAction?: (clip: EditorClip) => MenuItem[];
+}): import("react").JSX.Element;