@pixerate/editor 0.233.0 → 0.235.0

package/dist/animation-editor/index.js

@@ -1,9 +1,3 @@
-import {
-  effectLayerInput,
-  effectLayerOffered,
-  effectLayerRole,
-  effectSubjectKind
-} from "../chunk-I277KJLQ.js";
 import {
   createVectorMorph
 } from "../chunk-YMREOA67.js";
@@ -15,6 +9,14 @@ import {
   namedWithSuggestion,
   suggestName
 } from "../chunk-EUKY4KFX.js";
+import {
+  effectLayerInput,
+  effectLayerOffered,
+  effectLayerRole,
+  effectSubjectKind,
+  effectTemplateTools,
+  fillEffectTemplate
+} from "../chunk-G3RUKJ5C.js";
 import {
   IDENTITY_MATRIX,
   applyMatrix,
@@ -1802,7 +1804,10 @@ var MotionLayersEngine = class {
     this.reset();
     this.listeners.clear();
   }
+  /** Goes up each time pictures come in or are cleared, so a view that caches frames knows to draw again. */
+  revision = 0;
   notify() {
+    this.revision++;
     this.listeners.forEach((l) => l());
   }
   size(b) {
@@ -4484,6 +4489,57 @@ async function checkMotionShotLayers(scene, provider) {
   return issues;
 }
 
+// src/animation-editor/sequence.ts
+var fresh = (used, base) => {
+  const clean = base.replace(/[^\w.-]+/g, "-").replace(/^[^A-Za-z_]+/, "") || "item";
+  if (!used.has(clean)) return used.add(clean), clean;
+  for (let i = 2; ; i++) if (!used.has(`${clean}-${i}`)) return used.add(`${clean}-${i}`), `${clean}-${i}`;
+};
+function motionShotsFromSequence(sequence, options = {}) {
+  const sx = (options.width ?? sequence.stage.width) / sequence.stage.width;
+  const sy = (options.height ?? sequence.stage.height) / sequence.stage.height;
+  const scale = (r) => ({ x: r.x * sx, y: r.y * sy, width: r.width * sx, height: r.height * sy });
+  const full = { x: 0, y: 0, width: sequence.stage.width * sx, height: sequence.stage.height * sy };
+  const shotIds = new Set(options.shotIds ?? []);
+  const layerIds = new Set(options.layerIds ?? []);
+  const notes = [];
+  const provider = options.provider ? { provider: options.provider } : {};
+  const shots = sequence.shots.map((s, i) => {
+    const id = fresh(shotIds, `shot${i + 1}`);
+    const framing = s.camera?.framing ? scale(s.camera.framing) : void 0;
+    const view = framing ?? full;
+    const layers = [];
+    for (const layer of s.layers) {
+      if (layer.subject && "video" in layer.subject) {
+        notes.push(`Shot ${i + 1}: a layer plays a video, which an animation cannot; it was left out (the video editor plays it).`);
+        continue;
+      }
+      const { id: given, rect, subject, ...rest } = layer;
+      layers.push({ ...rest, id: fresh(layerIds, given ?? "layer"), ...subject ? { subject } : {}, ...rect ? { rect: scale(rect) } : {}, ...layer.effect ? provider : {} });
+    }
+    if (s.title) layers.push({ id: fresh(layerIds, `${id}-title`), subject: { text: s.title }, role: "overlay", rect: { x: view.x + view.width * 0.1, y: view.y + view.height * 0.38, width: view.width * 0.8, height: view.height * 0.24 } });
+    if (s.caption) layers.push({ id: fresh(layerIds, `${id}-caption`), subject: { text: s.caption }, role: "overlay", rect: { x: view.x + view.width * 0.1, y: view.y + view.height * 0.8, width: view.width * 0.8, height: view.height * 0.1 } });
+    const camera = framing || s.camera?.in !== void 0 || s.camera?.during !== void 0 ? { ...framing ?? {}, ...s.camera?.in !== void 0 ? { in: s.camera.in } : {}, ...s.camera?.during !== void 0 ? { during: s.camera.during } : {} } : void 0;
+    return {
+      id,
+      label: s.title ?? s.caption ?? `Shot ${i + 1}`,
+      ...camera ? { camera } : {},
+      run: [],
+      hold: s.hold,
+      ...layers.length ? { layers } : {},
+      ...i > 0 && s.transition ? { transition: { ...s.transition, ...provider } } : {}
+    };
+  });
+  return { shots, notes };
+}
+function motionSceneFromSequence(sequence, options = {}) {
+  const { shots, notes } = motionShotsFromSequence(sequence, options);
+  return {
+    scene: { version: 1, name: sequence.name, ...sequence.title ? { description: sequence.title } : {}, artwork: { width: sequence.stage.width, height: sequence.stage.height, background: options.background ?? "#000000", nodes: [] }, shots },
+    notes
+  };
+}
+
 // src/animation-editor/effects.ts
 var sourceOf = (c) => c.source;
 function motionSceneEffects(scene) {
@@ -4667,6 +4723,7 @@ var AnimationEditorController = class {
       redoLabel: h.redoName,
       revision: this.revision,
       effectsProvider: this.effects.provider,
+      layerPictures: this.layers.revision,
       recording: this.recording ? {
         shot: this.recording.options.id,
         at: this.recording.options.at,
@@ -5175,6 +5232,42 @@ var AnimationEditorController = class {
     if (!r.ok) return r;
     return this.layerResult(shot, void 0);
   }
+  /**
+   * Fills a provider sequence template and loads it: `replace` (default) makes a new scene the
+   * size of the template's stage from its shots; `append` adds its shots after the current ones,
+   * scaled to the artwork. Values are checked first and every problem is refused at once. One
+   * undo step. Returns the new shot and layer ids, slots left open and notes.
+   */
+  async fillTemplate(template, values = {}, options = {}) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refuse(reason);
+    const mode = options.mode ?? "replace";
+    let filled;
+    try {
+      filled = await fillEffectTemplate(this.effects.provider, template, values, options.name ? { name: options.name } : {});
+    } catch (error) {
+      if (isEffectError(error) || error instanceof Error) return this.refuse(error.message);
+      throw error;
+    }
+    const provider = this.effects.provider.id;
+    const label = `Template ${filled.template.name}`;
+    let shots;
+    let notes;
+    let r;
+    if (mode === "replace") {
+      const made = motionSceneFromSequence(filled.sequence, { provider });
+      shots = made.scene.shots;
+      notes = made.notes;
+      r = this.apply({ op: "replace_scene", scene: made.scene }, label);
+    } else {
+      const made = motionShotsFromSequence(filled.sequence, { provider, width: this.scene.artwork.width, height: this.scene.artwork.height, shotIds: this.scene.shots.map((s) => s.id), layerIds: this.scene.shots.flatMap((s) => (s.layers ?? []).map((l) => l.id)) });
+      shots = made.shots;
+      notes = made.notes;
+      r = this.apply({ op: "insert_shots", shots: made.shots }, label);
+    }
+    if (!r.ok) return r;
+    return { ok: true, template, mode, shots: shots.map((s) => s.id), layers: shots.flatMap((s) => (s.layers ?? []).map((l) => l.id)), openSlots: filled.openSlots, notes: [...filled.notes, ...notes] };
+  }
   // ---------------------------------------------------------------------------------------
   // Recording
   // ---------------------------------------------------------------------------------------
@@ -7087,6 +7180,20 @@ function createAnimationEffectsToolProvider(controller, options = {}) {
     extraTools: (ctx) => [
       ...animationCameraMoveTools(controller, ctx),
       ...animationShotLayerTools(controller, ctx),
+      ...effectTemplateTools(
+        {
+          provider: () => controller.effectsProvider,
+          fillDetails: "mode replace (default) makes a new scene from the template's shots, the size of its stage; mode append adds its shots after the current ones, scaled to the artwork. Each shot keeps its framing and camera moves, its layers and its transition; its title and caption become overlay word layers. Returns { template, mode, shots (new shot ids), layers (new layer ids), openSlots, notes }. Check the result with render_animation_frame.",
+          fillOptions: { mode: { type: "string", enum: ["replace", "append"], description: "replace (default): a new scene from the template; append: its shots after the current ones." } },
+          fill: async (template, values, options2) => {
+            const r = await controller.fillTemplate(template, values, { name: options2.name, mode: options2.mode });
+            if (!r.ok) throw new Error(r.error);
+            const { ok: _ok, ...rest } = r;
+            return rest;
+          }
+        },
+        ctx
+      ),
       {
         name: "add_vector_effect",
         title: "Add a vector effect",
@@ -7296,6 +7403,7 @@ export {
   motionRevealPadding,
   motionRulerTicks,
   motionSceneEffects,
+  motionSceneFromSequence,
   motionSceneHasLayers,
   motionSceneShapeProblems,
   motionSceneToJson,
@@ -7304,6 +7412,7 @@ export {
   motionShotCueTime,
   motionShotLayersInfo,
   motionShotTimeScale,
+  motionShotsFromSequence,
   motionStageSvg,
   motionTakeProblems,
   motionTakeShot,

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

@@ -144,6 +144,8 @@ export declare class MotionLayersEngine implements MotionLayerPictures {
     /** Forgets every picture and failure (a new provider, or the host changed). */
     reset(): void;
     dispose(): void;
+    /** Goes up each time pictures come in or are cleared, so a view that caches frames knows to draw again. */
+    revision: number;
     private notify;
     private size;
     private snap;

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

@@ -144,6 +144,8 @@ export declare class MotionLayersEngine implements MotionLayerPictures {
     /** Forgets every picture and failure (a new provider, or the host changed). */
     reset(): void;
     dispose(): void;
+    /** Goes up each time pictures come in or are cleared, so a view that caches frames knows to draw again. */
+    revision: number;
     private notify;
     private size;
     private snap;

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

@@ -0,0 +1,33 @@
+/**
+ * An effects provider's `EffectSequence` (what a sequence template fills to) as animation shots:
+ * each shot keeps its framing and camera moves, its layers and its transition. Its title and
+ * caption become overlay word layers placed in the shot's framing. Rects and framings are scaled
+ * from the sequence's stage to the artwork.
+ */
+import type { EffectSequence } from '../effects/types.cjs';
+import type { MotionScene, MotionShot } from './types.cjs';
+export interface MotionShotsFromSequence {
+    shots: MotionShot[];
+    /** What could not be carried over, in sentences. */
+    notes: string[];
+}
+export interface MotionSequenceOptions {
+    /** The artwork size the shots are for (default the sequence's stage). */
+    width?: number;
+    height?: number;
+    /** Shot ids already used (new ones avoid them). */
+    shotIds?: Iterable<string>;
+    /** Layer ids already used (new ones avoid them). */
+    layerIds?: Iterable<string>;
+    /** The provider the sequence's effects come from, saved on layers and transitions. */
+    provider?: string;
+}
+/** The shots of a sequence, sized for the artwork (see the module comment). */
+export declare function motionShotsFromSequence(sequence: EffectSequence, options?: MotionSequenceOptions): MotionShotsFromSequence;
+/** A new scene from a sequence: an empty artwork the size of its stage, and its shots. */
+export declare function motionSceneFromSequence(sequence: EffectSequence, options?: Pick<MotionSequenceOptions, 'provider'> & {
+    background?: string;
+}): {
+    scene: MotionScene;
+    notes: string[];
+};

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

@@ -0,0 +1,33 @@
+/**
+ * An effects provider's `EffectSequence` (what a sequence template fills to) as animation shots:
+ * each shot keeps its framing and camera moves, its layers and its transition. Its title and
+ * caption become overlay word layers placed in the shot's framing. Rects and framings are scaled
+ * from the sequence's stage to the artwork.
+ */
+import type { EffectSequence } from '../effects/types.js';
+import type { MotionScene, MotionShot } from './types.js';
+export interface MotionShotsFromSequence {
+    shots: MotionShot[];
+    /** What could not be carried over, in sentences. */
+    notes: string[];
+}
+export interface MotionSequenceOptions {
+    /** The artwork size the shots are for (default the sequence's stage). */
+    width?: number;
+    height?: number;
+    /** Shot ids already used (new ones avoid them). */
+    shotIds?: Iterable<string>;
+    /** Layer ids already used (new ones avoid them). */
+    layerIds?: Iterable<string>;
+    /** The provider the sequence's effects come from, saved on layers and transitions. */
+    provider?: string;
+}
+/** The shots of a sequence, sized for the artwork (see the module comment). */
+export declare function motionShotsFromSequence(sequence: EffectSequence, options?: MotionSequenceOptions): MotionShotsFromSequence;
+/** A new scene from a sequence: an empty artwork the size of its stage, and its shots. */
+export declare function motionSceneFromSequence(sequence: EffectSequence, options?: Pick<MotionSequenceOptions, 'provider'> & {
+    background?: string;
+}): {
+    scene: MotionScene;
+    notes: string[];
+};

package/dist/canvas/editorDocument.d.cts

@@ -1,16 +1,19 @@
 import type { HistoryManager } from '../history/HistoryManager.cjs';
+import type { EditorAssetRegistry } from '../persistence/assets.cjs';
 import { type EditorDocument } from '../persistence/editorDocument.cjs';
-import type { CanvasScene, CanvasScenesStore } from './scenes.cjs';
+import type { CanvasScene, CanvasScenesStore, CanvasViewport } from './scenes.cjs';
 import type { CanvasEdge, CanvasNode } from './types.cjs';
 /** What the document needs of an edge (React Flow's and Svelte Flow's edges fit). */
 export type CanvasEdgeLike = Pick<CanvasEdge, 'id' | 'source' | 'target'> & {
     selected?: boolean;
 };
-/** A canvas as it is saved: its nodes, edges and (with a scenes store) scenes. */
+/** A canvas as it is saved: its nodes, edges, (with a scenes store) scenes and (with `getViewport`) the view. */
 export interface CanvasEditorDocument<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge> {
     nodes: TNode[];
     edges: TEdge[];
     scenes?: CanvasScene[];
+    /** Where the canvas was looking when it was saved. */
+    viewport?: CanvasViewport;
 }
 export interface CanvasEditorDocumentOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge> {
     getNodes: () => TNode[];
@@ -28,12 +31,54 @@ export interface CanvasEditorDocumentOptions<TNode extends CanvasNode = CanvasNo
     subscribe?: (listener: () => void) => () => void;
     /** Why the canvas cannot be changed (a sentence), or `false`. */
     readOnly?: () => string | false;
+    /**
+     * The view saved with the document and restored on load. Panning and zooming are not
+     * document changes: they do not bump the revision, so they alone do not trigger a save.
+     */
+    getViewport?: () => CanvasViewport;
+    setViewport?: (viewport: CanvasViewport) => void;
+    /** Node fields left out of the document, besides `selected`, `dragging`, `measured` and `resizing`. */
+    omitNodeKeys?: readonly string[];
+    /** Edge fields left out of the document, besides `selected`. */
+    omitEdgeKeys?: readonly string[];
+    /**
+     * Checks a node of a document being loaded, after the built-in checks. Return what is wrong
+     * (a sentence) to refuse the whole load, or nothing to accept the node.
+     */
+    validateNode?: (node: TNode, index: number) => string | void;
+    /**
+     * Turns any document handed to `loadDocument` (a raw one or a migrated file) into the current
+     * shape before it is checked, e.g. an older layout the host stored without a file envelope.
+     */
+    normalize?: (document: unknown) => unknown;
+    /** The host's format version of the document (default 1); files with an older one are migrated. */
+    formatVersion?: number;
+    /** `migrations[v]` turns a version `v` file's document into version `v + 1`. Only files carry a version. */
+    migrations?: Record<number, (document: unknown) => unknown>;
+    /**
+     * Keeps inline binary data in node and edge data (image data URLs, long base64) out of the
+     * document as asset references; autosave and the document store save the bytes with it.
+     */
+    assets?: EditorAssetRegistry;
+}
+/** What to leave out of canvas nodes and edges: the runtime fields plus the host's own. */
+export interface CanvasDocumentOmitOptions {
+    omitNodeKeys?: readonly string[];
+    omitEdgeKeys?: readonly string[];
 }
+/**
+ * A string that changes only when the saved part of the nodes or edges changes (not selection,
+ * measuring or the omitted fields). The React and Svelte document bindings compare it to count
+ * changes the history does not see.
+ */
+export declare function canvasDocumentContentKey(nodes: readonly CanvasNode[], edges: readonly CanvasEdgeLike[], options?: CanvasDocumentOmitOptions): string;
 /**
  * The save / load / undo contract for a canvas whose nodes and edges live in the host (React
  * Flow or Svelte Flow state), kind `canvas`. The document is the nodes and edges without
- * selection or measurement, plus the scenes when a store is given. Recorded loads are one
- * undo step in the shared `history`; opening (`history: "reset"`) clears it.
+ * selection, measurement or `omitNodeKeys` / `omitEdgeKeys`, plus the scenes when a store is
+ * given and the viewport with `getViewport`. Loads are normalized, then checked (built-in
+ * checks, then `validateNode`) before anything changes. Recorded loads are one undo step in the
+ * shared `history`; opening (`history: "reset"`) clears it.
  */
 export declare function createCanvasEditorDocument<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge>(options: CanvasEditorDocumentOptions<TNode, TEdge>): EditorDocument<CanvasEditorDocument<TNode, TEdge>>;
 export interface CanvasGestureRecorderOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge> {

package/dist/canvas/editorDocument.d.ts

@@ -1,16 +1,19 @@
 import type { HistoryManager } from '../history/HistoryManager.js';
+import type { EditorAssetRegistry } from '../persistence/assets.js';
 import { type EditorDocument } from '../persistence/editorDocument.js';
-import type { CanvasScene, CanvasScenesStore } from './scenes.js';
+import type { CanvasScene, CanvasScenesStore, CanvasViewport } from './scenes.js';
 import type { CanvasEdge, CanvasNode } from './types.js';
 /** What the document needs of an edge (React Flow's and Svelte Flow's edges fit). */
 export type CanvasEdgeLike = Pick<CanvasEdge, 'id' | 'source' | 'target'> & {
     selected?: boolean;
 };
-/** A canvas as it is saved: its nodes, edges and (with a scenes store) scenes. */
+/** A canvas as it is saved: its nodes, edges, (with a scenes store) scenes and (with `getViewport`) the view. */
 export interface CanvasEditorDocument<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge> {
     nodes: TNode[];
     edges: TEdge[];
     scenes?: CanvasScene[];
+    /** Where the canvas was looking when it was saved. */
+    viewport?: CanvasViewport;
 }
 export interface CanvasEditorDocumentOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge> {
     getNodes: () => TNode[];
@@ -28,12 +31,54 @@ export interface CanvasEditorDocumentOptions<TNode extends CanvasNode = CanvasNo
     subscribe?: (listener: () => void) => () => void;
     /** Why the canvas cannot be changed (a sentence), or `false`. */
     readOnly?: () => string | false;
+    /**
+     * The view saved with the document and restored on load. Panning and zooming are not
+     * document changes: they do not bump the revision, so they alone do not trigger a save.
+     */
+    getViewport?: () => CanvasViewport;
+    setViewport?: (viewport: CanvasViewport) => void;
+    /** Node fields left out of the document, besides `selected`, `dragging`, `measured` and `resizing`. */
+    omitNodeKeys?: readonly string[];
+    /** Edge fields left out of the document, besides `selected`. */
+    omitEdgeKeys?: readonly string[];
+    /**
+     * Checks a node of a document being loaded, after the built-in checks. Return what is wrong
+     * (a sentence) to refuse the whole load, or nothing to accept the node.
+     */
+    validateNode?: (node: TNode, index: number) => string | void;
+    /**
+     * Turns any document handed to `loadDocument` (a raw one or a migrated file) into the current
+     * shape before it is checked, e.g. an older layout the host stored without a file envelope.
+     */
+    normalize?: (document: unknown) => unknown;
+    /** The host's format version of the document (default 1); files with an older one are migrated. */
+    formatVersion?: number;
+    /** `migrations[v]` turns a version `v` file's document into version `v + 1`. Only files carry a version. */
+    migrations?: Record<number, (document: unknown) => unknown>;
+    /**
+     * Keeps inline binary data in node and edge data (image data URLs, long base64) out of the
+     * document as asset references; autosave and the document store save the bytes with it.
+     */
+    assets?: EditorAssetRegistry;
+}
+/** What to leave out of canvas nodes and edges: the runtime fields plus the host's own. */
+export interface CanvasDocumentOmitOptions {
+    omitNodeKeys?: readonly string[];
+    omitEdgeKeys?: readonly string[];
 }
+/**
+ * A string that changes only when the saved part of the nodes or edges changes (not selection,
+ * measuring or the omitted fields). The React and Svelte document bindings compare it to count
+ * changes the history does not see.
+ */
+export declare function canvasDocumentContentKey(nodes: readonly CanvasNode[], edges: readonly CanvasEdgeLike[], options?: CanvasDocumentOmitOptions): string;
 /**
  * The save / load / undo contract for a canvas whose nodes and edges live in the host (React
  * Flow or Svelte Flow state), kind `canvas`. The document is the nodes and edges without
- * selection or measurement, plus the scenes when a store is given. Recorded loads are one
- * undo step in the shared `history`; opening (`history: "reset"`) clears it.
+ * selection, measurement or `omitNodeKeys` / `omitEdgeKeys`, plus the scenes when a store is
+ * given and the viewport with `getViewport`. Loads are normalized, then checked (built-in
+ * checks, then `validateNode`) before anything changes. Recorded loads are one undo step in the
+ * shared `history`; opening (`history: "reset"`) clears it.
  */
 export declare function createCanvasEditorDocument<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge>(options: CanvasEditorDocumentOptions<TNode, TEdge>): EditorDocument<CanvasEditorDocument<TNode, TEdge>>;
 export interface CanvasGestureRecorderOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdgeLike = CanvasEdge> {