Skip to content

Code-first video & image, rendered natively on WebGPU.

fix(skills): correct effect scales and APIs; restore effects catalog

okanasldbb8c190eefc
diff --git a/.changeset/styles-visual-effects.md b/.changeset/styles-visual-effects.md
new file mode 100644
index 00000000..f1fe4b16
--- /dev/null
+++ b/.changeset/styles-visual-effects.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+`Styles.*` presets are typed as visual effects, so `layer.withEffects(Styles.vhs())` typechecks without a cast. The effects catalog in the agent skill lists every effect class again (FilmGrain, Curves, Levels, ApplyLUT, Crop and others had dropped out), and the skills use the right scales for `FilmGrain` and `Vignette` `strength` (0–100) and the right `renderVideo` quality and codec values.
diff --git a/examples/19_framefields_film/src/film.ts b/examples/19_framefields_film/src/film.ts
index cf89f147..82566074 100644
--- a/examples/19_framefields_film/src/film.ts
+++ b/examples/19_framefields_film/src/film.ts
@@ -18,7 +18,15 @@ import { motionScene } from "./scenes/motion.js";
import { openScene } from "./scenes/open.js";
import { resolveScene } from "./scenes/resolve.js";
import { trackScene } from "./scenes/track.js";
-import { DURATION_FRAMES, FPS, H, INK, W, asset, registerFonts } from "./theme.js";
+import {
+ asset,
+ DURATION_FRAMES,
+ FPS,
+ H,
+ INK,
+ registerFonts,
+ W,
+} from "./theme.js";
export { trackScene };
@@ -44,7 +52,7 @@ export async function buildFilm(): Promise<Composition> {
film.add(Layer.audio(asset("score.mp3"), { id: "score", volume: 1 }));
// One shared emulsion over everything keeps paper, footage and type in the same world.
- film.apply(new FilmGrain({ strength: 0.05, size: 1.6, animated: true }));
+ film.apply(new FilmGrain({ strength: 5, size: 1.6, animated: true }));
return film;
}
diff --git a/examples/19_framefields_film/src/render-track.ts b/examples/19_framefields_film/src/render-track.ts
index ae36192f..823224ef 100644
--- a/examples/19_framefields_film/src/render-track.ts
+++ b/examples/19_framefields_film/src/render-track.ts
@@ -11,7 +11,9 @@ const currentDir =
const outputDir = path.resolve(currentDir, "../output");
async function main(): Promise<void> {
- console.log("=== Framefields Film: Chapter 05 'Track it.' Scene Rendering ===");
+ console.log(
+ "=== Framefields Film: Chapter 05 'Track it.' Scene Rendering ===",
+ );
await fs.mkdir(outputDir, { recursive: true });
await registerFonts();
@@ -26,7 +28,7 @@ async function main(): Promise<void> {
});
comp.add(trackScene({ from: 0, to: totalFrames }));
- comp.apply(new FilmGrain({ strength: 0.05, size: 1.6, animated: true }));
+ comp.apply(new FilmGrain({ strength: 5, size: 1.6, animated: true }));
console.log(
`✓ Composition assembled: ${W}x${H} @ ${FPS} FPS (${totalFrames} frames)`,
@@ -40,8 +42,7 @@ async function main(): Promise<void> {
const heroFrames = [
{
frame: 12,
- label:
- "Soft-Alpha Cutout · 3D Ground Contact Rings · Reticle Lock",
+ label: "Soft-Alpha Cutout · 3D Ground Contact Rings · Reticle Lock",
},
{
frame: 48,
diff --git a/examples/19_framefields_film/src/scenes/effects.ts b/examples/19_framefields_film/src/scenes/effects.ts
index 9aedc521..608ebe73 100644
--- a/examples/19_framefields_film/src/scenes/effects.ts
+++ b/examples/19_framefields_film/src/scenes/effects.ts
@@ -220,7 +220,7 @@ export function effectsScene() {
{
name: "grade",
title: "Graded",
- fx: (c) => warm(c).apply(new Vignette({ strength: 0.4 })),
+ fx: (c) => warm(c).apply(new Vignette({ strength: 40 })),
},
{
name: "halftone",
diff --git a/examples/19_framefields_film/src/scenes/film.ts b/examples/19_framefields_film/src/scenes/film.ts
index eac4c5c1..36e2bd6d 100644
--- a/examples/19_framefields_film/src/scenes/film.ts
+++ b/examples/19_framefields_film/src/scenes/film.ts
@@ -4,23 +4,23 @@
* verb lands in the sky.
*/
import { Layer, LayerAnimation, Vignette } from "framefields";
-import { LINE_WIDTH } from "./open.js";
import {
+ asset,
+ chapter,
EASE_IN_OUT,
EASE_OUT,
EMBER,
H,
- INK,
- PAPER,
- SAND,
- W,
- asset,
- chapter,
headline,
+ INK,
keys,
label,
+ PAPER,
+ SAND,
scene,
+ W,
} from "../theme.js";
+import { LINE_WIDTH } from "./open.js";
export const FILM_FROM = 68;
export const FILM_TO = 198;
@@ -37,10 +37,20 @@ type Key = [number, number, string?];
* The window, the plate inside it and its edge all derive from these keys (same
* frames, same eases), so they move as one piece.
*/
-const WIDTHS: Key[] = [[18, LINE_WIDTH], [42, W, EASE_IN_OUT]];
-const HEIGHTS: Key[] = [[0, 4], [16, 360, EASE_IN_OUT], [18, 360], [42, H, EASE_IN_OUT]];
-const map = (list: Key[], fn: (v: number) => number): Key[] => list.map(([f, v, e]) => [f, fn(v), e]);
-const sized = (anim = LayerAnimation.create()) => keys("width", WIDTHS, keys("height", HEIGHTS, anim));
+const WIDTHS: Key[] = [
+ [18, LINE_WIDTH],
+ [42, W, EASE_IN_OUT],
+];
+const HEIGHTS: Key[] = [
+ [0, 4],
+ [16, 360, EASE_IN_OUT],
+ [18, 360],
+ [42, H, EASE_IN_OUT],
+];
+const map = (list: Key[], fn: (v: number) => number): Key[] =>
+ list.map(([f, v, e]) => [f, fn(v), e]);
+const sized = (anim = LayerAnimation.create()) =>
+ keys("width", WIDTHS, keys("height", HEIGHTS, anim));
export function filmScene() {
const len = FILM_TO - FILM_FROM;
@@ -67,11 +77,24 @@ export function filmScene() {
height: H,
muted: true,
})
- .apply(new Vignette({ strength: 0.35, radius: 0.85, softness: 0.6 }))
+ .apply(new Vignette({ strength: 35, radius: 0.85, softness: 0.6 }))
.animate(
- keys("x", map(WIDTHS, (w) => (w - W) / 2),
- keys("y", [...map(HEIGHTS, (h) => (h - H) / 2), [46, 0], [70, -REFRAME, EASE_OUT]],
- keys("scale", [[0, 1.22], [len, 1.0, "power2.out"]]))),
+ keys(
+ "x",
+ map(WIDTHS, (w) => (w - W) / 2),
+ keys(
+ "y",
+ [
+ ...map(HEIGHTS, (h) => (h - H) / 2),
+ [46, 0],
+ [70, -REFRAME, EASE_OUT],
+ ],
+ keys("scale", [
+ [0, 1.22],
+ [len, 1.0, "power2.out"],
+ ]),
+ ),
+ ),
),
// The ember line's last trace: the window's frame, fading as it grows.
Layer.box({
@@ -84,9 +107,27 @@ export function filmScene() {
borderColor: EMBER,
borderWidth: 4,
strokeAlign: "inside",
- }).animate(sized(keys("opacity", [[20, 1], [38, 0, "power2.in"]]))),
+ }).animate(
+ sized(
+ keys("opacity", [
+ [20, 1],
+ [38, 0, "power2.in"],
+ ]),
+ ),
+ ),
],
- }).animate(sized(keys("x", map(WIDTHS, (w) => (W - w) / 2), keys("y", map(HEIGHTS, (h) => (H - h) / 2))))),
+ }).animate(
+ sized(
+ keys(
+ "x",
+ map(WIDTHS, (w) => (W - w) / 2),
+ keys(
+ "y",
+ map(HEIGHTS, (h) => (H - h) / 2),
+ ),
+ ),
+ ),
+ ),
letterbox("film-bar-top", 0, 44),
letterbox("film-bar-bottom", H - BAR, 44, true),
headline({
@@ -100,7 +141,15 @@ export function filmScene() {
inAt: 52,
outAt: len - 16,
}),
- ...chapter({ id: "film-ch", index: "01", name: "Composite", color: PAPER, inAt: 60, outAt: len - 12, y: H - BAR / 2 - 11 }),
+ ...chapter({
+ id: "film-ch",
+ index: "01",
+ name: "Composite",
+ color: PAPER,
+ inAt: 60,
+ outAt: len - 12,
+ y: H - BAR / 2 - 11,
+ }),
label({
id: "film-caption",
text: "Layers · Masks · Transforms",
@@ -126,6 +175,10 @@ function letterbox(id: string, y: number, at: number, fromBottom = false) {
height: BAR,
fillColor: INK,
}).animate(
- LayerAnimation.create().fromTo("y", fromBottom ? H : -BAR, y, { start: at, end: at + 22, ease: EASE_OUT }),
+ LayerAnimation.create().fromTo("y", fromBottom ? H : -BAR, y, {
+ start: at,
+ end: at + 22,
+ ease: EASE_OUT,
+ }),
);
}
diff --git a/examples/19_framefields_film/src/scenes/grade.ts b/examples/19_framefields_film/src/scenes/grade.ts
index b8161dec..9619c5c7 100644
--- a/examples/19_framefields_film/src/scenes/grade.ts
+++ b/examples/19_framefields_film/src/scenes/grade.ts
@@ -118,7 +118,7 @@ export function gradeScene() {
highlights: { cyanRed: 4, yellowBlue: -6 },
}),
)
- .apply(new Vignette({ strength: 0.45, radius: 0.8, softness: 0.65 }))
+ .apply(new Vignette({ strength: 45, radius: 0.8, softness: 0.65 }))
.animate(push());
return scene({
diff --git a/examples/21_full_circle/src/film.ts b/examples/21_full_circle/src/film.ts
index bdf932f6..21b3a8d9 100644
--- a/examples/21_full_circle/src/film.ts
+++ b/examples/21_full_circle/src/film.ts
@@ -57,7 +57,7 @@ export async function buildFilm(): Promise<Composition> {
);
// One lens and one emulsion over everything keeps plates and type in the same world.
- film.apply(new Vignette({ strength: 0.3, radius: 0.85, softness: 0.6 }));
- film.apply(new FilmGrain({ strength: 0.05, size: 1.6, animated: true }));
+ film.apply(new Vignette({ strength: 30, radius: 0.85, softness: 0.6 }));
+ film.apply(new FilmGrain({ strength: 5, size: 1.6, animated: true }));
return film;
}
diff --git a/examples/22_framefields_launch/src/film.ts b/examples/22_framefields_launch/src/film.ts
index 7e7ae722..cd327acd 100644
--- a/examples/22_framefields_launch/src/film.ts
+++ b/examples/22_framefields_launch/src/film.ts
@@ -46,7 +46,7 @@ export async function buildFilm(): Promise<Composition> {
durationFrames: DURATION,
}),
);
- film.apply(new Vignette({ strength: 0.12, radius: 0.95, softness: 0.7 }));
- film.apply(new FilmGrain({ strength: 0.035, size: 1.4, animated: true }));
+ film.apply(new Vignette({ strength: 12, radius: 0.95, softness: 0.7 }));
+ film.apply(new FilmGrain({ strength: 3.5, size: 1.4, animated: true }));
return film;
}
diff --git a/examples/26_mac_keyboard_from_3d_primitives/src/film.ts b/examples/26_mac_keyboard_from_3d_primitives/src/film.ts
index 18b5e119..caf20c88 100644
--- a/examples/26_mac_keyboard_from_3d_primitives/src/film.ts
+++ b/examples/26_mac_keyboard_from_3d_primitives/src/film.ts
@@ -209,7 +209,7 @@ export async function buildFilm(): Promise<Composition> {
caption(),
]);
// Fine grain dithers the floor's light pool, which would band in 8 bits.
- film.apply(new Vignette({ strength: 0.18, radius: 0.9, softness: 0.75 }));
- film.apply(new FilmGrain({ strength: 0.03, size: 1.2, animated: true }));
+ film.apply(new Vignette({ strength: 18, radius: 0.9, softness: 0.75 }));
+ film.apply(new FilmGrain({ strength: 3, size: 1.2, animated: true }));
return film;
}
diff --git a/packages/framefields/src/styles.ts b/packages/framefields/src/styles.ts
index 40670284..35b7e903 100644
--- a/packages/framefields/src/styles.ts
+++ b/packages/framefields/src/styles.ts
@@ -4,7 +4,8 @@
* knobs that matter most; for anything finer, build the stack from the
* effect classes directly.
*/
-import type { Effect } from "@framefields/core";
+
+import type { AnyVisualEffect } from "./effects/index.js";
import {
Ascii,
Contour,
@@ -24,8 +25,8 @@ import {
Vignette,
} from "./effects/index.js";
-type Look = Effect<object>[];
-const look = (...effects: unknown[]): Look => effects as Look;
+type Look = AnyVisualEffect[];
+const look = (...effects: AnyVisualEffect[]): Look => effects;
export const Styles = {
/** 8-bit game: PICO-8 palette, chunky pixels, light dithering. */
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index 000d3558..de59be46 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -1,6 +1,6 @@
---
name: framefields-compose
-description: Design, structure, and animate code-first video compositions using the framefields WebGPU SDK. Use when creating scenes, layout trees, kinetic typography, camera trajectories, vector shapes, or audio-synchronized motion graphics in framefields.
+description: Design, structure, and animate code-first video compositions using the framefields WebGPU SDK. Use when writing or changing a framefields film — scenes and transitions, layout trees, keyframes and easing, kinetic typography, shapes and morphs, charts, blend modes and mattes, 3D scenes (cameras, lights, materials, outlines, models), physics, GPU particles, procedural VFX layers, time remapping, or audio-synchronized motion.
---
# framefields-compose
@@ -9,9 +9,9 @@ description: Design, structure, and animate code-first video compositions using
Import everything from the [`framefields`](https://www.npmjs.com/package/framefields) npm package. If the project doesn't have framefields set up yet, follow the `framefields` skill first (install, project scaffold, first render).
## Overview
-`framefields` is a code-first, deterministic video composition SDK executing natively on WebGPU (Dawn) in Node.js. It replaces browser-based rendering (Puppeteer/Chromium) with high-performance GPU pipelines, Yoga flexbox layout, Slug vector typography, 3D camera transforms, and reactive audio/signal drivers.
+`framefields` is a code-first, deterministic video SDK on native WebGPU (Dawn) in Node.js: Yoga flexbox layout, GPU vector text, 3D, physics, particles, and signal-driven animation.
-Every composition is defined as a tree of layout nodes compiled into a deterministic execution program: `(composition, frame) → pixels`.
+A composition is a tree of layout nodes compiled into a deterministic program: `(composition, frame) → pixels`.
---
@@ -23,11 +23,8 @@ A `Composition` instance defines canvas dimensions, frame rate, background, regi
```typescript
import { Composition, Layer, FontManager } from "framefields";
-// Always register fonts before assembling layers
-await FontManager.register({
- family: "Inter",
- source: "assets/fonts/Inter.ttf"
-});
+// Register fonts before building text layers (the composition picks them up)
+await FontManager.register({ family: "Inter", source: "assets/fonts/Inter.ttf" });
const comp = new Composition({
width: 1920,
@@ -35,11 +32,10 @@ const comp = new Composition({
fps: 30,
durationMs: 10000, // or computeDuration()
backgroundColor: "#0E0D0C",
- fonts: ["assets/fonts/Inter.ttf"],
});
comp.add(Layer.box({ /* ... */ }));
-comp.add(Layer.audio("assets/score.mp3", { volume: 1 }));
+comp.add(Layer.audio("assets/score.mp3", { volume: 1, durationFrames: 300 }));
```
### 2. Scene Architecture (Production Pattern)
@@ -53,6 +49,8 @@ For the exported `Scene` / `Sequence` builder, scene windows are half-open: `[st
```typescript
// theme.ts
+import { Layer, type LayoutNode } from "framefields";
+
export const W = 1920;
export const H = 1080;
export const FPS = 30;
@@ -63,7 +61,7 @@ export const INK = "#0E0D0C";
export const PAPER = "#EEE9E0";
export const EMBER = "#FF5A1F";
-export function scene(options: { id: string; from: number; to: number; children: unknown[] }) {
+export function scene(options: { id: string; from: number; to: number; children: LayoutNode[] }) {
return Layer.box({
id: options.id,
position: "absolute",
@@ -73,7 +71,7 @@ export function scene(options: { id: string; from: number; to: number; children:
height: H,
startFrame: options.from,
durationFrames: options.to - options.from,
- children: options.children as never,
+ children: options.children,
});
}
```
@@ -100,11 +98,11 @@ All `Layer.*` builders return `AnimatableNode<T>` instances with chainable `.ani
| `Layer.caption(src, options)` | `"media"` | SRT-driven synchronized subtitle engine. Bottom-anchored auto-wrapping cues. |
| `Layer.chart(options, props)` | `"box"` | Charts built from native nodes (d3 scales and geometry). `type`: `"line" \| "area" \| "bar" \| "scatter" \| "candlestick" \| "pie" \| "donut"`. Options: `width`, `height`, `series: [{ name, data, color, type, curve, pointRadius }]` or `data`, `categories`, `stacked`, `xAxis`/`yAxis` (`min`, `max`, `ticks`, `grid`, `format`: a d3-format string like `"$,.0f"`), `legend`, `valueLabels`, `fontFamily`, `fontSize`, `colors`, `animate: { start, duration, stagger, ease } \| false`. `props` positions the chart box. Children get ids `<id>-bar-<series>-<i>`, `<id>-line-<series>`, `<id>-slice-<i>`. Keep scatter charts to a few hundred points: each point is a node. |
| `Layer.camera(options)` | `"camera"` | 3D scene camera with FOV, lens rack focus, and orbital coordinates. |
-| `Layer.light(options)` | `"light"` | 3D lighting primitive (`ambient`, `directional`, `point`, `spot`). Directional and spot take `castShadow: true`, `shadowSoftness`, `shadowDarkness`. |
+| `Layer.light(options)` | `"light"` | 3D lighting primitive (`ambient`, `directional`, `point`, `spot`); also `Layer.ambientLight` / `directionalLight` / `pointLight` / `spotLight` and `Light.*`, all taking one options object. Directional and spot take `castShadow: true`, `shadowSoftness`, `shadowDarkness`. |
| `Layer.environment(preset, options)` | `"light"` | The 3D scene's world: studio image-based light, exposure, tone mapping, fog, bloom. **Adding one switches the scene to physically based shading.** See *3D Look* below. |
| `Layer.sequence(entries, options)` | `"box"` | Scenes back to back with `Transition`s between them; returns a box whose `totalFrames` is the length. See *Scenes & Transitions*. |
| `Layer.model(options)` | `"model3d"` | 3D mesh loader (`.gltf`, `.glb`, `.obj`, `.fbx`, `.stl`, `.ply`). Supports skinning and audio deformation compute shaders. |
-| `Layer3D.roundedBox / sphere / cylinder / capsule / torus / ring / prism / pyramid / polyhedron / icosahedron / icosphere / shard(options)` | `"model3d"` | Procedural solid meshes, centered on `x`/`y`/`z` (y is down, so "top" is -y). `roundedBox`: `width`, `height`, `depth`, `radius`, `segments`, `taper`. `sphere`: `radius`. `cylinder`: `radius` or `radiusTop`/`radiusBottom`, `height`, `openEnded`, `flatShaded`. `capsule`: `radius`, `height` (cylindrical shaft) or `totalHeight`. `torus`: `radius`, `tube` (tube radius), `arc`. `ring`: flat annulus (`innerRadius`, `outerRadius`). `prism` / `pyramid`: solid capped flat-shaded N-gon prism or pyramid (`sides`, `radius`, `height`). `polyhedron` (`type: "tetrahedron" \| "octahedron" \| "dodecahedron" \| "icosahedron"`), `icosahedron`, `icosphere` (`radius`, `detail`, `flatShaded`). `shard`: procedural flat-faceted polyhedron rock/crystal (`radius`, `cuts`, `irregularity`, `seed`). Surface: `color`, `tint`, `roughness`, `metallic`, `emissive`, `emissiveIntensity`, `material` (`"lit" \| "glass" \| "acrylic" \| "frosted"`), `castShadow`, `wireframe`. Shared GPU buffers cache identical shapes. |
+| `Layer3D.roundedBox / sphere / cylinder / capsule / torus / ring / prism / pyramid / polyhedron / icosahedron / icosphere / shard(options)` | `"model3d"` | Procedural solid meshes, centered on `x`/`y`/`z` (y is down, so "top" is -y). `roundedBox`: `width`, `height`, `depth`, `radius`, `segments`, `taper`. `sphere`: `radius`. `cylinder`: `radius` or `radiusTop`/`radiusBottom`, `height` (required), `openEnded`, `flatShaded`. `capsule`: `radius`, `length` (straight shaft; total height is `length + 2 * radius`). `torus`: `radius`, `tube` (tube radius), `arc`. `ring`: flat annulus (`innerRadius`, `outerRadius`). `prism` / `pyramid`: solid capped flat-shaded N-gon prism or pyramid (`sides`, `radius`, `height`). `polyhedron` (`type: "tetrahedron" \| "octahedron" \| "dodecahedron" \| "icosahedron"`), `icosahedron`, `icosphere` (`radius`, `detail`, `flatShaded`). `shard`: procedural flat-faceted polyhedron rock/crystal (`radius` or `size: [x, y, z]`, `facets`, `irregularity`, `seed`). Surface: `color`, `tint`, `roughness`, `metallic`, `emissive`, `emissiveIntensity`, `material` (`"lit" \| "glass" \| "acrylic" \| "frosted"`), `castShadow`, `wireframe`. Shared GPU buffers cache identical shapes. |
| `Layer3D.extrude / lathe / tube / line / points(options)` | `"model3d"` | Custom & path-driven 3D geometry. `extrude`: extrude a 2D SVG path `d` (with holes) or `contour`/`holes` (`depth`, `bevelThickness`, `bevelSize`, `bevelSegments`, `bevelColor`). `lathe`: revolve a 2D `points` profile `[r, y][]` around the Y axis (`segments`, `phiStart`, `phiLength`, `closed`, `flatShaded`). `tube`: sweep a solid or thick-walled hollow pipe (`radius`, `innerRadius`, `radiusTaper`, `closed`, `capped`) along a `Path3D` or 3D control `points` using rotation-minimizing frames. `line`: 3D polyline (`points` or `Path3D`, `dashSize`, `gapSize`, per-vertex `colors`). `points`: 3D point cloud (`points`, `pointSize` for lit sphere dots or `0` for `point-list`, per-point `colors`). |
| `Layer3D.instances(options)` | `"model3d"` | Hardware-instanced single or multi-variant mesh rendering in 1 GPU draw call. Options: `count`, `mesh` / `meshes` (array of Layer3D primitives or meshes), `instanceAt(index, frame): { position, rotation, scale, color, emissive }`, or bind directly to Rapier `Physics.world3d` bodies via `bodies: Body3D[]` with `emissiveBySpeed` and `colorRamp`. |
| `Layer3D.swarm(options)` | `"model3d"` | Continuous 3D GPU particle swarm with compute-driven physics, 3D curl turbulence, vortex/cyclone field (`swirl`, `pull`, `axial`), ground plane collisions with Coulomb sliding friction and rotational roll torque, kinetic heat accumulation/cooling, and zero-copy packing directly into GPU instance buffers. |
@@ -113,8 +111,6 @@ All `Layer.*` builders return `AnimatableNode<T>` instances with chainable `.ani
## Media time remapping
-`Layer.ambientLight({ color, intensity, id })` and `Light.ambient({ color, intensity, id })` accept options objects like the other light helpers; the positional `(color, intensity, options)` form remains supported. Animation-builder instances passed through a layer's `animation` option are normalized to program specs, including `CameraAnimation`.
-
Video and audio layers accept `timeRemap` with an explicit `durationFrames`. Map frames are layer-local; `sourceSec` is absolute source time. Increasing source times play forward; decreasing source times play in reverse; equal source times hold the picture and silence the audio. Rate changes also change audio pitch. Do not combine this with `trimStartSec`.
```ts
@@ -345,7 +341,7 @@ puppet.animate(walkCycle, bob, LayerAnimation.stepped(2));
A path shape's `d` is animatable: keyframe two or more SVG paths and they morph. Any paths work (different point counts, curves, arcs, several subpaths); they are resampled and lined up so the morph does not twist. Eases apply as usual.
```typescript
-Layer.shape("path", { position: "absolute", x: 0, y: 0, width: 400, height: 400, d: BLOB_A, fillColor: "#3B82F6" })
+Layer.shape("path", { position: "absolute", x: 0, y: 0, width: 400, height: 400, d: BLOB_A, fill: "#3B82F6" })
.animate(LayerAnimation.keys("d", [[0, BLOB_A], [24, STAR, "back.out(1.4)"], [48, HEART, "expo.inOut"]]));
```
@@ -468,23 +464,19 @@ comp.add([
Layer3D.sphere({ radius: 90, color: "#e8e8e8", metallic: 1, roughness: 0.15 }); // chrome
Layer3D.roundedBox({ ..., color: "#ff5a1f", roughness: 0.45 }); // satin plastic
-Layer3D.cylinder({ ..., color: "#111", emissive: "#4da3ff", emissiveIntensity: 3 }); // neon tube
+Layer3D.cylinder({ ..., height: 400, color: "#111", emissive: "#4da3ff", emissiveIntensity: 3 }); // neon tube
```
- **Tone mapping `"neutral"` (default) keeps brand colors as authored**: orange stays orange. Use `"agx"` for a filmic roll-off.
- **Bloom only takes light well past white** (emissive ≳ 3, hot speculars), so ordinary bright surfaces don't glow. Raise `emissiveIntensity` to make something glow.
- **Shadows:** directional and spot lights can each cast shadows, subject to device texture-array limits. Meshes cast by default (`castShadow: false` opts out); flat layers (planes, cards) cast only with `castShadow: true`. Everything receives.
- **Art-directed materials:** `material: "toon"` works on meshes, flat 3D cards and native 3D text. Its `toon` options are `shadowColor` (shadow-side albedo multiplier; model shade color or `#80808c`), `lightColor` (lit-side multiplier; white), `threshold` (terminator cosine; 0.075), `softness` (transition width; 0.25) and `diffuse` (0 flat through 1 Lambert; 0). Toon surfaces use all scene lights, their colors, point/spot attenuation and real cast shadows; environment exposure, tone mapping, fog and emissive bloom still apply. Lower `threshold` to wrap light around a surface, or raise `shadowColor` for a bright shadow floor on illustrated cards. Physical and unlit materials are independent of these options.
-- **Geometry outlines:** `Layer.environment("neutral", { outlines: true })`, or `outlines: { color: "#191721", width: 2, referenceHeight: 1080, creaseAngle: 45, depthThreshold: 0.01, opacity: 1 }`. Width is in pixels at `referenceHeight` (default 1080), scaled with output height. Silhouettes/depth jumps use inverse-depth curvature; creases use surface normals, so textures, shadows and coplanar triangle seams do not acquire ink. `creaseAngle: 180` keeps only silhouettes/depth edges; `width: 0`, `opacity: 0` or `outlines: false` hides ink. Set `outline: false` on a 3D layer/model to exclude it while preserving its occlusion of outlines behind it (useful for already-outlined character artwork). Ink follows scene fog and runs **before** camera depth blur and bloom. This is a scene geometry pass, separate from the image-based `Toon` effect.
+- **Geometry outlines (ink):** `Layer.environment("neutral", { outlines: true })`, or `outlines: { color: "#191721", width: 2, referenceHeight: 1080, creaseAngle: 45, depthThreshold: 0.01, opacity: 1 }`. `width` is px at `referenceHeight`, scaled with the output height; start near 1 px at export height. Ink comes from depth and normals, so textures, shadows and coplanar seams get none; `creaseAngle: 180` keeps only silhouettes. `outline: false` on a layer/model excludes it but keeps it occluding ink behind it (for already-inked artwork). Ink follows fog and runs before depth blur and bloom; heavy lens blur spreads it into wide bands. Separate from the image-space `Toon` effect. `Layer3D.cube({ faces: { front: Layer.box(...) } })` faces inherit the cube's `toon`, `outline`, emissive and shadow settings unless set per face. Example: `examples/34_spatial_styling` in the engine repo.
- **3D pivots:** `anchorX/Y` choose the point held fixed during scale/rotation; changing an anchor at identity transform leaves the layer in place. Use `anchorY: 1` to keep a character's feet planted while scaling.
-
-With MSAA enabled, geometry ink shades the original color/depth/normal samples and then resolves color. Detecting contours only after the scene resolves loses subpixel coverage, especially where two outlined surfaces meet. Lens blur receives a separate nearest-sample depth resolve; normals and depths are never color-averaged for ink detection. Already-inked character artwork can remain excluded without losing occlusion. See `examples/34_spatial_styling` in the engine repository for daylight and firelit native scenes using these controls.
-
-Custom `Layer3D.cube({ faces: { front: Layer.box(...) } })` artwork inherits the cube's surface settings (including `toon`, `outline`, emissive and shadow casting), while explicit face settings take precedence. For delicate illustrated scenes, start near a one-pixel outline at the export height and use moderate lens blur: heavy defocus can spread a dark contour into a wide band on distant architecture.
- **Fog** fades to `fog.color` exactly, so set it to the composition background for a seamless horizon.
- **Models:** glTF materials bring base color, normal, metallic-roughness, occlusion and emissive maps; OBJ (`map_Kd`, `norm` in the `.mtl`) and FBX bring diffuse and normal maps, looked up next to the model. Textures can be PNG, JPEG, WebP, GIF, TIFF, AVIF or Basis KTX2 (ETC1S/UASTC, transcoded offline to RGBA8); TGA, PSD and DDS are skipped with a warning. Draco and meshopt-compressed glTF geometry is decoded by the asynchronous compositor loader; individual maps retain their own UV sets and texture transforms. glTF morph weights animate on the GPU before skinning. Unknown required glTF extensions fail clearly. Vertex colors (VOX, PLY, OFF, glTF `COLOR_0`) multiply the base color.
- **Model orientation:** the world is y-down, so a y-up model (most glTF, OBJ and FBX files) needs `rotateX: 180` to stand upright.
-- **Planar reflective floor:** `floor: { y, color, reflectivity, roughness, fadeDistance, opacity }` renders an exact mirrored-camera reflection pass with subterranean fragment clipping, 2-pass anisotropic roughness blur ($\sigma_y \approx 3.5 \sigma_x$ along the reflection axis), Schlick Fresnel grazing angle boost, linear distance fade, and HDR radiance bloom output.
+- **Reflective floor:** `floor: { y, color, reflectivity, roughness, fadeDistance, opacity }` mirrors the scene; `roughness` blurs the reflection, which also fades with distance and strengthens at grazing angles.
- `emissive` / `emissiveIntensity` / `exposure` animate like any prop (`.keys("emissiveIntensity", …)`).
- **Transparent 3D meshes:** glTF `BLEND` materials and meshes with reduced opacity draw after opaque scene items, sorted back to front by each mesh's bounds center without writing depth. This is an object-level approximation: intersecting or self-overlapping meshes cannot always sort correctly; translucent flat layers and glass use separate rendering paths.
- **Glass:** `material: "glass" | "acrylic" | "frosted"` on any Layer3D primitive, extruded text (`Layer3D.extrudedText`) or model refracts whatever is behind it on screen — the video, 2D layers, particles — with a rainbow fringe (`dispersion`, default 0.04), bend strength `thickness` (px, default 80) and `ior` (1.5). `color` tints the glass (deeper toward the edges); `frosted` blurs by `roughness`. Glass needs no environment: it draws its own studio reflections, and against a dark grade it reads best — skip `Lighting.*` rigs for glass-only scenes (their environment washes glass out). Glass shows only 2D content and opaque 3D drawn before it, not other glass.
@@ -583,12 +575,11 @@ Layer.vfx({ effectType: "Aurora", width: W, height: H, colorStart: "#2bff88", co
1. **Local Keyframe Coordinates:** Keyframes are strictly relative to the node's own timeline window (`0` = node appearance). Never offset keyframe frames by the parent's `startFrame`.
2. **Coordinate Overrides:** Animating `y` overrides the node's layout `y`. If a node is placed at `y: 400`, animate `fromTo("y", 440, 400)`, NOT `fromTo("y", 40, 0)`.
3. **No String Styles for Borders:** Use `borderColor` and `borderWidth`. CSS `border: "1px solid red"` is silently ignored.
-4. **Font Registration is Mandatory:** In headless WebGPU, system fonts do not exist. Every font must be registered via `FontManager.register()` and listed in `comp.fonts`. Emoji need a color emoji font too: framefields ships none, so register one with `FontManager.registerEmojiFont("assets/fonts/NotoColorEmoji.ttf")` (a CBDT/CBLC bitmap font such as Noto Color Emoji). Without it exports draw nothing for emoji.
+4. **Font Registration is Mandatory:** In headless WebGPU, system fonts do not exist. Register every font with `FontManager.register()` before building text layers. Emoji need a color emoji font too: framefields ships none, so register one with `FontManager.registerEmojiFont("assets/fonts/NotoColorEmoji.ttf")` (a CBDT/CBLC bitmap font such as Noto Color Emoji). Without it exports draw nothing for emoji.
5. **Integer Frames Only:** Keyframe frames, start frames, and durations must be integers. Decimal frames cause schema validation errors.
-6. **Relative vs. Absolute:** Providing `x` or `y` without `position: "relative"` turns the node into an absolute-positioned layer removed from flex flow.
+6. **`x`/`y` mean absolute:** a node with `x` or `y` and no `position` is absolutely positioned (out of flex flow), relative to its parent's content box.
7. **Audio Layer Duration:** Every `Layer.audio()` must be assigned `durationFrames` to prevent audio truncation in headless rendering.
-8. **Premultiplied Alpha:** Alpha shaders operate with premultiplied alpha. Never use `"src-alpha"` factor in custom blends.
-9. **Lint before rendering:** `comp.lint()` lists colors/gradients that would draw transparent, low-contrast text, off-canvas layers, shadow settings that do nothing and `roughness`/`metallic` without an environment. `renderVideo({ qa: true })` includes these findings.
-10. **Lottie vs. Image Layers:** Use `Layer.lottie("file.json" | "file.lottie", { width, height, fit })` for Lottie vector animations. Never pass `.json` or `.lottie` to `Layer.image()`, which only decodes raster formats and throws/warns if given a vector animation.
-11. **AI-generated media are assets, not build steps:** Images, clips, music or voice made with `ai` (from `framefields`) are generated once by a separate script into `assets/generated/` and loaded like any other file. Never call `ai` from `buildFilm()` or a scene function: it would spend money and change the film on every render, preview and test. The `framefields` skill (section 6) covers the key, the script and the model catalog.
-12. **Zooming into flat layers stays sharp:** text, shapes, images and SVGs rasterize at their scale on the canvas (up to 4×), so a camera push or a parent at `scale: 2` keeps glyphs and edges crisp. A leaf keeps its layout-size raster, and softens when magnified, if it is 3D or deflickered, is media with `effects`/`crop`, or carries an effect other than `LayerStyle` or a Gaussian/box `Blur`.
+8. **Lint before rendering:** `comp.lint()` lists colors/gradients that would draw transparent, low-contrast text, off-canvas layers, shadow settings that do nothing and `roughness`/`metallic` without an environment. `renderVideo({ qa: true })` includes these findings.
+9. **Lottie vs. Image Layers:** Use `Layer.lottie("file.json" | "file.lottie", { width, height, fit })` for Lottie vector animations. Never pass `.json` or `.lottie` to `Layer.image()`, which only decodes raster formats and throws/warns if given a vector animation.
+10. **AI-generated media are assets, not build steps:** Images, clips, music or voice made with `ai` (from `framefields`) are generated once by a separate script into `assets/generated/` and loaded like any other file. Never call `ai` from `buildFilm()` or a scene function: it would spend money and change the film on every render, preview and test. The `framefields` skill (section 6) covers the key, the script and the model catalog.
+11. **Zooming into flat layers stays sharp:** text, shapes, images and SVGs rasterize at their scale on the canvas (up to 4×), so a camera push or a parent at `scale: 2` keeps glyphs and edges crisp. A leaf keeps its layout-size raster, and softens when magnified, if it is 3D or deflickered, is media with `effects`/`crop`, or carries an effect other than `LayerStyle` or a Gaussian/box `Blur`.
diff --git a/plugins/framefields/skills/framefields-effects/SKILL.md b/plugins/framefields/skills/framefields-effects/SKILL.md
index f99891c2..7deaba05 100644
--- a/plugins/framefields/skills/framefields-effects/SKILL.md
+++ b/plugins/framefields/skills/framefields-effects/SKILL.md
@@ -9,20 +9,18 @@ description: Apply, configure, and modulate WebGPU post-processing shaders, styl
Import everything from the [`framefields`](https://www.npmjs.com/package/framefields) npm package. If the project doesn't have framefields set up yet, follow the `framefields` skill first (install, project scaffold, first render).
## Overview
-`framefields` features a native WebGPU shader execution pipeline for 2D VFX, tonal grading, cinematic lens simulation, spatial relighting, and real-time neural vision conditioning.
+Effects are typed `Effect` classes (grading, lens, texture, stylize, keying, temporal). Every prop takes a static value or a `Signal`.
-Effects in framefields are strongly typed `Effect` subclasses whose uniform properties can be driven by static values, time-varying keyframes, reactive `Signal` instances, or audio extraction pipelines.
-
-See [references/effects-catalog.md](references/effects-catalog.md) for the generated prop-level catalog, defaults, and type bounds.
+**Before setting a prop, look it up in [references/effects-catalog.md](references/effects-catalog.md)**: the generated list of every class with its props, defaults and ranges. Scales differ between effects, and a value on the wrong scale renders as nothing.
---
## Attaching Effects
-There are 4 main attachment modes in the engine:
+Four ways to attach effects:
-### 1. Layer-Level Effect Pipeline
-Attach one or more effects to any layer (`box`, `flex`, `shape`, `text`, `media`) directly via `.withEffect(effect)` or `.withEffects([...])`:
+### 1. A layer (`withEffect` / `withEffects`)
+Any layer (`box`, `flex`, `shape`, `text`, `media`):
```typescript
import { Layer, Curves, Vignette, Blur, Pixelate } from "framefields";
@@ -32,33 +30,27 @@ const videoLayer = Layer.video("assets/footage.mp4", { fit: "cover" })
.withEffect(new Curves({
master: [{ x: 0, y: 0.05 }, { x: 0.5, y: 0.52 }, { x: 1, y: 0.95 }]
}))
- .withEffect(new Vignette({ strength: 0.4, radius: 0.85, softness: 0.6 }))
+ .withEffect(new Vignette({ strength: 40, radius: 0.85, softness: 0.6 }))
.withEffect(new Blur({ strength: 8, blurType: "Gaussian" }));
// Styled container box with blur
const cardLayer = Layer.box({ width: 400, height: 300, background: "#1e1e24" })
- .withEffect(new Blur({ radius: 12 }));
+ .withEffect(new Blur({ strength: 12 }));
// Kinetic text with pixelation
const titleLayer = Layer.text("CYBERPUNK", { fontSize: 72 })
.withEffect(new Pixelate({ size: 8 }));
```
-### 2. Whole-Composition Master Emulsion
-Apply an overarching post-processing grade or film emulsion across all rendered layers:
+### 2. The whole composition (`comp.apply`)
+A grade or grain over everything rendered:
```typescript
import { Composition, FilmGrain, ColorBalance } from "framefields";
-const comp = new Composition({ width: 1920, height: 1080, fps: 30 });
+const comp = new Composition({ width: 1920, height: 1080, fps: 30, durationMs: 10_000 });
// Shared organic 35mm grain applied across titles, background video, and vector graphics
-comp.apply(new FilmGrain({
- strength: 0.06,
- size: 1.5,
- monochrome: true,
- animated: true,
- speed: 1.0,
-}));
+comp.apply(new FilmGrain({ strength: 18, size: 1.5, monochrome: true }));
comp.apply(new ColorBalance({
shadows: { cyanRed: 4, yellowBlue: -6 },
@@ -67,8 +59,8 @@ comp.apply(new ColorBalance({
}));
```
-### 3. Spatial & Tracked Sections (`comp.section` / `Layer.section`)
-Isolate a sub-region of a plate or canvas to apply localized effects:
+### 3. A region (`comp.section` / `Layer.section`)
+Effects inside a rectangle (or a tracked object) of a plate:
```typescript
// Box blur on a tracked object or explicit bounding rectangle
const blurredPlate = comp.section({
@@ -82,14 +74,14 @@ const blurredPlate = comp.section({
});
```
-### 4. Fluid Fluent Media Chains (`Media`)
-Process clips outside a layout tree before mounting or exporting:
+### 4. Media chains (`Media`)
+Process a clip outside the layout tree:
```typescript
import { Media, ApplyLUT, Crop } from "framefields";
const clip = Media.video("assets/raw_log.mp4")
.apply(new ApplyLUT({ lutUrl: "assets/luts/cinematic.cube", intensity: 1.0 }))
- .apply(new Crop({ cropType: "rectangle", topPercentage: 10, heightPercentage: 80 }));
+ .apply(new Crop({ cropType: "rect", topPercentage: 10, heightPercentage: 80 }));
const pngBuffer = await clip.renderFrame({ atMs: 1500 });
```
@@ -132,7 +124,7 @@ const pngBuffer = await clip.renderFrame({ atMs: 1500 });
### 4. Matte, Keying & Edge Operations
- **`ColorKey`**: Studio greenscreen/bluescreen keyer with spill suppression and smoothness controls.
-- **`Crop`**: Rectangular, circular, or arbitrary polygon path cropping with corner rounding.
+- **`Crop`**: `cropType: "rect"` (percent edges, `roundness` for rounded or circular corners) or `"path"` (`pathPoints` polygon); `mode: "rest"` keeps the outside instead.
### 5. Stylize Looks (`Styles.*`)
@@ -146,7 +138,7 @@ The effects behind them, for finer control:
- **`Dither`**: `bayer` / `noise` / `halftone`; 1-bit duotone (`dark` / `light`) or per-channel `levels`.
- **`Ascii`**: glyphs by brightness; `colorMode: "mono" | "source" | "green"`, `cellSize`, `fg` / `bg`, `invert`.
- **`Toon`**: brightness bands plus Sobel ink lines (`edgeColor`, `edgeWidth`, `edgeThreshold`).
-- **Geometry outlines for 3D:** use `Layer.environment(..., { outlines: { width: 2, referenceHeight: 1080, color: "#16131c", creaseAngle: 45 } })`. These use depth and surface normals rather than image contrast, ignore painted textures and lighting boundaries, follow scene fog, and render before camera depth blur and bloom. A layer/model with `outline: false` still occludes ink behind it. `material: "toon"` plus `toon: { shadowColor, lightColor, threshold, softness, diffuse }` controls actual surface lighting, including colored lights and cast shadows. These scene/material capabilities are independent of the 2D `Toon` effect and do not change the default physical look; see `framefields-compose` for defaults and ranges.
+- **3D ink and cel shading** are scene features, not this image effect: `Layer.environment(..., { outlines })` and `material: "toon"` (see `framefields-compose`, *3D Look*).
- **`RGBSplit`**: chromatic aberration along `angle` or `radial`.
- **`CRT`**: curvature, scanlines, aperture mask, noise, flicker, vignette; `tracking` and `chroma` give VHS wobble and colour bleed.
- **`Painterly`**: Kuwahara `oil` / `watercolor` (pigment edges, paper grain).
@@ -166,17 +158,13 @@ Cutouts, subject mattes, tracked boxes, pose, smart re-framing, subject outlines
## Reactive Signal Modulation
-Uniforms on any `Effect` accept reactive `Signal` instances instead of static values. When the signal changes, the GPU uniform buffer updates automatically without rebuilding the pipeline:
+Any numeric prop takes a `Signal` (audio envelopes, physics impacts, vision bounds, `sineSignal`), sampled every frame:
```typescript
-import { Layer, Blur, sineSignal, computed } from "framefields";
+import { Layer, Blur, sineSignal } from "framefields";
// Oscillating breath blur
-const blurSignal = sineSignal({
- frequencyHz: 0.5,
- min: 0,
- max: 20
-});
+const blurSignal = sineSignal({ frequency: 0.5, min: 0, max: 20 });
const layer = Layer.image("assets/bg.jpg")
.withEffect(new Blur({
@@ -186,6 +174,7 @@ const layer = Layer.image("assets/bg.jpg")
```
### Best Practices:
-1. **Emulsion Restraint:** Keep `FilmGrain` (`0.04–0.08`) and `Vignette` (`0.2–0.45`) subtle. Over-filtering looks amateurish.
-2. **Order Matters:** Place tonal grading (`Curves`, `ColorBalance`) before lens optics (`Blur`, `DepthOfField`), and apply grain (`FilmGrain`) as the outermost layer.
-3. **No Redundant Shaders:** For static image exports, set `animated: false` on `FilmGrain` to preserve deterministic static renders.
+1. **Check the prop's scale in the catalog before picking a number.** Scales differ per effect: `FilmGrain` and `Vignette` `strength` run 0–100 (defaults 15 and 50), `Blur` `strength` 0–100, while `Blur` `radius` is the 0–1 size of a *partial* blur region, not the blur amount. A value on the wrong scale renders as nothing, without an error.
+2. **Emulsion restraint:** keep `FilmGrain` around 10–25 and `Vignette` around 25–45. Over-filtering looks amateurish.
+3. **Order matters:** Place tonal grading (`Curves`, `ColorBalance`) before lens optics (`Blur`, `DepthOfField`), and apply grain (`FilmGrain`) as the outermost layer.
+4. **Stills:** set `animated: false` on `FilmGrain` so the grain does not change between frames of a held image.
diff --git a/plugins/framefields/skills/framefields-effects/references/effects-catalog.md b/plugins/framefields/skills/framefields-effects/references/effects-catalog.md
index 837292ad..86fec1d8 100644
--- a/plugins/framefields/skills/framefields-effects/references/effects-catalog.md
+++ b/plugins/framefields/skills/framefields-effects/references/effects-catalog.md
@@ -3,7 +3,7 @@
> Generated by `pnpm run sync:effects-catalog` from the node schemas (via `pnpm run generate:effects`) and `packages/framefields/src/effects/classes.ts`.
> Do not edit by hand — a stale catalog fails `pnpm run check:plugins`.
-46 effect classes are available from the package root and the `/effects` subpath:
+67 effect classes are available from the package root and the `/effects` subpath:
```ts
import { Blur, Curves, FilmGrain } from "framefields";
@@ -13,7 +13,7 @@ import { Blur, Curves, FilmGrain } from "framefields/effects";
Attach one with `layer.withEffect(effect)`, `layer.withEffects([...])`, `comp.apply(effect)`
for a whole composition, `new Media(comp.toVirtualMedia()).apply(effect)` inside a media chain,
or `comp.section({ effects: [...] })` for a spatial or tracked region. Every prop is an
-`EffectProp<T>`: a plain value, a reactive signal, or a function hook — see `sections.md`.
+`EffectProp<T>`: a plain value, a reactive signal, or a function hook.
Defaults come from the node's schema, or from the constructor for classes that are still
hand-written; a `—` means the value is computed (often track-dependent) or defaulted downstream.
@@ -67,6 +67,27 @@ Set `FRAMEFIELDS_STRICT_PROPS=1` to make an unknown prop or an out-of-range valu
| `Toon` | `Toon` | `levels`, `edgeThreshold`, `edgeWidth`, `edgeColor`, `saturation` |
| `Trails` | `Trails` | `decay`, `mode`, `zoom`, `rotation`, `offsetX`, `offsetY`, `hueShift`, `warmup` |
| `Vignette` | `Vignette` | `strength`, `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+| `Levels` | `Levels` | `master`, `red`, `green`, `blue` |
+| `FilmGrain` | `FilmGrain` | `strength`, `size`, `monochrome`, `animated`, `speed`, `shadows`, `midtones`, `highlights` |
+| `AudioSignalExtractor` | `AudioSignalExtractor` | `extractionMode`, `attackMs`, `releaseMs`, `sensitivity`, `noiseFloorDb`, `dynamicRangeDb`, `autoRange`, `smoothing`, `curve`, `beatThreshold`, `beatDecayMs`, `previewMode`, `nodeId` |
+| `Curves` | `Curves` | `curveType`, `master`, `red`, `green`, `blue`, `hueVsHue`, `hueVsSat`, `lumVsSat`, `satVsSat` |
+| `SelectiveColor` | `SelectiveColor` | `method`, `reds`, `yellows`, `greens`, `cyans`, `blues`, `magentas`, `whites`, `neutrals`, `blacks` |
+| `GradientMap` | `GradientMap` | `stops`, `smooth`, `dither`, `opacity` |
+| `ShadowsHighlights` | `ShadowsHighlights` | `shadowAmount`, `shadowTonalWidth`, `shadowRadius`, `highlightAmount`, `highlightTonalWidth`, `highlightRadius`, `colorCorrection`, `midtoneContrast` |
+| `ApplyLUT` | `ApplyLUT` | `lutUrl`, `intensity` |
+| `UnsharpMask` | `UnsharpMask` | `amount`, `radius`, `threshold` |
+| `HighPass` | `HighPass` | `radius`, `contrastBoost`, `monochrome` |
+| `HalftoneScreen` | `HalftoneScreen` | `mode`, `dotShape`, `frequency`, `angle`, `contrast`, `dotColor`, `paperColor`, `smooth`, `invert`, `cyanAngle`, `magentaAngle`, `yellowAngle`, `blackAngle`, `opacity` |
+| `TileOffset` | `TileOffset` | `offsetX`, `offsetY`, `wrap`, `edgeMode` |
+| `MotionBlur` | `MotionBlur` | `shutterAngle`, `samples`, `maxVelocity`, `shutterCurve`, `depthAware` |
+| `SSAO` | `SSAO` | `radius`, `bias`, `intensity`, `kernelSamples`, `blurRadius` |
+| `PBRGlass` | `PBRGlass` | `ior`, `roughness`, `transmission`, `dispersion`, `fresnelPower`, `tintColor` |
+| `DepthOfField` | `DepthOfField` | `focusDistance`, `focalLength`, `aperture`, `maxBlur`, `quality` |
+| `Crop` | `Crop` | `cropType`, `leftPercentage`, `topPercentage`, `widthPercentage`, `heightPercentage`, `roundness`, `pathPoints`, `mode` |
+| `Vision` | `Vision` | `enableDetection`, `enableSegmentation`, `enablePose`, `enableMatte`, `classes`, `confidence`, `variant`, `mode`, `matteSource`, `maxMissedFrames`, `modelsDir`, `baseUrl`, `maskThreshold`, `featherRadius`, `keyBackground`, `backgroundKeyThreshold`, `visionBundle` |
+| `Relight3D` | `Relight3D` | `lightType`, `intensity`, `lightPosX`, `lightPosY`, `lightPosZ`, `lightRadius`, `spotConeAngle`, `specularRoughness`, `specularStrength`, `metallic`, `ambientIntensity`, `volumetricDensity`, `depthScale`, `depthInvert`, `lightColor`, `ambientColor`, `normalMap` |
+| `TemporalDeflicker` | `TemporalDeflicker` | `blendWeight`, `disocclusionThreshold`, `maxMotionPixels`, `scale`, `windowSize` |
+| `Modulate` | `Modulate` | `hue`, `brightness`, `contrast`, `exposure`, `saturation`, `sepia` |
## Prop defaults
@@ -871,6 +892,393 @@ new Vignette({ strength: 50, radius: 1, softness: 0.5 });
| `centerX` | `EffectProp<number>` | `0.5` | Range 0 to 1. The X coordinate of the vignette center. |
| `centerY` | `EffectProp<number>` | `0.5` | Range 0 to 1. The Y coordinate of the vignette center. |
+### Levels
+
+```ts
+import { Levels } from "framefields/effects";
+
+new Levels({ /* props */ });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `master` | `LevelChannel` | `{ ...defaultChannel }` |
+| `red` | `LevelChannel` | `{ ...defaultChannel }` |
+| `green` | `LevelChannel` | `{ ...defaultChannel }` |
+| `blue` | `LevelChannel` | `{ ...defaultChannel }` |
+
+### FilmGrain
+
+```ts
+import { FilmGrain } from "framefields/effects";
+
+new FilmGrain({ strength: 15, size: 1.5, monochrome: true });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `strength` | `EffectProp<number>` | `15` |
+| `size` | `EffectProp<number>` | `1.5` |
+| `monochrome` | `boolean` | `true` |
+| `animated` | `boolean` | `true` |
+| `speed` | `EffectProp<number>` | `50` |
+| `shadows` | `EffectProp<number>` | `0.2` |
+| `midtones` | `EffectProp<number>` | `1.0` |
+| `highlights` | `EffectProp<number>` | `0.2` |
+
+### AudioSignalExtractor
+
+```ts
+import { AudioSignalExtractor } from "framefields/effects";
+
+new AudioSignalExtractor({ extractionMode: "rms_envelope", attackMs: 10, releaseMs: 120 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `extractionMode` | `\| "rms_envelope" \| "transient_beat" \| "sub_bass" \| "bass" \| "mid" \| "high" \| "spectral_flux"` | `"rms_envelope"` |
+| `attackMs` | `number` | `10` |
+| `releaseMs` | `number` | `120` |
+| `sensitivity` | `number` | `1.0` |
+| `noiseFloorDb` | `number` | `-48` |
+| `dynamicRangeDb` | `number` | `48` |
+| `autoRange` | `boolean` | `true` |
+| `smoothing` | `number` | `0.15` |
+| `curve` | `"linear" \| "exponential" \| "logarithmic" \| "square" \| "smoothstep"` | `"linear"` |
+| `beatThreshold` | `number` | `0.08` |
+| `beatDecayMs` | `number` | `80` |
+| `previewMode` | `"waveform" \| "envelope" \| "beat_markers" \| "spectrum"` | `"envelope"` |
+| `nodeId` | `string` | `"audio_extractor"` |
+
+### Curves
+
+```ts
+import { Curves } from "framefields/effects";
+
+new Curves({ curveType: "rgb" });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `curveType` | `"rgb" \| "hue-vs-hue" \| "hue-vs-sat" \| "lum-vs-sat" \| "sat-vs-sat"` | `"rgb"` |
+| `master` | `CurvesChannelPoint[]` | — |
+| `red` | `CurvesChannelPoint[]` | — |
+| `green` | `CurvesChannelPoint[]` | — |
+| `blue` | `CurvesChannelPoint[]` | — |
+| `hueVsHue` | `CurvesChannelPoint[]` | — |
+| `hueVsSat` | `CurvesChannelPoint[]` | — |
+| `lumVsSat` | `CurvesChannelPoint[]` | — |
+| `satVsSat` | `CurvesChannelPoint[]` | — |
+
+### SelectiveColor
+
+```ts
+import { SelectiveColor } from "framefields/effects";
+
+new SelectiveColor({ method: "Relative" });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `method` | `"Relative" \| "Absolute"` | `"Relative"` |
+| `reds` | `Partial<SelectiveColorAdjustment>` | — |
+| `yellows` | `Partial<SelectiveColorAdjustment>` | — |
+| `greens` | `Partial<SelectiveColorAdjustment>` | — |
+| `cyans` | `Partial<SelectiveColorAdjustment>` | — |
+| `blues` | `Partial<SelectiveColorAdjustment>` | — |
+| `magentas` | `Partial<SelectiveColorAdjustment>` | — |
+| `whites` | `Partial<SelectiveColorAdjustment>` | — |
+| `neutrals` | `Partial<SelectiveColorAdjustment>` | — |
+| `blacks` | `Partial<SelectiveColorAdjustment>` | — |
+
+### GradientMap
+
+```ts
+import { GradientMap } from "framefields/effects";
+
+new GradientMap({ stops: defaultStops, smooth: true, dither: true });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `stops` | `GradientMapStop[]` | `defaultStops` |
+| `smooth` | `boolean` | `true` |
+| `dither` | `boolean` | `true` |
+| `opacity` | `EffectProp<number>` | `1.0` |
+
+### ShadowsHighlights
+
+```ts
+import { ShadowsHighlights } from "framefields/effects";
+
+new ShadowsHighlights({ shadowAmount: 0, shadowTonalWidth: 50, shadowRadius: 30 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `shadowAmount` | `EffectProp<number>` | `0` |
+| `shadowTonalWidth` | `EffectProp<number>` | `50` |
+| `shadowRadius` | `EffectProp<number>` | `30` |
+| `highlightAmount` | `EffectProp<number>` | `0` |
+| `highlightTonalWidth` | `EffectProp<number>` | `50` |
+| `highlightRadius` | `EffectProp<number>` | `30` |
+| `colorCorrection` | `EffectProp<number>` | `0` |
+| `midtoneContrast` | `EffectProp<number>` | `0` |
+
+### ApplyLUT
+
+```ts
+import { ApplyLUT } from "framefields/effects";
+
+new ApplyLUT({ lutUrl: "", intensity: 1.0 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `lutUrl` | `string` | `""` |
+| `intensity` | `EffectProp<number>` | `1.0` |
+
+### UnsharpMask
+
+```ts
+import { UnsharpMask } from "framefields/effects";
+
+new UnsharpMask({ amount: 100, radius: 1.5, threshold: 3 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `amount` | `EffectProp<number>` | `100` |
+| `radius` | `EffectProp<number>` | `1.5` |
+| `threshold` | `EffectProp<number>` | `3` |
+
+### HighPass
+
+```ts
+import { HighPass } from "framefields/effects";
+
+new HighPass({ radius: 3.0, contrastBoost: 1.0, monochrome: true });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `radius` | `EffectProp<number>` | `3.0` |
+| `contrastBoost` | `EffectProp<number>` | `1.0` |
+| `monochrome` | `boolean` | `true` |
+
+### HalftoneScreen
+
+```ts
+import { HalftoneScreen } from "framefields/effects";
+
+new HalftoneScreen({ mode: "Monochrome", dotShape: "Circle", frequency: 30 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `mode` | `HalftoneMode` | `"Monochrome"` |
+| `dotShape` | `HalftoneDotShape` | `"Circle"` |
+| `frequency` | `EffectProp<number>` | `30` |
+| `angle` | `EffectProp<number>` | `45` |
+| `contrast` | `EffectProp<number>` | `1.0` |
+| `dotColor` | `string` | `"#000000"` |
+| `paperColor` | `string` | `"#ffffff"` |
+| `smooth` | `boolean` | `true` |
+| `invert` | `boolean` | `false` |
+| `cyanAngle` | `EffectProp<number>` | `15` |
+| `magentaAngle` | `EffectProp<number>` | `75` |
+| `yellowAngle` | `EffectProp<number>` | `0` |
+| `blackAngle` | `EffectProp<number>` | `45` |
+| `opacity` | `EffectProp<number>` | `1.0` |
+
+### TileOffset
+
+```ts
+import { TileOffset } from "framefields/effects";
+
+new TileOffset({ offsetX: 0, offsetY: 0, wrap: true });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `offsetX` | `EffectProp<number>` | `0` |
+| `offsetY` | `EffectProp<number>` | `0` |
+| `wrap` | `boolean` | `true` |
+| `edgeMode` | `TileOffsetEdgeMode` | `"wrap"` |
+
+### MotionBlur
+
+```ts
+import { MotionBlur } from "framefields/effects";
+
+new MotionBlur({ shutterAngle: 180, samples: 16, maxVelocity: 64 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `shutterAngle` | `EffectProp<number>` | `180` |
+| `samples` | `EffectProp<number>` | `16` |
+| `maxVelocity` | `EffectProp<number>` | `64` |
+| `shutterCurve` | `"box" \| "gaussian" \| "triangle"` | `"gaussian"` |
+| `depthAware` | `boolean` | `true` |
+
+### SSAO
+
+```ts
+import { SSAO } from "framefields/effects";
+
+new SSAO({ radius: 45, bias: 0.025, intensity: 1.5 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `radius` | `EffectProp<number>` | `45` |
+| `bias` | `EffectProp<number>` | `0.025` |
+| `intensity` | `EffectProp<number>` | `1.5` |
+| `kernelSamples` | `EffectProp<number>` | `16` |
+| `blurRadius` | `EffectProp<number>` | `4` |
+
+### PBRGlass
+
+```ts
+import { PBRGlass } from "framefields/effects";
+
+new PBRGlass({ ior: 1.49, roughness: 0.15, transmission: 0.92 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `ior` | `EffectProp<number>` | `1.49` |
+| `roughness` | `EffectProp<number>` | `0.15` |
+| `transmission` | `EffectProp<number>` | `0.92` |
+| `dispersion` | `EffectProp<number>` | `0.015` |
+| `fresnelPower` | `EffectProp<number>` | `5.0` |
+| `tintColor` | `EffectProp<string>` | `"#ffffff"` |
+
+### DepthOfField
+
+```ts
+import { DepthOfField } from "framefields/effects";
+
+new DepthOfField({ focusDistance: 500, focalLength: 50, aperture: 2.8 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `focusDistance` | `EffectProp<number>` | `500` |
+| `focalLength` | `EffectProp<number>` | `50` |
+| `aperture` | `EffectProp<number>` | `2.8` |
+| `maxBlur` | `EffectProp<number>` | `16` |
+| `quality` | `"low" \| "medium" \| "high" \| "ultra"` | `"high"` |
+
+### Crop
+
+```ts
+import { Crop } from "framefields/effects";
+
+new Crop({ cropType: "rect", leftPercentage: 0, topPercentage: 0 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `cropType` | `"rect" \| "path"` | `"rect"` |
+| `leftPercentage` | `EffectProp<number>` | `0` |
+| `topPercentage` | `EffectProp<number>` | `0` |
+| `widthPercentage` | `EffectProp<number>` | `100` |
+| `heightPercentage` | `EffectProp<number>` | `100` |
+| `roundness` | `EffectProp<number>` | `0` |
+| `pathPoints` | `{ x: number; y: number }[]` | — |
+| `mode` | `"cropped" \| "rest"` | — |
+
+### Vision
+
+```ts
+import { Vision } from "framefields/effects";
+
+new Vision({ confidence: 0.3, variant: "s", mode: "passthrough" });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `enableDetection` | `boolean` | — |
+| `enableSegmentation` | `boolean` | — |
+| `enablePose` | `boolean` | — |
+| `enableMatte` | `boolean` | — |
+| `classes` | `readonly string[]` | — |
+| `confidence` | `number` | `0.3` |
+| `variant` | `"t" \| "s" \| "m"` | `"s"` |
+| `mode` | `\| "passthrough" \| "mask" \| "matte" \| "crop" \| "skeleton" \| "boxes" \| "tracking" \| "depth"` | `"passthrough"` |
+| `matteSource` | `"instance" \| "selfie"` | `"instance"` |
+| `maxMissedFrames` | `number` | — |
+| `modelsDir` | `string` | — |
+| `baseUrl` | `string` | — |
+| `maskThreshold` | `number` | — |
+| `featherRadius` | `number` | — |
+| `keyBackground` | `boolean` | — |
+| `backgroundKeyThreshold` | `number` | — |
+| `visionBundle` | `unknown` | — |
+
+### Relight3D
+
+```ts
+import { Relight3D } from "framefields/effects";
+
+new Relight3D({ lightType: "Point", intensity: 1.0, lightPosX: 0.5 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `lightType` | `"Point" \| "Spot" \| "Directional" \| "Rim"` | `"Point"` |
+| `intensity` | `EffectProp<number>` | `1.0` |
+| `lightPosX` | `EffectProp<number>` | `0.5` |
+| `lightPosY` | `EffectProp<number>` | `0.5` |
+| `lightPosZ` | `EffectProp<number>` | `0.3` |
+| `lightRadius` | `EffectProp<number>` | `0.8` |
+| `spotConeAngle` | `EffectProp<number>` | `45` |
+| `specularRoughness` | `EffectProp<number>` | `0.35` |
+| `specularStrength` | `EffectProp<number>` | `0.7` |
+| `metallic` | `EffectProp<number>` | `0.0` |
+| `ambientIntensity` | `EffectProp<number>` | `0.4` |
+| `volumetricDensity` | `EffectProp<number>` | `0.2` |
+| `depthScale` | `EffectProp<number>` | `1.0` |
+| `depthInvert` | `boolean` | `false` |
+| `lightColor` | `string` | `"#ffffff"` |
+| `ambientColor` | `string` | `"#ffffff"` |
+| `normalMap` | `unknown` | — |
+
+### TemporalDeflicker
+
+```ts
+import { TemporalDeflicker } from "framefields/effects";
+
+new TemporalDeflicker({ blendWeight: 0.35, disocclusionThreshold: 0.15, maxMotionPixels: 64.0 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `blendWeight` | `EffectProp<number>` | `0.35` |
+| `disocclusionThreshold` | `EffectProp<number>` | `0.15` |
+| `maxMotionPixels` | `EffectProp<number>` | `64.0` |
+| `scale` | `number` | `0.5` |
+| `windowSize` | `number` | `2` |
+
+### Modulate
+
+```ts
+import { Modulate } from "framefields/effects";
+
+new Modulate({ hue: 0, brightness: 1.0, contrast: 1.0 });
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `hue` | `EffectProp<number>` | `0` |
+| `brightness` | `EffectProp<number>` | `1.0` |
+| `contrast` | `EffectProp<number>` | `1.0` |
+| `exposure` | `EffectProp<number>` | `0.0` |
+| `saturation` | `EffectProp<number>` | `1.0` |
+| `sepia` | `EffectProp<number>` | `0.0` |
+
## Node packages
Beyond these classes, the engine ships node plugins under `nodes/` (audio DSP, generators,
diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.md
index 940a6735..0392cfa4 100644
--- a/plugins/framefields/skills/framefields-render/SKILL.md
+++ b/plugins/framefields/skills/framefields-render/SKILL.md
@@ -15,7 +15,7 @@ Because video rendering is resource-intensive and native GPU pipelines run async
---
-## The 5-Step Verification Ladder
+## The Verification Ladder
Always proceed through the ladder in order. Catching a layout or timing bug at step 1 or 2 takes seconds; catching it after a 30-second 4K video render wastes minutes.
@@ -78,7 +78,6 @@ To verify easing curves, cut points, kinetic sweeps, or text wrapping without en
```typescript
import fs from "node:fs/promises";
-import { renderFrameGrid } from "framefields";
// Samples frames across the intro sweep (frames 0 to 60)
const gridPng = await comp.renderFrameGrid({
@@ -122,8 +121,8 @@ describe("Hero Scene Conformance", () => {
---
-### Step 4.5: Show the User Before Exporting (`preview`)
-When a person is in the loop, let them watch the composition before you spend time on the final render. `startPreview` serves a localhost player with the soundtrack, a timeline with the waveform, and frame stepping. The page loads the composition's own code and renders it with WebGPU in the browser, in real time: a device that can't draw every frame in time skips some, and the sound keeps its speed; the server only serves that code and the project's files. The page mixes the soundtrack itself with the export's mixer, in 2-second blocks around the playhead, each continuing the effect state of the block before (exactly the export's from the film's start; after a seek the first block warms its effects up from 2 s earlier until the background pass replaces it), so sound starts at once; the rest mixes in the background for the waveform and the master gain. It mixes in a background worker with its own GPU device, so it doesn't stall drawing. `framefieldsPreview.state()` reports `audioMixed` (blocks mixed, and how many are exact) and `audioMixer` (`worker`, `page` or `server`, the fallbacks in order). Point it at the module that builds the composition:
+### Step 5: Show the User Before Exporting (`preview`)
+When a person is in the loop, let them watch the composition before you spend time on the final render. `startPreview` serves a localhost player with the soundtrack, a timeline with the waveform, and frame stepping. The page loads the composition's own code and renders it with WebGPU in the browser, in real time: a device that can't draw every frame in time skips some, and the sound keeps its speed; the server only serves that code and the project's files. The soundtrack is the export's own mix, made in the page around the playhead, so sound starts at once. Point it at the module that builds the composition:
```typescript
import { startPreview } from "framefields";
@@ -143,27 +142,25 @@ await session.closed; // keep the process alive while the user watches
- **Point at a moment.** `#t=12.5` in the URL opens the player at 12.5 s (`#frame=750` by frame), and the address follows the playhead when it stops, so a link you give the user lands where you mean.
- **Drive it from a script, not with clicks.** If you can run JavaScript in the page (an agent browser), use `window.framefieldsPreview`: `await seek(seconds)` or `await seekFrame(n)` resolve once that frame is drawn (take the screenshot then), `play()` and `pause()` control playback, `notes()` lists the notes, and `state()` returns `{ state: "loading" | "ready" | "error", error, frame, time, playing, buffering, audio, connected, playbackFps, renderMs, meta }`. `<html data-preview="ready">` marks the first frame drawn. A hidden tab pauses playback, since browsers throttle it.
- **Show it where the user is.** `startPreview` only serves the page and returns the URL. If your app has a built-in browser, open the URL there. Otherwise give the user the link, or pass `open: true` to open their default browser (skipped when an open tab reconnects on its own). The page needs WebGPU (current Chrome, Edge or Safari).
-- **Playback runs in real time, on any device.** Play draws the frame due on the clock and skips the ones it missed, so it starts at once and the sound keeps its speed; a slow device shows fewer frames. Next to the timecode the page shows the frame rate playback reaches, apart from the film's own `fps`; `state()` reports it as `playbackFps`, and `renderMs` is how long the last frame took to draw. Paused, the page draws the exact frame under the playhead. Vision effects analyse each frame from the one drawn before it: while paused, the page analyses up to 20 s ahead so that stretch plays exactly, but past it a device that skips frames shows cutouts and tracking from the last frame it drew. Check them paused, or in the export.
-- Audio is the same mix `renderVideo` muxes (`audio: false` skips it). Playback uses the soundtrack as its clock; when a frame takes long (a video seek, a heavy shot), the picture skips ahead to catch up with the sound.
+- **Playback runs in real time.** A slow device skips frames to keep pace with the sound; `state()` reports the reached `playbackFps` and the last frame's `renderMs`. Paused, the page draws the exact frame. Vision effects analyse each frame from the one drawn before it, so check cutouts and tracking paused or in the export.
---
-### Step 5: Full Video Export (`renderVideo`)
+### Step 6: Full Video Export (`renderVideo`)
Once static frames and motion grids are verified, encode the final MP4/WebM video:
```typescript
-import path from "node:path";
-
const result = await comp.renderVideo({
outputPath: "output/final-video.mp4",
- quality: "high", // "draft" | "medium" | "high" | "lossless"
- codec: "avc", // "avc" (H.264) | "hevc" (H.265) | "vp9" | "av1"
- audioCodec: "aac",
- concurrency: 4, // Parallel frame encoding threads
+ quality: "very_high", // "very_low" | "low" | "high" | "very_high" (default)
+ codec: "h264", // "h264" (default, MP4) | "vp9" | "vp8" (WebM) | "gif"; "aac" | "mp3" | "opus" render audio only
});
+await result.cleanup?.(); // releases temporary files
+```
-// Always invoke cleanup to release temporary frame cache and file handles
-await result.cleanup?.();
+There is no HEVC or AV1 output; an unknown `codec` falls back to H.264.
+
+```typescript
```
Pass `qa: true` to have the engine check the output while it renders (see **Built-in Video QA** below) and return the findings as `result.qa`.
@@ -218,7 +215,7 @@ await stitchChunks({ chunks: ["out/chunk-0.mp4", "out/chunk-1.mp4"], audio: "out
- Names use letters, digits, `-`, `_` and `.` (at most 64). Errors name the render and field: `framefields.json: renders.teaser needs "entry"`.
- `npx framefields renders` lists them (`--json` for tools). `npx framefields check` with no argument checks every render; `npx framefields check teaser` checks one (artifacts under `output/check/<name>` when checking several).
- After adding a render, run `framefields check <name>`, then commit and push: the cloud and the dashboard read `framefields.json` from the pushed branch, and the dashboard greys out a render whose `entry` isn't on that branch.
-- Named renders need a framefields release that has them (the one after 2.11.0). With older versions, render a module path (below).
+- Named renders need framefields 2.12 or later. With older versions, render a module path (below).
## Rendering in the Cloud (`framefields render --cloud`)
@@ -265,7 +262,7 @@ try {
}
```
-Options passed to `renderCloud` override the named render's; `signal` cancels. `cloudClient()` exposes `start`, `status` and `cancel` for callers that track renders themselves. The HTTP API is `POST /v1/render` (`source`, `target`, `render`, `workers`, `max_workers`, `dry_run`, optional `name` and `title`), `GET` and `DELETE /v1/render/:id`, with `Authorization: Bearer <key>`.
+Options passed to `renderCloud` override the named render's; `signal` cancels. `cloudClient({ apiKey })` (key defaults to `FRAMEFIELDS_API_KEY`) exposes `start`, `status` and `cancel` for callers that track renders themselves. The HTTP API is `POST /v1/render` (`source`, `target`, `render`, `workers`, `max_workers`, `dry_run`, optional `name` and `title`), `GET` and `DELETE /v1/render/:id`, with `Authorization: Bearer <key>`.
### Cloud render failures
@@ -453,8 +450,8 @@ ffmpeg -i output/final-video.mp4 -af "volumedetect" -f null -
| Symptom | Root Cause | Solution |
|---|---|---|
-| Entire frame renders black | Missing font registration or `NaN` in uniform | Ensure every font used in `Layer.text` is registered via `FontManager.register()` and listed in `comp.fonts`. Verify all signal outputs are finite numbers. |
-| Media layer is invisible / blank | Bad input handle binding or zero opacity | Check that the media path exists and `opacity > 0`. If using an effect or section, ensure `fit: "cover"` and valid container dimensions. |
+| Entire frame renders black | Missing font registration or `NaN` in a signal | Register every font `Layer.text` uses with `FontManager.register()` before building layers. Check signal outputs are finite numbers. |
+| Media layer is invisible / blank | Wrong path, an LFS pointer file, or zero opacity | Check the path exists and is real media (`git lfs pull`, `framefields assets pull`), and `opacity > 0`. |
| Audio cuts out early | Missing `durationFrames` on audio layer | Explicitly assign `durationFrames: totalFrames` on `Layer.audio()`. |
| Vision cutout / mask is empty on a single `renderFrame` | Vision reads the previous rendered frame; frame 0 has none | Render two or more consecutive frames with the same `HeadlessMediaRenderer` and keep the last. `renderVideo` handles this automatically. |
| Ghosted double of the subject in a vision cutout | Frames rendered out of order (frame grid, or jumping from frame 3 to 48), so the cutout uses pixels from another frame | Verify vision layers with sequential frames or the exported MP4, not `renderFrameGrid`. |
@@ -464,5 +461,5 @@ ffmpeg -i output/final-video.mp4 -af "volumedetect" -f null -
| Encoder fails to open (`h264_rkmpp`, NVENC) | framefields < 2.2 uses the hardware encoder untested | Use framefields 2.2+, which falls back to libx264 etc., or set `FRAMEFIELDS_HW_CODECS=off`. |
| Render worker or cloud render fails | Project not render-ready (lockfile, export, LFS) | Read the `code` and `hint`; see **Cloud render failures** above and https://framefields.dev/docs/guides/render-service/ |
| Stitched video has a jump at a chunk seam | Chunks rendered with different framefields versions, settings or GPU types, or a stateful effect that reads wall-clock time | Render all chunks from one commit and one job; keep effects deterministic in the frame number. |
+| An effect shows no change | Value on the wrong scale (e.g. `Vignette` `strength: 0.4` on its 0–100 scale) | Look the prop up in the `framefields-effects` catalog. |
| Text looks misaligned or truncated | Layout node box smaller than text string | Set explicit wrapping `width` (e.g. `width: 1400`) or use `width: "fill"`. |
-| Colors appear washed out / dark edges | Unpremultiplied alpha blending | The engine operates with premultiplied alpha. Ensure custom shaders use `srcFactor: "one"`. |
diff --git a/plugins/framefields/skills/framefields-vision/SKILL.md b/plugins/framefields/skills/framefields-vision/SKILL.md
index bd0b4589..85ec0c2d 100644
--- a/plugins/framefields/skills/framefields-vision/SKILL.md
+++ b/plugins/framefields/skills/framefields-vision/SKILL.md
@@ -314,4 +314,3 @@ report.tracks; // [{ trackId, category, frames: [start, end], centerPath, … }]
| A preview of a clip outside the project shows nothing | Add its folder to `startPreview(…, { root: [process.cwd(), dir] })` |
| Renders offline or in CI | Copy the model cache, or set `FRAMEFIELDS_MODELS_BASE_URL` |
| SAM 2.1 Tiny mask loses a small object, its edges, or the subject after a cut | `sam2: { model: "small" }` |
-| Check the models themselves | `await runner.preload([...])` on a fresh `FRAMEFIELDS_MODELS_DIR`; SAM: `pnpm --filter @framefields/vision-sam test:sam2` (Tiny and Small) / `test:sam3` on a GPU machine |
diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.md
index 46098e2b..550a0842 100644
--- a/plugins/framefields/skills/framefields/SKILL.md
+++ b/plugins/framefields/skills/framefields/SKILL.md
@@ -321,7 +321,7 @@ console.log(data.images[0].url);
**The key.** Requests authenticate with an `ff_live_…` key from https://framefields.dev/dashboard/keys. For local execution, ask the user to set `FRAMEFIELDS_API_KEY` in the process environment themselves; never ask them to paste a key into chat. The script reads `process.env.FRAMEFIELDS_API_KEY` and fails with an actionable message when it is missing. Do not inspect or print environment variables or credential files, embed the key in source, or commit it. AI generation is optional and does not affect local composition and rendering. Without a key, gateway calls cannot run. Failures throw `ApiError` with the gateway's `type`: on `insufficient_credits` (status `402`) tell the user to top up at https://framefields.dev/dashboard/billing rather than retrying; `key_limit_reached` means the key's monthly cap; `rate_limited` and `too_many_inflight_requests` mean wait and retry. A `ValidationError` (`422`) lists the bad input fields in `fieldErrors`.
-**Generate once, into `assets/`, in its own script.** Generation costs money and is not deterministic, so it never runs inside `buildFilm()`, the preview, tests or the render worker. Write `src/generate.ts`, run it on purpose, download every output into `assets/generated/` (tracked in Git LFS, as above), and reference the local file from the film. Generated output URLs expire, and the worker renders from the repository.
+**Generate once, into `assets/`, in its own script.** Generation costs money and is not deterministic, so it never runs inside `buildFilm()`, the preview, tests or the render worker. Write `src/generate.ts`, run it on purpose, download every output into `assets/generated/`, pin it with `npx framefields assets add assets/generated` (or track it in Git LFS), and reference the local file from the film. Generated output URLs expire, and the worker renders from the repository.
```typescript
// src/generate.ts
diff --git a/scripts/sync-effects-catalog.mjs b/scripts/sync-effects-catalog.mjs
index f023beea..fa106831 100644
--- a/scripts/sync-effects-catalog.mjs
+++ b/scripts/sync-effects-catalog.mjs
@@ -79,7 +79,8 @@ function collectInterfaces() {
/** Brace-matched class bodies, so nested `super({ ... })` objects do not truncate the scan. */
function collectClasses() {
const classes = [];
- const re = /export class (\w+) extends Effect<(\w+)> \{/g;
+ // `Effect<Props, "Op", "domain">`, possibly wrapped over several lines.
+ const re = /export class (\w+) extends Effect<\s*(\w+Props)\b[^{]*?> \{/g;
for (const match of source.matchAll(re)) {
const start = match.index + match[0].length;
let depth = 1;
@@ -194,7 +195,7 @@ function buildCatalog() {
"or `comp.section({ effects: [...] })` for a spatial or tracked region. Every prop is an",
);
lines.push(
- "`EffectProp<T>`: a plain value, a reactive signal, or a function hook — see `sections.md`.",
+ "`EffectProp<T>`: a plain value, a reactive signal, or a function hook.",
);
lines.push("");
lines.push(