@officexapp/vidfarm-devcli 0.21.27 → 0.21.29

package/dist/src/devcli/sticker-pack.js

@@ -0,0 +1,396 @@
+// Sticker-PACK segmentation: turn ONE keyed plate holding MANY items into many
+// individually-cropped transparent stickers.
+//
+// Why this exists: `vidfarm cutout` makes ONE sticker per AI generation, and
+// `vidfarm mask --crop x,y,w,h` makes one per hand-measured rectangle. Neither
+// scales to "give me a sticker pack" — the standard, cheapest move, which is:
+// generate a SINGLE image containing every graphic you need, laid out on a flat
+// chroma plate, then cut each item out locally for $0. Measuring a dozen crop
+// rects by hand is the only hard part of that loop, so this module does it
+// automatically: it reads the keyed plate's ALPHA channel and finds the
+// connected islands of opaque pixels — one island per item — and reports their
+// bounding boxes. No AI, no vision call, no network: ffmpeg + a few typed
+// arrays.
+//
+// Deliberately size-agnostic: an item can be a tiny icon or an entire landscape
+// backdrop filling most of the plate. The only filter is `minAreaPct` (drop
+// speckle/JPEG noise), never a maximum — a "sticker" here means "a transparent
+// element you can place and animate", not "a small thing".
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolveFfmpeg } from "../services/clip-curation/ffmpeg.js";
+import { probeImageDimensions } from "./greenscreen-local.js";
+/** The plates we'll auto-pick from, best-first, with the color words that rule
+ *  each one out. Mirrors GREENSCREEN_PRESETS keys so `--preset` still applies. */
+export const PLATE_CANDIDATES = [
+    {
+        preset: "green",
+        keyColor: "#00FF00",
+        collides: ["green", "lime", "emerald", "mint", "olive", "forest", "jade", "grass", "leaf", "leaves", "foliage", "plant", "tree", "frog", "cactus", "avocado", "money", "dollar", "eco", "recycle", "matcha", "seaweed", "moss", "teal", "turquoise"]
+    },
+    {
+        preset: "magenta",
+        keyColor: "#FF00FF",
+        collides: ["magenta", "pink", "fuchsia", "fuscia", "violet", "purple", "lilac", "lavender", "orchid", "rose", "berry", "candy", "barbie", "neon pink"]
+    },
+    {
+        preset: "blue",
+        keyColor: "#0047BB",
+        collides: ["blue", "navy", "azure", "cobalt", "indigo", "sky", "ocean", "sea", "water", "denim", "cyan", "teal", "turquoise", "police", "sapphire"]
+    },
+    {
+        preset: "black",
+        keyColor: "#000000",
+        collides: ["black", "dark", "night", "shadow", "charcoal", "noir", "coal", "ink", "silhouette", "outline"]
+    },
+    {
+        preset: "white",
+        keyColor: "#FFFFFF",
+        collides: ["white", "snow", "cloud", "paper", "ivory", "cream", "milk", "ghost", "bone", "eggshell"]
+    }
+];
+/**
+ * Choose a chroma plate that the subject can't collide with. Scans the subject
+ * text (theme + item names + style notes) for each candidate's color words and
+ * returns the first plate with no hit. Falls back to green with `reason` set
+ * when EVERY plate collides, so the caller can warn instead of silently keying
+ * holes in the art.
+ */
+export function pickPlateColor(subjectText) {
+    const haystack = ` ${subjectText.toLowerCase().replace(/[^a-z0-9]+/g, " ")} `;
+    const hits = (c) => c.collides.filter((word) => haystack.includes(` ${word} `));
+    const rejections = [];
+    for (const candidate of PLATE_CANDIDATES) {
+        const collisions = hits(candidate);
+        if (!collisions.length) {
+            return {
+                preset: candidate.preset,
+                keyColor: candidate.keyColor,
+                moved: candidate.preset !== "green",
+                reason: rejections.length ? `the subject mentions ${rejections.join(", ")}` : null
+            };
+        }
+        rejections.push(`${collisions.join("/")} (rules out ${candidate.preset})`);
+    }
+    return {
+        preset: "green",
+        keyColor: "#00FF00",
+        moved: false,
+        reason: `every standard plate collides with the subject (${rejections.join("; ")}) — key by hand with --key-color, or split the pack into two sheets`
+    };
+}
+/**
+ * Detect the plate color of an EXISTING sheet by sampling its four corners.
+ * A sticker sheet always has plate at the corners (items are spaced inside), so
+ * when all four agree within `tolerance` that color IS the plate — which means
+ * a user can hand back a red/blue/purple sheet from a web generator and the cut
+ * still works without them knowing what a chroma key is. Returns null when the
+ * corners disagree (a busy or full-bleed image → let the caller fall back).
+ */
+export async function detectPlateColor(sourcePath, opts = {}) {
+    if (!existsSync(sourcePath))
+        throw new Error(`No such source file: ${sourcePath}`);
+    const dims = await probeImageDimensions(sourcePath);
+    if (!dims)
+        return null;
+    const ffmpeg = await resolveFfmpeg();
+    // An 8x8 patch inset 1% from each corner: inside the plate, outside any border
+    // artifact or JPEG ringing at the very edge.
+    const inset = Math.max(2, Math.round(Math.min(dims.width, dims.height) * 0.01));
+    const patch = 8;
+    const corners = [
+        [inset, inset],
+        [Math.max(0, dims.width - inset - patch), inset],
+        [inset, Math.max(0, dims.height - inset - patch)],
+        [Math.max(0, dims.width - inset - patch), Math.max(0, dims.height - inset - patch)]
+    ];
+    const samples = [];
+    for (const [x, y] of corners) {
+        const raw = await new Promise((resolve, reject) => {
+            const child = spawn(ffmpeg, [
+                "-hide_banner", "-v", "error",
+                "-i", sourcePath,
+                "-frames:v", "1",
+                "-vf", `crop=${patch}:${patch}:${x}:${y},scale=1:1:flags=area`,
+                "-f", "rawvideo", "-pix_fmt", "rgb24",
+                "-"
+            ], { stdio: ["ignore", "pipe", "ignore"] });
+            const chunks = [];
+            child.stdout.on("data", (d) => chunks.push(d));
+            child.on("error", reject);
+            child.on("close", () => resolve(Buffer.concat(chunks)));
+        });
+        if (raw.length < 3)
+            return null;
+        samples.push([raw[0], raw[1], raw[2]]);
+    }
+    const tolerance = opts.tolerance ?? 24;
+    const avg = [0, 1, 2].map((i) => Math.round(samples.reduce((s, c) => s + c[i], 0) / samples.length));
+    const spread = Math.max(...samples.map((s) => Math.max(Math.abs(s[0] - avg[0]), Math.abs(s[1] - avg[1]), Math.abs(s[2] - avg[2]))));
+    if (spread > tolerance)
+        return null; // corners disagree → not a uniform plate
+    const hex = `#${avg.map((v) => v.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
+    return { hex, rgb: avg };
+}
+/** Read a still's alpha plane as raw 8-bit luma at a given size (bundle-safe:
+ *  ffmpeg's `alphaextract` writes alpha as luma; rawvideo skips any decoding on
+ *  our side). Returns exactly width*height bytes. */
+async function readAlphaPlane(sourcePath, width, height) {
+    const ffmpeg = await resolveFfmpeg();
+    const args = [
+        "-hide_banner", "-v", "error",
+        "-i", sourcePath,
+        "-frames:v", "1",
+        "-vf", `alphaextract,scale=${width}:${height}:flags=area`,
+        "-f", "rawvideo", "-pix_fmt", "gray",
+        "-"
+    ];
+    return new Promise((resolve, reject) => {
+        const child = spawn(ffmpeg, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const chunks = [];
+        let stderr = "";
+        child.stdout.on("data", (d) => chunks.push(d));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const buf = Buffer.concat(chunks);
+            if (code !== 0 || buf.length < width * height) {
+                reject(new Error(`Couldn't read the plate's alpha channel (ffmpeg exit ${code})${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-2).join(" ")}` : ""}. Is the keyed file really transparent?`));
+                return;
+            }
+            resolve(new Uint8Array(buf.buffer, buf.byteOffset, width * height));
+        });
+    });
+}
+/** Separable max-filter (morphological dilation) with a square radius — used
+ *  only to decide which islands BELONG TOGETHER. Bounding boxes are always
+ *  measured on the undilated mask, so bridging never inflates a sticker. */
+function dilate(mask, w, h, radius) {
+    if (radius <= 0)
+        return mask;
+    const horiz = new Uint8Array(w * h);
+    for (let y = 0; y < h; y++) {
+        const row = y * w;
+        for (let x = 0; x < w; x++) {
+            const from = Math.max(0, x - radius);
+            const to = Math.min(w - 1, x + radius);
+            let hit = 0;
+            for (let i = from; i <= to; i++)
+                if (mask[row + i]) {
+                    hit = 1;
+                    break;
+                }
+            horiz[row + x] = hit;
+        }
+    }
+    const out = new Uint8Array(w * h);
+    for (let x = 0; x < w; x++) {
+        for (let y = 0; y < h; y++) {
+            const from = Math.max(0, y - radius);
+            const to = Math.min(h - 1, y + radius);
+            let hit = 0;
+            for (let i = from; i <= to; i++)
+                if (horiz[i * w + x]) {
+                    hit = 1;
+                    break;
+                }
+            out[y * w + x] = hit;
+        }
+    }
+    return out;
+}
+/**
+ * Find every item on a keyed plate by segmenting its alpha channel into
+ * connected islands of opaque pixels — the automatic replacement for measuring
+ * a dozen `--crop x,y,w,h` rects by hand.
+ *
+ * Two-mask trick: labelling runs on a DILATED mask (so an item's detached
+ * pieces — a floating antenna, a dotted arrow, the dot on an "i" — join into
+ * one island), while each island's bounding box is accumulated from the
+ * ORIGINAL mask, so the reported rect is still the item's true tight box.
+ */
+export async function segmentAlphaComponents(input) {
+    if (!existsSync(input.sourcePath))
+        throw new Error(`No such source file: ${input.sourcePath}`);
+    const dims = await probeImageDimensions(input.sourcePath);
+    if (!dims)
+        throw new Error(`Couldn't read image dimensions for ${input.sourcePath}.`);
+    // Analyse at most ~640px on the long side: segmentation is a layout question,
+    // not a detail one, and this keeps a 4K sheet under a few million ops.
+    const longSide = Math.max(dims.width, dims.height);
+    const scale = longSide > 640 ? 640 / longSide : 1;
+    const sw = Math.max(1, Math.round(dims.width * scale));
+    const sh = Math.max(1, Math.round(dims.height * scale));
+    const alpha = await readAlphaPlane(input.sourcePath, sw, sh);
+    const threshold = Math.min(254, Math.max(0, Math.round(input.alphaThreshold ?? 8)));
+    const mask = new Uint8Array(sw * sh);
+    let opaque = 0;
+    for (let i = 0; i < mask.length; i++) {
+        if (alpha[i] > threshold) {
+            mask[i] = 1;
+            opaque++;
+        }
+    }
+    if (!opaque) {
+        throw new Error("The keyed plate is fully transparent — everything got keyed away. Check --preset/--key-color (does the plate's background really match?) or lower --tolerance.");
+    }
+    const gapPct = input.gapPct ?? 1.2;
+    const radius = Math.max(1, Math.round((gapPct / 100) * Math.min(sw, sh)));
+    const bridged = dilate(mask, sw, sh, radius);
+    // ---- 8-connected labelling over the bridged mask (explicit stack, no recursion)
+    const labels = new Int32Array(sw * sh).fill(0);
+    const stack = new Int32Array(sw * sh);
+    const boxes = [];
+    let next = 0;
+    for (let start = 0; start < bridged.length; start++) {
+        if (!bridged[start] || labels[start])
+            continue;
+        next++;
+        const box = { minX: sw, minY: sh, maxX: -1, maxY: -1, area: 0 };
+        let top = 0;
+        stack[top++] = start;
+        labels[start] = next;
+        while (top > 0) {
+            const p = stack[--top];
+            const py = (p / sw) | 0;
+            const px = p - py * sw;
+            // Measure the box on the ORIGINAL mask only — dilation bridges, never grows.
+            if (mask[p]) {
+                box.area++;
+                if (px < box.minX)
+                    box.minX = px;
+                if (px > box.maxX)
+                    box.maxX = px;
+                if (py < box.minY)
+                    box.minY = py;
+                if (py > box.maxY)
+                    box.maxY = py;
+            }
+            for (let dy = -1; dy <= 1; dy++) {
+                const ny = py + dy;
+                if (ny < 0 || ny >= sh)
+                    continue;
+                for (let dx = -1; dx <= 1; dx++) {
+                    const nx = px + dx;
+                    if (nx < 0 || nx >= sw)
+                        continue;
+                    const q = ny * sw + nx;
+                    if (bridged[q] && !labels[q]) {
+                        labels[q] = next;
+                        stack[top++] = q;
+                    }
+                }
+            }
+        }
+        if (box.maxX >= 0)
+            boxes.push(box);
+    }
+    // ---- Filter speckle, cap, then sort into human reading order ---------------
+    const total = sw * sh;
+    const minAreaPct = input.minAreaPct ?? 0.15;
+    const kept = boxes.filter((b) => (b.area / total) * 100 >= minAreaPct);
+    const rejected = boxes.length - kept.length;
+    const maxItems = Math.max(1, input.maxItems ?? 64);
+    kept.sort((a, b) => b.area - a.area);
+    const capped = kept.slice(0, maxItems);
+    // Reading order: bucket into rows by vertical overlap, then left-to-right.
+    capped.sort((a, b) => a.minY - b.minY || a.minX - b.minX);
+    const rows = [];
+    for (const b of capped) {
+        const row = rows.find((r) => {
+            const rowTop = Math.min(...r.map((x) => x.minY));
+            const rowBottom = Math.max(...r.map((x) => x.maxY));
+            const overlap = Math.min(rowBottom, b.maxY) - Math.max(rowTop, b.minY);
+            return overlap > 0.4 * Math.min(rowBottom - rowTop, b.maxY - b.minY);
+        });
+        if (row)
+            row.push(b);
+        else
+            rows.push([b]);
+    }
+    const ordered = rows.flatMap((r) => r.sort((a, b) => a.minX - b.minX));
+    // ---- Map sample-space boxes back to source pixels --------------------------
+    // One sample pixel of slack on each side covers the downscale's rounding, so a
+    // subject's outermost antialiased edge never gets clipped off.
+    const inv = 1 / scale;
+    const components = ordered.map((b, i) => {
+        const x0 = Math.max(0, Math.floor((b.minX - 1) * inv));
+        const y0 = Math.max(0, Math.floor((b.minY - 1) * inv));
+        const x1 = Math.min(dims.width, Math.ceil((b.maxX + 2) * inv));
+        const y1 = Math.min(dims.height, Math.ceil((b.maxY + 2) * inv));
+        return {
+            index: i + 1,
+            x: x0,
+            y: y0,
+            width: Math.max(1, x1 - x0),
+            height: Math.max(1, y1 - y0),
+            area_pct: Math.round((b.area / total) * 1000) / 10
+        };
+    });
+    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected };
+}
+/**
+ * Re-encode a transparent still as a transparent GIF — the format a lot of
+ * sticker surfaces (chat, forums, Notion, old-school web overlays) still want.
+ * GIF alpha is 1-bit, so semi-transparent antialiased edges have to snap to
+ * either fully-opaque or fully-gone; `alpha_threshold` is where that line falls.
+ * Prefer PNG/WebP for compositions — this is for hand-off to GIF-only surfaces.
+ */
+export async function encodeTransparentGif(sourcePath, outputPath, opts = {}) {
+    const ffmpeg = await resolveFfmpeg();
+    const at = Math.min(255, Math.max(1, Math.round(opts.alphaThreshold ?? 128)));
+    const args = [
+        "-hide_banner", "-v", "error", "-y",
+        "-i", sourcePath,
+        "-filter_complex",
+        `[0:v]split[a][b];[a]palettegen=reserve_transparent=1:transparency_color=ff00ff[p];[b][p]paletteuse=alpha_threshold=${at}`,
+        outputPath
+    ];
+    await new Promise((resolve, reject) => {
+        const child = spawn(ffmpeg, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0 || !existsSync(outputPath)) {
+                reject(new Error(`Transparent GIF encode failed (ffmpeg exit ${code})${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-2).join(" ")}` : ""}.`));
+            }
+            else
+                resolve();
+        });
+    });
+}
+/**
+ * Key-and-encode an ANIMATED transparent GIF from a video clip whose background
+ * is already transparent (a keyed WebM/MOV). Same 1-bit-alpha caveat as the
+ * still encoder; `fps` and `width` exist because GIF is a heavy container and an
+ * animated sticker is usually small and short.
+ */
+export async function encodeTransparentAnimatedGif(sourcePath, outputPath, opts = {}) {
+    const ffmpeg = await resolveFfmpeg();
+    const fps = Math.min(50, Math.max(1, Math.round(opts.fps ?? 15)));
+    const at = Math.min(255, Math.max(1, Math.round(opts.alphaThreshold ?? 128)));
+    const scaleClause = opts.width && opts.width > 0 ? `,scale=${Math.round(opts.width)}:-1:flags=lanczos` : "";
+    const args = [
+        "-hide_banner", "-v", "error", "-y",
+        "-i", sourcePath,
+        "-filter_complex",
+        `[0:v]fps=${fps}${scaleClause},split[a][b];[a]palettegen=reserve_transparent=1:transparency_color=ff00ff[p];[b][p]paletteuse=alpha_threshold=${at}`,
+        "-loop", "0",
+        outputPath
+    ];
+    await new Promise((resolve, reject) => {
+        const child = spawn(ffmpeg, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0 || !existsSync(outputPath)) {
+                reject(new Error(`Animated transparent GIF encode failed (ffmpeg exit ${code})${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-2).join(" ")}` : ""}.`));
+            }
+            else
+                resolve();
+        });
+    });
+}
+//# sourceMappingURL=sticker-pack.js.map

package/dist/src/devcli/storyboard.js

@@ -0,0 +1,243 @@
+// Storyboarding — Vidfarm's wrapper over the STORYBOARD.md plan format.
+//
+// A storyboard is the PLAN for a video before any animation work happens: an
+// ordered set of frames (key moments) plus their narration. It lives at the
+// project root as one markdown file, `STORYBOARD.md`, with an optional companion
+// `SCRIPT.md` holding the full voiceover. The Vidfarm editor reads it directly —
+// the Storyboard/Preview toggle at the top of the editor renders these frames as
+// a contact sheet, tracks each frame's status (outline → built → animated), and
+// gives the director a per-frame comment box whose feedback comes back to the
+// agent. That makes the storyboard the natural INTERACTIVE checkpoint: draft the
+// plan, let the human approve or annotate it, then build.
+//
+// This module owns the format on Vidfarm's side: parse, validate, and scaffold.
+// It is deliberately backend-free (Node built-ins only) so it ships in the public
+// cloud-only CLI, and deliberately LENIENT — it never throws on a malformed plan,
+// it reports warnings, because a half-written storyboard is still useful to show.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/** Canonical filename for the plan at a project root. */
+export const STORYBOARD_FILENAME = "STORYBOARD.md";
+/** Canonical filename for the companion narration script. */
+export const SCRIPT_FILENAME = "SCRIPT.md";
+export const FRAME_STATUSES = ["outline", "built", "animated"];
+export const DEFAULT_FRAME_STATUS = "outline";
+// Frame sections: `## Frame 3 — Title`, `### Beat 1.1`, `## Scene 2`.
+const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
+const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
+const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
+/** A metadata list item: `- key: value` / `* key: value`. */
+const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
+const LEADING_INT_RE = /^(\d+)/;
+const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
+const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
+const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
+const VOICEOVER_KEYS = new Set(["voiceover", "vo", "voice_over", "narration"]);
+function stripQuotes(value) {
+    const t = value.trim();
+    if (t.length >= 2 && ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+function isFrameStatus(value) {
+    return FRAME_STATUSES.includes(value);
+}
+/**
+ * Parse a `STORYBOARD.md`. Tolerant by design: accepts freeform narrative,
+ * Frame/Beat/Scene headings at H2 or H3, unknown keys (kept in `extra`), and
+ * records anything surprising as a warning instead of failing.
+ */
+export function parseStoryboard(source) {
+    const warnings = [];
+    const lines = source.split(/\r?\n/);
+    // ---- Frontmatter (optional `---` block of key: value globals) -------------
+    const globals = { extra: {} };
+    let bodyStart = 0;
+    let firstNonEmpty = 0;
+    while (firstNonEmpty < lines.length && (lines[firstNonEmpty] ?? "").trim() === "")
+        firstNonEmpty++;
+    if ((lines[firstNonEmpty] ?? "").trim() === "---") {
+        let close = -1;
+        for (let i = firstNonEmpty + 1; i < lines.length; i++) {
+            if ((lines[i] ?? "").trim() === "---") {
+                close = i;
+                break;
+            }
+        }
+        if (close === -1) {
+            warnings.push({ message: "Frontmatter opening '---' has no closing '---'; treating the whole file as body.", line: firstNonEmpty + 1 });
+        }
+        else {
+            for (let i = firstNonEmpty + 1; i < close; i++) {
+                const raw = lines[i] ?? "";
+                if (!raw.trim())
+                    continue;
+                const colon = raw.indexOf(":");
+                if (colon === -1) {
+                    warnings.push({ message: `Ignored non key:value frontmatter line: "${raw.trim()}"`, line: i + 1 });
+                    continue;
+                }
+                const key = raw.slice(0, colon).trim().toLowerCase();
+                const value = stripQuotes(raw.slice(colon + 1).trim());
+                if (key === "format")
+                    globals.format = value;
+                else if (key === "message")
+                    globals.message = value;
+                else if (key === "arc")
+                    globals.arc = value;
+                else if (key === "audience")
+                    globals.audience = value;
+                else
+                    globals.extra[key] = value;
+            }
+            bodyStart = close + 1;
+        }
+    }
+    const sections = [];
+    let current = null;
+    for (let i = bodyStart; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const opened = FRAME_HEADING_RE.exec(line);
+        if (opened) {
+            current = {
+                headingText: line.slice(opened[0].length).replace(FRAME_TITLE_SEP_RE, "").trim(),
+                headingLine: i + 1,
+                level: (opened[1] ?? "##").length,
+                lines: []
+            };
+            sections.push(current);
+            continue;
+        }
+        // A sibling (or shallower) non-frame heading closes the current frame;
+        // deeper sub-headings stay part of its narrative.
+        const heading = HEADING_LEVEL_RE.exec(line);
+        if (current && heading && (heading[1] ?? "").length <= current.level) {
+            current = null;
+            continue;
+        }
+        if (current)
+            current.lines.push(line);
+    }
+    const frames = sections.map((section, idx) => {
+        const index = idx + 1;
+        const frame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };
+        const intMatch = LEADING_INT_RE.exec(section.headingText);
+        if (intMatch) {
+            frame.number = Number.parseInt(intMatch[1] ?? "", 10);
+            const rest = section.headingText.slice((intMatch[0] ?? "").length).replace(FRAME_TITLE_SEP_RE, "").trim();
+            if (rest)
+                frame.title = rest;
+        }
+        else if (section.headingText) {
+            frame.title = section.headingText;
+        }
+        const narrative = [];
+        for (const line of section.lines) {
+            const meta = META_RE.exec(line);
+            if (!meta) {
+                narrative.push(line);
+                continue;
+            }
+            const key = (meta[1] ?? "").toLowerCase();
+            const value = (meta[2] ?? "").trim();
+            if (key === "src")
+                frame.src = value;
+            else if (key === "duration") {
+                frame.duration = value;
+                const num = DURATION_NUM_RE.exec(value);
+                if (num)
+                    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
+                else
+                    warnings.push({ message: `Frame ${index}: could not parse duration "${value}".`, line: section.headingLine, frameIndex: index });
+            }
+            else if (key === "poster") {
+                const num = DURATION_NUM_RE.exec(value);
+                if (num)
+                    frame.poster = Number.parseFloat(num[1] ?? "");
+            }
+            else if (key === "status") {
+                const normalized = value.toLowerCase();
+                if (isFrameStatus(normalized))
+                    frame.status = normalized;
+                else {
+                    frame.extra.status = value;
+                    warnings.push({ message: `Frame ${index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`, line: section.headingLine, frameIndex: index });
+                }
+            }
+            else if (TRANSITION_KEYS.has(key))
+                frame.transitionIn = value;
+            else if (SCENE_KEYS.has(key))
+                frame.scene = value;
+            else if (VOICEOVER_KEYS.has(key))
+                frame.voiceover = stripQuotes(value);
+            else
+                frame.extra[key] = value;
+        }
+        frame.narrative = narrative.join("\n").trim();
+        return frame;
+    });
+    return { globals, frames, warnings };
+}
+/** Read + parse a project's storyboard (and its companion script). Missing file
+ *  is NOT an error — it returns `exists:false` with an empty manifest, so a
+ *  caller can say "no plan yet" instead of blowing up. */
+export function readStoryboard(projectDir) {
+    const absPath = path.join(projectDir, STORYBOARD_FILENAME);
+    const scriptAbs = path.join(projectDir, SCRIPT_FILENAME);
+    let script = { exists: false, path: SCRIPT_FILENAME, content: "" };
+    if (existsSync(scriptAbs)) {
+        try {
+            script = { exists: true, path: SCRIPT_FILENAME, content: readFileSync(scriptAbs, "utf8") };
+        }
+        catch { /* unreadable → treat as absent */ }
+    }
+    if (!existsSync(absPath)) {
+        return { exists: false, path: STORYBOARD_FILENAME, absPath, manifest: { globals: { extra: {} }, frames: [], warnings: [] }, script };
+    }
+    return { exists: true, path: STORYBOARD_FILENAME, absPath, manifest: parseStoryboard(readFileSync(absPath, "utf8")), script };
+}
+/** Which review stage the plan is in, mirroring what the editor's Storyboard
+ *  view shows the director: plan → visual sketches → animation. */
+export function storyboardStage(frames) {
+    if (frames.some((f) => f.status === "animated"))
+        return "final";
+    if (frames.some((f) => f.status === "built"))
+        return "sketch";
+    return "storyboard";
+}
+/** Render a starter `STORYBOARD.md`. Keeps every field the editor's Storyboard
+ *  view reads, so a freshly scaffolded plan renders as a real contact sheet
+ *  (with empty frames) rather than a blank page. */
+export function renderStoryboardScaffold(input) {
+    const frames = (input.frames?.length ? input.frames : Array.from({ length: Math.max(1, input.count ?? 5) }, () => "")).map((raw, i) => {
+        const [title, scene] = raw.split("|").map((s) => s.trim());
+        const n = i + 1;
+        return [
+            `## Frame ${n}${title ? ` — ${title}` : ""}`,
+            `- duration: 3s`,
+            `- status: outline`,
+            scene ? `- scene: ${scene}` : `- scene: `,
+            `- voiceover: `,
+            "",
+            scene ? "" : "What happens in this beat, in one or two plain sentences.",
+            ""
+        ].filter((line) => line !== undefined).join("\n");
+    });
+    return [
+        "---",
+        `format: ${input.format ?? "1080x1920"}`,
+        `message: ${input.message ?? ""}`,
+        `arc: ${input.arc ?? ""}`,
+        `audience: ${input.audience ?? ""}`,
+        "---",
+        "",
+        `# ${input.title ?? "Storyboard"}`,
+        "",
+        "Each frame below is one key moment. Advance `status` as you build:",
+        "`outline` (planned) → `built` (a real sub-composition exists at `src`) → `animated` (motion done).",
+        "",
+        ...frames
+    ].join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
+}
+//# sourceMappingURL=storyboard.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.27",
+  "version": "0.21.29",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -17,17 +17,23 @@
     "dist/src/devcli/composition-edit.js",
     "dist/src/devcli/cost-mode.js",
     "dist/src/devcli/doctor.js",
+    "dist/src/devcli/handoff.js",
     "dist/src/devcli/greenscreen-local.js",
     "dist/src/devcli/hyperframes-cli.js",
+    "dist/src/devcli/interaction-mode.js",
     "dist/src/devcli/local-backend.js",
     "dist/src/devcli/local-frontend-server.js",
     "dist/src/devcli/local-render.js",
     "dist/src/devcli/port-utils.js",
     "dist/src/devcli/process-scan.js",
+    "dist/src/devcli/qa-check.js",
+    "dist/src/devcli/qa-regime.js",
     "dist/src/devcli/sequence.js",
     "dist/src/devcli/skills.js",
     "dist/src/devcli/speech.js",
+    "dist/src/devcli/sticker-pack.js",
     "dist/src/devcli/stills.js",
+    "dist/src/devcli/storyboard.js",
     "dist/src/devcli/telemetry.js",
     "dist/src/devcli/timeline-edit.js",
     "dist/src/devcli/transitions.js",
@@ -86,6 +92,7 @@
     "start": "node --import ./dist/src/instrument.js --enable-source-maps dist/src/index.js",
     "check": "tsc -p tsconfig.json --noEmit && npm run check:skills",
     "test:clips": "node --import tsx --test test/clip-curation.test.ts",
+    "test:qa": "node --import tsx --test test/qa-check.test.ts",
     "check:skills": "node scripts/build-director-skill-rollup.mjs --check && node scripts/check-skill-routes.mjs",
     "benchmark:editor-chat": "node --import tsx scripts/benchmark-editor-chat-harness.mjs",
     "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",