@revola-ai/video-craft 0.2.1

package/README.md

@@ -0,0 +1,56 @@
+# @revola-ai/video-craft
+
+Durable craft knowledge for building videos in this repo, as machine-checked rules.
+
+## Adding a rule
+
+Pick the track that fits, then finish with the shared steps below.
+
+**Prose rule, anchored** (a lesson that points at live code):
+copy `src/rules/deriveSeamsDontMeasure.ts`. Anchor to a durable home - an
+exported kit symbol or a long-lived helper - over a scene-local constant.
+If an anchor later dangles, re-anchor it to where the evidence now lives;
+never flip it to `unanchorable` to silence the test.
+
+**Prose rule, unanchorable** (process guidance with no code to point at):
+copy `src/rules/deleteRejectedRigsCompletely.ts`. The `unanchorable` string
+must say why, and when to re-anchor if that changes.
+
+**Source rule** (mechanically checkable in scene source):
+copy `src/rules/noNestedSvgFilters.ts`. Also required: a fixture pair under
+`src/fixtures/` (broken shape fires, fixed shape does not, plus a
+false-positive guard), a `src/rules/<name>.test.ts`, and a clean run over the
+corpus - `src/corpus.test.ts` fails on any finding that is not a justified
+`KNOWN_EXCEPTIONS` entry naming a recorded follow-up. `include` globs are
+explicit per project; `exclude` is the coarse escape hatch for files a rule
+never applies to.
+
+**Component rule** (feeds a kit sidecar): set
+`scope: { kind: "component", slug, field }`. `whenToUse` and `whenNotToUse`
+allow one rule each per component - pick the crispest sentence.
+
+**Shared steps, in order:**
+
+1. Register the rule in `src/registry.ts`.
+2. Run `npx tsx packages/video-craft/scripts/generate.ts` (validates the
+   registry, then rewrites the outputs below).
+3. Run `./node_modules/.bin/tsc -p tsconfig.json --noEmit` - vitest does NOT
+   typecheck, and a malformed `Rule` literal is a type error, not a test
+   failure.
+4. Run `./node_modules/.bin/vitest run packages/video-craft`.
+5. Add a back-reference (`(Rule: \`<id>\`.)`) to the notes passage it was
+   mined from.
+
+Skipping step 2 makes the drift tests fail with a stale-file diff: run the
+generator, never hand-edit the generated files.
+
+## Outputs (machine-owned - do not hand-edit)
+
+- `packages/video-kit/src/motion/<slug>.meta.ts` - one per component with rules.
+- The `craft:begin pipeline` block in `HOW_I_BUILD_VIDEOS.md`.
+
+Component rules are discoverable through the sidecars, pipeline rules through
+the doc block; `src/registry.ts` is the complete list.
+
+Every rule needs a `learnedFrom`: a rule with no origin is an opinion, not
+knowledge. The verifier fails if that file disappears.

package/dist/anchors.js

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Project, ts } from "ts-morph";
+import { isUpstreamProvenance, upstreamCitationError } from "./provenance.js";
+function provenanceError(path, root) {
+  if (isUpstreamProvenance(path)) {
+    const malformed = upstreamCitationError(path);
+    return malformed ? `is a malformed upstream citation (${malformed})` : void 0;
+  }
+  return existsSync(join(root, path)) ? void 0 : "does not exist";
+}
+function verifyAnchors(rules, root) {
+  const errors = [];
+  const project = new Project({
+    useInMemoryFileSystem: false,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: { allowJs: true, jsx: ts.JsxEmit.ReactJSX }
+  });
+  for (const rule of rules) {
+    if (rule.learnedFrom) {
+      const bad = provenanceError(rule.learnedFrom, root);
+      if (bad) {
+        errors.push(`rule "${rule.id}": learnedFrom "${rule.learnedFrom}" ${bad}`);
+      }
+    }
+    for (const ex of rule.exceptions ?? []) {
+      const badRecord = provenanceError(ex.recordedIn, root);
+      if (badRecord) {
+        errors.push(
+          `rule "${rule.id}": exception recordedIn "${ex.recordedIn}" ${badRecord}`
+        );
+      }
+      const badProject = provenanceError(ex.project, root);
+      if (badProject) {
+        errors.push(`rule "${rule.id}": exception project "${ex.project}" ${badProject}`);
+      }
+    }
+    if (rule.enforcement.kind !== "prose") continue;
+    if (!("anchor" in rule.enforcement)) continue;
+    const { file, symbol } = rule.enforcement.anchor;
+    if (isUpstreamProvenance(file)) {
+      const malformed = upstreamCitationError(file);
+      if (malformed) {
+        errors.push(
+          `rule "${rule.id}": anchor file "${file}" is a malformed upstream citation (${malformed})`
+        );
+      }
+      continue;
+    }
+    const abs = join(root, file);
+    if (!existsSync(abs)) {
+      errors.push(`rule "${rule.id}": anchor file "${file}" does not exist`);
+      continue;
+    }
+    if (!symbol) continue;
+    const source = project.getSourceFile(abs) ?? project.addSourceFileAtPath(abs);
+    const exported = source.getExportedDeclarations().has(symbol);
+    const local = source.getVariableDeclaration(symbol) !== void 0 || source.getFunction(symbol) !== void 0 || source.getInterface(symbol) !== void 0 || source.getTypeAlias(symbol) !== void 0;
+    if (!exported && !local) {
+      errors.push(
+        `rule "${rule.id}": anchor symbol "${symbol}" no longer exists in "${file}" - re-anchor the rule to where the evidence now lives; do not flip it to unanchorable`
+      );
+    }
+  }
+  return errors;
+}
+export {
+  verifyAnchors
+};

package/dist/corpus.js

@@ -0,0 +1,91 @@
+import { RULES } from "./registry.js";
+import { matchedFiles, runSourceCheck } from "./sourceCheck.js";
+const HEX_RULE = "tokens-not-raw-hexes";
+const PANEL_FILL = "dark panel fill predates the rule; follow-up: tokenize into CK";
+const BG_RESTATED = "raw restatement of CK.bg (#0b0b0d) predates the rule; follow-up: reference the token";
+const HUE_RESTATED = "avatar hue pair restates CK accent tokens raw; predates the rule; follow-up: reference the tokens";
+const LAVENDER = "lavender text tint (#c9b8fb) has no CK token yet; predates the rule; follow-up: tokenize into CK";
+const ROCKET = "rocket illustration fill has no CK token yet; predates the rule; follow-up: tokenize into CK";
+const KNOWN_EXCEPTIONS = [
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S3Line.tsx", match: "#15141d", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S3Line.tsx", match: "#1c1a26", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S3Line.tsx", match: "#14131c", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S4Proof.tsx", match: "#16151e", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S2Turn.tsx", match: "#0b0b0d", justification: BG_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S4Proof.tsx", match: "#0b0b0d", justification: BG_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/craftKit.tsx", match: "#0b0b0d", justification: BG_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#8B5CF6", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#5CA4F6", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#5fd39a", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#f8b8aa", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#f5d67a", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#c9b8fb", justification: LAVENDER },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/ink.tsx", match: "#f5c66d", justification: ROCKET },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/ink.tsx", match: "#2a2833", justification: ROCKET },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/ink.tsx", match: "#bda6ff", justification: ROCKET },
+  // v2 (build2) frame-windowed carrier/hero binding: the tag is gated off over
+  // the seam-flight/vacate window (so hero-size never measures the shrinking
+  // carrier and no post-cue pose trips a geometry check), which a string literal
+  // cannot express; the runtime tag coverage (radar:scene tag-coverage, 22/22)
+  // still verifies every binding against sampled frames during its cues.
+  // Follow-up: remotion-videos-emp (source-evaluable hero/carrier windows).
+  {
+    rule: "data-radar-tags-declared",
+    file: "rcp-fund7-video/src/scenes/insurers.tsx",
+    match: 'data-radar={f < T_VACATE ? "insurer-edifice" : undefined}',
+    justification: "frame-windowed carrier tag gated off during the closing travel; runtime tag-coverage (22/22) verifies insurer-edifice during its cues. follow-up: remotion-videos-s300"
+  },
+  {
+    rule: "data-radar-tags-declared",
+    file: "rcp-fund7-video/src/surfaces.tsx",
+    match: "data-radar={radarId}",
+    justification: "Panel forwards its tag via the radarId prop (call sites pass literals); the gate only traces props named dataRadar. Runtime tag-coverage verifies the bindings. follow-up: remotion-videos-s300 (rename prop to dataRadar)"
+  }
+];
+function corpusFindings(root) {
+  const out = [];
+  for (const rule of RULES) {
+    if (rule.enforcement.kind !== "source") continue;
+    for (const finding of runSourceCheck(rule.enforcement.check, root)) {
+      out.push({ ...finding, rule: rule.id });
+    }
+  }
+  return out;
+}
+const findingKey = (f) => `${f.rule}|${f.file}|${f.match}`;
+const scopedInclude = (include, projectName) => include.flatMap((glob) => {
+  const [head, ...rest] = glob.split("/");
+  if (head === projectName) return [glob];
+  if (head === "*" || head === "**") return [[projectName, ...rest].join("/")];
+  return [];
+});
+function scanProject(root, projectName) {
+  const findings = [];
+  const excused = [];
+  const coveredRules = [];
+  const uncoveredRules = [];
+  const scanned = /* @__PURE__ */ new Set();
+  const excusedKeys = new Set(KNOWN_EXCEPTIONS.map(findingKey));
+  for (const rule of RULES) {
+    if (rule.enforcement.kind !== "source") continue;
+    const include = scopedInclude(rule.enforcement.check.include, projectName);
+    if (include.length === 0) {
+      uncoveredRules.push(rule.id);
+      continue;
+    }
+    coveredRules.push(rule.id);
+    const check = { ...rule.enforcement.check, include };
+    for (const abs of matchedFiles(check, root)) scanned.add(abs);
+    for (const finding of runSourceCheck(check, root)) {
+      const f = { ...finding, rule: rule.id };
+      (excusedKeys.has(findingKey(f)) ? excused : findings).push(f);
+    }
+  }
+  return { findings, excused, coveredRules, uncoveredRules, scannedFiles: scanned.size };
+}
+export {
+  KNOWN_EXCEPTIONS,
+  corpusFindings,
+  findingKey,
+  scanProject
+};

package/dist/projectDoc.js

@@ -0,0 +1,83 @@
+const exceptionLines = (r, indent) => (r.exceptions ?? []).map(
+  (ex) => `${indent}- waived in \`${ex.project}\`: ${ex.decision} (recorded: \`${ex.recordedIn}\`)`
+);
+function spliceBlock(doc, marker, body) {
+  const begin = `<!-- craft:begin ${marker} -->`;
+  const end = `<!-- craft:end ${marker} -->`;
+  const from = doc.indexOf(begin);
+  if (from === -1) throw new Error(`marker "craft:begin ${marker}" not found`);
+  const to = doc.indexOf(end, from);
+  if (to === -1) throw new Error(`marker "craft:end ${marker}" not found`);
+  return doc.slice(0, from + begin.length) + "\n" + body + "\n" + doc.slice(to);
+}
+function renderClaudeMdBlock(rules, { compact = true } = {}) {
+  const pipeline = rules.filter((r) => r.scope.kind === "pipeline").sort((a, b) => a.id.localeCompare(b.id));
+  const of = (tier) => pipeline.filter((r) => r.tier === tier);
+  const isWaived = (r) => (r.exceptions ?? []).length > 0;
+  const section = (heading, body) => body.length === 0 ? [] : [...heading, ``, ...body, ``];
+  const full = (r) => [`- ${r.claim} (\`${r.id}\`)`, ...exceptionLines(r, "  ")].join("\n");
+  const compacted = (rs, label) => {
+    if (rs.length === 0) return [];
+    if (!compact) return rs.map(full);
+    const waived = rs.filter(isWaived);
+    const plain = rs.filter((r) => !isWaived(r));
+    return [
+      ...waived.map(full),
+      ...waived.length && plain.length ? [``] : [],
+      ...plain.length ? [
+        // Wording is load-bearing and was wrong in review twice over. "further"
+        // dangles in a tier with no waived rules above it (process has none).
+        // And the lookup recipe must key on what the reader HOLDS - an id -
+        // not on the heading text: renderPipelineBlock emits `### <claim>`, so
+        // the id appears only in the `Rule id:` line two lines below. Naming
+        // the wrong token would send every lookup into a 139 KB scan, which is
+        // the one thing this compaction cannot afford to get wrong.
+        `${plain.length} more ${label} rule${plain.length === 1 ? "" : "s"} bind${plain.length === 1 ? "s" : ""} this work, listed by id below. To read one, search HOW_I_BUILD_VIDEOS.md for its id in a \`Rule id:\` line - the headings there are the claims themselves, so the id is not a heading. That is the only doc carrying each rule's why and provenance; the per-stage sheets under \`docs/rules/stages/\` carry the claims, scoped by stage. Every id here is a rule you are accountable to, not a suggestion.`,
+        ``,
+        plain.map((r) => `\`${r.id}\``).join(", ")
+      ] : []
+    ];
+  };
+  return [
+    `<!-- This block is generated from packages/video-craft/src/rules/. Do not edit it here. -->`,
+    ``,
+    ...section(
+      [
+        `### Gates - if you remember nothing else`,
+        ``,
+        `Each line below has cost a rebuild round. Every one is settled by running something, not by reading the diff: run the check.`
+      ],
+      of("gate").map(
+        (r) => [`- ${r.claim} (\`${r.id}\`)`, `  - verify: ${r.verify}`, ...exceptionLines(r, "  ")].join("\n")
+      )
+    ),
+    ...section([`### Craft rules`], compacted(of("craft"), "craft")),
+    ...section([`### Process rules`], compacted(of("process"), "process"))
+  ].join("\n").trimEnd();
+}
+function renderPipelineBlock(rules) {
+  const pipeline = rules.filter((r) => r.scope.kind === "pipeline").sort((a, b) => a.id.localeCompare(b.id));
+  return [
+    `<!-- This block is generated from packages/video-craft/src/rules/. Do not edit it here. -->`,
+    ``,
+    ...pipeline.flatMap((r) => [
+      `### ${r.claim}`,
+      ``,
+      r.why,
+      ``,
+      // The tier is restated here rather than only in the CLAUDE.md projection
+      // so the reference doc and the injected block cannot disagree about how
+      // much a rule weighs - a reader who arrives via a rule id from a build
+      // note lands here, not there.
+      `Learned from \`${r.learnedFrom}\`. Rule id: \`${r.id}\`. Tier: ${r.tier}.`,
+      ...r.verify ? [``, `Verify: ${r.verify}`] : [],
+      ...(r.exceptions ?? []).length > 0 ? [``, ...exceptionLines(r, "")] : [],
+      ``
+    ])
+  ].join("\n").trimEnd();
+}
+export {
+  renderClaudeMdBlock,
+  renderPipelineBlock,
+  spliceBlock
+};

package/dist/projectDocSync.js

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderClaudeMdBlock, renderPipelineBlock, spliceBlock } from "./projectDoc.js";
+import { RULES } from "./registry.js";
+function syncProjectedDocs(targetRoot, opts) {
+  const updated = [];
+  const skipped = [];
+  const claudePath = join(targetRoot, "CLAUDE.md");
+  if (!existsSync(claudePath)) {
+    throw new Error(
+      `CLAUDE.md does not exist in ${targetRoot} - rules:sync splices into existing files and never creates them. Create CLAUDE.md with the craft markers (<!-- craft:begin claude-md --> / <!-- craft:end claude-md -->) first.`
+    );
+  }
+  const howPath = join(targetRoot, "HOW_I_BUILD_VIDEOS.md");
+  const hasHow = existsSync(howPath);
+  writeFileSync(
+    claudePath,
+    spliceBlock(readFileSync(claudePath, "utf8"), "claude-md", renderClaudeMdBlock(RULES, { compact: hasHow })),
+    "utf8"
+  );
+  updated.push("CLAUDE.md");
+  if (opts?.claudeMdOnly) {
+    return { updated, skipped };
+  }
+  if (!hasHow) {
+    skipped.push({ file: "HOW_I_BUILD_VIDEOS.md", reason: "not present in target" });
+  } else {
+    writeFileSync(
+      howPath,
+      spliceBlock(readFileSync(howPath, "utf8"), "pipeline", renderPipelineBlock(RULES)),
+      "utf8"
+    );
+    updated.push("HOW_I_BUILD_VIDEOS.md");
+  }
+  return { updated, skipped };
+}
+export {
+  syncProjectedDocs
+};

package/dist/projectMeta.js

@@ -0,0 +1,37 @@
+import { COMPONENT_VARIANTS } from "./variants.js";
+const forComponent = (rules, slug, field) => rules.filter((r) => r.scope.kind === "component" && r.scope.slug === slug && r.scope.field === field).sort((a, b) => a.id.localeCompare(b.id)).map((r) => r.claim);
+function componentSlugs(rules) {
+  const slugs = /* @__PURE__ */ new Set();
+  for (const rule of rules) {
+    if (rule.scope.kind === "component") slugs.add(rule.scope.slug);
+  }
+  return [...slugs].sort();
+}
+const lit = (s) => JSON.stringify(s);
+function renderComponentMeta(rules, slug) {
+  const whenToUse = forComponent(rules, slug, "whenToUse")[0] ?? "";
+  const whenNotToUse = forComponent(rules, slug, "whenNotToUse")[0] ?? "";
+  const gotchas = forComponent(rules, slug, "gotcha");
+  const name = slug.replace(/-([a-z])/g, (_, c) => c.toUpperCase()) + "Meta";
+  const variants = COMPONENT_VARIANTS[slug] ?? [];
+  return [
+    `// GENERATED FILE - DO NOT EDIT.`,
+    `// Source of truth: packages/video-craft/src/rules/. Regenerate with:`,
+    `//   npx tsx packages/video-craft/scripts/generate.ts`,
+    `// Edits here are reverted by the drift test in packages/video-craft/src/drift.test.ts.`,
+    ``,
+    `export const ${name} = {`,
+    `  whenToUse: ${lit(whenToUse)},`,
+    `  whenNotToUse: ${lit(whenNotToUse)},`,
+    `  gotchas: [`,
+    ...gotchas.map((g) => `    ${lit(g)},`),
+    `  ],`,
+    `  variants: [${variants.map((v) => lit(v)).join(", ")}] as string[],`,
+    `};`,
+    ``
+  ].join("\n");
+}
+export {
+  componentSlugs,
+  renderComponentMeta
+};

package/dist/provenance.js

@@ -0,0 +1,41 @@
+const UPSTREAM_PROVENANCE_ROOTS = [
+  // Video projects that stayed in remotion-videos.
+  "revola-video",
+  "expanse-video",
+  "qse-video",
+  "act854-video",
+  "datapeak-video",
+  "klaviyo-segments-video",
+  "qpa-video",
+  "reverence-video",
+  "enjamb-teaser",
+  "workday-harness-video",
+  "rcp-fund7-video",
+  // Pre-split working documents that stayed with the video projects.
+  "claude-sessions-digest"
+];
+const UPSTREAM_ISSUE_PREFIX = "remotion-videos-";
+function isUpstreamIssue(id) {
+  return id.startsWith(UPSTREAM_ISSUE_PREFIX);
+}
+function isUpstreamProvenance(path) {
+  return UPSTREAM_PROVENANCE_ROOTS.some(
+    (root) => path === root || path.startsWith(`${root}/`)
+  );
+}
+function upstreamCitationError(path) {
+  if (path.includes("\\")) return "contains a backslash";
+  const segments = path.split("/");
+  if (segments.some((s) => s === "")) return "has an empty path segment";
+  if (segments.some((s) => s === "." || s === "..")) {
+    return "contains a relative segment";
+  }
+  return void 0;
+}
+export {
+  UPSTREAM_ISSUE_PREFIX,
+  UPSTREAM_PROVENANCE_ROOTS,
+  isUpstreamIssue,
+  isUpstreamProvenance,
+  upstreamCitationError
+};

package/dist/radar-check-ids.json

@@ -0,0 +1,34 @@
+[
+  "alignment-group",
+  "attachment-offset",
+  "band-breach",
+  "blank-region-hold",
+  "brand-provenance",
+  "brief-structure",
+  "case-system",
+  "contract-satisfiable",
+  "copy-tracks-the-read",
+  "crowding-legibility",
+  "dead-frame-at-cut",
+  "edge-touch",
+  "fade-stack-at-cut",
+  "frame-count",
+  "group-member-count",
+  "hero-regression",
+  "hero-size",
+  "loudness",
+  "occlusion",
+  "placeholder-content",
+  "rebanding-conflict",
+  "scene-serves-thesis",
+  "seam-continuity",
+  "seam-fidelity",
+  "sibling-overlap",
+  "snap",
+  "static-hold",
+  "tag-coverage",
+  "text-fit",
+  "thesis-fidelity",
+  "viz-declared",
+  "vo-element-sync"
+]