frameyard 0.4.0 → 0.5.0

package/examples/video/props/video.json

@@ -0,0 +1,8 @@
+{
+  "kicker": "Frameyard / Clip Study 001",
+  "title": "Moving",
+  "titleAccent": "Image",
+  "subtitle": "A local clip, loaded once and seeked twice from the composition clock.",
+  "detail": "Detail / second pass",
+  "accent": "#ffc37a"
+}

package/examples/video/scripts/make-clip.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+#
+# Regenerate examples/video/assets/clip.webm and clip.mp4.
+#
+# The visual is a procedural gradient field warped by two sinusoidal
+# displacement maps. The audio is an additive sine pad with pink-noise air.
+# Fixed seeds keep the generated grain stable across runs on the same FFmpeg.
+#
+# Requires FFmpeg with libvpx-vp9, libx264, Opus, and AAC support.
+#
+# Usage:
+#   examples/video/scripts/make-clip.sh
+#   examples/video/scripts/make-clip.sh --out-dir /tmp/frameyard-clip
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: make-clip.sh [--out-dir <directory>]
+
+Writes clip.webm (VP9 + Opus) and clip.mp4 (H.264 + AAC) to
+examples/video/assets by default.
+EOF
+}
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+out_dir="$(cd -- "$script_dir/.." && pwd)/assets"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --out-dir)
+      if [ "$#" -lt 2 ]; then
+        echo "make-clip: --out-dir requires a directory." >&2
+        usage >&2
+        exit 2
+      fi
+      out_dir="$2"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "make-clip: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+for tool in ffmpeg ffprobe; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "make-clip: $tool is required on PATH." >&2
+    exit 1
+  fi
+done
+
+mkdir -p "$out_dir"
+out_dir="$(cd -- "$out_dir" && pwd)"
+work_dir="$(mktemp -d "$out_dir/.make-clip.XXXXXX")"
+trap 'rm -rf "$work_dir"' EXIT
+
+# 12 seconds of a slow circular gradient, warped by two radial sine/cosine
+# displacement maps. Scaling up and cropping hides the displacement edges.
+ffmpeg -hide_banner -loglevel error -y \
+  -f lavfi -i "gradients=s=1280x720:r=30:d=12:c0=0x071827:c1=0x0d3a3a:c2=0x2f8a7e:c3=0xffd7a0:c4=0x123a58:c5=0x8fe6c8:n=6:type=circular:speed=0.02:seed=9" \
+  -f lavfi -i "nullsrc=s=1280x720:r=30:d=12,geq=lum='128+72*sin(hypot(X-640,Y-360)/42-T*0.55)':cb=128:cr=128" \
+  -f lavfi -i "nullsrc=s=1280x720:r=30:d=12,geq=lum='128+68*cos(hypot(X-640,Y-360)/55+T*0.47)':cb=128:cr=128" \
+  -filter_complex "[0:v][1:v][2:v]displace=edge=smear,scale=1440:810,crop=1280:720,gblur=sigma=6,eq=contrast=1.26:brightness=0.015:saturation=1.06,noise=alls=4:allf=t+u:all_seed=7,vignette=PI/3.6,format=yuv420p[v]" \
+  -map "[v]" -t 12 -an \
+  -c:v libvpx-vp9 -crf 31 -b:v 0 -row-mt 1 -tile-columns 2 -cpu-used 2 -g 60 \
+  "$work_dir/clip-video.webm"
+
+# A slow A-minor-ish pad with movement from chorus/echo and a filtered
+# pink-noise bed. The clip fades in and out so the timeline edit is soft.
+ffmpeg -hide_banner -loglevel error -y \
+  -f lavfi -i "aevalsrc=exprs='0.24*sin(2*PI*110*t)+0.12*sin(2*PI*164.81*t)+0.10*sin(2*PI*220*t)*(0.8+0.2*sin(2*PI*0.07*t))+0.06*sin(2*PI*261.63*t)+0.04*sin(2*PI*329.63*t)+0.018*sin(2*PI*440*t)':s=48000:d=12" \
+  -f lavfi -i "anoisesrc=color=pink:sample_rate=48000:duration=12:amplitude=0.08:seed=7" \
+  -filter_complex "[0:a]chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.3:2|1.3,aecho=0.8:0.6:280|520:0.25|0.16,lowpass=f=4200,volume=0.9[pad];[1:a]lowpass=f=700,volume=0.075[air];[pad][air]amix=inputs=2:duration=longest:normalize=0,afade=t=in:st=0:d=2,afade=t=out:st=9.4:d=2.6,alimiter=limit=0.9,pan=stereo|c0=c0|c1=c0[a]" \
+  -map "[a]" -t 12 -c:a libopus -b:a 96k \
+  "$work_dir/clip-audio.webm"
+
+ffmpeg -hide_banner -loglevel error -y \
+  -i "$work_dir/clip-video.webm" \
+  -i "$work_dir/clip-audio.webm" \
+  -map 0:v:0 -map 1:a:0 -c copy \
+  "$work_dir/clip.webm"
+
+# The MP4 variant is a transcode of the WebM source with the same timeline.
+ffmpeg -hide_banner -loglevel error -y \
+  -i "$work_dir/clip.webm" \
+  -c:v libx264 -preset medium -crf 20 -pix_fmt yuv420p -g 60 \
+  -c:a aac -b:a 128k -movflags +faststart \
+  "$work_dir/clip.mp4"
+
+for file in "$work_dir/clip.webm" "$work_dir/clip.mp4"; do
+  ffprobe -v error -select_streams v:0 \
+    -show_entries stream=codec_name,width,height,r_frame_rate \
+    -of default=noprint_wrappers=1 "$file" >/dev/null
+  ffprobe -v error -select_streams a:0 -show_entries stream=codec_name \
+    -of default=noprint_wrappers=1 "$file" >/dev/null
+done
+
+mv -f "$work_dir/clip.webm" "$out_dir/clip.webm"
+mv -f "$work_dir/clip.mp4" "$out_dir/clip.mp4"
+
+echo "Wrote $out_dir/clip.webm (VP9 + Opus)"
+echo "Wrote $out_dir/clip.mp4 (H.264 + AAC)"

package/examples/video/video.config.js

@@ -0,0 +1,6 @@
+export default {
+  compositions: {
+    video: "./compositions/video.html",
+    "video-mp4": "./compositions/video-mp4.html",
+  },
+};

package/examples/webgl/README.md

@@ -0,0 +1,30 @@
+# Frameyard WebGL example
+
+A 12-second, 1920×1080 composition that renders a procedural light field with a
+WebGL fragment shader and layers HTML/CSS typography over it:
+
+- a WebGL 1 fullscreen triangle with one cached program and cached uniforms
+- shader motion derived only from the composition frame
+- props for the kicker, title, subtitle, and accent color
+- frame-scheduled CSS typography and a frame-state progress bar
+- controller-updated frame and time readouts
+
+The composition lives in `compositions/webgl.html`; the external controller is
+`compositions/webgl.controller.js`. Draw every frame from `update()` and do not
+rely on the previous drawing buffer. Production sessions pin software WebGL so
+the captured pixels do not depend on the host GPU.
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check webgl --project examples/webgl
+node dist/cli.js still webgl --frame 210 --project examples/webgl --out webgl-still.png
+node dist/cli.js render webgl --project examples/webgl --props examples/webgl/props/webgl.json
+```
+
+Start the interactive preview with:
+
+```sh
+node dist/cli.js dev --project examples/webgl
+```

package/examples/webgl/compositions/webgl.controller.js

@@ -0,0 +1,200 @@
+const VERTEX_SHADER = `
+  attribute vec2 a_position;
+
+  void main() {
+    gl_Position = vec4(a_position, 0.0, 1.0);
+  }
+`;
+
+const FRAGMENT_SHADER = `
+  precision highp float;
+
+  uniform vec2 u_resolution;
+  uniform float u_frame;
+  uniform float u_duration;
+  uniform vec3 u_accent;
+
+  const float TAU = 6.28318530718;
+
+  float hash(vec2 p) {
+    return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+  }
+
+  void main() {
+    vec2 uv = gl_FragCoord.xy / u_resolution;
+    vec2 p = (gl_FragCoord.xy * 2.0 - u_resolution) / u_resolution.y;
+    float phase = (u_frame / max(u_duration, 1.0)) * TAU;
+
+    // A slow domain warp turns the contour field into a liquid surface.
+    vec2 q = p;
+    q.x += 0.045 * sin(p.y * 3.4 - phase * 0.8);
+    q.y += 0.10 * sin(p.x * 2.2 + phase * 0.55) + 0.035 * sin(p.x * 5.7 - phase * 0.9);
+
+    float terrain = q.y + 0.07 * sin(q.x * 3.6 + phase * 0.7) + 0.025 * sin(q.x * 8.4 - phase * 1.1);
+    float contour = abs(fract(terrain * 14.0 + phase * 0.5) - 0.5);
+    float line = smoothstep(0.455, 0.5, contour);
+    float glow = smoothstep(0.26, 0.5, contour);
+
+    vec3 ink = mix(vec3(0.016, 0.026, 0.038), vec3(0.035, 0.078, 0.085), uv.y);
+    vec3 color = ink;
+
+    float right = smoothstep(0.14, 0.66, uv.x);
+    color += u_accent * line * (0.10 + 0.38 * right);
+    color += u_accent * glow * 0.045 * right;
+
+    // A soft moving light and one thin orbit ring anchor the right side.
+    vec2 light = vec2(0.34 + 0.05 * cos(phase * 0.6), 0.06 + 0.04 * sin(phase * 0.45));
+    float radius = length(p - light);
+    float halo = 0.035 / (radius + 0.035);
+    vec3 white = mix(u_accent, vec3(0.92, 1.0, 0.98), 0.7);
+    color += white * halo * 0.42;
+
+    float ring = 1.0 - smoothstep(0.0, 0.007, abs(radius - 0.27 - 0.012 * sin(phase * 1.4)));
+    color += white * ring * 0.22;
+
+    // Static grain keeps the gradient from banding without adding temporal noise.
+    color += (hash(gl_FragCoord.xy) - 0.5) * 0.02;
+    float vignette = 1.0 - smoothstep(0.62, 1.28, length(p * vec2(0.86, 1.0)));
+    color *= 0.58 + 0.42 * vignette;
+
+    gl_FragColor = vec4(color, 1.0);
+  }
+`;
+
+let gl;
+let program;
+let buffer;
+let uniforms;
+let labels;
+let durationFrames = 360;
+let fps = 30;
+
+function compileShader(type, source) {
+  const shader = gl.createShader(type);
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (gl.getShaderParameter(shader, gl.COMPILE_STATUS) !== true) {
+    const log = gl.getShaderInfoLog(shader);
+    gl.deleteShader(shader);
+    throw new Error(log ?? "Could not compile the WebGL shader.");
+  }
+  return shader;
+}
+
+function linkProgram() {
+  const vertex = compileShader(gl.VERTEX_SHADER, VERTEX_SHADER);
+  const fragment = compileShader(gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
+  const next = gl.createProgram();
+  gl.attachShader(next, vertex);
+  gl.attachShader(next, fragment);
+  gl.linkProgram(next);
+  gl.detachShader(next, vertex);
+  gl.detachShader(next, fragment);
+  gl.deleteShader(vertex);
+  gl.deleteShader(fragment);
+  if (gl.getProgramParameter(next, gl.LINK_STATUS) !== true) {
+    const log = gl.getProgramInfoLog(next);
+    gl.deleteProgram(next);
+    throw new Error(log ?? "Could not link the WebGL program.");
+  }
+  return next;
+}
+
+function hexToRgb(value) {
+  const match = /^#([0-9a-f]{6})$/i.exec(typeof value === "string" ? value : "");
+  if (!match) {
+    return [0.47, 0.94, 0.78];
+  }
+  const number = Number.parseInt(match[1], 16);
+  return [((number >> 16) & 0xff) / 255, ((number >> 8) & 0xff) / 255, (number & 0xff) / 255];
+}
+
+export default {
+  validateProps(props) {
+    const errors = [];
+    for (const key of ["kicker", "title", "subtitle"]) {
+      if (typeof props[key] !== "string") {
+        errors.push(key + " must be a string");
+      }
+    }
+    if (typeof props.accent !== "string" || !/^#[0-9a-f]{6}$/i.test(props.accent)) {
+      errors.push("accent must be a #rrggbb color");
+    }
+    return errors;
+  },
+
+  mount({ root, props }) {
+    const canvas = root.querySelector("#field");
+    fps = Number(root.getAttribute("fps") ?? 30);
+    durationFrames = Number(root.getAttribute("duration-in-frames") ?? 360);
+
+    gl = canvas.getContext("webgl", {
+      alpha: false,
+      antialias: false,
+      depth: false,
+      stencil: false,
+      preserveDrawingBuffer: true,
+    });
+    if (!gl) {
+      throw new Error("WebGL is unavailable. The production renderer pins SwiftShader.");
+    }
+
+    program = linkProgram();
+    gl.useProgram(program);
+
+    buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    const position = gl.getAttribLocation(program, "a_position");
+    gl.enableVertexAttribArray(position);
+    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+
+    uniforms = {
+      frame: gl.getUniformLocation(program, "u_frame"),
+      resolution: gl.getUniformLocation(program, "u_resolution"),
+      duration: gl.getUniformLocation(program, "u_duration"),
+      accent: gl.getUniformLocation(program, "u_accent"),
+    };
+
+    const accent = hexToRgb(props.accent);
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    gl.uniform2f(uniforms.resolution, canvas.width, canvas.height);
+    gl.uniform1f(uniforms.duration, durationFrames);
+    gl.uniform3f(uniforms.accent, accent[0], accent[1], accent[2]);
+    gl.clearColor(0.016, 0.026, 0.038, 1);
+
+    labels = {
+      frame: root.querySelector("#frame"),
+      total: root.querySelector("#total"),
+      clock: root.querySelector("#clock"),
+    };
+    labels.total.textContent = String(durationFrames - 1).padStart(3, "0");
+  },
+
+  update({ frame }) {
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.uniform1f(uniforms.frame, frame);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    labels.frame.textContent = String(frame).padStart(3, "0");
+    labels.clock.textContent = (frame / fps).toFixed(2) + " S";
+  },
+
+  dispose() {
+    if (gl) {
+      if (buffer) {
+        gl.deleteBuffer(buffer);
+      }
+      if (program) {
+        gl.deleteProgram(program);
+      }
+    }
+    gl = undefined;
+    program = undefined;
+    buffer = undefined;
+    uniforms = undefined;
+    labels = undefined;
+    durationFrames = 360;
+    fps = 30;
+  },
+};

package/examples/webgl/compositions/webgl.html

@@ -0,0 +1,215 @@
+<!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>
+      </div>
+    </fy-composition>
+
+    <script type="text/fy-controller" src="./webgl.controller.js"></script>
+  </body>
+</html>

package/examples/webgl/props/webgl.json

@@ -0,0 +1,6 @@
+{
+  "kicker": "Shader Study / 001",
+  "title": "Liquid Light",
+  "subtitle": "A frame-driven WebGL field, resolved in software so every captured pixel stays reproducible.",
+  "accent": "#78f0c8"
+}

package/examples/webgl/video.config.js

@@ -0,0 +1,5 @@
+export default {
+  compositions: {
+    webgl: "./compositions/webgl.html",
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",
@@ -66,11 +66,13 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json",
+    "typecheck:browser": "tsc -p tsconfig.browser.json",
     "check:scripts": "node scripts/check-scripts.mjs",
     "lint": "oxlint",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm typecheck:test",
+    "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",
     "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",

package/skills/frameyard/SKILL.md

@@ -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.4.0
+frameyard-api-version: 0.5.0
 ---
 
 # Frameyard
@@ -22,7 +22,7 @@ Use Frameyard's public project format and CLI. Do not introduce an agent-only ru
 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`.
+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.
 
 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.
@@ -32,6 +32,7 @@ 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 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 `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.

package/skills/frameyard/references/json-results.md

@@ -118,7 +118,7 @@ Static validation diagnostics include source locations. Runtime diagnostics may
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "inline" },
-  "path": "/absolute/path/hello.mp4",
+  "path": "/absolute/path/out/hello.mp4",
   "width": 1920,
   "height": 1080,
   "fps": 30,
@@ -134,7 +134,7 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 }
 ```
 
-A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published. `concurrency` is the number of browser sessions actually used; it is capped by `durationInFrames` and by the CLI maximum of 16.
+A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published. Without `--out`, the final path is `out/<composition-id>.mp4` inside the project root. `concurrency` is the number of browser sessions actually used; it is capped by `durationInFrames` and by the CLI maximum of 16.
 
 ## tts