@mevdragon/vidfarm-devcli 0.8.0 → 0.10.0

package/dist/src/app.js

@@ -45,10 +45,10 @@ 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 { SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
+import { DescribeExecutionCommand, 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 { BUILTIN_PRESETS, ClipModelClient, effectiveHuntDurationSec, estimateScanCostFromDuration, normalizeHuntSpec, parseClipHuntPrompt, resolveDurationBand } 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";
@@ -59,7 +59,8 @@ import { hasUpstreamKey, isUpstreamEnabled, proxyRequestToUpstream, seedFromUpst
 import { TemplateSourceService } from "./services/template-sources.js";
 import { TemplateSourceAlreadyRegisteredError } from "./services/template-sources.js";
 import { renderCustomInpaintPage } from "./template-editor-pages.js";
-import { escapeAttribute, escapeHtml, escapeJsonForHtml, renderPageShell } from "./page-shell.js";
+import { TEMPLATE_EDITOR_SHELL_STYLES } from "./template-editor-shell.js";
+import { escapeAttribute, escapeHtml, escapeJsonForHtml, renderBrandLockup, renderPageShell, renderPrimaryNav } from "./page-shell.js";
 import { renderReadyPostScheduleData, renderReadyPostScheduleModal, renderReadyPostScheduleScript, renderReadyPostScheduleStyles } from "./ready-post-schedule-component.js";
 const auth = new AuthService();
 const billing = new BillingService();
@@ -81,6 +82,11 @@ const INSPIRATIONS_PREFIX = `${API_PREFIX}/inspirations`;
 const VIDEOS_PREFIX = `${API_PREFIX}/videos`;
 const PRIMITIVES_PREFIX = `${API_PREFIX}/primitives`;
 const CLIPS_PREFIX = "/clips";
+// Temp folder ("My Files → temporary") hard-TTL. Keep in sync with the
+// tag-scoped S3 lifecycle rule (30 days) in the CDK stacks and the clip-scan
+// Lambda's TEMP_SOURCE_TTL_DAYS — records, sweeps, and object lifecycle must
+// agree or users see phantom files (record without object) or orphans.
+const TEMP_FILE_TTL_DAYS = 30;
 const APPROVED_POSTS_PREFIX = `${API_PREFIX}/approved/posts`;
 const APPROVED_POSTS_PUBLIC_PREFIX = "/approved/posts";
 const ACCOUNT_FRONTEND_PREFIX = "/u/:userId";
@@ -3174,6 +3180,40 @@ async function buildChatBrainstormEditorChatBoot(input) {
         }
     };
 }
+async function buildClipsEditorChatBoot(input) {
+    const directorSkill = readRootSkillFile("SKILL.director.md", "SKILL.user.md") || null;
+    const availableProviders = (await normalizeEditorChatProviderRows(input.customer.id)).map((entry) => entry.provider);
+    const docsRoutes = [
+        { method: "GET", path: `${CLIPS_PREFIX}/feed`, summary: "List the caller's reusable clip library (optional ?q, ?source, ?limit)." },
+        { method: "POST", path: `${CLIPS_PREFIX}/search`, summary: "Hybrid structured + semantic clip search. Body is { query } (natural language) or { criteria } (structured filter)." },
+        { method: "POST", path: `${CLIPS_PREFIX}/scan`, summary: "Import a source video and mine it into clips. Body accepts source_url (a public/durable video URL), raw_s3_uri, or s3_key, plus an optional prompt describing which scenes to keep (e.g. 'people with food, no on-screen text, vertical, 5-10s')." },
+        { method: "GET", path: `${CLIPS_PREFIX}/scan/:scanId`, summary: "Poll clip-scan status for an in-progress import." },
+        { method: "GET", path: `${CLIPS_PREFIX}/presets`, summary: "List the caller's saved clip-search presets." }
+    ];
+    return {
+        apiUrl: resolveEditorChatApiUrl(),
+        threadsUrl: `${API_PREFIX}/editor-chat/threads`,
+        vidfarmApiKey: await getVisibleApiKey(input.customer.id),
+        cachedContext: {
+            directorSkill,
+            templateSkill: null,
+            availableProviders,
+            currentTemplateConfig: null
+        },
+        template: {
+            page: "docs",
+            tracerId: null,
+            tracers: [],
+            defaultRequestTracer: null,
+            activeTracer: null,
+            templateId: "chat-brainstorm",
+            templateSlug: "clip-curator",
+            templateTitle: "Clip curator",
+            templateDescription: "Search your reusable clip library and import new source videos to mine into clips.",
+            docsRoutes
+        }
+    };
+}
 function resolveEditorChatApiUrl() {
     return config.PUBLIC_EDITOR_CHAT_URL?.trim() || `${API_PREFIX}/editor-chat`;
 }
@@ -3504,7 +3544,15 @@ function normalizeEditorChatPath(input) {
         // advances the job so the copilot must be explicit about wanting it, but it
         // lives under the same prefix and is protected by its own auth guard, which
         // is fine.
-        COMPOSITIONS_PREFIX
+        COMPOSITIONS_PREFIX,
+        // Clip hunting (long-form → short-form): search/feed the caller's clip
+        // library, start a scan (POST /clips/scan with source_url|s3_key|
+        // temp_file_id + prompt/ranges/duration/aspect), and poll its status. The
+        // scan route is wallet-gated + billed for AWS compute only (BYOK AI keys),
+        // and NEVER runs GhostCut on the long-form source — "no text" is a
+        // scene-selection filter; caption removal stays a per-finished-clip
+        // primitive (/api/v1/primitives/videos/remove-captions).
+        CLIPS_PREFIX
     ];
     const parsed = trimmed.startsWith("http://") || trimmed.startsWith("https://")
         ? new URL(trimmed)
@@ -3634,7 +3682,7 @@ function normalizeOperationRequestTracer(tracer) {
 }
 function createTemplateHttpTool(input) {
     return tool({
-        description: "Call exactly one Vidfarm REST API route and inspect the response before deciding the next call. Use template routes for metadata, skill, config, operations, jobs, logs, and cancel routes. Use primitive routes under /api/v1/primitives for reusable image generation, image editing, inpainting, still rendering, social/media video download, AI video generation, video slide rendering, burned-in caption removal, video trim/extract/probe/mute/concat operations, audio trim/probe/concat/normalize operations, brainstorm strategy routes, and primitive job inspection; these primitive routes are allowed directly from editor chat even when they are not specific to the current template. Primitive POST bodies must use { tracer, payload: { ...primitive fields... }, webhook_url? }; do not put prompt, source_image_url, instruction, slides, html, or other primitive fields at the top level. Never say primitive image generation, image edit, inpaint, HTML render, video download, AI video generation, caption removal, trim, probe, extract-audio, concat, mute, video render, or brainstorm routes are unavailable here when the route exists. If the user asks to generate a new image similar to an attachment, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }. If the user asks to revise the attached image itself, call POST /api/v1/primitives/images/edit with body { tracer, payload: { source_image_url, instruction } }. If the user asks to download a social/media post into a durable MP4, call POST /api/v1/primitives/videos/download with body { tracer, payload: { source_url|video_url|url, quality?: \"best\"|\"hd\"|\"full_hd\" } }. If the user asks to generate a new AI video, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, provider?: \"openai\"|\"gemini\"|\"openrouter\", duration?: seconds, input_references?: [direct image asset URL], frame_images?: [{ image_url, frame_type }] } }; never send webpage or social post URLs in input_references. duration is seconds, not milliseconds, and duration_ms belongs only to /videos/render-slides slides. Default video models are openai/sora-2, gemini/veo-3.0-generate-001, and openrouter/bytedance/seedance-2.0. Use POST /api/v1/primitives/videos/render-slides only to assemble existing media URLs into an MP4 slideshow. Use POST /api/v1/primitives/media/dedupe to apply subtle dedupe transforms (zoom/tilt/rotate/saturation/speed/horizontal_flip/contrast/brightness/hue_rotate/blur/tint) to any image or video URL, with body { tracer, payload: { source_media_url, media_type?, effects?, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Use POST /api/v1/primitives/videos/trim for clipping, /videos/extract-audio for demuxing, /videos/probe or /audio/probe for metadata-only JSON outputs, /videos/extract-frame for stills, /videos/mute to remove audio, /videos/replace-audio to swap tracks, /videos/concat for sequential muted MP4 joins, /audio/trim for clipped audio, /audio/concat for stitched audio, and /audio/normalize for leveled/re-encoded audio. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. If the user explicitly asks for hooks, angles, awareness-stage advice, or a cold-start strategy questionnaire, call the matching brainstorm route immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart when the customer is starting from zero, /brainstorm/awareness_stages when they do not know what ad types to make, /brainstorm/angles when they want persuasive angles, and /brainstorm/hooks when they want many openings. Product placement is a first-class brainstorm primitive like angles and hooks: when the user wants to identify product-placement opportunities in a video or repurpose a video into a native ad for their product, call POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? } — it watches the video and returns timestamped native placement opportunities and prefers a Gemini key. You may also analyze an attached video directly to answer product-placement questions conversationally instead of the primitive when the user just wants a quick take. For brainstorm routes, do not send count by default; only include count when the user explicitly asks for a specific number of hooks, angles, questions, or opportunities. When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured output. When the user asks for content ideas or says they do not know where to start, prefer the sequence coldstart -> awareness_stages -> angles -> hooks, then use the output to choose templates. For template operation POST bodies, use top-level template_preview_media=\"auto\" by default, \"include\" when the user wants the template to use catalog preview media as references where supported, and \"exclude\" when the user asks not to use preview media as references. Templates decide which generation steps honor that policy. If a POST returns a queued job, do not poll it in this same response; continue with any remaining requested POST calls, then summarize the queued job ids and tracers. If you know a job_id but not the template or primitive, use GET /api/v1/user/me/jobs/:jobId or its /logs and /artifacts subroutes instead of paging through job lists. Use GET /api/v1/compositions/:forkId/remove-video-captions to look up both the original source video URL and the subtitle-removed mirrored URL for the current fork before feeding a video URL into a primitive route; this is a read-only, non-billing status check — never confuse it with POST /remove-video-captions-poll (which advances the fork's decompose-time subtitle-removal job and can bill). Use POST /api/v1/approved/posts with title, caption, pinned_comment, media URLs, and tracer to approve a finished output into a preview/share page. Use POST /api/v1/approved/posts/:postId/schedules with destination_type, destination_id, scheduled_at, timezone, and optional settings/additional_notes to schedule an approved post. When a rendered video was built from slideshow frame images, include both versions in one media array: final MP4 first with kind=\"video\" and role=\"primary\", then every finished captioned slide frame image in order with kind=\"image\" and role=\"slide\". Prefer create-slideshow result.renderVideoInput.slides[].imageUrl or result.slides[].frameImageUrl for carousel media; do not use backgroundImageUrl, manifests, thumbnails, or a partial files array as the full slide set. If the user supplies exact media file URLs for approval, use those URLs as the backup source of truth, preserve their order, infer kind when needed, and assign primary/video and slide/image roles correctly. If the user asks for N distinct generated outputs, make N sequential POST calls rather than one combined POST and do not stop after the first queued job.",
+        description: "Call exactly one Vidfarm REST API route and inspect the response before deciding the next call. Use template routes for metadata, skill, config, operations, jobs, logs, and cancel routes. Use primitive routes under /api/v1/primitives for reusable image generation, image editing, inpainting, still rendering, social/media video download, AI video generation, video slide rendering, burned-in caption removal, video trim/extract/probe/mute/concat operations, audio trim/probe/concat/normalize operations, brainstorm strategy routes, and primitive job inspection; these primitive routes are allowed directly from editor chat even when they are not specific to the current template. Primitive POST bodies must use { tracer, payload: { ...primitive fields... }, webhook_url? }; do not put prompt, source_image_url, instruction, slides, html, or other primitive fields at the top level. Never say primitive image generation, image edit, inpaint, HTML render, video download, AI video generation, caption removal, trim, probe, extract-audio, concat, mute, video render, or brainstorm routes are unavailable here when the route exists. If the user asks to generate a new image similar to an attachment, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }. If the user asks to revise the attached image itself, call POST /api/v1/primitives/images/edit with body { tracer, payload: { source_image_url, instruction } }. If the user asks to download a social/media post into a durable MP4, call POST /api/v1/primitives/videos/download with body { tracer, payload: { source_url|video_url|url, quality?: \"best\"|\"hd\"|\"full_hd\" } }. If the user asks to generate a new AI video, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, provider?: \"openai\"|\"gemini\"|\"openrouter\", duration?: seconds, input_references?: [direct image asset URL], frame_images?: [{ image_url, frame_type }] } }; never send webpage or social post URLs in input_references. duration is seconds, not milliseconds, and duration_ms belongs only to /videos/render-slides slides. Default video models are openai/sora-2, gemini/veo-3.0-generate-001, and openrouter/bytedance/seedance-2.0. Use POST /api/v1/primitives/videos/render-slides only to assemble existing media URLs into an MP4 slideshow. Use POST /api/v1/primitives/media/dedupe to apply subtle dedupe transforms (zoom/tilt/rotate/saturation/speed/horizontal_flip/contrast/brightness/hue_rotate/blur/tint) to any image or video URL, with body { tracer, payload: { source_media_url, media_type?, effects?, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Use POST /api/v1/primitives/videos/trim for clipping, /videos/extract-audio for demuxing, /videos/probe or /audio/probe for metadata-only JSON outputs, /videos/extract-frame for stills, /videos/mute to remove audio, /videos/replace-audio to swap tracks, /videos/concat for sequential muted MP4 joins, /audio/trim for clipped audio, /audio/concat for stitched audio, and /audio/normalize for leveled/re-encoded audio. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver on long videos), aspect crops every clip, and avoid_text prefers scenes WITHOUT on-screen text via scene SELECTION (never caption removal on the source). The hunt is async: it returns scan_id immediately; poll GET /clips/scan/:scanId, then browse results via GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys. To remove captions from a finished HUNTED clip, pass that clip's short mp4 to /videos/remove-captions afterwards. If the user explicitly asks for hooks, angles, awareness-stage advice, or a cold-start strategy questionnaire, call the matching brainstorm route immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart when the customer is starting from zero, /brainstorm/awareness_stages when they do not know what ad types to make, /brainstorm/angles when they want persuasive angles, and /brainstorm/hooks when they want many openings. Product placement is a first-class brainstorm primitive like angles and hooks: when the user wants to identify product-placement opportunities in a video or repurpose a video into a native ad for their product, call POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? } — it watches the video and returns timestamped native placement opportunities and prefers a Gemini key. You may also analyze an attached video directly to answer product-placement questions conversationally instead of the primitive when the user just wants a quick take. For brainstorm routes, do not send count by default; only include count when the user explicitly asks for a specific number of hooks, angles, questions, or opportunities. When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured output. When the user asks for content ideas or says they do not know where to start, prefer the sequence coldstart -> awareness_stages -> angles -> hooks, then use the output to choose templates. For template operation POST bodies, use top-level template_preview_media=\"auto\" by default, \"include\" when the user wants the template to use catalog preview media as references where supported, and \"exclude\" when the user asks not to use preview media as references. Templates decide which generation steps honor that policy. If a POST returns a queued job, do not poll it in this same response; continue with any remaining requested POST calls, then summarize the queued job ids and tracers. If you know a job_id but not the template or primitive, use GET /api/v1/user/me/jobs/:jobId or its /logs and /artifacts subroutes instead of paging through job lists. Use GET /api/v1/compositions/:forkId/remove-video-captions to look up both the original source video URL and the subtitle-removed mirrored URL for the current fork before feeding a video URL into a primitive route; this is a read-only, non-billing status check — never confuse it with POST /remove-video-captions-poll (which advances the fork's decompose-time subtitle-removal job and can bill). Use POST /api/v1/approved/posts with title, caption, pinned_comment, media URLs, and tracer to approve a finished output into a preview/share page. Use POST /api/v1/approved/posts/:postId/schedules with destination_type, destination_id, scheduled_at, timezone, and optional settings/additional_notes to schedule an approved post. When a rendered video was built from slideshow frame images, include both versions in one media array: final MP4 first with kind=\"video\" and role=\"primary\", then every finished captioned slide frame image in order with kind=\"image\" and role=\"slide\". Prefer create-slideshow result.renderVideoInput.slides[].imageUrl or result.slides[].frameImageUrl for carousel media; do not use backgroundImageUrl, manifests, thumbnails, or a partial files array as the full slide set. If the user supplies exact media file URLs for approval, use those URLs as the backup source of truth, preserve their order, infer kind when needed, and assign primary/video and slide/image roles correctly. If the user asks for N distinct generated outputs, make N sequential POST calls rather than one combined POST and do not stop after the first queued job.",
         inputSchema: z.object({
             method: z.enum(["GET", "POST"]).describe("HTTP method to use."),
             path: z.string().min(1).describe("Absolute path or same-origin URL for an allowed Vidfarm REST route."),
@@ -4096,6 +4144,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.",
@@ -4303,7 +4373,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;
@@ -4750,6 +4825,7 @@ app.get(`${ACCOUNT_FRONTEND_PREFIX}/discover`, (c) => redirectToPublicPath(c, "/
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/help`, (c) => redirectToPublicPath(c, "/help"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/chat`, (c) => dispatchScopedGetToLegacyRoute(c, "/chat"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/library`, (c) => dispatchScopedGetToLegacyRoute(c, "/library"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/clips`, (c) => dispatchScopedGetToLegacyRoute(c, "/clips"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/inpaint`, (c) => dispatchScopedGetToLegacyRoute(c, "/inpaint"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/calendar`, (c) => dispatchScopedGetToLegacyRoute(c, "/calendar"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/settings`, (c) => dispatchScopedGetToLegacyRoute(c, "/settings"));
@@ -6536,6 +6612,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)
@@ -6552,6 +6688,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
@@ -6588,7 +6754,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",
@@ -6706,13 +6872,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)
@@ -6742,13 +6908,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);
@@ -6894,8 +7060,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,
@@ -6911,6 +7092,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);
     }
 });
@@ -14535,7 +14725,9 @@ app.get(`${USER_PREFIX}/me/temporary-files`, async (c) => {
     return c.json({
         files,
         folders: Array.from(new Set(folders)).sort(),
-        ttl_days: 90,
+        // Temp folder hard-TTLs at 30 days: DynamoDB record TTL + tag-scoped S3
+        // lifecycle + this route's sweep all converge on the same deadline.
+        ttl_days: TEMP_FILE_TTL_DAYS,
         max_size_bytes: 100 * 1024 * 1024
     });
 });
@@ -14615,6 +14807,10 @@ app.post(`${USER_PREFIX}/me/temporary-files/upload`, async (c) => {
         const fileId = randomUUID();
         const storageKey = storage.userTemporaryFileKey(customer.id, fileId, fileName, folderPath);
         await storage.putBuffer(storageKey, buffer, contentType);
+        // The tag drives the bucket's 30-day lifecycle deletion of the original.
+        await storage.putObjectTags(storageKey, { "vidfarm-temp": "1" }).catch((error) => {
+            console.error(`[vidfarm] putObjectTags failed for temporary file key ${storageKey}:`, error);
+        });
         await serverlessRecords.createUserTemporaryFile({
             id: fileId,
             customerId: customer.id,
@@ -14623,7 +14819,7 @@ app.post(`${USER_PREFIX}/me/temporary-files/upload`, async (c) => {
             sizeBytes: buffer.byteLength,
             storageKey,
             folderPath,
-            expiresAt: addSeconds(new Date(), 90 * 24 * 60 * 60)
+            expiresAt: addSeconds(new Date(), TEMP_FILE_TTL_DAYS * 24 * 60 * 60)
         });
         const saved = await serverlessRecords.getUserTemporaryFile(customer.id, fileId);
         if (!saved) {
@@ -14649,6 +14845,11 @@ app.post(`${USER_PREFIX}/me/temporary-files`, async (c) => {
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported temporary file type: ${fileName}` }, 400);
         }
+        // Presigned transport: the bytes went straight to S3, so tag server-side at
+        // finalize — the tag drives the bucket's 30-day lifecycle deletion.
+        await storage.putObjectTags(expectedStorageKey, { "vidfarm-temp": "1" }).catch((error) => {
+            console.error(`[vidfarm] putObjectTags failed for temporary file key ${expectedStorageKey}:`, error);
+        });
         await serverlessRecords.createUserTemporaryFile({
             id: body.file_id,
             customerId: customer.id,
@@ -14657,7 +14858,7 @@ app.post(`${USER_PREFIX}/me/temporary-files`, async (c) => {
             sizeBytes: body.size_bytes,
             storageKey: expectedStorageKey,
             folderPath,
-            expiresAt: addSeconds(new Date(), 90 * 24 * 60 * 60)
+            expiresAt: addSeconds(new Date(), TEMP_FILE_TTL_DAYS * 24 * 60 * 60)
         });
         const saved = await serverlessRecords.getUserTemporaryFile(customer.id, body.file_id);
         if (!saved) {
@@ -14941,179 +15142,347 @@ app.post(`${USER_PREFIX}/me/provider-keys`, async (c) => {
 // 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));
+// Pre-scan estimate of the AWS compute the wallet will be billed for a hunt
+// (Lambda GB-seconds + Step Functions transitions — mirrors the post-hoc
+// billing in infra/lambda/clip-scan.ts). The BYOK AI spend is estimated
+// separately (estimateScanCostFromDuration) and is NOT wallet-billed.
+function estimateClipScanComputeUsd(effectiveDurationSec, targetSceneSec) {
+    const LAMBDA_X86_GB_SECOND_USD = 0.0000166667;
+    const LAMBDA_REQUEST_USD = 0.20 / 1_000_000;
+    const STEP_FUNCTIONS_STANDARD_TRANSITION_USD = 0.000025;
+    const CLIP_SCAN_MEMORY_GB = 3;
+    const avgSceneSec = Math.max(2, targetSceneSec ?? 4);
+    const scenes = Math.max(1, Math.ceil(effectiveDurationSec / avgSceneSec));
+    // probe decodes the windowed footage once; each scene worker extracts +
+    // uploads a clip (dominated by a fixed overhead + a share of re-encode time).
+    const probeSeconds = 15 + effectiveDurationSec * 0.08;
+    const perSceneSeconds = 8 + avgSceneSec * 0.6;
+    const finalizeSeconds = 3;
+    const lambdaSeconds = probeSeconds + scenes * perSceneSeconds + finalizeSeconds;
+    const gbSeconds = lambdaSeconds * CLIP_SCAN_MEMORY_GB;
+    const lambdaUsd = gbSeconds * LAMBDA_X86_GB_SECOND_USD + (scenes + 2) * LAMBDA_REQUEST_USD;
+    const stepFunctionsUsd = (3 + scenes) * STEP_FUNCTIONS_STANDARD_TRANSITION_USD;
+    const baseUsd = Number((lambdaUsd + stepFunctionsUsd).toFixed(6));
+    return {
+        estimated_scenes: scenes,
+        lambda_gb_seconds: Number(gbSeconds.toFixed(1)),
+        aws_compute_usd: baseUsd,
+        // What actually lands on the wallet (platform markup included).
+        estimated_charge_usd: Number(applyMarkupUsd(baseUsd).toFixed(6))
+    };
+}
 // 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 renderClipsPage(input) {
+    const libraryHref = withAccountQuery("/library", input.currentAccountId);
+    const clipsHref = withAccountQuery("/clips", input.currentAccountId);
+    return renderPageShell({
+        title: "Clips — VidFarm",
+        mainClass: "is-wide",
+        runtimeBoot: {
+            pageKind: "legacy",
+            title: "Clips",
+            userId: input.userId,
+            editorChat: input.editorChat ?? null
+        },
+        style: `
+      ${TEMPLATE_EDITOR_SHELL_STYLES}
+
+      .clips-frame { padding-left: 432px; }
+      .clips-shell { display: grid; grid-template-rows: auto minmax(0, 1fr); gap: 16px; min-height: 0; }
+      .clips-toolbar { display: grid; gap: 12px; }
+      .clips-toolbar-row { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
+      .clips-search { display: flex; gap: 10px; flex: 1 1 320px; min-width: 240px; margin: 0; }
+      .clips-search input { flex: 1; }
+      .clips-search button { flex: 0 0 auto; }
+      .clips-status { min-height: 20px; color: var(--muted); font-size: 0.94rem; }
+      .clips-scroll { min-height: 0; overflow: auto; padding-right: 6px; }
+      .clips-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(216px, 1fr)); gap: 16px; padding-bottom: 24px; }
+      .clip-card {
+        display: flex;
+        flex-direction: column;
+        overflow: hidden;
+        border: 1px solid rgba(255, 255, 255, 0.72);
+        border-radius: var(--radius-sm);
+        background: rgba(255, 252, 247, 0.82);
+        box-shadow: var(--shadow-soft);
+      }
+      .clip-thumb { position: relative; aspect-ratio: 9 / 16; overflow: hidden; background: #12161f; }
+      .clip-thumb img, .clip-thumb video { display: block; width: 100%; height: 100%; object-fit: cover; }
+      .clip-thumb .clip-noimg { display: flex; align-items: center; justify-content: center; height: 100%; color: rgba(255, 255, 255, 0.5); font-size: 0.82rem; }
+      .clip-range {
+        position: absolute; left: 8px; bottom: 8px;
+        padding: 2px 8px; border-radius: 8px;
+        background: rgba(20, 22, 30, 0.72); color: #f4efe6;
+        font-size: 12px; font-variant-numeric: tabular-nums;
+      }
+      .clip-score {
+        position: absolute; right: 8px; top: 8px;
+        padding: 1px 7px; border-radius: 8px;
+        background: rgba(36, 48, 65, 0.92); color: #f3e8cd;
+        font-size: 11px; font-weight: 800;
+      }
+      .clip-body { display: flex; flex-direction: column; gap: 8px; flex: 1; padding: 12px; }
+      .clip-desc { color: var(--ink); font-size: 0.9rem; line-height: 1.35; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+      .clip-tags { display: flex; flex-wrap: wrap; gap: 5px; }
+      .clip-tag { padding: 2px 7px; border-radius: 6px; background: rgba(244, 236, 223, 0.86); color: #6f7d95; font-size: 11px; }
+      .clip-row { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-top: auto; }
+      .clip-src { max-width: 58%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); font-size: 11px; }
+      .clip-dl { color: #b4823a; font-size: 12px; font-weight: 800; text-decoration: none; }
+      .clip-dl:hover { text-decoration: underline; }
+      .clips-empty { grid-column: 1 / -1; display: grid; place-items: center; min-height: 320px; padding: 48px 20px; text-align: center; color: var(--muted); font-size: 1.05rem; line-height: 1.7; }
+
+      .clips-import-dialog {
+        width: min(30rem, calc(100vw - 1.5rem));
+        padding: 0;
+        border: 1px solid rgba(191, 164, 109, 0.4);
+        border-radius: 26px;
+        background: rgba(255, 252, 247, 0.99);
+        box-shadow: 0 28px 72px rgba(37, 45, 61, 0.22);
+      }
+      .clips-import-dialog::backdrop { background: rgba(31, 38, 53, 0.32); backdrop-filter: blur(6px); }
+      .clips-import-form { display: grid; gap: 14px; margin: 0; padding: 22px 22px 20px; }
+      .clips-import-head { display: grid; gap: 6px; }
+      .clips-import-head h3 { font-size: 1.5rem; letter-spacing: -0.03em; }
+      .clips-import-head p { font-size: 0.9rem; }
+      .clips-import-field { display: grid; gap: 6px; }
+      .clips-import-field textarea { min-height: 96px; border-radius: 18px; }
+      .clips-import-note { min-height: 18px; font-size: 0.85rem; color: var(--muted); }
+      .clips-import-note[data-tone="error"] { color: #9f3d3d; }
+      .clips-import-note[data-tone="success"] { color: #3f7d55; }
+      .clips-import-actions { display: flex; justify-content: flex-end; gap: 10px; }
+
+      @media (max-width: 1180px) {
+        .clips-frame { padding-left: 0; }
+        .editor-right-rail { position: relative; inset: auto; width: 100%; height: 540px; margin-top: 14px; border-radius: 24px; overflow: hidden; }
+        .editor-chat-panel { border-right: 0; border-radius: 24px; }
+      }
+      @media (min-width: 1025px) and (max-width: 1180px) {
+        html, body { height: auto; min-height: 100%; overflow: auto; overflow-x: hidden; }
+        .app-shell { height: auto; min-height: 100svh; }
+        .page-stack, .frame { height: auto; min-height: 0; overflow: visible; }
+        .clips-scroll { overflow: visible; padding-right: 0; }
+      }
+      @media (max-width: 1024px) {
+        .clips-shell { grid-template-rows: auto auto; }
+        .clips-scroll { overflow: visible; padding-right: 0; }
+      }
+    `,
+        body: `
+      <section class="frame clips-frame">
+        <header class="topbar">
+          ${renderBrandLockup({ displayName: input.name, email: input.email, accountId: input.currentAccountId })}
+          <div class="topbar-actions">
+            ${renderPrimaryNav({ loggedIn: true, current: "library", accountId: input.currentAccountId })}
+          </div>
+        </header>
+        <div class="frame-body">
+          <section class="clips-shell">
+            <div class="clips-toolbar">
+              <div class="clips-toolbar-row">
+                <div class="view-toggle" role="tablist" aria-label="Library view">
+                  <a class="view-toggle-tab" role="tab" href="${escapeAttribute(libraryHref)}">Finished</a>
+                  <a class="view-toggle-tab is-active" role="tab" aria-current="page" href="${escapeAttribute(clipsHref)}">Clips</a>
+                </div>
+                <form class="clips-search" 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>
+                <button type="button" class="secondary" id="importSourceBtn">Import Source</button>
+              </div>
+              <div class="clips-status" id="status">Loading your clips…</div>
+            </div>
+            <div class="clips-scroll">
+              <div class="clips-grid" id="grid"></div>
+            </div>
+          </section>
+        </div>
+      </section>
+      <aside class="editor-right-rail" aria-label="Clip curator chat"><div class="editor-chat-panel" data-template-editor-chat-root></div></aside>
+      <dialog class="clips-import-dialog" id="importDialog">
+        <form class="clips-import-form" id="importForm" method="dialog">
+          <div class="clips-import-head">
+            <div class="label">Import source</div>
+            <h3>Mine a video into clips</h3>
+            <p>Paste a video URL — TikTok, YouTube, Instagram, X, or a direct link. We'll scan it and add the matching moments to your clip library.</p>
+          </div>
+          <div class="clips-import-field">
+            <label for="importUrl">Video URL</label>
+            <input id="importUrl" name="url" type="url" placeholder="https://youtube.com/watch?v=… or https://…/video.mp4" autocomplete="off" required />
+          </div>
+          <div class="clips-import-field">
+            <label for="importPrompt">What to clip for</label>
+            <textarea id="importPrompt" name="prompt" placeholder="Clip scenes of people with food, no text on screen, vertical, between 5-10 secs long"></textarea>
+          </div>
+          <div class="clips-import-note" id="importNote"></div>
+          <div class="clips-import-actions">
+            <button type="button" class="secondary" id="importCancel">Cancel</button>
+            <button type="submit" id="importSubmit">Start scan</button>
+          </div>
+        </form>
+      </dialog>
+      <script>
+        (function(){
+          var grid = document.getElementById('grid');
+          var statusEl = document.getElementById('status');
+          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 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 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 card(clip){
+            var range = fmtClock(clip.start_time_sec)+'–'+fmtClock(clip.end_time_sec);
+            var score = (clip.score!=null) ? '<div class="clip-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 class="clip-noimg">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="clip-tag">'+esc(t)+'</span>'; }).join('');
+            return '<div class="clip-card">'
+              + '<div class="clip-thumb" onmouseleave="var v=this.querySelector(&quot;video&quot;); if(v){v.pause();v.style.display=&quot;none&quot;;}">'+media+vid+'<div class="clip-range">'+range+' · '+clip.duration_sec.toFixed(1)+'s</div>'+score+'</div>'
+              + '<div class="clip-body">'
+              + '<div class="clip-desc">'+esc(clip.description||clip.tags&&clip.tags.transcript||'(untagged clip)')+'</div>'
+              + '<div class="clip-tags">'+tags+'</div>'
+              + '<div class="clip-row"><span class="clip-src" title="'+esc(clip.source_filename)+'">'+esc(clip.source_filename)+'</span>'
+              + '<a class="clip-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 render(clips, label){
+            if(!clips || clips.length===0){
+              statusEl.innerHTML = label || '';
+              grid.innerHTML = '<div class="clips-empty">No Clips Yet. Click "Import Source" to begin</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 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>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 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 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); }
+          form.addEventListener('submit', function(e){
+            e.preventDefault();
+            var q = input.value.trim();
+            if(q) search(q, null); else loadFeed();
           });
-        });
-      }).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();
-  });
+          // ── Import Source modal ────────────────────────────────────────
+          var importBtn = document.getElementById('importSourceBtn');
+          var importDialog = document.getElementById('importDialog');
+          var importForm = document.getElementById('importForm');
+          var importUrl = document.getElementById('importUrl');
+          var importPrompt = document.getElementById('importPrompt');
+          var importNote = document.getElementById('importNote');
+          var importCancel = document.getElementById('importCancel');
+          var importSubmit = document.getElementById('importSubmit');
+          var scanPoll = null;
 
-  loadPresets();
-  loadFeed();
-})();
-</script>
-</body>
-</html>`;
+          function setNote(msg, tone){
+            if(!importNote) return;
+            importNote.textContent = msg || '';
+            if(tone) importNote.setAttribute('data-tone', tone); else importNote.removeAttribute('data-tone');
+          }
+          function openImport(){
+            setNote('');
+            if(importDialog && typeof importDialog.showModal === 'function' && !importDialog.open) importDialog.showModal();
+            if(importUrl) importUrl.focus();
+          }
+          function closeImport(){
+            if(importDialog && importDialog.open) importDialog.close();
+          }
+          function pollScan(scanId){
+            if(scanPoll) clearInterval(scanPoll);
+            var tries = 0;
+            scanPoll = setInterval(function(){
+              tries++;
+              if(tries > 200){ clearInterval(scanPoll); scanPoll=null; statusEl.textContent='Still scanning in the background — check back shortly.'; return; }
+              fetch('/clips/scan/'+encodeURIComponent(scanId), {credentials:'same-origin', headers:{Accept:'application/json'}})
+                .then(function(r){ return r.ok ? r.json() : null; })
+                .then(function(d){
+                  if(!d) return;
+                  var src = d.source || {};
+                  var status = src.status || (d.scan && d.scan.status) || 'running';
+                  if(status==='complete'){
+                    clearInterval(scanPoll); scanPoll=null;
+                    statusEl.textContent='Import complete — refreshing your clips…';
+                    loadFeed();
+                  } else if(status==='failed'||status==='error'){
+                    clearInterval(scanPoll); scanPoll=null;
+                    statusEl.textContent='Import failed: '+(src.error||(d.scan&&d.scan.error)||'the source could not be scanned.');
+                  } else {
+                    statusEl.textContent='Scanning source… ('+status+')';
+                  }
+                }).catch(function(){});
+            }, 4000);
+          }
+
+          if(importBtn) importBtn.addEventListener('click', openImport);
+          if(importCancel) importCancel.addEventListener('click', closeImport);
+          if(importDialog) importDialog.addEventListener('click', function(e){
+            var rect = importDialog.getBoundingClientRect();
+            if(e.clientX<rect.left||e.clientX>rect.right||e.clientY<rect.top||e.clientY>rect.bottom) closeImport();
+          });
+          if(importForm) importForm.addEventListener('submit', function(e){
+            e.preventDefault();
+            var url = (importUrl && importUrl.value || '').trim();
+            var prompt = (importPrompt && importPrompt.value || '').trim();
+            if(!url){ setNote('Enter a video URL.', 'error'); return; }
+            setNote('Starting scan…');
+            if(importSubmit) importSubmit.disabled = true;
+            fetch('/clips/scan', {method:'POST', credentials:'same-origin', headers:{'Content-Type':'application/json', Accept:'application/json'}, body: JSON.stringify({source_url:url, prompt:prompt})})
+              .then(function(r){ return r.json().then(function(d){ return {ok:r.ok, status:r.status, data:d}; }); })
+              .then(function(res){
+                if(importSubmit) importSubmit.disabled = false;
+                if(!res.ok){ setNote((res.data && res.data.error) || 'Could not start the scan.', 'error'); return; }
+                setNote('Scan started — this can take a few minutes.', 'success');
+                statusEl.textContent='Scanning source…';
+                closeImport();
+                if(importForm.reset) importForm.reset();
+                if(res.data && res.data.scan_id) pollScan(res.data.scan_id);
+              })
+              .catch(function(){
+                if(importSubmit) importSubmit.disabled = false;
+                setNote('Network error — please try again.', 'error');
+              });
+          });
+
+          loadFeed();
+        })();
+      </script>
+    `
+    });
 }
 async function resolveCustomerProviderKey(customerId, provider) {
     const rows = (await listProviderKeysWithSecretsForCustomer(customerId));
@@ -15209,9 +15578,22 @@ function clipKeywordMatch(clip, q) {
         .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 — the Clips gallery, rendered in the same shell as the rest of the
+// frontend and reached via the Library page's "Finished / Clips" toggle. The
+// client fetches /clips/feed with the session cookie (mirrors /discover vs /feed).
+app.get(CLIPS_PREFIX, async (c) => {
+    const customer = await getPreferredBrowserCustomer(c);
+    if (!customer) {
+        return redirect(c, "/login");
+    }
+    return c.html(renderClipsPage({
+        userId: customer.id,
+        currentAccountId: customer.id,
+        name: customer.name,
+        email: customer.email,
+        editorChat: await buildClipsEditorChatBoot({ customer })
+    }));
+});
 // 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);
@@ -15331,14 +15713,79 @@ app.post(`${CLIPS_PREFIX}/match-scenes`, async (c) => {
     }
 });
 // POST /clips/scan — kick off a cloud scan of an uploaded/staged source video.
+// Inherently ASYNC: returns 202 + scan_id immediately; the Step Functions
+// pipeline runs the hunt and GET /clips/scan/:scanId polls it. Billing is AWS
+// compute only (clip_scan_lambda + step_functions_standard) — the AI spend is
+// the caller's own provider key (BYOK) and is never wallet-billed.
 app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
     const customer = requireCustomer(c);
     try {
         const body = (await c.req.json());
+        const guidancePrompt = body.prompt?.trim() || "";
+        // Build the hunt spec: explicit structured fields win, the free "what to
+        // clip for" prompt fills the gaps (duration band, vertical/aspect, no-text).
+        // A pasted "Import Source" URL rides in hunt_spec.source_url — the clip-scan
+        // Lambda ingests it (RapidAPI, incl. TikTok/YouTube/IG/X) into the user's
+        // 30-day temp folder before scanning.
+        const sourceUrl = readNonEmptyString(body.source_url) ?? readNonEmptyString(body.video_url) ?? readNonEmptyString(body.url);
+        if (sourceUrl && !/^https?:\/\//i.test(sourceUrl)) {
+            return c.json({ error: "That doesn't look like a valid video URL." }, 400);
+        }
+        const huntSpec = normalizeHuntSpec({
+            ...(body.hunt_spec && typeof body.hunt_spec === "object" ? body.hunt_spec : {}),
+            ...(body.ranges != null ? { ranges: body.ranges } : {}),
+            ...(body.target_duration_sec != null ? { target_duration_sec: body.target_duration_sec } : {}),
+            ...(body.aspect != null ? { aspect: body.aspect } : {}),
+            ...(body.crop_focus != null ? { crop_focus: body.crop_focus } : {}),
+            ...(body.avoid_text != null ? { avoid_text: body.avoid_text } : {}),
+            ...(body.no_text != null ? { no_text: body.no_text } : {})
+        });
+        const parsedPrompt = parseClipHuntPrompt(guidancePrompt);
+        if (!huntSpec.windows?.length && parsedPrompt.windows.length)
+            huntSpec.windows = parsedPrompt.windows;
+        if (!huntSpec.duration_band && parsedPrompt.target_duration_sec != null) {
+            const band = resolveDurationBand(parsedPrompt.target_duration_sec);
+            if (band)
+                huntSpec.duration_band = band;
+        }
+        if (!huntSpec.aspect && parsedPrompt.aspect)
+            huntSpec.aspect = parsedPrompt.aspect;
+        if (!huntSpec.avoid_text && parsedPrompt.avoid_text)
+            huntSpec.avoid_text = true;
+        if (!huntSpec.source_url && sourceUrl)
+            huntSpec.source_url = sourceUrl;
+        // Uploaded-source hunts: resolve a temp-folder file (the canonical home for
+        // hunt originals — 30-day TTL) or a My Files attachment to its S3 key.
+        let resolvedS3Key = readNonEmptyString(body.s3_key) ?? undefined;
+        const tempFileId = readNonEmptyString(body.temp_file_id);
+        const attachmentId = readNonEmptyString(body.attachment_id);
+        if (!body.raw_s3_uri && !resolvedS3Key && tempFileId) {
+            const file = await serverlessRecords.getUserTemporaryFile(customer.id, tempFileId);
+            if (!file)
+                return c.json({ error: "Temporary file not found — upload it first via /api/v1/user/me/temporary-files." }, 404);
+            resolvedS3Key = file.storageKey;
+        }
+        else if (!body.raw_s3_uri && !resolvedS3Key && attachmentId) {
+            const attachment = await serverlessRecords.getUserAttachment(customer.id, attachmentId);
+            if (!attachment)
+                return c.json({ error: "Attachment not found in My Files." }, 404);
+            resolvedS3Key = attachment.storageKey;
+        }
         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);
+            (resolvedS3Key && config.AWS_S3_BUCKET ? `s3://${config.AWS_S3_BUCKET}/${resolvedS3Key}` : undefined);
+        if (!rawS3Uri && !huntSpec.source_url) {
+            return c.json({ error: "Provide source_url (a video URL), temp_file_id/attachment_id of an upload, raw_s3_uri (s3://…), or s3_key of the staged source video." }, 400);
+        }
+        // Hunts bill AWS compute post-hoc, so submission is the spend gate (same
+        // policy as job submission).
+        try {
+            await assertWalletCanQueueJobs(customer.id);
+        }
+        catch (error) {
+            if (error instanceof InsufficientWalletFundsError) {
+                return insufficientFundsResponse(c, error);
+            }
+            throw error;
         }
         const provider = normalizeClipProvider(body.provider);
         const built = await buildCustomerClipClient(customer.id, provider);
@@ -15348,26 +15795,39 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
         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 tracer = readNonEmptyString(body.tracer) ?? `clips_import:${customer.id}`;
         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, {
+        // The URL ingest is deferred to the Lambda, so raw_s3_uri may be empty here.
+        const sourcePointer = rawS3Uri ?? huntSpec.source_url ?? "";
+        const filename = body.filename || (sourcePointer.split("/").pop() || "source.mp4").split("?")[0] || "source.mp4";
+        // Time-range hunts only pay for the windows: both estimates use the
+        // EFFECTIVE (windowed) duration, and the duration band drives the expected
+        // scene size. The BYOK estimate is the user's own provider spend; the
+        // compute estimate is what the wallet will be billed (AWS only, marked up).
+        const effectiveDurationSec = body.duration_sec && body.duration_sec > 0
+            ? effectiveHuntDurationSec(body.duration_sec, huntSpec.windows)
+            : null;
+        const estimate = effectiveDurationSec
+            ? estimateScanCostFromDuration(effectiveDurationSec, {
                 tier,
                 provider,
                 tagModelId: client.tagModelId,
                 embedModelId: client.embeddingModelId,
                 framesPerScene,
-                includeAudio
+                includeAudio,
+                avgSceneSec: huntSpec.duration_band?.target_sec
             })
             : null;
+        const computeEstimate = effectiveDurationSec
+            ? estimateClipScanComputeUsd(effectiveDurationSec, huntSpec.duration_band?.target_sec)
+            : null;
         const source = {
             source_video_id: sourceVideoId,
             owner_id: customer.id,
             filename,
-            raw_s3_uri: rawS3Uri,
+            raw_s3_uri: sourcePointer,
             duration_sec: body.duration_sec,
             clip_count: 0,
             tier,
@@ -15387,7 +15847,7 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
                     owner_id: customer.id,
                     source_video_id: sourceVideoId,
                     source_filename: filename,
-                    raw_s3_uri: rawS3Uri,
+                    raw_s3_uri: rawS3Uri ?? "",
                     tier,
                     provider,
                     tag_api_key: tagApiKey,
@@ -15395,7 +15855,9 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
                     embedding_api_key: embeddingKey ?? "",
                     guidance_prompt: guidancePrompt,
                     frames_per_scene: framesPerScene,
-                    include_audio: includeAudio
+                    include_audio: includeAudio,
+                    hunt_spec: huntSpec,
+                    tracer
                 })
             }));
             executionArn = res.executionArn;
@@ -15406,8 +15868,9 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
             source_video_id: sourceVideoId,
             status: executionArn ? "running" : "queued",
             tier,
-            raw_s3_uri: rawS3Uri,
+            raw_s3_uri: sourcePointer,
             execution_arn: executionArn,
+            tracer,
             created_at: now,
             updated_at: now
         };
@@ -15417,7 +15880,10 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
             source_video_id: sourceVideoId,
             status: scan.status,
             execution_arn: executionArn ?? null,
+            tracer,
+            hunt_spec: huntSpec,
             estimate,
+            compute_estimate: computeEstimate,
             pipeline_deployed: Boolean(config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN)
         }, 202);
     }
@@ -15428,9 +15894,32 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
 // 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"));
+    let scan = await clipRecords.getScan(customer.id, c.req.param("scanId"));
     if (!scan)
         return c.json({ error: "Scan not found" }, 404);
+    // Lazily reconcile with the Step Functions execution: the pipeline has no
+    // failure hook back into the scan record, so a crashed execution would
+    // otherwise leave "running" forever and pollers spin.
+    if ((scan.status === "running" || scan.status === "queued") && scan.execution_arn) {
+        try {
+            const desc = await clipScanSfn.send(new DescribeExecutionCommand({ executionArn: scan.execution_arn }));
+            if (desc.status === "FAILED" || desc.status === "TIMED_OUT" || desc.status === "ABORTED") {
+                scan = { ...scan, status: "failed", error: `Scan pipeline ${desc.status.toLowerCase().replace("_", " ")}.`, updated_at: nowIso() };
+                await clipRecords.putScan(scan);
+                const failedSource = await clipRecords.getSource(customer.id, scan.source_video_id);
+                if (failedSource && failedSource.status !== "complete") {
+                    await clipRecords.putSource({ ...failedSource, status: "failed", updated_at: nowIso() });
+                }
+            }
+            else if (desc.status === "SUCCEEDED") {
+                scan = { ...scan, status: "complete", updated_at: nowIso() };
+                await clipRecords.putScan(scan);
+            }
+        }
+        catch (error) {
+            devLog("clip_scan.reconcile_failed", { scan_id: scan.scan_id, ...devErrorFields(error) }, "warn");
+        }
+    }
     const source = await clipRecords.getSource(customer.id, scan.source_video_id);
     return c.json({ scan, source });
 });