Code-first video & image, rendered natively on WebGPU.
reduce agentmd
okanaslfe76cc42e2d6
diff --git a/.agent/rules/general-information.md b/.agent/rules/general-information.mdindex e12f72cb..30d8489a 100644--- a/.agent/rules/general-information.md+++ b/.agent/rules/general-information.md@@ -49,45 +49,4 @@ Framefields is a code-first video engine on native WebGPU (Dawn) in Node, with nFonts (`assets/fonts`), `*.mp4/mp3/wav/png/jpg`, `*.onnx`, `scratch*/`, `examples/output/`, `.hermes/` and `.env*` are gitignored. Never commit them or print secrets from `.env`. Write throwaway probes and logs under a `scratch/` or `output/` dir.-- Every font in `Layer.text` must be registered with `FontManager` and declared in `fonts`. There are no system fonts headlessly.--## Engine gotchas (violations fail silently)--- Premultiplied-alpha shaders use blend `srcFactor: "one"`, never `"src-alpha"` (it squares alpha and fades go murky grey).-- WGSL: every declared storage binding must be used, or Tint optimizes it out of the layout.-- Clamp scissor rects to non-negative integers within the surface.-- Signals are class instances; never `{ ...signal }` (it loses `.get(ctx)`). A `NaN` reaching a uniform turns the whole frame black with no error.-- `CompositorProgramSchema` is `.strict()`: a new field on a node or the program must be added to `program/schema.ts` (base nodes, media nodes, and the root for `effects`) or `comp.toSpec()` fails validation even though rendering works.-- Track keyframe frames and effect frame options must be integers (e.g. `Math.round(life * 0.55)` for a computed fade-out frame), or the schema rejects the program.-- The audio extractor scales hot multi-track sums; master soundtrack layers to roughly -14 dBFS RMS yourself and keep the summed peak near 0.9.-- Procedural SFX triggers render procedural whoosh/riser/impact/downshifter/glitch on the CPU (`renderSfx`, `mixSfxInto`, `softLimit`). `atBar` is where the effect *starts*: a whoosh peaks 0.42s in, so start it ~0.21 bars before the cut.-- `withAnimation` must keep `animation` an enumerable data property so `{ ...node }` spreads keep the tracks.-- Keep `isAbsolutePositioned` symmetric between `buildYogaNode` and `readLayout` in `resolve-layout.ts`, or coordinates double-add.-- Compositor specs: audio inputs go in `config.layout` as `kind: "media"` items with `inputHandleId` and `volume`, or the headless mixer drops them. Fonts go in the top-level `"fonts"` array with relative paths. Use the live handle ID, not its label, for `inputHandleId`.-- Path text (`pathOptions`) coordinates are local to the text node's box, like any child; rotation/scale pivot on the node's anchor. Size the node to contain the path.-- Shape paths support SVG arcs (`A`/`a`); a circle is two arcs (`M c c-r A r r 0 1 1 c c+r A r r 0 1 1 c c-r`) and draws on with `trimEnd`.-- A circular window: put the plate and a `Layer.shape("ellipse", { blendMode: "mask-in" })` in a box with `background: "transparent"` (any painted background makes the box its own layer group; without one the mask cuts everything beneath).-- Do not add per-effect helpers like `blurTrackedRegion`. Extend `comp.section` / `Layer.section` instead.--## Authoring API traps--- `LayerAnimation` has no `moveX`, `moveY`, `scale`, `rotate` or `trimPath`. Use `fromTo(prop, from, to, { start, end, ease })`.-- `fadeIn` and `fadeOut` take positional args: `.fadeIn(0, 20, "power2.out")`.-- Borders are `borderColor` plus `borderWidth`. CSS `border` is silently ignored.-- Setting only `x` or `y` makes a node absolute. Use `position: "relative"` to nudge a flow child. A centered flex needs an explicit `width` (or `"fill"`).-- Keyframes are relative to the node's own window. Never add the parent's `startFrame`. Animating `y` overrides layout `y`, so animate `fromTo("y", y + 40, y)`, not to `0`.-- Valid ease bases: `none power1 power2 power3 sine circ expo back elastic bounce spring cubic hold`. There is no `power4`.-- Don't nest an opaque-background container inside a `tilt3D`/`rotateX`/`perspective` container. Make one unified card.-- Every font in `Layer.text` must be registered with `FontManager` and declared in `fonts`. There are no system fonts headlessly.-- Every audio layer needs `durationFrames` (`audio.totalFrames`), or it cuts out early.--## Video taste--Follow `plugins/framefields/skills/framefields-compose/SKILL.md`. Build like a designer with an engineer's discipline.--- **Tokens first:** `theme.ts` with palette, type scale, spacing, radii, eases, and one `BEAT` constant.-- **Native layout trees only:** Never fake a UI, chart or screenshot with a pre-rendered bitmap.-- **One clock:** Captions or voiceover first, then the BeatGrid, then reading pace (~2.4 words/s). Generate audio first and derive timing from it. Never guess frames or slice the timeline evenly.-- **Restrained hierarchy:** One idea per shot, one focal point, generous negative space. Huge display size, small tracked-out label, high contrast.-- **Decisive motion:** Enter with deceleration (`expo.out`, `power3.out`, `back.out(1.5)`, spring). Exit fast (`power2/3.in`). Never use linear easing on position, scale, or rotation. Stagger siblings by 2-4 frames.-- **Verify before claiming done:** Use the ladder: typecheck -> schema parse -> `renderFrame` -> `renderFrameGrid` -> pixel probes -> `renderVideo` + `ffprobe`.+- Every font in `Layer.text` must be registered with `FontManager` and declared in `fonts`. There are no system fonts headlessly.\ No newline at end of filediff --git a/AGENTS.md b/AGENTS.mdindex 78b3895d..68241e35 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -37,40 +37,4 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb- Releases: changesets (`.changeset/`).## Local-only files-Gitignored, never commit: `assets/fonts`, `*.mp4/mp3/wav/png/jpg`, `*.onnx`, `scratch*/`, `examples/output/`, `.hermes/`, `.env*` (never print secrets). Put probes and logs under `scratch/` or `output/`.--## Engine gotchas (fail silently)-- Premultiplied-alpha blend uses `srcFactor: "one"`, never `"src-alpha"` (murky grey fades).-- WGSL: every declared storage binding must be used, or Tint drops it from the layout.-- Clamp scissor rects to non-negative integers within the surface.-- Signals are class instances; never spread them (loses `.get(ctx)`). A `NaN` uniform blacks out the frame.-- `CompositorProgramSchema` is `.strict()`: new node/program fields go in `program/schema.ts`, or `comp.toSpec()` fails.-- Keyframe frames and effect frame options must be integers (`Math.round(...)`).-- Master soundtrack layers to about -14 dBFS RMS, summed peak near 0.9.-- Procedural SFX (`renderSfx`, `mixSfxInto`, `softLimit`): `atBar` is where the effect starts; a whoosh peaks 0.42s in, so start ~0.21 bars before the cut.-- `withAnimation` keeps `animation` an enumerable data property so spreads keep tracks.-- Keep `isAbsolutePositioned` symmetric between `buildYogaNode` and `readLayout`.-- Compositor specs: audio is `config.layout` items with `kind: "media"`, `inputHandleId` (live handle ID, not label) and `volume`. Fonts go in top-level `"fonts"` with relative paths.-- Fonts: every `Layer.text` font must be registered with `FontManager` and declared in `fonts`; no system fonts. Emoji need a color emoji font (`FontManager.registerEmojiFont`, or `framefields fonts add emoji`). Missing glyphs fall back per grapheme across registered families, except path text, which is single-font.-- Path text (`pathOptions`) coordinates are local to the node's box; size the node to contain the path.-- Shape paths support SVG arcs; a circle is two arcs and draws on with `trimEnd`.-- Circular window: plate plus `Layer.shape("ellipse", { blendMode: "mask-in" })` in a box with `background: "transparent"`.-- No per-effect helpers like `blurTrackedRegion`; extend `comp.section` / `Layer.section`.--## Authoring API traps-- `LayerAnimation` has no `moveX/moveY/scale/rotate/trimPath`; use `fromTo(prop, from, to, { start, end, ease })`. `fadeIn`/`fadeOut` are positional: `.fadeIn(0, 20, "power2.out")`.-- Borders are `borderColor` + `borderWidth`; CSS `border` is ignored.-- Setting only `x` or `y` makes a node absolute; use `position: "relative"` to nudge. A centered flex needs an explicit `width` (or `"fill"`).-- Keyframes are relative to the node's own window (never add the parent's `startFrame`). Animating `y` overrides layout `y`: `fromTo("y", y + 40, y)`.-- Eases: `none power1 power2 power3 sine circ expo back elastic bounce spring cubic hold` (no `power4`).-- Don't nest an opaque container inside a `tilt3D`/`rotateX`/`perspective` container; make one card.-- Every audio layer needs `durationFrames` (`audio.totalFrames`).--## Video taste-Follow `plugins/framefields/skills/framefields/SKILL.md`.-- Tokens first: `theme.ts` with palette, type scale, spacing, radii, eases, one `BEAT`.-- Native layout trees only; never fake UI, charts or screenshots with bitmaps.-- One clock: captions/voiceover first, then BeatGrid, then reading pace (~2.4 words/s). Derive timing from generated audio; never guess or slice evenly.-- Restrained hierarchy: one idea and focal point per shot, negative space, huge display type, small tracked-out labels.-- Decisive motion: enter decelerating (`expo.out`, `power3.out`, `back.out(1.5)`, spring), exit fast (`power2/3.in`), never linear on position/scale/rotation, stagger siblings 2-4 frames.-- Verify: typecheck -> schema parse -> `renderFrame` -> `renderFrameGrid` -> pixel probes -> `renderVideo` + `ffprobe`.+Gitignored, never commit: `assets/fonts`, `*.mp4/mp3/wav/png/jpg`, `*.onnx`, `scratch*/`, `examples/output/`, `.hermes/`, `.env*` (never print secrets). Put probes and logs under `scratch/` or `output/`.\ No newline at end of filediff --git a/CLAUDE.md b/CLAUDE.mdindex 2bc01a97..e47c63d3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -38,39 +38,3 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb## Local-only filesGitignored, never commit: `assets/fonts`, `*.mp4/mp3/wav/png/jpg`, `*.onnx`, `scratch*/`, `examples/output/`, `.hermes/`, `.env*` (never print secrets). Put probes and logs under `scratch/` or `output/`.--## Engine gotchas (fail silently)-- Premultiplied-alpha blend uses `srcFactor: "one"`, never `"src-alpha"` (murky grey fades).-- WGSL: every declared storage binding must be used, or Tint drops it from the layout.-- Clamp scissor rects to non-negative integers within the surface.-- Signals are class instances; never spread them (loses `.get(ctx)`). A `NaN` uniform blacks out the frame.-- `CompositorProgramSchema` is `.strict()`: new node/program fields go in `program/schema.ts`, or `comp.toSpec()` fails.-- Keyframe frames and effect frame options must be integers (`Math.round(...)`).-- Master soundtrack layers to about -14 dBFS RMS, summed peak near 0.9.-- Procedural SFX (`renderSfx`, `mixSfxInto`, `softLimit`): `atBar` is where the effect starts; a whoosh peaks 0.42s in, so start ~0.21 bars before the cut.-- `withAnimation` keeps `animation` an enumerable data property so spreads keep tracks.-- Keep `isAbsolutePositioned` symmetric between `buildYogaNode` and `readLayout`.-- Compositor specs: audio is `config.layout` items with `kind: "media"`, `inputHandleId` (live handle ID, not label) and `volume`. Fonts go in top-level `"fonts"` with relative paths.-- Fonts: every `Layer.text` font must be registered with `FontManager` and declared in `fonts`; no system fonts. Emoji need a color emoji font (`FontManager.registerEmojiFont`, or `framefields fonts add emoji`). Missing glyphs fall back per grapheme across registered families, except path text, which is single-font.-- Path text (`pathOptions`) coordinates are local to the node's box; size the node to contain the path.-- Shape paths support SVG arcs; a circle is two arcs and draws on with `trimEnd`.-- Circular window: plate plus `Layer.shape("ellipse", { blendMode: "mask-in" })` in a box with `background: "transparent"`.-- No per-effect helpers like `blurTrackedRegion`; extend `comp.section` / `Layer.section`.--## Authoring API traps-- `LayerAnimation` has no `moveX/moveY/scale/rotate/trimPath`; use `fromTo(prop, from, to, { start, end, ease })`. `fadeIn`/`fadeOut` are positional: `.fadeIn(0, 20, "power2.out")`.-- Borders are `borderColor` + `borderWidth`; CSS `border` is ignored.-- Setting only `x` or `y` makes a node absolute; use `position: "relative"` to nudge. A centered flex needs an explicit `width` (or `"fill"`).-- Keyframes are relative to the node's own window (never add the parent's `startFrame`). Animating `y` overrides layout `y`: `fromTo("y", y + 40, y)`.-- Eases: `none power1 power2 power3 sine circ expo back elastic bounce spring cubic hold` (no `power4`).-- Don't nest an opaque container inside a `tilt3D`/`rotateX`/`perspective` container; make one card.-- Every audio layer needs `durationFrames` (`audio.totalFrames`).--## Video taste-Follow `plugins/framefields/skills/framefields/SKILL.md`.-- Tokens first: `theme.ts` with palette, type scale, spacing, radii, eases, one `BEAT`.-- Native layout trees only; never fake UI, charts or screenshots with bitmaps.-- One clock: captions/voiceover first, then BeatGrid, then reading pace (~2.4 words/s). Derive timing from generated audio; never guess or slice evenly.-- Restrained hierarchy: one idea and focal point per shot, negative space, huge display type, small tracked-out labels.-- Decisive motion: enter decelerating (`expo.out`, `power3.out`, `back.out(1.5)`, spring), exit fast (`power2/3.in`), never linear on position/scale/rotation, stagger siblings 2-4 frames.-- Verify: typecheck -> schema parse -> `renderFrame` -> `renderFrameGrid` -> pixel probes -> `renderVideo` + `ffprobe`.