@pixerate/editor 0.229.0 → 0.231.0

package/dist/animation-editor/camera-tools.d.cts

@@ -0,0 +1,10 @@
+/**
+ * Agent tools for provider camera moves in the animation editor (`MotionCamera.in` / `during`):
+ * list the moves by role, set one on a shot and clear it. They ride on the animation effects
+ * tool provider (`createAnimationEffectsToolProvider`), next to the other provider effects.
+ */
+import type { EffectToolContext } from '../effects/tools.cjs';
+import type { AgentTool } from '../tools/registry.cjs';
+import type { AnimationEditorController } from './controller.cjs';
+/** The camera move tools (see the module comment). */
+export declare function animationCameraMoveTools(controller: AnimationEditorController, ctx: EffectToolContext): AgentTool[];

package/dist/animation-editor/camera-tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent tools for provider camera moves in the animation editor (`MotionCamera.in` / `during`):
+ * list the moves by role, set one on a shot and clear it. They ride on the animation effects
+ * tool provider (`createAnimationEffectsToolProvider`), next to the other provider effects.
+ */
+import type { EffectToolContext } from '../effects/tools.js';
+import type { AgentTool } from '../tools/registry.js';
+import type { AnimationEditorController } from './controller.js';
+/** The camera move tools (see the module comment). */
+export declare function animationCameraMoveTools(controller: AnimationEditorController, ctx: EffectToolContext): AgentTool[];

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

@@ -0,0 +1,67 @@
+/**
+ * Provider camera moves in the animation editor (see `MotionCamera.in` / `during` and
+ * `@pixerate/editor/effects`). The compiled camera track still eases a box from framing to
+ * framing; with a provider that has camera moves (`capabilities.supportsCamera`) the camera's
+ * view comes from the provider's `cameraView` while a move plays, and stays where a hold move
+ * left it until the next framing. Without one, every function here returns null and the box
+ * track rules, as before camera moves.
+ */
+import { type MotionIssue } from './issues.cjs';
+import type { CameraMoveRole, CameraMoveSpec, CameraStage, CameraView, EffectProvider, EffectSummary } from '../effects/types.cjs';
+import type { MotionRect, MotionScene, MotionShot } from './types.cjs';
+/** When a shot's camera plays a move (or, after a hold move, eases from where it left off). */
+export interface MotionCameraWindow {
+    shot: string;
+    /** `in` and `during` play a provider move; `ease` eases from a hold move's last view to the next framing. */
+    kind: 'in' | 'during' | 'ease';
+    /** The move's id (`in` and `during`). */
+    move?: string;
+    values?: Record<string, unknown>;
+    start: number;
+    end: number;
+    from: CameraView;
+    to: CameraView;
+    /** Where the camera is when the window ends and until the next one, or null when the box track takes over again. */
+    after: CameraView | null;
+}
+/** A shot's camera move for a role as its parts (`{ move, ms?, preset?, values? }`), or undefined. */
+export declare function motionShotCameraMove(shot: MotionShot | undefined, role: CameraMoveRole): Exclude<CameraMoveSpec, string> | undefined;
+/** The stage a scene's camera looks at: its artwork's size. */
+export declare const motionCameraStage: (scene: MotionScene) => CameraStage;
+/** True when a provider can play camera moves. */
+export declare const effectsPlayCamera: (provider: EffectProvider | null | undefined) => provider is EffectProvider & {
+    cameraView: NonNullable<EffectProvider["cameraView"]>;
+};
+/** A provider's camera moves of a role (all of them with no role), in catalog order. Empty without camera support. */
+export declare function motionCameraMoves(provider: EffectProvider | null | undefined, role?: CameraMoveRole): Promise<EffectSummary[]>;
+/**
+ * Where the scene's camera plays provider moves, in time order. Empty without a provider that
+ * plays camera moves, or when no shot names one. Cached per compiled scene and provider.
+ */
+export declare function motionCameraWindows(scene: MotionScene, provider: EffectProvider | null | undefined): MotionCameraWindow[];
+/**
+ * Where the camera looks at `time` (ms) when a provider camera move decides it: during a move,
+ * and after a hold move until the next framing. Null otherwise (the camera box track rules), and
+ * always null without a provider that plays camera moves.
+ */
+export declare function motionCameraViewAt(scene: MotionScene, time: number, provider: EffectProvider | null | undefined): CameraView | null;
+/** The camera box a view shows (what becomes the SVG `viewBox`). */
+export declare function motionCameraBox(view: CameraView, scene: MotionScene): MotionRect;
+/**
+ * The CSS `transform` for a view's tilt and turn on a stage element `width` pixels wide (they
+ * are 3D, so an SVG cannot draw them): `perspective(…) rotateX(…) rotateY(…)`, or `''` when flat.
+ * The roll and the blur are drawn in the frame's SVG.
+ */
+export declare function motionCameraTransform(view: CameraView | null | undefined, width: number): string;
+/**
+ * The SVG with a view's roll and motion blur applied round its content: a rotation about the
+ * middle of the view's box, and a Gaussian blur (`blur` stage pixels, streaked along `blurAngle`
+ * as an axis-aligned approximation).
+ */
+export declare function withCameraViewEffects(svg: string, view: CameraView | null | undefined, box: MotionRect, idPrefix?: string): string;
+/**
+ * Problems with the scene's camera moves against a provider: moves it does not have or of the
+ * wrong role, and presets or values that do not fit (errors), or, without a provider that has
+ * camera moves, a note that they are not played.
+ */
+export declare function checkMotionCameraMoves(scene: MotionScene, provider: EffectProvider | null | undefined): Promise<MotionIssue[]>;

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

@@ -0,0 +1,67 @@
+/**
+ * Provider camera moves in the animation editor (see `MotionCamera.in` / `during` and
+ * `@pixerate/editor/effects`). The compiled camera track still eases a box from framing to
+ * framing; with a provider that has camera moves (`capabilities.supportsCamera`) the camera's
+ * view comes from the provider's `cameraView` while a move plays, and stays where a hold move
+ * left it until the next framing. Without one, every function here returns null and the box
+ * track rules, as before camera moves.
+ */
+import { type MotionIssue } from './issues.js';
+import type { CameraMoveRole, CameraMoveSpec, CameraStage, CameraView, EffectProvider, EffectSummary } from '../effects/types.js';
+import type { MotionRect, MotionScene, MotionShot } from './types.js';
+/** When a shot's camera plays a move (or, after a hold move, eases from where it left off). */
+export interface MotionCameraWindow {
+    shot: string;
+    /** `in` and `during` play a provider move; `ease` eases from a hold move's last view to the next framing. */
+    kind: 'in' | 'during' | 'ease';
+    /** The move's id (`in` and `during`). */
+    move?: string;
+    values?: Record<string, unknown>;
+    start: number;
+    end: number;
+    from: CameraView;
+    to: CameraView;
+    /** Where the camera is when the window ends and until the next one, or null when the box track takes over again. */
+    after: CameraView | null;
+}
+/** A shot's camera move for a role as its parts (`{ move, ms?, preset?, values? }`), or undefined. */
+export declare function motionShotCameraMove(shot: MotionShot | undefined, role: CameraMoveRole): Exclude<CameraMoveSpec, string> | undefined;
+/** The stage a scene's camera looks at: its artwork's size. */
+export declare const motionCameraStage: (scene: MotionScene) => CameraStage;
+/** True when a provider can play camera moves. */
+export declare const effectsPlayCamera: (provider: EffectProvider | null | undefined) => provider is EffectProvider & {
+    cameraView: NonNullable<EffectProvider["cameraView"]>;
+};
+/** A provider's camera moves of a role (all of them with no role), in catalog order. Empty without camera support. */
+export declare function motionCameraMoves(provider: EffectProvider | null | undefined, role?: CameraMoveRole): Promise<EffectSummary[]>;
+/**
+ * Where the scene's camera plays provider moves, in time order. Empty without a provider that
+ * plays camera moves, or when no shot names one. Cached per compiled scene and provider.
+ */
+export declare function motionCameraWindows(scene: MotionScene, provider: EffectProvider | null | undefined): MotionCameraWindow[];
+/**
+ * Where the camera looks at `time` (ms) when a provider camera move decides it: during a move,
+ * and after a hold move until the next framing. Null otherwise (the camera box track rules), and
+ * always null without a provider that plays camera moves.
+ */
+export declare function motionCameraViewAt(scene: MotionScene, time: number, provider: EffectProvider | null | undefined): CameraView | null;
+/** The camera box a view shows (what becomes the SVG `viewBox`). */
+export declare function motionCameraBox(view: CameraView, scene: MotionScene): MotionRect;
+/**
+ * The CSS `transform` for a view's tilt and turn on a stage element `width` pixels wide (they
+ * are 3D, so an SVG cannot draw them): `perspective(…) rotateX(…) rotateY(…)`, or `''` when flat.
+ * The roll and the blur are drawn in the frame's SVG.
+ */
+export declare function motionCameraTransform(view: CameraView | null | undefined, width: number): string;
+/**
+ * The SVG with a view's roll and motion blur applied round its content: a rotation about the
+ * middle of the view's box, and a Gaussian blur (`blur` stage pixels, streaked along `blurAngle`
+ * as an axis-aligned approximation).
+ */
+export declare function withCameraViewEffects(svg: string, view: CameraView | null | undefined, box: MotionRect, idPrefix?: string): string;
+/**
+ * Problems with the scene's camera moves against a provider: moves it does not have or of the
+ * wrong role, and presets or values that do not fit (errors), or, without a provider that has
+ * camera moves, a note that they are not played.
+ */
+export declare function checkMotionCameraMoves(scene: MotionScene, provider: EffectProvider | null | undefined): Promise<MotionIssue[]>;

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

@@ -71,6 +71,10 @@ export interface MotionShotTiming {
     cue?: number;
     /** How late the shot starts after its cue (ms), when the shot before ran past it. */
     missedBy?: number;
+    /** The provider camera move it gets in with (`camera.in`), and when it plays (`start` to `commandsStart`). */
+    cameraIn?: string;
+    /** The provider camera move it plays while it holds (`camera.during`), from `commandsEnd` to `end`. */
+    cameraDuring?: string;
 }
 export interface MotionCommandTiming {
     shot: string;

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

@@ -71,6 +71,10 @@ export interface MotionShotTiming {
     cue?: number;
     /** How late the shot starts after its cue (ms), when the shot before ran past it. */
     missedBy?: number;
+    /** The provider camera move it gets in with (`camera.in`), and when it plays (`start` to `commandsStart`). */
+    cameraIn?: string;
+    /** The provider camera move it plays while it holds (`camera.during`), from `commandsEnd` to `end`. */
+    cameraDuring?: string;
 }
 export interface MotionCommandTiming {
     shot: string;

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

@@ -9,9 +9,9 @@ import { type MotionEdit, type MotionEditResult } from './edit.cjs';
 import { type MotionFrame, type MotionFrameOptions, type MotionSvgOptions } from './evaluate.cjs';
 import { type FlairEffectOptions, type FlairExportOptions } from './flair.cjs';
 import type { MotionIssue } from './issues.cjs';
-import type { MotionScene } from './types.cjs';
+import { type MotionCamera, type MotionScene } from './types.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
-import type { EffectProvider, EffectValue } from '../effects/types.cjs';
+import type { CameraMoveRole, CameraMoveSpec, EffectProvider, EffectSummary, EffectValue } from '../effects/types.cjs';
 import { type MotionNodePose, type MotionTake, type MotionTakeOptions, type MotionTakeResult, type MotionTakeSample } from './record.cjs';
 import { type AppliedMotionEffect } from './effects.cjs';
 export interface AnimationEditorOptions {
@@ -40,6 +40,20 @@ export type MotionEffectResult = {
     ok: false;
     error: string;
 };
+/** What setting or clearing a shot's camera move did: the shot's camera now, and (when set) when the move plays (ms). */
+export type MotionCameraMoveResult = {
+    ok: true;
+    shot: string;
+    camera: MotionCamera | null;
+    window?: {
+        start: number;
+        end: number;
+    };
+    notes: string[];
+} | {
+    ok: false;
+    error: string;
+};
 /** What is selected on the timeline: a shot, and optionally one of its commands. */
 export interface AnimationEditorSelection {
     shot: string;
@@ -204,6 +218,24 @@ export declare class AnimationEditorController {
     }): Promise<MotionEffectResult>;
     /** Removes an applied effect: its commands, shots it alone filled and a vector effect's group. One undo step. Works without a provider. */
     removeMotionEffect(instance: string): MotionEffectResult;
+    /**
+     * The provider's camera moves for a role (`transition` for a shot's `camera.in`, `hold` for its
+     * `camera.during`), or all of them. Empty without a provider that has camera moves.
+     */
+    cameraMoves(role?: CameraMoveRole): Promise<EffectSummary[]>;
+    /**
+     * Sets the camera move a shot gets in with (`transition`, its `camera.in`) or plays while it
+     * holds (`hold`, its `camera.during`). The move is checked against the provider first (its
+     * role, preset and values; a preset's values are written out), then set in one undo step.
+     * A shot with no camera gets one that keeps the framing. Returns the shot's camera and when the
+     * move plays. `merge` folds a slider drag's changes into one undo step.
+     */
+    setShotCameraMove(shot: string, role: CameraMoveRole, spec: CameraMoveSpec, options?: {
+        merge?: string;
+    }): Promise<MotionCameraMoveResult>;
+    /** Removes a shot's camera move for a role, keeping its framing (a camera left with nothing is removed). One undo step. Works without a provider. */
+    clearShotCameraMove(shot: string, role: CameraMoveRole): MotionCameraMoveResult;
+    private cameraMoveResult;
     /** Opens a scene (JSON or object). `clearHistory` drops the undo stack (opening a file); otherwise it is one undo step. */
     load(scene: MotionScene | string, options?: {
         clearHistory?: boolean;

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

@@ -9,9 +9,9 @@ import { type MotionEdit, type MotionEditResult } from './edit.js';
 import { type MotionFrame, type MotionFrameOptions, type MotionSvgOptions } from './evaluate.js';
 import { type FlairEffectOptions, type FlairExportOptions } from './flair.js';
 import type { MotionIssue } from './issues.js';
-import type { MotionScene } from './types.js';
+import { type MotionCamera, type MotionScene } from './types.js';
 import { EffectsSlot } from '../effects/helpers.js';
-import type { EffectProvider, EffectValue } from '../effects/types.js';
+import type { CameraMoveRole, CameraMoveSpec, EffectProvider, EffectSummary, EffectValue } from '../effects/types.js';
 import { type MotionNodePose, type MotionTake, type MotionTakeOptions, type MotionTakeResult, type MotionTakeSample } from './record.js';
 import { type AppliedMotionEffect } from './effects.js';
 export interface AnimationEditorOptions {
@@ -40,6 +40,20 @@ export type MotionEffectResult = {
     ok: false;
     error: string;
 };
+/** What setting or clearing a shot's camera move did: the shot's camera now, and (when set) when the move plays (ms). */
+export type MotionCameraMoveResult = {
+    ok: true;
+    shot: string;
+    camera: MotionCamera | null;
+    window?: {
+        start: number;
+        end: number;
+    };
+    notes: string[];
+} | {
+    ok: false;
+    error: string;
+};
 /** What is selected on the timeline: a shot, and optionally one of its commands. */
 export interface AnimationEditorSelection {
     shot: string;
@@ -204,6 +218,24 @@ export declare class AnimationEditorController {
     }): Promise<MotionEffectResult>;
     /** Removes an applied effect: its commands, shots it alone filled and a vector effect's group. One undo step. Works without a provider. */
     removeMotionEffect(instance: string): MotionEffectResult;
+    /**
+     * The provider's camera moves for a role (`transition` for a shot's `camera.in`, `hold` for its
+     * `camera.during`), or all of them. Empty without a provider that has camera moves.
+     */
+    cameraMoves(role?: CameraMoveRole): Promise<EffectSummary[]>;
+    /**
+     * Sets the camera move a shot gets in with (`transition`, its `camera.in`) or plays while it
+     * holds (`hold`, its `camera.during`). The move is checked against the provider first (its
+     * role, preset and values; a preset's values are written out), then set in one undo step.
+     * A shot with no camera gets one that keeps the framing. Returns the shot's camera and when the
+     * move plays. `merge` folds a slider drag's changes into one undo step.
+     */
+    setShotCameraMove(shot: string, role: CameraMoveRole, spec: CameraMoveSpec, options?: {
+        merge?: string;
+    }): Promise<MotionCameraMoveResult>;
+    /** Removes a shot's camera move for a role, keeping its framing (a camera left with nothing is removed). One undo step. Works without a provider. */
+    clearShotCameraMove(shot: string, role: CameraMoveRole): MotionCameraMoveResult;
+    private cameraMoveResult;
     /** Opens a scene (JSON or object). `clearHistory` drops the undo stack (opening a file); otherwise it is one undo step. */
     load(scene: MotionScene | string, options?: {
         clearHistory?: boolean;

package/dist/animation-editor/effect-tools.d.cts

@@ -1,7 +1,8 @@
 /**
  * Agent tools for provider effects in the animation editor: the shared effect tools on artwork
  * nodes (`apply_effect` applies a motion effect, made into commands) and `add_vector_effect`
- * for vector effects that bring their own picture.
+ * for vector effects that bring their own picture, and the camera move tools (`list_camera_moves`,
+ * `set_shot_camera_move`, `clear_shot_camera_move`).
  */
 import type { AgentToolProvider } from '../tools/registry.cjs';
 import type { AnimationEditorController } from './controller.cjs';

package/dist/animation-editor/effect-tools.d.ts

@@ -1,7 +1,8 @@
 /**
  * Agent tools for provider effects in the animation editor: the shared effect tools on artwork
  * nodes (`apply_effect` applies a motion effect, made into commands) and `add_vector_effect`
- * for vector effects that bring their own picture.
+ * for vector effects that bring their own picture, and the camera move tools (`list_camera_moves`,
+ * `set_shot_camera_move`, `clear_shot_camera_move`).
  */
 import type { AgentToolProvider } from '../tools/registry.js';
 import type { AnimationEditorController } from './controller.js';

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

@@ -3,6 +3,7 @@ import { type AffineMatrix } from '../vector/geometry.cjs';
 import { type VectorSvgExportOptions } from '../vector/svg.cjs';
 import type { VectorDocument } from '../vector/types.cjs';
 import { type MotionNodeEntry, type MotionTimeline } from './compile.cjs';
+import type { CameraView, EffectProvider } from '../effects/types.cjs';
 import type { MotionRect, MotionScene } from './types.cjs';
 /**
  * A reveal clip (`wipe`, `iris`, `split`) in the units of the node's own box: 0–1 across it,
@@ -25,6 +26,12 @@ export interface MotionFrame {
     time: number;
     document: VectorDocument;
     camera: MotionRect;
+    /**
+     * Where the camera looks when a provider camera move decides it (`MotionCamera.in` /
+     * `during`), with its tilt, turn, roll and motion blur; `camera` is then this view's box.
+     * Absent otherwise.
+     */
+    view?: CameraView;
     /**
      * Reveal clips by node id, outermost first: draw each of those nodes inside a group clipped
      * to each shape (`motionFrameToSvg` does). The vector model has no clips, so they ride here.
@@ -38,6 +45,8 @@ export interface MotionFrameOptions {
     draw?: boolean;
     /** Apply moves, turns, scales and follows (default true). Off leaves nodes where they rest. */
     offsets?: boolean;
+    /** An effects provider to play the shots' camera moves (`MotionCamera.in` / `during`); without one the camera eases between framings. */
+    effects?: EffectProvider | null;
 }
 /** Id of the trim effect that draws strokes on. */
 export declare const MOTION_DRAW_EFFECT_ID = "~draw";

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

@@ -3,6 +3,7 @@ import { type AffineMatrix } from '../vector/geometry.js';
 import { type VectorSvgExportOptions } from '../vector/svg.js';
 import type { VectorDocument } from '../vector/types.js';
 import { type MotionNodeEntry, type MotionTimeline } from './compile.js';
+import type { CameraView, EffectProvider } from '../effects/types.js';
 import type { MotionRect, MotionScene } from './types.js';
 /**
  * A reveal clip (`wipe`, `iris`, `split`) in the units of the node's own box: 0–1 across it,
@@ -25,6 +26,12 @@ export interface MotionFrame {
     time: number;
     document: VectorDocument;
     camera: MotionRect;
+    /**
+     * Where the camera looks when a provider camera move decides it (`MotionCamera.in` /
+     * `during`), with its tilt, turn, roll and motion blur; `camera` is then this view's box.
+     * Absent otherwise.
+     */
+    view?: CameraView;
     /**
      * Reveal clips by node id, outermost first: draw each of those nodes inside a group clipped
      * to each shape (`motionFrameToSvg` does). The vector model has no clips, so they ride here.
@@ -38,6 +45,8 @@ export interface MotionFrameOptions {
     draw?: boolean;
     /** Apply moves, turns, scales and follows (default true). Off leaves nodes where they rest. */
     offsets?: boolean;
+    /** An effects provider to play the shots' camera moves (`MotionCamera.in` / `during`); without one the camera eases between framings. */
+    effects?: EffectProvider | null;
 }
 /** Id of the trim effect that draws strokes on. */
 export declare const MOTION_DRAW_EFFECT_ID = "~draw";

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

@@ -1,6 +1,7 @@
 import type { MotionBehavior } from '../animation/behavior.cjs';
 import { type AnimationEasing } from '../animation/easing.cjs';
 import type { MotionScene, MotionTrigger } from './types.cjs';
+import type { EffectProvider } from '../effects/types.cjs';
 /**
  * Export to Flair (`@pixerate/flair`): a scene becomes an `SvgMotion` (one SVG plus a list of
  * from → to changes on its elements), a catalog `VectorEffect`, or an `EffectDocument` for
@@ -153,6 +154,13 @@ export interface FlairExportOptions {
      * stepped time (`strobe`). `curves` and `behaviors` override it.
      */
     flair?: string;
+    /**
+     * An effects provider to play the shots' camera moves (`MotionCamera.in` / `during`): the camera
+     * is then sampled from its views at `fps`, keeping a move's cut as a change of no length. Without
+     * one a move is written as the eased framing. Either way each camera change a move makes is
+     * tagged `<move id>@<shot id>`.
+     */
+    effects?: EffectProvider | null;
 }
 /** The Flair version exports target by default. */
 export declare const FLAIR_EXPORT_VERSION = "0.39";

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

@@ -1,6 +1,7 @@
 import type { MotionBehavior } from '../animation/behavior.js';
 import { type AnimationEasing } from '../animation/easing.js';
 import type { MotionScene, MotionTrigger } from './types.js';
+import type { EffectProvider } from '../effects/types.js';
 /**
  * Export to Flair (`@pixerate/flair`): a scene becomes an `SvgMotion` (one SVG plus a list of
  * from → to changes on its elements), a catalog `VectorEffect`, or an `EffectDocument` for
@@ -153,6 +154,13 @@ export interface FlairExportOptions {
      * stepped time (`strobe`). `curves` and `behaviors` override it.
      */
     flair?: string;
+    /**
+     * An effects provider to play the shots' camera moves (`MotionCamera.in` / `during`): the camera
+     * is then sampled from its views at `fps`, keeping a move's cut as a change of no length. Without
+     * one a move is written as the eased framing. Either way each camera change a move makes is
+     * tagged `<move id>@<shot id>`.
+     */
+    effects?: EffectProvider | null;
 }
 /** The Flair version exports target by default. */
 export declare const FLAIR_EXPORT_VERSION = "0.39";