@cueframe/kernel 0.1.2 → 0.1.4

package/dist/{chunk-VHF66LCQ.js → chunk-RXCEPCAQ.js}

@@ -3,6 +3,10 @@ import {
   buildEasedZooms,
   buildPannedCenters
 } from "./chunk-QH3YI3ND.js";
+import {
+  flattenCompoundClips,
+  hasCompoundClips
+} from "./chunk-23HFEKV7.js";
 import {
   DOMINANCE_WEIGHTS,
   ENTER_SEC,
@@ -20,11 +24,7 @@ import {
   scoreAndRank,
   segmentShots,
   stabilizeSelectionHysteresis
-} from "./chunk-XQ72DZKJ.js";
-import {
-  flattenCompoundClips,
-  hasCompoundClips
-} from "./chunk-23HFEKV7.js";
+} from "./chunk-7TQCR7AB.js";
 import {
   compositionHasVo,
   roleDefaultGainDb
@@ -36,7 +36,7 @@ import {
 import {
   CueframeError,
   encodeError
-} from "./chunk-LLUW26BS.js";
+} from "./chunk-R5BMJ2NX.js";
 
 // ../execution/core/src/render/emphasis.ts
 function buildEmphasisSet(emphasisWords) {
@@ -178,6 +178,9 @@ function resolveBookendTimeline(brandKit, bodyFrames, fps) {
 }
 
 // ../execution/core/src/render/compositionRender.ts
+function renderInputError(code, message, locator) {
+  return new CueframeError(code, message, void 0, locator);
+}
 function projectClipEffects(clip, renderClipId) {
   const effects = clip.effects;
   if (!effects || effects.length === 0) return [];
@@ -217,53 +220,81 @@ function compositionFormatDimensions(format) {
 }
 function validateComposition(raw) {
   if (!raw || typeof raw !== "object") {
-    throw new Error("composition: expected object, got " + typeof raw);
+    throw renderInputError("invalid_composition", "composition: expected object, got " + typeof raw, {
+      compositionPath: "composition"
+    });
   }
   const obj = raw;
   if (obj.v !== 1) {
-    throw new Error("composition.v: expected literal 1");
+    throw renderInputError("invalid_composition", "composition.v: expected literal 1", {
+      compositionPath: "composition.v"
+    });
   }
   const fmt = obj.format;
   if (!fmt || typeof fmt.aspectRatio !== "string") {
-    throw new Error("composition.format.aspectRatio: required string");
+    throw renderInputError("invalid_composition", "composition.format.aspectRatio: required string", {
+      compositionPath: "composition.format.aspectRatio"
+    });
   }
   if (!Array.isArray(obj.tracks)) {
-    throw new Error("composition.tracks: expected array");
+    throw renderInputError("invalid_composition", "composition.tracks: expected array", {
+      compositionPath: "composition.tracks"
+    });
   }
   for (let i = 0; i < obj.tracks.length; i++) {
     const t = obj.tracks[i];
     if (!t || typeof t !== "object") {
-      throw new Error(`composition.tracks[${i}]: expected object`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}]: expected object`, {
+        compositionPath: `composition.tracks[${i}]`
+      });
     }
     if (typeof t.id !== "string") {
-      throw new Error(`composition.tracks[${i}].id: expected string`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}].id: expected string`, {
+        compositionPath: `composition.tracks[${i}].id`
+      });
     }
     if (!["video", "audio", "image", "overlay", "effect"].includes(t.kind)) {
-      throw new Error(`composition.tracks[${i}].kind: invalid value`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}].kind: invalid value`, {
+        compositionPath: `composition.tracks[${i}].kind`,
+        ...typeof t.id === "string" ? { trackId: t.id } : {}
+      });
     }
     if (!Array.isArray(t.contents)) {
-      throw new Error(`composition.tracks[${i}].contents: expected array`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}].contents: expected array`, {
+        compositionPath: `composition.tracks[${i}].contents`,
+        trackId: t.id
+      });
     }
   }
   if (obj.markers !== void 0 && !Array.isArray(obj.markers)) {
-    throw new Error("composition.markers: expected array when present");
+    throw renderInputError("invalid_composition", "composition.markers: expected array when present", {
+      compositionPath: "composition.markers"
+    });
   }
   if (obj.captions !== void 0) {
     const c = obj.captions;
     if (!c || typeof c !== "object") {
-      throw new Error("composition.captions: expected object when present");
+      throw renderInputError("invalid_composition", "composition.captions: expected object when present", {
+        compositionPath: "composition.captions"
+      });
     }
     if (!Array.isArray(c.segments)) {
-      throw new Error("composition.captions.segments: expected array");
+      throw renderInputError("invalid_composition", "composition.captions.segments: expected array", {
+        compositionPath: "composition.captions.segments"
+      });
     }
     if (c.style !== void 0 && (typeof c.style !== "object" || c.style === null)) {
-      throw new Error("composition.captions.style: expected object when present");
+      throw renderInputError("invalid_composition", "composition.captions.style: expected object when present", {
+        compositionPath: "composition.captions.style"
+      });
     }
     if (c.style !== void 0) {
       const fs = c.style.fontSize;
       if (fs !== void 0 && (typeof fs !== "number" || fs < 1 || fs > 15)) {
-        throw new Error(
-          `composition.captions.style.fontSize: PERCENT of composition height (1-15, default 5) \u2014 got ${String(fs)}. px values are not accepted; a px-intent value renders giant band-overflowing captions. Re-author the style with a percent value.`
+        throw renderInputError(
+          "invalid_composition",
+          `composition.captions.style.fontSize: PERCENT of composition height (1-15, default 5) \u2014 got ${String(fs)}. px values are not accepted; a px-intent value renders giant band-overflowing captions. Re-author the style with a percent value.`,
+          { compositionPath: "composition.captions.style.fontSize" }
         );
       }
     }
@@ -299,11 +330,13 @@ function overlayTransitionFields(c, fps) {
 function rendersNoFrames(c) {
   return !(c.duration > 0);
 }
-function resolveSrcUrl(mediaId, srcUrls) {
+function resolveSrcUrl(mediaId, srcUrls, locator) {
   const url = srcUrls[mediaId];
   if (!url) {
-    throw new Error(
-      `Composition references mediaId '${mediaId}' but no presigned URL was supplied. Pre-sign every unique mediaId before calling compositionToRenderInput.`
+    throw renderInputError(
+      "source_media_not_found",
+      `Composition references mediaId '${mediaId}' but no presigned URL was supplied. Pre-sign every unique mediaId before calling compositionToRenderInput.`,
+      { ...locator, mediaId }
     );
   }
   return url;
@@ -329,15 +362,24 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
     if (c.source.kind !== "media") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on a ${track.kind} track (expected 'media')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on a ${track.kind} track (expected 'media')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     if (rendersNoFrames(c)) continue;
-    const src = resolveSrcUrl(c.source.mediaId, srcUrls);
-    if (coViewUrls?.[c.source.mediaId] !== void 0 && c.region !== void 0 && !(c.region.x === 0 && c.region.y === 0 && c.region.w === 1 && c.region.h === 1)) {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}] (clip ${c.id}): a co-view clip (captions-behind-subject) cannot also carry a sub-frame region \u2014 the co-view render path does not honor region. Use one or the other.`
+    const src = resolveSrcUrl(c.source.mediaId, srcUrls, {
+      trackId: track.id,
+      clipId: c.id,
+      compositionPath: `composition.tracks[${track.id}].contents[${i}].source.mediaId`
+    });
+    const packedUrl = coViewUrls?.[c.id] ?? coViewUrls?.[c.source.mediaId];
+    if (packedUrl !== void 0 && c.region !== void 0 && !(c.region.x === 0 && c.region.y === 0 && c.region.w === 1 && c.region.h === 1)) {
+      throw renderInputError(
+        "invalid_composition",
+        `composition.tracks[${track.id}].contents[${i}] (clip ${c.id}): a co-view clip (captions-behind-subject) cannot also carry a sub-frame region \u2014 the co-view render path does not honor region. Use one or the other.`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].region` }
       );
     }
     if (track.kind === "audio") {
@@ -412,7 +454,7 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
         } : {},
         ...trajectoryUrls?.[c.id] !== void 0 ? { cropTrajectoryUrl: trajectoryUrls[c.id] } : {},
         ...trajectories?.[c.id] !== void 0 ? { cropTrajectory: trajectories[c.id] } : {},
-        ...coViewUrls?.[c.source.mediaId] !== void 0 ? { packedUrl: coViewUrls[c.source.mediaId] } : {}
+        ...packedUrl !== void 0 ? { packedUrl } : {}
       });
     }
     if (firstEmittedSubId !== void 0) {
@@ -444,12 +486,18 @@ function projectImageTrack(track, fps, srcUrls) {
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
     if (c.source.kind !== "media") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an image track (expected 'media')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an image track (expected 'media')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     if (rendersNoFrames(c)) continue;
-    const src = resolveSrcUrl(c.source.mediaId, srcUrls);
+    const src = resolveSrcUrl(c.source.mediaId, srcUrls, {
+      trackId: track.id,
+      clipId: c.id,
+      compositionPath: `composition.tracks[${track.id}].contents[${i}].source.mediaId`
+    });
     const { startFrame: timelineStartFrames, durationInFrames } = timelineSpanFrames(
       c.startTime,
       c.startTime + c.duration,
@@ -501,8 +549,15 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       if (durationInFrames2 === 0) continue;
       const src = alphaUrls[c.id];
       if (!src) {
-        throw new Error(
-          `composition.tracks[${track.id}].contents[${i}]: alpha-layer clip ${c.id} has no baked alpha (alphaUrls[${c.id}] missing) \u2014 bake before render`
+        throw renderInputError(
+          "variant_not_baked",
+          `composition.tracks[${track.id}].contents[${i}]: alpha-layer clip ${c.id} has no baked alpha (alphaUrls[${c.id}] missing) \u2014 bake before render`,
+          {
+            trackId: track.id,
+            clipId: c.id,
+            componentId: c.source.componentId,
+            compositionPath: `composition.tracks[${track.id}].contents[${i}].source`
+          }
         );
       }
       overlays.push({
@@ -544,8 +599,10 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       continue;
     }
     if (c.source.kind !== "overlay") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an overlay track (expected 'overlay', 'alpha-layer', or 'card')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an overlay track (expected 'overlay', 'alpha-layer', or 'card')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     const { startFrame, durationInFrames } = timelineSpanFrames(
@@ -559,8 +616,10 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       const fresh = jsSourceByClipId[c.id];
       const sc = typeof fresh === "string" && fresh.length > 0 ? fresh : overlayParams.sourceCode;
       if (typeof sc !== "string" || sc.length === 0) {
-        throw new Error(
-          `composition.tracks[${track.id}].contents[${i}].source: custom overlay has no sourceCode (no fresh jsSource for clip '${c.id}' and no inline params.sourceCode) \u2014 mirror code 'custom_missing_sourcecode'`
+        throw renderInputError(
+          "custom_missing_sourcecode",
+          `composition.tracks[${track.id}].contents[${i}].source: custom overlay has no sourceCode (no fresh jsSource for clip '${c.id}' and no inline params.sourceCode) \u2014 mirror code 'custom_missing_sourcecode'`,
+          { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
         );
       }
       const { componentId: _cid, sourceCode: _sc, ...props } = overlayParams;
@@ -591,8 +650,10 @@ function projectEffectTrack(track, fps) {
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
     if (c.source.kind !== "effect") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an effect track (expected 'effect')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an effect track (expected 'effect')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     const { startFrame, durationInFrames } = timelineSpanFrames(

package/dist/{chunk-LJ5W4ZBU.js → chunk-TLVPDT4R.js}

@@ -1,7 +1,7 @@
 import {
   ChatErrorView,
   DirectorTurnContext
-} from "./chunk-ZPLJ24OV.js";
+} from "./chunk-D6S3ZKIY.js";
 import {
   GenerationArtifact
 } from "./chunk-73DQTUWY.js";

package/dist/{chunk-PIURX6IZ.js → chunk-WTT3GGCA.js}

@@ -6,7 +6,7 @@ import {
 import {
   CueframeError,
   encodeError
-} from "./chunk-LLUW26BS.js";
+} from "./chunk-R5BMJ2NX.js";
 
 // ../composition/src/projection/cardTokens.ts
 var CARD_MOTION_VAR_NAMES = [
@@ -154,7 +154,10 @@ function overlapsMs(aStartSec, aDurationSec, bStartSec, bDurationSec) {
 }
 function tracksOf(composition) {
   const tracks = composition?.tracks;
-  return Array.isArray(tracks) ? tracks : [];
+  if (!Array.isArray(tracks)) return [];
+  return tracks.filter(
+    (track) => track.enabled !== false
+  );
 }
 function clipsOf(track) {
   const contents = track.contents;
@@ -210,7 +213,7 @@ async function behindReadinessForTarget(target, mattes) {
   if (!target) return { state: "no-clip" };
   const key = await matteIntentKey({ ...target.window, subjectClass: "person" });
   const entry = mattes?.[key];
-  if (!entry?.geometryR2Key) return { state: "no-matte", target };
+  if (!entry?.geometryUrl && !entry?.geometryR2Key) return { state: "no-matte", target };
   const presenceFraction = entry.presenceFraction ?? 0;
   if (presenceFraction < MIN_PRESENCE_FOR_BEHIND) {
     return { state: "no-subject", target, presenceFraction };
@@ -237,7 +240,9 @@ function matteWindowsByMediaId(composition, behindWindows) {
       const startSec = typeof trim?.start === "number" ? trim.start : 0;
       const endSec = typeof trim?.end === "number" ? trim.end : startSec + clip.duration;
       if (endSec <= startSec) continue;
-      if (!out.has(mediaId)) out.set(mediaId, { startSec, endSec });
+      const windows = out.get(mediaId) ?? [];
+      windows.push({ clipId: clip.id, startSec, endSec });
+      out.set(mediaId, windows);
     }
   }
   return out;

package/dist/{chunk-CAJQ7H5A.js → chunk-YE3F4LNJ.js}

@@ -1,41 +1,41 @@
 import {
   isContrastCritical
 } from "./chunk-YLDMAZZE.js";
-import {
-  catalog as catalog6
-} from "./chunk-BKHGL4MB.js";
-import {
-  catalog as catalog2
-} from "./chunk-GMD33ZD7.js";
-import {
-  catalog as catalog8
-} from "./chunk-SAMQUUO5.js";
-import {
-  catalog as catalog4
-} from "./chunk-RP4SXXLJ.js";
 import {
   catalog as catalog7
-} from "./chunk-DYZE7JZA.js";
+} from "./chunk-TMIBBD5E.js";
 import {
   catalog
-} from "./chunk-UQSOS726.js";
+} from "./chunk-6ABIXGLO.js";
 import {
   catalog as catalog3
 } from "./chunk-AWT3P5ZN.js";
+import {
+  catalog as catalog6
+} from "./chunk-THJAY7QS.js";
 import {
   catalog as catalog5
-} from "./chunk-G5BFI32U.js";
+} from "./chunk-XATRRDVG.js";
+import {
+  catalog as catalog2
+} from "./chunk-O7GNE4BQ.js";
+import {
+  catalog as catalog8
+} from "./chunk-BIBYZJL3.js";
+import {
+  catalog as catalog4
+} from "./chunk-3PM6VICZ.js";
 import {
   getPrimitiveSubtextParam,
   getPrimitiveTextParam
-} from "./chunk-DCVJWGIA.js";
+} from "./chunk-JY26PIRP.js";
 import {
   NEUTRAL_RAMP
 } from "./chunk-JF4JJAFP.js";
 import {
   CueframeError,
   encodeError
-} from "./chunk-LLUW26BS.js";
+} from "./chunk-R5BMJ2NX.js";
 
 // ../execution/compose/src/primitiveRegistry.ts
 var allCatalogs = [

package/dist/{chunk-TD347SSX.js → chunk-YXEZ75MB.js}

@@ -1,6 +1,9 @@
 import {
   waitForJob
-} from "./chunk-QETYXKQQ.js";
+} from "./chunk-7V3F5HO4.js";
+import {
+  CURATED_TOOLS
+} from "./chunk-PJ4R4N4Q.js";
 import {
   GENERATED_OPERATIONS,
   apiErrorFrom,
@@ -17,10 +20,7 @@ import {
   sniffImageMediaType,
   text,
   withMedia
-} from "./chunk-W3SIWT7J.js";
-import {
-  CURATED_TOOLS
-} from "./chunk-AO744WIK.js";
+} from "./chunk-RQ2G4DXI.js";
 
 // ../mcp/src/prompts.ts
 var skillListCache = null;
@@ -91,17 +91,17 @@ CLIPPING (find the best short-form moments in a long video): \`suggest_briefs\`
 
 Every expensive step has a cheap, inspectable check \u2014 prefer reading a value over rendering and eyeballing:
 - Framing & timing are data: \`get_media_context\` BEFORE you compose.
-- Evidence beats guessing: \`preview_frame\` (whole-composition stills), \`preview_component\` (ONE graphic as a MOTION clip \u2014 the same bake production composites), \`preview_clip\` (a fromSec\u2192toSec window as a watchable MP4, max 60s, capture-priced \u2014 judge a cut or transition at full fidelity WITHOUT paying for a full render). These are STATELESS: nothing to open, warm, or close; concurrent previews do not contend. \`preview_frame\` defaults to the PERSISTED composition and echoes \`previewed.{source, compositionId, etag}\` \u2014 what you saw is what create_render encodes.
+- Evidence beats guessing: \`preview_frame\` (whole-composition stills), \`preview_component\` (ONE authored graphic: \`executionMode:"live"\` returns a PNG image; \`executionMode:"baked"\` returns a transparent VP9 motion clip \u2014 exactly the lane production composites), \`preview_clip\` (a fromSec\u2192toSec window as a watchable MP4, max 60s, capture-priced \u2014 judge a cut or transition at full fidelity WITHOUT paying for a full render). These are STATELESS: nothing to open, warm, or close; concurrent previews do not contend. \`preview_frame\` defaults to the PERSISTED composition and echoes \`previewed.{source, compositionId, etag}\` \u2014 what you saw is what create_render encodes.
 - Quality is a number: \`score_composition\` returns scores + critique + a checkpointId; the compose result carries the winner's composite. **score vs consult**: score answers "how good IS this" (grounded numbers); \`consult\` answers "what SHOULD I change" (advice + an adoptable fix via \`select_candidate\`).
 
 ## Async model
 
 Every long job is either polled or pushed \u2014 never guessed:
-- \`wait_job\` kinds: \`render\`, \`compose\`, \`suggestions\`, \`verify\` (score jobs), \`preview\` (component clips), \`brand_kit_extract\`, \`consult\`. It blocks up to its window and returns a CONTINUATION when still running \u2014 re-call it.
+- \`wait_job\` kinds: \`media\` (imports/generation), \`render\`, \`compose\`, \`suggestions\`, \`verify\` (score jobs), \`preview_frame\` (composition stills), \`preview\` (component image-or-motion previews), \`brand_kit_extract\`, \`consult\`. It blocks up to its window and returns a CONTINUATION when still running \u2014 re-call it.
 - Webhooks (\`create_webhook\`): ONE terminal event per kind with status INSIDE the payload \u2014 \`render.completed\`, \`compose.completed\`, \`media.completed\`, \`suggest.completed\` \u2014 plus \`checkpoint.ready\` (a held compose paused for review). Read \`cueframe://webhook-events\` for the full contract before building a receiver.
 - Presigned URLs (stills, clips, render outputs) expire \u2014 render outputs last ~7 days (refresh via the render's refresh-url op); preview stills/clips ~1 hour. Re-read for a fresh link instead of caching one.
 
-CUSTOM GRAPHICS \u2014 author or FORK: \`create_component\` (tsxSource) from scratch, or \`get_component_source\` on a built-in primitive (e.g. \`cinematic-title\`) to fork its editable module. Iterate author\u2192preview\u2192fix with \`preview_component\` (202 + jobId; \`wait_job(kind:"preview")\` returns the clip URL \u2014 a compile failure lands on the job's FAILED terminal carrying the sanitized compiler error) \u2192 fix via \`update_component\` \u2192 preview again. Place it via \`apply_composition\` as an \`alpha-layer\` clip \u2014 the shared renderer never runs your code (it bakes to transparent video first).
+CUSTOM GRAPHICS \u2014 author or FORK: \`create_component\` (tsxSource) from scratch, or \`get_component_source\` on a built-in primitive (e.g. \`cinematic-title\`) to fork its editable module. Iterate author\u2192preview\u2192fix with \`preview_component\` (202 + jobId; \`wait_job(kind:"preview")\` returns a PNG image for \`executionMode:"live"\` or a VP9 motion URL for \`executionMode:"baked"\`; a compile failure lands on the job's FAILED terminal carrying the sanitized compiler error) \u2192 fix via \`update_component\` \u2192 preview again. Place baked components via \`apply_composition\` as an \`alpha-layer\` clip \u2014 the shared renderer never runs authored source code (it composites the transparent baked video).
 
 Cleanup: \`delete_project\` / \`delete_media\` / \`delete_webhook\` / \`delete_composition\`. \`list_projects\` re-orients you in an existing workspace; \`list_media\` (filter by \`source\`/\`tag\`) lists the library.
 
@@ -436,12 +436,16 @@ function registerCuratedTools(server, ex, opts) {
     for (const friendly of Object.keys(spec.pathArgs ?? {})) {
       inputSchema[friendly] = z.string().describe(`${friendly} (path).`);
     }
+    for (const [queryArg, description] of Object.entries(spec.queryArgs ?? {})) {
+      inputSchema[queryArg] = z.string().optional().describe(description);
+    }
     const bodySchema = bodySchemaFor(op);
     if (bodySchema) inputSchema.body = bodySchema;
     const annotations = { ...op.annotations, ...spec.annotations };
     server.registerTool(spec.name, { title: spec.title ?? titleCase(spec.name), description: spec.description, inputSchema, annotations }, async (args, extra) => timed(opts?.onEvent, spec.name, async (report) => {
       const a = args;
       try {
+        const query = Object.keys(spec.queryArgs ?? {}).filter((name) => a[name] !== void 0 && a[name] !== null && a[name] !== "").map((name) => `${encodeURIComponent(name)}=${encodeURIComponent(String(a[name]))}`).join("&");
         return await dispatchOp(ex, op, (p) => a[reverse[p]], a.body, extra, spec.name, async (res) => {
           if (spec.okText) return text(spec.okText(a));
           const json = res.text ? safeParse(res.text) : void 0;
@@ -454,17 +458,17 @@ function registerCuratedTools(server, ex, opts) {
             if (data.length) return withMedia(payload, data.map((d) => ({ data: d, kind })));
           }
           return text(payload);
-        });
+        }, query || void 0);
       } catch (err) {
         return errText(`${spec.name} failed: ${fmtErr(err)}`);
       }
     }));
   }
   registerWaitJob(server, ex, opts?.waitCapMs, opts?.onEvent);
-  registerPreviewCard(server, ex, opts?.onEvent);
+  registerPreviewCard(server, ex, opts?.waitCapMs, opts?.onEvent);
 }
-function registerPreviewCard(server, ex, onEvent) {
-  const op = opById("previewFrame");
+function registerPreviewCard(server, ex, waitCapMs, onEvent) {
+  const op = opById("previewFrameJob");
   server.registerTool(
     "preview_card",
     {
@@ -508,12 +512,19 @@ function registerPreviewCard(server, ex, onEvent) {
           "preview_card",
           async (res) => {
             const json = res.text ? safeParse(res.text) : void 0;
-            const urls = (Array.isArray(json?.stills) ? json.stills : []).map(
-              (st) => st?.url
-            );
+            const jobId = json?.jobId;
+            if (typeof jobId !== "string" || !jobId) {
+              return errText("preview_card enqueue returned no jobId");
+            }
+            const waitMs = Math.min(waitCapMs ?? 3e4, 3e4);
+            const done = await waitForJob(ex, "preview_frame", jobId, void 0, Date.now() + waitMs);
+            if (!done.ok) return errText(done.text);
+            if (done.stillRunning) return text(`${done.text}
+jobId: ${jobId}`);
+            const urls = done.mediaUrls ?? [];
             const data = await fetchPreviews(urls, 2);
             report({ preview: { urls: urls.filter(Boolean).length, fetched: data.length } });
-            const payload = res.text || `previewed card (${a.aspectRatio ?? "9:16"})`;
+            const payload = done.text || `previewed card (${a.aspectRatio ?? "9:16"})`;
             return data.length ? withMedia(payload, data.map((d) => ({ data: d, kind: "image" }))) : text(payload);
           }
         );
@@ -529,10 +540,10 @@ function registerWaitJob(server, ex, waitCapMs, onEvent) {
     {
       title: "Wait for Job",
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-      description: "Wait for a long-running job and return the resolved result \u2014 a BOUNDED long-poll. Polls the job status (render / compose / consult / clip-suggestions / verify) and blocks up to the transport window (30s on the hosted transport); if the job is still running at the window it returns a `Still running` continuation \u2014 call wait_job again with the same arguments to keep waiting (the job keeps executing server-side; nothing is lost between calls). Call this right after compose / create_render / consult / suggest_briefs / score_composition / preview_component. For event-driven fan-out, create_webhook delivers the terminal instead.",
+      description: "Wait for a long-running job and return the resolved result \u2014 a BOUNDED long-poll. Polls job status (media import/generation / render / compose / consult / clip-suggestions / verify / preview-frame) and blocks up to the transport window (30s on the hosted transport); if still running, it returns a continuation \u2014 call wait_job again with the same arguments (the job keeps executing server-side). Call this after import_media / generate_media / finalize_upload / import_resource / compose / create_render / consult / suggest_briefs / score_composition / preview_frame / preview_component. For event-driven fan-out, create_webhook delivers the terminal instead.",
       inputSchema: {
-        kind: z.enum(["render", "suggestions", "compose", "verify", "preview", "brand_kit_extract", "consult"]).describe("What to wait on: a render job, a compose job, a consult advisory, AI clip-suggestion analysis, or a generic async job (verify / preview / brand-kit extract \u2014 the kind is named in the enqueue receipt)."),
-        id: z.string().describe('kind="render": renderId. kind="compose": composeJobId. kind="consult": the consultJobId from the consult receipt (surfaces the advisory envelope \u2014 assessment, proposals, principles). kind="suggestions": mediaItemId. kind="verify"/"preview"/"brand_kit_extract": the jobId from the enqueue receipt.'),
+        kind: z.enum(["media", "render", "suggestions", "compose", "verify", "preview_frame", "preview", "brand_kit_extract", "consult"]).describe("What to wait on: media ingest/generation, render, compose, consult, clip-suggestion analysis, or a generic async job (verify / preview_frame / preview / brand-kit extract \u2014 use the enqueue receipt kind)."),
+        id: z.string().describe('kind="media": mediaItemId returned by import/generate/finalize/import_resource. kind="render": renderId. kind="compose": composeJobId. kind="consult": consultJobId. kind="suggestions": mediaItemId. Generic kinds use the jobId from the enqueue receipt.'),
         projectId: z.string().optional().describe('Required when kind="render", "compose", or "consult".'),
         timeoutMs: z.number().int().min(1e3).max(30 * 60 * 1e3).optional().describe("Maximum wait in ms (default 30 min for render/compose, 5 min for suggestions).")
       }
@@ -542,7 +553,7 @@ function registerWaitJob(server, ex, waitCapMs, onEvent) {
       if ((kind === "render" || kind === "compose" || kind === "consult") && !args.projectId) {
         return errText(`wait_job(kind="${kind}") requires a projectId.`);
       }
-      const defaultCap = kind === "suggestions" ? 5 * 60 * 1e3 : 30 * 60 * 1e3;
+      const defaultCap = kind === "suggestions" || kind === "media" ? 5 * 60 * 1e3 : 30 * 60 * 1e3;
       const requested = args.timeoutMs ?? defaultCap;
       const deadline = Date.now() + (waitCapMs ? Math.min(requested, waitCapMs) : requested);
       const res = await waitForJob(ex, kind, args.id, args.projectId, deadline);

package/dist/{chunk-TPA6PYN2.js → chunk-ZBRPF6GV.js}

@@ -2,7 +2,7 @@ import {
   COMPOSE_PLANNER_TOOLS,
   COMPOSE_ROLE_TOOLS,
   dispatchComposeRoleTool
-} from "./chunk-BZZTVOGG.js";
+} from "./chunk-D2EGO543.js";
 
 // ../authoring/src/agent/buildTools.ts
 import { tool } from "ai";
@@ -135,6 +135,22 @@ var buildPlannerTools = (p) => {
 
 // ../authoring/src/agent/errors.ts
 import { APICallError, TypeValidationError } from "ai";
+var BODY_EXCERPT = 200;
+function providerMessage(responseBody) {
+  if (!responseBody) return void 0;
+  try {
+    const body = JSON.parse(responseBody);
+    const msg = body?.error?.message ?? body?.message;
+    return msg == null ? void 0 : String(msg);
+  } catch {
+    return void 0;
+  }
+}
+function bodyExcerpt(responseBody) {
+  const trimmed = responseBody?.trim();
+  if (!trimmed) return void 0;
+  return trimmed.replace(/\s+/g, " ").slice(0, BODY_EXCERPT);
+}
 function extractProviderError(err) {
   if (APICallError.isInstance(err)) {
     const status = err.statusCode;
@@ -144,17 +160,16 @@ function extractProviderError(err) {
     if (status === 429) {
       return "API rate limit or quota exceeded. Try again later.";
     }
+    const detail = providerMessage(err.responseBody);
     if (status === 413 || status === 400) {
-      if (err.responseBody) {
-        try {
-          const body = JSON.parse(err.responseBody);
-          const msg = body?.error?.message ?? body?.message;
-          if (msg) return String(msg).slice(0, 200);
-        } catch {
-        }
-      }
+      if (detail) return detail.slice(0, 200);
     }
-    return err.message.slice(0, 300);
+    const where = status === void 0 ? "" : ` (HTTP ${status})`;
+    const evidence = detail ?? bodyExcerpt(err.responseBody);
+    return (evidence ? `${err.message}${where}: ${evidence}` : `${err.message}${where}`).slice(
+      0,
+      300
+    );
   }
   if (TypeValidationError.isInstance(err)) {
     return "Invalid response from AI provider. The provider may be misconfigured or unavailable.";