@rightkit/video-ui 0.0.0-stage → 0.1.1

package/dist/editor/model.js

@@ -0,0 +1,87 @@
+/**
+ * Read model: folds `project.show` (`ProjectShow`) into flat editor lanes with
+ * second-based geometry. Rust owns canonical ticks/frames — this model only
+ * translates for display and gesture maths, and converts back on commit.
+ */
+import { fpsValue, ticksToSeconds, titleLabel, } from "../lib/project.js";
+export function buildEditorModel(show) {
+    const corrected = show;
+    const tl = corrected.timeline;
+    const fps = fpsValue(tl.fps);
+    const sourceName = (id) => show.sources.find((s) => s.info.id === id)?.name ?? id.slice(0, 8);
+    const placements = new Map(show.layout.map((p) => [p.clip, p]));
+    const lanes = [];
+    for (const track of tl.video_tracks) {
+        lanes.push({
+            id: track.id,
+            kind: "video",
+            label: track.id,
+            clips: track.clips.map((c, index) => {
+                const p = placements.get(c.id);
+                return {
+                    id: c.id,
+                    kind: "video",
+                    start: (p?.start_frame ?? 0) / fps,
+                    duration: (p?.frames ?? 0) / fps,
+                    label: sourceName(c.source),
+                    ref: { kind: "video", clip: c, trackId: track.id, index },
+                };
+            }),
+        });
+    }
+    for (const track of tl.audio_tracks) {
+        lanes.push({
+            id: track.id,
+            kind: "audio",
+            label: track.role === "narration" ? "Narr" : track.role,
+            clips: track.clips.map((c) => ({
+                id: c.id,
+                kind: "audio",
+                start: ticksToSeconds(c.start),
+                duration: ticksToSeconds(c.trim_out - c.trim_in),
+                label: sourceName(c.source),
+                link: c.link,
+                ref: { kind: "audio", clip: c, trackId: track.id, role: track.role },
+            })),
+        });
+    }
+    for (const track of tl.overlay_tracks) {
+        lanes.push({
+            id: track.id,
+            kind: "overlay",
+            label: track.id,
+            clips: track.clips.map((c) => ({
+                id: c.id,
+                kind: "overlay",
+                start: c.start_frame / fps,
+                duration: c.frames / fps,
+                label: titleLabel(c.template),
+                ref: { kind: "title", clip: c, trackId: track.id },
+            })),
+        });
+    }
+    return {
+        corrections: tl.corrections ?? { captions: {}, positions: {}, audio: {} },
+        captions: corrected.editor_captions ?? [],
+        sources: show.sources,
+        fps,
+        durationS: Math.max(show.summary.duration_ms / 1000, 0),
+        revisionCursor: show.revision.cursor,
+        revisionTotal: show.revision.total,
+        canUndo: show.revision.can_undo,
+        canRedo: show.revision.can_redo,
+        lanes,
+        clipCount: show.summary.video_clips + show.summary.audio_clips,
+        sourceDurationS: new Map(show.sources.map((s) => [s.info.id, ticksToSeconds(s.info.duration)])),
+    };
+}
+export function findClip(model, id) {
+    for (const lane of model.lanes) {
+        const hit = lane.clips.find((c) => c.id === id);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+// Compatibility alias for consumers importing the shorter name.
+export const buildModel = buildEditorModel;

package/dist/editor/transcript.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Source↔output time mapping for transcript-driven editing. Mirrors
+ * `clip_ranges` in crates/cutright-engine/src/media_cmd.rs: every placed clip
+ * range (video gapless accumulation, audio explicit starts) maps a source-ms
+ * window onto output seconds. Word-edge evidence stays in the engine's
+ * validated `transcript.show` payload — this module only maps numbers.
+ */
+import type { ProjectShow } from "../lib/project.js";
+/** One placed source range: source [inS,outS) lands at outOffS + (t - inS). */
+export type ClipRange = {
+    inS: number;
+    outS: number;
+    outOffS: number;
+};
+/** source id → placed ranges, in output order (same walk as the engine). */
+export declare function clipRanges(show: ProjectShow): Map<string, ClipRange[]>;
+/** Output seconds for a source timestamp in ms, or null when unplaced. */
+export declare function sourceToOutput(ranges: readonly ClipRange[], sourceMs: number): number | null;
+/**
+ * Output ranges (seconds) covered by a source window [startMs, endMs). A word
+ * or span can be placed more than once; every covered piece is returned so a
+ * ripple-delete excises all of them.
+ */
+export declare function coveredOutputRanges(ranges: readonly ClipRange[], startMs: number, endMs: number): {
+    startS: number;
+    endS: number;
+}[];

package/dist/editor/transcript.js

@@ -0,0 +1,59 @@
+import { fpsValue, ticksToSeconds } from "../lib/project.js";
+/** source id → placed ranges, in output order (same walk as the engine). */
+export function clipRanges(show) {
+    const tl = show.timeline;
+    const fps = fpsValue(tl.fps);
+    const ranges = new Map();
+    const push = (source, r) => {
+        const list = ranges.get(source) ?? [];
+        list.push(r);
+        ranges.set(source, list);
+    };
+    const placements = new Map(show.layout.map((p) => [p.clip, p]));
+    for (const track of tl.video_tracks) {
+        for (const clip of track.clips) {
+            const p = placements.get(clip.id);
+            const inS = ticksToSeconds(clip.source_in);
+            const outS = ticksToSeconds(clip.source_out);
+            if (!p || outS <= inS)
+                continue;
+            push(clip.source, { inS, outS, outOffS: p.start_frame / fps });
+        }
+    }
+    for (const track of tl.audio_tracks) {
+        for (const clip of track.clips) {
+            const inS = ticksToSeconds(clip.trim_in);
+            const outS = ticksToSeconds(clip.trim_out);
+            if (outS <= inS)
+                continue;
+            push(clip.source, { inS, outS, outOffS: ticksToSeconds(clip.start) });
+        }
+    }
+    for (const list of ranges.values())
+        list.sort((a, b) => a.outOffS - b.outOffS);
+    return ranges;
+}
+/** Output seconds for a source timestamp in ms, or null when unplaced. */
+export function sourceToOutput(ranges, sourceMs) {
+    const s = sourceMs / 1000;
+    const r = ranges.find((r) => s >= r.inS && s < r.outS);
+    return r ? r.outOffS + (s - r.inS) : null;
+}
+/**
+ * Output ranges (seconds) covered by a source window [startMs, endMs). A word
+ * or span can be placed more than once; every covered piece is returned so a
+ * ripple-delete excises all of them.
+ */
+export function coveredOutputRanges(ranges, startMs, endMs) {
+    const out = [];
+    const a = startMs / 1000;
+    const b = endMs / 1000;
+    for (const r of ranges) {
+        const lo = Math.max(a, r.inS);
+        const hi = Math.min(b, r.outS);
+        if (hi <= lo)
+            continue;
+        out.push({ startS: r.outOffS + (lo - r.inS), endS: r.outOffS + (hi - r.inS) });
+    }
+    return out;
+}

package/dist/editor/vendor/hyperframes/PlayheadIndicator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Flat playhead: 1px accent line over the track height plus a small rotated
+ * grab-handle head pinned sticky to the ruler row.
+ */
+export declare function PlayheadIndicator({ color, scrubbing, stickyHead, }: {
+    color?: string;
+    scrubbing?: boolean;
+    stickyHead?: boolean;
+}): import("react").JSX.Element;

package/dist/editor/vendor/hyperframes/PlayheadIndicator.js

@@ -0,0 +1,38 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Adapted from heygen-com/hyperframes (Apache-2.0),
+ * packages/studio @ 1d9b3673fade7511dd13cde5c3776a0e45e47ca3.
+ * Upstream file: packages/studio/src/player/components/PlayheadIndicator.tsx.
+ * Modifications: inlined PLAYHEAD_HEAD_W (from ./timelineLayout); retargeted
+ * the colour props at the host app shell tokens; removed the radial-gradient glow —
+ * the fused the host app/the host app shell is flat with no gradients.
+ * See src/editor/NOTICES.md for the licence text and provenance.
+ */
+const PLAYHEAD_HEAD_W = 14;
+const HEAD_H = 9;
+/**
+ * Flat playhead: 1px accent line over the track height plus a small rotated
+ * grab-handle head pinned sticky to the ruler row.
+ */
+export function PlayheadIndicator({ color = "var(--rk-accent)", scrubbing = false, stickyHead = true, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", className: "absolute bottom-0", style: {
+                    left: "50%",
+                    top: 1 + HEAD_H,
+                    width: 1,
+                    marginLeft: -0.5,
+                    background: color,
+                } }), _jsx("div", { className: stickyHead ? "sticky" : "absolute", style: {
+                    left: 0,
+                    top: stickyHead ? 0 : 1,
+                    height: stickyHead ? 0 : undefined,
+                }, children: _jsx("div", { style: {
+                        width: PLAYHEAD_HEAD_W,
+                        height: HEAD_H,
+                        borderRadius: 2,
+                        marginTop: 1,
+                        background: scrubbing ? color : "transparent",
+                        border: `1.5px solid ${color}`,
+                        boxSizing: "border-box",
+                        transform: "rotate(45deg)",
+                    } }) })] }));
+}

package/dist/editor/vendor/hyperframes/audioWaveformPeaks.d.ts

@@ -0,0 +1,7 @@
+/** Peak is 0–1 against the file's own maximum. Hotter peaks paint more opaque. */
+export declare function loudnessToOpacity(peak: number): number;
+/**
+ * Max-in-bucket over the trimmed peak window, one value per bar.
+ * A point sample drops a transient that sits between bar columns.
+ */
+export declare function decimatePeaks(peaks: readonly number[], startFraction: number, endFraction: number, barCount: number): number[];

package/dist/editor/vendor/hyperframes/audioWaveformPeaks.js

@@ -0,0 +1,47 @@
+/*
+ * Adapted from heygen-com/hyperframes (Apache-2.0),
+ * packages/studio @ 1d9b3673fade7511dd13cde5c3776a0e45e47ca3.
+ * Upstream file: player/components/audioWaveformPeaks.ts. Modifications: none — copied unmodified.
+ * See src/editor/NOTICES.md for the licence text and provenance.
+ */
+/** Quietest bar that still clears the timeline contrast gate on the 70% pill. */
+const LOUDNESS_OPACITY_FLOOR = 0.64;
+const LOUDNESS_OPACITY_SPAN = 1 - LOUDNESS_OPACITY_FLOOR;
+/** Peak is 0–1 against the file's own maximum. Hotter peaks paint more opaque. */
+export function loudnessToOpacity(peak) {
+    if (!Number.isFinite(peak))
+        return LOUDNESS_OPACITY_FLOOR;
+    const clamped = Math.min(1, Math.max(0, peak));
+    return LOUDNESS_OPACITY_FLOOR + LOUDNESS_OPACITY_SPAN * clamped;
+}
+/**
+ * Max-in-bucket over the trimmed peak window, one value per bar.
+ * A point sample drops a transient that sits between bar columns.
+ */
+export function decimatePeaks(peaks, startFraction, endFraction, barCount) {
+    if (barCount <= 0 || peaks.length === 0)
+        return [];
+    const startFractionClamped = Math.min(1, Math.max(0, startFraction));
+    const endFractionClamped = Math.min(1, Math.max(startFractionClamped, endFraction));
+    const start = Math.floor(startFractionClamped * peaks.length);
+    const endIndex = Math.ceil(endFractionClamped * peaks.length);
+    const end = Math.max(start + 1, Math.min(peaks.length, endIndex));
+    const span = end - start;
+    const bars = [];
+    for (let index = 0; index < barCount; index++) {
+        let from = start + Math.floor((index * span) / barCount);
+        let to = start + Math.floor(((index + 1) * span) / barCount);
+        if (to <= from) {
+            from = Math.min(from, end - 1);
+            to = from + 1;
+        }
+        let max = 0;
+        for (let cursor = from; cursor < to; cursor++) {
+            const value = peaks[cursor] ?? 0;
+            if (value > max)
+                max = value;
+        }
+        bars.push(max);
+    }
+    return bars;
+}

package/dist/editor/vendor/hyperframes/rulerGeometry.d.ts

@@ -0,0 +1,13 @@
+export type EditorTimeRange = {
+    start: number;
+    end: number;
+};
+export type EditorTimeDisplayMode = "time" | "frame";
+export declare function getTimelineMajorTickInterval(duration: number, pixelsPerSecond?: number, frameRate?: number): number;
+/** Seconds between neighbouring ruler lines (minor ticks when drawn, else major): the snap grid. */
+export declare function getTimelineGridStep(duration: number, pixelsPerSecond?: number, frameRate?: number): number;
+export declare function generateTicks(duration: number, pixelsPerSecond?: number, frameRate?: number, range?: EditorTimeRange): {
+    major: number[];
+    minor: number[];
+};
+export declare function formatTimelineTickLabel(time: number, duration: number, majorInterval: number): string;

package/dist/editor/vendor/hyperframes/rulerGeometry.js

@@ -0,0 +1,133 @@
+/*
+ * Adapted from heygen-com/hyperframes (Apache-2.0),
+ * packages/studio @ 1d9b3673fade7511dd13cde5c3776a0e45e47ca3.
+ * Upstream file: packages/studio/src/player/components/timelineRulerGeometry.ts.
+ * Modifications: inlined formatTime/secondsToFrame from ../lib/time; replaced
+ * STUDIO_PREVIEW_FPS with an explicit frameRate parameter; replaced
+ * TimelineTimeDisplayMode/TimelineTimeRange imports with local types;
+ * removed rulerFrameRate() (the display-mode branch is owned by the caller).
+ * See src/editor/NOTICES.md for the licence text and provenance.
+ */
+function formatTime(time) {
+    if (!Number.isFinite(time) || time < 0)
+        return "00:00";
+    const mins = Math.floor(time / 60);
+    const secs = Math.floor(time % 60);
+    return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+}
+// fallow-ignore-next-line complexity
+export function getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate) {
+    const zoomIntervals = [
+        0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600,
+    ];
+    let interval;
+    if (Number.isFinite(pixelsPerSecond) && (pixelsPerSecond ?? 0) > 0) {
+        const targetMajorPx = 88;
+        interval =
+            zoomIntervals.find((candidate) => candidate * (pixelsPerSecond ?? 0) >= targetMajorPx) ??
+                3600;
+    }
+    else {
+        const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
+        const target = duration / 6;
+        interval = durationIntervals.find((candidate) => candidate >= target) ?? 60;
+    }
+    if (Number.isFinite(frameRate) && (frameRate ?? 0) > 0) {
+        const fps = frameRate ?? 0;
+        return Math.max(1, Math.ceil(interval * fps - 1e-6)) / fps;
+    }
+    return interval;
+}
+// fallow-ignore-next-line complexity
+function getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate) {
+    const pps = Number.isFinite(pixelsPerSecond) ? (pixelsPerSecond ?? 0) : 0;
+    if (pps <= 0)
+        return 4;
+    const fps = Number.isFinite(frameRate) ? (frameRate ?? 0) : 0;
+    const majorFrames = fps > 0 ? Math.round(majorInterval * fps) : 0;
+    const candidates = fps > 0 ? [4, 5, 3, 2] : [4, 2];
+    for (const parts of candidates) {
+        if (fps > 0 && majorFrames % parts !== 0)
+            continue;
+        if ((majorInterval / parts) * pps >= 8)
+            return parts;
+    }
+    return 0;
+}
+function roundTickValue(time) {
+    return Math.round(time * 1e6) / 1e6;
+}
+function isSupportedTickDuration(duration) {
+    return duration > 0 && Number.isFinite(duration) && duration <= 14400;
+}
+function getTickRange(duration, range) {
+    return {
+        start: Math.max(0, range?.start ?? 0),
+        end: Math.min(duration, range?.end ?? duration),
+    };
+}
+function appendMinorTicks(minor, majorTime, minorInterval, subdivisions, range, maxTicks, majorCount) {
+    for (let part = 1; part < subdivisions && majorCount + minor.length < maxTicks; part++) {
+        const time = majorTime + part * minorInterval;
+        if (time >= range.start - 0.001 && time <= range.end + 0.001) {
+            minor.push(roundTickValue(time));
+        }
+    }
+}
+function tickSpacing(duration, pixelsPerSecond, frameRate) {
+    const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
+    const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
+    return { majorInterval, subdivisions };
+}
+/** Seconds between neighbouring ruler lines (minor ticks when drawn, else major): the snap grid. */
+export function getTimelineGridStep(duration, pixelsPerSecond, frameRate) {
+    if (!isSupportedTickDuration(duration))
+        return 0;
+    const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
+    return subdivisions > 0 ? majorInterval / subdivisions : majorInterval;
+}
+export function generateTicks(duration, pixelsPerSecond, frameRate, range) {
+    if (!isSupportedTickDuration(duration))
+        return { major: [], minor: [] };
+    const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
+    const minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
+    const major = [];
+    const minor = [];
+    const maxTicks = 2000;
+    const tickRange = getTickRange(duration, range);
+    const firstMajorIndex = Math.max(0, Math.floor(tickRange.start / majorInterval));
+    for (let index = firstMajorIndex; major.length < maxTicks; index++) {
+        const time = index * majorInterval;
+        if (time > tickRange.end + 0.001)
+            break;
+        if (time >= tickRange.start - 0.001)
+            major.push(roundTickValue(time));
+        appendMinorTicks(minor, time, minorInterval, subdivisions, tickRange, maxTicks, major.length);
+    }
+    return { major, minor };
+}
+export function formatTimelineTickLabel(time, duration, majorInterval) {
+    if (!Number.isFinite(time))
+        return "00:00";
+    const safeTime = Math.max(0, time);
+    if (majorInterval < 0.1) {
+        const totalHundredths = Math.round(safeTime * 100);
+        const wholeSeconds = Math.floor(totalHundredths / 100);
+        const hundredth = totalHundredths % 100;
+        return `${formatTime(wholeSeconds)}.${hundredth.toString().padStart(2, "0")}`;
+    }
+    if (majorInterval < 1) {
+        const totalTenths = Math.round(safeTime * 10);
+        const wholeSeconds = Math.floor(totalTenths / 10);
+        const tenth = totalTenths % 10;
+        return `${formatTime(wholeSeconds)}.${tenth}`;
+    }
+    if (duration >= 3600 || safeTime >= 3600) {
+        const totalSeconds = Math.floor(safeTime);
+        const hours = Math.floor(totalSeconds / 3600);
+        const minutes = Math.floor((totalSeconds % 3600) / 60);
+        const seconds = totalSeconds % 60;
+        return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
+    }
+    return formatTime(safeTime);
+}

package/dist/editor/vendor/hyperframes/useInspectorGestureTransaction.d.ts

@@ -0,0 +1,33 @@
+/** One owner for continuous inspector edits: preview freely, persist once. */
+export declare function useInspectorGestureTransaction<T>({ sourceValue, onPreview, onCommit, }: {
+    sourceValue: T;
+    onPreview: (value: T) => void;
+    onCommit: (value: T) => void | Promise<unknown>;
+}): {
+    begin: () => void;
+    preview: (value: T) => void;
+    settle: () => void;
+    cancel: () => void;
+    activeRef: import("react").RefObject<{
+        before: T;
+        latest: T;
+    } | null>;
+};
+export declare function useInspectorGestureDraft<T>({ sourceValue, onPreview, onCommit, }: {
+    sourceValue: T;
+    onPreview: (value: T) => void;
+    onCommit: (value: T) => void | Promise<unknown>;
+}): {
+    draft: T;
+    setDraft: import("react").Dispatch<import("react").SetStateAction<T>>;
+    transaction: {
+        begin: () => void;
+        preview: (value: T) => void;
+        settle: () => void;
+        cancel: () => void;
+        activeRef: import("react").RefObject<{
+            before: T;
+            latest: T;
+        } | null>;
+    };
+};

package/dist/editor/vendor/hyperframes/useInspectorGestureTransaction.js

@@ -0,0 +1,126 @@
+/*
+ * Adapted from heygen-com/hyperframes (Apache-2.0),
+ * packages/studio @ 1d9b3673fade7511dd13cde5c3776a0e45e47ca3.
+ * Upstream file: components/editor/useInspectorGestureTransaction.ts. Modifications: none — copied unmodified.
+ * See src/editor/NOTICES.md for the licence text and provenance.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+function isPromiseCommit(result) {
+    return Boolean(result && typeof result.then === "function");
+}
+/** One owner for continuous inspector edits: preview freely, persist once. */
+export function useInspectorGestureTransaction({ sourceValue, onPreview, onCommit, }) {
+    const sourceRef = useRef(sourceValue);
+    const activeRef = useRef(null);
+    const previewRef = useRef(onPreview);
+    const commitRef = useRef(onCommit);
+    const generationRef = useRef(0);
+    const pendingRef = useRef(null);
+    const awaitingSourceAckRef = useRef(null);
+    const lastSourceValueRef = useRef(sourceValue);
+    if (!Object.is(lastSourceValueRef.current, sourceValue)) {
+        lastSourceValueRef.current = sourceValue;
+        const matchesSourceAck = Object.is(awaitingSourceAckRef.current?.value, sourceValue);
+        const matchesOptimisticValue = (activeRef.current && Object.is(activeRef.current.latest, sourceValue)) ||
+            (pendingRef.current && Object.is(pendingRef.current.latest, sourceValue)) ||
+            matchesSourceAck;
+        if (matchesSourceAck)
+            awaitingSourceAckRef.current = null;
+        if (!matchesOptimisticValue) {
+            generationRef.current += 1;
+            activeRef.current = null;
+            pendingRef.current = null;
+            awaitingSourceAckRef.current = null;
+            sourceRef.current = sourceValue;
+        }
+        else {
+            sourceRef.current = sourceValue;
+        }
+    }
+    previewRef.current = onPreview;
+    commitRef.current = onCommit;
+    const begin = useCallback(() => {
+        if (!activeRef.current) {
+            generationRef.current += 1;
+            activeRef.current = { before: sourceRef.current, latest: sourceRef.current };
+        }
+    }, []);
+    const preview = useCallback((value) => {
+        if (!activeRef.current) {
+            generationRef.current += 1;
+            activeRef.current = { before: sourceRef.current, latest: sourceRef.current };
+        }
+        activeRef.current.latest = value;
+        previewRef.current(value);
+    }, []);
+    const rollbackCommit = useCallback((active, generation) => {
+        if (generation !== generationRef.current)
+            return;
+        pendingRef.current = null;
+        if (awaitingSourceAckRef.current?.generation === generation) {
+            awaitingSourceAckRef.current = null;
+        }
+        sourceRef.current = active.before;
+        previewRef.current(active.before);
+    }, []);
+    const settle = useCallback(() => {
+        const active = activeRef.current;
+        activeRef.current = null;
+        if (active && !Object.is(active.before, active.latest)) {
+            const generation = ++generationRef.current;
+            sourceRef.current = active.latest;
+            pendingRef.current = active;
+            awaitingSourceAckRef.current = { generation, value: active.latest };
+            try {
+                const result = commitRef.current(active.latest);
+                if (isPromiseCommit(result)) {
+                    void result.then(() => {
+                        if (generation === generationRef.current)
+                            pendingRef.current = null;
+                    }, () => rollbackCommit(active, generation));
+                }
+                else if (generation === generationRef.current) {
+                    pendingRef.current = null;
+                    // Synchronous inspector consumers historically restore their preview
+                    // after persisting (color pickers close, curves release the pointer).
+                    // Async source mutations keep the optimistic preview until the write
+                    // resolves so they do not flash back to the baseline while pending.
+                    previewRef.current(active.before);
+                }
+            }
+            catch {
+                rollbackCommit(active, generation);
+            }
+        }
+    }, [rollbackCommit]);
+    const cancel = useCallback(() => {
+        generationRef.current += 1;
+        const active = activeRef.current;
+        activeRef.current = null;
+        if (active && !Object.is(active.before, active.latest)) {
+            sourceRef.current = active.before;
+            previewRef.current(active.before);
+        }
+    }, []);
+    useEffect(() => cancel, [cancel]);
+    return { begin, preview, settle, cancel, activeRef };
+}
+export function useInspectorGestureDraft({ sourceValue, onPreview, onCommit, }) {
+    const [draft, setDraft] = useState(sourceValue);
+    const transaction = useInspectorGestureTransaction({
+        sourceValue,
+        onPreview: (next) => {
+            setDraft(next);
+            onPreview(next);
+        },
+        onCommit: (next) => {
+            setDraft(next);
+            return onCommit(next);
+        },
+    });
+    useEffect(() => {
+        if (!transaction.activeRef.current)
+            setDraft(sourceValue);
+    }, [sourceValue, transaction.activeRef]);
+    return { draft, setDraft, transaction };
+}

package/dist/env.d.ts

@@ -0,0 +1,66 @@
+/// <reference types="vite/client" />
+
+declare module "*.css";
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}
+declare module "*.png" {
+  const src: string;
+  export default src;
+}
+declare module "*.txt?raw" {
+  const text: string;
+  export default text;
+}
+declare module "*.tsv?raw" {
+  const text: string;
+  export default text;
+}
+declare module "*?url" {
+  const src: string;
+  export default src;
+}
+
+// Build-time switches a host may define (Vite `define`); every read is typeof-guarded.
+declare const __RIGHTKIT_QA__: boolean | undefined;
+declare const __RIGHTKIT_DEMO__: boolean | undefined;
+declare const __RIGHTKIT_MOCK__: boolean | undefined;
+declare const __APP_VERSION__: string | undefined;
+
+interface Window {
+  /** UI QA only: the data source a QA shell selects. */
+  __RIGHTKIT_QA_DATA_SOURCE__?: "engine";
+}
+
+declare module "@rightkit-host/legal/legal-manifest.json" {
+  const manifest: {
+    documents: Array<{ id: string; role: string; title: string; publicUrl: string; version?: string; sha256?: string; [key: string]: unknown }>;
+    [key: string]: unknown;
+  };
+  export default manifest;
+}
+declare module "@rightkit-host/legal/legal-manifest.json?raw" {
+  const text: string;
+  export default text;
+}
+declare module "@rightkit-host/src/generated/legal-contract.json" {
+  const contract: { acceptanceVersion: string; materialSha256: string; [key: string]: unknown };
+  export default contract;
+}
+declare module "@rightkit-host/package.json" {
+  export const version: string;
+  const pkg: { name: string; version: string };
+  export default pkg;
+}
+declare module "@rightkit-host/legal/*.md?raw" {
+  const text: string;
+  export default text;
+}
+
+declare module "virtual:rightkit-legal" {
+  export const LEGAL_DOCUMENTS: readonly { title: string; content: string }[];
+  export const LEGAL_VERSION: string;
+  export const LEGAL_DOCUMENTS_HASH: string;
+  export const LEGAL_RECEIPT_DOCUMENTS: readonly { id: string; role: string; version: string; sha256: string; treatment: string; material: boolean }[];
+}

package/dist/hooks/useEngine.d.ts

@@ -0,0 +1,10 @@
+import { type DoctorReport, type EngineStatus } from "../lib/engine.js";
+export declare function subscribeDoctor(listener: () => void): () => void;
+export declare const getDoctor: () => DoctorReport | null;
+/** Polls `engine_status` and loads the doctor report once the engine is ready. */
+export declare function useEngine(): {
+    status: EngineStatus | null;
+    doctor: DoctorReport | null;
+    doctorError: string | null;
+    statusError: string | null;
+};