@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/dist/src/services/composition-lint.js

@@ -0,0 +1,199 @@
+// Static composition validation shared by the /editor chat copilot
+// (replace_composition_html preflight, both the in-process and Lambda copies),
+// the devcli (`vidfarm lint`), and publish preflights. Mirrors the checks the
+// HyperFrames CLI's `lint` runs against raw projects, adapted to vidfarm's
+// composition vocabulary (data-vf-* proxies, transition holds, caption spans).
+import { parseHTML } from "linkedom";
+import { CAPTION_ANIMATIONS, KEN_BURNS_PRESETS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS } from "../hyperframes/composition.js";
+const OVERLAP_EPSILON = 0.011;
+function parseNumberAttr(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function layerKeyFor(element) {
+    return (element.getAttribute("data-hf-id") ||
+        element.getAttribute("id") ||
+        element.getAttribute("data-hf-slug") ||
+        `<${element.tagName.toLowerCase()}>`);
+}
+export function lintCompositionHtml(html) {
+    const issues = [];
+    const push = (level, code, message, layer) => {
+        issues.push({ level, code, message, ...(layer ? { layer } : {}) });
+    };
+    const trimmed = typeof html === "string" ? html.trim() : "";
+    if (!trimmed) {
+        push("error", "empty_document", "Composition HTML is empty.");
+        return finalize(issues);
+    }
+    let document;
+    try {
+        ({ document } = parseHTML(trimmed));
+    }
+    catch (error) {
+        push("error", "unparseable_document", `Composition HTML could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+        return finalize(issues);
+    }
+    const root = document.querySelector("[data-composition-id]");
+    if (!root) {
+        push("error", "missing_composition_root", "No element carries data-composition-id — the composition root is required.");
+        return finalize(issues);
+    }
+    const width = parseNumberAttr(root.getAttribute("data-width"));
+    const height = parseNumberAttr(root.getAttribute("data-height"));
+    if (width === null || height === null) {
+        push("warning", "missing_canvas_size", "Composition root should declare numeric data-width and data-height (px).");
+    }
+    else if (width <= 0 || height <= 0) {
+        push("error", "invalid_canvas", `Composition root data-width/data-height must be positive (got ${width}x${height}).`);
+    }
+    const fpsRaw = root.getAttribute("data-fps");
+    if (fpsRaw !== null && (parseNumberAttr(fpsRaw) === null || parseNumberAttr(fpsRaw) <= 0)) {
+        push("warning", "invalid_fps", `Composition root data-fps is not a positive number (got "${fpsRaw}").`);
+    }
+    const clips = Array.from(document.querySelectorAll("[data-start]")).filter((el) => el !== root);
+    const rootDuration = parseNumberAttr(root.getAttribute("data-duration"));
+    if (rootDuration === null) {
+        if (clips.length === 0) {
+            push("error", "missing_root_duration", "Composition root has no data-duration and no timed clips to infer one from.");
+        }
+        else {
+            push("warning", "missing_root_duration", "Composition root has no data-duration; the runtime will infer it from the latest clip end. Declare it explicitly for deterministic renders.");
+        }
+    }
+    else if (rootDuration <= 0) {
+        push("error", "invalid_root_duration", `Composition root data-duration must be positive (got ${rootDuration}).`);
+    }
+    if (clips.length === 0) {
+        push("warning", "no_clips", "Composition has no timed clips ([data-start] elements).");
+    }
+    const timings = [];
+    const seenKeys = new Map();
+    for (const clip of clips) {
+        const key = layerKeyFor(clip);
+        const tag = clip.tagName.toLowerCase();
+        const isMedia = tag === "video" || tag === "audio";
+        const isProxy = clip.hasAttribute("data-vf-timeline-proxy");
+        const explicitKey = clip.getAttribute("data-hf-id") || clip.getAttribute("id");
+        if (explicitKey) {
+            seenKeys.set(explicitKey, (seenKeys.get(explicitKey) ?? 0) + 1);
+        }
+        const start = parseNumberAttr(clip.getAttribute("data-start"));
+        if (start === null || start < 0) {
+            push("error", "invalid_clip_timing", `Clip has a non-numeric or negative data-start ("${clip.getAttribute("data-start")}").`, key);
+            continue;
+        }
+        const duration = parseNumberAttr(clip.getAttribute("data-duration"));
+        if (duration === null) {
+            if (isMedia) {
+                push("warning", "media_missing_duration", "Media clip has no data-duration; it will fall back to the source's intrinsic length. Declare it for predictable trims.", key);
+            }
+            else {
+                push("error", "missing_clip_duration", "Non-media clip requires a positive data-duration.", key);
+            }
+        }
+        else if (duration <= 0) {
+            push("error", "invalid_clip_duration", `Clip data-duration must be positive (got ${duration}).`, key);
+        }
+        const trackRaw = clip.getAttribute("data-track-index");
+        const track = parseNumberAttr(trackRaw);
+        if (trackRaw === null || track === null || !Number.isInteger(track) || track < 0) {
+            push("warning", "missing_track_index", `Clip should declare an integer data-track-index >= 0 (got "${trackRaw ?? "<absent>"}").`, key);
+        }
+        // Nested clips fight parent visibility toggling and are unregistered in
+        // the upstream HyperFrames runtime (clips must be direct children).
+        let ancestor = clip.parentElement;
+        while (ancestor && ancestor !== root) {
+            if (ancestor.hasAttribute("data-start")) {
+                push("warning", "nested_clip", "Clip is nested inside another timed clip; move clips to the composition root.", key);
+                break;
+            }
+            ancestor = ancestor.parentElement;
+        }
+        if (isMedia && clip.parentElement && clip.parentElement !== root) {
+            push("warning", "nested_media", "video/audio elements should be direct children of the composition root — nested media renders blank/black under the HyperFrames runtime.", key);
+        }
+        if ((tag === "video" || tag === "img" || tag === "audio") && !isProxy) {
+            const src = clip.getAttribute("src") || clip.getAttribute("data-src");
+            const hasSourceChild = Boolean(clip.querySelector("source[src]"));
+            if (!src && !hasSourceChild) {
+                push("error", "media_missing_src", `<${tag}> clip has no src / data-src.`, key);
+            }
+        }
+        const kenBurns = clip.getAttribute("data-kenburns") ?? clip.querySelector("img[data-kenburns]")?.getAttribute("data-kenburns");
+        if (kenBurns && kenBurns !== "none" && !KEN_BURNS_PRESETS.includes(kenBurns)) {
+            push("error", "unknown_ken_burns", `Unknown data-kenburns preset "${kenBurns}".`, key);
+        }
+        const transition = clip.getAttribute("data-transition");
+        if (transition && transition !== "none" && !TRANSITION_PRESETS.includes(transition)) {
+            push("error", "unknown_transition", `Unknown data-transition preset "${transition}".`, key);
+        }
+        const transitionOut = clip.getAttribute("data-transition-out");
+        if (transitionOut && transitionOut !== "none" && !TRANSITION_OUT_PRESETS.includes(transitionOut)) {
+            push("error", "unknown_transition_out", `Unknown data-transition-out preset "${transitionOut}".`, key);
+        }
+        const captionAnimation = clip.getAttribute("data-caption-animation");
+        if (captionAnimation && captionAnimation !== "none" && !CAPTION_ANIMATIONS.includes(captionAnimation)) {
+            push("error", "unknown_caption_animation", `Unknown data-caption-animation preset "${captionAnimation}".`, key);
+        }
+        const effectiveDuration = duration !== null && duration > 0 ? duration : 0;
+        timings.push({
+            element: clip,
+            key,
+            start,
+            end: start + effectiveDuration,
+            track: track !== null && Number.isInteger(track) && track >= 0 ? track : null,
+            hasTransitionHold: clip.hasAttribute("data-transition-hold")
+        });
+    }
+    for (const [key, count] of seenKeys) {
+        if (count > 1) {
+            push("warning", "duplicate_layer_id", `Layer id "${key}" appears ${count} times; layer keys must be unique for editor/chat targeting.`);
+        }
+    }
+    // Same-track temporal overlap. Materialized transition holds
+    // (data-transition-hold) legitimately overlap their successor.
+    const byTrack = new Map();
+    for (const timing of timings) {
+        if (timing.track === null || timing.end <= timing.start) {
+            continue;
+        }
+        const bucket = byTrack.get(timing.track) ?? [];
+        bucket.push(timing);
+        byTrack.set(timing.track, bucket);
+    }
+    for (const [track, bucket] of byTrack) {
+        bucket.sort((a, b) => a.start - b.start || a.end - b.end);
+        for (let i = 1; i < bucket.length; i += 1) {
+            const prev = bucket[i - 1];
+            const current = bucket[i];
+            if (current.start < prev.end - OVERLAP_EPSILON && !prev.hasTransitionHold && !current.hasTransitionHold) {
+                push("error", "track_overlap", `Clips "${prev.key}" and "${current.key}" overlap on track ${track} (${prev.start}-${prev.end}s vs ${current.start}s start). Same-track clips must not overlap.`, current.key);
+            }
+        }
+    }
+    const scripts = document.querySelectorAll("script");
+    if (scripts.length > 0) {
+        push("warning", "scripts_stripped_on_save", `Composition contains ${scripts.length} <script> tag(s). Scripts survive local serve/disk renders, but every cloud/web editor save strips them (stored-XSS defense) — script-driven animation will be lost there. Prefer the declarative preset vocabulary (data-kenburns, data-transition, data-caption-animation) for compositions that round-trip through the web editor.`);
+    }
+    return finalize(issues);
+}
+function finalize(issues) {
+    const errors = issues.filter((issue) => issue.level === "error");
+    const warnings = issues.filter((issue) => issue.level === "warning");
+    return { ok: errors.length === 0, errors, warnings };
+}
+export function formatCompositionLintIssues(result) {
+    const lines = [];
+    for (const issue of result.errors) {
+        lines.push(`error  ${issue.code}${issue.layer ? ` [${issue.layer}]` : ""}: ${issue.message}`);
+    }
+    for (const issue of result.warnings) {
+        lines.push(`warn   ${issue.code}${issue.layer ? ` [${issue.layer}]` : ""}: ${issue.message}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=composition-lint.js.map

package/dist/src/services/hyperframes.js

@@ -65,6 +65,13 @@ function shouldRenderLocally() {
         (config.HYPERFRAMES_RENDER_BUCKET_NAME || config.HYPERFRAMES_LAMBDA_BUCKET_NAME));
     return !hasCloudStack;
 }
+// The bundled producer/aws-lambda libraries embed upstream-vendor doc links in
+// some error messages (font resolution, large-variables). Those URLs surface in
+// job logs and the export modal, so rewrite them to vidfarm's docs before the
+// message leaves the render layer.
+function scrubVendorDocLinks(text) {
+    return text.replace(/https?:\/\/[a-z0-9.-]*heygen\.com[^\s"')\]]*/gi, "https://vidfarm.cc/skill/vidfarm-director");
+}
 export class HyperframesService {
     async render(input) {
         const compositionHtml = normalizePublishHtml(input.compositionHtml || (input.composition ? buildHyperframeCompositionHtml(input.composition) : ""));
@@ -205,7 +212,7 @@ export class HyperframesService {
                     duration_ms: Date.now() - startedAtMs,
                     errors: Array.isArray(progress.errors) ? progress.errors.slice(0, 3) : progress.errors
                 }, "error");
-                throw new Error(`HyperFrames render ${handle.renderId} failed: ${JSON.stringify(progress.errors)}`);
+                throw new Error(`HyperFrames render ${handle.renderId} failed: ${scrubVendorDocLinks(JSON.stringify(progress.errors))}`);
             }
             if (Date.now() - startedAtMs > timeoutMs) {
                 devLog("hyperframes.render.timeout", {
@@ -263,16 +270,21 @@ export class HyperframesService {
             format: input.format || "mp4"
         });
         let lastStatus = null;
-        await executeRenderJob(job, projectDir, outputLocation, (progressJob, message) => {
-            if (progressJob.status !== lastStatus) {
-                devLog("hyperframes.render_local.progress", {
-                    render_id: renderId,
-                    status: progressJob.status,
-                    message
-                });
-                lastStatus = progressJob.status;
-            }
-        });
+        try {
+            await executeRenderJob(job, projectDir, outputLocation, (progressJob, message) => {
+                if (progressJob.status !== lastStatus) {
+                    devLog("hyperframes.render_local.progress", {
+                        render_id: renderId,
+                        status: progressJob.status,
+                        message
+                    });
+                    lastStatus = progressJob.status;
+                }
+            });
+        }
+        catch (error) {
+            throw new Error(scrubVendorDocLinks(error instanceof Error ? error.message : String(error)), { cause: error });
+        }
         // Single-segment encoded key — matches the `/storage/:key` route which
         // decodeURIComponent's one param (slashes ride through as %2F).
         const outputUrl = `${config.PUBLIC_BASE_URL}/storage/${encodeURIComponent(outputKey)}`;
@@ -338,7 +350,12 @@ export class HyperframesService {
         // png-sequence writes outputPath as a DIRECTORY of frame_000001.png … files.
         const job = createRenderJob({ fps: 30, quality: "high", format: "png-sequence" });
         try {
-            await executeRenderJob(job, projectDir, framesDir);
+            try {
+                await executeRenderJob(job, projectDir, framesDir);
+            }
+            catch (error) {
+                throw new Error(scrubVendorDocLinks(error instanceof Error ? error.message : String(error)), { cause: error });
+            }
             const frameFiles = (await readdir(framesDir))
                 .filter((name) => name.toLowerCase().endsWith(".png"))
                 .sort();
@@ -2510,6 +2527,31 @@ export function normalizePublishHtml(html) {
             continue;
         html.style.zIndex = String(trackIndex);
     }
+    // HyperFrames contract: visible timed elements (div/img) carry class="clip" —
+    // the upstream runtime keeps clip-less timed elements visible for the whole
+    // composition. video/audio deliberately stay bare (framework-managed), so the
+    // class is STRIPPED there (the editor's add-layer paths set it universally).
+    // Only promote layers with a valid timing window: a clip-less element with a
+    // missing/invalid data-duration historically stayed visible full-length, and
+    // promoting it would silently hide it on re-renders of older compositions.
+    for (const el of Array.from(document.querySelectorAll("[data-start]"))) {
+        if (el.hasAttribute("data-composition-id"))
+            continue;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "video" || tag === "audio") {
+            el.classList.remove("clip");
+            if (!el.getAttribute("class"))
+                el.removeAttribute("class");
+            continue;
+        }
+        const start = Number.parseFloat(el.getAttribute("data-start") || "");
+        const clipDuration = Number.parseFloat(el.getAttribute("data-duration") || "");
+        if (!Number.isFinite(start) || start < 0 || !Number.isFinite(clipDuration) || clipDuration <= 0)
+            continue;
+        if (!el.classList.contains("clip")) {
+            el.classList.add("clip");
+        }
+    }
     // Ken Burns motion must span exactly the clip: timeline edits touch
     // data-duration only, so re-derive the inline --vf-kb-dur (which drives
     // animation-duration) from data-duration on every [data-kenburns] layer.
@@ -2643,7 +2685,7 @@ function extractCompositionMetadata(html, input) {
     const compositionId = safeIdentifier(input.compositionId || htmlAttribute(html, "data-composition-id") || input.composition?.compositionId || "composition");
     const width = positiveInteger(input.width || htmlAttribute(html, "data-width") || input.composition?.width, 720);
     const height = positiveInteger(input.height || htmlAttribute(html, "data-height") || input.composition?.height, 1280);
-    const fps = positiveInteger(input.fps || 30, 30);
+    const fps = positiveInteger(input.fps || rootTagAttribute(html, "data-fps") || 30, 30);
     const duration = Number.parseFloat(htmlAttribute(html, "data-duration") || String(input.composition?.duration || ""));
     return {
         compositionId,
@@ -2673,6 +2715,18 @@ function forceEvenCompositionDimensions(html) {
         return `data-${dim}=${quote}${n - 1}${quote}`;
     });
 }
+// Reads an attribute from the SAME opening tag that carries
+// data-composition-id (the composition root). htmlAttribute matches the first
+// occurrence anywhere in the document, which nested sub-compositions or
+// embedded snippets could hijack — fps must come from the root only.
+function rootTagAttribute(html, name) {
+    const rootTag = html.match(/<[a-zA-Z][^>]*\bdata-composition-id\s*=[^>]*>/);
+    if (!rootTag) {
+        return "";
+    }
+    const value = rootTag[0].match(new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`, "i"));
+    return value ? value[1] : "";
+}
 function htmlAttribute(html, name) {
     const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const match = html.match(new RegExp(`${escaped}=(["'])(.*?)\\1`, "i"));

package/dist/src/services/serverless-records.js

@@ -591,6 +591,15 @@ class ServerlessRecordsServiceImpl {
         // so the coarse keyword filter never fights the TTL cache.
         return filterAndRankBySearch(this.templatesFeedCache.records, input.query).slice(0, limit);
     }
+    // Curated "Popular" picks: the handful of public templates flagged with a
+    // popularGroup. Drawn from the same cached feed as listTemplatesFeed (the set
+    // is tiny), ordered by popularRank so the editorial sequence is preserved.
+    async listPopularTemplates() {
+        const feed = await this.listTemplatesFeed({ limit: ServerlessRecordsServiceImpl.TEMPLATES_FEED_MAX });
+        return feed
+            .filter((record) => typeof record.popularGroup === "string" && record.popularGroup.trim().length > 0)
+            .sort((a, b) => (a.popularRank ?? 0) - (b.popularRank ?? 0));
+    }
     async queryTemplatesFeed() {
         const response = await dynamodb.send(new QueryCommand({
             TableName: requireMainTableName(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "demo/dist/**",
     "public/assets/**",
     "src/assets/**",
+    ".agents/skills/**",
     "README.md",
     "SKILL.director.md",
     "SKILL.platform.md",