@cueframe/kernel 0.0.1

package/dist/_members/composition/projection/safe-zones.js

@@ -0,0 +1,99 @@
+/** Bump on ANY change to a profile rect or the broadcast defaults below. The
+ *  render consumer embeds this into renderCacheKey (spec §15) so a profile edit
+ *  invalidates cached renders transitively, the way BAKE_VERSION already does —
+ *  never a remembered manual bump. */
+// v2: platform-name normalization (ig→reels, youtube→shorts) so the suggestion
+// vocabulary resolves to a profile instead of silently falling to broadcast.
+export const SAFE_ZONE_PROFILE_VERSION = "safezones-v2-2026.06.05";
+/** A centered inset of the output rect by `(1 - frac)/2` on every edge. For
+ *  fractions-of-output coordinates this IS the title/action-safe margin and is
+ *  aspect-agnostic (the output rect already carries the aspect). */
+function inset(frac) {
+    const m = (1 - frac) / 2;
+    return { x: m, y: m, w: frac, h: frac };
+}
+const TITLE_SAFE_FRAC = 0.9;
+const ACTION_SAFE_FRAC = 0.93;
+function broadcast() {
+    return { exclusions: [], titleSafe: inset(TITLE_SAFE_FRAC), actionSafe: inset(ACTION_SAFE_FRAC) };
+}
+/**
+ * Platform-UI exclusion rects per (platform, aspect). Fractions of output.
+ * Extend as a platform changes its chrome. Keyed off the suggestion's
+ * `platforms[]` + `format` (the destination the agent already chose).
+ */
+const PROFILES = {
+    tiktok: {
+        "9:16": [
+            { x: 0, y: 0.82, w: 1, h: 0.18 }, // bottom username/caption strip
+            { x: 0.86, y: 0.45, w: 0.14, h: 0.4 }, // right action rail (like/comment/share)
+            { x: 0, y: 0, w: 1, h: 0.06 }, // top (following/for-you tabs)
+        ],
+    },
+    reels: {
+        "9:16": [
+            { x: 0, y: 0.8, w: 1, h: 0.2 }, // bottom caption + audio strip
+            { x: 0.85, y: 0.42, w: 0.15, h: 0.42 }, // right action rail
+        ],
+    },
+    shorts: {
+        "9:16": [
+            { x: 0, y: 0.84, w: 1, h: 0.16 }, // bottom title/channel strip
+            { x: 0.88, y: 0.4, w: 0.12, h: 0.4 }, // right action rail
+        ],
+    },
+};
+/**
+ * Map the suggestion's platform vocabulary (what the agent/clip pass emits) to a
+ * PROFILES key. Suggestions say `ig`/`instagram`/`youtube`; the profile table is
+ * keyed by the surface-with-chrome (`reels`/`shorts`/`tiktok`). Without this, an
+ * `ig` clip silently falls through to broadcast and captions sit under the Reels
+ * UI. Unknown names pass through unchanged (→ broadcast fallback).
+ */
+const PLATFORM_ALIASES = {
+    ig: "reels",
+    instagram: "reels",
+    reels: "reels",
+    igreels: "reels",
+    yt: "shorts",
+    youtube: "shorts",
+    ytshorts: "shorts",
+    shorts: "shorts",
+    tiktok: "tiktok",
+    tt: "tiktok",
+};
+/** Normalize a platform name to a PROFILES key (lowercased, aliased). */
+export function normalizePlatform(platform) {
+    const k = (platform ?? "").trim().toLowerCase();
+    return PLATFORM_ALIASES[k] ?? k;
+}
+/**
+ * Resolve the safe-zone profile for a destination. Unknown platform (or an
+ * aspect a known platform has no profile for) → broadcast title/action-safe only
+ * (no platform exclusions) so the floor degrades to a correct, conservative
+ * result rather than throwing.
+ */
+export function lookupSafeZones(platform, aspect) {
+    const base = broadcast();
+    const key = normalizePlatform(platform);
+    // Exact platform when known; otherwise the UNION of every platform's chrome
+    // for this aspect — so when the destination isn't threaded, captions/overlays
+    // still clear ANY vertical surface's UI (the robust default) rather than
+    // silently dropping to broadcast and sitting under the bottom strip. A
+    // non-social aspect (16:9) has no profiles → union is empty → broadcast.
+    const exclusions = PROFILES[key]?.[aspect] ?? unionExclusionsForAspect(aspect);
+    // Copy the rects so callers can't mutate the shared table.
+    return { ...base, exclusions: exclusions.map((r) => ({ ...r })) };
+}
+/** Every known platform's exclusion rects for an aspect, concatenated. The
+ *  caller (placeInLegalArea) avoids all of them, so overlap is fine — the net
+ *  effect is the most-constraining chrome across platforms. */
+function unionExclusionsForAspect(aspect) {
+    const all = [];
+    for (const platform of Object.keys(PROFILES)) {
+        const ex = PROFILES[platform]?.[aspect];
+        if (ex)
+            all.push(...ex);
+    }
+    return all;
+}

package/dist/_members/composition/reframe/aspectLoss.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Aspect-loss advisory: a source whose shape disagrees with the output frame,
+ * placed with no authored camera.
+ *
+ * A `cover` fill scales the source until it covers the frame and throws the
+ * overflow away, centred. For a 3840×5760 portrait photo in a 16:9 frame that
+ * discards ~62% of the image about the middle — reliably decapitating anyone in
+ * it. In the 2026-08-05 toddler-parks session 15 of 68 imported candidates were
+ * portrait, every one placed into 16:9 with no crop intent, and nothing said a
+ * word at any point in the pipeline.
+ *
+ * Note this is WORSE for stills than the `fit` field suggests: `fit` is not
+ * threaded to the image path at all (MainComposition routes `kind:'image'` to
+ * StillCrop, which has no `fit` prop), so an image is always cropped by the
+ * derived still trajectory — whose faceless default centre is a hardcoded
+ * [0.5, 0.5]. Declaring `fit:"contain"` does not avoid this; authoring a
+ * `reframe` (or a `kenBurns`) does.
+ *
+ * ADVISORY only — same `(input) => string[]` contract as `detectNoAudioTrack`.
+ * Cropping to fill is a legitimate choice; this only says nobody made it.
+ */
+/**
+ * Fraction of the source that survives a `cover` fill. Purely a function of the
+ * two aspect ratios: the narrower dimension is fully used, the wider one is
+ * trimmed to match.
+ */
+export declare function coverVisibleFraction(source: {
+    width: number;
+    height: number;
+}, target: {
+    width: number;
+    height: number;
+}): number;
+/**
+ * Advisory for media placed into a materially different frame shape with no
+ * authored camera.
+ *
+ * `dimensionsByMediaId` is expected to be partial: image dimensions are
+ * populated LAZILY (they are not known at upload /complete), so a media with no
+ * width/height is SKIPPED rather than guessed at — an advisory that fires on
+ * missing metadata would train agents to ignore the channel.
+ */
+export declare function detectAspectCropLoss(composition: unknown, dimensionsByMediaId: Record<string, {
+    width?: number;
+    height?: number;
+} | undefined>, target: {
+    width: number;
+    height: number;
+}): string[];

package/dist/_members/composition/reframe/aspectLoss.js

@@ -0,0 +1,115 @@
+/**
+ * Aspect-loss advisory: a source whose shape disagrees with the output frame,
+ * placed with no authored camera.
+ *
+ * A `cover` fill scales the source until it covers the frame and throws the
+ * overflow away, centred. For a 3840×5760 portrait photo in a 16:9 frame that
+ * discards ~62% of the image about the middle — reliably decapitating anyone in
+ * it. In the 2026-08-05 toddler-parks session 15 of 68 imported candidates were
+ * portrait, every one placed into 16:9 with no crop intent, and nothing said a
+ * word at any point in the pipeline.
+ *
+ * Note this is WORSE for stills than the `fit` field suggests: `fit` is not
+ * threaded to the image path at all (MainComposition routes `kind:'image'` to
+ * StillCrop, which has no `fit` prop), so an image is always cropped by the
+ * derived still trajectory — whose faceless default centre is a hardcoded
+ * [0.5, 0.5]. Declaring `fit:"contain"` does not avoid this; authoring a
+ * `reframe` (or a `kenBurns`) does.
+ *
+ * ADVISORY only — same `(input) => string[]` contract as `detectNoAudioTrack`.
+ * Cropping to fill is a legitimate choice; this only says nobody made it.
+ */
+/**
+ * Fraction of the source that survives a `cover` fill. Purely a function of the
+ * two aspect ratios: the narrower dimension is fully used, the wider one is
+ * trimmed to match.
+ */
+export function coverVisibleFraction(source, target) {
+    const s = source.width / source.height;
+    const t = target.width / target.height;
+    if (!Number.isFinite(s) || !Number.isFinite(t) || s <= 0 || t <= 0)
+        return 1;
+    return Math.min(s, t) / Math.max(s, t);
+}
+/**
+ * Warn below this much of the source surviving. 0.75 = "more than a quarter of
+ * the picture is being thrown away" — comfortably past a 4:3-in-16:9 letterbox
+ * nudge (0.84) and well inside portrait-in-landscape (0.38).
+ */
+const VISIBLE_FRACTION_FLOOR = 0.75;
+/** How many clips to name before eliding. */
+const MAX_NAMED = 6;
+/** Collect every `kind:'media'` clip source, with its enclosing clip's id. */
+function collectMediaClips(value, nearestId, out) {
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectMediaClips(v, nearestId, out);
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    const obj = value;
+    const id = typeof obj.id === "string" ? obj.id : nearestId;
+    if (obj.kind === "media" && typeof obj.mediaId === "string") {
+        const reframe = obj.reframe;
+        const hasReframe = Array.isArray(reframe?.segments) && reframe.segments.length > 0;
+        out.push({
+            mediaId: obj.mediaId,
+            hasCamera: hasReframe || obj.kenBurns != null,
+            ...(id !== undefined ? { clipId: id } : {}),
+        });
+        return;
+    }
+    for (const v of Object.values(obj))
+        collectMediaClips(v, id, out);
+}
+/**
+ * Advisory for media placed into a materially different frame shape with no
+ * authored camera.
+ *
+ * `dimensionsByMediaId` is expected to be partial: image dimensions are
+ * populated LAZILY (they are not known at upload /complete), so a media with no
+ * width/height is SKIPPED rather than guessed at — an advisory that fires on
+ * missing metadata would train agents to ignore the channel.
+ */
+export function detectAspectCropLoss(composition, dimensionsByMediaId, target) {
+    const placed = [];
+    collectMediaClips(composition, undefined, placed);
+    if (placed.length === 0)
+        return [];
+    const offenders = [];
+    const seen = new Set();
+    for (const clip of placed) {
+        if (clip.hasCamera)
+            continue;
+        const dim = dimensionsByMediaId[clip.mediaId];
+        if (!dim?.width || !dim?.height)
+            continue; // dimensions arrive lazily — never guess
+        const visible = coverVisibleFraction({ width: dim.width, height: dim.height }, target);
+        if (visible >= VISIBLE_FRACTION_FLOOR)
+            continue;
+        const label = clip.clipId ?? clip.mediaId;
+        if (seen.has(label))
+            continue;
+        seen.add(label);
+        offenders.push({ label, lostPct: Math.round((1 - visible) * 100) });
+    }
+    if (offenders.length === 0)
+        return [];
+    const worst = offenders.reduce((a, b) => (b.lostPct > a.lostPct ? b : a));
+    const shown = offenders
+        .slice(0, MAX_NAMED)
+        .map((o) => `${o.label} (−${o.lostPct}%)`)
+        .join(", ");
+    const elided = offenders.length > MAX_NAMED ? ` (+${offenders.length - MAX_NAMED} more)` : "";
+    return [
+        `aspect_crop_loss — ${offenders.length} clip${offenders.length === 1 ? "" : "s"} ` +
+            `${offenders.length === 1 ? "is" : "are"} shaped very differently from the ` +
+            `${target.width}×${target.height} output and author no camera, so each is centre-cropped ` +
+            `to fill — discarding up to ${worst.lostPct}% of the picture with faces and subjects as ` +
+            `likely to fall outside the crop as inside it: ${shown}${elided}. Author a \`reframe\` ` +
+            `(focus a face, a point, or all-faces) or a \`kenBurns\` move on these clips, or render a ` +
+            `format closer to their shape. Note \`fit:"contain"\` does NOT avoid this for stills — ` +
+            `images are cropped by the still trajectory, which centres when it has no focus.`,
+    ];
+}

package/dist/_members/composition/reframe/coverage.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Reframe coverage invariant — the SINGLE source of truth for
+ * "a clip's `reframe.segments` MUST tile its PLAYED window: `[0, duration]`
+ * minus the clip's excluded spans" (clip-relative source seconds; segment 0 =
+ * the clip's `trim.start`). An excluded span is never walked by the renderer
+ * (`playableSpans` skips it and rebases across the gap), so it needs NO
+ * reframe coverage — demanding it would reject the compiler's own canonical
+ * trim output (trim → excludedRange + segments tiling the remainder).
+ *
+ * Pure arithmetic, ZERO runtime imports (structural param types only), so it is
+ * safe in BOTH the Convex V8 isolate (save-time `validateReframeCoverage`) AND
+ * the Temporal workflow sandbox (the compose-loop pre-derive gate). One
+ * definition, no drift — the two chokepoints enforce the exact same rule.
+ *
+ * Why it matters: `deriveTrajectory` bakes coverage = the union of the AUTHORED
+ * segments (it clamps, never extends). If the segments leave a gap (a forgotten
+ * head lead-in, or a source-absolute-vs-clip-relative time-base mis-map), the
+ * render walks a played frame no segment covers and `resolveSegmentAt` throws
+ * `trajectory_coverage_gap` deep in the renderer. Catching the gap on this pure
+ * path — where BOTH the played window and the segments are known — turns that
+ * cryptic late crash into an early, actionable, clip-named error.
+ */
+/** Seam-rounding slack: two segments meeting within EPS seconds are contiguous,
+ *  not a gap (matches the fps-conversion tolerance at a segment edge). */
+export declare const REFRAME_COVERAGE_EPS = 0.001;
+/**
+ * The FIRST uncovered `[start, end]` span (in clip-relative source seconds) where
+ * `segments` fail to tile the PLAYED window — `[0, duration]` minus `excluded` —
+ * or `null` when every played instant is covered. Order-independent (sorts a
+ * copy). A legitimate subjectless lead-in is NOT a gap only when it is handled
+ * EXPLICITLY: either a frame-center segment covering it, or an excluded span
+ * removing it from playback (the compiler's trim → excludedRange path). This
+ * helper never invents either (feedback_never_add_fallbacks).
+ *
+ * `excluded` spans are clip-relative like the segments (source-absolute
+ * `excludedRanges` convert via `- trim.start` at the call site). An excluded
+ * instant counts as covered because the renderer never resolves a trajectory
+ * there (`playableSpans` drops it), so the sweep unions segments + exclusions
+ * and any remaining hole is exactly a played-and-uncovered span — the set that
+ * crashes `resolveSegmentAt`.
+ */
+export declare function firstReframeCoverageGap(segments: ReadonlyArray<{
+    startSec: number;
+    endSec: number;
+}>, duration: number, eps?: number, excluded?: ReadonlyArray<{
+    startSec: number;
+    endSec: number;
+}>): readonly [number, number] | null;

package/dist/_members/composition/reframe/coverage.js

@@ -0,0 +1,62 @@
+/**
+ * Reframe coverage invariant — the SINGLE source of truth for
+ * "a clip's `reframe.segments` MUST tile its PLAYED window: `[0, duration]`
+ * minus the clip's excluded spans" (clip-relative source seconds; segment 0 =
+ * the clip's `trim.start`). An excluded span is never walked by the renderer
+ * (`playableSpans` skips it and rebases across the gap), so it needs NO
+ * reframe coverage — demanding it would reject the compiler's own canonical
+ * trim output (trim → excludedRange + segments tiling the remainder).
+ *
+ * Pure arithmetic, ZERO runtime imports (structural param types only), so it is
+ * safe in BOTH the Convex V8 isolate (save-time `validateReframeCoverage`) AND
+ * the Temporal workflow sandbox (the compose-loop pre-derive gate). One
+ * definition, no drift — the two chokepoints enforce the exact same rule.
+ *
+ * Why it matters: `deriveTrajectory` bakes coverage = the union of the AUTHORED
+ * segments (it clamps, never extends). If the segments leave a gap (a forgotten
+ * head lead-in, or a source-absolute-vs-clip-relative time-base mis-map), the
+ * render walks a played frame no segment covers and `resolveSegmentAt` throws
+ * `trajectory_coverage_gap` deep in the renderer. Catching the gap on this pure
+ * path — where BOTH the played window and the segments are known — turns that
+ * cryptic late crash into an early, actionable, clip-named error.
+ */
+/** Seam-rounding slack: two segments meeting within EPS seconds are contiguous,
+ *  not a gap (matches the fps-conversion tolerance at a segment edge). */
+export const REFRAME_COVERAGE_EPS = 1e-3;
+/**
+ * The FIRST uncovered `[start, end]` span (in clip-relative source seconds) where
+ * `segments` fail to tile the PLAYED window — `[0, duration]` minus `excluded` —
+ * or `null` when every played instant is covered. Order-independent (sorts a
+ * copy). A legitimate subjectless lead-in is NOT a gap only when it is handled
+ * EXPLICITLY: either a frame-center segment covering it, or an excluded span
+ * removing it from playback (the compiler's trim → excludedRange path). This
+ * helper never invents either (feedback_never_add_fallbacks).
+ *
+ * `excluded` spans are clip-relative like the segments (source-absolute
+ * `excludedRanges` convert via `- trim.start` at the call site). An excluded
+ * instant counts as covered because the renderer never resolves a trajectory
+ * there (`playableSpans` drops it), so the sweep unions segments + exclusions
+ * and any remaining hole is exactly a played-and-uncovered span — the set that
+ * crashes `resolveSegmentAt`.
+ */
+export function firstReframeCoverageGap(segments, duration, eps = REFRAME_COVERAGE_EPS, excluded = []) {
+    if (duration <= eps)
+        return null; // a zero/degenerate window has nothing to tile
+    const covered = [...segments, ...excluded].sort((a, b) => a.startSec - b.startSec);
+    let cursor = 0;
+    for (const span of covered) {
+        // Spans at/after the window end are outside the coverage domain — a
+        // malformed exclusion like [duration+0.5, …] must not manufacture a
+        // phantom gap [duration, span.start] on a fully-tiled window (the save
+        // guard separately rejects out-of-trim exclusions; THIS helper only
+        // answers coverage). Sorted input → nothing later can matter either.
+        if (span.startSec >= duration - eps)
+            break;
+        if (span.startSec > cursor + eps)
+            return [cursor, span.startSec]; // head / interior gap
+        cursor = Math.max(cursor, span.endSec);
+    }
+    if (cursor < duration - eps)
+        return [cursor, duration]; // tail gap
+    return null;
+}

package/dist/_members/composition/reframe/derive.d.ts

@@ -0,0 +1,37 @@
+/**
+ * derive — PURE multi-format derivation core (P5). Produce a reframed SIBLING
+ * composition for a new target Format: copy authored intent verbatim, set the
+ * new `format`, and author a GEOMETRIC single-subject `reframe` on every media
+ * clip that doesn't already carry one. Aspect-specific crop-window geometry,
+ * caption-band reserve, and width-anchored brand are re-resolved DOWNSTREAM at
+ * render from `composition.format` (deriveTrajectory + compositionFormatDimensions)
+ * — this module never touches them. Single-subject focus is aspect-independent.
+ *
+ * Group/editorial refinement (e.g. all-faces → active-speaker for a narrower
+ * aspect) is the explicit follow-on: an existing reframe is copied verbatim and
+ * the render honestly pads-and-holds (overframed) for the new aspect.
+ */
+import type { Composition, Format } from "../validators/composition.js";
+import type { Focus } from "./index.js";
+/** The inline face roster cached on `mediaItems.subjectTracks[windowHash].faces`. */
+export interface RosterFace {
+    faceId: string;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    speakingShare?: number;
+}
+export type ClipFaceRoster = RosterFace[];
+/** Output FormatSpec the caller targets (no `platform` — preserved from source). */
+export type TargetFormat = Pick<Format, "aspectRatio" | "fps" | "resolution">;
+/**
+ * Geometric single-subject focus for the target aspect:
+ *  - no faces → frame-center (screen-recording / faceless b-roll; honest center crop).
+ *  - 2+ faces carry a speakingShare signal → active-speaker (the wedge follows the speaker).
+ *  - otherwise → the single largest detected face (dominant subject).
+ */
+export declare function pickGeometricFocus(faces: ClipFaceRoster | undefined): Focus;
+export declare function deriveReframedComposition(source: Composition, targetFormat: TargetFormat, perceptionByClipId: Record<string, ClipFaceRoster>): Composition;

package/dist/_members/composition/reframe/derive.js

@@ -0,0 +1,73 @@
+const area = (f) => Math.max(0, f.bbox.width) * Math.max(0, f.bbox.height);
+/**
+ * Geometric single-subject focus for the target aspect:
+ *  - no faces → frame-center (screen-recording / faceless b-roll; honest center crop).
+ *  - 2+ faces carry a speakingShare signal → active-speaker (the wedge follows the speaker).
+ *  - otherwise → the single largest detected face (dominant subject).
+ */
+export function pickGeometricFocus(faces) {
+    if (!faces || faces.length === 0)
+        return { mode: "frame-center" };
+    const withSpeaking = faces.filter((f) => typeof f.speakingShare === "number");
+    if (faces.length >= 2 && withSpeaking.length >= 2)
+        return { mode: "active-speaker" };
+    // Equal-area tie-break: Array.prototype.sort is STABLE (ES2019+), so ties keep
+    // roster order and `[0]` resolves to the FIRST-in-roster face — a deterministic
+    // pick that P5.3 content-addressing relies on.
+    const dominant = [...faces].sort((a, b) => area(b) - area(a))[0];
+    return { mode: "face", faceId: dominant.faceId };
+}
+/** Clip-relative full-clip span [0, duration]. deriveTrajectory indexes segments
+ *  clip-relative (frame 0 = the clip's source-window start). */
+function fullClipDurationSec(content) {
+    const d = content.duration;
+    if (typeof d === "number" && d > 0)
+        return d;
+    const trim = content.source?.trim;
+    if (trim && typeof trim.start === "number" && typeof trim.end === "number" && trim.end > trim.start) {
+        return trim.end - trim.start;
+    }
+    return 0;
+}
+export function deriveReframedComposition(source, targetFormat, perceptionByClipId) {
+    // Deep copy so the source row is never mutated (structuredClone is available in
+    // the V8 isolate + Node test runtime; the wire shape is plain JSON).
+    const out = structuredClone(source);
+    // Format = target aspect; fps/resolution default to source (intrinsic to the
+    // edit unless the caller overrides); platform carried over from source.
+    out.format = {
+        aspectRatio: targetFormat.aspectRatio,
+        ...(targetFormat.fps ?? source.format.fps ? { fps: (targetFormat.fps ?? source.format.fps) } : {}),
+        ...(targetFormat.resolution ?? source.format.resolution
+            ? { resolution: (targetFormat.resolution ?? source.format.resolution) }
+            : {}),
+        ...(source.format.platform ? { platform: source.format.platform } : {}),
+    };
+    for (const track of out.tracks) {
+        // Audio clips are MediaClipSource too (`source.kind === "media"`) but live on
+        // audio tracks — a geometric viewport reframe is meaningless for sound, so skip
+        // the whole track. Target AUDIO specifically: IMAGE clips are also `kind:"media"`
+        // and legitimately keep a pan/zoom reframe, so this is not a "non-video" skip.
+        if (track.kind === "audio")
+            continue;
+        const contents = track.contents;
+        if (!Array.isArray(contents))
+            continue;
+        for (const content of contents) {
+            const src = content.source;
+            if (!src || src.kind !== "media")
+                continue; // overlay/component untouched
+            if (src.reframe)
+                continue; // already authored → copied verbatim
+            const dur = fullClipDurationSec(content);
+            if (dur <= 0)
+                continue; // degenerate clip: no crop target
+            const clipId = content.id;
+            const roster = typeof clipId === "string" ? perceptionByClipId[clipId] : undefined;
+            src.reframe = {
+                segments: [{ startSec: 0, endSec: dur, focus: pickGeometricFocus(roster), zoom: 1 }],
+            };
+        }
+    }
+    return out;
+}