@cueframe/kernel 0.0.1

package/dist/_members/core/render/eval/metrics.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Reframe eval metrics — pure, label-free, deterministic.
+ *
+ * Tier 1 (HARD CI BLOCKERS, no human labels): `jitter` + the center-crop
+ * comparison. These are what gate the build per the virtual-camera spec —
+ * "jitter-beats-center-crop is the only ship-blocker".
+ *
+ * Tier 2 (REPORTED, not blocking): `mIoU` — scaffolded + reported, NOT a gate,
+ * because per-frame human ground-truth boxes don't exist yet (RESOLVED #3).
+ *
+ * `jitter` = mean over frames of the absolute frame-to-frame difference of the
+ * composed crop box (center x/y AND size), in output-crop-normalized units. The
+ * per-component delta is normalized by the box's own size, so the metric is
+ * zoom-invariant: a half-window pan reads the same number at any zoom (the spec's
+ * "held feel is zoom-invariant" requirement). Lower is smoother. A static crop
+ * has zero pan jitter; the only motion it carries is the per-shot `zoom_scale`
+ * steps, which both paths share — so `jitter(ours) ≤ jitter(centerCrop)` isolates
+ * "where the camera points" as the sole variable.
+ */
+import type { CropBox } from './cropBox.js';
+/** Per-channel jitter breakdown (so a regression points at center vs zoom). */
+export interface JitterBreakdown {
+    /** Mean |Δ| of the window center, normalized by window size (output-crop units). */
+    center: number;
+    /** Mean |Δ| of the window size (zoom channel), normalized by mean window size. */
+    zoom: number;
+    /** Combined center + zoom mean absolute step — the headline jitter scalar. */
+    total: number;
+    /** The single largest per-frame center step (output-crop units) — teleport guard. */
+    maxCenterStep: number;
+}
+/**
+ * Jitter of a composed crop-box series. Empty / single-frame series → all zeros
+ * (no motion to measure). The center delta is divided by the per-frame window
+ * size so it is expressed in fractions of the crop window (output-crop space);
+ * the zoom delta is divided by the mean window size for the same normalization.
+ */
+export declare function jitter(boxes: CropBox[]): JitterBreakdown;
+/** Intersection-over-union of two source-normalized crop boxes. */
+export declare function iou(a: CropBox, b: CropBox): number;
+/**
+ * mIoU + IoU@0.5 vs a per-frame ground-truth crop-box series (Tier 2, REPORTED
+ * only). Scaffolded now so the harness emits a number the moment labels exist;
+ * NOT a CI gate (no hand-labeled fixtures yet — RESOLVED #3). Lengths must match.
+ */
+export declare function mIoU(ours: CropBox[], groundTruth: CropBox[]): {
+    mIoU: number;
+    iouAt50: number;
+    n: number;
+};

package/dist/_members/core/render/eval/metrics.js

@@ -0,0 +1,94 @@
+/**
+ * Reframe eval metrics — pure, label-free, deterministic.
+ *
+ * Tier 1 (HARD CI BLOCKERS, no human labels): `jitter` + the center-crop
+ * comparison. These are what gate the build per the virtual-camera spec —
+ * "jitter-beats-center-crop is the only ship-blocker".
+ *
+ * Tier 2 (REPORTED, not blocking): `mIoU` — scaffolded + reported, NOT a gate,
+ * because per-frame human ground-truth boxes don't exist yet (RESOLVED #3).
+ *
+ * `jitter` = mean over frames of the absolute frame-to-frame difference of the
+ * composed crop box (center x/y AND size), in output-crop-normalized units. The
+ * per-component delta is normalized by the box's own size, so the metric is
+ * zoom-invariant: a half-window pan reads the same number at any zoom (the spec's
+ * "held feel is zoom-invariant" requirement). Lower is smoother. A static crop
+ * has zero pan jitter; the only motion it carries is the per-shot `zoom_scale`
+ * steps, which both paths share — so `jitter(ours) ≤ jitter(centerCrop)` isolates
+ * "where the camera points" as the sole variable.
+ */
+/**
+ * Jitter of a composed crop-box series. Empty / single-frame series → all zeros
+ * (no motion to measure). The center delta is divided by the per-frame window
+ * size so it is expressed in fractions of the crop window (output-crop space);
+ * the zoom delta is divided by the mean window size for the same normalization.
+ */
+export function jitter(boxes) {
+    if (boxes.length < 2) {
+        return { center: 0, zoom: 0, total: 0, maxCenterStep: 0 };
+    }
+    let centerAcc = 0;
+    let zoomAcc = 0;
+    let maxCenterStep = 0;
+    let wSum = 0;
+    let hSum = 0;
+    for (const b of boxes) {
+        wSum += b.w;
+        hSum += b.h;
+    }
+    const meanW = wSum / boxes.length || 1e-6;
+    const meanH = hSum / boxes.length || 1e-6;
+    for (let i = 1; i < boxes.length; i++) {
+        const a = boxes[i - 1];
+        const b = boxes[i];
+        // Center delta in output-crop units: source-normalized delta ÷ window size
+        // (so it's a fraction of the visible window, not of the whole source).
+        const dxOut = Math.abs(b.cx - a.cx) / Math.max(b.w, 1e-6);
+        const dyOut = Math.abs(b.cy - a.cy) / Math.max(b.h, 1e-6);
+        const step = dxOut + dyOut;
+        centerAcc += step;
+        if (step > maxCenterStep)
+            maxCenterStep = step;
+        // Zoom (window-size) delta, normalized by the mean window size.
+        zoomAcc += Math.abs(b.w - a.w) / meanW + Math.abs(b.h - a.h) / meanH;
+    }
+    const denom = boxes.length - 1;
+    const center = centerAcc / denom;
+    const zoom = zoomAcc / denom;
+    return { center, zoom, total: center + zoom, maxCenterStep };
+}
+/** Intersection-over-union of two source-normalized crop boxes. */
+export function iou(a, b) {
+    const ax1 = a.cx - a.w / 2;
+    const ax2 = a.cx + a.w / 2;
+    const ay1 = a.cy - a.h / 2;
+    const ay2 = a.cy + a.h / 2;
+    const bx1 = b.cx - b.w / 2;
+    const bx2 = b.cx + b.w / 2;
+    const by1 = b.cy - b.h / 2;
+    const by2 = b.cy + b.h / 2;
+    const ix = Math.max(0, Math.min(ax2, bx2) - Math.max(ax1, bx1));
+    const iy = Math.max(0, Math.min(ay2, by2) - Math.max(ay1, by1));
+    const inter = ix * iy;
+    const union = a.w * a.h + b.w * b.h - inter;
+    return union > 0 ? inter / union : 0;
+}
+/**
+ * mIoU + IoU@0.5 vs a per-frame ground-truth crop-box series (Tier 2, REPORTED
+ * only). Scaffolded now so the harness emits a number the moment labels exist;
+ * NOT a CI gate (no hand-labeled fixtures yet — RESOLVED #3). Lengths must match.
+ */
+export function mIoU(ours, groundTruth) {
+    const n = Math.min(ours.length, groundTruth.length);
+    if (n === 0)
+        return { mIoU: 0, iouAt50: 0, n: 0 };
+    let sum = 0;
+    let hits = 0;
+    for (let i = 0; i < n; i++) {
+        const v = iou(ours[i], groundTruth[i]);
+        sum += v;
+        if (v >= 0.5)
+            hits++;
+    }
+    return { mIoU: sum / n, iouAt50: hits / n, n };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Export settings types and constants shared between desktop and cloud render paths.
+ * Extracted from cueframe/src/store/exportStore.ts — pure functions, no store deps.
+ */
+import type { CaptionStyle } from './types.js';
+export type ExportQuality = 'maximum' | 'social' | 'web' | 'potato' | 'source';
+export type ExportFormat = 'source' | '16:9' | '9:16' | '4:5' | '1:1';
+export type ExportResolution = 'source' | '1080p' | '1440p' | '4k';
+export interface FormatPreset {
+    label: string;
+    aspectWidth: number;
+    aspectHeight: number;
+}
+export interface RenderSettings {
+    format?: ExportFormat;
+    quality?: ExportQuality;
+    resolution?: ExportResolution;
+    watermark?: boolean;
+    captionsEnabled?: boolean;
+    captionStyle?: Partial<CaptionStyle>;
+}
+export declare const DEFAULT_FPS = 30;
+export declare const DEFAULT_WIDTH = 1920;
+export declare const DEFAULT_HEIGHT = 1080;
+export declare const DEFAULT_RENDER_SETTINGS: Required<Pick<RenderSettings, 'format' | 'quality' | 'resolution' | 'watermark' | 'captionsEnabled'>>;
+export declare const FORMAT_PRESETS: Record<Exclude<ExportFormat, 'source'>, FormatPreset>;
+export declare const RESOLUTION_PRESETS: Record<Exclude<ExportResolution, 'source'>, {
+    label: string;
+    height: number;
+}>;
+/** Convert a BPP value to an approximate CRF (H.264). */
+export declare function bppToCrf(bpp: number): number;
+/** Compute output dimensions and CRF from source dims + quality preset. */
+export declare function computeExportDimensions(sourceWidth: number, sourceHeight: number, format: ExportFormat, quality: ExportQuality): {
+    width: number;
+    height: number;
+    crf: number | undefined;
+};
+/** Ensure a dimension is even (required by most codecs). */
+export declare function ensureEven(n: number): number;

package/dist/_members/core/render/exportSettings.js

@@ -0,0 +1,65 @@
+// ── Constants ──────────────────────────────────────────────────────────────
+export const DEFAULT_FPS = 30;
+export const DEFAULT_WIDTH = 1920;
+export const DEFAULT_HEIGHT = 1080;
+export const DEFAULT_RENDER_SETTINGS = {
+    format: 'source',
+    quality: 'source',
+    resolution: 'source',
+    watermark: false,
+    captionsEnabled: true,
+};
+export const FORMAT_PRESETS = {
+    '16:9': { label: 'Landscape', aspectWidth: 16, aspectHeight: 9 },
+    '9:16': { label: 'TikTok / Reels', aspectWidth: 9, aspectHeight: 16 },
+    '4:5': { label: 'Instagram Portrait', aspectWidth: 4, aspectHeight: 5 },
+    '1:1': { label: 'Square', aspectWidth: 1, aspectHeight: 1 },
+};
+export const RESOLUTION_PRESETS = {
+    '1080p': { label: '1080p (Full HD)', height: 1080 },
+    '1440p': { label: '1440p (2K)', height: 1440 },
+    '4k': { label: '4K (Ultra HD)', height: 2160 },
+};
+// BPP (bits-per-pixel) presets — scales encoding quality proportionally to
+// resolution so file sizes are predictable across 720p through 4K.
+const BPP = {
+    maximum: 0.3,
+    social: 0.15,
+    web: 0.08,
+    potato: 0.04,
+};
+// ── Functions ──────────────────────────────────────────────────────────────
+/** Convert a BPP value to an approximate CRF (H.264). */
+export function bppToCrf(bpp) {
+    return Math.max(15, Math.min(36, Math.round(51 - bpp * 120)));
+}
+/** Compute output dimensions and CRF from source dims + quality preset. */
+export function computeExportDimensions(sourceWidth, sourceHeight, format, quality) {
+    let w;
+    let h;
+    if (format === 'source') {
+        w = sourceWidth;
+        h = sourceHeight;
+    }
+    else {
+        const preset = FORMAT_PRESETS[format];
+        const shortEdge = Math.min(sourceWidth, sourceHeight);
+        const minAspect = Math.min(preset.aspectWidth, preset.aspectHeight);
+        w = Math.round(shortEdge * (preset.aspectWidth / minAspect));
+        h = Math.round(shortEdge * (preset.aspectHeight / minAspect));
+    }
+    // Ensure even dimensions (required by most codecs)
+    w = w % 2 === 0 ? w : w + 1;
+    h = h % 2 === 0 ? h : h + 1;
+    if (quality === 'source') {
+        return { width: w, height: h, crf: undefined };
+    }
+    const bpp = BPP[quality];
+    if (bpp === undefined)
+        return { width: w, height: h, crf: undefined };
+    return { width: w, height: h, crf: bppToCrf(bpp) };
+}
+/** Ensure a dimension is even (required by most codecs). */
+export function ensureEven(n) {
+    return n % 2 === 0 ? n : n + 1;
+}

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

@@ -0,0 +1,14 @@
+export type { RenderInput, CompositionClip, CompositionOverlay, CompositionAudioTrack, CompositionEffect, CaptionWord, CaptionStyle, OverlayTemplate, OverlayParams } from './types.js';
+export type { ResolvedBrandKit } from '../../composition/projection/index.js';
+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, componentRefsByClipId, assembleRenderInput, validateComposition, compositionFormatDimensions, playableSpans, } 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, computeExportDimensions, ensureEven, } from './exportSettings.js';
+export type { ExportFormat, ExportQuality, ExportResolution, FormatPreset, RenderSettings, } from './exportSettings.js';
+export { faceArea, resolveSubjectFaces, selectedFaceCenter, isJump, emaSmooth, clip01, captionBandReserve, aspectWhRatio, nearestKpValue, activeWindowsFor, perSubjectSeries, calibrateShotScale, deriveSegment, deriveTrajectory, buildEasedZooms, buildPannedCenters, easeOutCubic, JUMP_THRESHOLD, MIN_SUBJECT_RESOLUTION, } from './deriveTrajectory.js';
+export type { Subject, Center, TrajectorySubject, TrajectorySegment, TrajectoryData, Face, FaceBox, SubjectTrack, ReframeSegment, } from './deriveTrajectory.js';
+export { mapFaceIdToPersonId, type FaceToPersonMapping } from './mapFaceToPerson.js';

package/dist/_members/core/render/index.js

@@ -0,0 +1,20 @@
+export { buildEmphasisSet, isEmphasized } from './emphasis';
+export { extractCaptionWordsFromDoc, sliceTranscriptWords, splitIntoSentences } from './captions';
+// (auto-reframe module deleted 2026-05-25 — baked-variants substrate
+// replacement. Crop trajectories now live in pre-baked variant videos,
+// not in render-time computation.)
+// (caption-safe-area deleted 2026-06-04 — the composition floor's reframe-yield
+// replaces the scalar caption shift. See @cueframe/composition/projection
+// resolveCompositionFloor + packages/execution/render-entry/src/floor/buildFloorInput.ts.)
+export { compositionToRenderInput, referencedMediaIds, componentRefsByClipId, assembleRenderInput, validateComposition, compositionFormatDimensions, playableSpans, } from './compositionRender';
+// Brand intro/outro bookend timeline math — pure, fps-driven, never throws.
+// Shared by compositionToRenderInput (forward: body → extended total) and the
+// cueframe renderer's MainComposition (bumper → reserved frames + body shift).
+export { bookendFrames, resolveBookendTimeline, CARD_BOOKEND_DEFAULT_MS, VIDEO_BOOKEND_DEFAULT_MS, } from './bookends';
+export { DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, computeExportDimensions, ensureEven, } from './exportSettings';
+// Crop-trajectory inline derive — PURE STAGE-B math over a cached SubjectTrack.
+// The render derives the crop trajectory INLINE from the track + the clip's
+// reframe (no pre-baked variant cache). See
+// brain/Projects/CueFrame/specs/2026-06-14-render-time-resolution-design.md.
+export { faceArea, resolveSubjectFaces, selectedFaceCenter, isJump, emaSmooth, clip01, captionBandReserve, aspectWhRatio, nearestKpValue, activeWindowsFor, perSubjectSeries, calibrateShotScale, deriveSegment, deriveTrajectory, buildEasedZooms, buildPannedCenters, easeOutCubic, JUMP_THRESHOLD, MIN_SUBJECT_RESOLUTION, } from './deriveTrajectory';
+export { mapFaceIdToPersonId } from './mapFaceToPerson';

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

@@ -0,0 +1,39 @@
+/**
+ * Face→person identity mapping for the perception ESCALATION path.
+ *
+ * The plan authors subjects against the FACE roster (`face-N`, YuNet/SCRFD).
+ * When the face tracker carries that identity in too few frames
+ * (`subject_not_tracked` — e.g. the subject looks away for most of a long
+ * segment), the compose escalates to the PERSON detector (YOLO11x + BoT-SORT),
+ * whose track names identities `person-N`. This maps the authored face id onto
+ * the person id whose body boxes CONTAIN that face, scored over exactly the
+ * frames where the face DID resolve — the face evidence is sparse but real, and
+ * a face box sits inside its own person's box in every such frame.
+ *
+ * Pure math, no I/O. Tracks may have different frame counts (defensive):
+ * frames align by relative position in the shared detection window.
+ */
+type Box = [number, number, number, number];
+interface TrackLike {
+    perFrameTracked: Array<Record<string, Box>>;
+}
+export interface FaceToPersonMapping {
+    personId: string;
+    /** Frames where the face resolved AND the winning person contained it. */
+    matchedFrames: number;
+    /** Frames where the face resolved at all (the scoring denominator). */
+    faceFrames: number;
+    /** Winner's total containment score / runner-up's (Infinity when unopposed). */
+    margin: number;
+}
+/**
+ * Map one authored face id to the person-track id that carries it, or null when
+ * the evidence is missing/ambiguous (caller fails loud — never a guess).
+ *
+ * Decision rule: sum per-frame containment per person id over the frames where
+ * the face resolves; the winner needs (a) support in ≥30% of those frames at
+ * ≥60% containment, and (b) a 1.5× margin over the runner-up (two people
+ * side-by-side must not coin-flip).
+ */
+export declare function mapFaceIdToPersonId(faceTrack: TrackLike, personTrack: TrackLike, faceId: string): FaceToPersonMapping | null;
+export {};

package/dist/_members/core/render/mapFaceToPerson.js

@@ -0,0 +1,73 @@
+/**
+ * Face→person identity mapping for the perception ESCALATION path.
+ *
+ * The plan authors subjects against the FACE roster (`face-N`, YuNet/SCRFD).
+ * When the face tracker carries that identity in too few frames
+ * (`subject_not_tracked` — e.g. the subject looks away for most of a long
+ * segment), the compose escalates to the PERSON detector (YOLO11x + BoT-SORT),
+ * whose track names identities `person-N`. This maps the authored face id onto
+ * the person id whose body boxes CONTAIN that face, scored over exactly the
+ * frames where the face DID resolve — the face evidence is sparse but real, and
+ * a face box sits inside its own person's box in every such frame.
+ *
+ * Pure math, no I/O. Tracks may have different frame counts (defensive):
+ * frames align by relative position in the shared detection window.
+ */
+/** Fraction of the FACE box's area inside the person box. 1 = fully contained. */
+function containment(face, person) {
+    const [fx1, fy1, fx2, fy2] = face;
+    const [px1, py1, px2, py2] = person;
+    const faceArea = Math.max(0, fx2 - fx1) * Math.max(0, fy2 - fy1);
+    if (faceArea === 0)
+        return 0;
+    const ix = Math.max(0, Math.min(fx2, px2) - Math.max(fx1, px1));
+    const iy = Math.max(0, Math.min(fy2, py2) - Math.max(fy1, py1));
+    return (ix * iy) / faceArea;
+}
+/**
+ * Map one authored face id to the person-track id that carries it, or null when
+ * the evidence is missing/ambiguous (caller fails loud — never a guess).
+ *
+ * Decision rule: sum per-frame containment per person id over the frames where
+ * the face resolves; the winner needs (a) support in ≥30% of those frames at
+ * ≥60% containment, and (b) a 1.5× margin over the runner-up (two people
+ * side-by-side must not coin-flip).
+ */
+export function mapFaceIdToPersonId(faceTrack, personTrack, faceId) {
+    const nF = faceTrack.perFrameTracked.length;
+    const nP = personTrack.perFrameTracked.length;
+    if (nF === 0 || nP === 0)
+        return null;
+    const scores = new Map();
+    let faceFrames = 0;
+    for (let i = 0; i < nF; i++) {
+        const face = faceTrack.perFrameTracked[i]?.[faceId];
+        if (!face)
+            continue;
+        faceFrames++;
+        // Align by relative position — identical-length tracks map i→i exactly.
+        const j = nF === 1 ? 0 : Math.round((i * (nP - 1)) / (nF - 1));
+        const persons = personTrack.perFrameTracked[j] ?? {};
+        for (const [pid, pbox] of Object.entries(persons)) {
+            const c = containment(face, pbox);
+            if (c <= 0)
+                continue;
+            const s = scores.get(pid) ?? { total: 0, matched: 0 };
+            s.total += c;
+            if (c >= 0.6)
+                s.matched++;
+            scores.set(pid, s);
+        }
+    }
+    if (faceFrames === 0 || scores.size === 0)
+        return null;
+    const ranked = [...scores.entries()].sort((a, b) => b[1].total - a[1].total);
+    const [winnerId, winner] = ranked[0];
+    const runnerUp = ranked[1]?.[1].total ?? 0;
+    const margin = runnerUp > 0 ? winner.total / runnerUp : Infinity;
+    if (winner.matched / faceFrames < 0.3)
+        return null; // too little real containment
+    if (margin < 1.5)
+        return null; // ambiguous between two people
+    return { personId: winnerId, matchedFrames: winner.matched, faceFrames, margin };
+}