@pixerate/editor 0.62.0 → 0.63.0

package/dist/animation-editor/index.d.cts

@@ -36,6 +36,10 @@ interface MotionScene {
      * per second ("on twos" at 12), for a hand-drawn look. Default: smooth.
      */
     steps?: number;
+    /** A beat grid to cue shots to (`MotionShot.at.beat`): music or a voiceover's rhythm. */
+    beat?: MotionBeatGrid;
+    /** A voiceover's words with their times, to cue shots to (`MotionShot.at.word`). */
+    narration?: MotionNarration;
     /** Wanted length in seconds `[min, max]`; `check` warns outside it. */
     target?: [number, number];
     /** Parameters a Flair effect made from this scene exposes (see `toFlairVectorEffect`). */
@@ -63,6 +67,31 @@ type MotionCamera = (MotionRect | {
     /** Zoom at a steady rate (the size changes by the same factor each moment) instead of linearly. */
     geometric?: boolean;
 };
+/** A steady beat: `bpm` beats a minute, the first at `offset` ms, `meter` beats a bar. */
+interface MotionBeatGrid {
+    bpm: number;
+    /** When beat 0 falls, ms (default 0). */
+    offset?: number;
+    /** Beats in a bar (default 4), for reading beats as bar and beat. */
+    meter?: number;
+}
+/** A voiceover: its words in order, each with when it is said (ms), from a TTS or speech-to-text word timing. */
+interface MotionNarration {
+    words: {
+        text: string;
+        start: number;
+        end?: number;
+    }[];
+}
+/** When a shot is cued to start: on a beat, on a narration word, or at a time. */
+interface MotionCue {
+    /** Beat number on the scene's beat grid, from 0 (fractions for off-beats: 2.5 is the "and" of beat 3). */
+    beat?: number;
+    /** Index of a word in the scene's narration, from 0. */
+    word?: number;
+    /** A time in ms. */
+    ms?: number;
+}
 /** One beat of the animation. */
 interface MotionShot {
     /** Stable id (unique in the scene), e.g. `intro`. */
@@ -71,6 +100,12 @@ interface MotionShot {
     label?: string;
     /** Omit to keep the current framing. */
     camera?: MotionCamera;
+    /**
+     * Start on a cue: a beat, a narration word or a time. The shot before holds until then; a
+     * cue that comes before the shot before has ended is missed (`check` says by how much).
+     * Give one of `beat`, `word` or `ms`.
+     */
+    at?: MotionCue;
     /** Commands, played one after another (unless a command says `with: "previous"`). */
     run: MotionCommand[];
     /** Milliseconds to hold after the commands finish (default 600). */
@@ -497,6 +532,14 @@ declare const MOTION_ISSUE_CODES: {
         readonly severity: "warning";
         readonly wording: "A spring is given a duration shorter than it takes to settle, so it jumps to its end.";
     };
+    readonly 'unknown-cue': {
+        readonly severity: "error";
+        readonly wording: "A shot is cued to a beat with no beat grid, or to a word the narration does not have.";
+    };
+    readonly 'cue-missed': {
+        readonly severity: "warning";
+        readonly wording: "A shot starts after its cue, because the shot before runs past it.";
+    };
     readonly 'scene-too-long': {
         readonly severity: "warning";
         readonly wording: "The scene runs past its target length.";
@@ -631,6 +674,10 @@ interface MotionShotTiming {
     /** When the last command ends (the hold follows). */
     commandsEnd: number;
     end: number;
+    /** The time the shot is cued to start (`at`), when it has a cue that resolves. */
+    cue?: number;
+    /** How late the shot starts after its cue (ms), when the shot before ran past it. */
+    missedBy?: number;
 }
 interface MotionCommandTiming {
     shot: string;
@@ -737,6 +784,16 @@ declare function resolveMotionCamera(camera: MotionCamera, scene: MotionScene):
 declare function motionPathLength(node: VectorNode, parentWorld?: AffineMatrix): number;
 /** How much a shot's `speed` stretches its time (1 / speed; 1 when unset or not above 0). */
 declare function motionShotTimeScale(shot: MotionShot): number;
+/** When beat `beat` falls on a grid, ms: `offset + beat · 60000 / bpm`. */
+declare function motionBeatTime(grid: MotionBeatGrid, beat: number): number;
+/** The beat (fractional) at `ms` on a grid, and its bar and beat in the bar (both from 1). */
+declare function motionBeatAt(grid: MotionBeatGrid, ms: number): {
+    beat: number;
+    bar: number;
+    beatInBar: number;
+};
+/** The time a cue names, ms, or undefined when it names a beat with no grid or a word the narration lacks. */
+declare function motionCueTime(scene: Pick<MotionScene, 'beat' | 'narration'>, cue: MotionCue): number | undefined;
 /** How many times a command plays (1 for `enter`, `exit` and `wait`, which do not repeat). */
 declare function motionCommandRepeat(command: MotionCommand): number;
 /** How long one target of a command takes (ms), every repeat included. */
@@ -875,6 +932,8 @@ type MotionEdit = {
     loop?: MotionScene['loop'];
     fps?: number;
     steps?: number | null;
+    beat?: MotionScene['beat'] | null;
+    narration?: MotionScene['narration'] | null;
     target?: [number, number] | null;
 } | {
     op: 'insert_shots';
@@ -884,7 +943,7 @@ type MotionEdit = {
     op: 'update_shot';
     shot: string;
     set?: Partial<MotionShot>;
-    remove?: ('label' | 'camera' | 'hold' | 'speed')[];
+    remove?: ('label' | 'camera' | 'hold' | 'speed' | 'at')[];
 } | {
     op: 'delete_shots';
     shots: string[];
@@ -1683,6 +1742,8 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     })[];
+    missedBy?: number | undefined;
+    cue?: number | undefined;
     hold?: number | undefined;
     camera?: MotionCamera | undefined;
     start: number;
@@ -1703,6 +1764,6 @@ declare function createAnimationEditorToolProvider(controller: AnimationEditorCo
  * A short authoring guide for a model writing vector animations with the animation editor's
  * tools. Static, so it caches well as part of a system prompt.
  */
-declare const ANIMATION_EDITOR_AGENT_INSTRUCTIONS = "You animate vector artwork. A scene is artwork (vector paths and groups, each with an id) plus shots.\n\nHow it plays\n- Shots play in order. A shot optionally moves the camera, plays its commands, then holds (default 600 ms).\n- Commands in a shot play one after another; give \"with\": \"previous\" to start one together with the command before, \"delay\" to wait, \"stagger\" to offset several targets.\n- Timing comes from the content: each command has a default length (enter 600 ms, move 700 ms, draw follows the path length). Only set \"duration\" to change the pace.\n- Anything that enters later is hidden until it enters. Things that never enter are visible from the start.\n- Every frame is a pure function of time: the same scene always plays the same frames.\n\nCommands\n- enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.\n- enter also reveals through a clip over the target's box: wipe (behind an edge travelling \"direction\", default right), iris (from the centre; \"shape\": circle or box) and split (from a line through the middle; \"orientation\": horizontal or vertical). exit wipe hides the same way. Reveals need a width and a height: use draw / undraw for a straight line.\n- draw draws strokes on to a fraction; move, rotate, scale and fade change the pose (about the centre); style blends solid colours and stroke width.\n- enter also has zoom (settles from larger) and rise (rises a short way, overshooting a touch); pop and zoom take a starting \"scale\".\n- morph turns a shape into another node's shape (keep the target hidden); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); follow moves along a path node (with \"rotate\", moves made meanwhile turn with the path).\n- Emphasis draws the eye and returns to rest: pulse (swell), shake (side to side, or \"axis\": \"vertical\"), teeter (rock), wave (bob, no settling), wiggle (seeded wander; the same seed wanders the same way) and color-pulse (tint and back).\n- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\n- Commands share their names and defaults with Flair's motion primitives (get_animation shows each one's \"flairPrimitive\"), and emphasis, reveals and follows export to Flair exactly.\n- effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).\n\nWorking method\n1. get_animation to learn the element ids (set_animation_artwork_svg first if there is no artwork: give every element you will animate an id; or import_flair_effect to start from a Flair effect and edit it).\n2. Plan a few shots, each one idea. Add them with insert_shots, or edit_animation to make several edits as one step (dry_run first when unsure).\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result.\n4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.\n\nKeep motion purposeful: one thing moving at a time reads best, ease-out for arrivals, ease-in for exits, and hold long enough to see each result.";
+declare const ANIMATION_EDITOR_AGENT_INSTRUCTIONS = "You animate vector artwork. A scene is artwork (vector paths and groups, each with an id) plus shots.\n\nHow it plays\n- Shots play in order. A shot optionally moves the camera, plays its commands, then holds (default 600 ms).\n- Commands in a shot play one after another; give \"with\": \"previous\" to start one together with the command before, \"delay\" to wait, \"stagger\" to offset several targets.\n- Timing comes from the content: each command has a default length (enter 600 ms, move 700 ms, draw follows the path length). Only set \"duration\" to change the pace.\n- Anything that enters later is hidden until it enters. Things that never enter are visible from the start.\n- Every frame is a pure function of time: the same scene always plays the same frames.\n\nCommands\n- enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.\n- enter also reveals through a clip over the target's box: wipe (behind an edge travelling \"direction\", default right), iris (from the centre; \"shape\": circle or box) and split (from a line through the middle; \"orientation\": horizontal or vertical). exit wipe hides the same way. Reveals need a width and a height: use draw / undraw for a straight line.\n- draw draws strokes on to a fraction; move, rotate, scale and fade change the pose (about the centre); style blends solid colours and stroke width.\n- enter also has zoom (settles from larger) and rise (rises a short way, overshooting a touch); pop and zoom take a starting \"scale\".\n- morph turns a shape into another node's shape (keep the target hidden); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); follow moves along a path node (with \"rotate\", moves made meanwhile turn with the path).\n- Emphasis draws the eye and returns to rest: pulse (swell), shake (side to side, or \"axis\": \"vertical\"), teeter (rock), wave (bob, no settling), wiggle (seeded wander; the same seed wanders the same way) and color-pulse (tint and back).\n- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- To time shots to music or a voiceover: set a \"beat\" grid or \"narration\" word timings with set_animation_settings, read them with get_timing_grid, and give a shot \"at\": { \"beat\": n } or { \"word\": i }. The shot before holds until the cue; check_animation warns when a cue is missed.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\n- Commands share their names and defaults with Flair's motion primitives (get_animation shows each one's \"flairPrimitive\"), and emphasis, reveals and follows export to Flair exactly.\n- effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).\n\nWorking method\n1. get_animation to learn the element ids (set_animation_artwork_svg first if there is no artwork: give every element you will animate an id; or import_flair_effect to start from a Flair effect and edit it).\n2. Plan a few shots, each one idea. Add them with insert_shots, or edit_animation to make several edits as one step (dry_run first when unsure).\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result.\n4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.\n\nKeep motion purposeful: one thing moving at a time reads best, ease-out for arrivals, ease-in for exits, and hold long enough to see each result.";
 
-export { ANIMATION_EDITOR_AGENT_INSTRUCTIONS, AnimationEditorController, type AnimationEditorOptions, type AnimationEditorSelection, type AnimationEditorState, type AnimationEditorToolProviderOptions, FLAIR_EASES, FLAIR_EXPORT_VERSION, type FlairEase, type FlairEaseName, type FlairEffectDocument, type FlairEffectOptions, type FlairExportOptions, type FlairImportOptions, type FlairImportResult, type FlairMotionExport, type FlairSpringEase, type FlairSvgAnimation, type FlairSvgMotion, type FlairVectorEffect, MOTION_ADDITIVE_PROPERTIES, MOTION_BLENDS, MOTION_CAMERA_MS, MOTION_COMMAND_SCHEMA, MOTION_COMMAND_TYPES, MOTION_DEFAULT_DURATIONS, MOTION_DEFAULT_HOLD, MOTION_DIRECTIONS, MOTION_DRAW_EFFECT_ID, MOTION_DRAW_MS_PER_UNIT, MOTION_DRAW_RANGE, MOTION_EASE_IN_OUT, MOTION_EASE_OUT, MOTION_EDIT_OPS, MOTION_ENTER_STYLES, MOTION_EXIT_STYLES, MOTION_IRIS_SHAPES, MOTION_ISSUE_CODES, MOTION_MIN_CHANGE_MS, MOTION_REPEAT_MODES, MOTION_SPEED_RANGE, MOTION_SPLIT_ORIENTATIONS, type MotionCamera, type MotionClipShape, type MotionColorPulseCommand, type MotionCommand, type MotionCommandBase, type MotionCommandTiming, type MotionCommandType, type MotionControl, type MotionDirection, type MotionDrawCommand, type MotionEdit, type MotionEditOp, type MotionEditResult, type MotionEffectCommand, type MotionEnterCommand, type MotionEnterStyle, type MotionExitCommand, type MotionExitStyle, type MotionFadeCommand, type MotionFit, type MotionFitOptions, type MotionFollowCommand, type MotionFrame, type MotionFrameOptions, type MotionIrisShape, type MotionIssue, type MotionIssueCode, type MotionIssueSeverity, type MotionMatch, type MotionMatchCommand, type MotionMorphCommand, type MotionMoveCommand, type MotionNodeEntry, type MotionPreset, type MotionProperty, type MotionPulseCommand, type MotionRect, type MotionReveal, type MotionRotateCommand, type MotionScaleCommand, type MotionScene, MotionSceneFormatError, type MotionSegment, type MotionShakeCommand, type MotionShot, type MotionShotTiming, type MotionSplitOrientation, type MotionStyleCommand, type MotionSvgOptions, type MotionTeeterCommand, type MotionTimeline, type MotionValue, type MotionWaitCommand, type MotionWaveCommand, type MotionWiggleCommand, activeSegment, applyMotionControlValues, applyMotionEdits, checkMotionScene, commandShapeProblems, compileMotionScene, createAnimationEditorToolProvider, createMotionScene, describeMotionElements, describeMotionShots, fitMotionRect, fitMotionScene, flairAtLeast, flairCurveFor, flairEaseFor, freshShotId, fromFlairSvgMotion, fromFlairVectorEffect, indexMotionNodes, interpolateMotionValue, isMotionCommand, isMotionShot, matchMotionNodes, motionAddTrackKey, motionClipAttrs, motionCommandDuration, motionCommandRepeat, motionCycleDuration, motionFlairPrimitive, motionFollowRoute, motionFrameAt, motionFrameToSvg, motionIssue, motionIssueKey, motionIssueLine, motionNodeClips, motionNodeOffset, motionPathLength, motionRestValue, motionRevealClip, motionRevealPadding, motionSceneShapeProblems, motionSceneToJson, motionShotAt, motionShotTimeScale, motionTrackKey, namedWithSuggestion, parseMotionScene, resolveMotionCamera, segmentProgress, segmentValue, shotShapeProblems, suggestName, toFlairEffectDocument, toFlairSvgMotion, toFlairVectorEffect, trackValue, withMotionLayers, withViewBox };
+export { ANIMATION_EDITOR_AGENT_INSTRUCTIONS, AnimationEditorController, type AnimationEditorOptions, type AnimationEditorSelection, type AnimationEditorState, type AnimationEditorToolProviderOptions, FLAIR_EASES, FLAIR_EXPORT_VERSION, type FlairEase, type FlairEaseName, type FlairEffectDocument, type FlairEffectOptions, type FlairExportOptions, type FlairImportOptions, type FlairImportResult, type FlairMotionExport, type FlairSpringEase, type FlairSvgAnimation, type FlairSvgMotion, type FlairVectorEffect, MOTION_ADDITIVE_PROPERTIES, MOTION_BLENDS, MOTION_CAMERA_MS, MOTION_COMMAND_SCHEMA, MOTION_COMMAND_TYPES, MOTION_DEFAULT_DURATIONS, MOTION_DEFAULT_HOLD, MOTION_DIRECTIONS, MOTION_DRAW_EFFECT_ID, MOTION_DRAW_MS_PER_UNIT, MOTION_DRAW_RANGE, MOTION_EASE_IN_OUT, MOTION_EASE_OUT, MOTION_EDIT_OPS, MOTION_ENTER_STYLES, MOTION_EXIT_STYLES, MOTION_IRIS_SHAPES, MOTION_ISSUE_CODES, MOTION_MIN_CHANGE_MS, MOTION_REPEAT_MODES, MOTION_SPEED_RANGE, MOTION_SPLIT_ORIENTATIONS, type MotionBeatGrid, type MotionCamera, type MotionClipShape, type MotionColorPulseCommand, type MotionCommand, type MotionCommandBase, type MotionCommandTiming, type MotionCommandType, type MotionControl, type MotionCue, type MotionDirection, type MotionDrawCommand, type MotionEdit, type MotionEditOp, type MotionEditResult, type MotionEffectCommand, type MotionEnterCommand, type MotionEnterStyle, type MotionExitCommand, type MotionExitStyle, type MotionFadeCommand, type MotionFit, type MotionFitOptions, type MotionFollowCommand, type MotionFrame, type MotionFrameOptions, type MotionIrisShape, type MotionIssue, type MotionIssueCode, type MotionIssueSeverity, type MotionMatch, type MotionMatchCommand, type MotionMorphCommand, type MotionMoveCommand, type MotionNarration, type MotionNodeEntry, type MotionPreset, type MotionProperty, type MotionPulseCommand, type MotionRect, type MotionReveal, type MotionRotateCommand, type MotionScaleCommand, type MotionScene, MotionSceneFormatError, type MotionSegment, type MotionShakeCommand, type MotionShot, type MotionShotTiming, type MotionSplitOrientation, type MotionStyleCommand, type MotionSvgOptions, type MotionTeeterCommand, type MotionTimeline, type MotionValue, type MotionWaitCommand, type MotionWaveCommand, type MotionWiggleCommand, activeSegment, applyMotionControlValues, applyMotionEdits, checkMotionScene, commandShapeProblems, compileMotionScene, createAnimationEditorToolProvider, createMotionScene, describeMotionElements, describeMotionShots, fitMotionRect, fitMotionScene, flairAtLeast, flairCurveFor, flairEaseFor, freshShotId, fromFlairSvgMotion, fromFlairVectorEffect, indexMotionNodes, interpolateMotionValue, isMotionCommand, isMotionShot, matchMotionNodes, motionAddTrackKey, motionBeatAt, motionBeatTime, motionClipAttrs, motionCommandDuration, motionCommandRepeat, motionCueTime, motionCycleDuration, motionFlairPrimitive, motionFollowRoute, motionFrameAt, motionFrameToSvg, motionIssue, motionIssueKey, motionIssueLine, motionNodeClips, motionNodeOffset, motionPathLength, motionRestValue, motionRevealClip, motionRevealPadding, motionSceneShapeProblems, motionSceneToJson, motionShotAt, motionShotTimeScale, motionTrackKey, namedWithSuggestion, parseMotionScene, resolveMotionCamera, segmentProgress, segmentValue, shotShapeProblems, suggestName, toFlairEffectDocument, toFlairSvgMotion, toFlairVectorEffect, trackValue, withMotionLayers, withViewBox };

package/dist/animation-editor/index.d.ts

@@ -36,6 +36,10 @@ interface MotionScene {
      * per second ("on twos" at 12), for a hand-drawn look. Default: smooth.
      */
     steps?: number;
+    /** A beat grid to cue shots to (`MotionShot.at.beat`): music or a voiceover's rhythm. */
+    beat?: MotionBeatGrid;
+    /** A voiceover's words with their times, to cue shots to (`MotionShot.at.word`). */
+    narration?: MotionNarration;
     /** Wanted length in seconds `[min, max]`; `check` warns outside it. */
     target?: [number, number];
     /** Parameters a Flair effect made from this scene exposes (see `toFlairVectorEffect`). */
@@ -63,6 +67,31 @@ type MotionCamera = (MotionRect | {
     /** Zoom at a steady rate (the size changes by the same factor each moment) instead of linearly. */
     geometric?: boolean;
 };
+/** A steady beat: `bpm` beats a minute, the first at `offset` ms, `meter` beats a bar. */
+interface MotionBeatGrid {
+    bpm: number;
+    /** When beat 0 falls, ms (default 0). */
+    offset?: number;
+    /** Beats in a bar (default 4), for reading beats as bar and beat. */
+    meter?: number;
+}
+/** A voiceover: its words in order, each with when it is said (ms), from a TTS or speech-to-text word timing. */
+interface MotionNarration {
+    words: {
+        text: string;
+        start: number;
+        end?: number;
+    }[];
+}
+/** When a shot is cued to start: on a beat, on a narration word, or at a time. */
+interface MotionCue {
+    /** Beat number on the scene's beat grid, from 0 (fractions for off-beats: 2.5 is the "and" of beat 3). */
+    beat?: number;
+    /** Index of a word in the scene's narration, from 0. */
+    word?: number;
+    /** A time in ms. */
+    ms?: number;
+}
 /** One beat of the animation. */
 interface MotionShot {
     /** Stable id (unique in the scene), e.g. `intro`. */
@@ -71,6 +100,12 @@ interface MotionShot {
     label?: string;
     /** Omit to keep the current framing. */
     camera?: MotionCamera;
+    /**
+     * Start on a cue: a beat, a narration word or a time. The shot before holds until then; a
+     * cue that comes before the shot before has ended is missed (`check` says by how much).
+     * Give one of `beat`, `word` or `ms`.
+     */
+    at?: MotionCue;
     /** Commands, played one after another (unless a command says `with: "previous"`). */
     run: MotionCommand[];
     /** Milliseconds to hold after the commands finish (default 600). */
@@ -497,6 +532,14 @@ declare const MOTION_ISSUE_CODES: {
         readonly severity: "warning";
         readonly wording: "A spring is given a duration shorter than it takes to settle, so it jumps to its end.";
     };
+    readonly 'unknown-cue': {
+        readonly severity: "error";
+        readonly wording: "A shot is cued to a beat with no beat grid, or to a word the narration does not have.";
+    };
+    readonly 'cue-missed': {
+        readonly severity: "warning";
+        readonly wording: "A shot starts after its cue, because the shot before runs past it.";
+    };
     readonly 'scene-too-long': {
         readonly severity: "warning";
         readonly wording: "The scene runs past its target length.";
@@ -631,6 +674,10 @@ interface MotionShotTiming {
     /** When the last command ends (the hold follows). */
     commandsEnd: number;
     end: number;
+    /** The time the shot is cued to start (`at`), when it has a cue that resolves. */
+    cue?: number;
+    /** How late the shot starts after its cue (ms), when the shot before ran past it. */
+    missedBy?: number;
 }
 interface MotionCommandTiming {
     shot: string;
@@ -737,6 +784,16 @@ declare function resolveMotionCamera(camera: MotionCamera, scene: MotionScene):
 declare function motionPathLength(node: VectorNode, parentWorld?: AffineMatrix): number;
 /** How much a shot's `speed` stretches its time (1 / speed; 1 when unset or not above 0). */
 declare function motionShotTimeScale(shot: MotionShot): number;
+/** When beat `beat` falls on a grid, ms: `offset + beat · 60000 / bpm`. */
+declare function motionBeatTime(grid: MotionBeatGrid, beat: number): number;
+/** The beat (fractional) at `ms` on a grid, and its bar and beat in the bar (both from 1). */
+declare function motionBeatAt(grid: MotionBeatGrid, ms: number): {
+    beat: number;
+    bar: number;
+    beatInBar: number;
+};
+/** The time a cue names, ms, or undefined when it names a beat with no grid or a word the narration lacks. */
+declare function motionCueTime(scene: Pick<MotionScene, 'beat' | 'narration'>, cue: MotionCue): number | undefined;
 /** How many times a command plays (1 for `enter`, `exit` and `wait`, which do not repeat). */
 declare function motionCommandRepeat(command: MotionCommand): number;
 /** How long one target of a command takes (ms), every repeat included. */
@@ -875,6 +932,8 @@ type MotionEdit = {
     loop?: MotionScene['loop'];
     fps?: number;
     steps?: number | null;
+    beat?: MotionScene['beat'] | null;
+    narration?: MotionScene['narration'] | null;
     target?: [number, number] | null;
 } | {
     op: 'insert_shots';
@@ -884,7 +943,7 @@ type MotionEdit = {
     op: 'update_shot';
     shot: string;
     set?: Partial<MotionShot>;
-    remove?: ('label' | 'camera' | 'hold' | 'speed')[];
+    remove?: ('label' | 'camera' | 'hold' | 'speed' | 'at')[];
 } | {
     op: 'delete_shots';
     shots: string[];
@@ -1683,6 +1742,8 @@ declare function describeMotionShots(scene: MotionScene): {
         note?: string;
         index: number;
     })[];
+    missedBy?: number | undefined;
+    cue?: number | undefined;
     hold?: number | undefined;
     camera?: MotionCamera | undefined;
     start: number;
@@ -1703,6 +1764,6 @@ declare function createAnimationEditorToolProvider(controller: AnimationEditorCo
  * A short authoring guide for a model writing vector animations with the animation editor's
  * tools. Static, so it caches well as part of a system prompt.
  */
-declare const ANIMATION_EDITOR_AGENT_INSTRUCTIONS = "You animate vector artwork. A scene is artwork (vector paths and groups, each with an id) plus shots.\n\nHow it plays\n- Shots play in order. A shot optionally moves the camera, plays its commands, then holds (default 600 ms).\n- Commands in a shot play one after another; give \"with\": \"previous\" to start one together with the command before, \"delay\" to wait, \"stagger\" to offset several targets.\n- Timing comes from the content: each command has a default length (enter 600 ms, move 700 ms, draw follows the path length). Only set \"duration\" to change the pace.\n- Anything that enters later is hidden until it enters. Things that never enter are visible from the start.\n- Every frame is a pure function of time: the same scene always plays the same frames.\n\nCommands\n- enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.\n- enter also reveals through a clip over the target's box: wipe (behind an edge travelling \"direction\", default right), iris (from the centre; \"shape\": circle or box) and split (from a line through the middle; \"orientation\": horizontal or vertical). exit wipe hides the same way. Reveals need a width and a height: use draw / undraw for a straight line.\n- draw draws strokes on to a fraction; move, rotate, scale and fade change the pose (about the centre); style blends solid colours and stroke width.\n- enter also has zoom (settles from larger) and rise (rises a short way, overshooting a touch); pop and zoom take a starting \"scale\".\n- morph turns a shape into another node's shape (keep the target hidden); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); follow moves along a path node (with \"rotate\", moves made meanwhile turn with the path).\n- Emphasis draws the eye and returns to rest: pulse (swell), shake (side to side, or \"axis\": \"vertical\"), teeter (rock), wave (bob, no settling), wiggle (seeded wander; the same seed wanders the same way) and color-pulse (tint and back).\n- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\n- Commands share their names and defaults with Flair's motion primitives (get_animation shows each one's \"flairPrimitive\"), and emphasis, reveals and follows export to Flair exactly.\n- effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).\n\nWorking method\n1. get_animation to learn the element ids (set_animation_artwork_svg first if there is no artwork: give every element you will animate an id; or import_flair_effect to start from a Flair effect and edit it).\n2. Plan a few shots, each one idea. Add them with insert_shots, or edit_animation to make several edits as one step (dry_run first when unsure).\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result.\n4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.\n\nKeep motion purposeful: one thing moving at a time reads best, ease-out for arrivals, ease-in for exits, and hold long enough to see each result.";
+declare const ANIMATION_EDITOR_AGENT_INSTRUCTIONS = "You animate vector artwork. A scene is artwork (vector paths and groups, each with an id) plus shots.\n\nHow it plays\n- Shots play in order. A shot optionally moves the camera, plays its commands, then holds (default 600 ms).\n- Commands in a shot play one after another; give \"with\": \"previous\" to start one together with the command before, \"delay\" to wait, \"stagger\" to offset several targets.\n- Timing comes from the content: each command has a default length (enter 600 ms, move 700 ms, draw follows the path length). Only set \"duration\" to change the pace.\n- Anything that enters later is hidden until it enters. Things that never enter are visible from the start.\n- Every frame is a pure function of time: the same scene always plays the same frames.\n\nCommands\n- enter (fade, pop, grow, slide, draw) and exit (fade, shrink, slide, undraw) bring things in and out.\n- enter also reveals through a clip over the target's box: wipe (behind an edge travelling \"direction\", default right), iris (from the centre; \"shape\": circle or box) and split (from a line through the middle; \"orientation\": horizontal or vertical). exit wipe hides the same way. Reveals need a width and a height: use draw / undraw for a straight line.\n- draw draws strokes on to a fraction; move, rotate, scale and fade change the pose (about the centre); style blends solid colours and stroke width.\n- enter also has zoom (settles from larger) and rise (rises a short way, overshooting a touch); pop and zoom take a starting \"scale\".\n- morph turns a shape into another node's shape (keep the target hidden); match does the same for a whole group, part by part (Smart Animate: draw the end state as a second, hidden group whose parts share names with the first); follow moves along a path node (with \"rotate\", moves made meanwhile turn with the path).\n- Emphasis draws the eye and returns to rest: pulse (swell), shake (side to side, or \"axis\": \"vertical\"), teeter (rock), wave (bob, no settling), wiggle (seeded wander; the same seed wanders the same way) and color-pulse (tint and back).\n- Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale \"blend\": \"add\" to stack them too (what they add stays); \"blend\": \"replace\" makes a change take over instead.\n- Any command but enter and exit can \"repeat\" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); \"duration\" is one cycle.\n- Springs (\"spring-gentle\", \"spring-quick\", \"spring-bouncy\", \"spring-slow\" or { \"type\": \"spring\", \u2026 }) feel physical; leave \"duration\" out and the spring sets it.\n- To time shots to music or a voiceover: set a \"beat\" grid or \"narration\" word timings with set_animation_settings, read them with get_timing_grid, and give a shot \"at\": { \"beat\": n } or { \"word\": i }. The shot before holds until the cue; check_animation warns when a cue is missed.\n- \"steps\": 12 (on a command, or for the whole scene with set_animation_settings) holds poses \"on twos\" for a hand-drawn look. \"geometric\": true on scale or a camera zooms at an even rate.\n- Commands share their names and defaults with Flair's motion primitives (get_animation shows each one's \"flairPrimitive\"), and emphasis, reveals and follows export to Flair exactly.\n- effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).\n\nWorking method\n1. get_animation to learn the element ids (set_animation_artwork_svg first if there is no artwork: give every element you will animate an id; or import_flair_effect to start from a Flair effect and edit it).\n2. Plan a few shots, each one idea. Add them with insert_shots, or edit_animation to make several edits as one step (dry_run first when unsure).\n3. To hit a length, fit_animation (keep the shots whose pace matters). check_animation and fix every error and warning; render_animation_frame (shot + \"end\") to look at the result.\n4. To make a reusable Flair effect, set_animation_controls (colour controls stand for every use of their default colour) and export_flair_effect.\n\nKeep motion purposeful: one thing moving at a time reads best, ease-out for arrivals, ease-in for exits, and hold long enough to see each result.";
 
-export { ANIMATION_EDITOR_AGENT_INSTRUCTIONS, AnimationEditorController, type AnimationEditorOptions, type AnimationEditorSelection, type AnimationEditorState, type AnimationEditorToolProviderOptions, FLAIR_EASES, FLAIR_EXPORT_VERSION, type FlairEase, type FlairEaseName, type FlairEffectDocument, type FlairEffectOptions, type FlairExportOptions, type FlairImportOptions, type FlairImportResult, type FlairMotionExport, type FlairSpringEase, type FlairSvgAnimation, type FlairSvgMotion, type FlairVectorEffect, MOTION_ADDITIVE_PROPERTIES, MOTION_BLENDS, MOTION_CAMERA_MS, MOTION_COMMAND_SCHEMA, MOTION_COMMAND_TYPES, MOTION_DEFAULT_DURATIONS, MOTION_DEFAULT_HOLD, MOTION_DIRECTIONS, MOTION_DRAW_EFFECT_ID, MOTION_DRAW_MS_PER_UNIT, MOTION_DRAW_RANGE, MOTION_EASE_IN_OUT, MOTION_EASE_OUT, MOTION_EDIT_OPS, MOTION_ENTER_STYLES, MOTION_EXIT_STYLES, MOTION_IRIS_SHAPES, MOTION_ISSUE_CODES, MOTION_MIN_CHANGE_MS, MOTION_REPEAT_MODES, MOTION_SPEED_RANGE, MOTION_SPLIT_ORIENTATIONS, type MotionCamera, type MotionClipShape, type MotionColorPulseCommand, type MotionCommand, type MotionCommandBase, type MotionCommandTiming, type MotionCommandType, type MotionControl, type MotionDirection, type MotionDrawCommand, type MotionEdit, type MotionEditOp, type MotionEditResult, type MotionEffectCommand, type MotionEnterCommand, type MotionEnterStyle, type MotionExitCommand, type MotionExitStyle, type MotionFadeCommand, type MotionFit, type MotionFitOptions, type MotionFollowCommand, type MotionFrame, type MotionFrameOptions, type MotionIrisShape, type MotionIssue, type MotionIssueCode, type MotionIssueSeverity, type MotionMatch, type MotionMatchCommand, type MotionMorphCommand, type MotionMoveCommand, type MotionNodeEntry, type MotionPreset, type MotionProperty, type MotionPulseCommand, type MotionRect, type MotionReveal, type MotionRotateCommand, type MotionScaleCommand, type MotionScene, MotionSceneFormatError, type MotionSegment, type MotionShakeCommand, type MotionShot, type MotionShotTiming, type MotionSplitOrientation, type MotionStyleCommand, type MotionSvgOptions, type MotionTeeterCommand, type MotionTimeline, type MotionValue, type MotionWaitCommand, type MotionWaveCommand, type MotionWiggleCommand, activeSegment, applyMotionControlValues, applyMotionEdits, checkMotionScene, commandShapeProblems, compileMotionScene, createAnimationEditorToolProvider, createMotionScene, describeMotionElements, describeMotionShots, fitMotionRect, fitMotionScene, flairAtLeast, flairCurveFor, flairEaseFor, freshShotId, fromFlairSvgMotion, fromFlairVectorEffect, indexMotionNodes, interpolateMotionValue, isMotionCommand, isMotionShot, matchMotionNodes, motionAddTrackKey, motionClipAttrs, motionCommandDuration, motionCommandRepeat, motionCycleDuration, motionFlairPrimitive, motionFollowRoute, motionFrameAt, motionFrameToSvg, motionIssue, motionIssueKey, motionIssueLine, motionNodeClips, motionNodeOffset, motionPathLength, motionRestValue, motionRevealClip, motionRevealPadding, motionSceneShapeProblems, motionSceneToJson, motionShotAt, motionShotTimeScale, motionTrackKey, namedWithSuggestion, parseMotionScene, resolveMotionCamera, segmentProgress, segmentValue, shotShapeProblems, suggestName, toFlairEffectDocument, toFlairSvgMotion, toFlairVectorEffect, trackValue, withMotionLayers, withViewBox };
+export { ANIMATION_EDITOR_AGENT_INSTRUCTIONS, AnimationEditorController, type AnimationEditorOptions, type AnimationEditorSelection, type AnimationEditorState, type AnimationEditorToolProviderOptions, FLAIR_EASES, FLAIR_EXPORT_VERSION, type FlairEase, type FlairEaseName, type FlairEffectDocument, type FlairEffectOptions, type FlairExportOptions, type FlairImportOptions, type FlairImportResult, type FlairMotionExport, type FlairSpringEase, type FlairSvgAnimation, type FlairSvgMotion, type FlairVectorEffect, MOTION_ADDITIVE_PROPERTIES, MOTION_BLENDS, MOTION_CAMERA_MS, MOTION_COMMAND_SCHEMA, MOTION_COMMAND_TYPES, MOTION_DEFAULT_DURATIONS, MOTION_DEFAULT_HOLD, MOTION_DIRECTIONS, MOTION_DRAW_EFFECT_ID, MOTION_DRAW_MS_PER_UNIT, MOTION_DRAW_RANGE, MOTION_EASE_IN_OUT, MOTION_EASE_OUT, MOTION_EDIT_OPS, MOTION_ENTER_STYLES, MOTION_EXIT_STYLES, MOTION_IRIS_SHAPES, MOTION_ISSUE_CODES, MOTION_MIN_CHANGE_MS, MOTION_REPEAT_MODES, MOTION_SPEED_RANGE, MOTION_SPLIT_ORIENTATIONS, type MotionBeatGrid, type MotionCamera, type MotionClipShape, type MotionColorPulseCommand, type MotionCommand, type MotionCommandBase, type MotionCommandTiming, type MotionCommandType, type MotionControl, type MotionCue, type MotionDirection, type MotionDrawCommand, type MotionEdit, type MotionEditOp, type MotionEditResult, type MotionEffectCommand, type MotionEnterCommand, type MotionEnterStyle, type MotionExitCommand, type MotionExitStyle, type MotionFadeCommand, type MotionFit, type MotionFitOptions, type MotionFollowCommand, type MotionFrame, type MotionFrameOptions, type MotionIrisShape, type MotionIssue, type MotionIssueCode, type MotionIssueSeverity, type MotionMatch, type MotionMatchCommand, type MotionMorphCommand, type MotionMoveCommand, type MotionNarration, type MotionNodeEntry, type MotionPreset, type MotionProperty, type MotionPulseCommand, type MotionRect, type MotionReveal, type MotionRotateCommand, type MotionScaleCommand, type MotionScene, MotionSceneFormatError, type MotionSegment, type MotionShakeCommand, type MotionShot, type MotionShotTiming, type MotionSplitOrientation, type MotionStyleCommand, type MotionSvgOptions, type MotionTeeterCommand, type MotionTimeline, type MotionValue, type MotionWaitCommand, type MotionWaveCommand, type MotionWiggleCommand, activeSegment, applyMotionControlValues, applyMotionEdits, checkMotionScene, commandShapeProblems, compileMotionScene, createAnimationEditorToolProvider, createMotionScene, describeMotionElements, describeMotionShots, fitMotionRect, fitMotionScene, flairAtLeast, flairCurveFor, flairEaseFor, freshShotId, fromFlairSvgMotion, fromFlairVectorEffect, indexMotionNodes, interpolateMotionValue, isMotionCommand, isMotionShot, matchMotionNodes, motionAddTrackKey, motionBeatAt, motionBeatTime, motionClipAttrs, motionCommandDuration, motionCommandRepeat, motionCueTime, motionCycleDuration, motionFlairPrimitive, motionFollowRoute, motionFrameAt, motionFrameToSvg, motionIssue, motionIssueKey, motionIssueLine, motionNodeClips, motionNodeOffset, motionPathLength, motionRestValue, motionRevealClip, motionRevealPadding, motionSceneShapeProblems, motionSceneToJson, motionShotAt, motionShotTimeScale, motionTrackKey, namedWithSuggestion, parseMotionScene, resolveMotionCamera, segmentProgress, segmentValue, shotShapeProblems, suggestName, toFlairEffectDocument, toFlairSvgMotion, toFlairVectorEffect, trackValue, withMotionLayers, withViewBox };

package/dist/animation-editor/index.js

@@ -149,6 +149,8 @@ var MOTION_ISSUE_CODES = {
   "out-of-frame": { severity: "warning", wording: "A node a command animates ends up outside the camera." },
   "too-fast": { severity: "warning", wording: "A change is too quick to follow." },
   "spring-cut-short": { severity: "warning", wording: "A spring is given a duration shorter than it takes to settle, so it jumps to its end." },
+  "unknown-cue": { severity: "error", wording: "A shot is cued to a beat with no beat grid, or to a word the narration does not have." },
+  "cue-missed": { severity: "warning", wording: "A shot starts after its cue, because the shot before runs past it." },
   "scene-too-long": { severity: "warning", wording: "The scene runs past its target length." },
   "scene-too-short": { severity: "warning", wording: "The scene ends before its target length." },
   "unknown-control-color": { severity: "warning", wording: "A control stands for a colour the scene never uses." },
@@ -206,8 +208,8 @@ ${problems.map((p) => `- ${p}`).join("\n")}`);
     this.problems = problems;
   }
 };
-var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "loop", "fps", "steps", "target", "controls", "presets"];
-var SHOT_KEYS = ["id", "label", "camera", "run", "hold", "speed"];
+var SCENE_KEYS = ["version", "name", "description", "artwork", "shots", "loop", "fps", "steps", "beat", "narration", "target", "controls", "presets"];
+var SHOT_KEYS = ["id", "label", "camera", "at", "run", "hold", "speed"];
 var CAMERA_KEYS = ["x", "y", "width", "height", "frame", "padding", "ease", "ms", "geometric"];
 var BASE_KEYS = ["type", "targets", "duration", "delay", "stagger", "with", "ease", "note", "repeat", "repeatMode", "steps"];
 var COMMAND_KEYS = {
@@ -361,6 +363,16 @@ function shotShapeProblems(shot, where) {
   if (shot.label !== void 0 && typeof shot.label !== "string") problems.push(`${name}: "label" must be a string.`);
   if (shot.hold !== void 0 && !(isNum(shot.hold) && shot.hold >= 0)) problems.push(`${name}: "hold" must be a number of milliseconds \u2265 0.`);
   if (shot.speed !== void 0 && !(isNum(shot.speed) && shot.speed >= 0.05 && shot.speed <= 20)) problems.push(`${name}: "speed" must be a number from 0.05 to 20 (2 plays it twice as fast).`);
+  if (shot.at !== void 0) {
+    const at = shot.at;
+    const given = isObject(at) ? ["beat", "word", "ms"].filter((k) => at[k] !== void 0) : [];
+    if (!isObject(at) || given.length !== 1) problems.push(`${name}: "at" must give one of { "beat": number }, { "word": index } or { "ms": number }.`);
+    else {
+      unknownKeys(at, ["beat", "word", "ms"], `${name} at`, problems);
+      const k = given[0];
+      if (!isNum(at[k]) || at[k] < 0 || k === "word" && !Number.isInteger(at[k])) problems.push(`${name}: "at.${k}" must be ${k === "word" ? "a word index \u2265 0" : "a number \u2265 0"}.`);
+    }
+  }
   if (shot.camera !== void 0) {
     const c = shot.camera;
     if (!isObject(c)) problems.push(`${name}: "camera" must be an object.`);
@@ -391,6 +403,16 @@ function motionSceneShapeProblems(input) {
     problems.push('Scene: "artwork" must be a vector document { width, height, nodes }.');
   if (input.loop !== void 0 && !["none", "loop", "ping-pong"].includes(input.loop)) problems.push('Scene: "loop" must be "none", "loop" or "ping-pong".');
   if (input.fps !== void 0 && !(isNum(input.fps) && input.fps > 0 && input.fps <= 120)) problems.push('Scene: "fps" must be a number from 1 to 120.');
+  if (input.beat !== void 0) {
+    const b = input.beat;
+    if (!isObject(b) || !(isNum(b.bpm) && b.bpm >= 1 && b.bpm <= 1e3) || b.offset !== void 0 && !isNum(b.offset) || b.meter !== void 0 && !(Number.isInteger(b.meter) && b.meter >= 1))
+      problems.push('Scene: "beat" must be { "bpm": 1\u20131000, "offset"?: ms, "meter"?: beats a bar }.');
+  }
+  if (input.narration !== void 0) {
+    const n = input.narration;
+    if (!isObject(n) || !Array.isArray(n.words) || !n.words.every((w, i, all) => isObject(w) && typeof w.text === "string" && isNum(w.start) && w.start >= 0 && (w.end === void 0 || isNum(w.end) && w.end >= w.start) && (i === 0 || w.start >= (all[i - 1].start ?? 0))))
+      problems.push('Scene: "narration" must be { "words": [{ "text", "start": ms, "end"?: ms }, \u2026] } in time order.');
+  }
   if (input.steps !== void 0 && !(isNum(input.steps) && input.steps > 0 && input.steps <= 120)) problems.push('Scene: "steps" must be frames per second from above 0 to 120.');
   if (input.target !== void 0 && !(Array.isArray(input.target) && input.target.length === 2 && input.target.every(isNum) && input.target[0] <= input.target[1]))
     problems.push('Scene: "target" must be [min, max] seconds.');
@@ -699,6 +721,21 @@ function motionPathLength(node, parentWorld = IDENTITY_MATRIX) {
 function motionShotTimeScale(shot) {
   return typeof shot.speed === "number" && shot.speed > 0 && Number.isFinite(shot.speed) ? 1 / shot.speed : 1;
 }
+function motionBeatTime(grid, beat) {
+  return (grid.offset ?? 0) + beat * 6e4 / grid.bpm;
+}
+function motionBeatAt(grid, ms) {
+  const beat = (ms - (grid.offset ?? 0)) * grid.bpm / 6e4;
+  const meter = Math.max(1, Math.round(grid.meter ?? 4));
+  const whole = Math.floor(beat + 1e-9);
+  return { beat, bar: Math.floor(whole / meter) + 1, beatInBar: (whole % meter + meter) % meter + 1 };
+}
+function motionCueTime(scene, cue) {
+  if (typeof cue.ms === "number") return Math.max(0, cue.ms);
+  if (typeof cue.beat === "number") return scene.beat && scene.beat.bpm > 0 ? Math.max(0, motionBeatTime(scene.beat, cue.beat)) : void 0;
+  if (typeof cue.word === "number") return scene.narration?.words[cue.word]?.start;
+  return void 0;
+}
 function motionCommandRepeat(command2) {
   if (command2.type === "wait" || command2.type === "enter" || command2.type === "exit") return 1;
   const n = command2.repeat ?? 1;
@@ -736,6 +773,12 @@ function compileMotionScene(scene) {
   const cameraMoves = [];
   let t = 0;
   scene.shots.forEach((shot, index) => {
+    const cue = shot.at ? motionCueTime(scene, shot.at) : void 0;
+    if (cue !== void 0 && cue > t) {
+      if (shots.length) shots[shots.length - 1].end = cue;
+      t = cue;
+    }
+    const missedBy = cue !== void 0 && t - cue > 0.5 ? t - cue : void 0;
     const start = t;
     let cursor = start;
     const f = motionShotTimeScale(shot);
@@ -762,7 +805,7 @@ function compileMotionScene(scene) {
       runEnd = Math.max(runEnd, end2);
     });
     const end = runEnd + (shot.hold ?? MOTION_DEFAULT_HOLD) * f;
-    shots.push({ id: shot.id, index, ...shot.label ? { label: shot.label } : {}, start, commandsStart, commandsEnd: runEnd, end });
+    shots.push({ id: shot.id, index, ...shot.label ? { label: shot.label } : {}, start, commandsStart, commandsEnd: runEnd, end, ...cue !== void 0 ? { cue } : {}, ...missedBy !== void 0 ? { missedBy } : {} });
     t = end;
   });
   const tracks = /* @__PURE__ */ new Map();
@@ -1366,6 +1409,17 @@ function checkMotionScene(scene) {
       }
     });
   });
+  scene.shots.forEach((shot, i) => {
+    if (!shot.at) return;
+    const timing = timeline.shots[i];
+    if (timing.cue === void 0) {
+      const what = shot.at.beat !== void 0 ? `beat ${shot.at.beat}, but the scene has no beat grid; set one with set_animation_settings ({ "beat": { "bpm": \u2026 } })` : `word ${shot.at.word}, but the narration has ${scene.narration?.words.length ?? 0} words (indexes from 0)`;
+      issues.push(motionIssue("unknown-cue", `Shot "${shot.id}" is cued to ${what}.`, { shot: shot.id }));
+    } else if (timing.missedBy !== void 0) {
+      const late = Math.round(timing.missedBy);
+      issues.push(motionIssue("cue-missed", `Shot "${shot.id}" is cued at ${Math.round(timing.cue)} ms but starts ${late} ms late, because the shot before runs until ${Math.round(timing.start)} ms; shorten that shot (its hold, durations or speed) or cue this one later.`, { shot: shot.id, measured: late, needed: 0, unit: "ms" }));
+    }
+  });
   for (const [key, track] of timeline.tracks) {
     if (key.endsWith("\0add")) continue;
     for (let i = 1; i < track.length; i++) {
@@ -1467,6 +1521,14 @@ function applyOne(scene, edit) {
         if (!(typeof edit.steps === "number" && edit.steps > 0 && edit.steps <= 120)) fail('"steps" must be frames per second from above 0 to 120 (12 is "on twos" at 24 fps), or null for smooth.');
         next.steps = edit.steps;
       }
+      for (const key of ["beat", "narration"]) {
+        if (edit[key] === null) delete next[key];
+        else if (edit[key] !== void 0) next[key] = edit[key];
+      }
+      {
+        const problems = motionSceneShapeProblems(next).filter((p) => /"beat"|"narration"/.test(p));
+        if (problems.length) fail(problems.join(" "));
+      }
       if (edit.target === null) delete next.target;
       else if (edit.target !== void 0) next.target = edit.target;
       return next;
@@ -2495,7 +2557,12 @@ var SHOT_FIELDS = {
   camera: CAMERA,
   run: { type: "array", items: MOTION_COMMAND_SCHEMA, description: "Commands, in order." },
   hold: MS("Hold after the commands (default 600)"),
-  speed: { type: "number", minimum: 0.05, maximum: 20, description: "Play the whole shot this many times as fast (default 1; 0.5 is half speed). fit_animation sets it." }
+  speed: { type: "number", minimum: 0.05, maximum: 20, description: "Play the whole shot this many times as fast (default 1; 0.5 is half speed). fit_animation sets it." },
+  at: object(
+    { beat: { type: "number", minimum: 0, description: `Beat number on the scene's beat grid, from 0 (2.5 is the "and" of beat 3).` }, word: { type: "integer", minimum: 0, description: "Index of a narration word, from 0." }, ms: { type: "number", minimum: 0, description: "A time in ms." } },
+    [],
+    "Start this shot on a cue (give one of beat, word or ms); the shot before holds until then. get_timing_grid lists beats and words."
+  )
 };
 var SHOT = object({ id: { type: "string", pattern: "^[A-Za-z0-9_][\\w.-]*$", description: 'Unique shot id, e.g. "intro".' }, ...SHOT_FIELDS }, ["id", "run"], "A shot.");
 var CONTROL = object(
@@ -2515,6 +2582,20 @@ var SETTINGS = {
   loop: { type: "string", enum: ["none", "loop", "ping-pong"], description: "Playback past the end (default none)." },
   fps: { type: "number", minimum: 1, maximum: 120, description: "Sampling rate for exports (default 30)." },
   steps: { anyOf: [{ type: "number", exclusiveMinimum: 0, maximum: 120 }, { type: "null" }], description: 'Stepped time for every command without its own: changes hold on a grid of this many frames per second (12 = "on twos" at 24 fps) for a hand-drawn look; null makes it smooth again (default).' },
+  beat: {
+    anyOf: [
+      object({ bpm: { type: "number", minimum: 1, maximum: 1e3, description: "Beats a minute." }, offset: { type: "number", description: "When beat 0 falls, ms (default 0)." }, meter: { type: "integer", minimum: 1, description: "Beats a bar (default 4)." } }, ["bpm"]),
+      { type: "null" }
+    ],
+    description: `A beat grid (music or a voiceover's rhythm) that shots can be cued to with "at": { "beat": n }; null clears.`
+  },
+  narration: {
+    anyOf: [
+      object({ words: { type: "array", items: object({ text: { type: "string", description: "The word." }, start: { type: "number", minimum: 0, description: "When it is said, ms." }, end: { type: "number", minimum: 0, description: "When it ends, ms." } }, ["text", "start"]), description: "Words in time order, from a TTS or speech-to-text word timing." } }, ["words"]),
+      { type: "null" }
+    ],
+    description: `A voiceover's word timings that shots can be cued to with "at": { "word": index }; null clears.`
+  },
   target: { anyOf: [{ type: "array", items: { type: "number", minimum: 0 }, minItems: 2, maxItems: 2 }, { type: "null" }], description: "Wanted length [min, max] in seconds; null clears." }
 };
 var EDIT_OP = {
@@ -2522,7 +2603,7 @@ var EDIT_OP = {
   oneOf: [
     object({ op: { const: "set_settings", description: "Like set_animation_settings." }, ...SETTINGS }, ["op"]),
     object({ op: { const: "insert_shots", description: "Like insert_shots." }, shots: { type: "array", items: SHOT, minItems: 1, description: "Shots to add." }, at: { type: "integer", minimum: 0, description: "Position (default: the end)." } }, ["op", "shots"]),
-    object({ op: { const: "update_shot", description: "Like update_shot." }, shot: SHOT_ID, set: object({ id: SHOT.properties.id, ...SHOT_FIELDS }, [], "Fields to replace."), remove: { type: "array", items: { type: "string", enum: ["label", "camera", "hold", "speed"] }, description: "Fields to clear." } }, ["op", "shot"]),
+    object({ op: { const: "update_shot", description: "Like update_shot." }, shot: SHOT_ID, set: object({ id: SHOT.properties.id, ...SHOT_FIELDS }, [], "Fields to replace."), remove: { type: "array", items: { type: "string", enum: ["label", "camera", "hold", "speed", "at"] }, description: "Fields to clear." } }, ["op", "shot"]),
     object({ op: { const: "delete_shots", description: "Like delete_shots." }, shots: { type: "array", items: SHOT_ID, minItems: 1, description: "Shot ids." } }, ["op", "shots"]),
     object({ op: { const: "move_shot", description: "Like move_shot." }, shot: SHOT_ID, to: { type: "integer", minimum: 0, description: "New position (0 = first)." } }, ["op", "shot", "to"]),
     object({ op: { const: "add_commands", description: "Like add_commands." }, shot: SHOT_ID, commands: { type: "array", items: MOTION_COMMAND_SCHEMA, minItems: 1, description: "Commands to add." }, at: { type: "integer", minimum: 0, description: "Index in the shot's run (default: the end)." } }, ["op", "shot", "commands"]),
@@ -2567,6 +2648,8 @@ function describeMotionShots(scene) {
       end: t.end,
       ...shot.camera ? { camera: shot.camera } : {},
       ...shot.hold !== void 0 ? { hold: shot.hold } : {},
+      ...t.cue !== void 0 ? { cue: Math.round(t.cue) } : {},
+      ...t.missedBy !== void 0 ? { missedBy: Math.round(t.missedBy) } : {},
       commands: shot.run.map((c, index) => {
         const ct = timeline.commands.find((x) => x.shotIndex === i && x.command === index);
         const primitive = motionFlairPrimitive(c);
@@ -2695,6 +2778,42 @@ function createAnimationEditorToolProvider(controller, options = {}) {
   const CURVES_DESCRIPTION = "Write cubic-bezier easings (ease, ease-in, ease-out, ease-in-out, back eases, custom curves) as one change with ease: [x1, y1, x2, y2] (default true). Needs Flair 0.36 or later; false samples them into linear steps for older Flair.";
   const FLAIR_DESCRIPTION = "The Flair version to export for (default 0.39): springs and stepped time need 0.39, behaviours 0.38, cubic-bezier curves 0.36; older versions get those sampled into linear steps.";
   const BEHAVIORS_DESCRIPTION = "Write pulses, shakes, teeters, waves, wiggles and colour pulses as one change with a Flair behavior, so they play exactly (default true; needs Flair 0.38 or later). False samples them into linear steps for older Flair.";
+  const getTimingGrid = {
+    name: "get_timing_grid",
+    title: "Read the beat grid and narration",
+    description: 'Returns the beats (number, time in ms, bar and beat in the bar) and narration words (index, text, start, end) between two times, to cue shots to with "at". Also says which shot plays at each. Without a beat grid or narration, that part is empty and says how to add one.',
+    inputSchema: object({
+      from: { type: "number", minimum: 0, description: "From this time, ms (default 0)." },
+      to: { type: "number", minimum: 0, description: "Up to this time, ms (default: the end of the animation, or of the narration if later)." },
+      limit: { type: "integer", minimum: 1, maximum: 1e3, description: "At most this many beats and words each (default 200)." }
+    }),
+    annotations: { title: "Read the beat grid and narration", ...READ },
+    handler: ({ from = 0, to, limit = 200 }) => {
+      const s = scene();
+      const timeline = compileMotionScene(s);
+      const words = s.narration?.words ?? [];
+      const end = to ?? Math.max(timeline.duration, words.length ? words[words.length - 1].end ?? words[words.length - 1].start : 0);
+      const shotAt = (ms) => timeline.shots.find((x) => ms >= x.start && ms < x.end)?.id;
+      const beats = [];
+      if (s.beat && s.beat.bpm > 0) {
+        const first = Math.max(0, Math.ceil(motionBeatAt(s.beat, from).beat - 1e-9));
+        for (let b = first; beats.length < limit; b++) {
+          const ms = motionBeatTime(s.beat, b);
+          if (ms > end) break;
+          const at = motionBeatAt(s.beat, ms);
+          const shot = shotAt(ms);
+          beats.push({ beat: b, ms: Math.round(ms), bar: at.bar, beatInBar: at.beatInBar, ...shot ? { shot } : {} });
+        }
+      }
+      const listed = words.map((w, index) => ({ index, text: w.text, start: w.start, ...w.end !== void 0 ? { end: w.end } : {}, ...shotAt(w.start) ? { shot: shotAt(w.start) } : {} })).filter((w) => w.start >= from && w.start <= end).slice(0, limit);
+      return {
+        from,
+        to: Math.round(end),
+        ...s.beat ? { grid: s.beat, beats } : { beats: [], hint: 'No beat grid: set_animation_settings with { "beat": { "bpm": 120 } }.' },
+        ...words.length ? { words: listed } : { words: [], narrationHint: 'No narration: set_animation_settings with { "narration": { "words": [{ "text", "start" }, \u2026] } }.' }
+      };
+    }
+  };
   const exportFlairMotion = {
     name: "export_flair_motion",
     title: "Export as Flair vector motion",
@@ -2806,7 +2925,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       {
         shot: SHOT_ID,
         set: object({ id: SHOT.properties.id, ...SHOT_FIELDS }, [], "Fields to replace."),
-        remove: { type: "array", items: { type: "string", enum: ["label", "camera", "hold", "speed"] }, description: "Fields to clear." }
+        remove: { type: "array", items: { type: "string", enum: ["label", "camera", "hold", "speed", "at"] }, description: "Fields to clear." }
       },
       ["shot"]
     ),
@@ -2872,7 +2991,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
   const setSettings = {
     name: "set_animation_settings",
     title: "Change animation settings",
-    description: "Sets the name, description, loop mode, export frame rate, stepped time or target length. Returns the timing.",
+    description: "Sets the name, description, loop mode, export frame rate, stepped time, beat grid, narration word timings or target length. Returns the timing.",
     inputSchema: object(SETTINGS),
     annotations: { title: "Change animation settings", ...WRITE_IDEMPOTENT },
     handler: (args) => apply({ op: "set_settings", ...args }, "Change settings")
@@ -2950,7 +3069,7 @@ function createAnimationEditorToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getAnimation, getShot, findElements, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, seekAnimation];
+  const reads = [getAnimation, getShot, findElements, getTimingGrid, checkAnimation, renderFrame, exportFlairMotion, exportFlairEffect, seekAnimation];
   const writes = [setArtworkSvg, fitAnimation, importFlairEffect, insertShots, updateShot, deleteShots, moveShot, addCommands, updateCommand, deleteCommands, setSettings, setControls, editAnimation, writeAnimation, undo, redo];
   return {
     id: options.id ?? "animation",
@@ -2989,6 +3108,7 @@ Commands
 - Emphasis stacks on other motion: a shake during a slide shakes as it slides. Give move, rotate or scale "blend": "add" to stack them too (what they add stays); "blend": "replace" makes a change take over instead.
 - Any command but enter and exit can "repeat" (loop, mirror back and forth, or offset to carry on: rotate by 90, repeat 4 is a full turn); "duration" is one cycle.
 - Springs ("spring-gentle", "spring-quick", "spring-bouncy", "spring-slow" or { "type": "spring", \u2026 }) feel physical; leave "duration" out and the spring sets it.
+- To time shots to music or a voiceover: set a "beat" grid or "narration" word timings with set_animation_settings, read them with get_timing_grid, and give a shot "at": { "beat": n } or { "word": i }. The shot before holds until the cue; check_animation warns when a cue is missed.
 - "steps": 12 (on a command, or for the whole scene with set_animation_settings) holds poses "on twos" for a hand-drawn look. "geometric": true on scale or a camera zooms at an even rate.
 - Commands share their names and defaults with Flair's motion primitives (get_animation shows each one's "flairPrimitive"), and emphasis, reveals and follows export to Flair exactly.
 - effect tweens a numeric parameter of a live path effect already on the node (twist angle, wiggle time, zig zag size).
@@ -3052,9 +3172,12 @@ export {
   isMotionShot,
   matchMotionNodes,
   motionAddTrackKey,
+  motionBeatAt,
+  motionBeatTime,
   motionClipAttrs,
   motionCommandDuration,
   motionCommandRepeat,
+  motionCueTime,
   motionCycleDuration,
   motionFlairPrimitive,
   motionFollowRoute,