visualfries 0.1.10115 → 0.3.2

package/README.md

@@ -36,6 +36,103 @@ This means development is driven by a singular vision and you have a direct line
 npm install visualfries
 ```
 
+## Agent CLI
+
+VisualFries includes a small agent-facing CLI for scene JSON workflows that do not require opening the ContentFries UI.
+
+```bash
+visualfries validate scene.json
+visualfries inspect scene.json --json
+visualfries qa scene.json --output ./qa
+visualfries doctor --json
+visualfries catalog --component TEXT --capabilities --json
+visualfries validate scene.json --strict-runtime-support
+visualfries explain scene.json --component views-badge --frame 12 --json
+visualfries parity scene.json --frames 5,12,35 --rois qa/parity-rois.json --output qa/parity --json
+visualfries validate-cues ./cues.json --duration 45 --json
+visualfries caption-scene \
+  --video ./input.mp4 \
+  --transcript ./transcript.srt \
+  --preset hidden-engine-center \
+  --output ./scene.json
+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
+visualfries render ./scene.json --output ./out.mp4
+```
+
+For static-heavy scenes, QA first and then use the faster duplicate-aware render:
+
+```bash
+visualfries render ./scene.json --output ./out.mp4 --skip-duplicates
+```
+
+`visualfries init` also creates a compose-ready package with `scene.json`, `cues.json`, `assets/`, `qa/`, and `notes.md`.
+
+For a one-command agent render:
+
+```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 \
+  --output ./out.mp4
+```
+
+The `caption-scene` command creates a render-ready VisualFries scene with a full-frame video layer, subtitle layer, asset registry, and subtitle timing data from transcript JSON, SRT, or VTT.
+
+The `render` command opens a controlled browser renderer, captures the scene frame-by-frame, and encodes MP4 with `ffmpeg`. Use `--frames-only` when an agent needs QA frames before encoding.
+
+For Node automations, use the agent-only export:
+
+```ts
+import { createCaptionScene, inspectScene, normalizeTranscript } from 'visualfries/agent';
+```
+
+Agent helpers also include timed text overlays:
+
+```ts
+import {
+	addAgentBrollSequence,
+	addAgentTextOverlays,
+	addAgentTransitions
+} from 'visualfries/agent';
+
+const sceneWithOverlays = addAgentTextOverlays({
+	scene,
+	overlays: [
+		{ text: 'LOVE THIS 😍', start: 0.4, end: 1.1, style: 'hook-punch' },
+		{ 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' }
+	]
+});
+
+const sceneWithTransitions = addAgentTransitions({
+	scene,
+	transitions: [
+		{ time: 2.0, style: 'dip-to-black' },
+		{ time: 5.0, style: 'swipe-left', color: '#04483D' }
+	]
+});
+```
+
+Start with [Authoring Best Practices](docs/AUTHORING_BEST_PRACTICES.md): native TEXT policy,
+component decision tree, animation runtime matrix, compositing truth, frame-QA, and known limits.
+Then see [Agent Workflow](docs/AGENT_WORKFLOW.md), [Agent Patterns](docs/AGENT_PATTERNS.md),
+and the [2026 authoring-system audit](docs/AUTHORING_SYSTEM_AUDIT.md).
+
+Visible typography defaults to native `TEXT`. Do not rasterize ordinary badges/metrics into
+`IMAGE`, and do not add a `SHAPE` solely as a text background when TEXT can own the treatment.
+
 ## Quick Start
 
 The best way to use VisualFries is within a Svelte component.
@@ -198,6 +295,31 @@ const builder = await createSceneBuilder(sceneData, container, {
 });
 ```
 
+## Server Renderer Mode (Canvas vs WebGL)
+
+Server mode remains canvas-first by default for backward compatibility:
+
+```typescript
+await createSceneBuilder(sceneData, container, {
+	environment: 'server'
+	// serverRendererMode defaults to "canvas"
+});
+```
+
+To opt into GPU rendering on server/headless runtimes:
+
+```typescript
+await createSceneBuilder(sceneData, container, {
+	environment: 'server',
+	serverRendererMode: 'webgl',
+	preferWebGL2: true,
+	powerPreference: 'high-performance'
+});
+```
+
+If WebGL is unavailable or initialization fails, Visualfries automatically falls back to canvas so deterministic render jobs keep running. When deterministic diagnostics are enabled, renderer selection and fallback reason are included in `getDiagnosticsReport()`.
+In `serverRendererMode: 'webgl'`, `fillBackgroundBlur` uses native `PIXI.BlurFilter` (same rendering path as client mode).
+
 ## Contributing
 
 As an early-stage, solo-developed project, contributions are highly encouraged! The best way to contribute right now is by: