@devinilabs/reelstack 1.3.2 → 1.4.1

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/docs/buyers-guide.md

@@ -145,7 +145,7 @@ Common moves:
 - **Pull a brand logo.** Run `/reelstack-icons logos:react` (or any Iconify ID).
 - **Capture a product UI.** Run `/reelstack-capture https://example.com`.
 
-**Reference reels.** ReelStack ships 12 reference reels at `~/.reelstack/reference/<family>/<preset>.tsx`. After scaffolding, your AI agent (Claude Code, etc.) can study these to give better iteration advice. To force a specific reference, pass `--reference=<preset>` to the scaffold command. See `~/.reelstack/docs/design-discipline.md` for the full catalog.
+**Reference reels.** As of v1.4, ReelStack ships **22 reference reels** at `~/.reelstack/reference/<family>/<preset>.tsx` — one per preset. The scaffolder copies the matching reference directly into your `src/<Name>Reel.tsx`, so every scaffold is production-grade by default. To force a specific reference (e.g., use ClaudeWatchReel's structure even when scaffolding Graphify), pass `--reference=<preset>`. To opt into the legacy thin-template flow, pass `--minimal`. See `~/.reelstack/docs/design-discipline.md` for the full catalog.
 
 ## 7. Validate before posting
 

package/docs/family-galleries/dark.md

@@ -84,7 +84,7 @@ Dark Cinematic inherits from **leonxlnx/taste-skill-brutalist** (Tactical Teleme
 - **WCAG AA+ contrast** documented inline in `palette.ts` (fg: 18.7:1, fgSoft: 13.4:1, fgMuted: 6.4:1).
 - **Optional hazard-red `#E61919` accent** — pull from the Brutalist tactical-telemetry palette for "hold / abort / kill switch" callouts.
 
-## Reference reels (v1.1.1+)
+## Reference reels (v1.4+ — every preset has one)
 
 3 reference reels ship for this family at `~/.reelstack/reference/dark/<preset>.tsx`:
 

package/docs/family-galleries/forbidden.md

@@ -69,7 +69,7 @@ Forbidden inherits from **leonxlnx/taste-skill-brutalist** (Swiss Industrial Pri
 - **WCAG AA+ contrast** documented inline in `palette.ts` (ink: 17.6:1, inkSoft: 13.0:1, inkMuted: 6.8:1).
 - **No-border-radius variant** — pass `radius={0}` to `<GlassCard />` for the Brutalist Swiss "rigid grid" look.
 
-## Reference reels (v1.1.1+)
+## Reference reels (v1.4+ — every preset has one)
 
 1 reference reel ships for this family at `~/.reelstack/reference/forbidden/<preset>.tsx`:
 

package/docs/family-galleries/glass.md

@@ -87,7 +87,7 @@ Glass Iridescent inherits from **leonxlnx/taste-skill-soft** + **leonxlnx/taste-
 - **`ALLOWED_ACCENTS`** export — lint flags any color outside `[iriCyan, iriViolet, iriRose, iriGold, violetPill, tealPill, ink]` as a hue bleed.
 - **WCAG AA+ contrast** documented inline in `palette.ts` (ink: 16.8:1, inkSoft: 12.4:1, etc.).
 
-## Reference reels (v1.1.1+)
+## Reference reels (v1.4+ — every preset has one)
 
 3 reference reels ship for this family at `~/.reelstack/reference/glass/<preset>.tsx`:
 

package/docs/family-galleries/paper.md

@@ -71,7 +71,7 @@ Cream Paper inherits from **leonxlnx/taste-skill-minimalist** + **leonxlnx/taste
 - **WCAG AA+ contrast** documented inline in `palette.ts` (heading: 15.6:1, body: 11.6:1, muted: 4.8:1).
 - **4-px grid constants** re-exported from the family entrypoint: `import { palette, GRID, GRID_2, GRID_4, … } from "@devinilabs/reelstack/families/paper"`.
 
-## Reference reels (v1.1.1+)
+## Reference reels (v1.4+ — every preset has one)
 
 3 reference reels ship for this family at `~/.reelstack/reference/paper/<preset>.tsx`:
 

package/docs/family-galleries/warm.md

@@ -76,7 +76,7 @@ Warm Signature inherits from **leonxlnx/taste-skill-minimalist** + **leonxlnx/ta
 - **WCAG AA+ contrast** documented inline in `palette.ts` (fg: 19.6:1, fgSoft: 13.9:1, fgMuted: 7.7:1).
 - **Diffused warm shadow stack** — Soft variant's multi-layer `paperShadow`-style stacks adapted to warm-zinc backgrounds for premium card depth.
 
-## Reference reels (v1.1.1+)
+## Reference reels (v1.4+ — every preset has one)
 
 2 reference reels ship for this family at `~/.reelstack/reference/warm/<preset>.tsx`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinilabs/reelstack",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "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",