@mevdragon/vidfarm-devcli 0.18.1 → 0.19.0

package/dist/src/reskin/theme.js

@@ -84,7 +84,11 @@ export const RESKIN_CSS = `
 /* layout */
 .rk-container{width:min(var(--rk-container),100%);margin:0 auto;padding:0 var(--rk-gutter)}
 .rk-container-wide{width:min(85rem,100%);margin:0 auto;padding:0 var(--rk-gutter)}
-.rk-page{padding:24px 0 80px}
+/* vertical-only so it never clobbers the horizontal gutter that .rk-container
+   / .rk-container-wide set via padding-left/right (a full padding shorthand
+   here would zero the side gutter, leaving content flush to the viewport
+   edges, most visible on mobile) */
+.rk-page{padding-top:24px;padding-bottom:80px}
 .rk-page-head{display:grid;gap:4px;margin-bottom:18px}
 .rk-h1{font-size:var(--rk-text-3xl);letter-spacing:-.03em}
 .rk-sub{font-size:var(--rk-text-base);color:var(--rk-text-muted)}
@@ -116,11 +120,10 @@ export const RESKIN_CSS = `
   transition:background var(--rk-dur) var(--rk-ease),color var(--rk-dur) var(--rk-ease)}
 .rk-sidebar-item:hover{background:var(--rk-n-100);color:var(--rk-ink)}
 .rk-sidebar-item.is-active{background:var(--rk-gold-tint);color:var(--rk-ink)}
-/* signed-in identity — subtle, small, pinned to the sidebar foot so you can
- * tell which account you're in at a glance */
-/* padding-bottom reserves room for the floating chat FAB (bottom-left,
- * ~56px + 16px margin) so the name/email are never hidden behind it */
-.rk-sidebar-account{margin-top:8px;padding:8px 13px 80px;border-top:1px solid var(--rk-border);
+/* signed-in identity — subtle, small, pinned to the very bottom of the sidebar
+ * so you can tell which account you're in at a glance. The chat FAB hovers
+ * ABOVE this block (see .rk-signed-in .rk-fab) rather than sharing the spot. */
+.rk-sidebar-account{margin-top:8px;padding:8px 13px 2px;border-top:1px solid var(--rk-border);
   color:var(--rk-n-500);line-height:1.3;overflow:hidden}
 .rk-sidebar-account-name{font-size:12px;font-weight:600;color:var(--rk-n-600);
   white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
@@ -135,6 +138,10 @@ export const RESKIN_CSS = `
   border:0;cursor:grab;background:var(--rk-gold-500);color:var(--rk-ink);display:grid;place-items:center;
   box-shadow:var(--rk-shadow-lg);touch-action:none;user-select:none;-webkit-user-select:none;
   transition:transform var(--rk-dur) var(--rk-ease),box-shadow var(--rk-dur) var(--rk-ease),opacity var(--rk-dur) var(--rk-ease)}
+/* signed in: the name/email block sits at the sidebar foot, so lift the FAB's
+ * default resting spot to hover just above it (never overlapping the identity).
+ * Only applies to the CSS default — a dragged FAB uses its saved inline top. */
+.rk-signed-in .rk-fab{bottom:calc(84px + env(safe-area-inset-bottom))}
 .rk-fab:hover{transform:translateY(-2px);box-shadow:0 6px 18px -6px rgba(252,185,0,.6),var(--rk-shadow-lg)}
 .rk-fab.is-dragging{cursor:grabbing;transition:none;transform:scale(1.08)}
 .rk-fab.is-open{opacity:0;pointer-events:none;transform:scale(.6)}
@@ -231,6 +238,12 @@ export const RESKIN_CSS = `
    a folder Open button, a per-row "…" kebab menu, and a copy-path toast.
    Reused verbatim by the chat dock (attach mode) and /library/raws (standalone). */
 .rk-dir{display:flex;flex-direction:column;min-height:0;flex:1}
+.rk-dir-space{flex:none;display:inline-flex;gap:2px;margin:2px 12px 8px;padding:2px;
+  background:var(--rk-n-100,#f1ede6);border:1px solid var(--rk-border);border-radius:var(--rk-r-full);align-self:flex-start}
+.rk-dir-space-btn{font-family:inherit;font-size:12px;font-weight:600;color:var(--rk-n-500,#7a7266);
+  background:transparent;border:0;border-radius:var(--rk-r-full);padding:4px 14px;cursor:pointer;
+  transition:background var(--rk-dur) var(--rk-ease),color var(--rk-dur) var(--rk-ease)}
+.rk-dir-space-btn.is-on{background:var(--rk-surface,#fff);color:var(--rk-ink);box-shadow:var(--rk-shadow-sm,0 1px 2px rgba(0,0,0,.06))}
 .rk-dir-search{flex:none;padding:0 12px 8px}
 .rk-dir-search-input{width:100%;font-family:inherit;font-size:12.5px;color:var(--rk-ink);
   background:var(--rk-surface,#fff);border:1px solid var(--rk-border);border-radius:var(--rk-r-full);padding:7px 12px;
@@ -302,8 +315,12 @@ export const RESKIN_CSS = `
 .rk-aichat-tool:hover{background:var(--rk-n-100);color:var(--rk-ink)}
 .rk-aichat-tool svg{width:15px;height:15px}
 .rk-aichat-tool.is-on{background:var(--rk-gold-tint);border-color:var(--rk-gold-600);color:var(--rk-ink)}
-.rk-aichat-log{flex:1;min-height:0;overflow-y:auto;padding:16px;display:grid;gap:10px;align-content:start;background:var(--rk-n-50)}
-.rk-aichat-msg{max-width:85%;padding:10px 14px;border-radius:var(--rk-r-2xl);font-size:13.5px;line-height:1.5;overflow-wrap:break-word}
+/* overflow-x:hidden + a capped single column (minmax(0,1fr), NOT the default
+   auto track which grows to content) keep the log scrolling ONLY vertically —
+   a wide child (long tool note / URL / file path) can no longer widen the grid
+   and force a horizontal scrollbar in the narrow dock column. */
+.rk-aichat-log{flex:1;min-height:0;overflow-y:auto;overflow-x:hidden;padding:16px;display:grid;grid-template-columns:minmax(0,1fr);gap:10px;align-content:start;background:var(--rk-n-50)}
+.rk-aichat-msg{max-width:85%;min-width:0;padding:10px 14px;border-radius:var(--rk-r-2xl);font-size:13.5px;line-height:1.5;overflow-wrap:anywhere;word-break:break-word}
 .rk-aichat-msg.is-ai{background:#fff;border:1px solid var(--rk-border);color:var(--rk-text);justify-self:start;
   border-bottom-left-radius:var(--rk-r-sm);box-shadow:var(--rk-shadow-xs)}
 .rk-aichat-msg.is-user{background:var(--rk-gold-tint2);color:var(--rk-ink);justify-self:end;border-bottom-right-radius:var(--rk-r-sm)}
@@ -320,6 +337,11 @@ export const RESKIN_CSS = `
 .rk-aichat-chip-label{max-width:150px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;font-family:inherit;
   font-size:11.5px;font-weight:600;text-align:left;text-decoration:underline;text-underline-offset:2px;text-decoration-color:transparent}
 .rk-aichat-chip-label:hover{text-decoration-color:currentColor}
+.rk-aichat-chip.is-pending{opacity:.75}
+.rk-aichat-chip.is-pending .rk-aichat-chip-label{text-decoration:none;cursor:default}
+.rk-aichat-chip-spin{width:11px;height:11px;flex:none;border-radius:50%;border:2px solid currentColor;
+  border-top-color:transparent;animation:rk-aichat-chip-spin .7s linear infinite}
+@keyframes rk-aichat-chip-spin{to{transform:rotate(360deg)}}
 /* composer = one bordered "text area" box: the textarea fills the top and the
    attach + send controls sit inside it along the bottom row. */
 .rk-aichat-composer{display:flex;flex-direction:column;gap:8px;margin:12px;padding:10px 10px 9px;flex:none;background:#fff;
@@ -341,8 +363,8 @@ export const RESKIN_CSS = `
 .rk-aichat-attach svg{width:18px;height:18px}
 
 /* ── live agentic turn: status → actions (tool notes + HTTP cards) → text ── */
-.rk-aichat-turn{display:grid;gap:8px;justify-items:start;width:100%}
-.rk-aichat-stream{white-space:pre-wrap}
+.rk-aichat-turn{display:grid;gap:8px;justify-items:start;width:100%;min-width:0}
+.rk-aichat-stream{white-space:pre-wrap;overflow-wrap:anywhere;word-break:break-word;max-width:100%}
 .rk-aichat-stream[hidden]{display:none}
 .rk-aichat-actions{display:grid;gap:6px;width:100%}
 .rk-aichat-actions:empty{display:none}
@@ -356,7 +378,7 @@ export const RESKIN_CSS = `
 @keyframes rk-aichat-blink{0%,80%,100%{opacity:.28;transform:translateY(0)}40%{opacity:1;transform:translateY(-2px)}}
 .rk-aichat-toolnote{display:inline-flex;align-items:center;gap:7px;font-size:11.5px;color:var(--rk-text-muted);
   font-family:var(--rk-font-mono);background:#fff;border:1px solid var(--rk-border);
-  border-radius:var(--rk-r-lg);padding:5px 10px;width:fit-content}
+  border-radius:var(--rk-r-lg);padding:5px 10px;width:fit-content;max-width:100%;overflow-wrap:anywhere;word-break:break-word}
 .rk-aichat-toolnote::before{content:"";width:6px;height:6px;border-radius:50%;background:var(--rk-gold-500);flex:none}
 .rk-aichat-loadmore{width:100%;margin-top:6px;padding:9px 12px;font-size:12.5px;font-weight:600;
   color:var(--rk-text);background:var(--rk-white);border:1px solid var(--rk-border);
@@ -521,6 +543,9 @@ export const RESKIN_CSS = `
   /* horizontal strip: kill the foot border + top offset so the account block
      sits centered in the row instead of showing a stray hairline above it */
   .rk-sidebar-account{padding:8px 13px 2px;border-top:0;margin-top:0}
+  /* strip/burger layout: the account block is no longer at the sidebar foot,
+     so drop the FAB back to its normal bottom-left resting spot */
+  .rk-signed-in .rk-fab{bottom:calc(16px + env(safe-area-inset-bottom))}
   .rk-content{margin-left:0}
   .rk-chat-left .rk-sidebar{visibility:visible}
 }

package/dist/src/services/billing.js

@@ -164,6 +164,10 @@ function resolveCostCenterSlug(input) {
             || explicitSlug === "video_download_lambda"
             || explicitSlug === "video_ingest_lambda"
             || explicitSlug === "rapidapi_remove_background"
+            // Local sharp chroma-key background removal + the 2-step media-overlay
+            // primitive (BYOK image gen + chroma key): platform compute/convenience.
+            || explicitSlug === "greenscreen_chroma_key"
+            || explicitSlug === "media_overlay"
             || explicitSlug === "primitive_media_lambda"
             || explicitSlug === "job_runner_lambda"
             || explicitSlug === "step_functions_standard"

package/dist/src/services/clip-curation/hunt.js

@@ -393,6 +393,8 @@ export function normalizeHuntSpec(raw) {
         spec.clips_per_10min = Math.min(200, perTen);
     if (typeof rec.source_url === "string" && rec.source_url.trim())
         spec.source_url = rec.source_url.trim();
+    if (typeof rec.folder_path === "string" && rec.folder_path.trim())
+        spec.folder_path = rec.folder_path.trim().slice(0, 500);
     return spec;
 }
 // ── misc ────────────────────────────────────────────────────────────────────

package/dist/src/services/clip-records.js

@@ -115,6 +115,34 @@ export class ClipRecordsService {
             ExpressionAttributeValues: { ":fp": folderPath }
         }));
     }
+    /**
+     * Rename/move a whole Raws folder: re-point every clip whose folder_path is
+     * `fromFolder` OR nested beneath it onto `toFolder` (prefix-preserving), so a
+     * folder rename carries its subfolders too. Returns the count moved.
+     * Paths are compared normalized (trimmed, no leading/trailing slashes).
+     */
+    async moveClipsFolder(owner, fromFolder, toFolder) {
+        const norm = (v) => String(v ?? "").split("/").map((s) => s.trim()).filter(Boolean).join("/");
+        const from = norm(fromFolder);
+        const to = norm(toFolder);
+        if (!from || from === to)
+            return 0;
+        const clips = await this.listClips(owner, { limit: 5000 });
+        let moved = 0;
+        for (const clip of clips) {
+            const fp = norm(clip.folder_path);
+            let next = null;
+            if (fp === from)
+                next = to;
+            else if (fp.startsWith(from + "/"))
+                next = to + fp.slice(from.length);
+            if (next != null) {
+                await this.updateClipFolder(owner, clip.clip_id, next);
+                moved += 1;
+            }
+        }
+        return moved;
+    }
     // ── Presets ──────────────────────────────────────────────────────────────
     async listPresets(owner) {
         const res = await dynamodb.send(new QueryCommand({

package/dist/src/services/file-directory.js

@@ -8,6 +8,7 @@
 //     /files/<subfolders…>/<name>     → My Files attachments  (users/<id>/files/…)
 //     /temp/<YYYY-MM-DD>/<name>        → Temp files            (users/<id>/temporary/…)
 //     /raws/<subfolders…>/<name>      → Raws / clip library   (clips/<owner>/…)
+//     /projects/<forkId>/<subpath…>   → Composition forks     (compositions/forks/<forkId>/…)
 //
 // It's a *virtual* layer: physical S3 keys are untouched. The canonical path is
 // what the UI copies, what the chat agent navigates, and what search annotates.
@@ -17,18 +18,20 @@
 // Pure logic, no runtime deps, so both `src/app.ts` (serve) and
 // `infra/lambda/editor-chat.ts` (cloud) import it, and the frontend explorer
 // client mirrors the same constants.
-export const DIRECTORY_ROOT_KEYS = ["files", "temp", "raws"];
+export const DIRECTORY_ROOT_KEYS = ["files", "temp", "raws", "projects", "approved"];
 export const DIRECTORY_ROOTS = [
     { key: "files", label: "My Files", description: "Durable personal files — brand assets, characters, saved context. Vector-searchable via notes." },
     { key: "temp", label: "Temp", description: "Scratch space, auto-organized by date (YYYY-MM-DD) and auto-deleted after 30 days." },
-    { key: "raws", label: "Raws", description: "The reusable clip / source-footage library, organized into folders by source." }
+    { key: "raws", label: "Raws", description: "The reusable clip / source-footage library, organized into folders by source." },
+    { key: "projects", label: "Projects", description: "Your video-editing projects — one folder per fork, holding that composition's working files (composition.html/json, cast, media) and saved versions. Read-only: browse to reference or study another fork." },
+    { key: "approved", label: "Approved", description: "Finished, ready-to-post cuts, organized into folders (defaults to a folder per tracer/campaign)." }
 ];
 // The attachments backend historically scopes its folders under the internal
 // key "my_files"; the canonical public root name is "files". These two helpers
 // bridge the canonical name and that backend scope so callers never hardcode it.
 export const ATTACHMENTS_FOLDER_SCOPE = "my_files";
 export function isDirectoryRoot(value) {
-    return value === "files" || value === "temp" || value === "raws";
+    return value === "files" || value === "temp" || value === "raws" || value === "projects" || value === "approved";
 }
 export function directoryRootLabel(root) {
     const info = DIRECTORY_ROOTS.find((r) => r.key === root);

package/dist/src/services/hyperframes.js

@@ -1628,6 +1628,197 @@ function normalizeViralDna(value) {
         keywords: asStringArray(record.keywords).map((item) => item.toLowerCase())
     };
 }
+// ---------------------------------------------------------------------------
+// Editor-harness pass — technical editing direction (the "how to edit like
+// this" companion to viral DNA's "why it works"). Isolated vision call in the
+// decompose burst (never the caption/scene call) so it can't dilute
+// timeline-layer quality; reuses the SAME sparse frames already sampled + the
+// ffmpeg cut timings for grounded pacing. Non-fatal: callers wrap in .catch().
+// ---------------------------------------------------------------------------
+export const DEFAULT_EDITOR_HARNESS = {
+    format: "other",
+    one_liner: "",
+    aspect_ratio: "",
+    pacing: { cut_rhythm: "medium", avg_scene_seconds: 0, cuts_per_10s: 0, energy_curve: "" },
+    typography: { caption_style: "", placement: "", font_character: "", emphasis: "", text_density: "none" },
+    broll: { reliance: "none", sourcing: "", shot_kinds: [], cadence: "" },
+    transitions: { default: "cut", intro: "", outro: "", usage: "" },
+    audio: { voiceover: "", music: "", sfx: "", captions_from: "" },
+    scenes: [],
+    important_scenes: [],
+    editing_bias: [],
+    do: [],
+    dont: []
+};
+const HARNESS_CUT_RHYTHMS = ["fast", "medium", "slow", "varied"];
+const HARNESS_TEXT_DENSITY = ["heavy", "moderate", "minimal", "none"];
+const HARNESS_BROLL_RELIANCE = ["heavy", "moderate", "light", "none"];
+const HARNESS_SCENE_IMPORTANCE = ["critical", "high", "normal"];
+function buildEditorHarnessPrompt(input) {
+    const frameListing = input.frameTimestamps.length > 0
+        ? `\nFRAMES SUPPLIED (in order, each captioned with its capture timestamp):\n${input.frameTimestamps.map((t, i) => `  frame ${i + 1} @ ${t.toFixed(2)}s`).join("\n")}\n`
+        : "";
+    const cutListing = input.sceneCuts.length > 0
+        ? `\nDETECTED HARD CUTS (seconds, from the editing timeline — use these to ground pacing/cut_rhythm/cuts_per_10s/avg_scene_seconds): ${input.sceneCuts.map((c) => c.toFixed(2)).join(", ")}\n`
+        : "\n(No hard cuts detected — likely a single continuous take or slow crossfades. Judge pacing from the frames.)\n";
+    const promptHint = input.userPrompt && input.userPrompt.trim().length > 0
+        ? `\nUSER GOAL (bias the harness toward recreating THIS intent): ${input.userPrompt.trim()}\n`
+        : "";
+    const roleVocab = SCENE_ROLE_VOCAB.join(" | ");
+    const formatVocab = CONTENT_FORMATS.join(" | ");
+    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}${promptHint}
+Return strictly valid JSON matching this schema:
+{
+  "format": string,                 // one of: ${formatVocab}
+  "one_liner": string,              // ONE sentence: how to edit to match this style
+  "aspect_ratio": string,           // "9:16" | "1:1" | "16:9" (infer from the frames)
+  "pacing": {
+    "cut_rhythm": "fast" | "medium" | "slow" | "varied",
+    "avg_scene_seconds": number,    // typical shot length in seconds
+    "cuts_per_10s": number,         // ground on the detected cuts + duration
+    "energy_curve": string          // e.g. "front-loaded hook then steady"
+  },
+  "typography": {
+    "caption_style": string,        // karaoke | word-pop | spotlight | stack-up | neon | bounce | none | free-form label
+    "placement": string,            // e.g. "center-lower" | "top" | "full-bleed" | "none"
+    "font_character": string,       // e.g. "bold condensed all-caps sans"
+    "emphasis": string,             // e.g. "active-word highlight in yellow" | "none"
+    "text_density": "heavy" | "moderate" | "minimal" | "none"
+  },
+  "broll": {
+    "reliance": "heavy" | "moderate" | "light" | "none",
+    "sourcing": string,             // generated | stock | screen-recording | talking-head | mixed
+    "shot_kinds": [string, ...],    // e.g. b_roll, product_shot, screen_recording, reaction, establishing, text_graphic
+    "cadence": string               // e.g. "new visual ~every 2s under VO"
+  },
+  "transitions": {
+    "default": string,              // junction at most cuts: cut | crossfade | whip | slide | zoom | dissolve | ...
+    "intro": string,                // first-clip entrance
+    "outro": string,                // last-clip exit
+    "usage": string                 // one line on how transitions are used
+  },
+  "audio": {
+    "voiceover": string,            // e.g. "first-person narration" | "none"
+    "music": string,                // e.g. "upbeat lofi bed, low volume" | "none"
+    "sfx": string,                  // e.g. "whoosh on cuts" | "none"
+    "captions_from": string         // "voiceover" | "on-screen text" | "none"
+  },
+  "scenes": [{
+    "role": string,                 // ${roleVocab}
+    "timestamp": string,            // human range, e.g. "0:00-0:03"
+    "start": number,                // numeric seconds where the beat begins
+    "importance": "critical" | "high" | "normal",
+    "must_keep": boolean,           // true if swapping/removing this beat kills the style
+    "note": string,                 // what happens in this beat
+    "edit_bias": string             // how to edit this beat while staying on-style
+  }],
+  "important_scenes": [string, ...],// roles or timestamps that carry the virality — protect when editing
+  "editing_bias": [string, ...],    // 3-6 top directives an editor MUST follow to stay on-style
+  "do": [string, ...],              // 2-5 concrete DOs
+  "dont": [string, ...]             // 2-5 concrete DON'Ts
+}
+
+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.
+- Keep every string tight and directive. Never invent audio you cannot infer — say "none"/"unknown" instead.
+- Output ONLY the JSON object.`;
+}
+function normalizeEditorHarness(raw) {
+    const rec = asPlainRecord(raw);
+    const oneOf = (value, allowed, fallback) => {
+        const s = normalizeSlug(readAnnotationString(value));
+        return allowed.includes(s) ? s : fallback;
+    };
+    const num = (value) => {
+        const n = Number(value);
+        return Number.isFinite(n) && n >= 0 ? Number(n.toFixed(2)) : 0;
+    };
+    const formatSlug = normalizeSlug(readAnnotationString(rec.format));
+    const format = CONTENT_FORMATS.includes(formatSlug)
+        ? formatSlug
+        : "other";
+    const pacing = asPlainRecord(rec.pacing);
+    const typography = asPlainRecord(rec.typography);
+    const broll = asPlainRecord(rec.broll);
+    const transitions = asPlainRecord(rec.transitions);
+    const audio = asPlainRecord(rec.audio);
+    const scenesRaw = Array.isArray(rec.scenes) ? rec.scenes : [];
+    const scenes = scenesRaw
+        .map((s) => {
+        const sr = asPlainRecord(s);
+        return {
+            role: normalizeSlug(readAnnotationString(sr.role)) || "context",
+            timestamp: readAnnotationString(sr.timestamp),
+            start: num(sr.start),
+            importance: oneOf(sr.importance, HARNESS_SCENE_IMPORTANCE, "normal"),
+            must_keep: sr.must_keep === true,
+            note: readAnnotationString(sr.note),
+            edit_bias: readAnnotationString(sr.edit_bias)
+        };
+    })
+        .filter((s) => s.note.length > 0 || s.edit_bias.length > 0)
+        .slice(0, 12);
+    return {
+        format,
+        one_liner: readAnnotationString(rec.one_liner),
+        aspect_ratio: readAnnotationString(rec.aspect_ratio),
+        pacing: {
+            cut_rhythm: oneOf(pacing.cut_rhythm, HARNESS_CUT_RHYTHMS, "medium"),
+            avg_scene_seconds: num(pacing.avg_scene_seconds),
+            cuts_per_10s: num(pacing.cuts_per_10s),
+            energy_curve: readAnnotationString(pacing.energy_curve)
+        },
+        typography: {
+            caption_style: readAnnotationString(typography.caption_style),
+            placement: readAnnotationString(typography.placement),
+            font_character: readAnnotationString(typography.font_character),
+            emphasis: readAnnotationString(typography.emphasis),
+            text_density: oneOf(typography.text_density, HARNESS_TEXT_DENSITY, "none")
+        },
+        broll: {
+            reliance: oneOf(broll.reliance, HARNESS_BROLL_RELIANCE, "none"),
+            sourcing: readAnnotationString(broll.sourcing),
+            shot_kinds: readAnnotationStringList(broll.shot_kinds, 8),
+            cadence: readAnnotationString(broll.cadence)
+        },
+        transitions: {
+            default: readAnnotationString(transitions.default) || "cut",
+            intro: readAnnotationString(transitions.intro),
+            outro: readAnnotationString(transitions.outro),
+            usage: readAnnotationString(transitions.usage)
+        },
+        audio: {
+            voiceover: readAnnotationString(audio.voiceover),
+            music: readAnnotationString(audio.music),
+            sfx: readAnnotationString(audio.sfx),
+            captions_from: readAnnotationString(audio.captions_from)
+        },
+        scenes,
+        important_scenes: readAnnotationStringList(rec.important_scenes, 8),
+        editing_bias: readAnnotationStringList(rec.editing_bias, 8),
+        do: readAnnotationStringList(rec.do, 6),
+        dont: readAnnotationStringList(rec.dont, 6)
+    };
+}
+async function runEditorHarnessPass(input) {
+    if (input.frames.length === 0)
+        return DEFAULT_EDITOR_HARNESS;
+    const prompt = buildEditorHarnessPrompt({
+        durationSeconds: input.durationSeconds,
+        frameTimestamps: input.frames.map((f) => f.timestamp),
+        sceneCuts: input.sceneCuts,
+        userPrompt: input.userPrompt ?? null
+    });
+    const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
+    return normalizeEditorHarness(attempt.result);
+}
 function shortElementId() {
     return `element_${randomUUID().slice(0, 8)}`;
 }
@@ -2025,7 +2216,7 @@ export async function smartDecomposeVideo(input) {
         // non-fatal. The placement call is DELIBERATELY a separate request from the
         // caption/scene vision call so it can never dilute timeline-layer quality —
         // it just reuses the same already-sampled sparse frames (no extra ffmpeg).
-        const [attempt, ocrFrames, transcript, placementSurfaces] = await Promise.all([
+        const [attempt, ocrFrames, transcript, placementSurfaces, editorHarness] = await Promise.all([
             callVisionWithFallback({
                 prompt,
                 frames,
@@ -2049,6 +2240,18 @@ 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); non-fatal.
+            runEditorHarnessPass({
+                frames,
+                keys: input.keys,
+                durationSeconds: meta.durationSeconds,
+                sceneCuts,
+                userPrompt: input.userPrompt ?? null
+            }).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", {
@@ -2147,12 +2350,15 @@ export async function smartDecomposeVideo(input) {
             caption_count: finalCaptions.length,
             captions_snapped: snapped.snappedCount,
             scenes_snapped: snappedScenes.snappedCount,
-            placement_surface_count: finalPlacementSurfaces.length
+            placement_surface_count: finalPlacementSurfaces.length,
+            editor_harness_format: editorHarness.format,
+            editor_harness_scene_count: editorHarness.scenes.length
         });
         return {
             summary: typeof record.summary === "string" ? record.summary : "",
             viralDna,
             placementSurfaces: finalPlacementSurfaces,
+            editorHarness,
             transcript,
             durationSeconds: meta.durationSeconds,
             width: meta.width,
@@ -2228,6 +2434,7 @@ export function buildSmartDecomposedHtml(input) {
     const audioId = shortElementId();
     const audioEl = `<audio class="clip" id="${audioId}" data-hf-id="${audioId}" data-hf-slug="source_audio" data-layer-mode="both" data-layer-kind="audio" data-viral-note="Original TikTok audio track." data-start="0" data-duration="${totalDuration}" data-end="${totalDuration}" data-track-index="1" data-label="Original audio" data-media-start="0" data-playback-start="0" data-timeline-role="music" data-volume="1" src="${escapeAttr(sourceUrl)}" preload="metadata"></audio>`;
     const viralDnaJson = escapeAttr(JSON.stringify(result.viralDna ?? DEFAULT_VIRAL_DNA));
+    const editorHarnessJson = escapeAttr(JSON.stringify(result.editorHarness ?? DEFAULT_EDITOR_HARNESS));
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -2241,7 +2448,7 @@ export function buildSmartDecomposedHtml(input) {
   </style>
 </head>
 <body>
-  <div data-composition-id="${escapeAttr(compositionId)}" data-source-video="${escapeAttr(sourceUrl)}" data-width="${result.width || 720}" data-height="${result.height || 1280}" data-duration="${totalDuration}" data-source-title="${escapeAttr(title)}" data-viral-dna="${viralDnaJson}">
+  <div data-composition-id="${escapeAttr(compositionId)}" data-source-video="${escapeAttr(sourceUrl)}" data-width="${result.width || 720}" data-height="${result.height || 1280}" data-duration="${totalDuration}" data-source-title="${escapeAttr(title)}" data-viral-dna="${viralDnaJson}" data-editor-harness="${editorHarnessJson}">
     <video data-vf-playback-source="true" src="${escapeAttr(sourceUrl)}" muted playsinline preload="auto" style="position:absolute;left:0%;top:0%;width:100%;height:100%;z-index:0;object-fit:cover;background:#050604"></video>
     ${sceneEls}
     ${audioEl}
@@ -2250,6 +2457,79 @@ export function buildSmartDecomposedHtml(input) {
 </body>
 </html>`;
 }
+// The public placeholder tile every blank scene starts on — a gray diagonal-
+// striped 720×1280 image with a dashed text box (uploaded once by
+// scripts/upload-scene-placeholder.ts). Hardcoded to the prod bucket URL (a
+// public object that resolves from any stage) so the blank composition renders
+// identically everywhere. Mirrors SCENE_PLACEHOLDER_IMAGE_URL in the SPA editor.
+export const SCENE_PLACEHOLDER_IMAGE_URL = "https://vidfarmprodstack-vidfarmbucket335ee12f-0vsvtd5earqy.s3.us-east-1.amazonaws.com/primitives/placeholders/scene-placeholder.png";
+const BLANK_PROJECT_SCENE_COUNT = 3;
+const BLANK_PROJECT_SCENE_DURATION = 4;
+// The canonical, reusable "new blank project" composition. This is the single
+// composition.html every fresh /editor/original/fork/new opens on, and the base
+// every blank project forks from (POST /api/v1/compositions seeds a new fork by
+// copying this). It mirrors blankProjectSemanticLayers() in the SPA editor: a
+// continuous placeholder image track (3 butt-cut 4s scenes on track 0) plus a
+// "Scene 1/2/3" caption on track 3, giving the user an editable 12s scaffold
+// instead of an empty canvas. Like the other builders it emits clips only — the
+// runtime is injected on serve by rewriteHyperframesDraftCompositionHtml, and z
+// is normalized to track index on the way out.
+export function buildBlankCompositionHtml(compositionId) {
+    const totalDuration = BLANK_PROJECT_SCENE_COUNT * BLANK_PROJECT_SCENE_DURATION;
+    const sceneEls = [];
+    const captionEls = [];
+    for (let index = 0; index < BLANK_PROJECT_SCENE_COUNT; index += 1) {
+        const sceneNumber = index + 1;
+        const start = index * BLANK_PROJECT_SCENE_DURATION;
+        const end = start + BLANK_PROJECT_SCENE_DURATION;
+        // Placeholder image scene — full canvas, track 0. Together the three form
+        // one continuous 12s media track the user replaces with real footage.
+        const imageId = `scene-${sceneNumber}-image`;
+        sceneEls.push(`<img class="clip" id="${imageId}" data-hf-id="${imageId}" data-hf-slug="scene_${sceneNumber}" data-layer-mode="both" data-layer-kind="image" data-viral-note="Placeholder scene backdrop — replace with your own media." data-start="${start}" data-duration="${BLANK_PROJECT_SCENE_DURATION}" data-end="${end}" data-track-index="0" data-label="Scene ${sceneNumber}" src="${escapeAttr(SCENE_PLACEHOLDER_IMAGE_URL)}" alt="" style="position:absolute;left:0%;top:0%;width:100%;height:100%;z-index:0;opacity:1;border-radius:0px;overflow:hidden;object-fit:cover;" />`);
+        // "Scene N" label sitting in the tile's blank text box — white on a solid
+        // black highlight so it reads over both the placeholder and swapped-in media.
+        const caption = {
+            slug: `scene_${sceneNumber}_label`,
+            text: `Scene ${sceneNumber}`,
+            start,
+            duration: BLANK_PROJECT_SCENE_DURATION,
+            x: 13.5,
+            y: 44,
+            width: 73,
+            height: 12,
+            font_size: 34,
+            color: "#ffffff",
+            background: "#000000",
+            background_style: "highlight-solid",
+            font_family: "TikTok Sans",
+            font_weight: 700,
+            viral_note: "Placeholder scene label — edit or delete once you add real media."
+        };
+        const captionId = `scene-${sceneNumber}-caption`;
+        const innerStyle = captionInlineTextStyle(caption);
+        captionEls.push(`<div class="clip" id="${captionId}" data-hf-id="${captionId}" data-hf-slug="${escapeAttr(caption.slug)}" data-layer-mode="publish" data-layer-kind="caption" data-viral-note="${escapeAttr(caption.viral_note ?? "")}" data-start="${start}" data-duration="${BLANK_PROJECT_SCENE_DURATION}" data-end="${end}" data-track-index="3" data-label="${escapeAttr(caption.text)}" data-text-background-style="${caption.background_style}" data-text-background-color="${escapeAttr(caption.background)}" data-font-family="${escapeAttr(caption.font_family)}" style="position:absolute;left:${caption.x}%;top:${caption.y}%;width:${caption.width}%;height:${caption.height}%;z-index:3;display:flex;align-items:center;justify-content:center;padding:3px;box-sizing:border-box;text-align:center;color:${caption.color};background:transparent;font-family:'${caption.font_family}', 'TikTok Sans', sans-serif;font-weight:${caption.font_weight};font-size:${caption.font_size}px;line-height:1.2;overflow:visible;"><span data-vf-text-lines="true"><span data-vf-text-inline="true" style="${innerStyle}">${escapeHtml(caption.text)}</span></span></div>`);
+    }
+    // data-vf-origin="raw": a brand-new project, so the editor never auto-prompts
+    // the Decompose modal (there is no source video to decompose).
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <style>
+    @import url("https://fonts.googleapis.com/css2?family=Abel&family=Montserrat:wght@600;700&family=Source+Code+Pro:wght@700&family=TikTok+Sans:wght@400;600;700;800;900&family=Yesteryear&display=swap");
+    html, body { width:100%; height:100%; margin:0; overflow:hidden; background:#050604; }
+    [data-composition-id] { position:relative; width:100vw; height:100vh; overflow:hidden; background:#050604; }
+  </style>
+</head>
+<body>
+  <div data-composition-id="${escapeAttr(compositionId)}" data-vf-origin="raw" data-width="720" data-height="1280" data-duration="${totalDuration}" data-source-title="Untitled project">
+    ${sceneEls.join("\n    ")}
+    ${captionEls.join("\n    ")}
+  </div>
+</body>
+</html>`;
+}
 function normalizeSlug(value) {
     return String(value ?? "")
         .toLowerCase()

package/dist/src/services/serverless-records.js

@@ -625,6 +625,12 @@ class ServerlessRecordsServiceImpl {
             title: input.title ?? null,
             caption: input.caption ?? "",
             pinnedComment: input.pinnedComment ?? null,
+            // Self-file into a tracer-derived Approved subfolder (canonical
+            // `/approved/<slug>`), mirroring how raws default into a source folder. An
+            // explicit folderPath (incl. "" for the root) always wins.
+            folderPath: input.folderPath !== undefined
+                ? normalizeFolder(input.folderPath ?? "")
+                : (input.tracer ? slugFolderSegment(input.tracer) : ""),
             mediaAssets: input.mediaAssets ?? [],
             sharePasswordHash: input.sharePasswordHash ?? null,
             zipStorageKey: input.zipStorageKey ?? null,
@@ -654,6 +660,23 @@ class ServerlessRecordsServiceImpl {
         const updated = await this.putRecord("ready_post", { ...post, status: "deleted", deletedAt: nowIso(), updatedAt: nowIso() });
         return updated;
     }
+    // Move one approved post into a folder (canonical /approved/<folderPath>); ""
+    // returns it to the root. Mirrors updateClipFolder for raws.
+    async setReadyPostFolder(customerId, postId, folderPath) {
+        const post = await this.getReadyPost(postId);
+        if (!post || post.customerId !== customerId)
+            return null;
+        return this.putRecord("ready_post", {
+            ...post,
+            folderPath: normalizeFolder(folderPath),
+            updatedAt: nowIso()
+        });
+    }
+    // Rename an approved folder by re-pointing every post inside it (the folder-rename
+    // primitive for the /approved directory root).
+    async moveReadyPostFolder(customerId, fromFolder, toFolder) {
+        await this.moveCollectionFolder("ready_post", customerId, fromFolder, toFolder);
+    }
     async setReadyPostMedia(input) {
         const post = await this.getReadyPost(input.postId);
         if (!post || post.customerId !== input.customerId)
@@ -861,6 +884,8 @@ class ServerlessRecordsServiceImpl {
             storageKey: input.storageKey,
             folderPath: normalizeFolder(input.folderPath),
             publicUrl: input.publicUrl ?? null,
+            thumbnailStorageKey: input.thumbnailStorageKey ?? null,
+            thumbnailUrl: input.thumbnailUrl ?? null,
             notes: input.notes ?? null,
             notesEmbedding: input.notesEmbedding ?? null,
             notesEmbeddingModel: input.notesEmbeddingModel ?? null,
@@ -870,6 +895,12 @@ class ServerlessRecordsServiceImpl {
     async updateUserAttachmentNotes(customerId, attachmentId, patch) {
         return this.mergeByIdForCustomer("user_attachment", customerId, attachmentId, patch);
     }
+    // Rename a My Files entry. Only the record's display name changes — the S3
+    // storageKey (and therefore the durable view URL) is untouched, so this is a
+    // cheap metadata-only rename that keeps every existing link working.
+    async renameUserAttachment(customerId, attachmentId, fileName) {
+        return this.mergeByIdForCustomer("user_attachment", customerId, attachmentId, { fileName });
+    }
     async listUserAttachments(customerId) {
         return this.listByCustomer("user_attachment", customerId);
     }
@@ -913,6 +944,10 @@ class ServerlessRecordsServiceImpl {
         if (existing)
             await this.deleteById("user_temporary_file", fileId);
     }
+    // Rename a temp file (display name only; storageKey/view URL untouched).
+    async renameUserTemporaryFile(customerId, fileId, fileName) {
+        return this.mergeByIdForCustomer("user_temporary_file", customerId, fileId, { fileName });
+    }
     async deleteExpiredUserTemporaryFiles() {
         const now = nowIso();
         const files = (await this.scanCollection("user_temporary_file"))
@@ -1445,6 +1480,14 @@ function normalizeFolder(value) {
         return "";
     return value.trim().replace(/^\/+|\/+$/g, "");
 }
+// Slugify a single folder-name segment (e.g. a tracer → an /approved subfolder).
+function slugFolderSegment(value) {
+    return String(value ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
 function isExpiredUserTemporaryFileRecord(record) {
     return typeof record.id === "string"
         && record.id.length > 0