@pixerate/editor 0.159.0 → 0.161.0

package/dist/video-editor/lut.d.cts

@@ -28,11 +28,21 @@ export declare function videoLutToCube(lut: VideoLut): string;
  * from the four corners of the one it falls in. Greys stay on the diagonal, unlike trilinear.
  */
 export declare function applyVideoLut(lut: VideoLut, rgb: readonly [number, number, number], out?: [number, number, number]): [number, number, number];
-/** Runs RGBA pixels (0–255, as `ImageData` has them) through a LUT in place, mixed with the originals by `strength` (0–1). Transparent pixels are left alone. */
+/**
+ * How much a colour (0–1 sRGB) looks like skin, 0–1: its chroma (BT.601 Cb / Cr) against the
+ * skin cluster, which holds for every complexion because skin differs mostly in lightness, not in
+ * hue. Full weight inside the cluster, falling smoothly to 0 just outside it, and faded out near
+ * black and white, where chroma means little. Used by `preserveSkinTones`.
+ */
+export declare function videoSkinToneWeight(r: number, g: number, b: number): number;
+/**
+ * Runs RGBA pixels (0–255, e.g. `ImageData.data`) through a LUT in place, mixed by `strength`.
+ * With `preserveSkinTones` (0–1) the mix is held back by that much on skin (see `videoSkinToneWeight`).
+ */
 export declare function applyVideoLutToPixels(lut: VideoLut, data: {
     length: number;
     [i: number]: number;
-}, strength?: number): void;
+}, strength?: number, preserveSkinTones?: number): void;
 /**
  * An SVG approximation of a LUT for SVG frames, which have no 3D tables: per-channel curves taken
  * along the LUT's grey axis (`feComponentTransfer` tables), then the colour matrix that best fits

package/dist/video-editor/lut.d.ts

@@ -28,11 +28,21 @@ export declare function videoLutToCube(lut: VideoLut): string;
  * from the four corners of the one it falls in. Greys stay on the diagonal, unlike trilinear.
  */
 export declare function applyVideoLut(lut: VideoLut, rgb: readonly [number, number, number], out?: [number, number, number]): [number, number, number];
-/** Runs RGBA pixels (0–255, as `ImageData` has them) through a LUT in place, mixed with the originals by `strength` (0–1). Transparent pixels are left alone. */
+/**
+ * How much a colour (0–1 sRGB) looks like skin, 0–1: its chroma (BT.601 Cb / Cr) against the
+ * skin cluster, which holds for every complexion because skin differs mostly in lightness, not in
+ * hue. Full weight inside the cluster, falling smoothly to 0 just outside it, and faded out near
+ * black and white, where chroma means little. Used by `preserveSkinTones`.
+ */
+export declare function videoSkinToneWeight(r: number, g: number, b: number): number;
+/**
+ * Runs RGBA pixels (0–255, e.g. `ImageData.data`) through a LUT in place, mixed by `strength`.
+ * With `preserveSkinTones` (0–1) the mix is held back by that much on skin (see `videoSkinToneWeight`).
+ */
 export declare function applyVideoLutToPixels(lut: VideoLut, data: {
     length: number;
     [i: number]: number;
-}, strength?: number): void;
+}, strength?: number, preserveSkinTones?: number): void;
 /**
  * An SVG approximation of a LUT for SVG frames, which have no 3D tables: per-channel curves taken
  * along the LUT's grey axis (`feComponentTransfer` tables), then the colour matrix that best fits

package/dist/video-editor/mask.d.cts

@@ -0,0 +1,48 @@
+import type { VideoClipMask } from './types.cjs';
+/**
+ * Clip masks as plain geometry: every shape becomes a polygon in frame pixels (curves as short
+ * straight segments), so the canvas preview, SVG frames and agents all cut the same shape. The
+ * polygon is in the layer's unrotated frame space: renderers turn it with the layer.
+ */
+/** A rect in frame pixels (the layer's placed picture). */
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A mask resolved for one layer: its outline in frame pixels, soft edge and side. */
+export interface VideoLayerMask {
+    /** The outline, `[x, y]` frame pixels before the layer's rotation. */
+    points: [number, number][];
+    /** Soft edge width in frame pixels (0 = hard). */
+    feather: number;
+    /** Show the outside instead of the inside. */
+    inverted: boolean;
+}
+/** The defaults a mask's missing fields take. */
+export declare const VIDEO_MASK_DEFAULTS: {
+    readonly x: 0.5;
+    readonly y: 0.5;
+    readonly width: 0.5;
+    readonly height: 0.5;
+    readonly rotation: 0;
+    readonly feather: 0;
+    readonly cornerRadius: 0;
+};
+/** A mask with its defaults filled in and values clamped (corner radius 0–1, sizes and feather at least 0). */
+export declare function normalizeVideoClipMask(mask: VideoClipMask): Required<Omit<VideoClipMask, 'points' | 'inverted'>> & Pick<VideoClipMask, 'points'> & {
+    inverted: boolean;
+};
+/** The mask's outline in frame pixels for a layer placed at `rect` (before the layer's own rotation). */
+export declare function videoMaskPolygon(mask: VideoClipMask, rect: Rect): [number, number][];
+/** A mask resolved for a layer placed at `rect`. */
+export declare function videoLayerMask(mask: VideoClipMask, rect: Rect): VideoLayerMask;
+/** An SVG path (`d`) of a resolved mask's outline. */
+export declare function videoMaskSvgPath(mask: VideoLayerMask): string;
+/**
+ * How much of a point (frame pixels) a resolved mask shows, 0 or 1 (no feather): an even-odd test
+ * against its outline. For agents and tests reading what a mask keeps.
+ */
+export declare function videoMaskContains(mask: VideoLayerMask, x: number, y: number): boolean;
+export {};

package/dist/video-editor/mask.d.ts

@@ -0,0 +1,48 @@
+import type { VideoClipMask } from './types.js';
+/**
+ * Clip masks as plain geometry: every shape becomes a polygon in frame pixels (curves as short
+ * straight segments), so the canvas preview, SVG frames and agents all cut the same shape. The
+ * polygon is in the layer's unrotated frame space: renderers turn it with the layer.
+ */
+/** A rect in frame pixels (the layer's placed picture). */
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A mask resolved for one layer: its outline in frame pixels, soft edge and side. */
+export interface VideoLayerMask {
+    /** The outline, `[x, y]` frame pixels before the layer's rotation. */
+    points: [number, number][];
+    /** Soft edge width in frame pixels (0 = hard). */
+    feather: number;
+    /** Show the outside instead of the inside. */
+    inverted: boolean;
+}
+/** The defaults a mask's missing fields take. */
+export declare const VIDEO_MASK_DEFAULTS: {
+    readonly x: 0.5;
+    readonly y: 0.5;
+    readonly width: 0.5;
+    readonly height: 0.5;
+    readonly rotation: 0;
+    readonly feather: 0;
+    readonly cornerRadius: 0;
+};
+/** A mask with its defaults filled in and values clamped (corner radius 0–1, sizes and feather at least 0). */
+export declare function normalizeVideoClipMask(mask: VideoClipMask): Required<Omit<VideoClipMask, 'points' | 'inverted'>> & Pick<VideoClipMask, 'points'> & {
+    inverted: boolean;
+};
+/** The mask's outline in frame pixels for a layer placed at `rect` (before the layer's own rotation). */
+export declare function videoMaskPolygon(mask: VideoClipMask, rect: Rect): [number, number][];
+/** A mask resolved for a layer placed at `rect`. */
+export declare function videoLayerMask(mask: VideoClipMask, rect: Rect): VideoLayerMask;
+/** An SVG path (`d`) of a resolved mask's outline. */
+export declare function videoMaskSvgPath(mask: VideoLayerMask): string;
+/**
+ * How much of a point (frame pixels) a resolved mask shows, 0 or 1 (no feather): an even-odd test
+ * against its outline. For agents and tests reading what a mask keeps.
+ */
+export declare function videoMaskContains(mask: VideoLayerMask, x: number, y: number): boolean;
+export {};

package/dist/video-editor/mix.d.cts

@@ -0,0 +1,107 @@
+import { type VideoAudioPeaks } from './audio.cjs';
+import type { VideoKey } from './keyframes.cjs';
+import { type VideoTimelineWord } from './transcript.cjs';
+import type { VideoClip } from './types.cjs';
+/**
+ * The sound mix as data: loudness measured the way streaming services and broadcasters measure it
+ * (ITU-R BS.1770, gated, in LUFS), the gain that brings a clip to a target, ducking keyframes that
+ * dip music under speech, and the beats of a music track. Pure functions over samples, peaks and
+ * ranges, so an agent and the inspector get the same numbers, and tests need no decoder.
+ */
+/** Length of one loudness hop (ms): a gating block is four hops (400 ms) moving one hop at a time. */
+export declare const VIDEO_LOUDNESS_HOP = 100;
+/**
+ * The K-weighted mean square of decoded audio per 100 ms hop, channels summed (each weighted 1, as
+ * for left, right and centre). What `VideoAudioPeaks.loudness` holds.
+ */
+export declare function videoLoudnessEnergy(channels: readonly Float32Array[], sampleRate: number): {
+    hop: number;
+    energy: Float32Array;
+};
+/**
+ * Integrated loudness (LUFS) of hop energies between two source times (ms): 400 ms blocks every
+ * 100 ms, gated at -70 LUFS and then 10 LU below the ungated level, as BS.1770-4 does. A stretch
+ * shorter than a block is measured as one block. `null` when everything is gated out (silence).
+ */
+export declare function videoLoudnessOf(loudness: {
+    hop: number;
+    energy: Float32Array;
+}, from?: number, to?: number): number | null;
+/** Integrated loudness (LUFS) of decoded audio. `null` for silence. */
+export declare function measureVideoLoudness(channels: readonly Float32Array[], sampleRate: number): number | null;
+/** Integrated loudness (LUFS) of a stretch of an asset's sound from its peaks, `null` for silence; throws for peaks without loudness. */
+export declare function videoAudioLoudness(peaks: VideoAudioPeaks, from?: number, to?: number): number | null;
+export interface VideoLoudnessGainOptions {
+    /** Most gain allowed (linear, default 4, the highest clip volume). */
+    maxGain?: number;
+    /** The sound's sample peak (dBFS); with it the gain is held so the peak stays under `ceiling`. */
+    peakDb?: number;
+    /** Highest peak allowed after the gain (dBFS, default -1). */
+    ceiling?: number;
+}
+/**
+ * The linear gain that brings a sound measured at `measured` LUFS to `target` LUFS (default -14,
+ * what streaming services play at), capped by `maxGain` and by the peak ceiling when `peakDb` is
+ * known. `limitedBy` says when a cap kept it short of the target.
+ */
+export declare function videoLoudnessGain(measured: number, target?: number, options?: VideoLoudnessGainOptions): {
+    gain: number;
+    gainDb: number;
+    limitedBy?: 'max-gain' | 'peak';
+};
+/** Timeline stretches where words are spoken, merged across gaps shorter than `mergeGap` ms (default 500). */
+export declare function videoSpeechRanges(words: readonly Pick<VideoTimelineWord, 'start' | 'end'>[], mergeGap?: number): {
+    from: number;
+    to: number;
+}[];
+export interface VideoDuckingOptions {
+    /** How far to dip under speech, in dB (default -14; -12 to -18 is usual). */
+    duckDb?: number;
+    /** How long the dip takes to come in before speech starts (ms, default 200). */
+    attack?: number;
+    /** How long the music takes to come back after speech ends (ms, default 400). */
+    release?: number;
+    /** Speech gaps shorter than this stay ducked (ms, default 600, never less than attack + release). */
+    mergeGap?: number;
+    /** The level the music sits at between dips (linear gain, default the clip's own volume or 1). */
+    base?: number;
+}
+/**
+ * Volume keyframes (clip time) that dip a music clip under speech: for each stretch of speech that
+ * overlaps it, the level eases down over `attack` ms before the speech, holds at `duckDb` and eases
+ * back over `release` ms after it. Stretches closer than the merge gap stay ducked between them.
+ * `[]` when no speech overlaps the clip. Keys are on whole ms and in time order.
+ */
+export declare function videoDuckingKeys(clip: Pick<VideoClip, 'start' | 'duration'>, speech: readonly {
+    from: number;
+    to: number;
+}[], options?: VideoDuckingOptions): VideoKey[];
+export interface VideoBeatOptions {
+    /** Resolution of the onset scan (ms, default 10). */
+    resolution?: number;
+    /** Closest two onsets may be (ms, default 250). */
+    minInterval?: number;
+    /** How far above the local average an onset must rise, in standard deviations (default 1.5). */
+    sensitivity?: number;
+    /** Slowest and fastest tempo to consider (BPM, default 60 and 200). */
+    minBpm?: number;
+    maxBpm?: number;
+}
+export interface VideoBeats {
+    /** Times of sharp rises in level (ms, in the clock asked in): hits, plucks, kicks. */
+    onsets: number[];
+    /** The tempo the onsets repeat at, or `null` when they do not repeat. */
+    bpm: number | null;
+    /** A steady beat grid at `bpm`, through the strongest onsets (ms); empty without a tempo. */
+    beats: number[];
+}
+/**
+ * The beats of a stretch of sound (source ms) from its peaks: an onset envelope (rises of the peak
+ * level), onsets where it rises well above its local average, the tempo from the envelope's
+ * autocorrelation and a beat grid at that tempo, phased to fit the onsets best. Works on peaks, so
+ * it is quick and needs no decoding beyond what waveforms already have; it finds the pulse of
+ * percussive music well and of ambient music poorly.
+ */
+export declare function findVideoAudioBeats(peaks: VideoAudioPeaks, from: number, to: number, options?: VideoBeatOptions): VideoBeats;
+/** The nearest time in a sorted list to `time`, or `null` when none is within `tolerance` ms. */
+export declare function nearestVideoBeat(beats: readonly number[], time: number, tolerance?: number): number | null;

package/dist/video-editor/mix.d.ts

@@ -0,0 +1,107 @@
+import { type VideoAudioPeaks } from './audio.js';
+import type { VideoKey } from './keyframes.js';
+import { type VideoTimelineWord } from './transcript.js';
+import type { VideoClip } from './types.js';
+/**
+ * The sound mix as data: loudness measured the way streaming services and broadcasters measure it
+ * (ITU-R BS.1770, gated, in LUFS), the gain that brings a clip to a target, ducking keyframes that
+ * dip music under speech, and the beats of a music track. Pure functions over samples, peaks and
+ * ranges, so an agent and the inspector get the same numbers, and tests need no decoder.
+ */
+/** Length of one loudness hop (ms): a gating block is four hops (400 ms) moving one hop at a time. */
+export declare const VIDEO_LOUDNESS_HOP = 100;
+/**
+ * The K-weighted mean square of decoded audio per 100 ms hop, channels summed (each weighted 1, as
+ * for left, right and centre). What `VideoAudioPeaks.loudness` holds.
+ */
+export declare function videoLoudnessEnergy(channels: readonly Float32Array[], sampleRate: number): {
+    hop: number;
+    energy: Float32Array;
+};
+/**
+ * Integrated loudness (LUFS) of hop energies between two source times (ms): 400 ms blocks every
+ * 100 ms, gated at -70 LUFS and then 10 LU below the ungated level, as BS.1770-4 does. A stretch
+ * shorter than a block is measured as one block. `null` when everything is gated out (silence).
+ */
+export declare function videoLoudnessOf(loudness: {
+    hop: number;
+    energy: Float32Array;
+}, from?: number, to?: number): number | null;
+/** Integrated loudness (LUFS) of decoded audio. `null` for silence. */
+export declare function measureVideoLoudness(channels: readonly Float32Array[], sampleRate: number): number | null;
+/** Integrated loudness (LUFS) of a stretch of an asset's sound from its peaks, `null` for silence; throws for peaks without loudness. */
+export declare function videoAudioLoudness(peaks: VideoAudioPeaks, from?: number, to?: number): number | null;
+export interface VideoLoudnessGainOptions {
+    /** Most gain allowed (linear, default 4, the highest clip volume). */
+    maxGain?: number;
+    /** The sound's sample peak (dBFS); with it the gain is held so the peak stays under `ceiling`. */
+    peakDb?: number;
+    /** Highest peak allowed after the gain (dBFS, default -1). */
+    ceiling?: number;
+}
+/**
+ * The linear gain that brings a sound measured at `measured` LUFS to `target` LUFS (default -14,
+ * what streaming services play at), capped by `maxGain` and by the peak ceiling when `peakDb` is
+ * known. `limitedBy` says when a cap kept it short of the target.
+ */
+export declare function videoLoudnessGain(measured: number, target?: number, options?: VideoLoudnessGainOptions): {
+    gain: number;
+    gainDb: number;
+    limitedBy?: 'max-gain' | 'peak';
+};
+/** Timeline stretches where words are spoken, merged across gaps shorter than `mergeGap` ms (default 500). */
+export declare function videoSpeechRanges(words: readonly Pick<VideoTimelineWord, 'start' | 'end'>[], mergeGap?: number): {
+    from: number;
+    to: number;
+}[];
+export interface VideoDuckingOptions {
+    /** How far to dip under speech, in dB (default -14; -12 to -18 is usual). */
+    duckDb?: number;
+    /** How long the dip takes to come in before speech starts (ms, default 200). */
+    attack?: number;
+    /** How long the music takes to come back after speech ends (ms, default 400). */
+    release?: number;
+    /** Speech gaps shorter than this stay ducked (ms, default 600, never less than attack + release). */
+    mergeGap?: number;
+    /** The level the music sits at between dips (linear gain, default the clip's own volume or 1). */
+    base?: number;
+}
+/**
+ * Volume keyframes (clip time) that dip a music clip under speech: for each stretch of speech that
+ * overlaps it, the level eases down over `attack` ms before the speech, holds at `duckDb` and eases
+ * back over `release` ms after it. Stretches closer than the merge gap stay ducked between them.
+ * `[]` when no speech overlaps the clip. Keys are on whole ms and in time order.
+ */
+export declare function videoDuckingKeys(clip: Pick<VideoClip, 'start' | 'duration'>, speech: readonly {
+    from: number;
+    to: number;
+}[], options?: VideoDuckingOptions): VideoKey[];
+export interface VideoBeatOptions {
+    /** Resolution of the onset scan (ms, default 10). */
+    resolution?: number;
+    /** Closest two onsets may be (ms, default 250). */
+    minInterval?: number;
+    /** How far above the local average an onset must rise, in standard deviations (default 1.5). */
+    sensitivity?: number;
+    /** Slowest and fastest tempo to consider (BPM, default 60 and 200). */
+    minBpm?: number;
+    maxBpm?: number;
+}
+export interface VideoBeats {
+    /** Times of sharp rises in level (ms, in the clock asked in): hits, plucks, kicks. */
+    onsets: number[];
+    /** The tempo the onsets repeat at, or `null` when they do not repeat. */
+    bpm: number | null;
+    /** A steady beat grid at `bpm`, through the strongest onsets (ms); empty without a tempo. */
+    beats: number[];
+}
+/**
+ * The beats of a stretch of sound (source ms) from its peaks: an onset envelope (rises of the peak
+ * level), onsets where it rises well above its local average, the tempo from the envelope's
+ * autocorrelation and a beat grid at that tempo, phased to fit the onsets best. Works on peaks, so
+ * it is quick and needs no decoding beyond what waveforms already have; it finds the pulse of
+ * percussive music well and of ambient music poorly.
+ */
+export declare function findVideoAudioBeats(peaks: VideoAudioPeaks, from: number, to: number, options?: VideoBeatOptions): VideoBeats;
+/** The nearest time in a sorted list to `time`, or `null` when none is within `tolerance` ms. */
+export declare function nearestVideoBeat(beats: readonly number[], time: number, tolerance?: number): number | null;

package/dist/video-editor/music-tools.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Agent tools for music and the mix: beats of a music track and a plan that snaps cuts to them,
+ * ducking music under speech, and loudness measured and normalised the way streaming services
+ * measure it (LUFS). Skill: `pixerate-bgm-alignment`.
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { VideoEditorController } from './controller.cjs';
+export interface VideoMusicToolProviderOptions {
+    /** Provider id (unique per registry). Default `video-music`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** The project cannot be edited: write tools are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** The agent playback surface its calls are acted out on (default `video`). */
+    playbackSurface?: string;
+}
+/** The music and mix tools for a video editor (see the module comment). */
+export declare function createVideoMusicToolProvider(controller: VideoEditorController, options?: VideoMusicToolProviderOptions): AgentToolProvider;

package/dist/video-editor/music-tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agent tools for music and the mix: beats of a music track and a plan that snaps cuts to them,
+ * ducking music under speech, and loudness measured and normalised the way streaming services
+ * measure it (LUFS). Skill: `pixerate-bgm-alignment`.
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { VideoEditorController } from './controller.js';
+export interface VideoMusicToolProviderOptions {
+    /** Provider id (unique per registry). Default `video-music`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** The project cannot be edited: write tools are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** The agent playback surface its calls are acted out on (default `video`). */
+    playbackSurface?: string;
+}
+/** The music and mix tools for a video editor (see the module comment). */
+export declare function createVideoMusicToolProvider(controller: VideoEditorController, options?: VideoMusicToolProviderOptions): AgentToolProvider;

package/dist/video-editor/parse.d.cts

@@ -1,5 +1,5 @@
 import { type VideoAnimatable, type VideoKeyframes } from './keyframes.cjs';
-import { type VideoAsset, type VideoAssetProxy, type VideoClip, type VideoClipEffect, type VideoEffectRef, type VideoEffectValues, type VideoClipAnimation, type VideoGrade, type VideoGradeLut, type VideoMarker, type VideoProject, type VideoSequence, type VideoTrack, type VideoTranscriptWord, type VideoTransform, type VideoTransition } from './types.cjs';
+import { type VideoClipMask, type VideoAsset, type VideoAssetProxy, type VideoClip, type VideoClipEffect, type VideoEffectRef, type VideoEffectValues, type VideoClipAnimation, type VideoGrade, type VideoGradeLut, type VideoMarker, type VideoProject, type VideoSequence, type VideoTrack, type VideoTranscriptWord, type VideoTransform, type VideoTransition } from './types.cjs';
 /**
  * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in strictly increasing time (clip-relative
  * ms), each value within `range`.
@@ -19,6 +19,8 @@ export declare function parseVideoTimeRemap(v: unknown, speed: unknown, path: st
 export declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAnimation | undefined;
 export declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
 export declare function parseVideoGradeLut(v: unknown, path: string): VideoGradeLut | undefined;
+/** A clip mask `{ shape, x, y, width, height, rotation, feather, cornerRadius, inverted, points }` (see `VideoClipMask`). */
+export declare function parseVideoClipMask(v: unknown, path: string): VideoClipMask | undefined;
 export declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
 /**
  * Effect control values: plain values (numbers, strings, switches, number lists) or, when

package/dist/video-editor/parse.d.ts

@@ -1,5 +1,5 @@
 import { type VideoAnimatable, type VideoKeyframes } from './keyframes.js';
-import { type VideoAsset, type VideoAssetProxy, type VideoClip, type VideoClipEffect, type VideoEffectRef, type VideoEffectValues, type VideoClipAnimation, type VideoGrade, type VideoGradeLut, type VideoMarker, type VideoProject, type VideoSequence, type VideoTrack, type VideoTranscriptWord, type VideoTransform, type VideoTransition } from './types.js';
+import { type VideoClipMask, type VideoAsset, type VideoAssetProxy, type VideoClip, type VideoClipEffect, type VideoEffectRef, type VideoEffectValues, type VideoClipAnimation, type VideoGrade, type VideoGradeLut, type VideoMarker, type VideoProject, type VideoSequence, type VideoTrack, type VideoTranscriptWord, type VideoTransform, type VideoTransition } from './types.js';
 /**
  * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in strictly increasing time (clip-relative
  * ms), each value within `range`.
@@ -19,6 +19,8 @@ export declare function parseVideoTimeRemap(v: unknown, speed: unknown, path: st
 export declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAnimation | undefined;
 export declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
 export declare function parseVideoGradeLut(v: unknown, path: string): VideoGradeLut | undefined;
+/** A clip mask `{ shape, x, y, width, height, rotation, feather, cornerRadius, inverted, points }` (see `VideoClipMask`). */
+export declare function parseVideoClipMask(v: unknown, path: string): VideoClipMask | undefined;
 export declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
 /**
  * Effect control values: plain values (numbers, strings, switches, number lists) or, when

package/dist/video-editor/plan.d.cts

@@ -0,0 +1,75 @@
+import { type VideoIssue } from './check.cjs';
+import { type VideoEdit } from './edit.cjs';
+import type { VideoProject } from './types.cjs';
+/**
+ * Plan first, apply later: a `VideoEditPlan` is a batch of edits worked out against the project
+ * and summarised (length before and after, clips added, removed and changed, stretches cut) without
+ * changing anything. People and agents review the plan, preview it, then apply it as one undo step
+ * or discard it. Plans are not part of the project or its history.
+ */
+/** A stretch a plan cuts or changes (timeline ms), with what is said there or why. */
+export interface VideoEditPlanRange {
+    from: number;
+    to: number;
+    /** The words in it, as the transcript tools return them. */
+    text?: string;
+    /** Why it is in the plan (e.g. `filler`, `pause`, `repetition`, `beat`). */
+    reason?: string;
+}
+/** What applying a plan would do. */
+export interface VideoEditPlanSummary {
+    /** The project's length now and after (ms). */
+    durationBefore: number;
+    durationAfter: number;
+    /** `durationAfter - durationBefore` (negative when it shortens). */
+    durationDelta: number;
+    /** Clip ids that would be new, gone or different. */
+    clipsAdded: string[];
+    clipsRemoved: string[];
+    clipsChanged: string[];
+    /** Problems the plan would add (issues the project does not have now). */
+    newIssues: VideoIssue[];
+    /** How many edits it applies. */
+    edits: number;
+}
+/** A proposed batch of edits and what it would do. */
+export interface VideoEditPlan {
+    /** Unique among the open plans (e.g. `plan1`). */
+    id: string;
+    /** A short label, also the undo step's label when applied. */
+    title: string;
+    /** What it does and why, for the reviewer. */
+    description?: string;
+    /** Who proposed it (`agent`, `user`, a tool name…). */
+    source?: string;
+    edits: VideoEdit[];
+    /** The stretches it cuts or changes, for a diff view. */
+    ranges?: VideoEditPlanRange[];
+    summary: VideoEditPlanSummary;
+}
+/** What changed between two versions of a project: clips added, removed and changed, and the length. */
+export declare function diffVideoProjects(before: VideoProject, after: VideoProject): Omit<VideoEditPlanSummary, 'newIssues' | 'edits'>;
+export interface VideoEditPlanInput {
+    /** Default: a fresh `plan<n>` id. */
+    id?: string;
+    title: string;
+    description?: string;
+    source?: string;
+    edits: readonly VideoEdit[];
+    ranges?: readonly VideoEditPlanRange[];
+}
+/**
+ * Works a plan out against a project without changing it: the edits are applied to a copy, all or
+ * nothing, and summarised. `ok: false` with the edit's error when they do not apply. `project` is
+ * what the project would become (to preview).
+ */
+export declare function planVideoEdits(project: VideoProject, input: VideoEditPlanInput): {
+    ok: true;
+    plan: VideoEditPlan;
+    project: VideoProject;
+} | {
+    ok: false;
+    error: string;
+};
+/** One line describing a plan's effect, e.g. "Removes 4 stretches (3.2 s shorter): 5 clips changed, 1 removed". */
+export declare function describeVideoEditPlan(plan: VideoEditPlan): string;

package/dist/video-editor/plan.d.ts

@@ -0,0 +1,75 @@
+import { type VideoIssue } from './check.js';
+import { type VideoEdit } from './edit.js';
+import type { VideoProject } from './types.js';
+/**
+ * Plan first, apply later: a `VideoEditPlan` is a batch of edits worked out against the project
+ * and summarised (length before and after, clips added, removed and changed, stretches cut) without
+ * changing anything. People and agents review the plan, preview it, then apply it as one undo step
+ * or discard it. Plans are not part of the project or its history.
+ */
+/** A stretch a plan cuts or changes (timeline ms), with what is said there or why. */
+export interface VideoEditPlanRange {
+    from: number;
+    to: number;
+    /** The words in it, as the transcript tools return them. */
+    text?: string;
+    /** Why it is in the plan (e.g. `filler`, `pause`, `repetition`, `beat`). */
+    reason?: string;
+}
+/** What applying a plan would do. */
+export interface VideoEditPlanSummary {
+    /** The project's length now and after (ms). */
+    durationBefore: number;
+    durationAfter: number;
+    /** `durationAfter - durationBefore` (negative when it shortens). */
+    durationDelta: number;
+    /** Clip ids that would be new, gone or different. */
+    clipsAdded: string[];
+    clipsRemoved: string[];
+    clipsChanged: string[];
+    /** Problems the plan would add (issues the project does not have now). */
+    newIssues: VideoIssue[];
+    /** How many edits it applies. */
+    edits: number;
+}
+/** A proposed batch of edits and what it would do. */
+export interface VideoEditPlan {
+    /** Unique among the open plans (e.g. `plan1`). */
+    id: string;
+    /** A short label, also the undo step's label when applied. */
+    title: string;
+    /** What it does and why, for the reviewer. */
+    description?: string;
+    /** Who proposed it (`agent`, `user`, a tool name…). */
+    source?: string;
+    edits: VideoEdit[];
+    /** The stretches it cuts or changes, for a diff view. */
+    ranges?: VideoEditPlanRange[];
+    summary: VideoEditPlanSummary;
+}
+/** What changed between two versions of a project: clips added, removed and changed, and the length. */
+export declare function diffVideoProjects(before: VideoProject, after: VideoProject): Omit<VideoEditPlanSummary, 'newIssues' | 'edits'>;
+export interface VideoEditPlanInput {
+    /** Default: a fresh `plan<n>` id. */
+    id?: string;
+    title: string;
+    description?: string;
+    source?: string;
+    edits: readonly VideoEdit[];
+    ranges?: readonly VideoEditPlanRange[];
+}
+/**
+ * Works a plan out against a project without changing it: the edits are applied to a copy, all or
+ * nothing, and summarised. `ok: false` with the edit's error when they do not apply. `project` is
+ * what the project would become (to preview).
+ */
+export declare function planVideoEdits(project: VideoProject, input: VideoEditPlanInput): {
+    ok: true;
+    plan: VideoEditPlan;
+    project: VideoProject;
+} | {
+    ok: false;
+    error: string;
+};
+/** One line describing a plan's effect, e.g. "Removes 4 stretches (3.2 s shorter): 5 clips changed, 1 removed". */
+export declare function describeVideoEditPlan(plan: VideoEditPlan): string;

package/dist/video-editor/render.d.cts

@@ -54,7 +54,7 @@ export type VideoCanvasContext = Pick<CanvasRenderingContext2D, 'save' | 'restor
  */
 export interface VideoScratchCanvas {
     canvas: CanvasImageSource;
-    ctx: VideoCanvasContext & Pick<CanvasRenderingContext2D, 'getImageData' | 'putImageData' | 'clearRect'>;
+    ctx: VideoCanvasContext & Pick<CanvasRenderingContext2D, 'getImageData' | 'putImageData' | 'clearRect'> & Partial<Pick<CanvasRenderingContext2D, 'moveTo' | 'lineTo' | 'closePath' | 'fill'>>;
 }
 export interface VideoDrawOptions {
     /** Puts an SVG filter (white balance) in the page, so the canvas's `filter: url(#id)` finds it. */

package/dist/video-editor/render.d.ts

@@ -54,7 +54,7 @@ export type VideoCanvasContext = Pick<CanvasRenderingContext2D, 'save' | 'restor
  */
 export interface VideoScratchCanvas {
     canvas: CanvasImageSource;
-    ctx: VideoCanvasContext & Pick<CanvasRenderingContext2D, 'getImageData' | 'putImageData' | 'clearRect'>;
+    ctx: VideoCanvasContext & Pick<CanvasRenderingContext2D, 'getImageData' | 'putImageData' | 'clearRect'> & Partial<Pick<CanvasRenderingContext2D, 'moveTo' | 'lineTo' | 'closePath' | 'fill'>>;
 }
 export interface VideoDrawOptions {
     /** Puts an SVG filter (white balance) in the page, so the canvas's `filter: url(#id)` finds it. */

package/dist/video-editor/timeline.d.cts

@@ -2,6 +2,8 @@ import type { VideoAsset, VideoClip, VideoProject, VideoSequence, VideoTrack } f
 /** Clip edges closer than this (ms) count as touching: a cut, not a gap. */
 export declare const VIDEO_TIME_EPSILON = 0.5;
 export declare const videoClipEnd: (clip: VideoClip) => number;
+/** What a clip is called in messages: "title", "colour", "effect clip", "adjustment clip", "compound clip" or "media clip". */
+export declare const videoClipTypeLabel: (clip: Pick<VideoClip, "type">) => string;
 /** Whether a track moves with ripple edits on other tracks (`syncLocked`, default true). */
 export declare const videoTrackSyncLocked: (track: VideoTrack) => boolean;
 /** Playback speed of a clip (1 for titles and colours). */

package/dist/video-editor/timeline.d.ts

@@ -2,6 +2,8 @@ import type { VideoAsset, VideoClip, VideoProject, VideoSequence, VideoTrack } f
 /** Clip edges closer than this (ms) count as touching: a cut, not a gap. */
 export declare const VIDEO_TIME_EPSILON = 0.5;
 export declare const videoClipEnd: (clip: VideoClip) => number;
+/** What a clip is called in messages: "title", "colour", "effect clip", "adjustment clip", "compound clip" or "media clip". */
+export declare const videoClipTypeLabel: (clip: Pick<VideoClip, "type">) => string;
 /** Whether a track moves with ripple edits on other tracks (`syncLocked`, default true). */
 export declare const videoTrackSyncLocked: (track: VideoTrack) => boolean;
 /** Playback speed of a clip (1 for titles and colours). */