@revola-ai/video-craft 0.2.1

package/src/rules/atmosphereGradientsFadeAtBothEnds.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "Fog gradient started
+ * *opaque* - a hard black band sliced the frame and cut the clock in half.
+ * Now transparent at BOTH ends, and confined to a world band that can't
+ * reach the clock." Only the durable half is kept as the claim; the band
+ * values themselves are per-scene design decisions.
+ */
+export const atmosphereGradientsFadeAtBothEnds: Rule = {
+  id: "atmosphere-gradients-fade-at-both-ends",
+  claim: "Make full-bleed atmosphere gradients (fog, haze) transparent at both ends and confine them to a declared world band.",
+  why: "A fog gradient that started opaque produced a hard black band that sliced the frame and cut the clock in half; band confinement guarantees it can never reach elements in other zones.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S1Graveyard.tsx" },
+  },
+};

package/src/rules/audioIsTheClock.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md ("Audio is the clock... Timing is a pure
+ * function of the audio"), merged with act854-video/BUILD_NOTES.md's
+ * measure-the-WAV procedure ("to fit a new VO: measure it, then edit only
+ * D_INTRO ... D_CLOSE"). The measuring side lives in video-cli's measure
+ * command, which derives frame counts from WAV sample counts.
+ */
+export const audioIsTheClock: Rule = {
+  id: "audio-is-the-clock",
+  claim: "Record or generate the voiceover first, measure it, and fit the video to the audio; never re-time audio to fit the video.",
+  why: "Reversing the order forces re-recording or hand-stretching audio every time timing shifts, and every feedback round shifts timing; deriving durations from the measured WAV makes a re-time a re-measure.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "gate",
+  verify: "`ffprobe -show_entries stream=nb_frames <render>` equals `total` in .video/timing.json",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/measure.ts" },
+  },
+};

package/src/rules/beatsDeriveFromTheirOwnSequence.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from the product-room build: the cold open's in-frame content starts
+ * when the browser frame arrives, making its Sequence 142 frames shorter than
+ * the section. A CLICK constant derived from the section length sat past the
+ * sequence's final rendered frame. The failure mode is the dangerous kind:
+ * no error, no missing element, just a beat that never happens.
+ */
+export const beatsDeriveFromTheirOwnSequence: Rule = {
+  id: "beats-derive-from-their-own-sequence",
+  claim: "Compute a beat's frame from the duration of the Sequence it renders in, never from a parent's or a section's length.",
+  why: "A click beat derived from its section's length landed 10 frames past the last frame its shorter in-frame sequence ever draws, so the cursor drifted toward the button and the scene cut away before the press - the beat silently did not exist, and nothing failed.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/productroom/PRColdOpen.tsx" },
+  },
+};

package/src/rules/bestSceneSetsTheBar.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 20 ("amazing, move on to
+ * the next scene, now you know what I like", "make it match the first 3
+ * scenes' animation quality", "i already upgraded scenes 1 and 2 so you can
+ * take them as inspo"). The preservation half of the directive is
+ * fixes-preserve-approved-elements; this rule owns the propagation half.
+ */
+export const bestSceneSetsTheBar: Rule = {
+  id: "best-scene-sets-the-bar",
+  claim: "The moment a scene is approved it becomes the film's standard: take it as inspiration for every other scene, name it in review, and measure the weakest scene against the strongest every round.",
+  why: "'Amazing, move on to the next scene, now you know what I like' and 'make it match the first 3 scenes' animation quality' show approval creating a bar; rounds that ignored it re-litigated settled taste scene by scene.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A cross-scene quality comparison made during review rounds; no single code location expresses it.",
+  },
+};

package/src/rules/bumpBeforeRefreeze.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "A same-version repack is a silent wrong
+ * pin: npm sees an unchanged dep string, keeps old content locally, and
+ * breaks fresh installs elsewhere." Already tool-enforced: freezeKit refuses
+ * the overwrite. The rule exists so agents do not work around the refusal.
+ */
+export const bumpBeforeRefreeze: Rule = {
+  id: "bump-before-refreeze",
+  claim: "If kit content changed, bump the kit version before re-freezing; never repack the same version with different bytes.",
+  why: "A same-version repack is a silent wrong pin: npm sees an unchanged dep string, keeps old content locally, and breaks fresh installs elsewhere.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/kitShell.ts", symbol: "freezeKit" },
+  },
+};

package/src/rules/cameraIsTheNarrator.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 10 ("amazing camera
+ * effects", "zoom in, take actions, zoom out - a detailed cinematic
+ * dashboard reveal", "each time it's showing typing, the camera should zoom
+ * in and follow the typing", against "camera buggy and clumsy" and "it
+ * zooms in and suddenly zooms out").
+ */
+export const cameraIsTheNarrator: Rule = {
+  id: "camera-is-the-narrator",
+  claim: "The camera tells the story with few, motivated, committed moves - a push into the element the VO names, a continuous journey through stations, following typing as it happens, a dive through an element into the next scene - each aimed at one subject with dwell time at the destination; unmotivated, whiplash, or decorative in-out moves read as mistakes.",
+  why: "'Amazing camera effects' was the recurring ask and 'camera buggy and clumsy ... it zooms in and suddenly zooms out' the recurring complaint; three deliberate moves consistently out-reviewed five micro-keys, and editorial single-subject framing beat crowded ensemble frames.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A camera-arc judgment across a scene's key schedule; no single code location expresses it.",
+  },
+};

package/src/rules/checkPinBeforeShip.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Before a video ships, run check-pin
+ * --project <dir>; it fails on a live link, a missing or uncommitted
+ * tarball, a lockfile/tarball integrity mismatch..." The tool enforces the
+ * checks; the rule makes running it mandatory, which the tool cannot
+ * self-enforce.
+ */
+export const checkPinBeforeShip: Rule = {
+  id: "check-pin-before-ship",
+  claim: "Run check-pin --project <dir> before any video ships; ship only on a frozen, committed, integrity-matching tarball pin.",
+  why: "Shipping on a live link or stale tarball makes the delivered render non-reproducible: the exact bytes that rendered it cannot be recovered later.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "gate",
+  verify: "`video check-pin --project <dir>`",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/cli.ts" },
+  },
+};

package/src/rules/coldViewerClarity.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 19 ("I showed someone
+ * this video and they said they don't get it", "make it more comprehensible
+ * so anyone watching understands what scene 5 is trying to communicate",
+ * "somehow make it more obvious what Raycast is for"). Visually approved
+ * scenes were rebuilt purely for comprehension.
+ */
+export const coldViewerClarity: Rule = {
+  id: "cold-viewer-clarity",
+  claim: "Every scene passes the cold-viewer test: someone outside the company can say what the scene is about; confusion is fixed with orientation copy, clearer visual metaphors, or slower reveals, because clarity and spectacle are the same axis, not a trade.",
+  why: "'I showed someone this video and they said they don't get it' triggered rebuilds of scenes that were already visually approved; polish that fails to communicate is not polish.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A comprehension judgment requiring an outside-context reading of the scene; no single code location expresses it.",
+  },
+};

package/src/rules/commitOrCutEffects.ts

@@ -0,0 +1,36 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 15: both directions were
+ * flagged - overuse ("don't overuse the reveal effect - maybe once or
+ * never", "the white flash effect in the last scene is too much", "just
+ * don't like that grain effect") and half-commitment ("the blur effect is
+ * so minimal and low effort").
+ */
+export const commitOrCutEffects: Rule = {
+  id: "commit-or-cut-effects",
+  claim: "An effect either commits or gets cut: a half-committed effect that barely registers is as much a defect as one stamped on every beat, and film grain is out entirely.",
+  why: "Review rounds flagged both failure directions - 'don't overuse the reveal effect' alongside 'the blur effect is so minimal and low effort' - so the only approved states for an effect are absent or unmistakable.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  // The blanket "film grain is out entirely" half of this claim contradicted
+  // the shipped kit, which exports and documents `FilmGrain` (video-kit
+  // src/craft/stage.tsx), and QGuard renders it twice in Shell.tsx. Unwaived,
+  // the projection read as a standing instruction to delete a deliberate,
+  // spec'd element - so an agent following CLAUDE.md would strip working
+  // work. The ban itself is real client feedback ("just don't like that grain
+  // effect", CREATIVE_EDGE directive 15), so it stands everywhere else.
+  exceptions: [
+    {
+      project: "qse-qguard-video",
+      decision:
+        "client chose ACT854's persistent frame chrome for the QGuard restyle, film grain included - specified in the mounted-once cinematic overlay as a 256px feTurbulence tile at mixBlendMode overlay (motion-brand-spec §6.1)",
+      recordedIn: "qse-qguard-video/docs/motion-brand-spec.md",
+    },
+  ],
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A commitment-level judgment per effect instance; no single code location expresses it.",
+  },
+};

package/src/rules/convertFramesAcrossClockBoundary.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md, the two follow-on fixes to the
+ * time remap - "both are the same class of bug (a design frame used where a
+ * playback frame was meant)".
+ */
+export const convertFramesAcrossClockBoundary: Rule = {
+  id: "convert-frames-across-clock-boundary",
+  claim: "When design and playback clocks coexist, route every cross-boundary value through the remap: values mirroring scene-internal beats convert design-to-playback, and values measuring the film read the composition timeline.",
+  why: "A design frame used where a playback frame is meant drifts silently: raw design-frame cue anchors would have been ~1.5s off picture at 1.34x, and the on-screen counter would have claimed a 60s runtime the 56.6s film does not have.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/mix.tsx", symbol: "at1" },
+  },
+};

package/src/rules/crossCutElementsLiveInTheHudLayer.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "in world space the S1 camera
+ * drags the line wherever the last cam key happens to be, so any S1 recut
+ * silently moves the seam. Pinning it to the HUD makes the contract a
+ * constant." The mechanism is CraftStage's hud prop ("renders in SCREEN
+ * space").
+ */
+export const crossCutElementsLiveInTheHudLayer: Rule = {
+  id: "cross-cut-elements-live-in-the-hud-layer",
+  claim: "Render any element that must hold an exact screen position across a scene cut (a seam contract) in the HUD/screen-space layer, never in world space under the camera.",
+  why: "In world space the camera drags the element wherever the last key happens to be, so any recut silently moves the seam and invalidates the neighbouring scene's match cut.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/craftKit.tsx", symbol: "CraftStage" },
+  },
+};

package/src/rules/cursorClicksRealControls.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/act854-qpa-video.md: client feedback
+ * "Fix the useless cursor presses inside tabs... it presses 3 times on the
+ * sidebar... it's confusing" and "at each tab there is a purple thing coming
+ * out of the cursor looking like it's pressing something inside the page,
+ * but it doesn't, and it looks really bad". Complements
+ * rebuild-ui-from-recon-not-screenshots on the interaction side.
+ */
+export const cursorClicksRealControls: Rule = {
+  id: "cursor-clicks-real-controls",
+  claim: "Every cursor click lands on a real, visible control and causes a visible state change; click ripples appear only on genuine navigation clicks, never as decorative presses inside content.",
+  why: "Decorative presses that change nothing read as confusing and 'really bad' to clients, and the ripple fix needed a second round because leftover presses survived; interaction realism is what sells a walkthrough as the real product.",
+  learnedFrom: "claude-sessions-digest/act854-qpa-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-kit/src/pure/walk.ts" },
+  },
+};

package/src/rules/cutOnRealAudioPauses.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "Cut points are the read's own
+ * pauses, not arithmetic. Verified with ffmpeg silencedetect -40dB:0.18 -
+ * every one lands inside a real pause." The P_S1...P_S5 playback lengths in
+ * tokensCraft.ts are the artifact of this procedure.
+ */
+export const cutOnRealAudioPauses: Rule = {
+  id: "cut-on-real-audio-pauses",
+  claim: "Place scene boundaries inside real pauses in the recorded read, verified with ffmpeg silencedetect, never by arithmetic division of the audio.",
+  why: "An arithmetic cut point lands mid-word or mid-breath; verifying against detected silences guarantees each scene change coincides with a pause in the narration.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/tokensCraft.ts" },
+  },
+};

package/src/rules/darkButNeverDim.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 14 ("use lighter colors
+ * ... very low contrast, it exhausted my eyes", "add more colors, everything
+ * looks too dark, but don't go outside the theming", "scene 1 and scene 2
+ * look like they come from different videos", "keep artifact colors and the
+ * background persistent").
+ */
+export const darkButNeverDim: Rule = {
+  id: "dark-but-never-dim",
+  claim: "The dark cinematic canvas never costs legibility: lift values, use lighter material (white-paper artifacts on the dark shell), keep tonal variety inside the theme, and hold the canvas consistent scene to scene - 'too dark to read comfortably' and 'these scenes look like different videos' are both hard fails.",
+  why: "'Very low contrast, it exhausted my eyes' and 'add more colors, everything looks too dark, but don't go outside the theming' show the dark theme failing on comfort while staying on brand; darkness is the style, dimness and canvas drift are the defects.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A contrast-and-consistency judgment across scenes at 1080p; no single code location expresses it.",
+  },
+};

package/src/rules/dataRadarTagsDeclared.test.ts

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "../testSupport";
+import { checkFile } from "../sourceCheck";
+import { dataRadarTagsDeclared } from "./dataRadarTagsDeclared";
+
+const check = () => {
+  if (dataRadarTagsDeclared.enforcement.kind !== "source") throw new Error("expected a source rule");
+  return dataRadarTagsDeclared.enforcement.check;
+};
+
+// The rule is PROJECT-wide (final-review I4): a declared element is routinely
+// tagged in a child component, not in the scene module, so the honest
+// source-level claim is "tagged somewhere in this project". Each fixture
+// directory below is its own one-project world (its own plan*.yaml), and any
+// file in it reports that project's findings.
+const runIn = (fixture: string, name: string) => {
+  const rel = `packages/video-craft/src/fixtures/${fixture}/${name}`;
+  return checkFile(check(), join(repoRoot, rel), rel, repoRoot);
+};
+
+describe("dataRadarTagsDeclared", () => {
+  test("fires on a names: element id no file in the project tags", () => {
+    const findings = runIn("data-radar-tags", "SceneWithGap.tsx");
+    expect(findings.map((f) => f.match)).toEqual(["cta"]);
+    expect(findings[0].message).toMatch(/declares names: element "cta"/);
+    expect(findings[0].message).toMatch(/no data-radar="cta" attribute exists anywhere/);
+    // Attributed to the PLAN, where the binding lives and where the author
+    // fixes it - not to whichever scene file happened to be parsed.
+    expect(findings[0].file).toMatch(/plan\.fixture\.yaml$/);
+  });
+
+  test("a declared id tagged in a SIBLING file of the same project is not a finding", () => {
+    // "hero" is declared for the `gap` section but tagged only in
+    // SceneClean.tsx. Under the old per-file rule this was a false positive
+    // waiting to happen - it is exactly the QGuard shape, where `once`'s
+    // login-scanner is tagged in src/artifacts/Stations.tsx.
+    const findings = runIn("data-radar-tags", "SceneClean.tsx");
+    expect(findings.map((f) => f.match)).toEqual(["cta"]);
+  });
+
+  test("does not fire on a null binding (an honest 'no single subject')", () => {
+    const findings = runIn("data-radar-tags", "SceneNullBinding.tsx");
+    expect(findings.map((f) => f.match)).toEqual(["cta"]);
+  });
+
+  test("accepts a template-literal tag family, e.g. data-radar={`branch-${kind}`}", () => {
+    expect(runIn("data-radar-dynamic", "Branches.tsx")).toEqual([]);
+  });
+
+  test("accepts a tag forwarded through a `dataRadar` prop its call sites pass a literal to", () => {
+    expect(runIn("data-radar-forwarded", "Scene.tsx")).toEqual([]);
+  });
+
+  test("reports the site, never a false clean, when data-radar is bound to an expression it cannot evaluate", () => {
+    const findings = runIn("data-radar-opaque", "Scene.tsx");
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toMatch(/cannot evaluate/);
+  });
+});