visualfries 0.1.10120 → 0.3.2

package/docs/AGENT_WORKFLOW.md

@@ -0,0 +1,364 @@
+# VisualFries Agent Workflow
+
+This document defines the agent-facing contract for VisualFries.
+
+Read [Authoring Best Practices](AUTHORING_BEST_PRACTICES.md) before authoring. It defines the
+native semantic component policy, runtime support matrix, effect/compositing limits, and required
+entry/settled/exit/reseek frame QA. Validation and inspection are structural gates, not rendering
+proof.
+
+## Goal
+
+Make VisualFries usable by agents without requiring the ContentFries UI:
+
+1. create render-ready scene JSON,
+2. add captions from transcripts,
+3. validate and inspect scenes,
+4. render fast QA previews through the CLI browser adapter,
+5. hand final VIDEO/GIF scenes to the local deterministic renderer path.
+
+## CLI
+
+```bash
+visualfries validate <scene.json> [--json]
+visualfries inspect <scene.json> [--json] [--screenshots --output <dir>]
+visualfries init <dir> [--video <video> --transcript <file>]
+visualfries caption-scene --video <video> --transcript <file> --output <scene.json>
+visualfries preset-cues --duration <seconds> --output <cues.json>
+visualfries validate-cues <cues.json> [--duration <seconds>] [--json]
+visualfries apply-cues <scene.json> --cues <cues.json> --output <scene.json>
+visualfries qa <scene.json> --output <dir>
+visualfries compose --video <video> --transcript <file> --output <out.mp4>
+visualfries produce <production-plan.json> --output <out.mp4> --scene-output <scene.json> --qa-output <dir>
+visualfries render <scene.json> --output <out.mp4|frames-dir> [--frames-only]
+visualfries catalog [--json]
+visualfries doctor [--json]
+```
+
+Use `produce` for authored edits that need more than captions plus generic cues. A production plan groups the edit into named beats and supports source trims, automatic video freeze-frame holds, native TEXT editorial overlays, exact multi-track audio, transitions, and QA frames. Visible typography compiles to native TEXT by default. `renderAs: "SVG"` is an explicit compatibility fallback for a documented native limitation. The command emits ordinary VisualFries scene JSON, renders at timeline event boundaries, then checks the finished audio lead-in.
+
+```json
+{
+	"version": 1,
+	"id": "proof-hook",
+	"settings": { "width": 1080, "height": 1920, "duration": 6, "fps": 30 },
+	"beats": [
+		{
+			"id": "reaction",
+			"start": 0,
+			"end": 3,
+			"media": [
+				{ "id": "reaction", "url": "./reaction.mp4", "start": 0, "end": 3, "freezeAt": 1.8 }
+			],
+			"overlays": [{ "text": "NOT DEAD.", "start": 1.8, "end": 3, "style": "verdict-slam" }]
+		}
+	],
+	"audio": [{ "id": "voice", "url": "./voice.wav", "startAt": 0, "volume": 1 }],
+	"transitions": [{ "time": 3, "style": "focus-pull" }],
+	"qa": { "framesAt": [0.1, 1.9, 3.1], "maxLeadingSilence": 0.1, "requiredText": ["NOT DEAD."] }
+}
+```
+
+```bash
+visualfries produce ./production-plan.json \
+  --scene-output ./scene.json \
+  --qa-output ./qa \
+  --output ./final.mp4
+```
+
+`render` uses a controlled Vite browser page, Playwright, and `ffmpeg` for static scenes and fast previews. It never requires opening ContentFries UI.
+
+Important render contract:
+
+- `--render-mode final` is the default.
+- Final scenes with `VIDEO` or `GIF` components require the local deterministic renderer. Native browser media seek is not trusted for final output because it can create stale, duplicated, or shifted frames.
+- Use `--render-mode preview` for quick QA frames or rough local checks.
+- `--allow-browser-media-final` exists only as an escape hatch for experiments. Do not use it for shipped output.
+- In final mode, the CLI predecodes active `VIDEO`/`GIF` ranges to exact frame images and injects a deterministic media provider into the render page.
+
+Useful render options:
+
+- `--frames-only` renders a PNG frame sequence for QA instead of MP4.
+- `--render-mode preview` permits the browser preview path for VIDEO/GIF scenes.
+- `--engine browser-preview` or `--engine deterministic-local` can force renderer planning when debugging.
+- `--from-frame <n>` and `--to-frame <n>` render a partial range for fast checks.
+- Full contiguous renders use the browser-side `renderFrameRange()` path, avoiding one Playwright round trip per frame.
+- `--stream-encode` pipes rendered frames directly into local `ffmpeg` with `image2pipe`. Prefer it for final contiguous MP4 renders once QA frames look right.
+- `--skip-duplicates` asks VisualFries deterministic dirty checking to reuse unchanged frames when possible.
+- `--fps <number>` overrides scene FPS.
+- `--audio <path|none>` overrides automatic audio mapping from the local scene audio mix.
+- Without `--audio`, final contiguous renders build a local mixed audio track from active VIDEO/AUDIO components, `audioTracks`, and `settings.audio`.
+- `VISUALFRIES_NODE_MODULES=/path/to/node_modules` lets agents point the CLI at an existing Playwright install.
+- `doctor --json` checks ffmpeg, Vite, Svelte Vite plugin, Playwright, Chromium, and temp directory resolution before an agent starts a render.
+- `catalog --json` lists supported caption presets, cue presets, overlay styles, b-roll motions, transitions, transcript formats, and CLI commands.
+- `validate-cues --json` checks cue file shape, known styles/motions/transitions, and timing before an agent applies cues.
+- `qa` writes `inspect.json`, `screenshots.json`, and sampled `frames/` into one QA directory.
+
+Use `init` to create a self-contained agent working directory:
+
+```bash
+visualfries init ./video-package \
+  --video ./input.mp4 \
+  --transcript ./transcript.srt \
+  --preset hidden-engine-center \
+  --cue-preset hidden-engine-dynamic
+```
+
+It creates `scene.json`, `cues.json`, `assets/`, `qa/frames/`, `qa/inspect.json`, `notes.md`, and transcript examples. `cues.json` is generated from the selected cue preset and can be edited before compose/render.
+
+Use `compose` when an agent should prepare the scene and, for now, produce a preview MP4 in one command:
+
+```bash
+visualfries compose \
+  --video ./input.mp4 \
+  --transcript ./transcript.srt \
+  --cue-preset hidden-engine-dynamic \
+  --cues ./cues.json \
+  --scene-output ./scene.json \
+  --qa-output ./qa/frames \
+  --render-mode preview \
+  --output ./out.mp4
+```
+
+`compose` runs the same underlying pipeline as the step-by-step workflow:
+
+```text
+caption-scene -> optional cue preset -> optional cue file -> inspect -> optional QA screenshots -> render
+```
+
+Use `apply-cues` when an agent has already planned the visual timeline:
+
+```bash
+visualfries preset-cues --duration 45 \
+  --preset hidden-engine-dynamic \
+  --output ./cues.json
+
+visualfries apply-cues ./scene.json \
+  --cues ./cues.json \
+  --output ./scene.with-cues.json
+```
+
+Cue files can contain `broll`, `overlays`, and `transitions` arrays:
+
+```json
+{
+	"broll": [
+		{ "url": "./assets/profile.mp4", "start": 2, "end": 5, "type": "VIDEO" },
+		{ "url": "./assets/chart.png", "start": 5, "end": 7, "type": "IMAGE", "motion": "slow-zoom-in" }
+	],
+	"overlays": [
+		{ "text": "LOVE THIS 😍", "start": 0.4, "end": 1.1, "style": "hook-punch" },
+		{ "text": "NECK 🤯", "start": 1.1, "end": 1.7, "style": "shock-word" }
+	],
+	"transitions": [
+		{ "time": 2, "style": "dip-to-black" },
+		{ "time": 5, "style": "swipe-left", "color": "#04483D" }
+	]
+}
+```
+
+Relative b-roll URLs are resolved relative to the cue file path, so an agent package can keep cues and assets together.
+
+`preset-cues` creates a valid starter cue file. It is not meant to replace creative judgment; agents should replace placeholder overlay text and add b-roll paths before the final render.
+
+## Node API
+
+Use the agent-only subpath for automations and CLIs:
+
+```ts
+import { createCaptionScene, inspectScene, normalizeTranscript } from 'visualfries/agent';
+```
+
+The root `visualfries` export includes the full library surface. Agents should use `visualfries/agent` for captioning and inspection because it avoids browser/Svelte runtime imports.
+
+Renderer planning is also agent-safe:
+
+```ts
+import { resolveAgentRenderPlan, requiresDeterministicRender } from 'visualfries/agent';
+
+const plan = resolveAgentRenderPlan(scene, { mode: 'final' });
+
+if (requiresDeterministicRender(scene)) {
+	// Final output needs local deterministic media predecode, not browser video seek.
+}
+```
+
+For short-form overlays:
+
+```ts
+import {
+	addAgentBrollSequence,
+	addAgentTextOverlays,
+	addAgentTransitions
+} from 'visualfries/agent';
+
+const sceneWithOverlays = addAgentTextOverlays({
+	scene,
+	overlays: [
+		{ text: 'LOVE THIS 😍', start: 0.4, end: 1.1, style: 'pop-label' },
+		{ text: 'NECK 🤯', start: 1.1, end: 1.7, style: 'shock-word' }
+	]
+});
+
+const sceneWithBroll = addAgentBrollSequence({
+	scene,
+	cues: [
+		{ url: './broll/profile.mp4', start: 2.0, end: 5.0, type: 'VIDEO' },
+		{ url: './broll/chart.png', start: 5.0, end: 7.0, type: 'IMAGE', motion: 'slow-zoom-in' }
+	]
+});
+
+const sceneWithTransitions = addAgentTransitions({
+	scene,
+	transitions: [
+		{ time: 2.0, style: 'dip-to-black' },
+		{ time: 5.0, style: 'swipe-left', color: '#04483D' }
+	]
+});
+```
+
+### `caption-scene`
+
+Creates a vertical 9:16 scene with:
+
+- full-frame video component,
+- subtitle component,
+- scene asset registry,
+- `settings.subtitles.data` populated from transcript JSON.
+
+Example:
+
+```bash
+visualfries caption-scene \
+  --video ./input.mp4 \
+  --transcript ./transcript.json \
+  --preset hidden-engine-center \
+  --output ./scene.json
+```
+
+Accepted transcript shapes:
+
+Plain subtitle files:
+
+```bash
+visualfries caption-scene \
+  --video ./input.mp4 \
+  --transcript ./captions.srt \
+  --preset hidden-engine-center \
+  --output ./scene.json
+```
+
+Supported subtitle file formats:
+
+- `.srt`
+- `.vtt`
+
+Structured JSON:
+
+```json
+{
+	"segments": [
+		{
+			"text": "The best content asset is not always a post.",
+			"start": 0,
+			"end": 2.4,
+			"words": [{ "text": "The", "start": 0, "end": 0.12 }]
+		}
+	]
+}
+```
+
+```json
+{
+	"words": [
+		{ "text": "The", "start": 0, "end": 0.12 },
+		{ "text": "best", "start": 0.12, "end": 0.35 }
+	]
+}
+```
+
+## Presets
+
+Initial caption presets:
+
+- `reels-center`
+- `reels-lower`
+- `podcast-clean`
+- `hidden-engine-center`
+
+Initial agent overlay styles:
+
+- `pop-label` for quick reaction labels above/below captions.
+- `shock-word` for large emphatic keyword reveals.
+- `soft-card` for calmer proof/context callouts.
+- `hook-punch` for the first loud hook label.
+- `proof-pill` for compact proof/credibility beats.
+- `metric-badge` for big numbers and business proof.
+- `danger-crossout` for wrong-path / negative beats.
+- `cta-card` for final choice/question cards.
+
+Initial agent b-roll helper:
+
+- `addAgentBrollSequence` for timed portrait video/image/GIF cues below captions and overlays.
+- Image cues default to subtle `slow-zoom-in`; use `motion: 'none' | 'slow-zoom-in' | 'slow-zoom-out' | 'drift-up'`.
+
+Initial agent transition helper:
+
+- `addAgentTransitions` for fast full-frame transition covers at exact beat times.
+- Transition helper covers use animated native SHAPE rectangles.
+- Supported styles: `dip-to-black`, `flash`, `swipe-left`, `swipe-up`.
+
+Overlay rules:
+
+- Keep the center caption lane free unless the overlay replaces captions for that moment.
+- Use one overlay idea per beat. Split “LOVE THIS” and “NECK” into separate timed cues.
+- Prefer 0.4-1.4 second overlay durations. Longer overlays start feeling like static slides.
+- Render 1-3 QA frames before MP4 encode when a new overlay style is used.
+
+See [AGENT_PATTERNS.md](AGENT_PATTERNS.md) for repeatable caption, overlay, b-roll, and QA patterns.
+
+## Quality Gates
+
+Before a scene is accepted:
+
+```bash
+visualfries validate scene.json
+visualfries inspect scene.json --json
+visualfries inspect scene.json --screenshots --samples 3 --output ./qa/frames --json
+```
+
+`inspect` checks schema validity, timeline bounds, missing assets, and subtitle data anchors. With `--screenshots`, it also renders sampled QA frames and returns their paths in the JSON report.
+
+Before publishing a rendered video:
+
+```bash
+visualfries inspect scene.json --screenshots --samples 3 --output ./qa-frames --json
+visualfries render scene.json --output ./out.mp4
+ffprobe -v error -show_entries stream=codec_type,width,height -of json ./out.mp4
+```
+
+For static-heavy scenes, proof screenshots, and overlay sections, the faster render path is:
+
+```bash
+visualfries render scene.json --output ./out.mp4 --skip-duplicates
+```
+
+Do not use `--skip-duplicates` blindly on complex video-heavy scenes until QA frames look correct.
+
+## Complete Agent Production Path
+
+VisualFries uses these layers for complete agent-driven production:
+
+1. CLI scene creation and validation. Done.
+2. Caption scene generator. Done.
+3. Renderer adapter: `visualfries render scene.json --output out.mp4`. Done for local browser + ffmpeg rendering.
+4. Agent text overlay cues. Done for initial pop/shock/card styles.
+5. Screenshot inspect: `visualfries inspect scene.json --screenshots`. Done.
+6. Agent project scaffold: `visualfries init <dir>`. Done.
+7. Pattern registry for transitions and b-roll layouts. Initial b-roll sequence helper, image motion, transition helper, and cookbook done.
+8. Cue-file CLI application for b-roll/overlays/transitions. Done.
+9. Starter cue presets: `visualfries preset-cues`. Done for `hidden-engine-dynamic` and `captioned-clean`.
+10. One-command agent compose workflow: `visualfries compose`. Done.
+11. Skill/cookbook examples for common agent jobs.
+
+The current implementation supports caption-scene creation, validation, inspection, QA frame rendering, MP4 rendering, b-roll cues, text overlays, simple transition cues, cue-file application from the CLI, starter cue presets, and one-command compose.

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. |