Skip to content

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

Fix engine timing and sampling bugs; add agent preflight checks (#59)

Okan Aslankanb1a40b470179
diff --git a/.changeset/fix-inspection-and-sequence-clocks.md b/.changeset/fix-inspection-and-sequence-clocks.md
new file mode 100644
index 00000000..296f5868
--- /dev/null
+++ b/.changeset/fix-inspection-and-sequence-clocks.md
@@ -0,0 +1,15 @@
+---
+"framefields": minor
+"@framefields/core": minor
+"@framefields/compositions": patch
+"@framefields/renderer": patch
+"@framefields/components": patch
+---
+
+Bound frame-grid sample generation before allocation, validate numeric sampling inputs, and keep automatically chosen samples inside the exported frame window. Render hooks and pixels now use one timestamp-selected frame; timestamp labels no longer change frame selection through rounding. Composition rendering rejects mismatching FPS overrides.
+
+Fix sequence duration with outgoing overlaps and delayed layers that previously outlived their scene. Explicit scene-layer windows must fit their owning scene, and overlaps cannot exceed either adjacent scene. Frame indices and frame-range steps must be safe integers; fractional timestamps and FPS remain supported.
+
+Add `framefields check <entry> --json` with isolated builder execution, schema/lint/timeline diagnostics, bounded worker lifetime and optional `--render` frame/grid smoke checks. Scaffolds include `check` and `check:render` scripts. Add JSON component/font discovery and an API reference generated from the owning timing/preflight types via `framefields api`.
+
+Normalize animation-builder inputs to strict program specs at the layer-builder boundary. Ambient light helpers now also accept an options object, consistently with other light helpers, while preserving positional color/intensity calls. These fixes allow the launch example to pass schema preflight.
diff --git a/AGENTS.md b/AGENTS.md
index 9a2c61a1..78b3895d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,7 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb
- Keep this file current when structure or dev patterns change but do not bloat it.
## Repo map
-- `packages/framefields`: public SDK. `Composition`, `Layer.*`, `LayerAnimation`, `Signal`, effects (`src/effects/classes.ts`), `FontManager`, `renderFrameGrid`. `src/index.ts` is the export surface. CLI in `src/cli/` (`init`, `add`, `list`, `fonts add|list`); `init` never prompts or overwrites, and its file templates are strings in `templates.ts` (a test parses them).
+- `packages/framefields`: public SDK. `Composition`, `Layer.*`, `LayerAnimation`, `Signal`, effects (`src/effects/classes.ts`), `FontManager`, `renderFrameGrid`. `src/index.ts` is the export surface. CLI in `src/cli/` (`init`, `add`, `list`, `fonts add|list`, `check`, `api`); `check` isolates builders in an IPC worker, `--render` adds GPU smoke checks, and `api` reads the build-generated type catalog. `init` never prompts or overwrites, and its file templates are strings in `templates.ts` (a test parses them).
- `packages/components`: the component registry `framefields add` copies into user projects (shadcn-style). `defineComponent`/`bind` contract in `src/core/contract.ts`, shared helpers in `src/core/` (keys, color, layout, surface, theme). Components import only `framefields` and `../core`. Registry items declare font needs (e.g. emoji); CLI fonts are pinned by URL, size and SHA-256 in `cli/fonts.ts`. Prop docs in `components.json` are generated (drift test). Tree-shake size budgets are tested.
- `packages/compositions`: Yoga layout (`utils/layout/resolve-layout.ts`), program schema (`program/schema.ts`), lint (`program/lint.ts`), animation/evaluator.
- `packages/webgpu-renderers`: WGSL shaders, 2D/3D pipelines, Slug text (`src/slug/`), audio DSP.
diff --git a/ENGINE_FIX_PLAN.md b/ENGINE_FIX_PLAN.md
new file mode 100644
index 00000000..c4a288e8
--- /dev/null
+++ b/ENGINE_FIX_PLAN.md
@@ -0,0 +1,193 @@
+# Engine fixes and agent DX implementation plan
+
+Prepared 2026-10-28 from [ENGINE_REVIEW.md](ENGINE_REVIEW.md), against reviewed commit `c6692762`.
+
+## Outcome and delivery order
+
+Fix all five reviewed defects, establish explicit timing contracts, and give agents a reliable path from authoring to validated output. The implementation on `codex/engine-timing-and-agent-checks` follows these stages. The validation record below distinguishes completed checks from remaining platform coverage.
+
+| Stage | Deliverable | Depends on | Completion evidence |
+| --- | --- | --- | --- |
+| 1 | Bounded, validated grid sampling | None | Invalid and excessive requests fail before allocation |
+| 2 | Shared frame selection and valid automatic grid bounds | Stage 1 | Hooks, labels and pixels select the same frame |
+| 3 | Correct sequence timeline and scene windows | None; combine with Stage 2 for integration validation | Scene boundaries and reported duration agree |
+| 4 | Structured preflight and deterministic smoke verification | Stages 1–3 | Fresh scaffold produces machine-readable checks and inspection artifacts |
+| 5 | JSON discovery, generated API guidance and maintained skills | Stage 4 contracts | Discovery and examples remain aligned with the shipped package |
+
+Stages 1–3 are the bug-fix scope. Stages 4–5 are the larger agent-DX improvements proposed in the review and should ship incrementally.
+
+## Timing and compatibility decisions
+
+Establish these contracts before implementation:
+
+- A layer window is `[startFrame, startFrame + durationFrames)`. Keyframes stay relative to the layer's own start.
+- Export frame count retains its current rule: `max(1, round(durationMs * fps / 1000))` for a valid positive duration. Automatically generated inspection samples use that same count.
+- Frame indices are nonnegative safe integers. Millisecond timestamps may be fractional, but must be finite and nonnegative. FPS must be finite and positive; fractional frame rates remain supported.
+- Resolve a request to a frame once. Preserve the headless renderer's existing `atMs` precedence when callers supply both `frame` and `atMs`, and apply the result to composition hooks as well. Document this choice. A future mutually exclusive TypeScript union can be considered separately rather than forcing a source-breaking change into this fix.
+- Grid render calls pass the resolved frame only. Display timestamps are derived from that frame, retaining sufficient precision internally. Do not round to whole milliseconds and use that rounded label to select pixels again.
+- Explicit frame-grid samples outside the composition duration remain permitted for diagnostics. Automatically derived samples stay inside the export window. A direct `renderFrame` call is not implicitly clamped.
+- A `Sequence` scene owns a temporal window. A delayed root layer with no duration defaults to the remaining scene duration. Explicit root durations must fit that scene. Reject invalid windows with scene and layer IDs rather than silently shortening explicit animation or media durations.
+
+Document observable changes: delayed scene layers end earlier; final overlap no longer shortens reported duration; invalid numeric grid inputs fail early; automatic grids no longer include the exclusive end; conflicting dual time requests run hooks at the renderer-selected frame.
+
+## Stage 1 — Bound and validate sample generation
+
+Primary files: `packages/framefields/src/renderer/framegrid.ts`, `packages/framefields/src/framegrid.test.ts`.
+
+Implementation:
+
+1. Normalize and validate `maxFrames` before resolving samples. Require a positive safe integer; preserve the documented hard cap of 120 and default of 64.
+2. Validate FPS and all selected sampling inputs before looping. Require frame-range bounds and `stepFrames` to be safe integers, with `stepFrames >= 1`; require finite millisecond bounds and `stepMs > 0`.
+3. Preserve the current selection order: nonempty `frames`, nonempty `timesMs`, millisecond range, frame range. Validate the chosen mode and report contradictory modes clearly in documentation; avoid silently changing precedence in this patch.
+4. Reject oversized explicit arrays using their length before creating a second array. Do not deduplicate samples in this fix: requested order and repeated inspection points are useful existing behavior.
+5. Generate ranges with a bounded counter, calculating each value from `start + index * step`. Before adding the next sample, reject if the cap would be exceeded. Also reject non-finite or non-advancing arithmetic. This bounds work even when count arithmetic overflows or floating-point precision prevents progress.
+6. Keep helpers small and named so numeric validation, range generation and sample conversion pass the complexity lint.
+
+Regression cases:
+
+- A billion-frame range fails with the threshold diagnostic without materializing the range.
+- `Infinity`, `NaN`, zero/negative steps, unsafe frame indices and fractional frame steps fail predictably.
+- Fractional millisecond steps remain valid; arithmetic that cannot advance fails.
+- Exactly the requested cap succeeds; cap + 1 fails; a requested cap above 120 still cannot exceed 120.
+- Explicit sample order and duplicates are preserved.
+
+Run historically nonterminating cases in a child process with a strict external timeout, so a regression cannot hang the test runner. Keep the ordinary finite cases as pure unit tests.
+
+Acceptance: every request either returns at most the effective cap or fails after bounded work, independent of range magnitude.
+
+## Stage 2 — Canonical frame selection and grid boundaries
+
+Primary files: `packages/core/src/` and its export surface, `packages/renderer/src/headless-webgpu-renderer.ts`, `packages/framefields/src/index.ts`, `packages/framefields/src/renderer/framegrid.ts`; existing frame-grid and media-time tests plus focused new request-resolution tests.
+
+Implementation:
+
+1. Add a small pure frame-request resolver to `@framefields/core`, shared by the public composition and headless paths. Return the resolved frame and exact frame timestamp. Validate inputs consistently and preserve `atMs` precedence.
+2. Have `Composition.renderFrame` resolve before hooks, call hooks with that frame, and forward only the canonical frame to the renderer. The direct headless API uses the same resolver for requests that enter there.
+3. Apply the composition's FPS consistently. An inspection grid FPS override must not cause hooks to use one clock and pixels another: for composition targets, reject a mismatching override with a clear message; retain explicit FPS selection for media pipelines that do not have an authoritative composition clock. Add an internal capability or adapter rather than guessing target identity from incidental fields.
+4. Update grid sample conversion to round to a frame once, derive `timeMs` from the selected frame, and pass only `frame` plus the effective FPS. Whole-millisecond formatting belongs in the label renderer.
+5. Reuse a narrow frame-count helper where export and automatic grid bounds need identical duration rounding. Do not broadly refactor all duration calculations in unrelated systems.
+6. For default frame ranges, use `lastFrame = frameCount - 1`, then `min(startFrame + 30, lastFrame)`. If an implicit range begins beyond the last frame, return a targeted range error. Preserve explicitly provided endpoints.
+7. For default millisecond ends, stop at the last valid frame timestamp. Do not force an extra endpoint sample when the step does not land on it.
+
+Regression cases:
+
+- `timesMs: [16.6]` at 30 fps selects frame 0 throughout; no round-trip through 17 ms changes it to frame 1.
+- `{ frame: 0, atMs: 1000 }` at 30 fps runs hooks and pixels at frame 30, matching the retained timestamp precedence.
+- Frame-only and timestamp-only requests agree when they identify the same frame.
+- Fractional FPS and a composition with live signal remapping use the same frame clock in hooks and pixels.
+- A 30-frame composition's automatic grid never requests frame 30; a one-frame composition requests only frame 0.
+- Fractional durations use the same frame count as export. Explicit out-of-window samples keep their documented behavior.
+- A mismatching grid FPS override fails before hooks or rendering start.
+
+GPU acceptance test: use a tiny font-free composition whose hook changes a visible color or signal on a known frame. Verify both the hook frame and rendered pixel values. Add a short export and compare the relevant decoded frame to the single-frame path, allowing codec tolerance.
+
+## Stage 3 — Sequence duration and scene ownership
+
+Primary files: `packages/compositions/src/program/sequence.ts`, `sequence.test.ts`, and relevant compositor/render tests. The public SDK re-exports these helpers, so update public guidance as well.
+
+### 3A. Timeline calculation
+
+1. Normalize each scene duration to a positive safe integer frame count. Preserve the current 60-frame default. Reject millisecond durations that round to zero instead of emitting zero-length scenes.
+2. Validate FPS, outgoing overlap and accumulated offsets. Use the scene schema and shared refinement helpers consistently from constructors and the standalone timeline function; the schema currently exists without constructor enforcement.
+3. Track the next scene start separately from `maxSceneEnd`. Subtract overlap only to place an actual next scene. Report total frames as the maximum exclusive end across all scenes.
+4. For overlaps between scenes, require a nonnegative integer no longer than either adjacent scene duration. Allow a full-scene overlap if it intentionally aligns starts. Reject larger overlaps instead of hiding them behind `Math.max(1, ...)`.
+5. Ignore a final outgoing transition for scheduling because it has no destination; retain it as metadata if callers need it. Empty sequences return zero frames and zero milliseconds.
+
+Tests: empty and single scene; final outgoing overlap; ordinary two- and three-scene overlaps; full overlap; excessive overlap; explicit zero override; fractional FPS; invalid numbers; and the invariant `totalFrames === max(start + duration)` for every nonempty result.
+
+### 3B. Compile layers inside scene windows
+
+1. Resolve each root layer's local start before applying the global scene offset.
+2. When duration is omitted, assign `sceneDuration - localStart`. Reject starts at or beyond the scene end with a diagnostic naming the scene and layer.
+3. Validate explicit root windows against scene bounds. Explain migration for deliberately spilling content: place it in the owning scene with an appropriate duration or in a separate composition-level layer.
+4. Audit existing parent-window behavior before altering nested nodes. Parent clipping should constrain descendants while keeping their starts and animation frames local. If existing temporal containment is insufficient, fix that behavior at its owning evaluator/layout boundary and add its regression there. Avoid adding a visual wrapper that changes layout, lighting or transform semantics merely to enforce time.
+5. Preserve source objects: compiling twice must not mutate input layers, descendants, animation tracks or signals.
+6. Update the existing test that expects a delayed layer to receive a full scene duration. Verify its end frame, not just the new numeric duration.
+
+Tests: a layer starting at 30 in a 60-frame scene lasts 30 frames; at scene boundary it disappears; explicit fitting duration stays intact; overflow fails clearly; nested local animation remains aligned; overlapping scenes retain their intended concurrent windows; repeated compilation is stable.
+
+GPU acceptance: render before and at a two-scene boundary, using distinct colors and a delayed layer. Include a nested animated child and an overlapping-scene case. Export duration should match the timeline's frame count when that count is supplied by the caller.
+
+## Stage 4 — One structured preflight and smoke workflow
+
+Proposed command: `framefields check <entry> --export <name> --json`, with optional `--render` for a small frame/grid smoke check. Integrate existing schema, lint and rendering APIs instead of maintaining parallel validators.
+
+Primary files: `packages/framefields/src/cli.ts`, new focused modules under `src/cli/`, `src/cli/templates.ts`, CLI tests, and existing diagnostic types where reuse is appropriate.
+
+Implement in two increments:
+
+1. **Document preflight:** load the requested builder, build once, validate the spec, collect lint findings and report known font/asset/timeline issues. Use the project's installed TypeScript tooling for source loading; reuse the preview's entry-loading machinery where it is suitable. Check the dependency path before choosing a loader. Importing a builder executes project code, so document the same side-effect-free builder contract already required by the skill.
+2. **Render smoke:** probe the backend and render a representative frame and bounded grid to an explicit output directory. Report success, failure or unavailable for each check; never imply that skipped GPU checks passed. Native renderer scripts and worker processes must terminate explicitly and clean up on failure.
+
+JSON contract:
+
+- A versioned envelope with SDK version, entry/export, overall status, check results and artifact paths.
+- Diagnostics with stable code, severity, stage, message and optional layer/property path and suggested action.
+- `stdout` contains exactly one JSON result in JSON mode; progress and project logging must be routed away from that stream. Prefer an isolated worker with a structured result channel so user `console.log` cannot corrupt output.
+- Exit 0 for completed requested checks with no errors; 1 for validation or execution failure; 2 for invalid CLI usage. Warnings remain visible without failing unless `--warnings-as-errors` is selected. A requested unavailable render check is not success.
+- Builder/worker exceptions preserve their original causes. Use a configurable timeout and terminate the worker with an actionable diagnostic if a builder or native task hangs.
+
+Scaffold integration: add a documented `check` script combining `tsc --noEmit` with CLI document preflight. Add an explicit `check:render` script for GPU inspection. Derive smoke sample positions from the actual duration rather than hardcoding frames from the original three-second template. Keep generated scripts deterministic and free of asset-generation calls.
+
+Acceptance: a fresh generated project can run unattended; JSON parses despite a noisy builder; missing fonts and invalid specs identify the source layer/property; failed typecheck stops the scripted pipeline; unavailable GPU checks are explicit; successful render checks return usable local artifacts.
+
+## Stage 5 — Discovery and agent guidance
+
+1. Add `--json` to component and font listing commands, reusing registry and font metadata. Include component names, descriptions, props, dependencies, font requirements and SDK/catalog version. Preserve current human output by default.
+2. Start API discovery with the affected surfaces: frame/grid options, scene timing, diagnostics and check command. Generate the catalog from TypeScript declarations, schemas and documented metadata. Fail a drift check when committed output disagrees with source; do not create a manually maintained duplicate catalog.
+3. Include explicit units, defaults, valid ranges, exclusive end semantics, examples and diagnostic codes. Compile runnable examples against the built package so development-only imports do not hide packaging defects.
+4. Update `plugins/framefields/skills/framefields-render/SKILL.md` for canonical time selection, grid boundaries and preflight; update the compose skill for sequence windows and overlap validation; update the base skill for the scaffold workflow. Edit the owning sources and preserve their symlink arrangement.
+5. If compositor-node behavior changes, update `nodes/node-compositor/SKILL.md` and its guarded tests. Keep the effects catalog generated; these fixes do not require manually editing it.
+6. Add public release notes with concise before/after examples and migration advice. Add changesets for the affected published packages; treat newly rejected scene overflows and fractional frame indices as compatibility-sensitive behavior and apply the repository's release policy.
+
+Acceptance: agents can discover the new contracts and follow one checked example without inferring units or assembling undocumented validation steps.
+
+## Validation and release gates
+
+For each correctness change: reproduce the original failure with a focused regression, implement the owning fix, then run its package tests and lint. Use package scripts and pnpm throughout.
+
+Suggested targeted commands, adjusted for the final test filenames:
+
+```sh
+pnpm --filter @framefields/core test
+pnpm --filter @framefields/compositions exec vitest run src/program/sequence.test.ts
+pnpm --filter framefields exec vitest run src/framegrid.test.ts
+pnpm --filter framefields exec vitest run src/cli/init.test.ts src/cli/add.test.ts src/cli/fonts.test.ts
+pnpm exec biome check --write <changed-source-files>
+pnpm build
+pnpm run check:plugins
+```
+
+Run the new hook/pixel and sequence-boundary tests on a real supported GPU backend, then render one short MP4 and inspect frame count/duration with `ffprobe`. Inspect a grid from the same composition and compare boundary pixels. Use a signal-remapped media case to check for missing recorded history. Run a Node 22 compatibility check as well as the current development runtime; the review probes used Node 26.
+
+Build affected dependencies before consumer checks when tests resolve `dist` rather than the `development` condition. Use `tsc --noEmit -p .` only where no suitable package script exists; never run an emitting bare `tsc`. Keep temporary media and probes in ignored scratch/output locations.
+
+The final integration gate is a clean temporary consumer using the packed SDK: initialize, typecheck, run preflight, render frame/grid/video, inspect output, and verify process exit. This catches bundle, declaration, template and lifecycle failures that source-level tests miss.
+
+## Suggested reviewable changes
+
+1. Grid numeric validation and bounded sampling, with pure regressions.
+2. Canonical frame resolution, hook alignment and automatic sample bounds, with GPU regression.
+3. Sequence timeline/window contracts and compatibility documentation, with boundary regression.
+4. Structured document preflight and JSON contract.
+5. Render smoke mode and scaffold integration.
+6. JSON discovery, generated guidance, skills and release notes.
+
+Ship the correctness fixes without waiting for the full discovery catalog. For every change, record what was tested, actual GPU/backend coverage, and any remaining platform gap. Do not replace unavailable verification with mocked success or silent fallback.
+
+## Implementation validation record
+
+- The full monorepo build passed, including bundled declaration checks, component tree-shaking budgets and installed-component typechecks. All 19 plugin validation checks passed.
+- Core suite: 66 tests passed. Sequence suite: 10 tests passed. CLI init/add/fonts/check suites: 33 tests passed. Registry/metadata suites: 6 tests passed.
+- GPU grid/timing/signal-track suites passed on an Apple M1 Pro Metal adapter. The media-time rendering suite passed all 18 tests, including live histories and audio/video export. The formerly unbounded sampling regression now runs in a child process with an external timeout.
+- Packed the built SDK and installed it in a fresh scaffold with its own dependency install and lockfile. Consumer typechecking, JSON document preflight, GPU smoke rendering, and generated video export scripts passed. The consumer used a font-free 64×64 composition to isolate engine and packaging behavior.
+- `ffprobe` confirmed 12 frames at 30 fps over 0.4 seconds. Decoding the export confirmed red pixels on frames 0 and 5 and green pixels on frames 6 and 11, within codec tolerance. Inspected the generated frame grid visually.
+- Packed preflight also passed under Node v22.23.4, the minimum supported major; native GPU validation used Node v26.7.0 on macOS arm64. Linux, Windows and Node 22 GPU rendering remain unverified here.
+- Standalone repository typechecking still reports errors in unchanged files: core media type resolution/virtual-media typing, framefields font-source test `BodyInit` typing, and preview tests importing component sources outside the SDK's `rootDir`. No changed implementation file retains a reported type error after dependency builds. Packed-consumer and build-time declaration checks pass.
+- The API catalog is generated directly into `dist/api.json` on every SDK build rather than maintaining a committed duplicate. It currently covers 11 timing, grid, sequence and preflight declarations; expanding it to the entire SDK is future work. Local asset checks run in document preflight; remote availability and decoding are exercised by the optional render step for sampled content.
+
+### Launch example integration follow-up
+
+Rendered `examples/22_framefields_launch` with cached assets on the Apple M1 Pro. Initial strict preflight exposed two additional authoring issues: camera animation-builder instances carried enumerable builder defaults into the program spec, and the example's ambient-light options objects were interpreted as positional colors. Layer builders now normalize animation instances with `toSpec()`, and ambient-light helpers accept options objects while preserving positional calls. Builder conformance tests cover both forms; all 33 conformance tests and 10 camera/light rendering tests passed.
+
+The example's typecheck, four timing/alignment tests, strict preflight, single frame, and 14-shot grid passed. Its full H.264 export completed in 139.13 seconds at 1920×1080, 60 fps. QA reported all 3,600 frames encoded, no black or frozen segments, no clipped audio samples or silent segments, and stereo 48 kHz audio with -14.1 dBFS RMS and -2.8 dBFS peak. `ffprobe` independently confirmed 3,600 video frames over 60 seconds; AAC padding extends container duration to 60.032 seconds. Remaining lint findings are five informational static-track notices. Rendered artifacts and JSON verification are local ignored files under `examples/22_framefields_launch/output/engine-review-40b7d883/`.
diff --git a/ENGINE_REVIEW.md b/ENGINE_REVIEW.md
new file mode 100644
index 00000000..d3ca8203
--- /dev/null
+++ b/ENGINE_REVIEW.md
@@ -0,0 +1,52 @@
+# Engine and agent DX review
+
+Reviewed 2026-10-28 at commit `c6692762`. This is a targeted review of sequencing, frame inspection, rendering time selection, and agent-facing workflows; it is not an exhaustive audit of every renderer, shader, node, or platform.
+
+Implementation follow-up: all five findings have fixes and focused regressions on `codex/engine-timing-and-agent-checks`. The agent workflow now includes isolated JSON preflight, optional GPU frame/grid checks, scaffold scripts, JSON component/font discovery and a type-generated API reference. See [the implementation plan](ENGINE_FIX_PLAN.md) for contracts and validation details. The evidence below describes the original review; subsequent GPU and packed-consumer validation is recorded in the plan.
+
+## Findings
+
+### P1 — Frame-grid safety limit is applied after building the entire sample list
+
+`resolveSamplePoints` builds the range in a loop before checking `maxFrames` ([framegrid.ts:183](packages/framefields/src/renderer/framegrid.ts#L183), [framegrid.ts:209](packages/framefields/src/renderer/framegrid.ts#L209), [framegrid.ts:217](packages/framefields/src/renderer/framegrid.ts#L217)). A request such as `endFrame: 1_000_000_000, stepFrames: 1` can exhaust memory before the advertised 120-frame hard limit is reached. `endFrame: Infinity` never terminates, and finite values can also stop advancing due to floating-point precision. This can hang an agent's inspection job instead of giving it the intended actionable error.
+
+Validate finite inputs and positive, advancing steps, calculate or enforce the maximum sample count before appending, and test both excessive and non-finite ranges. Validate `fps` and `maxFrames` as finite positive values too.
+
+### P2 — Frame and timestamp can select different frames and desynchronize hooks
+
+The grid passes both `frame` and `atMs` ([framegrid.ts:353](packages/framefields/src/renderer/framegrid.ts#L353)). `Composition.renderFrame` gives `frame` precedence for hooks ([index.ts:2199](packages/framefields/src/index.ts#L2199)), whereas the headless renderer gives `atMs` precedence ([headless-webgpu-renderer.ts:788](packages/renderer/src/headless-webgpu-renderer.ts#L788)). Timestamp rounding makes disagreement possible: `resolveSamplePoints({ timesMs: [16.6], fps: 30 })` returns `{ frame: 0, timeMs: 17 }`, but 17 ms maps to frame 1. The grid labels and hooks refer to frame 0 while pixels are rendered at frame 1; live signal histories can consequently be inconsistent. Direct `renderFrame` calls supplying both options have the same precedence conflict.
+
+Choose one canonical frame once, pass that to hooks and renderer, and use timestamps only for display or consistently define precedence. Add a regression for fractional timestamps and conflicting simultaneous options, including a frame hook.
+
+### P2 — Default frame grid includes the exclusive end of a composition
+
+For a 1-second composition at 30 fps, `resolveSamplePoints({}, 30, 1000)` returns `0, 5, 10, 15, 20, 25, 30` ([framegrid.ts:190](packages/framefields/src/renderer/framegrid.ts#L190)). Video export uses 30 frames, numbered 0–29 ([headless-webgpu-renderer.ts:1114](packages/renderer/src/headless-webgpu-renderer.ts#L1114)). The last grid cell is therefore outside the exported timeline and can show an empty or misleading frame. The default millisecond-range end also includes `durationMs`.
+
+For automatically derived bounds, use the same rounded frame count as export and clamp to the last valid frame; define whether explicit out-of-range samples are allowed. Cover short and fractional-duration compositions in tests.
+
+### P2 — Sequence reports too short a timeline when the final scene has an outgoing overlap
+
+`calculateSequenceTimeline` subtracts the outgoing overlap for every scene, including the last ([sequence.ts:161](packages/compositions/src/program/sequence.ts#L161)). For one 60-frame scene with `transitionOverlap: 10`, the function returns `totalFrames: 50` even though the scene offset describes frames 0–59. The same applies to a final `transitionOut.durationFrames`. A caller using this public timeline to size an export truncates the last scene. An overlap longer than the following scene can also make an earlier scene end after the reported total.
+
+Calculate total duration as the maximum scene end, and apply outgoing overlap only when determining a following scene's start. Validate overlap against the relevant scenes or explicitly define oversized overlap semantics. Test final-scene and oversized overlaps.
+
+### P2 — Delayed sequence layers extend past their scene by default
+
+`Sequence.toProgram()` adds a layer's local `startFrame` to the scene offset, but assigns the full scene duration when the layer has no explicit duration ([sequence.ts:301](packages/compositions/src/program/sequence.ts#L301)). In a 60-frame scene, a layer starting at local frame 30 gets duration 60 and ends at frame 90, bleeding 30 frames into the next scene. The existing test explicitly expects this behavior for a layer starting at frame 5 ([sequence.test.ts:120](packages/compositions/src/program/sequence.test.ts#L120)).
+
+Define scene window semantics explicitly and constrain default layer duration to the remaining scene window. If scene boundaries are intended as hard bounds, also handle explicitly longer layers and nested contents consistently. Add a two-scene boundary regression rather than asserting only the assigned duration.
+
+## Agent developer experience
+
+1. **Provide a single preflight command with structured output.** The CLI currently exposes `init`, `add`, `list`, and `fonts`, while the render skill requires agents to assemble typechecking, schema parsing, `comp.lint()`, frame inspection, and export checks themselves ([cli.ts](packages/framefields/src/cli.ts), [render skill](plugins/framefields/skills/framefields-render/SKILL.md)). A `framefields check <entry> --json` could report environment/GPU, schema and lint diagnostics, fonts, assets, timeline bounds, and suggested next commands with stable codes and a nonzero exit for errors. Keep this a thin integration over the existing checks, not a second validator.
+2. **Make frame selection unambiguous and observable.** Resolve a single frame and expose requested frame, actual frame, fps and source time in diagnostics. This directly addresses the mismatch above and makes agent-generated frame grids trustworthy.
+3. **Fail early on invalid authoring inputs.** Enforce finite values, ranges, scene windows and overlap constraints at public boundaries, and include layer IDs, property paths, actual values and corrective actions in errors. The repository's gotchas currently require agents to remember several silent-failure rules; migrate those rules into lint/schema checks where possible.
+4. **Offer a machine-readable API and component discovery surface.** Add JSON output for CLI discovery and a versioned API catalog generated from the same source as types and registry metadata. Include parameter units, frame-window conventions, defaults, supported values, and runnable examples. This reduces guesses and documentation drift without forcing agents to read large skills for every lookup.
+5. **Add one deterministic, lightweight verification path.** A scaffolded script or CLI mode should run typecheck, schema/lint, one representative frame and a small grid, with clear GPU-unavailable diagnostics and an explicit exit status. Keep full video/audio and pixel assertions available for deeper checks. Test the generated scaffold end to end so documentation, templates and installed package stay aligned.
+
+## Evidence and limits
+
+- Executed direct TypeScript probes for the sequence timeline, delayed layer duration, default grid samples, and fractional timestamp sample using `node --import tsx --conditions=development`.
+- Existing `@framefields/compositions` sequence tests passed (4 tests); the selected frame-grid sampling and safety tests passed (4 tests). These tests do not cover the edge cases above.
+- No GPU render or video export was performed in this review; rendering consequences follow from the inspected call paths and should be confirmed with focused regression tests. The potentially nonterminating range was identified from the loop and was not executed.
+- Runtime used for probes: Node `v26.7.0`. No engine code was modified.
diff --git a/packages/components/scripts/build-registry.ts b/packages/components/scripts/build-registry.ts
index b0c2379f..8145139d 100644
--- a/packages/components/scripts/build-registry.ts
+++ b/packages/components/scripts/build-registry.ts
@@ -15,7 +15,7 @@ import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import type { ComponentMeta, FontNeed } from "../src/core/meta.js";
-import { collectMeta } from "./build-meta.js";
+import { type CollectedMeta, collectMeta } from "./build-meta.js";
const SRC = fileURLToPath(new URL("../src", import.meta.url));
const NOT_COMPONENTS = new Set(["core", "test"]);
@@ -39,6 +39,7 @@ export interface RegistryEntry
}
export interface RegistryItem extends RegistryEntry {
+ props?: CollectedMeta["props"];
parts: readonly string[];
cues: readonly string[];
/** Fonts to install with it (`framefields add` fetches them). */
@@ -193,14 +194,17 @@ export function registryItem(
/** Every component folder under `src`, sorted by name. */
export async function buildRegistry(src = SRC): Promise<RegistryItem[]> {
- await collectMeta(src); // every folder has a meta, names are unique
+ const metas = await collectMeta(src); // every folder has a meta, names are unique
const items: RegistryItem[] = [];
for (const entry of readdirSync(src, { withFileTypes: true })) {
if (!entry.isDirectory() || NOT_COMPONENTS.has(entry.name)) continue;
const mod = (await import(
pathToFileURL(join(src, entry.name, "meta.ts")).href
)) as { default: ComponentMeta };
- items.push(registryItem(src, entry.name, mod.default));
+ items.push({
+ ...registryItem(src, entry.name, mod.default),
+ props: metas.find((meta) => meta.name === mod.default?.name)?.props,
+ });
}
const names = new Set(items.map((i) => i.name));
for (const item of items)
diff --git a/packages/compositions/src/program/sequence.test.ts b/packages/compositions/src/program/sequence.test.ts
index 74aadb79..16b51583 100644
--- a/packages/compositions/src/program/sequence.test.ts
+++ b/packages/compositions/src/program/sequence.test.ts
@@ -122,6 +122,73 @@ describe("Cinematic Sequencing & Carrier Match Cuts", () => {
// scene 2 node should be offset by 60 frames
expect(program.layout[1]?.id).toBe("card-2");
expect(program.layout[1]?.startFrame).toBe(65);
- expect(program.layout[1]?.durationFrames).toBe(90);
+ expect(program.layout[1]?.durationFrames).toBe(85);
+ });
+});
+
+describe("sequence window boundaries", () => {
+ it("does not subtract a final outgoing overlap", () => {
+ const result = calculateSequenceTimeline(
+ [{ id: "a", durationFrames: 60, transitionOut: { durationFrames: 10 } }],
+ 30,
+ );
+ expect(result.totalFrames).toBe(60);
+ expect(result.totalDurationMs).toBe(2000);
+ });
+ it("measures the union of fully overlapping scenes", () => {
+ const result = calculateSequenceTimeline(
+ [
+ { id: "a", durationFrames: 60, transitionOverlap: 30 },
+ { id: "b", durationFrames: 30, transitionOverlap: 10 },
+ ],
+ 30,
+ );
+ expect(result.sceneOffsets[1].startFrame).toBe(30);
+ expect(result.totalFrames).toBe(60);
+ });
+ it("rejects overlap longer than either adjacent scene", () => {
+ expect(() =>
+ calculateSequenceTimeline([
+ { id: "a", durationFrames: 60, transitionOverlap: 31 },
+ { id: "b", durationFrames: 30 },
+ ]),
+ ).toThrow(/a.*overlap/);
+ });
+ it("validates numeric boundaries and empty sequences", () => {
+ expect(calculateSequenceTimeline([]).totalFrames).toBe(0);
+ for (const durationFrames of [0, -1, 1.5, Infinity, NaN])
+ expect(() =>
+ calculateSequenceTimeline([{ id: "bad", durationFrames }]),
+ ).toThrow(/bad/);
+ expect(() =>
+ calculateSequenceTimeline([{ id: "tiny", durationMs: 0.1 }], 30),
+ ).toThrow(/tiny/);
+ expect(() => calculateSequenceTimeline([], NaN)).toThrow(/fps/);
+ });
+ it("ends delayed layers at their scene boundary without mutating inputs", () => {
+ const layer = { id: "late", kind: "box" as const, startFrame: 30 };
+ const sequence = Sequence.create().addScene({
+ id: "a",
+ durationFrames: 60,
+ layout: [layer],
+ });
+ expect(sequence.toProgram().layout[0]).toMatchObject({
+ startFrame: 30,
+ durationFrames: 30,
+ });
+ expect(sequence.toProgram()).toEqual(sequence.toProgram());
+ expect(layer).not.toHaveProperty("durationFrames");
+ });
+ it("rejects explicit windows outside their owning scene", () => {
+ for (const node of [
+ { id: "late", kind: "box" as const, startFrame: 60 },
+ { id: "long", kind: "box" as const, startFrame: 30, durationFrames: 31 },
+ ]) {
+ expect(() =>
+ Sequence.create()
+ .addScene({ id: "a", durationFrames: 60, layout: [node] })
+ .toProgram(),
+ ).toThrow(/a.*window/);
+ }
});
});
diff --git a/packages/compositions/src/program/sequence.ts b/packages/compositions/src/program/sequence.ts
index 30717b5a..8cb21fa7 100644
--- a/packages/compositions/src/program/sequence.ts
+++ b/packages/compositions/src/program/sequence.ts
@@ -6,6 +6,7 @@
* Complies with specs/cinematic-sequencing.ts.
*/
+import { assertFps } from "@framefields/core";
import { z } from "zod";
import type { CompositorProgramConfig, LayoutNode } from "./schema.js";
@@ -151,32 +152,83 @@ export function calculateSequenceTimeline(
}>,
fps = 60,
): SequenceTimelineResult {
- let accumulatedFrame = 0;
- const offsets: Array<{
- sceneId: string;
- startFrame: number;
- durationFrames: number;
- }> = [];
-
- for (const scene of scenes) {
- const startFrame = accumulatedFrame;
- const dur =
- scene.durationFrames ??
- (scene.durationMs ? Math.round((scene.durationMs / 1000) * fps) : 60);
-
- offsets.push({ sceneId: scene.id, startFrame, durationFrames: dur });
+ assertFps(fps);
+ const durations = scenes.map((scene) => sceneDuration(scene, fps));
+ let startFrame = 0;
+ let totalFrames = 0;
+ const sceneOffsets: SequenceTimelineResult["sceneOffsets"] = [];
+ for (const [i, scene] of scenes.entries()) {
+ const durationFrames = durations[i];
+ const endFrame = startFrame + durationFrames;
+ if (!Number.isSafeInteger(endFrame))
+ throw new Error(`Scene '${scene.id}' exceeds the safe frame range`);
+ sceneOffsets.push({ sceneId: scene.id, startFrame, durationFrames });
+ totalFrames = Math.max(totalFrames, endFrame);
const overlap =
scene.transitionOverlap ?? scene.transitionOut?.durationFrames ?? 0;
- accumulatedFrame += Math.max(1, dur - overlap);
+ if (!Number.isSafeInteger(overlap) || overlap < 0)
+ throw new Error(
+ `Scene '${scene.id}' overlap must be a nonnegative safe integer`,
+ );
+ if (
+ i + 1 < scenes.length &&
+ overlap > Math.min(durationFrames, durations[i + 1])
+ )
+ throw new Error(
+ `Scene '${scene.id}' overlap exceeds an adjacent scene duration`,
+ );
+ startFrame = endFrame - (i + 1 < scenes.length ? overlap : 0);
}
-
- const totalFrames = accumulatedFrame;
const totalDurationMs = Math.round((totalFrames / fps) * 1000);
+ if (!Number.isFinite(totalDurationMs))
+ throw new Error("Sequence duration exceeds the finite range");
+ return { totalFrames, totalDurationMs, sceneOffsets };
+}
+
+function sceneDuration(
+ scene: { id: string; durationFrames?: number; durationMs?: number },
+ fps: number,
+): number {
+ if (
+ scene.durationMs !== undefined &&
+ (!Number.isFinite(scene.durationMs) || scene.durationMs <= 0)
+ )
+ throw new Error(
+ `Scene '${scene.id}' durationMs must be finite and positive`,
+ );
+ const duration =
+ scene.durationFrames ??
+ (scene.durationMs === undefined
+ ? 60
+ : Math.round((scene.durationMs / 1000) * fps));
+ if (!Number.isSafeInteger(duration) || duration <= 0)
+ throw new Error(
+ `Scene '${scene.id}' duration must resolve to a positive safe integer frame count`,
+ );
+ return duration;
+}
+function compileSceneLayer(
+ node: LayoutNode,
+ sceneId: string,
+ offset: SequenceTimelineResult["sceneOffsets"][number],
+): LayoutNode {
+ const start = node.startFrame ?? 0;
+ const duration = node.durationFrames ?? offset.durationFrames - start;
+ if (
+ !Number.isSafeInteger(start) ||
+ start < 0 ||
+ !Number.isSafeInteger(duration) ||
+ duration <= 0 ||
+ start + duration > offset.durationFrames
+ )
+ throw new Error(
+ `Scene '${sceneId}', layer '${node.id}': window must fit within frames [0, ${offset.durationFrames})`,
+ );
return {
- totalFrames,
- totalDurationMs,
- sceneOffsets: offsets,
+ ...node,
+ startFrame: offset.startFrame + start,
+ durationFrames: duration,
};
}
@@ -189,7 +241,9 @@ export interface SceneOptions {
| "feature_spotlight"
| "outro"
| "custom";
+ /** Scene duration in milliseconds; rounded to frames using sequence FPS. */
durationMs?: number;
+ /** Positive integer frame count, taking precedence over durationMs. Defaults to 60. */
durationFrames?: number;
transitionOut?: {
type?: SceneTransitionType;
@@ -220,6 +274,7 @@ export class Scene {
public layout: LayoutNode[];
constructor(options: SceneOptions) {
+ SceneDefinitionSchema.parse(options);
this.id = options.id;
this.chapter = options.chapter ?? "custom";
this.durationMs = options.durationMs;
@@ -298,14 +353,8 @@ export class Sequence {
const offset = timeline.sceneOffsets[i];
if (!offset) continue;
- // Wrap scene elements inside a temporal container or offset their startFrames
for (const node of scene.layout) {
- const cloned = { ...node } as LayoutNode;
- cloned.startFrame = (cloned.startFrame ?? 0) + offset.startFrame;
- if (cloned.durationFrames === undefined) {
- cloned.durationFrames = offset.durationFrames;
- }
- rootLayout.push(cloned);
+ rootLayout.push(compileSceneLayer(node, scene.id, offset));
}
}
diff --git a/packages/core/src/frame-time.test.ts b/packages/core/src/frame-time.test.ts
new file mode 100644
index 00000000..1de35fa4
--- /dev/null
+++ b/packages/core/src/frame-time.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { frameCount, resolveFrameRequest } from "./frame-time.js";
+
+describe("frame time contracts", () => {
+ it("resolves fractional timestamps once and preserves timestamp precedence", () => {
+ expect(resolveFrameRequest({ atMs: 16.6 }, 30)).toEqual({
+ frame: 0,
+ timeMs: 0,
+ });
+ expect(resolveFrameRequest({ frame: 0, atMs: 1000 }, 30)).toEqual({
+ frame: 30,
+ timeMs: 1000,
+ });
+ expect(resolveFrameRequest({ frame: 7 }, 29.97)).toEqual(
+ resolveFrameRequest({ atMs: 7000 / 29.97 }, 29.97),
+ );
+ });
+ it("rejects invalid time inputs", () => {
+ for (const frame of [-1, 0.5, Infinity, NaN, Number.MAX_SAFE_INTEGER + 1])
+ expect(() => resolveFrameRequest({ frame }, 30)).toThrow(/frame/);
+ for (const atMs of [-1, Infinity, NaN])
+ expect(() => resolveFrameRequest({ atMs }, 30)).toThrow(/atMs/);
+ for (const fps of [0, -1, Infinity, NaN])
+ expect(() => resolveFrameRequest({}, fps)).toThrow(/fps/);
+ });
+ it("counts half-open export windows using rounded duration", () => {
+ expect(frameCount(1000, 30)).toBe(30);
+ expect(frameCount(50, 30)).toBe(2);
+ expect(frameCount(1, 30)).toBe(1);
+ });
+});
diff --git a/packages/core/src/frame-time.ts b/packages/core/src/frame-time.ts
new file mode 100644
index 00000000..38a0c7a3
--- /dev/null
+++ b/packages/core/src/frame-time.ts
@@ -0,0 +1,40 @@
+/** Frame windows are half-open: [startFrame, startFrame + durationFrames). */
+export function frameCount(durationMs: number, fps: number): number {
+ assertFps(fps);
+ if (!Number.isFinite(durationMs) || durationMs <= 0)
+ throw new Error("durationMs must be finite and positive");
+ const count = Math.max(1, Math.round((durationMs / 1000) * fps));
+ if (!Number.isSafeInteger(count))
+ throw new Error("Duration exceeds the safe frame range");
+ return count;
+}
+
+export function assertFps(fps: number): void {
+ if (!Number.isFinite(fps) || fps <= 0)
+ throw new Error(`Invalid fps: ${fps}. Must be finite and > 0.`);
+}
+
+/** Resolve once, before hooks or rendering. atMs takes precedence over frame. */
+export function resolveFrameRequest(
+ request: { frame?: number; atMs?: number },
+ fps: number,
+): { frame: number; timeMs: number } {
+ assertFps(fps);
+ if (
+ request.atMs !== undefined &&
+ (!Number.isFinite(request.atMs) || request.atMs < 0)
+ )
+ throw new Error("atMs must be finite and nonnegative");
+ const frame =
+ request.atMs !== undefined
+ ? Math.round((request.atMs / 1000) * fps)
+ : (request.frame ?? 0);
+ if (!Number.isSafeInteger(frame) || frame < 0)
+ throw new Error(
+ `Invalid frame index: ${frame}. Must be a nonnegative safe integer.`,
+ );
+ const timeMs = (frame / fps) * 1000;
+ if (!Number.isFinite(timeMs))
+ throw new Error("Frame timestamp exceeds the finite range");
+ return { frame, timeMs };
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 1ee3a5ba..86006ec2 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,5 +1,6 @@
export * from "./effects/index.js";
export * from "./errors.js";
+export * from "./frame-time.js";
export * from "./id-gen.js";
export * from "./media-time.js";
export * from "./media-time-signal.js";
diff --git a/packages/framefields/scripts/build-api-catalog.ts b/packages/framefields/scripts/build-api-catalog.ts
new file mode 100644
index 00000000..802ac0d5
--- /dev/null
+++ b/packages/framefields/scripts/build-api-catalog.ts
@@ -0,0 +1,77 @@
+/** Generate the agent-facing timing/preflight API reference from the owning types. */
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+const SOURCES = [
+ ["../../core/src/frame-time.ts", ["frameCount", "resolveFrameRequest"]],
+ ["../src/renderer/framegrid.ts", ["FrameGridOptions", "FrameSamplePoint"]],
+ [
+ "../../compositions/src/program/sequence.ts",
+ [
+ "SceneOptions",
+ "SequenceOptions",
+ "SequenceTimelineResult",
+ "calculateSequenceTimeline",
+ ],
+ ],
+ ["../src/cli/check.ts", ["CheckOptions"]],
+ ["../src/cli/check-result.ts", ["CheckReport", "CheckDiagnostic"]],
+] as const;
+
+export function buildApiCatalog(): { schemaVersion: 1; entries: object[] } {
+ const entries: object[] = [];
+ for (const [file, names] of SOURCES) {
+ const source = ts.createSourceFile(
+ file,
+ readFileSync(new URL(file, import.meta.url), "utf8"),
+ ts.ScriptTarget.Latest,
+ true,
+ );
+ for (const name of names) {
+ const declaration = source.statements.find(
+ (node) =>
+ (ts.isInterfaceDeclaration(node) || ts.isFunctionDeclaration(node)) &&
+ node.name?.text === name,
+ );
+ if (
+ !declaration ||
+ !(
+ ts.isInterfaceDeclaration(declaration) ||
+ ts.isFunctionDeclaration(declaration)
+ )
+ )
+ throw new Error(`Missing API declaration ${name} in ${file}`);
+ const text = declaration.getText(source);
+ const signature =
+ ts.isFunctionDeclaration(declaration) && declaration.body
+ ? `${text.slice(0, declaration.body.getStart(source) - declaration.getStart(source)).trim()};`
+ : text;
+ entries.push({
+ name,
+ declaration: signature,
+ documentation: ts
+ .getJSDocCommentsAndTags(declaration)
+ .map((doc) => doc.getText(source))
+ .join("\n"),
+ properties: ts.isInterfaceDeclaration(declaration)
+ ? declaration.members.map((member) => ({
+ declaration: member.getText(source),
+ documentation: ts
+ .getJSDocCommentsAndTags(member)
+ .map((doc) => doc.getText(source))
+ .join("\n"),
+ }))
+ : undefined,
+ });
+ }
+ }
+ return { schemaVersion: 1, entries };
+}
+
+export function writeApiCatalog(output: string): void {
+ writeFileSync(output, `${JSON.stringify(buildApiCatalog(), null, "\t")}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url))
+ writeApiCatalog(process.argv[2]);
diff --git a/packages/framefields/src/builder-schema-conformance.test.ts b/packages/framefields/src/builder-schema-conformance.test.ts
index 0142d361..4b8c5901 100644
--- a/packages/framefields/src/builder-schema-conformance.test.ts
+++ b/packages/framefields/src/builder-schema-conformance.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from "vitest";
import {
+ CameraAnimation,
Composition,
CompositorProgramSchema,
Layer,
@@ -29,7 +30,22 @@ const builders = {
flex: () => Layer.flex({ children: [Layer.text("a")] }),
box: () => Layer.box({ width: 100, height: 100 }),
camera: () => Layer.camera({ z: -800 }),
+ cameraAnimationInput: () =>
+ Layer.camera({
+ animation: CameraAnimation.camera().dolly({
+ fromDistance: -2000,
+ toDistance: -1000,
+ start: 0,
+ end: 30,
+ }),
+ }),
ambientLight: () => Layer.ambientLight(),
+ ambientLightOptions: () =>
+ Layer.ambientLight({
+ id: "ambient-options",
+ color: "#f00",
+ intensity: 0.6,
+ }),
pointLight: () => Layer.pointLight({ x: 0, y: 0, z: -200 }),
cube: () => Layer.cube({ size: 10 }),
cubeWithFaces: () =>
@@ -95,6 +111,22 @@ const builders = {
};
describe("Layer builders conform to CompositorProgramSchema", () => {
+ it("preserves ambient options and the existing positional call form", () => {
+ expect(
+ Layer.ambientLight({ id: "fill", color: "#123456", intensity: 0.7 }),
+ ).toMatchObject({
+ id: "fill",
+ color: "#123456",
+ intensity: 0.7,
+ lightType: "ambient",
+ });
+ expect(Layer.ambientLight("#123456", 0.7, { id: "fill" })).toMatchObject({
+ id: "fill",
+ color: "#123456",
+ intensity: 0.7,
+ lightType: "ambient",
+ });
+ });
for (const [name, build] of Object.entries(builders)) {
it(name, () => {
const comp = new Composition({
diff --git a/packages/framefields/src/cli.ts b/packages/framefields/src/cli.ts
index 17024b9c..e30157a1 100644
--- a/packages/framefields/src/cli.ts
+++ b/packages/framefields/src/cli.ts
@@ -10,8 +10,10 @@
*/
import { readFileSync } from "node:fs";
import { relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
import { parseArgs } from "node:util";
import { type AddReport, add } from "./cli/add.js";
+import { runCheck } from "./cli/check.js";
import { readConfig } from "./cli/config.js";
import {
FONTS,
@@ -23,6 +25,7 @@ import {
import {
type InitReport,
init,
+ ownVersion,
PACKAGE_MANAGERS,
type PackageManager,
shownPath,
@@ -33,6 +36,9 @@ import { AI_DASHBOARD } from "./cli/templates.js";
const HELP = `Usage: framefields <command> [options]
Commands:
+ api JSON reference generated from timing, grid and check types.
+ check <entry> Build, validate and lint a composition; --render also writes a
+ representative frame and grid. --export defaults to buildFilm.
init [dir] Start a framefields project in dir (default: here), or add
framefields to the project there: package.json, tsconfig,
src/theme.ts, film.ts, render.ts, assets/, .gitignore,
@@ -46,6 +52,14 @@ Commands:
and register them in the generated <components>/fonts.ts.
fonts list List the fonts you can install.
+Options for check:
+ --export <name> Composition or builder export (default buildFilm).
+ --render Also verify the GPU and render a small frame/grid.
+ --output <dir> Inspection artifacts (default output/check).
+ --timeout <ms> Worker timeout in milliseconds (default 60000).
+ --warnings-as-errors Fail on lint warnings.
+ --json Machine-readable check, component list, or font list result.
+
Options for init:
--name <name> Package name (default: the folder's name).
--pm <manager> npm, pnpm, yarn or bun (default: the one running this).
@@ -91,6 +105,12 @@ async function main(argv: string[]): Promise<number> {
emoji: { type: "boolean" },
"no-git": { type: "boolean" },
registry: { type: "string" },
+ json: { type: "boolean" },
+ export: { type: "string" },
+ render: { type: "boolean" },
+ output: { type: "string" },
+ timeout: { type: "string" },
+ "warnings-as-errors": { type: "boolean" },
help: { type: "boolean", short: "h" },
},
});
@@ -101,6 +121,48 @@ async function main(argv: string[]): Promise<number> {
}
const cwd = process.cwd();
const log = (line: string) => process.stdout.write(`${line}\n`);
+ if (command === "api") {
+ const catalog = JSON.parse(
+ readFileSync(
+ fileURLToPath(
+ new URL(
+ import.meta.url.endsWith(".ts") ? "../dist/api.json" : "./api.json",
+ import.meta.url,
+ ),
+ ),
+ "utf8",
+ ),
+ ) as object;
+ log(JSON.stringify({ ...catalog, sdkVersion: ownVersion() }));
+ return 0;
+ }
+ if (command === "check") {
+ if (names.length !== 1) {
+ process.stderr.write(
+ "Usage: framefields check <entry> [--export buildFilm] [--render] [--json]\n",
+ );
+ return 2;
+ }
+ const report = await runCheck({
+ entry: names[0],
+ exportName: values.export,
+ render: values.render,
+ outputDir: values.output,
+ timeoutMs:
+ values.timeout === undefined ? undefined : Number(values.timeout),
+ warningsAsErrors: values["warnings-as-errors"],
+ });
+ if (values.json) log(JSON.stringify(report));
+ else {
+ log(`Check ${report.status}: ${report.entry} (${report.exportName})`);
+ for (const d of report.diagnostics)
+ log(
+ `${d.severity} ${d.code}${d.path ? ` at ${d.path}` : ""}: ${d.message}`,
+ );
+ for (const file of report.artifacts) log(`Wrote ${file}`);
+ }
+ return report.status === "passed" ? 0 : 1;
+ }
if (command === "fonts") return fonts(names, cwd, values, log);
if (command === "init") {
if (names.length > 1) {
@@ -134,6 +196,23 @@ async function main(argv: string[]): Promise<number> {
if (command === "list") {
const index = await registry.index();
+ if (values.json) {
+ log(
+ JSON.stringify({
+ schemaVersion: 1,
+ sdkVersion: ownVersion(),
+ components: await Promise.all(
+ index.map(async (entry) => {
+ const { files: _files, ...item } = await registry.item(
+ entry.name,
+ );
+ return item;
+ }),
+ ),
+ }),
+ );
+ return 0;
+ }
const width = Math.max(...index.map((e) => e.name.length));
for (const e of index)
process.stdout.write(`${e.name.padEnd(width)} ${e.summary}\n`);
@@ -221,11 +300,30 @@ function logFontsModule(
async function fonts(
[sub, ...roles]: string[],
cwd: string,
- values: { overwrite?: boolean; "fonts-dir"?: string; dir?: string },
+ values: {
+ overwrite?: boolean;
+ "fonts-dir"?: string;
+ dir?: string;
+ json?: boolean;
+ },
log: (s: string) => void,
): Promise<number> {
if (sub === "list") {
const { config } = readConfig(cwd);
+ if (values.json) {
+ log(
+ JSON.stringify({
+ schemaVersion: 1,
+ sdkVersion: ownVersion(),
+ fonts: Object.entries(FONTS).map(([role, spec]) => ({
+ role,
+ ...spec,
+ configuredPath: config.fonts?.[role],
+ })),
+ }),
+ );
+ return 0;
+ }
for (const [role, spec] of Object.entries(FONTS))
log(
`${role.padEnd(6)} ${spec.label}${config.fonts?.[role] ? ` (installed: ${config.fonts[role]})` : ""}`,
diff --git a/packages/framefields/src/cli/check-assets.ts b/packages/framefields/src/cli/check-assets.ts
new file mode 100644
index 00000000..8a0cb238
--- /dev/null
+++ b/packages/framefields/src/cli/check-assets.ts
@@ -0,0 +1,51 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type {
+ CompositorProgramConfig,
+ LayoutNode,
+} from "@framefields/compositions/program";
+import type { CheckDiagnostic } from "./check-result.js";
+
+/** Local files only; remote availability and decoding belong to render checks. */
+export function checkLocalAssets(
+ spec: CompositorProgramConfig,
+): CheckDiagnostic[] {
+ const diagnostics: CheckDiagnostic[] = [];
+ const check = (source: string, path: string, layerId?: string) => {
+ if (/^[a-z][a-z\d+.-]*:/i.test(source) && !source.startsWith("file:"))
+ return;
+ const file = source.startsWith("file:") ? fileURLToPath(source) : source;
+ if (!existsSync(file))
+ diagnostics.push({
+ severity: "error",
+ code: "missing_local_asset",
+ stage: "assets",
+ path,
+ ...(layerId && { layerId }),
+ message: `Local asset '${source}' does not exist. Restore it or correct the source path relative to the project working directory.`,
+ });
+ };
+ for (const [i, font] of (spec.fonts ?? []).entries())
+ check(font, `fonts.${i}`);
+ const visit = (nodes: LayoutNode[], path: string) => {
+ for (const [i, node] of nodes.entries()) {
+ const location = `${path}.${i}`;
+ if (node.kind === "media") {
+ const source = node.src ?? node.inputHandleId;
+ if (
+ typeof source === "string" &&
+ (node.src !== undefined || /[/.]/.test(source))
+ )
+ check(
+ source,
+ `${location}.${node.src !== undefined ? "src" : "inputHandleId"}`,
+ node.id,
+ );
+ }
+ if ("children" in node && Array.isArray(node.children))
+ visit(node.children, `${location}.children`);
+ }
+ };
+ visit(spec.layout, "layout");
+ return diagnostics;
+}
diff --git a/packages/framefields/src/cli/check-result.ts b/packages/framefields/src/cli/check-result.ts
new file mode 100644
index 00000000..87bfeae1
--- /dev/null
+++ b/packages/framefields/src/cli/check-result.ts
@@ -0,0 +1,51 @@
+import type { RenderDiagnostic } from "@framefields/core";
+
+export interface CheckDiagnostic extends RenderDiagnostic {
+ stage:
+ | "build"
+ | "schema"
+ | "assets"
+ | "lint"
+ | "timeline"
+ | "render"
+ | "worker";
+ path?: string;
+}
+
+export interface CheckReport {
+ schemaVersion: 1;
+ sdkVersion: string;
+ entry: string;
+ exportName: string;
+ status: "passed" | "failed";
+ diagnostics: CheckDiagnostic[];
+ artifacts: string[];
+ render: "not_requested" | "skipped" | "passed" | "failed";
+ runtime?: { node: string; platform: string; arch: string };
+ timeline?: { fps: number; totalFrames: number; durationMs: number };
+ backend?: {
+ vendor: string;
+ device: string;
+ description: string;
+ software: boolean;
+ };
+}
+
+export function failedCheck(
+ entry: string,
+ exportName: string,
+ sdkVersion: string,
+ code: string,
+ message: string,
+): CheckReport {
+ return {
+ schemaVersion: 1,
+ sdkVersion,
+ entry,
+ exportName,
+ status: "failed",
+ diagnostics: [{ severity: "error", code, message, stage: "worker" }],
+ artifacts: [],
+ render: "not_requested",
+ };
+}
diff --git a/packages/framefields/src/cli/check-worker.ts b/packages/framefields/src/cli/check-worker.ts
new file mode 100644
index 00000000..ff88605d
--- /dev/null
+++ b/packages/framefields/src/cli/check-worker.ts
@@ -0,0 +1,155 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { frameCount } from "@framefields/core";
+import { Composition, CompositorProgramSchema, describeGpu } from "../index.js";
+import type { CheckOptions } from "./check.js";
+import { checkLocalAssets } from "./check-assets.js";
+import { type CheckReport, failedCheck } from "./check-result.js";
+
+type WorkerOptions = CheckOptions & {
+ exportName: string;
+ sdkVersion: string;
+ outputDir: string;
+};
+
+async function inspect(options: WorkerOptions): Promise<CheckReport> {
+ const report: CheckReport = {
+ schemaVersion: 1,
+ sdkVersion: options.sdkVersion,
+ entry: options.entry,
+ exportName: options.exportName,
+ status: "passed",
+ diagnostics: [],
+ artifacts: [],
+ render: options.render ? "skipped" : "not_requested",
+ runtime: {
+ node: process.version,
+ platform: process.platform,
+ arch: process.arch,
+ },
+ };
+ let stage: "build" | "schema" | "lint" | "timeline" | "render" = "build";
+ try {
+ // User-selected entry and export are necessarily loaded at runtime.
+ const mod: Record<string, unknown> = await import(
+ pathToFileURL(options.entry).href
+ );
+ const exported = mod[options.exportName];
+ const comp: unknown =
+ typeof exported === "function" ? await exported() : exported;
+ if (!isComposition(comp))
+ throw new Error(
+ `Export '${options.exportName}' must be a Composition or a builder returning one.`,
+ );
+ stage = "schema";
+ const spec = comp.toSpec();
+ const parsed = CompositorProgramSchema.safeParse(spec);
+ if (!parsed.success) {
+ for (const issue of parsed.error.issues)
+ report.diagnostics.push({
+ severity: "error",
+ code: "invalid_spec",
+ stage,
+ path: issue.path.join("."),
+ message: issue.message,
+ });
+ } else {
+ comp.toVirtualMedia();
+ report.diagnostics.push(...checkLocalAssets(parsed.data));
+ stage = "lint";
+ report.diagnostics.push(
+ ...comp.lint().map((d) => ({ ...d, stage: "lint" as const })),
+ );
+ stage = "timeline";
+ const durationMs = comp.durationMs ?? (await comp.computeDuration());
+ report.timeline = {
+ fps: comp.fps,
+ durationMs,
+ totalFrames: frameCount(durationMs, comp.fps),
+ };
+ if (options.render && !hasErrors(report)) {
+ stage = "render";
+ report.render = "failed";
+ report.backend = await describeGpu();
+ await renderSmoke(comp, report, options.outputDir);
+ report.render = "passed";
+ }
+ }
+ } catch (error) {
+ report.diagnostics.push({
+ severity: "error",
+ code: `${stage}_failed`,
+ stage,
+ message:
+ error instanceof Error ? (error.stack ?? error.message) : String(error),
+ });
+ }
+ if (
+ hasErrors(report) ||
+ (options.warningsAsErrors &&
+ report.diagnostics.some((d) => d.severity === "warning"))
+ )
+ report.status = "failed";
+ return report;
+}
+
+function hasErrors(report: CheckReport): boolean {
+ return report.diagnostics.some((d) => d.severity === "error");
+}
+
+// Bundles can carry distinct Composition constructors; check its public contract.
+function isComposition(value: unknown): value is Composition {
+ return (
+ value instanceof Composition ||
+ (typeof value === "object" &&
+ value !== null &&
+ "toSpec" in value &&
+ typeof value.toSpec === "function" &&
+ "lint" in value &&
+ typeof value.lint === "function" &&
+ "renderFrameGrid" in value &&
+ typeof value.renderFrameGrid === "function" &&
+ "computeDuration" in value &&
+ typeof value.computeDuration === "function")
+ );
+}
+
+async function renderSmoke(
+ comp: Composition,
+ report: CheckReport,
+ outputDir: string,
+): Promise<void> {
+ const count = report.timeline?.totalFrames ?? 1;
+ const frames = [...new Set([0, Math.floor((count - 1) / 2), count - 1])];
+ await mkdir(outputDir, { recursive: true });
+ const frameFile = join(outputDir, "frame.png");
+ await writeFile(frameFile, await comp.renderFrame({ frame: 0 }));
+ report.artifacts.push(frameFile);
+ const gridFile = join(outputDir, "grid.png");
+ await writeFile(
+ gridFile,
+ await comp.renderFrameGrid({ frames, cellWidth: 320 }),
+ );
+ report.artifacts.push(gridFile);
+}
+
+process.once("message", (options: WorkerOptions) => {
+ process.channel?.ref();
+ inspect(options).then(
+ (report) =>
+ process.send?.(report, () =>
+ process.exit(report.status === "passed" ? 0 : 1),
+ ),
+ (error: unknown) => {
+ const report = failedCheck(
+ options.entry,
+ options.exportName,
+ options.sdkVersion,
+ "worker_failed",
+ String(error),
+ );
+ process.send?.(report, () => process.exit(1));
+ },
+ );
+});
diff --git a/packages/framefields/src/cli/check.test.ts b/packages/framefields/src/cli/check.test.ts
new file mode 100644
index 00000000..31b8ca40
--- /dev/null
+++ b/packages/framefields/src/cli/check.test.ts
@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+import { runCheck } from "./check.js";
+
+const exec = promisify(execFile);
+const dirs: string[] = [];
+const sdk = new URL("../index.ts", import.meta.url).href;
+
+async function fixture(body: string): Promise<string> {
+ const dir = await mkdtemp(join(tmpdir(), "ff-check-"));
+ dirs.push(dir);
+ const entry = join(dir, "film.mts");
+ await writeFile(
+ entry,
+ `import { Composition, Layer } from ${JSON.stringify(sdk)};\n${body}`,
+ );
+ return entry;
+}
+
+afterEach(async () => {
+ await Promise.all(
+ dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+ );
+});
+
+describe("agent preflight", () => {
+ it("returns structured schema and lint failures with source paths", async () => {
+ const entry = await fixture(
+ 'export function buildFilm() { const c = new Composition({width:32,height:32,fps:30,durationFrames:2}); c.add(Layer.box({id:"bad",width:32,height:32,background:"definitely-invalid-color"})); return c; }',
+ );
+ const report = await runCheck({ entry });
+ expect(report.diagnostics).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "unknown_color",
+ layerId: "bad",
+ stage: "lint",
+ }),
+ ]),
+ );
+ expect(report.status).toBe("passed");
+ expect((await runCheck({ entry, warningsAsErrors: true })).status).toBe(
+ "failed",
+ );
+ const invalid = await fixture(
+ 'export function buildFilm() { const c = new Composition({width:32,height:32}); c.add({id:"bad",kind:"box",startFrame:-1}); return c; }',
+ );
+ expect((await runCheck({ entry: invalid })).diagnostics).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "invalid_spec",
+ path: "layout.0.startFrame",
+ }),
+ ]),
+ );
+ });
+ it("reports builder errors and a timeout as failures", async () => {
+ const entry = await fixture(
+ 'export function buildFilm() { throw new Error("broken builder"); }',
+ );
+ expect((await runCheck({ entry })).diagnostics[0]).toMatchObject({
+ code: "build_failed",
+ message: expect.stringContaining("broken builder"),
+ });
+ const hanging = await fixture(
+ "export async function buildFilm() { await new Promise(() => {}); }",
+ );
+ expect(
+ (await runCheck({ entry: hanging, timeoutMs: 5000 })).diagnostics[0].code,
+ ).toBe("check_timeout");
+ });
+ it("reports a missing local source before rendering", async () => {
+ const entry = await fixture(
+ 'export function buildFilm() { const c = new Composition({width:32,height:32,fps:30,durationFrames:2}); c.add(Layer.image("./missing-preflight-image.png", {id:"missing",width:32,height:32})); return c; }',
+ );
+ const report = await runCheck({ entry });
+ expect(report.status).toBe("failed");
+ expect(report.diagnostics).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "missing_local_asset",
+ layerId: "missing",
+ stage: "assets",
+ }),
+ ]),
+ );
+ });
+ it("keeps CLI stdout as one JSON object despite a noisy builder", async () => {
+ const entry = await fixture(
+ 'console.log("builder log"); export function buildFilm() { return new Composition({width:32,height:32,fps:30,durationFrames:2}); }',
+ );
+ const { stdout, stderr } = await exec(
+ process.execPath,
+ [
+ "--import",
+ "tsx",
+ "--conditions=development",
+ fileURLToPath(new URL("../cli.ts", import.meta.url)),
+ "check",
+ entry,
+ "--json",
+ ],
+ { timeout: 20000 },
+ );
+ expect(JSON.parse(stdout)).toMatchObject({
+ schemaVersion: 1,
+ status: "passed",
+ timeline: { totalFrames: 2 },
+ render: "not_requested",
+ });
+ expect(stderr).toContain("builder log");
+ });
+});
diff --git a/packages/framefields/src/cli/check.ts b/packages/framefields/src/cli/check.ts
new file mode 100644
index 00000000..84ac3f74
--- /dev/null
+++ b/packages/framefields/src/cli/check.ts
@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { type CheckReport, failedCheck } from "./check-result.js";
+import { ownVersion } from "./init.js";
+
+export interface CheckOptions {
+ /** Module path, resolved from the project working directory. */
+ entry: string;
+ /** Composition or builder export. Defaults to buildFilm. */
+ exportName?: string;
+ /** Also probe the GPU and write a representative PNG and bounded grid. */
+ render?: boolean;
+ /** Artifact directory. Defaults to output/check, relative to the working directory. */
+ outputDir?: string;
+ /** Maximum worker lifetime in milliseconds. Defaults to 60000. */
+ timeoutMs?: number;
+ /** Treat lint warnings as a failed check. Defaults to false. */
+ warningsAsErrors?: boolean;
+}
+
+/** The worker's IPC result is separate from arbitrary builder stdout/stderr. */
+export async function runCheck(options: CheckOptions): Promise<CheckReport> {
+ const entry = resolve(options.entry);
+ const exportName = options.exportName ?? "buildFilm";
+ const sdkVersion = ownVersion();
+ const timeout = options.timeoutMs ?? 60_000;
+ if (!Number.isSafeInteger(timeout) || timeout <= 0)
+ throw new Error("--timeout must be a positive integer in milliseconds");
+ const fail = (code: string, message: string) =>
+ failedCheck(entry, exportName, sdkVersion, code, message);
+ const source = import.meta.url.endsWith(".ts");
+ const args = source ? ["--conditions=development"] : [];
+ // TypeScript belongs to the consumer project; it is already in init's scaffold.
+ if (source || /\.[cm]?tsx?$/.test(entry)) {
+ try {
+ const require = createRequire(resolve("package.json"));
+ args.push("--import", pathToFileURL(require.resolve("tsx")).href);
+ } catch {
+ return fail(
+ "missing_ts_loader",
+ "Install the project's tsx dev dependency to check a TypeScript entry.",
+ );
+ }
+ }
+ args.push(
+ fileURLToPath(
+ new URL(
+ source ? "./check-worker.ts" : "./cli/check-worker.mjs",
+ import.meta.url,
+ ),
+ ),
+ );
+ return new Promise((done) => {
+ const child = spawn(process.execPath, args, {
+ stdio: ["ignore", "pipe", "pipe", "ipc"],
+ });
+ child.stdout?.pipe(process.stderr);
+ child.stderr?.pipe(process.stderr);
+ let result: CheckReport | undefined;
+ const timer = setTimeout(() => {
+ result = fail(
+ "check_timeout",
+ `Check exceeded ${timeout}ms; worker terminated.`,
+ );
+ child.kill("SIGKILL");
+ }, timeout);
+ child.on("message", (message: unknown) => {
+ if (isCheckReport(message)) result = message;
+ });
+ child.on("error", (error) => {
+ clearTimeout(timer);
+ done(fail("worker_start_failed", error.message));
+ });
+ child.on("close", (code, signal) => {
+ clearTimeout(timer);
+ done(
+ result ??
+ fail(
+ "worker_failed",
+ `Check worker exited without a result (code ${code}, signal ${signal}).`,
+ ),
+ );
+ });
+ child.send({
+ ...options,
+ entry,
+ exportName,
+ sdkVersion,
+ outputDir: resolve(options.outputDir ?? "output/check"),
+ });
+ });
+}
+
+function isCheckReport(value: unknown): value is CheckReport {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ "schemaVersion" in value &&
+ value.schemaVersion === 1 &&
+ "diagnostics" in value &&
+ Array.isArray(value.diagnostics)
+ );
+}
diff --git a/packages/framefields/src/cli/init.test.ts b/packages/framefields/src/cli/init.test.ts
index a798f829..f50ecbcb 100644
--- a/packages/framefields/src/cli/init.test.ts
+++ b/packages/framefields/src/cli/init.test.ts
@@ -121,6 +121,8 @@ describe("framefields init", () => {
});
expect(Object.keys(pkg.scripts)).toEqual([
"typecheck",
+ "check",
+ "check:render",
"frames",
"grid",
"preview",
diff --git a/packages/framefields/src/cli/init.ts b/packages/framefields/src/cli/init.ts
index da94111a..0c8ee729 100644
--- a/packages/framefields/src/cli/init.ts
+++ b/packages/framefields/src/cli/init.ts
@@ -338,7 +338,7 @@ function record(report: InitReport, path: string, result: "written" | boolean) {
}
/** This package's version, from the nearest `package.json` named framefields. */
-function ownVersion(): string {
+export function ownVersion(): string {
let dir = dirname(fileURLToPath(import.meta.url));
for (;;) {
const file = join(dir, "package.json");
diff --git a/packages/framefields/src/cli/registry.ts b/packages/framefields/src/cli/registry.ts
index 24ff2c19..1c0f887f 100644
--- a/packages/framefields/src/cli/registry.ts
+++ b/packages/framefields/src/cli/registry.ts
@@ -20,6 +20,14 @@ export interface RegistryEntry {
}
export interface RegistryItem extends RegistryEntry {
+ /** Generated from the component schema and JSDoc. */
+ props?: ReadonlyArray<{
+ name: string;
+ type: string;
+ required: boolean;
+ default?: unknown;
+ description?: string;
+ }>;
parts: readonly string[];
cues: readonly string[];
/** Fonts to install with it, by role (see `cli/fonts.ts`). */
diff --git a/packages/framefields/src/cli/templates.ts b/packages/framefields/src/cli/templates.ts
index 78d86e15..1d2c5853 100644
--- a/packages/framefields/src/cli/templates.ts
+++ b/packages/framefields/src/cli/templates.ts
@@ -27,6 +27,9 @@ export const DEV_DEPENDENCIES: Record<string, string> = {
export const SCRIPTS: Record<string, string> = {
typecheck: "tsc --noEmit -p .",
+ check: "tsc --noEmit -p . && framefields check src/film.ts --json",
+ "check:render":
+ "tsc --noEmit -p . && framefields check src/film.ts --render --json",
frames: "tsx src/render.ts frames",
grid: "tsx src/render.ts grid",
preview: "tsx src/render.ts preview",
@@ -179,7 +182,7 @@ export async function buildFilm(): Promise<Composition> {
export const RENDER_TS = `import { existsSync } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
-import { HeadlessMediaRenderer, startPreview } from "framefields";
+import { HeadlessMediaRenderer, frameCount, startPreview } from "framefields";
import { buildFilm } from "./film.js";
// Optional settings such as FRAMEFIELDS_API_KEY (see .env.example).
@@ -216,7 +219,7 @@ if (mode === "frames") {
}
} else if (mode === "grid") {
const png = await film.renderFrameGrid({
- frames: args.length ? args.map(Number) : [0, 10, 20, 30, 45, 60, 75, 89],
+ frames: args.length ? args.map(Number) : [...new Set([0, Math.floor((frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1) / 2), frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1])],
columns: 4,
cellWidth: 480,
showLabels: true,
diff --git a/packages/framefields/src/framegrid.test.ts b/packages/framefields/src/framegrid.test.ts
index b861bd63..fb561e67 100644
--- a/packages/framefields/src/framegrid.test.ts
+++ b/packages/framefields/src/framegrid.test.ts
@@ -1,3 +1,5 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
import { loadImage } from "skia-canvas";
import { describe, expect, it } from "vitest";
import {
@@ -23,7 +25,7 @@ describe("FrameGrid Rendering Conformance & Validations", () => {
expect(fps).toBe(30);
expect(samples.length).toBe(5); // 10, 15, 20, 25, 30
- expect(samples[0]).toEqual({ frame: 10, timeMs: 333 });
+ expect(samples[0]).toEqual({ frame: 10, timeMs: 1000 / 3 });
expect(samples[4]).toEqual({ frame: 30, timeMs: 1000 });
});
@@ -173,3 +175,78 @@ describe("FrameGrid Rendering Conformance & Validations", () => {
expect(standalonePng.length).toBeGreaterThan(1000);
});
});
+
+describe("bounded canonical grid sampling", () => {
+ it("bounds work before allocating an enormous range", async () => {
+ const source = new URL("./renderer/framegrid.ts", import.meta.url).href;
+ const script = `import { resolveSamplePoints } from ${JSON.stringify(source)};
+ for (const endFrame of [1_000_000_000, Infinity, NaN]) {
+ let rejected = false;
+ try { resolveSamplePoints({ endFrame, stepFrames: 1 }); } catch { rejected = true; }
+ if (!rejected) process.exit(1);
+ }
+ process.exit(0);`;
+ await promisify(execFile)(
+ process.execPath,
+ [
+ "--import",
+ "tsx",
+ "--conditions=development",
+ "--input-type=module",
+ "-e",
+ script,
+ ],
+ { timeout: 10000 },
+ );
+ });
+ it("validates steps, frame indices and limits", () => {
+ for (const stepFrames of [NaN, Infinity, 0.1])
+ expect(() => resolveSamplePoints({ stepFrames })).toThrow();
+ for (const maxFrames of [0, -1, 1.5, NaN, Infinity])
+ expect(() => resolveSamplePoints({ maxFrames })).toThrow(/maxFrames/);
+ expect(() => resolveSamplePoints({ frames: [0.5] })).toThrow(/frame/);
+ expect(() =>
+ resolveSamplePoints({ startMs: 1e20, endMs: 1e20, stepMs: 0.1 }),
+ ).toThrow(/advance/);
+ });
+ it("preserves explicit ordering and duplicates while enforcing the cap", () => {
+ expect(
+ resolveSamplePoints({ frames: [5, 0, 5] }).samples.map((s) => s.frame),
+ ).toEqual([5, 0, 5]);
+ expect(
+ resolveSamplePoints({
+ startFrame: 0,
+ endFrame: 119,
+ stepFrames: 1,
+ maxFrames: 200,
+ }).samples,
+ ).toHaveLength(120);
+ expect(() =>
+ resolveSamplePoints({ endFrame: 120, stepFrames: 1, maxFrames: 200 }),
+ ).toThrow(/120/);
+ });
+ it("keeps automatic samples inside rounded export duration", () => {
+ expect(
+ resolveSamplePoints({}, 30, 1000).samples.map((s) => s.frame),
+ ).toEqual([0, 5, 10, 15, 20, 25]);
+ expect(resolveSamplePoints({}, 30, 1).samples.map((s) => s.frame)).toEqual([
+ 0,
+ ]);
+ expect(
+ resolveSamplePoints({ stepFrames: 1 }, 30, 50).samples.map(
+ (s) => s.frame,
+ ),
+ ).toEqual([0, 1]);
+ expect(
+ resolveSamplePoints({ stepMs: 100 }, 30, 1000).samples.at(-1)?.frame,
+ ).toBeLessThan(30);
+ expect(
+ resolveSamplePoints({ frames: [30] }, 30, 1000).samples[0].frame,
+ ).toBe(30);
+ });
+ it("does not round-trip timestamp labels into another frame", () => {
+ expect(resolveSamplePoints({ timesMs: [16.6], fps: 30 }).samples).toEqual([
+ { frame: 0, timeMs: 0 },
+ ]);
+ });
+});
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index 8aa08d63..42d3f8e5 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -1,3 +1,5 @@
+import { resolveFrameRequest } from "@framefields/core";
+
export {
type Ai,
type AiConfig,
@@ -2189,18 +2191,21 @@ export class Composition {
public async renderFrame(
options: {
atMs?: number;
+ fps?: number;
frame?: number;
renderer?: HeadlessMediaRenderer;
} = {},
): Promise<Buffer> {
+ const { frame } = resolveFrameRequest(options, this.fps);
+ if (options.fps !== undefined && options.fps !== this.fps)
+ throw new Error(
+ `Composition fps is ${this.fps}; cannot render at fps ${options.fps}.`,
+ );
+
// Compile first: the frame's hooks then record its live signal time.
const vm = this.toVirtualMedia();
if (this.hasFrameHooks()) {
- const targetFrame =
- options.frame ??
- (options.atMs !== undefined
- ? Math.round((options.atMs / 1000) * this.fps)
- : 0);
+ const targetFrame = frame;
await this.notifyFrame({
frame: targetFrame,
fps: this.fps,
@@ -2223,7 +2228,7 @@ export class Composition {
const renderer = options.renderer ?? new HeadlessMediaRenderer();
return renderer.renderFrame(vm, {
fps: this.fps,
- ...options,
+ frame,
});
}
@@ -2407,6 +2412,10 @@ function withAnimation<
TCap extends NodeCapability = "visual",
>(node: T): AnimatableNode<T, TCap> {
const target = node as AnimatableNode<T, TCap>;
+ // Animation builders are structurally valid inputs, but carry enumerable
+ // authoring defaults that are not fields of the strict program schema.
+ if (target.animation instanceof LayerAnimation)
+ target.animation = target.animation.toSpec();
Object.defineProperty(target, "animate", {
value: (
...anims: (
@@ -3206,7 +3215,7 @@ export const Layer = {
...options,
}),
ambientLight: (
- color: string = "#ffffff",
+ color: string | Partial<LightNode> = "#ffffff",
intensity: number = 0.5,
options: Partial<LightNode> = {},
): AnimatableNode<LightNode> => Light.ambient(color, intensity, options),
@@ -3385,7 +3394,7 @@ export const Light = {
});
},
ambient: (
- color: string = "#ffffff",
+ color: string | Partial<LightNode> = "#ffffff",
intensity: number = 0.5,
options: Partial<LightNode> = {},
): AnimatableNode<LightNode> =>
@@ -3393,8 +3402,9 @@ export const Light = {
id: options.id ?? autoId("light-ambient"),
kind: "light",
lightType: "ambient",
- color,
+ color: typeof color === "string" ? color : (color.color ?? "#ffffff"),
intensity,
+ ...(typeof color === "object" && color),
...options,
}),
directional: (options: Partial<LightNode> = {}): AnimatableNode<LightNode> =>
diff --git a/packages/framefields/src/renderer/framegrid.ts b/packages/framefields/src/renderer/framegrid.ts
index 6d552d60..02088a71 100644
--- a/packages/framefields/src/renderer/framegrid.ts
+++ b/packages/framefields/src/renderer/framegrid.ts
@@ -1,10 +1,16 @@
import fs from "node:fs/promises";
-import type { VirtualMediaData } from "@framefields/core";
+import {
+ assertFps,
+ frameCount,
+ resolveFrameRequest,
+ type VirtualMediaData,
+} from "@framefields/core";
import { Canvas, loadImage } from "skia-canvas";
import { HeadlessMediaRenderer } from "./index.js";
export interface FrameSamplePoint {
frame: number;
+ /** Exact timestamp of the selected frame; round only when displaying labels. */
timeMs: number;
}
@@ -50,7 +56,8 @@ export interface FrameGridOptions {
timesMs?: number[];
/**
- * Frames per second override. If omitted, reads from media/composition metadata or defaults to 24.
+ * Media pipeline FPS override. Composition FPS is authoritative; a mismatch throws.
+ * If omitted, reads from media/composition metadata or defaults to 24.
*/
fps?: number;
@@ -130,103 +137,113 @@ export interface FrameGridOptions {
/**
* Resolves and validates the list of sample points from the provided options.
*/
+function samplingLimit(requested = 64): number {
+ if (!Number.isSafeInteger(requested) || requested < 1)
+ throw new Error("[FrameGrid] maxFrames must be a positive safe integer.");
+ return Math.min(requested, 120);
+}
+
+function checkSampleCount(count: number, limit: number): void {
+ if (count > limit)
+ throw new Error(
+ `[FrameGrid] Requested frames exceeds the safety threshold of ${limit}. Increase stepFrames/stepMs or narrow the start/end range.`,
+ );
+}
+
+function sampleRange(
+ start: number,
+ end: number,
+ step: number,
+ limit: number,
+ unit: "frame" | "millisecond",
+): number[] {
+ if (
+ !Number.isFinite(start) ||
+ !Number.isFinite(end) ||
+ start < 0 ||
+ end < start
+ )
+ throw new Error(
+ `[FrameGrid] Invalid ${unit} range: start${unit === "frame" ? "Frame" : "Ms"} must be <= end${unit === "frame" ? "Frame" : "Ms"}; bounds must be finite and nonnegative.`,
+ );
+ if (!Number.isFinite(step) || step <= 0)
+ throw new Error(
+ `[FrameGrid] Invalid ${unit === "frame" ? "stepFrames" : "stepMs"}: ${step}. Must be > 0 and finite.`,
+ );
+ if (unit === "frame" && ![start, end, step].every(Number.isSafeInteger))
+ throw new Error(
+ "[FrameGrid] Frame bounds and stepFrames must be safe integers.",
+ );
+ const values: number[] = [];
+ for (let i = 0; ; i++) {
+ const value = start + i * step;
+ if (!Number.isFinite(value))
+ throw new Error("[FrameGrid] Range arithmetic overflow.");
+ if (i > 0 && value <= values[i - 1])
+ throw new Error("[FrameGrid] Step does not advance the sampling range.");
+ if (value > end) break;
+ checkSampleCount(i + 1, limit);
+ values.push(value);
+ }
+ return values;
+}
+
+/** Resolve bounded samples. Explicit endpoints may lie outside the export window. */
export function resolveSamplePoints(
options: FrameGridOptions,
defaultFps = 24,
durationMs?: number,
): { samples: FrameSamplePoint[]; fps: number } {
const fps = options.fps ?? defaultFps;
- if (fps <= 0) {
- throw new Error(`[FrameGrid] Invalid fps: ${fps}. Must be > 0.`);
+ assertFps(fps);
+ const limit = samplingLimit(options.maxFrames);
+ let samples: FrameSamplePoint[];
+ if (options.frames?.length) {
+ checkSampleCount(options.frames.length, limit);
+ samples = options.frames.map((frame) =>
+ resolveFrameRequest({ frame }, fps),
+ );
+ } else if (options.timesMs?.length) {
+ checkSampleCount(options.timesMs.length, limit);
+ samples = options.timesMs.map((atMs) => resolveFrameRequest({ atMs }, fps));
+ } else {
+ samples = rangeSamples(options, fps, durationMs, limit);
}
+ if (!samples.length)
+ throw new Error("[FrameGrid] Zero frames were resolved for sampling.");
+ return { samples, fps };
+}
- const samples: FrameSamplePoint[] = [];
-
- if (Array.isArray(options.frames) && options.frames.length > 0) {
- for (const f of options.frames) {
- if (typeof f !== "number" || f < 0 || !Number.isFinite(f)) {
- throw new Error(`[FrameGrid] Invalid frame index in frames list: ${f}`);
- }
- samples.push({
- frame: Math.round(f),
- timeMs: Math.round((f / fps) * 1000),
- });
- }
- } else if (Array.isArray(options.timesMs) && options.timesMs.length > 0) {
- for (const ms of options.timesMs) {
- if (typeof ms !== "number" || ms < 0 || !Number.isFinite(ms)) {
- throw new Error(`[FrameGrid] Invalid timestamp in timesMs list: ${ms}`);
- }
- samples.push({
- frame: Math.round((ms / 1000) * fps),
- timeMs: Math.round(ms),
- });
- }
- } else if (
+function rangeSamples(
+ options: FrameGridOptions,
+ fps: number,
+ durationMs: number | undefined,
+ limit: number,
+): FrameSamplePoint[] {
+ const lastFrame =
+ durationMs === undefined ? undefined : frameCount(durationMs, fps) - 1;
+ if (
options.startMs !== undefined ||
options.endMs !== undefined ||
options.stepMs !== undefined
) {
- const startMs = options.startMs ?? 0;
- const endMs = options.endMs ?? durationMs ?? startMs + 1000;
- const stepMs = options.stepMs ?? Math.round((5 / fps) * 1000);
-
- if (startMs < 0 || endMs < startMs) {
- throw new Error(
- `[FrameGrid] Invalid millisecond range: startMs=${startMs}, endMs=${endMs}. startMs must be <= endMs.`,
- );
- }
- if (stepMs <= 0) {
- throw new Error(`[FrameGrid] Invalid stepMs: ${stepMs}. Must be > 0.`);
- }
-
- for (let ms = startMs; ms <= endMs; ms += stepMs) {
- samples.push({
- frame: Math.round((ms / 1000) * fps),
- timeMs: Math.round(ms),
- });
- }
- } else {
- const startFrame = options.startFrame ?? 0;
- const endFrame =
- options.endFrame ??
- (durationMs
- ? Math.min(startFrame + 30, Math.floor((durationMs / 1000) * fps))
- : startFrame + 30);
- const stepFrames = options.stepFrames ?? 5;
-
- if (startFrame < 0 || endFrame < startFrame) {
- throw new Error(
- `[FrameGrid] Invalid frame range: startFrame=${startFrame}, endFrame=${endFrame}. startFrame must be <= endFrame.`,
- );
- }
- if (stepFrames <= 0) {
- throw new Error(
- `[FrameGrid] Invalid stepFrames: ${stepFrames}. Must be > 0.`,
- );
- }
-
- for (let f = startFrame; f <= endFrame; f += stepFrames) {
- samples.push({
- frame: Math.round(f),
- timeMs: Math.round((f / fps) * 1000),
- });
- }
- }
-
- const maxFramesLimit = Math.min(options.maxFrames ?? 64, 120);
- if (samples.length > maxFramesLimit) {
- throw new Error(
- `[FrameGrid] Requested ${samples.length} frames exceeds the safety threshold of ${maxFramesLimit}. ` +
- `Increase stepFrames/stepMs or narrow the start/end range to prevent oversized images.`,
- );
- }
-
- if (samples.length === 0) {
- throw new Error("[FrameGrid] Zero frames were resolved for sampling.");
+ const start = options.startMs ?? 0;
+ const end =
+ options.endMs ??
+ (lastFrame === undefined ? start + 1000 : (lastFrame / fps) * 1000);
+ return sampleRange(
+ start,
+ end,
+ options.stepMs ?? 5000 / fps,
+ limit,
+ "millisecond",
+ ).map((atMs) => resolveFrameRequest({ atMs }, fps));
}
-
- return { samples, fps };
+ const start = options.startFrame ?? 0;
+ const end = options.endFrame ?? Math.min(start + 30, lastFrame ?? start + 30);
+ return sampleRange(start, end, options.stepFrames ?? 5, limit, "frame").map(
+ (frame) => resolveFrameRequest({ frame }, fps),
+ );
}
/**
@@ -352,7 +369,6 @@ export async function renderFrameGrid(
for (const sample of samples) {
const buf = await target.renderFrame({
frame: sample.frame,
- atMs: sample.timeMs,
fps,
renderer,
});
@@ -421,7 +437,7 @@ export async function renderFrameGrid(
// Sleek metadata pill badge
if (showLabels) {
- const label = `F:${sample.frame} • ${sample.timeMs}ms`;
+ const label = `F:${sample.frame} • ${Math.round(sample.timeMs)}ms`;
ctx.font = "bold 11px sans-serif";
const textWidth = ctx.measureText(label).width;
diff --git a/packages/framefields/src/timing-contracts.render.test.ts b/packages/framefields/src/timing-contracts.render.test.ts
new file mode 100644
index 00000000..bc1496bc
--- /dev/null
+++ b/packages/framefields/src/timing-contracts.render.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+ Composition,
+ HeadlessMediaRenderer,
+ Layer,
+ LayerAnimation,
+ Sequence,
+ signal,
+} from "./index.js";
+import { decodePngPixels, getPixel } from "./test-utils/pixels.js";
+
+describe("inspection and sequence timing contracts", () => {
+ it("runs hooks and draws the same timestamp-selected frame", async () => {
+ const opacity = signal(0);
+ const frames: number[] = [];
+ const comp = new Composition({
+ width: 32,
+ height: 32,
+ fps: 30,
+ durationFrames: 60,
+ backgroundColor: "#ff0000",
+ });
+ comp.add(
+ Layer.box({ width: 32, height: 32, background: "#00ff00" }).animate(
+ LayerAnimation.create().signal("opacity", opacity),
+ ),
+ );
+ comp.onRequestFrame((ctx) => {
+ frames.push(ctx.frame);
+ opacity.set(ctx.frame === 30 ? 1 : 0);
+ });
+ const renderer = new HeadlessMediaRenderer();
+ const render = vi.spyOn(renderer, "renderFrame");
+ const png = await comp.renderFrame({ frame: 0, atMs: 1000, renderer });
+ expect(frames.every((f) => f === 30)).toBe(true);
+ expect(frames).not.toHaveLength(0);
+ expect(render.mock.calls[0][1]).toMatchObject({ frame: 30, fps: 30 });
+ expect(render.mock.calls[0][1]).not.toHaveProperty("atMs");
+ expect(getPixel(await decodePngPixels(png), 16, 16)).toMatchObject({
+ r: 0,
+ g: 255,
+ b: 0,
+ });
+ await expect(comp.renderFrame({ fps: 24 })).rejects.toThrow(
+ /Composition fps/,
+ );
+ });
+
+ it("passes only canonical frames from fractional timestamp grids", async () => {
+ const comp = new Composition({
+ width: 32,
+ height: 32,
+ fps: 30,
+ durationFrames: 30,
+ backgroundColor: "#ff0000",
+ });
+ const renderer = new HeadlessMediaRenderer();
+ const render = vi.spyOn(renderer, "renderFrame");
+ await comp.renderFrameGrid({ timesMs: [16.6], renderer });
+ expect(render.mock.calls[0][1]).toMatchObject({ frame: 0, fps: 30 });
+ expect(render.mock.calls[0][1]).not.toHaveProperty("atMs");
+ });
+
+ it("clips nested content at the delayed scene layer's exclusive end", async () => {
+ const sequence = Sequence.create({
+ width: 32,
+ height: 32,
+ fps: 30,
+ backgroundColor: "#000000",
+ });
+ sequence.addScene({
+ id: "first",
+ durationFrames: 10,
+ layout: [
+ Layer.box({
+ id: "late",
+ startFrame: 5,
+ width: 32,
+ height: 32,
+ children: [
+ Layer.box({ width: 32, height: 32, background: "#ff0000" }),
+ ],
+ }),
+ ],
+ });
+ sequence.addScene({ id: "next", durationFrames: 10, layout: [] });
+ const comp = new Composition({
+ width: 32,
+ height: 32,
+ fps: 30,
+ durationFrames: sequence.calculateTimeline().totalFrames,
+ backgroundColor: "#000000",
+ });
+ for (const node of sequence.toProgram().layout) comp.add(node);
+ const before = getPixel(
+ await decodePngPixels(await comp.renderFrame({ frame: 9 })),
+ 16,
+ 16,
+ );
+ const after = getPixel(
+ await decodePngPixels(await comp.renderFrame({ frame: 10 })),
+ 16,
+ 16,
+ );
+ expect(before).toMatchObject({ r: 255, g: 0, b: 0 });
+ expect(after).toMatchObject({ r: 0, g: 0, b: 0 });
+ });
+});
diff --git a/packages/framefields/tsdown.config.ts b/packages/framefields/tsdown.config.ts
index 2986e3ca..1bcadb72 100644
--- a/packages/framefields/tsdown.config.ts
+++ b/packages/framefields/tsdown.config.ts
@@ -1,5 +1,6 @@
import { cpSync, existsSync } from "node:fs";
import { defineConfig } from "tsdown";
+import { writeApiCatalog } from "./scripts/build-api-catalog.ts";
import { fixDtsAliases } from "./scripts/fix-dts-aliases.mjs";
import { buildEngine } from "./src/preview/bundle.ts";
@@ -14,6 +15,7 @@ export default defineConfig({
"src/preview/index.ts",
"src/components/index.ts",
"src/cli.ts",
+ "src/cli/check-worker.ts",
],
format: ["esm"],
clean: true,
@@ -28,6 +30,7 @@ export default defineConfig({
);
cpSync(registry, "dist/registry", { recursive: true });
fixDtsAliases("dist");
+ writeApiCatalog("dist/api.json");
},
dts: { resolve: [/^@framefields\//] },
target: "es2022",
diff --git a/packages/renderer/src/headless-webgpu-renderer.ts b/packages/renderer/src/headless-webgpu-renderer.ts
index f08b7c0f..f7c0a979 100644
--- a/packages/renderer/src/headless-webgpu-renderer.ts
+++ b/packages/renderer/src/headless-webgpu-renderer.ts
@@ -10,7 +10,9 @@ import {
preflightMediaTime,
} from "@framefields/compositions";
import {
+ frameCount,
getMediaType,
+ resolveFrameRequest,
takeRenderDiagnostics,
updateClockSignals,
type VirtualMediaData,
@@ -785,10 +787,7 @@ export class HeadlessWebGPURenderer {
? (source as { toVirtualMedia(): VirtualMediaData }).toVirtualMedia()
: (source as VirtualMediaData);
const fps = options.fps ?? (vm.metadata?.fps || 30);
- const frame =
- options.atMs !== undefined
- ? Math.round((options.atMs / 1000) * fps)
- : (options.frame ?? 0);
+ const { frame } = resolveFrameRequest(options, fps);
return this.renderImage(vm, frame, fps, {
renderId: options.renderId,
format: options.format,
@@ -1111,7 +1110,7 @@ export class HeadlessWebGPURenderer {
durationMs = await this.resolveMediaDuration(virtualMedia, fps);
virtualMedia.metadata.durationMs = durationMs;
}
- const totalFrames = Math.max(1, Math.round((durationMs / 1000) * fps));
+ const totalFrames = frameCount(durationMs, fps);
const renderId = `vid-${randomUUID()}`;
const qaOptions: VideoQaOptions | undefined =
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index 8fa2e436..be1ddec2 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -49,6 +49,8 @@ For commercials, films, and multi-shot videos, break the project into discrete,
- **Scene modules (`scenes/hero.ts`):** Each scene returns a full-frame root box with `startFrame` and `durationFrames`. Children position themselves relative to scene start (`frame: 0` = scene onset).
- **Master assembly (`film.ts`):** Imports scenes, mounts them to `comp.add(scene())`, attaches the master soundtrack and composition-level grading/grain.
+For the exported `Scene` / `Sequence` builder, scene windows are half-open: `[startFrame, startFrame + durationFrames)`. A root layer starting at local frame 30 in a 60-frame scene defaults to 30 frames of duration. Explicit root-layer windows must fit their scene; invalid starts or overflow throw with the scene and layer IDs. Children and their keyframes remain local to their parent. Outgoing overlaps place the next scene and cannot exceed either adjacent scene's duration. The final scene's outgoing overlap has no destination and does not shorten the timeline. `calculateTimeline().totalFrames` is the maximum exclusive scene end.
+
```typescript
// theme.ts
export const W = 1920;
@@ -108,6 +110,8 @@ 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
diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.md
index c3114c06..461ecdb9 100644
--- a/plugins/framefields/skills/framefields-render/SKILL.md
+++ b/plugins/framefields/skills/framefields-render/SKILL.md
@@ -44,6 +44,10 @@ Typecheck the project:
npx tsc --noEmit -p .
```
+In projects initialized with the current CLI, `pnpm check` runs typechecking and document preflight. For another entry, run `pnpm exec framefields check src/film.ts --export buildFilm --json`. The export is a `Composition` or a builder returning one; importing it executes project code, so keep rendering, generation and writes out of the builder. The CLI runs it in an isolated process, routes builder logs to stderr and writes one versioned JSON result to stdout. Errors fail the command; warnings fail with `--warnings-as-errors`. `--timeout 60000` bounds the worker lifetime.
+
+`pnpm check:render` adds GPU verification, a frame and a three-point grid under `output/check`; `--output <dir>` changes the location. This smoke check does not replace targeted pixel assertions or video QA. A failed or unavailable GPU check is reported as a failure. Use `pnpm exec framefields api` for timing, grid and preflight type declarations generated from this SDK version.
+
---
### Step 2: Single Frame Inspection (`renderFrame`)
@@ -65,6 +69,8 @@ const pngBuffer = await comp.renderFrame({
await fs.writeFile("output/frame-45.png", pngBuffer);
```
+`atMs` takes precedence when both `frame` and `atMs` are supplied, including for frame hooks. Frame indices must be nonnegative safe integers; fractional timestamps and FPS are supported. A composition's FPS is authoritative: a different render/grid FPS override throws. Media pipelines can still select their rendering FPS.
+
---
### Step 3: Motion & Layout Stability Contact Sheets (`renderFrameGrid`)
@@ -90,6 +96,8 @@ Contact sheets immediately reveal:
- Text clipping or wrapping jumps across keyframe boundaries.
- Bad layer z-indexing or missing cut transitions.
+Grid frame ranges are inclusive, but the composition's duration is exclusive. Automatic sampling stops before the exported frame count (`max(1, round(durationMs * fps / 1000))`). Explicit points may sample beyond the export window for diagnostics. Sample order and duplicates are preserved. Frame steps must be positive safe integers, timestamp steps finite and positive. The sample limit is checked while generating points (64 by default, at most 120); invalid or excessive requests fail before creating a large list. Labels describe the actual selected frame, with timestamps formatted for display only.
+
---
### Step 4: Programmatic Conformance Probes in Vitest
diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.md
index 374b04ac..38f78be9 100644
--- a/plugins/framefields/skills/framefields/SKILL.md
+++ b/plugins/framefields/skills/framefields/SKILL.md
@@ -392,10 +392,15 @@ framefields has a registry of parametric motion components: a mouse pointer with
```bash
npx framefields list # every component, one line each
+npx framefields list --json # generated props, dependencies, fonts and examples
+npx framefields fonts list --json # pinned font catalog and configured paths
+npx framefields api # generated timing/grid/preflight reference
npx framefields add mouse-pointer focus-zoom # writes src/components/<name>/
npx framefields fonts add emoji # color emoji (chat-thread and captions add it themselves)
```
+The generated project also has `check` (TypeScript plus schema/lint/timeline preflight) and `check:render` (adds a GPU frame/grid smoke check) scripts. They produce versioned JSON for agents and terminate with a failure code on errors. For a custom entry, use `framefields check src/film.ts --export buildFilm --json`; add `--render` to write inspection artifacts under `output/check`. Keep the builder free of generation, rendering and writes, because preflight imports and executes it.
+
```typescript
import { MousePointer } from "./components/mouse-pointer/index.js";