@cueframe/kernel 0.2.51 → 0.2.52

package/dist/_members/composition/validators/composition.d.ts

@@ -335,6 +335,11 @@ export declare const ClipFit: z.ZodEnum<{
     cover: "cover";
 }>;
 export type ClipFit = z.infer<typeof ClipFit>;
+export declare const CaptionVisibility: z.ZodEnum<{
+    visible: "visible";
+    hidden: "hidden";
+}>;
+export type CaptionVisibility = z.infer<typeof CaptionVisibility>;
 export declare const PerClipEffect: z.ZodObject<{
     primitiveId: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -543,6 +548,10 @@ export declare const TimelineClip: z.ZodObject<{
         contain: "contain";
         cover: "cover";
     }>>;
+    captionVisibility: z.ZodOptional<z.ZodEnum<{
+        visible: "visible";
+        hidden: "hidden";
+    }>>;
     effects: z.ZodOptional<z.ZodArray<z.ZodObject<{
         primitiveId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -698,6 +707,7 @@ export declare const TrackContent: z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
         h: number;
     } | undefined;
     fit?: "contain" | "cover" | undefined;
+    captionVisibility?: "visible" | "hidden" | undefined;
     effects?: {
         primitiveId: string;
         params?: Record<string, unknown> | undefined;
@@ -857,6 +867,7 @@ export declare const Track: z.ZodObject<{
             h: number;
         } | undefined;
         fit?: "contain" | "cover" | undefined;
+        captionVisibility?: "visible" | "hidden" | undefined;
         effects?: {
             primitiveId: string;
             params?: Record<string, unknown> | undefined;
@@ -1148,6 +1159,13 @@ export declare function captionsAreBehindSubject(captions: {
 } | null | undefined): boolean;
 export type CompositionCaptions = z.infer<typeof CompositionCaptions>;
 export declare function captionWords(c: CompositionCaptions): CaptionWord[];
+/** One shared invariant for schema parsing, pure ops, and hosted writes. */
+export declare function captionVisibilityIssues(composition: {
+    tracks: Track[];
+}): Array<{
+    trackIndex: number;
+    contentIndex: number;
+}>;
 export declare const Composition: z.ZodObject<{
     v: z.ZodLiteral<1>;
     format: z.ZodObject<{
@@ -1302,6 +1320,7 @@ export declare const Composition: z.ZodObject<{
                 h: number;
             } | undefined;
             fit?: "contain" | "cover" | undefined;
+            captionVisibility?: "visible" | "hidden" | undefined;
             effects?: {
                 primitiveId: string;
                 params?: Record<string, unknown> | undefined;
@@ -1698,6 +1717,7 @@ export declare const CompositionVersion: z.ZodObject<{
                     h: number;
                 } | undefined;
                 fit?: "contain" | "cover" | undefined;
+                captionVisibility?: "visible" | "hidden" | undefined;
                 effects?: {
                     primitiveId: string;
                     params?: Record<string, unknown> | undefined;

package/dist/_members/composition/validators/render.d.ts

@@ -205,6 +205,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                     h: number;
                 } | undefined;
                 fit?: "contain" | "cover" | undefined;
+                captionVisibility?: "visible" | "hidden" | undefined;
                 effects?: {
                     primitiveId: string;
                     params?: Record<string, unknown> | undefined;
@@ -1049,6 +1050,7 @@ export declare const RenderJob: z.ZodObject<{
                         h: number;
                     } | undefined;
                     fit?: "contain" | "cover" | undefined;
+                    captionVisibility?: "visible" | "hidden" | undefined;
                     effects?: {
                         primitiveId: string;
                         params?: Record<string, unknown> | undefined;

package/dist/_members/composition-ops/index.d.ts

@@ -170,6 +170,10 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<[z.ZodObject<{
             contain: "contain";
             cover: "cover";
         }>>;
+        captionVisibility: z.ZodOptional<z.ZodEnum<{
+            visible: "visible";
+            hidden: "hidden";
+        }>>;
         effects: z.ZodOptional<z.ZodArray<z.ZodObject<{
             primitiveId: z.ZodString;
             params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -363,6 +367,10 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<[z.ZodObject<{
             contain: "contain";
             cover: "cover";
         }>>>;
+        captionVisibility: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            visible: "visible";
+            hidden: "hidden";
+        }>>>;
         effects: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
             primitiveId: z.ZodString;
             params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -552,6 +560,10 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<[z.ZodObject<{
             contain: "contain";
             cover: "cover";
         }>>;
+        captionVisibility: z.ZodOptional<z.ZodEnum<{
+            visible: "visible";
+            hidden: "hidden";
+        }>>;
         effects: z.ZodOptional<z.ZodArray<z.ZodObject<{
             primitiveId: z.ZodString;
             params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/_members/core/render/compositionAudioAndDepth.d.ts

@@ -7,13 +7,19 @@ export declare function assertBehindSubjectCaptionCoverage(captionSegments: Rend
     width: number;
     height: number;
 }, effects?: readonly CompositionEffect[]): void;
+/** The geometry needed to decide which video picture is visible, without an asset URL. */
+export type VisiblePictureClip = Pick<CompositionClip, 'id' | 'trackId' | 'contentIndex' | 'layerIndex' | 'timelineStartFrames' | 'durationInFrames'> & Partial<Pick<CompositionClip, 'region' | 'fit' | 'sourceWidth' | 'sourceHeight' | 'cropTrajectory' | 'cropTrajectoryUrl' | 'captionVisibility' | 'packedUrl' | 'mediaType'>> & {
+    hasClipEffects?: boolean;
+    hasCropIntent?: boolean;
+};
 /** The visible full-frame picture at each interval, following the renderer's zIndex/layer order. */
-export declare function visiblePackedHostWindows(clips: readonly CompositionClip[], startFrame: number, endFrame: number, output: {
+export declare function visiblePackedHostWindows(clips: readonly VisiblePictureClip[], startFrame: number, endFrame: number, output: {
     width: number;
     height: number;
-}, effects?: readonly CompositionEffect[]): Array<{
+}, effects?: readonly CompositionEffect[], hostMode?: 'packed-only' | 'all-video-candidates'): Array<{
     startFrame: number;
     endFrame: number;
     hostClipId?: string;
     candidateClipIds: string[];
+    captionVisible: boolean;
 }>;

package/dist/_members/core/render/compositionRender.d.ts

@@ -2,10 +2,24 @@ import type { Composition, Format, TimelineClip as WireClip } from "../../compos
 import type { RenderInput } from "./types.js";
 import type { TrajectoryData } from "../../composition/reframe/trajectory.js";
 import { type PreparedRenderInputLeaseV1, type SceneShotPreparationDependenciesV1 } from "./sceneShotPreparation.js";
+import { visiblePackedHostWindows } from "./compositionAudioAndDepth.js";
 export { validateComposition } from "./compositionValidation.js";
 export { assertBehindSubjectCaptionCoverage, visiblePackedHostWindows } from "./compositionAudioAndDepth.js";
 /** Re-exported from `trackProjection`, where the frame-lattice helpers it belongs with now live. */
 export { playableSpans, projectMediaPlaybackSpans } from "./trackProjection.js";
+/**
+ * Project the saved video timeline into candidate visible-picture windows for fact planning.
+ * No source URL or matte binding is created here. A hostClipId names the uniquely visible
+ * video candidate; callers must still check that its exact matte exists and is ready.
+ */
+export declare function captionVisibilityWindowsForComposition(composition: Composition, sourceDimensions: Record<string, {
+    width: number;
+    height: number;
+}>): {
+    fps: number;
+    windows: ReturnType<typeof visiblePackedHostWindows>;
+    mediaIdByProjectedClipId: Record<string, string>;
+};
 export declare function compositionFormatDimensions(format: Format): {
     width: number;
     height: number;

package/dist/_members/core/render/index.d.ts

@@ -11,7 +11,7 @@ export type { EmphasisWord } from './emphasis.js';
 export type { DocNode, TranscriptUtterance } from './captions.js';
 export { buildEmphasisSet, isEmphasized } from './emphasis.js';
 export { extractCaptionWordsFromDoc, sliceTranscriptWords, splitIntoSentences } from './captions.js';
-export { compositionToRenderInput, referencedMediaIds, assembleRenderInput, assemblePreparedRenderInput, validateComposition, compositionFormatDimensions, playableSpans, projectMediaPlaybackSpans, assertBehindSubjectCaptionCoverage, visiblePackedHostWindows, } from './compositionRender.js';
+export { compositionToRenderInput, referencedMediaIds, assembleRenderInput, assemblePreparedRenderInput, validateComposition, compositionFormatDimensions, captionVisibilityWindowsForComposition, playableSpans, projectMediaPlaybackSpans, assertBehindSubjectCaptionCoverage, visiblePackedHostWindows, } from './compositionRender.js';
 export { bookendFrames, resolveBookendTimeline, CARD_BOOKEND_DEFAULT_MS, VIDEO_BOOKEND_DEFAULT_MS, } from './bookends.js';
 export type { BookendTimeline } from './bookends.js';
 export { DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, ensureEven, qualityToCrf, resolutionToOutputSize, } from './exportSettings.js';

package/dist/_members/core/render/types.d.ts

@@ -69,6 +69,7 @@ export interface CompositionClip extends ProjectedVisualIdentity {
         h: number;
     };
     fit?: 'cover' | 'contain';
+    captionVisibility?: 'visible' | 'hidden';
     mediaType?: 'video' | 'audio' | 'image';
     kenBurns?: 'in' | 'out' | 'pan-l' | 'pan-r' | 'none';
     reframe?: Reframe;

package/dist/authoring/build-tools.js

@@ -4,13 +4,13 @@ import {
   buildPlannerTools,
   buildToolsFromSchemas,
   extractProviderError
-} from "../chunk-IHWC75AN.js";
-import "../chunk-KY3QBG7O.js";
+} from "../chunk-QVBUYWW6.js";
+import "../chunk-KMDZDH5E.js";
 import "../chunk-JOURGVOR.js";
 import "../chunk-7AZLFN26.js";
-import "../chunk-NLXQ7WTH.js";
-import "../chunk-LO3DH776.js";
-import "../chunk-LZEX2GAY.js";
+import "../chunk-5JCLZPMV.js";
+import "../chunk-MBSQKRDF.js";
+import "../chunk-CV3QQUMK.js";
 import "../chunk-WPZKOVYF.js";
 import "../chunk-B7J5UUUV.js";
 import "../chunk-KYRDKK2D.js";

package/dist/authoring/context.js

@@ -1,9 +1,9 @@
 import {
   buildDirectorContext
-} from "../chunk-OVV35ZS2.js";
-import "../chunk-NLXQ7WTH.js";
-import "../chunk-LO3DH776.js";
-import "../chunk-LZEX2GAY.js";
+} from "../chunk-FSEB4LSU.js";
+import "../chunk-5JCLZPMV.js";
+import "../chunk-MBSQKRDF.js";
+import "../chunk-CV3QQUMK.js";
 import "../chunk-WPZKOVYF.js";
 import "../chunk-B7J5UUUV.js";
 import "../chunk-KYRDKK2D.js";

package/dist/authoring/tools.js

@@ -6,12 +6,12 @@ import {
   COMPOSE_ROLE_TOOLS,
   COMPOSE_ROLE_TOOL_NAMES,
   dispatchComposeRoleTool
-} from "../chunk-KY3QBG7O.js";
+} from "../chunk-KMDZDH5E.js";
 import "../chunk-JOURGVOR.js";
 import "../chunk-7AZLFN26.js";
-import "../chunk-NLXQ7WTH.js";
-import "../chunk-LO3DH776.js";
-import "../chunk-LZEX2GAY.js";
+import "../chunk-5JCLZPMV.js";
+import "../chunk-MBSQKRDF.js";
+import "../chunk-CV3QQUMK.js";
 import "../chunk-WPZKOVYF.js";
 import "../chunk-B7J5UUUV.js";
 import "../chunk-KYRDKK2D.js";

package/dist/authoring.js

@@ -11,7 +11,7 @@ import {
   buildPlannerTools,
   buildToolsFromSchemas,
   extractProviderError
-} from "./chunk-IHWC75AN.js";
+} from "./chunk-QVBUYWW6.js";
 import {
   COMPOSE_MOTION_TOOLS,
   COMPOSE_MOTION_VERIFY_TOOLS,
@@ -20,14 +20,14 @@ import {
   COMPOSE_ROLE_TOOLS,
   COMPOSE_ROLE_TOOL_NAMES,
   dispatchComposeRoleTool
-} from "./chunk-KY3QBG7O.js";
+} from "./chunk-KMDZDH5E.js";
 import {
   AgentFixableCaptureError,
   getExcludedTools
 } from "./chunk-JOURGVOR.js";
 import {
   buildDirectorContext
-} from "./chunk-OVV35ZS2.js";
+} from "./chunk-FSEB4LSU.js";
 import {
   buildFastModel,
   buildModel,
@@ -49,9 +49,9 @@ import {
   initCodeGenPrompts
 } from "./chunk-Y4HPN4BC.js";
 import "./chunk-7AZLFN26.js";
-import "./chunk-NLXQ7WTH.js";
-import "./chunk-LO3DH776.js";
-import "./chunk-LZEX2GAY.js";
+import "./chunk-5JCLZPMV.js";
+import "./chunk-MBSQKRDF.js";
+import "./chunk-CV3QQUMK.js";
 import "./chunk-WPZKOVYF.js";
 import "./chunk-B7J5UUUV.js";
 import "./chunk-KYRDKK2D.js";

package/dist/{chunk-2LUAUF46.js → chunk-2M65KQNG.js}

@@ -1436,6 +1436,7 @@ var BriefCreateRequest = zod19.strictObject({
       "h": zod19.number().gt(briefCreateRequestSeededGraphicsItemRegionHExclusiveMin).max(briefCreateRequestSeededGraphicsItemRegionHMax)
     }).optional(),
     "fit": zod19.enum(["cover", "contain"]).optional(),
+    "captionVisibility": zod19.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
     "effects": zod19.array(zod19.strictObject({
       "primitiveId": zod19.string().min(1),
       "params": zod19.record(zod19.string(), zod19.unknown()).optional()
@@ -1697,6 +1698,7 @@ var BriefResponse = zod21.strictObject({
       "h": zod21.number().gt(briefResponseSeededGraphicsItemRegionHExclusiveMin).max(briefResponseSeededGraphicsItemRegionHMax)
     }).optional(),
     "fit": zod21.enum(["cover", "contain"]).optional(),
+    "captionVisibility": zod21.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
     "effects": zod21.array(zod21.strictObject({
       "primitiveId": zod21.string().min(1),
       "params": zod21.record(zod21.string(), zod21.unknown()).optional()
@@ -1947,6 +1949,7 @@ var BriefPatchRequest = zod23.strictObject({
       "h": zod23.number().gt(briefPatchRequestSeededGraphicsItemRegionHExclusiveMin).max(briefPatchRequestSeededGraphicsItemRegionHMax)
     }).optional(),
     "fit": zod23.enum(["cover", "contain"]).optional(),
+    "captionVisibility": zod23.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
     "effects": zod23.array(zod23.strictObject({
       "primitiveId": zod23.string().min(1),
       "params": zod23.record(zod23.string(), zod23.unknown()).optional()
@@ -2755,6 +2758,7 @@ var Composition = zod58.strictObject({
         "h": zod58.number().gt(compositionTracksItemContentsItemOneRegionHExclusiveMin).max(compositionTracksItemContentsItemOneRegionHMax)
       }).optional(),
       "fit": zod58.enum(["cover", "contain"]).optional(),
+      "captionVisibility": zod58.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
       "effects": zod58.array(zod58.strictObject({
         "primitiveId": zod58.string().min(1),
         "params": zod58.record(zod58.string(), zod58.unknown()).optional()
@@ -6282,6 +6286,7 @@ var CompositionOp = zod67.union([zod67.strictObject({
       "h": zod67.number().gt(compositionOpThreeClipRegionHExclusiveMin).max(compositionOpThreeClipRegionHMax)
     }).optional(),
     "fit": zod67.enum(["cover", "contain"]).optional(),
+    "captionVisibility": zod67.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
     "effects": zod67.array(zod67.strictObject({
       "primitiveId": zod67.string().min(1),
       "params": zod67.record(zod67.string(), zod67.unknown()).optional()
@@ -6431,6 +6436,7 @@ var CompositionOp = zod67.union([zod67.strictObject({
       "h": zod67.number().gt(compositionOpFivePatchRegionHExclusiveMin).max(compositionOpFivePatchRegionHMax)
     }).optional(),
     "fit": zod67.enum(["cover", "contain"]).optional(),
+    "captionVisibility": zod67.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
     "effects": zod67.array(zod67.strictObject({
       "primitiveId": zod67.string().min(1),
       "params": zod67.record(zod67.string(), zod67.unknown()).optional()
@@ -6576,6 +6582,7 @@ var CompositionOp = zod67.union([zod67.strictObject({
       "h": zod67.number().gt(compositionOpSevenClipsItemRegionHExclusiveMin).max(compositionOpSevenClipsItemRegionHMax)
     }).optional(),
     "fit": zod67.enum(["cover", "contain"]).optional(),
+    "captionVisibility": zod67.enum(["visible", "hidden"]).optional().describe("Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."),
     "effects": zod67.array(zod67.strictObject({
       "primitiveId": zod67.string().min(1),
       "params": zod67.record(zod67.string(), zod67.unknown()).optional()

package/dist/{chunk-4CNJGY7P.js → chunk-3I43W7DP.js}

@@ -1232,6 +1232,7 @@ function assertBehindSubjectCaptionCoverage(captionSegments, clips, fps, output,
       const startFrame = Math.round(word.startMs / 1e3 * fps);
       const endFrame = Math.max(startFrame + 1, Math.round(word.endMs / 1e3 * fps));
       for (const window of visiblePackedHostWindows(clips, startFrame, endFrame, output, effects)) {
+        if (!window.captionVisible) continue;
         if (window.hostClipId) continue;
         const code = window.candidateClipIds.length > 1 ? "behind_subject_caption_host_ambiguous" : "behind_subject_caption_host_missing";
         throw renderInputError(
@@ -1245,10 +1246,10 @@ function assertBehindSubjectCaptionCoverage(captionSegments, clips, fps, output,
 }
 var FULL_RECT = { left: 0, top: 0, right: 1, bottom: 1 };
 function hasClipEffect(clip, effects) {
-  return effects.some((effect) => effect.target.kind === "clip" && effect.trackId === clip.trackId && effect.contentIndex === clip.contentIndex);
+  return clip.hasClipEffects === true || effects.some((effect) => effect.target.kind === "clip" && effect.trackId === clip.trackId && effect.contentIndex === clip.contentIndex);
 }
 function pictureRect(clip, output, effects) {
-  if (clip.cropTrajectory || clip.cropTrajectoryUrl || hasClipEffect(clip, effects)) return void 0;
+  if (clip.cropTrajectory || clip.cropTrajectoryUrl || clip.hasCropIntent || hasClipEffect(clip, effects)) return void 0;
   if (clip.fit !== "contain") return FULL_RECT;
   const sourceWidth = clip.sourceWidth;
   const sourceHeight = clip.sourceHeight;
@@ -1271,7 +1272,7 @@ function coversLowerPictures(upper, lower, output, effects) {
     return upperRect.left <= rect.left + epsilon && upperRect.top <= rect.top + epsilon && upperRect.right + epsilon >= rect.right && upperRect.bottom + epsilon >= rect.bottom;
   });
 }
-function visiblePackedHostWindows(clips, startFrame, endFrame, output, effects = []) {
+function visiblePackedHostWindows(clips, startFrame, endFrame, output, effects = [], hostMode = "packed-only") {
   if (endFrame <= startFrame) return [];
   const boundaries = /* @__PURE__ */ new Set([startFrame, endFrame]);
   for (const clip of clips) {
@@ -1280,6 +1281,13 @@ function visiblePackedHostWindows(clips, startFrame, endFrame, output, effects =
     if (start > startFrame && start < endFrame) boundaries.add(start);
     if (end > startFrame && end < endFrame) boundaries.add(end);
   }
+  for (const effect of effects) {
+    if (effect.target.kind !== "global") continue;
+    const start = effect.startFrame ?? startFrame;
+    const end = start + (effect.durationInFrames ?? endFrame - start);
+    if (start > startFrame && start < endFrame) boundaries.add(start);
+    if (end > startFrame && end < endFrame) boundaries.add(end);
+  }
   const points = [...boundaries].sort((a, b) => a - b);
   const windows = [];
   for (let i = 0; i < points.length - 1; i++) {
@@ -1290,6 +1298,7 @@ function visiblePackedHostWindows(clips, startFrame, endFrame, output, effects =
     );
     const topLayer = Math.max(...active.map((clip) => clip.layerIndex));
     const top = active.filter((clip) => clip.layerIndex === topLayer);
+    const globalEffectActive = effects.some((effect) => effect.target.kind === "global" && (effect.startFrame ?? startFrame) <= start && (effect.startFrame ?? startFrame) + (effect.durationInFrames ?? endFrame - startFrame) >= end);
     const fullFrame = top[0]?.region === void 0 || top[0].region.x === 0 && top[0].region.y === 0 && top[0].region.w === 1 && top[0].region.h === 1;
     const provesOcclusion = top.length === 1 && fullFrame && (active.length === 1 || coversLowerPictures(
       top[0],
@@ -1297,18 +1306,22 @@ function visiblePackedHostWindows(clips, startFrame, endFrame, output, effects =
       output,
       effects
     ));
-    const host = provesOcclusion && top[0].packedUrl ? top[0] : void 0;
-    const unresolvedOverlap = top.length > 1 || top.length === 1 && !!top[0].packedUrl && active.length > 1 && !provesOcclusion;
-    const candidates = unresolvedOverlap ? active.filter((clip) => clip.packedUrl).map((clip) => clip.id) : top.map((clip) => clip.id);
+    const suppressesCaption = provesOcclusion && !globalEffectActive && pictureRect(top[0], output, effects) !== void 0;
+    const captionVisible = !(suppressesCaption && top[0].captionVisibility === "hidden");
+    const candidateHost = (clip) => hostMode === "all-video-candidates" ? clip.mediaType !== "image" : !!clip.packedUrl;
+    const host = provesOcclusion && candidateHost(top[0]) ? top[0] : void 0;
+    const unresolvedOverlap = top.length > 1 || top.length === 1 && active.length > 1 && !provesOcclusion;
+    const candidates = unresolvedOverlap ? active.filter(candidateHost).map((clip) => clip.id) : top.map((clip) => clip.id);
     const previous = windows[windows.length - 1];
-    if (previous && previous.endFrame === start && previous.hostClipId === host?.id && previous.candidateClipIds.join("\0") === candidates.join("\0")) {
+    if (previous && previous.endFrame === start && previous.hostClipId === host?.id && previous.captionVisible === captionVisible && previous.candidateClipIds.join("\0") === candidates.join("\0")) {
       previous.endFrame = end;
     } else {
       windows.push({
         startFrame: start,
         endFrame: end,
         ...host ? { hostClipId: host.id } : {},
-        candidateClipIds: candidates
+        candidateClipIds: candidates,
+        captionVisible
       });
     }
   }
@@ -1455,6 +1468,13 @@ function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajecto
       );
     }
     if (rendersNoFrames(c)) continue;
+    if (c.captionVisibility !== void 0 && track.kind !== "video") {
+      throw renderInputError(
+        "invalid_composition",
+        `Clip ${c.id}: captionVisibility is supported only on video media clips.`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].captionVisibility` }
+      );
+    }
     const src = resolveSrcUrl(c.source.mediaId, srcUrls, {
       trackId: track.id,
       clipId: c.id,
@@ -1546,6 +1566,7 @@ function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajecto
         ...c.animate !== void 0 ? { animate: c.animate } : {},
         ...c.region !== void 0 ? { region: c.region } : {},
         ...c.fit !== void 0 ? { fit: c.fit } : {},
+        ...c.captionVisibility !== void 0 ? { captionVisibility: c.captionVisibility } : {},
         ...s === 0 && c.transitionIn ? {
           transitionIn: mapTransitionType(c.transitionIn.type),
           transitionDurationFrames: Math.max(1, Math.round(c.transitionIn.duration * fps))
@@ -1813,6 +1834,71 @@ function projectEffectTrack(track, trackIndex, trackCount, fps) {
 }
 
 // ../execution/core/src/render/compositionRender.ts
+function captionVisibilityWindowsForComposition(composition, sourceDimensions) {
+  const { fps, width, height } = compositionFormatDimensions(composition.format);
+  const clips = [];
+  const mediaIdByProjectedClipId = {};
+  let endFrame = 0;
+  const trackCount = composition.tracks.length;
+  const effects = composition.tracks.flatMap(
+    (track, index) => track.enabled !== false && track.kind === "effect" ? projectEffectTrack(track, index, trackCount, fps) : []
+  );
+  for (const [trackIndex, track] of composition.tracks.entries()) {
+    if (track.enabled === false || track.kind !== "video" && track.kind !== "image") continue;
+    for (const [contentIndex, item] of track.contents.entries()) {
+      if (!("source" in item)) continue;
+      if (item.source.kind !== "media") {
+        throw renderInputError(
+          "clip_source_track_mismatch",
+          `Clip ${item.id} on video track ${track.id} must use a media source.`,
+          { trackId: track.id, clipId: item.id }
+        );
+      }
+      const spans = projectMediaPlaybackSpans(track.kind === "video" ? {
+        startTime: item.startTime,
+        duration: item.duration,
+        trim: item.source.trim,
+        excludedRanges: item.source.excludedRanges,
+        playbackRate: item.source.playbackRate,
+        fps
+      } : { startTime: item.startTime, duration: item.duration, fps });
+      const dimensions = sourceDimensions[item.source.mediaId];
+      const validDimensions = track.kind === "video" && dimensions && Number.isFinite(dimensions.width) && dimensions.width > 0 && Number.isFinite(dimensions.height) && dimensions.height > 0;
+      for (const [spanIndex, span] of spans.entries()) {
+        if (span.durationInFrames === 0) continue;
+        const id = spans.length === 1 ? item.id : `${item.id}#${spanIndex}`;
+        clips.push({
+          id,
+          trackId: track.id,
+          layerIndex: trackCount - trackIndex,
+          contentIndex,
+          timelineStartFrames: span.timelineStartFrames,
+          durationInFrames: span.durationInFrames,
+          ...track.kind === "image" ? { mediaType: "image" } : {},
+          ...validDimensions ? { sourceWidth: dimensions.width, sourceHeight: dimensions.height } : {},
+          ...item.region ? { region: item.region } : {},
+          ...item.fit ? { fit: item.fit } : {},
+          ...track.kind === "video" && item.captionVisibility ? { captionVisibility: item.captionVisibility } : {},
+          ...item.source.reframe?.segments.length ? { hasCropIntent: true } : {},
+          ...item.effects?.length ? { hasClipEffects: true } : {}
+        });
+        if (track.kind === "video") mediaIdByProjectedClipId[id] = item.source.mediaId;
+        endFrame = Math.max(endFrame, span.timelineStartFrames + span.durationInFrames);
+      }
+    }
+  }
+  for (const segment of composition.captions?.segments ?? []) {
+    for (const word of segment.words) {
+      const startFrame = Math.round(word.startMs / 1e3 * fps);
+      endFrame = Math.max(endFrame, Math.max(startFrame + 1, Math.round(word.endMs / 1e3 * fps)));
+    }
+  }
+  return {
+    fps,
+    windows: visiblePackedHostWindows(clips, 0, endFrame, { width, height }, effects, "all-video-candidates"),
+    mediaIdByProjectedClipId
+  };
+}
 var CAPTION_COLOR_FIELDS = [
   "color",
   "highlightColor",
@@ -1903,6 +1989,18 @@ function assertMergedCaptionFacesDrawable(composition) {
 function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUrls, alphaUrls, subCompositions, trajectories, options) {
   const flattened = hasCompoundClips(composition) ? flattenCompoundClips(composition, (id) => subCompositions?.[id]) : composition;
   composition = flattened;
+  for (const track of composition.tracks) {
+    for (const content of track.contents) {
+      if (!("source" in content) || content.captionVisibility === void 0) continue;
+      if (track.kind !== "video" || content.source.kind !== "media") {
+        throw renderInputError(
+          "invalid_composition",
+          `Clip ${content.id}: captionVisibility is supported only on video media clips.`,
+          { trackId: track.id, clipId: content.id, compositionPath: `composition.tracks[${track.id}].contents[${content.id}].captionVisibility` }
+        );
+      }
+    }
+  }
   assertMergedCaptionFacesDrawable(composition);
   const { width, height, fps } = compositionFormatDimensions(composition.format);
   const clips = [];
@@ -3086,6 +3184,7 @@ export {
   visiblePackedHostWindows,
   playableSpans,
   projectMediaPlaybackSpans,
+  captionVisibilityWindowsForComposition,
   compositionFormatDimensions,
   referencedMediaIds,
   compositionToRenderInput,

package/dist/{chunk-MOUWO53S.js → chunk-3OG2674K.js}

@@ -1,7 +1,7 @@
 import {
   bodySchemaFor,
   opById
-} from "./chunk-2LUAUF46.js";
+} from "./chunk-2M65KQNG.js";
 
 // ../mcp/src/generated/sceneContract.ts
 function deepFreeze(value) {

package/dist/{chunk-NLXQ7WTH.js → chunk-5JCLZPMV.js}

@@ -1,6 +1,6 @@
 import {
   Composition
-} from "./chunk-LZEX2GAY.js";
+} from "./chunk-CV3QQUMK.js";
 import {
   expandToLinkGroup
 } from "./chunk-KYRDKK2D.js";

package/dist/{chunk-LZEX2GAY.js → chunk-CV3QQUMK.js}

@@ -124,6 +124,7 @@ var CaptionRegion = Region.refine(
   "captions style.region must fit within the normalized frame"
 );
 var ClipFit = z2.enum(["cover", "contain"]);
+var CaptionVisibility = z2.enum(["visible", "hidden"]);
 var PerClipEffect = z2.object({
   primitiveId: z2.string().min(1),
   params: z2.record(z2.string(), z2.unknown()).optional()
@@ -166,6 +167,9 @@ var TimelineClip = z2.object({
   position: Position.optional(),
   region: Region.optional(),
   fit: ClipFit.optional(),
+  captionVisibility: CaptionVisibility.optional().describe(
+    "Video media clip only. Hide native captions while this clip is the visible full-frame picture; caption words and timings remain stored and resume when another visible clip takes over."
+  ),
   effects: z2.array(PerClipEffect).optional(),
   transitionIn: Transition.optional(),
   linkGroupId: z2.string().min(1).optional(),
@@ -314,6 +318,18 @@ function captionsAreBehindSubject(captions) {
 function captionWords(c) {
   return c.segments.flatMap((s) => s.words);
 }
+function captionVisibilityIssues(composition) {
+  const issues = [];
+  composition.tracks.forEach((track, trackIndex) => {
+    track.contents.forEach((item, contentIndex) => {
+      if (!("source" in item) || item.captionVisibility === void 0) return;
+      if (track.kind !== "video" || item.source.kind !== "media") {
+        issues.push({ trackIndex, contentIndex });
+      }
+    });
+  });
+  return issues;
+}
 var Composition = z2.object({
   v: z2.literal(1, {
     error: (issue) => issue.input === void 0 ? 'Missing version envelope: add top-level "v": 1 to the composition.' : `Invalid version envelope: top-level "v" must be the literal 1 (got ${JSON.stringify(issue.input)}).`
@@ -332,7 +348,15 @@ var Composition = z2.object({
   accessibility: CompositionAccessibility.optional(),
   ownerOrgId: z2.string().optional(),
   acl: AccessControl.optional()
-}).strict();
+}).strict().superRefine((composition, ctx) => {
+  for (const issue of captionVisibilityIssues(composition)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["tracks", issue.trackIndex, "contents", issue.contentIndex, "captionVisibility"],
+      message: "captionVisibility is supported only on video media clips"
+    });
+  }
+});
 var CompositionAuthorKind = z2.enum(["user", "agent", "import"]);
 var CompositionVersion = z2.object({
   id: z2.string().min(1),
@@ -502,6 +526,7 @@ export {
   Region,
   CaptionRegion,
   ClipFit,
+  CaptionVisibility,
   PerClipEffect,
   KeyframeEasing,
   Keyframe,
@@ -519,6 +544,7 @@ export {
   CompositionCaptions,
   captionsAreBehindSubject,
   captionWords,
+  captionVisibilityIssues,
   Composition,
   CompositionAuthorKind,
   CompositionVersion,

package/dist/{chunk-OVV35ZS2.js → chunk-FSEB4LSU.js}

@@ -2,7 +2,7 @@ import {
   selectAllClips,
   selectAllOverlays,
   selectSceneMarkers
-} from "./chunk-NLXQ7WTH.js";
+} from "./chunk-5JCLZPMV.js";
 
 // ../authoring/src/context/transcript.ts
 var MAX_TRANSCRIPT_CHARS = 6e4;