@mevdragon/vidfarm-devcli 0.13.0 → 0.14.0

package/dist/src/account-pages-legacy.js

@@ -6831,7 +6831,9 @@ export function renderLibraryPage(input) {
 
       .library-frame { padding-left: 432px; }
       .library-body, .library-shell, .library-list-shell { min-height: 0; }
-      .library-shell { display: grid; grid-template-rows: auto minmax(0, 1fr); gap: 12px; }
+      /* minmax(0,1fr) column: without it the implicit track grows to the
+         toolbar's min-content width and the whole page overflows on phones. */
+      .library-shell { display: grid; grid-template-columns: minmax(0, 1fr); grid-template-rows: auto minmax(0, 1fr); gap: 12px; }
       .library-toolbar {
         display: grid;
         grid-template-columns: auto minmax(200px, 1fr) auto auto;
@@ -7036,11 +7038,15 @@ export function renderLibraryPage(input) {
       ${renderReadyPostScheduleStyles()}
       @media (max-width: 1180px) {
         .library-frame { padding-left: 0; }
-        .editor-right-rail { position: relative; width: 100%; height: 560px; margin-top: 14px; border-radius: 24px; overflow: hidden; }
         .library-post { grid-template-columns: auto 248px minmax(0, 1fr); }
         .library-post-actions { grid-column: 3; justify-content: flex-start; }
         .library-post[data-collapsed="true"] .library-post-actions { grid-column: auto; }
       }
+      @media (min-width: 1025px) and (max-width: 1180px) {
+        /* Rail stacks inline below the content in this band only; at ≤1024px
+           the shared shell turns the rail into the FAB + popup overlay. */
+        .editor-right-rail { position: relative; width: 100%; height: 560px; margin-top: 14px; border-radius: 24px; overflow: hidden; }
+      }
       @media (min-width: 1025px) and (max-width: 1180px) {
         /* The chat rail stacks below the frame at 1180px but the shell only unlocks
            document scroll at 1024px; unlock it here too so stacked content stays reachable. */
@@ -7129,18 +7135,7 @@ export function renderLibraryPage(input) {
           grid-row: 2;
         }
         .library-frame { padding-left: 0; }
-        .editor-right-rail {
-          position: fixed !important;
-          inset: 0;
-          z-index: 110;
-          width: 100%;
-          height: 100svh;
-          min-height: 0;
-          margin: 0;
-          border-radius: 0;
-          overflow: visible;
-          pointer-events: none;
-        }
+        /* Rail overlay + FAB + popup at ≤1024px come from the shared shell styles. */
         .library-body { padding-top: 12px; }
         .library-shell { min-width: 0; }
         .library-list-shell { overflow: visible; padding-right: 0; }

package/dist/src/app.js

@@ -23,7 +23,7 @@ import { writeForkManifest } from "./services/fork-manifest.js";
 import { renderHelpPage } from "./help-page.js";
 import { renderHomepage } from "./homepage.js";
 import { COMPOSITION_RUNTIME_SCRIPT_BODY } from "./composition-runtime.js";
-import { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_CSS, TRANSITION_STYLE_MARKER } from "./hyperframes/composition.js";
+import { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_CSS, TRANSITION_STYLE_MARKER, upgradeLegacyTransitionCss } from "./hyperframes/composition.js";
 import { normalizeCompositionZIndexHtml, sanitizeCompositionHtml } from "./services/composition-sanitize.js";
 import { applyMarkupUsd } from "./services/billing-pricing.js";
 import { primitiveRegistry } from "./primitive-registry.js";
@@ -54,7 +54,7 @@ import { loadSpeechAudioLocally, MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES } from "./devc
 import { DescribeExecutionCommand, SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
 import { clipRecords, makeUserPreset } from "./services/clip-records.js";
 import { matchScenesToClips, searchUserClips, vectorIndex } from "./services/clip-search.js";
-import { BUILTIN_PRESETS, buildEffectiveGuidance, ClipModelClient, detectLocalAgent, effectiveHuntDurationSec, estimateScanCostFromDuration, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, probeVideo, resolveDurationBand, scanVideo } from "./services/clip-curation/index.js";
+import { BUILTIN_PRESETS, buildEffectiveGuidance, ClipModelClient, cosineSimilarity, detectLocalAgent, effectiveHuntDurationSec, estimateScanCostFromDuration, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, probeVideo, resolveDurationBand, scanVideo } 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";
@@ -401,7 +401,16 @@ const userAttachmentFinalizeSchema = z.object({
     content_type: z.string().trim().min(1).max(255),
     size_bytes: z.coerce.number().int().min(1).max(1024 * 1024 * 1024),
     storage_key: z.string().min(1).max(2000),
-    folder_path: z.string().trim().max(500).optional()
+    folder_path: z.string().trim().max(500).optional(),
+    notes: z.string().trim().max(4000).optional()
+});
+const userAttachmentNotesSchema = z.object({
+    notes: z.string().max(4000).nullable().optional()
+});
+const userAttachmentSearchSchema = z.object({
+    query: z.string().min(1).max(2000),
+    folder_path: z.string().trim().max(500).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional()
 });
 const userFileFolderSchema = z.object({
     folder_path: z.string().trim().min(1).max(500)
@@ -2917,6 +2926,9 @@ function serializeUserAttachment(c, attachment) {
         sizeBytes: attachment.sizeBytes,
         createdAt: attachment.createdAt,
         folderPath: attachment.folderPath ?? "",
+        notes: attachment.notes ?? null,
+        // Flag only — the raw vector never ships to the client (mirrors serializeClip).
+        hasNotesEmbedding: Boolean(attachment.notesEmbedding && attachment.notesEmbedding.length > 0),
         viewUrl: attachment.publicUrl || storage.getPublicUrl(attachment.storageKey) || buildUserAttachmentViewUrl(c, attachment.storageKey)
     };
 }
@@ -3975,16 +3987,19 @@ function browseFilesTextContentType(fileName) {
 }
 function createBrowseFilesTool(input) {
     return tool({
-        description: "Browse AND write the user's My Files filesystem — their personal library of uploaded assets (mp4, mov, webm, png, jpg, jpeg, gif, webp, svg, mp3, wav, m4a, aac, pdf, md, txt, csv, and more) organized into virtual folders. Use action=list to enumerate files and virtual folders so you can discover what assets exist; pass folder_path to scope the listing to one folder (omit or empty for the root). Use action=read to fetch one file by file_id (preferred; copy it from a prior list result) or by file_name: it returns the file's durable view_url plus metadata, and for text files (md, txt, csv, srt, vtt, json) it also returns the full text_content inline so you can read it. For images, video, audio, and PDFs it returns view_url only — reference that URL directly (drop it into composition layers, or pass it into primitive routes like images/edit source_image_url, videos/generate input_references, or videos/download); you cannot read their raw bytes as text. Use action=write to SAVE a text file into My Files — pass file_name (e.g. About.md), content (the full text), and optional folder_path to namescope it under a product/offer folder. This is how you persist Getting Started context the user can reuse later: a product About.md or Interview.md, and awareness-levels.md / persuasive-angles.md / ad-hooks.md distilled from brainstorm output. write only accepts text files (md, txt, csv, json, srt, vtt); to save generated images/video/audio use the primitive routes and reference their durable URLs. write returns the new file_id and view_url. Always list before you read so you use a real file_id; never invent file ids or view URLs.",
+        description: "Browse AND write the user's My Files filesystem — their personal library of uploaded assets (mp4, mov, webm, png, jpg, jpeg, gif, webp, svg, mp3, wav, m4a, aac, pdf, md, txt, csv, and more) organized into virtual folders. Use action=list to enumerate files and virtual folders so you can discover what assets exist; pass folder_path to scope the listing to one folder (omit or empty for the root). Use action=search to find files by MEANING when you don't know where something lives: pass query (plain language, e.g. 'character reference sheet for the mascot' or 'logo on transparent background') and it matches keywords AND vector-embedded metadata notes across every file's name, folder, and notes — prefer search over paging through list when My Files is large or the user references an asset vaguely. Use action=read to fetch one file by file_id (preferred; copy it from a prior list/search result) or by file_name: it returns the file's durable view_url plus metadata, and for text files (md, txt, csv, srt, vtt, json) it also returns the full text_content inline so you can read it. For images, video, audio, and PDFs it returns view_url only — reference that URL directly (drop it into composition layers, or pass it into primitive routes like images/edit source_image_url, videos/generate input_references, or videos/download); you cannot read their raw bytes as text. Use action=write to SAVE a text file into My Files — pass file_name (e.g. About.md), content (the full text), optional folder_path to namescope it under a product/offer folder, and optional notes. This is how you persist Getting Started context the user can reuse later: a product About.md or Interview.md, and awareness-levels.md / persuasive-angles.md / ad-hooks.md distilled from brainstorm output. write saves text files (md, txt, csv, json, srt, vtt) via content, or IMPORTS any media asset into the library by passing its durable URL as source_url — e.g. save a finished image job's output as character_sprite_card.png so it persists in My Files instead of living only in a job result. write returns the new file_id and view_url. Use action=annotate to set metadata notes on ANY existing file (including binary assets): notes say what the file is, who/what it depicts, and when to use it, and they are vector-embedded so future sessions can search their way back to the asset. Annotate every asset worth finding again — especially character references: keep a character_sprite_card.png plus an about_character.md per recurring character in that character's folder, annotate both, and pass the sprite card's view_url into generation reference inputs (images prompt_attachments / videos input_references) for character consistency. Always list or search before you read so you use a real file_id; never invent file ids or view URLs.",
         inputSchema: z.object({
-            action: z.enum(["list", "read", "write"]).describe("list = enumerate files and folders; read = fetch one file's view_url and, for text files, its contents; write = save a text file into My Files."),
-            folder_path: z.string().optional().describe("Folder to scope a list to, the folder of the file to read, or the folder to write into. Omit or leave empty for the root."),
-            file_id: z.string().optional().describe("Attachment id to read, copied from a prior list result. Preferred over file_name."),
-            file_name: z.string().optional().describe("File name to read when you do not have the id, or the name to save under for write (e.g. About.md). For read it is matched within folder_path when one is provided."),
-            content: z.string().optional().describe("For write: the full text content of the file to save (e.g. Markdown for About.md). Required for write; ignored otherwise."),
-            explanation: z.string().optional().describe("Short reason for the browse or save.")
+            action: z.enum(["list", "read", "write", "annotate", "search"]).describe("list = enumerate files and folders; read = fetch one file's view_url and, for text files, its contents; write = save a text file into My Files; annotate = set the metadata notes on one existing file; search = find files by meaning across names, folders, and notes."),
+            folder_path: z.string().optional().describe("Folder to scope a list or search to, the folder of the file to read, or the folder to write into. Omit or leave empty for the root."),
+            file_id: z.string().optional().describe("Attachment id to read or annotate, copied from a prior list/search result. Preferred over file_name."),
+            file_name: z.string().optional().describe("File name to read/annotate when you do not have the id, or the name to save under for write (e.g. About.md). Matched within folder_path when one is provided."),
+            content: z.string().optional().describe("For write: the full text content of the file to save (e.g. Markdown for About.md). Required for text writes; mutually exclusive with source_url."),
+            source_url: z.string().optional().describe("For write: a durable media URL (from a finished primitive job result or an existing asset) to IMPORT into My Files as file_name — this is how you save a generated character_sprite_card.png or other binary asset into the library. Mutually exclusive with content."),
+            notes: z.string().optional().describe("For annotate (required) or write (optional): metadata notes describing what the file is, who/what it depicts, and when to use it — e.g. 'Sprite card for Zara, our mascot: front/side/back views, teal jacket. Use as the reference image whenever generating Zara.' Notes are vector-embedded so search finds the file by meaning. For annotate, an empty string clears existing notes."),
+            query: z.string().optional().describe("For search: what you're looking for, in plain language. Required for search; ignored otherwise."),
+            explanation: z.string().optional().describe("Short reason for the browse, save, annotation, or search.")
         }),
-        execute: async ({ action, folder_path, file_id, file_name, content, explanation }) => {
+        execute: async ({ action, folder_path, file_id, file_name, content, source_url, notes, query, explanation }) => {
             const listUrl = new URL(`${USER_PREFIX}/me/attachments`, config.PUBLIC_BASE_URL);
             const headers = new Headers();
             headers.set("vidfarm-api-key", input.vidfarmApiKey);
@@ -3997,22 +4012,59 @@ function createBrowseFilesTool(input) {
                 if (action === "write") {
                     const name = (file_name ?? "").trim();
                     if (!name) {
-                        return { action, explanation: explanation ?? null, status: 400, error: "write requires file_name (e.g. About.md)." };
+                        return { action, explanation: explanation ?? null, status: 400, error: "write requires file_name (e.g. About.md, or character_sprite_card.png with source_url)." };
                     }
-                    if (typeof content !== "string") {
-                        return { action, explanation: explanation ?? null, status: 400, error: "write requires content (the full text of the file)." };
+                    const importSrc = (source_url ?? "").trim();
+                    let fileBlob;
+                    if (importSrc) {
+                        // Import a durable media URL (e.g. a finished primitive job's output)
+                        // into My Files. The api-key header only travels to our own origin.
+                        let sourceUrl;
+                        try {
+                            sourceUrl = new URL(importSrc, config.PUBLIC_BASE_URL);
+                        }
+                        catch {
+                            return { action, explanation: explanation ?? null, status: 400, error: `source_url is not a valid URL: ${importSrc.slice(0, 200)}` };
+                        }
+                        const sourceHeaders = new Headers();
+                        if (sourceUrl.origin === new URL(config.PUBLIC_BASE_URL).origin) {
+                            sourceHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
+                        }
+                        const sourceResponse = await fetch(sourceUrl, {
+                            method: "GET",
+                            headers: sourceHeaders,
+                            signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                        });
+                        if (!sourceResponse.ok) {
+                            return { action, explanation: explanation ?? null, status: sourceResponse.status, error: `Could not fetch source_url (${sourceResponse.status}). Use a durable URL from a finished job result or an existing asset.` };
+                        }
+                        const sourceBytes = await sourceResponse.arrayBuffer();
+                        if (sourceBytes.byteLength > 50 * 1024 * 1024) {
+                            return { action, explanation: explanation ?? null, status: 400, error: "source_url asset is larger than the 50 MB My Files limit." };
+                        }
+                        const sourceType = (sourceResponse.headers.get("content-type") ?? "").split(";")[0].trim();
+                        fileBlob = new Blob([sourceBytes], sourceType ? { type: sourceType } : undefined);
                     }
-                    if (!isBrowseFilesTextFile(name, "")) {
-                        return { action, explanation: explanation ?? null, status: 400, error: `write only supports text files (md, txt, csv, json, srt, vtt). "${name}" is not one; save generated media via primitive routes and reference their view_url instead.` };
+                    else {
+                        if (typeof content !== "string") {
+                            return { action, explanation: explanation ?? null, status: 400, error: "write requires content (the full text of the file) or source_url (a durable media URL to import)." };
+                        }
+                        if (!isBrowseFilesTextFile(name, "")) {
+                            return { action, explanation: explanation ?? null, status: 400, error: `write with content only supports text files (md, txt, csv, json, srt, vtt). To save media like "${name}", pass its durable URL as source_url instead.` };
+                        }
+                        fileBlob = new Blob([content], { type: browseFilesTextContentType(name) });
                     }
                     const uploadUrl = new URL(`${USER_PREFIX}/me/attachments/upload`, config.PUBLIC_BASE_URL);
                     const uploadHeaders = new Headers();
                     uploadHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
                     const form = new FormData();
-                    form.append("file", new Blob([content], { type: browseFilesTextContentType(name) }), name);
+                    form.append("file", fileBlob, name);
                     if (normalizedFolder) {
                         form.append("folder_path", normalizedFolder);
                     }
+                    if (typeof notes === "string" && notes.trim()) {
+                        form.append("notes", notes.trim());
+                    }
                     const writeResponse = await fetch(uploadUrl, {
                         method: "POST",
                         headers: uploadHeaders,
@@ -4047,11 +4099,65 @@ function createBrowseFilesTool(input) {
                             content_type: saved.contentType,
                             size_bytes: saved.sizeBytes,
                             folder_path: saved.folderPath ?? "",
+                            notes: saved.notes ?? null,
                             view_url: saved.viewUrl,
                             created_at: saved.createdAt
                         }
                     };
                 }
+                if (action === "search") {
+                    const q = (query ?? "").trim();
+                    if (!q) {
+                        return { action, explanation: explanation ?? null, status: 400, error: "search requires query (what you're looking for, in plain language)." };
+                    }
+                    const searchUrl = new URL(`${USER_PREFIX}/me/attachments/search`, config.PUBLIC_BASE_URL);
+                    const searchHeaders = new Headers();
+                    searchHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
+                    searchHeaders.set("Content-Type", "application/json");
+                    const searchResponse = await fetch(searchUrl, {
+                        method: "POST",
+                        headers: searchHeaders,
+                        body: JSON.stringify({ query: q, ...(normalizedFolder ? { folder_path: normalizedFolder } : {}), limit: 20 }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const searchText = await searchResponse.text();
+                    let searchJson = null;
+                    try {
+                        searchJson = searchText ? JSON.parse(searchText) : null;
+                    }
+                    catch {
+                        searchJson = null;
+                    }
+                    if (!searchResponse.ok || !Array.isArray(searchJson?.results)) {
+                        return {
+                            action,
+                            explanation: explanation ?? null,
+                            status: searchResponse.status,
+                            error: `My Files search failed (${searchResponse.status}). ${(searchJson?.error ?? searchText).slice(0, 500)}`
+                        };
+                    }
+                    return {
+                        action,
+                        explanation: explanation ?? null,
+                        status: 200,
+                        query: q,
+                        folder_path: normalizedFolder,
+                        semantic: Boolean(searchJson.semantic),
+                        result_count: searchJson.results.length,
+                        results: searchJson.results.map((file) => ({
+                            file_id: file.id,
+                            file_name: file.fileName,
+                            content_type: file.contentType,
+                            size_bytes: file.sizeBytes,
+                            folder_path: file.folderPath ?? "",
+                            notes: file.notes ?? null,
+                            similarity: file.similarity ?? null,
+                            keyword_match: Boolean(file.keyword_match),
+                            view_url: file.viewUrl,
+                            created_at: file.createdAt
+                        }))
+                    };
+                }
                 const listResponse = await fetch(listUrl, {
                     method: "GET",
                     headers,
@@ -4086,6 +4192,7 @@ function createBrowseFilesTool(input) {
                             content_type: file.contentType,
                             size_bytes: file.sizeBytes,
                             folder_path: file.folderPath ?? "",
+                            notes: file.notes ?? null,
                             view_url: file.viewUrl,
                             created_at: file.createdAt
                         }))
@@ -4104,7 +4211,56 @@ function createBrowseFilesTool(input) {
                         status: 404,
                         error: file_id || file_name
                             ? "No matching file in My Files. Call action=list first to copy an exact file_id."
-                            : "read requires file_id (preferred) or file_name."
+                            : `${action} requires file_id (preferred) or file_name.`
+                    };
+                }
+                if (action === "annotate") {
+                    if (typeof notes !== "string") {
+                        return { action, explanation: explanation ?? null, status: 400, error: "annotate requires notes (the metadata to attach; empty string clears)." };
+                    }
+                    const annotateUrl = new URL(`${USER_PREFIX}/me/attachments/${encodeURIComponent(match.id)}`, config.PUBLIC_BASE_URL);
+                    const annotateHeaders = new Headers();
+                    annotateHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
+                    annotateHeaders.set("Content-Type", "application/json");
+                    const annotateResponse = await fetch(annotateUrl, {
+                        method: "PATCH",
+                        headers: annotateHeaders,
+                        body: JSON.stringify({ notes }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const annotateText = await annotateResponse.text();
+                    let annotateJson = null;
+                    try {
+                        annotateJson = annotateText ? JSON.parse(annotateText) : null;
+                    }
+                    catch {
+                        annotateJson = null;
+                    }
+                    if (!annotateResponse.ok || !annotateJson?.attachment) {
+                        return {
+                            action,
+                            explanation: explanation ?? null,
+                            status: annotateResponse.status,
+                            error: `Could not annotate file (${annotateResponse.status}). ${(annotateJson?.error ?? annotateText).slice(0, 500)}`
+                        };
+                    }
+                    const annotated = annotateJson.attachment;
+                    return {
+                        action,
+                        explanation: explanation ?? null,
+                        status: 200,
+                        annotated: true,
+                        notes_embedded: Boolean(annotateJson.notes_embedded),
+                        file: {
+                            file_id: annotated.id,
+                            file_name: annotated.fileName,
+                            content_type: annotated.contentType,
+                            size_bytes: annotated.sizeBytes,
+                            folder_path: annotated.folderPath ?? "",
+                            notes: annotated.notes ?? null,
+                            view_url: annotated.viewUrl,
+                            created_at: annotated.createdAt
+                        }
                     };
                 }
                 const fileInfo = {
@@ -4113,6 +4269,7 @@ function createBrowseFilesTool(input) {
                     content_type: match.contentType,
                     size_bytes: match.sizeBytes,
                     folder_path: match.folderPath ?? "",
+                    notes: match.notes ?? null,
                     view_url: match.viewUrl,
                     created_at: match.createdAt
                 };
@@ -4231,8 +4388,9 @@ function createEditorActionTool() {
                 "replace_composition_html",
                 "export_composition",
                 "generate_layer",
-                "set_captions"
-            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url. Use set_captions to lay down a full run of ANIMATED word-by-word captions (TikTok/CapCut style): pass captions[] cues (or text + start/duration to auto-page), plus caption_style; it replaces any existing animated caption layers. To restyle existing captions without changing text/timing, use set_layer_style with caption_* fields on each caption layer."),
+                "set_captions",
+                "set_transitions"
+            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url. Use set_captions to lay down a full run of ANIMATED word-by-word captions (TikTok/CapCut style): pass captions[] cues (or text + start/duration to auto-page), plus caption_style; it replaces any existing animated caption layers. To restyle existing captions without changing text/timing, use set_layer_style with caption_* fields on each caption layer. Use set_transitions to configure scene transitions across the WHOLE timeline in one call: transition = the junction preset applied at every cut (every scene clip except each track's first; 'none' clears), transition_intro = the first clip's entrance, transition_outro = the last clip's exit."),
             layer_key: z.string().optional().describe("Existing layer key from editor_context (required for remove/set/duplicate/split). MAY be either the element_id (data-hf-id) or the slug (data-hf-slug). For add_layer, optionally provide a stable id (starts with a letter, [A-Za-z0-9_-], <=64 chars) to reuse in later tool calls this turn."),
             slug: z.string().optional().describe("snake_case slug for the layer. On add_layer, seeds data-hf-slug. On set_layer_identity, sets it. Slugs give viral DNA a stable handle for the element."),
             note: z.string().optional().describe("Human-facing note explaining the layer's role, referenced by viral DNA. On add_layer seeds data-hf-note. On set_layer_identity, sets it. Empty string removes."),
@@ -4265,8 +4423,12 @@ function createEditorActionTool() {
             object_position: z.string().optional().describe("CSS object-position for image/video (e.g., center, top, bottom left)."),
             ken_burns: z.enum(["zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right", "none"]).optional().describe("Ken Burns motion for still-image layers: a slow pan/zoom spanning the clip's full duration. Apply with set_layer_media on an existing image, or seed it on add_layer/generate_layer when kind/media_type is image. 'none' removes the effect. When the user says 'animate the images' / 'ken burns', apply it to every still image, varying presets across adjacent clips (zoom-in, pan-left, zoom-out, ...) for a documentary feel."),
             ken_burns_intensity: z.number().optional().describe("Ken Burns strength: extra zoom / pan travel as a fraction of the frame, 0.04-0.5 (default 0.18; ~0.1 subtle, ~0.3 dramatic). Only meaningful alongside ken_burns."),
-            transition: z.enum(["crossfade", "fade-black", "slide-left", "slide-right", "slide-up", "slide-down", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open", "none"]).optional().describe("Scene transition INTO this clip at its start, from the previous clip on the same track. Set it on the INCOMING clip (the one after the cut) with set_layer_media, or seed it on add_layer/generate_layer. Works on video and image scene clips; 'none' removes it. The previous butt-cut clip is automatically held on screen beneath the incoming one for the transition window — do not retime anything yourself. When the user asks for 'transitions between scenes' / 'smooth cuts', apply one to EVERY scene clip except the first, varying or matching presets to the template's energy (crossfade/fade-black = calm, slide/wipe = energetic, zoom/circle-open = punchy)."),
-            transition_duration: z.number().optional().describe("Transition length in seconds, 0.1-2.5 (default 0.5; ~0.3 snappy, ~1.0 slow cinematic). Only meaningful alongside transition."),
+            transition: z.enum(["crossfade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "whip-left", "whip-right", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open", "none"]).optional().describe("Scene transition INTO this clip at its start, from the previous clip on the same track. Set it on the INCOMING clip (the one after the cut) with set_layer_media, or seed it on add_layer/generate_layer. On set_transitions it is the junction preset applied at EVERY cut. Works on video and image scene clips; 'none' removes it. The previous butt-cut clip is automatically held on screen beneath the incoming one for the transition window — do not retime anything yourself. Preset energy: crossfade/fade-black/fade-white/blur = calm, smoke = dreamy, slide/wipe = energetic, whip/flash = fast-paced social, zoom/circle-open = punchy."),
+            transition_duration: z.number().optional().describe("Transition length in seconds, 0.1-2.5 (default 0.5; ~0.3 snappy, ~1.0 slow cinematic). Only meaningful alongside transition/transition_intro."),
+            transition_out: z.enum(["fade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-close", "none"]).optional().describe("Exit transition OUT of this clip at its end (fade to black, slide away, ...). Set it with set_layer_media on the clip that should animate away, or seed it on add_layer/generate_layer. The animation plays over the clip's last transition_out_duration seconds; no retiming needed. Most cuts only need the incoming clip's transition — use transition_out for ending a video (fade to black), for clips followed by a gap, or for deliberate dip-to-black moments (outgoing fade-black + incoming fade-black)."),
+            transition_out_duration: z.number().optional().describe("Exit transition length in seconds, 0.1-2.5 (default 0.5). Only meaningful alongside transition_out/transition_outro."),
+            transition_intro: z.enum(["crossfade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "whip-left", "whip-right", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open", "none"]).optional().describe("set_transitions only: entrance for the very FIRST scene clip (fade in from black = fade-black). 'none' clears it."),
+            transition_outro: z.enum(["fade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-close", "none"]).optional().describe("set_transitions only: exit for the very LAST scene clip (fade to black = fade-black). 'none' clears it."),
             caption_style: z.enum(["spotlight", "karaoke", "word-pop", "stack-up", "neon", "bounce"]).optional().describe("Animated caption preset look: spotlight (active word gets a highlight pill, bold outline text), karaoke (words fill with color as spoken), word-pop (one word at a time, punchy scale-in), stack-up (words fade/rise in and stay), neon (active word glow pulse), bounce (active word bounces). Applies animation + colors + background treatment in one go; individual caption_*/color/background/background_style fields override specifics."),
             caption_animation: z.enum(["highlight-pop", "karaoke-fill", "word-pop", "cumulative-reveal", "glow-pulse", "bounce-wave", "none"]).optional().describe("Word-by-word caption animation, if you want to set it directly instead of via caption_style. Works on set_captions, add_layer (kind=text), and set_layer_style. 'none' removes the animation and flattens the layer back to static text."),
             caption_active_color: z.string().optional().describe("CSS color the active word takes while it is spoken (karaoke fill color, highlight text color, glow color)."),
@@ -4691,7 +4853,11 @@ function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
         }
     }
     // And the scene-transition keyframes: toggling data-transition on a clip
-    // must animate immediately on older stored compositions.
+    // must animate immediately on older stored compositions. Compositions that
+    // embed the V1 block get it swapped for the current one in place; if the
+    // swap misses (drifted block), the marker check below appends V2 after it,
+    // which wins by source order.
+    rewritten = upgradeLegacyTransitionCss(rewritten);
     if (!rewritten.includes(TRANSITION_STYLE_MARKER)) {
         const transitionTag = `<style data-vf-transitions="true">${TRANSITION_CSS}</style>`;
         if (/<\/head>/i.test(rewritten)) {
@@ -14772,6 +14938,52 @@ app.get(`${USER_PREFIX}/me/generated-media`, async (c) => {
         next_cursor: page.nextCursor
     });
 });
+// Embedder for My Files notes — the same BYOK seam clip search uses. Prefer the
+// provider matching the embedding model the file library was built with (from
+// the newest annotated attachment) so query vectors stay cosine-comparable; a
+// fresh library takes the first embed-capable key (gemini → openai; openrouter
+// can't embed). Null (no key) fail-softs notes search to keyword-only.
+async function buildFileNotesEmbedder(customerId) {
+    const attachments = await serverlessRecords.listUserAttachments(customerId);
+    const libModel = attachments.find((a) => a.notesEmbeddingModel && Array.isArray(a.notesEmbedding) && a.notesEmbedding.length > 0)?.notesEmbeddingModel ?? null;
+    const providers = libModel ? [libModel.startsWith("text-embedding") ? "openai" : "gemini"] : ["gemini", "openai"];
+    for (const provider of providers) {
+        const apiKey = await resolveCustomerProviderKey(customerId, provider);
+        if (!apiKey)
+            continue;
+        const client = new ClipModelClient({ provider, apiKey });
+        if (client.canEmbed)
+            return client;
+    }
+    return null;
+}
+// What we embed for a My Files entry: folder + file name + the notes, so
+// "the sprite card for our mascot" is findable from any phrasing. Fail-soft:
+// no key or an embed error still saves the notes (keyword-searchable).
+async function embedAttachmentNotes(customerId, input) {
+    if (!input.notes.trim())
+        return null;
+    try {
+        const embedder = await buildFileNotesEmbedder(customerId);
+        if (!embedder?.embeddingModelId)
+            return null;
+        const text = [input.folderPath, input.fileName, input.notes].filter(Boolean).join("\n");
+        const embedding = await embedder.embedQuery(text);
+        return embedding && embedding.length > 0 ? { embedding, model: embedder.embeddingModelId } : null;
+    }
+    catch (error) {
+        devLog("attachment_notes.embed_failed", devErrorFields(error));
+        return null;
+    }
+}
+function attachmentKeywordMatch(attachment, q) {
+    const hay = `${attachment.fileName} ${attachment.folderPath ?? ""} ${attachment.notes ?? ""}`.toLowerCase();
+    return q
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((term) => hay.includes(term));
+}
 app.get(`${USER_PREFIX}/me/attachments`, async (c) => {
     const customer = requireCustomer(c);
     const attachments = (await serverlessRecords.listUserAttachments(customer.id)).map((attachment) => serializeUserAttachment(c, attachment));
@@ -14850,6 +15062,7 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
         const fileName = sanitizeFileName(file.name || "upload.bin");
         const contentType = file.type || inferAttachmentContentType(fileName);
         const folderPath = sanitizeStorageSubpath(String(formData.get("folder_path") ?? ""));
+        const notes = String(formData.get("notes") ?? "").trim().slice(0, 4000) || null;
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported attachment type: ${fileName}` }, 400);
         }
@@ -14861,6 +15074,7 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
         const attachmentId = randomUUID();
         const storageKey = storage.userAttachmentKey(customer.id, attachmentId, fileName, folderPath);
         const stored = await storage.putBuffer(storageKey, buffer, contentType);
+        const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
         await serverlessRecords.createUserAttachment({
             id: attachmentId,
             customerId: customer.id,
@@ -14869,7 +15083,10 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
             sizeBytes: buffer.byteLength,
             storageKey,
             folderPath,
-            publicUrl: stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey)
+            publicUrl: stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey),
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
         });
         const attachment = await serverlessRecords.getUserAttachment(customer.id, attachmentId);
         if (!attachment) {
@@ -14898,6 +15115,8 @@ app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported attachment type: ${fileName}` }, 400);
         }
+        const notes = body.notes?.trim() || null;
+        const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
         await serverlessRecords.createUserAttachment({
             id: body.attachment_id,
             customerId: customer.id,
@@ -14906,7 +15125,10 @@ app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
             sizeBytes: body.size_bytes,
             storageKey: expectedStorageKey,
             folderPath,
-            publicUrl: storage.getPublicUrl(expectedStorageKey) || buildUserAttachmentViewUrl(c, expectedStorageKey)
+            publicUrl: storage.getPublicUrl(expectedStorageKey) || buildUserAttachmentViewUrl(c, expectedStorageKey),
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
         });
         const attachment = await serverlessRecords.getUserAttachment(customer.id, body.attachment_id);
         if (!attachment) {
@@ -14940,6 +15162,89 @@ app.patch(`${USER_PREFIX}/me/attachments/folders`, async (c) => {
     await serverlessRecords.moveUserAttachmentFolder(customer.id, fromFolder, toFolder);
     return c.json({ ok: true, from_folder_path: fromFolder, to_folder_path: toFolder });
 });
+// PATCH /me/attachments/:attachmentId — set/clear the metadata notes on one My
+// Files entry and (re)embed them for vector search. Notes are what make assets
+// findable by MEANING later — e.g. annotate a character_sprite_card.png with
+// who the character is so /me/attachments/search finds it from any phrasing.
+// (Registered after the /folders PATCH so "folders" never matches as an id.)
+app.patch(`${USER_PREFIX}/me/attachments/:attachmentId`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = userAttachmentNotesSchema.parse(await c.req.json());
+        const attachment = await serverlessRecords.getUserAttachment(customer.id, c.req.param("attachmentId"));
+        if (!attachment) {
+            return c.json({ error: "Attachment not found." }, 404);
+        }
+        const notes = (body.notes ?? "").trim() || null;
+        const embedded = notes
+            ? await embedAttachmentNotes(customer.id, { fileName: attachment.fileName, folderPath: attachment.folderPath, notes })
+            : null;
+        const updated = await serverlessRecords.updateUserAttachmentNotes(customer.id, attachment.id, {
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
+        });
+        if (!updated) {
+            return c.json({ error: "Attachment not found." }, 404);
+        }
+        return c.json({ ok: true, attachment: serializeUserAttachment(c, updated), notes_embedded: Boolean(embedded) });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to update attachment notes." }, 400);
+    }
+});
+// POST /me/attachments/search — find My Files entries by meaning, mirroring
+// /clips/search: keyword filter over name/folder/notes, semantically re-ranked
+// via the notes embeddings; when nothing keyword-matches, relax to a pure
+// semantic pass. Embeddings are BYOK — no saved key fail-softs to keyword-only.
+app.post(`${USER_PREFIX}/me/attachments/search`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = userAttachmentSearchSchema.parse(await c.req.json());
+        const query = body.query.trim();
+        if (!query) {
+            return c.json({ error: "Provide a search query." }, 400);
+        }
+        const folderPath = sanitizeStorageSubpath(body.folder_path);
+        const limit = Math.max(1, Math.min(100, body.limit ?? 20));
+        const all = await serverlessRecords.listUserAttachments(customer.id);
+        const scoped = folderPath ? all.filter((a) => (a.folderPath ?? "") === folderPath) : all;
+        let queryEmbedding;
+        try {
+            const embedder = await buildFileNotesEmbedder(customer.id);
+            if (embedder)
+                queryEmbedding = await embedder.embedQuery(query);
+        }
+        catch (error) {
+            devLog("attachment_search.embed_failed", devErrorFields(error));
+        }
+        const keywordIds = new Set(scoped.filter((a) => attachmentKeywordMatch(a, query)).map((a) => a.id));
+        const pool = keywordIds.size > 0 ? scoped.filter((a) => keywordIds.has(a.id)) : scoped;
+        const hits = pool
+            .map((a) => ({
+            attachment: a,
+            keyword: keywordIds.has(a.id),
+            similarity: queryEmbedding && Array.isArray(a.notesEmbedding) && a.notesEmbedding.length > 0
+                ? cosineSimilarity(a.notesEmbedding, queryEmbedding)
+                : undefined
+        }))
+            .filter((h) => h.keyword || (h.similarity ?? 0) > 0)
+            .sort((x, y) => ((y.similarity ?? 0) + (y.keyword ? 0.2 : 0)) - ((x.similarity ?? 0) + (x.keyword ? 0.2 : 0)))
+            .slice(0, limit);
+        return c.json({
+            results: hits.map((h) => ({
+                ...serializeUserAttachment(c, h.attachment),
+                similarity: h.similarity ?? null,
+                keyword_match: h.keyword
+            })),
+            semantic: Boolean(queryEmbedding),
+            folder_path: folderPath || null
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "My Files search failed." }, 400);
+    }
+});
 app.delete(`${USER_PREFIX}/me/attachments/folders`, async (c) => {
     const customer = requireCustomer(c);
     const body = userFileFolderSchema.parse(await c.req.json());
@@ -15519,20 +15824,31 @@ function renderClipsPage(input) {
       .clips-import-note[data-tone="success"] { color: #3f7d55; }
       .clips-import-actions { display: flex; justify-content: flex-end; gap: 10px; }
 
-      @media (max-width: 1180px) {
+      @media (min-width: 1025px) and (max-width: 1180px) {
+        /* Rail stacks inline below the content in this band only; at ≤1024px
+           the shared shell turns the rail into the FAB + popup overlay. */
         .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-frame { padding-left: 0; }
         .clips-shell { grid-template-rows: auto auto; }
         .clips-scroll { overflow: visible; padding-right: 0; }
+        .clips-toolbar-row { gap: 8px; }
+        .clips-search { flex: 1 1 100%; min-width: 0; }
+        .clips-search input { min-width: 0; font-size: 16px; }
+        .clips-import-form input,
+        .clips-import-form textarea,
+        .clips-import-form select { font-size: 16px; }
+      }
+      @media (max-width: 560px) {
+        .clips-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; }
+        .clip-body { padding: 10px; }
       }
     `,
         body: `