frameyard 0.8.0 → 0.9.0

package/scaffolds/init/README.md

@@ -0,0 +1,56 @@
+# My Frameyard project
+
+Coding agents should read `AGENTS.md` for the project rules and the lint, check, still, and render workflow.
+
+The reusable composition is a partial HTML fragment at `compositions/hello.html`. The edit is `timelines/main.timeline.json`, which places that composition as a clip in the project format. The project format is fixed in `fy.config.js`.
+
+Start the preview:
+
+```sh
+npx frameyard dev
+```
+
+The preview lists the timeline next to the compositions. Open the timeline to scrub it and inspect the program monitor.
+
+Validate and render the timeline:
+
+```sh
+npx frameyard doctor
+npx frameyard check main
+npx frameyard render main --props props/main.json
+```
+
+`props/main.json` maps composition clip IDs to props overrides. The video is written to `out/main.mp4` in the project. Pass `--out <file.mp4>` to choose another path. Timelines with heavy composition work accept `--workers <n>` and `--scratch <dir>`.
+
+The composition can still be previewed and rendered on its own:
+
+```sh
+npx frameyard check hello
+npx frameyard render hello --props props/hello.json
+```
+
+Install a font when the design needs one:
+
+```sh
+npx frameyard font search "space grotesk" --subset latin --json
+npx frameyard font add space-grotesk --subset latin
+```
+
+Or vendor a local font:
+
+```sh
+npx frameyard font add --file ./fonts/SpaceGrotesk.woff2 \
+  --family "Space Grotesk" --license OFL-1.1 --license-file ./fonts/OFL.txt
+npx frameyard font verify
+```
+
+The server injects the font sheet into every composition; use the family name in CSS. Commit `fy.fonts.json`, `assets/fonts/`, and license files. See `AGENTS.md` for the policy limits.
+
+Or run the pinned scripts from `package.json`:
+
+```sh
+npm run dev
+npm run check -- main
+npm run render -- main --props props/main.json
+npm run still -- main --frame 42 --out main-42.png
+```

package/scaffolds/init/compositions/hello.html

@@ -0,0 +1,79 @@
+<script type="application/json" data-fy="props">
+  { "title": "Hello, Frameyard", "accent": "#b8f36b" }
+</script>
+<style>
+  @keyframes fade-up {
+    from {
+      opacity: 0;
+      transform: translateY(28px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+  @keyframes drift {
+    from {
+      transform: translate(-120px, -80px);
+    }
+    to {
+      transform: translate(120px, 80px);
+    }
+  }
+  #hello {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    display: grid;
+    place-items: center;
+    overflow: hidden;
+    background: #0b0d10;
+    color: #e8edf3;
+    font-family: Inter, system-ui, sans-serif;
+  }
+  #hello h1 {
+    position: relative;
+    margin: 0;
+    font-size: 96px;
+    letter-spacing: -0.04em;
+    opacity: 0;
+    animation: fade-up 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+  }
+  #hello p {
+    position: relative;
+    margin: 18px 0 0;
+    color: #8a97a6;
+    font-size: 26px;
+  }
+  #glow {
+    position: absolute;
+    left: 50%;
+    top: 50%;
+    width: 520px;
+    height: 520px;
+    margin: -260px 0 0 -260px;
+    border-radius: 50%;
+    background: var(--fy-prop-accent);
+    filter: blur(120px);
+    opacity: 0.16;
+    animation: drift 12s ease-in-out infinite alternate;
+  }
+  #sweep {
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    width: calc(var(--fy-progress) * 100%);
+    height: 4px;
+    background: var(--fy-prop-accent);
+  }
+</style>
+<fy-composition width="1280" height="720" fps="30" duration-in-frames="150">
+  <div id="hello">
+    <div id="glow"></div>
+    <div style="position: relative; text-align: center">
+      <h1 id="title" data-fy-text="title" data-fy-anim-start="0" data-fy-anim-duration="24"></h1>
+      <p>Deterministic video, authored on the web.</p>
+    </div>
+    <div id="sweep"></div>
+  </div>
+</fy-composition>

package/scaffolds/init/fy.config.js

@@ -0,0 +1,9 @@
+export default {
+  format: { width: 1280, height: 720, fps: 30 },
+  compositions: {
+    hello: "./compositions/hello.html",
+  },
+  timelines: {
+    main: "./timelines/main.timeline.json",
+  },
+};

package/scaffolds/init/gitignore.template

@@ -0,0 +1 @@
+out/

package/scaffolds/init/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npx --yes frameyard@{{VERSION}} dev",
+    "check": "npx --yes frameyard@{{VERSION}} check",
+    "render": "npx --yes frameyard@{{VERSION}} render",
+    "still": "npx --yes frameyard@{{VERSION}} still"
+  }
+}

package/scaffolds/init/props/hello.json

@@ -0,0 +1,4 @@
+{
+  "title": "Hello, Frameyard",
+  "accent": "#b8f36b"
+}

package/scaffolds/init/props/main.json

@@ -0,0 +1,6 @@
+{
+  "hello": {
+    "title": "Hello, Frameyard",
+    "accent": "#b8f36b"
+  }
+}

package/scaffolds/init/timelines/main.timeline.json

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

package/scaffolds/local-models/LOCAL-MODELS.md

@@ -0,0 +1,77 @@
+# Optional local-model scaffold
+
+Install these files into a workspace when a local model and Frameyard share the
+same machine. They are not active in this repository by default.
+
+```sh
+npx frameyard add local-models
+```
+
+For a new project, install the normal scaffold and the host setup together:
+
+```sh
+npx frameyard init my-project --local-models
+```
+
+Manual copy is still possible:
+
+```sh
+mkdir -p .opencode .pi
+cp -R scaffolds/local-models/opencode/. .opencode/
+cp -R scaffolds/local-models/pi/. .pi/
+cp scaffolds/local-models/fy.policy.json .
+```
+
+The CLI refuses to overwrite an existing file. If the target workspace already
+has an `.opencode/opencode.jsonc` or `.pi/` configuration, merge the scaffold
+instead of copying over it.
+
+## What each file does
+
+- `fy.policy.json`: the `authoring` tier and `shared-cpu` profile. It
+  blocks `tts`, `transcribe`, and `render`; allows `lint`, `context`, `doctor`,
+  `add`, `inspect`, `compare`, `font search`, `font list`, `font verify`,
+  `font add` without `--force`, `check`, and at most four still frames; and
+  denies `--force`/`--overwrite`, `font remove`, and an unlicensed `font add
+  --url`. Adjust the tier or profile for the machine. Remove the file to return
+  to the default `full` tier.
+- `.opencode/opencode.jsonc`: project-local OpenCode permissions for a local
+  model session. It denies the common heavy shell forms and protects
+  `fy.policy.json`, `.opencode/`, `.pi/`, and `skills/frameyard/` from
+  edits. It also adds `./skills` as a skill search path, which assumes the
+  official skill lives in the workspace; remove that line if it does not.
+- `.pi/settings.json`: points Pi at `http://127.0.0.1:9931` and defaults to
+  `LFM3-1.7B-Q8_0`, with only `read`, `bash`, `edit`, and `write` enabled.
+- `.pi/APPEND_SYSTEM.md`: the local-model workflow: `context` → `lint` →
+  `still` → `check` → handoff with `--dry-run`.
+- `.pi/sandbox.json`: committed but `enabled: false`. Enable it only after
+  testing Chromium, FFmpeg, and the local router with the filesystem/network
+  rules you need.
+
+## Human overrides
+
+The policy is a guardrail, not a security boundary. A human who intends to run
+a heavy operation can override it:
+
+```sh
+FRAMEYARD_POLICY=full npx frameyard render main --props props/main.json
+```
+
+The generated example READMEs in this repository use that prefix because they
+may be run with the scaffold installed.
+
+## Pi project trust
+
+Pi loads `.pi/` only for trusted projects. Either start Pi with:
+
+```sh
+pi --approve
+```
+
+or add the project to `~/.pi/agent/trust.json` once. The trust entry is the only
+global change; the rest stays in the workspace.
+
+## Opting out
+
+Remove `fy.policy.json` and the `.opencode/`/`.pi/` files you copied.
+The CLI then defaults to `full`, and the host configuration no longer applies.

package/scaffolds/local-models/fy.policy.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "policy": "authoring",
+  "profile": "shared-cpu"
+}

package/scaffolds/local-models/opencode/opencode.jsonc

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "skills": ["./skills"],
+  "permissions": [
+    { "action": "edit", "resource": "fy.policy.json", "effect": "deny" },
+    { "action": "edit", "resource": ".opencode/**", "effect": "deny" },
+    { "action": "edit", "resource": ".pi/**", "effect": "deny" },
+    { "action": "edit", "resource": "skills/frameyard/**", "effect": "deny" },
+    { "action": "shell", "resource": "*frameyard render*", "effect": "deny" },
+    { "action": "shell", "resource": "*frameyard tts*", "effect": "deny" },
+    { "action": "shell", "resource": "*frameyard transcribe*", "effect": "deny" },
+    { "action": "shell", "resource": "*dist/cli.js render*", "effect": "deny" },
+    { "action": "shell", "resource": "*dist/cli.js tts*", "effect": "deny" },
+    { "action": "shell", "resource": "*dist/cli.js transcribe*", "effect": "deny" },
+    { "action": "shell", "resource": "*--dry-run*", "effect": "allow" },
+  ],
+}

package/scaffolds/local-models/pi/APPEND_SYSTEM.md

@@ -0,0 +1,21 @@
+# Frameyard resource policy
+
+This workspace uses `fy.policy.json` at the repository root. Do not edit that
+file, `.pi/`, `.opencode/`, or `skills/frameyard/`.
+
+## Working loop
+
+1. Run `frameyard lint <id> --json` while editing.
+2. Inspect at most four representative stills with `frameyard still <id> --frame <spec> --json`.
+3. Run `frameyard check <id> --json` once at the end when the active policy allows it.
+4. Do not run `frameyard tts`, `frameyard transcribe`, or `frameyard render` unless the
+   user explicitly asks. Use `--dry-run` and report `deferred: true` with the exact
+   handoff command instead.
+5. `frameyard font search`, `font list`, and `font verify` are allowed; `font add`
+   is allowed without `--force`. `font remove`, `font add --force`, and an
+   unlicensed `font add --url` require the `full` policy.
+6. Read `AGENTS.md` and `skills/frameyard/SKILL.md` before changing public behavior.
+
+The local llama.cpp router is at `http://127.0.0.1:9931`. Use a small text model for
+the lint loop and a vision-capable model only for representative stills. Do not
+switch to a larger local model just to re-read the same files.

package/scaffolds/local-models/pi/sandbox.json

@@ -0,0 +1,15 @@
+{
+  "enabled": false,
+  "allowBrowserProcess": false,
+  "network": {
+    "allowLocalBinding": true,
+    "allowAllUnixSockets": true,
+    "allowedDomains": [],
+    "deniedDomains": []
+  },
+  "filesystem": {
+    "allowRead": [".", "~/.config", "~/.local"],
+    "allowWrite": [".", "/tmp"],
+    "denyWrite": ["fy.policy.json", ".pi", ".opencode", "skills/frameyard"]
+  }
+}

package/scaffolds/local-models/pi/settings.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://pi.dev/schemas/settings.schema.json",
+  "llamaSettings": {
+    "servers": [
+      {
+        "url": "http://127.0.0.1:9931",
+        "id": "local",
+        "name": "Local llama.cpp"
+      }
+    ]
+  },
+  "defaultTools": ["read", "bash", "edit", "write"],
+  "defaultProvider": "local",
+  "defaultModel": "LFM3-1.7B-Q8_0"
+}

package/skills/frameyard/README.md

@@ -25,6 +25,7 @@ When you work inside the Frameyard repository itself, `npx frameyard` resolves t
 ## Contents
 
 - `SKILL.md`: trigger description and operating workflow
+- `references/quick-reference.md`: compact skeletons, command table, policy table, and common fixes
 - `references/deterministic-authoring.md`
 - `references/bindings.md`
 - `references/controllers.md`

package/skills/frameyard/SKILL.md

@@ -1,92 +1,90 @@
 ---
 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.8.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, search or install project fonts, 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.9.0
 ---
 
 # Frameyard
 
-Use Frameyard's public project format and CLI. Do not introduce an agent-only runtime, a hosted service, or direct calls to `qwen-tts` or `whisper-cli`.
+Use the public project format and CLI. Do not add an agent-only runtime, a hosted service, or direct calls to `qwen-tts`, `sherpa-onnx-offline-tts`, or `whisper-cli`.
 
-## First decisions
+## First moves
 
-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` 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.
+1. Find `fy.config.js` from the working directory upward, or run `npx frameyard init <directory>`.
+2. Run `npx frameyard context --json`; read `format`, `compositions`, `timelines`, `fonts`, the target, its props, and its controller before editing.
+3. Confirm that speech or transcription is requested or explicitly approved before producing assets.
+4. If context is small, read [quick reference](references/quick-reference.md) first. Router: static/card → quick reference; timelines → [timelines](references/timelines.md); fonts → [fonts](references/fonts.md); captions → [subtitles and karaoke](references/subtitles-karaoke.md); failures → [diagnostics](references/diagnostics.md) and [failure recovery](references/failure-recovery.md); Canvas/WebGL → [controllers](references/controllers.md).
 
 ## Workflow
 
-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 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`. 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.
+1. **Author** one `<fy-composition>` fragment. Props, the controller, import maps, and styles are top-level siblings; never add a document shell. Omit `duration-in-frames` and `fps` only for a static composition, which renders to PNG and cannot use animation/media/transcripts. Use a controller only for Canvas, WebGL, karaoke, or per-frame math. Read [deterministic authoring](references/deterministic-authoring.md).
+2. **Assemble** a version-1 timeline with explicit tracks and clips. Sources are composition IDs, nested timeline IDs, or local media. `start`, `sourceIn`, and `duration` are integer frames; no remote URLs. Read [timelines](references/timelines.md).
+3. **Provide props** as JSON. Composition props merge over defaults; timeline overrides are keyed by composition clip ID. Use `validateProps()` for domain rules.
+4. **Lint** with `npx frameyard lint <id> --json`. It validates the document/timeline, resolves references, projects every timeline scene/keyframe channel, scans controller determinism, and probes media metadata without Chromium. It is the edit loop, not the full gate.
+5. **Check** with `npx frameyard check <id> --json`. Every animated frame is evaluated, or a static composition once. Read `diagnostics` and `kind`; treat warnings as actionable.
+6. **Inspect** with `npx frameyard still <id> --frame <spec> --out <path> --json`. A spec is a frame, an inclusive range, or a comma-separated list. The policy allows at most 32 unique frames in `full` (4 in `authoring`, 1 in `light`). One frame uses a `.png` file; multiple frames use a directory. Use `npx frameyard inspect`/`compare` for text facts, and view the PNGs when the host supports it; if not, say so.
+7. **Render** with `npx frameyard render <id> [--out <file>] [--props <file>] --json`. Composition renders accept `--concurrency`; timeline renders accept `--workers` and `--scratch`; `--container`, `--codec`, and `--encoder` select delivery. A static composition rejects those four flags. If the policy blocks render, use `--dry-run` and hand off the command; do not claim a render.
+8. **Report** the project, entries, controller, props, generated assets, validation, diagnostics, still paths and inspection status, video path, and failures. Never claim success when `check` fails, a still is missing, a render exits nonzero, or inspection was skipped.
+
+## Authoring contract
+
+- A composition is a partial fragment with one top-level `<fy-composition>` and a top-level `data-fy="props"` block. Do not use `data-fy-host` or `data-fy="format"`. `width`, `height`, and `fps` inherit the project `format`; declare both dimensions together.
+- A static composition has neither `duration-in-frames` nor `fps`; it runs `mount()`/`validateProps()`, not `update()`, and has no frame-state variables. Declaring `fps` without `duration-in-frames` is an error. A static timeline clip needs an explicit `duration` and `sourceIn: 0`.
+- Bindings: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `<template data-fy-repeat>`. Primitive top-level props are also `--fy-prop-<name>` CSS variables. Bindings apply once, before `mount`.
+- CSS/WAAPI animations are seeked from the frame clock. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation in frames. Frame state: `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, `--fy-duration-frames`.
+- Exactly one optional controller, inline or external, is the only executable code. It may export `mount`, `update`, `dispose`, and `validateProps`; at least one is required. Other scripts and `on*` handlers are rejected.
+- Media and transcript `src` values resolve from the project root; controller `src` and ordinary HTML URLs resolve from the composition URL. Embedded media uses `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 import map may add bare specifiers for controllers; `frameyard` and `frameyard/` are reserved.
+
+## Determinism
+
+- A composition frame depends only on its integer `frame`, immutable `props`, and assets loaded before frame production. A timeline frame derives from its active clips.
+- Use `random("stable:key")` from `frameyard/runtime`; never `Math.random()`. Never use `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions as animation inputs.
+- Load remote data, fonts, and images before frame production. Network is blocked during capture. Prefer project fonts installed with `npx frameyard font add`; remote font URLs produce `FONT_REMOTE` and are not reproducible. Keep `update({ frame, props })` synchronous and seek-safe; do not carry state between frames.
+- Let the runtime seek embedded video; do not play, pause, or set `currentTime` in `update()`. Redraw WebGL from the current frame; production pins software WebGL.
+- Do not run model inference inside `mount()`, `update()`, or frame production.
 
-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.
+## Resource policy
 
-## Command rules
+`fy.policy.json` is read from the working directory upward, independent of `fy.config.js`; `FRAMEYARD_POLICY` overrides it.
 
-- 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 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.
-- 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 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 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
-
-- 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.
-- Keep `update({ frame, props })` synchronous and seek-safe. Do not carry state between frames.
-- Let the runtime seek embedded `<video>` elements. Do not play, pause, or set `currentTime` in `update()`.
-- Redraw WebGL canvases from the current frame. Production pins software WebGL; do not depend on GPU-specific results or the previous frame's drawing buffer.
-- Do not run model inference inside `mount()`, `update()`, or frame production.
+- `light`: one still frame; blocks `check`, `tts`, `transcribe`, and `render`.
+- `authoring`: four still frames and `check` at low priority; blocks `tts`, `transcribe`, and `render`.
+- `full`: everything up to the 32-frame still cap.
+- `lint`, `context`, `doctor`, `add`, `inspect`, `compare`, and `--dry-run` are available in every tier. `font search`, `font list`, and `font verify` are available in every tier; `font add` requires `authoring` or `full`; `font remove`, `font add --force`, and `font add --url` without `--license`/`--license-file` require `full`.
+- When blocked, run `--dry-run`, report `deferred: true`, and give the user `commandLine`, `prerequisites`, and `blockers`. Never claim a render or asset exists.
+- `--profile shared-cpu` caps timeline workers at 2 and composition concurrency at 1 and lowers priority; `--low-priority` lowers priority without caps. Values above a cap fail with `RESOURCE_PROFILE_CONFLICT`; do not clamp silently.
+- `light`/`authoring` deny `--force` and `--overwrite`; ask before replacing an output. Do not edit the policy file, host configuration, or skill source. The policy is a guardrail, not a security boundary.
 
-## Diagnostics rule
+## Command rules
+
+- Use `--json` for non-interactive commands; parse stdout, keep stderr for progress/diagnostics. Use `--project <dir>` outside the project root.
+- Outputs default to `out/<id>.<ext>` for video and `out/<id>.png` for static compositions; explicit `--out` is relative to the current directory. Replace outputs only with approval.
+- For a timeline, `--props` is a map keyed by top-level composition clip ID; for a composition, it is the props object. Use `--concurrency` for animated compositions, `--workers`/`--scratch` for timelines. `--container <mp4|mov|mkv|webm>`, `--codec <h264|hevc|vp9>`, and `--encoder <auto|software|nvenc|qsv>` select delivery; the output extension must match the container.
+- Produce speech and transcripts only with `npx frameyard tts` and `npx frameyard transcribe`, never upstream executables; read [audio assets](references/audio-assets.md). Do not overwrite generated assets without approval.
+- Use `npx frameyard add --list --json` and `add composition|timeline <id> --template <name> --json` for templates; merge the returned registration object into `fy.config.js`. `add` never edits the config or overwrites an entry.
+- Use `npx frameyard font search <query> --json` to find a Fontsource family, then `npx frameyard font add <fontsource-id> --json` to pin and vendor it. Use `font add --file` for a local or brand font, or `font add --url` for an explicit HTTPS source. Reference the returned CSS family. `font list`, `font verify`, and `font remove` manage the manifest; never edit `fy.fonts.json` hashes by hand. Read [fonts](references/fonts.md).
+- Use `npx frameyard doctor --json` before reporting an environment problem. Read [JSON results](references/json-results.md) and [failure recovery](references/failure-recovery.md).
 
-`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.
+## Diagnostics and karaoke
 
-## Subtitle and karaoke rule
+`check`, `still`, and `render` run static validation before Chromium; errors stop, warnings allow frames. Diagnostics carry a stable `code`, message, and optional source location/suggestion. Treat `BINDING_PATH_MISSING`, `ANIMATION_*`, `STATIC_*`, and `DETERMINISM_WARNING` as actionable.
 
-Use canonical transcripts produced by `npx frameyard transcribe`. Declare them with `<fy-transcript src="assets/voice.transcript.json" words>`. Convert integer source-relative milliseconds to composition frames with the audio clip's start frame, trim start, and the composition `fps`. Karaoke highlighting requires actual `words` timings; never interpolate segment timings. Read [subtitles and karaoke](references/subtitles-karaoke.md).
+Use transcripts from `npx frameyard transcribe`. Convert source-relative milliseconds to composition frames with the clip start, trim start, and `fps`. Karaoke requires measured `words`; never interpolate segment timings.
 
 ## CLI invocation
 
-Use `npx frameyard` (or an installed `frameyard` binary) directly. `scripts/frameyard.mjs` is a fallback for hosts that cannot resolve package binaries: it prefers the package-local `dist/cli.js`, then the `frameyard` command on `PATH`. When the skill is copied out of the package, set `FRAMEYARD_CLI` to an installed CLI path if that command is unavailable.
+Use `npx frameyard` or an installed binary. `scripts/frameyard.mjs` is the fallback; set `FRAMEYARD_CLI` when the command is unavailable. Pin the CLI with `npx frameyard@<version>` when it differs from `frameyard-api-version`.
 
 ```sh
 npx frameyard check <id> --json
-node scripts/frameyard.mjs check <id> --json   # fallback
+node scripts/frameyard.mjs check <id> --json
 ```
 
-When the CLI version differs from `frameyard-api-version`, pin it with `npx frameyard@<version>`.
-
 ## References
 
+- [Quick reference](references/quick-reference.md)
+- [Fonts](references/fonts.md)
 - [Timelines](references/timelines.md)
 - [Deterministic HTML authoring](references/deterministic-authoring.md)
 - [Bindings](references/bindings.md)

package/skills/frameyard/references/audio-assets.md

@@ -34,7 +34,9 @@ Declare required transcripts with:
 
 ## Local speech synthesis
 
-Use Frameyard, not `qwen-tts` directly:
+Use Frameyard instead of calling the upstream executables directly:
+
+### qwentts.cpp (default)
 
 ```sh
 npx frameyard tts \
@@ -47,6 +49,7 @@ npx frameyard tts \
   --json
 ```
 
+- `--engine qwen` is the default and may be omitted.
 - CustomVoice only: `--speaker` is required.
 - Text comes from `--text-file` or stdin.
 - `--style` maps to the upstream style instruction.
@@ -58,6 +61,28 @@ npx frameyard tts \
 - Executable resolution: `--executable`, then `FRAMEYARD_QWEN_TTS`, then `PATH`.
 - Frameyard does not build qwentts.cpp, download models, or redistribute weights.
 
+### Supertonic 3
+
+```sh
+npx frameyard tts \
+  --engine supertonic \
+  --speaker 0 \
+  --model-dir models/sherpa-onnx-supertonic-3-tts-int8-2026-05-11 \
+  --language es \
+  --text-file script.txt \
+  --out assets/voice-es.wav \
+  --json
+```
+
+- The engine covers 31 languages and requires one of their codes (`es`, `en`, `fr`, `de`, ...); `--language` is mandatory.
+- `--speaker` is the numeric `--sid`, not a name.
+- `--model-dir` points at the extracted Supertonic 3 archive with its seven files; do not pass individual files.
+- `--style` and `--device` are qwen-only. Put Supertonic expression tags such as `<laugh>`, `<breath>`, and `<sigh>` in the text.
+- The engine writes its native WAV; Frameyard normalizes it to 24 kHz mono and records `sourceSampleRate` and `sourceChannels` in the manifest.
+- `--force` is required to replace an existing asset. Do not pass it without user approval.
+- Executable resolution: `--executable`, then `FRAMEYARD_SHERPA_ONNX_TTS`, then `PATH`.
+- Frameyard does not build sherpa-onnx, download the model archive, or redistribute weights. The upstream Supertonic repository is archived and its weights use the OpenRAIL-M license.
+
 ## Local transcription
 
 ```sh
@@ -77,9 +102,13 @@ npx frameyard transcribe assets/voice.wav \
 - Executable resolution: `--executable`, then `FRAMEYARD_WHISPER_CLI`, then `PATH`.
 - Frameyard does not download Whisper models or execute Whisper's generated karaoke shell script.
 
+## Pinned upstream revisions
+
+The wrappers target the CLI surfaces of qwentts.cpp commit `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4`, sherpa-onnx commit `af2d8d81dbfa61c4cea4c568da78f3982edca005` (v2.0.1), and whisper.cpp commit `284029c07012d2000941a08d38a31ffb71f4734e`.
+
 ## Provenance manifest
 
-Both commands update `frameyard.assets.json` in the project root unless `--manifest <file>` is supplied. The manifest records:
+Both commands update `fy.assets.json` in the project root unless `--manifest <file>` is supplied. The manifest records:
 
 - artifact path, content hash, and size;
 - generator command, Frameyard version, executable, and integration revision;
@@ -93,5 +122,5 @@ Commit the manifest with the project. It explains how generated inputs were prod
 - Do not regenerate or overwrite an existing generated asset without permission.
 - Do not silently switch models, speakers, language, or text.
 - Report the manifest path and the exact asset paths after success.
-- `npx frameyard doctor` verifies manifest integrity, including artifact, source, model, and derived-export hashes, and optional integration executables; it does not download or repair anything. Pass `--talker-model`, `--codec-model`, or `--model` to inspect model readability and identity before generation.
+- `npx frameyard doctor` verifies manifest integrity, including artifact, source, model, and derived-export hashes, and optional integration executables; it does not download or repair anything. Pass `--talker-model`, `--codec-model`, `--model-dir`, or `--model` to inspect model readability and identity before generation.
 - Once assets are frozen, checking and rendering do not need the model or inference executable.