@pixerate/editor 0.231.1 → 0.233.0

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

@@ -159,6 +159,34 @@ export declare const MOTION_ISSUE_CODES: {
         readonly severity: "error";
         readonly wording: "A camera move's preset or values do not fit its controls.";
     };
+    readonly 'layer-effect-unknown': {
+        readonly severity: "error";
+        readonly wording: "A shot layer names an effect the provider does not have, one that cannot be a layer, or a subject its effect cannot take.";
+    };
+    readonly 'layer-effect-values': {
+        readonly severity: "error";
+        readonly wording: "A shot layer's preset or values do not fit its effect's controls.";
+    };
+    readonly 'layer-not-drawn': {
+        readonly severity: "note";
+        readonly wording: "Shot layers name provider effects, but there is no effects provider to draw them, so they are left out of frames.";
+    };
+    readonly 'layer-slot-empty': {
+        readonly severity: "warning";
+        readonly wording: "A shot layer's subject is a slot nobody has filled, so it draws nothing.";
+    };
+    readonly 'transition-unknown': {
+        readonly severity: "error";
+        readonly wording: "A shot names a transition the provider does not have, or an effect that is not a transition.";
+    };
+    readonly 'transition-first-shot': {
+        readonly severity: "note";
+        readonly wording: "The first shot has a transition, but there is no shot before it, so it does not play.";
+    };
+    readonly 'transition-not-played': {
+        readonly severity: "note";
+        readonly wording: "Shots name transitions, but there is no effects provider to play them, so they crossfade.";
+    };
 };
 export type MotionIssueCode = keyof typeof MOTION_ISSUE_CODES;
 export interface MotionIssue {

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

@@ -159,6 +159,34 @@ export declare const MOTION_ISSUE_CODES: {
         readonly severity: "error";
         readonly wording: "A camera move's preset or values do not fit its controls.";
     };
+    readonly 'layer-effect-unknown': {
+        readonly severity: "error";
+        readonly wording: "A shot layer names an effect the provider does not have, one that cannot be a layer, or a subject its effect cannot take.";
+    };
+    readonly 'layer-effect-values': {
+        readonly severity: "error";
+        readonly wording: "A shot layer's preset or values do not fit its effect's controls.";
+    };
+    readonly 'layer-not-drawn': {
+        readonly severity: "note";
+        readonly wording: "Shot layers name provider effects, but there is no effects provider to draw them, so they are left out of frames.";
+    };
+    readonly 'layer-slot-empty': {
+        readonly severity: "warning";
+        readonly wording: "A shot layer's subject is a slot nobody has filled, so it draws nothing.";
+    };
+    readonly 'transition-unknown': {
+        readonly severity: "error";
+        readonly wording: "A shot names a transition the provider does not have, or an effect that is not a transition.";
+    };
+    readonly 'transition-first-shot': {
+        readonly severity: "note";
+        readonly wording: "The first shot has a transition, but there is no shot before it, so it does not play.";
+    };
+    readonly 'transition-not-played': {
+        readonly severity: "note";
+        readonly wording: "Shots name transitions, but there is no effects provider to play them, so they crossfade.";
+    };
 };
 export type MotionIssueCode = keyof typeof MOTION_ISSUE_CODES;
 export interface MotionIssue {

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

@@ -0,0 +1,55 @@
+/**
+ * Checking shot layers and transitions against an effects provider before they are saved, and
+ * describing them for tools and panels. A layer's effect must be one a layer can show (a
+ * generator, filter, overlay or title), take the subject it is given (or need none), and have
+ * values and a preset that fit; a transition's effect must have the use `transition`. A preset's
+ * values are written out, so the scene plays the same without the provider's presets.
+ */
+import { type EffectProvider } from '../effects/types.cjs';
+import { type MotionIssue } from './issues.cjs';
+import type { MotionScene, MotionShotLayer, MotionShotTransition } from './types.cjs';
+/** A layer as tools and panels report it: its fields, its shot and when it shows (ms). */
+export interface MotionShotLayerInfo extends MotionShotLayer {
+    shot: string;
+    /** Its place in the shot (0 = bottom). */
+    index: number;
+    role: NonNullable<MotionShotLayer['role']>;
+    start: number;
+    end: number;
+}
+/** A shot's layers and transition. */
+export interface MotionShotLayersInfo {
+    shot: string;
+    layers: MotionShotLayerInfo[];
+    /** Its transition with when it plays, or null (the first shot never has one). */
+    transition: (MotionShotTransition & {
+        start: number;
+        end: number;
+    }) | null;
+}
+/** Every shot's layers and transition (or one shot's). */
+export declare function motionShotLayersInfo(scene: MotionScene, shot?: string): MotionShotLayersInfo[];
+/** The shot holding a layer, and its index there. */
+export declare function findMotionShotLayer(scene: MotionScene, id: string): {
+    shot: number;
+    index: number;
+} | null;
+/** Every layer id in the scene. */
+export declare const motionLayerIds: (scene: MotionScene) => string[];
+/** A free layer id: `layer1`, `layer2`… */
+export declare function freshMotionLayerId(scene: MotionScene, base?: string): string;
+/**
+ * Checks a layer against the provider and returns it as it is saved (with the effect's provider
+ * and name, a preset's values written out). Throws a sentence saying what to do for an effect
+ * that cannot be a layer, a subject it cannot take (or a picture it needs and lacks), and values
+ * or a preset that do not fit. A bare subject (no `effect`) needs no provider.
+ */
+export declare function resolveMotionShotLayer(provider: EffectProvider | null, layer: MotionShotLayer): Promise<MotionShotLayer>;
+/** Checks a transition against the provider and returns it as it is saved (its length written out). */
+export declare function resolveMotionShotTransition(provider: EffectProvider | null, transition: MotionShotTransition): Promise<MotionShotTransition>;
+/**
+ * Problems with the scene's shot layers and transitions against a provider: effects it does not
+ * have or that do not fit (errors), empty slots (warnings), and, without a provider, notes that
+ * effect layers are not drawn and transitions crossfade.
+ */
+export declare function checkMotionShotLayers(scene: MotionScene, provider: EffectProvider | null | undefined): Promise<MotionIssue[]>;

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

@@ -0,0 +1,55 @@
+/**
+ * Checking shot layers and transitions against an effects provider before they are saved, and
+ * describing them for tools and panels. A layer's effect must be one a layer can show (a
+ * generator, filter, overlay or title), take the subject it is given (or need none), and have
+ * values and a preset that fit; a transition's effect must have the use `transition`. A preset's
+ * values are written out, so the scene plays the same without the provider's presets.
+ */
+import { type EffectProvider } from '../effects/types.js';
+import { type MotionIssue } from './issues.js';
+import type { MotionScene, MotionShotLayer, MotionShotTransition } from './types.js';
+/** A layer as tools and panels report it: its fields, its shot and when it shows (ms). */
+export interface MotionShotLayerInfo extends MotionShotLayer {
+    shot: string;
+    /** Its place in the shot (0 = bottom). */
+    index: number;
+    role: NonNullable<MotionShotLayer['role']>;
+    start: number;
+    end: number;
+}
+/** A shot's layers and transition. */
+export interface MotionShotLayersInfo {
+    shot: string;
+    layers: MotionShotLayerInfo[];
+    /** Its transition with when it plays, or null (the first shot never has one). */
+    transition: (MotionShotTransition & {
+        start: number;
+        end: number;
+    }) | null;
+}
+/** Every shot's layers and transition (or one shot's). */
+export declare function motionShotLayersInfo(scene: MotionScene, shot?: string): MotionShotLayersInfo[];
+/** The shot holding a layer, and its index there. */
+export declare function findMotionShotLayer(scene: MotionScene, id: string): {
+    shot: number;
+    index: number;
+} | null;
+/** Every layer id in the scene. */
+export declare const motionLayerIds: (scene: MotionScene) => string[];
+/** A free layer id: `layer1`, `layer2`… */
+export declare function freshMotionLayerId(scene: MotionScene, base?: string): string;
+/**
+ * Checks a layer against the provider and returns it as it is saved (with the effect's provider
+ * and name, a preset's values written out). Throws a sentence saying what to do for an effect
+ * that cannot be a layer, a subject it cannot take (or a picture it needs and lacks), and values
+ * or a preset that do not fit. A bare subject (no `effect`) needs no provider.
+ */
+export declare function resolveMotionShotLayer(provider: EffectProvider | null, layer: MotionShotLayer): Promise<MotionShotLayer>;
+/** Checks a transition against the provider and returns it as it is saved (its length written out). */
+export declare function resolveMotionShotTransition(provider: EffectProvider | null, transition: MotionShotTransition): Promise<MotionShotTransition>;
+/**
+ * Problems with the scene's shot layers and transitions against a provider: effects it does not
+ * have or that do not fit (errors), empty slots (warnings), and, without a provider, notes that
+ * effect layers are not drawn and transitions crossfade.
+ */
+export declare function checkMotionShotLayers(scene: MotionScene, provider: EffectProvider | null | undefined): Promise<MotionIssue[]>;

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

@@ -0,0 +1,11 @@
+/**
+ * Agent tools for shot layers and transitions in the animation editor (`MotionShot.layers` /
+ * `transition`): list them, add, change, restack and remove layers, and set or clear the
+ * transition into a shot. 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 shot layer and transition tools (see the module comment). */
+export declare function animationShotLayerTools(controller: AnimationEditorController, ctx: EffectToolContext): AgentTool[];

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

@@ -0,0 +1,11 @@
+/**
+ * Agent tools for shot layers and transitions in the animation editor (`MotionShot.layers` /
+ * `transition`): list them, add, change, restack and remove layers, and set or clear the
+ * transition into a shot. 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 shot layer and transition tools (see the module comment). */
+export declare function animationShotLayerTools(controller: AnimationEditorController, ctx: EffectToolContext): AgentTool[];

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

@@ -0,0 +1,166 @@
+/**
+ * Shot layers and transitions (see `MotionShotLayer`, `MotionShotTransition`): when each layer
+ * shows, how it is drawn into a frame's SVG, and `MotionLayersEngine`, which renders provider
+ * effect layers and transitions to pictures.
+ *
+ * Frames stay SVG and stay a pure function of time: a layer's pixels go into the frame as an
+ * `<image>` (`background` layers under the artwork, `subject` and `overlay` layers over it), taken
+ * from the engine's cache. A picture that is not rendered yet is left out and the engine renders it
+ * in the background, then tells the editor to draw again; `idle()` waits for every picture asked
+ * for, so `AnimationEditorController.toSvgExact` draws exact frames.
+ *
+ * A transition replaces the frame for its length with the provider's blend of the last frame of the
+ * shot before (`from`) and the live frame of its own shot (`to`). Both are drawn as SVG and turned
+ * into pixels by the host (`MotionLayerHost.rasterize`). Until it is rendered (or with no provider
+ * or host) the two frames crossfade.
+ */
+import { EffectsSlot } from '../effects/helpers.cjs';
+import type { EffectDescription, EffectLayerRole, EffectPixels, EffectProvider } from '../effects/types.cjs';
+import type { MotionLayerSubject, MotionRect, MotionScene, MotionShotLayer } from './types.cjs';
+/** When a layer shows. */
+export interface MotionLayerSpan {
+    layer: MotionShotLayer;
+    shot: string;
+    shotIndex: number;
+    /** Its place in its shot's `layers`. */
+    index: number;
+    role: EffectLayerRole;
+    start: number;
+    end: number;
+}
+/** A layer showing at a moment. */
+export interface MotionActiveLayer extends MotionLayerSpan {
+    /** Ms since the layer started: the time its effect is drawn at. */
+    time: number;
+    /** Its opacity now, with its fade. */
+    opacity: number;
+}
+/** A transition at a moment. */
+export interface MotionActiveTransition {
+    /** The shot it plays into. */
+    shot: string;
+    shotIndex: number;
+    effect: string;
+    start: number;
+    end: number;
+    /** 0 → 1 through it. */
+    progress: number;
+}
+/** Every layer of the scene with when it shows, in drawing order (shot by shot, bottom to top). Pure and cached per scene. */
+export declare function motionLayerSpans(scene: MotionScene): MotionLayerSpan[];
+/** The layers showing at `time`, in drawing order, with their effect time and faded opacity. */
+export declare function motionLayersAt(scene: MotionScene, time: number): MotionActiveLayer[];
+/** The transition playing at `time`, if any. */
+export declare function motionTransitionAt(scene: MotionScene, time: number): MotionActiveTransition | null;
+/** True when the scene has shot layers or transitions, so frames need `MotionLayerPictures`. */
+export declare const motionSceneHasLayers: (scene: MotionScene) => boolean;
+/** Where frames get layer pictures from (`MotionLayersEngine`). Each returns an image URL, or undefined while it is not ready. */
+export interface MotionLayerPictures {
+    /** The picture of an effect layer at its time (the size of its box). */
+    layer(scene: MotionScene, active: MotionActiveLayer, box: MotionRect): string | undefined;
+    /** A subject picture as a URL usable inside an SVG image (a `data:` URL). */
+    subject(subject: Extract<MotionLayerSubject, {
+        image: string;
+    }>): string | undefined;
+    /** The whole frame during a transition. */
+    transition(scene: MotionScene, time: number, active: MotionActiveTransition): string | undefined;
+}
+/** An SVG string as a `data:` URL. */
+export declare const svgDataUrl: (svg: string) => string;
+/**
+ * Adds a frame's layers to its SVG (made with the artwork's background left out): the background
+ * colour, then `background` layers, the artwork, then `subject` and `overlay` layers. Layers with
+ * no `rect` fill the camera's view.
+ */
+export declare function withMotionShotLayers(svg: string, scene: MotionScene, time: number, camera: MotionRect, pictures: MotionLayerPictures | undefined, background: boolean): string;
+/**
+ * A frame during a transition: the provider's picture filling the view, or until it is ready a
+ * crossfade of the last frame of the shot before (`from`, a whole frame SVG, nested with its own
+ * framing) and this frame.
+ */
+export declare function motionTransitionSvg(svg: string, from: string, active: MotionActiveTransition, camera: MotionRect, picture: string | undefined): string;
+/**
+ * What the engine needs from its host to make pictures: a browser host is
+ * `browserMotionLayerHost()`. Outside a browser, give one that rasterizes SVG (e.g. resvg).
+ */
+export interface MotionLayerHost {
+    /** Draws a standalone SVG into pixels of this size (straight alpha). */
+    rasterize(svg: string, width: number, height: number): Promise<EffectPixels>;
+    /** Pixels as an image URL for an SVG `<image>` (a `data:` URL). */
+    encode(pixels: EffectPixels): Promise<string> | string;
+    /** A picture URL as a `data:` URL, so it draws inside a rasterized SVG (where outside URLs do not load). */
+    loadImage(url: string): Promise<string>;
+}
+export interface MotionLayersEngineOptions {
+    slot?: EffectsSlot;
+    host?: MotionLayerHost | null;
+    /** Pixels per artwork unit of layer pictures (default 1); the longest side is at most `maxSize`. */
+    scale?: number;
+    /** Longest side of a layer or transition picture (default 1280). */
+    maxSize?: number;
+    /** Effect time is rounded to this many frames a second, so frames share pictures (default 30). */
+    fps?: number;
+    /** Pictures kept (default 160). */
+    maxEntries?: number;
+    maxRenderers?: number;
+    /** Draws a frame of a scene as SVG (the controller gives `motionFrameToSvg` with its options). */
+    frameSvg?: (scene: MotionScene, time: number) => string;
+}
+/** What a frame would draw (or wait for): failures say why a layer stays empty. */
+export interface MotionLayerFailure {
+    key: string;
+    layer?: string;
+    transition?: string;
+    error: Error;
+}
+/**
+ * Renders and caches shot layer and transition pictures for one editor. Follows the editor's
+ * provider slot: a new provider clears the cache. Without a provider (or a host) it makes no
+ * pictures, and frames draw bare subjects and crossfades only.
+ */
+export declare class MotionLayersEngine implements MotionLayerPictures {
+    readonly slot: EffectsSlot;
+    host: MotionLayerHost | null;
+    frameSvg: ((scene: MotionScene, time: number) => string) | undefined;
+    private readonly cache;
+    private readonly pending;
+    private readonly failures;
+    private readonly descriptions;
+    private readonly listeners;
+    private readonly pool;
+    private readonly options;
+    private generation;
+    private readonly detach;
+    constructor(options?: MotionLayersEngineOptions);
+    get provider(): EffectProvider | null;
+    /** Called when a picture is ready (draw the frame again). */
+    subscribe(listener: () => void): () => void;
+    /** Why pictures failed, newest last. */
+    failuresList(): MotionLayerFailure[];
+    /** True while any picture is being made. */
+    get busy(): boolean;
+    /** Resolves once every picture asked for so far is made (or failed). */
+    idle(): Promise<void>;
+    /** Forgets every picture and failure (a new provider, or the host changed). */
+    reset(): void;
+    dispose(): void;
+    private notify;
+    private size;
+    private snap;
+    private get;
+    private request;
+    describe(id: string): Promise<EffectDescription>;
+    subject(subject: {
+        image: string;
+    }): string | undefined;
+    /** The pixels a layer's subject feeds its effect, at `size`. */
+    private subjectPixels;
+    layer(scene: MotionScene, active: MotionActiveLayer, b: MotionRect): string | undefined;
+    transition(scene: MotionScene, time: number, active: MotionActiveTransition): string | undefined;
+    private readonly fromPixels;
+    private idleExcept;
+}
+/** A host that draws with the browser's canvas and image decoding, or null outside a browser. */
+export declare function browserMotionLayerHost(doc?: Document | undefined): MotionLayerHost | null;
+/** Whether a scene's layer would draw nothing because its subject slot is empty. */
+export declare const motionLayerSlot: (layer: MotionShotLayer) => string | undefined;

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

@@ -0,0 +1,166 @@
+/**
+ * Shot layers and transitions (see `MotionShotLayer`, `MotionShotTransition`): when each layer
+ * shows, how it is drawn into a frame's SVG, and `MotionLayersEngine`, which renders provider
+ * effect layers and transitions to pictures.
+ *
+ * Frames stay SVG and stay a pure function of time: a layer's pixels go into the frame as an
+ * `<image>` (`background` layers under the artwork, `subject` and `overlay` layers over it), taken
+ * from the engine's cache. A picture that is not rendered yet is left out and the engine renders it
+ * in the background, then tells the editor to draw again; `idle()` waits for every picture asked
+ * for, so `AnimationEditorController.toSvgExact` draws exact frames.
+ *
+ * A transition replaces the frame for its length with the provider's blend of the last frame of the
+ * shot before (`from`) and the live frame of its own shot (`to`). Both are drawn as SVG and turned
+ * into pixels by the host (`MotionLayerHost.rasterize`). Until it is rendered (or with no provider
+ * or host) the two frames crossfade.
+ */
+import { EffectsSlot } from '../effects/helpers.js';
+import type { EffectDescription, EffectLayerRole, EffectPixels, EffectProvider } from '../effects/types.js';
+import type { MotionLayerSubject, MotionRect, MotionScene, MotionShotLayer } from './types.js';
+/** When a layer shows. */
+export interface MotionLayerSpan {
+    layer: MotionShotLayer;
+    shot: string;
+    shotIndex: number;
+    /** Its place in its shot's `layers`. */
+    index: number;
+    role: EffectLayerRole;
+    start: number;
+    end: number;
+}
+/** A layer showing at a moment. */
+export interface MotionActiveLayer extends MotionLayerSpan {
+    /** Ms since the layer started: the time its effect is drawn at. */
+    time: number;
+    /** Its opacity now, with its fade. */
+    opacity: number;
+}
+/** A transition at a moment. */
+export interface MotionActiveTransition {
+    /** The shot it plays into. */
+    shot: string;
+    shotIndex: number;
+    effect: string;
+    start: number;
+    end: number;
+    /** 0 → 1 through it. */
+    progress: number;
+}
+/** Every layer of the scene with when it shows, in drawing order (shot by shot, bottom to top). Pure and cached per scene. */
+export declare function motionLayerSpans(scene: MotionScene): MotionLayerSpan[];
+/** The layers showing at `time`, in drawing order, with their effect time and faded opacity. */
+export declare function motionLayersAt(scene: MotionScene, time: number): MotionActiveLayer[];
+/** The transition playing at `time`, if any. */
+export declare function motionTransitionAt(scene: MotionScene, time: number): MotionActiveTransition | null;
+/** True when the scene has shot layers or transitions, so frames need `MotionLayerPictures`. */
+export declare const motionSceneHasLayers: (scene: MotionScene) => boolean;
+/** Where frames get layer pictures from (`MotionLayersEngine`). Each returns an image URL, or undefined while it is not ready. */
+export interface MotionLayerPictures {
+    /** The picture of an effect layer at its time (the size of its box). */
+    layer(scene: MotionScene, active: MotionActiveLayer, box: MotionRect): string | undefined;
+    /** A subject picture as a URL usable inside an SVG image (a `data:` URL). */
+    subject(subject: Extract<MotionLayerSubject, {
+        image: string;
+    }>): string | undefined;
+    /** The whole frame during a transition. */
+    transition(scene: MotionScene, time: number, active: MotionActiveTransition): string | undefined;
+}
+/** An SVG string as a `data:` URL. */
+export declare const svgDataUrl: (svg: string) => string;
+/**
+ * Adds a frame's layers to its SVG (made with the artwork's background left out): the background
+ * colour, then `background` layers, the artwork, then `subject` and `overlay` layers. Layers with
+ * no `rect` fill the camera's view.
+ */
+export declare function withMotionShotLayers(svg: string, scene: MotionScene, time: number, camera: MotionRect, pictures: MotionLayerPictures | undefined, background: boolean): string;
+/**
+ * A frame during a transition: the provider's picture filling the view, or until it is ready a
+ * crossfade of the last frame of the shot before (`from`, a whole frame SVG, nested with its own
+ * framing) and this frame.
+ */
+export declare function motionTransitionSvg(svg: string, from: string, active: MotionActiveTransition, camera: MotionRect, picture: string | undefined): string;
+/**
+ * What the engine needs from its host to make pictures: a browser host is
+ * `browserMotionLayerHost()`. Outside a browser, give one that rasterizes SVG (e.g. resvg).
+ */
+export interface MotionLayerHost {
+    /** Draws a standalone SVG into pixels of this size (straight alpha). */
+    rasterize(svg: string, width: number, height: number): Promise<EffectPixels>;
+    /** Pixels as an image URL for an SVG `<image>` (a `data:` URL). */
+    encode(pixels: EffectPixels): Promise<string> | string;
+    /** A picture URL as a `data:` URL, so it draws inside a rasterized SVG (where outside URLs do not load). */
+    loadImage(url: string): Promise<string>;
+}
+export interface MotionLayersEngineOptions {
+    slot?: EffectsSlot;
+    host?: MotionLayerHost | null;
+    /** Pixels per artwork unit of layer pictures (default 1); the longest side is at most `maxSize`. */
+    scale?: number;
+    /** Longest side of a layer or transition picture (default 1280). */
+    maxSize?: number;
+    /** Effect time is rounded to this many frames a second, so frames share pictures (default 30). */
+    fps?: number;
+    /** Pictures kept (default 160). */
+    maxEntries?: number;
+    maxRenderers?: number;
+    /** Draws a frame of a scene as SVG (the controller gives `motionFrameToSvg` with its options). */
+    frameSvg?: (scene: MotionScene, time: number) => string;
+}
+/** What a frame would draw (or wait for): failures say why a layer stays empty. */
+export interface MotionLayerFailure {
+    key: string;
+    layer?: string;
+    transition?: string;
+    error: Error;
+}
+/**
+ * Renders and caches shot layer and transition pictures for one editor. Follows the editor's
+ * provider slot: a new provider clears the cache. Without a provider (or a host) it makes no
+ * pictures, and frames draw bare subjects and crossfades only.
+ */
+export declare class MotionLayersEngine implements MotionLayerPictures {
+    readonly slot: EffectsSlot;
+    host: MotionLayerHost | null;
+    frameSvg: ((scene: MotionScene, time: number) => string) | undefined;
+    private readonly cache;
+    private readonly pending;
+    private readonly failures;
+    private readonly descriptions;
+    private readonly listeners;
+    private readonly pool;
+    private readonly options;
+    private generation;
+    private readonly detach;
+    constructor(options?: MotionLayersEngineOptions);
+    get provider(): EffectProvider | null;
+    /** Called when a picture is ready (draw the frame again). */
+    subscribe(listener: () => void): () => void;
+    /** Why pictures failed, newest last. */
+    failuresList(): MotionLayerFailure[];
+    /** True while any picture is being made. */
+    get busy(): boolean;
+    /** Resolves once every picture asked for so far is made (or failed). */
+    idle(): Promise<void>;
+    /** Forgets every picture and failure (a new provider, or the host changed). */
+    reset(): void;
+    dispose(): void;
+    private notify;
+    private size;
+    private snap;
+    private get;
+    private request;
+    describe(id: string): Promise<EffectDescription>;
+    subject(subject: {
+        image: string;
+    }): string | undefined;
+    /** The pixels a layer's subject feeds its effect, at `size`. */
+    private subjectPixels;
+    layer(scene: MotionScene, active: MotionActiveLayer, b: MotionRect): string | undefined;
+    transition(scene: MotionScene, time: number, active: MotionActiveTransition): string | undefined;
+    private readonly fromPixels;
+    private idleExcept;
+}
+/** A host that draws with the browser's canvas and image decoding, or null outside a browser. */
+export declare function browserMotionLayerHost(doc?: Document | undefined): MotionLayerHost | null;
+/** Whether a scene's layer would draw nothing because its subject slot is empty. */
+export declare const motionLayerSlot: (layer: MotionShotLayer) => string | undefined;

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

@@ -17,6 +17,8 @@ export declare function clipsShapeProblems(clips: unknown): string[];
 export declare function driversShapeProblems(drivers: unknown): string[];
 /** Problems with one shot's shape. */
 export declare function shotShapeProblems(shot: unknown, where: string): string[];
+/** Problems with a shot's `layers` and `transition`. */
+export declare function shotLayersShapeProblems(shot: Record<string, unknown>, name: string): string[];
 /** Problems with a scene's shape (empty when well formed). */
 export declare function motionSceneShapeProblems(input: unknown): string[];
 /** Reads a scene from JSON (a string or a parsed value). Throws `MotionSceneFormatError` listing every problem. */

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

@@ -17,6 +17,8 @@ export declare function clipsShapeProblems(clips: unknown): string[];
 export declare function driversShapeProblems(drivers: unknown): string[];
 /** Problems with one shot's shape. */
 export declare function shotShapeProblems(shot: unknown, where: string): string[];
+/** Problems with a shot's `layers` and `transition`. */
+export declare function shotLayersShapeProblems(shot: Record<string, unknown>, name: string): string[];
 /** Problems with a scene's shape (empty when well formed). */
 export declare function motionSceneShapeProblems(input: unknown): string[];
 /** Reads a scene from JSON (a string or a parsed value). Throws `MotionSceneFormatError` listing every problem. */

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

@@ -1,4 +1,4 @@
-import type { CameraMoveSpec, EffectValue } from '../effects/types.cjs';
+import type { CameraMoveSpec, EffectLayer, EffectShotTransition, EffectValue } from '../effects/types.cjs';
 import type { AnimationEasing } from '../animation/easing.cjs';
 import type { AnimationLoopMode } from '../animation/evaluate.cjs';
 import type { VectorDocument } from '../vector/types.cjs';
@@ -153,6 +153,49 @@ export interface MotionShot {
      * durations, staggers and hold all scale by 1 / speed. `fit_animation` sets it to fit a length.
      */
     speed?: number;
+    /**
+     * Provider effects and pictures shown with the shot, bottom to top (see `MotionShotLayer`):
+     * `background` layers under the artwork, `subject` and `overlay` layers over it.
+     */
+    layers?: MotionShotLayer[];
+    /**
+     * How the shot before gives way to this one: a provider transition effect blends the last
+     * frame of the shot before into this shot over `ms`. With no camera `in`, the camera cuts.
+     */
+    transition?: MotionShotTransition;
+}
+/** What a shot layer shows or feeds its effect: a picture or SVG (URL, `data:` URL or markup), words, or a `slot` the host fills. */
+export type MotionLayerSubject = {
+    image: string;
+} | {
+    svg: string;
+} | {
+    text: string;
+    font?: string;
+    weight?: number | string;
+} | {
+    slot: string;
+};
+/**
+ * A layer of a shot (the shape of Flair's `SceneLayer` and the effects contract's
+ * `EffectLayer`): a provider effect (a generator, filter, overlay or title), optionally applied
+ * to a `subject`, or a bare subject. It lasts from `from` to `until` (default: from the shot's
+ * start until the next shot starts), placed at `rect` in artwork units (moving with the camera)
+ * or filling the screen.
+ */
+export interface MotionShotLayer extends Omit<EffectLayer, 'id' | 'subject'> {
+    /** Unique in the scene (e.g. `layer1`). */
+    id: string;
+    subject?: MotionLayerSubject;
+    /** The provider it was added with (its `id`). */
+    provider?: string;
+    /** The effect's name when it was added, shown where no provider can draw it. */
+    name?: string;
+}
+/** A provider transition into a shot (the effects contract's `EffectShotTransition`). */
+export interface MotionShotTransition extends EffectShotTransition {
+    provider?: string;
+    name?: string;
 }
 /** How `split` splits outlined text. */
 export type MotionTextUnit = 'letter' | 'word' | 'line';