@cueframe/kernel 0.2.22 → 0.2.24

package/dist/{chunk-PRSRV7AT.js → chunk-TE3PNQG6.js}

@@ -43,14 +43,14 @@ import {
   makeDefaultScreenTexture,
   resolveCamera,
   useImageTexture
-} from "./chunk-DEDZKZ6G.js";
+} from "./chunk-JBWSK2YD.js";
 import {
   DEVICE_GLASS_OPACITY_ENCODED,
   DeviceMesh,
   StudioRig,
   deviceDimensions,
   laptopLayout
-} from "./chunk-TZ7DKL2G.js";
+} from "./chunk-OBA6NW4S.js";
 
 // ../execution/primitives/src/scenes/changelog-bite/index.tsx
 import {

package/dist/{chunk-WLU5XPDG.js → chunk-TXI53LIT.js}

@@ -3,7 +3,7 @@ import {
   assertSceneShotParamsAdmitted,
   materializeComponentSource,
   renderComponentAlpha
-} from "./chunk-CDZBSLVA.js";
+} from "./chunk-H5CPILOK.js";
 import {
   componentArtifactId,
   componentBundleId,
@@ -16,7 +16,7 @@ import {
 } from "./chunk-WXHD6OUT.js";
 import {
   resolvedComponentRenderer
-} from "./chunk-VDSO2KZY.js";
+} from "./chunk-5BAWOULP.js";
 import {
   ComponentBakeJobV2,
   ComponentBakeRequestV2,

package/dist/{chunk-LD4XQQRL.js → chunk-WAUVKF2F.js}

@@ -26,7 +26,7 @@ import {
   perspectiveFor,
   resolveCamera,
   useStage
-} from "./chunk-DEDZKZ6G.js";
+} from "./chunk-JBWSK2YD.js";
 
 // ../execution/primitives/src/effects/blur/index.tsx
 import React2 from "react";

package/dist/{chunk-7YL7NJJF.js → chunk-XACXNDFL.js}

@@ -1302,6 +1302,10 @@ function evaluateScene(spec2, requestedFrame, durationInFrames) {
 
 // ../composition/src/scene/clipRules.ts
 import { ZodError } from "zod";
+var SCENE_SLOT_MEDIA_FORMATS = {
+  image: "PNG, JPEG or WebP",
+  video: "MP4 or WebM"
+};
 function slotOwner(spec2, slot) {
   const find = (layers) => {
     for (const layer of layers) {
@@ -1429,7 +1433,7 @@ function bindingIssues(spec2, assets, path, mediaKindById) {
     } else if (kind !== slots.get(name)) {
       issues.push({
         path: `${path}.${name}`,
-        detail: `slot '${name}' needs ${slots.get(name)} media (${slots.get(name) === "image" ? "PNG, JPEG or WebP" : "MP4 or WebM"}); '${mediaId}' is ${kind}.`,
+        detail: `slot '${name}' needs ${slots.get(name)} media (${slots.get(name) === "image" ? SCENE_SLOT_MEDIA_FORMATS.image : SCENE_SLOT_MEDIA_FORMATS.video}); '${mediaId}' is ${kind}.`,
         code: "validation_error"
       });
     }
@@ -3450,6 +3454,7 @@ export {
   evaluateChannel,
   sceneTransformMatrix,
   evaluateScene,
+  SCENE_SLOT_MEDIA_FORMATS,
   isSceneShotSource,
   readSceneSourceRef,
   isTimelineClip,

package/dist/component-runtime/browserOptions.js

@@ -4,9 +4,9 @@ import {
   componentBrowserOptions,
   resolvedComponentRenderer,
   webglBackend
-} from "../chunk-VDSO2KZY.js";
+} from "../chunk-5BAWOULP.js";
 import "../chunk-ZVG446DJ.js";
-import "../chunk-7YL7NJJF.js";
+import "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/component-runtime/render.js

@@ -26,14 +26,14 @@ import {
   stagedBrowserLocator,
   verifyLocalStagedBrowser,
   vp9AlphaFfmpegOverride
-} from "../chunk-CDZBSLVA.js";
+} from "../chunk-H5CPILOK.js";
 import "../chunk-WB2VFDQZ.js";
 import "../chunk-EXY4JJPH.js";
 import "../chunk-DAARYRNT.js";
 import "../chunk-5NGYBI5Z.js";
-import "../chunk-VDSO2KZY.js";
+import "../chunk-5BAWOULP.js";
 import "../chunk-ZVG446DJ.js";
-import "../chunk-7YL7NJJF.js";
+import "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-AVTEPAWI.js";
 import "../chunk-2ESYSVXG.js";

package/dist/component-runtime.js

@@ -7,7 +7,7 @@ import {
   sourceIdentityForBake,
   startComponentAssetServer,
   verifyComponentOutput
-} from "./chunk-WLU5XPDG.js";
+} from "./chunk-TXI53LIT.js";
 import {
   COMPONENT_MEDIA_HEADROOM,
   COMPONENT_MEDIA_TIERS,
@@ -52,7 +52,7 @@ import {
   stagedBrowserLocator,
   verifyLocalStagedBrowser,
   vp9AlphaFfmpegOverride
-} from "./chunk-CDZBSLVA.js";
+} from "./chunk-H5CPILOK.js";
 import "./chunk-WB2VFDQZ.js";
 import {
   bundleIdentityFields,
@@ -86,7 +86,7 @@ import {
   resolvedComponentRenderer,
   webGlRefusal,
   webglBackend
-} from "./chunk-VDSO2KZY.js";
+} from "./chunk-5BAWOULP.js";
 import {
   CANVAS2D_COMPONENT_MANIFEST_V2,
   COMPONENT_BUNDLE_VERSION,
@@ -127,7 +127,7 @@ import {
   authoredComponentProps,
   readComponentSourceRef
 } from "./chunk-ZVG446DJ.js";
-import "./chunk-7YL7NJJF.js";
+import "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";

package/dist/compose.js

@@ -7,10 +7,10 @@ import "./chunk-ZZRBKGDA.js";
 import "./chunk-GULDS3VE.js";
 import {
   catalog as catalog4
-} from "./chunk-YV5AYMNK.js";
+} from "./chunk-JRJQECCF.js";
 import {
   catalog as catalog7
-} from "./chunk-PRSRV7AT.js";
+} from "./chunk-TE3PNQG6.js";
 import {
   catalog
 } from "./chunk-ZS3A3QUM.js";
@@ -30,7 +30,7 @@ import {
 } from "./chunk-RAXHCRVV.js";
 import {
   catalog as catalog2
-} from "./chunk-LD4XQQRL.js";
+} from "./chunk-WAUVKF2F.js";
 import "./chunk-MFHXCHRI.js";
 import {
   catalog as catalog8
@@ -40,8 +40,8 @@ import "./chunk-FWSJLHSV.js";
 import "./chunk-ZFEXATWN.js";
 import "./chunk-XHGZ2E77.js";
 import "./chunk-W2245F6G.js";
-import "./chunk-DEDZKZ6G.js";
-import "./chunk-TZ7DKL2G.js";
+import "./chunk-JBWSK2YD.js";
+import "./chunk-OBA6NW4S.js";
 import {
   getPrimitiveSubtextParam,
   getPrimitiveText,
@@ -56,7 +56,7 @@ import {
   encodeError
 } from "./chunk-QWXUYVHX.js";
 import "./chunk-7PA7FGLD.js";
-import "./chunk-7YL7NJJF.js";
+import "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";

package/dist/composition/scene.js

@@ -41,6 +41,7 @@ import {
   SCENE_SLAB_BODY_TRIANGLES,
   SCENE_SLAB_CONTENT_FACE_TRIANGLES,
   SCENE_SLAB_CONTENT_OFFSET,
+  SCENE_SLOT_MEDIA_FORMATS,
   SCENE_TESSELLATION_VERSION,
   SCENE_TRANSITION_KINDS,
   SCENE_WORLD_OBJECT_PROPERTIES,
@@ -129,7 +130,7 @@ import {
   selectSceneBakeScale,
   verifySceneVideoPresentationIndexV1,
   verifySealedSceneShotPlanV1
-} from "../chunk-7YL7NJJF.js";
+} from "../chunk-XACXNDFL.js";
 import {
   MIB,
   SCENE_CONTEXT_GL_BUDGET_BYTES,
@@ -185,6 +186,7 @@ export {
   SCENE_SLAB_BODY_TRIANGLES,
   SCENE_SLAB_CONTENT_FACE_TRIANGLES,
   SCENE_SLAB_CONTENT_OFFSET,
+  SCENE_SLOT_MEDIA_FORMATS,
   SCENE_SURFACE_TEXTURE_BUDGET_BYTES,
   SCENE_TESSELLATION_VERSION,
   SCENE_TRANSITION_KINDS,

package/dist/composition-ops.js

@@ -1,6 +1,6 @@
 import {
   playableSpans
-} from "./chunk-PQDALM2G.js";
+} from "./chunk-JNQKX4OI.js";
 import "./chunk-QH3YI3ND.js";
 import "./chunk-QISFYLBB.js";
 import "./chunk-K4VE64CR.js";
@@ -33,8 +33,9 @@ import "./chunk-WREYUH2E.js";
 import "./chunk-QWXUYVHX.js";
 import "./chunk-7PA7FGLD.js";
 import {
+  SCENE_SLOT_MEDIA_FORMATS,
   SceneShotSpecV2
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import {
   introducedCaptionFaceIssues
@@ -490,20 +491,48 @@ function resolveClipKind(clip, track) {
   return resolved;
 }
 var CompositionOp = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("clip.add"), clip: TimelineClip, trackId: z.string().optional(), newTrack: z.boolean().optional(), newTrackId: z.string().optional() }).strict(),
-  z.object({ type: z.literal("clip.remove"), clipId: z.string() }).strict(),
-  z.object({ type: z.literal("clip.update"), clipId: z.string(), patch: TimelineClip.partial() }).strict(),
-  z.object({ type: z.literal("removeClipsByMediaId"), mediaId: z.string() }).strict(),
-  z.object({ type: z.literal("loadOverlays"), clips: z.array(TimelineClip) }).strict(),
-  z.object({ type: z.literal("addMarker"), marker: Marker }).strict(),
-  z.object({ type: z.literal("removeMarker"), markerId: z.string() }).strict(),
-  z.object({ type: z.literal("updateMarker"), markerId: z.string(), updates: Marker.partial() }).strict(),
-  z.object({ type: z.literal("setCropIntents"), clipId: z.string(), segments: z.array(ReframeSegment).nullable() }).strict(),
-  z.object({ type: z.literal("setEffects"), clipId: z.string(), effects: z.array(PerClipEffect) }).strict(),
-  z.object({ type: z.literal("setCaptionStyle"), style: CaptionStyle.partial() }).strict(),
-  z.object({ type: z.literal("setCaptionDepth"), zPlane: z.enum(["front", "behind-subject"]) }).strict(),
-  z.object({ type: z.literal("setCaptions"), segments: z.array(CaptionSegment), style: CaptionStyle.partial().optional() }).strict(),
-  z.object({ type: z.literal("applyMotionPreset"), clipId: z.string(), preset: z.string(), params: z.object({ enterMs: z.number().optional(), exitMs: z.number().optional(), staggerMs: z.number().optional() }).strict().optional() }).strict(),
+  z.object({ type: z.literal("clip.add"), clip: TimelineClip, trackId: z.string().optional(), newTrack: z.boolean().optional(), newTrackId: z.string().optional() }).strict().describe(
+    "Add a clip to the timeline. The clip self-routes to a track by FAMILY (`clip.kind`, else derived from `source.kind`, else the target track) \u2014 a `media` clip MUST carry `kind` (video|audio|image) or a `trackId`, else it is rejected as ambiguous. `trackId` targets an existing SAME-family track; `newTrack:true` (with optional pinned `newTrackId`) creates a fresh track of that family."
+  ),
+  z.object({ type: z.literal("clip.remove"), clipId: z.string() }).strict().describe(
+    "Remove a clip by id (located across every track)."
+  ),
+  z.object({ type: z.literal("clip.update"), clipId: z.string(), patch: TimelineClip.partial() }).strict().describe(
+    "Patch an existing clip by id (cross-family). The patch is a partial TimelineClip. NOTE: `source` is REPLACED wholesale \u2014 the patch merges at the top level only, so a partial `source` WIPES the source fields you omit. Patch the whole source object when changing it. (To change reframe/excluded ranges, prefer setCropIntents / addExcludedRange, not a source patch.)"
+  ),
+  z.object({ type: z.literal("removeClipsByMediaId"), mediaId: z.string() }).strict().describe(
+    "Remove EVERY clip sourced from a given mediaId (e.g. after deleting that media)."
+  ),
+  z.object({ type: z.literal("loadOverlays"), clips: z.array(TimelineClip) }).strict().describe(
+    "Replace the overlay channel wholesale with the given clips (bulk set, not a merge)."
+  ),
+  z.object({ type: z.literal("addMarker"), marker: Marker }).strict().describe(
+    "Add a timeline marker (a named time point/range; carry extensions in `metadata`)."
+  ),
+  z.object({ type: z.literal("removeMarker"), markerId: z.string() }).strict().describe(
+    "Remove a marker by id."
+  ),
+  z.object({ type: z.literal("updateMarker"), markerId: z.string(), updates: Marker.partial() }).strict().describe(
+    "Patch a marker's fields by id (partial merge)."
+  ),
+  z.object({ type: z.literal("setCropIntents"), clipId: z.string(), segments: z.array(ReframeSegment).nullable() }).strict().describe(
+    "Set (or CLEAR, with `segments: null`) the camera/reframe channel on a MEDIA clip \u2014 the time-aligned source\u2192output viewport (focus, zoom, ease, bias). This is the PREFERRED way to author reframing; do NOT reframe via a whole-source `clip.update` patch. Segments tile the clip's duration."
+  ),
+  z.object({ type: z.literal("setEffects"), clipId: z.string(), effects: z.array(PerClipEffect) }).strict().describe(
+    "Set (or CLEAR, with `effects: []`) a clip's EFFECT channel \u2014 the registered effect primitives stacked onto that clip, each `{ primitiveId, params? }`. WHOLESALE: the array REPLACES the clip's current effects, so send the full stack (read the clip first to add one). This is the ONLY way to change effects on an existing clip \u2014 do NOT reach for a `clip.update` patch, whose top-level merge is the source-clobbering footgun documented above."
+  ),
+  z.object({ type: z.literal("setCaptionStyle"), style: CaptionStyle.partial() }).strict().describe(
+    "Merge style overrides (font/color/position/emphasis) onto the composition's caption layer. Partial \u2014 omitted fields keep their current value; creates the caption container if absent."
+  ),
+  z.object({ type: z.literal("setCaptionDepth"), zPlane: z.enum(["front", "behind-subject"]) }).strict().describe(
+    "Set the caption compositing plane. Use `behind-subject` to place captions behind the segmented foreground subject; use `front` for conventional captions above all video layers."
+  ),
+  z.object({ type: z.literal("setCaptions"), segments: z.array(CaptionSegment), style: CaptionStyle.partial().optional() }).strict().describe(
+    "Replace the caption SEGMENTS wholesale \u2014 author the word-timed caption layer directly (each segment = one sentence/page of `words` with timeline-ms `startMs`/`endMs`, optional `emphasis`). This is how a client with its OWN word timings (e.g. a generated VO take) gets word-synced captions without a source transcript; the compose lane's transcript slice writes the same layer. `style`, when given, merges with setCaptionStyle semantics; an omitted style keeps the existing one. Renderer paginates within a segment and never pools words across two \u2014 keep segments sentence-bounded."
+  ),
+  z.object({ type: z.literal("applyMotionPreset"), clipId: z.string(), preset: z.string(), params: z.object({ enterMs: z.number().optional(), exitMs: z.number().optional(), staggerMs: z.number().optional() }).strict().optional() }).strict().describe(
+    "Shell a STATIC `card` clip with a frame-driven MOTION preset \u2014 the public card-shelling op (the layout renders VERBATIM; only the container animates in/out). The server wraps the card in the chosen `preset` (fade-up / slide-in-left / slide-in-right / scale-pop / stagger-reveal), transpiles it, mints it as a LIVE component, and swaps the clip source to that component (the bakeless live lane \u2014 no box). `params` tunes timing (`enterMs`/`exitMs`, `staggerMs` for stagger-reveal). The target must be a static card (components already carry motion; library overlays already move); re-run overwrites idempotently ONLY while the target is still a card (an uncompilable shell); once shelled, the clip is a COMPONENT \u2014 to change its motion, remove and re-add the card, then re-shell. Honored under `dry_run` (validates preset + target without transpiling or persisting). ORDERING: the preset resolves its target against the PERSISTED composition \u2014 a card added in the SAME batch is not yet visible to it. Persist the clip.add batch first, then shell in a following call."
+  ),
   // Scene shots (spec §"Authoring, persistence, and discovery"). Route-materialized: the host
   // registers the generated wrapper source through its component store and rewrites these to
   // addTrack / clip.add / clip.update carrying `props.componentRef`; the agent edits a scene
@@ -524,7 +553,7 @@ var CompositionOp = z.discriminatedUnion("type", [
     // Lives here, not in the published api/openapi.json. It used to exist ONLY
     // in that document, which made the contract hand-maintained and put it out
     // of reach of a scripted sync from this SSOT.
-    'Author a scene shot and place it on a dedicated overlay track. The host validates the scene, generates and registers an immutable wrapper component source, and emits the ordinary track/clip operations carrying `props.componentRef` \u2014 you edit a scene SPEC, never wrapper TSX or a source hash. Registration and the composition update are ONE undoable edit; a failure publishes nothing and leaves no clip pointing at an unresolved source. Pass EXACTLY ONE of `trackId` (an existing dedicated scene track) or `newTrack: true` (mint one). That track holds scene-shot clips and gaps only \u2014 no generic component/primitive/media clips in v1 \u2014 and existing generic overlay tracks are unaffected. Scene clips use front zPlane and full-frame placement: outer per-clip `region`, `position`, `scale`, `rotation`, `fit`, `effects`, `animate`, `params.transition`, `params.sequenceGroup` and internal fadeIn/fadeOut are REFUSED with a path, because the shot\'s own layer transforms are the single transform owner. TEXT: `space: "screen"` text is composed above the world result, stays fixed in the frame and stays sharp through focus; `space: "world"` text is rasterized into the 3D scene, moves with the camera and is occluded by geometry. Screenshots and world text are UNLIT and colour-managed so product UI colours are not tinted by the studio lighting, while device bodies are lit and cast shadows; an unlit surface still occludes. SCOPE GAP (pre-existing, neither closed nor changed by scene shots): global wrap effects \u2014 composition-level grades and camera effects \u2014 do not reach front-overlay clips, so they do not affect a scene shot. Author the look INSIDE the shot (`post.grain`, `post.vignette`, `post.focus`, `backdrop`, `environment`) instead. DISCOVERY: there is no built-in scene primitive to look up in list_catalog; the wrapper this operation registers appears afterwards as an ordinary INSTALLED component under the existing catalog rules.'
+    `Author a scene shot and place it on a dedicated overlay track. The host validates the scene, generates and registers an immutable wrapper component source, and emits the ordinary track/clip operations carrying \`props.componentRef\` \u2014 you edit a scene SPEC, never wrapper TSX or a source hash. Registration and the composition update are ONE undoable edit; a failure publishes nothing and leaves no clip pointing at an unresolved source. Pass EXACTLY ONE of \`trackId\` (an existing dedicated scene track) or \`newTrack: true\` (mint one). That track holds scene-shot clips and gaps only \u2014 no generic component/primitive/media clips in v1 \u2014 and existing generic overlay tracks are unaffected. Scene clips use front zPlane and full-frame placement: outer per-clip \`region\`, \`position\`, \`scale\`, \`rotation\`, \`fit\`, \`effects\`, \`animate\`, \`params.transition\`, \`params.sequenceGroup\` and internal fadeIn/fadeOut are REFUSED with a path, because the shot's own layer transforms are the single transform owner. TEXT: \`space: "screen"\` text is composed above the world result, stays fixed in the frame and stays sharp through focus; \`space: "world"\` text is rasterized into the 3D scene, moves with the camera and is occluded by geometry. Screenshots and world text are UNLIT and colour-managed so product UI colours are not tinted by the studio lighting, while device bodies are lit and cast shadows; an unlit surface still occludes. SCOPE GAP (pre-existing, neither closed nor changed by scene shots): global wrap effects \u2014 composition-level grades and camera effects \u2014 do not reach front-overlay clips, so they do not affect a scene shot. Author the look INSIDE the shot (\`post.grain\`, \`post.vignette\`, \`post.focus\`, \`backdrop\`, \`environment\`) instead. DISCOVERY: there is no built-in scene primitive to look up in list_catalog; the wrapper this operation registers appears afterwards as an ordinary INSTALLED component under the existing catalog rules. ASSETS: \`assets\` binds each slot name a layer references to a media id in the same project, and the slot's declared KIND decides what it admits \u2014 an image slot takes ${SCENE_SLOT_MEDIA_FORMATS.image}, a video slot ${SCENE_SLOT_MEDIA_FORMATS.video}. Binding the wrong kind is refused with the slot's path.`
   ),
   z.object({
     type: z.literal("scene.update"),
@@ -534,25 +563,53 @@ var CompositionOp = z.discriminatedUnion("type", [
     transitionIn: Transition.optional(),
     scene: SceneShotSpecV2.optional(),
     assets: SceneAssetBindings.optional()
-  }).strict().describe("Revise a scene shot in place by clip id. Send a replacement `scene` and/or `assets`; timing changes use the ordinary clip timing fields (`startTime`, `duration`, `transitionIn`). Omitted fields keep their persisted values and the MERGED result is re-validated as a whole, so a partial edit cannot leave the shot invalid. Changing only values or asset IDs updates props and bindings and REUSES the pinned source; changing the referenced SLOT SET regenerates the wrapper manifest and registers a new immutable source version atomically. Undo restores the source reference, spec, bindings and timing together. Topology, asset bindings, text content, font properties, device kind and colours are STATIC within a shot's animation \u2014 change them here (a revised spec) rather than trying to animate them. This is not a source trim or slip: a shortened or extended clip resamples the SAME normalized animation over its new duration, and trim/slip requests on generated animation are rejected rather than reinterpreted as media trims. In one batch, `scene.update` may target a shot added by an earlier `scene.add`."),
-  z.object({ type: z.literal("materializeGrid"), clipId: z.string(), grid: z.enum(["beat", "word", "shot"]), maxMarkers: z.number().int().positive().max(2e3).optional() }).strict(),
+  }).strict().describe(`Revise a scene shot in place by clip id. Send a replacement \`scene\` and/or \`assets\`; timing changes use the ordinary clip timing fields (\`startTime\`, \`duration\`, \`transitionIn\`). Omitted fields keep their persisted values and the MERGED result is re-validated as a whole, so a partial edit cannot leave the shot invalid. Changing only values or asset IDs updates props and bindings and REUSES the pinned source; changing the referenced SLOT SET regenerates the wrapper manifest and registers a new immutable source version atomically. Undo restores the source reference, spec, bindings and timing together. Topology, asset bindings, text content, font properties, device kind and colours are STATIC within a shot's animation \u2014 change them here (a revised spec) rather than trying to animate them. This is not a source trim or slip: a shortened or extended clip resamples the SAME normalized animation over its new duration, and trim/slip requests on generated animation are rejected rather than reinterpreted as media trims. In one batch, \`scene.update\` may target a shot added by an earlier \`scene.add\`. ASSETS: \`assets\` binds each slot name a layer references to a media id in the same project, and the slot's declared KIND decides what it admits \u2014 an image slot takes ${SCENE_SLOT_MEDIA_FORMATS.image}, a video slot ${SCENE_SLOT_MEDIA_FORMATS.video}. Binding the wrong kind is refused with the slot's path.`),
+  z.object({ type: z.literal("materializeGrid"), clipId: z.string(), grid: z.enum(["beat", "word", "shot"]), maxMarkers: z.number().int().positive().max(2e3).optional() }).strict().describe(
+    'Materialize a clip\'s SOURCE-media temporal GRID as timeline markers \u2014 the rhythm authority you cut to. `grid:"beat"` reads a MUSIC bed\'s beat map (get_media_context.beatGrid), `grid:"word"` the VO word onsets (wordGrid); each grid point is projected from media time to TIMELINE time through the clip\'s placement (startTime, trim, playbackRate, excludedRanges) and written as a `kind:"beat"|"word"` marker (`metadata.sourceClipId` set). Points outside the clip\'s visible window are skipped. Re-running REPLACES the prior markers from the same clip+grid (idempotent). Land cuts and transition MIDPOINTS on the markers (a 0.5s transition starts 0.25s before its marker). `maxMarkers` (default 500, ceiling 2000) \u2014 exceeding it fails loud with the count. `grid:"shot"` is not yet exposed (shot_grid_unavailable). The target must be a media clip; absent evidence fails loud (grid_unavailable) naming how to get it (declare audioRole:"music" at ingest / transcribe).'
+  ),
   z.object({
     type: z.literal("captions.fromTranscript"),
     mediaId: z.string().min(1),
     window: z.object({ startSec: z.number().min(0), endSec: z.number().positive() }).strict().optional()
-  }).strict(),
-  z.object({ type: z.literal("setFormat"), format: Format.pick({ aspectRatio: true, fps: true, resolution: true }) }).strict(),
-  z.object({ type: z.literal("addTrack"), kind: Track.shape.kind, name: z.string().optional(), id: z.string().optional() }).strict(),
-  z.object({ type: z.literal("removeTrack"), trackId: z.string() }).strict(),
-  z.object({ type: z.literal("updateTrack"), trackId: z.string(), updates: Track.pick({ name: true, enabled: true, volume: true }).partial() }).strict(),
-  z.object({ type: z.literal("reorderTracks"), fromIndex: z.number(), toIndex: z.number() }).strict(),
-  z.object({ type: z.literal("moveClipToTrack"), clipId: z.string(), targetTrackId: z.string(), newStartTime: z.number().optional() }).strict(),
-  z.object({ type: z.literal("duplicateClip"), clipId: z.string(), newClipId: z.string().optional() }).strict(),
-  z.object({ type: z.literal("cutAndRipple"), start: z.number(), end: z.number() }).strict(),
-  z.object({ type: z.literal("ripple"), time: z.number(), amount: z.number() }).strict(),
-  z.object({ type: z.literal("addExcludedRange"), clipId: z.string(), sourceStart: z.number(), sourceEnd: z.number(), reason: z.string().optional() }).strict(),
-  z.object({ type: z.literal("removeExcludedRange"), clipId: z.string(), rangeIdx: z.number() }).strict()
-]);
+  }).strict().describe(
+    "Attach caption CONTENT from the media's cached transcript \u2014 no pasting words. ROUTE-MATERIALIZED like applyMotionPreset/materializeGrid: the server slices the word-timed transcript to `window` (source seconds; absent = the whole media), rebases times, sentence-splits into segments, and applies it as `setCaptions`. 422 media_no_transcript when the media has no transcript or no words in the window. For your OWN word timings use setCaptions directly."
+  ),
+  z.object({ type: z.literal("setFormat"), format: Format.pick({ aspectRatio: true, fps: true, resolution: true }) }).strict().describe(
+    "Set the output format \u2014 `aspectRatio` (16:9|9:16|1:1|4:5) plus optional `fps` and `resolution`. Merges: an omitted field keeps the current value."
+  ),
+  z.object({ type: z.literal("addTrack"), kind: Track.shape.kind, name: z.string().optional(), id: z.string().optional() }).strict().describe(
+    "Add an EMPTY track of a given family (video|audio|image|overlay|effect). Optional pinned `id`."
+  ),
+  z.object({ type: z.literal("removeTrack"), trackId: z.string() }).strict().describe(
+    "Remove a track AND all its clips by id."
+  ),
+  z.object({ type: z.literal("updateTrack"), trackId: z.string(), updates: Track.pick({ name: true, enabled: true, volume: true }).partial() }).strict().describe(
+    "Patch a track's `name` / `enabled` by id."
+  ),
+  z.object({ type: z.literal("reorderTracks"), fromIndex: z.number(), toIndex: z.number() }).strict().describe(
+    "Move a track from one index to another (changes layer/compositing order)."
+  ),
+  z.object({ type: z.literal("moveClipToTrack"), clipId: z.string(), targetTrackId: z.string(), newStartTime: z.number().optional() }).strict().describe(
+    "Move a clip to another SAME-family track, optionally at a new `newStartTime`."
+  ),
+  z.object({ type: z.literal("duplicateClip"), clipId: z.string(), newClipId: z.string().optional() }).strict().describe(
+    "Duplicate a clip by id. Pin `newClipId` to make the copy's id deterministic (required for a clean undo/inverse)."
+  ),
+  z.object({ type: z.literal("cutAndRipple"), start: z.number(), end: z.number() }).strict().describe(
+    "Server-authoritative: delete the [start,end] time window (seconds) and ripple every downstream clip/marker/caption earlier to close the gap."
+  ),
+  z.object({ type: z.literal("ripple"), time: z.number(), amount: z.number() }).strict().describe(
+    "Server-authoritative: shift everything at/after `time` (seconds) by `amount` seconds (+ opens a gap, \u2212 closes one)."
+  ),
+  z.object({ type: z.literal("addExcludedRange"), clipId: z.string(), sourceStart: z.number(), sourceEnd: z.number(), reason: z.string().optional() }).strict().describe(
+    "Server-authoritative: exclude a [sourceStart,sourceEnd] span (seconds) of a clip's SOURCE (an internal trim) and ripple downstream \u2014 the preferred way to drop a sub-range vs a source patch."
+  ),
+  z.object({ type: z.literal("removeExcludedRange"), clipId: z.string(), rangeIdx: z.number() }).strict().describe(
+    "Server-authoritative: remove a clip's previously-added excluded range by index (re-includes that span, ripples downstream)."
+  )
+]).describe(
+  "One scoped composition operation. Discriminated by `type` \u2014 `clip.add` / `clip.remove` / `clip.update` patch clips across any family; the rest cover markers, reframe, effects, captions, format, tracks, and the server-authoritative ripple recomputes. Every variant is `.strict()`: an unknown field is refused, not ignored."
+);
 function mergedCaptionStyle(composition, patch) {
   const existing = composition.captions?.style ?? {};
   if (!patch) return existing;

package/dist/core/render.js

@@ -66,7 +66,7 @@ import {
   sliceTranscriptWords,
   splitIntoSentences,
   validateComposition
-} from "../chunk-PQDALM2G.js";
+} from "../chunk-JNQKX4OI.js";
 import {
   buildEasedZooms,
   buildPannedCenters,
@@ -80,7 +80,7 @@ import "../chunk-KYRDKK2D.js";
 import "../chunk-WREYUH2E.js";
 import "../chunk-QWXUYVHX.js";
 import "../chunk-7PA7FGLD.js";
-import "../chunk-7YL7NJJF.js";
+import "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-AVTEPAWI.js";
 import "../chunk-2ESYSVXG.js";

package/dist/core.js

@@ -10,7 +10,7 @@ import {
   ensureEven,
   extractCaptionWordsFromDoc,
   isEmphasized
-} from "./chunk-PQDALM2G.js";
+} from "./chunk-JNQKX4OI.js";
 import "./chunk-QH3YI3ND.js";
 import "./chunk-QISFYLBB.js";
 import "./chunk-K4VE64CR.js";
@@ -20,7 +20,7 @@ import "./chunk-KYRDKK2D.js";
 import "./chunk-WREYUH2E.js";
 import "./chunk-QWXUYVHX.js";
 import "./chunk-7PA7FGLD.js";
-import "./chunk-7YL7NJJF.js";
+import "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";

package/dist/mcp/adapter.js

@@ -2,10 +2,10 @@ import {
   querySchemaShape,
   serializeQuery,
   waitForJob
-} from "../chunk-NG7DP46H.js";
+} from "../chunk-MMZMS3S4.js";
 import {
   CURATED_TOOLS
-} from "../chunk-DJWCD3RF.js";
+} from "../chunk-3OOMVQ6I.js";
 import {
   apiErrorFrom,
   bodySchemaFor,
@@ -16,7 +16,7 @@ import {
   opById,
   safeParse,
   sniffImageMediaType
-} from "../chunk-URQQTAHZ.js";
+} from "../chunk-PNJ7DACK.js";
 import "../chunk-2ESYSVXG.js";
 
 // ../mcp/src/adapter.ts

package/dist/mcp/core.js

@@ -16,8 +16,9 @@ import {
   sniffAudioMediaType,
   sniffImageMediaType,
   text,
+  textWithData,
   withMedia
-} from "../chunk-URQQTAHZ.js";
+} from "../chunk-PNJ7DACK.js";
 import "../chunk-2ESYSVXG.js";
 export {
   __resetPreviewCache,
@@ -37,5 +38,6 @@ export {
   sniffAudioMediaType,
   sniffImageMediaType,
   text,
+  textWithData,
   withMedia
 };

package/dist/mcp/curation.js

@@ -10,7 +10,7 @@ import {
   formatResourceCandidates,
   formatTranscriptPage,
   formatWarnings
-} from "../chunk-DJWCD3RF.js";
+} from "../chunk-3OOMVQ6I.js";
 import "../chunk-2ESYSVXG.js";
 export {
   CRUD_COVERAGE,

package/dist/mcp/server.js

@@ -7,10 +7,10 @@ import {
   registerRawTools,
   registerSkillPrompts,
   titleCase
-} from "../chunk-BAVEHXVC.js";
-import "../chunk-NG7DP46H.js";
-import "../chunk-DJWCD3RF.js";
-import "../chunk-URQQTAHZ.js";
+} from "../chunk-NXEJASGI.js";
+import "../chunk-MMZMS3S4.js";
+import "../chunk-3OOMVQ6I.js";
+import "../chunk-PNJ7DACK.js";
 import "../chunk-2ESYSVXG.js";
 export {
   RAW_EXCLUDED_OPERATION_IDS,

package/dist/mcp.js

@@ -7,10 +7,10 @@ import {
   buildServer,
   registerCuratedTools,
   registerRawTools
-} from "./chunk-BAVEHXVC.js";
-import "./chunk-NG7DP46H.js";
-import "./chunk-DJWCD3RF.js";
-import "./chunk-URQQTAHZ.js";
+} from "./chunk-NXEJASGI.js";
+import "./chunk-MMZMS3S4.js";
+import "./chunk-3OOMVQ6I.js";
+import "./chunk-PNJ7DACK.js";
 import "./chunk-2ESYSVXG.js";
 export {
   API_URLS,

package/dist/primitives/effects.js

@@ -12,13 +12,13 @@ import {
   Vignette,
   catalog,
   laneDepths
-} from "../chunk-LD4XQQRL.js";
+} from "../chunk-WAUVKF2F.js";
 import "../chunk-MFHXCHRI.js";
 import "../chunk-XHGZ2E77.js";
 import "../chunk-W2245F6G.js";
-import "../chunk-DEDZKZ6G.js";
-import "../chunk-TZ7DKL2G.js";
-import "../chunk-7YL7NJJF.js";
+import "../chunk-JBWSK2YD.js";
+import "../chunk-OBA6NW4S.js";
+import "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-AVTEPAWI.js";
 import "../chunk-2ESYSVXG.js";

package/dist/primitives/layouts.js

@@ -8,12 +8,12 @@ import {
   SplitScreen,
   StaggeredBentoGrid,
   catalog
-} from "../chunk-YV5AYMNK.js";
+} from "../chunk-JRJQECCF.js";
 import "../chunk-XHGZ2E77.js";
 import "../chunk-W2245F6G.js";
-import "../chunk-DEDZKZ6G.js";
-import "../chunk-TZ7DKL2G.js";
-import "../chunk-7YL7NJJF.js";
+import "../chunk-JBWSK2YD.js";
+import "../chunk-OBA6NW4S.js";
+import "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-AVTEPAWI.js";
 import "../chunk-2ESYSVXG.js";

package/dist/primitives/scenes.js

@@ -8,15 +8,15 @@ import {
   ProductLaunchTrailer,
   TerminalToBrowserDeploy,
   catalog
-} from "../chunk-PRSRV7AT.js";
+} from "../chunk-TE3PNQG6.js";
 import "../chunk-QGAWDLYX.js";
 import "../chunk-S5H6GH6M.js";
 import "../chunk-QAGGJHAF.js";
 import "../chunk-MFHXCHRI.js";
 import "../chunk-W2245F6G.js";
-import "../chunk-DEDZKZ6G.js";
-import "../chunk-TZ7DKL2G.js";
-import "../chunk-7YL7NJJF.js";
+import "../chunk-JBWSK2YD.js";
+import "../chunk-OBA6NW4S.js";
+import "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-AVTEPAWI.js";
 import "../chunk-2ESYSVXG.js";

package/dist/primitives.js

@@ -1,9 +1,9 @@
 import {
   catalog as catalog4
-} from "./chunk-YV5AYMNK.js";
+} from "./chunk-JRJQECCF.js";
 import {
   catalog as catalog7
-} from "./chunk-PRSRV7AT.js";
+} from "./chunk-TE3PNQG6.js";
 import {
   catalog
 } from "./chunk-ZS3A3QUM.js";
@@ -23,7 +23,7 @@ import {
 } from "./chunk-RAXHCRVV.js";
 import {
   catalog as catalog2
-} from "./chunk-LD4XQQRL.js";
+} from "./chunk-WAUVKF2F.js";
 import "./chunk-MFHXCHRI.js";
 import {
   catalog as catalog8
@@ -33,9 +33,9 @@ import "./chunk-FWSJLHSV.js";
 import "./chunk-ZFEXATWN.js";
 import "./chunk-XHGZ2E77.js";
 import "./chunk-W2245F6G.js";
-import "./chunk-DEDZKZ6G.js";
-import "./chunk-TZ7DKL2G.js";
-import "./chunk-7YL7NJJF.js";
+import "./chunk-JBWSK2YD.js";
+import "./chunk-OBA6NW4S.js";
+import "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";