frameyard 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,123 @@ Frameyard uses `0.x` versions until the composition, configuration, CLI,
 JSON-result, transcript, and skill contracts stabilize. Before `1.0.0`, a
 contract change may ship in a minor release and is called out explicitly below.
 
+## [0.5.0] - 2026-10-31
+
+### Added
+
+- `examples/webgl/` demonstrates a frame-seeked WebGL shader driven by an
+  external controller.
+- `examples/video/` demonstrates two-pass embedded video with the same
+  composition rendered from WebM and MP4 sources, plus a script that
+  regenerates both clips with FFmpeg.
+- `test/examples.test.ts` captures a still from every bundled example.
+- `pnpm compare-stills <a.png> <b.png>` reports an exact decoded-pixel diff and
+  exits nonzero on any difference, for checking determinism at the capture
+  boundary.
+- The benchmark adds WebGL and embedded-video fixtures, `--concurrency`, and
+  bench-only `--browser-arg`/`--no-browser-arg` A/B runs. `bench/README.md`
+  documents the measurement recipe.
+
+### Changed
+
+- `render` no longer requires `--out`. The default output is
+  `out/<composition-id>.mp4` inside the project root, and scaffolded projects
+  ignore `out/` in `.gitignore`.
+- Production capture composites frames in software while WebGL remains on
+  SwiftShader, and opens and closes parallel browser sessions concurrently.
+  Sequential and `--concurrency 4` renders are substantially faster; capture
+  timing and pixels can change for existing projects. Determinism remains at
+  the capture boundary for the same pinned runtime and inputs. See
+  [ADR 0009](./docs/adr/0009-composite-production-frames-in-software.md).
+- Static validation, the composition host, and preview share one browser-safe
+  composition descriptor for metadata, props, controller, animation, media, and
+  transcript declarations. This is an internal refactor with no authoring
+  contract change.
+
+### Fixed
+
+- Embedded video seeks 1 ms past the frame time so millisecond-rounded WebM
+  timestamps select the intended source frame.
+- Capture sessions stay hidden until the first seek, so an animated ancestor
+  cannot leave the load frame on screen in the captured still.
+
+[0.5.0]: https://github.com/vladiantio/frameyard/compare/v0.4.0...v0.5.0
+
+## [0.4.0] - 2026-10-30
+
+### Breaking
+
+- **Composition authoring model:** compositions are HTML documents, not
+  JavaScript modules. `video.config.js` entries point to `.html` files, and the
+  public `defineComposition` authoring path is removed. The `mount → update →
+  dispose` lifecycle remains only as the optional controller contract.
+- **Authoring namespace:** `fy-composition`, `fy-transcript`, `data-fy-*`,
+  `--fy-*`, and `text/fy-controller` replace the corresponding
+  `frameyard`/`data-frameyard-*` names. Existing embedded-media attributes move
+  from `data-frameyard-*` to `data-fy-*`.
+- **Executable code:** only the optional controller, inline or external, may
+  execute. Other executable `<script>` elements and inline `on*` handlers are
+  rejected.
+- **Validation and karaoke:** domain validation and subtitle/karaoke rendering
+  move to the optional controller; no built-in subtitle renderer is added.
+- **Diagnostics:** warnings are structured diagnostic objects with `severity`,
+  `code`, `message`, and optional `details`, not plain strings. Error envelopes
+  gain optional `error.details` and top-level `diagnostics`. Unsupported visual
+  elements inside a composition (`iframe`, `object`, `embed`) and `javascript:`
+  URLs are rejected.
+
+### Added
+
+- Declarative HTML composition contract: `<fy-composition>` metadata, a
+  `data-fy="props"` default-props block, `data-fy-text`, `data-fy-attr-*`,
+  `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat` bindings.
+- Frame-scheduled CSS animation with `data-fy-anim-start`,
+  `data-fy-anim-duration`, and `data-fy-anim-easing`, plus `--fy-frame`,
+  `--fy-time`, `--fy-progress`, `--fy-fps`, and `--fy-duration` frame-state
+  variables.
+- Optional composition controller, inline or external, with `mount`, `update`,
+  `dispose`, and `validateProps`. Inline controllers are extracted and served
+  through a virtual module URL so relative imports and `import.meta.url` work.
+- Node-side static composition validation before Chromium in `check`, `still`,
+  and `render`, and on load in `dev`, with source-located diagnostics.
+- Binding, animation, script, event-handler, unsupported-element, and
+  asset-reference validation.
+- `entry`, `controller`, and top-level `diagnostics` in `check`, `still`, and
+  `render` JSON results.
+- Agent-facing minimal skeleton, binding table, controller examples, and
+  common-mistakes guidance in the skill and scaffold.
+- Injected composition host exposing `window.__fy` with metadata, resolved
+  audio/transcript clips, `load`, `seek`, `settle`, and `dispose`.
+- HTML `<audio>` and `<fy-transcript>` declarations for the audio timeline and
+  transcript requirements.
+- Same-origin iframe preview and a direct render/check/still path that share
+  the host API.
+
+### Changed
+
+- Preview loads each composition document in a same-origin iframe; `check`,
+  `still`, and `render` navigate directly to the composition URL. The separate
+  preview-page render path is removed.
+- Static validation and the composition host read metadata, default props,
+  controller declarations, animation, media, and transcript rules through one
+  browser-safe composition document reader. Controller `src` is project-relative
+  in host output; the authoring value is retained as `rawSrc`.
+- `check` fails fast on static errors without launching Chromium; warnings
+  still allow frame evaluation. Nested `data-fy-repeat` is rejected with a
+  clear diagnostic; nested data uses the controller.
+- `init` scaffolds an HTML composition and no longer generates a JavaScript
+  composition module.
+- The agent skill, README, design baseline, and project guides document the
+  HTML model. See [the 0.4 migration guide](./docs/migration-0.4.md).
+
+### Removed
+
+- JavaScript composition modules, `defineComposition`, and the
+  `data-frameyard-*` authoring attributes.
+- The preview-page composition loading path used by the renderer.
+
+[0.4.0]: https://github.com/vladiantio/frameyard/compare/v0.3.0...v0.4.0
+
 ## [0.3.0] - 2026-10-30
 
 ### Added

package/GLOSSARY.md

@@ -18,14 +18,42 @@ _Avoid_: Scene, template, video
 The fixed dimensions, frame rate, and duration in frames that define a composition's output contract.
 _Avoid_: Render options, props
 
+**Composition descriptor**:
+The fixed facts read from an HTML composition before frame production: composition metadata, default props, and the controller declaration. It excludes per-load declarations such as audio clips, transcripts, and animation schedules.
+_Avoid_: Composition config, parsed document
+
 **Composition lifecycle**:
-The `mount → update → dispose` sequence that governs a composition's frame production.
+The host-driven sequence that loads an HTML composition, seeks it to frames, and releases it.
 _Avoid_: Render loop, playback lifecycle
 
+**Controller lifecycle**:
+The `mount → update → dispose` sequence a composition controller uses for per-frame computation.
+_Avoid_: Composition lifecycle
+
 **Composition revision**:
 A specific version of a composition's source and metadata.
 _Avoid_: Build, release
 
+**HTML composition**:
+A composition whose source is an HTML document.
+_Avoid_: HTML template, page
+
+**Composition controller**:
+An optional JavaScript controller, either inline in the composition document or in an external module, that performs per-frame computation an HTML composition's declarative HTML and CSS cannot express.
+_Avoid_: Composition module, plugin
+
+**Inline controller**:
+A composition controller whose source is embedded in the composition document.
+_Avoid_: Embedded script
+
+**External controller**:
+A composition controller whose source is a separate JavaScript module referenced by the composition document.
+_Avoid_: Controller file
+
+**Declarative binding**:
+An HTML attribute that maps a prop into text, an attribute, a class, or element presence.
+_Avoid_: Template expression, interpolation
+
 **Props**:
 The immutable, JSON-serializable inputs supplied to a composition for one render.
 _Avoid_: Options, settings, mutable state
@@ -48,6 +76,10 @@ _Avoid_: Playback-driven animation
 The single source of animation time, derived from the current frame and the composition's frame rate.
 _Avoid_: Wall clock, playback timer
 
+**Frame-state variable**:
+A CSS custom property whose value is derived from the current composition frame.
+_Avoid_: Animation variable, clock variable
+
 **Seek safety**:
 The property that any frame can be produced correctly without depending on previously produced frames.
 _Avoid_: History-dependent updates
@@ -88,14 +120,26 @@ _Avoid_: Soundtrack, audio track, final cut
 
 ### Rendering
 
+**Composition host**:
+The injected runtime that loads an HTML composition, applies its bindings, and exposes its frame clock to preview and render.
+_Avoid_: Preview runtime, render runtime
+
 **Preview**:
 An interactive, frame-accurate inspection of a composition using the same composition behavior as a render.
 _Avoid_: Visual editor
 
 **Check**:
-A validation operation that checks configuration, props, assets, audio, and transcript requirements, then mounts a composition and evaluates every frame without capturing or encoding.
+A validation operation that first runs static composition validation, then loads a composition and evaluates every frame without capturing or encoding.
 _Avoid_: Test render, dry run
 
+**Static composition validation**:
+The Node-side validation of a composition document's metadata, bindings, controller declaration, scripts, and asset references before browser frame production.
+_Avoid_: Lint, preflight
+
+**Composition diagnostic**:
+A structured error or warning about a composition's source, metadata, bindings, controller, assets, or frame production, with a stable code and optional source location.
+_Avoid_: Log message, error string
+
 **Render**:
 The production of one complete video from a composition and a fixed set of props.
 _Avoid_: Recording, export