@cueframe/kernel 0.2.22 → 0.2.23

package/dist/_members/mcp/core.d.ts

@@ -38,6 +38,19 @@ export type ToolResult = {
     structuredContent?: Record<string, unknown>;
 };
 export declare function text(s: string): ToolResult;
+/**
+ * A JSON response, carried BOTH ways: the rendered prose a human reads, and the
+ * parsed object a program can consume.
+ *
+ * Curated tools used to return prose only, so `create_render` promised
+ * `{id,status,warnings?}` and delivered "Render queued.\n\nrenderId: …". A
+ * generic MCP consumer had to scrape it (CUE-15 P0). `structuredContent` is the
+ * protocol's channel for exactly this; the text block stays as display.
+ *
+ * Attached only for a non-null, non-array OBJECT, which is what the protocol
+ * allows — a bare array or scalar would be rejected by a validating client.
+ */
+export declare function textWithData(s: string, data: unknown): ToolResult;
 export declare function errText(s: string): ToolResult;
 export declare function firstText(r: ToolResult): string;
 export declare function sniffImageMediaType(base64: string): string | undefined;
@@ -45,7 +58,9 @@ export declare function sniffAudioMediaType(base64: string): string | undefined;
 export declare function withMedia(payload: string, media: {
     data: string;
     kind: 'image' | 'audio';
-}[]): ToolResult;
+}[], 
+/** The parsed response, carried alongside the media for programmatic callers. */
+data?: unknown): ToolResult;
 export declare function fetchAsBase64(url: string, opts?: {
     timeoutMs?: number;
     maxBytes?: number;

package/dist/{chunk-DJWCD3RF.js → chunk-3OOMVQ6I.js}

@@ -312,7 +312,7 @@ Call wait_job(kind="compose", id="${j.composeJobId}", projectId="${a.projectId}"
     name: "apply_composition",
     operationId: "applyComposition",
     pathArgs: { projectId: "id" },
-    description: 'Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Pass `if_match` for optimistic-concurrency control (409 stale_etag on mismatch) and `dry_run: true` to validate the batch without persisting. Use this to seed a composition (add media clips) or make targeted edits (set a crop intent, reorder clips, set the format). CAPTIONS: attach content with {type:"captions.fromTranscript", mediaId, window?} \u2014 the server slices the cached word-timed transcript, rebases times, and sentence-splits into segments (no pasting words; 422 media_no_transcript if the media has no speech); style it with {type:"setCaptionStyle", style}; or set explicit words with {type:"setCaptions", segments, style?} (e.g. translations or your own VO timings). Brand is NOT set here \u2014 it lives on the project (create_project / PATCH /projects/:id with brandKitId). CARDS: a {kind:"card", html, tokens} clip projects each `tokens` KEY `x` to the CSS custom property `--cf-x`, so the html must read it as `var(--cf-x)` \u2014 write `tokens:{"plate":"#0af"}` + `background:var(--cf-plate)`. Do NOT put dashes in the key: `"--plate"` becomes `--cf---plate` and your `var(--plate)` then resolves to NOTHING, which CSS silently degrades to a transparent background and black text. Responses carry `warnings[]` when a card reads a var nothing defines. SCENE SHOTS: for a 3D product shot \u2014 a tilted page screenshot, a lit laptop/phone showing a real screenshot, two-colour type, a colour-field backdrop, focus/grain/vignette and a camera move \u2014 use {type:"scene.add", clipId, newTrack|trackId, startTime, duration, scene, assets} and revise it with {type:"scene.update", clipId, scene?, assets?, startTime?, duration?}. You author a scene SPEC, never wrapper TSX; the server registers the component for you. There is NO built-in scene primitive in list_catalog \u2014 READ cueframe://scene-shot first for the JSON schema, the canonical V2 world-objects recipe with nested groups, slabs, pages, phones, laptops, world/screen text, admitted surfaces, camera motion, lighting, and the current resource limits.',
+    description: 'Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Pass `if_match` for optimistic-concurrency control (409 stale_etag on mismatch) and `dry_run: true` to validate the batch without persisting. Use this to seed a composition (add media clips) or make targeted edits (set a crop intent, reorder clips, set the format). CAPTIONS: attach content with {type:"captions.fromTranscript", mediaId, window?} \u2014 the server slices the cached word-timed transcript, rebases times, and sentence-splits into segments (no pasting words; 422 media_no_transcript if the media has no speech); style it with {type:"setCaptionStyle", style}; or set explicit words with {type:"setCaptions", segments, style?} (e.g. translations or your own VO timings). Brand is NOT set here \u2014 it lives on the project (create_project / update_project with brandKitId \u2014 or PATCH /projects/:id over REST). CARDS: a {kind:"card", html, tokens} clip projects each `tokens` KEY `x` to the CSS custom property `--cf-x`, so the html must read it as `var(--cf-x)` \u2014 write `tokens:{"plate":"#0af"}` + `background:var(--cf-plate)`. Do NOT put dashes in the key: `"--plate"` becomes `--cf---plate` and your `var(--plate)` then resolves to NOTHING, which CSS silently degrades to a transparent background and black text. Responses carry `warnings[]` when a card reads a var nothing defines. SCENE SHOTS: for a 3D product shot \u2014 a tilted page screenshot, a lit laptop/phone showing a real screenshot, two-colour type, a colour-field backdrop, focus/grain/vignette and a camera move \u2014 use {type:"scene.add", clipId, newTrack|trackId, startTime, duration, scene, assets} and revise it with {type:"scene.update", clipId, scene?, assets?, startTime?, duration?}. You author a scene SPEC, never wrapper TSX; the server registers the component for you. There is NO built-in scene primitive in list_catalog \u2014 READ cueframe://scene-shot first for the JSON schema, the canonical V2 world-objects recipe with nested groups, slabs, pages, phones, laptops, world/screen text, admitted surfaces, camera motion, lighting, and the current resource limits.',
     okFormat: (j, a) => {
       const warns = formatWarnings(j);
       if (j && typeof j.valid === "boolean") {
@@ -348,7 +348,7 @@ ${JSON.stringify(r.errors ?? [], null, 2)}${warns}`;
     name: "create_render",
     operationId: "createRender",
     pathArgs: { projectId: "id" },
-    description: "Queue an MP4 render of a project's composition. Returns { id (renderId), status, warnings? } \u2014 `warnings[]` carries non-fatal advisories (omitted when none). The render themes from the project's brand kit (bind one via create_project / PATCH /projects/:id with brandKitId; without one the output is unbranded). Then call wait_job(kind=\"render\", id=renderId, projectId=...) to block until the file is ready and get the download URL, or register a webhook (create_webhook on render.completed \u2014 status rides the payload).",
+    description: "Queue an MP4 render of a project's composition. Returns { id (renderId), status, warnings? } \u2014 `warnings[]` carries non-fatal advisories (omitted when none). The render themes from the project's brand kit (bind one via create_project / update_project with brandKitId \u2014 or PATCH /projects/:id over REST; without one the output is unbranded). Then call wait_job(kind=\"render\", id=renderId, projectId=...) to block until the file is ready and get the download URL, or register a webhook (create_webhook on render.completed \u2014 status rides the payload).",
     okFormat: (j, a) => `Render queued.
 
 renderId: ${j.id}
@@ -552,7 +552,7 @@ Poll get_media_facts(mediaItemId="${a.mediaItemId}", kind="${a.body?.kind}", sta
   {
     name: "create_project",
     operationId: "createProject",
-    description: "Create a new project \u2014 the unit you compose and render into. compose / apply_composition / create_render / the preview family all require a projectId; this mints one. Pass name (required) plus optionally a format (aspectRatio/fps/resolution) and brandKitId. brandKitId binds a brand kit to the PROJECT (pass the kitId from create_brand_kit): colors/fonts/motion theme every render of this project automatically (omit it and the output is unbranded). Bind or change it later via PATCH /projects/:id. Returns the ProjectResponse (id + metadata)."
+    description: "Create a new project \u2014 the unit you compose and render into. compose / apply_composition / create_render / the preview family all require a projectId; this mints one. Pass name (required) plus optionally a format (aspectRatio/fps/resolution) and brandKitId. brandKitId binds a brand kit to the PROJECT (pass the kitId from create_brand_kit): colors/fonts/motion theme every render of this project automatically (omit it and the output is unbranded). Bind or change it later via update_project (PATCH /projects/:id over REST). Returns the ProjectResponse (id + metadata)."
   },
   {
     name: "new_composition",
@@ -806,7 +806,7 @@ Render it with create_render(projectId="${a.projectId}", body={ compositionId: "
   {
     name: "create_brand_kit",
     operationId: "createBrandKit",
-    description: "Create or UPSERT a brand kit (re-POSTing the same kitId updates it in place \u2014 this is also the brand-kit UPDATE path). Sets fonts/colors/logo. This is brand step 0 of the workflow: author the kit, then bind it to a PROJECT so colors/fonts/motion theme the output AUTOMATICALLY \u2014 pass its kitId as brandKitId to create_project, or attach it to an existing project via PATCH /projects/:id. Without a bound kit, create_render produces UNBRANDED output. Tenant-scoped (no project arg)."
+    description: "Create or UPSERT a brand kit (re-POSTing the same kitId updates it in place \u2014 this is also the brand-kit UPDATE path). Sets fonts/colors/logo. This is brand step 0 of the workflow: author the kit, then bind it to a PROJECT so colors/fonts/motion theme the output AUTOMATICALLY \u2014 pass its kitId as brandKitId to create_project, or attach it to an existing project via update_project (PATCH /projects/:id over REST). Without a bound kit, create_render produces UNBRANDED output. Tenant-scoped (no project arg)."
   },
   {
     name: "extract_brand_kit",

package/dist/{chunk-NG7DP46H.js → chunk-EDR75OU7.js}

@@ -5,7 +5,7 @@ import {
   isOk,
   opById,
   safeParse
-} from "./chunk-URQQTAHZ.js";
+} from "./chunk-RGKDDR7H.js";
 
 // ../mcp/src/wait.ts
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/{chunk-BAVEHXVC.js → chunk-LPFVUT3S.js}

@@ -2,10 +2,10 @@ import {
   querySchemaShape,
   serializeQuery,
   waitForJob
-} from "./chunk-NG7DP46H.js";
+} from "./chunk-EDR75OU7.js";
 import {
   CURATED_TOOLS
-} from "./chunk-DJWCD3RF.js";
+} from "./chunk-3OOMVQ6I.js";
 import {
   GENERATED_OPERATIONS,
   apiErrorFrom,
@@ -21,8 +21,9 @@ import {
   safeParse,
   sniffImageMediaType,
   text,
+  textWithData,
   withMedia
-} from "./chunk-URQQTAHZ.js";
+} from "./chunk-RGKDDR7H.js";
 
 // ../mcp/src/prompts.ts
 var skillListCache = null;
@@ -3616,7 +3617,7 @@ function registerResources(server, ex) {
     }),
     {
       title: "Component catalog",
-      description: "The component catalog: the FULL built-in primitive catalog (96 primitives + 7 scenes \u2014 lower-third, cinematic-title, color-grade, the scenes \u2026) PLUS your org-installed custom components. This is 'discover what to build with'. resources/list enumerates EVERY entry with its discovery facets (source/category/kind/tier/useCase) and a placement hint; read one for its full prop schema. NOT only your authored components. URI: cueframe://component/{componentId}.",
+      description: "The component catalog: the FULL built-in primitive catalog (lower-third, cinematic-title, color-grade, the `scenes`-category templates \u2026) PLUS your org-installed custom components. This is 'discover what to build with'. resources/list enumerates EVERY entry with its discovery facets (source/category/kind/tier/useCase) and a placement hint; read one for its full prop schema. NOT only your authored components. NOTE the word 'scene' means two different things: the `scenes` CATEGORY here is composed built-in templates you place by primitiveId, whereas a SCENE SHOT (the scene.add op, cueframe://scene-shot) is a 3D spec you author and has no catalog entry at all. URI: cueframe://component/{componentId}.",
       mimeType: "application/json"
     },
     async (uri, { componentId }) => jsonResource(uri, await read(ex, "getComponent", () => String(componentId)))
@@ -3760,9 +3761,9 @@ function registerCuratedTools(server, ex, opts) {
             const urls = spec.preview.urls(json).filter(Boolean);
             const data = await fetchPreviews(urls, spec.preview.cap ?? 12);
             report({ preview: { urls: urls.length, fetched: data.length } });
-            if (data.length) return withMedia(payload, data.map((d) => ({ data: d, kind })));
+            if (data.length) return withMedia(payload, data.map((d) => ({ data: d, kind })), json);
           }
-          return text(payload);
+          return textWithData(payload, json);
         }, query);
       } catch (err) {
         return errText(`${spec.name} failed: ${fmtErr(err)}`);

package/dist/{chunk-URQQTAHZ.js → chunk-RGKDDR7H.js}

@@ -9344,6 +9344,10 @@ function encodePaymentSignature(payload) {
 function text(s) {
   return { content: [{ type: "text", text: s }] };
 }
+function textWithData(s, data) {
+  const structured = data !== null && typeof data === "object" && !Array.isArray(data) ? data : void 0;
+  return structured ? { content: [{ type: "text", text: s }], structuredContent: structured } : { content: [{ type: "text", text: s }] };
+}
 function errText(s) {
   return { content: [{ type: "text", text: s }], isError: true };
 }
@@ -9400,7 +9404,7 @@ function sniffAudioMediaType(base64) {
   if (head.length >= 4 && head[0] === 255 && (head[1] & 224) === 224 && (head[1] >> 3 & 3) !== 1 && (head[1] >> 1 & 3) !== 0 && head[2] >> 4 > 0 && head[2] >> 4 < 15 && (head[2] >> 2 & 3) !== 3) return "audio/mpeg";
   return void 0;
 }
-function withMedia(payload, media) {
+function withMedia(payload, media, data) {
   const blocks = [{ type: "text", text: payload }];
   for (const m of media) {
     if (!m.data) continue;
@@ -9411,7 +9415,8 @@ function withMedia(payload, media) {
     }
     blocks.push({ type: m.kind, data: m.data, mimeType });
   }
-  return { content: blocks };
+  const structured = data !== null && typeof data === "object" && !Array.isArray(data) ? data : void 0;
+  return structured ? { content: blocks, structuredContent: structured } : { content: blocks };
 }
 var MAX_PREVIEW_BYTES = 2 * 1024 * 1024;
 var MAX_PREVIEW_BYTES_TOTAL = 3 * 1024 * 1024;
@@ -9590,6 +9595,7 @@ async function dispatchOp(ex, op, mapArg, body, extra, label, formatOk, query) {
 export {
   GENERATED_OPERATIONS,
   text,
+  textWithData,
   errText,
   firstText,
   sniffImageMediaType,

package/dist/compose.js

@@ -5,9 +5,6 @@ import {
 import "./chunk-JQMPHKLU.js";
 import "./chunk-ZZRBKGDA.js";
 import "./chunk-GULDS3VE.js";
-import {
-  catalog as catalog4
-} from "./chunk-YV5AYMNK.js";
 import {
   catalog as catalog7
 } from "./chunk-PRSRV7AT.js";
@@ -22,23 +19,26 @@ import {
 import "./chunk-QGAWDLYX.js";
 import {
   catalog as catalog6
-} from "./chunk-VLJOIUHL.js";
+} from "./chunk-A76GTLSA.js";
 import "./chunk-S5H6GH6M.js";
-import "./chunk-QAGGJHAF.js";
 import {
   catalog as catalog5
 } from "./chunk-RAXHCRVV.js";
 import {
   catalog as catalog2
-} from "./chunk-LD4XQQRL.js";
-import "./chunk-MFHXCHRI.js";
+} from "./chunk-AMKPFIF4.js";
 import {
   catalog as catalog8
 } from "./chunk-RL5SO653.js";
 import "./chunk-LT4PWSR2.js";
 import "./chunk-FWSJLHSV.js";
 import "./chunk-ZFEXATWN.js";
+import {
+  catalog as catalog4
+} from "./chunk-YV5AYMNK.js";
 import "./chunk-XHGZ2E77.js";
+import "./chunk-QAGGJHAF.js";
+import "./chunk-MFHXCHRI.js";
 import "./chunk-W2245F6G.js";
 import "./chunk-DEDZKZ6G.js";
 import "./chunk-TZ7DKL2G.js";

package/dist/composition-ops.js

@@ -490,20 +490,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
@@ -535,24 +563,52 @@ var CompositionOp = z.discriminatedUnion("type", [
     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(),
+  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/mcp/adapter.js

@@ -2,10 +2,10 @@ import {
   querySchemaShape,
   serializeQuery,
   waitForJob
-} from "../chunk-NG7DP46H.js";
+} from "../chunk-EDR75OU7.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-RGKDDR7H.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-RGKDDR7H.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-LPFVUT3S.js";
+import "../chunk-EDR75OU7.js";
+import "../chunk-3OOMVQ6I.js";
+import "../chunk-RGKDDR7H.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-LPFVUT3S.js";
+import "./chunk-EDR75OU7.js";
+import "./chunk-3OOMVQ6I.js";
+import "./chunk-RGKDDR7H.js";
 import "./chunk-2ESYSVXG.js";
 export {
   API_URLS,

package/dist/primitives/effects.js

@@ -12,9 +12,9 @@ import {
   Vignette,
   catalog,
   laneDepths
-} from "../chunk-LD4XQQRL.js";
-import "../chunk-MFHXCHRI.js";
+} from "../chunk-AMKPFIF4.js";
 import "../chunk-XHGZ2E77.js";
+import "../chunk-MFHXCHRI.js";
 import "../chunk-W2245F6G.js";
 import "../chunk-DEDZKZ6G.js";
 import "../chunk-TZ7DKL2G.js";

package/dist/primitives/ui-blocks.js

@@ -30,14 +30,14 @@ import {
   VisualDocsSnippet,
   VoiceWaveform,
   catalog
-} from "../chunk-VLJOIUHL.js";
+} from "../chunk-A76GTLSA.js";
 import {
   DashboardPopulate
 } from "../chunk-S5H6GH6M.js";
-import "../chunk-QAGGJHAF.js";
 import "../chunk-LT4PWSR2.js";
 import "../chunk-FWSJLHSV.js";
 import "../chunk-XHGZ2E77.js";
+import "../chunk-QAGGJHAF.js";
 import "../chunk-W2245F6G.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/primitives.js

@@ -1,6 +1,3 @@
-import {
-  catalog as catalog4
-} from "./chunk-YV5AYMNK.js";
 import {
   catalog as catalog7
 } from "./chunk-PRSRV7AT.js";
@@ -15,23 +12,26 @@ import {
 import "./chunk-QGAWDLYX.js";
 import {
   catalog as catalog6
-} from "./chunk-VLJOIUHL.js";
+} from "./chunk-A76GTLSA.js";
 import "./chunk-S5H6GH6M.js";
-import "./chunk-QAGGJHAF.js";
 import {
   catalog as catalog5
 } from "./chunk-RAXHCRVV.js";
 import {
   catalog as catalog2
-} from "./chunk-LD4XQQRL.js";
-import "./chunk-MFHXCHRI.js";
+} from "./chunk-AMKPFIF4.js";
 import {
   catalog as catalog8
 } from "./chunk-RL5SO653.js";
 import "./chunk-LT4PWSR2.js";
 import "./chunk-FWSJLHSV.js";
 import "./chunk-ZFEXATWN.js";
+import {
+  catalog as catalog4
+} from "./chunk-YV5AYMNK.js";
 import "./chunk-XHGZ2E77.js";
+import "./chunk-QAGGJHAF.js";
+import "./chunk-MFHXCHRI.js";
 import "./chunk-W2245F6G.js";
 import "./chunk-DEDZKZ6G.js";
 import "./chunk-TZ7DKL2G.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueframe/kernel",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "type": "module",
   "description": "Publish-only aggregate of CueFrame's isomorphic kernel packages — composition, primitives, authoring, MCP, and friends shipped as one npm artifact. Members remain separate workspace packages; this only changes what ships.",
   "files": [
@@ -17,25 +17,25 @@
     "tsup": "^8.3.5",
     "typescript": "^5.9.3",
     "@cueframe/account-model": "0.1.0",
-    "@cueframe/animate": "0.1.0",
-    "@cueframe/cloud-import": "0.1.0",
     "@cueframe/brand-derivation": "0.1.0",
     "@cueframe/authoring": "0.1.0",
-    "@cueframe/composition": "0.1.0",
+    "@cueframe/animate": "0.1.0",
+    "@cueframe/cloud-import": "0.1.0",
     "@cueframe/compose": "0.1.0",
-    "@cueframe/core": "0.1.0",
     "@cueframe/component-runtime": "0.1.0",
-    "@cueframe/errors": "0.1.0",
-    "@cueframe/director": "0.1.0",
-    "@cueframe/composition-ops": "0.1.0",
+    "@cueframe/composition": "0.1.0",
+    "@cueframe/core": "0.1.0",
     "@cueframe/foundation": "0.1.0",
+    "@cueframe/director": "0.1.0",
+    "@cueframe/errors": "0.1.0",
+    "@cueframe/media-model": "0.1.0",
+    "@cueframe/perception": "0.1.0",
     "@cueframe/plane": "0.1.0",
     "@cueframe/nle-export": "0.1.0",
     "@cueframe/mcp": "0.1.0",
-    "@cueframe/media-model": "0.1.0",
     "@cueframe/render-harness": "0.1.0",
-    "@cueframe/perception": "0.1.0",
-    "@cueframe/primitives": "0.1.0"
+    "@cueframe/primitives": "0.1.0",
+    "@cueframe/composition-ops": "0.1.0"
   },
   "peerDependencies": {
     "gsap": "3.13.0",

package/dist/{chunk-VLJOIUHL.js → chunk-A76GTLSA.js}

@@ -1,9 +1,6 @@
 import {
   DashboardPopulate
 } from "./chunk-S5H6GH6M.js";
-import {
-  useFrameScale
-} from "./chunk-QAGGJHAF.js";
 import {
   resolveTypeface
 } from "./chunk-LT4PWSR2.js";
@@ -14,6 +11,9 @@ import {
   FitText,
   resolveFitFontSize
 } from "./chunk-XHGZ2E77.js";
+import {
+  useFrameScale
+} from "./chunk-QAGGJHAF.js";
 import {
   ACCENT,
   ACCENT_DEEP,

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

@@ -1,9 +1,9 @@
-import {
-  EASING_BY_INTENT
-} from "./chunk-MFHXCHRI.js";
 import {
   FitText
 } from "./chunk-XHGZ2E77.js";
+import {
+  EASING_BY_INTENT
+} from "./chunk-MFHXCHRI.js";
 import {
   ACCENT,
   ACCENT_STRONG,