@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/dist/src/devcli/stills.js

@@ -0,0 +1,249 @@
+// `vidfarm stills` — render PNG still frames of the CURRENT composition
+// in-process, without a full MP4 render. This is the coding agent's visual
+// self-verification loop: edit composition.html, render 3-8 stills, look at
+// them, iterate.
+//
+// Implementation mirrors HyperframesService.renderStill (src/services/
+// hyperframes.ts): stage the composition as a HyperFrames project dir, drive
+// @hyperframes/producer's createRenderJob/executeRenderJob with the
+// "png-sequence" format, then pick the captured frames nearest each requested
+// timestamp. Deliberately NOT importing HyperframesService — that class drags
+// in config.ts (which mkdirs at import) and the whole cloud-render surface;
+// this is a lean local-file implementation.
+//
+// Cost control: png-sequence captures EVERY frame on the fps grid, so we
+// (a) cap the staged composition's duration at the last requested timestamp
+// and (b) render on a coarse integer fps grid (4fps → 0.25s accuracy, dropped
+// to 2/1fps for long timelines) instead of the composition's native 30fps.
+// Requested timestamps are snapped to that grid; the actually-captured time
+// is reported next to each written PNG.
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseHTML } from "linkedom";
+import { inspectComposition } from "./composition-edit.js";
+const MAX_DEFAULT_STILLS = 8;
+const MAX_GRID_FRAMES = 600;
+// The in-process producer shells out to ffmpeg/ffprobe resolved from
+// HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH (then PATH). Point it at
+// the bundled static binaries, same as src/services/hyperframes.ts does.
+async function ensureProducerFfmpegEnv() {
+    if (!process.env.HYPERFRAMES_FFMPEG_PATH?.trim()) {
+        try {
+            const mod = (await import("ffmpeg-static"));
+            const resolved = typeof mod === "string" ? mod : mod.default;
+            if (typeof resolved === "string" && resolved && existsSync(resolved)) {
+                process.env.HYPERFRAMES_FFMPEG_PATH = resolved;
+            }
+        }
+        catch { /* PATH fallback */ }
+    }
+    if (!process.env.HYPERFRAMES_FFPROBE_PATH?.trim()) {
+        try {
+            const mod = (await import("ffprobe-static"));
+            const resolved = (mod.path ?? mod.default?.path);
+            if (typeof resolved === "string" && resolved && existsSync(resolved)) {
+                process.env.HYPERFRAMES_FFPROBE_PATH = resolved;
+            }
+        }
+        catch { /* PATH fallback */ }
+    }
+}
+/**
+ * Default timestamps when --at is omitted: the midpoint of each distinct
+ * scene clip on the LOWEST video track (capped at 8), else 0 / mid / end of
+ * the composition.
+ */
+export function defaultStillTimestamps(layers, durationSeconds) {
+    const isSceneClip = (layer) => layer.duration > 0 && (layer.is_timeline_proxy ||
+        layer.kind === "video" ||
+        layer.kind === "scene" ||
+        (layer.src !== null && /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(layer.src)) ||
+        // Canvas-filling clips of any kind read as scenes (image scenes,
+        // solid/title cards) — overlays/captions are never full-canvas.
+        layer.is_full_canvas);
+    const scenes = layers.filter(isSceneClip);
+    if (scenes.length > 0) {
+        const lowestTrack = Math.min(...scenes.map((layer) => layer.track));
+        const seen = new Set();
+        const midpoints = [];
+        for (const layer of scenes.filter((l) => l.track === lowestTrack).sort((a, b) => a.start - b.start)) {
+            const key = layer.key || `${layer.start}-${layer.duration}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            midpoints.push(layer.start + layer.duration / 2);
+            if (midpoints.length >= MAX_DEFAULT_STILLS)
+                break;
+        }
+        if (midpoints.length > 0)
+            return midpoints;
+    }
+    if (durationSeconds <= 0)
+        return [0];
+    return [...new Set([0, durationSeconds / 2, Math.max(0, durationSeconds - 0.5)])];
+}
+// Pick the coarsest integer fps grid that keeps capture cheap while staying
+// within 0.25s of any requested timestamp where possible.
+function pickGridFps(maxTimestamp) {
+    for (const fps of [4, 2, 1]) {
+        if ((maxTimestamp + 1) * fps <= MAX_GRID_FRAMES)
+            return fps;
+    }
+    return 1;
+}
+// Cap the staged copy's root data-duration so the producer never captures
+// frames past the last requested still.
+function capCompositionDuration(html, capSeconds) {
+    const { document } = parseHTML(html);
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        throw new Error("Composition root ([data-composition-id]) not found in composition.html.");
+    const existing = Number.parseFloat(root.getAttribute("data-duration") ?? "");
+    const capped = Number.isFinite(existing) && existing > 0 ? Math.min(existing, capSeconds) : capSeconds;
+    root.setAttribute("data-duration", String(Number(capped.toFixed(3))));
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+// Same guard as renderLocal: libx264-adjacent tooling (and the runtime's
+// canvas sizing) prefers even data-width/data-height.
+function forceEvenDimensions(html) {
+    return html.replace(/\bdata-(width|height)=(["'])(\d+)\2/gi, (match, dim, quote, value) => {
+        const n = Number.parseInt(value, 10);
+        if (!Number.isFinite(n) || n % 2 === 0)
+            return match;
+        return `data-${dim}=${quote}${n - 1}${quote}`;
+    });
+}
+/**
+ * Stage the composition as a HyperFrames project dir: the (duration-capped)
+ * composition.html becomes index.html, and every sibling file/dir is copied in
+ * so relative asset references keep resolving. Mirrors stageProject in
+ * src/services/hyperframes.ts, but against a local composition dir.
+ */
+function stageCompositionProject(htmlPath, stagedHtml) {
+    const sourceDir = path.dirname(htmlPath);
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-stills-"));
+    writeFileSync(path.join(projectDir, "index.html"), stagedHtml, "utf8");
+    for (const entry of readdirSync(sourceDir)) {
+        if (entry === path.basename(htmlPath) || entry === "index.html" || entry === "stills")
+            continue;
+        const from = path.join(sourceDir, entry);
+        try {
+            const info = statSync(from);
+            if (info.isDirectory()) {
+                cpSync(from, path.join(projectDir, entry), { recursive: true, force: true });
+            }
+            else if (info.isFile()) {
+                copyFileSync(from, path.join(projectDir, entry));
+            }
+        }
+        catch {
+            // best-effort: a missing/unreadable sibling never blocks the stills
+        }
+    }
+    return projectDir;
+}
+export async function renderCompositionStills(input) {
+    const html = readFileSync(input.htmlPath, "utf8");
+    if (!html.includes("data-composition-id=")) {
+        throw new Error(`stills requires composition HTML with data-composition-id (${input.htmlPath}).`);
+    }
+    const info = inspectComposition(html);
+    const durationSeconds = info.duration_seconds > 0 ? info.duration_seconds : 1;
+    const requested = (input.at && input.at.length > 0
+        ? input.at
+        : defaultStillTimestamps(info.layers, durationSeconds))
+        .map((t) => Math.min(Math.max(0, t), Math.max(0, durationSeconds - 0.01)))
+        .sort((a, b) => a - b);
+    if (requested.length === 0)
+        throw new Error("stills: no timestamps to render.");
+    const gridFps = pickGridFps(requested[requested.length - 1]);
+    const capSeconds = Math.min(durationSeconds, requested[requested.length - 1] + 2 / gridFps);
+    await ensureProducerFfmpegEnv();
+    const stagedHtml = forceEvenDimensions(capCompositionDuration(html, capSeconds));
+    const projectDir = stageCompositionProject(input.htmlPath, stagedHtml);
+    const framesDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-stills-frames-"));
+    const outDir = path.resolve(input.outDir ?? path.join(path.dirname(input.htmlPath), "stills"));
+    mkdirSync(outDir, { recursive: true });
+    // Declarative vidfarm compositions carry no scripts (cloud saves strip
+    // them), so they can never satisfy the engine's window.__timelines
+    // sub-composition poll — which otherwise stalls capture-session init for the
+    // full 45s playerReadyTimeout before proceeding anyway. When the html has no
+    // timeline registration at all, cap that wait via the engine's env knob.
+    // Compositions that DO register GSAP timelines keep the default.
+    const priorReadyTimeout = process.env.PRODUCER_PLAYER_READY_TIMEOUT_MS;
+    if (!priorReadyTimeout?.trim() && !stagedHtml.includes("__timelines")) {
+        process.env.PRODUCER_PLAYER_READY_TIMEOUT_MS = "10000";
+    }
+    try {
+        // Same producer entry points renderStill uses; "png-sequence" writes the
+        // frames dir as frame_000001.png … at 1/gridFps intervals.
+        const { createRenderJob, executeRenderJob } = await import("@hyperframes/producer");
+        // Quiet mode (--json) swaps in a no-op logger so stdout stays parseable —
+        // the producer's default logger writes progress lines to stdout.
+        const silentLogger = { error() { }, warn() { }, info() { }, debug() { } };
+        const job = createRenderJob({
+            fps: gridFps,
+            quality: "high",
+            format: "png-sequence",
+            ...(input.quiet ? { logger: silentLogger } : {})
+        });
+        let lastStatus = null;
+        const executeRender = () => executeRenderJob(job, projectDir, framesDir, (progressJob) => {
+            if (!input.quiet && progressJob.status !== lastStatus) {
+                lastStatus = progressJob.status;
+                console.log(`\x1b[2m  ${progressJob.status}\x1b[0m`);
+            }
+        });
+        // The engine also logs init/browser lines via console.log directly (they
+        // bypass the producer logger); in quiet mode reroute console stdout to
+        // stderr for the duration of the render so stdout stays pure JSON.
+        const originalConsole = { log: console.log, info: console.info, debug: console.debug };
+        if (input.quiet) {
+            const toStderr = (...args) => {
+                process.stderr.write(`${args.map((value) => (typeof value === "string" ? value : JSON.stringify(value))).join(" ")}\n`);
+            };
+            console.log = toStderr;
+            console.info = toStderr;
+            console.debug = toStderr;
+        }
+        try {
+            await executeRender();
+        }
+        finally {
+            console.log = originalConsole.log;
+            console.info = originalConsole.info;
+            console.debug = originalConsole.debug;
+        }
+        const frameFiles = readdirSync(framesDir)
+            .filter((name) => name.toLowerCase().endsWith(".png"))
+            .sort();
+        if (frameFiles.length === 0) {
+            throw new Error("stills render produced no frames — check the composition with `vidfarm lint` first.");
+        }
+        const stills = [];
+        for (const t of requested) {
+            const frameIndex = Math.min(frameFiles.length - 1, Math.max(0, Math.round(t * gridFps)));
+            const capturedSec = Number((frameIndex / gridFps).toFixed(3));
+            const stillName = `still-${capturedSec.toFixed(2).padStart(6, "0")}s.png`;
+            const dest = path.join(outDir, stillName);
+            copyFileSync(path.join(framesDir, frameFiles[frameIndex]), dest);
+            stills.push({ requested_sec: Number(t.toFixed(3)), captured_sec: capturedSec, path: dest });
+        }
+        return {
+            ok: true,
+            composition: input.htmlPath,
+            out_dir: outDir,
+            grid_fps: gridFps,
+            duration_seconds: durationSeconds,
+            stills
+        };
+    }
+    finally {
+        if (!priorReadyTimeout?.trim())
+            delete process.env.PRODUCER_PLAYER_READY_TIMEOUT_MS;
+        rmSync(framesDir, { recursive: true, force: true });
+        rmSync(projectDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=stills.js.map

package/dist/src/editor-chat.js

@@ -1,3 +1,6 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { lintCompositionHtml } from "./services/composition-lint.js";
 export const EDITOR_CHAT_PROVIDER_PRIORITY = [
     "openai",
     "gemini",
@@ -69,6 +72,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "The editor_context block includes last_export_url, last_export_title, last_export_status, and last_export_render_id when a render has succeeded in this session. Treat last_export_url as the current 'finished Export MP4' for this composition. If the user asks to approve, package, share, or schedule the exported video without providing an explicit URL, use last_export_url as the primary MP4 media (kind=video, role=primary) for POST /api/v1/approved/posts. If last_export_url is null, tell the user to Export first (or offer to call editor_action with action_type=export_composition on their behalf) instead of guessing a URL.",
         "Each layer in editor_context includes element_id (data-hf-id), optional slug (data-hf-slug), and optional note (data-hf-note). layer_key on any editor_action may be EITHER the element_id or the slug — prefer the slug when the user (or a viral DNA blurb) refers to a layer by its human name like 'the hero_image'. Use set_layer_identity to add/change a layer's slug or note. Slugs are the stable AI-friendly handle: when planning viral DNA notes, reference the element by its slug (e.g., 'raise the {{hero_image}} to full canvas at 4s') so future turns can resolve it deterministically.",
         "Treat the most recent <editor_context> block in the user message as the source of truth for current layer_keys, layer indices (called track in HTML: track=layer index, higher = drawn on top), durations, and composition_duration_seconds. Never invent layer_keys for remove/set/duplicate/split actions; only reference keys that appear there.",
+        "CRITICAL — verify your edits actually landed. An editor_action tool result only echoes the arguments you sent; it is NOT proof the change was applied or saved. The real outcome shows up in the NEXT <editor_context>. Before telling the user an edit succeeded, check that block: (1) if it contains save_status:\"error\" (or is_read_only:true / a save_error message), the composition is NOT being saved — do NOT claim any edit worked; tell the user exactly what save_error says (e.g. the video is read-only from this link and they should open their own copy to edit) and stop making mutating editor_action calls until it clears; (2) if it contains recent_action_results, each entry with ok:false is an edit from your previous turn that FAILED (read its error) — acknowledge the failure and retry or explain it rather than repeating a false success; (3) otherwise confirm the intended change is reflected in the layers (e.g. the new text on the target layer) before saying it's done. Never report a timeline edit as successful without this check.",
         "editor_context also carries the canvas shape and free time: composition_width, composition_height, and aspect_ratio (e.g. '9:16') describe the output frame — when generating media to place on this timeline, request the matching aspect_ratio on /videos/generate and /images/generate so it fills the canvas without letterboxing or wrong cropping. timeline_gaps is a precomputed array of {start, end, duration} spans (seconds) where NO visual layer is on screen — i.e. the literal blank/black moments. When the user says something like 'at 00:05:52 there's blank space, add X', map their timestamp (interpret mm:ss or seconds sensibly) to the covering entry in timeline_gaps, set the new layer's start to that gap's start (or the user's exact time if inside the gap) and clamp its duration to fit the gap unless the user asks otherwise. If the requested time is NOT inside any timeline_gaps entry, tell the user it already has content there and offer to overlay on a higher track or replace the existing layer instead of silently colliding.",
         "For add_layer, always supply a stable layer_key (e.g., vf-caption-hook, vf-hero-image, vf-narration-audio) so later tool calls in the same turn can reference the new layer without waiting for the next <editor_context>. The editor uses that layer_key as the new layer's id. Choose kind from video, image, audio, text, or html. Provide src (exact URL) for video/image/audio, text for text layers, and html for html layers. Pick a track index higher than every existing layer on the requested time range, or set start/duration so the range is collision-free. Default visual layers fill roughly the upper-middle of the canvas; text layers default to a lower-third band. Always include explanation.",
         "GENERATE-AND-PLACE (preferred for NEW AI footage/images on the timeline): when the user wants to generate a NEW AI video or image and drop it on the timeline — fill a blank gap, replace a scene, or add an overlay — call editor_action with action_type=generate_layer. This ONE action submits the primitive generate job, immediately drops a 'Generating…' placeholder clip into the target slot, and auto-swaps in the finished media when the job settles — you do NOT poll and you do NOT make a separate add_layer call. Set media_type ('video' or 'image'), prompt, and aspect_ratio to the editor_context aspect_ratio so it fills the canvas. Set intent: 'fill_gap' (also set start=the timeline_gaps span start and duration to fit the gap), 'replace_layer' (also set replace_layer_key to the scene's layer_key/slug — its timing and geometry, including full-canvas, are copied automatically), or 'add' (set start/track/geometry for an overlay). For video pass gen_duration (seconds of footage, e.g. 4) and, for character consistency, input_references=[cast reference_url or still_url]; for image pass prompt_attachments=[reference image URL]. Optionally set provider/model/resolution/generate_audio. Give explanation. Because generation is asynchronous, the placeholder appears now and the real media lands in a later turn — do NOT claim the media is finished; tell the user it is generating and will appear on the timeline shortly.",
@@ -89,6 +93,8 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "When you simply want to change a layer's media without moving it, prefer set_layer_media (kind must match: video↔video, image↔image, audio↔audio) — it keeps the same node, id, track, and geometry.",
         "CONTEXT AVAILABLE FOR USE — this composition can expose TWO video sources plus a text/scene context: (1) the ORIGINAL video — the raw uploaded source, with any baked-in subtitles/captions; (2) the DECOMPOSED video — a processed, caption-free copy Vidfarm produces asynchronously (subtitles removed) that the composition timeline renders from; and (3) the decomposed video context (transcript + per-scene visual descriptions + viral DNA) available via the video_context tool. The original and the decomposed video are NOT the same URL, and you should not carry both URLs in default context. When the user asks to reuse, re-render, or feed the composition's video into a primitive route (image extract, ai video edit, media/dedupe, video trim, video probe, etc.), call GET /api/v1/compositions/:forkId/remove-video-captions FIRST to read { status, original_source_url, mirrored_url } and pick correctly — here original_source_url is the ORIGINAL video and mirrored_url is the DECOMPOSED video: prefer the DECOMPOSED video (mirrored_url) when status=\"done\" and the downstream call should be caption-free (thumbnails, style references, re-cut hooks); prefer the ORIGINAL video (original_source_url) when the user explicitly wants the raw upload (branded intros, provenance, when captions are the subject matter). If status is \"pending\" and the user is not blocked on subtitle removal, use the ORIGINAL video and mention that the decomposed (caption-free) video is still processing. If status is \"none\" or \"failed\", there is no decomposed video yet — use the ORIGINAL video only. Do not call POST /remove-video-captions-poll unless the user explicitly asks to advance the subtitle-removal job. To strip burned-in captions from any OTHER video URL (not this fork's decompose flow), use the POST /api/v1/primitives/videos/remove-captions primitive instead.",
         "The OPTIONAL video_context tool returns this fork's decomposed video context: the source video's verbatim audio transcript (full text plus timestamped segments), a literal visual description of every scene, per-scene transcript excerpts, and viral DNA. Call it with the fork id from editor_context whenever the user asks what the source video says or shows, when writing/translating captions, hooks, or dubs that must match the spoken audio, or when you need scene-by-scene grounding before planning timeline edits. It is read-only and non-billing, so prefer it over guessing from frames or memory. If it returns status=\"none\", the fork was never smart-decomposed — offer to run POST /api/v1/compositions/:forkId/auto-decompose first. The same data is available via GET /api/v1/compositions/:forkId/video-context.json through http_request (useful for other forks).",
+        "KNOWLEDGE ON DEMAND (load_skill): deeper authoring knowledge ships as vidfarm skill packs you can read mid-conversation with the load_skill tool — the composition HTML contract (hyperframes-core), motion/animation craft and transition doctrine (hyperframes-animation), seek-safe keyframe patterns (hyperframes-keyframes), creative direction/palettes/typography (hyperframes-creative), caption identities (embedded-captions), media/audio resolution (vidfarm-media), and end-to-end workflow playbooks (product-launch-video, faceless-explainer, website-to-video, general-video, motion-graphics, slideshow, talking-head-recut). Call load_skill with the pack name to read its SKILL.md; it lists reference files you can then load by relative path (e.g. file='references/step-4-vo.md'). Use it when a request needs craft beyond the built-in preset vocabulary — designing a whole composition via replace_composition_html, picking motion or transition language for a style, or following a named workflow. Load only what the task needs, never bulk-load packs, and never paste large skill content back to the user.",
+        "replace_composition_html is validated before it reaches the editor: when the HTML violates the composition contract (missing data-composition-id, invalid clip timing, same-track overlaps, unknown preset names, media without src) the tool result comes back with rejected=true and lint_errors, and NOTHING is applied — fix the reported issues and call it again. lint_warnings are advisory and the action still applies (e.g. <script> tags survive local renders but are stripped on cloud/web saves — keep web-editor compositions declarative).",
         "TEMPLATE FORMAT — MATCH IT WHEN WRITING TEXT: the COMPOSITION BRIEF (stable template context in the system prompt) carries composition_context — WHAT THIS TEMPLATE IS: its format/genre and narrative arc (trend_tagline, hook, retention, payoff, preserve, avoid). ALWAYS read it before writing or adjusting ANY captions, text layers, or on-screen copy, and make your copy fit the template's format and voice — do NOT default to generic product/app ad copy. The format dictates the caption style: a text-message / DM / iMessage conversation template's captions must read like short back-and-forth chat messages between people (in-character, conversational), a 'story time' / talking-head template reads like first-person spoken narration, a listicle reads like punchy numbered items, a fake-news / headline template reads like a news chyron, etc. `preserve` usually names format cues that must stay (e.g. the messaging-bubble layout); `avoid` names what to keep out. When the template's format is a conversation, skit, or roleplay, keep the captions in that voice and only weave the product in the way that format allows (subtly, in-dialogue) rather than replacing the messages with feature bullets. If the brief's composition_context is thin or you are unsure what the video actually shows, call video_context (scene visual descriptions + transcript) to ground the format BEFORE writing captions.",
         "MY FILES: the user has a personal file library ('My Files') of uploaded assets — videos (mp4/mov/webm), images (png/jpg/jpeg/gif/webp/svg), audio (mp3/wav/m4a/aac), and documents (pdf/md/txt/csv) — organized into virtual folders. Use the browse_files tool to explore AND write it: call action=list (optionally with folder_path) to see what files and folders exist, action=search with a plain-language query to find files by MEANING (keyword + vector match over every file's name, folder, and metadata notes — prefer it over paging list when the library is large or the user references an asset vaguely), action=read with a file_id (copied from a prior list/search) to fetch one file, action=write with file_name + content (or source_url) to SAVE a file, and action=annotate with file_id + notes to attach metadata notes to any existing file. When the user references their own footage, brand assets, logos, music, a brief, or a script ('use my product photo', 'the video I uploaded', 'my brand logo', 'the script in my files'), browse_files search or list first to find it rather than asking them to re-upload or paste a URL. For text files (md/txt/csv/srt/vtt/json), read returns the full text_content inline so you can read a brief or script directly. For images/video/audio/pdf, read returns only a durable view_url — use that URL as media: drop it into the timeline via editor_action add_layer/set_layer_media, or pass it into primitive routes (images/edit source_image_url, videos/generate input_references, videos/download). Never invent file ids or view URLs — always list or search to discover the real ones first.",
         "SAVING CONTEXT TO MY FILES: browse_files action=write persists durable, reusable context the user (and future chats/agents) can read back. write saves text files (md/txt/csv/json/srt/vtt) via content, and IMPORTS media into the library via source_url (a durable URL from a finished primitive job or existing asset) — use source_url to persist a generated asset the user will want again (a character sprite card, a recurring background, a logo variant) instead of leaving it stranded in a job result. Use write to capture the Getting Started artifacts as Markdown: a product About.md (basic offer/product context) or a deeper Interview.md, plus awareness-levels.md, persuasive-angles.md, and ad-hooks.md distilled from the matching brainstorm outputs. When a brainstorm job returns strategy the user wants to keep, offer to save it (or save it) as the corresponding .md so it is not lost when the chat ends. Namescope every write under the right product/offer folder (see MY FILES IS MULTI-OFFER) — e.g. folder_path='acme-skincare', file_name='About.md'. Pass notes on write (or annotate afterwards) for any asset worth finding again: notes describe what the file is, who/what it depicts, and when to use it, and they are vector-embedded so action=search finds the file by meaning in future sessions. Before overwriting an existing file of the same name in the same folder, confirm with the user (writing the same name replaces it).",
@@ -451,4 +457,254 @@ export function compactEditorChatModelMessages(messages) {
         ...recentMessages
     ];
 }
+// ——— Skill packs the load_skill chat tool can fetch on demand. Served from
+// GET /skill/:name (SKILL.md) and GET /skill-pack/:name/files/<path>
+// (reference files), vendored under .agents/skills. Keep this list in sync
+// with the packs actually vendored in the repo.
+export const EDITOR_CHAT_SKILL_PACKS = [
+    { name: "vidfarm-director", summary: "the full director playbook (REST + devcli flows)" },
+    { name: "hyperframes", summary: "workflow router for the HyperFrames skill suite" },
+    { name: "hyperframes-cli", summary: "HyperFrames CLI dev loop (init/lint/validate/inspect/snapshot/render)" },
+    { name: "hyperframes-core", summary: "composition HTML contract: data-* timing attrs, tracks, clips, determinism rules" },
+    { name: "hyperframes-animation", summary: "motion rules catalog, scene blueprints, transition doctrine, runtime adapters" },
+    { name: "hyperframes-keyframes", summary: "seek-safe keyframe/CSS animation patterns" },
+    { name: "hyperframes-creative", summary: "design specs, palettes, typography, house style, narration craft" },
+    { name: "vidfarm-media", summary: "narration TTS/STT, BGM/SFX/media resolution through vidfarm primitives" },
+    { name: "embedded-captions", summary: "caption identity catalog + subject-occlusion caption pipeline" },
+    { name: "talking-head-recut", summary: "timed graphic overlay cards on existing footage" },
+    { name: "product-launch-video", summary: "product/launch promo workflow (time-coded shot sequences)" },
+    { name: "faceless-explainer", summary: "text-to-faceless-explainer workflow" },
+    { name: "website-to-video", summary: "website capture to video workflow" },
+    { name: "general-video", summary: "general multi-scene composition workflow" },
+    { name: "motion-graphics", summary: "short motion-graphic workflow with category modules" },
+    { name: "slideshow", summary: "interactive slideshow/deck composition contract" }
+];
+export const EDITOR_CHAT_SKILL_FILE_MAX_CHARS = 24_000;
+// ——— Stream guardrails shared by the in-process chat (src/app.ts) and the
+// deployed Lambda copy (infra/lambda/editor-chat.ts). One implementation so
+// the two stream loops cannot drift.
+export const EDITOR_CHAT_JOB_ID_PATTERN = /\bjob_[a-z0-9]+\b/gi;
+const HTTP_TOOL_CLAIM_PATTERN = /\b(?:http_request|REST API call|API call|GET\s+https?:\/\/|POST\s+https?:\/\/|GET\s+\/api\/|POST\s+\/api\/)/i;
+export function collectJobIdsFromUnknown(value, output = new Set()) {
+    if (typeof value === "string") {
+        for (const match of value.matchAll(EDITOR_CHAT_JOB_ID_PATTERN)) {
+            output.add(match[0]);
+        }
+        return output;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            collectJobIdsFromUnknown(entry, output);
+        }
+        return output;
+    }
+    if (value && typeof value === "object") {
+        for (const entry of Object.values(value)) {
+            collectJobIdsFromUnknown(entry, output);
+        }
+    }
+    return output;
+}
+export function collectVerifiedHttpJobIds(toolResult) {
+    if (!toolResult || typeof toolResult !== "object") {
+        return new Set();
+    }
+    const record = toolResult;
+    return collectJobIdsFromUnknown(record.response?.body ?? record.result?.body);
+}
+export function readAsyncJobHandoff(output) {
+    if (!output || typeof output !== "object") {
+        return null;
+    }
+    const record = output;
+    const body = record.response?.body;
+    if (!body || typeof body !== "object") {
+        return null;
+    }
+    const job = body;
+    if (typeof job.job_id !== "string" || typeof job.status !== "string") {
+        return null;
+    }
+    if (job.status === "succeeded" || job.status === "failed" || job.status === "cancelled") {
+        return null;
+    }
+    return {
+        jobId: job.job_id,
+        tracer: typeof job.tracer === "string" ? job.tracer : null,
+        status: job.status,
+        isNewQueuedJob: record.request?.method === "POST" && record.response?.status === 202
+    };
+}
+export function buildAsyncJobHandoffText(input) {
+    // "Render …" wording is load-bearing: template-editor-chat.tsx emits the
+    // identical strings client-side and dedupes with a substring check, so any
+    // wording change here double-prints every queued-job handoff.
+    if (!input.isNewQueuedJob) {
+        return `Render \`${input.jobId}\` is ${input.status}.`;
+    }
+    return [
+        `Started render \`${input.jobId}\`${input.tracer ? ` with tracer \`${input.tracer}\`` : ""}.`,
+        "If it takes a while, ask for an update later and I can check it for you."
+    ].join("\n\n");
+}
+export function buildEditorChatGuardrailNotice(input) {
+    const mentionedJobIds = collectJobIdsFromUnknown(input.assistantText);
+    const unverifiedJobIds = [...mentionedJobIds].filter((jobId) => !input.verifiedJobIds.has(jobId));
+    const notices = [];
+    if (input.redactedJobIds.size) {
+        notices.push("Guardrail: I withheld unverified job ID text because it did not come from a visible HTTP response card.");
+    }
+    else if (unverifiedJobIds.length) {
+        notices.push("Guardrail: I mentioned an unverified job ID. Ignore it unless it appears in a visible HTTP response card.");
+    }
+    if (!input.hasHttpRequestResult && HTTP_TOOL_CLAIM_PATTERN.test(input.assistantText)) {
+        notices.push("Guardrail: no `http_request` tool result was recorded for this response, so any claimed REST/API call should be treated as not executed.");
+    }
+    return notices.length ? `\n\n${notices.join("\n\n")}` : "";
+}
+export function redactUnverifiedJobIds(input) {
+    return input.text.replace(EDITOR_CHAT_JOB_ID_PATTERN, (jobId) => {
+        if (input.verifiedJobIds.has(jobId)) {
+            return jobId;
+        }
+        input.redactedJobIds.add(jobId);
+        return "[unverified job id]";
+    });
+}
+const SKILL_PACK_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+const SKILL_PACK_TEXT_FILE_RE = /\.(md|txt|json|ya?ml|mjs|cjs|js|html|css|srt|vtt|sh)$/i;
+// Shared implementation behind the load_skill chat tool (registered in both
+// src/app.ts and infra/lambda/editor-chat.ts). Fetches vendored skill-pack
+// content from the vidfarm host's public /skill + /skill-pack routes.
+export async function loadEditorChatSkillContent(input) {
+    const skill = input.skill.trim().toLowerCase().replace(/^\//, "");
+    if (!SKILL_PACK_NAME_RE.test(skill)) {
+        return { skill: input.skill, error: "Invalid skill pack name." };
+    }
+    const knownPack = EDITOR_CHAT_SKILL_PACKS.some((pack) => pack.name === skill);
+    const file = (input.file ?? "").trim().replace(/^\.?\//, "");
+    if (file && (file.includes("..") || !SKILL_PACK_TEXT_FILE_RE.test(file))) {
+        return { skill, file, error: "file must be a text file path inside the pack (no '..'; markdown/scripts/data files only)." };
+    }
+    const base = input.publicBaseUrl.replace(/\/$/, "");
+    const url = file
+        ? `${base}/skill-pack/${encodeURIComponent(skill)}/files/${file.split("/").map(encodeURIComponent).join("/")}`
+        : `${base}/skill/${encodeURIComponent(skill)}`;
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => {
+        timeoutController.abort(new Error("Skill fetch timed out after 30 seconds."));
+    }, 30_000);
+    try {
+        const signal = input.abortSignal
+            ? AbortSignal.any([input.abortSignal, timeoutController.signal])
+            : timeoutController.signal;
+        const response = await fetch(url, { method: "GET", signal });
+        if (!response.ok) {
+            return {
+                explanation: input.explanation ?? null,
+                skill,
+                file: file || null,
+                status: response.status,
+                error: `Skill content unavailable (${response.status}).${knownPack ? "" : " Unknown pack — the tool description lists the available packs."}`
+            };
+        }
+        const raw = await response.text();
+        const truncated = raw.length > EDITOR_CHAT_SKILL_FILE_MAX_CHARS;
+        return {
+            explanation: input.explanation ?? null,
+            skill,
+            file: file || "SKILL.md",
+            truncated,
+            content: truncated
+                ? `${raw.slice(0, EDITOR_CHAT_SKILL_FILE_MAX_CHARS)}\n\n[truncated — load a specific reference file for the rest]`
+                : raw
+        };
+    }
+    catch (error) {
+        return {
+            explanation: input.explanation ?? null,
+            skill,
+            file: file || null,
+            error: error instanceof Error ? error.message : "Skill fetch failed."
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+// ——— load_skill tool factory + replace_composition_html lint gate, shared by
+// both chat copies (src/app.ts and infra/lambda/editor-chat.ts) so the tool
+// description, schema, and gating semantics cannot drift between deployments.
+export function createLoadSkillTool(input) {
+    return tool({
+        description: `OPTIONAL knowledge fetch: load a vidfarm skill pack document on demand instead of guessing at authoring craft. Available packs: ${EDITOR_CHAT_SKILL_PACKS.map((pack) => `${pack.name} — ${pack.summary}`).join("; ")}. Call with just skill=<name> to read the pack's SKILL.md (it lists the pack's reference files), then load a specific reference with file=<relative path> (e.g. 'references/step-4-vo.md', 'rules-index.md'). Text files only; long files are truncated. Read-only and non-billing. Load only what the current task needs.`,
+        inputSchema: z.object({
+            skill: z.string().min(1).describe("Skill pack name, e.g. 'hyperframes-animation'."),
+            file: z.string().optional().describe("Optional text file path inside the pack. Omit to fetch SKILL.md."),
+            explanation: z.string().optional().describe("Short reason for loading this knowledge.")
+        }),
+        execute: async ({ skill, file, explanation }) => loadEditorChatSkillContent({
+            skill,
+            file,
+            explanation,
+            publicBaseUrl: input.publicBaseUrl,
+            abortSignal: input.abortSignal
+        })
+    });
+}
+// Lint gate for editor_action's replace_composition_html escape hatch. Returns
+// the tool result to send INSTEAD of the echoed args, or null to pass through.
+// A rejected result omits action_type, so the browser's extractEditorAction
+// never applies it — rejected payloads are inert by construction.
+export function lintReplaceCompositionAction(args) {
+    if (args.action_type !== "replace_composition_html") {
+        return null;
+    }
+    const lint = lintCompositionHtml(typeof args.composition_html === "string" ? args.composition_html : "");
+    if (!lint.ok) {
+        return {
+            rejected: true,
+            reason: "composition_html failed validation and was NOT applied. Fix the lint_errors and call replace_composition_html again.",
+            lint_errors: lint.errors,
+            lint_warnings: lint.warnings,
+            explanation: args.explanation
+        };
+    }
+    if (lint.warnings.length) {
+        return { ...args, lint_warnings: lint.warnings };
+    }
+    return null;
+}
+// Streaming wrapper around redactUnverifiedJobIds: ai-sdk text deltas split at
+// arbitrary byte boundaries, so a verified id like job_abc123 can arrive as
+// "…job_ab" + "c123…" — redacting each chunk independently mangles the leading
+// fragment. Hold back a trailing potential id fragment until the next delta
+// (or flush) completes it.
+export function createStreamingJobIdRedactor(input) {
+    let carry = "";
+    const TRAILING_FRAGMENT = /\bjob_[a-z0-9]*$/i;
+    const MAX_CARRY_CHARS = 64;
+    const redact = (text) => redactUnverifiedJobIds({
+        text,
+        verifiedJobIds: input.verifiedJobIds,
+        redactedJobIds: input.redactedJobIds
+    });
+    return {
+        push(text) {
+            let combined = carry + text;
+            carry = "";
+            const match = combined.match(TRAILING_FRAGMENT);
+            if (match && match[0].length <= MAX_CARRY_CHARS) {
+                carry = match[0];
+                combined = combined.slice(0, combined.length - carry.length);
+            }
+            return combined ? redact(combined) : "";
+        },
+        flush() {
+            const rest = carry;
+            carry = "";
+            return rest ? redact(rest) : "";
+        }
+    };
+}
 //# sourceMappingURL=editor-chat.js.map

package/dist/src/frontend/homepage-client.js

@@ -65,6 +65,10 @@ function HomepageClientApp({ boot }) {
     const bookmarks = useStore(store, (state) => state.bookmarks);
     const loading = useStore(store, (state) => state.loading);
     const error = useStore(store, (state) => state.error);
+    const view = useStore(store, (state) => state.view);
+    const popularTemplates = useStore(store, (state) => state.popularTemplates);
+    const popularLoading = useStore(store, (state) => state.popularLoading);
+    const popularError = useStore(store, (state) => state.popularError);
     const [bookmarksReady, setBookmarksReady] = useState(false);
     const visibleTemplates = useMemo(() => filterTemplates({ templates, searchQuery, bookmarksOnly, bookmarks }), [templates, searchQuery, bookmarksOnly, bookmarks]);
     useEffect(() => {
@@ -121,6 +125,51 @@ function HomepageClientApp({ boot }) {
         }, 8000);
         return () => window.clearInterval(timer);
     }, [hasProcessingTemplates, refreshFeed]);
+    // The curated Popular picks come from a separate endpoint and are the same
+    // for everyone, so they're fetched lazily the first time the toggle is opened
+    // (and re-fetched, without a spinner, while any pick is still downloading).
+    const refreshPopular = useCallback(async (options) => {
+        if (options?.showLoading) {
+            store.getState().setPopularLoading(true);
+        }
+        try {
+            const response = await fetch("/discover/popular", {
+                credentials: "same-origin",
+                cache: "no-store",
+                headers: { Accept: "application/json" }
+            });
+            const payload = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                throw new Error(typeof payload.error === "string" && payload.error ? payload.error : "Unable to load popular formats.");
+            }
+            store.getState().setPopularTemplates(Array.isArray(payload.templates) ? payload.templates : []);
+        }
+        catch (fetchError) {
+            if (options?.showLoading) {
+                store.getState().setPopularError(fetchError instanceof Error ? fetchError.message : "Unable to load popular formats.");
+            }
+            else {
+                debugError("homepage.popular_refresh_failed", { message: fetchError instanceof Error ? fetchError.message : String(fetchError) });
+            }
+        }
+    }, [store]);
+    const popularLoaded = useStore(store, (state) => state.popularLoaded);
+    useEffect(() => {
+        if (view !== "popular" || popularLoaded) {
+            return;
+        }
+        void refreshPopular({ showLoading: true });
+    }, [view, popularLoaded, refreshPopular]);
+    const hasProcessingPopular = view === "popular" && popularTemplates.some((template) => template.status === "processing");
+    useEffect(() => {
+        if (!hasProcessingPopular) {
+            return;
+        }
+        const timer = window.setInterval(() => {
+            void refreshPopular();
+        }, 8000);
+        return () => window.clearInterval(timer);
+    }, [hasProcessingPopular, refreshPopular]);
     const handleDeleteTemplate = useCallback(async (templateId) => {
         try {
             const response = await fetch(`/discover/templates/${encodeURIComponent(templateId)}`, {
@@ -219,7 +268,7 @@ function HomepageClientApp({ boot }) {
             return { ok: false, error: submitError instanceof Error ? submitError.message : "Unable to add that video." };
         }
     }, [refreshFeed]);
-    return (_jsx(HomepageShell, { account: boot.account, templates: templates, visibleTemplates: visibleTemplates, searchQuery: searchQuery, bookmarksOnly: bookmarksOnly, bookmarks: bookmarks, loading: loading, error: error, skillEndpointPrefix: boot.skillEndpointPrefix, onSearchQueryChange: (value) => store.getState().setSearchQuery(value), onBookmarksOnlyChange: (value) => store.getState().setBookmarksOnly(value), onToggleBookmark: (templateId) => store.getState().toggleBookmark(templateId), onAddTemplate: handleAddTemplate, onDeleteTemplate: handleDeleteTemplate }));
+    return (_jsx(HomepageShell, { account: boot.account, templates: templates, visibleTemplates: visibleTemplates, searchQuery: searchQuery, bookmarksOnly: bookmarksOnly, bookmarks: bookmarks, loading: loading, error: error, view: view, popularTemplates: popularTemplates, popularLoading: popularLoading, popularError: popularError, skillEndpointPrefix: boot.skillEndpointPrefix, onSearchQueryChange: (value) => store.getState().setSearchQuery(value), onBookmarksOnlyChange: (value) => store.getState().setBookmarksOnly(value), onViewChange: (value) => store.getState().setView(value), onToggleBookmark: (templateId) => store.getState().toggleBookmark(templateId), onAddTemplate: handleAddTemplate, onDeleteTemplate: handleDeleteTemplate }));
 }
 const boot = readBoot();
 const root = document.getElementById("homepage-root");