@cueframe/kernel 0.0.1

package/dist/chunk-JRQVPFLF.js

@@ -0,0 +1,459 @@
+import {
+  CueframeError,
+  encodeError
+} from "./chunk-37NJ27UU.js";
+
+// ../execution/core/src/render/vcam/constants.ts
+var P_MIN = 0.5;
+var SIZE_MIN = 0.06;
+var SIZE_DOMINANT = 0.18;
+var MAX_SUBJECTS = 3;
+var DOMINANCE_WEIGHTS = {
+  size: 0.4,
+  centrality: 0.2,
+  persistence: 0.2,
+  speaking: 0.2
+};
+var ENTER_SEC = 0.3;
+var LEAVE_SEC = 0.5;
+var REGION_PAD = 0.06;
+var DEADZONE = 0.1;
+var SMOOTH_WINDOW_SEC = 0.5;
+var REGION_MEDIAN_SEC = 0.12;
+var REACQUIRE_GLIDE_PER_SEC = 8;
+var ZOOM_MIN = 0.4;
+var ZOOM_MAX = 1;
+var MIN_ZOOM_SHOT_FRAMES = 0.4;
+
+// ../execution/core/src/select/model.ts
+var HOLD = "__hold__";
+
+// ../execution/core/src/select/select.ts
+function fail(code, message, fix) {
+  throw new Error(encodeError(new CueframeError(code, message, fix)));
+}
+function clauseHolds(sig, clause) {
+  if (clause.signal !== void 0) {
+    const s = sig[clause.signal];
+    if (s === void 0) return false;
+    if (clause.gte !== void 0 && s.value < clause.gte) return false;
+  }
+  return true;
+}
+function whenHolds(sig, when) {
+  const all = when.all ?? [];
+  const any = when.any ?? [];
+  if (all.length > 0 && !all.every((c) => clauseHolds(sig, c))) return false;
+  if (any.length > 0 && !any.some((c) => clauseHolds(sig, c))) return false;
+  return true;
+}
+function scoreCandidate(id, sig, weightKeys, weights, ruleBoost) {
+  const contributions = {};
+  let score = 0;
+  for (const k of weightKeys) {
+    const w = weights[k];
+    const s = sig[k];
+    const v = s ? s.value * (s.confidence ?? 1) : 0;
+    const term = w * v;
+    contributions[k] = term;
+    score += term;
+  }
+  score += ruleBoost;
+  return { candidateId: id, score, contributions };
+}
+function select(candidates, policy, opts) {
+  const { dtSec, ticks } = opts;
+  const ids = candidates.map((c) => c.id);
+  const idSet = new Set(ids);
+  const weightKeys = Object.keys(policy.weights).filter((k) => (policy.weights[k] ?? 0) > 0);
+  for (const k of weightKeys) {
+    let measured = false;
+    for (const c of candidates) {
+      for (const env of c.signals) if (env[k] !== void 0) {
+        measured = true;
+        break;
+      }
+      if (measured) break;
+    }
+    if (!measured) {
+      fail("selector_signal_absent", `weight on signal '${k}' but no candidate measures it at any moment`, { signal: k });
+    }
+  }
+  for (const o of policy.overrides ?? []) {
+    if (!idSet.has(o.candidateId)) fail("selector_override_conflict", `override candidateId '${o.candidateId}' not in roster`, { candidateId: o.candidateId });
+  }
+  const rules = policy.rules ?? [];
+  const eligibility = policy.eligibility ?? [];
+  const floor = policy.floor ?? {};
+  const segments = new Array(ticks);
+  for (let t = 0; t < ticks; t++) {
+    const startSec = t * dtSec;
+    const endSec = (t + 1) * dtSec;
+    const tSec = startSec;
+    const hits = (policy.overrides ?? []).filter((o) => tSec >= o.startSec && tSec < o.endSec);
+    if (hits.length > 1) {
+      fail("selector_override_conflict", `two overlapping overrides at ${tSec}s: ${hits.map((h) => h.candidateId).join(", ")}`, { atSec: tSec });
+    }
+    if (hits.length === 1) {
+      segments[t] = pinned(startSec, endSec, hits[0].candidateId, "override", "override span");
+      continue;
+    }
+    if (policy.lockSourceId && idSet.has(policy.lockSourceId)) {
+      segments[t] = pinned(startSec, endSec, policy.lockSourceId, "lock", `locked to '${policy.lockSourceId}'`);
+      continue;
+    }
+    const sigAt = (c) => c.signals[t] ?? {};
+    const eligible = candidates.filter((c) => eligibility.length === 0 || eligibility.every((cl) => clauseHolds(sigAt(c), cl)));
+    const ruleBoostFor = (c) => {
+      let boost = 0;
+      const forces = [];
+      for (const r of rules) {
+        const fires = whenHolds(sigAt(c), r.when) && rulePrefers(r, c.id);
+        if (!fires) continue;
+        if (r.then.force) forces.push(r);
+        boost += r.then.boost ?? 0.3;
+      }
+      return { boost, forces };
+    };
+    const forcedIds = /* @__PURE__ */ new Set();
+    for (const c of eligible) {
+      const { forces } = ruleBoostFor(c);
+      if (forces.length > 0) forcedIds.add(c.id);
+    }
+    if (forcedIds.size > 1) {
+      fail("selector_override_conflict", `two force rules elect different candidates at ${tSec}s: ${[...forcedIds].join(", ")}`, { atSec: tSec });
+    }
+    if (forcedIds.size === 1) {
+      const fid = [...forcedIds][0];
+      const scored2 = scoreAll(eligible, sigAt, weightKeys, policy.weights, ruleBoostFor);
+      segments[t] = { startSec, endSec, chosen: fid, alsoChosen: [], perCandidateScores: scored2, reasons: [`force rule \u2192 '${fid}'`], pacingNote: "rule" };
+      continue;
+    }
+    const scored = scoreAll(eligible, sigAt, weightKeys, policy.weights, ruleBoostFor);
+    const floorKeys = Object.keys(floor);
+    const anyAboveFloor = floorKeys.length === 0 || eligible.some((c) => {
+      const sig = sigAt(c);
+      return floorKeys.some((k2) => sig[k2] !== void 0 && sig[k2].value >= (floor[k2] ?? 0));
+    });
+    if (eligible.length === 0 || !anyAboveFloor) {
+      segments[t] = { startSec, endSec, chosen: HOLD, alsoChosen: [], perCandidateScores: scored, reasons: floorKeys.length && eligible.length ? ["no candidate above floor"] : ["no eligible candidate"], pacingNote: "hold" };
+      continue;
+    }
+    const k = Math.max(1, policy.topK);
+    const top = scored.slice(0, k);
+    segments[t] = {
+      startSec,
+      endSec,
+      chosen: top[0].candidateId,
+      alsoChosen: top.slice(1).map((s) => s.candidateId),
+      perCandidateScores: scored,
+      reasons: [`argmax score ${top[0].score.toFixed(4)}`],
+      pacingNote: "argmax"
+    };
+  }
+  return segments;
+}
+function pinned(startSec, endSec, id, note, reason) {
+  return { startSec, endSec, chosen: id, alsoChosen: [], perCandidateScores: [], reasons: [reason], pacingNote: note };
+}
+function rulePrefers(r, id) {
+  if (r.then.preferCandidateId !== void 0) return r.then.preferCandidateId === id;
+  return true;
+}
+function scoreAll(cands, sigAt, weightKeys, weights, ruleBoostFor) {
+  const scored = cands.map((c) => scoreCandidate(c.id, sigAt(c), weightKeys, weights, ruleBoostFor(c).boost));
+  return sortScores(scored);
+}
+function sortScores(scored) {
+  scored.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.candidateId < b.candidateId ? -1 : a.candidateId > b.candidateId ? 1 : 0;
+  });
+  return scored;
+}
+function scoreAndRank(candidates, weights) {
+  const weightKeys = Object.keys(weights);
+  const scored = candidates.map((c) => scoreCandidate(c.id, c.signals, weightKeys, weights, 0));
+  return sortScores(scored);
+}
+
+// ../execution/core/src/render/vcam/shots.ts
+function segmentShots(interiorCuts, segLen) {
+  if (segLen <= 0) return [];
+  const cuts = [...new Set(interiorCuts)].filter((c) => c > 0 && c < segLen).sort((a, b) => a - b);
+  const bounds = [0, ...cuts, segLen];
+  const shots = [];
+  for (let i = 0; i < bounds.length - 1; i++) {
+    const start = bounds[i];
+    const end = bounds[i + 1];
+    if (end - start > 0) shots.push({ start, end });
+  }
+  return shots;
+}
+
+// ../execution/core/src/render/vcam/cameraPath.ts
+function clampCenter(c, sizeFrac) {
+  if (sizeFrac >= 1) return 0.5;
+  const half = sizeFrac / 2;
+  return Math.max(half, Math.min(1 - half, c));
+}
+function gate1D(held, lo, hi, win, dz) {
+  const safe = Math.max(0, win - 2 * dz);
+  const ext = hi - lo;
+  const mid = (lo + hi) / 2;
+  if (ext >= safe) {
+    if (Math.abs(mid - held) <= dz) return held;
+    return mid > held ? mid - dz : mid + dz;
+  }
+  const safeLo = held - safe / 2;
+  const safeHi = held + safe / 2;
+  if (lo >= safeLo && hi <= safeHi) return held;
+  if (lo < safeLo) return lo + safe / 2;
+  return hi - safe / 2;
+}
+function includeGlide1D(c, prev, lo, hi, win, maxStep) {
+  const ext = hi - lo;
+  let target;
+  if (ext >= win) {
+    target = c;
+  } else {
+    const winLo = c - win / 2;
+    const winHi = c + win / 2;
+    if (lo >= winLo && hi <= winHi) target = c;
+    else if (lo < winLo) target = lo + win / 2;
+    else target = hi - win / 2;
+  }
+  const d = target - prev;
+  if (d > maxStep) return prev + maxStep;
+  if (d < -maxStep) return prev - maxStep;
+  return target;
+}
+function deadzoneGate(regions, crop, dzX, dzY) {
+  const out = [];
+  let hx = clampCenter(regions[0].cx, crop.w);
+  let hy = clampCenter(regions[0].cy, crop.h);
+  for (const r of regions) {
+    const loX = r.cx - r.w / 2;
+    const hiX = r.cx + r.w / 2;
+    const loY = r.cy - r.h / 2;
+    const hiY = r.cy + r.h / 2;
+    hx = clampCenter(gate1D(hx, loX, hiX, crop.w, dzX), crop.w);
+    hy = clampCenter(gate1D(hy, loY, hiY, crop.h, dzY), crop.h);
+    out.push([hx, hy]);
+  }
+  return out;
+}
+function hammingSmooth(centers, halfWindow) {
+  const n = centers.length;
+  if (n <= 1 || halfWindow < 1) return centers.map((c) => [c[0], c[1]]);
+  const weight = (d) => 0.54 + 0.46 * Math.cos(Math.PI * d / halfWindow);
+  const out = new Array(n);
+  for (let i = 0; i < n; i++) {
+    const lo = Math.max(0, i - halfWindow);
+    const hi = Math.min(n - 1, i + halfWindow);
+    let sx = 0;
+    let sy = 0;
+    let sw = 0;
+    for (let j = lo; j <= hi; j++) {
+      const w = weight(j - i);
+      sx += centers[j][0] * w;
+      sy += centers[j][1] * w;
+      sw += w;
+    }
+    out[i] = sw > 0 ? [sx / sw, sy / sw] : [centers[i][0], centers[i][1]];
+  }
+  return out;
+}
+function fillShot(regions) {
+  const first = regions.find((r) => r !== null) ?? null;
+  if (first === null) return null;
+  const out = new Array(regions.length);
+  let last = first;
+  for (let i = 0; i < regions.length; i++) {
+    if (regions[i] !== null) last = regions[i];
+    out[i] = last;
+  }
+  return out;
+}
+function cameraPath(regions, cropFor, fps, interiorCuts, centerHold = [0.5, 0.5]) {
+  const n = regions.length;
+  if (n === 0) return [];
+  const halfWindow = Math.max(1, Math.round(SMOOTH_WINDOW_SEC * fps));
+  const out = new Array(n);
+  const shots = segmentShots(interiorCuts, n);
+  for (const shot of shots) {
+    const slice = regions.slice(shot.start, shot.end);
+    const filled = fillShot(slice);
+    if (filled === null) {
+      for (let i = shot.start; i < shot.end; i++) out[i] = [centerHold[0], centerHold[1]];
+      continue;
+    }
+    const crop0 = cropFor(shot.start);
+    const dzX = DEADZONE * crop0.w;
+    const dzY = DEADZONE * crop0.h;
+    const gated = deadzoneGate(filled, crop0, dzX, dzY);
+    const hw = Math.min(halfWindow, Math.max(1, gated.length - 1));
+    const smoothed = hammingSmooth(gated, hw);
+    const maxStepX = REACQUIRE_GLIDE_PER_SEC * crop0.w / fps;
+    const maxStepY = REACQUIRE_GLIDE_PER_SEC * crop0.h / fps;
+    let prevX = clampCenter(smoothed[0][0], crop0.w);
+    let prevY = clampCenter(smoothed[0][1], crop0.h);
+    for (let i = 0; i < smoothed.length; i++) {
+      const crop = cropFor(shot.start + i);
+      const r = filled[i];
+      const incX = includeGlide1D(smoothed[i][0], prevX, r.cx - r.w / 2, r.cx + r.w / 2, crop.w, maxStepX);
+      const incY = includeGlide1D(smoothed[i][1], prevY, r.cy - r.h / 2, r.cy + r.h / 2, crop.h, maxStepY);
+      prevX = clampCenter(incX, crop.w);
+      prevY = clampCenter(incY, crop.h);
+      out[shot.start + i] = [prevX, prevY];
+    }
+  }
+  return out;
+}
+
+// ../execution/core/src/select/stabilize.ts
+function stabilizeSelectionHysteresis(framedIds, presence, n, params) {
+  const { enterFrames, leaveFrames } = params;
+  const everIn = /* @__PURE__ */ 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 };
+}
+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 };
+  let incumbent = null;
+  let heldFrames = 0;
+  const leadRun = /* @__PURE__ */ new Map();
+  let cooldownId = null;
+  let cooldownLeft = 0;
+  for (let t = 0; t < n; t++) {
+    const raw = rawWinnerPerTick[t];
+    if (incumbent === null) {
+      if (raw !== HOLD_ID) {
+        incumbent = raw;
+        heldFrames = 1;
+      }
+      chosenPerTick[t] = incumbent ?? raw;
+      if (cooldownLeft > 0) cooldownLeft--;
+      continue;
+    }
+    const incScore = scoreById(incumbent, t);
+    let challenger = null;
+    let challengerScore = -Infinity;
+    if (raw !== HOLD_ID && raw !== incumbent) {
+      challenger = raw;
+      challengerScore = scoreById(raw, t);
+    }
+    if (challenger !== null && challengerScore >= incScore + switchMargin) {
+      leadRun.set(challenger, (leadRun.get(challenger) ?? 0) + 1);
+    }
+    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;
+    const maxHoldHit = maxHoldFrames !== void 0 && heldFrames >= maxHoldFrames && challenger !== null && !inCooldown;
+    const eligibleToSwitch = challenger !== null && !inCooldown && (maxHoldHit || heldFrames >= minHoldFrames && leadFrames >= enterFrames);
+    if (eligibleToSwitch) {
+      cooldownId = incumbent;
+      cooldownLeft = cooldownFrames;
+      incumbent = challenger;
+      heldFrames = 1;
+      leadRun.clear();
+    } else {
+      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 };
+}
+var HOLD_ID = "__hold__";
+function stabilizePresenceGate(wantOnPerTick, n, params) {
+  const { minOnFrames, minGapFrames } = params;
+  const windows = [];
+  if (n === 0) return windows;
+  let activeId = null;
+  let activeStart = 0;
+  const lastOffTick = /* @__PURE__ */ 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;
+      }
+      if (heldFrames < minOnFrames) continue;
+      closeActive(t);
+    }
+    if (want !== HOLD_ID) {
+      const off = lastOffTick.get(want);
+      if (off !== void 0 && t - off < minGapFrames) {
+        continue;
+      }
+      activeId = want;
+      activeStart = t;
+    }
+  }
+  closeActive(n);
+  return windows;
+}
+
+export {
+  segmentShots,
+  P_MIN,
+  SIZE_MIN,
+  SIZE_DOMINANT,
+  MAX_SUBJECTS,
+  DOMINANCE_WEIGHTS,
+  ENTER_SEC,
+  LEAVE_SEC,
+  REGION_PAD,
+  REGION_MEDIAN_SEC,
+  ZOOM_MIN,
+  ZOOM_MAX,
+  MIN_ZOOM_SHOT_FRAMES,
+  HOLD,
+  select,
+  scoreAndRank,
+  cameraPath,
+  stabilizeSelectionHysteresis,
+  stabilizeIncumbentChallenger,
+  stabilizePresenceGate
+};