fix(video-workflows): pad the frame's own duration to match the transition tail (#1889)

* fix(video-workflows): pad the frame's own duration to match the transition tail

transitions.mjs extends the index.html WRAPPER's data-duration to cover an
outgoing transition's tail, but the frame's own internal composition file
kept its shorter, content-only data-duration (authored per frame-worker.md's
"duration is fixed upstream" instruction). The render engine clip-gates a
sub-composition's visible content at its own declared duration, so content
vanished abruptly at content-end instead of fading through the wrapper's
extended fade-out tween.

A user root-caused and verified this themselves: padding the frame's own
duration to match the wrapper fixed it, project-wide, across every
non-final frame. transitions.mjs already computes the correct padded
duration for the wrapper - it now writes the same value into the matching
frame's own file at inject time.

Extracted to a shared lib/pad-frame-duration.mjs (mirroring the existing
lib/transition-registry.mjs convention) since transitions.mjs's own
top-level CLI dispatch runs on import, making it untestable directly.
Duplicated identically across pr-to-video, faceless-explainer, and
product-launch-video, whose transitions.mjs copies are otherwise
byte-identical (confirmed via diff) - one root cause, one fix, applied
everywhere it lives.

* fix(skills): avoid duration helper file race

skills-manifest.json

@@ -6,8 +6,8 @@
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "844c54a06fd16d3c",
+      "hash": "6dac80491c3db278",
-      "files": 17
+      "files": 18
     },
     "figma": {
       "hash": "0adc2a1e01767db7",
@@ -62,12 +62,12 @@
       "files": 132
     },
     "pr-to-video": {
-      "hash": "132b44ddda774fef",
+      "hash": "d40ba25aa5af30e1",
-      "files": 21
+      "files": 22
     },
     "product-launch-video": {
-      "hash": "32cab842cc7a6b76",
+      "hash": "b1895d518ec04da5",
-      "files": 18
+      "files": 20
     },
     "remotion-to-hyperframes": {
       "hash": "9d959b31fa0fc9d0",

skills/faceless-explainer/scripts/lib/pad-frame-duration.mjs

@@ -0,0 +1,36 @@
+// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
+// sync with the padded index.html wrapper duration transitions.mjs computes.
+//
+// The frame's OWN internal file declares its #root/clip data-duration to the
+// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
+// upstream"). When an outgoing transition pads the index.html WRAPPER's
+// data-duration to cover the transition tail, the frame's own internal
+// duration is left short — the render engine clip-gates the sub-composition's
+// visible content at that shorter value, so content vanishes abruptly at
+// content-end instead of fading gracefully through the wrapper's extended
+// fade-out tween. Pad the frame's own file to match so both durations agree.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
+  const framePath = resolve(hyperframesDir, frameSrc);
+  let html;
+  try {
+    html = readFileSync(framePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return;
+    throw err;
+  }
+  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
+  let m;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
+    if (!/data-duration="[\d.]+"/.test(tag)) continue;
+    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
+    if (newTag === tag) return;
+    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
+    return;
+  }
+}

skills/faceless-explainer/scripts/transitions.mjs

@@ -28,6 +28,7 @@ import { join, resolve } from "node:path";
 import { parseStoryboard } from "./lib/storyboard.mjs";
 import { parseFormat } from "./lib/dimensions.mjs";
 import { loadTransitionRegistry, transitionsByName } from "./lib/transition-registry.mjs";
+import { padFrameInternalDuration } from "./lib/pad-frame-duration.mjs";
 
 const flag = (argv, name, def) => {
   const i = argv.indexOf(`--${name}`);
@@ -183,6 +184,12 @@ function runInject(argv) {
     const dur = resolveDur(spec, rec, reg);
     const T = r3(incoming.start); // cut = incoming start (frames tile)
     outgoing.duration = r3(outgoing.duration + dur); // extend outgoing only
+    padFrameInternalDuration(
+      hyperframesDir,
+      order[i - 1].frame.src,
+      outgoing.id,
+      outgoing.duration,
+    );
     gsapLines.push(
       ...buildGsap(rec, outgoing.id, incoming.id, dur, T, spec.direction, CW, CH, die),
     );

skills/pr-to-video/scripts/lib/pad-frame-duration.mjs

@@ -0,0 +1,36 @@
+// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
+// sync with the padded index.html wrapper duration transitions.mjs computes.
+//
+// The frame's OWN internal file declares its #root/clip data-duration to the
+// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
+// upstream"). When an outgoing transition pads the index.html WRAPPER's
+// data-duration to cover the transition tail, the frame's own internal
+// duration is left short — the render engine clip-gates the sub-composition's
+// visible content at that shorter value, so content vanishes abruptly at
+// content-end instead of fading gracefully through the wrapper's extended
+// fade-out tween. Pad the frame's own file to match so both durations agree.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
+  const framePath = resolve(hyperframesDir, frameSrc);
+  let html;
+  try {
+    html = readFileSync(framePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return;
+    throw err;
+  }
+  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
+  let m;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
+    if (!/data-duration="[\d.]+"/.test(tag)) continue;
+    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
+    if (newTag === tag) return;
+    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
+    return;
+  }
+}

skills/pr-to-video/scripts/transitions.mjs

@@ -28,6 +28,7 @@ import { join, resolve } from "node:path";
 import { parseStoryboard } from "./lib/storyboard.mjs";
 import { parseFormat } from "./lib/dimensions.mjs";
 import { loadTransitionRegistry, transitionsByName } from "./lib/transition-registry.mjs";
+import { padFrameInternalDuration } from "./lib/pad-frame-duration.mjs";
 
 const flag = (argv, name, def) => {
   const i = argv.indexOf(`--${name}`);
@@ -183,6 +184,12 @@ function runInject(argv) {
     const dur = resolveDur(spec, rec, reg);
     const T = r3(incoming.start); // cut = incoming start (frames tile)
     outgoing.duration = r3(outgoing.duration + dur); // extend outgoing only
+    padFrameInternalDuration(
+      hyperframesDir,
+      order[i - 1].frame.src,
+      outgoing.id,
+      outgoing.duration,
+    );
     gsapLines.push(
       ...buildGsap(rec, outgoing.id, incoming.id, dur, T, spec.direction, CW, CH, die),
     );

skills/product-launch-video/scripts/lib/pad-frame-duration.mjs

@@ -0,0 +1,36 @@
+// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
+// sync with the padded index.html wrapper duration transitions.mjs computes.
+//
+// The frame's OWN internal file declares its #root/clip data-duration to the
+// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
+// upstream"). When an outgoing transition pads the index.html WRAPPER's
+// data-duration to cover the transition tail, the frame's own internal
+// duration is left short — the render engine clip-gates the sub-composition's
+// visible content at that shorter value, so content vanishes abruptly at
+// content-end instead of fading gracefully through the wrapper's extended
+// fade-out tween. Pad the frame's own file to match so both durations agree.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
+  const framePath = resolve(hyperframesDir, frameSrc);
+  let html;
+  try {
+    html = readFileSync(framePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return;
+    throw err;
+  }
+  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
+  let m;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
+    if (!/data-duration="[\d.]+"/.test(tag)) continue;
+    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
+    if (newTag === tag) return;
+    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
+    return;
+  }
+}

skills/product-launch-video/scripts/lib/pad-frame-duration.test.mjs

@@ -0,0 +1,76 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { padFrameInternalDuration } from "./pad-frame-duration.mjs";
+
+// Regression: an outgoing transition pads the index.html WRAPPER's
+// data-duration to cover the transition tail, but the frame's own internal
+// file kept its shorter content-only duration, so the render engine
+// clip-gated the sub-composition's visible content at the shorter value —
+// content vanished abruptly instead of fading through the wrapper's
+// extended fade-out tween. A user diagnosed and verified this fix
+// themselves: pad the frame's own #root/clip data-duration to match.
+test("padFrameInternalDuration pads the matching frame's own data-duration", () => {
+  const dir = mkdtempSync(join(tmpdir(), "transitions-pad-"));
+  const framesDir = join(dir, "compositions", "frames");
+  mkdirSync(framesDir, { recursive: true });
+  const frameSrc = "compositions/frames/scene-1.html";
+  const framePath = join(dir, frameSrc);
+  writeFileSync(
+    framePath,
+    `<template>
+  <div
+    id="root"
+    data-composition-id="scene-1"
+    data-width="1920"
+    data-height="1080"
+    data-duration="4.2"
+  ></div>
+</template>`,
+  );
+
+  try {
+    padFrameInternalDuration(dir, frameSrc, "scene-1", 4.7);
+    const updated = readFileSync(framePath, "utf8");
+    assert.match(updated, /data-duration="4\.7"/);
+    assert.doesNotMatch(updated, /data-duration="4\.2"/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("padFrameInternalDuration only touches the tag matching the given frame id", () => {
+  const dir = mkdtempSync(join(tmpdir(), "transitions-pad-scope-"));
+  const framesDir = join(dir, "compositions", "frames");
+  mkdirSync(framesDir, { recursive: true });
+  const frameSrc = "compositions/frames/scene-2.html";
+  const framePath = join(dir, frameSrc);
+  const original = `<template>
+  <div id="root" data-composition-id="scene-2" data-duration="3.0">
+    <div data-composition-id="unrelated-child" data-duration="1.0"></div>
+  </div>
+</template>`;
+  writeFileSync(framePath, original);
+
+  try {
+    padFrameInternalDuration(dir, frameSrc, "scene-2", 3.5);
+    const updated = readFileSync(framePath, "utf8");
+    assert.match(updated, /data-composition-id="scene-2" data-duration="3\.5"/);
+    assert.match(updated, /data-composition-id="unrelated-child" data-duration="1\.0"/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("padFrameInternalDuration is a no-op when the frame file does not exist", () => {
+  const dir = mkdtempSync(join(tmpdir(), "transitions-pad-missing-"));
+  try {
+    assert.doesNotThrow(() =>
+      padFrameInternalDuration(dir, "compositions/frames/missing.html", "missing", 5),
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

skills/product-launch-video/scripts/transitions.mjs

@@ -28,6 +28,7 @@ import { join, resolve } from "node:path";
 import { parseStoryboard } from "./lib/storyboard.mjs";
 import { parseFormat } from "./lib/dimensions.mjs";
 import { loadTransitionRegistry, transitionsByName } from "./lib/transition-registry.mjs";
+import { padFrameInternalDuration } from "./lib/pad-frame-duration.mjs";
 
 const flag = (argv, name, def) => {
   const i = argv.indexOf(`--${name}`);
@@ -183,6 +184,12 @@ function runInject(argv) {
     const dur = resolveDur(spec, rec, reg);
     const T = r3(incoming.start); // cut = incoming start (frames tile)
     outgoing.duration = r3(outgoing.duration + dur); // extend outgoing only
+    padFrameInternalDuration(
+      hyperframesDir,
+      order[i - 1].frame.src,
+      outgoing.id,
+      outgoing.duration,
+    );
     gsapLines.push(
       ...buildGsap(rec, outgoing.id, incoming.id, dur, T, spec.direction, CW, CH, die),
     );