@pixerate/editor 0.231.0 → 0.232.0

package/dist/effects/index.d.cts

@@ -7,6 +7,7 @@
 export * from './types.cjs';
 export * from './errors.cjs';
 export * from './helpers.cjs';
+export * from './templates.cjs';
 export * from './conformance.cjs';
 export * from './fake.cjs';
 export * from './tools.cjs';

package/dist/effects/index.d.ts

@@ -7,6 +7,7 @@
 export * from './types.js';
 export * from './errors.js';
 export * from './helpers.js';
+export * from './templates.js';
 export * from './conformance.js';
 export * from './fake.js';
 export * from './tools.js';

package/dist/effects/index.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-N4ZXW3WB.js";
 import {
   createEffectAuthoringSession
-} from "../chunk-SBPGIZQN.js";
+} from "../chunk-MUSZYMBX.js";
 import {
   EffectRendererPool
 } from "../chunk-EHLOCVWB.js";
@@ -12,6 +12,10 @@ import {
   CAMERA_MOVE_ROLES,
   EFFECT_ERROR_CODES,
   EFFECT_KINDS,
+  EFFECT_LAYER_ROLES,
+  EFFECT_SUBJECT_KINDS,
+  EFFECT_TEMPLATE_SLOT_TYPES,
+  EFFECT_TRANSITION_MS,
   EFFECT_USES,
   EffectControlError,
   EffectDisposedError,
@@ -20,6 +24,7 @@ import {
   EffectsSlot,
   NoEffectsProviderError,
   UnknownEffectError,
+  UnknownTemplateError,
   applyEffectMask,
   cameraBoxOfView,
   cameraMoveField,
@@ -45,13 +50,242 @@ import {
   sampleEffectCameraMove,
   searchEffectSummaries,
   srgbToLinear
-} from "../chunk-TCZ2J7PR.js";
+} from "../chunk-PQYDJ2AV.js";
 import "../chunk-V2ZCJRDM.js";
 import "../chunk-RNSANXPT.js";
 import {
   ANIMATION_EASING_PRESETS
 } from "../chunk-5UJHB3BW.js";
 
+// src/effects/templates.ts
+var SLOT_NAME = /^[A-Za-z][\w-]*$/;
+var COLOR = /^#[0-9a-fA-F]{6}$/;
+var EFFECT_SEQUENCE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var isSubjectTemplateSlot = (slot) => slot.type === "image" || slot.type === "video" || slot.type === "svg";
+function effectSubjectKind(subject) {
+  if (!isObject(subject)) return void 0;
+  for (const k of ["slot", "image", "video", "svg", "text"]) if (typeof subject[k] === "string") return k;
+  return void 0;
+}
+var typeName = (value) => value === null ? "null" : Array.isArray(value) ? "a list" : typeof value === "object" ? "an object" : typeof value === "string" ? `the words ${JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value)}` : `${typeof value === "number" ? "the number" : "the value"} ${String(value)}`;
+function range(slot) {
+  const whole = slot.integer ? "whole number" : "number";
+  if (slot.min !== void 0 && slot.max !== void 0) return `a ${whole} from ${slot.min} to ${slot.max}`;
+  if (slot.min !== void 0) return `a ${whole} of at least ${slot.min}`;
+  if (slot.max !== void 0) return `a ${whole} of at most ${slot.max}`;
+  return `a ${whole}`;
+}
+function templateSlotTakes(slot) {
+  switch (slot.type) {
+    case "text":
+      return `words${slot.maxLength !== void 0 ? ` (up to ${slot.maxLength} characters)` : ""}`;
+    case "color":
+      return `a colour written #RRGGBB, like "${slot.default}"`;
+    case "number":
+      return range(slot);
+    case "video":
+      return "a video URL";
+    case "svg":
+      return "SVG markup or an SVG URL";
+    default:
+      return "a picture: a URL, a data: URL or <svg> markup";
+  }
+}
+function templateValueProblem(slot, value) {
+  const no = (extra = "") => `Slot "${slot.name}" takes ${templateSlotTakes(slot)}${extra}, not ${typeName(value)}.`;
+  switch (slot.type) {
+    case "text":
+      if (typeof value !== "string") return no();
+      if (slot.maxLength !== void 0 && value.length > slot.maxLength) return `Slot "${slot.name}" takes up to ${slot.maxLength} characters; the value has ${value.length}. Shorten it.`;
+      return void 0;
+    case "color":
+      return typeof value === "string" && COLOR.test(value) ? void 0 : no();
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) return no();
+      if (slot.integer && !Number.isInteger(value)) return `Slot "${slot.name}" takes ${range(slot)}; ${value} is not whole.`;
+      if (slot.min !== void 0 && value < slot.min || slot.max !== void 0 && value > slot.max) return `Slot "${slot.name}" takes ${range(slot)}; ${value} is out of range.`;
+      return void 0;
+    default: {
+      const host = ` (or { "slot": "${slot.name}" } to leave it for the host)`;
+      if (typeof value === "string") return value.trim() ? void 0 : no(host);
+      const kind = effectSubjectKind(value);
+      if (!kind) return no(host);
+      if (kind === "slot") return SLOT_NAME.test(value.slot) ? void 0 : `Slot "${slot.name}" left for the host is { "slot": name }, the name letters, digits, "-" and "_", starting with a letter.`;
+      const fits = kind === slot.type || slot.type === "image" && kind === "svg";
+      if (!fits) return `Slot "${slot.name}" takes { "${slot.type}": \u2026 }${slot.type === "image" ? ' or { "svg": \u2026 }' : ""}, not { "${kind}": \u2026 }.`;
+      return value[kind].trim() ? void 0 : `Slot "${slot.name}"'s "${kind}" is a non-empty string.`;
+    }
+  }
+}
+var slotList = (slots) => slots.length ? `the slots are ${slots.map((s) => `${s.name} (${s.type})`).join(", ")}` : "the template has no slots";
+function checkTemplateValues(slots, values) {
+  if (values === void 0) return [];
+  if (!isObject(values)) return [`Values are an object of slot names to values; ${slotList(slots)}.`];
+  const byName = new Map(slots.map((s) => [s.name, s]));
+  const errors = [];
+  for (const [name, value] of Object.entries(values)) {
+    const slot = byName.get(name);
+    if (!slot) errors.push(`There is no slot "${name}"; ${slotList(slots)}.`);
+    else if (value !== void 0) {
+      const problem = templateValueProblem(slot, value);
+      if (problem) errors.push(problem);
+    }
+  }
+  return errors;
+}
+function templateSlotSchema(slot) {
+  const about = `${slot.label}${slot.description ? `: ${slot.description}` : ""}.`;
+  switch (slot.type) {
+    case "text":
+      return { type: "string", ...slot.maxLength !== void 0 ? { maxLength: slot.maxLength } : {}, description: `${about} Words${slot.maxLength !== void 0 ? `, up to ${slot.maxLength} characters` : ""}. Default ${JSON.stringify(slot.default)}.` };
+    case "color":
+      return { type: "string", pattern: COLOR.source, description: `${about} A colour as #RRGGBB. Default ${slot.default}.` };
+    case "number":
+      return {
+        type: slot.integer ? "integer" : "number",
+        ...slot.min !== void 0 ? { minimum: slot.min } : {},
+        ...slot.max !== void 0 ? { maximum: slot.max } : {},
+        description: `${about} ${range(slot).replace(/^a /, "A ")}. Default ${slot.default}.`
+      };
+    default: {
+      const key = slot.type;
+      const object2 = (k, what) => ({ type: "object", properties: { [k]: { type: "string", description: what } }, required: [k], additionalProperties: false, description: `{ "${k}": \u2026 }` });
+      return {
+        anyOf: [
+          { type: "string", minLength: 1, description: key === "video" ? "A video URL." : key === "svg" ? "SVG markup or an SVG URL." : "A picture URL, a data: URL or <svg> markup." },
+          object2(key, key === "video" ? "A video URL." : key === "svg" ? "SVG markup or an SVG URL." : "A picture URL or a data: URL."),
+          ...key === "image" ? [object2("svg", "SVG markup.")] : [],
+          object2("slot", "A slot name, to leave the subject for the host to fill.")
+        ],
+        description: `${about} ${templateSlotTakes(slot).replace(/^a /, "A ")}. ${slot.hasDefault ? "Default: a placeholder picture." : "No default: left out, the host fills it."}`
+      };
+    }
+  }
+}
+function templateValuesSchema(slots) {
+  return {
+    type: "object",
+    properties: Object.fromEntries(slots.map((s) => [s.name, templateSlotSchema(s)])),
+    additionalProperties: false,
+    description: `Slot values by name; slots left out take their defaults. ${slots.length ? `Slots: ${slots.map((s) => s.name).join(", ")}.` : "This template has no slots."}`
+  };
+}
+function templateDefaultValues(slots) {
+  const out = {};
+  for (const s of slots) if (!isSubjectTemplateSlot(s)) out[s.name] = s.default;
+  return out;
+}
+function templateSlotSummary(slot) {
+  const fallback = isSubjectTemplateSlot(slot) ? slot.hasDefault ? "a placeholder by default" : "the host fills it when none is given" : `default ${JSON.stringify(slot.default)}`;
+  return `${slot.name} (${slot.type}): ${slot.label}; takes ${templateSlotTakes(slot)}; ${fallback}.`;
+}
+function searchTemplateSummaries(catalog, options = {}) {
+  const words = (options.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+  const scored = [];
+  for (const t of catalog) {
+    if (!hasEffectTags(t, options.tags)) continue;
+    let score = 0;
+    const name = t.name.toLowerCase();
+    const rest = [t.id, ...t.tags ?? [], t.description].join(" ").toLowerCase();
+    if (!words.every((w) => name.includes(w) || rest.includes(w))) continue;
+    for (const w of words) score += name.includes(w) ? 2 : 1;
+    scored.push({ t, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  const out = scored.map((s) => s.t);
+  return options.limit !== void 0 ? out.slice(0, Math.max(0, options.limit)) : out;
+}
+var effectLayerRole = (layer) => layer.role ?? (layer.rect ? "subject" : "background");
+function effectLayerInput(description) {
+  const images = description.inputs.filter((i) => i.kind === "image");
+  return (images.find((i) => i.name === "source") ?? images.find((i) => i.name !== "from" && i.name !== "to"))?.name;
+}
+var EFFECT_LAYER_USES = ["generator", "filter", "overlay", "title"];
+var effectLayerOffered = (e) => (e.kind === "shader" || e.kind === "vector") && e.uses.some((u) => EFFECT_LAYER_USES.includes(u));
+var isRect = (r) => isObject(r) && ["x", "y", "width", "height"].every((k) => Number.isFinite(r[k])) && r.width > 0 && r.height > 0;
+var isLayerTime = (t) => typeof t === "number" && Number.isFinite(t) && t >= 0 || isObject(t) && Number.isInteger(t.shots) && t.shots >= 1;
+function effectSubjectProblem(subject) {
+  const kind = effectSubjectKind(subject);
+  if (!kind) return `a subject is one of { image }, { video }, { svg }, { text } or { slot }, not ${typeName(subject)}`;
+  if (!subject[kind].trim()) return `a subject's "${kind}" is a non-empty string`;
+  return void 0;
+}
+function checkEffectSequence(sequence, catalog) {
+  const problems = [];
+  if (!isObject(sequence)) return ["A sequence is an object with name, stage and shots."];
+  if (typeof sequence.name !== "string" || !sequence.name) problems.push("The sequence needs a name.");
+  const stage = sequence.stage;
+  if (!isObject(stage) || !(Number(stage.width) > 0) || !(Number(stage.height) > 0)) problems.push("The sequence needs a stage { width, height } in pixels, both > 0.");
+  if (!Array.isArray(sequence.shots) || !sequence.shots.length) return [...problems, "The sequence needs at least one shot."];
+  const byId = catalog ? new Map(catalog.map((e) => [e.id, e])) : void 0;
+  const ids = /* @__PURE__ */ new Set();
+  sequence.shots.forEach((shot, i) => {
+    const at = `shot ${i + 1}`;
+    if (!isObject(shot)) return void problems.push(`${at} is not an object.`);
+    if (!(Number.isFinite(shot.hold) && shot.hold >= 0)) problems.push(`${at}: hold must be ms \u2265 0.`);
+    for (const k of ["title", "caption"]) if (shot[k] !== void 0 && typeof shot[k] !== "string") problems.push(`${at}: ${k} must be words.`);
+    if (shot.camera !== void 0) {
+      const camera = shot.camera;
+      if (!isObject(camera)) problems.push(`${at}: camera must be an object.`);
+      else if (camera.framing !== void 0 && !isRect(camera.framing)) problems.push(`${at}: camera.framing must be { x, y, width, height } with width and height > 0.`);
+    }
+    if (!Array.isArray(shot.layers)) problems.push(`${at}: layers must be a list (it may be empty).`);
+    else
+      shot.layers.forEach((layer, j) => {
+        const where = `${at}, layer ${j + 1}`;
+        if (!isObject(layer)) return void problems.push(`${where} is not an object.`);
+        if (layer.id !== void 0) {
+          if (typeof layer.id !== "string" || !layer.id) problems.push(`${where}: id must be a non-empty string.`);
+          else if (ids.has(layer.id)) problems.push(`${where}: id "${layer.id}" is used twice.`);
+          else ids.add(layer.id);
+        }
+        if (layer.effect === void 0 && layer.subject === void 0) problems.push(`${where} has neither an effect nor a subject.`);
+        if (layer.effect !== void 0 && (typeof layer.effect !== "string" || !layer.effect)) problems.push(`${where}: effect must be an effect id.`);
+        else if (typeof layer.effect === "string" && byId) {
+          const e = byId.get(layer.effect);
+          if (!e) problems.push(`${where}: the provider has no effect "${layer.effect}".`);
+          else if (!effectLayerOffered(e)) problems.push(`${where}: "${layer.effect}" (${e.kind}, ${e.uses.join("/")}) cannot be a layer; a layer's effect is a generator, filter, overlay or title.`);
+        }
+        if (layer.subject !== void 0) {
+          const p = effectSubjectProblem(layer.subject);
+          if (p) problems.push(`${where}: ${p}.`);
+        }
+        if (layer.role !== void 0 && !EFFECT_LAYER_ROLES.includes(layer.role)) problems.push(`${where}: role is one of ${EFFECT_LAYER_ROLES.join(", ")}.`);
+        if (layer.rect !== void 0 && !isRect(layer.rect)) problems.push(`${where}: rect must be { x, y, width, height } with width and height > 0.`);
+        for (const k of ["from", "until"]) if (layer[k] !== void 0 && !isLayerTime(layer[k])) problems.push(`${where}: ${k} is ms \u2265 0 or { shots: n } with n \u2265 1.`);
+        if (layer.opacity !== void 0 && !(typeof layer.opacity === "number" && layer.opacity >= 0 && layer.opacity <= 1)) problems.push(`${where}: opacity is 0\u20131.`);
+        if (layer.fade !== void 0 && !(typeof layer.fade === "number" && layer.fade >= 0)) problems.push(`${where}: fade is ms \u2265 0.`);
+        if (layer.values !== void 0 && !isObject(layer.values)) problems.push(`${where}: values must be an object of control values.`);
+      });
+    if (shot.transition !== void 0) {
+      const t = shot.transition;
+      if (i === 0) problems.push(`${at} has a transition, but there is no shot before it.`);
+      if (!isObject(t) || typeof t.effect !== "string" || !t.effect) problems.push(`${at}: transition needs an effect id.`);
+      else {
+        if (t.ms !== void 0 && !(typeof t.ms === "number" && t.ms > 0)) problems.push(`${at}: transition ms must be > 0.`);
+        const e = byId?.get(t.effect);
+        if (byId && !e) problems.push(`${at}: the provider has no transition "${t.effect}".`);
+        else if (e && !e.uses.includes("transition")) problems.push(`${at}: "${t.effect}" is not a transition (its uses are ${e.uses.join(", ")}).`);
+      }
+    }
+  });
+  return problems;
+}
+function effectSequenceEffects(sequence) {
+  const out = /* @__PURE__ */ new Set();
+  for (const shot of sequence.shots) {
+    for (const l of shot.layers) if (l.effect) out.add(l.effect);
+    if (shot.transition) out.add(shot.transition.effect);
+  }
+  return [...out];
+}
+function effectSequenceSlots(sequence) {
+  const out = /* @__PURE__ */ new Set();
+  for (const shot of sequence.shots) for (const l of shot.layers) if (l.subject && "slot" in l.subject) out.add(l.subject.slot);
+  return [...out];
+}
+
 // src/effects/conformance.ts
 var codeOf = (e) => isEffectError(e) ? e.code : e instanceof Error ? `untyped ${e.name}: ${e.message}` : String(e);
 async function rejectsWith(code, run) {
@@ -191,6 +425,87 @@ async function checkCamera(provider, d, issues) {
     }
   }
 }
+var wrongValue = (slot) => slot.type === "number" ? "not a number" : slot.type === "text" ? 42 : slot.type === "color" ? "blue" : 42;
+function checkSlot(templateId, slot, issues) {
+  const at = (message) => issues.push({ templateId, message: `slot ${JSON.stringify(slot?.name)}: ${message}` });
+  if (!slot || typeof slot.name !== "string" || !/^[A-Za-z][\w-]*$/.test(slot.name)) return at('needs a name of letters, digits, "-" and "_", starting with a letter');
+  if (!EFFECT_TEMPLATE_SLOT_TYPES.includes(slot.type)) return at(`type "${slot.type}" is not one of ${EFFECT_TEMPLATE_SLOT_TYPES.join(", ")}`);
+  if (typeof slot.label !== "string" || !slot.label) at("needs a label");
+  if (isSubjectTemplateSlot(slot)) {
+    if (typeof slot.hasDefault !== "boolean") at("a subject slot needs hasDefault (a boolean)");
+    if ("default" in slot) at("a subject slot describes hasDefault, not its default");
+    return;
+  }
+  const fallback = slot.default;
+  if (fallback === void 0) return at("needs a default");
+  const problem = templateValueProblem(slot, fallback);
+  if (problem) at(`its default does not fit: ${problem}`);
+  if (slot.type === "number" && slot.min !== void 0 && slot.max !== void 0 && slot.min > slot.max) at("min is above max");
+}
+async function checkTemplates(provider, list, issues) {
+  const top = (message) => issues.push({ message });
+  const templates = await provider.listTemplates();
+  if (!Array.isArray(templates)) return top("listTemplates did not return a list");
+  const seen = /* @__PURE__ */ new Set();
+  for (const t of templates) if (seen.has(t.id)) top(`duplicate template id "${t.id}"`);
+  else seen.add(t.id);
+  const unknownDescribe = await rejectsWith("unknown_template", () => provider.describeTemplate("__no_such_template__"));
+  if (unknownDescribe) top(`describeTemplate of an unknown id ${unknownDescribe}`);
+  const unknownFill = await rejectsWith("unknown_template", () => provider.instantiateTemplate("__no_such_template__"));
+  if (unknownFill) top(`instantiateTemplate of an unknown id ${unknownFill}`);
+  for (const summary of templates) {
+    const id = summary.id;
+    const at = (message) => issues.push({ templateId: id, message });
+    if (!id || typeof id !== "string") top("a template has no id");
+    if (!summary.name) at("template has no name");
+    if (!summary.description) at("template has no description");
+    if (!(Number.isInteger(summary.shots) && summary.shots >= 1)) at("shots must be a whole number \u2265 1");
+    if (summary.durationMs !== void 0 && !(summary.durationMs > 0)) at("durationMs must be > 0 when present");
+    let slots;
+    try {
+      const d = await provider.describeTemplate(id);
+      if (d.id !== id) at(`describeTemplate returned id "${d.id}"`);
+      if (!Array.isArray(d.slots)) {
+        at("describeTemplate gave no slots list");
+        continue;
+      }
+      slots = d.slots;
+      const names = /* @__PURE__ */ new Set();
+      for (const slot of slots) {
+        if (names.has(slot?.name)) at(`slot "${slot.name}" is declared twice`);
+        names.add(slot?.name);
+        checkSlot(id, slot, issues);
+      }
+    } catch (e) {
+      at(`describeTemplate failed: ${codeOf(e)}`);
+      continue;
+    }
+    try {
+      const result = await provider.instantiateTemplate(id);
+      if (!result.ok) at(`instantiateTemplate with the defaults failed: ${result.errors.join(" ")}`);
+      else {
+        for (const p of checkEffectSequence(result.sequence, list)) at(`with the defaults, ${p}`);
+        if (result.sequence?.shots?.length !== summary.shots) at(`listTemplates says ${summary.shots} shots; the sequence has ${result.sequence?.shots?.length}`);
+        if (!Array.isArray(result.openSlots) || !Array.isArray(result.notes)) at("instantiateTemplate needs openSlots and notes lists");
+        else {
+          const open = Array.isArray(result.sequence?.shots) ? effectSequenceSlots(result.sequence) : [];
+          if (open.some((s) => !result.openSlots.includes(s))) at(`openSlots ${JSON.stringify(result.openSlots)} misses slots the sequence leaves open (${open.join(", ")})`);
+        }
+      }
+    } catch (e) {
+      at(`instantiateTemplate with the defaults failed: ${codeOf(e)}`);
+    }
+    const bad = { __no_such_slot__: "x", ...slots[0] ? { [slots[0].name]: wrongValue(slots[0]) } : {} };
+    try {
+      const result = await provider.instantiateTemplate(id, bad);
+      if (result.ok) at("instantiateTemplate accepted an unknown slot and a value of the wrong type");
+      else if (!result.errors.length || result.errors.some((e) => typeof e !== "string" || !e)) at("instantiateTemplate refused bad values without a sentence for each");
+      else if (slots[0] && result.errors.length < 2) at("instantiateTemplate should refuse every bad value at once (an unknown slot and a wrong type gave one error)");
+    } catch (e) {
+      at(`instantiateTemplate with bad values threw (${codeOf(e)}) instead of returning { ok: false, errors }`);
+    }
+  }
+}
 async function checkEffectProvider(provider, options = {}) {
   const issues = [];
   const top = (message) => issues.push({ message });
@@ -205,6 +520,12 @@ async function checkEffectProvider(provider, options = {}) {
   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");
+  if (caps?.supportsTemplates !== void 0 && typeof caps.supportsTemplates !== "boolean") top("capabilities.supportsTemplates is not a boolean");
+  const templateMethods = ["listTemplates", "describeTemplate", "instantiateTemplate"];
+  if (caps?.supportsTemplates) {
+    for (const m of templateMethods) if (typeof provider[m] !== "function") top(`supportsTemplates is set but ${m} is missing`);
+  }
+  if (!caps?.supportsTemplates && templateMethods.some((m) => typeof provider[m] === "function")) top("template methods are present but capabilities.supportsTemplates is not set");
   const list = await provider.list();
   const ids = /* @__PURE__ */ new Set();
   for (const e of list) {
@@ -307,9 +628,125 @@ async function checkEffectProvider(provider, options = {}) {
       }
     }
   }
+  if (caps?.supportsTemplates && options.templates !== false && templateMethods.every((m) => typeof provider[m] === "function")) await checkTemplates(provider, list, issues);
   return issues;
 }
 
+// src/effects/fake-templates.ts
+var PLACEHOLDER = /\{\{([A-Za-z][\w-]*)\}\}/g;
+var WHOLE = /^\{\{([A-Za-z][\w-]*)\}\}$/;
+var picture = (label, tint) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 90" width="160" height="90"><rect width="160" height="90" fill="${tint}"/><text x="80" y="50" text-anchor="middle" font-family="sans-serif" font-size="14" fill="#fff">${label}</text></svg>`;
+var TEMPLATES = [
+  {
+    summary: { id: "fake.title-sequence", name: "Title sequence", description: "A gradient behind a title with a lower-third bar, then a crossfade to a closing shot with a caption.", tags: ["title", "intro"], shots: 2, durationMs: 4600 },
+    slots: [
+      { name: "title", type: "text", label: "Title", default: "Hello", maxLength: 40 },
+      { name: "subtitle", type: "text", label: "Closing caption", default: "See you soon", maxLength: 60 },
+      { name: "accent", type: "color", label: "Accent colour", default: "#0ea5e9" },
+      { name: "holdMs", type: "number", label: "Time on each shot (ms)", default: 2e3, min: 500, max: 1e4, integer: true }
+    ],
+    sequence: {
+      name: "title-sequence",
+      title: "{{title}}",
+      stage: { width: 1280, height: 720 },
+      shots: [
+        {
+          hold: "{{holdMs}}",
+          title: "{{title}}",
+          layers: [
+            { id: "backdrop", effect: "fake.gradient", role: "background", values: { from: "{{accent}}" }, until: { shots: 1 } },
+            { id: "bar", effect: "fake.bar", role: "overlay", values: { color: "{{accent}}" }, from: 200 }
+          ]
+        },
+        {
+          hold: "{{holdMs}}",
+          caption: "{{subtitle}}",
+          transition: { effect: "fake.crossfade", ms: 600 },
+          layers: [{ id: "closing", effect: "fake.gradient", role: "background", values: { from: "#111827", to: "{{accent}}" } }]
+        }
+      ]
+    }
+  },
+  {
+    summary: { id: "fake.picture-reveal", name: "Picture reveal", description: "A tinted picture, then a crossfade to the picture in full colour with a logo over it and a caption.", tags: ["product", "reveal"], shots: 2, durationMs: 4800 },
+    slots: [
+      { name: "picture", type: "image", label: "Picture", description: "The picture to reveal.", hasDefault: true, subjectDefault: picture("Picture", "#64748b") },
+      { name: "logo", type: "image", label: "Logo", description: "A logo shown over the second shot; the host fills it when none is given.", hasDefault: false },
+      { name: "caption", type: "text", label: "Caption", default: "Now in colour", maxLength: 50 },
+      { name: "holdMs", type: "number", label: "Time on each shot (ms)", default: 2e3, min: 500, max: 1e4, integer: true }
+    ],
+    sequence: {
+      name: "picture-reveal",
+      stage: { width: 1280, height: 720 },
+      shots: [
+        { hold: "{{holdMs}}", layers: [{ id: "tinted", effect: "fake.tint", subject: { slot: "picture" }, values: { color: "#704214", amount: 0.6 } }] },
+        {
+          hold: "{{holdMs}}",
+          caption: "{{caption}}",
+          transition: { effect: "fake.crossfade", ms: 800 },
+          layers: [
+            { id: "picture", subject: { slot: "picture" }, role: "background" },
+            { id: "logo", subject: { slot: "logo" }, role: "overlay", rect: { x: 1040, y: 40, width: 200, height: 112 }, fade: 300 }
+          ]
+        }
+      ]
+    }
+  }
+];
+var describeOf = (t) => ({
+  ...t.summary,
+  slots: t.slots.map(({ subjectDefault: _d, ...slot }) => slot)
+});
+function subjectOf(type, value) {
+  if (typeof value !== "string") return value;
+  if (value.trimStart().startsWith("<svg") || type === "svg") return { svg: value };
+  return type === "video" ? { video: value } : { image: value };
+}
+function fill(t, values) {
+  const slots = new Map(t.slots.map((s) => [s.name, s]));
+  const valueOf = (name) => {
+    const s = slots.get(name);
+    return values[name] ?? (isSubjectTemplateSlot(s) ? s.subjectDefault : s.default);
+  };
+  const walk = (v, key) => {
+    if (typeof v === "string") {
+      const whole = WHOLE.exec(v);
+      if (whole && slots.has(whole[1])) return valueOf(whole[1]);
+      return v.replace(PLACEHOLDER, (m, name) => slots.has(name) ? String(valueOf(name)) : m);
+    }
+    if (Array.isArray(v)) return v.map((x) => walk(x));
+    if (!v || typeof v !== "object") return v;
+    if (key === "subject" && typeof v.slot === "string") {
+      const s = slots.get(v.slot);
+      const value = s ? valueOf(s.name) : void 0;
+      return s && value !== void 0 ? subjectOf(s.type, value) : v;
+    }
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, k)]));
+  };
+  return walk(t.sequence);
+}
+function fakeTemplateMethods() {
+  const byId = new Map(TEMPLATES.map((t) => [t.summary.id, t]));
+  const get = (id) => {
+    const t = byId.get(id);
+    if (!t) throw new UnknownTemplateError(id, "the fake provider");
+    return t;
+  };
+  return {
+    listTemplates: (options) => searchTemplateSummaries(TEMPLATES.map((t) => t.summary), options).map((s) => structuredClone(s)),
+    describeTemplate: (id) => structuredClone(describeOf(get(id))),
+    instantiateTemplate(id, values = {}, options = {}) {
+      const t = get(id);
+      const errors = checkTemplateValues(describeOf(t).slots, values);
+      if (options.name !== void 0 && (typeof options.name !== "string" || !EFFECT_SEQUENCE_NAME.test(options.name))) errors.push(`The sequence name is lowercase words and dashes (like "${t.summary.id.replace(/^fake\./, "")}").`);
+      if (errors.length) return { ok: false, errors };
+      const sequence = fill(t, values);
+      if (options.name) sequence.name = options.name;
+      return { ok: true, sequence, openSlots: effectSequenceSlots(sequence), notes: [] };
+    }
+  };
+}
+
 // src/effects/fake.ts
 var HEX = "^#[0-9a-fA-F]{6}$";
 var colour = (description) => ({ type: "string", pattern: HEX, description });
@@ -689,6 +1126,7 @@ function createFakeEffectProvider(options = {}) {
     supportsVector: true,
     supportsAuthoring,
     ...options.camera ? { supportsCamera: true } : {},
+    ...options.templates ? { supportsTemplates: true } : {},
     maxSize: 8192,
     ...options.capabilities
   };
@@ -775,6 +1213,7 @@ function createFakeEffectProvider(options = {}) {
         return sampleCameraViews((u) => camera(id, { from, to, u, ms, stage }, values), { ms, fps, cut: d.camera?.cut });
       }
     } : {},
+    ...options.templates ? fakeTemplateMethods() : {},
     ...supportsAuthoring ? {
       openAuthoring: (from) => createEffectAuthoringSession(from, { provider })
     } : {}
@@ -1304,6 +1743,12 @@ export {
   CAMERA_MOVE_ROLES,
   EFFECT_ERROR_CODES,
   EFFECT_KINDS,
+  EFFECT_LAYER_ROLES,
+  EFFECT_LAYER_USES,
+  EFFECT_SEQUENCE_NAME,
+  EFFECT_SUBJECT_KINDS,
+  EFFECT_TEMPLATE_SLOT_TYPES,
+  EFFECT_TRANSITION_MS,
   EFFECT_USES,
   EFFECT_USE_LABELS,
   EffectControlError,
@@ -1314,6 +1759,7 @@ export {
   EffectsSlot,
   NoEffectsProviderError,
   UnknownEffectError,
+  UnknownTemplateError,
   applyEffectMask,
   cameraBoxOfView,
   cameraMoveField,
@@ -1322,6 +1768,8 @@ export {
   cameraMovesFor,
   cameraViewOfBox,
   checkEffectProvider,
+  checkEffectSequence,
+  checkTemplateValues,
   countEffectTags,
   createEffectAuthoringSession,
   createEffectAuthoringToolProvider,
@@ -1331,10 +1779,17 @@ export {
   effectControlField,
   effectFieldValue,
   effectFontFamilies,
+  effectLayerInput,
+  effectLayerOffered,
+  effectLayerRole,
   effectOffered,
   effectParameterFields,
   effectSampleInputs,
   effectSamplePicture,
+  effectSequenceEffects,
+  effectSequenceSlots,
+  effectSubjectKind,
+  effectSubjectProblem,
   effectValueErrors,
   encodeEffectFloat,
   groupEffectsByCategory,
@@ -1343,6 +1798,7 @@ export {
   isEffectError,
   isEffectFontControl,
   isEffectPixels,
+  isSubjectTemplateSlot,
   linearToSrgb,
   normaliseEffectTag,
   renderEffectThumbnail,
@@ -1351,5 +1807,12 @@ export {
   sampleCameraViews,
   sampleEffectCameraMove,
   searchEffectSummaries,
-  srgbToLinear
+  searchTemplateSummaries,
+  srgbToLinear,
+  templateDefaultValues,
+  templateSlotSchema,
+  templateSlotSummary,
+  templateSlotTakes,
+  templateValueProblem,
+  templateValuesSchema
 };

package/dist/effects/templates.d.cts

@@ -0,0 +1,56 @@
+/**
+ * Helpers for sequence templates and the sequences they fill to (see `EffectSequence`): the
+ * values a template takes as a JSON Schema, checking values before asking the provider, checking
+ * a sequence before loading it, and which input a layer's subject feeds. Dependency-free.
+ */
+import type { JsonSchema } from '../tools/schema.cjs';
+import { type EffectDescription, type EffectLayer, type EffectLayerRole, type EffectSequence, type EffectSubjectKind, type EffectSummary, type EffectTemplateSearchOptions, type EffectTemplateSlot, type EffectTemplateSummary } from './types.cjs';
+export declare const EFFECT_SEQUENCE_NAME: RegExp;
+/** True for a subject slot (`image`, `video`, `svg`). */
+export declare const isSubjectTemplateSlot: (slot: Pick<EffectTemplateSlot, "type">) => boolean;
+/** The kind of a subject (`image`, `video`, `svg`, `text`, `slot`), or undefined when it is none of them. */
+export declare function effectSubjectKind(subject: unknown): EffectSubjectKind | undefined;
+/** What a slot takes, in a few words ("words (up to 40 characters)", "a colour like #FF5A36"). */
+export declare function templateSlotTakes(slot: EffectTemplateSlot): string;
+/** The problem with one value for a slot, as a sentence, or undefined when it fits. */
+export declare function templateValueProblem(slot: EffectTemplateSlot, value: unknown): string | undefined;
+/**
+ * Every problem with `values` for a template's slots, as sentences: unknown slots, wrong types,
+ * out-of-range numbers, text too long. Empty when they fit. Slots left out take their defaults.
+ */
+export declare function checkTemplateValues(slots: readonly EffectTemplateSlot[], values: unknown): string[];
+/** One slot's value as a JSON Schema. */
+export declare function templateSlotSchema(slot: EffectTemplateSlot): JsonSchema;
+/** The values a template takes as a strict JSON Schema (every slot optional; `additionalProperties: false`). */
+export declare function templateValuesSchema(slots: readonly EffectTemplateSlot[]): JsonSchema & {
+    type: 'object';
+};
+/** The defaults of a template's text, colour and number slots: an example `values` object to change. */
+export declare function templateDefaultValues(slots: readonly EffectTemplateSlot[]): Record<string, string | number>;
+/** One line on a slot: its name, type, what it takes and its default. */
+export declare function templateSlotSummary(slot: EffectTemplateSlot): string;
+/** Templates matching every word of `query` (in name, id, tags or description) and every tag, best first. */
+export declare function searchTemplateSummaries<T extends EffectTemplateSummary>(catalog: readonly T[], options?: EffectTemplateSearchOptions): T[];
+/** Where a layer sits: its `role`, else `subject` when it has a `rect`, else `background`. */
+export declare const effectLayerRole: (layer: Pick<EffectLayer, "role" | "rect">) => EffectLayerRole;
+/**
+ * The image input a layer's subject feeds: `source` when the effect has it, else its first image
+ * input; undefined when it takes no picture (a generator: then the layer cannot have a subject).
+ */
+export declare function effectLayerInput(description: Pick<EffectDescription, 'inputs'>): string | undefined;
+/** The uses a layer's effect may have (a transition belongs on `EffectSequenceShot.transition`, a camera move on `camera`). */
+export declare const EFFECT_LAYER_USES: readonly ["generator", "filter", "overlay", "title"];
+/** True for an effect a layer can show. */
+export declare const effectLayerOffered: (e: Pick<EffectSummary, "kind" | "uses">) => boolean;
+/** Problems with one subject, or undefined when it is sound. */
+export declare function effectSubjectProblem(subject: unknown): string | undefined;
+/**
+ * Every problem with a sequence's shape, as sentences ("shot 2, layer 1: …"). With `catalog`, also
+ * effect ids it does not list, layer effects that cannot be layers and transitions without the
+ * use `transition`. Empty when the sequence is sound.
+ */
+export declare function checkEffectSequence(sequence: unknown, catalog?: readonly Pick<EffectSummary, 'id' | 'kind' | 'uses'>[]): string[];
+/** Every effect id a sequence names (layers and transitions), each once. */
+export declare function effectSequenceEffects(sequence: EffectSequence): string[];
+/** Subject slots a sequence leaves for the host (`{ slot }` subjects), each once. */
+export declare function effectSequenceSlots(sequence: EffectSequence): string[];