@devinilabs/reelstack 1.3.2 → 1.4.0

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.2",
+  "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",