hyperframes 0.8.22 → 0.8.24

package/dist/cli.js

@@ -50,7 +50,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.8.22" : "0.0.0-dev";
+    VERSION = true ? "0.8.24" : "0.0.0-dev";
   }
 });
 
@@ -73411,7 +73411,22 @@ async function downloadWithRetry(url, localPath, timeoutMs, signal, onTransientR
       return await runDownloadAttempt(url, localPath, timeoutMs, attempt + 1, options, signal);
     } catch (error) {
       const classified = classifyDownloadFailure(error);
-      if (!classified.locallyRetryable || attempt >= maxTransientRetries) throw classified;
+      if (!classified.locallyRetryable || attempt >= maxTransientRetries) {
+        const identity2 = safeDownloadUrlIdentity(url);
+        throw new UrlDownloadError(
+          classified.kind,
+          classified.retryable,
+          classified.message,
+          classified.status,
+          {
+            ...classified.telemetry,
+            urlFingerprint: identity2.urlFingerprint,
+            initialHost: identity2.host,
+            attempt: attempt + 1
+          },
+          classified.locallyRetryable
+        );
+      }
       if (classified.retryable) onTransientRetry?.(classified);
       const identity = safeDownloadUrlIdentity(url);
       emitDownloadTelemetry(options, {
@@ -84035,6 +84050,47 @@ ${other.raw}`)
         }
         return findings;
       },
+      // gsap_timeline_return_used_as_tween — `tl.to()` returns the TIMELINE, not the tween it just
+      // created. `gsap.to()` returns a Tween, so the two read identically and behave nothing alike.
+      // Capturing the timeline's return and later treating it as an individual animation aims a
+      // tween-scoped call at the whole composition: `.kill()` on it interrupts the master timeline
+      // and detaches it from its parent, which stops a parent-driven seek dead while leaving an
+      // explicit `tl.progress()` still working -- so a render of the packaged defaults looks fine
+      // and only live playback breaks. A rebuild that collected these to discard them also leaves
+      // every previous keyframe in place and stacks the new ones on top.
+      ({ scripts }) => {
+        const findings = [];
+        for (const script of scripts) {
+          const source = stripJsComments(script.content);
+          const timelineVars = collectTimelineVarNames(source);
+          if (timelineVars.length === 0) continue;
+          const receivers = timelineVars.map(escapeRegExp22).join("|");
+          const pattern = new RegExp(
+            String.raw`(?:\.push\s*\(\s*|(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*)(?:${receivers})\s*\.\s*(to|from|fromTo|set|call|add)\s*\(`,
+            "g"
+          );
+          let match;
+          while ((match = pattern.exec(source)) !== null) {
+            const boundName = match[1];
+            const method = match[2];
+            if (boundName) {
+              const treatedAsTween = new RegExp(
+                String.raw`\b${escapeRegExp22(boundName)}\s*\.\s*(?:kill|revert|invalidate|pause|resume|restart|seek|progress|timeScale)\s*\(`
+              );
+              if (!treatedAsTween.test(source)) continue;
+            }
+            const contextStart = Math.max(0, match.index - 40);
+            findings.push({
+              code: "gsap_timeline_return_used_as_tween",
+              severity: "error",
+              message: `\`${match[0].includes(".push") ? "push" : boundName}\` captures the return of \`.${method}()\` on timeline \`${timelineVars[0]}\`, but a timeline's \`.to()\`/\`.from()\`/\`.set()\` returns THE TIMELINE ITSELF, not the tween it created. Every captured value is the same master timeline, so a tween-scoped call on it \u2014 \`.kill()\` above all \u2014 hits the whole composition: it interrupts the timeline and detaches it from its parent, which freezes a parent-driven seek while an explicit \`tl.progress()\` keeps working. Only \`gsap.to()\` returns a tween.`,
+              fixHint: "To build a group of keyframes you can later discard, put them in a nested timeline: `const nested = gsap.timeline(); nested.to(...); tl.add(nested, 0);` \u2014 then `nested.kill()` replaces exactly those keyframes and cannot reach `tl`. Children keep their absolute times when the nest is added at 0. To hold a single real tween, create it with `gsap.to(...)` and place it with `tl.add(tween, at)`.",
+              snippet: truncateSnippet(source.slice(contextStart, match.index + match[0].length + 60))
+            });
+          }
+        }
+        return findings;
+      },
       // gsap_group_selector_keyframes
       ({ scripts }) => {
         const findings = [];
@@ -87208,6 +87264,37 @@ function extractionFrameCountForDuration(durationSeconds, fps, isVFR) {
 function sdrToHdrTransformKey(transfer) {
   return `sdr2hdr-${transfer}`;
 }
+function safeVideoExtractionSourceIdentity(source) {
+  if (!isHttpUrl(source)) return null;
+  const identity = safeDownloadUrlIdentity(source);
+  return {
+    sourceFingerprint: `sha256:${identity.urlFingerprint}`,
+    host: identity.host ?? "other"
+  };
+}
+function downloadStatusClass(error) {
+  const status = error.status ?? error.telemetry?.status;
+  if (typeof status === "number" && status >= 400 && status < 500) return "http_4xx";
+  if (typeof status === "number" && status >= 500 && status < 600) return "http_5xx";
+  if (error.kind === "timeout") return "timeout";
+  if (error.kind === "network") return "network";
+  return "other";
+}
+function downloadFailureGroup(source, error) {
+  const sourceIdentity = safeVideoExtractionSourceIdentity(source);
+  const failureHost = error.telemetry?.finalHost ?? error.telemetry?.initialHost;
+  const attempt = error.telemetry?.attempt;
+  return {
+    ...sourceIdentity ? { sourceFingerprint: sourceIdentity.sourceFingerprint } : {},
+    ...failureHost ?? sourceIdentity?.host ? { host: failureHost ?? sourceIdentity?.host } : {},
+    statusClass: downloadStatusClass(error),
+    retry: {
+      phase: "download",
+      used: typeof attempt === "number" && attempt >= 2 ? 1 : 0,
+      budget: 1
+    }
+  };
+}
 function isVideoSourceExtractionError(error) {
   return typeof error === "object" && error !== null && "hyperframesVideoSourceExtractionError" in error && error.hyperframesVideoSourceExtractionError === true;
 }
@@ -87999,6 +88086,7 @@ async function extractAllVideoFrames(videos, baseDir, options, signal, config, c
         videoId: video.id,
         kind: classified.kind,
         retryable: classified.retryable,
+        ...err instanceof UrlDownloadError ? { group: downloadFailureGroup(video.src, err) } : {},
         error: classified.diagnostic
       });
     }
@@ -93096,6 +93184,7 @@ __export(src_exports, {
   runFfmpeg: () => runFfmpeg,
   runVideoExtractionWithRetry: () => runVideoExtractionWithRetry,
   safeDownloadUrlIdentity: () => safeDownloadUrlIdentity,
+  safeVideoExtractionSourceIdentity: () => safeVideoExtractionSourceIdentity,
   sampleRgb48le: () => sampleRgb48le,
   scaleProtocolTimeoutForComposition: () => scaleProtocolTimeoutForComposition,
   selectVerifySampleIndicesForTask: () => selectVerifySampleIndicesForTask,
@@ -125699,12 +125788,88 @@ var init_planValidation = __esm({
   }
 });
 
+// ../producer/src/services/render/extractionFailureMetadata.ts
+function stringOrEmpty(value) {
+  return value === void 0 ? "" : value;
+}
+function retrySortTuple(retry) {
+  return retry === void 0 ? ["", -1, -1] : [retry.phase, retry.used, retry.budget];
+}
+function extractionFailureGroupSortTuple(group) {
+  const retry = retrySortTuple(group.retry);
+  return [
+    group.kind,
+    stringOrEmpty(group.sourceFingerprint),
+    stringOrEmpty(group.host),
+    stringOrEmpty(group.statusClass),
+    retry[0],
+    retry[1],
+    retry[2]
+  ];
+}
+function compareExtractionFailureGroups(left, right) {
+  const leftTuple = extractionFailureGroupSortTuple(left);
+  const rightTuple = extractionFailureGroupSortTuple(right);
+  for (let index = 0; index < leftTuple.length; index += 1) {
+    const leftValue = leftTuple[index];
+    const rightValue = rightTuple[index];
+    if (leftValue < rightValue) return -1;
+    if (leftValue > rightValue) return 1;
+  }
+  return 0;
+}
+function extractionFailureGroupIdentityKey(group) {
+  return JSON.stringify(extractionFailureGroupSortTuple(group));
+}
+var init_extractionFailureMetadata = __esm({
+  "../producer/src/services/render/extractionFailureMetadata.ts"() {
+    "use strict";
+  }
+});
+
 // ../producer/src/services/render/stages/extractVideosStage.ts
 import { existsSync as existsSync51 } from "fs";
 import { join as join50 } from "path";
 function shouldCopyExtractedFrames(platform11) {
   return platform11 === "win32";
 }
+function buildExtractionFailureMetadata(inputs) {
+  const kindCounts = /* @__PURE__ */ new Map();
+  const grouped = /* @__PURE__ */ new Map();
+  for (const input2 of inputs) {
+    kindCounts.set(input2.kind, (kindCounts.get(input2.kind) ?? 0) + input2.affectedElementCount);
+    const key2 = extractionFailureGroupIdentityKey(input2);
+    const existing = grouped.get(key2);
+    if (existing) {
+      existing.affectedElementCount += input2.affectedElementCount;
+    } else {
+      grouped.set(key2, { ...input2 });
+    }
+  }
+  const allGroups = [...grouped.values()].sort(compareExtractionFailureGroups);
+  return {
+    schemaVersion: 1,
+    kindCounts: [...kindCounts].map(([kind, affectedElementCount]) => ({
+      kind,
+      affectedElementCount
+    })).sort((a, b2) => a.kind < b2.kind ? -1 : a.kind > b2.kind ? 1 : 0),
+    groups: allGroups.slice(0, MAX_EXTRACTION_FAILURE_GROUPS),
+    omittedGroupCount: Math.max(0, allGroups.length - MAX_EXTRACTION_FAILURE_GROUPS)
+  };
+}
+function extractionFailureMetadataFromResult(result) {
+  return buildExtractionFailureMetadata(
+    result.errors.map((failure) => ({
+      kind: failure.kind ?? "internal",
+      affectedElementCount: 1,
+      ...failure.group
+    }))
+  );
+}
+function safeVideoExtractionSourceLogMetadata(source) {
+  const identity = safeVideoExtractionSourceIdentity(source);
+  return identity ? { sourceType: "remote", ...identity } : { sourceType: "local" };
+}
 function resolveVideoExtractionPolicy(env = process.env) {
   const rawMode = env.HF_VIDEO_EXTRACTION_FAILURE_MODE?.trim().toLowerCase();
   const failureMode = rawMode === "observe" || rawMode === "off" ? rawMode : "enforce";
@@ -125738,7 +125903,8 @@ function buildVideoExtractionStageError(result) {
   return new VideoExtractionStageError(
     retryable ? "VIDEO_EXTRACTION_FAILED" : "VIDEO_SOURCE_UNRENDERABLE",
     retryable,
-    failures
+    failures,
+    extractionFailureMetadataFromResult(result)
   );
 }
 function buildHdrProbeStageError(failures) {
@@ -125753,7 +125919,13 @@ function buildHdrProbeStageError(failures) {
   return new VideoExtractionStageError(
     retryable ? "VIDEO_EXTRACTION_FAILED" : "VIDEO_SOURCE_UNRENDERABLE",
     retryable,
-    summary
+    summary,
+    buildExtractionFailureMetadata(
+      failures.map((failure) => ({
+        kind: failure.kind,
+        affectedElementCount: 1
+      }))
+    )
   );
 }
 function isHdrProbeFailure(failure) {
@@ -125880,7 +126052,10 @@ async function runExtractVideosStage(input2) {
     const totalVideos = composition.videos.length;
     for (let i2 = 0; i2 < totalVideos; i2++) {
       const v2 = composition.videos[i2];
-      log2?.info(`Extracting frames from video ${i2 + 1}/${totalVideos}: ${v2.src}`);
+      log2?.info(
+        `Extracting frames from video ${i2 + 1}/${totalVideos}`,
+        safeVideoExtractionSourceLogMetadata(v2.src)
+      );
     }
     extractionResult = await extractAllVideoFrames(
       composition.videos,
@@ -125952,7 +126127,7 @@ function appendAutoDetectedVideoAudio(composition, extracted) {
     existingAudioSrcs.add(video.src);
   }
 }
-var VideoExtractionStageError;
+var MAX_EXTRACTION_FAILURE_GROUPS, VideoExtractionStageError;
 var init_extractVideosStage = __esm({
   "../producer/src/services/render/stages/extractVideosStage.ts"() {
     "use strict";
@@ -125960,19 +126135,35 @@ var init_extractVideosStage = __esm({
     init_renderOrchestrator();
     init_shared();
     init_encoderInterruption();
+    init_extractionFailureMetadata();
+    MAX_EXTRACTION_FAILURE_GROUPS = 8;
     VideoExtractionStageError = class extends Error {
-      constructor(code, retryable, failures) {
+      constructor(code, retryable, failures, extractionFailure = buildExtractionFailureMetadata(
+        failures.map((failure) => ({
+          kind: failure.kind,
+          affectedElementCount: failure.count
+        }))
+      )) {
         const total = failures.reduce((sum, failure) => sum + failure.count, 0);
         const breakdown = failures.map((failure) => `${failure.kind}=${failure.count}`).join(",");
         super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]`);
         this.code = code;
         this.retryable = retryable;
         this.failures = failures;
+        this.extractionFailure = extractionFailure;
         this.name = "VideoExtractionStageError";
+        this.publicMetadata = { extractionFailure };
       }
       code;
       retryable;
       failures;
+      extractionFailure;
+      /**
+       * Producer servers may expose this explicitly public, JSON-compatible data
+       * without knowing its schema. Boundary adapters remain responsible for
+       * validating and applying policy to it.
+       */
+      publicMetadata;
     };
   }
 });
@@ -132280,10 +132471,12 @@ function extractSafeRenderErrorMetadata(error) {
   if (!errorCode || typeof error !== "object" || error === null) return void 0;
   const owner = "owner" in error ? error.owner : void 0;
   const retryable = "retryable" in error ? error.retryable : void 0;
+  const publicMetadata = "publicMetadata" in error ? error.publicMetadata : void 0;
   return {
     errorCode,
     errorOwner: owner === "user" || owner === "system" ? owner : void 0,
-    retryable: typeof retryable === "boolean" ? retryable : void 0
+    retryable: typeof retryable === "boolean" ? retryable : void 0,
+    ...isPlainObject4(publicMetadata) ? { errorMetadata: publicMetadata } : {}
   };
 }
 function parseServerFps(value) {
@@ -132605,6 +132798,7 @@ async function writeRenderStreamFailure(input2) {
       errorCode: safeError?.errorCode,
       errorOwner: safeError?.errorOwner,
       retryable: safeError?.retryable,
+      errorMetadata: safeError?.errorMetadata,
       stage: job.currentStage,
       elapsedMs,
       errorDetails: job.errorDetails ?? null,
@@ -132730,6 +132924,7 @@ function createRenderHandlers(options = {}) {
           errorCode: safeError?.errorCode,
           errorOwner: safeError?.errorOwner,
           retryable: safeError?.retryable,
+          errorMetadata: safeError?.errorMetadata,
           stage: job.currentStage,
           durationMs,
           errorDetails: job.errorDetails ?? null
@@ -149583,18 +149778,22 @@ function geometryIssueAnchor(candidate, time) {
     rect: candidate.rect
   };
 }
-function captionCenterInZone(rect, zone, canvas) {
-  const cx = rect.left + rect.width / 2;
-  const cy = rect.top + rect.height / 2;
-  const inside = cx >= zone.x0 * canvas.width && cx <= zone.x1 * canvas.width && cy >= zone.y0 * canvas.height && cy <= zone.y1 * canvas.height;
-  return { inside, cy };
+function captionBoxOverlapsZone(box, zone, canvas) {
+  const zx0 = zone.x0 * canvas.width;
+  const zy0 = zone.y0 * canvas.height;
+  const zx1 = zone.x1 * canvas.width;
+  const zy1 = zone.y1 * canvas.height;
+  const bx1 = box.left + box.width;
+  const by1 = box.top + box.height;
+  const overlaps = box.left < zx1 && bx1 > zx0 && box.top < zy1 && by1 > zy0;
+  return { overlaps, cy: box.top + box.height / 2 };
 }
 function captionFinding(candidate, options, canvas, time) {
   const zone = options.captionZone;
   if (!zone || candidate.kind !== "text" || !candidateIsSized(candidate, canvas)) return null;
   if ("data-layout-allow-caption-zone" in candidate.dataAttributes) return null;
-  const { inside, cy } = captionCenterInZone(candidate.rect, zone, canvas);
-  if (!inside) return null;
+  const { overlaps, cy } = captionBoxOverlapsZone(candidate.elementRect, zone, canvas);
+  if (!overlaps) return null;
   const text2 = candidate.text.slice(0, 48);
   const pctFromBottom = Math.round((canvas.height - cy) / canvas.height * 100);
   return {
@@ -149604,7 +149803,7 @@ function captionFinding(candidate, options, canvas, time) {
       code: "caption_zone_collision",
       severity: zone.severity === "error" ? "error" : "warning",
       text: text2,
-      message: `<${candidate.tag}> "${text2}" is centred in the reserved caption band (~${pctFromBottom}% up from the bottom).`,
+      message: `<${candidate.tag}> "${text2}" overlaps the reserved caption band (~${pctFromBottom}% up from the bottom).`,
       fixHint: "Keep main content outside the configured caption band, or mark intentional lower-third copy with data-layout-allow-caption-zone."
     }
   };
@@ -203174,18 +203373,25 @@ async function captionImagesWithGemini(outputDir, progress, warnings, options =
   }
   const openRouterKey = process.env.OPENROUTER_API_KEY;
   const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
-  if (!openRouterKey && !geminiKey) {
+  const vertexProject = process.env.HYPERFRAMES_VERTEX_PROJECT_ID;
+  const vertexServiceAccount = process.env.HYPERFRAMES_VERTEX_SERVICE_ACCOUNT;
+  const useVertex = Boolean(vertexProject && vertexServiceAccount);
+  if (!openRouterKey && !useVertex && !geminiKey) {
     reportOutcome();
     return geminiCaptions;
   }
-  const useOpenRouter = Boolean(openRouterKey);
-  const providerName = useOpenRouter ? "OpenRouter" : "Gemini";
-  const model = useOpenRouter ? process.env.HYPERFRAMES_OPENROUTER_MODEL || "google/gemini-3.1-flash-lite" : process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview";
+  const provider = openRouterKey ? "openrouter" : useVertex ? "vertex" : "gemini";
+  const providerName = { openrouter: "OpenRouter", vertex: "Vertex AI", gemini: "Gemini" }[provider];
+  const model = {
+    openrouter: process.env.HYPERFRAMES_OPENROUTER_MODEL || "google/gemini-3.1-flash-lite",
+    vertex: process.env.HYPERFRAMES_VERTEX_MODEL || "gemini-2.5-flash",
+    gemini: process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview"
+  }[provider];
   const requestTimeoutMs = resolveVisionRequestTimeoutMs();
   progress("design", `Captioning images with ${providerName} vision...`);
   try {
     let captionOne;
-    if (openRouterKey) {
+    if (provider === "openrouter") {
       captionOne = async ({ mimeType, base64, prompt, maxTokens, timeoutMs }) => {
         return runBoundedVisionRequest(async (signal) => {
           const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
@@ -203221,9 +203427,31 @@ async function captionImagesWithGemini(outputDir, progress, warnings, options =
         }, timeoutMs);
       };
     } else {
-      if (!geminiKey) return geminiCaptions;
       const { GoogleGenAI: GoogleGenAI2 } = await Promise.resolve().then(() => (init_node4(), node_exports));
-      const ai = new GoogleGenAI2({ apiKey: geminiKey });
+      let ai;
+      if (provider === "vertex") {
+        if (!vertexProject || !vertexServiceAccount) return geminiCaptions;
+        let credentials;
+        try {
+          credentials = JSON.parse(vertexServiceAccount);
+        } catch {
+          warnings.push(
+            "HYPERFRAMES_VERTEX_SERVICE_ACCOUNT is not valid JSON; skipped vision captioning."
+          );
+          internalError = true;
+          reportOutcome();
+          return geminiCaptions;
+        }
+        ai = new GoogleGenAI2({
+          vertexai: true,
+          project: vertexProject,
+          location: process.env.HYPERFRAMES_VERTEX_LOCATION || "us-central1",
+          googleAuthOptions: { credentials }
+        });
+      } else {
+        if (!geminiKey) return geminiCaptions;
+        ai = new GoogleGenAI2({ apiKey: geminiKey });
+      }
       captionOne = async ({ mimeType, base64, prompt, maxTokens, timeoutMs }) => {
         const response = await runBoundedVisionRequest(
           (signal) => ai.models.generateContent({
@@ -203236,6 +203464,12 @@ async function captionImagesWithGemini(outputDir, progress, warnings, options =
             ],
             config: {
               maxOutputTokens: maxTokens,
+              // A one-line factual caption needs no reasoning, and leaving thinking on is
+              // not merely wasteful: thinking tokens are drawn from maxOutputTokens, so the
+              // model can spend the whole budget and return empty text. That surfaces as a
+              // successful request with no caption — the capture then logs "Captioned N/N
+              // images" followed by "0 images captioned", which is what production shows.
+              thinkingConfig: { thinkingBudget: 0 },
               abortSignal: signal,
               httpOptions: { timeout: timeoutMs }
             }
@@ -203327,6 +203561,7 @@ async function captionImagesWithGemini(outputDir, progress, warnings, options =
         reportOutcome();
         return geminiCaptions;
       }
+      const hostConcurrency = sharp3.concurrency();
       progress("design", `Rasterizing + captioning ${svgFiles.length} SVGs via vision API...`);
       const SVG_BATCH = 20;
       const SVG_RENDER_SIZE = 256;
@@ -203339,10 +203574,11 @@ async function captionImagesWithGemini(outputDir, progress, warnings, options =
         }
         const timeoutMs = Math.max(1, Math.min(requestTimeoutMs, remainingMs));
         const batch = svgFiles.slice(i2, i2 + SVG_BATCH);
-        const results = await Promise.allSettled(
-          batch.map(async ({ relPath }) => {
+        const rasterized = [];
+        sharp3.concurrency(1);
+        try {
+          for (const { relPath } of batch) {
             const filePath = join121(assetsDir, relPath);
-            let pngBase64;
             try {
               const svgSource = readFileSync84(filePath, "utf-8");
               const lightFillHits = (svgSource.match(/fill\s*=\s*["'](#fff(fff)?|white|#[ef][ef][ef]|#[ef]{6})["']/gi) || []).length;
@@ -203354,11 +203590,18 @@ async function captionImagesWithGemini(outputDir, progress, warnings, options =
                 fit: "inside",
                 withoutEnlargement: false
               }).flatten({ background: bg }).png().toBuffer();
-              pngBase64 = pngBuffer.toString("base64");
+              rasterized.push({ relPath, pngBase64: pngBuffer.toString("base64") });
             } catch {
               svgsSkipped++;
-              return { file: relPath, caption: "" };
+              rasterized.push({ relPath, pngBase64: null });
             }
+          }
+        } finally {
+          sharp3.concurrency(hostConcurrency);
+        }
+        const results = await Promise.allSettled(
+          rasterized.map(async ({ relPath, pngBase64 }) => {
+            if (pngBase64 === null) return { file: relPath, caption: "" };
             const caption = await captionOne({
               mimeType: "image/png",
               base64: pngBase64,
@@ -204810,8 +205053,8 @@ ${extracted.bodyHtml}
     try {
       const lines = generateAssetDescriptions(outputDir, tokens, catalogedAssets, geminiCaptions);
       if (lines.length > 0) {
-        const hasVisionKey = !!(!skipVision && (process.env.OPENROUTER_API_KEY || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY));
-        const header = hasVisionKey ? "# Asset Descriptions\n\nOne line per file. Read this instead of opening every image individually.\n\nTo find a specific brand or icon, **grep this file for the brand name in the description text** (e.g. `grep -i 'autodesk' asset-descriptions.md`). The Gemini Vision captions identify what's actually in each file \u2014 that's the agent's selector.\n\nThe `logo-<hash>.svg` filename prefix is a cheap structural hint (DOM said this SVG was inside a `<header>`, home-link `<a>`, or had an aria-label matching the page brand). It is NOT a content claim \u2014 many `logo-*` files are nav icons or decorative shapes. Trust the captions, not the filename prefix.\n\n" : "# Asset Descriptions\n\n\u26A0\uFE0F  GEMINI_API_KEY not set \u2014 descriptions below are catalog-derived (alt text, headings, section context, filename) instead of Vision-generated. To get richer Vision descriptions on the next capture, set GEMINI_API_KEY (or GOOGLE_API_KEY) and re-run.\n\nThe `logo-<hash>.svg` filename prefix is a structural hint (DOM said this SVG was inside a `<header>`, home-link `<a>`, or had an aria-label matching the page brand). To pick the actual brand logo without Vision, open the `logo-*` candidates in a previewer or rasterize them with `sharp` before referencing \u2014 composing a fake logo ships off-brand in the final video.\n\n";
+        const hasVisionKey = !!(!skipVision && (process.env.OPENROUTER_API_KEY || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || process.env.HYPERFRAMES_VERTEX_PROJECT_ID && process.env.HYPERFRAMES_VERTEX_SERVICE_ACCOUNT));
+        const header = hasVisionKey ? "# Asset Descriptions\n\nOne line per file. Read this instead of opening every image individually.\n\nTo find a specific brand or icon, **grep this file for the brand name in the description text** (e.g. `grep -i 'autodesk' asset-descriptions.md`). The Gemini Vision captions identify what's actually in each file \u2014 that's the agent's selector.\n\nThe `logo-<hash>.svg` filename prefix is a cheap structural hint (DOM said this SVG was inside a `<header>`, home-link `<a>`, or had an aria-label matching the page brand). It is NOT a content claim \u2014 many `logo-*` files are nav icons or decorative shapes. Trust the captions, not the filename prefix.\n\n" : "# Asset Descriptions\n\n\u26A0\uFE0F  No vision credentials \u2014 descriptions below are catalog-derived (alt text, headings, section context, filename) instead of Vision-generated. To get richer Vision descriptions on the next capture, set GEMINI_API_KEY (or GOOGLE_API_KEY), or HYPERFRAMES_VERTEX_PROJECT_ID plus HYPERFRAMES_VERTEX_SERVICE_ACCOUNT for Vertex service-account auth, and re-run.\n\nThe `logo-<hash>.svg` filename prefix is a structural hint (DOM said this SVG was inside a `<header>`, home-link `<a>`, or had an aria-label matching the page brand). To pick the actual brand logo without Vision, open the `logo-*` candidates in a previewer or rasterize them with `sharp` before referencing \u2014 composing a fake logo ships off-brand in the final video.\n\n";
         writeFileSync56(
           join126(outputDir, "extracted", "asset-descriptions.md"),
           header + lines.map((l) => "- " + l).join("\n") + "\n",