@cueframe/kernel 0.2.22 → 0.2.24

package/dist/_members/composition/scene/clipRules.d.ts

@@ -14,6 +14,16 @@
  */
 import type { Composition, Gap, TimelineClip, Track } from '../validators/composition.js';
 import { type SceneShotSpecV2 } from './schema.js';
+/**
+ * What a scene slot admits, stated once. The refusal below names these formats;
+ * so does the `scene.add` / `scene.update` contract, which reads them from here.
+ * They were only ever in the refusal, so the only way to learn them was to bind
+ * the wrong media and read the error.
+ */
+export declare const SCENE_SLOT_MEDIA_FORMATS: {
+    readonly image: "PNG, JPEG or WebP";
+    readonly video: "MP4 or WebM";
+};
 export type SceneClipIssueCode = 'validation_error' | 'invalid_composition';
 /** One rejection: a path into the clip (or request) and an actionable detail. */
 export interface SceneClipRuleIssue {

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/_members/mcp/generated/operations.d.ts

@@ -27,6 +27,8 @@ export interface GeneratedOperation {
     bodyKey: string | null;
     description: string;
     annotations: GeneratedAnnotations;
+    /** The 2xx JSON body as a self-contained JSON Schema, when it is an object. */
+    outputSchema?: Record<string, unknown>;
 }
 export interface GeneratedQueryParameter {
     name: string;

package/dist/animate/preparation-facts.js

@@ -4,11 +4,11 @@ import {
   sceneGrainPreparationCpuAllocationV1,
   scenePresetBuilderDescriptorV1,
   sceneSlabPreparationFactsV1
-} from "../chunk-TZ7DKL2G.js";
+} from "../chunk-OBA6NW4S.js";
 import {
   photographicStudioPreparationFactsV1,
   sceneFocusPreparationAllocationsV1
-} from "../chunk-7YL7NJJF.js";
+} from "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/animate.js

@@ -102,7 +102,7 @@ import {
   useStage,
   weightsAt,
   worldTransform
-} from "./chunk-DEDZKZ6G.js";
+} from "./chunk-JBWSK2YD.js";
 import {
   DEFAULT_LIGHTING_PROFILE,
   DEVICE_GLASS_OPACITY_ENCODED,
@@ -161,7 +161,7 @@ import {
   studioShadowFrustum,
   verifyPhotographicStudioHdr,
   withNormalisedFaceUv
-} from "./chunk-TZ7DKL2G.js";
+} from "./chunk-OBA6NW4S.js";
 import {
   ALLOWED_BAKE_SCALES,
   DEFAULT_BAKE_SCALE,
@@ -183,7 +183,7 @@ import {
   projectedSlotEdges,
   sceneFocusPreparationAllocationsV1,
   selectSceneBakeScale
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";

package/dist/authoring/scene.js

@@ -13,7 +13,7 @@ import {
   sceneTrackIdFor,
   validateSceneAdd,
   validateSceneUpdate
-} from "../chunk-E54DK225.js";
+} from "../chunk-JCQTSVZQ.js";
 import {
   SCENE_TRANSITION_KINDS,
   collectSceneClipIssues,
@@ -22,7 +22,7 @@ import {
   offFrameLattice,
   readSceneSourceRef,
   sceneClipShapeIssues
-} from "../chunk-7YL7NJJF.js";
+} from "../chunk-XACXNDFL.js";
 import "../chunk-2L7PYYJK.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/authoring.js

@@ -4,7 +4,7 @@ import {
   hasSceneOp,
   isSceneOp,
   materializeSceneOpsCore
-} from "./chunk-E54DK225.js";
+} from "./chunk-JCQTSVZQ.js";
 import {
   ZERO_USAGE,
   buildDirectorTools,
@@ -67,7 +67,7 @@ import "./chunk-7PA7FGLD.js";
 import {
   collectSceneClipIssues,
   isSceneShotClip
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 import "./chunk-2L7PYYJK.js";
 import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";

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-VDSO2KZY.js → chunk-5BAWOULP.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-ZVG446DJ.js";
 import {
   STUDIO_SHADOW_MAP_BUDGET
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 
 // ../execution/component-runtime/src/webglProbe.ts
 function webglBackend(platform, hardware) {

package/dist/{chunk-CDZBSLVA.js → chunk-H5CPILOK.js}

@@ -15,7 +15,7 @@ import {
   componentBrowserBackend,
   componentBrowserOptions,
   readGpuAttestation
-} from "./chunk-VDSO2KZY.js";
+} from "./chunk-5BAWOULP.js";
 import {
   ComponentCapturePageRasterAttestationV1,
   ComponentGraphicsApiV2,
@@ -28,7 +28,7 @@ import {
 } from "./chunk-ZVG446DJ.js";
 import {
   parseSceneShotSpecV2
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 import {
   BUNDLED_FONT_FACES
 } from "./chunk-AVTEPAWI.js";

package/dist/{chunk-DEDZKZ6G.js → chunk-JBWSK2YD.js}

@@ -19,7 +19,7 @@ import {
   slabTriangleCount,
   takeSceneEnvironment,
   useSceneActualResourceRegistrarV1
-} from "./chunk-TZ7DKL2G.js";
+} from "./chunk-OBA6NW4S.js";
 import {
   PHOTOGRAPHIC_STUDIO_RIG_ID,
   SCENE_SLAB_CONTENT_OFFSET,
@@ -31,7 +31,7 @@ import {
   sceneTextureBytes,
   sceneVideoMidpointAddressV1,
   selectSceneBakeScale
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 import {
   resolveCaptionFaces
 } from "./chunk-AVTEPAWI.js";

package/dist/{chunk-E54DK225.js → chunk-JCQTSVZQ.js}

@@ -8,7 +8,7 @@ import {
   sceneShotImageSlots,
   sceneShotVideoSlots,
   sceneSpecIssues
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 
 // ../authoring/src/scene/validate.ts
 var SceneAuthoringError = class extends Error {

package/dist/{chunk-PQDALM2G.js → chunk-JNQKX4OI.js}

@@ -51,7 +51,7 @@ import {
   sceneFullMipLevels,
   sceneTextureBytes,
   selectSceneBakeScale
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 import {
   SCENE_CONTEXT_GL_BUDGET_BYTES,
   SCENE_MAX_TRIANGLES,

package/dist/{chunk-YV5AYMNK.js → chunk-JRJQECCF.js}

@@ -24,7 +24,7 @@ import {
 } from "./chunk-W2245F6G.js";
 import {
   FlexLayout
-} from "./chunk-DEDZKZ6G.js";
+} from "./chunk-JBWSK2YD.js";
 
 // ../execution/primitives/src/layouts/chat-to-preview-layout/index.tsx
 import { Easing, interpolate, useCurrentFrame, useVideoConfig } from "remotion";

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

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

package/dist/{chunk-BAVEHXVC.js → chunk-NXEJASGI.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 {
   GENERATED_OPERATIONS,
   apiErrorFrom,
@@ -21,8 +21,9 @@ import {
   safeParse,
   sniffImageMediaType,
   text,
+  textWithData,
   withMedia
-} from "./chunk-URQQTAHZ.js";
+} from "./chunk-PNJ7DACK.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)))
@@ -3747,7 +3748,8 @@ function registerCuratedTools(server, ex, opts) {
     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: z.object(inputSchema), annotations }, async (args, extra) => timed(opts?.onEvent, spec.name, async (report) => {
+    const outputSchema = op.outputSchema && !spec.okText ? z.fromJSONSchema(op.outputSchema) : void 0;
+    server.registerTool(spec.name, { title: spec.title ?? titleCase(spec.name), description: spec.description, inputSchema: z.object(inputSchema), ...outputSchema ? { outputSchema } : {}, annotations }, async (args, extra) => timed(opts?.onEvent, spec.name, async (report) => {
       const a = { ...spec.defaults ?? {}, ...args };
       try {
         const query = serializeQuery(op.queryParams, a);
@@ -3760,9 +3762,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-TZ7DKL2G.js → chunk-OBA6NW4S.js}

@@ -18,7 +18,7 @@ import {
   sceneW5GeneratedRigAllocationsV1,
   sceneW5PresetAllocationsV1,
   sceneW5WorldTextAllocationsV1
-} from "./chunk-7YL7NJJF.js";
+} from "./chunk-XACXNDFL.js";
 
 // ../execution/animate/src/three/toneMapping.ts
 import {