@cueframe/kernel 0.1.1 → 0.1.3

package/dist/_members/convex-api/dataModel.d.ts

@@ -2,5 +2,5 @@ import type { GenericId } from "convex/values";
 import type { SystemTableNames } from "convex/server";
 /** Table NAMES only — the vendored surface deliberately omits document
  *  shapes (Doc/DataModel). Public consumers use exclusively `Id<...>`. */
-export type TableNames = "agentMessages" | "agentThreads" | "apiAuditLog" | "billingPlanState" | "brandKits" | "briefs" | "checkpoints" | "clips" | "clipSuggestionRuns" | "componentVersions" | "composeJobs" | "compositionEvents" | "compositionRuns" | "compositions" | "compositionVersions" | "contextFiles" | "conversations" | "corrections" | "critics" | "dashboardInsights" | "directorProfiles" | "directorWorkflows" | "enrichmentCandidates" | "exports" | "idempotencyKeys" | "installedComponents" | "jobs" | "markers" | "mediaItems" | "mediaUnderstanding" | "overlays" | "pricingPolicy" | "processingEvents" | "projects" | "providerStates" | "renderJobs" | "resourceQueryCache" | "resourceRateBuckets" | "restorePoints" | "runs" | "searchQueries" | "sessions" | "sessionTokens" | "settings" | "socialAccounts" | "socialInsights" | "socialMediaItems" | "templateEmbeddings" | "templates" | "timelineClips" | "tracks" | "transcripts" | "uploadTokens" | "usageEvents" | "userSettings" | "videoChunkEmbeddings" | "webhookDeliveries" | "webhookProjectUpdateDebounce" | "webhooks" | "x402Payments";
+export type TableNames = "agentMessages" | "agentThreads" | "apiAuditLog" | "billingPlanState" | "brandKits" | "briefs" | "checkpoints" | "clips" | "clipSuggestionRuns" | "componentVersions" | "composeJobs" | "compositionEvents" | "compositionRuns" | "compositions" | "compositionVersions" | "contextFiles" | "conversations" | "corrections" | "critics" | "dashboardInsights" | "directorProfiles" | "directorWorkflows" | "enrichmentCandidates" | "exports" | "idempotencyKeys" | "installedComponents" | "jobs" | "markers" | "mediaFactRequests" | "mediaFacts" | "mediaItems" | "mediaUnderstanding" | "orgGatewayKeys" | "overlays" | "pricingPolicy" | "processingEvents" | "projects" | "providerStates" | "renderJobs" | "sightedJobSnapshots" | "resourceQueryCache" | "resourceRateBuckets" | "restorePoints" | "runs" | "searchQueries" | "sessions" | "sessionTokens" | "settings" | "socialAccounts" | "socialInsights" | "socialMediaItems" | "templateEmbeddings" | "templates" | "timelineClips" | "tracks" | "transcripts" | "uploadTokens" | "usageEvents" | "userSettings" | "videoChunkEmbeddings" | "webhookDeliveries" | "webhookProjectUpdateDebounce" | "webhooks" | "x402Payments";
 export type Id<TableName extends TableNames | SystemTableNames> = GenericId<TableName>;

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

@@ -1,3 +1,3 @@
 export * from './types.js';
-export { buildEmphasisSet, isEmphasized, extractCaptionWordsFromDoc, DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, computeExportDimensions, ensureEven, } from './render/index.js';
+export { buildEmphasisSet, isEmphasized, extractCaptionWordsFromDoc, DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, ensureEven, } from './render/index.js';
 export type { RenderInput, CompositionClip, CompositionOverlay, CompositionAudioTrack, CaptionWord, CaptionStyle, EmphasisWord, DocNode, ExportFormat, ExportQuality, ExportResolution, FormatPreset, RenderSettings, } from './render/index.js';

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

@@ -1,60 +1,16 @@
-/**
- * Brand intro/outro BOOKEND timeline math — pure, fps-driven, never throws.
- *
- * Phase 2 of the brand-consistent demo pipeline: when the resolved brand kit
- * carries an `intro`/`outro` bumper, the render prepends the intro and appends
- * the outro to the body composition. This module owns the ONE timeline
- * calculation both sides of the render share:
- *
- *   - `compositionToRenderInput` (this package) reads it FORWARD — body duration
- *     in, extended total out — to size the Remotion composition's
- *     `durationInFrames`.
- *   - `MainComposition` (cueframe renderer) reads `bookendFrames` to place the
- *     intro at frame 0, shift the body forward by the intro, and append the
- *     outro — so the math can't diverge between "how long is the video" and
- *     "where does each piece sit."
- *
- * SOFT by construction (mirrors the brand cascade's "never crash the render"
- * rule): a missing/odd bumper, a video bumper with no source, or a non-positive
- * fps yields 0 reserved frames — no bookend, never a throw, never negative.
- * Fail-loud belongs at BrandKit PUT-time validation, not render-time placement.
- */
 import type { ResolvedBrandKit } from "../../composition/projection/index.js";
-/** Card bumper default length when the kit didn't set one (mirrors the resolver). */
 export declare const CARD_BOOKEND_DEFAULT_MS = 1500;
-/**
- * Video bumper fallback length when the kit set no `durationMs`. The resolver
- * forces no default for `kind:'video'` ("clip length governs"), but the pure
- * timeline math can't probe the clip's intrinsic length, so the renderer
- * reserves this deterministic window. A kit that sets `durationMs` overrides it.
- */
 export declare const VIDEO_BOOKEND_DEFAULT_MS = 3000;
 type Bumper = NonNullable<ResolvedBrandKit["intro"]>;
-/**
- * Frames a single intro/outro bumper reserves on the timeline, or 0 when it is
- * absent/odd (soft). `card` always reserves (defaults to 1.5s); `video` reserves
- * only with a usable `src` (else there is nothing to play).
- */
 export declare function bookendFrames(bumper: ResolvedBrandKit["intro"] | undefined, fps: number): number;
 export interface BookendTimeline {
-    /** Frames the intro reserves at the head (0 = no intro). */
     introFrames: number;
-    /** Frames the outro reserves at the tail (0 = no outro). */
     outroFrames: number;
-    /** First body frame on the extended timeline (= introFrames). */
     bodyStartFrames: number;
-    /** Body length in frames — unchanged from the un-bookended timeline. */
     bodyFrames: number;
-    /** First outro frame (= introFrames + bodyFrames). */
     outroStartFrames: number;
-    /** Extended composition total: intro + body + outro. */
     totalFrames: number;
 }
-/**
- * Forward timeline math: given the resolved kit's bumpers and the body's frame
- * length, place the bookends and compute the extended total. fps-driven; a
- * non-positive body folds to 0 (the total is then just the bookends).
- */
 export declare function resolveBookendTimeline(brandKit: {
     intro?: ResolvedBrandKit["intro"];
     outro?: ResolvedBrandKit["outro"];

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

@@ -1,11 +1,5 @@
 import type { CaptionWord } from './types.js';
 import type { EmphasisWord } from './emphasis.js';
-/**
- * Word-timed transcript utterance — minimal shape covering Deepgram /
- * AssemblyAI / legacy-Whisper outputs. Times are seconds (provider
- * convention); the slicer rebases to milliseconds for the Captions
- * primitive.
- */
 export interface TranscriptUtterance {
     speaker?: string | null;
     text?: string;
@@ -18,48 +12,12 @@ export interface TranscriptUtterance {
         confidence?: number;
     }>;
 }
-/**
- * Slice a transcript's word stream to a clip window.
- *
- * Source: `utterances[].words[]` with second-precision `start` / `end`.
- * Output: `CaptionWord[]` with millisecond timings rebased so the
- * first word's `startMs` is 0 (relative to the clip, not the source).
- * Words wholly outside `[fromSec, toSec)` are dropped; words that
- * straddle either edge are clamped to the boundary.
- *
- * Pure function — no I/O, no DB. Caller fetches the transcript blob
- * (typically from R2) and feeds the parsed `utterances` here.
- */
 export declare function sliceTranscriptWords(utterances: TranscriptUtterance[], fromSec: number, toSec: number): CaptionWord[];
-/** ProseMirror/TipTap document node — generic to avoid @tiptap/core dependency. */
 export interface DocNode {
     type?: string;
     text?: string;
     attrs?: Record<string, unknown>;
     content?: DocNode[];
 }
-/**
- * Walk a TipTap doc JSONContent and extract non-deleted timedWord nodes
- * as CaptionWord[].
- *
- * In v2 the wire-shape composition encodes cuts physically (clip
- * startTime/duration), so caption timings are taken straight off the
- * timedWord attrs without any deletion-range shift.
- *
- * This makes the ProseMirror doc the single source of truth for caption text,
- * instead of re-reading raw Whisper transcripts.
- */
 export declare function extractCaptionWordsFromDoc(doc: DocNode, emphasisWords: EmphasisWord[]): CaptionWord[];
-/**
- * Group a flat word stream into sentence-bounded segments — start a new segment
- * after any word that ends a sentence (`isSentenceEnd`). Caption words carry
- * punctuation from Deepgram's `punctuated_word`, so the trailing-character test
- * is reliable; abbreviations and initialisms are guarded so they don't
- * false-split mid-sentence.
- *
- * This is how a raw transcript slice becomes `composition.captions.segments`:
- * the renderer treats each segment as a hard caption-page boundary, so
- * sentence-bounded segments make captions cut at sentence ends. A stream with
- * no terminal punctuation yields a single segment; an empty stream yields none.
- */
 export declare function splitIntoSentences(words: CaptionWord[]): CaptionWord[][];

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

@@ -1,88 +1,12 @@
-/**
- * Wire-shape `Composition` → `RenderInput` translator.
- *
- * `Composition` is the canonical multi-track wire shape from
- * `@cueframe/composition`. It crosses the API boundary
- * (PUT /v1/projects/:id/composition), gets snapshotted onto
- * `renderJobs.composition`, and is what the Remotion worker reads
- * before kicking off a render.
- *
- * This module is the single bridge from that wire shape to the
- * frame-based `RenderInput` Remotion consumes:
- *
- *   {format, tracks[]: [{kind, contents[]: TimelineClip[]}]}
- *      ↓
- *   compositionToRenderInput(composition, srcUrls)
- *      ↓
- *   { clips, overlays, audioTracks, effects, width, height, fps,
- *     durationInFrames }
- *
- * Track-kind handling:
- *   - `video` → `CompositionClip[]`. Each clip's wire startTime/duration
- *     map to timelineStartFrames/durationInFrames; `source.trim`'s
- *     source-relative seconds map to sourceInFrames/sourceOutFrames.
- *     Clips on multiple video tracks layer in track order (z-order
- *     follows the wire array).
- *   - `audio` → `CompositionAudioTrack[]`. `source.volumeDb` (if set)
- *     converts to linear gain via `10^(dB/20)`; `source.fadeInMs` /
- *     `source.fadeOutMs` convert to frames.
- *   - `image` → `CompositionClip[]` with `mediaType: 'image'`. Stills
- *     have no source timeline (sourceIn/Out are zero); `source.kenBurns`
- *     flows through as a convenience that the renderer's <StillCrop> lowers
- *     to a `reframe` (kenBurnsToReframe) and runs through the UNIFIED crop
- *     renderer, so a still gets the same per-frame point-zoom video does.
- *     Sub-frame durations are dropped (would crash Remotion's <Sequence>).
- *   - `overlay` → `CompositionOverlay[]`. Wire `source.primitiveId`
- *     becomes `template`; `source.params` flow through to the renderer.
- *   - `effect` → `CompositionEffect[]` with `target.kind: 'global'`,
- *     scoped to the effect clip's wire start/duration.
- *
- * `srcUrls` is a `mediaId → presigned URL` map. The caller (Temporal
- * activity) pre-signs every unique mediaId before calling this. A
- * referenced mediaId missing from `srcUrls` throws — silent fallbacks
- * are forbidden (the v0 path's silent-fallback bug class).
- */
 import type { Composition, Format } from "../../composition/validators/index.js";
 import type { RenderInput } from "./types.js";
 import type { TrajectoryData } from "../../composition/reframe/trajectory.js";
-/**
- * Resolve `Format` (`aspectRatio`, optional `fps` + `resolution`) to
- * concrete pixel dimensions. Mirrors the public-composition path's
- * `publicFormatDimensions` so a Composition with `format: { aspectRatio:
- * "9:16", fps: 30, resolution: "fhd" }` lands at the same 1080×1920
- * regardless of which translator the worker traversed.
- */
 export declare function compositionFormatDimensions(format: Format): {
     width: number;
     height: number;
     fps: number;
 };
-/**
- * Runtime-validate an untrusted value as a `Composition`. The Temporal
- * activity reads `renderJobs.composition` which is stored as
- * `v.optional(v.any())` — Convex doesn't enforce shape at read time. A
- * schema drift or a manual DB edit could leave a malformed value here,
- * and the renderer would crash later in the pipeline with a less
- * actionable error.
- *
- * Returns the validated composition or throws with a specific error
- * message. Call this at the activity boundary before passing the
- * composition to `compositionToRenderInput`. Pure JS validation — no
- * Zod runtime — so this module ships into the Temporal worker without
- * dragging the package's Zod surface along.
- */
 export declare function validateComposition(raw: unknown): Composition;
-/**
- * Given a clip's effective trim window [trimStart, trimEnd] and an
- * optional sorted+non-overlapping list of excluded ranges (all in source
- * coordinates), return the playable spans in order. Each span is a
- * contiguous source range that should render as a sub-clip.
- *
- * Invariant (enforced upstream): Σ(span.end - span.start) === clip.duration.
- */
-/** The clip's playable spans (seconds) = [trimStart, trimEnd] minus
- *  excludedRanges. SSOT for section splitting — exported so the Director derives
- *  the SAME sections the render uses when it builds structure-first keep-outs. */
 export declare function playableSpans(trimStart: number, trimEnd: number, excluded: Array<{
     start: number;
     end: number;
@@ -90,117 +14,14 @@ export declare function playableSpans(trimStart: number, trimEnd: number, exclud
     start: number;
     end: number;
 }>;
-/**
- * Every unique mediaId the composition references — the SAME references
- * `compositionToRenderInput` resolves through `srcUrls` (any clip whose
- * `source.kind === 'media'`, on any track family). Interactive hosts (the
- * editor preview) gate on this BEFORE converting: a referenced id without a
- * URL yet is a LOADING state there, while the converter's fail-loud throw
- * stays correct for export/server paths where every URL must already exist.
- * Living next to the converter keeps the two walks from drifting.
- */
 export declare function referencedMediaIds(composition: Composition): string[];
-/**
- * Every component-REFERENCE `custom` overlay clip, as `clipId → componentId` —
- * the SAME references `compositionToRenderInput` resolves through
- * `jsSourceByClipId` (bakeless live lane). Clips carrying their own inline
- * `params.sourceCode` (desktop-authored customs) need no materialization and
- * are excluded. Interactive hosts (the editor preview) gate on this BEFORE
- * converting and feed the fetched live `jsSource`s in — the converter's
- * fail-loud `custom_missing_sourcecode` throw stays correct for export/server
- * paths. Living next to the converter keeps the walks from drifting.
- */
 export declare function componentRefsByClipId(composition: Composition): Record<string, string>;
-/**
- * Translate a wire-shape `Composition` to a frame-based `RenderInput`.
- *
- * The output's `durationInFrames` is the max content end across all
- * tracks (clips + overlays + effects). An empty composition produces
- * an empty RenderInput with duration 0 — caller decides whether that
- * should error or render a black frame; we don't make a policy call
- * here.
- */
-export declare function compositionToRenderInput(composition: Composition, srcUrls: Record<string, string>, 
-/**
- * Optional parallel map: `clipId → presigned crop-trajectory JSON URL`
- * (keyed PER CLIP since Phase 2 — two clips of one media with different
- * framing each carry their own trajectory). Populated by the caller
- * (Temporal activity) when the mediaItem has a baked variant for the
- * clip's window-qualified (intentHash, aspect). The renderer fetches the
- * JSON at composition time and applies a per-frame CSS transform on the
- * raw video to produce the cropped output. When unset for a given clipId,
- * the renderer plays the raw source un-cropped.
- */
-trajectoryUrls?: Record<string, string>, 
-/**
- * Optional parallel map: `mediaId → presigned frame-packed co-view URL`
- * (scene over matte, one opaque H.264). Populated by the caller for any clip
- * whose timeline range overlaps a behind-subject caption window and whose
- * matte the gate baked (content-driven, Phase 6). Matte PRESENCE is the gate —
- * the render splits it into scene background + subject cut-out for the z-split.
- */
-coViewUrls?: Record<string, string>, 
-/**
- * Optional parallel map: `clipId → baked-alpha file URL/path` for alpha-layer
- * clips (2.6b). The box bake (renderComponentAlpha) writes the transparent
- * video; the caller (session daemon / director) threads the path here. The
- * renderer mounts it as an alpha overlay at the clip's zPlane.
- */
-alphaUrls?: Record<string, string>, 
-/**
- * Optional parallel map: `clipId → FRESH transpiled jsSource` for
- * component-backed `custom` overlays (bakeless live lane). Materialized per
- * render from `installedComponents` (renders.ts) — the live-lane peer of
- * `alphaUrls`. The overlay projection prefers it over any stored
- * `params.sourceCode`, so a component edit is reflected on the next render
- * with no composition re-save.
- */
-jsSourceByClipId?: Record<string, string>, 
-/**
- * Compound-clip resolution: `compositionId → Composition` for every
- * `{kind:'composition'}` source the composition (transitively) embeds.
- * Flattening happens HERE, at the one translator every render lane flows
- * through, so an embedded sequence renders identically on desktop, cloud
- * and still lanes. A compound clip with no entry FAILS LOUD
- * (`compound_unresolved`) rather than rendering a deliverable that is
- * silently missing a sequence.
- */
-subCompositions?: Record<string, Composition>, 
-/**
- * Optional parallel map: `clipId → an ALREADY-DERIVED crop trajectory`, the
- * in-memory peer of `trajectoryUrls`.
- *
- * The editor supplies this. `deriveTrajectory` is pure and the subject track
- * it reads arrives presigned on the media row, so a preview surface can
- * derive exactly what the render will derive — same function, same track,
- * same authored reframe — with no round trip and nothing to store. That is
- * what lets a follow-the-speaker clip move in the preview instead of only in
- * an output someone has already paid for.
- *
- * Server renders keep using `trajectoryUrls`: their trajectory is written to
- * R2 by an action, and inlining a per-frame series would bloat the snapshot.
- */
-trajectories?: Record<string, TrajectoryData>): RenderInput;
-/**
- * Assemble a RenderInput from an ALREADY-validated (and brand-ref-resolved)
- * composition plus PRE-RESOLVED asset URL maps. This is the pure core shared by
- * the director's `resolveRenderEnvironment` (which resolves the URLs with R2/S3
- * creds, host-side) AND the in-container session daemon (which is handed the URLs
- * and holds no creds). One builder ⇒ render and capture cannot diverge on the
- * composition→RenderInput translation.
- *
- * `fontAssets` (when present) are the host-presigned brand font faces; they are
- * attached to the RenderInput's brandKit so the renderer can `@font-face` them.
- * The caller does the cred-bound URL/font resolution; this only assembles.
- */
+export declare function compositionToRenderInput(composition: Composition, srcUrls: Record<string, string>, trajectoryUrls?: Record<string, string>, coViewUrls?: Record<string, string>, alphaUrls?: Record<string, string>, jsSourceByClipId?: Record<string, string>, subCompositions?: Record<string, Composition>, trajectories?: Record<string, TrajectoryData>): RenderInput;
 export declare function assembleRenderInput(composition: Composition, resolved: {
     srcUrls: Record<string, string>;
     trajectoryUrls?: Record<string, string>;
     coViewUrls?: Record<string, string>;
-    /** clipId → baked-alpha file URL/path for alpha-layer clips (2.6b). */
     alphaUrls?: Record<string, string>;
-    /** clipId → FRESH transpiled jsSource for component-backed `custom` overlays
-     *  (bakeless live lane; live-lane peer of `alphaUrls`). */
     jsSourceByClipId?: Record<string, string>;
     fontAssets?: NonNullable<RenderInput["brandKit"]>["fontAssets"];
 }): RenderInput;

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

@@ -1,28 +1,3 @@
-/**
- * deriveTrajectory — PURE TypeScript STAGE-B crop-trajectory math (the cheap
- * "apply a crop intent" half), derived over a cached source-level `subjectTrack`.
- *
- * This is the SINGLE crop derivation for EVERY render surface — the agent's
- * in-loop capture, the verifier eval, AND the customer ship render — by
- * construction: each surface calls THIS function over the SAME cached track +
- * the SAME authored reframe, so the trajectory is identical bytes with no
- * pre-baked variant cache to drift. Render-time-resolution (2026-06-14): the
- * trajectory is DERIVED INLINE at render, never looked up as a baked variant,
- * which deleted the trajectory variant cache + its `variant_not_baked` bug class.
- *
- * Lives in @cueframe/execution/core (`@cueframe/core/render`) — it depends only
- * on TYPES from @cueframe/perception (`SubjectTrack`/`Face`/`FaceBox`) and
- * @cueframe/composition (`ReframeSegment` + the eased-ramp helpers), both legal
- * execution-framework dependencies (execution MAY depend on perception +
- * composition). The Modal `reframe_bake` re-detection path is retired — there is
- * one derivation, so there is no TS↔Python drift to guard against.
- *
- * Output shape is the canonical `TrajectoryData` from
- * @cueframe/composition/reframe/trajectory — the SSOT that both this producer and
- * the renderer (CropFromTrajectory.tsx) import; neither declares a local mirror.
- *
- * See brain/Projects/CueFrame/specs/2026-06-14-render-time-resolution-design.md.
- */
 import type { Face, FaceBox, SubjectTrack } from '../../perception/index.js';
 export type { Face, FaceBox, SubjectTrack } from '../../perception/index.js';
 import type { ReframeSegment } from '../../composition/reframe/index.js';
@@ -31,15 +6,7 @@ export { buildEasedZooms, buildPannedCenters, easeOutCubic } from '../../composi
 import type { TrajectorySubject, TrajectoryData } from '../../composition/reframe/trajectory.js';
 export type { TrajectorySubject, TrajectorySegment, TrajectoryData } from '../../composition/reframe/trajectory.js';
 import { type ShotFit } from './vcam/framing.js';
-/**
- * Normalized area of a face detection — used to rank faces largest-first
- * (largest ≈ closest to camera = `face-0` by convention). Mirrors
- * reframe_bake.py `_face_area` (width/height path; negatives clamp to 0).
- */
 export declare function faceArea(face: Face): number;
-/** The crop subject pick the agent authors on a segment (mirror of the wire
- *  `cropIntents[].subject`). `active-speaker` is resolved upstream (per
- *  keyframe) into a concrete `face` before this is consulted. */
 export type Subject = {
     kind: 'face';
     faceId: string;
@@ -54,131 +21,24 @@ export type Subject = {
     x: number;
     y: number;
 };
-/**
- * Filter the detector's face list by the segment's subject pick:
- *  - `all-faces` → all faces (cropper fits the union bbox).
- *  - `frame-center` → [] (cropper centers on the source geometric center).
- *  - `face` faceId=`face-N` → the face with that STABLE tracker id this frame.
- *    The roster the agent authors against carries the tracker's stable ids, so
- *    `face-2` means "that tracked person," NOT "the 3rd-largest face this frame."
- *    Absent this frame → [] (caller emits no center; EMA forward-fills) rather
- *    than silently snapping to a DIFFERENT person — the old area-rank +
- *    out-of-range→largest behavior is exactly what made the crop ping-pong
- *    between speakers (brain Issue crop-subject-resolved-by-area-rank).
- *  - The EMPTY-string faceId is a sentinel (the active-speaker degrade, see
- *    deriveSegment) meaning "no specific subject this frame → largest face."
- * Throws on an unknown kind.
- *
- * NB: the retired Python `reframe_bake._resolve_subject_faces` did area-rank;
- * that path is dead (TS is the only live derivation), so there is no drift.
- */
 export declare function resolveSubjectFaces(faces: Face[], subject: Subject): Face[];
-/** A normalized crop center `[cx, cy]` in [0,1] vs source dims. */
 export type Center = [number, number];
-/**
- * The target crop center from face dets + subject pick. Mirrors
- * reframe_bake.py `_selected_face_center`: `frame-center` (and no usable
- * selection) → null (caller centers on source); otherwise the area-weighted
- * centroid of the selected faces (degenerates to a single face's center).
- */
 export declare function selectedFaceCenter(faces: Face[], subject: Subject): Center | null;
-/** Normalized distance beyond which adjacent centers are treated as a shot
- *  change (hard cut / new angle) and smoothing snaps instead of blending —
- *  mirror of reframe_bake.py `JUMP_THRESHOLD`. */
 export declare const JUMP_THRESHOLD = 0.15;
-/** Minimum fraction of a segment's frames in which an authored `face` subject
- *  must actually be tracked. Below this, deriveTrajectory FAILS LOUD instead of
- *  silently centering the crop — the authored identity isn't really in the clip
- *  (tracker ID fragmentation). A genuine subject is present for the large
- *  majority of frames it's framed over; 40% is a generous floor. */
 export declare const MIN_SUBJECT_RESOLUTION = 0.4;
 export declare function isJump(a: Center, b: Center): boolean;
-/**
- * Shot-aware EMA on per-frame centers. Forward-fill nulls with the last-known
- * position, then a forward + backward EMA pass, where BOTH passes snap (no
- * blend) ONLY across a detector-reported shot cut (`cutFrames`).
- *
- * Phase 1 (vcam): the `isJump`/`JUMP_THRESHOLD` inference is GONE as a cut
- * signal. A center jump is NEVER inferred to be a cut — that inference was the
- * false-cut snap (a ByteTrack detection-lag jiggle read as a new shot →
- * teleport). Cuts come ONLY from `shotBoundaries`. `isJump`/`JUMP_THRESHOLD`
- * remain exported (legacy consumers) but no longer drive smoothing here.
- *
- * Phase 3 (vcam): the `all-faces` CAMERA-CENTER smoothing is now the deadzone-
- * inclusion + Hamming-window stage in `cameraPath` (the camera TRACKS a moving
- * group). `emaSmooth` stays for the SEPARABLE non-center use — the per-subject
- * `face_box_series` the floor reads (`perSubjectSeries`) — and for the
- * UNCHANGED face/active-speaker/frame-center center path (byte-identical to the
- * pre-Phase-3 behavior, the mode-isolation invariant). It is NOT used for the
- * all-faces centers any more.
- */
 export declare function emaSmooth(centers: (Center | null)[], alpha?: number, cutFrames?: ReadonlySet<number>): Center[];
-/** Clamp to [0,1] — mirror of reframe_bake.py `_clip01`. */
 export declare function clip01(v: number): number;
-/** Bottom-band fraction the render keeps clear for captions per aspect.
- *  CAPTION_BAND_RESERVE is the SSOT in @cueframe/composition (imported above). */
 export declare function captionBandReserve(aspect: string): number;
-/** Output aspect as width/height (e.g. '9:16' → 0.5625). FAILS LOUD on a
- *  malformed aspect — a silent 9/16 default frames every non-vertical render
- *  vertically (no-fallbacks rule). Callers pass `composition.format.aspectRatio`,
- *  which the Composition validator constrains to a known enum, so a throw here
- *  is a genuine drift/bug, never a user-reachable path. */
 export declare function aspectWhRatio(aspect: string): number;
-/**
- * The crop window size (source-normalized) for a given `zoom_scale` + output
- * aspect — the bake half of the renderer's `computeCropTransform`: the largest
- * output-aspect rect that fits the source, scaled by the zoom (clamped to
- * [0.4,1.0] like `bakedZoom`). Shared so the cameraPath deadzone (output-crop
- * units) can convert to the source-normalized geometry the regions live in.
- */
 export declare function cropWindowSizeFor(srcW: number, srcH: number, zoomScale: number, aspect: string): {
     w: number;
     h: number;
 };
-/** Return the value at the largest key ≤ `key` (fallback to the smallest key
- *  when none precedes; null when empty) — mirror of `_nearest_kp_value`.
- *  per-keyframe-speaker is a Map<frameOffset, faceId>. */
 export declare function nearestKpValue(d: Map<number, string>, key: number): string | null;
-/** Contiguous [startFrame, endFrame) ranges where `faceId` is the active
- *  speaker; adjacent same-speaker spans merge — mirror of `_active_windows_for`.
- *  Each keyframe pick holds until the next keyframe (last → frameCount). */
 export declare function activeWindowsFor(faceId: string, perKeyframeSpeaker: Map<number, string>, frameCount: number): Array<[number, number]>;
-/**
- * Build smoothed per-subject normalized face-box series + active windows from
- * the tracker's per-frame `{faceId: [x1,y1,x2,y2]}` (pixel) output. Mirror of
- * reframe_bake.py `_per_subject_series`: stable subject order = first
- * appearance; centers + sizes EMA-smoothed (alpha 0.35) with the same shot-aware
- * reset as the crop centers; frames with no tracked face stay null.
- */
 export declare function perSubjectSeries(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, perKeyframeSpeaker: Map<number, string>, frameCount: number, cutFrames?: ReadonlySet<number>): TrajectorySubject[];
-/** §22.1 target face-height fraction of the OUTPUT per editorial shot scale
- *  (mirror of reframe_bake.py `_SHOT_SCALE_TARGET`). */
-/**
- * §22.1 (Phase 4): calibrate ZOOM to the DETECTED face for an editorial shot
- * scale. zoom = median(face_h_px)/fit_h / target, clamped [ZOOM_MIN, ZOOM_MAX].
- * shotScale seeds ZOOM ONLY — verticalBias (headroom) is the agent's AUTHORED
- * value, passed through verbatim; it is NEVER overridden here (the floor-vision
- * fix). When the authored fields are omitted: zoom defaults to 1.0 (frame as-is)
- * and headroom to 0 (dead-center, never auto-applied). Falls back to the authored
- * zoom/bias when shotScale is unset or no face was detected.
- *
- * The target table + the clamp live in @cueframe/composition/reframe/shotScale —
- * the SAME module the plan-time punch-in guard reads, so a shotScale the guard
- * admitted and the zoom this bakes can never disagree. Do NOT re-declare them here.
- *
- * NOTE this honors whatever shotScale reaches it. Whether the punch-in was EARNED
- * (is there room around the face? pixels to magnify?) is decided at the plan, by
- * `punchInWarrant` in that same module. A shotScale arriving here that the warrant
- * would refuse is a bug in the guard, not something to re-check.
- */
 export declare function calibrateShotScale(shotScale: string | undefined | null, subjects: TrajectorySubject[], srcW: number, srcH: number, aspect: string, fallbackZoom: number | undefined, fallbackVbias: number | undefined, authoredSubject?: Subject): [number, number];
-/**
- * Derive ONE segment's per-frame crop centers + per-subject series from a
- * segment-local slice of the cached track. Mirror of the STAGE B half of
- * reframe_bake.py `_bake_segment` (steps 4–7): per-frame subject filter
- * (active-speaker uses the nearest keyframe pick; otherwise largest/face-N) →
- * shot-aware EMA (alpha 0.35) → holes land at [0.5,0.5] → per-subject series.
- */
 export declare function deriveSegment(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, perKeyframeSpeaker: Map<number, string>, subject: Subject, cutFrames?: ReadonlySet<number>, fps?: number, aspect?: string, zoomScale?: number): {
     centers: Center[];
     subjects: TrajectorySubject[];

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

@@ -3,11 +3,5 @@ export interface EmphasisWord {
     sourceStart: number;
     sourceEnd: number;
 }
-/**
- * Build a Set keyed by "poolItemId:sourceStart" for O(1) emphasis lookups.
- * sourceStart is rounded to 3 decimal places to handle floating-point drift
- * between transcript sources and stored emphasis data.
- */
 export declare function buildEmphasisSet(emphasisWords: EmphasisWord[]): Set<string>;
-/** Check if a word (by poolItemId + sourceStart) is in the emphasis set. */
 export declare function isEmphasized(set: Set<string>, poolItemId: string, sourceStart: number): boolean;

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

@@ -1,87 +1,18 @@
-/**
- * Reframe eval — the COMPOSED crop box per output frame.
- *
- * The eval target is the crop box the camera ACTUALLY lands on, in
- * output-crop-normalized space — NOT the raw `centers`/`zoom_scale` of the
- * trajectory JSON. Per the virtual-camera spec ("the composed (post-floor) crop
- * is the eval target … zoom is two-layer"), the jitter / center-crop metrics
- * sample the box `computeCropTransform` produces, so they measure what ships.
- *
- * Phase 0 samples the BASE camera path (the trajectory) — the floor yield is a
- * separate, caption-driven layer with its own golden (Phase 4). The geometry
- * below is the bake half of `computeCropTransform`
- * (packages/execution/render-entry/src/CropFromTrajectory.tsx): crop-window size from
- * `zoom_scale`, center from the per-frame `centers`, coverage-clamped so the
- * window never runs past the source edge. We replicate it here (rather than
- * import the renderer — execution must not depend on the Remotion bundle) and a
- * test pins this replica against the renderer's published clamp behavior.
- *
- * Coordinate system: the crop box is expressed in SOURCE-NORMALIZED units —
- * `cx,cy` ∈ [0,1] (window center vs source dims) and `w,h` ∈ [0,1] (window size
- * as a fraction of the source). Frame-to-frame motion of THIS box is the camera
- * motion; normalizing the per-component delta by the box's own size converts it
- * to output-crop-normalized units (a half-window pan is the same number at any
- * zoom — the zoom-invariant "held feel" the spec requires).
- */
 import type { TrajectoryData, TrajectorySegment } from '../../../composition/reframe/trajectory.js';
-/** The composed crop window for one output frame, source-normalized. */
 export interface CropBox {
-    /** Window center x ∈ [0,1] vs source width (after the coverage clamp). */
     cx: number;
-    /** Window center y ∈ [0,1] vs source height (after the coverage clamp). */
     cy: number;
-    /** Window width as a fraction of the source width ∈ (0,1]. */
     w: number;
-    /** Window height as a fraction of the source height ∈ (0,1]. */
     h: number;
 }
-/**
- * Crop-window dimensions (source-normalized) for a given `zoom_scale` + output
- * aspect — the bake half of `computeCropTransform`. The largest output-aspect
- * rect that fits the source, scaled by the clamped zoom. No `faceScale` (the
- * floor's caption-band yield) is applied here — Phase 0 samples the base path.
- */
 export declare function cropWindowSize(srcW: number, srcH: number, zoomScale: number, aspect: string): {
     w: number;
     h: number;
 };
-/** The composed crop box for one frame of one segment. */
 export declare function cropBoxForFrame(seg: TrajectorySegment, frameInSeg: number, srcW: number, srcH: number, aspect: string): CropBox;
-/**
- * Flatten a `TrajectoryData` to the per-output-frame composed crop-box series
- * over all its segments, in order. This is the series the jitter metric walks.
- */
 export declare function cropBoxSeries(traj: TrajectoryData): CropBox[];
-/**
- * The STATIC center-crop baseline a content-aware reframe MUST beat on
- * smoothness: the same per-segment `zoom_scale` (so the only variable is WHERE
- * the camera points), but the center pinned to source-center every frame
- * (coverage-clamped, which for a centered window is a no-op). A static crop has
- * zero pan jitter by construction — its only frame-to-frame motion is the
- * per-shot `zoom_scale` steps the algorithm itself authors. The reframe is
- * "adding jitter for nothing" if it cannot beat THIS.
- */
 export declare function centerCropBoxSeries(traj: TrajectoryData): CropBox[];
-/**
- * The RAW subject-centroid path baseline (the research bar): the per-frame
- * `centers` the algorithm computed, BEFORE any smoothing/deadzone, composed into
- * a crop box at the same per-segment zoom. A reframe must be SMOOTHER than the
- * path it is smoothing. Phase 0 cannot reconstruct the pre-EMA centroid from the
- * shipped trajectory (it only carries the smoothed `centers`), so this is a
- * scaffold that returns the shipped centers; Phase 3 wires the true raw path via
- * `eval/inclusion` + `eval/index` (keeping `emaSmooth` importable, per the
- * spec's characterization gate).
- */
 export declare function rawCentroidBoxSeries(traj: TrajectoryData): CropBox[];
-/**
- * Compose an arbitrary per-frame `centers` series (e.g. the raw tracking
- * centroid, or the same centroid through the OLD `emaSmooth`) into a crop-box
- * series at a fixed per-frame crop window — the Phase-3 "smoother than EMA"
- * characterization baseline. `cropFor(frame)` gives the source-normalized window
- * for that output frame (the same the shipping path uses), so the ONLY variable
- * between ours and the baseline is the smoother. Centers are coverage-clamped
- * exactly as the renderer clamps them.
- */
 export declare function cropBoxSeriesFromCenters(centers: Array<[number, number]>, cropFor: (frame: number) => {
     w: number;
     h: number;