@cueframe/kernel 0.2.57 → 0.2.59-rc.0

package/dist/component-runtime/template/testing.js

@@ -0,0 +1,383 @@
+import {
+  bindTemplate,
+  findReferences,
+  parseTemplateDocument
+} from "../../chunk-NECN7TT4.js";
+import "../../chunk-CEO47DIE.js";
+import {
+  contractFacts
+} from "../../chunk-XR76OZKC.js";
+import {
+  CANVAS2D_COMPONENT_MANIFEST_V2
+} from "../../chunk-BZVOCVQV.js";
+import "../../chunk-ZCEYEIRB.js";
+import "../../chunk-6KZCXAYL.js";
+import "../../chunk-AFUITAH6.js";
+import "../../chunk-WPZKOVYF.js";
+import "../../chunk-B7J5UUUV.js";
+import "../../chunk-EQH37KNZ.js";
+import "../../chunk-WREYUH2E.js";
+import {
+  CURRENT_MATTE_BAKE_VERSION
+} from "../../chunk-IVFMOHAC.js";
+import "../../chunk-DKBFAQCW.js";
+import "../../chunk-ILO4NEZ3.js";
+import "../../chunk-XQGQ5EFS.js";
+import "../../chunk-VG2ND6PX.js";
+import {
+  parseSceneShotSpecV2
+} from "../../chunk-CL5Y6V6K.js";
+import "../../chunk-2L7PYYJK.js";
+import "../../chunk-OOL7ZUG7.js";
+import "../../chunk-U67V476Y.js";
+
+// ../execution/component-runtime/src/template/testing/fixtures.ts
+function minimalTemplate() {
+  return {
+    v: 1,
+    slug: "warp",
+    name: "Warp",
+    composition: { v: 1, format: { aspectRatio: "16:9", fps: 30, resolution: "fhd" }, tracks: [
+      { id: "video", kind: "video", name: "Source", contents: [
+        {
+          id: "main",
+          kind: "video",
+          startTime: 0,
+          duration: 8,
+          source: { kind: "media", mediaId: "{{source}}", trim: { start: 4, end: 12 }, muted: false }
+        }
+      ] }
+    ] },
+    parameters: [{ name: "source", type: "media", kind: "video", required: true }],
+    components: {}
+  };
+}
+function withComponent(doc, opts = {}) {
+  const { slot, slotKind } = opts;
+  doc.components.c1 = {
+    source: {
+      version: 2,
+      componentId: "c1",
+      tsxSource: "export default () => null;",
+      manifest: { ...CANVAS2D_COMPONENT_MANIFEST_V2, assets: slot ? { [slot]: { kind: slotKind ?? "image", required: true } } : {} }
+    },
+    name: "C1",
+    description: "fixture component",
+    category: "text",
+    propSchema: { type: "object" }
+  };
+  doc.composition.tracks.push({ id: "comp", kind: "overlay", name: "C", contents: [{
+    id: "c",
+    kind: "overlay",
+    startTime: 0,
+    duration: 2,
+    source: { kind: "component", componentId: "c1", props: {}, ...slot ? { assets: { [slot]: `{{${slot}}}` } } : {} }
+  }] });
+  return doc;
+}
+function sceneWithImageSlot(slot) {
+  return parseSceneShotSpecV2({
+    version: 2,
+    referenceSize: { width: 1920, height: 1080 },
+    environment: { kind: "photographic-studio-v1" },
+    backdrop: { kind: "solid", color: "#000000" },
+    layers: [{
+      kind: "page",
+      id: "p",
+      transform: { position: [0, 0, 0], rotation: [0, 0, 0], scale: 1 },
+      width: 720,
+      height: 900,
+      surfaces: { content: { source: "image", assetSlot: slot } }
+    }]
+  });
+}
+var video = (durationSec = 30) => ({ mediaId: "m1", kind: "video", durationSec });
+var withTrack = (doc, track) => {
+  doc.composition.tracks.push(track);
+  return doc;
+};
+var overlay = (params) => ({ id: "t", kind: "overlay", name: "T", contents: [{
+  id: "o",
+  kind: "overlay",
+  startTime: 0,
+  duration: 2,
+  source: { kind: "overlay", primitiveId: "heroText", params }
+}] });
+var withParams = (doc, ...ps) => {
+  doc.parameters.push(...ps);
+  return doc;
+};
+var TEMPLATE_BINDING_FIXTURES = [
+  {
+    name: "minimal-video",
+    doc: minimalTemplate,
+    media: { source: video() },
+    expect: { at: [["tracks.0.contents.0.source.mediaId", "m1"]] }
+  },
+  {
+    name: "text-inline-and-whole-leaf",
+    doc: () => withTrack(
+      withParams(minimalTemplate(), { name: "title", type: "string", required: true }, { name: "size", type: "number", required: true }),
+      overlay({ text: "Hi {{title}}!", fontSizePct: "{{size}}" })
+    ),
+    values: { title: "Sam", size: 27 },
+    media: { source: video() },
+    expect: { at: [["tracks.1.contents.0.source.params", { text: "Hi Sam!", fontSizePct: 27 }]] }
+  },
+  {
+    name: "escaped-brace",
+    doc: () => withTrack(minimalTemplate(), overlay({ text: "\\{{not a ref}}" })),
+    media: { source: video() },
+    expect: { at: [["tracks.1.contents.0.source.params.text", "{{not a ref}}"]] }
+  },
+  {
+    name: "image-swap-strips-trim",
+    doc: () => {
+      const doc = minimalTemplate();
+      doc.parameters[0] = { name: "logo", type: "media", kind: "image", required: true };
+      doc.composition.tracks[0] = { id: "img", kind: "image", name: "Logo", contents: [{
+        id: "l",
+        kind: "image",
+        startTime: 0,
+        duration: 3,
+        fit: "contain",
+        source: { kind: "media", mediaId: "{{logo}}", trim: { start: 0, end: 3 }, playbackRate: 1 }
+      }] };
+      return doc;
+    },
+    media: { logo: { mediaId: "m2", kind: "image" } },
+    expect: { at: [["tracks.0.contents.0.fit", "contain"], ["tracks.0.contents.0.source.trim", void 0], ["tracks.0.contents.0.source.playbackRate", void 0]] }
+  },
+  {
+    name: "missing-required",
+    doc: minimalTemplate,
+    media: {},
+    expect: { error: { code: "template_values_invalid", fields: [{ param: "source", reason: "required" }] } }
+  },
+  {
+    name: "kind-mismatch",
+    doc: minimalTemplate,
+    media: { source: { mediaId: "m1", kind: "image" } },
+    expect: { error: { code: "template_media_kind_mismatch" } }
+  },
+  {
+    name: "short-media",
+    doc: minimalTemplate,
+    media: { source: video(10) },
+    expect: { error: { code: "template_values_invalid", fields: [{ param: "source", reason: "media is 10s, template trims to 12s" }] } }
+  },
+  {
+    name: "short-media-no-trim",
+    doc: () => {
+      const doc = minimalTemplate();
+      delete doc.composition.tracks[0].contents[0].source.trim;
+      return doc;
+    },
+    media: { source: video(5) },
+    expect: { error: { code: "template_values_invalid", fields: [{ param: "source", reason: "media is 5s, clip needs 8s" }] } }
+  },
+  {
+    name: "asset-slot-image",
+    doc: () => withParams(withComponent(minimalTemplate(), { slot: "screen", slotKind: "image" }), { name: "screen", type: "media", kind: "image", required: true }),
+    media: { source: video(), screen: { mediaId: "m9", kind: "image" } },
+    expect: { at: [["tracks.1.contents.0.source.assets", { screen: "m9" }]] }
+  },
+  {
+    name: "asset-slot-kind-mismatch",
+    doc: () => withParams(withComponent(minimalTemplate(), { slot: "screen", slotKind: "image" }), { name: "screen", type: "media", kind: "image", required: true }),
+    media: { source: video(), screen: { mediaId: "m9", kind: "video" } },
+    expect: { error: { code: "template_media_kind_mismatch" } }
+  },
+  {
+    name: "scene-shot-slot",
+    doc: () => withTrack(
+      withParams(minimalTemplate(), { name: "shot", type: "media", kind: "image", required: true }),
+      { id: "s", kind: "overlay", name: "S", contents: [{
+        id: "sc",
+        kind: "overlay",
+        startTime: 0,
+        duration: 4,
+        source: { kind: "component", componentId: "scene-x", props: { scene: sceneWithImageSlot("shot") }, assets: { shot: "{{shot}}" } }
+      }] }
+    ),
+    media: { source: video(), shot: { mediaId: "m5", kind: "image" } },
+    expect: { at: [["tracks.1.contents.0.source.assets", { shot: "m5" }]] }
+  },
+  {
+    name: "undeclared-reference",
+    doc: () => withTrack(minimalTemplate(), overlay({ text: "{{nope}}" })),
+    media: { source: video() },
+    expect: { error: { code: "template_parameter_undeclared" } }
+  },
+  {
+    name: "misplaced-reference",
+    doc: () => {
+      const doc = withParams(minimalTemplate(), { name: "len", type: "number", required: true });
+      doc.composition.tracks[0].contents[0].duration = "{{len}}";
+      return doc;
+    },
+    values: { len: 8 },
+    media: { source: video() },
+    expect: { error: { code: "template_values_invalid" } }
+  },
+  {
+    name: "preset-base-with-override",
+    doc: () => {
+      const doc = withParams(minimalTemplate(), { name: "title", type: "string", required: true }, { name: "layout", type: "enum", required: true, options: ["split", "stacked"] });
+      doc.presets = { warm: { label: "Warm", values: { title: "Warm", layout: "split" } } };
+      return withTrack(doc, overlay({ text: "{{title}}", layout: "{{layout}}" }));
+    },
+    values: { title: "Mine" },
+    preset: "warm",
+    media: { source: video() },
+    expect: { at: [["tracks.1.contents.0.source.params", { text: "Mine", layout: "split" }]] }
+  },
+  {
+    name: "unknown-preset",
+    doc: minimalTemplate,
+    preset: "nope",
+    media: { source: video() },
+    expect: { error: { code: "template_values_invalid", fields: [{ param: "preset", reason: "unknown preset nope" }] } }
+  },
+  {
+    name: "enum-outside-options",
+    doc: () => withParams(minimalTemplate(), { name: "layout", type: "enum", required: true, options: ["split"] }),
+    values: { layout: "stacked" },
+    media: { source: video() },
+    expect: { error: { code: "template_values_invalid", fields: [{ param: "layout", reason: "expected one of split" }] } }
+  },
+  {
+    name: "boolean-whole-leaf-and-inline",
+    doc: () => withTrack(withParams(minimalTemplate(), { name: "on", type: "boolean", required: true }), overlay({ show: "{{on}}", note: "on={{on}}" })),
+    values: { on: "true" },
+    media: { source: video() },
+    expect: { at: [["tracks.1.contents.0.source.params", { show: true, note: "on=true" }]] }
+  }
+];
+function readFixturePath(value, path) {
+  return path.split(".").reduce((v, key) => v == null ? void 0 : v[key], value);
+}
+
+// ../execution/component-runtime/src/template/testing/templateApplyContract.ts
+var kit = (name) => ({
+  kitId: "ignored",
+  name,
+  colors: { primary: "#111111", secondary: "#222222", accent: "#f7c948", background: "#000000", text: "#ffffff" },
+  headingFont: { fontFamily: "Inter", fontWeight: 700 },
+  bodyFont: { fontFamily: "Inter", fontWeight: 400 }
+});
+function contractDoc() {
+  const doc = minimalTemplate();
+  doc.parameters.push({ name: "title", type: "string", required: true, default: "Hello" });
+  doc.composition.tracks.push({ id: "t", kind: "overlay", name: "T", contents: [{
+    id: "o",
+    kind: "overlay",
+    startTime: 0,
+    duration: 2,
+    source: { kind: "overlay", primitiveId: "heroText", params: { text: "{{title}}" } }
+  }] });
+  doc.brandKit = kit("Document kit");
+  doc.presets = { granite: { label: "Granite", values: { title: "Granite" }, brandKit: kit("Granite kit") } };
+  return parseTemplateDocument(doc);
+}
+var source = { mediaId: "m1", kind: "video", durationSec: 30 };
+var SAMPLE_SHA = "b".repeat(64);
+var CONTRACT_MATTE_KEY = "4aa54bdd6d0d";
+function matteCase(bakeVersion, sha256) {
+  const doc = minimalTemplate();
+  doc.parameters[0] = {
+    name: "source",
+    type: "media",
+    kind: "video",
+    required: true,
+    sample: { url: "https://cdn.cueframe.ai/samples/contract.mp4", sha256: SAMPLE_SHA, mimeType: "video/mp4" },
+    prepared: { mattes: { [CONTRACT_MATTE_KEY]: { url: "https://cdn.cueframe.ai/mattes/contract.mp4", sha256: "c".repeat(64), mimeType: "video/mp4", bakeVersion } } }
+  };
+  return { doc: parseTemplateDocument(doc), values: {}, media: { source: { ...source, sha256 } } };
+}
+function logicalMedia(doc, composition) {
+  const out = structuredClone(composition);
+  const media = new Set(doc.parameters.filter((p) => p.type === "media").map((p) => p.name));
+  for (const ref of findReferences(doc)) {
+    if (!ref.wholeLeaf || !media.has(ref.name)) continue;
+    const parent = ref.path.slice(0, -1).reduce((v, k) => v?.[k], out);
+    const leaf = ref.path[ref.path.length - 1];
+    if (typeof parent?.[leaf] === "string" && parent[leaf].length > 0) parent[leaf] = `media:${ref.name}`;
+  }
+  return out;
+}
+function runTemplateApplyContract(harness) {
+  const { describe, it, expect, makeLane, kind } = harness;
+  const fact = contractFacts(it, harness.knownRed);
+  describe(`template apply contract (${kind})`, () => {
+    fact("contract_apply_reads_back_bound_composition", async () => {
+      const lane = await makeLane();
+      const doc = contractDoc();
+      await lane.apply({ doc, values: { title: "Sam" }, media: { source } });
+      const stored = await lane.readBack();
+      expect(stored && logicalMedia(doc, stored.composition)).toEqual(logicalMedia(doc, bindTemplate(doc, { title: "Sam" }, { source })));
+    });
+    fact("contract_apply_preset_kit_over_document_kit", async () => {
+      const lane = await makeLane();
+      const doc = contractDoc();
+      const plain = await lane.apply({ doc, values: {}, media: { source } });
+      const granite = await lane.apply({ doc, values: {}, media: { source }, preset: "granite" });
+      expect(plain.brandKit?.name).toBe("Document kit");
+      expect(granite.brandKit?.name).toBe("Granite kit");
+      if (kind === "server" || plain.brandKit?.kitId !== void 0) expect(plain.brandKit?.kitId).toBe(`template:${doc.slug}`);
+      if (kind === "server" || granite.brandKit?.kitId !== void 0) expect(granite.brandKit?.kitId).toBe(`template:${doc.slug}:granite`);
+    });
+    fact("contract_apply_refuses_missing_media", async () => {
+      const lane = await makeLane();
+      await expect(lane.apply({ doc: contractDoc(), values: {}, media: {} })).rejects.toMatchObject({ code: "template_values_invalid" });
+    });
+    if (kind === "server") {
+      const server = async () => {
+        const lane = await makeLane();
+        if (!lane.server) throw new Error(`${lane.name}: a server lane supplies lane.server`);
+        return { lane, server: lane.server };
+      };
+      fact("contract_apply_installs_component_once", async () => {
+        const { lane, server: s } = await server();
+        const doc = parseTemplateDocument(withComponent(contractDoc()));
+        await lane.apply({ doc, values: {}, media: { source } });
+        await lane.apply({ doc, values: {}, media: { source } });
+        expect(await s.readComponentVersionCount("c1")).toBe(1);
+      });
+      fact("contract_apply_refuses_differing_component", async () => {
+        const { lane, server: s } = await server();
+        await s.seedComponent("c1", "export default () => 1;");
+        const doc = parseTemplateDocument(withComponent(contractDoc()));
+        await expect(lane.apply({ doc, values: {}, media: { source } })).rejects.toMatchObject({ code: "template_component_conflict" });
+        expect(await s.readComponentVersionCount("c1")).toBe(1);
+        expect(await lane.readBack()).toBe(null);
+      });
+      fact("contract_apply_brandKitId_over_both_kits", async () => {
+        const { lane, server: s } = await server();
+        const brandKitId = await s.seedBrandKit("Org kit");
+        const applied = await lane.apply({ doc: contractDoc(), values: {}, media: { source }, preset: "granite", brandKitId });
+        expect(applied.brandKit?.name).toBe("Org kit");
+      });
+    }
+    if (kind === "desktop") {
+      fact("contract_apply_refuses_stale_matte", async () => {
+        const lane = await makeLane();
+        await expect(lane.apply(matteCase(`stale-${CURRENT_MATTE_BAKE_VERSION}`, SAMPLE_SHA))).rejects.toThrow(/bakeVersion/);
+      });
+      fact("contract_apply_matte_only_on_its_sample", async () => {
+        const lane = await makeLane();
+        expect((await lane.apply(matteCase(CURRENT_MATTE_BAKE_VERSION, SAMPLE_SHA))).mattes).toEqual([CONTRACT_MATTE_KEY]);
+        expect((await lane.apply(matteCase(CURRENT_MATTE_BAKE_VERSION, "d".repeat(64)))).mattes ?? []).toEqual([]);
+      });
+    }
+  });
+}
+export {
+  CONTRACT_MATTE_KEY,
+  TEMPLATE_BINDING_FIXTURES,
+  minimalTemplate,
+  readFixturePath,
+  runTemplateApplyContract,
+  sceneWithImageSlot,
+  withComponent
+};

package/dist/component-runtime/template.d.ts

@@ -0,0 +1 @@
+export * from "../_members/component-runtime/template/index.js";

package/dist/component-runtime/template.js

@@ -0,0 +1,251 @@
+import {
+  MATTE_KEY,
+  PRESET_NAME,
+  TEMPLATE_MAX_BYTES,
+  TemplateDocumentSchema,
+  TemplateError,
+  TemplateParameterSchema,
+  bindTemplate,
+  checkReferences,
+  coerceParameterValue,
+  findReferences,
+  parseTemplateDocument
+} from "../chunk-NECN7TT4.js";
+import "../chunk-CEO47DIE.js";
+import "../chunk-BZVOCVQV.js";
+import "../chunk-ZCEYEIRB.js";
+import "../chunk-6KZCXAYL.js";
+import "../chunk-AFUITAH6.js";
+import "../chunk-WPZKOVYF.js";
+import "../chunk-B7J5UUUV.js";
+import "../chunk-EQH37KNZ.js";
+import "../chunk-WREYUH2E.js";
+import {
+  CURRENT_MATTE_BAKE_VERSION
+} from "../chunk-IVFMOHAC.js";
+import "../chunk-DKBFAQCW.js";
+import "../chunk-ILO4NEZ3.js";
+import "../chunk-XQGQ5EFS.js";
+import "../chunk-VG2ND6PX.js";
+import "../chunk-CL5Y6V6K.js";
+import "../chunk-2L7PYYJK.js";
+import "../chunk-OOL7ZUG7.js";
+import "../chunk-U67V476Y.js";
+
+// ../execution/component-runtime/src/template/extract.ts
+function extractTemplate(args) {
+  const escape = (v) => typeof v === "string" ? v.replaceAll("{{", "\\{{") : Array.isArray(v) ? v.map(escape) : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, escape(x)])) : v;
+  const composition = escape(args.composition);
+  const clips = /* @__PURE__ */ new Map();
+  for (const track of composition.tracks) for (const clip2 of track.contents) clips.set(clip2.id, clip2);
+  const clip = (id) => {
+    const found = clips.get(id);
+    if (!found) throw new Error(`clip ${id} is not in the composition`);
+    return found;
+  };
+  const parameters = [];
+  for (const m of args.mediaParams) {
+    const source = clip(m.clipId).source;
+    const holder = m.slot === void 0 ? source : source?.assets;
+    const key = m.slot ?? "mediaId";
+    if (typeof holder?.[key] !== "string" || holder[key].length === 0) {
+      throw new Error(`clip ${m.clipId} has no media at source.${m.slot === void 0 ? "mediaId" : `assets.${m.slot}`}`);
+    }
+    parameters.push({ name: m.name, type: "media", kind: m.kind, required: m.required ?? true, default: holder[key], ...m.label ? { label: m.label } : {} });
+    holder[key] = `{{${m.name}}}`;
+  }
+  for (const t of args.textParams) {
+    const parent = t.leafPath.slice(0, -1).reduce((v, k) => v?.[k], clip(t.clipId));
+    const leaf = t.leafPath[t.leafPath.length - 1];
+    if (parent == null || !(leaf in parent)) throw new Error(`clip ${t.clipId} has no leaf ${t.leafPath.join(".")}`);
+    parameters.push({
+      name: t.name,
+      type: t.type,
+      required: t.required,
+      default: t.default ?? parent[leaf],
+      ...t.options ? { options: t.options } : {},
+      ...t.label ? { label: t.label } : {},
+      ...t.min !== void 0 ? { min: t.min } : {},
+      ...t.max !== void 0 ? { max: t.max } : {}
+    });
+    parent[leaf] = `{{${t.name}}}`;
+  }
+  const doc = parseTemplateDocument({
+    v: 1,
+    slug: args.slug,
+    name: args.name,
+    ...args.description ? { description: args.description } : {},
+    composition,
+    parameters,
+    components: args.components
+  });
+  const { misplaced, mediaSiteErrors } = checkReferences(doc);
+  if (misplaced.length || mediaSiteErrors.length) {
+    throw new TemplateError("template_values_invalid", [...misplaced.map((m) => `reference outside a string leaf: ${m}`), ...mediaSiteErrors].join("; "));
+  }
+  return doc;
+}
+
+// ../execution/component-runtime/src/template/checks.ts
+var TEMPLATE_PROBES = Object.freeze([
+  { name: "red", rgb: [230, 40, 40] },
+  { name: "green", rgb: [40, 200, 60] },
+  { name: "blue", rgb: [40, 80, 230] },
+  { name: "yellow", rgb: [240, 220, 40] },
+  { name: "magenta", rgb: [220, 40, 220] },
+  { name: "cyan", rgb: [40, 210, 220] },
+  { name: "orange", rgb: [245, 140, 30] },
+  { name: "violet", rgb: [130, 60, 200] }
+]);
+var TEMPLATE_CHECK_LIMITS = Object.freeze({
+  /** A pixel matches a probe when every channel is within this distance. */
+  probeTolerance: 36,
+  /** A parameter is seen when some frame shows at least this many probe pixels, counted at full output resolution (a 20x20 patch). */
+  minFullResPixels: 400,
+  /** Below this many full-resolution probe pixels (about 64x64) the parameter is seen but flagged as barely visible. */
+  lowFullResPixels: 4096,
+  /** A pixel changed between two frames when some channel moved more than this. */
+  diffThreshold: 24,
+  /** Consecutive sampled frames that differ in fewer pixels than this count as not moving. */
+  stillDiff: 2e-3,
+  /** A frame is blank when this fraction of its pixels sits within `blankSpread` of its mean colour (a uniform frame). */
+  blankShare: 0.999,
+  blankSpread: 8,
+  /** More blank sampled frames than this fraction fails the template. */
+  blankFraction: 0.2,
+  /** The last-to-first change may be at most this many times the average neighbouring change. */
+  seamRatio: 2.5
+});
+function templateCheckFrames(durationInFrames, loop, stride = 5) {
+  if (!Number.isInteger(durationInFrames) || durationInFrames < 4) throw new Error("A template check needs at least 4 frames.");
+  if (!Number.isInteger(stride) || stride < 1) throw new Error("stride must be a positive integer.");
+  const frames = /* @__PURE__ */ new Set();
+  for (let f = 0; f < durationInFrames; f += stride) frames.add(f);
+  if (loop) for (const f of [0, 1, durationInFrames - 2, durationInFrames - 1]) frames.add(f);
+  return [...frames].sort((a, b) => a - b);
+}
+function assignTemplateProbes(parameters) {
+  const visual = parameters.filter((p) => p.type === "media" && (p.kind === "image" || p.kind === "video"));
+  if (visual.length > TEMPLATE_PROBES.length) {
+    throw new Error(`A template check supports at most ${TEMPLATE_PROBES.length} image or video parameters; this template has ${visual.length}.`);
+  }
+  return Object.fromEntries(visual.map((p, i) => [p.name, TEMPLATE_PROBES[i]]));
+}
+function assertFrame(input, frame) {
+  if (frame.rgba.length !== input.width * input.height * 4) {
+    throw new Error(`Frame ${frame.frame} has ${frame.rgba.length} bytes; expected ${input.width * input.height * 4}.`);
+  }
+}
+function probeCoverage(rgba, probe, tolerance = TEMPLATE_CHECK_LIMITS.probeTolerance) {
+  const [r, g, b] = probe.rgb;
+  let hits = 0;
+  for (let i = 0; i < rgba.length; i += 4) {
+    if (Math.abs(rgba[i] - r) <= tolerance && Math.abs(rgba[i + 1] - g) <= tolerance && Math.abs(rgba[i + 2] - b) <= tolerance) hits++;
+  }
+  return hits / (rgba.length / 4);
+}
+function changedFraction(a, b) {
+  const threshold = TEMPLATE_CHECK_LIMITS.diffThreshold;
+  let changed = 0;
+  for (let i = 0; i < a.length; i += 4) {
+    if (Math.abs(a[i] - b[i]) > threshold || Math.abs(a[i + 1] - b[i + 1]) > threshold || Math.abs(a[i + 2] - b[i + 2]) > threshold) changed++;
+  }
+  return changed / (a.length / 4);
+}
+function isBlankFrame(rgba) {
+  const n = rgba.length / 4;
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  for (let i = 0; i < rgba.length; i += 4) {
+    r += rgba[i];
+    g += rgba[i + 1];
+    b += rgba[i + 2];
+  }
+  r /= n;
+  g /= n;
+  b /= n;
+  const spread = TEMPLATE_CHECK_LIMITS.blankSpread;
+  let near = 0;
+  for (let i = 0; i < rgba.length; i += 4) {
+    if (Math.abs(rgba[i] - r) <= spread && Math.abs(rgba[i + 1] - g) <= spread && Math.abs(rgba[i + 2] - b) <= spread) near++;
+  }
+  return near / n >= TEMPLATE_CHECK_LIMITS.blankShare;
+}
+function analyzeTemplateFrames(input) {
+  if (input.frames.length < 2) throw new Error("A template check needs at least two frames.");
+  if (!(input.scale > 0 && input.scale <= 1)) throw new Error("scale must be within (0, 1].");
+  const frames = [...input.frames].sort((a, b) => a.frame - b.frame);
+  for (const frame of frames) assertFrame(input, frame);
+  const byFrame = new Map(frames.map((f) => [f.frame, f.rgba]));
+  const failures = [];
+  const warnings = [];
+  const pixels = input.width * input.height;
+  const toFullRes = (coverage) => coverage * pixels / (input.scale * input.scale);
+  const slots = {};
+  for (const [name, probe] of Object.entries(input.slots)) {
+    let peak = 0;
+    let seenFrames = 0;
+    for (const frame of frames) {
+      const coverage = probeCoverage(frame.rgba, probe);
+      peak = Math.max(peak, coverage);
+      if (toFullRes(coverage) >= TEMPLATE_CHECK_LIMITS.minFullResPixels) seenFrames++;
+    }
+    const peakFullResPixels = Math.round(toFullRes(peak));
+    const seen = peakFullResPixels >= TEMPLATE_CHECK_LIMITS.minFullResPixels;
+    slots[name] = { seen, peakCoverage: peak, peakFullResPixels, framesSeen: seenFrames };
+    const percent = (peak * 100).toFixed(2);
+    if (!seen) failures.push(`Media parameter ${name} never appears (peak ${peakFullResPixels} px, ${percent}% of the frame).`);
+    else if (peakFullResPixels < TEMPLATE_CHECK_LIMITS.lowFullResPixels) warnings.push(`Media parameter ${name} is barely visible (peak ${peakFullResPixels} px, ${percent}% of the frame).`);
+  }
+  const blank = frames.filter((f) => isBlankFrame(f.rgba)).length;
+  const blankFraction = blank / frames.length;
+  if (blankFraction > TEMPLATE_CHECK_LIMITS.blankFraction) {
+    failures.push(`${Math.round(blankFraction * 100)}% of sampled frames are blank.`);
+  }
+  let still = true;
+  for (let i = 1; i < frames.length; i++) {
+    if (changedFraction(frames[i - 1].rgba, frames[i].rgba) >= TEMPLATE_CHECK_LIMITS.stillDiff) {
+      still = false;
+      break;
+    }
+  }
+  if (still) warnings.push("Nothing moves between sampled frames.");
+  let seam = null;
+  if (input.loop) {
+    const last = input.durationInFrames - 1;
+    const needed = [0, 1, last - 1, last];
+    if (needed.some((f) => !byFrame.has(f))) throw new Error(`A loop check needs frames ${needed.join(", ")}.`);
+    const across = changedFraction(byFrame.get(last), byFrame.get(0));
+    const neighbours = (changedFraction(byFrame.get(last - 1), byFrame.get(last)) + changedFraction(byFrame.get(0), byFrame.get(1))) / 2;
+    const ratio = across === 0 ? 0 : across / Math.max(neighbours, TEMPLATE_CHECK_LIMITS.stillDiff);
+    seam = { ratio };
+    if (ratio > TEMPLATE_CHECK_LIMITS.seamRatio) {
+      failures.push(`The loop jumps at its seam: the last-to-first change is ${ratio.toFixed(1)}x the neighbouring frames.`);
+    }
+  }
+  return { slots, blankFraction, still, seam, failures, warnings };
+}
+export {
+  CURRENT_MATTE_BAKE_VERSION,
+  MATTE_KEY,
+  PRESET_NAME,
+  TEMPLATE_CHECK_LIMITS,
+  TEMPLATE_MAX_BYTES,
+  TEMPLATE_PROBES,
+  TemplateDocumentSchema,
+  TemplateError,
+  TemplateParameterSchema,
+  analyzeTemplateFrames,
+  assignTemplateProbes,
+  bindTemplate,
+  changedFraction,
+  checkReferences,
+  coerceParameterValue,
+  extractTemplate,
+  findReferences,
+  isBlankFrame,
+  parseTemplateDocument,
+  probeCoverage,
+  templateCheckFrames
+};