@cueframe/kernel 0.1.1 → 0.1.3

package/dist/{chunk-ZWMV6DD2.js → chunk-ICSZF37W.js}

@@ -3,15 +3,13 @@ import {
 } from "./chunk-KYRDKK2D.js";
 import {
   Composition
-} from "./chunk-PODIYN2K.js";
+} from "./chunk-WZH57M53.js";
 
-// ../composition/src/ops/compositionOps.ts
+// ../composition/src/ops/compositionOps.shared.ts
 function findOrCreateTrackByKind(composition, kind) {
   const existing = composition.tracks.find((t) => t.kind === kind);
   if (existing) return existing;
   const track = {
-    // UUID suffix avoids id collisions when a track of `kind` is created,
-    // deleted, then re-created at the same `tracks.length` index.
     id: `track-${kind}-${crypto.randomUUID().slice(0, 8)}`,
     kind,
     contents: []
@@ -71,8 +69,11 @@ function cutTimedRange(start, end, cutStart, cutEnd) {
 }
 function shiftTimedRange(start, end, from, amount) {
   if (start < from) return null;
-  const s = Math.max(0, start + amount);
-  return { start: s, end: end !== void 0 ? Math.max(s, end + amount) : void 0 };
+  const shiftedStart = Math.max(0, start + amount);
+  return {
+    start: shiftedStart,
+    end: end !== void 0 ? Math.max(shiftedStart, end + amount) : void 0
+  };
 }
 function selectionPatch(composition, entities) {
   const clipIds = entities.filter((e) => e.kind === "clip").map((e) => e.clipId);
@@ -91,16 +92,17 @@ function selectionPatch(composition, entities) {
 }
 function pruneSelectionInDraft(draft, removedClipIds) {
   const kept = draft.selection.filter(
-    (e) => !("clipId" in e) || !removedClipIds.has(e.clipId)
+    (entity) => !("clipId" in entity) || !removedClipIds.has(entity.clipId)
   );
   const patch = selectionPatch(draft.composition, kept);
   draft.selection = patch.selection;
   draft.selectedClipId = patch.selectedClipId;
   draft.selectedOverlayId = patch.selectedOverlayId;
 }
+
+// ../composition/src/ops/compositionOps.ts
 function createCompositionOps(get, set) {
   return {
-    // ── Clip operations ──
     addClip: (clip, options) => {
       set((draft) => {
         if (options?.newTrack) {
@@ -116,18 +118,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    /**
-     * Family-routed clip add — the single primitive behind the consolidated
-     * `clip.add` op (@cueframe/composition-ops). Routes a clip onto a track of
-     * the resolved FAMILY: either an existing track pinned by `trackId`, or a
-     * track of `kind` (created if absent, optionally with a pinned `newTrackId`
-     * for byte-faithful op-replay). Replaces the three family-specific adders
-     * (addClip/addOverlay/addAudioClip) at the OP layer — those stay for the
-     * editor's direct calls.
-     *
-     * Fails LOUD if `trackId` names a missing track, or a track of a DIFFERENT
-     * family (a clip must land on its own family — never silently mis-route).
-     */
     addClipToTrack: (clip, target) => {
       set((draft) => {
         if ("trackId" in target) {
@@ -181,7 +171,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    /** Remove every clip whose `source.mediaId === mediaId`. */
     removeClipsByMediaId: (mediaId) => {
       set((draft) => {
         const removed = /* @__PURE__ */ new Set();
@@ -217,7 +206,6 @@ function createCompositionOps(get, set) {
         );
       }
     },
-    /** Replace the whole selection. The multi-select entry point. */
     setSelection: (entities) => {
       const composition = get().composition;
       const live = entities.filter(
@@ -225,7 +213,6 @@ function createCompositionOps(get, set) {
       );
       set(selectionPatch(composition, expandToLinkGroup(composition, live)));
     },
-    /** Every clip on the timeline, in track then start order. */
     selectAllClips: () => {
       const composition = get().composition;
       const entities = [];
@@ -290,18 +277,6 @@ function createCompositionOps(get, set) {
       });
       return { rippled: rateChange ? rateChange.delta !== 0 : false };
     },
-    // ── Overlay operations (TimelineClips on kind:'overlay' tracks) ──
-    // GUARD AT THE WRITE. An overlay source without a `primitiveId` is not a clip — it is a
-    // hole that renders as `unknown overlay primitive 'undefined'`, and the RENDERER was the
-    // first thing to notice it (2026-07-13: every capture_frames of a live compose died on
-    // this, the author went blind, and it landed zero graphics on a 90s customer pitch).
-    //
-    // `primitiveId: z.string().min(1)` is ALREADY required by the composition validator — but
-    // the in-loop capture path renders the in-memory store and never validates it, so the
-    // schema never ran. Refuse at the write instead, where the caller is still on the stack and
-    // the message can name it. (Same reasoning as compositionRender's `custom`-with-no-
-    // sourceCode guard, which patched one instance of this at the render boundary; this closes
-    // the class.)
     addOverlay: (clip) => {
       if (clip.source.kind === "overlay" && !clip.source.primitiveId) {
         throw new Error(
@@ -358,10 +333,6 @@ function createCompositionOps(get, set) {
       });
       set(selectionPatch(composition, kept));
     },
-    /**
-     * (see addOverlay's guard) Replace all overlays — clears existing overlay tracks, creates
-     * one with provided clips.
-     */
     loadOverlays: (clips) => {
       set((draft) => {
         draft.composition.tracks = draft.composition.tracks.filter((t) => t.kind !== "overlay");
@@ -375,7 +346,6 @@ function createCompositionOps(get, set) {
         draft.selectedOverlayId = null;
       });
     },
-    // ── Audio operations (TimelineClips on kind:'audio' tracks) ──
     addAudioClip: (clip) => {
       set((draft) => {
         const track = findOrCreateTrackByKind(draft.composition, "audio");
@@ -408,7 +378,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── Marker operations ──
     addMarker: (marker) => {
       set((draft) => {
         if (!draft.composition.markers) draft.composition.markers = [];
@@ -428,7 +397,6 @@ function createCompositionOps(get, set) {
         if (m) Object.assign(m, updates);
       });
     },
-    // ── cutAndRipple (replaces v1 deletedRanges) ──
     cutAndRipple: (start, end) => {
       if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end) return;
       const span = end - start;
@@ -491,18 +459,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── addExcludedRange ──
-    //
-    // Marks a range of source media on a media-source clip as excluded.
-    // Atomically: clamps to the clip's `trim` window, merges/coalesces with
-    // existing `excludedRanges` (touching ranges merge), shrinks
-    // `clip.duration` by the net delta added to Σ excluded, and ripples
-    // downstream same-track items left by that delta.
-    //
-    // Wire-shape invariant: (trim.end − trim.start) − Σexcludedrange = duration.
-    // The `trimEnd` fallback below restores trim.end from
-    // `duration + Σexcluded` when `trim` is absent — the same invariant
-    // rearranged.
     addExcludedRange: (clipId, sourceStart, sourceEnd, reason) => {
       if (!Number.isFinite(sourceStart) || !Number.isFinite(sourceEnd)) return;
       if (!(sourceEnd > sourceStart)) return;
@@ -584,12 +540,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── removeExcludedRange ──
-    //
-    // Inverse of addExcludedRange. Removes the excluded range at the given
-    // index, restores the clip's duration by the same amount, and ripples
-    // downstream same-track items right. When the resulting list is empty,
-    // drops the field entirely so the wire stays canonical.
     removeExcludedRange: (clipId, rangeIdx) => {
       set((draft) => {
         const found = findClipById(draft.composition, clipId);
@@ -615,18 +565,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── setCropIntents ──
-    //
-    // Author the camera channel (`reframe`) on a media clip. Each segment
-    // carries the canonical reframe params (focus, zoom, bias, ease) the
-    // derive math honors directly — no closed-enum framing names, no
-    // hardcoded scale constants.
-    //
-    // `null`/empty clears `reframe`; the clip then renders from the raw source.
-    //
-    // Used by the agent's `set_crop_intents` tool (name kept; the arg shape is
-    // reframe) and the desktop editor's framing timeline. Replaces the deleted
-    // subject-centric cropIntents (2026-06-14 cutover).
     setCropIntents: (clipId, segments) => {
       set((draft) => {
         const found = findClipById(draft.composition, clipId);
@@ -640,23 +578,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── setEffects ──
-    //
-    // Author a clip's EFFECT channel (`TimelineClip.effects`) — the registered
-    // effect primitives (+ params) the renderer stacks onto that clip. WHOLESALE:
-    // the array REPLACES whatever was there, and `[]` CLEARS the channel (the
-    // same set/clear shape setCropIntents has). `effects` has been in the
-    // validator — and accepted by `clip.add` — all along, but until the
-    // `setEffects` op there was no way to change it on an EXISTING clip except a
-    // whole-clip `clip.update` patch, which the op vocabulary explicitly steers
-    // callers away from (a partial `source` in that patch clobbers the source).
-    //
-    // Named EXACTLY like the wire op it records (`setEffects`) — the factory and
-    // the op vocabulary are one vocabulary, so there is no method→op rename table
-    // for the conformance guard to carry.
-    //
-    // Cross-track by id, like `updateClip` — the clip's family is irrelevant to
-    // its effect stack. Same merge shape as `updateClip(id, { effects })`.
     setEffects: (clipId, effects) => {
       set((draft) => {
         const found = findClipById(draft.composition, clipId);
@@ -668,17 +589,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── setCaptionStyle ──
-    //
-    // Apply the agent's caption STYLE overrides (font, size, color, position,
-    // emphasis treatment, …) onto the top-level `composition.captions.style` —
-    // the exact field the renderer consumes (compositionRender.ts) and the
-    // Captions primitive reads. Merge (not replace) so each `set_captions` call
-    // overrides only the fields it names and leaves the rest (and the
-    // transcript-sliced `words`) intact. Undefined fields are dropped so an
-    // omitted field never clobbers an existing one. If captions don't exist yet
-    // (style set before the transcript slice lands), create the container with
-    // empty words — the compose/insert path fills the words.
     setCaptionStyle: (style) => {
       set((draft) => {
         const clean = Object.fromEntries(
@@ -693,18 +603,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── setCaptionDepth ──
-    //
-    // Put the caption layer UNDER the speaker's silhouette, or back in front.
-    // One choice for the whole layer, not per segment, because it decides
-    // whether the SOURCE needs a matte — the $0.12/source-minute rung, and a
-    // caption layer usually spans the whole video. See `CaptionDepth` in the
-    // schema for why the 2026-06-11 front-only rule was reversed.
-    //
-    // Unlike `setCaptionStyle`, this does NOT create a caption container out of
-    // nothing. Depth on a layer with no words is a request to matte footage
-    // nobody is reading over — expensive and invisible — so a caller who has
-    // not authored captions yet gets a no-op rather than a bill.
     setCaptionDepth: (zPlane) => {
       set((draft) => {
         const existing = draft.composition.captions;
@@ -716,15 +614,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── setCaptions ──
-    //
-    // Replace the caption SEGMENTS wholesale — the words layer. Until this op,
-    // caption words were populated ONLY by the compose/from-suggestion
-    // transcript-slice lanes, so a client agent holding its own word timings
-    // (e.g. a generated VO take) had no way to author the engine caption layer
-    // (memoir v4, 2026-07-21). Segments REPLACE (not merge — word timing is one
-    // coherent document); `style`, when given, merges with setCaptionStyle
-    // semantics, and an omitted style keeps the existing one.
     setCaptions: (segments, style, derivedFrom) => {
       set((draft) => {
         const existing = draft.composition.captions;
@@ -736,7 +625,6 @@ function createCompositionOps(get, set) {
         draft.composition.captions = derivedFrom ? { source: "derived", from: derivedFrom, segments, ...styleField } : { source: "authored", segments, ...styleField };
       });
     },
-    // ── ripple ──
     ripple: (time, amount) => {
       set((draft) => {
         for (const track of draft.composition.tracks) {
@@ -770,15 +658,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    // ── Canvas / format ──
-    //
-    // Patches `composition.format` — `aspectRatio` is required (the field
-    // has no default), `fps`, `resolution`, and `platform` fall back to the
-    // existing values on the wire. Clip start/duration values are not retimed:
-    // a 30→60 fps switch keeps the same wall-clock seconds. Layout-sensitive
-    // overlays may need re-rendering by the caller after a switch. `platform`
-    // is output-determining (safe-zone placement) — carry it forward so an
-    // aspect-only change never silently erases it.
     setFormat: (next) => {
       set((draft) => {
         const prev = draft.composition.format;
@@ -790,18 +669,6 @@ function createCompositionOps(get, set) {
         };
       });
     },
-    // ── Track operations ──
-    //
-    // Capability parity: the cloud agent must be able to do everything the
-    // editor can (these were previously editor-only, in
-    // apps/studio/src/store/compositionStore/compositionOps.ts). They are pure
-    // `set` mutations over `composition.tracks` + the selection fields already
-    // on `CompositionOpsState`, so they live in core unchanged. The agent's
-    // tool layer can now surface them; the editor keeps calling the same names.
-    /**
-     * Append a new track of `kind` to `composition.tracks`. If `id` is omitted
-     * a UUID-suffixed id is generated (matches `findOrCreateTrackByKind`).
-     */
     addTrack: (kind, name, id) => {
       set((draft) => {
         const track = {
@@ -813,7 +680,6 @@ function createCompositionOps(get, set) {
         draft.composition.tracks.push(track);
       });
     },
-    /** Remove a track and any clip selection that references its contents. */
     removeTrack: (trackId) => {
       set((draft) => {
         const idx = draft.composition.tracks.findIndex((t) => t.id === trackId);
@@ -829,7 +695,6 @@ function createCompositionOps(get, set) {
         draft.composition.tracks.splice(idx, 1);
       });
     },
-    /** Patch a track's `name` / `enabled`. */
     updateTrack: (trackId, updates) => {
       set((draft) => {
         const track = draft.composition.tracks.find((t) => t.id === trackId);
@@ -841,7 +706,6 @@ function createCompositionOps(get, set) {
         }
       });
     },
-    /** Move a track from `fromIndex` to `toIndex` within `composition.tracks`. */
     reorderTracks: (fromIndex, toIndex) => {
       set((draft) => {
         const len = draft.composition.tracks.length;
@@ -852,14 +716,6 @@ function createCompositionOps(get, set) {
         draft.composition.tracks.splice(clamped, 0, moved);
       });
     },
-    /**
-     * Move a clip to a different track, optionally updating its startTime.
-     *
-     * The op trusts callers to validate kind-compatibility and overlap; the
-     * Fabric drag handler is responsible for snapping back when invalid. No-op
-     * if the clip isn't found, the target track doesn't exist, or target ===
-     * source. Selection stays put (the clip id is unchanged).
-     */
     moveClipToTrack: (clipId, targetTrackId, newStartTime) => {
       set((draft) => {
         let sourceTrack;
@@ -883,11 +739,6 @@ function createCompositionOps(get, set) {
         target.contents.sort((a, b) => a.startTime - b.startTime);
       });
     },
-    /**
-     * Duplicate a clip. The copy receives a new id and is appended to the same
-     * track immediately after the original's `[startTime + duration]` (nudged
-     * forward to avoid overlap with whatever follows).
-     */
     duplicateClip: (id) => {
       let newId;
       set((draft) => {
@@ -1063,9 +914,6 @@ function mergeTimelineTranscripts(clips, transcripts) {
         timelineStart: clip.startTime + (segment.startTime - trimStart) / rate,
         timelineEnd: clip.startTime + (clampedEnd - trimStart) / rate,
         clipId: clip.id,
-        // The v1 TimelineWord field is named `poolItemId`; v2 calls it
-        // `mediaId`. Same semantic — retain v1 name on the wire so the
-        // agent context (which reads `word.poolItemId`) keeps working.
         poolItemId: mediaId,
         sourceStart: segment.startTime,
         sourceEnd: clampedEnd,

package/dist/chunk-IEXAKOEX.js

@@ -0,0 +1,113 @@
+import {
+  EntityId,
+  ISODateTime,
+  NonEmptyString
+} from "./chunk-XELS2BGA.js";
+
+// ../data-models/account-model/src/validators/userSettings.ts
+import { z } from "zod";
+var UserSettings = z.object({
+  id: EntityId("userSettings"),
+  userId: NonEmptyString,
+  enableUnderstanding: z.boolean().optional(),
+  activeBrandKitId: EntityId("brandKits").optional()
+});
+
+// ../data-models/account-model/src/validators/conversation.ts
+import { z as z2 } from "zod";
+var ConversationProject = z2.object({
+  id: NonEmptyString,
+  home: z2.enum(["local", "cloud"])
+});
+var Conversation = z2.object({
+  id: EntityId("conversations"),
+  clientId: NonEmptyString,
+  userId: NonEmptyString,
+  title: NonEmptyString,
+  project: ConversationProject.optional(),
+  createdAt: ISODateTime,
+  updatedAt: ISODateTime,
+  messages: z2.string()
+});
+
+// ../data-models/account-model/src/validators/uploadToken.ts
+import { z as z3 } from "zod";
+var UploadTokenScope = z3.enum(["tus", "companion"]);
+var UploadToken = z3.object({
+  id: EntityId("uploadTokens"),
+  token: NonEmptyString,
+  userId: NonEmptyString,
+  projectId: EntityId("projects").optional(),
+  orgId: NonEmptyString.optional(),
+  scope: UploadTokenScope.optional(),
+  expiresAt: ISODateTime
+});
+
+// ../data-models/account-model/src/validators/contextFile.ts
+import { z as z4 } from "zod";
+var ContextFile = z4.object({
+  id: EntityId("contextFiles"),
+  orgId: NonEmptyString,
+  userId: NonEmptyString,
+  filename: NonEmptyString,
+  content: z4.string(),
+  generatedFrom: z4.array(NonEmptyString),
+  version: z4.number().int().nonnegative(),
+  updatedAt: ISODateTime
+});
+
+// ../data-models/account-model/src/validators/dashboardInsight.ts
+import { z as z5 } from "zod";
+var DashboardInsight = z5.object({
+  id: EntityId("dashboardInsights"),
+  orgId: NonEmptyString,
+  sourceHash: NonEmptyString,
+  heroInsight: NonEmptyString,
+  contentSuggestions: z5.array(NonEmptyString),
+  generatedAt: ISODateTime
+});
+
+// ../data-models/account-model/src/validators/sessionToken.ts
+import { z as z6 } from "zod";
+var SessionTokenScope = z6.enum(["session-read"]);
+var SessionToken = z6.object({
+  id: EntityId("sessionTokens"),
+  token: NonEmptyString,
+  sessionId: NonEmptyString,
+  projectId: EntityId("projects"),
+  orgId: NonEmptyString,
+  scope: SessionTokenScope,
+  expiresAt: ISODateTime,
+  sandboxId: NonEmptyString.optional(),
+  readyAt: z6.number().optional(),
+  scheduledCloseId: NonEmptyString.optional(),
+  scratchCompositionId: EntityId("compositions").optional(),
+  managed: z6.boolean().optional(),
+  leaseJobId: NonEmptyString.optional(),
+  leaseExpiresAt: z6.number().optional()
+});
+
+// ../data-models/account-model/src/validators/workingComposition.ts
+import { z as z7 } from "zod";
+var WorkingComposition = z7.object({
+  id: EntityId("workingCompositions"),
+  sessionId: NonEmptyString,
+  projectId: EntityId("projects"),
+  orgId: NonEmptyString,
+  composition: z7.unknown(),
+  version: z7.number(),
+  updatedAt: z7.number()
+});
+
+export {
+  UserSettings,
+  ConversationProject,
+  Conversation,
+  UploadTokenScope,
+  UploadToken,
+  ContextFile,
+  DashboardInsight,
+  SessionTokenScope,
+  SessionToken,
+  WorkingComposition
+};

package/dist/{chunk-RF7U3SCL.js → chunk-KFECIHED.js}

@@ -1,6 +1,6 @@
 import {
   waitForJob
-} from "./chunk-MMEJ3Y7E.js";
+} from "./chunk-SDCEJAO2.js";
 import {
   GENERATED_OPERATIONS,
   apiErrorFrom,
@@ -17,10 +17,10 @@ import {
   sniffImageMediaType,
   text,
   withMedia
-} from "./chunk-SIGGQRY2.js";
+} from "./chunk-DL7WYISQ.js";
 import {
   CURATED_TOOLS
-} from "./chunk-HI4UTTPS.js";
+} from "./chunk-DJW3UGBH.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",
     {
@@ -476,9 +480,6 @@ function registerPreviewCard(server, ex, onEvent) {
         tokens: z.record(z.string()).optional().describe("Token substitutions the html references (e.g. brand colours, fonts). Same shape as the clip source `tokens`."),
         aspectRatio: z.enum(["16:9", "9:16", "1:1", "4:5"]).optional().describe("Frame to size the card into. Default 9:16 \u2014 a card that fits 16:9 often overflows vertical.")
       },
-      // Renders inline and persists nothing — the read-only stance curation.ts
-      // already takes for preview_frame. Stated in full: an omitted hint is not
-      // neutral (destructiveHint/openWorldHint default TRUE in the schema).
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async (args, extra) => timed(onEvent, "preview_card", async (report) => {
@@ -511,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);
           }
         );
@@ -531,13 +539,11 @@ function registerWaitJob(server, ex, waitCapMs, onEvent) {
     "wait_job",
     {
       title: "Wait for Job",
-      // Polls status; changes nothing. Idempotent by construction — the whole
-      // continuation contract is "call again with the same arguments".
       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).")
       }
@@ -547,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);
@@ -583,9 +589,6 @@ function registerBurnedTombstones(server, onEvent) {
       {
         title: `${titleCase(b.name)} (retired)`,
         description: `RETIRED (2026-07 verb cutover) \u2014 use ${b.replacement}. ${b.reason}`,
-        // A tombstone only ever throws. Announcing it as read-only and
-        // closed-world keeps a stale agent from being made to confirm a
-        // "destructive" call that does nothing (schema defaults both to true).
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
       },
       async () => timed(onEvent, b.name, async () => errText(burnedNameError(b)))