frameyard 0.9.0 → 0.10.0

package/dist/server/timeline-preview-html.js

@@ -1,3 +1,4 @@
+import { PREVIEW_CSS } from "./preview-style.js";
 function escapeHtml(value) {
     return value.replace(/[&<>"']/g, (character) => {
         switch (character) {
@@ -20,6 +21,121 @@ const IMPORT_MAP = JSON.stringify({
         "frameyard/runtime": "/__frameyard/framework/runtime/index.js",
     },
 });
+const PAGE_CSS = `
+  #app {
+    display: grid;
+    grid-template-rows: 54px minmax(0, 1fr) 216px 58px;
+    height: 100vh;
+  }
+  #viewport { min-height: 0; }
+  #stage-wrap { overflow: hidden; }
+  #stage {
+    position: relative;
+    width: 100%; height: 100%;
+    transform-origin: top left;
+    overflow: hidden;
+    background: #000;
+    isolation: isolate;
+  }
+  .timeline-layer { position: absolute; left: 50%; top: 50%; transform-origin: center; }
+  .timeline-layer iframe, .timeline-layer video, .timeline-layer img { display: block; border: 0; }
+
+  #timeline {
+    position: relative;
+    min-height: 0;
+    border-top: 1px solid var(--line);
+    background: var(--panel);
+    overflow: auto;
+    padding: 12px 18px 16px;
+  }
+  .ruler {
+    display: grid;
+    grid-template-columns: 96px minmax(0, 1fr);
+    gap: 10px;
+    height: 20px;
+  }
+  .ruler-scale { position: relative; border-bottom: 1px solid var(--line); }
+  .ruler-scale::before {
+    content: ""; position: absolute; left: 0; right: 0; bottom: 0; height: 7px;
+    background-image: linear-gradient(90deg, var(--line-strong) 0 1px, transparent 1px);
+    background-size: 10% 100%;
+    opacity: 0.55;
+    pointer-events: none;
+  }
+  .ruler-tick {
+    position: absolute; top: -1px; transform: translateX(-50%);
+    font-family: var(--mono); font-size: 9px; color: var(--muted);
+    letter-spacing: 0.06em; pointer-events: none;
+  }
+  .ruler-tick:first-child { transform: none; }
+  .ruler-tick:last-child { transform: translateX(-100%); }
+  #timeline-inner { position: relative; }
+  #tracks { position: relative; display: flex; flex-direction: column; }
+  .track { display: grid; grid-template-columns: 96px minmax(0, 1fr); gap: 10px; min-height: 30px; }
+  .track-label {
+    display: flex; align-items: center; justify-content: flex-end;
+    font-size: 9px; white-space: nowrap;
+  }
+  .lane {
+    position: relative; border: 1px solid var(--line);
+    background: var(--ink); overflow: hidden;
+  }
+  .clip {
+    position: absolute; top: 3px; bottom: 3px; border-radius: 1px;
+    background: linear-gradient(180deg, rgba(74, 96, 118, 0.5), rgba(38, 52, 66, 0.55));
+    border: 1px solid rgba(140, 170, 195, 0.38); color: #dce8f5;
+    font: 10px/1 var(--mono); padding: 6px 8px; overflow: visible;
+    white-space: nowrap;
+  }
+  .clip-label { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .clip.composition {
+    background: linear-gradient(180deg, rgba(184, 243, 107, 0.20), rgba(184, 243, 107, 0.07));
+    border-color: rgba(184, 243, 107, 0.45); color: var(--paper);
+  }
+  .clip.audio {
+    background: linear-gradient(180deg, rgba(232, 199, 106, 0.20), rgba(232, 199, 106, 0.06));
+    border-color: rgba(232, 199, 106, 0.42); color: #f4e7c4;
+  }
+  .clip.nested {
+    background: linear-gradient(180deg, rgba(168, 130, 200, 0.22), rgba(168, 130, 200, 0.07));
+    border-color: rgba(168, 130, 200, 0.45); color: #e8d9f5;
+  }
+  .keyframe-marker {
+    position: absolute; top: 50%; width: 7px; height: 7px;
+    background: var(--accent); border: 1px solid var(--ink); border-radius: 1px;
+    transform: translate(-50%, -50%) rotate(45deg); cursor: pointer; z-index: 2;
+  }
+  .keyframe-marker:hover { background: #ffffff; }
+  .transition {
+    position: absolute; top: 6px; bottom: 6px; border-radius: 1px; z-index: 1;
+    background: repeating-linear-gradient(
+      45deg,
+      rgba(184, 243, 107, 0.22) 0 4px,
+      rgba(184, 243, 107, 0.06) 4px 8px
+    );
+    border: 1px solid rgba(184, 243, 107, 0.5); pointer-events: none;
+  }
+  .playhead {
+    position: absolute; top: 0; bottom: 0; width: 1px;
+    left: calc(106px + (100% - 106px) * var(--playhead-factor, 0));
+    background: var(--accent);
+    box-shadow: 0 0 10px rgba(184, 243, 107, 0.7);
+    pointer-events: none;
+    z-index: 3;
+  }
+  .playhead::before {
+    content: ""; position: absolute; top: 0; left: -3px;
+    width: 7px; height: 7px; background: var(--accent);
+    transform: rotate(45deg);
+  }
+  #timeline #error, #timeline #diagnostics { margin-top: 10px; }
+
+  @media (max-width: 760px) {
+    #app { grid-template-rows: 54px minmax(0, 1fr) 180px auto; }
+    footer { flex-wrap: wrap; padding: 9px 14px; }
+    .meta { display: none; }
+  }
+`;
 export function renderTimelinePreviewHtml(timelineId, options = {}) {
     const id = escapeHtml(timelineId);
     if (options.embed) {
@@ -50,179 +166,39 @@ export function renderTimelinePreviewHtml(timelineId, options = {}) {
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Frameyard timeline ${id}</title>
     <style>
-      :root {
-        color-scheme: dark;
-        --bg: #0b0d10;
-        --panel: #11151a;
-        --panel-2: #171c23;
-        --line: #252c35;
-        --text: #e8edf3;
-        --muted: #8a97a6;
-        --accent: #b8f36b;
-        --accent-ink: #101408;
-        --danger: #ff8a8a;
-        --mono: "SFMono-Regular", ui-monospace, "Cascadia Code", "Liberation Mono", monospace;
-        --sans: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
-      }
-      * { box-sizing: border-box; }
-      html, body { height: 100%; }
-      body {
-        margin: 0;
-        background: var(--bg);
-        color: var(--text);
-        font-family: var(--sans);
-        font-size: 13px;
-        overflow: hidden;
-      }
-      #app {
-        display: grid;
-        grid-template-rows: 54px minmax(0, 1fr) 210px 58px;
-        height: 100vh;
-      }
-      header {
-        display: flex;
-        align-items: center;
-        gap: 18px;
-        padding: 0 18px;
-        border-bottom: 1px solid var(--line);
-        background: linear-gradient(180deg, #11151a, #0d1014);
-      }
-      .brand { display: flex; align-items: center; gap: 9px; font-weight: 650; }
-      .mark {
-        width: 17px; height: 17px; border-radius: 4px;
-        background: linear-gradient(135deg, var(--accent), #5fd6ff);
-        box-shadow: 0 0 18px rgba(184, 243, 107, 0.3);
-      }
-      .tag { color: var(--muted); font-family: var(--mono); font-size: 10px; text-transform: uppercase; letter-spacing: 0.1em; }
-      a { color: var(--accent); text-decoration: none; }
-      a:hover { text-decoration: underline; }
-      .meta { margin-left: auto; color: var(--muted); font-family: var(--mono); font-size: 11px; }
-      #viewport {
-        min-height: 0;
-        display: grid;
-        place-items: center;
-        padding: 20px;
-        overflow: hidden;
-        background:
-          radial-gradient(circle at 50% 20%, #141b24 0, transparent 55%),
-          #080a0d;
-      }
-      #stage-wrap {
-        position: relative;
-        overflow: hidden;
-        box-shadow: 0 30px 90px rgba(0, 0, 0, 0.55);
-        background: #000;
-      }
-      #stage {
-        position: relative;
-        transform-origin: top left;
-        overflow: hidden;
-        background: #000;
-        isolation: isolate;
-      }
-      .timeline-layer { position: absolute; left: 50%; top: 50%; transform-origin: center; }
-      .timeline-layer iframe, .timeline-layer video, .timeline-layer img { display: block; border: 0; }
-      #timeline {
-        position: relative;
-        min-height: 0;
-        border-top: 1px solid var(--line);
-        background: var(--panel);
-        overflow: auto;
-        padding: 10px 16px 16px;
-      }
-      #tracks { position: relative; display: flex; flex-direction: column; gap: 6px; }
-      .track { display: grid; grid-template-columns: 72px minmax(0, 1fr); gap: 8px; min-height: 30px; }
-      .track-label {
-        display: flex; align-items: center; justify-content: flex-end;
-        color: var(--muted); font-family: var(--mono); font-size: 10px;
-        text-transform: uppercase; letter-spacing: 0.06em;
-      }
-      .lane {
-        position: relative; border: 1px solid var(--line); border-radius: 6px;
-        background: #0d1116; overflow: hidden;
-      }
-      .clip {
-        position: absolute; top: 3px; bottom: 3px; border-radius: 4px;
-        background: linear-gradient(180deg, #2a4058, #1d2c3d);
-        border: 1px solid #3b5672; color: #dce8f5;
-        font: 10px/1 var(--mono); padding: 6px 7px; overflow: visible;
-        white-space: nowrap;
-      }
-      .clip-label { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-      .keyframe-marker {
-        position: absolute; top: 50%; width: 6px; height: 6px;
-        background: var(--accent); border: 1px solid #0d1116; border-radius: 1px;
-        transform: translate(-50%, -50%) rotate(45deg); cursor: pointer; z-index: 2;
-      }
-      .keyframe-marker:hover { background: #ffffff; }
-      .clip.composition { background: linear-gradient(180deg, #314a33, #203120); border-color: #4d704d; }
-      .clip.audio { background: linear-gradient(180deg, #4a3b22, #302516); border-color: #6e5631; }
-      .clip.nested { background: linear-gradient(180deg, #443152, #2c2036); border-color: #63477a; }
-      .transition {
-        position: absolute; top: 8px; bottom: 8px; border-radius: 4px; z-index: 1;
-        background: repeating-linear-gradient(
-          45deg,
-          rgba(184, 243, 107, 0.24) 0 4px,
-          rgba(184, 243, 107, 0.08) 4px 8px
-        );
-        border: 1px solid rgba(184, 243, 107, 0.55); pointer-events: none;
-      }
-      #playhead {
-        position: absolute; top: 0; bottom: 0; width: 1px; background: var(--accent);
-        box-shadow: 0 0 12px rgba(184, 243, 107, 0.7); pointer-events: none;
-      }
-      #error, #diagnostics {
-        margin-top: 10px; border: 1px solid #4b3030; border-radius: 6px;
-        padding: 9px 11px; background: #1b1111; color: var(--danger);
-        font-family: var(--mono); font-size: 11px; white-space: pre-wrap;
-      }
-      #diagnostics { border-color: var(--line); background: var(--panel-2); color: var(--muted); }
-      footer {
-        display: flex; align-items: center; gap: 12px; padding: 0 18px;
-        border-top: 1px solid var(--line); background: var(--panel);
-      }
-      button {
-        border: 1px solid var(--line); background: var(--panel-2); color: var(--text);
-        border-radius: 6px; padding: 8px 12px; cursor: pointer;
-      }
-      button:hover { border-color: #3a4654; }
-      .step {
-        width: 32px; height: 32px; padding: 0; border-radius: 6px;
-        color: var(--muted); font-size: 18px; line-height: 1;
-      }
-      .jump {
-        height: 32px; padding: 0 8px; border-radius: 6px;
-        color: var(--muted); font: 10px var(--mono);
-      }
-      .step:hover:not(:disabled), .jump:hover:not(:disabled) { color: var(--text); }
-      .play {
-        width: 38px; height: 38px; border-radius: 50%; border: 0;
-        background: var(--accent); color: var(--accent-ink);
-        font-size: 15px; font-weight: 700;
-      }
-      .scrub { flex: 1; accent-color: var(--accent); }
-      .readout { min-width: 150px; text-align: right; color: var(--muted); font-family: var(--mono); font-size: 11px; }
-      .readout b { color: var(--text); font-weight: 600; }
-      .audio { display: flex; align-items: center; gap: 8px; color: var(--muted); font-family: var(--mono); font-size: 11px; }
-      .audio input[type="range"] { width: 80px; accent-color: var(--accent); }
-      .hint { color: var(--muted); font-family: var(--mono); font-size: 10px; }
+${PREVIEW_CSS}
+${PAGE_CSS}
     </style>
     <script type="importmap" data-fy-host>${IMPORT_MAP}</script>
   </head>
   <body data-timeline-id="${id}" data-embed="0">
     <div id="app">
       <header>
-        <div class="brand"><span class="mark"></span>frameyard <span class="tag">timeline</span></div>
-        <a href="/__frameyard/">← compositions</a>
-        <span id="title" class="hint"></span>
+        <div class="brand">
+          <span class="mark" aria-hidden="true"><i></i><i></i><i></i><i></i></span>
+          <span class="wordmark">frameyard</span>
+          <span class="slash">/</span>
+          <span class="tag">timeline</span>
+        </div>
+        <span class="topbar-rule"></span>
+        <a href="/__frameyard/">&larr; compositions</a>
+        <span id="title" class="title"></span>
         <div id="meta" class="meta"></div>
       </header>
       <main id="viewport">
-        <div id="stage-wrap"><div id="stage"></div></div>
+        <div id="stage-wrap">
+          <div id="stage"></div>
+        </div>
       </main>
       <section id="timeline">
-        <div id="tracks"></div>
-        <div id="playhead"></div>
+        <div id="timeline-inner">
+          <div class="ruler">
+            <span class="ruler-spacer" aria-hidden="true"></span>
+            <div id="ruler-scale" class="ruler-scale"></div>
+          </div>
+          <div id="tracks"></div>
+          <div id="playhead" class="playhead" aria-hidden="true"></div>
+        </div>
         <div id="error" role="alert" hidden></div>
         <div id="diagnostics" hidden></div>
       </section>
@@ -232,8 +208,8 @@ export function renderTimelinePreviewHtml(timelineId, options = {}) {
         <button id="play-button" class="play" type="button" aria-label="Play">&#9654;</button>
         <button id="step-forward" class="step" type="button" aria-label="Next frame" aria-keyshortcuts="ArrowRight" title="Next frame (→)">&#8250;</button>
         <button id="jump-forward" class="jump" type="button" aria-label="Forward one second" aria-keyshortcuts="Shift+ArrowRight" title="Forward one second (Shift+→)">+1s</button>
-        <input id="scrub" class="scrub" type="range" min="0" max="0" value="0" step="1" aria-label="Timeline frame">
-        <div class="readout"><b id="frame">0</b> / <span id="duration">0</span> f <span id="clock">0.00s</span></div>
+        <div class="scrub-wrap"><input id="scrub" class="scrub" type="range" min="0" max="0" value="0" step="1" aria-label="Timeline frame"></div>
+        <div class="readout"><span class="readout-label">frame</span><span id="frame">0</span><span class="dim">/</span><span id="duration">0</span><span class="dim">f</span><span class="dim">·</span><span id="clock" class="clock">0.00s</span></div>
         <label class="audio"><input id="mute" type="checkbox"> mute <input id="volume" type="range" min="0" max="1" step="0.01" value="0.8" aria-label="Audio volume"></label>
       </footer>
     </div>

package/dist/server/timeline-preview-html.js.map

@@ -1 +1 @@
-{"version":3,"file":"timeline-preview-html.js","sourceRoot":"","sources":["../../src/server/timeline-preview-html.ts"],"names":[],"mappings":"AAAA,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,EAAE;QAC7C,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,GAAG;gBACN,OAAO,OAAO,CAAC;YACjB,KAAK,GAAG;gBACN,OAAO,MAAM,CAAC;YAChB,KAAK,GAAG;gBACN,OAAO,MAAM,CAAC;YAChB,KAAK,GAAG;gBACN,OAAO,QAAQ,CAAC;YAClB;gBACE,OAAO,OAAO,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;IAChC,OAAO,EAAE;QACP,SAAS,EAAE,iCAAiC;QAC5C,mBAAmB,EAAE,yCAAyC;KAC/D;CACF,CAAC,CAAC;AAEH,MAAM,UAAU,yBAAyB,CAAC,UAAkB,EAAE,OAAO,GAAwB,EAAE;IAC7F,MAAM,EAAE,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAClC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO;;;;;gCAKqB,EAAE;;;;;;;4CAOU,UAAU;;4BAE1B,EAAE;;;;QAItB,CAAC;IACP,CAAC;IAED,OAAO;;;;;gCAKuB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA+JU,UAAU;;4BAE1B,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA8BtB,CAAC;AACT,CAAC"}
+{"version":3,"file":"timeline-preview-html.js","sourceRoot":"","sources":["../../src/server/timeline-preview-html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,EAAE;QAC7C,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,GAAG;gBACN,OAAO,OAAO,CAAC;YACjB,KAAK,GAAG;gBACN,OAAO,MAAM,CAAC;YAChB,KAAK,GAAG;gBACN,OAAO,MAAM,CAAC;YAChB,KAAK,GAAG;gBACN,OAAO,QAAQ,CAAC;YAClB;gBACE,OAAO,OAAO,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;IAChC,OAAO,EAAE;QACP,SAAS,EAAE,iCAAiC;QAC5C,mBAAmB,EAAE,yCAAyC;KAC/D;CACF,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHhB,CAAC;AAEF,MAAM,UAAU,yBAAyB,CAAC,UAAkB,EAAE,OAAO,GAAwB,EAAE;IAC7F,MAAM,EAAE,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAClC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO;;;;;gCAKqB,EAAE;;;;;;;4CAOU,UAAU;;4BAE1B,EAAE;;;;QAItB,CAAC;IACP,CAAC;IAED,OAAO;;;;;gCAKuB,EAAE;;EAEhC,WAAW;EACX,QAAQ;;4CAEkC,UAAU;;4BAE1B,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA4CtB,CAAC;AACT,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.10.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.9.0";
+export const VERSION = "0.10.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC"}

package/docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md

@@ -1,6 +1,6 @@
 # Render timelines with segmented lossless clip intermediates
 
-**Status:** Accepted
+**Status:** Accepted. Extended by [ADR-0024](./0024-stream-composition-captures-and-skip-trivial-composites.md): captures stream into FFV1, and single full-frame compositions skip the intermediate and composite.
 **Date:** 2026-10-31
 
 Timeline rendering will be segmented and parallel. For each segment, Chromium renders the active composition and nested-timeline clips to lossless FFV1 intermediates; FFmpeg decodes media, applies the clip's fit and static transform, composites the segment, encodes H.264, and the ordered segments are concatenated without re-encoding. Audio is mixed once for the whole timeline and muxed at the end. Preview remains a live Chromium timeline host with a bounded pool of active clips; parity is guaranteed at clip capture, not at the final composite.

package/docs/adr/0024-stream-composition-captures-and-skip-trivial-composites.md

@@ -0,0 +1,86 @@
+# Stream composition captures and skip trivial composites
+
+**Status:** Accepted. Extends [ADR-0012](./0012-render-timelines-with-segmented-lossless-clip-intermediates.md). Extended by [ADR-0025](./0025-capture-timeline-layers-in-parallel-with-a-global-limit.md): independent layers are captured concurrently under a global session limit. Extended by [ADR-0026](./0026-reuse-loaded-composition-sessions-across-segments.md): loaded sessions are reused across segments.
+**Date:** 2026-11-06
+
+The production timeline renderer will stream captured PNG buffers directly into
+the lossless FFV1 encoder instead of writing a PNG sequence to scratch first. A
+segment whose visual content is a single full-frame composition with no
+transform, opacity, blend, transition, or keyframes will bypass the FFV1
+intermediate and the FFmpeg composite entirely and encode the capture directly
+into the delivery segment over the timeline background. All other segments keep
+the segmented lossless path.
+
+## Context
+
+The 60-minute composition-only gate rendered 108,000 frames in 37.28 minutes
+with four workers. Per-stage worker time was 48.9%
+capture, 23.2% FFV1, 24.7% composite, and 2.8% session setup. The run wrote
+15.52 GB of PNG intermediates, and the FFV1 stage added 8.64 minutes of wall
+time at four workers. Capture itself was the floor: 92.6% of the capture loop
+was `Page.captureScreenshot` plus PNG encoding.
+
+The gate is a one-layer composition workload, so the FFV1 intermediate and the
+composite are identity operations apart from painting the timeline background.
+Streaming alone improved the 60-second gate from 43.27 seconds to 38.76
+seconds, but CPU contention between four concurrent captures and four FFV1
+encoders limited the gain. The direct path removes both stages for qualifying
+segments.
+
+## Decision
+
+- `captureCompositionLayer` opens an FFV1 encoder before capture and writes
+  each PNG buffer to its stdin. The encoder is bounded with
+  `FRAMEYARD_FFV1_THREADS` (default 2; `0` uses FFmpeg's default) so concurrent
+  captures retain CPU headroom.
+- `processTimelineSegment` detects a single active composition layer whose
+  source dimensions equal the stage, whose transform is the identity, and which
+  has no keyframes, blend, transition, or opacity. It also requires an opaque
+  timeline background. Such a segment uses `startDirectSegmentEncoder`, streams
+  the capture into the delivery codec over a solid background, and skips
+  `compositeTimelineSegment`.
+- Static compositions, media layers, nested timelines, transformed or animated
+  clips, blends, transitions, and transparent nested backgrounds keep the
+  segmented lossless path. Nested timelines continue to use FFV1.
+
+## Considered Options
+
+- **Keep the file-based PNG sequence.** Rejected: it wrote 15.52 GB to scratch,
+  serialized capture and FFV1, and spent 8.64 minutes of wall time on FFV1 at
+  four workers.
+- **Stream FFV1 only.** Accepted as the general path, but insufficient alone:
+  the 60-second gate improved by only 10.4% because capture and FFV1 contend for
+  CPU. It remains necessary for multi-layer and transformed segments.
+- **Always encode directly and skip the composite.** Rejected: multi-layer,
+  blended, keyframed, transformed, and nested segments need the FFmpeg
+  compositor.
+- **Use a GPU/Skia compositor.** Rejected for this change: the gate is capture
+  bound, and GPU rasterization would not remove screenshot/PNG encoding. It
+  would also complicate the capture-pixel reproducibility guarantee.
+- **Parallelize layer capture first.** Deferred for this change: it helps
+  multi-layer timelines but not the one-layer long-form gate. The measured
+  60-second two-layer run improved only 5.1% from streaming (62.79 to 59.60
+  seconds). ADR 0025 then captured independent layers concurrently and reduced
+  that run to 43.78 seconds.
+
+## Consequences
+
+- A qualifying direct segment emits `timeline.segment.direct` instead of
+  `timeline.segment.composite` in the opt-in stage timings.
+- Direct segments are encoded once, without a lossless FFV1 round trip. The
+  reproducibility guarantee remains at clip capture. For the 60-minute gate,
+  the direct output is byte-identical to the FFV1-and-composite output
+  (SHA-256 `02dab384...b6aab`).
+- Scratch no longer contains per-frame PNG sequences. The 60-minute gate wrote
+  no PNG files to disk; the 15.52 GB of PNG buffers went through memory and
+  pipes. FFV1 files remain for non-direct segments.
+- The 60-minute gate at eight workers completed in 19.83 minutes, 34% inside the
+  30-minute target. ADR 0026 later reduced it to 18.78 minutes by reusing loaded
+  sessions. At four workers the ten-minute gate projects about 24 minutes.
+- Multi-layer segments keep the lossless path and still pay for FFV1 and the
+  composite. ADR 0025 captures their independent layers concurrently; the
+  two-layer 60-second run improved from 62.79 to 59.60 seconds with streaming
+  and to 43.78 seconds with parallel layer capture.
+- The direct path is covered by the timeline rendering suite, including a
+  transparent full-frame composition over a non-black timeline background, and
+  by the full 108,000-frame gate with an FFprobe frame-count check.

package/docs/adr/0025-capture-timeline-layers-in-parallel-with-a-global-limit.md

@@ -0,0 +1,67 @@
+# Capture timeline layers in parallel with a global limit
+
+**Status:** Accepted. Extends [ADR-0024](./0024-stream-composition-captures-and-skip-trivial-composites.md). Extended by [ADR-0026](./0026-reuse-loaded-composition-sessions-across-segments.md): loaded sessions are reused across segments.
+**Date:** 2026-11-06
+
+Segments with more than one visual layer now capture their composition and
+static-image layers concurrently. A FIFO semaphore bounds active capture
+sessions across the whole render, independent of the segment worker count. The
+layer results are reordered before compositing so track order and output pixels
+are unchanged.
+
+## Context
+
+The segmented renderer processed `segment.layers` sequentially. A two-layer
+60-second gate with streaming FFV1 took 59.60 s: the segment time was the sum of
+both captures plus the composite. The same one-layer workload took 43.27 s
+before the direct fast path, and 27.64 s after it. The layer captures are
+independent, so the serial loop was leaving the second composition idle while
+the first encoded.
+
+An unbounded `Promise.all` is not safe: eight workers with three layers could
+open twenty-four Chromium sessions and run twenty-four concurrent FFV1
+encoders. The segment worker count already bounds the final segment encoders,
+but it does not bound capture sessions.
+
+## Decision
+
+- `createSemaphore(limit)` provides a FIFO capture limit.
+- The default limit is `min(workers * 2, 12)`. `FRAMEYARD_CAPTURE_CONCURRENCY`
+  overrides it for local A/B measurements.
+- Every composition and static-composition capture takes a slot for the whole
+  session and encoder lifetime. Nested timelines do not hold an outer slot;
+  their inner captures take slots from the same semaphore.
+- A segment starts all layer tasks together and uses `Promise.allSettled`.
+  It reorders successful results by layer index before compositing and throws
+  the first failure after every task has settled, so no capture is left writing
+  into scratch after the segment fails.
+- The direct one-layer segment path is unchanged; it takes one slot.
+
+## Considered Options
+
+- **Keep the sequential layer loop.** Rejected: it serializes independent
+  captures and leaves CPU idle during FFV1.
+- **Use unbounded `Promise.all`.** Rejected: capture sessions multiply with
+  workers and layers, causing memory and encoder oversubscription.
+- **Limit only per segment.** Rejected: a per-segment limit still multiplies by
+  the worker count, so eight workers with two layers would open sixteen
+  sessions.
+- **Reuse sessions instead.** Deferred for this change: a pool removes session
+  startup but does not shorten the critical path of a multi-layer segment. ADR
+  0026 adds the pool as a separate optimization.
+
+## Consequences
+
+- The two-layer 60-second gate fell from 59.60 s to 43.78 s (−26.5%) with four
+  workers; the output is byte-identical to the sequential run.
+- The one-layer 60-minute gate is unaffected because every segment uses the
+  direct path.
+- Peak capture sessions are bounded at 12, including eight-worker renders with
+  multi-layer segments.
+- Captures that share a static-composition cache key still wait for one slot
+  each; the capture itself is deduplicated by the existing promise cache.
+- A failed layer task settles its siblings before the segment throws; the
+  scratch directory is then cleaned by the render's existing failure path.
+- The full timeline rendering suite passes with parallel captures, including
+  transparent compositions, blends, keyframes, transitions, nested timelines,
+  and static layers.

package/docs/adr/0026-reuse-loaded-composition-sessions-across-segments.md

@@ -0,0 +1,70 @@
+# Reuse loaded composition sessions across segments
+
+**Status:** Accepted. Extends [ADR-0025](./0025-capture-timeline-layers-in-parallel-with-a-global-limit.md). Extended by [ADR-0027](./0027-encode-two-full-frame-layers-through-dual-pipes.md): two full-frame layers encode through dual image pipes.
+**Date:** 2026-11-06
+
+The timeline renderer keeps a bounded pool of loaded composition sessions and
+leases them to segment captures. A session is keyed by composition entry, props,
+and transparent-background mode, and is reused across segments and clips that
+share those inputs. Sessions are discarded on a capture error and all sessions
+are closed when the render ends.
+
+## Context
+
+Every composition layer of every segment opened a new Chromium browser, loaded
+the composition, waited for `networkidle` (roughly 450 ms), and closed it. The
+one-layer 60-minute gate opened 360 sessions; a two-layer workload opens 720.
+The 10-minute one-layer gate without a pool took 211.8 s, and its session stage
+was a repeated fixed cost rather than frame work.
+
+The host already has the right reuse semantics: `load` restores the pristine DOM
+and mounts the controller once, while `seek` is required to be stateless. A
+loaded session with the same props can seek to any frame of any segment.
+
+## Decision
+
+- `CompositionSessionPool` stores idle sessions in a map keyed by
+  `entry + props + transparentBackground`.
+- `maxIdle` is `max(2, workers)`. Active sessions are already bounded by the
+  capture semaphore; the idle cap bounds memory for workloads with many unique
+  compositions.
+- `captureCompositionFrames` leases a session instead of opening one directly.
+  A successful capture releases the lease; a capture, diagnostics, or encoder
+  error discards it.
+- Nested timelines share the render's pool. Static compositions keep their
+  one-shot capture and cache because they are captured once per props variant.
+- The render closes the pool before the preview server in its cleanup path.
+- The session timing event records `reused: true` when the lease came from the
+  pool.
+
+## Considered Options
+
+- **Remove `networkidle` only.** Rejected as the primary change: it removes a
+  fixed wait but does not avoid browser launch, navigation, and host load. It
+  also weakens the asset-loading boundary for compositions with stylesheet
+  background images. Session reuse amortizes the whole startup cost instead.
+- **Share one browser process without reusing pages.** Rejected: it saves the
+  browser launch but still pays navigation, host load, and `networkidle` per
+  segment.
+- **Per-worker pools.** Rejected: a shared pool lets any worker reuse an idle
+  session and keeps the idle budget independent of worker count.
+- **Unbounded idle caching.** Rejected: compositions with many unique props or
+  entries could retain an unbounded number of pages and media elements.
+
+## Consequences
+
+- The 10-minute one-layer gate fell from 211.8 s to 192.6 s (−9.0%) with the
+  same 8 workers and byte-identical output. The full 60-minute gate fell from
+  19.83 to 18.78 minutes (−5.3%) and opened eight sessions for 360 segments
+  instead of 360 sessions. Its output is byte-identical to the baseline.
+- The two-layer 60-second gate did not show a clear gain (43.78 s to 45.43 s):
+  six segments are too few for reuse to pay back the pool's initial opens. The
+  long-form workload is the target.
+- Reused sessions return accumulated diagnostics; the final merge continues to
+  deduplicate them. A page error discards the session so a broken render cannot
+  poison later segments.
+- The pool is internal to a render. There is no public CLI or JSON contract
+  change.
+- Tests cover same-key reuse, discard, idle-budget eviction, close, and the
+  existing timeline suite with embedded media, controllers, blends, keyframes,
+  transitions, and nested timelines.