@mevdragon/vidfarm-devcli 0.20.3 → 0.20.5

package/dist/src/cli.js

@@ -114,8 +114,10 @@ Make a video in one command (orchestrates ingest → decompose → fork):
 Composition lifecycle (fork → decompose → snapshot → render):
   fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
   pull <forkId>             Sync composition.html/json + video-context   → GET  .../compositions/:forkId/{composition.html,...}
-                            + cast.json to disk, then print timeline gaps
-                            (blank space) and scene/layer keys to target.
+                            + cast.json to disk, write a local agent brief
+                            (.harness/context.json + .harness/agent-guide.md),
+                            then print
+                            timeline gaps (blank space) and scene/layer keys.
     --dir <path>            Local dir (default: .vidfarm/<forkId>)
     --refetch               Overwrite local copies with the cloud version
   decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
@@ -1376,6 +1378,129 @@ async function fetchCompositionFiles(input) {
         console.log(`[vidfarm] fetched ${filename} (${body.length} bytes)`);
     }
 }
+function readJsonFile(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readJsonString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function readJsonStringList(value, max = 8) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const text = readJsonString(entry);
+        if (text && !out.includes(text))
+            out.push(text);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+function writeLocalAgentHarnessFiles(dir) {
+    const videoContext = readJsonFile(path.join(dir, "video-context.json"));
+    const editorHarness = readJsonFile(path.join(dir, "editor-harness.json"));
+    const sceneAnnotations = readJsonFile(path.join(dir, "scene-annotations.json"));
+    const cast = readJsonFile(path.join(dir, "cast.json"));
+    const viralDna = videoContext && readJsonString(videoContext.status) === "ready" && videoContext.viral_dna && typeof videoContext.viral_dna === "object"
+        ? videoContext.viral_dna
+        : null;
+    const harness = editorHarness && readJsonString(editorHarness.status) === "ready" && editorHarness.harness && typeof editorHarness.harness === "object"
+        ? editorHarness.harness
+        : null;
+    const annotations = sceneAnnotations && readJsonString(sceneAnnotations.status) === "done" && Array.isArray(sceneAnnotations.annotations)
+        ? sceneAnnotations.annotations
+        : [];
+    const castMembers = cast && Array.isArray(cast.cast) ? cast.cast : [];
+    const harnessDir = path.join(dir, ".harness");
+    mkdirSync(harnessDir, { recursive: true });
+    const contextPath = path.join(harnessDir, "context.json");
+    const instructionsPath = path.join(harnessDir, "agent-guide.md");
+    const bundle = {
+        generated_by: "vidfarm-devcli",
+        generated_at: new Date().toISOString(),
+        source_title: readJsonString(videoContext?.summary) || null,
+        composition_context: viralDna,
+        editor_harness: harness,
+        scenes: Array.isArray(videoContext?.scenes) ? videoContext?.scenes : [],
+        scene_annotations: annotations,
+        cast: castMembers,
+        transcript: videoContext?.transcript ?? null
+    };
+    writeFileSync(contextPath, JSON.stringify(bundle, null, 2));
+    const emotionalPunch = viralDna?.emotional_punch && typeof viralDna.emotional_punch === "object"
+        ? viralDna.emotional_punch
+        : null;
+    const importantScenes = readJsonStringList(harness?.important_scenes, 6);
+    const editingBias = readJsonStringList(harness?.editing_bias, 6);
+    const doList = readJsonStringList(harness?.do, 5);
+    const dontList = readJsonStringList(harness?.dont, 5);
+    const preserve = readJsonStringList(emotionalPunch?.preserve, 5);
+    const mustPreserve = annotations
+        .flatMap((entry) => readJsonStringList(entry.must_preserve, 3).map((item) => {
+        const slug = readJsonString(entry.scene_slug);
+        return slug ? `${slug}: ${item}` : item;
+    }))
+        .slice(0, 8);
+    const agentMd = `# Vidfarm Local Harness
+
+Read \`.harness/context.json\` before making substantial edits. This fork was pulled from Vidfarm with decompose context; do not freestyle the rewrite from \`composition.html\` alone.
+
+Files to use:
+- \`video-context.json\`: transcript, scene descriptions, and viral DNA.
+- \`editor-harness.json\`: the technical editing brief under \`harness\` (pace, typography, audio, scene roles).
+- \`scene-annotations.json\`: per-scene replacement and regeneration DNA.
+- \`.harness/context.json\`: merged agent-facing snapshot generated by \`vidfarm pull\`.
+- \`.harness/agent-guide.md\`: Vidfarm-specific local scripting guidance generated by \`vidfarm pull\`.
+
+Rules:
+- Treat the viral DNA and editor harness as hard defaults unless the user explicitly overrides them.
+- If you rewrite text, make it fit the existing performance and joke mechanic. Do not replace a format-specific bit with generic product-benefit copy.
+- Preserve the emotional punch first: tone, mechanism, contrast, audio/visual tension, delivery, and preserve beats.
+- Protect any harness scene marked critical/must_keep and the must_preserve notes from scene annotations.
+- When swapping visuals, match both the literal scene DNA and the narrative purpose of the beat.
+
+Current format snapshot:
+- Trend tagline: ${readJsonString(viralDna?.trend_tagline) || "unknown"}
+- Hook: ${readJsonString(viralDna?.hook) || "unknown"}
+- Payoff: ${readJsonString(viralDna?.payoff) || "unknown"}
+- Emotional core: ${readJsonString(emotionalPunch?.core_emotion) || "unknown"}
+- Tone: ${readJsonString(emotionalPunch?.tone) || "unknown"}
+- Mechanism: ${readJsonString(emotionalPunch?.mechanism) || "unknown"}
+- Contrast: ${readJsonString(emotionalPunch?.contrast) || "unknown"}
+- Audio/visual tension: ${readJsonString(emotionalPunch?.audio_visual_tension) || "unknown"}
+- Delivery: ${readJsonString(emotionalPunch?.delivery) || "unknown"}
+- Harness one-liner: ${readJsonString(harness?.one_liner) || "unknown"}
+
+Priority preserve beats:
+${preserve.length ? preserve.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Important scenes:
+${importantScenes.length ? importantScenes.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Scene-level must-preserve cues:
+${mustPreserve.length ? mustPreserve.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Editing bias:
+${editingBias.length ? editingBias.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Do:
+${doList.length ? doList.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Don't:
+${dontList.length ? dontList.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+`;
+    writeFileSync(instructionsPath, agentMd);
+    return { contextPath, instructionsPath };
+}
 async function fetchVideoAssets(input) {
     const refs = readSourceRefs(input.dir);
     if (!refs.compositionSourceUrl && !refs.originalSourceUrl) {
@@ -4439,12 +4564,24 @@ async function runPullCommand(argv) {
     if (!existsSync(htmlPath))
         throw new Error(`pull did not fetch composition.html for ${forkId} (check credentials / fork id).`);
     const info = inspectComposition(readFileSync(htmlPath, "utf8"));
+    const harnessFiles = writeLocalAgentHarnessFiles(dir);
     const hasContext = existsSync(path.join(dir, "video-context.json"));
     const hasCast = existsSync(path.join(dir, "cast.json"));
     const hasAnnotations = existsSync(path.join(dir, "scene-annotations.json"));
     const hasHarness = existsSync(path.join(dir, "editor-harness.json"));
     if (ctx.json) {
-        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, has_scene_annotations: hasAnnotations, has_editor_harness: hasHarness, ...info });
+        printJson({
+            ok: true,
+            fork_id: forkId,
+            dir,
+            has_video_context: hasContext,
+            has_cast: hasCast,
+            has_scene_annotations: hasAnnotations,
+            has_editor_harness: hasHarness,
+            harness_context_path: harnessFiles.contextPath,
+            harness_instructions_path: harnessFiles.instructionsPath,
+            ...info
+        });
         return;
     }
     console.log(`${GREEN}Pulled ${forkId} → ${dir}${RESET}`);
@@ -4456,6 +4593,7 @@ async function runPullCommand(argv) {
         console.log(`  ${layer.key}  ${DIM}${layer.kind ?? "?"} ${layer.start}-${(layer.start + layer.duration).toFixed(2)}s track${layer.track}${flags ? ` [${flags}]` : ""}${layer.slug ? ` slug=${layer.slug}` : ""}${RESET}`);
     }
     console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}, ${hasAnnotations ? "scene-annotations.json ✓" : "scene-annotations.json ✗"}, ${hasHarness ? "editor-harness.json ✓ (style brief under .harness)" : "editor-harness.json ✗"}.${RESET}`);
+    console.log(`${DIM}Agent brief: ${path.relative(dir, harnessFiles.instructionsPath) || path.basename(harnessFiles.instructionsPath)}; merged context: ${path.relative(dir, harnessFiles.contextPath)}.${RESET}`);
     console.log(`${DIM}Next: vidfarm generate video --prompt "..." --aspect-ratio ${info.aspect_ratio ?? "9:16"} --place ${dir} --at <gap start>|--replace <layer_key>${RESET}`);
 }
 async function runVisibilityCommand(argv) {

package/dist/src/editor-chat.js

@@ -117,7 +117,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "KNOWLEDGE ON DEMAND (load_skill): deeper authoring knowledge ships as vidfarm skill packs you can read mid-conversation with the load_skill tool — YOUR OWN capability map for this editor (editor-capabilities: the editor_action verb catalog, editor_context fields, forking rules, the three-axes SWAP↔REPLACE re-theme model, and fueling a scenes replace with raws — load it before a full re-theme, a multi-scene rebuild, or when you need an exact verb/param), the composition HTML contract (hyperframes-core), motion/animation craft and transition doctrine (hyperframes-animation), seek-safe keyframe patterns (hyperframes-keyframes), creative direction/palettes/typography (hyperframes-creative), caption identities (embedded-captions), media/audio resolution (vidfarm-media), and end-to-end workflow playbooks (product-launch-video, faceless-explainer, website-to-video, general-video, motion-graphics, slideshow, talking-head-recut). Call load_skill with the pack name to read its SKILL.md; it lists reference files you can then load by relative path (e.g. file='references/step-4-vo.md'). Use it when a request needs craft beyond the built-in preset vocabulary — designing a whole composition via replace_composition_html, picking motion or transition language for a style, or following a named workflow. NOTE: hyperframes-animation and hyperframes-keyframes describe BOTH script-driven adapters (anime.js/GSAP/Lottie/Three.js) AND script-free CSS techniques — in the web editor apply only the CSS @keyframes / declarative-preset half (the JS adapters are stripped on save; see the web-editor motion rule), and reserve the adapter half for local devcli work. Load only what the task needs, never bulk-load packs, and never paste large skill content back to the user.",
         "replace_composition_html is validated before it reaches the editor: when the HTML violates the composition contract (missing data-composition-id, invalid clip timing, same-track overlaps, unknown preset names, media without src) the tool result comes back with rejected=true and lint_errors, and NOTHING is applied — fix the reported issues and call it again. lint_warnings are advisory and the action still applies.",
         "MOTION IN THE WEB EDITOR IS DECLARATIVE / CSS ONLY — no author <script>. This editor strips every <script> tag on save (stored-XSS defense), so replace_composition_html that contains a <script> is REJECTED (rejected=true), not applied. That means the JavaScript runtime animation adapters — anime.js, GSAP, Lottie, Three.js, TypeGPU, WAAPI-driven code — are NOT available here; they are a local-devcli-only capability. Author all motion for the web editor with the durable, script-free vocabulary: (1) built-in preset actions — set_layer_media ken_burns (still-image pan/zoom), set_transitions / transition + transition_out (scene entrances/exits), set_captions / caption_animation (word-by-word captions); and (2) plain CSS — @keyframes rules in a <style> block plus an inline animation on the layer element (the renderer scrubs and bakes CSS @keyframes deterministically into the final MP4, exactly like the preview). Never try to drive motion with anime.js/GSAP/etc. in the web editor, and never claim you added a scripted animation here. If the user explicitly wants a JS-adapter animation (a Lottie file, a GSAP timeline, a Three.js scene), tell them that is a local devcli / hyperframes-CLI workflow and offer the CSS/preset equivalent for the web editor instead.",
-        "TEMPLATE FORMAT — MATCH IT WHEN WRITING TEXT: the COMPOSITION BRIEF (stable template context in the system prompt) carries composition_context — WHAT THIS TEMPLATE IS: its format/genre and narrative arc (trend_tagline, hook, retention, payoff, preserve, avoid) plus emotional_punch (core_emotion, tone, arc, peak_moment, mechanism, humor, delivery, preserve) — the FEELING the format delivers and what makes it land. ALWAYS read it before writing or adjusting ANY captions, text layers, or on-screen copy, and make your copy fit the template's format and voice — do NOT default to generic product/app ad copy. emotional_punch is the part a remix most often flattens: if the format is a joke, keep emotional_punch.humor's mechanic (rebuild the SAME joke around the new subject, don't drop it for a feature bullet); match emotional_punch.tone and emotional_punch.delivery so intonation, comedic timing, and vibe survive; and never trade the peak_moment's payoff for a flat product plug. The format dictates the caption style: a text-message / DM / iMessage conversation template's captions must read like short back-and-forth chat messages between people (in-character, conversational), a 'story time' / talking-head template reads like first-person spoken narration, a listicle reads like punchy numbered items, a fake-news / headline template reads like a news chyron, etc. `preserve` usually names format cues that must stay (e.g. the messaging-bubble layout); `avoid` names what to keep out. When the template's format is a conversation, skit, or roleplay, keep the captions in that voice and only weave the product in the way that format allows (subtly, in-dialogue) rather than replacing the messages with feature bullets. If the brief's composition_context is thin or you are unsure what the video actually shows, call video_context (scene visual descriptions + transcript) to ground the format BEFORE writing captions.",
+        "TEMPLATE FORMAT — MATCH IT WHEN WRITING TEXT: the COMPOSITION BRIEF (stable template context in the system prompt) carries composition_context — WHAT THIS TEMPLATE IS: its format/genre and narrative arc (trend_tagline, hook, retention, payoff, preserve, avoid) plus emotional_punch (core_emotion, tone, arc, peak_moment, mechanism, contrast, humor, audio_visual_tension, delivery, preserve) — the FEELING the format delivers and what makes it land. ALWAYS read it before writing or adjusting ANY captions, text layers, or on-screen copy, and make your copy fit the template's format and voice — do NOT default to generic product/app ad copy. emotional_punch is the part a remix most often flattens: if the format is a joke, keep emotional_punch.humor's mechanic (rebuild the SAME joke around the new subject, don't drop it for a feature bullet); preserve emotional_punch.contrast when the bit depends on a mismatch (for example tough soundtrack vs delicate visuals, swagger vs mundane setting); use emotional_punch.audio_visual_tension when audio and visuals intentionally play against each other; match emotional_punch.tone and emotional_punch.delivery so intonation, comedic timing, and vibe survive; and never trade the peak_moment's payoff for a flat product plug. The format dictates the caption style: a text-message / DM / iMessage conversation template's captions must read like short back-and-forth chat messages between people (in-character, conversational), a 'story time' / talking-head template reads like first-person spoken narration, a listicle reads like punchy numbered items, a fake-news / headline template reads like a news chyron, etc. `preserve` usually names format cues that must stay (e.g. the messaging-bubble layout); `avoid` names what to keep out. When the template's format is a conversation, skit, or roleplay, keep the captions in that voice and only weave the product in the way that format allows (subtly, in-dialogue) rather than replacing the messages with feature bullets. If the brief's composition_context is thin or you are unsure what the video actually shows, call video_context (scene visual descriptions + transcript) to ground the format BEFORE writing captions.",
         "FILE DIRECTORY: the user's files live in ONE navigable directory with three canonical roots, each with nested subfolders and a copyable path per file: (1) /files — durable 'My Files' assets they keep and reuse (videos mp4/mov/webm, images png/jpg/jpeg/gif/webp/svg, audio mp3/wav/m4a/aac, documents pdf/md/txt/csv), vector-searchable via metadata notes; (2) /temp — scratch space auto-foldered by date (YYYY-MM-DD) and auto-deleted after 30 days; (3) /raws — the reusable clip / source-footage library, foldered by source (e.g. /raws/<source-slug>/). A file's canonical path looks like /raws/product-demos/clip.mp4 or /files/acme-skincare/logo.png. Use the browse_files tool to navigate, search, read, write, and reorganize it: action=list with path (e.g. path='/', '/raws', '/files/brand-assets') enumerates that folder's subfolders + files as canonical items (path, name, kind, view_url); action=search with a plain-language query finds files by MEANING across roots — it combines semantic vector match, substring, and absolute-path match (scope with path='/raws' for footage, '/files' for durable assets, '/' for everything; force one signal with mode=semantic|substring|path). Prefer search over paging list when the library is large or the user references an asset vaguely. When you omit path entirely, list/search now default to '/' (the whole directory) so /raws and /temp are never hidden — but pass path='/raws' to stay in footage. For /raws you can add content_type to filter by EXACT shot kind (talking_head, b_roll, product_shot, screen_recording, demo, reaction, interview, establishing, lifestyle, text_graphic; comma-separate to OR them) — this is an exact tag filter, distinct from the semantic query. For a big folder, list returns next_offset; pass it back as offset to page deeper (with limit up to 500). action=read with a file_id (copied from a prior list/search) fetches one file; action=write with file_name + content (or source_url) SAVES a text/media file into /files; action=annotate with file_id + notes attaches vector-embedded metadata to a /files entry; action=move with file_id + a target path (e.g. path='/raws/demos') reorganizes a raw between /raws folders; action=rename with path + new_name (+ file_id for a file) renames a /files or /temp file or folder in place — use it to keep the directory tidy (e.g. fix a character folder or file name). When the user references their own footage, brand assets, logos, music, a brief, a script, or raw clips ('use my product photo', 'the video I uploaded', 'my brand logo', 'that clip of the founder'), browse_files search or list first to find it rather than asking them to re-upload or paste a URL. For text files (md/txt/csv/srt/vtt/json), read returns the full text_content inline so you can read a brief or script directly. For images/video/audio/pdf, read returns only a durable view_url — use that URL as media: drop it into the timeline via editor_action add_layer/set_layer_media, or pass it into primitive routes (images/edit source_image_url, videos/generate input_references, videos/download). Never invent file ids, paths, or view URLs — always list or search to discover the real ones first.",
         "SAVING CONTEXT TO MY FILES: browse_files action=write persists durable, reusable context the user (and future chats/agents) can read back. write saves text files (md/txt/csv/json/srt/vtt) via content, and IMPORTS media into the library via source_url (a durable URL from a finished primitive job or existing asset) — use source_url to persist a generated asset the user will want again (a character sprite card, a recurring background, a logo variant) instead of leaving it stranded in a job result. Use write to capture the Getting Started artifacts as Markdown: a product About.md (basic offer/product context) or a deeper Interview.md, plus awareness-levels.md, persuasive-angles.md, and ad-hooks.md distilled from the matching brainstorm outputs. When a brainstorm job returns strategy the user wants to keep, offer to save it (or save it) as the corresponding .md so it is not lost when the chat ends. Namescope every write under the right product/offer folder (see MY FILES IS MULTI-OFFER) — e.g. folder_path='acme-skincare', file_name='About.md'. Pass notes on write (or annotate afterwards) for any asset worth finding again: notes describe what the file is, who/what it depicts, and when to use it, and they are vector-embedded so action=search finds the file by meaning in future sessions. Before overwriting an existing file of the same name in the same folder, confirm with the user (writing the same name replaces it).",
         "RECURRING CHARACTERS ARE FIRST-CLASS: mascots, spokespeople, avatars, and product characters that must look the same across videos live in a dedicated, browsable home — the /files/characters/ folder, one subfolder per character keyed by a URL-safe SLUG (lowercase, hyphenated), e.g. /files/characters/zara/. Each character is a TRIO of files in that folder: (1) <character_id>.json — the machine-readable MANIFEST, named after the character's id which is 'character_'+slug (e.g. slug 'zara' → id 'character_zara' → file character_zara.json; the id ALREADY carries the 'character_' prefix, so never double it to character_character_zara.json): { id:'character_<slug>', slug, name, role, appearance (face/build/hair/skin), wardrobe, palette (signature colors), voice (tone/accent/energy), do, dont, sprite_card_path:'/files/characters/<slug>/character_sprite_card.png', about_path:'/files/characters/<slug>/character_about.md', created_at }; (2) character_sprite_card.png — ONE reference-sheet image (full body front/side/back plus a face close-up on a neutral background); (3) character_about.md — the prose the .json summarizes, for richer wording when prompting. AWARENESS: when a user refers to 'our mascot', 'the same character', 'the fox', or names a character, FIRST browse_files list path='/files/characters' (or search) to see who already exists and read that character's manifest + about — never re-imagine a saved character from memory; that is how characters drift off-model. CONSISTENCY: on every generation featuring the character, pass the sprite card's view_url as the reference input (prompt_attachments for images/generate + images/edit, input_references for videos/generate and generate_layer) and lift wording from the manifest/about into the prompt.",

package/dist/src/services/hyperframes.js

@@ -1550,7 +1550,9 @@ Return strictly valid JSON matching this schema:
       "arc": string,
       "peak_moment": string,
       "mechanism": string,
+      "contrast": string,
       "humor": string,
+      "audio_visual_tension": string,
       "delivery": string,
       "preserve": [string, ...]
     },
@@ -1598,10 +1600,12 @@ VIRAL_DNA RULES:
   - "arc": how the feeling MOVES across the runtime (e.g. "curiosity → mounting tension → relief-laugh", "flat setup → sudden absurd turn").
   - "peak_moment": the single beat that lands the emotional hit — the punchline, the reveal, the gut-punch, the beat-drop — and roughly when.
   - "mechanism": WHY it lands — the technique doing the work (comedic timing, irony, subversion of expectation, escalation, deadpan intonation, relatability, a trending-sound drop synced to the visual). Weigh the AUDIO here: on TikTok/Reels the trending sound or music bed is frequently the single biggest driver of the emotional hit, so if a recognizable trending sound, a beat drop, or a music swell is doing the work, name it as the mechanism.
-  - "humor": if it's funny, state what the JOKE actually is and why it works, concretely enough that a remixer can rebuild the same joke with new subject matter; write "none" if the format is not comedic.
+  - "contrast": the specific mismatch / juxtaposition that creates the feeling. This is CRITICAL for irony- or sass-driven formats: identify the actual tension, not just the visible gesture. Examples: "hard, macho soundtrack over a dainty office-laptop scene", "overconfident delivery about a trivial preference", "luxury attitude applied to a mundane workflow". If there is no real mismatch, write "none".
+  - "humor": if it's funny, state what the JOKE actually is and why it works, concretely enough that a remixer can rebuild the same joke with new subject matter; write "none" if the format is not comedic. Focus on the underlying bit, not surface choreography.
+  - "audio_visual_tension": describe how the SOUND and VISUALS interact emotionally: whether the soundtrack / vocal cadence reinforces the visuals, undercuts them, or creates a deliberate mismatch. Name the exact pairing if that's the joke or swagger engine; write "none" only if audio contributes nothing.
   - "delivery": the performance cues to preserve so the vibe survives — speech intonation / cadence (from the AUDIO TRANSCRIPT), the pause held before the punchline, a facial beat or reaction, and especially the SOUND: the music / trending-audio bed, where the beat drop or lyric hit lands relative to the cut, a music swell, an sfx sting, the deadpan-then-cut. This is what keeps intonation, comedic timing, and the audio-driven vibe from being lost in a remix.
   - "preserve": 2-4 emotional beats a remix MUST keep to reproduce the same feeling (e.g. "keep the beat drop landing exactly on the reveal cut", "hold the silent beat before the reveal", "keep the flat unbothered delivery", "the payoff must undercut the buildup, not confirm it").
-  Use BOTH the frames and the AUDIO TRANSCRIPT block above. Never leave emotional_punch empty — infer the feeling from the frames, captions, and pacing even when there is no audio, and when the audio is music-only, treat the sound itself as the emotional engine.
+  Use BOTH the frames and the AUDIO TRANSCRIPT block above. Never leave emotional_punch empty — infer the feeling from the frames, captions, and pacing even when there is no audio, and when the audio is music-only, treat the sound itself as the emotional engine. Do NOT over-index on a single gesture or hand movement if the real emotional engine is the character attitude, the soundtrack choice, the setting mismatch, or the audio-vs-visual contrast.
 - "preserve": 3-5 concrete elements a remixer MUST keep to preserve the format (e.g., "Pinned comment stays on-screen the whole video", "Wedding dance payoff shot").
 - "avoid": 3-5 things that would break the format if changed (e.g., "Do not remove the on-screen text overlay", "Do not slow the cuts below 1.5s").
 - "promotions": 3-5 categories of product / service / offer this exact format could be reused to promote, WITHOUT changing the beat structure or hook mechanic. Each item is a concrete pitchable use-case, not a genre. Examples: "SaaS free-trial signup (before/after workflow)", "Fitness challenge (7-day transformation)", "Local restaurant grand-opening (line-out-the-door proof)", "Ebook / course launch (result-first payoff)", "Real-estate open-house (walk-through reveal)". Anchor each promotion to the same viral tactic captured in "hook" — do not invent unrelated verticals.
@@ -1781,7 +1785,16 @@ function resolveFontSize(input) {
     return normalizeFontSize(input.fontSize, input.canvasHeight);
 }
 const DEFAULT_EMOTIONAL_PUNCH = {
-    core_emotion: "", tone: "", arc: "", peak_moment: "", mechanism: "", humor: "", delivery: "", preserve: []
+    core_emotion: "",
+    tone: "",
+    arc: "",
+    peak_moment: "",
+    mechanism: "",
+    contrast: "",
+    humor: "",
+    audio_visual_tension: "",
+    delivery: "",
+    preserve: []
 };
 export const DEFAULT_VIRAL_DNA = {
     trend_tagline: "", hook: "", retention: "", payoff: "", emotional_punch: { ...DEFAULT_EMOTIONAL_PUNCH }, preserve: [], avoid: [], promotions: [], keywords: []
@@ -1800,7 +1813,9 @@ function normalizeEmotionalPunch(value) {
         arc: asString(record.arc ?? record.emotional_arc),
         peak_moment: asString(record.peak_moment ?? record.peakMoment),
         mechanism: asString(record.mechanism),
+        contrast: asString(record.contrast),
         humor: asString(record.humor),
+        audio_visual_tension: asString(record.audio_visual_tension ?? record.audioVisualTension),
         delivery: asString(record.delivery),
         preserve: asStringArray(record.preserve).slice(0, 4)
     };
@@ -1865,12 +1880,26 @@ function buildEditorHarnessPrompt(input) {
     const roleVocab = SCENE_ROLE_VOCAB.join(" | ");
     const formatVocab = CONTENT_FORMATS.join(" | ");
     const audioDigest = buildAudioDigestForPrompt(input.transcript ?? null);
+    const emotional = input.viralDna?.emotional_punch;
+    const emotionalSnapshot = emotional && [
+        emotional.core_emotion,
+        emotional.tone,
+        emotional.arc,
+        emotional.peak_moment,
+        emotional.mechanism,
+        emotional.contrast,
+        emotional.humor,
+        emotional.audio_visual_tension,
+        emotional.delivery
+    ].some((value) => value && value.trim().length > 0)
+        ? `\nVIRAL DNA FEELING SNAPSHOT (operationalize this in the harness; do NOT drift from it):\n- core_emotion: ${emotional.core_emotion || "—"}\n- tone: ${emotional.tone || "—"}\n- arc: ${emotional.arc || "—"}\n- peak_moment: ${emotional.peak_moment || "—"}\n- mechanism: ${emotional.mechanism || "—"}\n- contrast: ${emotional.contrast || "—"}\n- humor: ${emotional.humor || "—"}\n- audio_visual_tension: ${emotional.audio_visual_tension || "—"}\n- delivery: ${emotional.delivery || "—"}\n- preserve: ${(emotional.preserve || []).join("; ") || "—"}\n`
+        : "";
     return `You are Vidfarm's EDITING DIRECTOR. You are studying a short-form video to write an EDITOR HARNESS — a compact, technical brief that lets another AI editor recreate this video's STYLE (not its exact content) in one clean pass on a timeline editor (scenes, captions, audio, transitions, keyframes).
 
 This is DIFFERENT from "viral DNA" (why the video works / what to preserve). The harness is HOW to edit: pace, typography, b-roll usage, transitions, audio bed, and the role each scene plays. Be concrete and directive — every field should be something an editor can act on, not vibes.
 
 Video duration: ${input.durationSeconds.toFixed(2)} seconds.
-${frameListing}${cutListing}${audioDigest}${promptHint}
+${frameListing}${cutListing}${audioDigest}${emotionalSnapshot}${promptHint}
 Return strictly valid JSON matching this schema:
 {
   "format": string,                 // one of: ${formatVocab}
@@ -1933,7 +1962,7 @@ RULES:
 - Ground pacing numbers on the detected cuts + duration when cuts are supplied; otherwise estimate from the frames. Round avg_scene_seconds and cuts_per_10s to at most 2 decimals.
 - "scenes": 3-8 entries covering the whole runtime in order, each tied to a real moment you see. Reserve importance "critical" for the 1-3 beats that actually carry the style/retention (usually the hook + payoff).
 - Prefer the caption_style / transition / shot_kind vocabulary above so the editor can map straight to presets; a free-form label is fine when nothing fits.
-- "emotional": this is HOW to edit so the FEELING survives — the vibe, the joke, the intonation, and the SOUND are the first things a remix flattens, so make these directive. Use the AUDIO TRANSCRIPT block: on TikTok/Reels the trending sound / music bed is often the biggest carrier of the feeling. "target_feeling" = the emotion the recreated edit must produce; "tone" = the register to hold; "comedic_timing" = the exact editing move that sells the joke (the beat held before a cut, the deadpan-then-punch, the sfx sting or beat-drop on the button word) or "none"; "intonation" = the vocal delivery/cadence to preserve on any VO or on-cam speech (or "none" if silent) — flag it if the speech must be re-voiced in the SAME cadence; "vibe_anchors" = 2-4 concrete edit choices that carry the emotion, and include the audio ones (e.g. "keep the trending sound and land the beat drop on the reveal cut", "swell the music on the payoff", "hold a full beat of silence before the reveal cut", "cut hard on the punch word"). Infer the feeling from frames + pacing even without audio, and when the audio is music-only treat the sound as the emotional engine; never leave it empty.
+- "emotional": this is HOW to edit so the FEELING survives — the vibe, the joke, the intonation, and the SOUND are the first things a remix flattens, so make these directive. Use the AUDIO TRANSCRIPT block: on TikTok/Reels the trending sound / music bed is often the biggest carrier of the feeling. "target_feeling" = the emotion the recreated edit must produce; "tone" = the register to hold; "comedic_timing" = the exact editing move that sells the joke (the beat held before a cut, the deadpan-then-punch, the sfx sting or beat-drop on the button word) or "none"; "intonation" = the vocal delivery/cadence to preserve on any VO or on-cam speech (or "none" if silent) — flag it if the speech must be re-voiced in the SAME cadence; "vibe_anchors" = 2-4 concrete edit choices that carry the emotion, and include the audio ones (e.g. "keep the trending sound and land the beat drop on the reveal cut", "swell the music on the payoff", "hold a full beat of silence before the reveal cut", "cut hard on the punch word"). When the viral-DNA snapshot above names a contrast or audio_visual_tension, convert that into actionable edit moves instead of drifting to superficial gestures. Infer the feeling from frames + pacing even without audio, and when the audio is music-only treat the sound as the emotional engine; never leave it empty.
 - Keep every string tight and directive. Never invent audio you cannot infer — say "none"/"unknown" instead.
 - Output ONLY the JSON object.`;
 }
@@ -2030,7 +2059,8 @@ async function runEditorHarnessPass(input) {
         frameTimestamps: input.frames.map((f) => f.timestamp),
         sceneCuts: input.sceneCuts,
         userPrompt: input.userPrompt ?? null,
-        transcript: input.transcript ?? null
+        transcript: input.transcript ?? null,
+        viralDna: input.viralDna ?? null
     });
     const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
     return normalizeEditorHarness(attempt.result);
@@ -2437,13 +2467,12 @@ export async function smartDecomposeVideo(input) {
             sceneCuts,
             transcript
         });
-        // Phase 2 — vision, OCR, product-placement, and the editor harness run
-        // concurrently, all now transcript-aware. OCR and placement failures are
-        // non-fatal. The placement + harness calls are DELIBERATELY separate
-        // requests from the caption/scene vision call so they can never dilute
-        // timeline-layer quality — they reuse the same sparse frames (no extra
-        // ffmpeg) plus the transcript from phase 1.
-        const [attempt, ocrFrames, placementSurfaces, editorHarness] = await Promise.all([
+        // Phase 2 — vision, OCR, and product-placement run concurrently, all now
+        // transcript-aware. OCR and placement failures are non-fatal. The
+        // placement call is DELIBERATELY separate from the caption/scene vision
+        // call so it can never dilute timeline-layer quality — it reuses the same
+        // sparse frames (no extra ffmpeg) plus the transcript from phase 1.
+        const [attempt, ocrFrames, placementSurfaces] = await Promise.all([
             callVisionWithFallback({
                 prompt,
                 frames,
@@ -2461,19 +2490,6 @@ export async function smartDecomposeVideo(input) {
             }).catch((err) => {
                 console.error("smart decompose placement pass failed", err instanceof Error ? err.message : err);
                 return [];
-            }),
-            // Editor harness — technical editing direction. Isolated call in the same
-            // burst (reuses these frames + the detected cuts + the transcript); non-fatal.
-            runEditorHarnessPass({
-                frames,
-                keys: input.keys,
-                durationSeconds: meta.durationSeconds,
-                sceneCuts,
-                userPrompt: input.userPrompt ?? null,
-                transcript
-            }).catch((err) => {
-                console.error("smart decompose editor-harness pass failed", err instanceof Error ? err.message : err);
-                return DEFAULT_EDITOR_HARNESS;
             })
         ]);
         devLog("hyperframes.smart_decompose.ocr_completed", {
@@ -2559,6 +2575,21 @@ export async function smartDecomposeVideo(input) {
         if (input.trendTaglineHint && input.trendTaglineHint.trim().length > 0) {
             viralDna.trend_tagline = input.trendTaglineHint.trim();
         }
+        // Editor harness — technical editing direction. Run AFTER viral DNA is
+        // normalized so the harness can operationalize the exact emotional punch
+        // instead of guessing independently and drifting from the decompose result.
+        const editorHarness = await runEditorHarnessPass({
+            frames,
+            keys: input.keys,
+            durationSeconds: meta.durationSeconds,
+            sceneCuts,
+            userPrompt: input.userPrompt ?? null,
+            transcript,
+            viralDna
+        }).catch((err) => {
+            console.error("smart decompose editor-harness pass failed", err instanceof Error ? err.message : err);
+            return DEFAULT_EDITOR_HARNESS;
+        });
         // NOTE: the per-scene clip-annotation + content-format pass is deliberately
         // NOT run here — it is a separate vision call that would risk the ~60s origin
         // timeout on longer videos. /auto-decompose seeds scene-annotations.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "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": {
@@ -32,7 +32,7 @@
   "scripts": {
     "dev": "tsx --import ./src/instrument.ts watch src/index.ts",
     "dev:frontend": "node scripts/build-homepage-client.mjs --watch",
-    "dev:cli": "tsx src/cli.ts --help",
+    "dev:cli": "tsx src/cli.ts",
     "build:frontend": "node scripts/build-homepage-client.mjs",
     "build:hyperframes-editor": "cd demo && node scripts/build.mjs",
     "operator:template-artifact": "node scripts/platform-operator-template-artifact.mjs",