v2.2.0 — Native templates and visual quality safeguards

v2.2.0 — Native templates and default visual quality safeguards

v2.2.0 turns the v2.1 topic DSL into an end-to-end visual system. Topic objects, relations, states, cue actions, covers, and QC evidence now flow through the selected template's native structure instead of falling back to a generic card renderer.

Install

pipx install creating-explainer-videos-skill==2.2.0
# or
npm install --global creating-explainer-videos-skill@2.2.0

Then update the installed Skill:

explainer-video-skill install --target codex --json
explainer-video-skill verify --target codex --json

What changed

• The compiler emits Paper Theatre, Spatial Chamber, or Ink Explainer native DOM fingerprints and native motion selectors.
• Spatial Chamber routes use visible, directional, boundary-to-boundary paths and animate every signal route.
• Semantic roles and explicit tones distinguish inputs, controllers, success, warning, failure, and metrics without requiring custom CSS.
• Covers reuse the completed topic scene and therefore carry the same subject objects and relationships as the film.
• Static validation rejects caption-area collisions, unreadably small text containers, missing cue actions, disconnected spatial mechanisms, and undrawn connectors.
• Mechanism IDs and narration mechanismRefs make it possible to verify that the spoken explanation covers the intended mechanism.
• Canonical narration, TTS input, and subtitles must match cue by cue; average cue duration must be at least 2.2 seconds.
• Media QC verifies template structure and topic cover provenance, extracts one representative frame per narration cue, and creates denser contact sheets.
• Final audio is normalized to approximately -16 LUFS during mux.

Forward-validation lesson

A technically decodable MP4 can still be visually generic, omit the selected template's motion language, route lines through text, or use a cover unrelated to the topic. This release converts those observed failure modes into compiler behavior, tests, and release-blocking checks so the intended production method is explicit and repeatable across different Agent environments.

Compatibility

The CLI and Skill name are unchanged. New and rebuilt schema-2 projects must satisfy the stricter mechanism, narration, timing, scene, and QC contracts. Existing published artifacts are untouched. Schema-1 projects retain the v2.0 generic fallback, which remains unsuitable as evidence of a completed topic-specific scene.

See MIGRATION_V2.md for the exact upgrade checklist.

Verification boundary

The release suite covers unit tests, examples, packed npm and wheel installation, real HyperFrames rendering, cover capture, FFmpeg mux, ffprobe inspection, template-structure audit, representative cue frames, and contact sheets. Human review is still required for factual accuracy, teaching clarity, pronunciation, synchronization, and publication approval.