visualfries 0.1.10115 → 0.3.2

package/docs/AUTHORING_BEST_PRACTICES.md

@@ -0,0 +1,188 @@
+# VisualFries Authoring Best Practices
+
+VisualFries is an authoring system, not only a schema. A scene is correct only when its semantic components survive validation, runtime evaluation, frame QA, and final rendering.
+
+## Default workflow
+
+```text
+inspect inputs and runtime
+  -> choose native semantic components
+  -> author scene
+  -> validate + inspect structure
+  -> frame-QA entry, settled, and exit states
+  -> reseek the same frames
+  -> render with the deterministic final path
+```
+
+Validation proves shape. `inspect` proves structural references and timing. Neither proves that a renderer evaluates an animation or effect.
+
+## Component decision tree
+
+1. Is the visible content typography?
+   - Use `TEXT` for headings, metrics, labels, badges, cards, verdicts, CTAs, and other editable words.
+   - Use `SUBTITLES` when typography follows transcript timing.
+2. Is it a photo, screenshot, logo, illustration, or supplied bitmap/vector asset?
+   - Use `IMAGE` (`GIF` for animated image assets).
+3. Is it moving footage or sound?
+   - Use `VIDEO` or `AUDIO`.
+4. Is it independent geometry, decoration, progress, a mask-like layout element, or a transition cover?
+   - Use `SHAPE`.
+5. Does typography require a treatment that native `TEXT` cannot render?
+   - Rasterization is an explicit fallback. Record the missing native capability and frame-QA the result. Do not rasterize typography merely for convenience.
+
+## Native TEXT is mandatory by default
+
+Use one `TEXT` component for a normal metric badge such as `881 VIEWS`. It owns its text, background, radius, alignment, outline, shadow, and animation.
+
+Good:
+
+```json
+{
+	"id": "views-badge",
+	"type": "TEXT",
+	"text": "881 VIEWS",
+	"timeline": { "startAt": 0.2, "endAt": 2.8 },
+	"order": 10,
+	"appearance": {
+		"x": 90,
+		"y": 150,
+		"width": 420,
+		"height": 132,
+		"horizontalAlign": "center",
+		"verticalAlign": "center",
+		"background": {
+			"enabled": true,
+			"color": "#F5D547",
+			"target": "wrapper",
+			"radius": 24
+		},
+		"text": {
+			"fontFamily": "Montserrat",
+			"fontSize": { "value": 72, "unit": "px" },
+			"fontWeight": "900",
+			"color": "#101820",
+			"textAlign": "center",
+			"outline": { "enabled": true, "color": "#FFFFFF", "size": 2 },
+			"shadow": {
+				"enabled": true,
+				"color": "#000000",
+				"blur": 12,
+				"offsetX": 0,
+				"offsetY": 4,
+				"opacity": 0.55
+			}
+		}
+	}
+}
+```
+
+Bad:
+
+- `881 VIEWS.png` as a full-card `IMAGE`.
+- A rectangle `SHAPE` whose only purpose is to sit behind ordinary `TEXT`.
+- SVG typography generated by a production plan without an explicit native limitation.
+- Assuming schema-valid `clipColor`, dashed outline, or a generic blur must render.
+
+A separate `SHAPE` is justified when geometry needs independent timing, motion, progress behavior, or decoration. It is not the default badge background.
+
+Directly authored transition geometry is `SHAPE`. `addAgentTransitions` now emits a full-frame animated rectangle rather than the former empty-TEXT compatibility cover.
+
+Complete example: [`examples/native-text-metric-badge.json`](examples/native-text-metric-badge.json).
+
+## TEXT rendering and compositing
+
+`TEXT` uses a wrapper plus an inner text element.
+
+- `appearance.background.target: "wrapper"` fills the fixed component box. Use this for badges/cards and for gradient text on a background.
+- `appearance.background.target: "element"` hugs the glyph block and receives legacy `0.22em` padding only when explicit padding is absent.
+- `appearance.text.padding` accepts a non-negative pixel number or `{ top, right, bottom, left }`.
+- `appearance.background.radius` is in pixels.
+- `appearance.text.color` accepts solid colors or gradients. Gradient glyphs use CSS background clipping.
+- `appearance.background.color` accepts solid colors or gradients.
+- Avoid gradient glyphs plus an element-target background: both compete for the inner element's CSS background. Use a wrapper background.
+- Structured outline uses pixel width. Only solid outline is rendered; `dashed`, `dotted`, and `dashArray` remain validation-only.
+- Structured shadow renders color, opacity, x/y offsets, and blur. Legacy named shadow presets remain separate behavior.
+- Wrapper-background TEXT animations target the wrapper, so background and glyph enter together.
+- Plain `TEXT` can target `words`, `lines`, or `chars` through SplitText animations. Transcript-timed active-word behavior belongs on `SUBTITLES`; plain TEXT has no typed word-timing authoring field.
+- `activeWord` and `activeLine` support color/background/weight/scale. `highlightColors` cycles solid colors by active index. If both modes are enabled, `activeWord` wins and validation reports the conflict.
+- Gradient entries in `highlightColors` are diagnosed as unsupported.
+- `clipColor` has no defined runtime semantics. Runtime-aware validation warns before permissive nested parsing can strip it; strict mode rejects it.
+
+Browser preview keeps TEXT as HTML above the Pixi canvas. Server/final rendering rasterizes TEXT into Pixi. Risky cross-type stacking and CSS effects require final-render frame QA because preview and final compositing can differ.
+
+## Animation contract
+
+Runtime-confirmed component animation support:
+
+| Component           | Animation status      | Notes                                                                                        |
+| ------------------- | --------------------- | -------------------------------------------------------------------------------------------- |
+| `TEXT`              | Supported             | Element or wrapper target; words/lines/chars available.                                      |
+| `SUBTITLES`         | Supported with limits | Cue timing works; advanced `out` anchors need visual QA.                                     |
+| `IMAGE`             | Supported             | Shared Pixi target: relative x/y offsets, opacity, degree rotation, uniform and axis scales. |
+| `VIDEO`             | Supported transforms  | Same Pixi contract; playback-rate/loop parity remains limited.                               |
+| `GIF`               | Supported transforms  | Same Pixi contract; native/final GIF timing parity remains limited.                          |
+| `SHAPE`             | Supported             | Regular and progress shapes use a stable outer Pixi target.                                  |
+| `COLOR`, `GRADIENT` | Supported             | Canvas fill rendered into Pixi, then the shared transform target.                            |
+| `AUDIO`             | Not applicable        | AUDIO has no visual animation target.                                                        |
+
+For Pixi visuals, animation `x` and `y` are translation offsets relative to authored placement. Pivot/transform origin is fixed at the component center and is not author-configurable. This matches TEXT translation semantics and keeps swipe/drift helpers coherent.
+
+Animation rules:
+
+- `component.timeline.startAt` offsets the component timeline.
+- Animation-entry `startAt` is relative to component start.
+- `enabled: false` entries do not run.
+- Prefer frame-index-derived times (`frame / fps`) for deterministic QA.
+- For each animation, inspect pre-entry, first-active/mid-entry, settled, and exit frames.
+- Seek forward, backward, and back to the same frame. Same frame must reproduce the same transform/pixels.
+- Destroy/rebuild tests matter; teardown must revert and kill GSAP timelines.
+- SplitText selectors (`words`, `lines`, `chars`, CSS selectors) are TEXT-only. Runtime-aware validation warns (or errors in strict mode) instead of treating Pixi root fallback as support.
+- Animation `setup` steps and `alignTween: "end"|"center"` are not production-safe yet.
+
+Complete IMAGE example: [`examples/image-animation.json`](examples/image-animation.json).
+
+## Effects and renderer truth
+
+Confirmed:
+
+- TEXT: structured shadow and solid outline.
+- IMAGE/VIDEO: `layoutSplit` and `fillBackgroundBlur` through the Pixi split-screen path.
+- SHAPE: basic canvas/Pixi geometry and progress shapes.
+
+Validation-only or incomplete:
+
+- Generic `blur`, `colorAdjustment`, and `rotationRandomizer` are not generally attached to renderers.
+- SHAPE rectangle `cornerRadius` and gradient fill require explicit rendered verification; do not treat schema acceptance as support.
+- Agent transition helpers emit native animated SHAPE rectangles.
+- Same-layer component stacking uses `component.order` (higher order renders later/on top after synchronization). Higher layer order renders above lower layer order in final Pixi composition.
+
+## QA checklist
+
+```bash
+visualfries doctor --json
+visualfries catalog --component TEXT --capabilities --json
+visualfries validate scene.json --strict-runtime-support
+visualfries inspect scene.json --json
+visualfries explain scene.json --component views-badge --frame 12 --json
+visualfries parity scene.json --frames 5,12,35 --output qa/parity --json
+
+# Render explicit frame windows around authored events.
+visualfries render scene.json --frames-only --from-frame 5 --to-frame 20 --output qa/entry
+visualfries render scene.json --frames-only --from-frame 35 --to-frame 36 --output qa/settled
+
+# Final VIDEO/GIF scenes use deterministic-local rendering.
+visualfries render scene.json --stream-encode --output out.mp4
+```
+
+Uniform three-frame sampling can miss a late or short entrance. Production plans should declare exact `qa.framesAt`; raw scenes should render explicit frame ranges.
+
+`parity` captures actual client composition and final server composition, records SHA-256 plus raw and semantic ffmpeg SSIM, evaluates optional class/ROI thresholds from `--rois`, and renders every requested frame forward then backward. It also writes 4× amplified diff rows and a contact sheet. Add `--strict` for CI. The torture-scene baseline passes with zero runtime/resource errors; raw GIF/video decoder noise remains visible and is reported separately from semantic mismatch.
+
+## Known open limitations
+
+- Visual transform origin is fixed center for Pixi targets; TEXT uses CSS transform ownership. No authorable cross-renderer origin exists.
+- Browser HTML TEXT versus final Pixi TEXT can produce cross-type stacking differences.
+- `clipColor`, gradient highlight palettes, dashed/dotted outline, generic effects, and animation setup steps are unsupported.
+- Native GIF timing and VIDEO/GIF playback controls are not yet preview/final parity guarantees.
+- `componentCenter` and advanced out/align anchors have timing limitations.
+- Radial GRADIENT shape/position currently uses a centered max-radius fallback.

package/docs/AUTHORING_SYSTEM_AUDIT.md

@@ -0,0 +1,98 @@
+# VisualFries Authoring System Audit
+
+Date: 2026-07-12
+
+Scope: schema/runtime truth, semantic component selection, visual animation, TEXT compositing, agent diagnostics, preview/final parity, and real frame QA. The current repo is authoritative. The browser/WebGL/MediaBunny worktree was evidence only; browser export was not blindly ported.
+
+## Findings, evidence, disposition
+
+| Severity | Finding                                                                                                                               | Evidence                                                                                     | Disposition                                                                                                                                                                                                                              |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Critical | Schema accepted animation data for every component although construction attached `AnimationHook` only to TEXT/SUBTITLES/IMAGE.       | Base component schema versus `ComponentDirector`; browser regression from the Funeral short. | Fixed for every visual type through a shared Pixi wrapper target; AUDIO remains explicitly nonvisual. Registry/director synchronization tests prevent silent drift.                                                                      |
+| Critical | COLOR and GRADIENT validated but had no render hook.                                                                                  | `ComponentDirector` returned bare components.                                                | Fixed with canvas fills, Pixi texture/display construction, shared animation target, tests, and frame-QA scene coverage.                                                                                                                 |
+| High     | IMAGE x/y bridge used absolute-center semantics that contradicted TEXT and authored drift/swipe helpers.                              | `PixiAnimationTarget`, b-roll helpers, transition helpers.                                   | Fixed: all Pixi x/y are placement-relative offsets around a fixed-center outer wrapper. Migration note added.                                                                                                                            |
+| High     | Unsupported runtime fields could validate silently.                                                                                   | Base animation catchalls, permissive nested TEXT parsing, effect schemas.                    | Fixed materially: capability registry, default warnings, strict runtime-support gate, property/selector/effect/text conflict diagnostics, and pre-parse clipColor detection. Unknown string presets still need deeper static resolution. |
+| High     | Production-plan visible typography defaulted to raster/SVG.                                                                           | Overlay schema/compiler.                                                                     | Fixed: native TEXT is default; SVG remains explicit documented fallback.                                                                                                                                                                 |
+| High     | Transition helpers used empty TEXT as full-frame geometry.                                                                            | Agent transition helper and regressions.                                                     | Fixed: helpers now emit animated native SHAPE rectangles.                                                                                                                                                                                |
+| High     | Browser HTML TEXT and final Pixi-rasterized TEXT do not share one stacking representation.                                            | `DomManager`, `HtmlTextHook`, `HtmlToCanvasHook`.                                            | Calibrated parity now passes for supported stacking in the torture scene. Arbitrary HTML/Pixi cross-layer interleaving remains an explicit architectural limitation.                                                                       |
+| Critical | Generated browser harness replaced EventEmitter3 with a shim that discarded listener context, breaking Pixi WebGL prerender and texture updates. | Browser stacks at `BatchRenderer.onPrerender` (`_flushId`) and `Texture.onBaseTextureUpdated` (`noFrame`). | Fixed with a context/once/removal-compatible shim and regression. Browser IMAGE/VIDEO/GIF/SHAPE/COLOR/GRADIENT now render with zero runtime errors. |
+| High     | Client seek returned before its asynchronous render and newly attached animation timelines settled.                                   | `TimelineManager.seek`, `RenderManager` queue, sparse browser captures.                       | Fixed: both renderer paths now render, re-seek after lazy construction, render again, and the harness performs an initialized seek barrier.                                                                                               |
+| High     | Preview and final used different hard-coded canvas backgrounds and ignored scene background.                                          | `AppManager` renderer options.                                                               | Fixed: both paths use the solid scene background contract; gradient scene backgrounds still require a GRADIENT component.                                                                                                                |
+| Medium   | Unconfigured system fonts were treated as Google Fonts, creating CORS failures and nondeterministic fallback noise.                    | Font discovery and SVG text generation.                                                      | Fixed: remote font loading is explicit; unconfigured Arial/system families stay local.                                                                                                                                                   |
+| Medium   | TEXT padding, active scale, and highlight palette fields were absent/ignored.                                                         | TEXT schema/builders/highlighter builders.                                                   | Fixed: px padding, active word/line scale, solid palette cycling, reset coverage, and deterministic active-word precedence.                                                                                                              |
+| Medium   | Active-line reset restored background styling instead of glyph color.                                                                 | `LineHighlighterAnimationBuilder`.                                                           | Fixed and asserted explicitly.                                                                                                                                                                                                           |
+| Medium   | `clipColor` was silently stripped by permissive nested parsing and had no defined semantics.                                          | Runtime/schema search plus parse behavior.                                                   | Not invented. Warned by default, rejected by strict gate, documented as open semantic design.                                                                                                                                            |
+| Medium   | `visible: false` became true in component state.                                                                                      | Truthy fallback in `_ComponentState`.                                                        | Fixed with nullish default and shared wrapper visibility enforcement.                                                                                                                                                                    |
+| Medium   | Same-layer order, component teardown, structured shadow/outline, wrapper transform ownership, and radius units had confirmed defects. | Prior audit source/render tests.                                                             | Fixed in the current uncommitted audit set with regression coverage.                                                                                                                                                                     |
+| High     | Scene teardown destroyed Pixi before async component hooks completed, while manager listeners could not be removed by identity.          | `SceneBuilder.destroy`, `ComponentsManager.destroy`, `EventManager.on`, `RenderManager`.       | Fixed: component/media teardown is awaited before Pixi/DOM destruction; registered callback identities are detached and covered by lifecycle regressions.                                                                                |
+
+## Runtime truth
+
+- TEXT/SUBTITLES: HTML animation target; TEXT selectors include container, words, lines, chars, and CSS.
+- IMAGE/VIDEO/GIF/SHAPE/COLOR/GRADIENT: stable outer Pixi target with relative x/y, opacity, degree rotation, scale, scaleX, and scaleY. Pixi selectors support container only.
+- AUDIO: no visual target and no visual animation claim.
+- Visual timing is component-relative; disabled global/list entries do not evaluate; destroy reverts/kills timelines.
+- Pixi transform origin is fixed component center and not authorable.
+- COLOR supports CSS-color canvas fill including alpha. GRADIENT supports linear/radial canvas fills; radial shape/position currently falls back to centered max radius.
+
+## TEXT/compositing truth
+
+- Paint/style merge order is component background, glyph fill/gradient, then text effects. Active highlight background is a separate element behind split glyphs.
+- Wrapper-target background is preferred for badges/cards and required when both background and glyph are gradients.
+- Element-target gradient background plus gradient glyph fill is diagnosed because both use `background-image` on the inner element.
+- Pixel padding is authorable through `appearance.text.padding`; absent element-target padding keeps the prior `0.22em` fallback.
+- Active word/line scale and solid `highlightColors` work. Active word takes precedence if both modes are enabled. Gradient highlight palettes remain unsupported.
+- Structured solid outline and structured shadow work. Dashed/dotted outline and generic effects remain unsupported/incomplete.
+
+## Agent contract
+
+```bash
+visualfries catalog --component TEXT --capabilities --json
+visualfries validate scene.json                    # compatible load + explicit warnings
+visualfries validate scene.json --strict-runtime-support
+visualfries inspect scene.json --json
+visualfries explain scene.json --component <id> --frame <n> --json
+```
+
+`explain` seeks the actual browser runtime and reads the chosen HTML/Pixi target; it does not approximate easing in a separate static evaluator.
+
+## Verification state
+
+- `pnpm exec vitest run`: 64/64 files, 439/439 tests passed.
+- `pnpm run check`: 0 errors; 8 pre-existing docs/accessibility/CSS warnings.
+- `pnpm run build`: passed; `pnpm run package` and standalone `pnpm exec publint` passed.
+- A local runtime-truth torture scene passed strict runtime validation with 0 issues across 9 visual components. Generated QA inputs and outputs are intentionally not committed.
+- Real deterministic final render: 46 frames; frames 0, 9, 18, 30, and 45 visually reviewed.
+- Sparse forward/back/reseek `[18, 30, 18]`: repeated frame 18 matched exactly at SHA-256 `5e30d8dd44ed7cd9ee7ecca8dd6f48dcbf8a48adfd4ac11b47d0eb3d1645636b`.
+- Runtime `explain` at SHAPE frame 18 returned the actual Pixi target and computed x/y/opacity/rotation/scales.
+- Browser/final parity is green on frames 0, 9, 18, 30, and 45. Raw whole-frame SSIM is `0.926262–0.999791`; semantic SSIM is `0.967344–0.999804`. Same-Pixi settled ROIs are `0.995803–1.0` raw, TEXT/SUBTITLES are `0.997588–0.999813`, and zero browser/final runtime or resource errors were recorded.
+- Forward/reverse order `[0,9,18,30,45,45,30,18,9,0]` is stable. Frames 9/18/30/45 are byte-exact in both paths; final frame 0 repeats at SSIM `0.999791` because SVG text rasterization differs by at most three luma levels.
+- A local contact sheet and parity manifest were reviewed across preview, final, and amplified-difference outputs; generated files are intentionally not committed.
+- `git diff --check`: clean. No commit, push, merge, publish, or global-skill modification occurred.
+
+## Open limitations
+
+1. Browser HTML typography is always above the shared Pixi canvas. Arbitrary TEXT/Pixi cross-layer interleaving can still differ from final ordering; the supported torture composition keeps typography above Pixi visuals.
+2. Native GIF and deterministic ffmpeg decoding differ in palette dithering. Raw GIF ROI reaches `0.539`; 2px semantic SSIM is `0.977`, confirming matching structure/color fields without pretending pixels are identical.
+3. Native browser VIDEO and predecoded final VIDEO use different decode/color paths; current ROI semantic SSIM is `0.939–0.998`. Exact media-frame identity needs a future PTS contract for half-frame starts.
+4. Plain absolute local paths now load, but relative paths are still resolved from process cwd rather than the scene file directory, and assetId-only component sources still need runtime hydration from the asset registry.
+5. Final frame-0 SVG text reseek is visually stable (`0.999791`) but not byte-exact. Other sampled forward/back reseeks are exact.
+6. Transform origin is not authorable across visual renderers.
+7. `clipColor` semantics, gradient highlight palettes, generic effects, dashed/dotted outline, and animation setup steps remain unsupported.
+8. Unknown system animation preset names are still resolved at construction time rather than fully diagnosed statically.
+9. Advanced animation center/end anchors and active-line transcript timing remain limited.
+10. Radial gradient shape/position fields use a centered fallback.
+11. Browser export remains a separate next phase; the MediaBunny spike was not promoted without the higher-priority runtime-truth/parity gates.
+
+## Honest readiness score
+
+| Dimension | Score | Reason |
+| --- | ---: | --- |
+| Creative speed | 8.3/10 | Semantic helpers, native transitions, and capability discovery remove substantial source-reading. |
+| Runtime trust | 8.2/10 | Strict runtime gate and construction-synchronized registry close the largest silent-success gaps. Unknown preset resolution remains. |
+| Editability | 8.7/10 | Native TEXT defaults, padding/highlighting, SHAPE transitions, and raw JSON output preserve authorability. |
+| Determinism | 8.2/10 | Shared targets and frames 9/18/30/45 reseek exactly; frame-0 SVG text is visually stable rather than byte-exact, and native media timing caveats remain. |
+| Debugging | 8.0/10 | Runtime-backed explain plus stable capability IDs are useful; deeper preset/effect state could improve. |
+| Agent ergonomics | 8.1/10 | Catalog, strict validate, inspect, explain, docs, examples, and release notes form a coherent loop. |
+| Preview/final parity | 8.2/10 | Zero missing visuals/errors; semantic whole-frame and all class ROIs pass. Cross-layer HTML/Pixi ordering and decoder-level pixel differences remain. |
+| Production readiness | 8.0/10 | Agent-visible runtime truth plus green supported-path parity clears the 8/10 bar. Relative/assetId media hydration and arbitrary mixed stacking still block 9/10. |

package/docs/BROWSER_EXPORT_SPIKE.md

@@ -0,0 +1,55 @@
+# Browser WebGL + MediaBunny export spike
+
+This spike adds a separate deterministic browser export path. Existing interactive preview and local/cloud FFmpeg rendering are unchanged.
+
+MediaBunny is pinned to `1.49.0` for this spike. The newer release available during implementation was less than 14 days old.
+
+## Architecture and next slices
+
+Current scene transitions are schema data only; existing agent transitions are full-frame overlay components. This milestone therefore keeps normal preview untouched and proves a separate browser export boundary: server-mode Pixi scene canvases → curated WebGL transition canvas → MediaBunny encode/mux. Next reviewable slices are: wire the curated adapter into a frame-index transition manager at the renderer's pre-present seam, adapt MediaBunny decoded samples to the deterministic media provider for real browser video inputs, then add an OPFS/File System Access target for long exports. None requires replacing the FFmpeg/cf-worker fallback.
+
+## What it proves
+
+- VisualFries/Pixi renders two animated 1080x1920 scenes at exact `frameIndex / 30` timestamps.
+- A curated gl-transitions-compatible WebGL adapter composites `from`, `to`, `progress`, `ratio`, and whitelisted parameters. It ships `fade` and `radial-wipe`; shader compile/link failure falls back to fade.
+- The final WebGL canvas is fed directly to MediaBunny `CanvasSource`. No PNG/JPEG serialization and no websocket frame transport occurs.
+- MediaBunny encodes AVC/H.264 video and AAC audio and muxes MP4. The in-browser audio mix starts at timestamp zero.
+- Every `CanvasSource.add()` is awaited, propagating encoder/writer backpressure. The 10-second demo uses `BufferTarget`; larger integrations can pass a positional `StreamTarget` writable that honors each chunk's `position`.
+
+## Run interactively
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:5173/browser-export-spike`, confirm the AVC + AAC capability report, then click **Render 10-second MP4**.
+
+## Produce the checked artifact
+
+```bash
+node scripts/render-browser-export-spike.mjs
+```
+
+Default output: `artifacts/browser-export-spike/demo.mp4`.
+
+Inspect it:
+
+```bash
+ffprobe -v error -show_streams -show_format artifacts/browser-export-spike/demo.mp4
+ffmpeg -i artifacts/browser-export-spike/demo.mp4 -vf "select='eq(n,119)+eq(n,120)+eq(n,135)+eq(n,149)+eq(n,150)'" -vsync 0 artifacts/browser-export-spike/frame-%02d.png
+```
+
+Expected: 300 frames, 10 seconds, 1080x1920 AVC video, AAC stereo audio with `start_time=0`, no blank transition samples, and zero shader fallbacks on a compatible WebGL implementation.
+
+## Verified artifact (2026-07-11)
+
+- H.264, 1080x1920, 30fps, 300 decoded frames, video duration `10.000000`
+- AAC stereo, 48kHz, audio `start_time=0.000000` (AAC padding extends its reported duration to `10.069333`)
+- First 100ms audio RMS approximately `-34.6 dB`, confirming immediate non-silent audio
+- Transition-window sampled average luma ranged `38.49..50.77`; visual frame inspection found no blank/white frame
+- Four motion samples produced four different decoded-frame hashes
+- Runtime shader fallback count: `0`
+
+## Capability and fallback contract
+
+The browser path probes the exact requested dimensions and AVC/AAC configuration before work starts. It never silently changes codecs. If unavailable, the structured result names `deterministic-local-ffmpeg`, preserving the existing VisualFries/cf-worker fallback. This milestone does not promise mobile support or arbitrary user GLSL.

package/docs/DETERMINISTIC_RENDERER.md

@@ -0,0 +1,83 @@
+# VisualFries Deterministic Renderer
+
+VisualFries should own final rendering as a local, first-class capability.
+
+## Decision
+
+Final output for scenes containing `VIDEO` or `GIF` media must not rely on native browser media seek. Browser media seek is acceptable for preview and QA only.
+
+The local deterministic renderer is the source-of-truth path:
+
+```text
+scene.json
+  -> collect VIDEO/GIF requirements
+  -> predecode media to exact frame images/manifests
+  -> browser compositor receives exact frame image for each scene frame
+  -> encode frames with ffmpeg
+  -> mix/mux audio with ffmpeg
+  -> mp4
+```
+
+ContentFries cloud workers should eventually become hosted execution wrappers around this VisualFries renderer. They own queues, uploads, progress, retries, chunking, URL signing, auth-specific asset resolution, and deployment concerns, but the render semantics should live in VisualFries.
+
+## Preview Contract
+
+Preview means cheap and fast:
+
+- sampled QA frames,
+- low-resolution or short-range renders,
+- layout inspection,
+- rough browser media playback when explicitly requested.
+
+Preview is not a slower copy of final render. If a preview takes longer than final output, it is not a useful preview.
+
+## Current Migration State
+
+This package now exposes agent-safe render planning:
+
+```ts
+import { resolveAgentRenderPlan, requiresDeterministicRender } from 'visualfries/agent';
+
+const plan = resolveAgentRenderPlan(scene, { mode: 'final' });
+```
+
+The CLI blocks final `VIDEO`/`GIF` renders unless the caller explicitly chooses preview or the legacy escape hatch:
+
+```bash
+visualfries render scene.json --render-mode preview --output preview.mp4
+visualfries render scene.json --allow-browser-media-final --output unsafe-experiment.mp4
+```
+
+The package also includes the first local predecode core:
+
+```ts
+import { prepareLocalDeterministicMedia } from 'visualfries/agent';
+```
+
+`prepareLocalDeterministicMedia()` resolves `VIDEO`/`GIF` components, computes active frame windows, extracts exact image sequences with local `ffmpeg`, and returns a `visualfries-provider-predecoded` frame manifest. The CLI can inject that manifest into the render page as a deterministic media provider.
+
+The CLI also supports image-pipe final encoding:
+
+```bash
+visualfries render scene.json --stream-encode --image-format jpg --output out.mp4
+```
+
+With `--stream-encode`, rendered frames are written directly into local `ffmpeg` through `image2pipe` instead of first creating a temporary frame sequence. If audio is present, the CLI writes a silent video first and then muxes audio with `-c:v copy`.
+
+Audio mixing is local-first as well. The CLI now plans audio from active `VIDEO`/`AUDIO` components, `audioTracks`, and `settings.audio`, prepares each source to 48k stereo FLAC, applies timeline delay/volume, mixes with `amix`, trims to the rendered range, and muxes the mixed track into the final MP4.
+
+The same implementation is available as an importable local render boundary:
+
+```ts
+import { renderSceneLocally } from 'visualfries/agent';
+```
+
+Hosted workers should call this boundary instead of reimplementing frame extraction, browser composition, stream encoding, or audio mixing. The scene passed into this boundary must already contain public, local, or otherwise render-accessible media URLs. URL signing, signed URL refresh, and private asset authorization are wrapper responsibilities, not VisualFries responsibilities. VisualFries must not know how to authenticate ContentFries private assets; if media URLs are not render-accessible, it should fail with useful diagnostics. The package must stay light: `ffmpeg`, Playwright/Chromium, and hosted queue/upload infrastructure are runtime dependencies of the caller, not bundled VisualFries assets.
+
+The local renderer owns trim-aware final output. When `scene.settings.trimZones` intersects the requested contiguous frame window, VisualFries renders only the kept frame ranges and concatenates them through the stream encoder. Audio mixing uses the same kept scene-time ranges so video duration and audio duration stay aligned.
+
+The same boundary also supports exact single-frame output with `framesOnly: true` and explicit server renderer selection through `serverRendererMode: "canvas" | "webgl"`. Hosted wrappers should pass these options through instead of maintaining separate single-frame or renderer-mode semantics.
+
+Frame image quality accepts either browser form (`0..1`) or percent form (`0..100`) and is normalized before the browser render starts. This keeps wrappers from failing later with opaque frame extraction errors when they pass values such as `88`.
+
+The next migration slice is making the ContentFries worker call the VisualFries core instead of carrying its own duplicate render semantics.

package/docs/NEXT_RELEASE.md

@@ -0,0 +1,28 @@
+# Next Release Notes (Unreleased)
+
+Recommended semver: **0.2.0**. The schemas remain additive/loadable, but confirmed ignored behavior now evaluates and can change pixels. This deserves a pre-1.0 minor release rather than pretending it is a patch-only change.
+
+## Added
+
+- Typed component capability registry exposed through agent exports and `catalog --component <TYPE> --capabilities --json`.
+- Warning-by-default runtime-support diagnostics and `validate --strict-runtime-support` for agents/CI.
+- Runtime-backed `explain --component <id> --frame <n>` computed target state.
+- Shared deterministic Pixi animation target for IMAGE, VIDEO, GIF, regular/progress SHAPE, COLOR, and GRADIENT.
+- Real COLOR and GRADIENT canvas-to-Pixi render paths.
+- Native TEXT pixel padding, active word/line scale, and solid highlight palette cycling.
+
+## Behavior fixes / migration notes
+
+- Pixi animation x/y now mean placement-relative translation offsets, matching TEXT and existing swipe/drift helpers. Scenes authored against the short-lived absolute-center IMAGE bridge should subtract the component center from old x/y values.
+- `addAgentTransitions` now emits native SHAPE rectangles instead of background-only empty TEXT.
+- `visible: false` is preserved by component state and shared visual wrappers.
+- Active word wins when active word and active line are both enabled; runtime validation reports the conflict.
+- `clipColor` is diagnosed before permissive parsing can silently discard it. Strict runtime validation rejects it.
+
+## Still limited
+
+- Transform origin is fixed-center for Pixi visuals and not authorable across renderers.
+- Client HTML TEXT stacking versus final Pixi TEXT remains an architectural parity gap.
+- Native GIF timing and VIDEO/GIF loop/playback-rate parity are not guarantees yet.
+- Gradient highlight palettes, clipColor semantics, generic effects, and advanced setup/anchor behavior remain unsupported.
+- Radial gradient shape/position uses a centered max-radius fallback.

package/docs/PROPOSED_VISUALFRIES_SKILL.md

@@ -0,0 +1,68 @@
+# Proposed VisualFries Skill Update (Review Only)
+
+This is a repo-local proposal. It does not modify `/Users/lukasgregor/.agents/skills/visualfries/SKILL.md`.
+
+Apply these sections to the installed skill only after review/approval.
+
+## Replace the agent rule
+
+```text
+inspect inputs and actual runtime capability
+-> choose native semantic components
+-> author scene JSON
+-> validate + inspect structure
+-> frame-QA entry, settled, exit, and deterministic reseeks
+-> final deterministic render
+```
+
+## Add: Semantic component policy
+
+- Visible/editable typography defaults to native `TEXT`, including metrics, labels, badges, verdicts, cards, hooks, and CTAs.
+- Transcript-timed typography uses `SUBTITLES`.
+- A TEXT badge owns its background/gradient/radius/alignment/outline/shadow/animation when those treatments are runtime-supported.
+- Do not create a separate `SHAPE` merely as an ordinary text background. SHAPE is independent geometry, decoration, progress, mask-like layout, or transition content.
+- Transition covers use native animated `SHAPE`; do not use empty TEXT as geometry.
+- Use `IMAGE` for real image assets: photos, screenshots, logos, illustrations, or supplied raster/vector artwork.
+- Raster/SVG typography is an explicit fallback. Record which native limitation requires it and frame-QA it.
+- Production-plan overlays default to native TEXT. Use `renderAs: "SVG"` only for a documented compatibility fallback.
+
+## Add: Runtime truth
+
+- Validation is not rendering proof.
+- Confirmed visual targets: `TEXT`, `SUBTITLES`, `IMAGE`, `VIDEO`, `GIF`, `SHAPE`, `COLOR`, and `GRADIENT`. AUDIO is nonvisual.
+- Pixi animation `x`/`y` are placement-relative offsets. Pivot is fixed center. Supported properties: x, y, opacity, rotation (degrees), scale, scaleX, scaleY.
+- `clipColor` is unsupported and strict runtime validation rejects it.
+- `appearance.text.padding` supports pixels; absent element-target padding preserves the legacy `0.22em` fallback.
+- Active word/line scale and solid `highlightColors` cycling work. Active word wins when both word and line modes are enabled.
+- Gradient text should use wrapper-target background when a card background is also needed.
+- Browser HTML TEXT and final Pixi-rasterized TEXT can stack differently; verify risky cross-type compositions in final mode.
+
+## Replace QA guidance
+
+For every animated component:
+
+1. Render a pre-entry frame.
+2. Render first-active or mid-entry frame.
+3. Render settled frame.
+4. Render exit frame when applicable.
+5. Seek away and back to the same frame; compare state/pixels.
+
+Uniform three-frame QA is not enough for short or late events. Prefer exact production-plan `qa.framesAt` or explicit `--from-frame`/`--to-frame` windows.
+
+```bash
+visualfries doctor --json
+visualfries catalog --component TEXT --capabilities --json
+visualfries validate scene.json --strict-runtime-support
+visualfries inspect scene.json --json
+visualfries explain scene.json --component <id> --frame <n> --json
+visualfries parity scene.json --frames <csv> --output qa/parity --json
+visualfries render scene.json --frames-only --from-frame 5 --to-frame 20 --output qa/entry
+visualfries render scene.json --frames-only --from-frame 35 --to-frame 36 --output qa/settled
+visualfries render scene.json --stream-encode --output out.mp4
+```
+
+## Replace the current limitation section
+
+- Cookbook depth is not the only remaining gap.
+- Open engine gaps include authorable transform origin, browser/final TEXT stacking parity, clipColor semantics, gradient highlight palettes, generic effects, VIDEO/GIF playback parity, advanced animation anchors/setup, and calibrated preview/final parity metrics.
+- Link the installed skill to `docs/AUTHORING_BEST_PRACTICES.md` in the package/repository.

package/docs/examples/agent-cues.json

@@ -0,0 +1,49 @@
+{
+  "broll": [
+    {
+      "url": "./assets/profile-scroll.mp4",
+      "start": 0.2,
+      "end": 1.4,
+      "type": "VIDEO",
+      "fade": 0.18
+    },
+    {
+      "url": "./assets/chart.png",
+      "start": 1.4,
+      "end": 2.6,
+      "type": "IMAGE",
+      "motion": "slow-zoom-in"
+    }
+  ],
+  "overlays": [
+    {
+      "text": "LOVE THIS \ud83d\ude0d",
+      "start": 0.4,
+      "end": 1.1,
+      "style": "hook-punch"
+    },
+    {
+      "text": "NECK \ud83e\udd2f",
+      "start": 1.1,
+      "end": 1.7,
+      "style": "shock-word"
+    },
+    {
+      "text": "your move",
+      "start": 2.1,
+      "end": 2.7,
+      "style": "cta-card"
+    }
+  ],
+  "transitions": [
+    {
+      "time": 1.4,
+      "style": "dip-to-black"
+    },
+    {
+      "time": 2.3,
+      "style": "swipe-left",
+      "color": "#04483D"
+    }
+  ]
+}

package/docs/examples/agent-transcript.json

@@ -0,0 +1,23 @@
+{
+	"segments": [
+		{
+			"id": "s1",
+			"text": "Your content is free therapy for people who will never buy.",
+			"start": 0,
+			"end": 2.8,
+			"words": [
+				{ "text": "Your", "start": 0, "end": 0.2 },
+				{ "text": "content", "start": 0.2, "end": 0.55 },
+				{ "text": "is", "start": 0.55, "end": 0.7 },
+				{ "text": "free", "start": 0.7, "end": 1.05 },
+				{ "text": "therapy", "start": 1.05, "end": 1.5 },
+				{ "text": "for", "start": 1.5, "end": 1.68 },
+				{ "text": "people", "start": 1.68, "end": 2.0 },
+				{ "text": "who", "start": 2.0, "end": 2.15 },
+				{ "text": "will", "start": 2.15, "end": 2.32 },
+				{ "text": "never", "start": 2.32, "end": 2.55 },
+				{ "text": "buy.", "start": 2.55, "end": 2.8 }
+			]
+		}
+	]
+}

package/docs/examples/agent-transcript.srt

@@ -0,0 +1,7 @@
+1
+00:00:00,000 --> 00:00:01,200
+The best content asset is not always a post.
+
+2
+00:00:01,200 --> 00:00:02,800
+Sometimes it is the boring problem behind it.

package/docs/examples/agent-transcript.vtt

@@ -0,0 +1,7 @@
+WEBVTT
+
+00:00:00.000 --> 00:00:01.200
+The best content asset is not always a post.
+
+00:00:01.200 --> 00:00:02.800
+Sometimes it is the boring problem behind it.