npm - frameyard - Versions diffs - 0.5.0 → 0.6.0 - Mend

frameyard 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

package/CHANGELOG.md +55 -0
package/GLOSSARY.md +152 -24
package/README.md +94 -29
package/dist/cli.js +111 -14
package/dist/cli.js.map +1 -1
package/dist/contracts.d.ts +12 -0
package/dist/contracts.d.ts.map +1 -1
package/dist/contracts.js.map +1 -1
package/dist/errors.d.ts +1 -1
package/dist/errors.d.ts.map +1 -1
package/dist/errors.js.map +1 -1
package/dist/index.d.ts +2 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +1 -0
package/dist/index.js.map +1 -1
package/dist/preview/main.js +89 -11
package/dist/preview/main.js.map +1 -1
package/dist/preview/timeline-data.d.ts +85 -0
package/dist/preview/timeline-data.d.ts.map +1 -0
package/dist/preview/timeline-data.js +2 -0
package/dist/preview/timeline-data.js.map +1 -0
package/dist/preview/timeline-host.d.ts +19 -0
package/dist/preview/timeline-host.d.ts.map +1 -0
package/dist/preview/timeline-host.js +297 -0
package/dist/preview/timeline-host.js.map +1 -0
package/dist/preview/timeline-main.d.ts +17 -0
package/dist/preview/timeline-main.d.ts.map +1 -0
package/dist/preview/timeline-main.js +364 -0
package/dist/preview/timeline-main.js.map +1 -0
package/dist/project.d.ts +16 -1
package/dist/project.d.ts.map +1 -1
package/dist/project.js +81 -26
package/dist/project.js.map +1 -1
package/dist/renderer/browser.d.ts +2 -0
package/dist/renderer/browser.d.ts.map +1 -1
package/dist/renderer/browser.js +6 -1
package/dist/renderer/browser.js.map +1 -1
package/dist/renderer/ffmpeg.d.ts +61 -0
package/dist/renderer/ffmpeg.d.ts.map +1 -1
package/dist/renderer/ffmpeg.js +198 -0
package/dist/renderer/ffmpeg.js.map +1 -1
package/dist/renderer/timeline.d.ts +109 -0
package/dist/renderer/timeline.d.ts.map +1 -0
package/dist/renderer/timeline.js +984 -0
package/dist/renderer/timeline.js.map +1 -0
package/dist/scaffold.d.ts.map +1 -1
package/dist/scaffold.js +89 -24
package/dist/scaffold.js.map +1 -1
package/dist/server/preview-html.d.ts.map +1 -1
package/dist/server/preview-html.js +15 -1
package/dist/server/preview-html.js.map +1 -1
package/dist/server/server.d.ts.map +1 -1
package/dist/server/server.js +39 -1
package/dist/server/server.js.map +1 -1
package/dist/server/timeline-preview-data.d.ts +4 -0
package/dist/server/timeline-preview-data.d.ts.map +1 -0
package/dist/server/timeline-preview-data.js +97 -0
package/dist/server/timeline-preview-data.js.map +1 -0
package/dist/server/timeline-preview-html.d.ts +4 -0
package/dist/server/timeline-preview-html.d.ts.map +1 -0
package/dist/server/timeline-preview-html.js +227 -0
package/dist/server/timeline-preview-html.js.map +1 -0
package/dist/timeline/plan.d.ts +32 -0
package/dist/timeline/plan.d.ts.map +1 -0
package/dist/timeline/plan.js +68 -0
package/dist/timeline/plan.js.map +1 -0
package/dist/timeline/resolve.d.ts +60 -0
package/dist/timeline/resolve.d.ts.map +1 -0
package/dist/timeline/resolve.js +523 -0
package/dist/timeline/resolve.js.map +1 -0
package/dist/timeline/schema.d.ts +71 -0
package/dist/timeline/schema.d.ts.map +1 -0
package/dist/timeline/schema.js +425 -0
package/dist/timeline/schema.js.map +1 -0
package/dist/version.d.ts +1 -1
package/dist/version.js +1 -1
package/docs/adr/0002-make-frame-and-props-the-only-animation-state.md +2 -0
package/docs/adr/0005-keep-parallel-rendering-opt-in-and-frame-ordered.md +2 -0
package/docs/adr/0007-make-html-documents-the-composition-unit.md +1 -1
package/docs/adr/0009-composite-production-frames-in-software.md +1 -1
package/docs/adr/0010-make-timelines-the-render-unit.md +24 -0
package/docs/adr/0011-compose-timeline-frames-in-a-live-browser-host.md +22 -0
package/docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md +31 -0
package/docs/v0.1-design.md +135 -86
package/examples/demo/README.md +10 -3
package/examples/demo/timelines/demo.timeline.json +12 -0
package/examples/demo/video.config.js +4 -0
package/examples/video/README.md +50 -6
package/examples/video/compositions/video-overlay.html +350 -0
package/examples/video/props/video-timeline.json +10 -0
package/examples/video/timelines/video-timeline-mp4.timeline.json +44 -0
package/examples/video/timelines/video-timeline.timeline.json +44 -0
package/examples/video/video.config.js +6 -0
package/package.json +1 -1
package/skills/frameyard/SKILL.md +17 -13
package/skills/frameyard/references/timelines.md +141 -0

package/examples/video/compositions/video-overlay.html ADDED Viewed

@@ -0,0 +1,350 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <script type="application/json" data-fy="props">
+      {
+        "kicker": "Frameyard / Timeline Overlay 001",
+        "title": "Timeline",
+        "titleAccent": "Overlay",
+        "subtitle": "The clip lives on a timeline track. This HTML layer composites over it with alpha.",
+        "detail": "Detail / second pass",
+        "format": "30 FPS",
+        "accent": "#ffc37a"
+      }
+    </script>
+    <style>
+      @keyframes fade-in {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+      @keyframes rise {
+        from {
+          opacity: 0;
+          transform: translateY(42px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+      @keyframes draw {
+        from {
+          opacity: 0;
+          transform: scaleX(0);
+        }
+        to {
+          opacity: 1;
+          transform: scaleX(1);
+        }
+      }
+      @keyframes detail-cycle {
+        0% {
+          opacity: 0;
+        }
+        6% {
+          opacity: 1;
+        }
+        94% {
+          opacity: 1;
+        }
+        100% {
+          opacity: 0;
+        }
+      }
+      @keyframes outro-fade {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+      html,
+      body,
+      fy-composition {
+        background: transparent;
+      }
+      #scene {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        isolation: isolate;
+        color: #eef4f1;
+        font-family: Inter, "Helvetica Neue", ui-sans-serif, system-ui, sans-serif;
+      }
+      #scrim {
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(
+          90deg,
+          rgba(4, 8, 11, 0.94) 0%,
+          rgba(4, 8, 11, 0.82) 22%,
+          rgba(4, 8, 11, 0.35) 46%,
+          rgba(4, 8, 11, 0) 66%
+        );
+        pointer-events: none;
+      }
+      #footer-scrim {
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        height: 150px;
+        background: linear-gradient(0deg, rgba(4, 8, 11, 0.88) 0%, rgba(4, 8, 11, 0) 100%);
+        pointer-events: none;
+      }
+      #frame-border {
+        position: absolute;
+        inset: 36px;
+        border: 1px solid rgba(238, 244, 241, 0.16);
+        pointer-events: none;
+      }
+      #header {
+        position: absolute;
+        top: 80px;
+        left: 148px;
+        right: 148px;
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        gap: 32px;
+        animation: fade-in 1s linear both;
+      }
+      #kicker {
+        display: flex;
+        align-items: center;
+        gap: 15px;
+        font:
+          600 14px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.24em;
+        text-transform: uppercase;
+        color: var(--fy-prop-accent);
+      }
+      #kicker::before {
+        content: "";
+        width: 8px;
+        height: 8px;
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 16px var(--fy-prop-accent);
+      }
+      #format {
+        font:
+          500 12px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.16em;
+        text-transform: uppercase;
+        color: #b9c6c8;
+        text-shadow: 0 2px 18px rgba(0, 0, 0, 0.65);
+      }
+      #copy {
+        position: absolute;
+        top: 278px;
+        left: 148px;
+        width: 860px;
+      }
+      #title {
+        margin: 0;
+        font-size: 174px;
+        line-height: 0.84;
+        letter-spacing: -0.064em;
+        font-weight: 660;
+      }
+      #title span,
+      #title em {
+        display: block;
+        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #title em {
+        margin-top: 0.06em;
+        font-family: "Iowan Old Style", "Palatino Linotype", Georgia, ui-serif, serif;
+        font-style: italic;
+        font-weight: 400;
+        letter-spacing: -0.035em;
+        color: var(--fy-prop-accent);
+      }
+      #subtitle {
+        width: 720px;
+        margin: 38px 0 0;
+        font-size: 29px;
+        line-height: 1.5;
+        font-weight: 420;
+        color: #b3c1c4;
+        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #detail {
+        position: absolute;
+        left: 1332px;
+        top: 646px;
+        width: 440px;
+        animation: detail-cycle 1s linear both;
+      }
+      #detail-bar {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        gap: 16px;
+        height: 22px;
+        margin-bottom: 10px;
+        padding: 0 10px;
+        background: rgba(4, 8, 11, 0.55);
+        font:
+          600 11px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.18em;
+        text-transform: uppercase;
+      }
+      #detail-bar > span:first-child {
+        color: var(--fy-prop-accent);
+      }
+      #detail-time {
+        color: #c0cdcf;
+        font-weight: 500;
+      }
+      #detail-window {
+        position: relative;
+        width: 440px;
+        height: 248px;
+        box-sizing: border-box;
+        overflow: hidden;
+        border: 1px solid rgba(255, 195, 122, 0.75);
+        background: transparent;
+        box-shadow: 0 24px 90px rgba(0, 0, 0, 0.45);
+      }
+      #detail-tint {
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(0deg, rgba(4, 8, 11, 0.32) 0%, rgba(4, 8, 11, 0) 45%);
+        pointer-events: none;
+      }
+      #footer {
+        position: absolute;
+        left: 148px;
+        right: 148px;
+        bottom: 70px;
+        contain: layout paint style;
+        animation: fade-in 1s linear both;
+      }
+      #rule {
+        position: relative;
+        height: 1px;
+        background: rgba(238, 244, 241, 0.24);
+        transform-origin: left center;
+        animation: draw 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #progress {
+        position: absolute;
+        inset: 0 auto 0 0;
+        width: calc(var(--fy-progress) * 100%);
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 14px var(--fy-prop-accent);
+      }
+      #footer-row {
+        display: flex;
+        justify-content: space-between;
+        align-items: baseline;
+        gap: 24px;
+        margin-top: 18px;
+        font:
+          500 12px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.14em;
+        color: #a4b1b3;
+        text-transform: uppercase;
+        text-shadow: 0 2px 14px rgba(0, 0, 0, 0.7);
+      }
+      #footer-row strong {
+        color: #edf5f2;
+        font-weight: 600;
+      }
+      #footer-row .accent {
+        color: var(--fy-prop-accent);
+      }
+      #frame-counter {
+        display: inline-block;
+        min-width: 3ch;
+        text-align: right;
+      }
+      #frame-counter::after {
+        counter-reset: fy-frame var(--fy-frame);
+        content: counter(fy-frame);
+      }
+      #outro-fade {
+        position: absolute;
+        inset: 0;
+        background: #04080b;
+        pointer-events: none;
+        opacity: 0;
+        animation: outro-fade 1s linear both;
+      }
+    </style>
+  </head>
+  <body>
+    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="360">
+      <div id="scene">
+        <div id="scrim"></div>
+        <div id="footer-scrim"></div>
+        <div id="frame-border"></div>
+        <header id="header" data-fy-anim-start="8" data-fy-anim-duration="28">
+          <div id="kicker" data-fy-text="kicker"></div>
+          <div id="format">Timeline video / <span data-fy-text="format"></span></div>
+        </header>
+        <div id="copy">
+          <h1 id="title">
+            <span
+              data-fy-text="title"
+              data-fy-anim-start="14"
+              data-fy-anim-duration="44"
+              data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+            ></span>
+            <em
+              data-fy-text="titleAccent"
+              data-fy-anim-start="26"
+              data-fy-anim-duration="44"
+              data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+            ></em>
+          </h1>
+          <p
+            id="subtitle"
+            data-fy-text="subtitle"
+            data-fy-anim-start="40"
+            data-fy-anim-duration="40"
+            data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+          ></p>
+        </div>
+        <div id="detail" data-fy-anim-start="112" data-fy-anim-duration="170">
+          <div id="detail-bar">
+            <span data-fy-text="detail"></span>
+            <span id="detail-time">SRC 5.8–10.8 S</span>
+          </div>
+          <div id="detail-window">
+            <div id="detail-tint"></div>
+          </div>
+        </div>
+        <div id="footer" data-fy-anim-start="46" data-fy-anim-duration="30">
+          <div id="rule" data-fy-anim-start="52" data-fy-anim-duration="50">
+            <div id="progress"></div>
+          </div>
+          <div id="footer-row">
+            <span>Hero / v1 · SRC <strong>0.0–12.0 S</strong></span>
+            <span>Detail / v2 · SRC <strong>5.8–10.8 S</strong></span>
+            <span>Frame <strong id="frame-counter"></strong> / 359</span>
+            <span class="accent">HTML overlay / v3 · 30 FPS</span>
+          </div>
+        </div>
+        <div id="outro-fade" data-fy-anim-start="329" data-fy-anim-duration="30"></div>
+      </div>
+    </fy-composition>
+  </body>
+</html>

package/examples/video/props/video-timeline.json ADDED Viewed

@@ -0,0 +1,10 @@
+{
+  "overlay": {
+    "kicker": "Frameyard / Timeline Overlay 001",
+    "title": "Track",
+    "titleAccent": "Overlay",
+    "subtitle": "One clip on v1, a second pass on v2, and this HTML layer on v3.",
+    "detail": "Detail / second pass",
+    "accent": "#8fe6c8"
+  }
+}

package/examples/video/timelines/video-timeline-mp4.timeline.json ADDED Viewed

@@ -0,0 +1,44 @@
+{
+  "version": 1,
+  "name": "Video on a track, HTML overlay on top (MP4)",
+  "tracks": [
+    { "id": "v1", "kind": "video", "name": "Hero video" },
+    { "id": "v2", "kind": "video", "name": "Detail video" },
+    { "id": "v3", "kind": "video", "name": "HTML overlay" }
+  ],
+  "clips": [
+    {
+      "id": "hero",
+      "track": "v1",
+      "source": { "kind": "video", "src": "assets/clip.mp4" },
+      "start": 0,
+      "audio": { "gain": 0.85 }
+    },
+    {
+      "id": "detail",
+      "track": "v2",
+      "source": { "kind": "video", "src": "assets/clip.mp4" },
+      "start": 120,
+      "sourceIn": 174,
+      "duration": 150,
+      "transform": {
+        "fit": "cover",
+        "width": 440,
+        "height": 248,
+        "x": 592,
+        "y": 262,
+        "rotation": 0,
+        "opacity": 1
+      },
+      "audio": { "muted": true }
+    },
+    {
+      "id": "overlay",
+      "track": "v3",
+      "source": { "kind": "composition", "id": "video-overlay" },
+      "start": 0,
+      "duration": 360,
+      "props": { "format": "H.264 + AAC / 30 FPS" }
+    }
+  ]
+}

package/examples/video/timelines/video-timeline.timeline.json ADDED Viewed

@@ -0,0 +1,44 @@
+{
+  "version": 1,
+  "name": "Video on a track, HTML overlay on top",
+  "tracks": [
+    { "id": "v1", "kind": "video", "name": "Hero video" },
+    { "id": "v2", "kind": "video", "name": "Detail video" },
+    { "id": "v3", "kind": "video", "name": "HTML overlay" }
+  ],
+  "clips": [
+    {
+      "id": "hero",
+      "track": "v1",
+      "source": { "kind": "video", "src": "assets/clip.webm" },
+      "start": 0,
+      "audio": { "gain": 0.85 }
+    },
+    {
+      "id": "detail",
+      "track": "v2",
+      "source": { "kind": "video", "src": "assets/clip.webm" },
+      "start": 120,
+      "sourceIn": 174,
+      "duration": 150,
+      "transform": {
+        "fit": "cover",
+        "width": 440,
+        "height": 248,
+        "x": 592,
+        "y": 262,
+        "rotation": 0,
+        "opacity": 1
+      },
+      "audio": { "muted": true }
+    },
+    {
+      "id": "overlay",
+      "track": "v3",
+      "source": { "kind": "composition", "id": "video-overlay" },
+      "start": 0,
+      "duration": 360,
+      "props": { "format": "VP9 + Opus / 30 FPS" }
+    }
+  ]
+}

package/examples/video/video.config.js CHANGED Viewed

@@ -1,6 +1,12 @@
 export default {
+  format: { width: 1920, height: 1080, fps: 30 },
   compositions: {
     video: "./compositions/video.html",
     "video-mp4": "./compositions/video-mp4.html",
+    "video-overlay": "./compositions/video-overlay.html",
+  },
+  timelines: {
+    "video-timeline": "./timelines/video-timeline.timeline.json",
+    "video-timeline-mp4": "./timelines/video-timeline-mp4.timeline.json",
   },
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",

package/skills/frameyard/SKILL.md CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 name: frameyard
-description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML, CSS, and an optional JavaScript controller. Use when a user asks to build or operate a Frameyard project, produce parameterized video, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
-frameyard-api-version: 0.5.0
+description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML compositions and JSON timelines. Use when a user asks to build or operate a Frameyard project, produce parameterized video, assemble clips into a timeline, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
+frameyard-api-version: 0.6.0
 ---
 # Frameyard
@@ -11,19 +11,20 @@ Use Frameyard's public project format and CLI. Do not introduce an agent-only ru
 ## First decisions
 1. Find the project: look for `video.config.js` from the working directory upward, or run `npx frameyard init <directory>` to scaffold one.
-2. Read the composition entry points listed in `video.config.js`. They are `.html` documents; there is no directory scanning.
-3. Read the composition HTML, its optional controller, and the props file before changing behavior.
+2. Read the `format`, `compositions`, and `timelines` maps in `video.config.js`. Entries are explicit `.html` and `.json` documents; there is no directory scanning.
+3. Read the timeline JSON, the referenced composition HTML, its optional controller, and the props files before changing behavior.
 4. If the task needs speech or transcription, confirm that inference is requested or explicitly approved before producing assets.
 ## Workflow
-1. **Author** the composition as a full HTML document with one `<fy-composition>` root. Put metadata, default props, markup, CSS animation, bindings, audio, and transcripts in the document. Use an optional controller for Canvas 2D, WebGL, karaoke, or per-frame computation CSS cannot express. Read [deterministic authoring](references/deterministic-authoring.md), [bindings](references/bindings.md), and [controllers](references/controllers.md).
-2. **Provide props** as JSON. Validate domain-specific requirements with a controller's `validateProps()`.
-3. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
-4. **Validate** with `npx frameyard check <id> --json`. Static validation runs before Chromium; then every frame is evaluated. Read the structured `diagnostics` array. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
-5. **Inspect** representative frames with `npx frameyard still <id> --frame <n> --out <file.png> --json`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
-6. **Render** with `npx frameyard render <id> [--out <file.mp4>] [--props <file>] [--concurrency <n>] --json`. The default output is `out/<id>.mp4` in the project root.
-7. **Report** the project path, composition entry, controller, props, generated assets, provenance manifest, validation results, diagnostics, still paths and inspection status, final video path, and any failures.
+1. **Author compositions** as full HTML documents with one `<fy-composition>` root. Put metadata, default props, markup, CSS animation, bindings, audio, and transcripts in the document. Use an optional controller for Canvas 2D, WebGL, karaoke, or per-frame computation CSS cannot express. Read [deterministic authoring](references/deterministic-authoring.md), [bindings](references/bindings.md), and [controllers](references/controllers.md).
+2. **Assemble the timeline** in JSON: project format, video/audio tracks, composition, media, and nested-timeline clips, source ranges, static transforms, and audio. Read [timelines](references/timelines.md).
+3. **Provide props** as JSON. Composition props merge over defaults; timeline render props are a map keyed by composition clip ID. Validate domain-specific requirements with a controller's `validateProps()`.
+4. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
+5. **Validate** with `npx frameyard check <id> --json`, where `<id>` is a timeline or composition. Static validation runs before Chromium; then every frame is evaluated. Read the structured `diagnostics` array. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
+6. **Inspect** representative frames with `npx frameyard still <id> --frame <n> --out <file.png> --json`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
+7. **Render** with `npx frameyard render <id> [--out <file.mp4>] [--props <file>] --json`. Composition renders accept `--concurrency <n>`; timeline renders accept `--workers <n>` and `--scratch <dir>`. The default output is `out/<id>.mp4` in the project root.
+8. **Report** the project path, timeline and composition entries, controller, props, generated assets, provenance manifest, validation results, diagnostics, still paths and inspection status, final video path, and any failures.
 Never claim success when `check` fails, a still is missing, a render exits nonzero, or visual inspection was skipped. A partial or unpublished render is not a successful result.
@@ -33,13 +34,15 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 - Keep the current output files unless the user explicitly approves replacement. Use `--force` only with that approval.
 - Use `--project <dir>` when not running from the project root.
 - `render` writes to `out/<id>.mp4` in the project root unless `--out` is passed. Explicit `--out` paths are relative to the current working directory.
-- Use `--concurrency <n>` only when faster local rendering is useful; the default is `1` and the maximum is `16`. It changes capture scheduling only, not composition behavior or output frame order.
+- Use `--concurrency <n>` only for composition renders; the default is `1` and the maximum is `16`. Use `--workers <n>` for timeline renders; the default is `8`. Timeline renders also accept `--scratch <dir>` for FFV1 intermediates.
+- For a timeline, `--props` is a JSON object keyed by top-level composition clip ID. For a composition, it is the props object.
 - Use `npx frameyard doctor --json` before reporting an environment problem. It inspects without repairing or downloading.
 - Read [JSON results](references/json-results.md) for result and error shapes, and [failure recovery](references/failure-recovery.md) for actionable error codes.
 ## Authoring rules
 - A composition is a full HTML document with one `<fy-composition width height fps duration-in-frames>` root and a `data-fy="props"` default-props block.
+- A timeline is a versioned JSON document with explicit tracks and clips. Sources are composition IDs, nested timeline IDs, or local video/image/audio paths. Timeline frames, sourceIn, and duration are integer frames. No remote URLs.
 - Bindings are explicit: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat` on `<template>`. Primitive top-level props are also `--fy-prop-<name>` CSS variables.
 - CSS `@keyframes` and the Web Animations API are seeked from the frame clock. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation per element in frames.
 - Frame-state variables on `:root`: `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames`.
@@ -50,7 +53,7 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 ## Determinism guardrails
-- A frame may depend only on its integer `frame`, immutable `props`, and assets loaded before frame production.
+- A composition frame may depend only on its integer `frame`, immutable `props`, and assets loaded before frame production. A timeline frame derives from its active clips and the same composition rules.
 - Use `random("stable:key")` from `frameyard/runtime`; never use `Math.random()`.
 - Never use `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions as animation inputs.
 - Finish remote data, fonts, and image loading during the loading phase. Network requests are blocked during frame capture.
@@ -80,6 +83,7 @@ When the CLI version differs from `frameyard-api-version`, pin it with `npx fram
 ## References
+- [Timelines](references/timelines.md)
 - [Deterministic HTML authoring](references/deterministic-authoring.md)
 - [Bindings](references/bindings.md)
 - [Controllers](references/controllers.md)