Changelog.

Fixed

• Stable cold-demo media acquisition. Clean Linux activation now uses retained, digest-verified FFmpeg 6.1.1 release assets after the former rolling snapshot disappeared upstream.

Changed

• Xiaomi companion name. The separately installed Xiaomi speech companion is now narova-xiaomi. Its provider remains mimo, so existing project selections and registrations continue to work.
• Shared timing facts. Narration timing and effect anchors now share one internal boundary while preserving external-caption compatibility, mix output profiles, scene placement, and render reuse.
• Faster guarded publication. Tagged releases execute tool and package checks once while retaining the same full verification and direct-publication protection.

Added

• Creator-owned generated-shot continuity. A small optional project-config block names characters, objects, places, or other entities and lets the creator or agent explicitly select one shot's keep/change intent. One contained image anchor can be supplied when the selected provider declares support; unsupported anchors fail before paid work. Recipe version 3 preserves exact context and anchor identity for inspection and regeneration. Narova does not infer the world, choose style or camera, rank candidates, retry generation, reuse sceneState, or claim that the provider honored the reference in its pixels.

Fixed

• Explicit continuity removal. A malformed version-3 recipe missing its continuity snapshot now fails before generation and points to --no-continuity, instead of silently becoming continuity-free.

Changed

• Locality-first choreography guidance. One-scene authored JavaScript now starts with scene.choreographyFile, keeping unchanged sibling scenes eligible for render reuse. Top-level choreography remains the unrestricted form for deliberate cross-scene work and retains conservative whole-video reuse. The author or directing agent chooses the truthful scope; no runtime, schema, analyzer, rewrite, style rule, quality gate, or creative restriction was added.

Changed

• Trustworthy delivery execution reuse. Multi-preset and repeated delivery performs each proven source render, encode, and thumbnail operation once while preserving every requested deterministic member. Exact execution identity plus recorded size, SHA-256, and duration protect cross-build reuse; uncertain or changed evidence rebuilds safely. Source, encode, and thumbnail work remain separately attributed, and equivalent named outputs are independent files with byte-identical content.
• Existing render cache in delivery. The common HyperFrames source now uses Narova's dependency-aware scene or whole-video cache path. Project-global choreography remains conservative, expressive work may still force a rebuild, and no style, provider, renderer capability, output contract, creative gate, or authoring restriction is added.

Added

• Independent brand and design context. Agent intake recognizes project-local BRAND.md and DESIGN.md independently, keeps durable identity separate from an applied surface system, and records relevant video-specific adaptations with exact citations. Either file, both, or neither remain valid. Context and links stay untrusted; no counterpart generation, automatic merge, token projection, external linter, rendered-conformance claim, hidden style, runtime change, or release gate is added.

Added

• Bounded local PDF evidence. narova ingest <local.pdf> --pages <1,3-5> renders only explicitly selected physical pages, preserves available embedded text, and records page-level identity and provenance. It performs no OCR, model work, interpretation, creative selection, link following, or document actions.
• Resolved sentence and word cues. Browser-authored choreography can use index-addressed sentenceCue and wordCue spans over normalized resolved timing in full or isolated coordinates, without text search, semantic selection, or copied timestamps.
• Exact authored-code feedback. Check and HyperFrames composition compile authored JavaScript in its real emitted context without executing it, attribute syntax and synchronous initialization failures, and preserve every valid creative escape hatch without adding a style, selector, or complexity gate.

Fixed

• External-browser cue compatibility. Indexed helpers use a separate normalized timing view while existing numeric cues and the accepted raw standard-caption projection retain their prior behavior. Cache identity and project migration remain unchanged.

Added

• Joined audio mix and delivery proof views. narova review --audio-levels can return ordered digest-bound labeled windows, join authored bed/SFX declarations and resolved global windows to measured total-mix facts, or directly measure a selected audio member from a delivered container. Missing and ambiguous evidence stays explicit; the views remain advisory, read-only, target-free, scoreless, non-prescriptive, and non-gating.

Fixed

• External-narration scene anchors. Scene-anchored SFX now resolve to the scene's global start plus the authored offset in the external-narration mixer, matching the validated authoring contract and the primary mixer.

Added

• Artifact-bound audio level facts. narova review --audio-levels reports declared-basis loudness, peak, and clipping facts for an exact existing artifact or selected interval, without a target, score, gate, recommendation, or mutation.
• Bounded authored-3D operations and proof. The optional 3D-production companion can assess and inspect existing Blender scenes, report exact loaded-shot and decoded-pixel/projection facts, render caller-selected sparse proofs or final frames, and hand an explicitly timed PNG sequence back to Narova for composition. Receipts bind exact inputs and outputs; no creative values are selected or judged.
• Xiaomi MiMo speech companion. The separately installed narova-mimo skill adds explicit preset, natural-language voice-design, and reference-audio cloning modes through one bounded provider worker. It registers only on request, submits billed operations once, validates audio before publication, and keeps credentials out of observable output.

Fixed

• Complete media release gates. CI and npm publication provision and verify FFmpeg and FFprobe before the full conformance suite. Audio measurement uses explicit bounded worker counts, decoder-corruption plus timestamp-offset fixtures create their conditions explicitly, and the authored-3D suite clean-installs its pinned deterministic-physics dependency.
• Rendering and evidence fidelity. Default subtitle plates remain readable, exact measured Judge probe results are no longer blurred by unavailable semantic correspondence, and root direct clips render at full opacity across both local renderers.

Added

• Task-local physical reasoning for authored 3D. The optional 3D-production companion adds progressive support, contact, constraint, and motion-risk reasoning plus a pinned deterministic rigid-body baker whose canonical time-indexed transforms can be sampled in any frame order.
• The Precious Thing in Explore. The owner-approved 31-second authored-3D fable leads the gallery with byte-pinned video, poster, captions, portable project, sources, narration, timings, and rights evidence.

Added

• Artifact-bound scene-state evidence. Projects can attach one bounded, task-specific state file to a scene and compare its named numeric, boolean, or string facts through creator-owned assertions. Builds bind the exact source identity to the video receipt; judgement preserves method, time, unit, availability, and measured or inferred basis. Missing evidence remains uncertain, while rendering, cache, revisions, proofs, validity, release, repair, creative scoring, and selection remain unchanged.

Added

• Per-scene clip-audio authority. A scene can explicitly preserve synchronized native clip audio or retain synthesized narration authority, with transcript-matched timings and no speech looping.
• Narrated duration floors and authored captions. scene.minDur pads a preserved performance with trailing silence, while caption plate and size controls remain consistent across both local renderers.

Added

• Google provider companion. A separately selectable narova-google skill registers independent Gemini speech and Veo video workers. Standard-library adapters isolate credentials, perform no automatic billed retry, and leave core Narova local-first.

Added

• Claims and check precision. Claims tables are read by their named claim column, empty ledgers are reported, bullets remain collectable after tables, and written-number quantities match their digit forms.
• Verified local voice acquisition and scoped help. Piper downloads verify their complete model pair with bounded retry, and nested asset, walkthrough, and branch actions show their own help.

Fixed

• Honest readiness and restyling. Doctor guidance names the actual provisioning surface, documented chrome classes no longer warn as reserved, and familiar license identifiers receive advisory vocabulary checks.

Added

• External video-provider protocol. Registered provider-v1 workers handle vendor submission, polling, and download while core retains validation, staging, provenance, asset registration, and rollback. Separate Runway and OpenAI/Sora companions implement the boundary.

Fixed

• Provider boundary hardening. Private same-filesystem stages, bounded worker I/O, media validation, incremental hashing, complete secret scanning, v2 provenance, and selective no-browser frame extraction fail closed without changing v1 recipe readability.

Added

• Skill content identity. Every first-party skill declares Apache-2.0 and a checksum over canonical content; release verification rejects missing or stale identities.

Added

• Instant trustworthy revisions. Dependency-aware scene reuse isolates local visual identity from placement, tracks scene-scoped assets, reports exactly what rebuilt or reused and why, and preserves decoded audiovisual equivalence with a forced-clean build.

Added

• Video CI rendered-evidence judgement. narova judge compares creator-owned assertions with encoded evidence without a universal quality score, while planning, focused proof comparison, and bounded caption repair remain unranked and branch-isolated.

Fixed

• Complete large machine envelopes. Machine JSON output writes every byte even beyond a single pipe write.

Fixed

• Reliable detached previews. HyperFrames' post-bind readiness now supplies the actual port, while one identity-bound start/stop transaction preserves explicit-port exactness, automatic fallback, and recoverable state when shutdown cannot be confirmed.
• Agent protocol hardening. Short and overlapping known credentials are fully redacted, and malformed provider names consistently return usage status 2.
• Release-surface conformance. Gallery archive basenames are safe for the projected remix command, and the colored-TTY regression is hermetic without changing NO_COLOR behavior.

Added

• Versioned agent machine protocol. Every public operation honors an explicit machine-output request and emits exactly one versioned result envelope (narova.result/1) to standard output: operation, success, data, diagnostics, and committed artifacts. A closed exit-status vocabulary separates usage errors, operation failures, and subject non-passes from success; diagnostics carry fixed severities and stable dot-namespaced codes from a public registry; envelope evolution is additive within a major version. The shipped AGENT_PROTOCOL.md documents the inspect → modify → validate → preview → critique → build → verify loop for machine consumers.
• Shareable project archives. narova pack produces a deterministic byte-identical .narova archive (ZIP + narova.archive.json manifest) containing verified authoring closure. narova open verifies and safely materializes an archive — digest-checked, path-confined, non-executing, with a trust notice — and narova inspect validates without writing. narova remix materializes a local archive, directory, or bounded github: locator into a fresh project with its own identity, a recorded (not verified) provenance parent, and no inherited history.
• Explore gallery. The website gains a static /explore/ route of curated project entries offering watch (rendered video with captions and poster), inspect (publication-time static projection of the archive), and remix (copyable narova remix command and archive download). No project content is executed in the browser; entries are admission-reviewed and checked in.

Changed

• Public surface cleanup. The monolithic SPEC.md and checked-in agent-convention aliases are removed; the canonical core skill lives at one repository location and discoverability uses the documented skill-install mechanism.
• Relicensed to Apache-2.0. Narova's code and first-party companions move from MIT to the Apache License 2.0 with a NOTICE; previous releases remain MIT and third-party assets keep their own licenses.

Changed

• Living center visuals for the demo. The built-in demo project's scenes now animate a centered play-mark medallion (scene 1) and staggered popping dots (scene 2) over a subtle gradient, using only cross-renderer motion primitives so the browser and browserless profiles render identical geometry.

Added

• One-command activation: narova demo. A readiness checklist with live progress reconciles the machine first: find-what-exists, then digest-verified provisioning into ~/.narova — a pinned piper voice on every platform and a pinned static ffmpeg on Linux (macOS and Windows fail closed to explicit install guidance). The demo then runs the ordinary build pipeline — real synthesis, measured timing, render, encode — finishing with a playable MP4, SRT/VTT captions, and the readable demo project left behind, reporting measured time-to-first-video and network bytes. Warm reruns reuse everything. A bare interactive narova runs the welcome flow, and narova-uninstall --purge-tools removes provisioned tooling on request. New clean-machine CI job proves the Linux path end to end.

Added

• Evidence-graded project provenance. narova provenance composes existing claims, media, AI-generation, and reproducibility evidence into prose or JSON. Every fact remains visibly verified, declared, or unknown; missing and tampered evidence stays explicit, rights buckets remain display-only, and exact used-asset closure is never implied.
• Portable credits and toolchain evidence. narova assets credits --format text|youtube|web|json renders one stable attribution set for each destination. Manifests now record locally available renderer and speech-backend versions without executing providers or using the network, and optional authored provenance declarations remain advisory.

Added

• Revision impact and history. Every successful base build now records a revision to the append-only out/revisions.jsonl when — and only when — the effective resolved project state changed; an unchanged rebuild records nothing and says so. Each record carries the audio/timing fingerprints, per-scene identity digests, measured stage durations, and a measured reuse report: per-scene audio byte-identity by content digest, render-span reuse vs identity re-render vs fallback, sentence-cache hit/fresh counts, and shared artifacts rebuilt by design. Ratios state their basis and unit; missing evidence is "not applicable", never invented; fallback re-renders never count as reuse.
• narova diff and narova history. diff predicts the revision impact of your current edits per scene (script / visual / timing / structural; narration-only edits keep other scenes' audio and visuals), with a predicted reuse summary that states its basis and unit, and an estimated render time scaled from previously measured stage durations — omitted, with a plain statement, before any measurement exists. history lists recorded revisions with one-line change summaries and measured reuse, annotates a free-text label (metadata only), and compares two revisions a..b producing the same report from the records alone. Verified end to end on a real narrated build: editing one spoken turn left every other scene's audio byte-identical (digest-verified) while prediction matched measurement exactly.

Added

• Creative-identity contract. narova check gains advisory-only surfaces that counter unattended-mode visual convergence — agents reaching near-identical looks across unrelated briefs. A project with an authored creative.md rationale gets citation resolvability (unresolvable cites warn), a deterministic multi-dimensional identity fingerprint computed from the config alone, an isolation-safe self-check that verifies the written claims against the measured identity and flags contradicted or under-authored identity (works with zero sibling history, i.e. sandboxed runs), and a sibling advisory against a local fingerprint-only ledger. narova check --creative-identity emits out/creative-identity.json. None of these surfaces can fail any check level. Validated by a preregistered controlled comparison: palette diversity ratios 4.24×/2.18×, two fixation events fired, owner blind review confirmed improvement.

Added

• ElevenLabs voice design. The optional companion ships an explicitly invoked helper (tool/design.py) that turns a text voice description into preview audio plus an audition index — a human picks, a separate step creates the permanent voice, and the resulting voice ID drops into the ordinary reel.config.mjs voice block. Seed makes the request reproducible; remix derives a new voice from an existing one. Companion skill 1.1.0; no core or provider-protocol change.

Fixed

• Fresh-directory release builds pass. Captions (or their recorded intentional omission) publish before the post-synth release gate in build --release, so a first-ever release build satisfies the caption presence rule like every later one — no undocumented plain-build-first workaround. Gate conditions and plain-build behavior are unchanged.

Added

• Claim coverage reporting. Every check level prints claims: N of M vo turns look factual (heuristic) — informational, never a warning. A gate that sees little is a visible number instead of silence.

Changed

• Spoken-style figures are claims. The grounding heuristic classifies number-word quantities ("eighty percent", "eight percentage points", "three times") and ratios ("fifteen of fifteen") — the natural authoring style for local TTS, previously invisible to the digits-only gate.
• Human claims ledgers match. Bullets count anywhere in claims.md, and detected claims match ledger quantity content across digit↔number-word spelling ("94%" ↔ "ninety-four percent"). Digit-boundary anchored: "8%" never lands inside "48%".
• Honest narration estimates. The estimate accounts for per-sentence gaps exactly as assembly does; the tempo-correlated under-report is structurally removed (measured: −17.0% at tempo 1.0 vs −17.1% at 1.3, uniform calibration).
• Local-first default fonts. Generic-only default --sans/--mono: naming no font means zero network font resolution. Token overrides now genuinely replace the chain.

Fixed

• branch save diagnostic names narova shots --motion --proof, the only command that writes the required receipt.

Verified

• Spelled-narration release builds refuse without a ledger and pass with a topic-organized digit-only one (stock 0.31.6 passed silently); default projects build complete videos with zero font-fetch lines.

Added

• Optional compressed companion. narova build --companion [size] writes a compressed copy beside the untouched primary — an agent-owned iteration lever for quick review cuts while the final stays full quality. Deterministic derived encoding, quick-review defaults without an aim, and an honest aim/achieved/bitrate line. Nothing is enforced; no preset commits to a size.

Verified

• The seven-minute production that motivated the change produced a 58.1MB companion from a 60MB aim with a single flag, replacing a hand-rolled two-pass ffmpeg escape.

Added

• Agent observability surfaces. Multi-clip render failures name the stage, the candidate clips, and retries; cache downgrades are announced at check time instead of degrading silently.
• Advisory review evidence. narova review gains --coverage (clip reuse), --contact-sheet (labeled stills), --excerpt (word-timed pronunciation cuts), --silences (pause report), and --takes (sentence/identity index). Advisory only — nothing gates a build.
• Deterministic narration takes. Unchanged sentences reproduce their takes through identity-derived seeds, verified byte-identical for every bundled backend. Authored variation stays first-class: vary, per-sentence take nonces, and a project off-switch.
• Capability disclosure. narova providers list shows which pronunciation and delivery mechanisms each backend honors; check warns before markup is silently ignored.

Changed

• No silent empty captions. A build with narration audio never publishes an empty caption sidecar; release check fails one without a recorded reason.

Verified

• Review surfaces run against a real seven-minute production: the silence report found the exact owner-reported pause plus ten more; the take index exposed the voice split behind perceived narrator drift; double-generation under pinned seeds reproduced qwen and chatterbox takes byte-identically.

Added

• Optional 3D-production companion. Install a focused direction layer for authored 3D subject and world representation, capability routing, scene direction, and honest inspection without adding another renderer or core dependency.

Changed

• 3D guidance leaves the core skill. Core Narova keeps its complete 3D surface while specialist production judgment moves into the independently installed companion.
• Proof before scale. Risky 3D work establishes an intentional visual target and, when needed, a short movement premise before full production.

Verified

• An owner-reviewed 94-second procedural film passed release, encoded-motion, and black-frame checks; the evidence is intentionally bounded to that model and run.

Changed

• Clear product category. npm, GitHub, the READMEs, and the website now consistently describe Narova as a local-first prompt-to-video CLI and agent skill.
• Search and sharing foundations. The website adds canonical URLs, complete social cards, structured data, a crawlable favicon, and a sitemap.

Verified

• Automated checks protect package keywords, canonical metadata, structured data, and sitemap integrity.

Changed

• Lockstep compatibility. The skill checks narova --version, reuses only its exact compatible release, and installs the pinned npm package when the CLI is missing, older, or newer.
• One compatibility pin. Expected runtime version is derived from the skill's single exact npm spec.

Verified

• Tests cover exact reuse, stale upgrades, PATH conflicts, npm failures, and unresolved post-install mismatches.

Changed

• npm-only lifecycle. The superseded GitHub installer and unscoped migration path are gone; install, update, and removal target @narova/narova.
• Reliable version sync. Release automation updates both skill metadata and its exact npm bootstrap pin.

Security

• Publishing uses npm Trusted Publishing without a token fallback and rejects tags whose commit is not on main.
• Node 18 and Node 24 run the same package, install, and release gates.

Added

• Public npm bootstrap. The standalone CLI became available as public @narova/narova. This initial release was published manually and has no provenance attestation.
• Packed-artifact gate. CI installs the exact tarball into a fresh prefix, exercises all commands, scaffolds a project, and requires a clean check.

Changed

• Verifiable bootstrap. The skill pins its matching npm release instead of executing a mutable remote shell installer.
• Lean artifact. Runtime code and docs ship; legacy installation and development files do not.

Added

• Verified creative-asset lifecycle. Import, download, search, acquisition, verification, provenance, rights, and credits now share one provider-neutral registry.
• Core stock adapters. Twelve deterministic adapters share one CLI: nine need no key, while Pexels, Pixabay, and Freesound remain independently optional.
• LLM sourcing companion. The separate skill installs no CLI and guides flexible discovery across 101 photo, video, audio, font, 2D/3D, culture, map, and science sources.

Changed

• Honest readiness. All repeatable adapters live in core; changing web sources remain LLM-led, and absent optional keys never block the rest.
• Clear ownership. Code handles mechanical provider work while the agent keeps creative queries, selection, and item-level license judgment.

Verified

• Real API search/download/registry tests passed for every no-key adapter, and a live agent-browser Mixkit flow preserved a Restricted License through download, import, verification, and credits.

Added

• CLI installer and uninstaller. tool/install.sh installs narova, narova-setup, and narova-uninstall from a selected GitHub ref. Run it again to update. Uninstall keeps projects, models, caches, and skills.
• Install lifecycle tests. Tests cover installation, update, repeated uninstall, package contents, and skill-to-CLI use from temporary directories.

Changed

• Repository layout. CLI code now lives in tool/; skills/narova/ contains only instructions and references.
• Skill setup. The skill finds narova on PATH or installs it when needed.
• Development commands. Tests, packaging, versioning, docs, and companion providers now use tool/.

Added

• Proof branches by default. branch save --rationale snapshots a small candidate with a durable, project-bound, byte-verified proof bundle; ambitious release requires 2–3 content-distinct proofs, exact expansion lineage, and only one approved winner. Concurrent same-name publication is compare-and-swap safe, and restores retain proof-time CLI overrides.
• Pilot visibility gate. shots --motion --proof fails when sampled evidence is predominantly near-black or absent.
• Real creativity A/B. Eight same-model pilots compare with/without Narova guidance; the documented result is honest about conceptual convergence.

Changed

• Genuinely raw canvas. Both bundled renderers no longer reserve or constrain the zero-style frame; safeLayout restores guardrails explicitly, and restored pre-0.28 projects retain historical geometry.
• Medium-neutral intent. The creative brief leads with intended effect, representation, temporal behavior, evidence, and rejection criteria. Camera/depth/light are conditional.

Added

• Creative confidence loop. New projects scaffold competing directions, a visual contract, beat map, three-shot pilot gate, and rejection criteria in creative-brief.md.
• Beat-level visual review. narova shots --beats samples the arrival and resolved state of narration groups, both sides of markers, and useful coverage for silent scenes.

Changed

• Fail-before-render release gate. build --release preflights before synthesis, then rechecks measured timing before compose/render, and requires an approved brief for non-trivial productions.
• Camera-aware cinematic critique. Persistent raw Three.js worlds are assessed by their internal directed camera cuts and moves, not just their top-level scene count.

Fixed

• Duration provenance. Creative gating distinguishes fallback and authored runtime, then trusts measurements only with a scene-topology-aware timing fingerprint.
• Complete variant preflight. Base and selected/all variants are checked before any release write begins.
• Raw 3D shot accounting. Helper, direct timeline, inline callback, and named callback cuts combine without double counting implementations.

Fixed

• HF selective-render timing (pixel-verified). Isolated per-scene renders of a non-first scene now match a clean full render at the decoded-frame level (new equivalence test). The scene's Three.js canvas now animates, marker-triggered elements appear, karaoke overlays show, and turn cues fire on time — global-to-local rebasing was incomplete before.
• captions:false invalidation. Toggling the caption band now changes the render-cache key, so captioned pixels can no longer be served for a captions-off build.
• scene.cssFile now applies. It was accepted by the schema but silently ignored; now merged into the stylesheet and hashed.
• Branch restore round-trips. Scene file refs and imports restore at their original project-relative paths; the saver uses Narova's real ESM/CJS config loader, not a regex parser.
• LRU retention bounds the count. Cache pruning no longer leaves the cache over budget when kept spans are the oldest entries.
• Subtitle preset is genuinely neutral. No speaker colors, no glow, no equalizer/label by default; karaoke/slam/pop/rise keep the richer look.
• Manifest theme defaults agree with runtime. Legacy teal/navy defaults removed in favor of the v0.26 monochrome palette.

Changed

• Selective-render safety gate. Projects with project-global behavior (choreography, .js imports) transparently take a whole-video render for HyperFrames, with a stated reason, instead of attempting an unsafe isolate. no-browser is unaffected.
• Docs. Product position is "deterministic scene-scripted video with exceptionally strong narration synchronization, but narration is optional"; the fixed male/female duet casting prescription was removed.

Changed

• Chrome off by default. Topbar, counter, and progress bar are off unless explicitly enabled. The absence of chrome is now the baseline.
• Neutral default palette. Monochrome gray base replaces the navy/teal identity. Light mode is similarly neutral. Narova no longer has an accidental house style.
• Subtitles as default captions. Plain text timed to speech — no per-word color highlights or animation by default. Karaoke, slam, pop, rise remain available as explicit presets.
• Skill instructions de-anchored. Concept branching uses orthogonal creative dimensions instead of fixed archetypes. Craft rules ("hook in first 2s," "one idea per video," mandatory CTA) moved to optional narova critique profiles.

Fixed

• HF selective-render equivalence. Transitions, markers, choreography, overlays, and chrome now render identically in per-scene and full renders.
• Cache dependency model. All global render inputs (markers, patterns, chrome, theme, captions, series) now correctly invalidate cached spans.
• Complete branch snapshots. Scene file references, imports, and generated-media specs preserved in releases.
• Bounded cache retention. LRU pruning keeps recent creative alternatives around instead of deleting them immediately.

Added

• Per-scene HyperFrames render cache. HyperFrames now renders each scene as its own independent project — same per-scene caching architecture no-browser has had. Only changed scenes re-render; the rest reuse cached spans via ffmpeg concat. "Try five versions of scene 4" is cheap on both renderers.
• Named time markers. config.markers = { reveal: 2.5 } creates author-defined time anchors. Use data-cue="marker:reveal" or at: { marker: "reveal" }. Decouples timing from narration turns.
• Creative branch system. narova branch set|list|show with rationale, status, and parentage metadata.
• LLM creativity benchmark framework. 10 adversarial briefs + diversity scorer. Fixture-based CI; LLM-adapter substitution for real evaluation.
• narova critique command. Opt-in craft heuristics by profile: social-short, explainer, presentation, accessibility, or all.

Changed

• Zero-style defaults. patterns: false by default. No decorative grid. Craft checks separated from correctness.
• Better error messages. No-browser and schema errors point to available escape hatches.

Changed

• Maintenance release. The canonical changelog records no separately notable user-facing change for this version.

Added

• Scene-level render cache — narova build reuses previously rendered output instead of re-rendering the whole video every time. Each rendered span is keyed on a hash of its scene content, measured word/turn timings, and the shared render context (theme, format, fps, quality, voices, assets, choreography), so a span is reused only when reproducing it would yield perceptually-identical pixels. no-browser gets full per-scene caching (only changed scenes re-render, concatenated with the single full audio track); hyperframes gets whole-video caching (reuses the MP4 when nothing changed). Missing, empty, or wrong-duration spans are re-rendered; any cache failure falls back to a full render — caching can never fail a build. --reuse (TTS) is a separate, unaffected layer.
• Per-scene sceneHash covers author JS — the manifest's per-scene hash now includes choreographyFile, scriptFile, and threeModule contents (matching the check determinism scan), so editing one of those files invalidates only that scene's cached span.

Changed

• HyperFrames engine pinned to 0.7.96 (was 0.7.64).
• build --plan shows the cache reuse decision — the same per-scene plan the real build uses, so change scope is legible before any work runs.

Added

• scene.threeModule — the raw Three.js / WebGL escape hatch beneath declarative scene.three. A project-relative JS file inlined into the deterministic 3D bootstrap with THREE, scene, camera, renderer, tl (GSAP timeline), seed, size, duration, assets(), onRender(), and narova helpers in scope. Custom shaders, procedural geometry, post-processing, and particle systems now have a deterministic home — the largest creative-ceiling lift in the release.
• Generated-media provenance — narova generate writes a .gen.json spec sidecar next to every clip (provider, model, prompt, params, artifact hash). --regenerate <mp4> re-runs a shot from its spec; --model / --size / --duration capture or override. Generated clips are now editable creative source, not opaque output.
• build --plan — print what a revision will rebuild (per-scene scope) before doing the work. Advisory only; never changes behavior. Reduces fear of disturbing approved scenes.
• Determinism scan covers all author JS — per-scene choreographyFile, scriptFile, and threeModule are now linted for wall-clock / random / rAF / setTimeout / fetch hazards (previously only project choreography was scanned).

Changed

• Real correctness category in check — the correctness: warning prefix is wired to genuine determinism / reproducibility issues (e.g. infinite CSS animation). Previously the helper existed but no rule used it, so correctness and quality were indistinguishable.
• Honest 3D escape-hatch docs — removed the false "component-custom escape hatch" claim (no such mechanism existed). The real hatch is scene.threeModule, documented in full.

Added

• captions: false — disable the visual caption band entirely. Caption DOM, CSS padding, and presets are cleanly omitted. SRT/VTT sidecars always export.
• config.patterns — control built-in layout classes. Defaults to true for backward compat. Set patterns: false to define your own visual language.
• scene.scriptFile — per-scene raw JavaScript escape hatch for Three.js/WebGL/canvas. Inlined into scene animation context with timeline, DOM, and Three.js globals in scope. Same determinism contract as project choreography.
• Per-scene content hashes — every scene carries a hash field in the manifest. narova plan shows per-scene hash diffs. Foundation for scene-level render caching.

Changed

• Layout patterns separated from production CSS — 30+ built-in layout classes extracted to opt-in patternsCss(). Default CSS is now neutral infrastructure only: background, chrome, captions, walkthrough, marks, typography. A blank project is a canvas.
• Default background neutralized — removed accent/pink/gold radial gradient glow blobs. Default is flat var(--stage) with subtle grid.
• Default scaffold neutralized — init uses plain inline styles, not layout classes. Documents captions, chrome, and patterns options.
• Hook/CTA enforcement is context-aware — skipped for silent projects and captions: false. Warnings tagged craft: vs correctness:.

Fixed

• Documentation honesty — scene.three documented as declarative (not "unlimited"). Creative-diversity eval reframed as schema conformance test.
• Removed .grad / .hairline from default CSS.

Fixed

• Theme token preservation — custom theme tokens (stage, deep, halo, colw, user-defined) now survive the full manifest round-trip. Previously only accent and bg were preserved.
• Measured cue timing for 3D — { at: { cue: N } } now resolves to actual measured turn start times from timings.json, not cue * 2.
• Semantic action validation — draw/speak/react/follow/transform now fail validation with clear errors. Supported: appear, disappear, move, rotate, scale, orbit, revolve.
• Deterministic particle randomness — mulberry32 seeded PRNG replaces Math.random() in particle generation. Same scene + object identity → identical layouts across builds.
• data-grow / data-mark highlight — transformOrigin is now pre-seeded via tl.set() before tween, avoiding the HyperFrames sub-composition timeline breakage.
• GSAP vendored locally — GSAP 3.14.2 ships in vendor/gsap/. Generated compositions have zero CDN dependencies at render time.
• Release restore + --reuse — releases now save fingerprint and timings so --reuse works after restore.
• Version consistency — all 7 version sources (root pkg, tool pkg, SKILL.md, README, SPEC.md, CLI, docs) now fail CI when they drift.

Added

• Creative modularity — 6 file-reference types per scene (bodyFile, cssFile, choreographyFile, threeFile, elementsFile, visualFile). config.imports for reusable project-level modules. All file contents hashed for deterministic build invalidation.
• Expanded variant model — kind tags (hook, visual, narration, pacing, captions), sceneOverrides, theme/captions/timing overrides per variant. Backward-compatible.
• Concept branching — SKILL.md encourages sketching 2-3 distinct creative directions before committing to the final project.
• Creative-diversity eval suite — 10 radically different briefs, 11 convergence metrics, human review checklist. Run via node tool/evals/creative-diversity-eval.js.
• 476 tests pass (470 unit + 6 eval) — revision guarantee tests, planner accuracy tests, version consistency CI test.

Changed

• Skill restructured into hard invariants, optional craft heuristics, and creative mandate — encouraging custom HTML/CSS/SVG/Three.js over built-in templates.
• Project scaffold is now neutral — one narrator, no default palette, replace-everything design.

Added

• 3D visual system — declarative scene.three and scene.elements for cameras, lights, primitives, models, GSAP-driven animations, and tone-mapped output (ACES filmic default). Three.js upgraded from the deprecated r149 UMD to r185 ESM (esbuild-bundled global script with GLTFLoader included).
• Character abstraction — built-in presets (cat, mouse, robot) compile to THREE.Group assemblies of relative parts. One line per character; config.characters for custom ones. Group-level actions (move, rotate, appear) cascade to all descendants.
• InstancedMesh + geo/material cache — instances: [...] renders N copies in one draw call; identical primitives share buffers and programs.
• narova generate — AI clip generation via Sora/Runway APIs, downloaded to assets/ for use as scene.clip.
• canvas3d/model3d node types in the portable visual tree.
• Choreography hook — optional project-level choreography: "choreo.js" file with custom GSAP timeline code inlined into the composition. tl, DATA, gsap, and cueTime in scope; turn-anchored tweens are exactly as seek-safe as the built-in vocabulary. check lints for determinism (warns on Date, Math.random, rAF, setTimeout, fetch).

Changed

• Current correction: the non-rendering canvas3d/model3d placeholders were retired; use the fully managed scene.three or raw scene.threeModule surfaces.
• Three.js upgraded from r149 UMD to r185 ESM — the old UMD was deprecated after r149 and removed at r161. Shipped as a global script opaque to HyperFrames' compiler.
• Tone mapping now configurable (aces, agx, neutral, linear) at scene.three.toneMapping; ACES filmic is the default for video.

Fixed

• Group/character appear/disappear no longer targets .material on a THREE.Group (the old code silently killed the scene).
• Material-cache opacity bleed: tweening one mesh's opacity no longer fades every same-colored sibling.
• Animation from values honored via tl.fromTo instead of dropped.
• Boot poll bounded to 200 retries + error surface instead of polling forever.
• GLTF models load deterministically via prefetch + parseAsync, gated before frame 0.

Added

• Two free local renderers — HyperFrames keeps the complete browser/HTML/CSS surface; Narova No-Browser adds deterministic browserless Skia + FFmpeg rendering.
• Portable visual trees — stacks, groups, type, shapes, paths, raster/SVG assets, local fonts, RTL text, full-frame video, keyframes, transitions, captions, and snapshots work without a browser.
• Renderer CLI — choose with --renderer hyperframes|no-browser, then inspect capabilities and requirements with narova renderers list|doctor.
• Complex no-browser eval — a real four-scene production proof covers custom narration, audio processing/mixing, product playback, multilingual visuals, cartoon motion, captions, snapshots, and MP4 validation.

Changed

• Renderer identity and scene.visual now survive config, manifests, variants, builds, deliverables, preview, checks, and QA. HTML-only scenes fail clearly under no-browser instead of degrading silently.
• Custom narrator word timings now feed SRT/VTT and both renderers through one normalized timing contract.

Fixed

• Current FFmpeg voice compression parameters, raster/video RGBA transfer, mixed external narration selection, and long caption wrapping.

Added

• Optional OpenAI companion — a dependency-free Speech API worker with environment-only authentication, direct validated WAV output, and the generic narova-tts-provider/v1 protocol.
• Current speech controls — steerable gpt-4o-mini-tts by default, the latest fixed snapshot, legacy speed/quality models, 13 built-in voices, existing custom voice IDs, delivery instructions, speed, and multilingual guidance.
• Full provider tests — model and option validation, credentials, request mapping, voice listing, output safety, and no-retry billing behavior are part of npm test.

Changed

• README, specification, skill guidance, CLI reference, and landing page now present OpenAI and ElevenLabs as peer optional providers while Narova stays local-first.

Security

• .env.local is ignored; credentials never enter project configuration, cache identity, protocol output, or generated artifacts.

Changed

• Skill context re-engineered — SKILL.md reduced from 339 to 127 lines (−62%) based on Anthropic's context engineering best practices for Claude 5 models. Overly prescriptive intake scripts, redundant hard rules, and example dialogues replaced by progressive disclosure through the existing references/ files.
• Ten hard rules → four key gotchas — only genuinely non-inferrable rendering details remain upfront (no looping CSS, SVG namespacing, output hygiene, sourcing vs. balance). Discoverable rules (voice defaults, narrator counts, theme mode conventions) now live in reference docs.
• Workflow compressed — eight detailed step sections condensed to a numbered one-line-per-step list with file-pointer references.

Added

• AGENTS.md — lightweight repo-level project guidance (CLAUDE.md symlinks to it). Six gotchas specific to the narova project.

Added

• External narration — config.narration.file lets you use pre-recorded audio instead of TTS. No voices or TTS backend needed.
• External karaoke captions — narration.wordTimings accepts a JSON file of word-timed cues. Narova injects word-level karaoke overlays into every scene at compose time — the spoken word highlights in gold with no caption HTML in your scene bodies.
• Auto bed/SFX mixing for external narration — when bed or sfx are configured alongside narration.file, narova mixes them with the external audio using ffmpeg. No TTS venv needed.
• Voice processing for external narration — narration.process with optional highpass, lowpass, compressor, and loudness settings.
• narova karaoke generate — transcribe an audio file to word-timed karaoke JSON + SRT using faster-whisper or whisper-cpp. --transcript maps a clean transcript onto Whisper timings.
• narova retime — auto-derive scene durations from word timing data. --apply rewrites the config in-place.
• WhatsApp export preset — whatsapp-compressed: 540×960, rate-controlled H.264 encode under 16 MB for messaging apps.
• Port auto-detection for preview — narova preview finds the next available port instead of silently failing on conflicts.

Changed

• narova check now reports "external" backend (not "silent") when config.narration is set, and estimates duration from explicit scene dur values.
• narova check detects HyperFrames-reserved class names used as CSS selectors in theme.css — previously only checked HTML class attributes.
• Hook checks (lead-in silence, on-screen text warnings) are skipped when using external narration.

Added

• Real product walkthroughs — narration-timed semantic clicks, typing, waits, scrolling, evidence screenshots, and agent-readable exploration through optional agent-browser sessions.
• Generated browser-window and full-bleed layouts retain Narova voiceover, word-synced captions, overlays, and platform exports.
• Content-addressed capture manifests track action drift, media metadata, and config/synthesis/timing/media/evidence hashes; incomplete or stale takes fail composition and release checks.
• A real browser-to-MP4 eval validates interactive capture, 1280×720 output, retained audio, and black-frame safety.
• An 83-second narrated showcase demonstrates project creation, configuration, search, task assignment, automation, and teammate invitation in one 24-operation browser take.

Changed

• narova plan now models capture as its own stage, recapturing only when actions or narration timing change.
• Walkthrough renders use lossless PNG frame extraction so product text stays sharp.
• The isolated walkthrough cursor is reinstalled in agent-browser's fresh recording context, and semantic clicks emit a short expanding ripple that fades and is removed after each click.

Security

• Capture is always explicit; builds never replay browser actions. Typed values and URL queries are redacted, while embedded URL credentials are rejected and stripped defensively.

Added

• External TTS provider protocol — explicitly registered executable workers speak versioned narova-tts-provider/v1 JSON Lines without placing provider code in Narova core.
• narova providers add|list|doctor|remove plus generic external voice listing through narova voices list --backend <provider>.
• Optional ElevenLabs companion skill — isolated HTTP worker, environment-only API key, voice IDs, provider options, WAV conversion, and mocked tests with no paid calls.
• Provider protocol/version/options are included deterministically in audio fingerprints and sentence-cache identity.
• Urdu sentence punctuation — native full stops (۔) and question marks (؟) now split speech and timing groups consistently in Python synthesis and Node manifest processing.
• Urdu voice direction — Narova’s skill instructions now delegate meaningful Urdu dialogue polishing to the optional urdu-voice-director skill while keeping caption text free of provider-specific performance tags.

Changed

• Narova remains local-first: Piper is still the default, and external workers run only after explicit registration.
• The website now covers the current provider architecture, planning and release workflow, export profiles, Urdu-aware dialogue, and accessibility improvements.

Added

• Clear URL-to-video boundary: agents interpret sources and write the story; narova ingest performs the mechanical HTML, image, and screenshot pass.
• Complete CLI documentation for --deliverables and --safe-area-guides.

Changed

• Export behavior now documents scale-and-pad limitations, canonical platform presets, and when HyperFrames receives an explicit resolution.

Added

• narova check --strict verifies detected claims against claims.md; check --release fails builds with remote dependencies, missing evidence, unsupported markup, or empty frames.
• Voice-less silent projects, claims-ledger table parsing, and YouTube as a first-class platform.

Fixed

• Release asset gating, visual-content detection, platform duration behavior, and Pexels authentication documentation.

Added

• Complete audio fingerprints for safe --reuse, asset-content hashing, and five-stage rebuild planning.
• Manifest-first pipeline, canonical export preset registry, YouTube profiles, named project release snapshots, and exact preset dimensions.

Changed

• Portable manifest paths and authoring-only safe-area guides keep projects reproducible without leaking machine-local paths.

Added

• Render-path CSS compatibility lint, automatic looping for short b-roll clips, and long-video wipe warnings.

Fixed

• Built-in b-roll styling and WebM looping now stay on HyperFrames’ fast, compatible render path.

Changed

• timeline.json became the canonical manifest.json.

Added

• Content hashes, narova plan, and named manifest releases under ~/.narova/releases/.

Added

• Comprehensive YouTube, TikTok, Reels, Shorts, LinkedIn, X, and Narova-standard export profiles with ffmpeg encoding, loudness targets, safe-area metadata, and thumbnails.

Added

• Versioned timeline IR — narova compile produces out/timeline.json (schema v1.0), a self-contained JSON document with project metadata, format, voices, scenes, assets, deliverables, and variants. Auto-written by synth/compose/build and enriched with word timings post-synthesis.
• Timeline validation: narova key required, schema version compatibility enforced, structural integrity checks.
• mergeTimings with correct sentence-to-turn distribution and no double-offset on turn start times.
• Full asset tree walk for timeline inventory.
• 31 unit tests for compilation, validation, merge, and round-trip.

Changed

• Variants now carry full scene definitions (body, VO, transition) in the timeline.
• SPEC.md updated with timeline IR documentation section.

Added

• XTTS language support — per-turn and per-voice lang now flows through to coqui-tts against 17 supported languages.
• Release automation: scripts/sync-version.js keeps all version surfaces in sync.

Changed

• Documentation remediation: narrowed "any URL", restructured frontmatter, qualified platform/offline claims, read-only update check.

Fixed

• Version drift across five surfaces.

Added

• npx retry with exponential backoff for DNS failures.
• Stock assets reference documentation.

Changed

• Doctor command now reports mismatched tool versions and venv health.

Added

• captions.maxWords config — limits words per caption line to prevent overcrowding.
• CSS custom property tokens for caption zone spacing (--cap-pad, --cap-gap).

Fixed

• Restored b-roll data-duration attribute for reliable HyperFrames seek and playback; scene-bounded clipping prevents b-roll from bleeding into the next scene.

Fixed

• B-roll StaticGuard: removed data-duration + clip class to prevent b-roll clips from persisting across scene boundaries.

Fixed

• gainDb now works for all backends (was applied only to piper); now also applies to xtts, qwen, and chatterbox outputs.

Added

• Silent scenes — vo-less scenes with a fixed dur (seconds) for visual-only segments (title cards, separators, end cards).

Fixed

• Caption end time capped at the scene boundary, preventing words from rendering into the next scene's visual space.

Added

• Per-voice gain control — gainDb on any voice, range −24 to +24 dB, applied in the synth stage after TTS before audio mixing.
• B-roll clips are now root-level HyperFrames clip nodes, keeping them out of the scene DOM for cleaner composition.

Changed

• Renamed config key music → bed (old key still accepted).

Fixed

• Studio preview project naming: compose and build assign unique HyperFrames project names per narova project, preventing collision when multiple projects are open.

Added

• Partial word alignment for mixed-language scenes — alignment falls back gracefully on per-word mismatch, keeping estimates for words that cannot be measured.
• B-roll videos are now HyperFrames-native clip nodes (seek-safe, no frame-dropping on timeline scrub).

Fixed

• Per-turn language cache key now uses sentence_cache_key() for stable identity.
• Arabic and Urdu captions now render right-to-left (RTL).
• Unique Studio project names per narova project (prevents preview collision).
• Generated CSS externalized to keep each scene's HTML body under HyperFrames' 500-line lint threshold.

Added

• Per-turn language for multilingual TTS — lang on any turn selects the TTS language for chatterbox and qwen backends.
• Voice sample management: narova voice sample add/list/remove for chatterbox voice cloning (validation, auto-normalization: mono, 24 kHz, voice-range EQ, peak-safe loudness).

Changed

• Agent intake: agents must ask before picking defaults; intake is a dynamic principle, not a fixed checklist.

Fixed

• Chatterbox voice samples auto-normalized on import (mono, 24 kHz, voice-range EQ, peak-safe loudness).
• Force CPU on Apple Silicon for XTTS, Qwen, and Chatterbox — MPS has known conv1d breakage with these models.
• narova check warns when scene body HTML uses HyperFrames-reserved class names (e.g. .scene, .container).
• Landing page redesigned around a video-first workflow; multi-speaker messaging corrected.

Added

• Music bed + spot SFX — music: {file, volume, fadeIn, fadeOut} and sfx: [{file, scene, at, volume}] mixed into narration via ffmpeg. Music changes don't require re-synthesis.
• Caption style presets + keyword emphasis — captions: {preset: karaoke|slam|pop|rise, emphasis: [...]}.
• Per-platform size presets + duration-band lint — platform: tiktok|reels|shorts|linkedin|x picks frame size and duration-band lint. SRT + WebVTT sidecars.
• Forced word alignment — align: true | {engine}. Measured word timings replace estimates; per-scene graceful fallback.
• Chatterbox v3 — multilingual voice cloning with per-voice lang, watermarked output.
• Scene transitions + hand-drawn annotations — transition: fade|wipe|slide|zoom; data-mark="underline|circle|box|highlight".
• Hook-variant generation — variants: [{id, scene}]; narova build --variant <id> renders A/B hook tests.
• narova ingest <url> — fetches page, downloads images, takes headless screenshot, appends sources.md, seeds claims.md.
• Hook enforcement in narova check — warns on lead-in silence >200ms, scene 1 missing visible text, missing saveable end-card.
• B‑roll per scene — clip: "assets/bg.mp4" on any scene plays a looped video behind the HTML overlay.
• Series/multi‑part mode — series: {part, total} adds a “Part 2 / 5” badge overlay for multi-episode scripts.
• Voice sample management — narova voice sample add/list/remove for chatterbox clone samples.
• Interactive landing page (this site) and changelog subpage.
• Demo GIF, CHANGELOG.md, references/audio.md.

Changed

• README restructured around the demo: hook, GIF, why-bullets, install, quickstart.
• SPEC updated to the 0.7.0 contract; stale examples/ references repointed to generated/.

Fixed

• Slam caption overlap — fromTo scale tween parked every upcoming word at the from-state; rewritten as .to() tweens only.

Added

• Photo motion, scene transitions, XTTS voice cloning, and Qwen instruct control.
• Chatterbox voice-cloning TTS backend.
• narova skill showcase reel.

Fixed

• Session friction from the us-iran-standoff build: motion glitches, scene ids, QA workflow, CLI edges.
• Loud clone-path errors, drift lint, chatterbox validation and cache identity.

Added

• Example intro videos: Folio3, Careem, DeepLearning.AI, US–Iran standoff briefing.
• Hardening against the failures found in the bazaartech retrospective.
• Skill exposed to .agents-standard agents at project scope.

Changed

• Aligned versions and hardened config/argument edges from the skill review.

Removed

• Legacy examples superseded by the generated intro projects.

Added

• Source-aware, asset-native pipeline: any URL becomes verified source material.
• Iteration-consistent synthesis: unchanged turns keep byte-identical audio across revisions.
• Prompt-to-video craft references and anti-template visual-variety rules.
• Qwen3-TTS backend and theme-from-intent skill rules.

Changed

• Breaking: narova IS the skill — tool bundled under the standard skills/ layout.
• Docs rewritten in plain language; tests moved into the skill.

Changed

• Breaking: build/preview run on the HyperFrames render engine; the old player/capture/assemble/serve pipeline is deleted.

Added

• narova compose — HyperFrames composition generator.
• audio/full.wav — the concatenated narration track.
• Zero-dependency test suite for schema, lints, compose, and timings.
• Claude Code agent skill + installer.

Added

• narova check — fast config validation with no synth or capture.
• vkf-upgrade example: a 7-scene 1:1 social announcement.

Fixed

• py/ and scripts/ now ship in the published package files.

Added

• Initial release: a script-to-narrated-kinetic-video toolkit.