@pixerate/editor 0.223.9 → 0.224.0

package/dist/effects/index.js

@@ -3,11 +3,12 @@ import {
 } from "../chunk-N4ZXW3WB.js";
 import {
   createEffectAuthoringSession
-} from "../chunk-WMVEYSOA.js";
+} from "../chunk-WA4IS2EY.js";
 import {
   EffectRendererPool
 } from "../chunk-EHLOCVWB.js";
 import {
+  CAMERA_MOVE_ROLES,
   EFFECT_ERROR_CODES,
   EFFECT_KINDS,
   EFFECT_USES,
@@ -22,17 +23,21 @@ import {
   countEffectTags,
   createEffectPixels,
   createEffectToolProvider,
+  effectOffered,
   effectValueErrors,
   encodeEffectFloat,
   hasEffectTags,
+  isCameraView,
   isEffectError,
   isEffectPixels,
   linearToSrgb,
   normaliseEffectTag,
   resolveEffectValues,
+  sampleCameraViews,
+  sampleEffectCameraMove,
   searchEffectSummaries,
   srgbToLinear
-} from "../chunk-6G2NLMVK.js";
+} from "../chunk-HKPLKISO.js";
 import "../chunk-V2ZCJRDM.js";
 import "../chunk-RNSANXPT.js";
 import {
@@ -62,6 +67,20 @@ function checkSummary(e, issues) {
   if (typeof e.loop !== "boolean") at("loop is not a boolean");
   if (e.duration !== void 0 && !(e.duration > 0)) at("duration must be a positive number of ms when present");
   if (e.backgroundOpacity !== void 0 && (typeof e.backgroundOpacity !== "string" || !e.backgroundOpacity)) at("backgroundOpacity must name a control when present");
+  if (e.kind === "camera") {
+    if (e.uses?.length !== 1 || e.uses[0] !== "camera") at('a camera effect must have exactly the use "camera"');
+    const m = e.camera;
+    if (!m) at("a camera effect needs camera: { role, durationMs }");
+    else {
+      if (!CAMERA_MOVE_ROLES.includes(m.role)) at(`camera.role "${m.role}" is not one of ${CAMERA_MOVE_ROLES.join(", ")}`);
+      if (!(Number.isFinite(m.durationMs) && m.durationMs >= 0)) at("camera.durationMs must be a number of ms \u2265 0");
+      if (m.cut !== void 0 && !(m.cut >= 0 && m.cut <= 1)) at("camera.cut must be 0\u20131 when present");
+      if (e.duration !== void 0 && e.duration !== m.durationMs) at(`duration ${e.duration} differs from camera.durationMs ${m.durationMs}`);
+    }
+  } else {
+    if (e.uses?.includes("camera")) at('only camera effects may have the use "camera"');
+    if (e.camera !== void 0) at("only camera effects may have camera");
+  }
 }
 function checkDescription(id, d, issues) {
   const at = (message) => issues.push({ effectId: id, message });
@@ -102,7 +121,8 @@ async function checkRender(provider, d, size, issues) {
   try {
     renderer = await provider.createRenderer(d.id, { width: size, height: size });
   } catch (e) {
-    if (!(d.kind === "vector" && codeOf(e) === "unsupported")) at(`createRenderer failed: ${codeOf(e)}`);
+    if (!((d.kind === "vector" || d.kind === "camera") && codeOf(e) === "unsupported")) at(`createRenderer failed: ${codeOf(e)}`);
+    else if (!(e instanceof Error && e.message.trim())) at("createRenderer refused without saying why");
     return;
   }
   try {
@@ -118,6 +138,51 @@ async function checkRender(provider, d, size, issues) {
   const after = await rejectsWith("disposed", () => renderer.render({ time: 0, inputs }));
   if (after) at(`render after dispose ${after}`);
 }
+var sameView = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var near = (a, b) => ["zoom", "scrollX", "scrollY", "tilt", "turn", "roll", "perspective", "blur", "blurAngle"].every((k) => Math.abs((a[k] ?? 0) - (b[k] ?? 0)) <= 1e-6 * Math.max(1, Math.abs(a[k] ?? 0)));
+var STAGE = { width: 320, height: 180 };
+var WIDE = { zoom: 1, scrollX: 0, scrollY: 0 };
+var CLOSE = { zoom: 2, scrollX: 0, scrollY: 0 };
+async function checkCamera(provider, d, issues) {
+  const at = (message) => issues.push({ effectId: d.id, message });
+  const camera = d.camera;
+  const to = camera.role === "hold" ? WIDE : CLOSE;
+  const ms = camera.durationMs || 1e3;
+  const ctx = (u) => ({ from: WIDE, to, u, ms, stage: STAGE });
+  const views = [];
+  for (const u of [0, 0.25, 0.5, 0.75, 1]) {
+    try {
+      const view = provider.cameraView(d.id, ctx(u));
+      if (view instanceof Promise) {
+        at("cameraView must be synchronous; it returned a Promise");
+        return;
+      }
+      if (!isCameraView(view)) at(`cameraView at u ${u} is not a CameraView (zoom > 0, finite scrollX and scrollY): ${JSON.stringify(view)}`);
+      else views.push(view);
+      const again = provider.cameraView(d.id, ctx(u));
+      if (isCameraView(view) && !sameView(view, again)) at(`cameraView is not pure: two calls at u ${u} gave different views`);
+    } catch (e) {
+      at(`cameraView at u ${u} failed: ${codeOf(e)}`);
+    }
+  }
+  const bad = await rejectsWith("invalid_values", () => provider.cameraView(d.id, ctx(0.5), { __not_a_control__: 1 }));
+  if (bad) at(`cameraView with an unknown control ${bad}`);
+  if (provider.sampleCameraMove && views.length === 5) {
+    try {
+      const sample = await provider.sampleCameraMove(d.id, { from: WIDE, to, ms, stage: STAGE, fps: 10 });
+      const keys = sample?.keys;
+      if (!Array.isArray(keys) || keys.length < 2) at("sampleCameraMove returned fewer than two keys");
+      else {
+        if (keys.some((k, i) => !isCameraView(k.view) || !Number.isFinite(k.t) || i > 0 && k.t < keys[i - 1].t)) at("sampleCameraMove keys must be CameraViews in time order");
+        if (keys[0].t !== 0 || keys[keys.length - 1].t !== ms) at(`sampleCameraMove keys must run from 0 to ${ms} ms, got ${keys[0].t} to ${keys[keys.length - 1].t}`);
+        else if (!near(keys[0].view, views[0]) || !near(keys[keys.length - 1].view, views[4])) at("sampleCameraMove disagrees with cameraView at the start or end of the move");
+        if (camera.cut !== void 0 && sample.cut === void 0) at("sampleCameraMove gave no cut for a move that cuts");
+      }
+    } catch (e) {
+      at(`sampleCameraMove failed: ${codeOf(e)}`);
+    }
+  }
+}
 async function checkEffectProvider(provider, options = {}) {
   const issues = [];
   const top = (message) => issues.push({ message });
@@ -129,6 +194,9 @@ async function checkEffectProvider(provider, options = {}) {
   if (caps?.supportsAuthoring !== void 0 && typeof caps.supportsAuthoring !== "boolean") top("capabilities.supportsAuthoring is not a boolean");
   if (caps?.supportsVector && typeof provider.applyVectorEffect !== "function") top("supportsVector is set but applyVectorEffect is missing");
   if (caps?.supportsAuthoring && typeof provider.openAuthoring !== "function") top("supportsAuthoring is set but openAuthoring is missing");
+  if (caps?.supportsCamera !== void 0 && typeof caps.supportsCamera !== "boolean") top("capabilities.supportsCamera is not a boolean");
+  if (caps?.supportsCamera && typeof provider.cameraView !== "function") top("supportsCamera is set but cameraView is missing");
+  if (provider.sampleCameraMove && typeof provider.cameraView !== "function") top("sampleCameraMove is present but cameraView is missing");
   const list = await provider.list();
   const ids = /* @__PURE__ */ new Set();
   for (const e of list) {
@@ -136,6 +204,7 @@ async function checkEffectProvider(provider, options = {}) {
     ids.add(e.id);
     checkSummary(e, issues);
   }
+  if (!caps?.supportsCamera && list.some((e) => e.kind === "camera")) top("the catalog lists camera effects but capabilities.supportsCamera is not set");
   const all = await provider.search("");
   if (all.length !== list.length) top(`search("") returned ${all.length} effects, list() ${list.length}`);
   const firstUse = list[0]?.uses[0];
@@ -147,6 +216,14 @@ async function checkEffectProvider(provider, options = {}) {
   if (unknown) top(`describe of an unknown id ${unknown}`);
   const unknownRenderer = await rejectsWith("unknown_effect", () => provider.createRenderer("__no_such_effect__", { width: 4, height: 4 }));
   if (unknownRenderer) top(`createRenderer of an unknown id ${unknownRenderer}`);
+  if (caps?.supportsCamera && provider.cameraView) {
+    const probe = { from: WIDE, to: CLOSE, u: 0.5, ms: 1e3, stage: STAGE };
+    const unknownCamera = await rejectsWith("unknown_effect", () => provider.cameraView("__no_such_effect__", probe));
+    if (unknownCamera) top(`cameraView of an unknown id ${unknownCamera}`);
+    const notCamera = list.find((e) => e.kind !== "camera");
+    const wrongKind = notCamera && await rejectsWith("unsupported", () => provider.cameraView(notCamera.id, probe));
+    if (wrongKind) issues.push({ effectId: notCamera.id, message: `cameraView of a ${notCamera.kind} effect ${wrongKind}` });
+  }
   const size = options.size ?? 8;
   for (const id of options.ids ?? [...ids]) {
     let d;
@@ -158,6 +235,7 @@ async function checkEffectProvider(provider, options = {}) {
     }
     checkDescription(id, d, issues);
     if (options.render !== false && d.kind !== "motion") await checkRender(provider, d, size, issues);
+    if (d.kind === "camera" && d.camera && caps.supportsCamera && provider.cameraView) await checkCamera(provider, d, issues);
     if ((d.kind === "vector" || d.kind === "motion") && caps.supportsVector && provider.applyVectorEffect) {
       try {
         const m = await provider.applyVectorEffect(id, '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect id="r" width="10" height="10"/></svg>');
@@ -172,7 +250,7 @@ async function checkEffectProvider(provider, options = {}) {
   }
   if (caps?.supportsAuthoring && options.authoring !== false && typeof provider.openAuthoring === "function") {
     const targetEffect = (await Promise.all((options.ids ?? [...ids]).map((id) => provider.describe(id)))).find(
-      (d) => d.kind !== "motion" && d.kind !== "vector"
+      (d) => d.kind !== "motion" && d.kind !== "vector" && d.kind !== "camera"
     );
     if (targetEffect) {
       try {
@@ -394,6 +472,71 @@ var DESCRIPTIONS = [
     inputs: []
   }
 ];
+var CAMERA_DESCRIPTIONS = [
+  {
+    id: "fake.glide",
+    name: "Glide",
+    kind: "camera",
+    category: "camera",
+    uses: ["camera"],
+    description: "Moves the camera smoothly from one framing to the next.",
+    tags: ["move", "smooth"],
+    transparent: false,
+    loop: false,
+    duration: 800,
+    camera: { role: "transition", durationMs: 800 },
+    controls: {
+      type: "object",
+      additionalProperties: false,
+      properties: { curve: { type: "string", enum: ["linear", "smooth"], description: "Speed curve: linear, or smooth (ease in and out). Default smooth." } }
+    },
+    defaults: { curve: "smooth" },
+    presets: [],
+    inputs: []
+  },
+  {
+    id: "fake.whip",
+    name: "Whip pan",
+    kind: "camera",
+    category: "camera",
+    uses: ["camera"],
+    description: "Whips the camera away from one framing, cuts halfway in a blur, and lands on the next.",
+    tags: ["move", "fast", "cut"],
+    transparent: false,
+    loop: false,
+    duration: 400,
+    camera: { role: "transition", durationMs: 400, cut: 0.5 },
+    controls: {
+      type: "object",
+      additionalProperties: false,
+      properties: { blur: { type: "number", minimum: 0, maximum: 100, description: "Motion blur at the cut, in stage pixels. Default 40." } }
+    },
+    defaults: { blur: 40 },
+    presets: [{ name: "Clean", values: { blur: 0 } }],
+    inputs: []
+  },
+  {
+    id: "fake.drift",
+    name: "Drift",
+    kind: "camera",
+    category: "camera",
+    uses: ["camera"],
+    description: "Zooms slowly into the middle of the framing while the shot holds.",
+    tags: ["ken burns", "slow"],
+    transparent: false,
+    loop: false,
+    duration: 4e3,
+    camera: { role: "hold", durationMs: 4e3 },
+    controls: {
+      type: "object",
+      additionalProperties: false,
+      properties: { scale: { type: "number", minimum: 1, maximum: 2, description: "Zoom at the end of the hold, as a multiple of the framing's zoom. Default 1.15." } }
+    },
+    defaults: { scale: 1.15 },
+    presets: [],
+    inputs: []
+  }
+];
 var summaryOf = ({ controls: _c, defaults: _d, presets: _p, inputs: _i, ...summary }) => summary;
 var hexToRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
 var smooth = (t) => t * t * (3 - 2 * t);
@@ -478,6 +621,35 @@ function renderPixels(d, v, request, width, height) {
   }
   return out;
 }
+var lerp = (a, b, t) => a + (b - a) * t;
+var viewAt = (cx, cy, zoom, ctx) => ({ zoom, scrollX: ctx.stage.width / (2 * zoom) - cx, scrollY: ctx.stage.height / (2 * zoom) - cy });
+var centreOf = (v, ctx) => [ctx.stage.width / (2 * v.zoom) - v.scrollX, ctx.stage.height / (2 * v.zoom) - v.scrollY];
+function cameraViewOf(d, ctx, v) {
+  const { from, to, u } = ctx;
+  const [x0, y0] = centreOf(from, ctx);
+  const [x1, y1] = centreOf(to, ctx);
+  switch (d.id) {
+    case "fake.glide": {
+      const k = v.curve === "smooth" ? smooth(u) : u;
+      return viewAt(lerp(x0, x1, k), lerp(y0, y1, k), lerp(from.zoom, to.zoom, k), ctx);
+    }
+    case "fake.whip": {
+      const out = u < 0.5;
+      const at = out ? from : to;
+      const off = out ? Math.pow(u * 2, 3) : 1 - (1 - Math.pow(1 - (u - 0.5) * 2, 3));
+      const dist = Math.hypot(x1 - x0, y1 - y0);
+      const [dx, dy] = dist > 1e-6 ? [(x1 - x0) / dist, (y1 - y0) / dist] : [1, 0];
+      const reach = ctx.stage.width / at.zoom * off * (out ? 1 : -1);
+      const [cx, cy] = centreOf(at, ctx);
+      const blur = v.blur * off;
+      return { ...viewAt(cx + dx * reach, cy + dy * reach, at.zoom, ctx), ...blur > 0 ? { blur, blurAngle: Math.atan2(dy, dx) * 180 / Math.PI } : {} };
+    }
+    case "fake.drift":
+      return viewAt(x0, y0, from.zoom * lerp(1, v.scale, smooth(u)), ctx);
+    default:
+      throw new EffectUnsupportedError(`"${d.id}" is a ${d.kind} effect, not a camera move.`, d.id);
+  }
+}
 function toFloat(p) {
   const f = new Float32Array(p.data.length);
   for (let i = 0; i < f.length; i += 4) {
@@ -508,16 +680,24 @@ function createFakeEffectProvider(options = {}) {
     supportsHostImages: false,
     supportsVector: true,
     supportsAuthoring,
+    ...options.camera ? { supportsCamera: true } : {},
     maxSize: 8192,
     ...options.capabilities
   };
-  const byId = new Map(DESCRIPTIONS.map((d) => [d.id, d]));
+  const all = options.camera ? [...DESCRIPTIONS, ...CAMERA_DESCRIPTIONS] : DESCRIPTIONS;
+  const byId = new Map(all.map((d) => [d.id, d]));
   const get = (id) => {
     const d = byId.get(id);
     if (!d) throw new UnknownEffectError(id, "the fake provider");
     return d;
   };
-  const summaries = DESCRIPTIONS.map(summaryOf);
+  const summaries = all.map(summaryOf);
+  const camera = (id, ctx, values) => {
+    const d = get(id);
+    if (d.kind !== "camera") throw new EffectUnsupportedError(`"${id}" is a ${d.kind} effect, not a camera move.`, id);
+    if (!(ctx.u >= 0 && ctx.u <= 1)) throw new EffectUnsupportedError(`u must be 0\u20131 through the move, got ${ctx.u}.`, id);
+    return cameraViewOf(d, ctx, resolveEffectValues(d, values));
+  };
   const provider = {
     id: "fake",
     name: "Fake effects",
@@ -528,6 +708,7 @@ function createFakeEffectProvider(options = {}) {
     describe: (id) => structuredClone(get(id)),
     createRenderer(id, ro) {
       const d = get(id);
+      if (d.kind === "camera") throw new EffectUnsupportedError(`"${id}" is a camera move: it moves a scene's camera and draws no pixels. Use cameraView.`, id);
       if (d.kind !== "shader") throw new EffectUnsupportedError(`"${id}" is a ${d.kind} effect; use applyVectorEffect.`, id);
       const { width, height } = ro;
       const depth = ro.depth ?? 8;
@@ -578,6 +759,14 @@ function createFakeEffectProvider(options = {}) {
         loop: false
       };
     },
+    ...options.camera ? {
+      cameraView: camera,
+      sampleCameraMove: (id, request) => {
+        const d = get(id);
+        const { from, to, ms, stage, fps, values } = request;
+        return sampleCameraViews((u) => camera(id, { from, to, u, ms, stage }, values), { ms, fps, cut: d.camera?.cut });
+      }
+    } : {},
     ...supportsAuthoring ? {
       openAuthoring: (from) => createEffectAuthoringSession(from, { provider })
     } : {}
@@ -593,7 +782,8 @@ var EFFECT_USE_LABELS = {
   overlay: "Overlay",
   title: "Title",
   motion: "Motion",
-  interactive: "Interactive"
+  interactive: "Interactive",
+  camera: "Camera"
 };
 var HEX2 = /^#[0-9a-f]{6}([0-9a-f]{2})?$/i;
 var typeOf = (s) => Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s.type;
@@ -1102,6 +1292,7 @@ function createEffectAuthoringToolProvider(host, options) {
   };
 }
 export {
+  CAMERA_MOVE_ROLES,
   EFFECT_ERROR_CODES,
   EFFECT_KINDS,
   EFFECT_USES,
@@ -1125,6 +1316,7 @@ export {
   effectControlField,
   effectFieldValue,
   effectFontFamilies,
+  effectOffered,
   effectParameterFields,
   effectSampleInputs,
   effectSamplePicture,
@@ -1132,6 +1324,7 @@ export {
   encodeEffectFloat,
   groupEffectsByCategory,
   hasEffectTags,
+  isCameraView,
   isEffectError,
   isEffectFontControl,
   isEffectPixels,
@@ -1139,6 +1332,8 @@ export {
   normaliseEffectTag,
   renderEffectThumbnail,
   resolveEffectValues,
+  sampleCameraViews,
+  sampleEffectCameraMove,
   searchEffectSummaries,
   srgbToLinear
 };

package/dist/effects/types.d.cts

@@ -9,8 +9,11 @@
 import type { JsonSchema } from '../tools/schema.cjs';
 import type { FlairSvgAnimation } from '../animation-editor/flair.cjs';
 import type { EffectAuthoringSession, EffectAuthoringSource } from './authoring.cjs';
-/** How an effect is drawn: a pixel shader, an animated vector picture, or motion applied to someone else's vector art. */
-export type EffectKind = 'shader' | 'vector' | 'motion';
+/**
+ * How an effect is drawn: a pixel shader, an animated vector picture, motion applied to someone
+ * else's vector art, or a camera move, which moves a scene's camera and draws no pixels.
+ */
+export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera';
 /**
  * What an effect is for. An effect may have several uses.
  *
@@ -21,10 +24,33 @@ export type EffectKind = 'shader' | 'vector' | 'motion';
  * - `title`: draws type or a graphic meant as a title.
  * - `motion`: animates vector art (`applyVectorEffect`).
  * - `interactive`: reacts to pointer, scroll or audio input at run time.
+ * - `camera`: moves a scene's camera (`cameraView`). Only `camera` effects have it, and they have
+ *   no other use, so editors that draw pixels never offer them.
  */
-export type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive';
+export type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive' | 'camera';
 export declare const EFFECT_KINDS: readonly EffectKind[];
 export declare const EFFECT_USES: readonly EffectUse[];
+/**
+ * What a camera move does to a shot.
+ *
+ * - `transition`: moves the camera from one framing (`from`) to the next (`to`): a glide, a whip
+ *   pan, a punch zoom, a cut.
+ * - `hold`: moves the camera within one framing while the shot holds (`from` and `to` are the
+ *   same): a Ken Burns drift, a crash zoom.
+ */
+export type CameraMoveRole = 'transition' | 'hold';
+export declare const CAMERA_MOVE_ROLES: readonly CameraMoveRole[];
+/** How a `camera` effect moves (`EffectSummary.camera`). */
+export interface EffectCameraMove {
+    role: CameraMoveRole;
+    /** Length of the move at its default values (ms); 0 for a cut. A hold plays across the shot's hold instead. */
+    durationMs: number;
+    /**
+     * Where the view jumps, 0–1 through the move (0.5 for a whip pan or punch zoom that cuts
+     * halfway). Keyframes either side of it must not be tweened across. Absent for a smooth move.
+     */
+    cut?: number;
+}
 /** One entry of a provider's catalog. */
 export interface EffectSummary {
     /** Stable id, saved in documents. Never reused for a different effect. */
@@ -48,6 +74,8 @@ export interface EffectSummary {
      * background of its own to fade (an overlay is already transparent).
      */
     backgroundOpacity?: string;
+    /** How a `camera` effect moves. Present exactly when `kind` is `camera`. */
+    camera?: EffectCameraMove;
 }
 export interface EffectSearchOptions {
     kind?: EffectKind;
@@ -161,6 +189,77 @@ export type EffectVectorTarget = string | {
     svg: string;
     nodeIds?: readonly string[];
 };
+/**
+ * Where a scene's camera looks (the shape of Flair's `View`). The scene is drawn at
+ * (point + scroll) × zoom, then turned by `tilt`, `turn` and `roll` round the middle of the stage
+ * and seen in perspective, then blurred by `blur` while the camera moves. Positions are in the
+ * scene's own units, so a framing is `stage.width / zoom` wide.
+ */
+export interface CameraView {
+    /** Scale of the scene on the stage; > 0. */
+    zoom: number;
+    /** Scene offset before scaling, in scene units. */
+    scrollX: number;
+    scrollY: number;
+    /** Tips the scene back round its horizontal axis (CSS `rotateX`), degrees, −75 to 75. Default 0. */
+    tilt?: number;
+    /** Swings the scene round its vertical axis (CSS `rotateY`), degrees, −75 to 75. Default 0. */
+    turn?: number;
+    /** Rolls the scene round the line of sight (CSS `rotateZ`), degrees clockwise, −180 to 180. Default 0. */
+    roll?: number;
+    /** Distance of the lens from the scene as a multiple of the stage width; smaller is more dramatic. Default the provider's own. */
+    perspective?: number;
+    /** Motion blur in stage pixels while the camera moves; 0 or absent when still. */
+    blur?: number;
+    /** Direction the blur streaks, degrees on screen (0 horizontal, 90 vertical); absent when it blurs every way (a zoom or a turn). */
+    blurAngle?: number;
+}
+/** The stage a camera looks at, in pixels. */
+export interface CameraStage {
+    width: number;
+    height: number;
+}
+/** Where a camera move is: what `cameraView` takes. */
+export interface CameraMoveContext {
+    /** The framing the move leaves; for a hold, the framing it moves within (the same as `to`). */
+    from: CameraView;
+    /** The framing the move arrives at. */
+    to: CameraView;
+    /** How far through the move, 0–1. */
+    u: number;
+    /** Length of the whole move (ms): its `durationMs`, the editor's override, or for a hold the shot's hold. */
+    ms: number;
+    stage: CameraStage;
+}
+/** What `sampleCameraMove` takes: the move's framings, length and stage, and how often to key it. */
+export interface CameraMoveSampleRequest {
+    from: CameraView;
+    to: CameraView;
+    /** Length of the move (ms). */
+    ms: number;
+    stage: CameraStage;
+    /** Keys per second; > 0. */
+    fps: number;
+    /** Control values; missing controls take their defaults. */
+    values?: EffectValues;
+}
+/** One key of a sampled camera move. */
+export interface CameraKeyframe {
+    /** Ms from the start of the move. */
+    t: number;
+    view: CameraView;
+}
+/**
+ * A camera move as keyframes, so an editor can bake it without calling `cameraView` each frame.
+ * Keys are in time order from `t` 0 to `ms`, one per frame. At a cut two keys share the cut's
+ * `t`: the view just before it, then the view after; tweening between consecutive keys never
+ * crosses the jump.
+ */
+export interface CameraMoveSample {
+    keys: readonly CameraKeyframe[];
+    /** Ms of the cut, when the move has one. */
+    cut?: number;
+}
 /** What a provider can do, so editors can degrade cleanly. */
 export interface EffectProviderCapabilities {
     /** Renders off the main thread. */
@@ -177,6 +276,8 @@ export interface EffectProviderCapabilities {
     maxSize?: number;
     /** Implements `openAuthoring`: effects can be edited, not only used. */
     supportsAuthoring?: boolean;
+    /** Lists `camera` effects and implements `cameraView` (and maybe `sampleCameraMove`). */
+    supportsCamera?: boolean;
 }
 export type MaybePromise<T> = T | Promise<T>;
 /**
@@ -196,7 +297,10 @@ export interface EffectProvider {
     /** Effects matching every word of `query` (in name, id, category, tags or description), best first. */
     search(query: string, options?: EffectSearchOptions): MaybePromise<readonly EffectSummary[]>;
     describe(id: string): MaybePromise<EffectDescription>;
-    /** A pixel renderer. A `vector` effect may refuse with `EffectUnsupportedError` where it cannot lay out SVG (a Worker). */
+    /**
+     * A pixel renderer. A `vector` effect may refuse with `EffectUnsupportedError` where it cannot
+     * lay out SVG (a Worker); a `camera` effect draws no pixels and may refuse with one saying so.
+     */
     createRenderer(id: string, options: EffectRendererOptions): MaybePromise<EffectRenderer>;
     /**
      * Vector and motion effects as an animated SVG. Present when `capabilities.supportsVector`. A
@@ -210,4 +314,17 @@ export interface EffectProvider {
      * `UnknownEffectError`; an effect the provider cannot edit throws `EffectUnsupportedError`.
      */
     openAuthoring?(from: EffectAuthoringSource): MaybePromise<EffectAuthoringSession>;
+    /**
+     * Where a camera move puts the camera `ctx.u` of the way through it, with its motion blur.
+     * Present when `capabilities.supportsCamera`. Synchronous and pure: the same id, context and
+     * values always give the same view, so editors may call it per frame or cache it. Unknown ids
+     * throw `UnknownEffectError`, invalid values `EffectControlError`, and an effect that is not a
+     * camera move (or a `u` outside 0–1) `EffectUnsupportedError`.
+     */
+    cameraView?(id: string, ctx: CameraMoveContext, values?: EffectValues): CameraView;
+    /**
+     * A camera move as keyframes (see `CameraMoveSample`). Optional even with `supportsCamera`;
+     * `sampleEffectCameraMove` falls back to `cameraView` per frame. Errors as for `cameraView`.
+     */
+    sampleCameraMove?(id: string, request: CameraMoveSampleRequest): MaybePromise<CameraMoveSample>;
 }