@cueframe/kernel 0.0.1

package/dist/_members/core/select/stabilize.js

@@ -0,0 +1,242 @@
+/**
+ * select/stabilize.ts — the continuity/selection STABILIZER seam (spec §1.4 step
+ * 4 + L1). The scoring (`select.ts`) generalizes cleanly; the stabilizer does
+ * NOT — it is THREE kinds behind ONE `stabilize(kind, …)` seam, dispatched per
+ * kind by the adapter. This is the honest "build a small fixed set of per-kind
+ * stabilizers," not "one function" (L1; the prior draft's "selection-hysteresis
+ * generalizes verbatim" claim is retracted).
+ *
+ * Phase 1 implements the two kinds reframe needs:
+ *   - `selection-hysteresis` — the per-id set-MEMBERSHIP state machine (the
+ *     `topK>1` reframe stabilizer), lifted VERBATIM from `vcam/subjectSet.ts`
+ *     (`inset`/`presRun`/`absRun` + the short-clip `usedFallback` bypass). Pure;
+ *     byte-equivalence-preserving.
+ *   - `geometric-deadzone` — `vcam/cameraPath.ts`, lifted VERBATIM and SEALED
+ *     (deadzone inclusion invariant + Hamming + glide cap). Re-exported, NEVER
+ *     altered — perturbing its math risks the shipped `inclusionRate ≈ 1.0` (L1).
+ *
+ * Phase 2 (switch) adds `incumbent-challenger` (topK=1 + switchMargin — NEW code,
+ * vcam has no incumbent concept) and `presence-gate` (overlay binary show/hide).
+ * Their seams are declared here so the dispatch shape is fixed; they fail loud
+ * until built (no silent stub — `feedback_never_add_fallbacks`).
+ */
+/**
+ * The per-id set-MEMBERSHIP hysteresis state machine — the `topK>1` selection
+ * stabilizer (spec §1.4 step 4; §2 maps it as CORE for reframe's membership).
+ * Lifted VERBATIM from `vcam/subjectSet.ts:306-343`: each member enters after
+ * `enterFrames` consecutive present frames and leaves after `leaveFrames` absent
+ * frames — independent per-id booleans. A member is FRAMED this frame iff it is
+ * IN the set AND present this frame.
+ *
+ * `usedFallback` is the short-segment bypass: a segment that ends before any
+ * member clears the ENTER debounce uses the static framed set (so a brief clip
+ * with a clear dominant subject is still framed, never center-held — the spec's
+ * `minSegmentForHysteresis` bypass).
+ *
+ * Pure. Byte-identical to the inline vcam logic — `framedIds` order drives the
+ * per-frame `here` order, so the adapter must pass ids in dominance order.
+ */
+export function stabilizeSelectionHysteresis(framedIds, presence, n, params) {
+    const { enterFrames, leaveFrames } = params;
+    const everIn = new Set();
+    const inset = new Map(framedIds.map((id) => [id, false]));
+    const presRun = new Map(framedIds.map((id) => [id, 0]));
+    const absRun = new Map(framedIds.map((id) => [id, 0]));
+    const inThisFrame = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const here = [];
+        for (const id of framedIds) {
+            if (presence(id, i)) {
+                presRun.set(id, presRun.get(id) + 1);
+                absRun.set(id, 0);
+            }
+            else {
+                absRun.set(id, absRun.get(id) + 1);
+                presRun.set(id, 0);
+            }
+            if (!inset.get(id) && presRun.get(id) >= enterFrames)
+                inset.set(id, true);
+            if (inset.get(id) && absRun.get(id) >= leaveFrames)
+                inset.set(id, false);
+            if (inset.get(id) && presence(id, i)) {
+                here.push(id);
+                everIn.add(id);
+            }
+        }
+        inThisFrame[i] = here;
+    }
+    return { everIn, inThisFrame, usedFallback: everIn.size === 0 };
+}
+// ── geometric-deadzone (Phase 1) ─────────────────────────────────────────────
+// `cameraPath` is the geometric-deadzone continuity stabilizer, lifted VERBATIM
+// and SEALED. It is NOT re-implemented here — it is re-exported from its sealed
+// home so the dispatch surface names it without touching its math.
+export { cameraPath } from '../render/vcam/cameraPath';
+/**
+ * The incumbent/challenger selection stabilizer — the `topK=1` (switch cut)
+ * anti-ping-pong machine (spec §1.4 step 4, NEW code; L1). Inputs are the per-tick
+ * RAW winner id (the score argmax for that tick) and the per-tick scores by id, so
+ * the stabilizer is candidate-AGNOSTIC (it reads ids + scalars + policy knobs).
+ *
+ * Rule (spec §3.2 + §1.3 knobs):
+ *   - A challenger replaces the incumbent ONLY IF it leads the incumbent by
+ *     `switchMargin` for `enterFrames` CONTINUOUS ticks AND the incumbent has held
+ *     ≥ `minHoldFrames`.
+ *   - `cooldownFrames` forbids re-entering the just-left incumbent for that long.
+ *   - `maxHoldFrames` (optional) forces the incumbent to yield to the best
+ *     challenger after that many held ticks even without a margin lead.
+ *   - A `__hold__` raw winner (no candidate above floor) holds the incumbent (the
+ *     source lowering: "stay on the incumbent, emit no cut").
+ *
+ * `scoreById(id, t)` returns the candidate's score at tick t (0 if not scored).
+ * Pure. Deterministic — no Date, no Map-order math.
+ */
+export function stabilizeIncumbentChallenger(rawWinnerPerTick, scoreById, n, params) {
+    const { minHoldFrames, enterFrames, switchMargin, cooldownFrames, maxHoldFrames } = params;
+    const chosenPerTick = new Array(n);
+    const suppressed = [];
+    if (n === 0)
+        return { chosenPerTick, suppressed };
+    // Seed the incumbent with the first tick's raw winner (a __hold__ first tick
+    // means there is no incumbent yet — the first concrete winner seeds it).
+    let incumbent = null;
+    let heldFrames = 0;
+    // Per-challenger continuous-lead run length (reset when the lead breaks).
+    const leadRun = new Map();
+    // Cooldown: the id just dethroned → ticks remaining before it may re-enter.
+    let cooldownId = null;
+    let cooldownLeft = 0;
+    for (let t = 0; t < n; t++) {
+        const raw = rawWinnerPerTick[t];
+        if (incumbent === null) {
+            // No incumbent yet: adopt the first concrete (non-hold) raw winner.
+            if (raw !== HOLD_ID) {
+                incumbent = raw;
+                heldFrames = 1;
+            }
+            chosenPerTick[t] = incumbent ?? raw; // raw is HOLD here if still unseeded
+            if (cooldownLeft > 0)
+                cooldownLeft--;
+            continue;
+        }
+        const incScore = scoreById(incumbent, t);
+        // Find the best challenger (the highest-scoring id that is NOT the incumbent
+        // and is not in cooldown). The raw winner is the global argmax; if it equals
+        // the incumbent there is no challenger this tick.
+        let challenger = null;
+        let challengerScore = -Infinity;
+        if (raw !== HOLD_ID && raw !== incumbent) {
+            challenger = raw;
+            challengerScore = scoreById(raw, t);
+        }
+        // Update each challenger's continuous-lead run.
+        if (challenger !== null && challengerScore >= incScore + switchMargin) {
+            leadRun.set(challenger, (leadRun.get(challenger) ?? 0) + 1);
+        }
+        // Any id that is NOT a margin-leading challenger this tick loses its run.
+        for (const id of [...leadRun.keys()]) {
+            if (id !== challenger || challengerScore < incScore + switchMargin)
+                leadRun.set(id, 0);
+        }
+        const leadFrames = challenger !== null ? (leadRun.get(challenger) ?? 0) : 0;
+        const inCooldown = challenger !== null && challenger === cooldownId && cooldownLeft > 0;
+        // Forced variety: maxHold reached → yield to the best challenger (margin
+        // waived). Without a challenger this tick, keep holding (nothing to yield to).
+        const maxHoldHit = maxHoldFrames !== undefined && heldFrames >= maxHoldFrames && challenger !== null && !inCooldown;
+        const eligibleToSwitch = challenger !== null &&
+            !inCooldown &&
+            (maxHoldHit || (heldFrames >= minHoldFrames && leadFrames >= enterFrames));
+        if (eligibleToSwitch) {
+            // Dethrone: the old incumbent enters cooldown.
+            cooldownId = incumbent;
+            cooldownLeft = cooldownFrames;
+            incumbent = challenger;
+            heldFrames = 1;
+            leadRun.clear();
+        }
+        else {
+            // Hold. If there WAS a margin-leading challenger we blocked, surface it.
+            if (challenger !== null && challengerScore > incScore) {
+                const blockedBy = inCooldown
+                    ? 'cooldown'
+                    : challengerScore < incScore + switchMargin
+                        ? 'switch-margin'
+                        : heldFrames < minHoldFrames
+                            ? 'min-hold'
+                            : 'enter-debounce';
+                const releaseAtTick = blockedBy === 'min-hold'
+                    ? t + (minHoldFrames - heldFrames)
+                    : blockedBy === 'cooldown'
+                        ? t + cooldownLeft
+                        : null;
+                suppressed.push({ atTick: t, wouldHaveBeenId: challenger, byScore: challengerScore - incScore, blockedBy, releaseAtTick });
+            }
+            heldFrames++;
+        }
+        chosenPerTick[t] = incumbent;
+        if (cooldownLeft > 0)
+            cooldownLeft--;
+    }
+    return { chosenPerTick, suppressed };
+}
+/** The abstain sentinel, mirrored here so the stabilizer can recognize a held
+ *  tick without importing the model (keeps the stabilizer model-free at runtime;
+ *  the value is the same literal as `model.HOLD`). */
+const HOLD_ID = '__hold__';
+/**
+ * The presence-gate stabilizer — overlay binary show/hide (spec §6.2 + L1, NEW
+ * code). Overlay is ADDITIVE (the primary is always underneath; there is no
+ * incumbent to dethrone), so this is NOT incumbent/challenger: it is a per-
+ * candidate binary "is this overlay on?" with min-on (no blink-out) and min-gap
+ * (no re-trigger flicker) hysteresis.
+ *
+ * `wantOnPerTick[t]` is the candidate id the adapter wants overlaid at tick t (the
+ * floor-cleared winner), or `__hold__` for "no overlay this tick" (primary alone).
+ * Output: coalesced ON windows per candidate, after the min-on / min-gap debounce.
+ *
+ * Reads ONLY ids + policy knobs (the rot-guard holds). Pure + deterministic.
+ */
+export function stabilizePresenceGate(wantOnPerTick, n, params) {
+    const { minOnFrames, minGapFrames } = params;
+    const windows = [];
+    if (n === 0)
+        return windows;
+    let activeId = null;
+    let activeStart = 0;
+    // Last OFF tick per candidate (for the min-gap check) — the tick AFTER its last
+    // ON window ended.
+    const lastOffTick = new Map();
+    const closeActive = (endTick) => {
+        if (activeId !== null) {
+            windows.push({ candidateId: activeId, startTick: activeStart, endTick });
+            lastOffTick.set(activeId, endTick);
+            activeId = null;
+        }
+    };
+    for (let t = 0; t < n; t++) {
+        const want = wantOnPerTick[t];
+        if (activeId !== null) {
+            const heldFrames = t - activeStart;
+            if (want === activeId) {
+                continue; // stay on
+            }
+            // Want to turn this one off (either a different candidate or __hold__). Honor
+            // min-on: don't close before minOnFrames have elapsed.
+            if (heldFrames < minOnFrames)
+                continue; // extend the ON window through min-on
+            closeActive(t);
+            // fall through to (possibly) start a new candidate this same tick
+        }
+        if (want !== HOLD_ID) {
+            // Want this candidate ON. Honor min-gap from its OWN previous OFF.
+            const off = lastOffTick.get(want);
+            if (off !== undefined && t - off < minGapFrames) {
+                continue; // too soon to re-trigger this candidate; stay off
+            }
+            activeId = want;
+            activeStart = t;
+        }
+    }
+    closeActive(n);
+    return windows;
+}

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

@@ -0,0 +1,84 @@
+export interface ProjectSettings {
+    width: number;
+    height: number;
+}
+export interface MediaMetadata {
+    duration: number;
+    width: number;
+    height: number;
+    codec: string;
+    frameRate: number;
+    fileSize: number;
+    /** Offset between audio and video start times (seconds). Applied to transcription timestamps. */
+    audioOffset: number;
+}
+export type ProxyStatus = 'none' | 'generating' | 'ready' | 'failed';
+export type ProcessingStatus = {
+    phase: 'idle';
+} | {
+    phase: 'uploading';
+    percent: number;
+} | {
+    phase: 'processing';
+    percent: number;
+    message?: string;
+} | {
+    phase: 'complete';
+} | {
+    phase: 'error';
+    message: string;
+} | {
+    phase: 'cancelled';
+};
+export type PoolItem = {
+    id: string;
+    name: string;
+    filePath: string;
+    assetUrl: string;
+    metadata: MediaMetadata | null;
+    processingStatus: ProcessingStatus;
+    createdAt: number;
+    proxyPath: string | null;
+    proxyStatus: ProxyStatus;
+};
+export type TimelineClip = {
+    id: string;
+    poolItemId: string;
+    sourceIn: number;
+    sourceOut: number;
+    timelineStart: number;
+    timelineEnd: number;
+    playbackRate?: number;
+    volume?: number;
+    muted?: boolean;
+    opacity?: number;
+    scale?: number;
+    rotation?: number;
+    transitionIn?: 'fade' | 'dissolve' | 'wipe' | 'none';
+    transitionDuration?: number;
+};
+export type AudioTrack = {
+    id: string;
+    poolItemId: string;
+    volume: number;
+    startTime: number;
+    sourceIn: number;
+    sourceOut: number;
+    fadeInDuration?: number;
+    fadeOutDuration?: number;
+    ducking?: boolean;
+    duckingLevel?: number;
+    loop?: boolean;
+};
+export type OverlayTemplate = 'custom' | 'gif' | 'image' | 'lottie' | (string & {});
+export type OverlayParamValue = string | number | boolean | null;
+export type OverlayParams = Record<string, OverlayParamValue | Record<string, OverlayParamValue>>;
+export type Overlay = {
+    id: string;
+    template: OverlayTemplate;
+    templateId?: string;
+    startTime: number;
+    duration: number;
+    params: OverlayParams;
+    rippled?: boolean;
+};

package/dist/_members/core/types.js

@@ -0,0 +1,7 @@
+// ============ Project Types ============
+export {};
+// ============ Brand Kit Types ============
+// Moved to @cueframe/composition/brand-kit (Phase-3 Slice 1 — decouple authoring
+// from the renderer; brand is a composition-level fact). Reconcile with the
+// render-side BrandKit (@cueframe/composition/validators) + ResolvedBrandKit
+// (@cueframe/composition/projection) in Phase 4.

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

@@ -0,0 +1 @@
+export * from "./registry.js";

package/dist/_members/errors/index.js

@@ -0,0 +1 @@
+export * from "./registry";