frameyard 0.5.0 → 0.7.0

package/examples/demo/README.md

@@ -10,14 +10,21 @@ A 30-second, 1920×1080 HTML composition that exercises the current core:
 - frame-state CSS variables for the progress bar
 
 The composition lives in `compositions/demo.html`; the optional controller is
-`compositions/demo.controller.js`.
+`compositions/demo.controller.js`. `timelines/demo.timeline.json` wraps the
+composition as a clip in a 1920×1080, 30 fps timeline.
 
 From the repository root:
 
 ```sh
 pnpm build
-node dist/cli.js check demo --project examples/demo
-node dist/cli.js still demo --frame 240 --project examples/demo --out demo-still.png
+node dist/cli.js check demo-timeline --project examples/demo
+node dist/cli.js still demo-timeline --frame 240 --project examples/demo --out demo-still.png
+node dist/cli.js render demo-timeline --project examples/demo --props examples/demo/props/demo.json
+```
+
+The composition remains renderable on its own:
+
+```sh
 node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json
 ```
 

package/examples/demo/timelines/demo.timeline.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "tracks": [{ "id": "v1", "kind": "video" }],
+  "clips": [
+    {
+      "id": "demo",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "demo" },
+      "start": 0
+    }
+  ]
+}

package/examples/demo/video.config.js

@@ -1,5 +1,9 @@
 export default {
+  format: { width: 1920, height: 1080, fps: 30 },
   compositions: {
     demo: "./compositions/demo.html",
   },
+  timelines: {
+    "demo-timeline": "./timelines/demo.timeline.json",
+  },
 };

package/examples/video/README.md

@@ -1,7 +1,7 @@
 # Frameyard video example
 
-A 12-second, 1920×1080 composition that treats a local clip as source footage
-and seeks it twice. The project includes the same layout for two source codecs:
+A 12-second, 1920×1080 project that treats a local clip as source footage. The
+project includes the same layout for two source codecs:
 
 - `video` reads `assets/clip.webm` (VP9 + Opus)
 - `video-mp4` reads `assets/clip.mp4` (H.264 + AAC)
@@ -25,11 +25,49 @@ controller is needed. The header, copy, and footer fade individually rather
 than the whole scene; a full-scene opacity animation above a video can leave
 the load frame on screen in interactive preview after a large seek.
 
+## Timeline with the video on a track
+
+`video-timeline` and `video-timeline-mp4` move the footage out of the
+composition and onto timeline tracks. The HTML is now a transparent overlay
+above it:
+
+- `v1` holds the hero clip: the whole 12-second source, audio at `0.85`
+- `v2` holds the detail pass from source frame 174 (5.8 s) for 150 frames,
+  muted, placed in a 440×248 transform box in the bottom right
+- `v3` holds `video-overlay`, an HTML-only composition with no `<video>`
+  elements and a transparent document background
+
+`video-timeline` reads `assets/clip.webm` (VP9 + Opus) and
+`video-timeline-mp4` reads `assets/clip.mp4` (H.264 + AAC). Both share the same
+overlay composition and props file; the overlay clip sets its own `format` prop
+so the header reports the codec of each timeline.
+
+The detail clip uses `transform.width` and `transform.height` instead of
+`scale`, with `fit: "cover"` filling that box. The box matches the overlay's
+detail window exactly, so the video and its chrome stay aligned in production
+and preview.
+
+The overlay draws the scrim, typography, frame border, detail-window chrome,
+progress bar, and outro fade. `video-overlay` declares its own frame animations,
+so the title and footer still animate on the timeline clock. Production captures
+the overlay with alpha and composites it over the video layers with FFmpeg; the
+interactive timeline preview composites the same layers in Chromium.
+
+Both timelines accept `props/video-timeline.json`, which overrides the overlay
+composition's props. Timeline `--props` is keyed by composition clip id, so the
+file targets the `overlay` clip.
+
+Open the preview with `node dist/cli.js dev --project examples/video`; the
+compositions and both timelines are listed.
+
 The compositions live in `compositions/video.html` and
-`compositions/video-mp4.html`. Both clips are 12-second 1280×720 files generated
-procedurally for this example; the MP4 is transcoded from the WebM source.
-Replace either asset with a local, seekable video file that is at least
-12 seconds long; remote URLs and live streams are not supported.
+`compositions/video-mp4.html`; the overlay lives in
+`compositions/video-overlay.html`, and the timelines in
+`timelines/video-timeline.timeline.json` and
+`timelines/video-timeline-mp4.timeline.json`. Both clips are 12-second 1280×720
+files generated procedurally for this example; the MP4 is transcoded from the
+WebM source. Replace either asset with a local, seekable video file that is at
+least 12 seconds long; remote URLs and live streams are not supported.
 
 Regenerate both clips from scratch with the bundled FFmpeg script:
 
@@ -48,10 +86,16 @@ From the repository root:
 pnpm build
 node dist/cli.js check video --project examples/video
 node dist/cli.js check video-mp4 --project examples/video
+node dist/cli.js check video-timeline --project examples/video
+node dist/cli.js check video-timeline-mp4 --project examples/video
 node dist/cli.js still video --frame 210 --project examples/video --out video-still.png
 node dist/cli.js still video-mp4 --frame 210 --project examples/video --out video-mp4-still.png
+node dist/cli.js still video-timeline --frame 210 --project examples/video --out video-timeline-still.png
+node dist/cli.js still video-timeline-mp4 --frame 210 --project examples/video --out video-timeline-mp4-still.png
 node dist/cli.js render video --project examples/video --props examples/video/props/video.json
 node dist/cli.js render video-mp4 --project examples/video --props examples/video/props/video.json
+node dist/cli.js render video-timeline --project examples/video --props examples/video/props/video-timeline.json
+node dist/cli.js render video-timeline-mp4 --project examples/video --props examples/video/props/video-timeline.json
 ```
 
 Start the interactive preview with:

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",
@@ -59,7 +59,7 @@
     "@types/node": "26.6.5",
     "oxfmt": "0.75.0",
     "oxlint": "1.90.0",
-    "typescript": "5.9.3",
+    "typescript": "7.0.2",
     "vitest": "5.0.5"
   },
   "scripts": {
@@ -74,8 +74,10 @@
     "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm typecheck:test && pnpm typecheck:browser",
     "compare-stills": "node scripts/compare-stills.mjs",
     "check": "pnpm check:static && pnpm test",
+    "check:preview": "pnpm check:static && pnpm test:preview",
     "test": "pnpm build && vitest run",
-    "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/random.test.ts test/release.test.ts test/scaffold.test.ts test/transcript.test.ts",
+    "test:preview": "pnpm build && vitest run test/preview-runtime.test.ts test/timeline-preview.test.ts test/timeline-preview-runtime.test.ts",
+    "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/encoders.test.ts test/random.test.ts test/release.test.ts test/scaffold.test.ts test/transcript.test.ts",
     "bench": "pnpm build && node scripts/bench-render.mjs",
     "set-version": "node scripts/set-version.mjs",
     "verify-release": "node scripts/verify-release.mjs",

package/skills/frameyard/README.md

@@ -10,16 +10,18 @@ Install from the repository with the open agent-skills CLI:
 npx skills add vladiantio/frameyard
 ```
 
-The skill lives at `skills/frameyard` in the repository and npm package. Alternatively, copy or symlink the whole `skills/frameyard/` directory into the skill location your agent host uses. Examples:
+The skill lives at `skills/frameyard` in the repository and npm package. Alternatively, copy or symlink the whole `skills/frameyard/` directory into the skill location your agent host uses:
 
-- Claude Code project skills: `.claude/skills/frameyard`
-- Agent hosts that read `.agents/skills`: `.agents/skills/frameyard`
-- Global installations: place it under your host's documented personal skills directory
+- Project-scoped: `.claude/skills/frameyard` for Claude Code, or `.agents/skills/frameyard` for hosts that read the shared `.agents` container.
+- Personal or global: `~/.claude/skills/frameyard`, `~/.agents/skills/frameyard`, or another host's personal directory; for example, OpenCode reads `~/.config/opencode/skills/frameyard`.
+- Keep one canonical copy and symlink it into the host directories you use, so updates do not drift.
 
-The skill is host-neutral: it uses only the normal `frameyard` project format and CLI. There is no agent-only runtime.
+The skill is host-neutral: it uses only the normal `frameyard` project format and CLI. There is no agent-only runtime. All `references/`, `scripts/`, and `SKILL.md` paths inside the skill are relative, so the directory works wherever it is installed.
 
 Run the CLI with `npx frameyard`. It resolves the latest published version; pin it with `npx frameyard@<version>` or install the package locally when the CLI version must match the skill. When the skill is copied outside the npm package, `scripts/frameyard.mjs` falls back to the `frameyard` command on `PATH`; if that command is unavailable, set `FRAMEYARD_CLI` to an installed CLI path.
 
+When you work inside the Frameyard repository itself, `npx frameyard` resolves the published package, not your working tree. Run the built CLI (`node dist/cli.js`, after `pnpm build`) or `skills/frameyard/scripts/frameyard.mjs`, which prefers the repository build. The repository `AGENTS.md` is the authority for development commands.
+
 ## Contents
 
 - `SKILL.md`: trigger description and operating workflow