@mevdragon/vidfarm-devcli 0.7.0 → 0.7.1

package/dist/src/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
@@ -71,7 +72,10 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
     --query <text>          Keyword search over the catalog
     --mine                  Only your own uploaded inspirations
     --limit <n>             Max results
-  inspiration-add <url>     Ingest a TikTok/YT/IG/X video as a template  → POST /discover/templates
+  inspiration-add <url|file>  Ingest a TikTok/YT/IG/X URL — or upload a    → POST /discover/templates
+                            local MP4/MOV/WebM file — as a private        (files: presign + PUT via
+                            template. --title (uploads; defaults to the    /discover/templates/upload)
+                            template id), --tagline, --notes optional.
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
@@ -99,17 +103,28 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --no-wait               Return the job id instead of polling to the URL
     --place <dir>           After generating, place it into that composition
     --at <time> | --replace <layer_key>   Placement (fill gap vs replace scene)
-  place <dir|composition.html>   Insert a media URL into a local composition
+  place <dir|composition.html>   Insert media into a local composition
                             (fill a gap or replace a scene) — same clip markup
                             the browser editor makes; serve live-morphs it.
-    --src <url>             Direct media URL to place (required)
-    --kind <video|image>    Media kind (inferred from the URL if omitted)
+    --src <url|file>        Media to place (required). A URL is used as-is; a
+                            LOCAL FILE PATH is imported without bloating S3 — a
+                            serve working copy copies it onto the box's own disk
+                            store (free, local render only); any other dir
+                            uploads it to the ephemeral temp store (folder below).
+    --base-url <url>        Serve box origin that hosts /storage (default
+                            http://localhost:3000) — set if you ran serve --port.
+    --folder <path>         Temp-store folder for uploaded local files (default: temp)
+    --kind <video|image>    Media kind (inferred from the URL/path if omitted)
     --at <time>             Start it at this time (seconds / mm:ss) — fill a gap
     --replace <layer_key>   Replace this scene/layer (copies its timing+geometry)
     --duration <n>          Timeline length in seconds
     --track <n>             Timeline layer index (auto if omitted)
     --x --y --width --height   Geometry as % (default full canvas 0/0/100/100)
     --object-fit <fit>      cover|contain|fill|none|scale-down (default cover)
+    --ken-burns <preset>    Animate a still image (slow pan/zoom): zoom-in|
+                            zoom-out|pan-left|pan-right|pan-up|pan-down|
+                            zoom-in-left|zoom-in-right
+    --ken-burns-intensity <n>   Travel/zoom strength 0.04-0.5 (default 0.18)
   remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
@@ -125,6 +140,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
 
 Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
+    --video <url|file>      Primary MP4 (URL, or a local file auto-uploaded to temp/)
+    --media <url|file>      Extra media (repeatable; local files auto-upload to temp/)
+    --folder <path>         Temp-store folder for uploaded local files (default: temp)
+    --caption <text>        Post caption (required)
   posts                     List your approved posts                     → GET  /api/v1/approved/posts
   post <postId>             Read one approved post (prints share URL)    → GET  /api/v1/approved/posts/:postId
   schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
@@ -146,7 +165,9 @@ Agent skill (install the latest director skill so your AI agent can act):
 
 Files (multi-step flows the devcli handles for you):
   upload <file>             Upload to the EPHEMERAL temp store, print URL → POST /api/v1/user/me/temporary-files/upload
-    --folder <path>         Namescope the upload under a product/offer folder
+    --folder <path>         Namescope the upload under a folder. Prefer a
+                            throwaway 'temp' folder (--folder temp) for scratch
+                            media so it never clutters your durable library.
   put-file [file]           Write a file INTO My Files (persistent lib)  → POST /api/v1/user/me/attachments/upload
     --folder <path>         Namescope under a product/offer folder (e.g. acme-skincare)
     --as <name>             Name the saved file (required for --content/--stdin)
@@ -160,6 +181,10 @@ Files (multi-step flows the devcli handles for you):
     --print                 Print text contents (md/txt/csv/json) instead of saving
   put-file / get-file / files are the My Files (persistent) read+write set;
   upload is the throwaway temp store for dropping media into a composition.
+  Local file paths: to avoid uploading assets to Vidfarm S3 at all, reference
+  them straight from disk with 'place --src ./clip.mp4' on a 'serve' box (copied
+  to that box's local disk store, free local render). When you DO need a durable
+  URL (cloud render/approve), keep it under a throwaway 'temp/' folder.
 
 Cost spectrum (default to the cheapest approach that works; see SKILL.director.md):
   free        Reuse a decomposed template, swap captions/images/existing MP4s
@@ -496,6 +521,12 @@ async function runServeCommand(argv) {
     // local-render by definition — cloud rendering is the EXPLICIT
     // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
     process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
+    // Same trap as the state machine ARN: a dev-shell .env can carry the staging
+    // media-lambda URL, which would route probe/thumbnail/trim/etc. to a cloud
+    // Lambda that cannot fetch this box's localhost storage URLs ("fetch
+    // failed"). Media ops on a serve box always run in-process.
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL = "";
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_SECRET = "";
     process.env.VIDFARM_DATA_DIR = dataDir;
     process.env.VIDFARM_API_KEY = apiKey;
     process.env.PORT = String(port);
@@ -1131,17 +1162,77 @@ async function runVideosCommand(argv) {
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
 async function runInspirationAddCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), tagline: { type: "string" }, notes: { type: "string" } } });
-    const sourceUrl = parsed.positionals[0];
-    if (!sourceUrl)
-        throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X).");
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" }, tagline: { type: "string" }, notes: { type: "string" } } });
+    const source = parsed.positionals[0];
+    if (!source)
+        throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X) or a local video file path.");
     const ctx = commonContext(parsed.values);
+    // Local file → upload flow: presign, PUT the bytes (straight to S3, or the
+    // server multipart fallback on a local-storage box), then finalize with the
+    // storage key. Anything that parses as http(s) keeps the classic URL ingest.
+    const isUrl = /^https?:\/\//i.test(source);
+    const localPath = isUrl ? null : path.resolve(process.cwd(), source);
+    if (localPath) {
+        if (!existsSync(localPath)) {
+            throw new Error(`inspiration-add: "${source}" is not an http(s) URL and no such local file exists.`);
+        }
+        const fileName = path.basename(localPath);
+        const buffer = readFileSync(localPath);
+        const contentType = guessContentType(fileName);
+        const presign = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: "/discover/templates/upload/presign",
+            auth: ctx.auth,
+            body: { file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength }
+        });
+        assertApiOk(presign, "inspiration-add (presign)");
+        let storageKey = presign.json?.storage_key;
+        let uploadedName = presign.json?.file_name || fileName;
+        if (presign.json?.transport === "presigned" && presign.json?.upload?.url) {
+            const upload = presign.json.upload;
+            const put = await fetch(upload.url, {
+                method: upload.method || "PUT",
+                headers: upload.headers || {},
+                body: new Uint8Array(buffer)
+            });
+            if (!put.ok)
+                throw new Error(`inspiration-add upload failed with HTTP ${put.status}.`);
+        }
+        else {
+            const form = new FormData();
+            form.append("file", new Blob([new Uint8Array(buffer)], { type: contentType }), fileName);
+            const res = await fetch(new URL(presign.json?.upload?.url || "/discover/templates/upload", ctx.host), {
+                method: "POST",
+                headers: buildAuthHeaders(ctx.auth),
+                body: form
+            });
+            const json = await res.json().catch(() => null);
+            if (!res.ok || !json?.storage_key) {
+                throw new Error(`inspiration-add upload failed with HTTP ${res.status}${json?.error ? `: ${json.error}` : ""}.`);
+            }
+            storageKey = json.storage_key;
+            uploadedName = json.file_name || fileName;
+        }
+        if (!storageKey)
+            throw new Error("inspiration-add upload did not return a storage key.");
+        const result = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: "/discover/templates",
+            auth: ctx.auth,
+            body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: parsed.values.title, tagline: parsed.values.tagline, notes: parsed.values.notes }
+        });
+        assertApiOk(result, "inspiration-add");
+        emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
+        return;
+    }
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
         path: "/discover/templates",
         auth: ctx.auth,
-        body: { source_url: sourceUrl, tagline: parsed.values.tagline, notes: parsed.values.notes }
+        body: { source_url: source, tagline: parsed.values.tagline, notes: parsed.values.notes }
     });
     assertApiOk(result, "inspiration-add");
     emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
@@ -1375,25 +1466,7 @@ async function pollPrimitiveJob(ctx, jobId) {
 // Upload a local file to the ephemeral temp store, returning its durable URL.
 // Used to turn `--ref @local.png` into a direct asset URL for reference images.
 async function uploadTempFileForRef(ctx, absPath) {
-    if (!existsSync(absPath))
-        throw new Error(`No such reference file: ${absPath}`);
-    const form = new FormData();
-    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
-    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
-    const text = await res.text();
-    let json = null;
-    try {
-        json = text ? JSON.parse(text) : null;
-    }
-    catch {
-        json = null;
-    }
-    if (!res.ok)
-        throw new Error(`reference upload failed (${res.status}): ${text.slice(0, 200)}`);
-    const url = json?.file?.view_url ?? json?.file?.s3_url;
-    if (!url)
-        throw new Error("reference upload returned no durable URL.");
-    return url;
+    return uploadLocalToTempStore(ctx, absPath);
 }
 // Resolve --ref values: pass http(s) URLs through; upload @local files.
 async function resolveReferenceUrls(ctx, refs) {
@@ -1431,6 +1504,100 @@ function resolveCompositionHtmlPath(target) {
         throw new Error(`No such composition file or dir: ${abs}.`);
     return abs;
 }
+// ── Local file paths as media (no S3 upload) ────────────────────────────────
+// Power users bulk-building compositions want to reference media that lives on
+// their own disk WITHOUT uploading every asset to Vidfarm storage. Two cases:
+//
+//   1. The composition is a `vidfarm serve` working copy (its path runs through
+//      <data-dir>/storage/compositions/forks/<forkId>/working/). That box renders
+//      IN-PROCESS for free and serves /storage/:key off local disk, so we just
+//      copy the file into the same disk store and reference it by the box's own
+//      localhost URL. Nothing ever touches S3.
+//   2. Any other composition dir (e.g. a `vidfarm pull` dir headed for cloud
+//      render/publish). The cloud renderer can't reach the user's disk, so a
+//      local file has to become a durable URL — we upload it to the EPHEMERAL
+//      temp store, namescoped under a folder (default `temp/`) so it stays easy
+//      to find and purge instead of bloating the durable library.
+//
+// A localhost /storage URL only resolves against the serve box that owns the
+// file, so case-1 compositions are for local render/preview; to render in the
+// cloud or share, upload the media (case 2) instead.
+// Read the durable URL out of a temporary-files upload response, tolerating both
+// the camelCase (viewUrl/s3Url) and snake_case (view_url/s3_url) shapes the API
+// has used across versions.
+function readUploadedFileUrl(json) {
+    const file = json?.file ?? {};
+    return file.viewUrl ?? file.view_url ?? file.s3Url ?? file.s3_url ?? null;
+}
+// If `htmlPath` sits inside a `vidfarm serve` disk store, return that store's
+// root (`<data-dir>/storage`); otherwise null. Detected structurally from the
+// canonical working-copy layout rather than any running server.
+function findServeStorageRoot(htmlPath) {
+    const norm = path.resolve(htmlPath);
+    const marker = `${path.sep}storage${path.sep}compositions${path.sep}forks${path.sep}`;
+    const idx = norm.indexOf(marker);
+    if (idx === -1)
+        return null;
+    return norm.slice(0, idx + `${path.sep}storage`.length);
+}
+// Copy a local media file into a serve box's disk store under a public-read key
+// and return that storage key. The key is stable-random so re-placing the same
+// file never collides.
+function importLocalMediaToServeStore(storageRoot, absFile) {
+    const safeName = path.basename(absFile).replace(/[^\w.\-]+/g, "_") || "media.bin";
+    const key = `users/local-media/${randomUUID()}/${safeName}`;
+    const dest = path.join(storageRoot, ...key.split("/"));
+    mkdirSync(path.dirname(dest), { recursive: true });
+    copyFileSync(absFile, dest);
+    return key;
+}
+function serveStorageUrl(baseUrl, key) {
+    return `${trimTrailingSlash(baseUrl)}/storage/${encodeURIComponent(key)}`;
+}
+// Upload a local file to the EPHEMERAL temp store on ctx.host, optionally
+// namescoped under a folder, and return its durable URL.
+async function uploadLocalToTempStore(ctx, absPath, folder) {
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
+    if (folder)
+        form.append("folder_path", folder);
+    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    if (!res.ok)
+        throw new Error(`local media upload failed (${res.status}): ${text.slice(0, 200)}`);
+    const url = readUploadedFileUrl(json);
+    if (!url)
+        throw new Error("local media upload returned no durable URL.");
+    return url;
+}
+// Turn a --src value (http(s) URL or local file path) into a fetchable media
+// URL, importing/uploading local files as described above.
+async function resolvePlaceableMediaSrc(ctx, rawSrc, opts) {
+    const value = rawSrc.trim();
+    if (/^https?:\/\//i.test(value))
+        return { src: value, origin: "url", detail: null };
+    const abs = path.resolve(process.cwd(), value.startsWith("@") ? value.slice(1) : value);
+    if (!existsSync(abs)) {
+        throw new Error(`place --src "${rawSrc}" is neither an http(s) URL nor an existing local file.`);
+    }
+    const storageRoot = findServeStorageRoot(opts.htmlPath);
+    if (storageRoot) {
+        const key = importLocalMediaToServeStore(storageRoot, abs);
+        return { src: serveStorageUrl(opts.baseUrl, key), origin: "local-serve", detail: key };
+    }
+    const folder = opts.folder ?? "temp";
+    const url = await uploadLocalToTempStore(ctx, abs, folder);
+    return { src: url, origin: "cloud-temp", detail: folder };
+}
 // Apply an insert/replace of a media URL onto a composition.html on disk.
 function placeMediaOnDisk(input) {
     const html = readFileSync(input.htmlPath, "utf8");
@@ -1446,6 +1613,8 @@ function placeMediaOnDisk(input) {
         width: input.width,
         height: input.height,
         objectFit: input.objectFit,
+        kenBurns: input.kenBurns,
+        kenBurnsIntensity: input.kenBurnsIntensity,
         slug: input.slug
     };
     const result = input.replace
@@ -1475,6 +1644,8 @@ async function runGenerateCommand(argv) {
             at: { type: "string" },
             replace: { type: "string" },
             track: { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
             "layer-key": { type: "string" }
         }
     });
@@ -1546,6 +1717,8 @@ async function runGenerateCommand(argv) {
             at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
             replace: parsed.values.replace,
             track: parsed.values.track ? Number(parsed.values.track) : undefined,
+            kenBurns: parsed.values["ken-burns"],
+            kenBurnsIntensity: parsed.values["ken-burns-intensity"] ? Number(parsed.values["ken-burns-intensity"]) : undefined,
             layerKey: parsed.values["layer-key"]
         });
         if (!ctx.json)
@@ -1577,21 +1750,34 @@ async function runPlaceCommand(argv) {
             width: { type: "string" },
             height: { type: "string" },
             "object-fit": { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
             "layer-key": { type: "string" },
-            slug: { type: "string" }
+            slug: { type: "string" },
+            // Local file support: where a serve box serves /storage from, and which
+            // temp folder cloud uploads land under.
+            "base-url": { type: "string" },
+            folder: { type: "string" }
         }
     });
     const target = parsed.positionals[0];
     if (!target)
-        throw new Error("place requires a composition path: `vidfarm place <dir-or-composition.html> --src <url> ...`.");
-    const src = parsed.values.src;
-    if (!src || !/^https?:\/\//i.test(src))
-        throw new Error("place requires --src <direct media URL>.");
+        throw new Error("place requires a composition path: `vidfarm place <dir-or-composition.html> --src <url|file> ...`.");
+    const rawSrc = parsed.values.src;
+    if (!rawSrc)
+        throw new Error("place requires --src <media URL or local file path>.");
     const ctx = commonContext(parsed.values);
     const htmlPath = resolveCompositionHtmlPath(target);
+    const baseUrl = parsed.values["base-url"] ?? "http://localhost:3000";
+    const resolvedSrc = await resolvePlaceableMediaSrc(ctx, rawSrc, {
+        htmlPath,
+        baseUrl,
+        folder: parsed.values.folder
+    });
+    const src = resolvedSrc.src;
     const kind = parsed.values.kind === "video" || parsed.values.kind === "image"
         ? parsed.values.kind
-        : inferMediaKindFromUrl(src);
+        : inferMediaKindFromUrl(rawSrc);
     const num = (v) => (v !== undefined ? Number(v) : undefined);
     const placement = placeMediaOnDisk({
         htmlPath,
@@ -1606,13 +1792,21 @@ async function runPlaceCommand(argv) {
         width: num(parsed.values.width),
         height: num(parsed.values.height),
         objectFit: parsed.values["object-fit"],
+        kenBurns: parsed.values["ken-burns"],
+        kenBurnsIntensity: num(parsed.values["ken-burns-intensity"]),
         layerKey: parsed.values["layer-key"],
         slug: parsed.values.slug
     });
     if (ctx.json) {
-        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, timeline_gaps: placement.gaps });
+        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, src, media_origin: resolvedSrc.origin, timeline_gaps: placement.gaps });
     }
     else {
+        if (resolvedSrc.origin === "local-serve") {
+            console.log(`${DIM}Local file → serve disk store (${resolvedSrc.detail}); referenced as ${src}. No S3 upload. Renders on this serve box only.${RESET}`);
+        }
+        else if (resolvedSrc.origin === "cloud-temp") {
+            console.log(`${DIM}Local file → uploaded to ephemeral temp store under "${resolvedSrc.detail}/" on ${ctx.host}; referenced as ${src}.${RESET}`);
+        }
         console.log(`${GREEN}Placed ${kind} as ${placement.layerKey}${parsed.values.replace ? ` (replaced ${parsed.values.replace})` : ""} in ${htmlPath}.${RESET}`);
         console.log(`${DIM}Remaining timeline gaps: ${placement.gaps.length ? placement.gaps.map((g) => `${g.start}-${g.end}s`).join(", ") : "none"}.${RESET}`);
         console.log(`${DIM}Publish with: vidfarm publish --dir ${path.dirname(htmlPath)} --fork <forkId>  (or it live-morphs under \`serve\`).${RESET}`);
@@ -1706,6 +1900,7 @@ async function runApproveCommand(argv) {
             caption: { type: "string" },
             title: { type: "string" },
             pinned: { type: "string" },
+            folder: { type: "string" },
             tracer: { type: "string" }
         }
     });
@@ -1713,11 +1908,21 @@ async function runApproveCommand(argv) {
     const caption = parsed.values.caption;
     if (!caption)
         throw new Error("approve requires --caption <text>.");
+    // An approved post is a shareable cloud page, so any media must be a durable
+    // URL the page can load. Pass an http(s) URL through; a local file is uploaded
+    // to the ephemeral temp store (default folder `temp/`) first.
+    const uploadFolder = parsed.values.folder ?? "temp";
+    const resolveApproveMedia = async (value) => {
+        if (/^https?:\/\//i.test(value.trim()))
+            return value.trim();
+        const abs = path.resolve(process.cwd(), value.trim());
+        return uploadLocalToTempStore(ctx, abs, uploadFolder);
+    };
     const media = [];
     if (parsed.values.video)
-        media.push({ url: parsed.values.video, kind: "video", role: "primary" });
+        media.push({ url: await resolveApproveMedia(String(parsed.values.video)), kind: "video", role: "primary" });
     for (const url of parsed.values.media ?? [])
-        media.push({ url });
+        media.push({ url: await resolveApproveMedia(String(url)) });
     if (media.length === 0) {
         console.warn(`${DIM}[vidfarm] no --video / --media given; approving a text-only post.${RESET}`);
     }
@@ -1883,7 +2088,7 @@ async function runUploadCommand(argv) {
     }
     const result = { status: res.status, ok: res.ok, json, text };
     assertApiOk(result, "upload");
-    emitResult(result, ctx.json, [["Durable URL ", result.json?.file?.view_url ?? result.json?.file?.s3_url]]);
+    emitResult(result, ctx.json, [["Durable URL ", readUploadedFileUrl(result.json)]]);
 }
 async function runDownloadCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });

package/dist/src/composition-runtime.js

@@ -146,6 +146,31 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     }
   }
 
+  // Ken Burns image clips carry a CSS transform animation (vf-kb-* keyframes)
+  // directly on the [data-kenburns] <img>. CSS animations run on the wall clock,
+  // not player time, so the runtime scrubs them: pause + set currentTime from
+  // normalized clip progress. Normalizing against data-duration (instead of
+  // trusting the inline --vf-kb-dur) keeps the preview correct even while a
+  // timeline resize has not yet re-synced the inline duration.
+  function syncKenBurnsClip(clip, timing) {
+    if (typeof clip.getAnimations !== "function") return;
+    const progress = timing.duration > 0
+      ? Math.max(0, Math.min(1, (time - timing.start) / timing.duration))
+      : 0;
+    let anims = [];
+    try { anims = clip.getAnimations({ subtree: true }); } catch { return; }
+    for (const anim of anims) {
+      if (typeof anim.animationName !== "string" || anim.animationName.indexOf("vf-kb-") !== 0) continue;
+      let total = 0;
+      try { total = Number(anim.effect?.getComputedTiming?.().duration) || 0; } catch {}
+      if (!total) continue;
+      try {
+        anim.pause();
+        anim.currentTime = progress * total;
+      } catch {}
+    }
+  }
+
   function apply(nextTime, options = {}) {
     const forceSeek = Boolean(options.forceSeek);
     const fromClock = Boolean(options.fromClock);
@@ -160,6 +185,7 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
         } else {
           setVisibility(clip, active);
         }
+        if (clip.hasAttribute("data-kenburns")) syncKenBurnsClip(clip, timing);
       }
       if (clip instanceof HTMLMediaElement) {
         applyMediaState(clip);

package/dist/src/devcli/composition-edit.js

@@ -6,6 +6,9 @@
 // pushes them identically to a browser-made edit. Pure DOM (linkedom) — no
 // ffmpeg, no network.
 import { parseHTML } from "linkedom";
+const KEN_BURNS_PRESETS = new Set([
+    "zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right"
+]);
 const round3 = (v) => Number(v.toFixed(3));
 const clampPercent = (v) => Math.min(100, Math.max(0, v));
 function serialize(document) {
@@ -209,6 +212,15 @@ function buildMediaClip(document, opts, id, track, geom) {
         node.setAttribute("data-playback-start", ps);
         styles.push("background:#050604");
     }
+    else if (opts.kenBurns && KEN_BURNS_PRESETS.has(opts.kenBurns)) {
+        // Ken Burns lives on the <img> itself (see src/hyperframes/composition.ts):
+        // data-kenburns picks the keyframes; the inline vars supply span + strength.
+        node.setAttribute("data-kenburns", opts.kenBurns);
+        styles.push(`--vf-kb-dur:${round3(geom.duration)}s`);
+        if (opts.kenBurnsIntensity !== undefined && Number.isFinite(opts.kenBurnsIntensity)) {
+            styles.push(`--vf-kb-amount:${Math.max(0.04, Math.min(0.5, opts.kenBurnsIntensity))}`);
+        }
+    }
     node.setAttribute("style", `${styles.join(";")};`);
     return node;
 }

package/dist/src/editor-chat.js

@@ -77,6 +77,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "If the composition brief's cast is absent or empty, or the referenced person is not in it, fall back to extracting a still yourself: call GET /api/v1/compositions/:forkId/remove-video-captions to pick the correct source video, then POST /api/v1/primitives/videos/extract-frame with source_video_url set to that URL and at_ms at a moment the person is clearly on screen (use video_context scene timings), then feed the returned image URL as generate_layer input_references (video) or prompt_attachments (image) exactly as above. Prefer the cast reference_url when present because it is already isolated from other people and reusable.",
         "When placing generated character media on the timeline, prefer generate_layer (it applies the placement rules for you): to drop the character into a blank moment use intent='fill_gap' with start/duration on a timeline_gaps span; to swap them into an existing scene use intent='replace_layer' with replace_layer_key (its timing and full-canvas geometry are copied automatically). Always set aspect_ratio to the canvas (e.g. 9:16 for vertical) so the clip fills the frame. Only when you already have a finished media URL should you fall back to add_layer with explicit collision-free start/duration and full-canvas geometry (x=0, y=0, width=100, height=100) for a timeline-proxy/full-canvas replacement.",
         "Use set_layer_visual for geometry (x, y, width, height in %, plus font_size and border_radius in px). Use set_layer_style for text/color styling (color, background, background_style plain|outline|highlight-solid|highlight-translucent, font_family, font_weight, italic, underline, text_align, border_radius, font_size). Use set_layer_media to swap src, volume, muted, playback_start, or object_fit on media layers. Use set_layer_timing for start, duration, track index, playback_start.",
+        "KEN BURNS / ANIMATE STILL IMAGES: every still-image layer supports a built-in Ken Burns effect — a slow pan or zoom that spans the clip's full duration in both the preview and the final render. Apply it with editor_action set_layer_media and the ken_burns field (presets: zoom-in, zoom-out, pan-left, pan-right, pan-up, pan-down, zoom-in-left, zoom-in-right; 'none' removes it), optionally ken_burns_intensity (0.04-0.5, default 0.18; ~0.1 subtle, ~0.3 dramatic). When the user says 'animate the images', 'make the photos move', 'ken burns', or similar, apply a preset to EVERY still-image layer in one pass (one set_layer_media call per layer), varying presets across adjacent clips — e.g. zoom-in, then pan-left, then zoom-out — so consecutive stills don't repeat the same motion. Zoom presets suit subjects centered in frame (products, faces); pan presets suit wide scenery or tall screenshots. You can also seed ken_burns directly on add_layer (kind=image) or generate_layer (media_type=image) so freshly placed stills arrive already animated. It only applies to image layers — never set it on video, text, or audio.",
         "Use duplicate_layer to clone an existing layer; supply layer_key for the source, and optionally start/duration/track/label on the duplicate. Use split_layer with layer_key and split_time to cut at a moment in the timeline. Use group_layers with layer_keys (>=2) and optional group_label; ungroup_layers with layer_keys of any grouped members.",
         "Prefer one editor_action call per mutation. For a multi-layer composition, sequence calls: generate or fetch each asset, then add or edit each layer with its own editor_action call. Chain edits by reusing the layer_key you assigned during add_layer.",
         "Layer/track ordering is the ONLY thing that controls visual stacking. `track` is both the timeline layer index AND the CSS z-index — the editor forces `z-index = track` on every layer at publish time. Higher track draws visually on top; lower track draws underneath. There is no separate z-index override — if the AI wants a layer above another, give it a higher track. If html/text overlays should sit ABOVE a video/image, their track must be a larger integer than the visual media below them.",

package/dist/src/frontend/homepage-client.js

@@ -142,21 +142,76 @@ function HomepageClientApp({ boot }) {
     }, [refreshFeed]);
     const handleAddTemplate = useCallback(async (submission) => {
         try {
+            // Upload path: presign → PUT the bytes (straight to S3, or the local
+            // multipart fallback) → finalize with the storage key. The URL path
+            // posts source_url directly, exactly as before.
+            let uploadRef = null;
+            if (submission.file) {
+                const file = submission.file;
+                const presignResponse = await fetch("/discover/templates/upload/presign", {
+                    method: "POST",
+                    credentials: "same-origin",
+                    headers: { "content-type": "application/json", Accept: "application/json" },
+                    body: JSON.stringify({
+                        file_name: file.name,
+                        content_type: file.type || null,
+                        size_bytes: file.size
+                    })
+                });
+                const presign = await presignResponse.json().catch(() => ({}));
+                if (!presignResponse.ok) {
+                    return { ok: false, error: presign.error || "Unable to start the video upload." };
+                }
+                if (presign.transport === "presigned" && presign.upload?.url && presign.storage_key) {
+                    const put = await fetch(presign.upload.url, {
+                        method: presign.upload.method || "PUT",
+                        headers: presign.upload.headers || {},
+                        body: file
+                    });
+                    if (!put.ok) {
+                        return { ok: false, error: `Video upload failed (${put.status}). Try again.` };
+                    }
+                    uploadRef = { storage_key: presign.storage_key, file_name: presign.file_name || file.name };
+                }
+                else {
+                    const form = new FormData();
+                    form.append("file", file, presign.file_name || file.name);
+                    const direct = await fetch(presign.upload?.url || "/discover/templates/upload", {
+                        method: "POST",
+                        credentials: "same-origin",
+                        body: form
+                    });
+                    const directPayload = await direct.json().catch(() => ({}));
+                    if (!direct.ok || !directPayload.storage_key) {
+                        return { ok: false, error: directPayload.error || "Video upload failed. Try again." };
+                    }
+                    uploadRef = { storage_key: directPayload.storage_key, file_name: directPayload.file_name || file.name };
+                }
+            }
             const response = await fetch("/discover/templates", {
                 method: "POST",
                 credentials: "same-origin",
                 headers: { "content-type": "application/json", Accept: "application/json" },
-                body: JSON.stringify({
-                    source_url: submission.sourceUrl,
-                    tagline: submission.tagline || null,
-                    notes: submission.notes || null
-                })
+                body: JSON.stringify(uploadRef
+                    ? {
+                        upload: uploadRef,
+                        title: submission.title || null,
+                        tagline: submission.tagline || null,
+                        notes: submission.notes || null
+                    }
+                    : {
+                        source_url: submission.sourceUrl,
+                        tagline: submission.tagline || null,
+                        notes: submission.notes || null
+                    })
             });
             const payload = await response.json().catch(() => ({}));
             if (!response.ok) {
                 return { ok: false, error: typeof payload.error === "string" && payload.error ? payload.error : "Unable to add that video." };
             }
-            debugLog("homepage.template_added", { source_url: submission.sourceUrl });
+            debugLog("homepage.template_added", uploadRef
+                ? { storage_key: uploadRef.storage_key }
+                : { source_url: submission.sourceUrl });
             await refreshFeed();
             return { ok: true };
         }