@mevdragon/vidfarm-devcli 0.18.0 → 0.19.0

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

@@ -0,0 +1,117 @@
+// Shared canonical file-directory path model.
+//
+// The user's files live in three *separate* backends — My Files attachments,
+// Temp files, and the Raws (clip) library — each with its own DynamoDB records
+// and S3 prefix. This module is the ONE place that defines the unified virtual
+// directory that presents them as three navigable roots:
+//
+//     /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.
+// A file's real handle is still its backend id (attachment/temp/clip id) — the
+// path is the human-readable navigation + display layer on top.
+//
+// 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", "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: "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" || value === "projects" || value === "approved";
+}
+export function directoryRootLabel(root) {
+    const info = DIRECTORY_ROOTS.find((r) => r.key === root);
+    return info ? info.label : root;
+}
+/**
+ * Normalize a relative folder path: trim each segment, drop empties and any
+ * leading/trailing slashes, collapse repeats. `"/a//b/ "` → `"a/b"`.
+ */
+export function normalizeFolderPath(value) {
+    return String(value ?? "")
+        .split("/")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .join("/");
+}
+/**
+ * Parse a canonical directory path into its root + relative folder path.
+ *
+ * A path is always interpreted as a FOLDER location (what to list / scope to):
+ * every segment after the root is treated as folder path. Files are addressed
+ * by backend id, not resolved from the trailing segment, so there's no
+ * file-vs-folder ambiguity to guess at here.
+ *
+ *   "/raws/product-demos"  → { root:"raws", folderPath:"product-demos" }
+ *   "/"  or  ""            → { root:null,   folderPath:"" }  (virtual root)
+ */
+export function parseDirectoryPath(input) {
+    const segments = String(input ?? "")
+        .split("/")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (segments.length === 0)
+        return { root: null, folderPath: "", segments: [] };
+    const [head, ...rest] = segments;
+    if (!isDirectoryRoot(head))
+        return { root: null, folderPath: "", segments };
+    return { root: head, folderPath: rest.join("/"), segments: rest };
+}
+/**
+ * Build a canonical directory path from parts. `name` omitted → a folder path.
+ *
+ *   buildDirectoryPath("files", "logos", "logo.png") → "/files/logos/logo.png"
+ *   buildDirectoryPath("raws", "demos")              → "/raws/demos"
+ *   buildDirectoryPath("temp")                       → "/temp"
+ */
+export function buildDirectoryPath(root, folderPath, name) {
+    const parts = [root, normalizeFolderPath(folderPath)];
+    if (name)
+        parts.push(String(name).trim());
+    return "/" + parts.filter(Boolean).join("/");
+}
+/** Build a folder DirectoryItem for a child folder name under a root/parent. */
+export function folderItem(root, parentFolder, childName) {
+    const folderPath = normalizeFolderPath(parentFolder ? `${parentFolder}/${childName}` : childName);
+    return {
+        path: buildDirectoryPath(root, folderPath),
+        root,
+        folderPath,
+        name: childName,
+        kind: "folder"
+    };
+}
+/**
+ * Given a flat list of items' folderPaths (+ any explicit empty-folder records)
+ * and the current folder, return the immediate CHILD folder names. Mirrors the
+ * client explorer's `immediateFolders`, kept here so server and client agree.
+ */
+export function immediateChildFolders(folderPaths, currentFolder) {
+    const cur = normalizeFolderPath(currentFolder);
+    const prefix = cur ? cur + "/" : "";
+    const names = new Set();
+    for (const raw of folderPaths) {
+        const n = normalizeFolderPath(raw);
+        if (!n || (cur && n === cur) || n.indexOf(prefix) !== 0)
+            continue;
+        const child = n.slice(prefix.length).split("/")[0];
+        if (child)
+            names.add(child);
+    }
+    return Array.from(names).sort();
+}
+//# sourceMappingURL=file-directory.js.map

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

package/dist/src/services/storage.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, createReadStream, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, PutObjectTaggingCommand, S3Client } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
@@ -13,6 +13,19 @@ function isS3NotFoundError(error) {
     const httpStatusCode = typeof metadata?.httpStatusCode === "number" ? metadata.httpStatusCode : undefined;
     return name === "NoSuchKey" || code === "NoSuchKey" || name === "NotFound" || httpStatusCode === 404;
 }
+// Media objects live at stable, content-addressed-ish keys and are the
+// heavy bytes browsers re-fetch on every /discover visit today (S3 objects
+// currently ship no Cache-Control). Give media a 1-day fresh window with a
+// week-long stale-while-revalidate tail so it caches hard but still self-heals
+// if a key is ever overwritten in place. NON-media (json records, composition
+// html, text) stays uncached — those are mutable and must never go stale.
+function cacheControlForContentType(contentType) {
+    const ct = (contentType || "").toLowerCase();
+    if (ct.startsWith("video/") || ct.startsWith("image/") || ct.startsWith("audio/")) {
+        return "public, max-age=86400, stale-while-revalidate=604800";
+    }
+    return undefined;
+}
 export class StorageService {
     localRoot = path.join(config.VIDFARM_DATA_DIR, "storage");
     s3 = config.STORAGE_DRIVER === "s3"
@@ -98,7 +111,8 @@ export class StorageService {
                 Bucket: config.AWS_S3_BUCKET,
                 Key: key,
                 Body: value,
-                ContentType: contentType
+                ContentType: contentType,
+                CacheControl: cacheControlForContentType(contentType)
             }));
             return { key, url: this.getPublicUrl(key) };
         }
@@ -113,6 +127,30 @@ export class StorageService {
      * no client header contract), which the bucket's tag-scoped lifecycle rule
      * expires after 30 days. No-op on the local filesystem driver.
      */
+    /**
+     * Store a file that already lives on disk WITHOUT reading it fully into memory.
+     * Streams the bytes to S3 (ContentLength from the file's size, so no multipart
+     * dependency) or copies on the local driver. Use for large media (whole-video
+     * raw imports, render outputs) where `putBuffer(readFileSync(...))` would pin
+     * the entire file in a Buffer and risk OOM on memory-bounded Lambdas.
+     */
+    async putFile(key, localPath, contentType = "application/octet-stream") {
+        if (this.s3 && config.AWS_S3_BUCKET) {
+            await this.s3.send(new PutObjectCommand({
+                Bucket: config.AWS_S3_BUCKET,
+                Key: key,
+                Body: createReadStream(localPath),
+                ContentLength: statSync(localPath).size,
+                ContentType: contentType,
+                CacheControl: cacheControlForContentType(contentType)
+            }));
+            return { key, url: this.getPublicUrl(key) };
+        }
+        const filePath = this.resolveLocalPath(key);
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        copyFileSync(localPath, filePath);
+        return { key, url: this.getPublicUrl(key) };
+    }
     async putObjectTags(key, tags) {
         if (!this.s3 || !config.AWS_S3_BUCKET)
             return;
@@ -331,6 +369,13 @@ export function joinStorageKey(...parts) {
         .filter(Boolean)
         .join("/");
 }
+// Shared process-wide StorageService instance. StorageService binds its driver
+// (s3 vs local fs) + data dir from `config` at construction, so importing this
+// singleton must happen AFTER any env that flips RECORDS_DRIVER/STORAGE_DRIVER/
+// VIDFARM_DATA_DIR has been set (the in-process devcli local path arranges that
+// via withLocalBackend before it imports any service). app.ts, the extracted
+// directory/clip-scan services, and the devcli all share this one instance.
+export const storage = new StorageService();
 function normalizeStorageKey(key) {
     const normalized = key.replace(/^\/+/, "");
     if (!normalized ||

package/dist/src/services/upstream.js

@@ -117,9 +117,9 @@ function seedAuthHeaders(shareToken) {
         headers["vidfarm-share-token"] = shareToken;
     return headers;
 }
-// /editor/<template_id> issues a 302 → /editor/<template_id>?fork=<id>
+// /editor/<template_id> issues a 302 → /editor/<template_id>/fork/<id>
 // whenever the caller (or the template's default fork) has one. Follow the
-// redirect once by hand so we can read the fork id off the query string.
+// redirect once by hand so we can read the fork id off the path.
 async function resolveUpstreamForkId(input) {
     try {
         const res = await fetch(`${input.host}/editor/${encodeURIComponent(input.templateId)}`, {
@@ -132,9 +132,9 @@ async function resolveUpstreamForkId(input) {
             const location = res.headers.get("location");
             if (location) {
                 const target = new URL(location, input.host);
-                const fork = target.searchParams.get("fork");
-                if (fork)
-                    return fork;
+                const match = target.pathname.match(/^\/editor\/[^/]+\/fork\/([^/]+)\/?$/);
+                if (match)
+                    return decodeURIComponent(match[1]);
             }
         }
     }