motionrender 0.2.7 → 0.2.9

package/blocks/fx-paper-collage.json

@@ -0,0 +1,212 @@
+{
+  "id": "fx-paper-collage",
+  "name": "Paper collage",
+  "category": "effect",
+  "kind": "scene",
+  "durationFrames": 150,
+  "transition": {
+    "type": "fade",
+    "durationFrames": 12
+  },
+  "description": "Editorial paper-collage B-roll: stop-motion cutouts drop and slide over cardstock backing with tape strips and punchy label tags.",
+  "params": {
+    "subject": {
+      "type": "string",
+      "default": "",
+      "description": "Subject cutout image (asset id or path)"
+    },
+    "label": {
+      "type": "string",
+      "default": "KEY TAKEAWAY",
+      "description": "Punchy kicker on tape tag"
+    },
+    "headline": {
+      "type": "string",
+      "default": "Visual metaphor in motion",
+      "description": "Editorial caption text"
+    }
+  },
+  "layers": [
+    {
+      "id": "bg",
+      "type": "rect",
+      "x": 0,
+      "y": 0,
+      "width": "{{canvas.width}}",
+      "height": "{{canvas.height}}",
+      "fill": "{{bg}}"
+    },
+    {
+      "id": "backing-paper",
+      "type": "rect",
+      "x": "{{round(canvas.width * 0.5)}}",
+      "y": "{{round(canvas.height * 0.48)}}",
+      "width": "{{round(min(canvas.width, canvas.height) * 0.76)}}",
+      "height": "{{round(min(canvas.width, canvas.height) * 0.95)}}",
+      "rotation": -2.5,
+      "fill": "{{surface}}",
+      "radius": 4,
+      "shadow": {
+        "color": "rgba(0,0,0,0.2)",
+        "blur": 26,
+        "offsetX": 6,
+        "offsetY": 12
+      },
+      "animations": [
+        {
+          "property": "y",
+          "keyframes": [
+            { "frame": 0, "value": "{{canvas.height + 200}}", "easing": "easeOutBack" },
+            { "frame": 18, "value": "{{round(canvas.height * 0.48)}}" }
+          ]
+        }
+      ]
+    },
+    {
+      "if": "{{subject}}",
+      "id": "subject-image",
+      "type": "image",
+      "src": "{{subject}}",
+      "x": "{{round(canvas.width * 0.5)}}",
+      "y": "{{round(canvas.height * 0.45)}}",
+      "width": "{{round(min(canvas.width, canvas.height) * 0.62)}}",
+      "height": "{{round(min(canvas.width, canvas.height) * 0.62)}}",
+      "rotation": 3,
+      "filter": "grayscale(1) contrast(1.75) brightness(1.05)",
+      "shadow": {
+        "color": "rgba(0,0,0,0.25)",
+        "blur": 18,
+        "offsetX": 5,
+        "offsetY": 9
+      },
+      "animations": [
+        {
+          "property": "scale",
+          "keyframes": [
+            { "frame": 10, "value": 0.4, "easing": "easeOutBack" },
+            { "frame": 24, "value": 1.0 }
+          ]
+        }
+      ]
+    },
+    {
+      "if": "{{!subject}}",
+      "id": "subject-placeholder",
+      "type": "rect",
+      "x": "{{round(canvas.width * 0.5)}}",
+      "y": "{{round(canvas.height * 0.45)}}",
+      "width": "{{round(min(canvas.width, canvas.height) * 0.58)}}",
+      "height": "{{round(min(canvas.width, canvas.height) * 0.58)}}",
+      "rotation": 2,
+      "fill": "{{muted}}",
+      "radius": 8,
+      "shadow": {
+        "color": "rgba(0,0,0,0.2)",
+        "blur": 16,
+        "offsetX": 4,
+        "offsetY": 8
+      },
+      "animations": [
+        {
+          "property": "scale",
+          "keyframes": [
+            { "frame": 10, "value": 0.4, "easing": "easeOutBack" },
+            { "frame": 24, "value": 1.0 }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "tape-strip",
+      "type": "rect",
+      "x": "{{round(canvas.width * 0.38)}}",
+      "y": "{{round(canvas.height * 0.48 - min(canvas.width, canvas.height) * 0.45)}}",
+      "width": "{{round(min(canvas.width, canvas.height) * 0.24)}}",
+      "height": "{{round(min(canvas.width, canvas.height) * 0.055)}}",
+      "rotation": -16,
+      "fill": "rgba(240, 230, 210, 0.85)",
+      "startFrame": 20,
+      "shadow": {
+        "color": "rgba(0,0,0,0.1)",
+        "blur": 4,
+        "offsetX": 1,
+        "offsetY": 2
+      }
+    },
+    {
+      "id": "label-tag",
+      "type": "text",
+      "content": "{{label}}",
+      "fontFamily": "Inter",
+      "fontWeight": 900,
+      "fontSize": "{{round(min(canvas.width, canvas.height) * 0.042)}}",
+      "color": "#111111",
+      "background": "{{accent}}",
+      "padding": "{{round(min(canvas.width, canvas.height) * 0.015)}}",
+      "rotation": -3.5,
+      "x": "{{round(canvas.width * 0.5)}}",
+      "y": "{{round(canvas.height * 0.72)}}",
+      "startFrame": 28,
+      "shadow": {
+        "color": "rgba(0,0,0,0.2)",
+        "blur": 12,
+        "offsetX": 4,
+        "offsetY": 6
+      },
+      "animations": [
+        {
+          "property": "y",
+          "keyframes": [
+            { "frame": 28, "value": "{{round(canvas.height * 0.78)}}", "easing": "easeOutCubic" },
+            { "frame": 38, "value": "{{round(canvas.height * 0.72)}}" }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "headline-text",
+      "type": "text",
+      "content": "{{headline}}",
+      "fontFamily": "Inter",
+      "fontWeight": 700,
+      "fontSize": "{{round(min(canvas.width, canvas.height) * 0.038)}}",
+      "color": "{{text}}",
+      "maxWidth": "{{round(min(canvas.width, canvas.height) * 0.75)}}",
+      "textAlign": "center",
+      "x": "{{round(canvas.width * 0.5)}}",
+      "y": "{{round(canvas.height * 0.81)}}",
+      "startFrame": 36,
+      "animations": [
+        {
+          "property": "opacity",
+          "keyframes": [
+            { "frame": 36, "value": 0 },
+            { "frame": 46, "value": 1 }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "sfx-paper-drop",
+      "type": "audio",
+      "src": "sfx:thump",
+      "startFrame": 14,
+      "volume": 0.85
+    },
+    {
+      "id": "sfx-subject-slide",
+      "type": "audio",
+      "src": "sfx:whoosh",
+      "startFrame": 18,
+      "volume": 0.6
+    },
+    {
+      "id": "sfx-tag-snap",
+      "type": "audio",
+      "src": "sfx:pop",
+      "startFrame": 28,
+      "volume": 0.65
+    }
+  ]
+}
+

package/dist/cli.js

@@ -659,7 +659,7 @@ var init_src = __esm({
     spanSchema = z3.object({ text: z3.string(), color: paint.optional(), fontSize: z3.number().positive().optional(), fontWeight: fontWeight.optional(), fontStyle: fontStyle.optional(), fontFamily: z3.string().optional(), background: color.optional().describe("Highlight behind the span"), underline: z3.boolean().optional() });
     cssFilter = z3.string().regex(/^\s*((blur|brightness|contrast|grayscale|hue-rotate|invert|opacity|saturate|sepia|drop-shadow)\([^()]*(\([^()]*\)[^()]*)*\)\s*)+$/, 'Use CSS filter functions such as "brightness(1.2) saturate(0.5)"');
     blendModes = ["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"];
-    sfxNames = ["click", "tick", "pop", "whoosh", "thump", "ding", "riser"];
+    sfxNames = ["click", "tick", "pop", "whoosh", "thump", "ding", "riser", "shimmer", "sparkle", "impact", "ambient-pad"];
     isBuiltinSound = (src) => src.startsWith("sfx:");
     builtinSoundName = (src) => src.slice(4);
     gradeLooks = ["warm", "cool", "cinematic", "teal-orange", "noir", "vivid", "faded"];
@@ -813,7 +813,7 @@ var init_src = __esm({
       }),
       baseLayer.extend({ type: z3.literal("image"), src: z3.string().min(1), objectFit: z3.enum(["cover", "contain", "fill"]).default("cover"), radius: z3.number().nonnegative().default(0).describe("Rounded corners, clipping the picture") }),
       baseLayer.extend({ type: z3.literal("video"), src: z3.string().min(1), objectFit: z3.enum(["cover", "contain", "fill"]).default("cover"), radius: z3.number().nonnegative().default(0).describe("Rounded corners, clipping the picture"), trimStart: z3.number().int().nonnegative().default(0).describe("Frames of the source to skip, at the composition fps"), playbackRate: z3.number().positive().max(16).default(1), loop: z3.boolean().default(false).describe("Restart from the first source frame when the source ends; otherwise hold the last frame"), volume: z3.number().min(0).max(4).default(1).describe("Volume of the clip's own sound; 1 is unchanged; animatable"), muted: z3.boolean().default(false), duck: duckSchema.optional() }),
-      baseLayer.extend({ type: z3.literal("audio"), src: z3.string().min(1).refine((src) => !isBuiltinSound(src) || sfxNames.includes(builtinSoundName(src)), { message: `Built-in sounds are ${sfxNames.map((n) => `sfx:${n}`).join(", ")}` }).describe("An audio asset id, a file relative to the composition, or a built-in sound: sfx:click, sfx:tick, sfx:pop, sfx:whoosh, sfx:thump, sfx:ding, sfx:riser"), volume: z3.number().min(0).max(4).default(1).describe("1 is unchanged, 0.5 is half, 2 is double; animatable with keyframes"), duck: duckSchema.optional(), trimStart: z3.number().int().nonnegative().default(0).describe("Frames of the source to skip, at the composition fps"), playbackRate: z3.number().positive().max(16).default(1), loop: z3.boolean().default(false).describe("Restart from the start of the source when it ends; otherwise silence"), fadeInFrames: z3.number().int().nonnegative().default(0), fadeOutFrames: z3.number().int().nonnegative().default(0) }),
+      baseLayer.extend({ type: z3.literal("audio"), src: z3.string().min(1).refine((src) => !isBuiltinSound(src) || sfxNames.includes(builtinSoundName(src)), { message: `Built-in sounds are ${sfxNames.map((n) => `sfx:${n}`).join(", ")}` }).describe("An audio asset id, a file relative to the composition, or a built-in sound: sfx:click, sfx:tick, sfx:pop, sfx:whoosh, sfx:thump, sfx:ding, sfx:riser, sfx:shimmer, sfx:sparkle, sfx:impact, sfx:ambient-pad"), volume: z3.number().min(0).max(4).default(1).describe("1 is unchanged, 0.5 is half, 2 is double; animatable with keyframes"), duck: duckSchema.optional(), trimStart: z3.number().int().nonnegative().default(0).describe("Frames of the source to skip, at the composition fps"), playbackRate: z3.number().positive().max(16).default(1), loop: z3.boolean().default(false).describe("Restart from the start of the source when it ends; otherwise silence"), fadeInFrames: z3.number().int().nonnegative().default(0), fadeOutFrames: z3.number().int().nonnegative().default(0) }),
       // Captions: shows the line being spoken at each moment. With word timings the current word is highlighted; spoken words keep
       // `color`, words still to come use `upcomingColor`. x, y is the anchor of the first line (centre for textAlign center).
       baseLayer.extend({
@@ -1132,16 +1132,16 @@ function videoFrameIndex(layer, ownFrame, frameCount) {
 }
 function layerWindows(composition, include) {
   const out = [];
-  const walk = (layers, offset, limit) => {
+  const walk = (layers, offset, limit, scene) => {
     for (const layer of layers) {
       if (!layer.visible) continue;
       const start = offset + layer.startFrame, end = Math.min(limit, layer.endFrame === void 0 ? Infinity : offset + layer.endFrame);
       if (end <= start) continue;
-      if (layer.type === "group") walk(layer.children, start, end);
-      else if (include(layer)) out.push({ layer, startFrame: start, endFrame: end });
+      if (layer.type === "group") walk(layer.children, start, end, scene);
+      else if (include(layer)) out.push({ layer, startFrame: start, endFrame: end, scene });
     }
   };
-  for (const scene of composition.scenes) walk(scene.layers, scene.startFrame, Math.min(scene.startFrame + scene.durationFrames, composition.durationFrames));
+  for (const scene of composition.scenes) walk(scene.layers, scene.startFrame, Math.min(scene.startFrame + scene.durationFrames, composition.durationFrames), scene);
   return out;
 }
 function soundIntervals(composition, media = {}) {
@@ -1577,7 +1577,11 @@ var init_src5 = __esm({
       thump: tone("0.9*sin(2*PI*(110*t-80*t*t))*exp(-t*9)+0.3*sin(2*PI*55*t)*exp(-t*6)", 0.6),
       ding: tone("0.5*sin(2*PI*1318*t)*exp(-t*3)+0.25*sin(2*PI*3640*t)*exp(-t*5)+0.12*sin(2*PI*7110*t)*exp(-t*8)", 1.8),
       riser: tone("(t/1.6)*(t/1.6)*(0.6*sin(2*PI*(180*t+380*t*t))+0.25*sin(2*PI*(360*t+760*t*t)))", 1.6),
-      whoosh: ["-f", "lavfi", "-i", "anoisesrc=d=0.7:c=pink:a=0.9:r=48000:seed=11", "-af", "highpass=f=300,lowpass=f=3500,volume='sin(PI*t/0.7)*sin(PI*t/0.7)*sin(PI*t/0.7)':eval=frame,volume=3"]
+      whoosh: ["-f", "lavfi", "-i", "anoisesrc=d=0.7:c=pink:a=0.9:r=48000:seed=11", "-af", "highpass=f=300,lowpass=f=3500,volume='sin(PI*t/0.7)*sin(PI*t/0.7)*sin(PI*t/0.7)':eval=frame,volume=3"],
+      shimmer: tone("0.3*sin(2*PI*1318*t)*exp(-t*2.5)+0.25*sin(2*PI*1661*t)*exp(-t*3)+0.2*sin(2*PI*1975*t)*exp(-t*3.5)+0.15*sin(2*PI*2637*t)*exp(-t*4)", 1.5),
+      sparkle: tone("0.35*sin(2*PI*2093*t)*exp(-t*4)+0.25*sin(2*PI*2637*t)*exp(-t*5)+0.2*sin(2*PI*3136*t)*exp(-t*6)+0.15*sin(2*PI*4186*t)*exp(-t*7)", 1.2),
+      impact: tone("0.9*sin(2*PI*(160*t-120*t*t))*exp(-t*4)+0.6*sin(2*PI*(70*t-30*t*t))*exp(-t*2)+0.3*sin(2*PI*40*t)*exp(-t*1.5)", 1),
+      "ambient-pad": tone("0.25*(sin(2*PI*130.8*t)+0.2*sin(2*PI*131.2*t))+0.2*(sin(2*PI*196*t)+0.2*sin(2*PI*196.4*t))+0.2*(sin(2*PI*261.6*t)+0.15*sin(2*PI*329.6*t))*sin(PI*t/3.0)", 3)
     };
     sfxArgs = (name2, output) => {
       const recipe = sfxRecipes[name2];
@@ -2112,7 +2116,7 @@ async function createRenderer(composition, options3 = {}) {
       try {
         const page = await context.newPage();
         await page.setContent(sheetPage);
-        return Buffer.from(await page.evaluate((a) => window.sheet(a), { images, labels, columns, cell }), "base64");
+        return Buffer.from(await page.evaluate((a) => window.sheet(a), { images, labels, columns, cell, safeBands: options4.safeBands }), "base64");
       } finally {
         await context.close();
       }
@@ -2167,8 +2171,8 @@ var init_src7 = __esm({
 ${canvasRuntimeSource}
 const rt=createCanvasRuntime(document.querySelector('#c'),document.querySelector('#measure'));
 window.OVE={load:rt.load,draw:async(p)=>{await rt.draw(p);return rt.canvas.toDataURL('image/png').slice('data:image/png;base64,'.length)},inspect:async(p)=>{await rt.draw({...p,report:true});return rt.report()}};</script>`;
-    sheetPage = `<!doctype html><canvas id="s"></canvas><script>window.sheet=async({images,labels,columns,cell})=>{const c=document.querySelector('#s'),rows=Math.ceil(images.length/columns),gap=8,label=26,ctx=c.getContext('2d');c.width=columns*cell.w+(columns+1)*gap;c.height=rows*(cell.h+label)+(rows+1)*gap;ctx.fillStyle='#0b0d14';ctx.fillRect(0,0,c.width,c.height);ctx.font='600 15px system-ui,sans-serif';ctx.textBaseline='middle';
-for(let i=0;i<images.length;i++){const img=new Image();img.src=images[i];await img.decode();const x=gap+(i%columns)*(cell.w+gap),y=gap+Math.floor(i/columns)*(cell.h+label+gap);ctx.drawImage(img,x,y,cell.w,cell.h);ctx.fillStyle='#c9cfdd';ctx.fillText(labels[i],x+2,y+cell.h+label/2)}return c.toDataURL('image/png').slice(22)}</script>`;
+    sheetPage = `<!doctype html><canvas id="s"></canvas><script>window.sheet=async({images,labels,columns,cell,safeBands})=>{const c=document.querySelector('#s'),rows=Math.ceil(images.length/columns),gap=8,label=26,ctx=c.getContext('2d');c.width=columns*cell.w+(columns+1)*gap;c.height=rows*(cell.h+label)+(rows+1)*gap;ctx.fillStyle='#0b0d14';ctx.fillRect(0,0,c.width,c.height);ctx.font='600 15px system-ui,sans-serif';ctx.textBaseline='middle';
+for(let i=0;i<images.length;i++){const img=new Image();img.src=images[i];await img.decode();const x=gap+(i%columns)*(cell.w+gap),y=gap+Math.floor(i/columns)*(cell.h+label+gap);ctx.drawImage(img,x,y,cell.w,cell.h);if(safeBands){for(const b of safeBands){const bx=x+b.x0*cell.w,by=y+b.y0*cell.h,bw=(b.x1-b.x0)*cell.w,bh=(b.y1-b.y0)*cell.h;ctx.fillStyle='rgba(239,68,68,0.18)';ctx.fillRect(bx,by,bw,bh);ctx.lineWidth=1.5;ctx.strokeStyle='rgba(239,68,68,0.55)';ctx.strokeRect(bx,by,bw,bh);}}ctx.fillStyle='#c9cfdd';ctx.fillText(labels[i],x+2,y+cell.h+label/2)}return c.toDataURL('image/png').slice(22)}</script>`;
     allLayers = (composition) => composition.scenes.flatMap((scene) => scene.layers);
     browserArgs = ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", ...(process.env.OVE_CHROMIUM_ARGS ?? "").split(/\s+/).filter(Boolean)];
     browserInstallHint = `Install one with "ove browser install" (Playwright's Chromium, about 150 MB), install Google Chrome, or set OVE_CHROMIUM_EXECUTABLE to a Chromium-based browser.`;
@@ -2221,7 +2225,7 @@ async function planAudio(composition, baseDir, probe2 = hasAudioStream) {
     clips.push({ source: soundtrack, start: 0, duration, loop: true, volume: composition.export.audioVolume, envelope: volumeEnvelope({ layer: { volume: composition.export.audioVolume }, fps, start: 0, duration, duck: composition.export.duck, others }) });
   }
   const hasAudio = /* @__PURE__ */ new Map();
-  for (const { layer, startFrame, endFrame } of windows) {
+  for (const { layer, startFrame, endFrame, scene } of windows) {
     const source = await sourceOf(composition, layer.src, baseDir);
     await ensureExists(source);
     if (layer.type === "video") {
@@ -2229,7 +2233,11 @@ async function planAudio(composition, baseDir, probe2 = hasAudioStream) {
       if (!await hasAudio.get(source)) continue;
     }
     const start = startFrame / fps, duration = (endFrame - startFrame) / fps;
-    clips.push({ source, start, duration, trim: layer.trimStart / fps, rate: layer.playbackRate, loop: layer.loop, volume: layer.volume, envelope: volumeEnvelope({ layer, fps, start, duration, duck: layer.duck, others }), ...layer.type === "audio" ? { fadeIn: layer.fadeInFrames / fps, fadeOut: layer.fadeOutFrames / fps } : {} });
+    let fadeIn = layer.type === "audio" ? (layer.fadeInFrames ?? 0) / fps : 0;
+    let fadeOut = layer.type === "audio" ? (layer.fadeOutFrames ?? 0) / fps : 0;
+    if (scene?.transitionIn?.type === "fade" && fadeIn === 0 && startFrame === scene.startFrame) fadeIn = scene.transitionIn.durationFrames / fps;
+    if (scene?.transitionOut?.type === "fade" && fadeOut === 0 && endFrame === Math.min(scene.startFrame + scene.durationFrames, composition.durationFrames)) fadeOut = scene.transitionOut.durationFrames / fps;
+    clips.push({ source, start, duration, trim: layer.trimStart / fps, rate: layer.playbackRate, loop: layer.loop, volume: layer.volume, envelope: volumeEnvelope({ layer, fps, start, duration, duck: layer.duck, others }), ...layer.type === "audio" ? { fadeIn, fadeOut } : fadeIn || fadeOut ? { fadeIn, fadeOut } : {} });
   }
   return clips.length ? { clips, durationSeconds: composition.durationFrames / fps } : void 0;
 }
@@ -2301,6 +2309,8 @@ async function reviewComposition(composition, options3 = {}) {
   for (let f = 0; f < durationFrames; f += every) frames.push(f);
   if (frames.at(-1) !== durationFrames - 1) frames.push(durationFrames - 1);
   const sheetCount = Math.max(1, Math.min(options3.sheetFrames ?? 20, durationFrames)), sheetFrames = Array.from({ length: sheetCount }, (_, i) => Math.min(durationFrames - 1, Math.round((i + 0.5) * durationFrames / sheetCount)));
+  const bands = safeZoneBands(width, height, options3.safeZone);
+  const safeBands = options3.showSafeZones ? bands.map((b) => ({ x0: b.x0 / width, y0: b.y0 / height, x1: b.x1 / width, y1: b.y1 / height })) : void 0;
   const renderer = await createRenderer(composition, { baseDir, concurrency: options3.concurrency ?? defaultConcurrency(), scale: Math.min(1, 1280 / Math.max(width, height)), allowCode: options3.allowCode });
   let reports = [], sheet;
   try {
@@ -2309,7 +2319,7 @@ async function reviewComposition(composition, options3 = {}) {
       options3.onProgress?.(++done, frames.length);
       return r2;
     })));
-    sheet = await renderer.contactSheet(sheetFrames, { columns: options3.columns ?? (width >= height ? 4 : 6) });
+    sheet = await renderer.contactSheet(sheetFrames, { columns: options3.columns ?? (width >= height ? 4 : 6), safeBands });
   } finally {
     await renderer.close();
   }
@@ -2343,7 +2353,6 @@ async function reviewComposition(composition, options3 = {}) {
     const other = report.texts.find((o) => o !== t && o.id !== t.id && visible(o) && overlap(t, o) > 0.15 * Math.min(area(t), area(o)) && (t.kind === "captions" || o.kind === "captions" || t.id < o.id));
     return other ? t.kind === "captions" || other.kind === "captions" ? `"${(t.kind === "captions" ? other : t).text}" sits under the captions: keep content out of the captions band` : `"${t.text}" overlaps "${other.text}"` : void 0;
   }, "error");
-  const bands = safeZoneBands(width, height, options3.safeZone);
   if (bands.length) persistent("safe-zone", hold, (t) => {
     if (!visible(t)) return;
     const band = bands.find((b) => overlap(t, b) > 0.25 * area(t));
@@ -2360,7 +2369,10 @@ async function reviewComposition(composition, options3 = {}) {
   }
   const near = steps2.filter((s) => s.length > 1);
   if (steps2.length > 8) issues.push({ severity: "warning", code: "type-scale", message: `${steps2.length} steps of font size (${steps2.map((s) => s.join("/")).join(", ")}): pick a scale of 5\u20138 sizes and reuse them` });
-  else if (near.length) issues.push({ severity: "warning", code: "type-scale", message: `Nearly equal font sizes (${near.map((s) => s.join("/")).join(", ")}): use one size for each step of the type scale` });
+  else if (near.length) {
+    const replace = Object.fromEntries(near.flatMap((group) => group.slice(1).map((s) => [String(s), group[0]])));
+    issues.push({ severity: "warning", code: "type-scale", message: `Nearly equal font sizes (${near.map((s) => s.join("/")).join(", ")}): use one size for each step of the type scale`, suggestion: { replace } });
+  }
   if (colours.length > 5) issues.push({ severity: "warning", code: "text-colours", message: `${colours.length} text colours (${colours.join(", ")}): use a heading colour, a body colour and one or two accents` });
   const change = reports.slice(1).map((r2, i) => {
     const a = reports[i].thumb.pixels, b = r2.thumb.pixels;
@@ -11183,7 +11195,33 @@ async function initProject(dir, options3 = {}) {
   loadComposition(composition);
   await writeFile14(compositionPath, JSON.stringify(composition, null, 2) + "\n");
   await writeFile14(join19(target, "composition.schema.json"), JSON.stringify(compositionJsonSchema, null, 2) + "\n");
-  if (options3.skill !== false) await cp(skillsRoot, join19(target, ".claude", "skills"), { recursive: true, force: true });
+  if (options3.skill !== false) {
+    await cp(skillsRoot, join19(target, ".claude", "skills"), { recursive: true, force: true });
+    await cp(skillsRoot, join19(target, ".agent", "skills"), { recursive: true, force: true });
+    const agentsMd = `# MotionRender (OVE) Agent Instructions
+
+MotionRender is a frame-deterministic motion graphics video engine.
+
+## Essential Commands
+- \`mr dev\`: Start local hot-reloading preview server
+- \`mr render\`: Headless video rendering
+- \`mr still --frame <n>\`: Export a single frame as image
+- \`mr review\`: Automated design, type scale, safe-zone, and audio check
+- \`mr review --show-safe-zones\`: Generate contact sheet with social UI overlays
+
+## Composition Grammar
+Full skill documentation and guidelines are located in:
+- \`.agent/skills/ove/SKILL.md\`
+- \`.claude/skills/ove/SKILL.md\`
+`;
+    await writeFile14(join19(target, "AGENTS.md"), agentsMd);
+    const cursorRules = `# MotionRender Rules
+- Motion graphics compositions are defined in \`composition.json\` adhering to \`composition.schema.json\`.
+- Use \`mr review\` to verify visual hierarchy, text safety, and audio loudness.
+- Detailed agent skills are located in \`.agent/skills/\`.
+`;
+    await writeFile14(join19(target, ".cursorrules"), cursorRules);
+  }
   return (await listFiles(target)).map((file2) => relative2(target, file2)).sort();
 }
 
@@ -11211,7 +11249,7 @@ var commandSpecs = {
   inspect: { values: variables, positionals: 1 },
   captions: { values: ["--output", ...variables], positionals: 1 },
   still: { values: ["--frame", "--output", ...variables], flags: ["--transparent", "--allow-code"], positionals: 1 },
-  review: { values: ["--output", "--every", "--sheet-frames", "--frames", ...variables], flags: ["--json", "--allow-code"], positionals: 1 },
+  review: { values: ["--output", "--every", "--sheet-frames", "--frames", ...variables], flags: ["--json", "--allow-code", "--show-safe-zones"], positionals: 1 },
   render: { values: [...renderValues, ...variables], flags: ["--transparent", "--no-motion-blur", "--allow-code"], positionals: 1 },
   ai: {
     values: ["--public-port", "--host", "--allow-host", "--instruction", "--prompt", "--provider", "--model", "--base-url", "--brief", "--kind", "--aspect", "--duration", "--fps", "--out", "--voice", "--language", "--size", "--composition", "--id", "--start", "--output", "--template", "--out-dir", "--fields", "--max-attempts", "--tail", "--asset", "--limit", "--port", "--crf", "--bitrate", "--audio-bitrate", "--scale", "--loudness", "--concurrency", "--preset", "--codec", "--format"],
@@ -11226,6 +11264,7 @@ var distance = (a, b) => {
   return d[a.length][b.length];
 };
 var wantsHelp = (argv2) => argv2.includes("--help") || argv2.includes("-h") || argv2[0] === "help";
+var wantsVersion = (argv2) => argv2.includes("--version") || argv2.includes("-v") || argv2[0] === "version";
 function checkArgs(argv2) {
   const args = argv2.flatMap((arg) => /^--[a-z-]+=/.test(arg) ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg]);
   const [command2] = args;
@@ -11386,6 +11425,21 @@ if (wantsHelp(process.argv.slice(2))) {
   console.log(usage2);
   process.exit(0);
 }
+if (wantsVersion(process.argv.slice(2))) {
+  let version = "0.2.7";
+  try {
+    const pkg = JSON.parse(await readFile26(new URL("../package.json", import.meta.url), "utf8"));
+    version = pkg.version || version;
+  } catch {
+    try {
+      const pkg = JSON.parse(await readFile26(new URL("../../package.json", import.meta.url), "utf8"));
+      version = pkg.version || version;
+    } catch {
+    }
+  }
+  console.log(`motionrender ${version}`);
+  process.exit(0);
+}
 var argv;
 try {
   argv = checkArgs(process.argv.slice(2));
@@ -11452,7 +11506,8 @@ var workerToken = () => {
 };
 async function renderVideo(composition, baseDir, output, settings) {
   const started = Date.now();
-  let lastReport = 0;
+  let lastReport = 0, lastPct = -1;
+  const isTty = Boolean(process.stdout.isTTY);
   const workers = option4("--workers");
   if (workers) {
     const chunkSize = option4("--chunk-size") === void 0 ? void 0 : Number(option4("--chunk-size"));
@@ -11482,9 +11537,19 @@ async function renderVideo(composition, baseDir, output, settings) {
     return;
   }
   const result = await renderMedia(composition, { ...settings, baseDir, output, allowCode: flag4("--allow-code"), onProgress: ({ rendered, total }) => {
-    if (rendered === total || Date.now() - lastReport > 1e3) {
-      lastReport = Date.now();
-      console.log(`Rendered ${rendered}/${total}`);
+    const pct = Math.floor(rendered / total * 100);
+    if (isTty) {
+      if (rendered === total || Date.now() - lastReport > 200) {
+        lastReport = Date.now();
+        process.stdout.write(`Rendered ${rendered}/${total} (${pct}%)\r`);
+        if (rendered === total) process.stdout.write("\n");
+      }
+    } else {
+      if (rendered === total || pct >= lastPct + 10 && Date.now() - lastReport > 1e3) {
+        lastReport = Date.now();
+        lastPct = pct;
+        console.log(`Rendered ${rendered}/${total} (${pct}%)`);
+      }
     }
   } });
   console.log(`Created ${result.output} (${result.format}, ${result.frames} frames, ${result.durationSeconds.toFixed(2)} seconds; rendered in ${((Date.now() - started) / 1e3).toFixed(1)}s with ${settings.concurrency} page${settings.concurrency === 1 ? "" : "s"})`);
@@ -11643,13 +11708,36 @@ Saving the file reloads the preview. Press Ctrl+C to stop.`);
         const frame = Number(option4("--frame") ?? 0);
         if (!Number.isInteger(frame) || frame < 0 || frame >= composition.durationFrames) throw new Error(`--frame must be an integer from 0 to ${composition.durationFrames - 1}`);
         const output = resolve26(option4("--output") ?? `still-${frame}.png`);
-        await renderStill(composition, { frame, output, baseDir, allowCode: flag4("--allow-code"), transparent: flag4("--transparent") ? true : void 0 });
+        let done = false;
+        if (!flag4("--transparent")) {
+          const targetFile = resolve26(file);
+          for (let p2 = 3e3; p2 <= 3020; p2++) {
+            try {
+              const c = new AbortController(), t = setTimeout(() => c.abort(), 120);
+              const res = await fetch(`http://127.0.0.1:${p2}/api/state`, { signal: c.signal });
+              clearTimeout(t);
+              if (res.ok) {
+                const s = await res.json();
+                if (s?.file && resolve26(s.file) === targetFile && !s.error) {
+                  const fr = await fetch(`http://127.0.0.1:${p2}/api/frame?f=${frame}`);
+                  if (fr.ok) {
+                    await writeFile24(output, Buffer.from(await fr.arrayBuffer()));
+                    done = true;
+                    break;
+                  }
+                }
+              }
+            } catch {
+            }
+          }
+        }
+        if (!done) await renderStill(composition, { frame, output, baseDir, allowCode: flag4("--allow-code"), transparent: flag4("--transparent") ? true : void 0 });
         console.log(`Created ${output}`);
       } else if (command === "review") {
         const output = resolve26(option4("--output") ?? "review.png"), every = option4("--every") === void 0 ? void 0 : Number(option4("--every")), sheetOption = option4("--sheet-frames") ?? option4("--frames"), sheetFrames = sheetOption === void 0 ? void 0 : Number(sheetOption);
         if (every !== void 0 && !(Number.isInteger(every) && every > 0)) throw new Error("--every must be a whole number of frames");
         if (sheetFrames !== void 0 && !(Number.isInteger(sheetFrames) && sheetFrames > 0 && sheetFrames <= 60)) throw new Error("--sheet-frames must be from 1 to 60");
-        const result = await reviewComposition(composition, { baseDir, allowCode: flag4("--allow-code"), every, sheetFrames, onProgress: (done, total) => {
+        const result = await reviewComposition(composition, { baseDir, allowCode: flag4("--allow-code"), every, sheetFrames, showSafeZones: flag4("--show-safe-zones"), onProgress: (done, total) => {
           if (!flag4("--json") && (done === total || done % 10 === 0)) process.stderr.write(`Checked ${done}/${total} frames\r`);
         } });
         await writeFile24(output, result.sheet);

package/dist/index.js

@@ -553,7 +553,7 @@ var splitSchema = z3.object({
 var spanSchema = z3.object({ text: z3.string(), color: paint.optional(), fontSize: z3.number().positive().optional(), fontWeight: fontWeight.optional(), fontStyle: fontStyle.optional(), fontFamily: z3.string().optional(), background: color.optional().describe("Highlight behind the span"), underline: z3.boolean().optional() });
 var cssFilter = z3.string().regex(/^\s*((blur|brightness|contrast|grayscale|hue-rotate|invert|opacity|saturate|sepia|drop-shadow)\([^()]*(\([^()]*\)[^()]*)*\)\s*)+$/, 'Use CSS filter functions such as "brightness(1.2) saturate(0.5)"');
 var blendModes = ["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"];
-var sfxNames = ["click", "tick", "pop", "whoosh", "thump", "ding", "riser"];
+var sfxNames = ["click", "tick", "pop", "whoosh", "thump", "ding", "riser", "shimmer", "sparkle", "impact", "ambient-pad"];
 var isBuiltinSound = (src) => src.startsWith("sfx:");
 var builtinSoundName = (src) => src.slice(4);
 var gradeLooks = ["warm", "cool", "cinematic", "teal-orange", "noir", "vivid", "faded"];
@@ -707,7 +707,7 @@ var layerSchema = z3.discriminatedUnion("type", [
   }),
   baseLayer.extend({ type: z3.literal("image"), src: z3.string().min(1), objectFit: z3.enum(["cover", "contain", "fill"]).default("cover"), radius: z3.number().nonnegative().default(0).describe("Rounded corners, clipping the picture") }),
   baseLayer.extend({ type: z3.literal("video"), src: z3.string().min(1), objectFit: z3.enum(["cover", "contain", "fill"]).default("cover"), radius: z3.number().nonnegative().default(0).describe("Rounded corners, clipping the picture"), trimStart: z3.number().int().nonnegative().default(0).describe("Frames of the source to skip, at the composition fps"), playbackRate: z3.number().positive().max(16).default(1), loop: z3.boolean().default(false).describe("Restart from the first source frame when the source ends; otherwise hold the last frame"), volume: z3.number().min(0).max(4).default(1).describe("Volume of the clip's own sound; 1 is unchanged; animatable"), muted: z3.boolean().default(false), duck: duckSchema.optional() }),
-  baseLayer.extend({ type: z3.literal("audio"), src: z3.string().min(1).refine((src) => !isBuiltinSound(src) || sfxNames.includes(builtinSoundName(src)), { message: `Built-in sounds are ${sfxNames.map((n) => `sfx:${n}`).join(", ")}` }).describe("An audio asset id, a file relative to the composition, or a built-in sound: sfx:click, sfx:tick, sfx:pop, sfx:whoosh, sfx:thump, sfx:ding, sfx:riser"), volume: z3.number().min(0).max(4).default(1).describe("1 is unchanged, 0.5 is half, 2 is double; animatable with keyframes"), duck: duckSchema.optional(), trimStart: z3.number().int().nonnegative().default(0).describe("Frames of the source to skip, at the composition fps"), playbackRate: z3.number().positive().max(16).default(1), loop: z3.boolean().default(false).describe("Restart from the start of the source when it ends; otherwise silence"), fadeInFrames: z3.number().int().nonnegative().default(0), fadeOutFrames: z3.number().int().nonnegative().default(0) }),
+  baseLayer.extend({ type: z3.literal("audio"), src: z3.string().min(1).refine((src) => !isBuiltinSound(src) || sfxNames.includes(builtinSoundName(src)), { message: `Built-in sounds are ${sfxNames.map((n) => `sfx:${n}`).join(", ")}` }).describe("An audio asset id, a file relative to the composition, or a built-in sound: sfx:click, sfx:tick, sfx:pop, sfx:whoosh, sfx:thump, sfx:ding, sfx:riser, sfx:shimmer, sfx:sparkle, sfx:impact, sfx:ambient-pad"), volume: z3.number().min(0).max(4).default(1).describe("1 is unchanged, 0.5 is half, 2 is double; animatable with keyframes"), duck: duckSchema.optional(), trimStart: z3.number().int().nonnegative().default(0).describe("Frames of the source to skip, at the composition fps"), playbackRate: z3.number().positive().max(16).default(1), loop: z3.boolean().default(false).describe("Restart from the start of the source when it ends; otherwise silence"), fadeInFrames: z3.number().int().nonnegative().default(0), fadeOutFrames: z3.number().int().nonnegative().default(0) }),
   // Captions: shows the line being spoken at each moment. With word timings the current word is highlighted; spoken words keep
   // `color`, words still to come use `upcomingColor`. x, y is the anchor of the first line (centre for textAlign center).
   baseLayer.extend({
@@ -1098,16 +1098,16 @@ function videoFrameIndex(layer, ownFrame, frameCount) {
 }
 function layerWindows(composition, include) {
   const out = [];
-  const walk = (layers, offset, limit) => {
+  const walk = (layers, offset, limit, scene) => {
     for (const layer of layers) {
       if (!layer.visible) continue;
       const start = offset + layer.startFrame, end = Math.min(limit, layer.endFrame === void 0 ? Infinity : offset + layer.endFrame);
       if (end <= start) continue;
-      if (layer.type === "group") walk(layer.children, start, end);
-      else if (include(layer)) out.push({ layer, startFrame: start, endFrame: end });
+      if (layer.type === "group") walk(layer.children, start, end, scene);
+      else if (include(layer)) out.push({ layer, startFrame: start, endFrame: end, scene });
     }
   };
-  for (const scene of composition.scenes) walk(scene.layers, scene.startFrame, Math.min(scene.startFrame + scene.durationFrames, composition.durationFrames));
+  for (const scene of composition.scenes) walk(scene.layers, scene.startFrame, Math.min(scene.startFrame + scene.durationFrames, composition.durationFrames), scene);
   return out;
 }
 var audioWindows = (composition) => layerWindows(composition, (layer) => layer.type === "audio" ? layer.volume > 0 : layer.type === "video" && !layer.muted && layer.volume > 0);
@@ -1410,7 +1410,11 @@ var sfxRecipes = {
   thump: tone("0.9*sin(2*PI*(110*t-80*t*t))*exp(-t*9)+0.3*sin(2*PI*55*t)*exp(-t*6)", 0.6),
   ding: tone("0.5*sin(2*PI*1318*t)*exp(-t*3)+0.25*sin(2*PI*3640*t)*exp(-t*5)+0.12*sin(2*PI*7110*t)*exp(-t*8)", 1.8),
   riser: tone("(t/1.6)*(t/1.6)*(0.6*sin(2*PI*(180*t+380*t*t))+0.25*sin(2*PI*(360*t+760*t*t)))", 1.6),
-  whoosh: ["-f", "lavfi", "-i", "anoisesrc=d=0.7:c=pink:a=0.9:r=48000:seed=11", "-af", "highpass=f=300,lowpass=f=3500,volume='sin(PI*t/0.7)*sin(PI*t/0.7)*sin(PI*t/0.7)':eval=frame,volume=3"]
+  whoosh: ["-f", "lavfi", "-i", "anoisesrc=d=0.7:c=pink:a=0.9:r=48000:seed=11", "-af", "highpass=f=300,lowpass=f=3500,volume='sin(PI*t/0.7)*sin(PI*t/0.7)*sin(PI*t/0.7)':eval=frame,volume=3"],
+  shimmer: tone("0.3*sin(2*PI*1318*t)*exp(-t*2.5)+0.25*sin(2*PI*1661*t)*exp(-t*3)+0.2*sin(2*PI*1975*t)*exp(-t*3.5)+0.15*sin(2*PI*2637*t)*exp(-t*4)", 1.5),
+  sparkle: tone("0.35*sin(2*PI*2093*t)*exp(-t*4)+0.25*sin(2*PI*2637*t)*exp(-t*5)+0.2*sin(2*PI*3136*t)*exp(-t*6)+0.15*sin(2*PI*4186*t)*exp(-t*7)", 1.2),
+  impact: tone("0.9*sin(2*PI*(160*t-120*t*t))*exp(-t*4)+0.6*sin(2*PI*(70*t-30*t*t))*exp(-t*2)+0.3*sin(2*PI*40*t)*exp(-t*1.5)", 1),
+  "ambient-pad": tone("0.25*(sin(2*PI*130.8*t)+0.2*sin(2*PI*131.2*t))+0.2*(sin(2*PI*196*t)+0.2*sin(2*PI*196.4*t))+0.2*(sin(2*PI*261.6*t)+0.15*sin(2*PI*329.6*t))*sin(PI*t/3.0)", 3)
 };
 var sfxArgs = (name2, output) => {
   const recipe = sfxRecipes[name2];
@@ -1847,8 +1851,8 @@ var runtime = `<!doctype html><canvas id="c"></canvas><script>${lottieSource}</s
 ${canvasRuntimeSource}
 const rt=createCanvasRuntime(document.querySelector('#c'),document.querySelector('#measure'));
 window.OVE={load:rt.load,draw:async(p)=>{await rt.draw(p);return rt.canvas.toDataURL('image/png').slice('data:image/png;base64,'.length)},inspect:async(p)=>{await rt.draw({...p,report:true});return rt.report()}};</script>`;
-var sheetPage = `<!doctype html><canvas id="s"></canvas><script>window.sheet=async({images,labels,columns,cell})=>{const c=document.querySelector('#s'),rows=Math.ceil(images.length/columns),gap=8,label=26,ctx=c.getContext('2d');c.width=columns*cell.w+(columns+1)*gap;c.height=rows*(cell.h+label)+(rows+1)*gap;ctx.fillStyle='#0b0d14';ctx.fillRect(0,0,c.width,c.height);ctx.font='600 15px system-ui,sans-serif';ctx.textBaseline='middle';
-for(let i=0;i<images.length;i++){const img=new Image();img.src=images[i];await img.decode();const x=gap+(i%columns)*(cell.w+gap),y=gap+Math.floor(i/columns)*(cell.h+label+gap);ctx.drawImage(img,x,y,cell.w,cell.h);ctx.fillStyle='#c9cfdd';ctx.fillText(labels[i],x+2,y+cell.h+label/2)}return c.toDataURL('image/png').slice(22)}</script>`;
+var sheetPage = `<!doctype html><canvas id="s"></canvas><script>window.sheet=async({images,labels,columns,cell,safeBands})=>{const c=document.querySelector('#s'),rows=Math.ceil(images.length/columns),gap=8,label=26,ctx=c.getContext('2d');c.width=columns*cell.w+(columns+1)*gap;c.height=rows*(cell.h+label)+(rows+1)*gap;ctx.fillStyle='#0b0d14';ctx.fillRect(0,0,c.width,c.height);ctx.font='600 15px system-ui,sans-serif';ctx.textBaseline='middle';
+for(let i=0;i<images.length;i++){const img=new Image();img.src=images[i];await img.decode();const x=gap+(i%columns)*(cell.w+gap),y=gap+Math.floor(i/columns)*(cell.h+label+gap);ctx.drawImage(img,x,y,cell.w,cell.h);if(safeBands){for(const b of safeBands){const bx=x+b.x0*cell.w,by=y+b.y0*cell.h,bw=(b.x1-b.x0)*cell.w,bh=(b.y1-b.y0)*cell.h;ctx.fillStyle='rgba(239,68,68,0.18)';ctx.fillRect(bx,by,bw,bh);ctx.lineWidth=1.5;ctx.strokeStyle='rgba(239,68,68,0.55)';ctx.strokeRect(bx,by,bw,bh);}}ctx.fillStyle='#c9cfdd';ctx.fillText(labels[i],x+2,y+cell.h+label/2)}return c.toDataURL('image/png').slice(22)}</script>`;
 var allLayers = (composition) => composition.scenes.flatMap((scene) => scene.layers);
 var browserArgs = ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", ...(process.env.OVE_CHROMIUM_ARGS ?? "").split(/\s+/).filter(Boolean)];
 var browserInstallHint = `Install one with "ove browser install" (Playwright's Chromium, about 150 MB), install Google Chrome, or set OVE_CHROMIUM_EXECUTABLE to a Chromium-based browser.`;
@@ -1999,7 +2003,7 @@ async function createRenderer(composition, options = {}) {
       try {
         const page = await context.newPage();
         await page.setContent(sheetPage);
-        return Buffer.from(await page.evaluate((a) => window.sheet(a), { images, labels, columns, cell }), "base64");
+        return Buffer.from(await page.evaluate((a) => window.sheet(a), { images, labels, columns, cell, safeBands: options2.safeBands }), "base64");
       } finally {
         await context.close();
       }
@@ -2098,7 +2102,7 @@ async function planAudio(composition, baseDir, probe2 = hasAudioStream) {
     clips.push({ source: soundtrack, start: 0, duration, loop: true, volume: composition.export.audioVolume, envelope: volumeEnvelope({ layer: { volume: composition.export.audioVolume }, fps, start: 0, duration, duck: composition.export.duck, others }) });
   }
   const hasAudio = /* @__PURE__ */ new Map();
-  for (const { layer, startFrame, endFrame } of windows) {
+  for (const { layer, startFrame, endFrame, scene } of windows) {
     const source = await sourceOf(composition, layer.src, baseDir);
     await ensureExists(source);
     if (layer.type === "video") {
@@ -2106,7 +2110,11 @@ async function planAudio(composition, baseDir, probe2 = hasAudioStream) {
       if (!await hasAudio.get(source)) continue;
     }
     const start = startFrame / fps, duration = (endFrame - startFrame) / fps;
-    clips.push({ source, start, duration, trim: layer.trimStart / fps, rate: layer.playbackRate, loop: layer.loop, volume: layer.volume, envelope: volumeEnvelope({ layer, fps, start, duration, duck: layer.duck, others }), ...layer.type === "audio" ? { fadeIn: layer.fadeInFrames / fps, fadeOut: layer.fadeOutFrames / fps } : {} });
+    let fadeIn = layer.type === "audio" ? (layer.fadeInFrames ?? 0) / fps : 0;
+    let fadeOut = layer.type === "audio" ? (layer.fadeOutFrames ?? 0) / fps : 0;
+    if (scene?.transitionIn?.type === "fade" && fadeIn === 0 && startFrame === scene.startFrame) fadeIn = scene.transitionIn.durationFrames / fps;
+    if (scene?.transitionOut?.type === "fade" && fadeOut === 0 && endFrame === Math.min(scene.startFrame + scene.durationFrames, composition.durationFrames)) fadeOut = scene.transitionOut.durationFrames / fps;
+    clips.push({ source, start, duration, trim: layer.trimStart / fps, rate: layer.playbackRate, loop: layer.loop, volume: layer.volume, envelope: volumeEnvelope({ layer, fps, start, duration, duck: layer.duck, others }), ...layer.type === "audio" ? { fadeIn, fadeOut } : fadeIn || fadeOut ? { fadeIn, fadeOut } : {} });
   }
   return clips.length ? { clips, durationSeconds: composition.durationFrames / fps } : void 0;
 }
@@ -2155,6 +2163,8 @@ async function reviewComposition(composition, options = {}) {
   for (let f = 0; f < durationFrames; f += every) frames.push(f);
   if (frames.at(-1) !== durationFrames - 1) frames.push(durationFrames - 1);
   const sheetCount = Math.max(1, Math.min(options.sheetFrames ?? 20, durationFrames)), sheetFrames = Array.from({ length: sheetCount }, (_, i) => Math.min(durationFrames - 1, Math.round((i + 0.5) * durationFrames / sheetCount)));
+  const bands = safeZoneBands(width, height, options.safeZone);
+  const safeBands = options.showSafeZones ? bands.map((b) => ({ x0: b.x0 / width, y0: b.y0 / height, x1: b.x1 / width, y1: b.y1 / height })) : void 0;
   const renderer = await createRenderer(composition, { baseDir, concurrency: options.concurrency ?? defaultConcurrency(), scale: Math.min(1, 1280 / Math.max(width, height)), allowCode: options.allowCode });
   let reports = [], sheet;
   try {
@@ -2163,7 +2173,7 @@ async function reviewComposition(composition, options = {}) {
       options.onProgress?.(++done, frames.length);
       return r;
     })));
-    sheet = await renderer.contactSheet(sheetFrames, { columns: options.columns ?? (width >= height ? 4 : 6) });
+    sheet = await renderer.contactSheet(sheetFrames, { columns: options.columns ?? (width >= height ? 4 : 6), safeBands });
   } finally {
     await renderer.close();
   }
@@ -2197,7 +2207,6 @@ async function reviewComposition(composition, options = {}) {
     const other = report.texts.find((o) => o !== t && o.id !== t.id && visible(o) && overlap(t, o) > 0.15 * Math.min(area(t), area(o)) && (t.kind === "captions" || o.kind === "captions" || t.id < o.id));
     return other ? t.kind === "captions" || other.kind === "captions" ? `"${(t.kind === "captions" ? other : t).text}" sits under the captions: keep content out of the captions band` : `"${t.text}" overlaps "${other.text}"` : void 0;
   }, "error");
-  const bands = safeZoneBands(width, height, options.safeZone);
   if (bands.length) persistent("safe-zone", hold, (t) => {
     if (!visible(t)) return;
     const band = bands.find((b) => overlap(t, b) > 0.25 * area(t));
@@ -2214,7 +2223,10 @@ async function reviewComposition(composition, options = {}) {
   }
   const near = steps.filter((s) => s.length > 1);
   if (steps.length > 8) issues.push({ severity: "warning", code: "type-scale", message: `${steps.length} steps of font size (${steps.map((s) => s.join("/")).join(", ")}): pick a scale of 5\u20138 sizes and reuse them` });
-  else if (near.length) issues.push({ severity: "warning", code: "type-scale", message: `Nearly equal font sizes (${near.map((s) => s.join("/")).join(", ")}): use one size for each step of the type scale` });
+  else if (near.length) {
+    const replace = Object.fromEntries(near.flatMap((group) => group.slice(1).map((s) => [String(s), group[0]])));
+    issues.push({ severity: "warning", code: "type-scale", message: `Nearly equal font sizes (${near.map((s) => s.join("/")).join(", ")}): use one size for each step of the type scale`, suggestion: { replace } });
+  }
   if (colours.length > 5) issues.push({ severity: "warning", code: "text-colours", message: `${colours.length} text colours (${colours.join(", ")}): use a heading colour, a body colour and one or two accents` });
   const change = reports.slice(1).map((r, i) => {
     const a = reports[i].thumb.pixels, b = r.thumb.pixels;