@pixerate/editor 0.232.0 → 0.233.0

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

@@ -75,6 +75,9 @@ export interface MotionShotTiming {
     cameraIn?: string;
     /** The provider camera move it plays while it holds (`camera.during`), from `commandsEnd` to `end`. */
     cameraDuring?: string;
+    /** The provider transition into it (`transition.effect`), played from `start` to `transitionEnd`. Never on the first shot. */
+    transition?: string;
+    transitionEnd?: number;
 }
 export interface MotionCommandTiming {
     shot: string;

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

@@ -75,6 +75,9 @@ export interface MotionShotTiming {
     cameraIn?: string;
     /** The provider camera move it plays while it holds (`camera.during`), from `commandsEnd` to `end`. */
     cameraDuring?: string;
+    /** The provider transition into it (`transition.effect`), played from `start` to `transitionEnd`. Never on the first shot. */
+    transition?: string;
+    transitionEnd?: number;
 }
 export interface MotionCommandTiming {
     shot: string;

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

@@ -9,10 +9,12 @@ 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 MotionCamera, type MotionScene } from './types.cjs';
+import { type MotionCamera, type MotionScene, type MotionShotLayer, type MotionShotTransition } from './types.cjs';
 import { EffectsSlot } from '../effects/helpers.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 { MotionLayersEngine, type MotionLayerHost } from './layers.cjs';
+import { type MotionShotLayerInfo, type MotionShotLayersInfo } from './layer-edit.cjs';
 import { type AppliedMotionEffect } from './effects.cjs';
 export interface AnimationEditorOptions {
     /** The scene to open (default: an empty one over a blank 800 × 450 artwork). */
@@ -30,6 +32,12 @@ export interface AnimationEditorOptions {
      * scenes keep the commands effects made. Change it later with `setEffectsProvider`.
      */
     effects?: EffectProvider | null;
+    /**
+     * Makes shot layer and transition pictures (see `MotionLayersEngine`). Default: the browser's
+     * canvas (`browserMotionLayerHost`), or none outside a browser, where effect layers are left
+     * out of frames and transitions crossfade.
+     */
+    layerHost?: MotionLayerHost | null;
 }
 /** What the effect edits return. */
 export type MotionEffectResult = {
@@ -54,6 +62,23 @@ export type MotionCameraMoveResult = {
     ok: false;
     error: string;
 };
+/** What a shot layer or transition edit did: the layer it added or changed (when there is one) and the shot's layers and transition afterwards. */
+export type MotionShotLayerResult = ({
+    ok: true;
+    layer?: MotionShotLayerInfo;
+    notes: string[];
+} & MotionShotLayersInfo) | {
+    ok: false;
+    error: string;
+};
+/** A layer as `addShotLayer` takes it: its id is made when left out. */
+export type MotionShotLayerInput = Omit<MotionShotLayer, 'id' | 'provider' | 'name'> & {
+    id?: string;
+};
+/** Changes to a layer: fields to set, and `null` to clear an optional one. */
+export type MotionShotLayerChanges = {
+    [K in Exclude<keyof MotionShotLayer, 'id' | 'provider' | 'name'>]?: MotionShotLayer[K] | null;
+};
 /** What is selected on the timeline: a shot, and optionally one of its commands. */
 export interface AnimationEditorSelection {
     shot: string;
@@ -133,6 +158,8 @@ export declare class AnimationEditorController {
     readonly player: AnimationPlayer;
     /** The effects provider slot (see `setEffectsProvider`). */
     readonly effects: EffectsSlot;
+    /** Renders shot layer and transition pictures for frames (see `MotionLayersEngine`). */
+    readonly layers: MotionLayersEngine;
     private scene;
     private issues;
     private selection;
@@ -256,8 +283,46 @@ export declare class AnimationEditorController {
     viewScene(): MotionScene;
     /** The scene at `time` (default: the playhead). */
     frame(time?: number, options?: MotionFrameOptions): MotionFrame;
-    /** The scene at `time` (default: the playhead) as SVG. */
+    /**
+     * The scene at `time` (default: the playhead) as SVG. Shot layer and transition pictures that
+     * are not rendered yet are left out (a transition crossfades) and come in on a later frame;
+     * `toSvgExact` waits for them.
+     */
     toSvg(time?: number, options?: MotionSvgOptions & MotionOverlayOptions): string;
+    /** Like `toSvg`, once every shot layer and transition picture of the frame is rendered (or has failed). */
+    toSvgExact(time?: number, options?: MotionSvgOptions & MotionOverlayOptions): Promise<string>;
+    /** Every shot's layers and transition (or one shot's). Throws for an unknown shot, naming the shots. */
+    shotLayers(shot?: string): MotionShotLayersInfo[];
+    private noShot;
+    private noLayer;
+    private layerResult;
+    private layerEdit;
+    /**
+     * Adds a layer to a shot: a provider effect (a generator, filter, overlay or title), optionally
+     * applied to a `subject`, or a bare subject. Checked against the provider first; at `index`
+     * (default the top). One undo step. Returns the layer (with its id) and the shot's layers.
+     */
+    addShotLayer(shot: string, layer: MotionShotLayerInput, options?: {
+        index?: number;
+    }): Promise<MotionShotLayerResult>;
+    /** Changes a layer's fields (`null` clears an optional one); the result is checked against the provider. One undo step (`merge` folds a slider drag into one). */
+    updateShotLayer(layer: string, changes: MotionShotLayerChanges, options?: {
+        merge?: string;
+    }): Promise<MotionShotLayerResult>;
+    /** Removes a layer. One undo step. Works without a provider. */
+    removeShotLayer(layer: string): Promise<MotionShotLayerResult>;
+    /** Moves a layer to `index` in its shot (0 = bottom). One undo step. */
+    moveShotLayer(layer: string, index: number): Promise<MotionShotLayerResult>;
+    /**
+     * Sets the provider transition into a shot from the shot before (not the first shot). Checked
+     * against the provider (its use, preset and values; its length is written out). With no camera
+     * move in, the camera cuts. One undo step (`merge` folds a slider drag into one).
+     */
+    setShotTransition(shot: string, transition: MotionShotTransition, options?: {
+        merge?: string;
+    }): Promise<MotionShotLayerResult>;
+    /** Removes a shot's transition. One undo step. Works without a provider. */
+    clearShotTransition(shot: string): MotionShotLayerResult;
     /**
      * Starts recording a take: the playhead goes to where the take's shot will start (default:
      * the end of the scene) and plays on, and every `recordSample` (or stage gesture) is a value

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

@@ -9,10 +9,12 @@ 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 MotionCamera, type MotionScene } from './types.js';
+import { type MotionCamera, type MotionScene, type MotionShotLayer, type MotionShotTransition } from './types.js';
 import { EffectsSlot } from '../effects/helpers.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 { MotionLayersEngine, type MotionLayerHost } from './layers.js';
+import { type MotionShotLayerInfo, type MotionShotLayersInfo } from './layer-edit.js';
 import { type AppliedMotionEffect } from './effects.js';
 export interface AnimationEditorOptions {
     /** The scene to open (default: an empty one over a blank 800 × 450 artwork). */
@@ -30,6 +32,12 @@ export interface AnimationEditorOptions {
      * scenes keep the commands effects made. Change it later with `setEffectsProvider`.
      */
     effects?: EffectProvider | null;
+    /**
+     * Makes shot layer and transition pictures (see `MotionLayersEngine`). Default: the browser's
+     * canvas (`browserMotionLayerHost`), or none outside a browser, where effect layers are left
+     * out of frames and transitions crossfade.
+     */
+    layerHost?: MotionLayerHost | null;
 }
 /** What the effect edits return. */
 export type MotionEffectResult = {
@@ -54,6 +62,23 @@ export type MotionCameraMoveResult = {
     ok: false;
     error: string;
 };
+/** What a shot layer or transition edit did: the layer it added or changed (when there is one) and the shot's layers and transition afterwards. */
+export type MotionShotLayerResult = ({
+    ok: true;
+    layer?: MotionShotLayerInfo;
+    notes: string[];
+} & MotionShotLayersInfo) | {
+    ok: false;
+    error: string;
+};
+/** A layer as `addShotLayer` takes it: its id is made when left out. */
+export type MotionShotLayerInput = Omit<MotionShotLayer, 'id' | 'provider' | 'name'> & {
+    id?: string;
+};
+/** Changes to a layer: fields to set, and `null` to clear an optional one. */
+export type MotionShotLayerChanges = {
+    [K in Exclude<keyof MotionShotLayer, 'id' | 'provider' | 'name'>]?: MotionShotLayer[K] | null;
+};
 /** What is selected on the timeline: a shot, and optionally one of its commands. */
 export interface AnimationEditorSelection {
     shot: string;
@@ -133,6 +158,8 @@ export declare class AnimationEditorController {
     readonly player: AnimationPlayer;
     /** The effects provider slot (see `setEffectsProvider`). */
     readonly effects: EffectsSlot;
+    /** Renders shot layer and transition pictures for frames (see `MotionLayersEngine`). */
+    readonly layers: MotionLayersEngine;
     private scene;
     private issues;
     private selection;
@@ -256,8 +283,46 @@ export declare class AnimationEditorController {
     viewScene(): MotionScene;
     /** The scene at `time` (default: the playhead). */
     frame(time?: number, options?: MotionFrameOptions): MotionFrame;
-    /** The scene at `time` (default: the playhead) as SVG. */
+    /**
+     * The scene at `time` (default: the playhead) as SVG. Shot layer and transition pictures that
+     * are not rendered yet are left out (a transition crossfades) and come in on a later frame;
+     * `toSvgExact` waits for them.
+     */
     toSvg(time?: number, options?: MotionSvgOptions & MotionOverlayOptions): string;
+    /** Like `toSvg`, once every shot layer and transition picture of the frame is rendered (or has failed). */
+    toSvgExact(time?: number, options?: MotionSvgOptions & MotionOverlayOptions): Promise<string>;
+    /** Every shot's layers and transition (or one shot's). Throws for an unknown shot, naming the shots. */
+    shotLayers(shot?: string): MotionShotLayersInfo[];
+    private noShot;
+    private noLayer;
+    private layerResult;
+    private layerEdit;
+    /**
+     * Adds a layer to a shot: a provider effect (a generator, filter, overlay or title), optionally
+     * applied to a `subject`, or a bare subject. Checked against the provider first; at `index`
+     * (default the top). One undo step. Returns the layer (with its id) and the shot's layers.
+     */
+    addShotLayer(shot: string, layer: MotionShotLayerInput, options?: {
+        index?: number;
+    }): Promise<MotionShotLayerResult>;
+    /** Changes a layer's fields (`null` clears an optional one); the result is checked against the provider. One undo step (`merge` folds a slider drag into one). */
+    updateShotLayer(layer: string, changes: MotionShotLayerChanges, options?: {
+        merge?: string;
+    }): Promise<MotionShotLayerResult>;
+    /** Removes a layer. One undo step. Works without a provider. */
+    removeShotLayer(layer: string): Promise<MotionShotLayerResult>;
+    /** Moves a layer to `index` in its shot (0 = bottom). One undo step. */
+    moveShotLayer(layer: string, index: number): Promise<MotionShotLayerResult>;
+    /**
+     * Sets the provider transition into a shot from the shot before (not the first shot). Checked
+     * against the provider (its use, preset and values; its length is written out). With no camera
+     * move in, the camera cuts. One undo step (`merge` folds a slider drag into one).
+     */
+    setShotTransition(shot: string, transition: MotionShotTransition, options?: {
+        merge?: string;
+    }): Promise<MotionShotLayerResult>;
+    /** Removes a shot's transition. One undo step. Works without a provider. */
+    clearShotTransition(shot: string): MotionShotLayerResult;
     /**
      * Starts recording a take: the playhead goes to where the take's shot will start (default:
      * the end of the scene) and plays on, and every `recordSample` (or stage gesture) is a value

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

@@ -27,7 +27,7 @@ export type MotionEdit = {
     op: 'update_shot';
     shot: string;
     set?: Partial<MotionShot>;
-    remove?: ('label' | 'camera' | 'hold' | 'speed' | 'at')[];
+    remove?: ('label' | 'camera' | 'hold' | 'speed' | 'at' | 'layers' | 'transition')[];
 } | {
     op: 'delete_shots';
     shots: string[];

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

@@ -27,7 +27,7 @@ export type MotionEdit = {
     op: 'update_shot';
     shot: string;
     set?: Partial<MotionShot>;
-    remove?: ('label' | 'camera' | 'hold' | 'speed' | 'at')[];
+    remove?: ('label' | 'camera' | 'hold' | 'speed' | 'at' | 'layers' | 'transition')[];
 } | {
     op: 'delete_shots';
     shots: string[];

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

@@ -4,6 +4,7 @@ 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 MotionLayerPictures } from './layers.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,
@@ -48,6 +49,12 @@ export interface MotionFrameOptions {
     /** An effects provider to play the shots' camera moves (`MotionCamera.in` / `during`); without one the camera eases between framings. */
     effects?: EffectProvider | null;
 }
+export interface MotionLayerFrameOptions {
+    /** Where shot layer and transition pictures come from (the controller's `MotionLayersEngine`). Without it, effect layers are left out and transitions crossfade. */
+    layers?: MotionLayerPictures;
+    /** Play shot transitions (default true). Off draws each shot's own frame. */
+    transitions?: boolean;
+}
 /** Id of the trim effect that draws strokes on. */
 export declare const MOTION_DRAW_EFFECT_ID = "~draw";
 /** A copy of the scene with each control's default colour replaced by its value (exact, case-insensitive matches). */
@@ -84,7 +91,7 @@ export declare function motionNodeClips(id: string, timeline: MotionTimeline, ti
  * function of time, so frames can be drawn in any order (and the same frames come out every time).
  */
 export declare function motionFrameAt(scene: MotionScene, time: number, options?: MotionFrameOptions): MotionFrame;
-export interface MotionSvgOptions extends MotionFrameOptions, VectorSvgExportOptions {
+export interface MotionSvgOptions extends MotionFrameOptions, MotionLayerFrameOptions, VectorSvgExportOptions {
 }
 /** A clip shape's SVG attributes. */
 export declare function motionClipAttrs(clip: MotionClipShape): Record<string, number>;

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

@@ -4,6 +4,7 @@ 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 MotionLayerPictures } from './layers.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,
@@ -48,6 +49,12 @@ export interface MotionFrameOptions {
     /** An effects provider to play the shots' camera moves (`MotionCamera.in` / `during`); without one the camera eases between framings. */
     effects?: EffectProvider | null;
 }
+export interface MotionLayerFrameOptions {
+    /** Where shot layer and transition pictures come from (the controller's `MotionLayersEngine`). Without it, effect layers are left out and transitions crossfade. */
+    layers?: MotionLayerPictures;
+    /** Play shot transitions (default true). Off draws each shot's own frame. */
+    transitions?: boolean;
+}
 /** Id of the trim effect that draws strokes on. */
 export declare const MOTION_DRAW_EFFECT_ID = "~draw";
 /** A copy of the scene with each control's default colour replaced by its value (exact, case-insensitive matches). */
@@ -84,7 +91,7 @@ export declare function motionNodeClips(id: string, timeline: MotionTimeline, ti
  * function of time, so frames can be drawn in any order (and the same frames come out every time).
  */
 export declare function motionFrameAt(scene: MotionScene, time: number, options?: MotionFrameOptions): MotionFrame;
-export interface MotionSvgOptions extends MotionFrameOptions, VectorSvgExportOptions {
+export interface MotionSvgOptions extends MotionFrameOptions, MotionLayerFrameOptions, VectorSvgExportOptions {
 }
 /** A clip shape's SVG attributes. */
 export declare function motionClipAttrs(clip: MotionClipShape): Record<string, number>;