npm - frameyard - Versions diffs - 0.7.0 → 0.8.0 - Mend

frameyard 0.7.0 → 0.8.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 (138) hide show

package/CHANGELOG.md +61 -0
package/GLOSSARY.md +40 -16
package/README.md +54 -48
package/dist/cli.js +23 -16
package/dist/cli.js.map +1 -1
package/dist/composition/descriptor.d.ts +17 -3
package/dist/composition/descriptor.d.ts.map +1 -1
package/dist/composition/descriptor.js +51 -28
package/dist/composition/descriptor.js.map +1 -1
package/dist/composition/format.d.ts +12 -0
package/dist/composition/format.d.ts.map +1 -0
package/dist/composition/format.js +28 -0
package/dist/composition/format.js.map +1 -0
package/dist/composition/index.d.ts +2 -1
package/dist/composition/index.d.ts.map +1 -1
package/dist/composition/index.js +1 -0
package/dist/composition/index.js.map +1 -1
package/dist/contracts.d.ts +55 -6
package/dist/contracts.d.ts.map +1 -1
package/dist/contracts.js +3 -0
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/html/document-adapter.d.ts +3 -3
package/dist/html/document-adapter.d.ts.map +1 -1
package/dist/html/document-adapter.js +1 -1
package/dist/html/document-adapter.js.map +1 -1
package/dist/html/index.d.ts +1 -1
package/dist/html/index.d.ts.map +1 -1
package/dist/html/parse.d.ts +10 -2
package/dist/html/parse.d.ts.map +1 -1
package/dist/html/parse.js +14 -5
package/dist/html/parse.js.map +1 -1
package/dist/html/validate.d.ts +12 -1
package/dist/html/validate.d.ts.map +1 -1
package/dist/html/validate.js +233 -61
package/dist/html/validate.js.map +1 -1
package/dist/index.d.ts +4 -4
package/dist/index.d.ts.map +1 -1
package/dist/index.js +2 -2
package/dist/index.js.map +1 -1
package/dist/preview/main.d.ts +2 -2
package/dist/preview/main.d.ts.map +1 -1
package/dist/preview/main.js +35 -14
package/dist/preview/main.js.map +1 -1
package/dist/preview/timeline-data.d.ts +5 -1
package/dist/preview/timeline-data.d.ts.map +1 -1
package/dist/preview/timeline-host.d.ts.map +1 -1
package/dist/preview/timeline-host.js +10 -0
package/dist/preview/timeline-host.js.map +1 -1
package/dist/preview/timeline-main.js +3 -2
package/dist/preview/timeline-main.js.map +1 -1
package/dist/project.d.ts +3 -5
package/dist/project.d.ts.map +1 -1
package/dist/project.js.map +1 -1
package/dist/renderer/browser.d.ts +2 -2
package/dist/renderer/browser.d.ts.map +1 -1
package/dist/renderer/browser.js +10 -4
package/dist/renderer/browser.js.map +1 -1
package/dist/renderer/ffmpeg.d.ts +3 -0
package/dist/renderer/ffmpeg.d.ts.map +1 -1
package/dist/renderer/ffmpeg.js +122 -56
package/dist/renderer/ffmpeg.js.map +1 -1
package/dist/renderer/index.d.ts +40 -4
package/dist/renderer/index.d.ts.map +1 -1
package/dist/renderer/index.js +99 -24
package/dist/renderer/index.js.map +1 -1
package/dist/renderer/timeline.d.ts.map +1 -1
package/dist/renderer/timeline.js +89 -0
package/dist/renderer/timeline.js.map +1 -1
package/dist/runtime/host.d.ts.map +1 -1
package/dist/runtime/host.js +155 -31
package/dist/runtime/host.js.map +1 -1
package/dist/scaffold.d.ts.map +1 -1
package/dist/scaffold.js +104 -101
package/dist/scaffold.js.map +1 -1
package/dist/server/composition-html.d.ts +13 -7
package/dist/server/composition-html.d.ts.map +1 -1
package/dist/server/composition-html.js +65 -16
package/dist/server/composition-html.js.map +1 -1
package/dist/server/server.d.ts.map +1 -1
package/dist/server/server.js +26 -6
package/dist/server/server.js.map +1 -1
package/dist/server/timeline-preview-data.d.ts.map +1 -1
package/dist/server/timeline-preview-data.js +11 -0
package/dist/server/timeline-preview-data.js.map +1 -1
package/dist/server/timeline-preview-html.d.ts.map +1 -1
package/dist/server/timeline-preview-html.js +2 -1
package/dist/server/timeline-preview-html.js.map +1 -1
package/dist/timeline/resolve.d.ts +4 -3
package/dist/timeline/resolve.d.ts.map +1 -1
package/dist/timeline/resolve.js +14 -4
package/dist/timeline/resolve.js.map +1 -1
package/dist/timeline/schema.d.ts +7 -0
package/dist/timeline/schema.d.ts.map +1 -1
package/dist/timeline/schema.js +50 -0
package/dist/timeline/schema.js.map +1 -1
package/dist/version.d.ts +1 -1
package/dist/version.js +1 -1
package/docs/adr/0007-make-html-documents-the-composition-unit.md +1 -1
package/docs/adr/0008-share-the-composition-document-grammar.md +1 -1
package/docs/adr/0011-compose-timeline-frames-in-a-live-browser-host.md +1 -1
package/docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md +1 -1
package/docs/adr/0014-compose-timeline-clips-with-css-blend-modes.md +37 -0
package/docs/adr/0015-inherit-composition-format-from-the-project.md +28 -0
package/docs/adr/0016-author-compositions-as-html-fragments.md +32 -0
package/docs/adr/0017-render-timeless-compositions-as-stills.md +99 -0
package/docs/migration-0.4.md +3 -1
package/docs/migration-0.8.md +163 -0
package/docs/preview-testing.md +7 -0
package/docs/v0.1-design.md +42 -34
package/examples/blend/README.md +106 -0
package/examples/blend/assets/ink.mp4 +0 -0
package/examples/blend/compositions/aurora.html +55 -0
package/examples/blend/compositions/backdrop.html +74 -0
package/examples/blend/compositions/labels.html +149 -0
package/examples/blend/scripts/make-ink.sh +26 -0
package/examples/blend/timelines/blend.timeline.json +155 -0
package/examples/blend/video.config.js +11 -0
package/examples/demo/compositions/demo.html +243 -251
package/examples/static/README.md +17 -0
package/examples/static/compositions/still.html +37 -0
package/examples/static/timelines/still.timeline.json +13 -0
package/examples/static/video.config.js +9 -0
package/examples/video/compositions/video-mp4.html +349 -357
package/examples/video/compositions/video-overlay.html +337 -345
package/examples/video/compositions/video.html +349 -357
package/examples/webgl/compositions/webgl.html +205 -213
package/package.json +2 -1
package/skills/frameyard/SKILL.md +15 -13
package/skills/frameyard/references/common-mistakes.md +29 -6
package/skills/frameyard/references/controllers.md +5 -4
package/skills/frameyard/references/deterministic-authoring.md +41 -36
package/skills/frameyard/references/diagnostics.md +11 -3
package/skills/frameyard/references/failure-recovery.md +25 -5
package/skills/frameyard/references/json-results.md +46 -4
package/skills/frameyard/references/timelines.md +16 -12

package/examples/webgl/compositions/webgl.html CHANGED Viewed

@@ -1,215 +1,207 @@
-<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <script type="application/json" data-fy="props">
-      {
-        "kicker": "Shader Study / 001",
-        "title": "Liquid Light",
-        "subtitle": "A frame-driven WebGL field, resolved in software so every captured pixel stays reproducible.",
-        "accent": "#78f0c8"
-      }
-    </script>
-    <style>
-      @keyframes rise {
-        from {
-          opacity: 0;
-          transform: translateY(44px);
-        }
-        to {
-          opacity: 1;
-          transform: translateY(0);
-        }
-      }
-      @keyframes fade {
-        from {
-          opacity: 0;
-        }
-        to {
-          opacity: 1;
-        }
-      }
-      @keyframes draw {
-        from {
-          opacity: 0;
-          transform: scaleX(0);
-        }
-        to {
-          opacity: 1;
-          transform: scaleX(1);
-        }
-      }
-      html,
-      body,
-      fy-composition {
-        background: #060a0e;
-      }
-      #scene {
-        position: relative;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-        background: #060a0e;
-        color: #edf6f3;
-        font-family: Inter, ui-sans-serif, system-ui, sans-serif;
-      }
-      #field {
-        position: absolute;
-        inset: 0;
-        display: block;
-        width: 100%;
-        height: 100%;
-      }
-      #scrim {
-        position: absolute;
-        inset: 0;
-        background: linear-gradient(
-          90deg,
-          rgba(4, 8, 11, 0.94) 0%,
-          rgba(4, 8, 11, 0.78) 34%,
-          rgba(4, 8, 11, 0.18) 66%,
-          rgba(4, 8, 11, 0) 100%
-        );
-      }
-      #vignette {
-        position: absolute;
-        inset: 0;
-        background: radial-gradient(ellipse at 60% 45%, transparent 34%, rgba(0, 0, 0, 0.46) 100%);
-        pointer-events: none;
-      }
-      #kicker {
-        position: absolute;
-        top: 72px;
-        left: 148px;
-        display: flex;
-        align-items: center;
-        gap: 16px;
-        font:
-          600 14px/1 ui-monospace,
-          monospace;
-        letter-spacing: 0.26em;
-        text-transform: uppercase;
-        color: var(--fy-prop-accent);
-        animation: fade 1s linear both;
-      }
-      #kicker::before {
-        content: "";
-        width: 8px;
-        height: 8px;
-        background: var(--fy-prop-accent);
-        box-shadow: 0 0 18px var(--fy-prop-accent);
-      }
-      #meta {
-        position: absolute;
-        top: 72px;
-        right: 148px;
-        text-align: right;
-        font:
-          500 13px/1.9 ui-monospace,
-          monospace;
-        letter-spacing: 0.12em;
-        color: #80908e;
-        animation: fade 1s linear both;
-      }
-      #meta strong {
-        color: #dce9e6;
-        font-weight: 500;
-      }
-      #title {
-        position: absolute;
-        top: 292px;
-        left: 148px;
-        width: 780px;
-        margin: 0;
-        font-size: 168px;
-        line-height: 0.88;
-        letter-spacing: -0.062em;
-        font-weight: 660;
-        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
-      }
-      #subtitle {
-        position: absolute;
-        top: 604px;
-        left: 152px;
-        width: 720px;
-        margin: 0;
-        font-size: 30px;
-        line-height: 1.45;
-        font-weight: 420;
-        color: #96a7a3;
-        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
-      }
-      #footer {
-        position: absolute;
-        left: 148px;
-        right: 148px;
-        bottom: 64px;
-        animation: fade 1s linear both;
-      }
-      #rule {
-        position: relative;
-        height: 1px;
-        background: rgba(237, 246, 243, 0.14);
-        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 16px var(--fy-prop-accent);
-      }
-      #footer-row {
-        display: flex;
-        justify-content: space-between;
-        align-items: baseline;
-        gap: 24px;
-        margin-top: 18px;
-        font:
-          500 13px/1 ui-monospace,
-          monospace;
-        letter-spacing: 0.14em;
-        color: #758581;
-        animation: fade 1s linear both;
-      }
-      #footer-row strong {
-        color: var(--fy-prop-accent);
-        font-weight: 600;
-      }
-      #footer-meta {
-        display: flex;
-        gap: 28px;
-      }
-    </style>
-  </head>
-  <body>
-    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="360">
-      <div id="scene">
-        <canvas id="field" width="1920" height="1080"></canvas>
-        <div id="scrim"></div>
-        <div id="vignette"></div>
-        <div id="kicker" data-fy-text="kicker" data-fy-anim-start="0" data-fy-anim-duration="28"></div>
-        <div id="meta" data-fy-anim-start="18" data-fy-anim-duration="34">
-          <div><strong>WEBGL 1.0</strong> / SWIFTSHADER</div>
-          <div>1920 × 1080 · 30 FPS</div>
-          <div>12.00 S · 360 FRAMES</div>
-        </div>
-        <h1 id="title" data-fy-text="title" data-fy-anim-start="6" data-fy-anim-duration="56"></h1>
-        <p id="subtitle" data-fy-text="subtitle" data-fy-anim-start="34" data-fy-anim-duration="52"></p>
-        <div id="footer" data-fy-anim-start="28" data-fy-anim-duration="30">
-          <div id="rule" data-fy-anim-start="38" data-fy-anim-duration="60">
-            <div id="progress"></div>
-          </div>
-          <div id="footer-row" data-fy-anim-start="44" data-fy-anim-duration="30">
-            <span>FRAME <strong id="frame">000</strong> / <span id="total">359</span></span>
-            <span id="clock">0.00 S</span>
-            <span id="footer-meta"><span>FRAME-SEEKED</span><span>NO RAF</span></span>
-          </div>
-        </div>
+<script type="application/json" data-fy="props">
+  {
+    "kicker": "Shader Study / 001",
+    "title": "Liquid Light",
+    "subtitle": "A frame-driven WebGL field, resolved in software so every captured pixel stays reproducible.",
+    "accent": "#78f0c8"
+  }
+</script>
+<style>
+  @keyframes rise {
+    from {
+      opacity: 0;
+      transform: translateY(44px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+  @keyframes fade {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+  @keyframes draw {
+    from {
+      opacity: 0;
+      transform: scaleX(0);
+    }
+    to {
+      opacity: 1;
+      transform: scaleX(1);
+    }
+  }
+  html,
+  body,
+  fy-composition {
+    background: #060a0e;
+  }
+  #scene {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: #060a0e;
+    color: #edf6f3;
+    font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  }
+  #field {
+    position: absolute;
+    inset: 0;
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+  #scrim {
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(
+      90deg,
+      rgba(4, 8, 11, 0.94) 0%,
+      rgba(4, 8, 11, 0.78) 34%,
+      rgba(4, 8, 11, 0.18) 66%,
+      rgba(4, 8, 11, 0) 100%
+    );
+  }
+  #vignette {
+    position: absolute;
+    inset: 0;
+    background: radial-gradient(ellipse at 60% 45%, transparent 34%, rgba(0, 0, 0, 0.46) 100%);
+    pointer-events: none;
+  }
+  #kicker {
+    position: absolute;
+    top: 72px;
+    left: 148px;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    font:
+      600 14px/1 ui-monospace,
+      monospace;
+    letter-spacing: 0.26em;
+    text-transform: uppercase;
+    color: var(--fy-prop-accent);
+    animation: fade 1s linear both;
+  }
+  #kicker::before {
+    content: "";
+    width: 8px;
+    height: 8px;
+    background: var(--fy-prop-accent);
+    box-shadow: 0 0 18px var(--fy-prop-accent);
+  }
+  #meta {
+    position: absolute;
+    top: 72px;
+    right: 148px;
+    text-align: right;
+    font:
+      500 13px/1.9 ui-monospace,
+      monospace;
+    letter-spacing: 0.12em;
+    color: #80908e;
+    animation: fade 1s linear both;
+  }
+  #meta strong {
+    color: #dce9e6;
+    font-weight: 500;
+  }
+  #title {
+    position: absolute;
+    top: 292px;
+    left: 148px;
+    width: 780px;
+    margin: 0;
+    font-size: 168px;
+    line-height: 0.88;
+    letter-spacing: -0.062em;
+    font-weight: 660;
+    animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+  }
+  #subtitle {
+    position: absolute;
+    top: 604px;
+    left: 152px;
+    width: 720px;
+    margin: 0;
+    font-size: 30px;
+    line-height: 1.45;
+    font-weight: 420;
+    color: #96a7a3;
+    animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+  }
+  #footer {
+    position: absolute;
+    left: 148px;
+    right: 148px;
+    bottom: 64px;
+    animation: fade 1s linear both;
+  }
+  #rule {
+    position: relative;
+    height: 1px;
+    background: rgba(237, 246, 243, 0.14);
+    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 16px var(--fy-prop-accent);
+  }
+  #footer-row {
+    display: flex;
+    justify-content: space-between;
+    align-items: baseline;
+    gap: 24px;
+    margin-top: 18px;
+    font:
+      500 13px/1 ui-monospace,
+      monospace;
+    letter-spacing: 0.14em;
+    color: #758581;
+    animation: fade 1s linear both;
+  }
+  #footer-row strong {
+    color: var(--fy-prop-accent);
+    font-weight: 600;
+  }
+  #footer-meta {
+    display: flex;
+    gap: 28px;
+  }
+</style>
+<fy-composition width="1920" height="1080" fps="30" duration-in-frames="360">
+  <div id="scene">
+    <canvas id="field" width="1920" height="1080"></canvas>
+    <div id="scrim"></div>
+    <div id="vignette"></div>
+    <div id="kicker" data-fy-text="kicker" data-fy-anim-start="0" data-fy-anim-duration="28"></div>
+    <div id="meta" data-fy-anim-start="18" data-fy-anim-duration="34">
+      <div><strong>WEBGL 1.0</strong> / SWIFTSHADER</div>
+      <div>1920 × 1080 · 30 FPS</div>
+      <div>12.00 S · 360 FRAMES</div>
+    </div>
+    <h1 id="title" data-fy-text="title" data-fy-anim-start="6" data-fy-anim-duration="56"></h1>
+    <p id="subtitle" data-fy-text="subtitle" data-fy-anim-start="34" data-fy-anim-duration="52"></p>
+    <div id="footer" data-fy-anim-start="28" data-fy-anim-duration="30">
+      <div id="rule" data-fy-anim-start="38" data-fy-anim-duration="60">
+        <div id="progress"></div>
       </div>
-    </fy-composition>
+      <div id="footer-row" data-fy-anim-start="44" data-fy-anim-duration="30">
+        <span>FRAME <strong id="frame">000</strong> / <span id="total">359</span></span>
+        <span id="clock">0.00 S</span>
+        <span id="footer-meta"><span>FRAME-SEEKED</span><span>NO RAF</span></span>
+      </div>
+    </div>
+  </div>
+</fy-composition>
-    <script type="text/fy-controller" src="./webgl.controller.js"></script>
-  </body>
-</html>
+<script type="text/fy-controller" src="./webgl.controller.js"></script>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",
@@ -79,6 +79,7 @@
     "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",
+    "bench:static": "pnpm build && node bench/static-composition.mjs",
     "set-version": "node scripts/set-version.mjs",
     "verify-release": "node scripts/verify-release.mjs",
     "retag-release": "node scripts/retag-release.mjs"

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 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.7.0
+frameyard-api-version: 0.8.0
 ---
 # Frameyard
@@ -11,19 +11,19 @@ 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 `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.
+2. Read the `format`, `compositions`, and `timelines` maps in `video.config.js`. Entries are explicit `.html` composition fragments and `.json` timeline documents; there is no directory scanning.
+3. Read the timeline JSON, the referenced composition fragment, 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 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).
+1. **Author compositions** as partial HTML fragments with one top-level `<fy-composition>` root. Put metadata, default props, markup, CSS animation, bindings, audio, and transcripts in the fragment. Do not add `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`; Frameyard generates the document shell. Use an optional controller for Canvas 2D, WebGL, karaoke, or per-frame computation CSS cannot express. Omit both `duration-in-frames` and `fps` only when the composition is intentionally static; a static composition is captured once, renders to PNG, and cannot use animation scheduling, media, or transcripts. 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 blend modes, 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).
+5. **Validate** with `npx frameyard check <id> --json`, where `<id>` is a timeline or composition. Static validation runs before Chromium; then every animated frame is evaluated, or a static composition's single state is inspected once. Read the structured `diagnostics` array and the result `kind`. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
 6. **Inspect** representative frames with `npx frameyard still <id> --frame <spec> --out <path> --json`, where `<spec>` is a frame number, an inclusive range like `2-12`, or a comma-separated list with at most 32 unique frames. With one frame, `--out` is a `.png` file; with multiple frames, it is a directory and the files are `still-<id>-<frame>.png`. 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>] [--props <file>] --json`. Composition renders accept `--concurrency <n>`; timeline renders accept `--workers <n>` and `--scratch <dir>`. `--container <mp4|mov|mkv|webm>` and `--codec <h264|hevc|vp9>` select the delivery pair (MP4/H.264 by default, WebM defaults to VP9), and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded, defaulting to `auto`. The output extension must match the container. The default output is `out/<id>.<ext>` in the project root.
+7. **Render** with `npx frameyard render <id> [--out <file>] [--props <file>] --json`. Animated composition renders accept `--concurrency <n>`; timeline renders accept `--workers <n>` and `--scratch <dir>`. `--container <mp4|mov|mkv|webm>` and `--codec <h264|hevc|vp9>` select the delivery pair (MP4/H.264 by default, WebM defaults to VP9), and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded, defaulting to `auto`. The output extension must match the container. The default output is `out/<id>.<ext>` for video and `out/<id>.png` for a static composition. A static composition render rejects `--container`, `--codec`, `--encoder`, and `--concurrency`; use a timeline when the deliverable must be video.
 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,9 +33,9 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 - Use `--json` for every non-interactive command. Parse stdout as the structured result; treat stderr as progress and diagnostics.
 - 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 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.
-- `still --frame <spec>` accepts `n`, `n-m`, or a comma-separated list; ranges are inclusive, duplicates are removed preserving the first occurrence, order is preserved, and one call captures at most 32 unique frames. Do not use `still` as an image-sequence exporter. With multiple frames, `--out` is a directory and files are named `still-<id>-<frame>.png`; with one frame, `--out` is a `.png` file.
+- `render` writes to `out/<id>.mp4` in the project root for timelines and animated compositions, and to `out/<id>.png` for static compositions, unless `--out` is passed. Explicit `--out` paths are relative to the current working directory.
+- Use `--concurrency <n>` only for animated 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.
+- `still --frame <spec>` accepts `n`, `n-m`, or a comma-separated list; ranges are inclusive, duplicates are removed preserving the first occurrence, order is preserved, and one call captures at most 32 unique frames. A static composition exposes only frame 0. Do not use `still` as an image-sequence exporter. With multiple frames, `--out` is a directory and files are named `still-<id>-<frame>.png`; with one frame, `--out` is a `.png` file.
 - `--encoder` selects the encoder: `auto` (default) probes NVENC, then Quick Sync, then the codec's software encoder; `software` forces `libx264`, `libx265`, or `libvpx-vp9`; `nvenc` and `qsv` force a vendor. `--codec <h264|hevc|vp9>` and `--container <mp4|mov|mkv|webm>` select the delivery pair: MP4 and MOV hold H.264/HEVC with AAC, MKV holds H.264/HEVC/VP9, and WebM holds VP9 with Opus and defaults to VP9. `--out` must use the container's extension. The probe is a real one-frame encode. Encoders, codecs, and containers change encoded bytes and file size, not captured frames; do not switch them to fix a visual difference. With `nvenc`, timeline `--workers` is capped at eight, the consumer driver session limit, and a larger value reports an `ENCODER_WARNING`. HEVC MP4/MOV files use the `hvc1` tag and do not play in browsers without platform HEVC decoding.
 - 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.
@@ -43,15 +43,17 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 ## 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 composition is a partial HTML fragment with one top-level `<fy-composition>` root and a top-level `data-fy="props"` default-props block. Props, the controller, and import maps are top-level siblings of the root; top-level `<style>` and `<link rel="stylesheet">` elements are hoisted into the generated head. Do not use the reserved `data-fy-host` attribute or `data-fy="format"` block. `width`, `height`, and `fps` are optional and inherit from the project `format`; declare them to override it.
+- A composition with neither `duration-in-frames` nor `fps` is static. It is captured once and renders to PNG. It may use `<img>`, CSS, SVG, and canvas, but not `data-fy-anim-*`, `<video>`, `<audio>`, or `<fy-transcript>`. Its controller runs `mount()` and `validateProps()`; `update()` is not called and frame-state variables are not set. CSS animations are paused at time 0. Declaring `fps` without `duration-in-frames` is an error. A static composition clip in a timeline needs an explicit `duration` and `sourceIn: 0`.
 - 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`.
 - A composition has exactly one optional controller, inline or external. It may export `mount`, `update`, `dispose`, and `validateProps`; at least one is required. Use inline for small controllers; extract to an external module for Canvas 2D, WebGL, karaoke, reuse, tests, or a large controller.
 - The controller is the only executable code. Other executable scripts and `on*` handlers are rejected.
-- Media and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition document.
+- Media and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition URL.
 - Embedded video/audio use `data-fy-start` (frames), `data-fy-trim` (seconds), optional `data-fy-duration` (seconds), and `data-fy-volume` (0-1). Transcripts use `<fy-transcript src words>`.
+- An optional top-level `<script type="importmap">` may add bare specifiers for controllers. Frameyard hoists it before the host module; `frameyard` and `frameyard/` specifiers are reserved.
 ## Determinism guardrails
@@ -66,7 +68,7 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 ## Diagnostics rule
-`check`, `still`, and `render` run static composition validation before Chromium. Errors fail before a browser starts; warnings allow frame evaluation. Every diagnostic has a stable `code`, a `message`, and optional `details` with source locations and suggestions. Treat warnings as actionable. Do not ignore `BINDING_PATH_MISSING`, `ANIMATION_NOT_FOUND`, `ANIMATION_MULTIPLE`, or `DETERMINISM_WARNING`.
+`check`, `still`, and `render` run static composition validation before Chromium. Errors fail before a browser starts; warnings allow frame evaluation. Every diagnostic has a stable `code`, a `message`, and optional `details` with source locations and suggestions. Treat warnings as actionable. Do not ignore `BINDING_PATH_MISSING`, `ANIMATION_NOT_FOUND`, `ANIMATION_MULTIPLE`, `STATIC_UPDATE_IGNORED`, `STATIC_ANIMATION_PAUSED`, or `DETERMINISM_WARNING`. `STATIC_ANIMATION_UNSUPPORTED` and `STATIC_MEDIA_UNSUPPORTED` mean the composition should be animated with `duration-in-frames`/`fps` or the media should move to a timeline.
 ## Subtitle and karaoke rule

package/skills/frameyard/references/common-mistakes.md CHANGED Viewed

@@ -2,14 +2,19 @@
 ## Using the old authoring model
-- **JavaScript composition modules / `defineComposition`** were removed in 0.4. A composition is a `.html` document listed in `video.config.js`.
+- **JavaScript composition modules / `defineComposition`** were removed in 0.4. A composition is a `.html` fragment listed in `video.config.js`.
 - **`data-frameyard-*`** media attributes were removed in 0.4. Use `data-fy-*`.
 ## Document structure
-- Missing `<!doctype html>` or missing/multiple `<fy-composition>` roots.
-- Missing `width`, `height`, `fps`, or `duration-in-frames` on the root.
-- Missing the `data-fy="props"` block when the composition relies on default props.
+- Adding `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`; compositions are fragments and the framework owns the shell (`COMPOSITION_DOCUMENT_SHELL`).
+- Missing/multiple `<fy-composition>` roots, a root nested inside another element, or missing `duration-in-frames` on an animated composition. `width`, `height`, and `fps` may be omitted when the project declares `format`, but declaring only one of `width` and `height` is an error.
+- Forgetting both `duration-in-frames` and `fps` on a composition that should animate; that composition is now static and renders to PNG. Declaring `fps` without `duration-in-frames` is an error.
+- Rendering a composition that declares no dimensions in a project without `format`; add `width`/`height` or the project `format` (`COMPOSITION_FORMAT_UNRESOLVED`).
+- Missing the top-level `data-fy="props"` block when the composition relies on default props; a nested props block is rejected.
+- Putting props, the controller, or an import map inside `<fy-composition>` instead of at the top level.
+- Using the reserved `data-fy-host` attribute or `data-fy="format"` block.
+- Declaring an import map with `frameyard` or `frameyard/` specifiers; those are reserved (`IMPORT_MAP_INVALID`).
 - Visual content outside `<fy-composition>`; it is not captured.
 - Using `<base>`, refresh/CSP meta tags, `<iframe>`, `<object>`, or `<embed>`.
@@ -46,10 +51,28 @@
 - Using remote, live, or unseekable media sources.
 - Using `<source>` or `<track>` children; use a local `src` and `<fy-transcript>`.
-- Adding or changing media in `update()`; prepare it in the document or in `mount()`.
+- Adding or changing media in `update()`; prepare it in the fragment or in `mount()`.
 - Calling `play()`, `pause()`, or setting `currentTime` on a video.
 - Assuming media/transcript `src` is document-relative. It is project-root-relative.
-- Assuming the controller `src` is project-root-relative. It is document-relative.
+- Assuming the controller `src` is project-root-relative. It is relative to the composition URL.
+## Timelines
+- Putting `blend` on an audio clip. It is only valid on visual clips.
+- Using `hue`, `saturation`, `color`, or `luminosity`. They need cross-channel math and are rejected; use one of the separable CSS modes.
+- Expecting a blend on a transparent nested timeline to see the parent's layers. A nested timeline is its own document and blends only against its own backdrop.
+- Expecting a blend on a composition with an opaque background to reach lower tracks. The composition's alpha is opaque; leave its background transparent.
+- Expecting preview and final render blend pixels to match exactly. CSS is the reference and FFmpeg approximates it; the guarantee is at clip capture.
+- Omitting `duration` on a static composition clip, or setting `sourceIn` above 0. A static source has no intrinsic duration or frames.
+- Expecting a static composition clip to contribute audio or transcripts. It is visual-only.
+## Static compositions
+- Expecting `update()` or `--fy-*` frame-state variables to run. A static composition only runs `mount()` and prop validation; use CSS, markup, or mount-time canvas drawing.
+- Adding `data-fy-anim-*`, `<video>`, `<audio>`, or `<fy-transcript>` to a static composition. These are `STATIC_ANIMATION_UNSUPPORTED` or `STATIC_MEDIA_UNSUPPORTED`.
+- Relying on CSS animations or transitions at capture time; they are paused at 0 with `STATIC_ANIMATION_PAUSED`.
+- Passing `--container`, `--codec`, `--encoder`, or `--concurrency` to `render` for a static composition. Use a timeline image clip if the deliverable must be video.
+- Requesting a still frame other than 0 from a static composition.
 ## Validation

package/skills/frameyard/references/controllers.md CHANGED Viewed

@@ -36,17 +36,18 @@ export default {
 };
 ```
-Exactly one controller is allowed. Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
+Exactly one controller is allowed, and it must be a top-level sibling of `<fy-composition>` in the fragment. Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
 ## Lifecycle
 - `mount({ root, props })` runs once per load and may be asynchronous. Use it to query the root, create canvases, and start loading local data.
 - `update({ frame, props, root })` runs on every seek. It must be synchronous and seek-safe: derive the frame from `frame` and `props` only.
-- `dispose()` releases resources and resets module-scope state. The host calls it before remounting or disposing the document.
+- `dispose()` releases resources and resets module-scope state. The host calls it before remounting or disposing the composition host.
+- A static composition runs `mount()` and `validateProps()` only. `update()` is not called and frame-state variables are not set; the host reports `STATIC_UPDATE_IGNORED`. Do not create media in a static controller: the host rejects it with `STATIC_MEDIA_UNSUPPORTED`. Draw canvas/WebGL content once from `mount()`.
 - `validateProps(props)` is optional and synchronous. Return an array of human-readable errors, or `void`.
 - A validation-only controller may export just `validateProps`.
-Keep mutable state in module scope, never on `this`. The controller module is imported once per document; `load` remounts it without re-importing, so `dispose` must reset module state.
+Keep mutable state in module scope, never on `this`. The controller module is imported once per page; `load` remounts it without re-importing, so `dispose` must reset module state.
 ## Props validation
@@ -105,7 +106,7 @@ Never use `Math.random()`, `Date.now()`, `performance.now()`, timers, independen
 Prefer declarative `<video>`/`<audio>` elements with `data-fy-*` attributes. The host pauses and seeks them; do not call `play()`, `pause()`, or set `currentTime` in `update()`. Media created by the controller is allowed in `mount`; media added or changed in `update` cannot be prepared without network access.
-Media and transcript `src` values resolve from the project root. The controller `src` resolves relative to the composition document.
+Media and transcript `src` values resolve from the project root. The controller `src` resolves relative to the composition URL.
 ## Karaoke