frameyard 0.8.0 → 0.10.0

package/scaffolds/init/AGENTS.md

@@ -0,0 +1,131 @@
+# AGENTS.md
+
+This project produces deterministic, parameterized video with Frameyard. This file is the local summary; the official skill has the full contract.
+
+## Project layout
+
+- `fy.config.js` explicitly maps project IDs to sources. There is no directory scanning. It declares the project `format`, `compositions`, and `timelines`.
+- `compositions/` contains HTML fragments; an optional controller lives beside the fragment as a `.controller.js` module.
+- `timelines/` contains JSON timeline documents that assemble clips into one video.
+- `props/hello.json` contains composition props; `props/main.json` contains timeline overrides keyed by composition clip ID.
+- `out/` contains rendered files and is gitignored. `assets/` contains local media and generated assets.
+- `package.json` pins the CLI in `dev`, `check`, `render`, and `still` scripts.
+
+An animated composition declares `duration-in-frames`. A composition with neither `duration-in-frames` nor `fps` is static: it is captured once, renders to PNG, and cannot use animation, media, or transcripts. `width`, `height`, and `fps` inherit the project `format`; declare `width` and `height` together or not at all.
+
+## Composition skeleton
+
+A composition is a partial HTML fragment, not a full document. Keep one top-level `<fy-composition>`; props, the controller, import maps, and styles are top-level siblings. Do not add `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`.
+
+```html
+<script type="application/json" data-fy="props">{ "title": "Hello" }</script>
+<style>
+  html, body { margin: 0; width: 100%; height: 100%; }
+</style>
+<fy-composition width="1280" height="720" fps="30" duration-in-frames="150">
+  <h1 data-fy-text="title"></h1>
+</fy-composition>
+```
+
+## Timeline skeleton
+
+`timelines/main.timeline.json` assembles clips in the project format:
+
+```json
+{
+  "version": 1,
+  "tracks": [{ "id": "v1", "kind": "video" }],
+  "clips": [
+    {
+      "id": "hello",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "hello" },
+      "start": 0
+    }
+  ]
+}
+```
+
+- `source.kind` is `composition`, `timeline`, `video`, `image`, or `audio`. `start`, `sourceIn`, and `duration` are timeline frames. Image clips require a duration.
+- A static composition clip needs an explicit `duration` and `sourceIn: 0`. It contributes no audio.
+- Tracks composite bottom-to-top. Same-track overlap requires a timeline `transitions` entry; see the skill for transforms, keyframes, blends, and transitions.
+
+## Bindings and animation
+
+- 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`; controller-created DOM is not re-bound.
+- 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 on `:root`: `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, `--fy-duration-frames`.
+
+## Controller
+
+Exactly one optional controller is allowed, inline or external, as a top-level sibling. It may export `mount`, `update`, `dispose`, and `validateProps`; at least one is required. `mount` may be async; `update` is synchronous and seek-safe. The controller is the only executable code; other scripts and `on*` handlers are rejected. Extract large or reusable controllers to an external module.
+
+```html
+<script type="text/fy-controller">
+export default {
+  mount({ root, props }) {},
+  update({ frame, props }) {},
+};
+</script>
+```
+
+## Determinism
+
+- A frame depends only on its integer `frame`, immutable `props`, and assets loaded before frame production.
+- Use `random("stable:key")` from `frameyard/runtime`; never `Math.random()`, `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions.
+- Load remote data, fonts, and images before frames. Network is blocked during capture; do not `fetch()` from `update()`.
+- Vendor fonts with `npx frameyard font add --file`; do not rely on a remote Google Fonts link for a deterministic render. The server injects `@font-face` rules and the host waits for `document.fonts.ready`.
+- Let the runtime seek embedded video; do not play, pause, or set `currentTime`. Redraw Canvas/WebGL from the current frame.
+- Do not run model inference inside `mount()`, `update()`, or frame production.
+
+## Fonts
+
+- `fy.fonts.json` records installed families, licenses, and SHA-256 values; commit it with `assets/fonts/`.
+- Search Fontsource with `npx frameyard font search "<query>" --json`, then install a family with `npx frameyard font add <fontsource-id> --json`. Variable `wght` is the default; add `--static --weight 400,700` for static files.
+- Use `npx frameyard font add --file <path> --family "<name>" --license <id> --license-file <path>` for a local or brand font. Use `--url` for an explicit HTTPS source with `--sha256`.
+- Run `npx frameyard font list --json` and `npx frameyard font verify --json` after moving files. Do not edit manifest hashes by hand.
+- `font add` requires `authoring` or `full`; `font remove`, `font add --force`, and an unlicensed `--url` import require `full`.
+
+## Media and transcripts
+
+- Composition audio uses `<audio>` with `data-fy-start` (frames), `data-fy-trim` (seconds), optional `data-fy-duration` (seconds), and `data-fy-volume` (0-1). Timeline audio uses frames and audio tracks.
+- Media and transcript `src` values resolve from the project root; controller `src` and ordinary HTML URLs resolve from the composition URL.
+- Declare transcripts with `<fy-transcript src="assets/voice.transcript.json" words>`. `words` requires measured word timings; never interpolate segment timings.
+- Use Frameyard's `tts`/`transcribe` wrappers; never call `qwen-tts`, `sherpa-onnx-offline-tts`, or `whisper-cli` directly. Do not overwrite generated assets without approval. Commit `fy.assets.json` when present; do not edit hashes.
+
+## Resource policy
+
+A workspace can commit `fy.policy.json` to gate expensive operations. The nearest file from the working directory upward applies, independent of `fy.config.js`; `FRAMEYARD_POLICY` overrides it. `light` allows one still frame and blocks `check`, `tts`, `transcribe`, and `render`; `authoring` allows four still frames and `check` at low priority and blocks the three heavy operations; `full` allows everything up to the 32-frame still cap. `--profile shared-cpu` caps timeline workers at 2 and composition concurrency at 1. `tts`, `transcribe`, and `render` accept `--dry-run`; use it and report the handoff when blocked. The policy is a guardrail, not a security boundary.
+
+## Agent workflow
+
+1. Read `fy.config.js`, the timeline, the composition, its controller, and the props. Run `npx frameyard context --json` first.
+2. Author with native HTML, CSS, SVG, Canvas, WebGL, and an optional controller. Use `npx frameyard add --list --json` for templates and merge the returned registration object into `fy.config.js`.
+3. Lint the edit loop with `npx frameyard lint main --json`. It does not run `validateProps` or composition runtime.
+4. Run `npx frameyard check main --json` for the full gate when the policy allows it; read diagnostics and warnings.
+5. Inspect with `npx frameyard still main --frame <spec> --out <dir|file.png> --json`. The policy captures at most 32 unique frames in `full` (4 in `authoring`, 1 in `light`). Use `npx frameyard inspect`/`compare` for text facts; view the PNGs when possible.
+6. Render with `npx frameyard render main --props props/main.json [--workers <n>] [--scratch <dir>] --json`. If the policy blocks it, use `--dry-run` and report the handoff.
+7. Report sources, props, diagnostics, still paths, inspection status, output path, and failures. Never claim success when `check` fails, a still is missing, or a render exits nonzero.
+
+## Commands
+
+```sh
+npx frameyard dev
+npx frameyard context --json
+npx frameyard doctor --json
+npx frameyard add --list --json
+npx frameyard lint main --json
+npx frameyard check main --json
+npx frameyard still main --frame 42 --out main-42.png --json
+npx frameyard inspect main-42.png --json
+npx frameyard render main --props props/main.json --workers 8 --scratch /path/to/scratch --json
+```
+
+- Use `--json` for non-interactive commands. Parse stdout; keep stderr for progress and diagnostics.
+- Use `--project <dir>` outside the project root. Outputs default to `out/<id>.mp4` or `out/<id>.png`.
+- `--concurrency` is for animated compositions; `--workers`/`--scratch` are for timelines. `--container <mp4|mov|mkv|webm>`, `--codec <h264|hevc|vp9>`, and `--encoder <auto|software|nvenc|qsv>` select delivery; the extension must match.
+- `--dry-run` validates and prints a handoff plan. `--profile shared-cpu` caps workers/concurrency and lowers priority.
+- `still`/`render` replace outputs only with `--overwrite`; generated assets only with `--force`, and only with approval. The resource policy denies both outside `full`.
+
+The official `frameyard` agent skill has the full contract. Install it with `npx skills add vladiantio/frameyard`. This project was scaffolded with frameyard {{VERSION}}; `npx frameyard` resolves the latest version, so run `npx frameyard@{{VERSION}}` when you need the scaffolding version.

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`