@cueframe/kernel 0.2.47 → 0.2.48

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

@@ -1,6 +1,19 @@
 import type { Composition } from "../../composition/validators/index.js";
-import type { CompositionAudioTrack, CompositionClip, CompositionOverlay, RenderInput } from "./types.js";
+import type { CompositionAudioTrack, CompositionClip, CompositionEffect, CompositionOverlay, RenderInput } from "./types.js";
 export declare function applyRoleDefaultGains(audioTracks: CompositionAudioTrack[], composition: Composition): void;
 export declare function applyDuckEnvelopes(audioTracks: CompositionAudioTrack[], composition: Composition, fps: number): void;
 export declare function bindBehindSubjectHosts(overlays: CompositionOverlay[], clips: readonly CompositionClip[]): void;
-export declare function assertBehindSubjectCaptionCoverage(captionSegments: RenderInput['captionSegments'], clips: readonly CompositionClip[], fps: number): void;
+export declare function assertBehindSubjectCaptionCoverage(captionSegments: RenderInput['captionSegments'], clips: readonly CompositionClip[], fps: number, output: {
+    width: number;
+    height: number;
+}, effects?: readonly CompositionEffect[]): void;
+/** 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: {
+    width: number;
+    height: number;
+}, effects?: readonly CompositionEffect[]): Array<{
+    startFrame: number;
+    endFrame: number;
+    hostClipId?: string;
+    candidateClipIds: string[];
+}>;

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

@@ -3,7 +3,7 @@ import type { RenderInput } from "./types.js";
 import type { TrajectoryData } from "../../composition/reframe/trajectory.js";
 import { type PreparedRenderInputLeaseV1, type SceneShotPreparationDependenciesV1 } from "./sceneShotPreparation.js";
 export { validateComposition } from "./compositionValidation.js";
-export { assertBehindSubjectCaptionCoverage } from "./compositionAudioAndDepth.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";
 export declare function compositionFormatDimensions(format: Format): {
@@ -20,6 +20,11 @@ export declare function compositionToRenderInput(composition: Composition, srcUr
      * no scene lane.
      */
     isSceneClip?: (clip: WireClip) => boolean;
+    /** Dimensions of source media, keyed by mediaId. Missing or invalid values remain unprojected. */
+    sourceDimensions?: Record<string, {
+        width: number;
+        height: number;
+    }>;
 }): RenderInput;
 /**
  * Projection plus the host's resolved bindings. When the host pins `componentSources`, every
@@ -51,6 +56,10 @@ export declare function assembleRenderInput(composition: Composition, resolved:
     coViewUrls?: Record<string, string>;
     alphaUrls?: Record<string, string>;
     trajectories?: Record<string, TrajectoryData>;
+    sourceDimensions?: Record<string, {
+        width: number;
+        height: number;
+    }>;
     fontAssets?: NonNullable<RenderInput["brandKit"]>["fontAssets"];
     componentSources?: RenderInput["componentSources"];
 }): RenderInput;

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, } from './compositionRender.js';
+export { compositionToRenderInput, referencedMediaIds, assembleRenderInput, assemblePreparedRenderInput, validateComposition, compositionFormatDimensions, 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/trackProjection.d.ts

@@ -44,7 +44,10 @@ export declare function projectMediaPlaybackSpans({ startTime, duration, trim, e
     timelineStartFrames: number;
     durationInFrames: number;
 }>;
-export declare function projectMediaTrack(track: Track, trackIndex: number, trackCount: number, fps: number, srcUrls: Record<string, string>, trajectoryUrls?: Record<string, string>, coViewUrls?: Record<string, string>, trajectories?: Record<string, TrajectoryData>): {
+export declare function projectMediaTrack(track: Track, trackIndex: number, trackCount: number, fps: number, srcUrls: Record<string, string>, trajectoryUrls?: Record<string, string>, coViewUrls?: Record<string, string>, trajectories?: Record<string, TrajectoryData>, sourceDimensions?: Record<string, {
+    width: number;
+    height: number;
+}>): {
     clips: CompositionClip[];
     audio: CompositionAudioTrack[];
     effects: CompositionEffect[];

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

@@ -45,6 +45,9 @@ export interface CompositionClip extends ProjectedVisualIdentity {
     previewSrc?: string;
     sourceInFrames: number;
     sourceOutFrames: number;
+    /** Intrinsic media dimensions from the admitted media pool; absent when unverified. */
+    sourceWidth?: number;
+    sourceHeight?: number;
     timelineStartFrames: number;
     durationInFrames: number;
     trimStartFrames?: number;

package/dist/{chunk-KCXADPOC.js → chunk-GI2NTS6B.js}

@@ -3,7 +3,7 @@ import {
   projectMediaPlaybackSpans,
   sliceTranscriptWords,
   splitIntoSentences
-} from "./chunk-FEG264CF.js";
+} from "./chunk-INYP56TC.js";
 import {
   createHeadlessStore,
   findClipById,

package/dist/{chunk-FEG264CF.js → chunk-INYP56TC.js}

@@ -1223,30 +1223,93 @@ function bindBehindSubjectHosts(overlays, clips) {
     );
   }
 }
-function assertBehindSubjectCaptionCoverage(captionSegments, clips, fps) {
-  const packed = clips.filter((clip) => clip.packedUrl !== void 0);
+function assertBehindSubjectCaptionCoverage(captionSegments, clips, fps, output, effects = []) {
   for (const segment of captionSegments ?? []) {
     for (const word of segment) {
       const startFrame = Math.round(word.startMs / 1e3 * fps);
       const endFrame = Math.max(startFrame + 1, Math.round(word.endMs / 1e3 * fps));
-      const covering = packed.filter((clip) => {
-        const clipEnd = clip.timelineStartFrames + clip.durationInFrames;
-        return clip.timelineStartFrames <= startFrame && clipEnd >= endFrame;
-      });
-      if (covering.length === 1) continue;
-      const overlapping = packed.filter((clip) => {
-        const clipEnd = clip.timelineStartFrames + clip.durationInFrames;
-        return clip.timelineStartFrames < endFrame && clipEnd > startFrame;
+      for (const window of visiblePackedHostWindows(clips, startFrame, endFrame, output, effects)) {
+        if (window.hostClipId) continue;
+        const code = window.candidateClipIds.length > 1 ? "behind_subject_caption_host_ambiguous" : "behind_subject_caption_host_missing";
+        throw renderInputError(
+          code,
+          `Behind-subject caption word '${word.text}' is not fully covered by a unique visible packed host during frames [${window.startFrame}, ${window.endFrame}); an exact matte is required for the visible picture.`,
+          { candidateClipIds: window.candidateClipIds, startFrame: window.startFrame, endFrame: window.endFrame }
+        );
+      }
+    }
+  }
+}
+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);
+}
+function pictureRect(clip, output, effects) {
+  if (clip.cropTrajectory || clip.cropTrajectoryUrl || hasClipEffect(clip, effects)) return void 0;
+  if (clip.fit !== "contain") return FULL_RECT;
+  const sourceWidth = clip.sourceWidth;
+  const sourceHeight = clip.sourceHeight;
+  if (!sourceWidth || !sourceHeight || !output.width || !output.height) return void 0;
+  const sourceAspect = sourceWidth / sourceHeight;
+  const outputAspect = output.width / output.height;
+  if (sourceAspect >= outputAspect) {
+    const pictureHeight = outputAspect / sourceAspect;
+    return { left: 0, right: 1, top: (1 - pictureHeight) / 2, bottom: (1 + pictureHeight) / 2 };
+  }
+  const pictureWidth = sourceAspect / outputAspect;
+  return { left: (1 - pictureWidth) / 2, right: (1 + pictureWidth) / 2, top: 0, bottom: 1 };
+}
+function coversLowerPictures(upper, lower, output, effects) {
+  const upperRect = pictureRect(upper, output, effects);
+  if (!upperRect) return false;
+  const epsilon = 1e-6;
+  return lower.every((clip) => {
+    const rect = pictureRect(clip, output, effects) ?? FULL_RECT;
+    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 = []) {
+  if (endFrame <= startFrame) return [];
+  const boundaries = /* @__PURE__ */ new Set([startFrame, endFrame]);
+  for (const clip of clips) {
+    const start = clip.timelineStartFrames;
+    const end = start + clip.durationInFrames;
+    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++) {
+    const start = points[i];
+    const end = points[i + 1];
+    const active = clips.filter(
+      (clip) => clip.timelineStartFrames <= start && clip.timelineStartFrames + clip.durationInFrames >= end
+    );
+    const topLayer = Math.max(...active.map((clip) => clip.layerIndex));
+    const top = active.filter((clip) => clip.layerIndex === topLayer);
+    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],
+      active.filter((clip) => clip !== top[0]),
+      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 previous = windows[windows.length - 1];
+    if (previous && previous.endFrame === start && previous.hostClipId === host?.id && previous.candidateClipIds.join("\0") === candidates.join("\0")) {
+      previous.endFrame = end;
+    } else {
+      windows.push({
+        startFrame: start,
+        endFrame: end,
+        ...host ? { hostClipId: host.id } : {},
+        candidateClipIds: candidates
       });
-      const candidates = covering.length > 1 ? covering : overlapping;
-      const code = candidates.length > 1 ? "behind_subject_caption_host_ambiguous" : "behind_subject_caption_host_missing";
-      throw renderInputError(
-        code,
-        candidates.length > 1 ? `Behind-subject caption word '${word.text}' is covered by multiple packed clips (${candidates.map((clip) => clip.id).join(", ")}).` : `Behind-subject caption word '${word.text}' is not fully covered by one packed clip; an exact matte is required for its entire interval.`,
-        { candidateClipIds: candidates.map((clip) => clip.id), startFrame, endFrame }
-      );
     }
   }
+  return windows;
 }
 
 // ../execution/core/src/render/trackProjection.ts
@@ -1374,7 +1437,7 @@ function projectMediaPlaybackSpans({
     };
   });
 }
-function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajectoryUrls, coViewUrls, trajectories) {
+function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajectoryUrls, coViewUrls, trajectories, sourceDimensions) {
   const clips = [];
   const audio = [];
   const effects = [];
@@ -1395,6 +1458,8 @@ function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajecto
       compositionPath: `composition.tracks[${track.id}].contents[${i}].source.mediaId`
     });
     const packedUrl = coViewUrls?.[c.id];
+    const dimensions = sourceDimensions?.[c.source.mediaId];
+    const validDimensions = dimensions !== void 0 && Number.isFinite(dimensions.width) && dimensions.width > 0 && Number.isFinite(dimensions.height) && dimensions.height > 0;
     const packedEnvelopeFields = packedUrl === void 0 ? [] : [
       c.region !== void 0 && !(c.region.x === 0 && c.region.y === 0 && c.region.w === 1 && c.region.h === 1) ? "region" : null,
       c.opacity !== void 0 && c.opacity !== 1 ? "opacity" : null,
@@ -1461,6 +1526,10 @@ function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajecto
         src,
         sourceInFrames: span.sourceInFrames,
         sourceOutFrames: span.sourceOutFrames,
+        ...validDimensions ? {
+          sourceWidth: dimensions.width,
+          sourceHeight: dimensions.height
+        } : {},
         timelineStartFrames: timelineCursorFrames,
         durationInFrames: subDurationFrames,
         trimStartFrames: frames(c.source.trim?.start ?? 0, fps),
@@ -1816,7 +1885,8 @@ function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUr
         srcUrls,
         trajectoryUrls,
         coViewUrls,
-        trajectories
+        trajectories,
+        options?.sourceDimensions
       );
       clips.push(...c);
       audioTracks.push(...audio);
@@ -1876,7 +1946,7 @@ function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUr
   const bodyDurationInFrames = maxBackgroundEndFrames > 0 ? Math.min(maxEndFrames, maxBackgroundEndFrames) : maxEndFrames;
   const captionSegments = composition.captions?.segments.map((seg) => seg.words).filter((words) => words.length > 0);
   if (composition.captions?.zPlane === "behind-subject") {
-    assertBehindSubjectCaptionCoverage(captionSegments, clips, fps);
+    assertBehindSubjectCaptionCoverage(captionSegments, clips, fps, { width, height }, effects);
   }
   const brandKit = composition.brandKit;
   const { totalFrames: durationInFrames } = resolveBookendTimeline(
@@ -1956,7 +2026,10 @@ function assembleRenderInput(composition, resolved) {
     resolved.trajectories,
     // The same manifest-backed answer the shape rules used, so projection cannot floor a scene
     // clip's boundary into a length the rules above would have refused.
-    resolveSource ? { isSceneClip: (clip) => isSceneShotClip(clip, resolveSource) } : void 0
+    {
+      ...resolveSource ? { isSceneClip: (clip) => isSceneShotClip(clip, resolveSource) } : {},
+      sourceDimensions: resolved.sourceDimensions
+    }
   );
   if (renderInput.brandKit && resolved.fontAssets && resolved.fontAssets.length > 0) {
     renderInput.brandKit.fontAssets = resolved.fontAssets;
@@ -2973,6 +3046,7 @@ export {
   resolveBookendTimeline,
   validateComposition,
   assertBehindSubjectCaptionCoverage,
+  visiblePackedHostWindows,
   playableSpans,
   projectMediaPlaybackSpans,
   compositionFormatDimensions,

package/dist/{chunk-OYWX4NEP.js → chunk-TBZU7JYA.js}

@@ -31,7 +31,7 @@ import {
 } from "./chunk-AOIY7NGF.js";
 import {
   CompositionOp
-} from "./chunk-KCXADPOC.js";
+} from "./chunk-GI2NTS6B.js";
 
 // ../mcp/src/prompts.ts
 var skillListCache = null;

package/dist/composition-ops.js

@@ -20,8 +20,8 @@ import {
   replaceRegion,
   resolveClipKind,
   wrapWithOpRecorder
-} from "./chunk-KCXADPOC.js";
-import "./chunk-FEG264CF.js";
+} from "./chunk-GI2NTS6B.js";
+import "./chunk-INYP56TC.js";
 import "./chunk-QH3YI3ND.js";
 import "./chunk-JPMVNMF3.js";
 import "./chunk-IMIUHG2E.js";

package/dist/core/render.js

@@ -66,8 +66,9 @@ import {
   selectedFaceCenter,
   sliceTranscriptWords,
   splitIntoSentences,
-  validateComposition
-} from "../chunk-FEG264CF.js";
+  validateComposition,
+  visiblePackedHostWindows
+} from "../chunk-INYP56TC.js";
 import {
   buildEasedZooms,
   buildPannedCenters,
@@ -156,5 +157,6 @@ export {
   selectedFaceCenter,
   sliceTranscriptWords,
   splitIntoSentences,
-  validateComposition
+  validateComposition,
+  visiblePackedHostWindows
 };

package/dist/core.js

@@ -10,7 +10,7 @@ import {
   ensureEven,
   extractCaptionWordsFromDoc,
   isEmphasized
-} from "./chunk-FEG264CF.js";
+} from "./chunk-INYP56TC.js";
 import "./chunk-QH3YI3ND.js";
 import "./chunk-JPMVNMF3.js";
 import "./chunk-IMIUHG2E.js";

package/dist/mcp/server.js

@@ -8,13 +8,13 @@ import {
   registerRawTools,
   registerSkillPrompts,
   titleCase
-} from "../chunk-OYWX4NEP.js";
+} from "../chunk-TBZU7JYA.js";
 import "../chunk-FYS2XUKJ.js";
 import "../chunk-XSBVOXSB.js";
 import "../chunk-CFIQY4OE.js";
 import "../chunk-AOIY7NGF.js";
-import "../chunk-KCXADPOC.js";
-import "../chunk-FEG264CF.js";
+import "../chunk-GI2NTS6B.js";
+import "../chunk-INYP56TC.js";
 import "../chunk-QH3YI3ND.js";
 import "../chunk-JPMVNMF3.js";
 import "../chunk-IMIUHG2E.js";

package/dist/mcp.js

@@ -8,13 +8,13 @@ import {
   buildServer,
   registerCuratedTools,
   registerRawTools
-} from "./chunk-OYWX4NEP.js";
+} from "./chunk-TBZU7JYA.js";
 import "./chunk-FYS2XUKJ.js";
 import "./chunk-XSBVOXSB.js";
 import "./chunk-CFIQY4OE.js";
 import "./chunk-AOIY7NGF.js";
-import "./chunk-KCXADPOC.js";
-import "./chunk-FEG264CF.js";
+import "./chunk-GI2NTS6B.js";
+import "./chunk-INYP56TC.js";
 import "./chunk-QH3YI3ND.js";
 import "./chunk-JPMVNMF3.js";
 import "./chunk-IMIUHG2E.js";

package/dist/render-harness.js

@@ -46,7 +46,7 @@ import {
   parseSceneComponentCaptureIntentV1,
   prepareSceneShotRenderInput,
   readSceneShotManifest
-} from "./chunk-FEG264CF.js";
+} from "./chunk-INYP56TC.js";
 import "./chunk-QH3YI3ND.js";
 import "./chunk-JPMVNMF3.js";
 import "./chunk-IMIUHG2E.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueframe/kernel",
-  "version": "0.2.47",
+  "version": "0.2.48",
   "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": [
@@ -16,25 +16,25 @@
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.9.3",
-    "@cueframe/account-model": "0.1.0",
-    "@cueframe/animate": "0.1.0",
     "@cueframe/authoring": "0.1.0",
-    "@cueframe/cloud-import": "0.1.0",
-    "@cueframe/brand-derivation": "0.1.0",
-    "@cueframe/component-runtime": "0.1.0",
+    "@cueframe/account-model": "0.1.0",
     "@cueframe/compose": "0.1.0",
-    "@cueframe/core": "0.1.0",
+    "@cueframe/composition": "0.1.0",
+    "@cueframe/cloud-import": "0.1.0",
     "@cueframe/director": "0.1.0",
-    "@cueframe/errors": "0.1.0",
     "@cueframe/composition-ops": "0.1.0",
-    "@cueframe/nle-export": "0.1.0",
+    "@cueframe/animate": "0.1.0",
+    "@cueframe/brand-derivation": "0.1.0",
     "@cueframe/foundation": "0.1.0",
+    "@cueframe/perception": "0.1.0",
     "@cueframe/mcp": "0.1.0",
+    "@cueframe/errors": "0.1.0",
+    "@cueframe/component-runtime": "0.1.0",
     "@cueframe/media-model": "0.1.0",
-    "@cueframe/composition": "0.1.0",
-    "@cueframe/perception": "0.1.0",
-    "@cueframe/render-harness": "0.1.0",
     "@cueframe/primitives": "0.1.0",
+    "@cueframe/nle-export": "0.1.0",
+    "@cueframe/core": "0.1.0",
+    "@cueframe/render-harness": "0.1.0",
     "@cueframe/plane": "0.1.0"
   },
   "peerDependencies": {