@pixerate/editor 0.233.0 → 0.235.0

package/dist/video-editor/index.js

@@ -153,6 +153,13 @@ import {
 import {
   namedWithSuggestion
 } from "../chunk-EUKY4KFX.js";
+import {
+  effectLayerRole,
+  effectLayerSpan,
+  effectSequenceTiming,
+  effectTemplateTools,
+  fillEffectTemplate
+} from "../chunk-G3RUKJ5C.js";
 import "../chunk-EHLOCVWB.js";
 import {
   CAMERA_MOVE_MAX_MS,
@@ -3454,6 +3461,106 @@ var VideoPreviewEngine = class {
   }
 };
 
+// src/video-editor/sequence.ts
+var svgUrl = (svg) => svg.trimStart().startsWith("<") ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}` : svg;
+var GROUPS = ["base", "background", "subject", "overlay", "text"];
+function videoEditsFromSequence(project, sequence, options = {}) {
+  const at = options.at ?? videoProjectDuration(project);
+  const W = project.width;
+  const H = project.height;
+  const sx = W / sequence.stage.width;
+  const sy = H / sequence.stage.height;
+  const timing = effectSequenceTiming(sequence);
+  const provider = options.provider ? { provider: options.provider } : {};
+  const notes = [];
+  const usedClips = new Set(allVideoClipIds(project));
+  const usedTracks = new Set(project.tracks.map((t) => t.id));
+  const usedAssets = new Set(project.assets.map((a) => a.id));
+  const fresh = (used, base) => {
+    for (let i = 1; ; i++) if (!used.has(`${base}${i}`)) return used.add(`${base}${i}`), `${base}${i}`;
+  };
+  const edits = [];
+  const assets = [];
+  const placeholders = {};
+  const items = [];
+  const placement = (r) => {
+    if (!r) return {};
+    const x = (r.x + r.width / 2) * sx - W / 2;
+    const y = (r.y + r.height / 2) * sy - H / 2;
+    const scale = Math.min(r.width * sx / W, r.height * sy / H);
+    return { transform: { x: Math.round(x * 100) / 100, y: Math.round(y * 100) / 100, scale: Math.round(scale * 1e3) / 1e3 } };
+  };
+  const clipOf = (layer, start, duration, shot) => {
+    const id = fresh(usedClips, "tpl-c");
+    const common = { id, start, duration, ...layer.opacity !== void 0 && layer.opacity < 1 ? { opacity: layer.opacity } : {}, ...layer.fade ? { fadeIn: layer.fade, fadeOut: layer.fade } : {}, ...placement(layer.rect) };
+    const effects = layer.effect ? { effects: [{ id: "fx1", effect: layer.effect, ...provider, ...layer.values ? { values: layer.values } : {} }] } : {};
+    const s = layer.subject;
+    if (!s) return { ...common, type: "effect", effect: layer.effect, ...provider, ...layer.values ? { values: layer.values } : {} };
+    if ("slot" in s) {
+      (placeholders[s.slot] ??= []).push(id);
+      if (layer.effect) notes.push(`Shot ${shot + 1}: the "${s.slot}" slot is a grey placeholder; when you swap in the picture, apply ${layer.effect} to it again (apply_effect).`);
+      return { ...common, type: "color", color: "#475569", name: `Slot "${s.slot}"` };
+    }
+    if ("text" in s) return { ...common, type: "text", text: s.text, ...s.font ? { fontFamily: s.font } : {}, ...typeof s.weight === "number" ? { fontWeight: s.weight } : {}, ...effects };
+    const asset = fresh(usedAssets, "tpl-a");
+    assets.push(asset);
+    if ("video" in s) {
+      notes.push(`Shot ${shot + 1}: a video's length is not known here, so its asset is given the clip's length (${Math.round(duration)} ms); correct it with update_video_asset if it is longer.`);
+      edits.push({ op: "add_asset", asset: { id: asset, kind: "video", src: s.video, duration } });
+    } else edits.push({ op: "add_asset", asset: { id: asset, kind: "image", src: "image" in s ? s.image : svgUrl(s.svg) } });
+    return { ...common, type: "media", asset, fit: "contain", ...effects };
+  };
+  sequence.shots.forEach((shot, i) => {
+    const shotStart = timing.starts[i];
+    const shotEnd = timing.starts[i + 1] ?? timing.total;
+    let base;
+    shot.layers.forEach((layer, j) => {
+      const span = effectLayerSpan(layer, i, timing.starts, timing.total);
+      if (span.end - span.start <= 0) return void notes.push(`Shot ${i + 1}, layer ${j + 1} lasts no time, so it was left out.`);
+      const clip = clipOf(layer, at + span.start, span.end - span.start, i);
+      const isBase = j === 0 && !base && span.start === shotStart && span.end === shotEnd && effectLayerRole(layer) === "background" && !layer.rect;
+      const item = { group: isBase ? "base" : effectLayerRole(layer), clip };
+      if (isBase) base = item;
+      items.push(item);
+    });
+    if (!base) {
+      base = { group: "base", clip: { id: fresh(usedClips, "tpl-c"), type: "color", color: "#000000", name: `Shot ${i + 1}`, start: at + shotStart, duration: shotEnd - shotStart } };
+      items.push(base);
+    }
+    if (i > 0 && shot.transition) {
+      base.clip.transition = { type: "effect", duration: shot.transition.ms ?? 800, effect: { effect: shot.transition.effect, ...provider, ...shot.transition.values ? { values: shot.transition.values } : {} } };
+      if (shot.layers.length > 1) notes.push(`Shot ${i + 1}: its transition blends the clips on the base track; the layers above it cut.`);
+    }
+    const words = (text, y, size, name) => items.push({ group: "text", clip: { id: fresh(usedClips, "tpl-c"), type: "text", text, name, fontSize: Math.round(size), start: at + shotStart, duration: shotEnd - shotStart, transform: { x: 0, y: Math.round(y) } } });
+    if (shot.title) words(shot.title, 0, H * 0.09, "Title");
+    if (shot.caption) words(shot.caption, H * 0.35, H * 0.045, "Caption");
+    if (shot.camera?.in !== void 0 || shot.camera?.during !== void 0 || shot.camera?.framing) notes.push(`Shot ${i + 1}: its camera framing and moves were not carried over; set them with set_clip_camera_move on its clips.`);
+  });
+  const lanes = [];
+  for (const group of GROUPS) {
+    const mine = [];
+    for (const item of items.filter((x) => x.group === group).sort((a, b) => a.clip.start - b.clip.start)) {
+      let lane = group === "base" ? mine[0] : mine.find((l) => l.ends.every((e) => e <= item.clip.start + 1e-6));
+      if (!lane) mine.push(lane = { group, id: fresh(usedTracks, "tpl-v"), ends: [], clips: [] });
+      lane.ends.push(item.clip.start + item.clip.duration);
+      lane.clips.push(item);
+    }
+    lanes.push(...mine);
+  }
+  for (const lane of lanes) edits.push({ op: "add_track", track: { id: lane.id, kind: "video", name: `Template ${lane.group}` }, at: 0 });
+  for (const lane of lanes) for (const item of lane.clips) edits.push({ op: "add_clip", track: lane.id, clip: item.clip });
+  return {
+    edits,
+    clips: lanes.flatMap((l) => l.clips.map((c) => c.clip.id)),
+    tracks: lanes.map((l) => l.id).reverse(),
+    assets,
+    start: at,
+    end: at + timing.total,
+    placeholders,
+    notes
+  };
+}
+
 // src/video-editor/controller.ts
 var VideoEditorController = class _VideoEditorController {
   history;
@@ -3818,6 +3925,29 @@ var VideoEditorController = class _VideoEditorController {
     if (place) checkVideoEffectPlace(d, place);
     return d;
   }
+  /**
+   * Fills a provider sequence template and puts it on the timeline at `at` (default the end), on
+   * new tracks above the others (see `videoEditsFromSequence`). Values are checked first and every
+   * problem is refused at once. One undo step. Returns the new tracks, clips and assets, where it
+   * starts and ends, the placeholder clips standing in for open slots, and notes.
+   */
+  async fillTemplate(template, values = {}, options = {}) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refused(reason);
+    if (options.at !== void 0 && !(Number.isFinite(options.at) && options.at >= 0)) return this.refused(`"at" is a time in ms, 0 or more (got ${options.at}).`);
+    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.refused(error.message);
+      throw error;
+    }
+    const made = videoEditsFromSequence(this.getState().project, filled.sequence, { at: options.at, provider: this.effects.provider.id });
+    const r = this.apply(made.edits, `Template ${filled.template.name}`);
+    if (!r.ok) return r;
+    const { edits: _edits, notes, ...rest } = made;
+    return { ok: true, template, ...rest, openSlots: filled.openSlots, notes: [...filled.notes, ...notes] };
+  }
   refused(message) {
     return this.refuse(message);
   }
@@ -5923,6 +6053,20 @@ function createVideoEffectsToolProvider(controller, options = {}) {
     subscribe: (notify) => controller.subscribe(() => notify()),
     extraTools: (ctx) => [
       ...videoCameraMoveTools(controller, ctx),
+      ...effectTemplateTools(
+        {
+          provider: () => controller.effectsProvider,
+          fillDetails: `It goes on the timeline at "at" (default the end of the project), on new tracks above the others: each shot's bottom layer on a base track (with the shot's transition), other layers as effect, picture and text clips on tracks by role, titles and captions as text clips; an open subject slot becomes a grey placeholder clip named after it. Camera moves are not carried over. Returns { template, tracks, clips, assets, start, end (ms), placeholders (clip ids by open slot), openSlots, notes }. To fill an open slot, add the picture with add_video_asset and put it on the placeholder's track at its start with add_video_clip in overwrite mode.`,
+          fillOptions: { at: { type: "number", minimum: 0, description: "Where on the timeline it starts, ms (default the end of the project)." } },
+          fill: async (template, values, options2) => {
+            const r = await controller.fillTemplate(template, values, { name: options2.name, at: options2.at });
+            if (!r.ok) throw new Error(r.error);
+            const { ok: _ok, ...rest } = r;
+            return rest;
+          }
+        },
+        ctx
+      ),
       {
         name: "add_video_effect_clip",
         title: "Add an effect clip",
@@ -6684,6 +6828,7 @@ export {
   videoEaseBezier,
   videoEaseProgress,
   videoEaseToAnimationEasing,
+  videoEditsFromSequence,
   videoEffectFrameTime,
   videoEffectLayerKey,
   videoEffectValuesAt,

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

@@ -0,0 +1,38 @@
+/**
+ * An effects provider's `EffectSequence` (what a sequence template fills to) as video edits, so a
+ * template lands on the timeline as one undo step:
+ *
+ * - Each shot's bottom layer, when it lasts exactly the shot, goes on a base track; otherwise the
+ *   shot gets a black colour clip there. A shot's transition goes on its base clip (a provider
+ *   `effect` transition from the base clip before), so it blends the base pictures.
+ * - Other layers go on tracks above by role (background, subject, overlay), packed so clips of a
+ *   track never overlap: an effect with no subject is an effect clip; a picture or SVG is a media
+ *   clip on a new image asset, carrying the layer's effect as a clip effect; words are a text clip;
+ *   an open slot is a grey placeholder colour clip named after it.
+ * - A layer's `rect` becomes the clip's placement; `opacity` and `fade` carry over.
+ * - Titles and captions are text clips on the top track.
+ *
+ * Camera moves are not carried over (notes say so); set them with `set_clip_camera_move`.
+ */
+import type { EffectSequence } from '../effects/types.cjs';
+import type { VideoEdit } from './edit.cjs';
+import type { VideoProject } from './types.cjs';
+export interface VideoSequenceEdits {
+    edits: VideoEdit[];
+    /** The new clips' ids, base clips first. */
+    clips: string[];
+    /** The new tracks' ids, top to bottom. */
+    tracks: string[];
+    assets: string[];
+    /** Where the sequence starts and ends on the timeline (ms). */
+    start: number;
+    end: number;
+    /** Placeholder clips standing in for open subject slots, by slot. */
+    placeholders: Record<string, string[]>;
+    notes: string[];
+}
+/** The edits that put a sequence on a project's timeline at `at` (default its end), on new tracks above the others. */
+export declare function videoEditsFromSequence(project: VideoProject, sequence: EffectSequence, options?: {
+    at?: number;
+    provider?: string;
+}): VideoSequenceEdits;

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

@@ -0,0 +1,38 @@
+/**
+ * An effects provider's `EffectSequence` (what a sequence template fills to) as video edits, so a
+ * template lands on the timeline as one undo step:
+ *
+ * - Each shot's bottom layer, when it lasts exactly the shot, goes on a base track; otherwise the
+ *   shot gets a black colour clip there. A shot's transition goes on its base clip (a provider
+ *   `effect` transition from the base clip before), so it blends the base pictures.
+ * - Other layers go on tracks above by role (background, subject, overlay), packed so clips of a
+ *   track never overlap: an effect with no subject is an effect clip; a picture or SVG is a media
+ *   clip on a new image asset, carrying the layer's effect as a clip effect; words are a text clip;
+ *   an open slot is a grey placeholder colour clip named after it.
+ * - A layer's `rect` becomes the clip's placement; `opacity` and `fade` carry over.
+ * - Titles and captions are text clips on the top track.
+ *
+ * Camera moves are not carried over (notes say so); set them with `set_clip_camera_move`.
+ */
+import type { EffectSequence } from '../effects/types.js';
+import type { VideoEdit } from './edit.js';
+import type { VideoProject } from './types.js';
+export interface VideoSequenceEdits {
+    edits: VideoEdit[];
+    /** The new clips' ids, base clips first. */
+    clips: string[];
+    /** The new tracks' ids, top to bottom. */
+    tracks: string[];
+    assets: string[];
+    /** Where the sequence starts and ends on the timeline (ms). */
+    start: number;
+    end: number;
+    /** Placeholder clips standing in for open subject slots, by slot. */
+    placeholders: Record<string, string[]>;
+    notes: string[];
+}
+/** The edits that put a sequence on a project's timeline at `at` (default its end), on new tracks above the others. */
+export declare function videoEditsFromSequence(project: VideoProject, sequence: EffectSequence, options?: {
+    at?: number;
+    provider?: string;
+}): VideoSequenceEdits;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.233.0",
+  "version": "0.235.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-animation-editor/SKILL.md

@@ -172,6 +172,9 @@ refuse.
 | `remove_shot_layer` | Remove a layer. |
 | `set_shot_transition` | Set the transition into a shot from the one before (a provider effect with use `transition`, its `ms`, `preset`, `values`). Not on the first shot. Returns the transition with `start` / `end`. |
 | `clear_shot_transition` | Remove a shot's transition, so it cuts (or the camera eases) again. |
+| `list_templates` | List the provider's sequence templates (`query`, `tags`): ids, names, shot counts, lengths. Returns `available: false` without templates. Call before `describe_template`. |
+| `describe_template` | Read a template's slots (type, label, default, limits), its `valuesSchema` and `exampleValues`. Call before `fill_template`. |
+| `fill_template` | Fill a template (`template`, `values`, `name`, `mode` replace or append) and load its shots as one undo step. Every value that does not fit is refused at once. Returns the new `shots`, `layers`, `openSlots` and `notes`. |
 
 ### Save and open
 
@@ -228,6 +231,13 @@ Flair's scenes do:
    `layer-not-drawn` and `transition-not-played` (no provider: effect layers are left out and
    transitions crossfade).
 
+A provider's **sequence templates** are whole scenes of such shots with slots to fill (a
+product reveal, before and after, a stat countdown): `list_templates`, `describe_template`, then
+`fill_template` with `values` (start from `exampleValues`). `mode` replace (default) makes a new
+scene the size of the template's stage; append adds its shots after yours, scaled to the
+artwork. Titles and captions become overlay word layers. Fill the `openSlots` it reports with
+`update_shot_layer` (`subject`), then animate artwork over the shots as usual.
+
 Layers are pixels: the Flair `SvgMotion` export leaves them out. Use them for backgrounds, looks
 and titles, and keep what should animate node by node in the artwork.
 

package/skills/pixerate-animation-motion-graphics/SKILL.md

@@ -68,6 +68,8 @@ This skill is the method. `pixerate-animation-editor` has the full tool referenc
 | A set length | `fit_animation` with `seconds`, `keep` for fixed shots |
 | The camera travels to the next part | `update_shot` camera `frame`, then `set_shot_camera_move` role `transition` (a glide; a whip pan for energy) |
 | A slow push while a shot holds | `set_shot_camera_move` role `hold` (a Ken Burns drift), with a longer `hold` |
+| A background, look or title behind or over a shot | `add_shot_layer` (a generator for a background, an overlay or title over it); `set_shot_transition` between shots |
+| A whole ready-made sequence (a reveal, a countdown) | `list_templates`, `describe_template`, `fill_template` (mode append keeps your shots), then animate artwork over it |
 
 ## Recipes
 
@@ -98,6 +100,8 @@ This skill is the method. `pixerate-animation-editor` has the full tool referenc
 - `edit_animation`: several edits as one undo step
 - `fit_animation`, `set_animation_settings`, `get_timing_grid`: length, settings and cues
 - `list_camera_moves`, `set_shot_camera_move`: provider camera moves into and during a shot
+- `add_shot_layer`, `set_shot_transition`: provider effect layers and transitions on shots
+- `list_templates`, `describe_template`, `fill_template`: a provider's sequence template as shots
 - `check_animation`, `get_motion_path`, `render_animation_frame`: check and look
 - `export_lottie`, `export_flair_motion`: deliver
 - `undo_animation`: take back a step

package/skills/pixerate-canvas/SKILL.md

@@ -168,12 +168,12 @@ the reason (for example a variant combination that already exists, or a cycle).
 
 ### Save and open
 
-The host may add the shared document tools (see `pixerate-agent-tools`). A canvas document is `{ nodes, edges, scenes }`: every node (`id`, `position`, `data`, `type`, `parentId`...) and edge without selection or measurement, plus the saved scenes.
+The host may add the shared document tools (see `pixerate-agent-tools`). A canvas document is `{ nodes, edges, scenes, viewport }`: every node (`id`, `position`, `data`, `type`, `parentId`...) and edge without selection, measurement or the fields the host leaves out, plus the saved scenes and, when the host saves it, the `viewport` (`{ x, y, zoom }`) the canvas was looking at. Large inline images in node data may come back as `pixerate-asset:` references: pass them back unchanged, they are only valid in this session.
 
 | Tool | Use |
 | --- | --- |
 | `get_canvas_document` | Take a copy of the whole canvas as `{ kind, formatVersion, revision, document }` before a risky rewrite, or to hand it on. To read the canvas, use `get_editor_state`: it is smaller and says more. Refuses very large canvases. |
-| `load_canvas_document` | Put back a copy from `get_canvas_document` (its `document`, or the whole result). Checked first: duplicate ids, edges to missing nodes and parents that do not exist are refused and nothing changes. One undo step (`undo_canvas` brings the previous canvas back). To add or change a few nodes use `canvas_add_node` / `canvas_update_node`. |
+| `load_canvas_document` | Put back a copy from `get_canvas_document` (its `document`, or the whole result). Checked first: duplicate ids, edges to missing nodes, parents that do not exist, a bad `viewport` and anything the host's own node check rejects (the error names the node and says why) are refused and nothing changes. A `viewport` in the document moves the view; leave it out to keep the current view. One undo step (`undo_canvas` brings the previous canvas back). To add or change a few nodes use `canvas_add_node` / `canvas_update_node`. |
 | `undo_canvas` | Undo the last canvas change (one tool call, command or user gesture such as a drag). Returns `undone` (the step's name) and whether more can be undone. Fails with "Nothing to undo." when there is nothing. |
 | `redo_canvas` | Redo the last undone canvas change. |
 | `save_canvas_document` | Save the canvas under a `name` in the host's storage (the same name replaces that copy). Returns the `key`. Only listed when the host has storage. Save when the user asks, not after every edit. |

package/skills/pixerate-video-editor/SKILL.md

@@ -89,6 +89,14 @@ the pitfalls, and uses the tools below.
     plays across the rest of the clip at `framing` (a Ken Burns drift on a still). The moves are
     baked into the clip's x, y, scale and rotation keys at the project's fps, two keys at a cut,
     so the preview and exports play them without the provider. Check with `get_video_frame`.
+13. **Sequence templates** (a provider with templates): for a ready-made opening, reveal or
+    countdown, `list_templates`, then `describe_template` for its slots, then `fill_template`
+    with `values` (start from its `exampleValues`) and `at`. It lands on new tracks above the
+    others as one undo step: each shot's bottom layer on a base track carrying the shot's
+    transition, other layers as effect, picture and text clips by role. Open slots come back as
+    grey placeholder clips (`placeholders`); put the real picture over one with
+    `add_video_asset` and `add_video_clip` in `overwrite` mode. Camera moves are not carried
+    over: add them with `set_clip_camera_move`.
 
 ## Best practices
 
@@ -302,6 +310,9 @@ and every write tool is refused with the reason.
 | `list_video_camera_moves` | List the provider's camera moves for a `role` (`transition` into a clip, `hold` across it) with `durationMs` and `cut`. Returns `available: false` without camera moves. Call before `set_clip_camera_move`. |
 | `set_clip_camera_move` | Play a camera move on a clip's picture (`clip`, `role`, `move`, `ms` for a transition, `preset`, `values`, `from` and `framing` as `{ zoom, x, y }`): baked into its transform keys, one per frame, two at a cut. Returns the camera, key counts, `cuts`, `windows` and `notes` (tilt, turn and blur cannot be baked). Refuses a clip keyed by hand. |
 | `clear_clip_camera_move` | Remove a clip's move for a `role` and re-bake the other; with none left the transform goes back to what it was. |
+| `list_templates` | List the provider's sequence templates (`query`, `tags`): ids, names, shot counts, lengths. Returns `available: false` without templates. Call before `describe_template`. |
+| `describe_template` | Read a template's slots (type, label, default, limits), its `valuesSchema` and `exampleValues`. Call before `fill_template`. |
+| `fill_template` | Fill a template (`template`, `values`, `name`, `at` ms) and put it on new tracks at `at` as one undo step. Every value that does not fit is refused at once. Returns the new `tracks`, `clips`, `assets`, `start`, `end`, `placeholders` by open slot, and `notes`. |
 
 ### Save and open
 

package/skills/pixerate-video-montage/SKILL.md

@@ -66,6 +66,7 @@ music track and cutting to them, see `pixerate-bgm-alignment`.
 | A section change | Dip to black or a held shot, then a new rhythm |
 | Continuity of motion | Cut on action (`roll_video_edit` onto the movement) |
 | Photos in a slideshow | Image assets, a slow push-in: with a provider that has camera moves, `set_clip_camera_move` role `hold` (a Ken Burns drift) on each photo; otherwise `set_video_keyframes` scale 1 to 1.08 |
+| An opening or closing sequence the provider has as a template | `list_templates`, `describe_template`, then `fill_template` with `at` the start; put the real pictures over its placeholders |
 
 ## Recipes
 
@@ -97,4 +98,5 @@ start: 0, duration: <sequence>, fadeOut: 2000 }`; `update_video_clip` on the las
 - `set_video_transition`: crossfades and dips
 - `update_video_clip`, `set_video_keyframes`: fades, volume and push-ins
 - `list_video_camera_moves`, `set_clip_camera_move`: provider camera moves (a drift across a photo)
+- `list_templates`, `describe_template`, `fill_template`: a provider's sequence template as clips on new tracks
 - `undo_video`: take back a step