@mevdragon/vidfarm-devcli 0.7.0 → 0.8.0

package/dist/src/app.js

@@ -21,13 +21,14 @@ import { writeForkManifest } from "./services/fork-manifest.js";
 import { renderHelpPage } from "./help-page.js";
 import { renderHomepage } from "./homepage.js";
 import { COMPOSITION_RUNTIME_SCRIPT_BODY } from "./composition-runtime.js";
+import { KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER } from "./hyperframes/composition.js";
 import { normalizeCompositionZIndexHtml, sanitizeCompositionHtml } from "./services/composition-sanitize.js";
 import { applyMarkupUsd } from "./services/billing-pricing.js";
 import { primitiveRegistry } from "./primitive-registry.js";
 import { decryptString, encryptString, hashSecret, safeEqualHash } from "./lib/crypto.js";
 import { devErrorFields, devLog } from "./lib/dev-log.js";
 import { displayNameFromEmail } from "./lib/display-name.js";
-import { createId } from "./lib/ids.js";
+import { createId, createIdV7 } from "./lib/ids.js";
 import { resolveRootFileCandidates } from "./lib/package-root.js";
 import { stripTrackingParams } from "./lib/url-clean.js";
 import { addSeconds, nowIso } from "./lib/time.js";
@@ -44,7 +45,12 @@ import { ServerlessProviderKeyService } from "./services/serverless-provider-key
 import { ServerlessTemplateConfigService } from "./services/serverless-template-configs.js";
 import { parseHTML } from "linkedom";
 import { joinStorageKey, StorageService } from "./services/storage.js";
-import { analyzeCastMembers, buildSmartDecomposedHtml, HyperframesService, smartDecomposeVideo, stampCompositionIdentity } from "./services/hyperframes.js";
+import { SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
+import { clipRecords, makeUserPreset } from "./services/clip-records.js";
+import { matchScenesToClips, searchUserClips } from "./services/clip-search.js";
+import { BUILTIN_PRESETS, ClipModelClient, estimateScanCostFromDuration } from "./services/clip-curation/index.js";
+import { analyzeCastMembers, annotateScenesFromSource, buildSmartDecomposedHtml, HyperframesService, smartDecomposeVideo, stampCompositionIdentity } from "./services/hyperframes.js";
+import { buildPendingSceneAnnotationsState } from "./services/scene-annotations.js";
 import { createPrimitiveJobContext } from "./primitive-context.js";
 import { buildPendingCastState, castMemberFromRaw, extractCastStill, isolateCastMember } from "./services/cast.js";
 import { MediaDurationExceededError, probeMediaAsset } from "./services/media-processing.js";
@@ -74,6 +80,7 @@ const COMPOSITIONS_PREFIX = `${API_PREFIX}/compositions`;
 const INSPIRATIONS_PREFIX = `${API_PREFIX}/inspirations`;
 const VIDEOS_PREFIX = `${API_PREFIX}/videos`;
 const PRIMITIVES_PREFIX = `${API_PREFIX}/primitives`;
+const CLIPS_PREFIX = "/clips";
 const APPROVED_POSTS_PREFIX = `${API_PREFIX}/approved/posts`;
 const APPROVED_POSTS_PUBLIC_PREFIX = "/approved/posts";
 const ACCOUNT_FRONTEND_PREFIX = "/u/:userId";
@@ -4140,6 +4147,8 @@ function createEditorActionTool() {
             background_style: z.enum(["plain", "outline", "highlight-solid", "highlight-translucent"]).optional().describe("Text background treatment."),
             object_fit: z.string().optional().describe("CSS object-fit for image/video (cover, contain, fill, none, scale-down)."),
             object_position: z.string().optional().describe("CSS object-position for image/video (e.g., center, top, bottom left)."),
+            ken_burns: z.enum(["zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right", "none"]).optional().describe("Ken Burns motion for still-image layers: a slow pan/zoom spanning the clip's full duration. Apply with set_layer_media on an existing image, or seed it on add_layer/generate_layer when kind/media_type is image. 'none' removes the effect. When the user says 'animate the images' / 'ken burns', apply it to every still image, varying presets across adjacent clips (zoom-in, pan-left, zoom-out, ...) for a documentary feel."),
+            ken_burns_intensity: z.number().optional().describe("Ken Burns strength: extra zoom / pan travel as a fraction of the frame, 0.04-0.5 (default 0.18; ~0.1 subtle, ~0.3 dramatic). Only meaningful alongside ken_burns."),
             volume: z.number().optional().describe("Volume 0..1 for audio/video."),
             muted: z.boolean().optional().describe("Toggle mute on audio/video."),
             group_label: z.string().optional().describe("Optional label for group_layers."),
@@ -4514,6 +4523,21 @@ function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
             rewritten = `${rewritten}\n${runtimeTag}`;
         }
     }
+    // Ken Burns keyframes: always available in the editor iframe so toggling
+    // data-kenburns on a layer animates immediately, even for compositions
+    // stored before the builder embedded the stylesheet.
+    if (!rewritten.includes(KEN_BURNS_STYLE_MARKER)) {
+        const kenBurnsTag = `<style data-vf-kenburns="true">${KEN_BURNS_CSS}</style>`;
+        if (/<\/head>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/head>/i, `${kenBurnsTag}\n</head>`);
+        }
+        else if (/<\/body>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/body>/i, `${kenBurnsTag}\n</body>`);
+        }
+        else {
+            rewritten = `${rewritten}\n${kenBurnsTag}`;
+        }
+    }
     return rewritten;
 }
 async function renderHyperframesStudioEditorPage(input) {
@@ -4806,7 +4830,10 @@ function buildTemplateHomepageEntry(template) {
     if (!template.videoUrl)
         return null;
     const isPrivate = template.visibility === "private";
-    const title = isPrivate ? (template.title || template.id) : template.id;
+    // Older records stored the source host ("youtube.com") as a title fallback —
+    // never show that as a card title; the template id is the canonical default.
+    const storedTitle = template.title && template.title !== template.sourceHost ? template.title : null;
+    const title = isPrivate ? (storedTitle || template.id) : template.id;
     const previewUrl = template.thumbnailUrl || template.videoUrl || null;
     return {
         title,
@@ -4842,26 +4869,213 @@ const DISCOVER_SUBMISSION_HOSTS = [
 function isSupportedDiscoverSubmissionHost(host) {
     return DISCOVER_SUBMISSION_HOSTS.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
 }
-// Discover "Add Template": ingest a social video URL as a PRIVATE inspiration
-// owned by the caller. The download job runs async; /discover/feed finalizes
-// it and mints the private template once the video lands.
-app.post("/discover/templates", async (c) => {
+// Upload cap for "Add Template → upload a video". Generous relative to the
+// 50 MB My Files cap because template sources are full short-form videos; the
+// bytes go straight to S3 via presigned PUT, never through a Lambda body.
+const INSPIRATION_UPLOAD_MAX_BYTES = 200 * 1024 * 1024;
+function isUploadableInspirationVideo(fileName, contentType) {
+    if (contentType.startsWith("video/"))
+        return true;
+    return [".mp4", ".m4v", ".mov", ".webm"].includes(path.extname(fileName).toLowerCase());
+}
+function isOwnInspirationUploadKey(storageKey, customerId) {
+    return storageKey.startsWith(`users/${customerId}/inspiration-uploads/`);
+}
+// Discover "Add Template" (upload, step 1 of 3): mint a write target for a
+// local video file. Contract shared by web + devcli: presign here (JSON), PUT
+// (or multipart-fallback POST) the bytes, then POST /discover/templates with
+// { upload: { storage_key, file_name } } to queue the ingest. In `vidfarm
+// serve` cloud-passthrough mode this proxies upstream so the client PUTs
+// straight to cloud S3 and the ingest lands in the cloud account — multipart
+// bodies can't proxy (text-only proxy), so proxying the presign avoids ever
+// needing to.
+app.post("/discover/templates/upload/presign", async (c) => {
     const customer = await requireBrowserCustomer(c);
     if (!customer)
         return c.json({ ok: false, error: "Log in to add templates." }, 401);
-    // Cloud passthrough (vidfarm serve): Add Template ingests into the CLOUD
-    // account — the download job, billing, and catalog entry all live upstream,
-    // and the proxied /discover/feed finalizes it. Local ingest only happens
-    // when no upstream key is configured.
     if (hasUpstreamKey()) {
         const proxied = await proxyRequestToUpstream(c);
         if (proxied)
             return proxied;
     }
     const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
+    const fileName = sanitizeFileName(readNonEmptyString(body.file_name) ?? "upload.mp4");
+    const contentType = readNonEmptyString(body.content_type) ?? inferAttachmentContentType(fileName);
+    if (!isUploadableInspirationVideo(fileName, contentType)) {
+        return c.json({ ok: false, error: "Upload a video file (MP4, MOV, or WebM)." }, 400);
+    }
+    const sizeBytes = Number(body.size_bytes);
+    if (Number.isFinite(sizeBytes) && sizeBytes > INSPIRATION_UPLOAD_MAX_BYTES) {
+        return c.json({ ok: false, error: "Video uploads can be at most 200 MB." }, 400);
+    }
+    const uploadId = randomUUID();
+    const storageKey = storage.inspirationUploadKey(customer.id, uploadId, fileName);
+    if (config.STORAGE_DRIVER !== "s3") {
+        return c.json({
+            transport: "server",
+            upload_id: uploadId,
+            file_name: fileName,
+            content_type: contentType,
+            storage_key: storageKey,
+            upload: {
+                method: "POST",
+                url: "/discover/templates/upload",
+                form_field: "file"
+            }
+        });
+    }
+    const upload = await storage.createWriteUrl(storageKey, { contentType, expiresIn: 3600 });
+    return c.json({
+        transport: "presigned",
+        upload_id: uploadId,
+        file_name: fileName,
+        content_type: contentType,
+        storage_key: storageKey,
+        upload: {
+            method: upload.method,
+            url: upload.url,
+            headers: upload.headers,
+            expires_in_seconds: upload.expiresIn
+        }
+    });
+});
+// Upload step 2 (multipart fallback): only used when presign returned
+// transport "server" — i.e. the local storage driver (vidfarm serve without
+// S3). Deliberately not proxied upstream: the upstream proxy is text-only,
+// and in passthrough mode the presign already handed the client a direct
+// cloud target.
+app.post("/discover/templates/upload", async (c) => {
+    const customer = await requireBrowserCustomer(c);
+    if (!customer)
+        return c.json({ ok: false, error: "Log in to add templates." }, 401);
+    const formData = await c.req.formData().catch(() => null);
+    const file = formData?.get("file");
+    if (!isFormFile(file))
+        return c.json({ ok: false, error: "Select a video file to upload." }, 400);
+    const fileName = sanitizeFileName(file.name || "upload.mp4");
+    const contentType = file.type || inferAttachmentContentType(fileName);
+    if (!isUploadableInspirationVideo(fileName, contentType)) {
+        return c.json({ ok: false, error: "Upload a video file (MP4, MOV, or WebM)." }, 400);
+    }
+    const buffer = Buffer.from(await file.arrayBuffer());
+    if (buffer.byteLength > INSPIRATION_UPLOAD_MAX_BYTES) {
+        return c.json({ ok: false, error: "Video uploads can be at most 200 MB." }, 400);
+    }
+    const uploadId = randomUUID();
+    const storageKey = storage.inspirationUploadKey(customer.id, uploadId, fileName);
+    const stored = await storage.putBuffer(storageKey, buffer, contentType);
+    return c.json({
+        ok: true,
+        storage_key: storageKey,
+        file_name: fileName,
+        content_type: contentType,
+        size_bytes: buffer.byteLength,
+        url: stored.url
+    }, 201);
+});
+// Discover "Add Template": ingest a social video URL — or a video the caller
+// just uploaded via the presign/upload pair above — as a PRIVATE inspiration
+// owned by the caller. The download/ingest job runs async; /discover/feed
+// finalizes it and mints the private template once the video lands.
+app.post("/discover/templates", async (c) => {
+    const customer = await requireBrowserCustomer(c);
+    if (!customer)
+        return c.json({ ok: false, error: "Log in to add templates." }, 401);
+    const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
+    const uploadRef = asRecord(body.upload);
+    const uploadStorageKey = readNonEmptyString(uploadRef?.storage_key);
+    // Cloud passthrough (vidfarm serve): Add Template ingests into the CLOUD
+    // account — the download/ingest job, billing, and catalog entry all live
+    // upstream, and the proxied /discover/feed finalizes it. The one exception:
+    // an upload key minted by THIS box (local presign fallback while upstream
+    // was unreachable) — its bytes only exist locally, so ingest locally.
+    if (hasUpstreamKey() && !(uploadStorageKey && isOwnInspirationUploadKey(uploadStorageKey, customer.id))) {
+        const proxied = await proxyRequestToUpstream(c);
+        if (proxied)
+            return proxied;
+    }
+    if (uploadStorageKey) {
+        if (!isOwnInspirationUploadKey(uploadStorageKey, customer.id)) {
+            return c.json({ ok: false, error: "That upload doesn't belong to this account." }, 403);
+        }
+        const uploadUrl = storage.getPublicUrl(uploadStorageKey);
+        if (!uploadUrl)
+            return c.json({ ok: false, error: "Uploaded video could not be resolved." }, 400);
+        const explicitTitle = readNonEmptyString(body.title) ?? null;
+        const tagline = readNonEmptyString(body.tagline) ?? readNonEmptyString(body.trend_tagline) ?? null;
+        const notes = readNonEmptyString(body.notes) ?? null;
+        const uploadFileName = readNonEmptyString(uploadRef?.file_name) ?? null;
+        const primitive = primitiveRegistry.get("primitive:video_ingest");
+        if (!primitive)
+            return c.json({ ok: false, error: "Video ingest primitive not available" }, 500);
+        const operation = primitive.operations["run"];
+        if (!operation)
+            return c.json({ ok: false, error: "Video ingest operation not available" }, 500);
+        // Only a caller-chosen title flows into the manifest — never the file
+        // name. An untitled upload finalizes with title null so its /discover
+        // card displays the minted template id.
+        const payload = operation.inputSchema.parse({
+            source_video_url: uploadUrl,
+            title: explicitTitle ?? tagline ?? undefined,
+            file_name: uploadFileName ?? undefined,
+            save_manifest: true
+        });
+        let job;
+        try {
+            await assertWalletCanQueueJobs(customer.id);
+            job = await jobs.createRootJob({
+                templateId: primitive.id,
+                operationName: "run",
+                workflowName: operation.workflow,
+                tracer: `discover_template_upload:${customer.id}`,
+                payload,
+                webhookUrl: null,
+                customer,
+                providerHint: undefined
+            });
+        }
+        catch (error) {
+            if (error instanceof InsufficientWalletFundsError)
+                return insufficientFundsResponse(c, error);
+            if (error instanceof ActiveJobLimitExceededError)
+                return activeJobLimitExceededResponse(c, error);
+            throw error;
+        }
+        // No Step Functions worker on a local (vidfarm serve) box — run the ingest
+        // in-process, detached, exactly like local renders. /discover/feed polls
+        // finalize the inspiration when the job lands.
+        if (!config.VIDFARM_JOB_STATE_MACHINE_ARN) {
+            void runPrimitiveJobInProcess(job.id).catch((error) => {
+                console.error("local video ingest failed", job.id, error instanceof Error ? error.message : error);
+            });
+        }
+        // Every upload key is unique (uuid segment), so no dedupe pass: two
+        // uploads of the same file are two intentional inspirations.
+        let inspiration = await serverlessRecords.createInspiration({
+            customerId: customer.id,
+            sourceUrl: uploadUrl,
+            originalUrl: uploadUrl,
+            sourceHost: "upload",
+            downloadJobId: job.id,
+            trendTagline: tagline,
+            visibility: "private",
+            notes
+        });
+        // Pending-card label while the ingest runs: explicit title, else the file
+        // name. Finalize overwrites this from the manifest, so an untitled upload
+        // ends at title null → the card shows the minted template id.
+        const pendingTitle = explicitTitle ?? uploadFileName;
+        if (pendingTitle) {
+            inspiration = (await serverlessRecords.updateInspiration({
+                inspirationId: inspiration.id,
+                patch: { title: pendingTitle }
+            })) ?? inspiration;
+        }
+        return c.json(serializeInspiration(inspiration), 202);
+    }
     const sourceUrl = readNonEmptyString(body.source_url);
     if (!sourceUrl)
-        return c.json({ ok: false, error: "Enter a video URL." }, 400);
+        return c.json({ ok: false, error: "Enter a video URL or upload a video file." }, 400);
     const originalUrl = stripTrackingParams(sourceUrl);
     const sourceHost = safeUrlHostname(originalUrl);
     if (!sourceHost)
@@ -4908,6 +5122,13 @@ app.post("/discover/templates", async (c) => {
             return activeJobLimitExceededResponse(c, error);
         throw error;
     }
+    // Same local-box treatment as the upload branch: no Step Functions worker
+    // means the download job must run in-process or it queues forever.
+    if (!config.VIDFARM_JOB_STATE_MACHINE_ARN) {
+        void runPrimitiveJobInProcess(job.id).catch((error) => {
+            console.error("local video download failed", job.id, error instanceof Error ? error.message : error);
+        });
+    }
     const inspiration = await serverlessRecords.createInspiration({
         customerId: customer.id,
         sourceUrl,
@@ -4975,13 +5196,21 @@ app.delete("/discover/templates/:entryId", async (c) => {
 // client-side via status.
 function buildPendingInspirationHomepageEntry(inspiration) {
     return {
-        title: inspiration.trendTagline || inspiration.title || inspiration.sourceHost || "New template",
+        // Uploads: explicit title (or file name, stored at submit time) outranks
+        // the tagline; URL ingests keep tagline-first.
+        title: (inspiration.sourceHost === "upload"
+            ? (inspiration.title || inspiration.trendTagline)
+            : (inspiration.trendTagline || inspiration.title)) || inspiration.sourceHost || "New template",
         templateId: inspiration.id,
         slugId: inspiration.id,
         difficulty: "easy",
         viralDna: inspiration.status === "failed"
-            ? (inspiration.errorMessage || "Video download failed. Check the URL and try adding it again.")
-            : (inspiration.notes || "Downloading the source video. This card unlocks automatically once it's ready."),
+            ? (inspiration.errorMessage || (inspiration.sourceHost === "upload"
+                ? "Video ingest failed. Try uploading the file again."
+                : "Video download failed. Check the URL and try adding it again."))
+            : (inspiration.notes || (inspiration.sourceHost === "upload"
+                ? "Processing your uploaded video. This card unlocks automatically once it's ready."
+                : "Downloading the source video. This card unlocks automatically once it's ready.")),
         previewUrl: inspiration.thumbnailUrl || "",
         approvedAt: inspiration.createdAt,
         sourceType: inspiration.sourceHost || "social",
@@ -5676,6 +5905,42 @@ async function recordCastLambdaUsage(input) {
         console.error("cast billing failed", error instanceof Error ? error.message : error);
     }
 }
+// Charges the caller's wallet for the lambda compute of one scene-annotation
+// poll (the video download + frame sample + annotation vision call). Idempotent
+// per fork+poll-start so a client re-poll of the same tick never double-charges.
+// Never throws. Mirrors recordCastLambdaUsage.
+async function recordSceneAnnotationsLambdaUsage(input) {
+    const durationMs = Date.now() - input.startedAtMs;
+    const memoryMb = Math.max(128, Number.parseInt(process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE || "2048", 10) || 2048);
+    const gbSeconds = (memoryMb / 1024) * (durationMs / 1000);
+    const LAMBDA_X86_GB_SECOND_USD = 0.0000166667;
+    const LAMBDA_REQUEST_USD = 0.20 / 1_000_000;
+    const lambdaCostUsd = Number(((gbSeconds * LAMBDA_X86_GB_SECOND_USD) + LAMBDA_REQUEST_USD).toFixed(6));
+    if (lambdaCostUsd <= 0)
+        return;
+    try {
+        await billing.record({
+            customerId: input.customerId,
+            jobId: `scene-annotations:${input.forkId}:${input.startedAtMs}`,
+            tracer: null,
+            templateId: "auto-decompose",
+            type: "cpu_estimate",
+            costUsd: lambdaCostUsd,
+            costCenterSlug: "auto_decompose_lambda",
+            idempotencyKey: `scene_annotations_lambda:${input.forkId}:${input.startedAtMs}`,
+            occurredAtMs: Date.now(),
+            metadata: {
+                fork_id: input.forkId,
+                duration_ms: durationMs,
+                memory_mb: memoryMb,
+                gb_seconds: Number(gbSeconds.toFixed(6))
+            }
+        });
+    }
+    catch (error) {
+        console.error("scene-annotations billing failed", error instanceof Error ? error.message : error);
+    }
+}
 async function snapshotForkVersion(input) {
     const version = (input.fork.latestVersion ?? 0) + 1;
     // Bound namespace growth for user-initiated snapshots. Internal reasons
@@ -5692,6 +5957,9 @@ async function snapshotForkVersion(input) {
     // Placement surfaces travel with every version too (reusable decompose
     // metadata, same as cast identification).
     const workingPlacement = await storage.readText(storage.compositionForkWorkingKey(input.fork.id, "product-placement.json"));
+    // Scene annotations (clip-replacement + recreation DNA) likewise travel with
+    // every version — reusable decompose metadata, same as placement surfaces.
+    const workingAnnotations = await storage.readText(storage.compositionForkWorkingKey(input.fork.id, "scene-annotations.json"));
     if (workingHtml) {
         await storage.putText(storage.compositionForkVersionKey(input.fork.id, version, "composition.html"), workingHtml, "text/html; charset=utf-8");
     }
@@ -5704,6 +5972,9 @@ async function snapshotForkVersion(input) {
     if (workingPlacement) {
         await storage.putBuffer(storage.compositionForkVersionKey(input.fork.id, version, "product-placement.json"), Buffer.from(workingPlacement, "utf8"), "application/json");
     }
+    if (workingAnnotations) {
+        await storage.putBuffer(storage.compositionForkVersionKey(input.fork.id, version, "scene-annotations.json"), Buffer.from(workingAnnotations, "utf8"), "application/json");
+    }
     const versionRecord = await serverlessRecords.createForkVersion({
         forkId: input.fork.id,
         ownerCustomerId: input.fork.customerId,
@@ -5794,6 +6065,7 @@ app.post(COMPOSITIONS_PREFIX, async (c) => {
         // identified people + reference stills as the shared default composition.
         const cast = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "cast.json"));
         const placement = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "product-placement.json"));
+        const annotations = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "scene-annotations.json"));
         if (html) {
             await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), html, "text/html; charset=utf-8");
         }
@@ -5806,6 +6078,9 @@ app.post(COMPOSITIONS_PREFIX, async (c) => {
         if (placement) {
             await storage.putBuffer(storage.compositionForkWorkingKey(fork.id, "product-placement.json"), Buffer.from(placement, "utf8"), "application/json");
         }
+        if (annotations) {
+            await storage.putBuffer(storage.compositionForkWorkingKey(fork.id, "scene-annotations.json"), Buffer.from(annotations, "utf8"), "application/json");
+        }
     }
     else if (template.videoUrl) {
         // Template exists but has no canonical fork yet — seed with raw HTML.
@@ -6170,6 +6445,20 @@ app.post(`${INSPIRATIONS_PREFIX}/:inspirationId/decompose`, async (c) => {
             catch (placementPersistError) {
                 console.error("inspiration product-placement persist failed", placementPersistError instanceof Error ? placementPersistError.message : placementPersistError);
             }
+            // Seed the scene-annotation pass "pending" on the canonical fork too,
+            // before the snapshot, so the pending state travels with v1 and every
+            // downstream fork can drive /scene-annotations-poll (or inherit the
+            // completed annotations once the canonical fork's poll finishes).
+            try {
+                await storage.putJson(storage.compositionForkWorkingKey(canonicalFork.id, "scene-annotations.json"), buildPendingSceneAnnotationsState({
+                    compositionId: canonicalFork.id,
+                    sourceUrl,
+                    title
+                }));
+            }
+            catch (annotationSeedError) {
+                console.error("inspiration scene-annotations seed failed", annotationSeedError instanceof Error ? annotationSeedError.message : annotationSeedError);
+            }
             await writeForkManifest(storage, canonicalFork, { kind: "working" });
             await snapshotForkVersion({
                 fork: canonicalFork,
@@ -6552,6 +6841,21 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         catch (placementPersistError) {
             console.error("product-placement persist failed", placementPersistError instanceof Error ? placementPersistError.message : placementPersistError);
         }
+        // Seed the per-scene clip-annotation pass as "pending" and let the client
+        // drive it via POST /scene-annotations-poll (same async model as cast /
+        // ghostcut). The annotation is its own vision call — running it inline would
+        // risk the ~60s origin timeout on longer videos — and it reads the finalized
+        // scenes back from smart-decompose.json at poll time. Non-fatal.
+        try {
+            await storage.putJson(storage.compositionForkWorkingKey(fork.id, "scene-annotations.json"), buildPendingSceneAnnotationsState({
+                compositionId,
+                sourceUrl: analysisSourceUrl,
+                title: typeof title === "string" ? title : fork.id
+            }));
+        }
+        catch (annotationSeedError) {
+            console.error("scene-annotations seed failed", annotationSeedError instanceof Error ? annotationSeedError.message : annotationSeedError);
+        }
         // Seed the cast-identification 2nd pass as "pending" and let the client
         // drive it via POST /cast-poll (same async model as ghostcut). We identify
         // cast from the same caption-free analysis source the vision pass used, so
@@ -7102,6 +7406,204 @@ app.get(`${COMPOSITIONS_PREFIX}/:forkId/product-placement.json`, async (c) => {
         return c.json({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
     }
 });
+// Read-only scene-annotation context for a fork: the detected content FORMAT
+// plus one annotation per scene carrying the literal + viral DNA needed to
+// (a) match a REPLACEMENT clip from the library (each annotation ships a
+// ready-to-run match_criteria + embedding_text) and (b) let an AI agent
+// RE-CREATE the beat from scratch (recreation_prompt + recreation_notes).
+// Reusable decompose metadata — the editor-chat harness and desktop agents read
+// it to plan clip swaps or regeneration. Optional-auth like /product-placement.json.
+// Returns { status: "none" } when the fork was never decomposed (or predates
+// this pass).
+app.get(`${COMPOSITIONS_PREFIX}/:forkId/scene-annotations.json`, async (c) => {
+    const customer = await getBrowserCustomer(c);
+    try {
+        const access = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: customer?.id ?? null, shareToken: readShareToken(c) }, "view");
+        const text = await storage.readText(storage.compositionForkWorkingKey(access.fork.id, "scene-annotations.json"));
+        if (!text) {
+            return c.json({
+                ok: true,
+                status: "none",
+                hint: "This fork has no scene-annotation pass yet. Run POST /api/v1/compositions/:forkId/auto-decompose to generate scene annotations."
+            });
+        }
+        let state;
+        try {
+            state = JSON.parse(text);
+        }
+        catch {
+            return c.json({ ok: true, status: "none" });
+        }
+        // Surface the pass's own state-machine status (pending/processing/done/
+        // failed) so pollers and agents can tell "not done yet" from "no annotations
+        // found". Annotations/contentFormat are only meaningful once status=="done".
+        return c.json({
+            ok: true,
+            status: state.status,
+            reason: state.failureReason ?? null,
+            provider: state.provider ?? null,
+            model: state.model ?? null,
+            source_url: state.sourceUrl ?? null,
+            duration_seconds: state.durationSeconds ?? null,
+            content_format: state.status === "done" ? state.contentFormat : null,
+            annotation_count: Array.isArray(state.annotations) ? state.annotations.length : 0,
+            annotations: state.status === "done" && Array.isArray(state.annotations) ? state.annotations : []
+        });
+    }
+    catch (error) {
+        if (error instanceof ForkNotFoundError || error instanceof ForkAccessDeniedError)
+            return forkAccessErrorResponse(c, error);
+        return c.json({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
+    }
+});
+// Drives the async scene-annotation pass to completion — one vision call over
+// the finalized scenes (read back from smart-decompose.json) that classifies
+// the content format and annotates every scene with its clip-match + recreation
+// DNA. Mirrors /cast-poll but single-stage: pending -> processing -> done|failed.
+// Terminal states short-circuit (idempotent). On success it also backfills the
+// detected content format onto the template + inspiration metadata.
+app.post(`${COMPOSITIONS_PREFIX}/:forkId/scene-annotations-poll`, async (c) => {
+    const caller = await getBrowserCustomer(c);
+    if (!caller)
+        return c.json({ ok: false, error: "Unauthorized" }, 401);
+    const startedAtMs = Date.now();
+    try {
+        const access = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: caller.id, shareToken: readShareToken(c) }, "edit");
+        const fork = access.fork;
+        const stateKey = storage.compositionForkWorkingKey(fork.id, "scene-annotations.json");
+        const stateText = await storage.readText(stateKey);
+        if (!stateText)
+            return c.json({ ok: true, status: "none" });
+        let state;
+        try {
+            state = JSON.parse(stateText);
+        }
+        catch {
+            return c.json({ ok: true, status: "none" });
+        }
+        // Terminal states — no re-work.
+        if (state.status === "done" || state.status === "failed") {
+            return c.json({
+                ok: true,
+                status: state.status,
+                reason: state.failureReason ?? null,
+                content_format: state.status === "done" ? state.contentFormat : null,
+                annotation_count: Array.isArray(state.annotations) ? state.annotations.length : 0
+            });
+        }
+        // Another poll is already running this fork's (single) vision call — don't
+        // pay for a duplicate. Re-enter only if the in-flight attempt looks stalled.
+        const STALE_PROCESSING_MS = 3 * 60 * 1000;
+        if (state.status === "processing" && Date.now() - (state.savedAtMs ?? 0) < STALE_PROCESSING_MS) {
+            return c.json({ ok: true, status: "pending", note: "in_progress" });
+        }
+        const keys = await loadCustomerVisionKeys(caller.id);
+        if (!(keys.gemini || keys.openai || keys.openrouter)) {
+            const next = { ...state, status: "failed", failureReason: "no_provider_key", savedAtMs: Date.now() };
+            await storage.putJson(stateKey, next);
+            return c.json({ ok: true, status: "failed", reason: "no_provider_key" });
+        }
+        // Read the finalized scenes + viral DNA + summary + transcript from the
+        // decompose snapshot (same source /cast-poll grounds on). Without it there
+        // is nothing to annotate.
+        const smartText = await storage.readText(storage.compositionForkWorkingKey(fork.id, "smart-decompose.json"));
+        if (!smartText) {
+            const next = { ...state, status: "failed", failureReason: "missing_decompose_snapshot", savedAtMs: Date.now() };
+            await storage.putJson(stateKey, next);
+            return c.json({ ok: true, status: "failed", reason: "missing_decompose_snapshot" });
+        }
+        let scenes = [];
+        let viralDna = null;
+        let summary = "";
+        let transcript = null;
+        let userPrompt = null;
+        try {
+            const snapshot = JSON.parse(smartText);
+            scenes = Array.isArray(snapshot.result?.scenes) ? snapshot.result.scenes : [];
+            viralDna = snapshot.result?.viralDna ?? null;
+            summary = typeof snapshot.result?.summary === "string" ? snapshot.result.summary : "";
+            transcript = snapshot.result?.transcript ?? null;
+            userPrompt = typeof snapshot.userPrompt === "string" ? snapshot.userPrompt : null;
+        }
+        catch {
+            const next = { ...state, status: "failed", failureReason: "unreadable_decompose_snapshot", savedAtMs: Date.now() };
+            await storage.putJson(stateKey, next);
+            return c.json({ ok: true, status: "failed", reason: "unreadable_decompose_snapshot" });
+        }
+        if (scenes.length === 0) {
+            // A slideshow/time-slice fork with no real scenes — nothing to annotate.
+            const next = { ...state, status: "done", savedAtMs: Date.now() };
+            await storage.putJson(stateKey, next);
+            return c.json({ ok: true, status: "done", annotation_count: 0 });
+        }
+        // Claim the work so concurrent pollers back off (see the staleness guard).
+        await storage.putJson(stateKey, { ...state, status: "processing", savedAtMs: Date.now() });
+        let outcome;
+        try {
+            outcome = await annotateScenesFromSource({
+                sourceUrl: state.sourceUrl,
+                keys,
+                scenes,
+                viralDna: viralDna ?? { trend_tagline: "", hook: "", retention: "", payoff: "", preserve: [], avoid: [], promotions: [], keywords: [] },
+                summary,
+                transcript,
+                userPrompt
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            const next = { ...state, status: "failed", failureReason: reason, savedAtMs: Date.now() };
+            await storage.putJson(stateKey, next);
+            return c.json({ ok: true, status: "failed", reason });
+        }
+        const next = {
+            ...state,
+            status: "done",
+            provider: outcome.provider,
+            model: outcome.model,
+            durationSeconds: outcome.durationSeconds,
+            contentFormat: outcome.contentFormat,
+            annotations: outcome.annotations,
+            savedAtMs: Date.now()
+        };
+        await storage.putJson(stateKey, next);
+        // Backfill the detected content format onto the template + inspiration
+        // metadata now that we know it (the synchronous decompose couldn't). This is
+        // what the catalog + clip matcher filter on. Best-effort.
+        try {
+            const forkTemplate = fork.templateId ? await serverlessRecords.getTemplate(fork.templateId) : null;
+            if (forkTemplate) {
+                await serverlessRecords.updateTemplate({
+                    templateId: forkTemplate.id,
+                    patch: { contentFormat: outcome.contentFormat.format }
+                });
+                if (forkTemplate.inspirationId) {
+                    await serverlessRecords.updateInspiration({
+                        inspirationId: forkTemplate.inspirationId,
+                        patch: { contentFormat: outcome.contentFormat.format }
+                    });
+                }
+            }
+        }
+        catch (backfillError) {
+            console.error("scene-annotations content-format backfill failed", backfillError instanceof Error ? backfillError.message : backfillError);
+        }
+        await recordSceneAnnotationsLambdaUsage({ customerId: caller.id, forkId: fork.id, startedAtMs });
+        return c.json({
+            ok: true,
+            status: "done",
+            provider: outcome.provider,
+            model: outcome.model,
+            content_format: outcome.contentFormat,
+            annotation_count: outcome.annotations.length
+        });
+    }
+    catch (error) {
+        if (error instanceof ForkNotFoundError || error instanceof ForkAccessDeniedError)
+            return forkAccessErrorResponse(c, error);
+        return c.json({ ok: false, error: error instanceof Error ? error.message : "scene-annotations-poll failed" }, 500);
+    }
+});
 // Drives the async cast-identification 2nd pass one unit of work per call
 // (analyze -> per-member still -> per-member isolation -> done), mirroring
 // /remove-video-captions-poll. Each invocation makes at most one heavy external call so the
@@ -7747,6 +8249,7 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/clone`, async (c) => {
         const json = await readVersionFile("composition.json");
         const cast = await readVersionFile("cast.json");
         const placement = await readVersionFile("product-placement.json");
+        const annotations = await readVersionFile("scene-annotations.json");
         if (html) {
             await storage.putText(storage.compositionForkWorkingKey(cloned.id, "composition.html"), html, "text/html; charset=utf-8");
         }
@@ -7759,6 +8262,9 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/clone`, async (c) => {
         if (placement) {
             await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "product-placement.json"), Buffer.from(placement, "utf8"), "application/json");
         }
+        if (annotations) {
+            await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "scene-annotations.json"), Buffer.from(annotations, "utf8"), "application/json");
+        }
         await snapshotForkVersion({
             fork: cloned,
             callerCustomerId: customer.id,
@@ -7781,8 +8287,15 @@ app.get(`${COMPOSITIONS_PREFIX}/:forkId/versions`, async (c) => {
         const limit = Number.parseInt(c.req.query("limit") ?? "25", 10);
         const cursor = c.req.query("cursor") ?? null;
         const page = await serverlessRecords.listForkVersions({ forkId: access.fork.id, limit, cursor });
+        // Fork content is world-viewable, but the snapshot trail is personal.
+        // /editor parks users without their own fork on the template's shared
+        // default fork, so without this scoping the History modal would list the
+        // fork owner's (i.e. another user's) publish/decompose history.
+        const visible = access.capabilities.isOwner
+            ? page.items
+            : page.items.filter((version) => Boolean(customer && version.createdBy === customer.id));
         return c.json({
-            versions: page.items.map(serializeVersion),
+            versions: visible.map(serializeVersion),
             next_cursor: page.nextCursor
         });
     }
@@ -7945,7 +8458,14 @@ async function finalizeInspirationIfReady(inspiration) {
                 customerId: ready.customerId,
                 originalUrl: ready.originalUrl,
                 sourceHost: ready.sourceHost,
-                title: ready.trendTagline || ready.title || ready.sourceHost || "Untitled",
+                // No host/"Untitled" fallback: a template without an explicit title or
+                // tagline displays as its template id on /discover. For uploads the
+                // manifest title IS the caller's explicit title, so it outranks the
+                // tagline; URL ingests keep tagline-first (manifest title is just the
+                // social post's own caption).
+                title: (ready.sourceHost === "upload"
+                    ? (ready.title || ready.trendTagline)
+                    : (ready.trendTagline || ready.title)) || null,
                 thumbnailUrl: ready.thumbnailUrl,
                 videoUrl: ready.videoUrl,
                 durationSeconds: ready.durationSeconds,
@@ -8138,6 +8658,7 @@ app.post(`${VIDEOS_PREFIX}/:inspirationId/decompose`, async (c) => {
         const json = await readSource("composition.json");
         const cast = await readSource("cast.json");
         const placement = await readSource("product-placement.json");
+        const annotations = await readSource("scene-annotations.json");
         if (html)
             await storage.putText(storage.compositionForkWorkingKey(cloned.id, "composition.html"), html, "text/html; charset=utf-8");
         if (json)
@@ -8146,6 +8667,8 @@ app.post(`${VIDEOS_PREFIX}/:inspirationId/decompose`, async (c) => {
             await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "cast.json"), Buffer.from(cast, "utf8"), "application/json");
         if (placement)
             await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "product-placement.json"), Buffer.from(placement, "utf8"), "application/json");
+        if (annotations)
+            await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "scene-annotations.json"), Buffer.from(annotations, "utf8"), "application/json");
         await snapshotForkVersion({
             fork: cloned,
             callerCustomerId: customer.id,
@@ -10229,6 +10752,13 @@ app.use(`${API_PREFIX}/*`, async (c, next) => {
 });
 app.use(`${USER_PREFIX}/me`, requireAuth);
 app.use(`${USER_PREFIX}/me/*`, requireAuth);
+// The /clips API (feed/search/scan/presets) is auth-gated; the bare /clips path
+// is the public HTML gallery page (like /discover vs /discover/feed). Hono's
+// `/clips/*` also matches the bare `/clips`, so let that one path through
+// unauthenticated.
+const isClipsGalleryPage = (c) => c.req.path === CLIPS_PREFIX || c.req.path === `${CLIPS_PREFIX}/`;
+app.use(`${CLIPS_PREFIX}/*`, (c, next) => (isClipsGalleryPage(c) ? next() : requireAuth(c, next)));
+app.use(`${CLIPS_PREFIX}/*`, (c, next) => (isClipsGalleryPage(c) ? next() : captureApiCallHistory(c, next)));
 app.use(AGENCY_PREFIX, requireAuth);
 app.use(`${AGENCY_PREFIX}/*`, requireAuth);
 app.use(`${API_PREFIX}/rate-limit-status`, requireAuth);
@@ -14405,6 +14935,574 @@ app.post(`${USER_PREFIX}/me/provider-keys`, async (c) => {
     });
     return c.json({ ok: true }, 201);
 });
+// ── Clip curation (the third library: viral DNA + formats + CLIPS) ───────────
+// First-class clips API mirroring the devcli `clips` commands. /clips/* is gated
+// by requireAuth + captureApiCallHistory (middleware above). BYOK Gemini: search
+// and natural-language→criteria use the caller's saved gemini provider key.
+const clipScanSfn = new SFNClient({});
+const BUILTIN_CLIP_PRESET_IDS = new Set(BUILTIN_PRESETS.map((p) => p.preset_id));
+// First-class Clips gallery page (served at /clips). Self-contained HTML; the
+// client fetches /clips/feed, /clips/presets and /clips/search with the session
+// cookie. Standalone browse/search — no video generation required.
+function renderClipsPage() {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Clips — Vidfarm</title>
+<style>
+  :root { --bg:#0b0d12; --panel:#141821; --panel2:#1b2130; --line:#242c3a; --text:#e7ecf5; --dim:#8b96ab; --accent:#5b8cff; --accent2:#3ad6a0; }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--text); font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; }
+  a { color:inherit; text-decoration:none; }
+  header.top { display:flex; align-items:center; gap:22px; padding:14px 24px; border-bottom:1px solid var(--line); position:sticky; top:0; background:rgba(11,13,18,.9); backdrop-filter:blur(8px); z-index:5; }
+  header.top .brand { font-weight:700; letter-spacing:.3px; }
+  header.top nav { display:flex; gap:6px; }
+  header.top nav a { padding:6px 12px; border-radius:8px; color:var(--dim); font-weight:600; }
+  header.top nav a.active, header.top nav a:hover { color:var(--text); background:var(--panel2); }
+  .wrap { max-width:1200px; margin:0 auto; padding:28px 24px 80px; }
+  .hero h1 { font-size:26px; margin:0 0 4px; }
+  .hero p { color:var(--dim); margin:0 0 20px; }
+  .searchbar { display:flex; gap:10px; margin-bottom:14px; }
+  .searchbar input { flex:1; background:var(--panel); border:1px solid var(--line); color:var(--text); border-radius:10px; padding:12px 14px; font-size:15px; outline:none; }
+  .searchbar input:focus { border-color:var(--accent); }
+  .searchbar button { background:var(--accent); color:#fff; border:0; border-radius:10px; padding:0 18px; font-weight:700; cursor:pointer; }
+  .presets { display:flex; flex-wrap:wrap; gap:8px; margin-bottom:22px; }
+  .chip { background:var(--panel); border:1px solid var(--line); color:var(--dim); border-radius:999px; padding:6px 13px; font-size:13px; font-weight:600; cursor:pointer; }
+  .chip:hover, .chip.active { color:var(--text); border-color:var(--accent); }
+  .status { color:var(--dim); font-size:14px; margin-bottom:16px; min-height:20px; }
+  .grid { display:grid; grid-template-columns:repeat(auto-fill,minmax(230px,1fr)); gap:18px; }
+  .card { background:var(--panel); border:1px solid var(--line); border-radius:14px; overflow:hidden; display:flex; flex-direction:column; }
+  .card .thumb { position:relative; aspect-ratio:9/16; background:#000; overflow:hidden; }
+  .card .thumb img, .card .thumb video { width:100%; height:100%; object-fit:cover; display:block; }
+  .card .thumb .range { position:absolute; left:8px; bottom:8px; background:rgba(0,0,0,.7); border-radius:6px; padding:2px 7px; font-size:12px; font-variant-numeric:tabular-nums; }
+  .card .thumb .score { position:absolute; right:8px; top:8px; background:rgba(58,214,160,.15); color:var(--accent2); border:1px solid rgba(58,214,160,.4); border-radius:6px; padding:1px 6px; font-size:11px; font-weight:700; }
+  .card .body { padding:11px 12px 12px; display:flex; flex-direction:column; gap:8px; flex:1; }
+  .card .desc { font-size:13px; color:var(--text); display:-webkit-box; -webkit-line-clamp:2; -webkit-box-orient:vertical; overflow:hidden; }
+  .card .tags { display:flex; flex-wrap:wrap; gap:5px; }
+  .card .tag { font-size:11px; color:var(--dim); background:var(--panel2); border-radius:5px; padding:1px 6px; }
+  .card .row { display:flex; align-items:center; justify-content:space-between; margin-top:auto; }
+  .card .src { font-size:11px; color:var(--dim); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; max-width:60%; }
+  .card a.dl { font-size:12px; font-weight:700; color:var(--accent); }
+  .empty { text-align:center; color:var(--dim); padding:60px 20px; }
+  .empty code { background:var(--panel2); padding:2px 8px; border-radius:6px; color:var(--accent2); }
+</style>
+</head>
+<body>
+<header class="top">
+  <div class="brand">Vidfarm</div>
+  <nav>
+    <a href="/discover">Discover</a>
+    <a href="/library">Library</a>
+    <a href="/clips" class="active">Clips</a>
+  </nav>
+</header>
+<div class="wrap">
+  <div class="hero">
+    <h1>Clips</h1>
+    <p>Your reusable clip library — mined from long-form video, searchable by tag or natural language.</p>
+  </div>
+  <form class="searchbar" id="searchForm">
+    <input id="q" type="search" placeholder="Search clips — e.g. &quot;someone looks confused after reading a message&quot;" autocomplete="off" />
+    <button type="submit">Search</button>
+  </form>
+  <div class="presets" id="presets"></div>
+  <div class="status" id="status">Loading your clips…</div>
+  <div class="grid" id="grid"></div>
+</div>
+<script>
+(function(){
+  var grid = document.getElementById('grid');
+  var statusEl = document.getElementById('status');
+  var presetsEl = document.getElementById('presets');
+  var form = document.getElementById('searchForm');
+  var input = document.getElementById('q');
+
+  function fmtClock(sec){ var m=Math.floor(sec/60), s=Math.floor(sec%60); return (m<10?'0':'')+m+':'+(s<10?'0':'')+s; }
+  function esc(t){ var d=document.createElement('div'); d.textContent=(t==null?'':String(t)); return d.innerHTML; }
+
+  function topTags(tags){
+    if(!tags) return [];
+    var out=[];
+    ['subject','action','emotion','composition'].forEach(function(k){ (tags[k]||[]).slice(0,1).forEach(function(v){ out.push(v); }); });
+    if(tags.energy) out.push('energy:'+tags.energy);
+    return out.slice(0,4);
+  }
+
+  function card(clip){
+    var range = fmtClock(clip.start_time_sec)+'–'+fmtClock(clip.end_time_sec);
+    var score = (clip.score!=null) ? '<div class="score">'+ (clip.score*100).toFixed(0) +'</div>' : '';
+    var media = clip.thumbnail_url
+      ? '<img loading="lazy" src="'+esc(clip.thumbnail_url)+'" onmouseover="var v=this.parentNode.querySelector(&quot;video&quot;); if(v){v.style.display=&quot;block&quot;;v.play();}" />'
+      : '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:#556">no thumb</div>';
+    var vid = clip.view_url ? '<video muted loop playsinline preload="none" style="display:none;position:absolute;inset:0" src="'+esc(clip.view_url)+'"></video>' : '';
+    var tags = topTags(clip.tags).map(function(t){ return '<span class="tag">'+esc(t)+'</span>'; }).join('');
+    return '<div class="card">'
+      + '<div class="thumb" onmouseleave="var v=this.querySelector(&quot;video&quot;); if(v){v.pause();v.style.display=&quot;none&quot;;}">'+media+vid+'<div class="range">'+range+' · '+clip.duration_sec.toFixed(1)+'s</div>'+score+'</div>'
+      + '<div class="body">'
+      + '<div class="desc">'+esc(clip.description||clip.tags&&clip.tags.transcript||'(untagged clip)')+'</div>'
+      + '<div class="tags">'+tags+'</div>'
+      + '<div class="row"><span class="src" title="'+esc(clip.source_filename)+'">'+esc(clip.source_filename)+'</span>'
+      + '<a class="dl" href="/clips/'+encodeURIComponent(clip.clip_id)+'/download">Download</a></div>'
+      + '</div></div>';
+  }
+
+  function render(clips, label){
+    if(!clips || clips.length===0){
+      grid.innerHTML='';
+      statusEl.innerHTML = label || '';
+      grid.innerHTML = '<div class="empty">No clips yet. Build your library from the CLI:<br><br><code>vidfarm clips scan your-video.mp4</code><br><br>or POST a source to <code>/clips/scan</code>.</div>';
+      return;
+    }
+    statusEl.textContent = (label||'') + clips.length + ' clip' + (clips.length===1?'':'s');
+    grid.innerHTML = clips.map(card).join('');
+  }
+
+  function handleAuth(res){
+    if(res.status===401||res.status===403){
+      grid.innerHTML='';
+      statusEl.innerHTML='Sign in to Vidfarm to see your clips. Then build a library with <code style="background:#1b2130;padding:2px 6px;border-radius:6px">vidfarm clips scan</code>.';
+      throw new Error('unauthorized');
+    }
+    return res.json();
+  }
+
+  function loadFeed(){
+    statusEl.textContent='Loading your clips…';
+    fetch('/clips/feed?limit=120', {credentials:'same-origin', headers:{Accept:'application/json'}})
+      .then(handleAuth).then(function(d){ render(d.clips, ''); }).catch(function(){});
+  }
+
+  function search(query, criteria){
+    statusEl.textContent='Searching…';
+    fetch('/clips/search', {method:'POST', credentials:'same-origin', headers:{'Content-Type':'application/json', Accept:'application/json'}, body: JSON.stringify(criteria?{criteria:criteria, limit:60}:{query:query, limit:60})})
+      .then(handleAuth).then(function(d){
+        var label = (d.semantic?'semantic ':'') + 'results for "' + (query||'preset') + '" — ';
+        render(d.results, label);
+      }).catch(function(){});
+  }
+
+  function loadPresets(){
+    fetch('/clips/presets', {credentials:'same-origin', headers:{Accept:'application/json'}})
+      .then(handleAuth).then(function(d){
+        presetsEl.innerHTML = (d.presets||[]).map(function(p){
+          return '<span class="chip" data-id="'+esc(p.preset_id)+'">'+esc(p.name)+'</span>';
+        }).join('');
+        var byId = {}; (d.presets||[]).forEach(function(p){ byId[p.preset_id]=p; });
+        Array.prototype.forEach.call(presetsEl.querySelectorAll('.chip'), function(chip){
+          chip.addEventListener('click', function(){
+            Array.prototype.forEach.call(presetsEl.querySelectorAll('.chip'), function(c){ c.classList.remove('active'); });
+            chip.classList.add('active');
+            var p = byId[chip.getAttribute('data-id')];
+            if(p){ input.value=''; search(p.name, p.criteria); }
+          });
+        });
+      }).catch(function(){});
+  }
+
+  form.addEventListener('submit', function(e){
+    e.preventDefault();
+    Array.prototype.forEach.call(presetsEl.querySelectorAll('.chip'), function(c){ c.classList.remove('active'); });
+    var q = input.value.trim();
+    if(q) search(q, null); else loadFeed();
+  });
+
+  loadPresets();
+  loadFeed();
+})();
+</script>
+</body>
+</html>`;
+}
+async function resolveCustomerProviderKey(customerId, provider) {
+    const rows = (await listProviderKeysWithSecretsForCustomer(customerId));
+    for (const row of rows) {
+        if (row.provider === provider && (row.status ?? "active") === "active") {
+            const secret = readStoredSecret(String(row.secret ?? "")).trim();
+            if (secret)
+                return secret;
+        }
+    }
+    return null;
+}
+// Normalize a request-supplied provider to the supported set (default gemini).
+function normalizeClipProvider(value) {
+    return value === "openai" || value === "openrouter" ? value : "gemini";
+}
+/**
+ * A client for embedding MATCH queries in the SAME vector space the library was
+ * built with (derived from the newest clip's embedding_model), so scene-annotation
+ * queries are cosine-comparable to the stored clips. Returns null when embeddings
+ * aren't available (no key) — matching then falls back to the structured filter.
+ */
+async function buildMatchEmbedder(customerId) {
+    const libModel = await clipRecords.getLibraryEmbeddingModel(customerId);
+    const provider = libModel && libModel.startsWith("text-embedding") ? "openai" : "gemini";
+    const key = await resolveCustomerProviderKey(customerId, provider);
+    if (!key)
+        return null;
+    const client = new ClipModelClient({ provider, apiKey: key });
+    return client.canEmbed ? client : null;
+}
+// Build a ClipModelClient for a customer + provider, resolving the tagging key
+// and (for OpenRouter, which can't embed) an embedding key from their saved keys.
+async function buildCustomerClipClient(customerId, provider) {
+    const apiKey = await resolveCustomerProviderKey(customerId, provider);
+    if (!apiKey) {
+        return { error: `Add a ${provider} provider key first (BYOK) — POST /api/v1/user/me/provider-keys.` };
+    }
+    let embedding = null;
+    let embeddingKey = null;
+    if (provider === "gemini" || provider === "openai") {
+        embedding = { provider, apiKey };
+        embeddingKey = apiKey;
+    }
+    else {
+        // OpenRouter: pair with a gemini/openai key for embeddings if the user has one.
+        const g = await resolveCustomerProviderKey(customerId, "gemini");
+        const o = g ? null : await resolveCustomerProviderKey(customerId, "openai");
+        if (g) {
+            embedding = { provider: "gemini", apiKey: g };
+            embeddingKey = g;
+        }
+        else if (o) {
+            embedding = { provider: "openai", apiKey: o };
+            embeddingKey = o;
+        }
+    }
+    return {
+        client: new ClipModelClient({ provider, apiKey, embedding, publicBaseUrl: config.PUBLIC_BASE_URL }),
+        apiKey,
+        embeddingKey
+    };
+}
+function parseClipStorageKey(pathOrUri) {
+    const m = /^s3:\/\/[^/]+\/(.+)$/.exec(pathOrUri || "");
+    return m ? m[1] : null;
+}
+async function clipMediaUrl(pathOrUri) {
+    if (!pathOrUri)
+        return null;
+    const key = parseClipStorageKey(pathOrUri);
+    if (key)
+        return (await storage.getReadUrl(key)) ?? storage.getPublicUrl(key);
+    return pathOrUri; // non-s3 value (e.g. a local devcli-origin path) — pass through
+}
+async function serializeClip(clip) {
+    const [view_url, thumbnail_url] = await Promise.all([
+        clipMediaUrl(clip.file_path),
+        clipMediaUrl(clip.thumbnail_path)
+    ]);
+    const { embedding, ...rest } = clip;
+    void embedding; // never ship the raw vector to the client
+    return { ...rest, view_url, thumbnail_url };
+}
+function normalizeScanTier(value) {
+    return value === "flash" ? "flash" : "flash-lite";
+}
+function clipKeywordMatch(clip, q) {
+    const hay = `${clip.description} ${clip.tags.transcript} ${clip.source_filename} ${Object.values(clip.tags).flat().join(" ")}`.toLowerCase();
+    return q
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((term) => hay.includes(term));
+}
+// GET /clips — the first-class Clips gallery page (public HTML; the client
+// fetches /clips/feed with the session cookie). Mirrors /discover vs /discover/feed.
+app.get(CLIPS_PREFIX, (c) => c.html(renderClipsPage()));
+// GET /clips/feed — the caller's clip library as JSON (optional ?source, ?q, ?limit).
+app.get(`${CLIPS_PREFIX}/feed`, async (c) => {
+    const customer = requireCustomer(c);
+    const limit = clampPageLimit(Number(c.req.query("limit") || "60"), 200);
+    const q = c.req.query("q")?.trim();
+    let clips = await clipRecords.listClips(customer.id, {
+        sourceVideoId: c.req.query("source") || undefined,
+        limit: q ? 5000 : limit
+    });
+    if (q)
+        clips = clips.filter((clip) => clipKeywordMatch(clip, q)).slice(0, limit);
+    return c.json({ clips: await Promise.all(clips.map(serializeClip)) });
+});
+// POST /clips/search — hybrid structured + semantic search.
+app.post(`${CLIPS_PREFIX}/search`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const limit = Math.max(1, Math.min(200, Number(body.limit) || 20));
+        const provider = normalizeClipProvider(body.provider);
+        let criteria = body.criteria ?? (body.query ? { semantic_text: body.query } : {});
+        let queryEmbedding;
+        if (body.query || criteria.semantic_text) {
+            const built = await buildCustomerClipClient(customer.id, provider);
+            if ("client" in built) {
+                const client = built.client;
+                if (body.query && !body.criteria)
+                    criteria = await client.naturalLanguageToCriteria(body.query);
+                if (client.canEmbed)
+                    queryEmbedding = await client.embedQuery(criteria.semantic_text ?? body.query ?? "");
+            }
+        }
+        const hits = await searchUserClips(customer.id, { criteria, queryEmbedding, limit });
+        const results = await Promise.all(hits.map(async (h) => ({ ...(await serializeClip(h.clip)), score: h.score, similarity: h.similarity })));
+        return c.json({ results, criteria, semantic: Boolean(queryEmbedding) });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Clip search failed." }, 400);
+    }
+});
+function normalizeMatchScene(s, index) {
+    const criteria = s.match_criteria ?? s.criteria ?? (s.embedding_text || s.text ? { semantic_text: s.embedding_text || s.text } : {});
+    const text = s.embedding_text || s.text || criteria.semantic_text || "";
+    return {
+        id: s.scene_slug || s.id || `scene_${index}`,
+        criteria,
+        text,
+        limit: s.limit,
+        meta: {
+            scene_slug: s.scene_slug || s.id,
+            start: s.start,
+            duration: s.duration,
+            replaceability: s.replaceability,
+            scene_role: s.scene_role
+        }
+    };
+}
+// POST /clips/match — find the top library clips that could REPLACE one scene.
+// Body: a scene annotation, or {criteria, embedding_text|text, limit}.
+app.post(`${CLIPS_PREFIX}/match`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const scene = normalizeMatchScene(body, 0);
+        const limit = Math.max(1, Math.min(50, Number(body.limit) || scene.limit || 8));
+        let queryEmbedding;
+        if (scene.text) {
+            const embedder = await buildMatchEmbedder(customer.id);
+            if (embedder)
+                [queryEmbedding] = await embedder.embedQueries([scene.text]);
+        }
+        const hits = await searchUserClips(customer.id, { criteria: scene.criteria, queryEmbedding, limit });
+        const matches = await Promise.all(hits.map(async (h) => ({ ...(await serializeClip(h.clip)), score: h.score, similarity: h.similarity })));
+        return c.json({ matches, criteria: scene.criteria, semantic: Boolean(queryEmbedding) });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Clip match failed." }, 400);
+    }
+});
+// POST /clips/match-scenes — batch: take a decomposed video's scene annotations
+// and return the top replacement-clip matches per scene (one library read).
+// Body: { scenes | annotations: SceneAnnotation[], limit? }.
+app.post(`${CLIPS_PREFIX}/match-scenes`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json());
+        const raw = body.scenes ?? body.annotations ?? [];
+        if (!Array.isArray(raw) || raw.length === 0) {
+            return c.json({ error: "Provide scenes[] (or annotations[]) of scene annotations to match." }, 400);
+        }
+        if (raw.length > 200)
+            return c.json({ error: "Too many scenes (max 200 per request)." }, 400);
+        const defaultLimit = Math.max(1, Math.min(50, Number(body.limit) || 5));
+        const scenes = raw.map(normalizeMatchScene);
+        // One batch embedding call for every scene's query text (in the library's space).
+        const embedder = await buildMatchEmbedder(customer.id);
+        let embeddings = [];
+        if (embedder)
+            embeddings = await embedder.embedQueries(scenes.map((s) => s.text || " "));
+        const queries = scenes.map((s, i) => ({
+            id: s.id,
+            criteria: s.criteria,
+            queryEmbedding: embedder ? embeddings[i] : undefined,
+            limit: s.limit ?? defaultLimit,
+            meta: s.meta
+        }));
+        const results = await matchScenesToClips(customer.id, queries);
+        const serialized = await Promise.all(results.map(async (r) => ({
+            scene_slug: r.id,
+            ...(r.meta ?? {}),
+            matches: await Promise.all(r.matches.map(async (h) => ({ ...(await serializeClip(h.clip)), score: h.score, similarity: h.similarity })))
+        })));
+        return c.json({ results: serialized, semantic: Boolean(embedder) });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Clip match-scenes failed." }, 400);
+    }
+});
+// POST /clips/scan — kick off a cloud scan of an uploaded/staged source video.
+app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json());
+        const rawS3Uri = body.raw_s3_uri ??
+            (body.s3_key && config.AWS_S3_BUCKET ? `s3://${config.AWS_S3_BUCKET}/${body.s3_key}` : undefined);
+        if (!rawS3Uri) {
+            return c.json({ error: "Provide raw_s3_uri (s3://…) or s3_key of the uploaded source video." }, 400);
+        }
+        const provider = normalizeClipProvider(body.provider);
+        const built = await buildCustomerClipClient(customer.id, provider);
+        if ("error" in built)
+            return c.json({ error: built.error }, 400);
+        const { client, apiKey: tagApiKey, embeddingKey } = built;
+        const tier = normalizeScanTier(body.tier);
+        const framesPerScene = Math.max(1, Math.min(3, Number(body.frames_per_scene) || 2));
+        const includeAudio = body.include_audio !== false && provider === "gemini";
+        const guidancePrompt = body.prompt?.trim() || "";
+        const now = nowIso();
+        const scanId = createIdV7("clipscan");
+        const sourceVideoId = createIdV7("srcvid");
+        const filename = body.filename || rawS3Uri.split("/").pop() || "source.mp4";
+        const estimate = body.duration_sec && body.duration_sec > 0
+            ? estimateScanCostFromDuration(body.duration_sec, {
+                tier,
+                provider,
+                tagModelId: client.tagModelId,
+                embedModelId: client.embeddingModelId,
+                framesPerScene,
+                includeAudio
+            })
+            : null;
+        const source = {
+            source_video_id: sourceVideoId,
+            owner_id: customer.id,
+            filename,
+            raw_s3_uri: rawS3Uri,
+            duration_sec: body.duration_sec,
+            clip_count: 0,
+            tier,
+            status: "pending",
+            scan_id: scanId,
+            created_at: now,
+            updated_at: now
+        };
+        await clipRecords.putSource(source);
+        let executionArn;
+        if (config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN) {
+            const res = await clipScanSfn.send(new StartExecutionCommand({
+                stateMachineArn: config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN,
+                name: scanId.replace(/[^A-Za-z0-9-_]/g, "-").slice(0, 80),
+                input: JSON.stringify({
+                    scan_id: scanId,
+                    owner_id: customer.id,
+                    source_video_id: sourceVideoId,
+                    source_filename: filename,
+                    raw_s3_uri: rawS3Uri,
+                    tier,
+                    provider,
+                    tag_api_key: tagApiKey,
+                    embedding_provider: client.embeddingProvider ?? "",
+                    embedding_api_key: embeddingKey ?? "",
+                    guidance_prompt: guidancePrompt,
+                    frames_per_scene: framesPerScene,
+                    include_audio: includeAudio
+                })
+            }));
+            executionArn = res.executionArn;
+        }
+        const scan = {
+            scan_id: scanId,
+            owner_id: customer.id,
+            source_video_id: sourceVideoId,
+            status: executionArn ? "running" : "queued",
+            tier,
+            raw_s3_uri: rawS3Uri,
+            execution_arn: executionArn,
+            created_at: now,
+            updated_at: now
+        };
+        await clipRecords.putScan(scan);
+        return c.json({
+            scan_id: scanId,
+            source_video_id: sourceVideoId,
+            status: scan.status,
+            execution_arn: executionArn ?? null,
+            estimate,
+            pipeline_deployed: Boolean(config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN)
+        }, 202);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Failed to start clip scan." }, 400);
+    }
+});
+// GET /clips/scan/:scanId — poll scan status.
+app.get(`${CLIPS_PREFIX}/scan/:scanId`, async (c) => {
+    const customer = requireCustomer(c);
+    const scan = await clipRecords.getScan(customer.id, c.req.param("scanId"));
+    if (!scan)
+        return c.json({ error: "Scan not found" }, 404);
+    const source = await clipRecords.getSource(customer.id, scan.source_video_id);
+    return c.json({ scan, source });
+});
+// GET /clips/sources — scanned source videos.
+app.get(`${CLIPS_PREFIX}/sources`, async (c) => {
+    const customer = requireCustomer(c);
+    return c.json({ sources: await clipRecords.listSources(customer.id) });
+});
+// GET /clips/presets — built-in + saved presets.
+app.get(`${CLIPS_PREFIX}/presets`, async (c) => {
+    const customer = requireCustomer(c);
+    return c.json({ presets: await clipRecords.listPresets(customer.id) });
+});
+// POST /clips/presets — save a custom preset from criteria or a NL query.
+app.post(`${CLIPS_PREFIX}/presets`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json());
+        if (!body.name)
+            return c.json({ error: "name is required." }, 400);
+        let criteria = body.criteria;
+        if (!criteria && body.query) {
+            const built = await buildCustomerClipClient(customer.id, normalizeClipProvider(body.provider));
+            if ("error" in built)
+                return c.json({ error: built.error }, 400);
+            criteria = await built.client.naturalLanguageToCriteria(body.query);
+        }
+        if (!criteria)
+            return c.json({ error: "Provide criteria or query." }, 400);
+        const preset = makeUserPreset({ name: body.name, criteria, description: body.description, owner: customer.id });
+        await clipRecords.putPreset(customer.id, preset);
+        return c.json({ preset }, 201);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Failed to save preset." }, 400);
+    }
+});
+// DELETE /clips/presets/:presetId — delete a saved (non-builtin) preset.
+app.delete(`${CLIPS_PREFIX}/presets/:presetId`, async (c) => {
+    const customer = requireCustomer(c);
+    const id = c.req.param("presetId");
+    if (id.startsWith("preset_") && BUILTIN_CLIP_PRESET_IDS.has(id)) {
+        return c.json({ error: "Built-in presets cannot be deleted." }, 400);
+    }
+    await clipRecords.deletePreset(customer.id, id);
+    return c.json({ ok: true });
+});
+// GET /clips/:clipId/download — presigned redirect to the clip mp4.
+app.get(`${CLIPS_PREFIX}/:clipId/download`, async (c) => {
+    const customer = requireCustomer(c);
+    const clip = await clipRecords.getClip(customer.id, c.req.param("clipId"));
+    if (!clip)
+        return c.json({ error: "Clip not found" }, 404);
+    const url = await clipMediaUrl(clip.file_path);
+    if (!url)
+        return c.json({ error: "Clip file unavailable" }, 404);
+    return redirect(c, url, 302);
+});
+// GET /clips/:clipId — one clip (+ presigned view/thumbnail urls).
+app.get(`${CLIPS_PREFIX}/:clipId`, async (c) => {
+    const customer = requireCustomer(c);
+    const clip = await clipRecords.getClip(customer.id, c.req.param("clipId"));
+    if (!clip)
+        return c.json({ error: "Clip not found" }, 404);
+    return c.json({ clip: await serializeClip(clip) });
+});
+// DELETE /clips/:clipId — remove a clip record (+ vector).
+app.delete(`${CLIPS_PREFIX}/:clipId`, async (c) => {
+    const customer = requireCustomer(c);
+    await clipRecords.deleteClip(customer.id, c.req.param("clipId"));
+    return c.json({ ok: true });
+});
 app.get(`${TEMPLATES_PREFIX}/sources`, async (c) => {
     try {
         requireAdmin(c);