@mevdragon/vidfarm-devcli 0.7.1 → 0.9.0

package/dist/src/app.js

@@ -28,7 +28,7 @@ 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";
@@ -45,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";
@@ -75,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";
@@ -4090,6 +4096,28 @@ function createEditorFrontendActionTool(input) {
         }
     });
 }
+// Discover-chat only: lets the AI create a BRAND-NEW video for the user, either
+// from a text prompt (mode=generate) or by replicating a pasted video URL
+// (mode=replicate). The tool itself is a passthrough — it just structures the
+// user's intent; the chat frontend runs the ingest→decompose→fork pipeline and
+// drops an "Open in editor" link into the thread when it's ready.
+function createVideoCreationTool() {
+    return tool({
+        description: "Create a NEW editable video for the user from scratch. Call this the MOMENT the user asks to \"create/make a video of ...\" (set mode=generate and put the idea in `prompt`) OR to \"replicate/recreate/remix this video\" from a pasted TikTok/YouTube/Instagram/X URL (set mode=replicate, put the URL in `source_url`, and put any requested changes in `instructions`). This kicks off video creation in the browser and posts an 'Open in editor' link to the chat when the new video is ready — you do not need to poll or call any other tool. This is the ONLY way to make a brand-new video; the editor tools only edit an already-open composition.",
+        inputSchema: z.object({
+            mode: z.enum(["generate", "replicate"]).describe("generate = brand-new from a text prompt; replicate = recreate a pasted video URL."),
+            prompt: z.string().optional().describe("For mode=generate: what the video should be about."),
+            source_url: z.string().optional().describe("For mode=replicate: the TikTok/YouTube/Instagram/X video URL to recreate."),
+            instructions: z.string().optional().describe("Optional changes to apply while creating/recreating (e.g. 'make it about my coffee brand', 'change the hook to ...').")
+        }),
+        execute: async ({ mode, prompt, source_url, instructions }) => ({
+            mode,
+            prompt: prompt ?? null,
+            source_url: source_url ?? null,
+            instructions: instructions ?? null
+        })
+    });
+}
 function createEditorActionTool() {
     return tool({
         description: "Directly mutate the composition timeline in the editor OR start an export render OR generate-and-place AI media. Use this whenever the user asks for a timeline change (add/remove/duplicate/split layers, retime, reposition, resize, restyle text, swap media, group/ungroup), asks to generate an AI video/image and drop it on the timeline (action_type=generate_layer), or asks to export/render/publish/download the final MP4 (action_type=export_composition). The most recent <editor_context> in the user message is the source of truth for current layer_keys, layer indices (called 'track'), durations, timeline_gaps (blank spans), pending_generations (AI gens still rendering), and the most recent exported MP4 (last_export_url). Always provide explanation. For add_layer, also provide layer_key with a stable descriptive id (e.g., 'vf-caption-hook', 'vf-hero-image') so subsequent tool calls in the same turn can reference it — the editor will use that id as the new layer's data-hf-id. PREFER action_type=generate_layer to create NEW AI footage/images on the timeline: it submits the primitive generate job, drops a placeholder clip into the target slot immediately, and auto-swaps in the finished media when the job settles (no manual poll, no separate add_layer). Only use the http_request→add_layer flow for media that already has a URL. Avoid layer/track collisions: pick a track index higher than any existing layer on the requested time range, or set start/duration so the range is free. Never invent layer_keys for remove/set/duplicate/split actions; only use keys present in the most recent editor_context. For action_type=export_composition, no layer_key/geometry fields are needed; the editor kicks off the render and streams status in the UI, and the resulting MP4 URL will appear in the next <editor_context> as last_export_url.",
@@ -4297,7 +4325,12 @@ async function streamEditorChatAgent(input, send) {
                 frontend_action: createEditorFrontendActionTool({
                     tracerRegistry
                 }),
-                editor_action: createEditorActionTool()
+                editor_action: createEditorActionTool(),
+                // Discover/brainstorm surface only: "create me a video of…" / "replicate
+                // this URL…". The editor surfaces edit an already-open composition.
+                ...(input.template.templateId === "chat-brainstorm"
+                    ? { create_video: createVideoCreationTool() }
+                    : {})
             };
         })()
         : undefined;
@@ -5899,6 +5932,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
@@ -5915,6 +5984,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");
     }
@@ -5927,6 +5999,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,
@@ -6017,6 +6092,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");
         }
@@ -6029,6 +6105,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.
@@ -6393,6 +6472,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,
@@ -6470,6 +6563,66 @@ app.post(`${INSPIRATIONS_PREFIX}/:inspirationId/decompose`, async (c) => {
         }
     });
 });
+// A "processing" state older than this is treated as abandoned (crashed lambda)
+// so a forced re-run may start. Must exceed the longest real decompose but stay
+// under the API lambda's 15-min timeout.
+const DECOMPOSE_PROCESSING_STALE_MS = 10 * 60 * 1000;
+async function readDecomposeJobState(forkId) {
+    const text = await storage.readText(storage.compositionForkWorkingKey(forkId, "decompose.json"));
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeDecomposeJobState(forkId, state) {
+    try {
+        await storage.putJson(storage.compositionForkWorkingKey(forkId, "decompose.json"), state);
+    }
+    catch (error) {
+        console.error("decompose.json write failed", error instanceof Error ? error.message : error);
+    }
+}
+function decomposeDoneResponse(job, extra = {}) {
+    return {
+        ok: true,
+        status: "done",
+        mode: "smart",
+        provider: job.provider ?? null,
+        model: job.model ?? null,
+        scene_count: job.sceneCount ?? 0,
+        caption_count: job.captionCount ?? 0,
+        duration_seconds: job.durationSeconds ?? null,
+        became_default_fork: job.becameDefaultFork ?? false,
+        ghostcut_pending: job.ghostcutPending ?? false,
+        ...extra
+    };
+}
+// Read-only decompose job status — the client's poll target while a decompose
+// runs (or after a 504). Fast: just reads decompose.json.
+app.get(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
+    const caller = await getBrowserCustomer(c);
+    try {
+        const access = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: caller?.id ?? null, shareToken: readShareToken(c) }, "view");
+        const job = await readDecomposeJobState(access.fork.id);
+        if (!job)
+            return c.json({ ok: true, status: "none" });
+        if (job.status === "done")
+            return c.json(decomposeDoneResponse(job, { resumed: true }));
+        if (job.status === "failed")
+            return c.json({ ok: true, status: "failed", error: job.failureReason ?? "Decompose failed." });
+        const stale = Date.now() - (job.updatedAtMs ?? job.startedAtMs ?? 0) >= DECOMPOSE_PROCESSING_STALE_MS;
+        return c.json({ ok: true, status: "processing", stale, started_at_ms: job.startedAtMs });
+    }
+    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);
+    }
+});
 app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
     const caller = await getBrowserCustomer(c);
     if (!caller)
@@ -6486,6 +6639,36 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
         const userPromptRaw = typeof body.user_prompt === "string" ? body.user_prompt.trim() : "";
         const userPrompt = userPromptRaw.length > 0 ? userPromptRaw.slice(0, 4000) : null;
+        // Idempotency / resumability guard. POST STARTS a decompose (idempotently);
+        // GET /auto-decompose is the poll. An in-flight run always wins so a client's
+        // post-504 retry (or a second caller) never starts a duplicate. A completed
+        // job is returned from cache unless `force` (the editor's decompose click)
+        // asks for a fresh re-run. Absent / failed / abandoned jobs (re)start — so a
+        // plain POST with no `force` still kicks the first decompose (back-compat for
+        // the editor-chat copilot's http_request call).
+        const forceRun = body.force === true;
+        const existingJob = await readDecomposeJobState(fork.id);
+        const jobFresh = existingJob
+            ? Date.now() - (existingJob.updatedAtMs ?? existingJob.startedAtMs ?? 0) < DECOMPOSE_PROCESSING_STALE_MS
+            : false;
+        if (existingJob?.status === "processing" && jobFresh) {
+            return c.json({ ok: true, status: "processing", started_at_ms: existingJob.startedAtMs });
+        }
+        if (existingJob?.status === "done" && !forceRun) {
+            return c.json(decomposeDoneResponse(existingJob, { resumed: true }));
+        }
+        // Claim the job so concurrent polls/kicks back off. A local helper stamps
+        // "failed" on every early-error return so a poller never hangs on processing.
+        await writeDecomposeJobState(fork.id, { status: "processing", startedAtMs, updatedAtMs: Date.now() });
+        const failDecompose = async (payload, statusCode) => {
+            await writeDecomposeJobState(fork.id, {
+                status: "failed",
+                startedAtMs,
+                updatedAtMs: Date.now(),
+                failureReason: typeof payload.error === "string" ? payload.error : "Auto-decompose failed."
+            });
+            return c.json(payload, statusCode);
+        };
         // Parse the current composition HTML with a real DOM (linkedom) so
         // attribute values come back UNESCAPED — `data-source-video="foo?a=1&amp;b=2"`
         // reads as `foo?a=1&b=2`, which is what ghostcut and the vision extractor
@@ -6522,7 +6705,7 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
             }
             catch (error) {
                 if (error instanceof MediaDurationExceededError) {
-                    return c.json({
+                    return failDecompose({
                         ok: false,
                         error: `Source video is ${error.durationSeconds.toFixed(1)}s — Vidfarm caps auto-decompose at ${error.maxDurationSeconds}s. Trim the source before forking.`,
                         code: "source_too_long",
@@ -6640,13 +6823,13 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         const customerKeys = await loadCustomerVisionKeys(caller.id);
         const hasAnyKey = Boolean(customerKeys.gemini || customerKeys.openai || customerKeys.openrouter);
         if (!hasAnyKey) {
-            return c.json({
+            return failDecompose({
                 ok: false,
                 error: "Decompose requires an AI provider key. Add a Gemini, OpenAI, or OpenRouter key in Settings and try again."
             }, 400);
         }
         if (!sourceUrl) {
-            return c.json({ ok: false, error: "Composition has no source video URL." }, 400);
+            return failDecompose({ ok: false, error: "Composition has no source video URL." }, 400);
         }
         const inspirationForTagline = forkInspirationId
             ? await serverlessRecords.getInspiration(forkInspirationId)
@@ -6676,13 +6859,13 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         }
         catch (error) {
             console.error("smart decompose failed", error instanceof Error ? error.message : error);
-            return c.json({
+            return failDecompose({
                 ok: false,
                 error: error instanceof Error ? error.message : "Smart decompose failed."
             }, 502);
         }
         if (smart.scenes.length === 0 && smart.captions.length === 0) {
-            return c.json({
+            return failDecompose({
                 ok: false,
                 error: "Smart decompose returned no scenes. Try again with different guidance."
             }, 502);
@@ -6775,6 +6958,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
@@ -6813,8 +7011,23 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
             }
         }
         await chargeDecomposeUsage({ mode: "smart" });
+        // Stamp the job "done" so a client whose request 504'd mid-run (or any later
+        // poll) resolves to completion and reloads the composition.
+        await writeDecomposeJobState(fork.id, {
+            status: "done",
+            startedAtMs,
+            updatedAtMs: Date.now(),
+            provider: smart.provider,
+            model: smart.model,
+            sceneCount: smart.scenes.length,
+            captionCount: smart.captions.length,
+            durationSeconds: smart.durationSeconds,
+            becameDefaultFork: becameDefault,
+            ghostcutPending: ghostcutTaskId !== null
+        });
         return c.json({
             ok: true,
+            status: "done",
             mode: "smart",
             provider: smart.provider,
             model: smart.model,
@@ -6830,6 +7043,15 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
     catch (error) {
         if (error instanceof ForkNotFoundError || error instanceof ForkAccessDeniedError)
             return forkAccessErrorResponse(c, error);
+        // Persist a failed job (best-effort) so the client's poll reads a terminal
+        // failure instead of hanging on "processing". Safe: only reached after the
+        // caller passed access control.
+        await writeDecomposeJobState(c.req.param("forkId"), {
+            status: "failed",
+            startedAtMs,
+            updatedAtMs: Date.now(),
+            failureReason: error instanceof Error ? error.message : "Auto-decompose failed."
+        });
         return c.json({ ok: false, error: error instanceof Error ? error.message : "Auto-decompose failed." }, 500);
     }
 });
@@ -7325,6 +7547,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
@@ -7970,6 +8390,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");
         }
@@ -7982,6 +8403,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,
@@ -8375,6 +8799,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)
@@ -8383,6 +8808,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,
@@ -10466,6 +10893,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);
@@ -14642,6 +15076,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);