@devinilabs/reelstack 1.3.1 → 1.4.0

package/cli/lint.js

@@ -2,14 +2,14 @@
  * `reelstack lint <file> [--critique]` — static-analysis pass over a reel composition.
  *
  * Reports (default mode — list of violations with line numbers):
- *   - SAFE_ZONE_BREACH:           element y-coords overlap reserved bands.
- *   - MOTION_FLOOR_VIOLATION:     scenes with too few simultaneous animation layers.
- *   - HERO_TEXT_OVERFLOW:         counter or hero text wider than canvas - 64px gutter.
+ *   - SAFE_ZONE_BREACH:           (warn) element y-coords overlap reserved bands — decorative elements OK with data-reelstack-safe-override.
+ *   - MOTION_FLOOR_VIOLATION:     (warn) scenes with too few simultaneous animation layers — nested-motion components produce false positives.
+ *   - HERO_TEXT_OVERFLOW:         (warn) counter or hero text wider than canvas - 64px gutter.
  *   - AUDIO_NOT_LOCKED:           file imports <Audio> but defines no BEAT const block.
- *   - HAND_DRAWN_BRAND:           inline <svg> longer than 800 chars in a logo-sized element.
+ *   - HAND_DRAWN_BRAND:           (warn) inline <svg> longer than 800 chars — intentional brand SVGs are fine.
  *   - ACCENT_ALLOWLIST_VIOLATION: (warn) hex color outside the resolved family's ALLOWED_ACCENTS list — intentional sponsor/custom accents are fine, the rule catches accidental token typos.
- *   - SPACING_NON_GRID:           padding/margin/gap not on the 4px grid.
- *   - MISSING_REDUCE_MOTION:      component imports useCurrentFrame but lacks a `reduceMotion` prop.
+ *   - SPACING_NON_GRID:           (warn) padding/margin/gap not on the 4px grid — optical-spacing exceptions OK.
+ *   - MISSING_REDUCE_MOTION:      (warn) component imports useCurrentFrame but lacks a `reduceMotion` prop — accessibility hygiene, not render-blocking.
  *   - GENERIC_PLACEHOLDER:        "Lorem ipsum", "John Doe", "Acme Corp" — leftover stub copy.
  *   - HOOK_LATENCY:               earliest <Sequence> starts after frame 30 — first second of reel is empty.
  *   - CTA_MISSING:                (warn) no CTA component or CTA keyword (follow/subscribe/etc.) found anywhere.
@@ -86,14 +86,14 @@ function lint(file) {
     if (topMatch) {
       const y = Number(topMatch[1]);
       if (y >= 0 && y < TOP_SAFE && !line.includes("data-reelstack-safe-override")) {
-        violations.push({ line: i + 1, code: "SAFE_ZONE_BREACH", msg: `top: ${y} overlaps top reserved band (0..${TOP_SAFE}).` });
+        violations.push({ line: i + 1, code: "SAFE_ZONE_BREACH", severity: "warning", msg: `top: ${y} overlaps top reserved band (0..${TOP_SAFE}). Add data-reelstack-safe-override if decorative.` });
       }
     }
     const bottomMatch = line.match(/bottom:\s*(-?\d+)\s*,?/);
     if (bottomMatch) {
       const b = Number(bottomMatch[1]);
       if (b >= 0 && b < BOTTOM_SAFE && !line.includes("data-reelstack-safe-override")) {
-        violations.push({ line: i + 1, code: "SAFE_ZONE_BREACH", msg: `bottom: ${b} overlaps bottom reserved band (0..${BOTTOM_SAFE}).` });
+        violations.push({ line: i + 1, code: "SAFE_ZONE_BREACH", severity: "warning", msg: `bottom: ${b} overlaps bottom reserved band (0..${BOTTOM_SAFE}). Add data-reelstack-safe-override if decorative.` });
       }
     }
   });
@@ -114,7 +114,8 @@ function lint(file) {
       violations.push({
         line: lineNum,
         code: "HAND_DRAWN_BRAND",
-        msg: `Inline <svg> is ${svg.length} chars — likely hand-drawn. Use /reelstack-icons to pull a real brand SVG.`,
+        severity: "warning",
+        msg: `Inline <svg> is ${svg.length} chars — could be hand-drawn. For brand marks, use /reelstack-icons; intentional inline brand SVGs are fine.`,
       });
     }
   }
@@ -197,7 +198,8 @@ function lint(file) {
       violations.push({
         line: lineOf(openIdx),
         code: "MOTION_FLOOR_VIOLATION",
-        msg: `Sequence at frame ${fromValue} has ${motionCalls} motion calls, family rule is ≥3 (≥4 in opener).`,
+        severity: "warning",
+        msg: `Sequence at frame ${fromValue} has ${motionCalls} motion calls, family rule is ≥3 (≥4 in opener). If motion lives in a nested component, this warning is a false positive.`,
       });
     }
 
@@ -219,7 +221,8 @@ function lint(file) {
       violations.push({
         line: i + 1,
         code: "HERO_TEXT_OVERFLOW",
-        msg: `fontSize ${px}px on apparent hero-counter; cap at 256px or wrap with maxWidth=${HERO_TEXT_MAX}.`,
+        severity: "warning",
+        msg: `fontSize ${px}px on apparent hero-counter; verify it fits within ${HERO_TEXT_MAX}px (canvas - 64px gutter) on real devices.`,
       });
     }
   });
@@ -265,7 +268,8 @@ function lint(file) {
         violations.push({
           line: lineOfIdx(idx),
           code: "SPACING_NON_GRID",
-          msg: `${rawProp}: ${val} is off the 4px grid. Round to ${Math.round(val / 4) * 4}.`,
+          severity: "warning",
+          msg: `${rawProp}: ${val} is off the 4px grid. Round to ${Math.round(val / 4) * 4} — or accept the warning if this is intentional optical spacing.`,
         });
       }
     };
@@ -309,7 +313,8 @@ function lint(file) {
             violations.push({
               line: lineOfIdx(mFC.index),
               code: "MISSING_REDUCE_MOTION",
-              msg: `React.FC component uses useCurrentFrame but prop type lacks "reduceMotion". Add reduceMotion?: boolean for accessibility.`,
+              severity: "warning",
+              msg: `React.FC component uses useCurrentFrame but prop type lacks "reduceMotion". Add reduceMotion?: boolean for accessibility (warning — not render-blocking).`,
             });
           }
         }
@@ -317,7 +322,8 @@ function lint(file) {
           violations.push({
             line: 1,
             code: "MISSING_REDUCE_MOTION",
-            msg: `Component uses useCurrentFrame but no reduceMotion prop found anywhere. Add reduceMotion?: boolean.`,
+            severity: "warning",
+            msg: `Component uses useCurrentFrame but no reduceMotion prop found anywhere. Add reduceMotion?: boolean for accessibility (warning — not render-blocking).`,
           });
         }
       }

package/cli/scaffold.js

@@ -1,8 +1,20 @@
 /**
- * `reelstack scaffold` — copies a family template into the buyer's
- * src/<Name>Reel.tsx, substitutes preset metadata (palette, BEATs,
- * frame count, copy), and patches src/Root.tsx to register the new
- * composition.
+ * `reelstack scaffold` — produces a production-quality reel scaffold by
+ * preferring the reference reel (cloned from a real Devini Labs production
+ * reel) over the generic family template. Substitutes preset metadata,
+ * does a mechanical export rename, strips the reference header, and
+ * patches src/Root.tsx to register the new composition.
+ *
+ * v1.4 flow:
+ *   1. Resolve reference reel for family + preset.
+ *   2. If reference exists (and --minimal not passed):
+ *      - Read reference verbatim (2000-3800 lines of production motion).
+ *      - Strip the reference header JSDoc.
+ *      - Rename `export const <PresetClass>Reel` → `export const <Name>Reel`.
+ *      - Inject a /** SCAFFOLDED FROM: <ref> *\/ marker.
+ *   3. Else fall back to generic template + placeholder substitution.
+ *   4. Write to src/<Name>Reel.tsx.
+ *   5. Register in src/Root.tsx.
  */
 const fs = require("node:fs");
 const path = require("node:path");
@@ -127,6 +139,77 @@ function injectReferenceComment(tsx, refPath) {
   return tsx.slice(0, after) + block + tsx.slice(after);
 }
 
+/**
+ * v1.4: Strip the reference reel's leading JSDoc header block. References
+ * start with `/** REFERENCE — <ClassName>  (Family: <fam>) ... *\/`.
+ * When the reference becomes a buyer's reel, that header doesn't apply.
+ */
+function stripReferenceHeader(tsx) {
+  if (!tsx.startsWith("/**")) return tsx;
+  if (!/^\/\*\*\s*\n\s*\*\s*REFERENCE\b/.test(tsx)) return tsx;
+  const end = tsx.indexOf("*/");
+  if (end === -1) return tsx;
+  // Skip the closing `*/` plus any trailing newline.
+  let cut = end + 2;
+  while (tsx[cut] === "\n") cut++;
+  return tsx.slice(cut);
+}
+
+/**
+ * v1.4: Mechanical export rename — replace `export const <X>Reel` with
+ * `export const <NewName>Reel`. The reference reel has the production
+ * class name (e.g. GraphifyReel); we rewrite it to the buyer's chosen
+ * name (e.g. MyLaunchReel). Returns the rewritten source and the original
+ * class name (so we can announce what changed in the scaffold summary).
+ */
+function renameReelExport(tsx, newName) {
+  const m = tsx.match(/export\s+const\s+(\w+Reel)\b/);
+  if (!m) return { tsx, originalClassName: null };
+  const originalClassName = m[1];
+  const targetClassName = `${newName}Reel`;
+  if (originalClassName === targetClassName) {
+    return { tsx, originalClassName };
+  }
+  // Replace ALL occurrences of the original class name with the new one.
+  // This catches the export, any internal references (helper components
+  // named after the reel, JSDoc, comments), and keeps the file coherent.
+  const re = new RegExp(`\\b${originalClassName}\\b`, "g");
+  return {
+    tsx: tsx.replace(re, targetClassName),
+    originalClassName,
+  };
+}
+
+/**
+ * v1.4: Inject a top-of-file marker so the buyer (and Claude on subsequent
+ * iteration) knows this file was scaffolded from a reference reel and the
+ * canonical hooks/CTAs are Devini Labs strings that should be replaced.
+ */
+function injectScaffoldHeader({ name, family, preset, refPath, originalClassName }) {
+  const rel = path.relative(REELSTACK_PKG, refPath) || refPath;
+  return `/**
+ * ${name}Reel — scaffolded by ReelStack v1.4
+ *
+ * Family:    ${family}
+ * Preset:    ${preset}
+ * Source:    ${rel}
+ * Cloned at: ${new Date().toISOString()}
+ *
+ * This file is a faithful clone of the production ${originalClassName || preset + "Reel"}
+ * — same motion vocabulary, palette, and scene structure. Canonical Devini
+ * Labs hook / sub / CTA strings are still in place. REPLACE them with your
+ * own content before publishing. The motion floor (≥4 layers in opener,
+ * ≥3 in anchor scenes) is preserved.
+ *
+ * Next steps:
+ *   1. Replace the hero hook, sub, and CTA copy with your reel's narrative.
+ *   2. Run \`/reelstack-beats <vo.wav>\` to lock motion to your voiceover.
+ *   3. Look for REFERENCE-STRIP markers and swap in your assets.
+ *   4. Run \`/reelstack-lint src/${name}Reel.tsx\` and address any errors.
+ */
+`;
+}
+
 function patchRoot(rootPath, name, durationFrames) {
   if (!fs.existsSync(rootPath)) {
     fail(`src/Root.tsx not found at ${rootPath}. Skipping registration.`);
@@ -193,15 +276,35 @@ async function run(argv, opts = {}) {
   }
 
   const presetMeta = loadPreset(family, preset);
-  const template = loadTemplate(family);
-  let tsx = substitute(template, presetMeta, name);
-
-  // v1.1.1+ — resolve the reference reel for this preset (or buyer's override
-  // via --reference=<preset>) so a `/** REFERENCE: <path> */` comment can be
-  // injected into the scaffold, and a hint surfaced after Studio.
   const ref = resolveReference(family, preset, args.reference);
-  if (ref) {
-    tsx = injectReferenceComment(tsx, ref.path);
+
+  // v1.4 flow: prefer reference reel (production-grade DNA) over the generic
+  // template. Buyer can opt into the generic template via --minimal.
+  let tsx;
+  let scaffoldedFromReference = false;
+  let originalClassName = null;
+
+  if (ref && !args.minimal) {
+    let refSrc = fs.readFileSync(ref.path, "utf8");
+    refSrc = stripReferenceHeader(refSrc);
+    const renamed = renameReelExport(refSrc, name);
+    refSrc = renamed.tsx;
+    originalClassName = renamed.originalClassName;
+    const header = injectScaffoldHeader({
+      name,
+      family,
+      preset,
+      refPath: ref.path,
+      originalClassName,
+    });
+    tsx = header + refSrc;
+    scaffoldedFromReference = true;
+  } else {
+    const template = loadTemplate(family);
+    tsx = substitute(template, presetMeta, name);
+    if (ref) {
+      tsx = injectReferenceComment(tsx, ref.path);
+    }
   }
 
   const outFile = path.join(cwd, "src", `${name}Reel.tsx`);
@@ -225,13 +328,18 @@ async function run(argv, opts = {}) {
   console.log(c.gray(`  Family:        `) + family);
   console.log(c.gray(`  Preset:        `) + `${preset} (from ${presetMeta.source})`);
   console.log(c.gray(`  Frame count:   `) + `${presetMeta.durationFrames} (${(presetMeta.durationFrames / 30).toFixed(1)}s @ 30fps)`);
+  console.log(c.gray(`  Source:        `) + (scaffoldedFromReference
+    ? `reference reel (${path.basename(ref.path)})${originalClassName ? ` — renamed ${originalClassName} → ${name}Reel` : ""}`
+    : `generic template`));
   console.log(c.gray(`  Output:        `) + path.relative(cwd, outFile));
   console.log("");
   console.log(c.cyan("→ ") + `Open Remotion Studio with ${c.bold("npm run dev")} and select "${name}Reel" from the comp list.`);
-  if (ref) {
-    console.log(c.cyan("ℹ ") + `Reference reel available: ${ref.path}`);
-    console.log(c.gray("  Claude will study this reel when iterating on your scaffold. Open it"));
-    console.log(c.gray("  yourself to learn the family's motion vocabulary."));
+  if (scaffoldedFromReference) {
+    console.log(c.cyan("ℹ ") + `Scaffolded from production reference. Canonical Devini Labs hook/sub/CTA copy is in the file —`);
+    console.log(c.gray("  replace those strings with your own narrative before publishing. The motion, palette, and scene"));
+    console.log(c.gray("  structure are production-grade and preserved verbatim."));
+  } else if (ref) {
+    console.log(c.cyan("ℹ ") + `Reference reel available for study: ${ref.path}`);
   }
   console.log("");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinilabs/reelstack",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Premium 9:16 Reel OS for Remotion. 5 cinematic style families, 22 production-tested presets, audio-locked motion, IG-safe by default. v1.1+ bakes in leonxlnx/taste-skill design discipline + huashu-design productivity patterns.",
   "keywords": [
     "remotion",

package/reference/dark/claudedispatch.tsx

@@ -2424,7 +2424,7 @@ export const ClaudeDispatchReel: React.FC = () => {
 
   return (
     <AbsoluteFill style={{ backgroundColor: C.bg, fontFamily: FONT }}>
-      {/* REFERENCE-STRIP: <Audio> tag removed — bring your own voiceover */}
+      {/* REFERENCE-STRIP: voiceover tag removed — bring your own voiceover */}
 
       <Background frame={frame} fps={fps} />