@real-music-packages/web-core 0.45.2 → 0.47.0

package/dist/scene/index.js

@@ -39,6 +39,7 @@ import {
   vstackFollowBox
 } from "../chunk-DBFGX6OK.js";
 import {
+  SAFE_ZONE,
   ctaScene,
   drawSafeGuides,
   hookScene,
@@ -2528,18 +2529,18 @@ function sectionMinimapLayer() {
           c.fillRect(x0 - 1, barY - round - 3, 2, barHeight + 6);
         });
       }
-      const px = timeToX(left, width, dur, tMs);
+      const px2 = timeToX(left, width, dur, tMs);
       c.globalAlpha = 0.85;
       c.fillStyle = accent;
-      drawBar(c, left, barY - round, Math.max(0, px - left), barHeight, round);
+      drawBar(c, left, barY - round, Math.max(0, px2 - left), barHeight, round);
       c.globalAlpha = 1;
       c.fillStyle = accent;
       c.beginPath();
-      c.arc(px, barY, barHeight * 1.6, 0, Math.PI * 2);
+      c.arc(px2, barY, barHeight * 1.6, 0, Math.PI * 2);
       c.fill();
       c.fillStyle = ctx.theme.paper;
       c.beginPath();
-      c.arc(px, barY, barHeight * 0.7, 0, Math.PI * 2);
+      c.arc(px2, barY, barHeight * 0.7, 0, Math.PI * 2);
       c.fill();
       if (showLabel) {
         const act = activeSection(sections, tMs);
@@ -2549,7 +2550,7 @@ function sectionMinimapLayer() {
           c.textAlign = "center";
           c.textBaseline = "bottom";
           c.font = `700 ${Math.round(barHeight * 2.4)}px ${ctx.theme.fontBody}`;
-          c.fillText(act.label, px, barY - barHeight * 2.2);
+          c.fillText(act.label, px2, barY - barHeight * 2.2);
         }
       }
       c.restore();
@@ -3836,9 +3837,9 @@ function tensionGraphLayer() {
       c.stroke();
       const revealed = [];
       for (let i = 0; i < series.length; i++) {
-        const px = x(series[i].tMs);
-        if (px <= playX) {
-          revealed.push({ x: px, y: y(series[i].value) });
+        const px2 = x(series[i].tMs);
+        if (px2 <= playX) {
+          revealed.push({ x: px2, y: y(series[i].value) });
         } else {
           if (i > 0) {
             const a = series[i - 1], b = series[i];
@@ -4529,15 +4530,15 @@ function compositeRhythmLayer() {
         c.stroke();
       }
       if (playhead && tMs >= w0 && tMs <= w1) {
-        const px = x(tMs);
+        const px2 = x(tMs);
         const topY = grids.length ? lhY - rowGap * grids.length - tickH : lhY - tickH;
         const botY = rhY + tickH;
         c.strokeStyle = mergeColor;
         c.globalAlpha = 0.5;
         c.lineWidth = 2;
         c.beginPath();
-        c.moveTo(px, topY);
-        c.lineTo(px, botY);
+        c.moveTo(px2, topY);
+        c.lineTo(px2, botY);
         c.stroke();
         c.globalAlpha = 1;
       }
@@ -4585,6 +4586,241 @@ var compositeRhythmFactory = {
   }
 };
 
+// src/scene/layers/videoSource.ts
+var DEFAULTS12 = {
+  fit: "cover",
+  focus: { x: 0.5, y: 0.38 },
+  startMs: 0,
+  sourceStartMs: 0,
+  loop: true,
+  rate: 1,
+  mute: true,
+  opacity: 1,
+  clockMode: "play",
+  driftTolMs: 120
+};
+function clamp2(x, lo, hi) {
+  return x < lo ? lo : x > hi ? hi : x;
+}
+function fitBoxes(iW, iH, bw, bh, mode, focus) {
+  if (iW <= 0 || iH <= 0 || bw <= 0 || bh <= 0) {
+    return { sx: 0, sy: 0, sw: Math.max(0, iW), sh: Math.max(0, iH), dx: 0, dy: 0, dw: 0, dh: 0 };
+  }
+  if (mode === "contain") {
+    const scale2 = Math.min(bw / iW, bh / iH);
+    const dw = iW * scale2;
+    const dh = iH * scale2;
+    return { sx: 0, sy: 0, sw: iW, sh: iH, dx: (bw - dw) / 2, dy: (bh - dh) / 2, dw, dh };
+  }
+  const scale = Math.max(bw / iW, bh / iH);
+  const sw = Math.min(iW, bw / scale);
+  const sh = Math.min(iH, bh / scale);
+  const sx = clamp2(focus.x * iW - sw / 2, 0, iW - sw);
+  const sy = clamp2(focus.y * iH - sh / 2, 0, iH - sh);
+  return { sx, sy, sw, sh, dx: 0, dy: 0, dw: bw, dh: bh };
+}
+function sourceTimeMs(tMs, o) {
+  const elapsed = Math.max(0, (tMs - o.startMs) * o.rate);
+  const span = o.durationMs - o.sourceStartMs;
+  if (!o.loop || !(span > 0)) {
+    const end = o.durationMs > 0 ? o.durationMs : Infinity;
+    return Math.min(o.sourceStartMs + elapsed, end);
+  }
+  return o.sourceStartMs + elapsed % span;
+}
+function needsSeek(currentMs, wantMs, tolMs) {
+  return Math.abs(currentMs - wantMs) > tolMs;
+}
+function isVideoLike(x) {
+  return !!x && typeof x === "object" && typeof x.currentTime === "number" && typeof x.duration === "number";
+}
+function sourceSize(src) {
+  const s = src;
+  const w = s?.videoWidth || s?.naturalWidth || s?.width || 0;
+  const h = s?.videoHeight || s?.naturalHeight || s?.height || 0;
+  return { w, h };
+}
+function loadVideo(url, mute) {
+  const v = document.createElement("video");
+  v.src = url;
+  v.muted = mute;
+  v.playsInline = true;
+  v.preload = "auto";
+  v.crossOrigin = "anonymous";
+  return new Promise((resolve, reject) => {
+    const ok = () => resolve(v);
+    v.addEventListener("canplaythrough", ok, { once: true });
+    v.addEventListener("error", () => reject(new Error(`video-source: failed to load ${url}`)), { once: true });
+    v.load();
+  });
+}
+function videoSourceLayer() {
+  let src = null;
+  let o = { ...DEFAULTS12, durationMs: 0 };
+  let started = false;
+  return {
+    key: "video-source",
+    async init(_ctx, props) {
+      o = {
+        fit: props.fit ?? DEFAULTS12.fit,
+        focus: props.focus ?? DEFAULTS12.focus,
+        startMs: props.startMs ?? DEFAULTS12.startMs,
+        sourceStartMs: props.sourceStartMs ?? DEFAULTS12.sourceStartMs,
+        loop: props.loop ?? DEFAULTS12.loop,
+        rate: props.rate ?? DEFAULTS12.rate,
+        mute: props.mute ?? DEFAULTS12.mute,
+        opacity: props.opacity ?? DEFAULTS12.opacity,
+        clockMode: props.clockMode ?? DEFAULTS12.clockMode,
+        driftTolMs: props.driftTolMs ?? DEFAULTS12.driftTolMs,
+        durationMs: props.durationMs ?? 0
+      };
+      if (o.clockMode === "seek") {
+        throw new Error(
+          'video-source: clockMode "seek" needs an async draw path the runner does not have yet; use "play"'
+        );
+      }
+      src = typeof props.src === "string" ? await loadVideo(props.src, o.mute) : props.src;
+      if (isVideoLike(src)) {
+        src.muted = o.mute;
+        src.playbackRate = o.rate;
+        if (!o.durationMs && Number.isFinite(src.duration)) o.durationMs = src.duration * 1e3;
+      }
+    },
+    draw(ctx, tMs) {
+      if (!src) return;
+      const { w: iW, h: iH } = sourceSize(src);
+      if (iW <= 0 || iH <= 0) return;
+      if (isVideoLike(src)) {
+        const want = sourceTimeMs(tMs, o);
+        if (!started && tMs >= o.startMs) {
+          started = true;
+          src.currentTime = want / 1e3;
+          void src.play?.();
+        } else if (started && needsSeek(src.currentTime * 1e3, want, o.driftTolMs)) {
+          src.currentTime = want / 1e3;
+        }
+      }
+      const b = fitBoxes(iW, iH, ctx.W, ctx.H, o.fit, o.focus);
+      if (b.dw <= 0 || b.dh <= 0) return;
+      const g = ctx.ctx2d;
+      g.save();
+      if (o.opacity !== 1) g.globalAlpha = g.globalAlpha * o.opacity;
+      g.drawImage(src, b.sx, b.sy, b.sw, b.sh, b.dx, b.dy, b.dw, b.dh);
+      g.restore();
+    }
+  };
+}
+var videoSourceFactory = {
+  key: "video-source",
+  create: videoSourceLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["video-source: props must be an object"];
+    const p = props;
+    if (p.src == null) errs.push("video-source.src is required");
+    else if (typeof p.src !== "string" && typeof p.src !== "object") {
+      errs.push("video-source.src must be a URL string or a CanvasImageSource");
+    }
+    if (p.fit != null && p.fit !== "cover" && p.fit !== "contain") {
+      errs.push('video-source.fit must be "cover" or "contain"');
+    }
+    if (p.clockMode != null && p.clockMode !== "play" && p.clockMode !== "seek") {
+      errs.push('video-source.clockMode must be "play" or "seek"');
+    }
+    if (p.focus != null) {
+      const f = p.focus;
+      if (typeof f?.x !== "number" || typeof f?.y !== "number") {
+        errs.push("video-source.focus must be {x, y} numbers");
+      }
+    }
+    for (const k of ["startMs", "sourceStartMs", "rate", "opacity", "driftTolMs", "durationMs"]) {
+      if (p[k] != null && (typeof p[k] !== "number" || !Number.isFinite(p[k]))) {
+        errs.push(`video-source.${k} must be a finite number`);
+      }
+    }
+    if (p.rate != null && p.rate <= 0) errs.push("video-source.rate must be > 0");
+    const looping = p.loop == null ? DEFAULTS12.loop : p.loop === true;
+    if (looping && typeof p.src === "object" && p.durationMs == null) {
+      errs.push("video-source.durationMs is required when looping a non-<video> source");
+    }
+    return errs;
+  }
+};
+
+// src/scene/layers/paneSeam.ts
+var DEFAULTS13 = {
+  orientation: "h",
+  style: "line",
+  thicknessPx: 4,
+  shadowPx: 28,
+  opacity: 0.9
+};
+function paneSeamLayer() {
+  let p = { ...DEFAULTS13 };
+  return {
+    key: "pane-seam",
+    init(_ctx, props) {
+      p = {
+        atFrac: props.atFrac,
+        orientation: props.orientation ?? DEFAULTS13.orientation,
+        style: props.style ?? DEFAULTS13.style,
+        thicknessPx: props.thicknessPx ?? DEFAULTS13.thicknessPx,
+        shadowPx: props.shadowPx ?? DEFAULTS13.shadowPx,
+        opacity: props.opacity ?? DEFAULTS13.opacity,
+        color: props.color
+      };
+    },
+    draw(ctx) {
+      const g = ctx.ctx2d;
+      const horiz = p.orientation === "h";
+      const at = horiz ? p.atFrac * ctx.H : p.atFrac * ctx.W;
+      const color = p.color ?? ctx.theme.ink;
+      g.save();
+      if (p.style === "shadow" && p.shadowPx > 0) {
+        const grad = horiz ? g.createLinearGradient(0, at - p.shadowPx, 0, at + p.shadowPx) : g.createLinearGradient(at - p.shadowPx, 0, at + p.shadowPx, 0);
+        grad.addColorStop(0, "rgba(0,0,0,0)");
+        grad.addColorStop(0.5, "rgba(0,0,0,0.35)");
+        grad.addColorStop(1, "rgba(0,0,0,0)");
+        g.fillStyle = grad;
+        if (horiz) g.fillRect(0, at - p.shadowPx, ctx.W, 2 * p.shadowPx);
+        else g.fillRect(at - p.shadowPx, 0, 2 * p.shadowPx, ctx.H);
+      }
+      g.globalAlpha = g.globalAlpha * p.opacity;
+      g.fillStyle = color;
+      const t = p.thicknessPx;
+      if (horiz) g.fillRect(0, at - t / 2, ctx.W, t);
+      else g.fillRect(at - t / 2, 0, t, ctx.H);
+      g.restore();
+    }
+  };
+}
+var paneSeamFactory = {
+  key: "pane-seam",
+  create: paneSeamLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["pane-seam: props must be an object"];
+    const p = props;
+    if (typeof p.atFrac !== "number" || !Number.isFinite(p.atFrac)) {
+      errs.push("pane-seam.atFrac must be a finite number");
+    } else if (p.atFrac < 0 || p.atFrac > 1) {
+      errs.push("pane-seam.atFrac must be within 0..1");
+    }
+    if (p.orientation != null && p.orientation !== "h" && p.orientation !== "v") {
+      errs.push('pane-seam.orientation must be "h" or "v"');
+    }
+    if (p.style != null && p.style !== "line" && p.style !== "shadow") {
+      errs.push('pane-seam.style must be "line" or "shadow"');
+    }
+    for (const k of ["thicknessPx", "shadowPx", "opacity"]) {
+      if (p[k] != null && (typeof p[k] !== "number" || !Number.isFinite(p[k]))) {
+        errs.push(`pane-seam.${k} must be a finite number`);
+      }
+    }
+    return errs;
+  }
+};
+
 // src/scene/layers/handIndicator.ts
 function activeOpacity(notes, tMs, fadeMs) {
   let lastEnd = -Infinity;
@@ -4759,6 +4995,8 @@ registerLayer(endCardFactory);
 registerLayer(imageRevealFactory);
 registerLayer(compositeRhythmFactory);
 registerLayer(handIndicatorFactory);
+registerLayer(videoSourceFactory);
+registerLayer(paneSeamFactory);
 
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
@@ -4879,6 +5117,63 @@ function identityCamera(W, H) {
   return { cx: W / 2, cy: H / 2, zoom: 1 };
 }
 
+// src/scene/region.ts
+var FULL_REGION = { x: 0, y: 0, w: 1, h: 1 };
+function isFullRegion(r) {
+  return r.x === 0 && r.y === 0 && r.w === 1 && r.h === 1;
+}
+function regionRect(r, W, H) {
+  return { x: r.x * W, y: r.y * H, w: r.w * W, h: r.h * H };
+}
+function validateRegion(r) {
+  const errs = [];
+  if (typeof r !== "object" || r === null) return ["region must be an object"];
+  const o = r;
+  for (const k of ["x", "y", "w", "h"]) {
+    const v = o[k];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+      errs.push(`region.${k} must be a finite number`);
+    }
+  }
+  if (errs.length) return errs;
+  const { x, y, w, h } = o;
+  if (w <= 0 || h <= 0) errs.push("region.w and region.h must be > 0");
+  if (x < 0 || y < 0) errs.push("region.x and region.y must be >= 0");
+  if (x + w > 1 + 1e-9 || y + h > 1 + 1e-9) errs.push("region must fit inside the frame (x+w <= 1, y+h <= 1)");
+  return errs;
+}
+function paneSafeBox(r, W, H) {
+  const frame = safeBox(W, H);
+  const px2 = r.x * W;
+  const py = r.y * H;
+  const pw = r.w * W;
+  const ph = r.h * H;
+  const left = Math.min(Math.max(frame.left, px2), px2 + pw) - px2;
+  const right = Math.max(Math.min(frame.right, px2 + pw), px2) - px2;
+  const top = Math.min(Math.max(frame.top, py), py + ph) - py;
+  const bottom = Math.max(Math.min(frame.bottom, py + ph), py) - py;
+  const w = Math.max(0, right - left);
+  const h = Math.max(0, bottom - top);
+  const r2 = left + w;
+  const b2 = top + h;
+  return {
+    left,
+    right: r2,
+    top,
+    bottom: b2,
+    w,
+    h,
+    // Same expression shape as safeBox() so a full-frame region is bit-identical
+    // to the frame box (left + w/2 differs in the last float ulp).
+    cx: (left + r2) / 2,
+    cy: (top + b2) / 2,
+    // Mirrors the frame version, but centered on the PANE's midline (pw/2) —
+    // a layer centering content inside a pane centers on the pane, not on the
+    // frame, and the pane may be horizontally offset.
+    centeredW: Math.max(0, 2 * Math.min(pw / 2 - left, left + w - pw / 2))
+  };
+}
+
 // src/scene/runner.ts
 function resolveAnchor(anchor, totalSec) {
   if (typeof anchor === "number") return anchor;
@@ -4921,7 +5216,10 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "particle-burst",
   "texture",
   "stat-counter",
-  "end-card"
+  "end-card",
+  // S7c — the seam belongs to the FRAME, between the panes, so it must not pan
+  // with the camera the way a pane's contents do.
+  "pane-seam"
 ]);
 function defaultBufferFactory() {
   const g = globalThis;
@@ -4972,14 +5270,33 @@ async function buildScene(opts) {
       if (errs.length) {
         throw new Error(`buildScene: invalid props for "${sl.k}": ${errs.join("; ")}`);
       }
+      let region;
+      let base = baseCtx;
+      if (sl.region) {
+        const rErrs = validateRegion(sl.region);
+        if (rErrs.length) {
+          throw new Error(`buildScene: invalid region for "${sl.k}": ${rErrs.join("; ")}`);
+        }
+        if (!isFullRegion(sl.region)) {
+          region = sl.region;
+          base = {
+            ...baseCtx,
+            W: region.w * W,
+            H: region.h * H,
+            safeBox: paneSafeBox(region, W, H)
+          };
+        }
+      }
       const layer = factory.create();
-      await layer.init({ ...baseCtx, ctx2d: null }, sl.p ?? {});
+      await layer.init({ ...base, ctx2d: null }, sl.p ?? {});
       bound.push({
         layer,
         startMs: seg.startMs,
         endMs: seg.endMs,
         segIndex,
-        screenPinned: SCREEN_PINNED_KEYS.has(sl.k)
+        screenPinned: SCREEN_PINNED_KEYS.has(sl.k),
+        region,
+        base
       });
     }
   }
@@ -5060,6 +5377,20 @@ async function buildScene(opts) {
     }
     return plan;
   }
+  function drawBound(target, b, drawTMs, sharedCtx) {
+    if (!b.region) {
+      b.layer.draw(sharedCtx, drawTMs);
+      return;
+    }
+    const r = regionRect(b.region, W, H);
+    target.save();
+    target.beginPath();
+    target.rect(r.x, r.y, r.w, r.h);
+    target.clip();
+    target.translate(r.x, r.y);
+    b.layer.draw({ ...b.base, ctx2d: target }, drawTMs);
+    target.restore();
+  }
   function drawSegmentInto(target, segIndex, drawTMs) {
     const ctx = { ...baseCtx, ctx2d: target };
     const cam = camera(drawTMs);
@@ -5068,7 +5399,7 @@ async function buildScene(opts) {
     for (const b of bound) {
       if (b.segIndex !== segIndex || b.screenPinned) continue;
       if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
-      b.layer.draw(ctx, drawTMs);
+      drawBound(target, b, drawTMs, ctx);
     }
     target.restore();
     target.save();
@@ -5076,7 +5407,7 @@ async function buildScene(opts) {
     for (const b of bound) {
       if (b.segIndex !== segIndex || !b.screenPinned) continue;
       if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
-      b.layer.draw(ctx, drawTMs);
+      drawBound(target, b, drawTMs, ctx);
     }
     target.restore();
   }
@@ -5116,7 +5447,7 @@ async function buildScene(opts) {
       for (const b of bound) {
         if (b.screenPinned) continue;
         if (tMs < b.startMs || tMs >= b.endMs) continue;
-        b.layer.draw(ctx, tMs);
+        drawBound(ctx2d, b, tMs, ctx);
       }
       ctx2d.restore();
       ctx2d.save();
@@ -5124,7 +5455,7 @@ async function buildScene(opts) {
       for (const b of bound) {
         if (!b.screenPinned) continue;
         if (tMs < b.startMs || tMs >= b.endMs) continue;
-        b.layer.draw(ctx, tMs);
+        drawBound(ctx2d, b, tMs, ctx);
       }
       ctx2d.restore();
       return;
@@ -5186,6 +5517,345 @@ async function recordSceneSpec(opts) {
   });
 }
 
+// src/scene/presets.ts
+var DEFAULT_HOOK_CENTER_FRAC = SAFE_ZONE.top + 0.06;
+var DEFAULTS14 = {
+  split: 0.42,
+  durationSec: 8,
+  seam: "line",
+  size: [1080, 1920],
+  theme: "default",
+  fps: 30,
+  hookFontPx: 84
+};
+function reactionSplitSpec(o) {
+  const split = o.split ?? DEFAULTS14.split;
+  if (!(split > 0 && split < 1)) {
+    throw new Error(`reactionSplitSpec: split must be strictly between 0 and 1 (got ${split})`);
+  }
+  if (!o.app.length) {
+    throw new Error("reactionSplitSpec: `app` must contain at least one layer");
+  }
+  const durationSec = o.durationSec ?? DEFAULTS14.durationSec;
+  const seam = o.seam ?? DEFAULTS14.seam;
+  const topPane = { x: 0, y: 0, w: 1, h: split };
+  const bottomPane = { x: 0, y: split, w: 1, h: 1 - split };
+  const layers = [
+    { k: "video-source", region: topPane, p: o.reaction },
+    ...o.app.map((l) => ({ ...l, region: l.region ?? bottomPane }))
+  ];
+  if (seam !== "none") {
+    layers.push({ k: "pane-seam", p: { atFrac: split, orientation: "h", style: seam } });
+  }
+  layers.push({
+    k: "kinetic-text",
+    p: {
+      text: o.hook,
+      mode: "word-pop",
+      startMs: 0,
+      revealMs: 900,
+      fontPx: o.hookFontPx ?? DEFAULTS14.hookFontPx,
+      centerFrac: o.hookCenterFrac ?? DEFAULT_HOOK_CENTER_FRAC,
+      ...o.hookColor ? { color: o.hookColor } : {}
+    }
+  });
+  const timeline = [{ at: [0, "end"], layers }];
+  if (o.endCard) {
+    if (o.endCard.atSec < 0 || o.endCard.atSec >= durationSec) {
+      throw new Error(
+        `reactionSplitSpec: endCard.atSec ${o.endCard.atSec} must be within [0, ${durationSec})`
+      );
+    }
+    timeline.push({
+      at: [o.endCard.atSec, "end"],
+      layers: [{
+        k: "end-card",
+        p: {
+          ...o.endCard.text ? { text: o.endCard.text } : {},
+          ...o.endCard.handle ? { handle: o.endCard.handle } : {}
+        }
+      }]
+    });
+  }
+  return {
+    size: o.size ?? DEFAULTS14.size,
+    theme: o.theme ?? DEFAULTS14.theme,
+    durationMode: "fixed",
+    durationSec,
+    fps: o.fps ?? DEFAULTS14.fps,
+    timeline
+  };
+}
+
+// src/scene/reactions.ts
+var REACTION_EMOTIONS = [
+  "confused",
+  "shocked",
+  "impressed",
+  "delighted",
+  "deadpan",
+  "skeptical"
+];
+var DEFAULT_FOCUS = { x: 0.5, y: 0.38 };
+function isFrac(v) {
+  return typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+}
+function nonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function validateReactionManifest(json) {
+  const errs = [];
+  if (json == null || typeof json !== "object") return ["manifest must be an object"];
+  const m = json;
+  if (!Array.isArray(m.clips)) return ["manifest.clips must be an array"];
+  const seen = /* @__PURE__ */ new Set();
+  m.clips.forEach((raw, i) => {
+    const at = `clips[${i}]`;
+    if (raw == null || typeof raw !== "object") {
+      errs.push(`${at} must be an object`);
+      return;
+    }
+    const c = raw;
+    if (!nonEmptyString(c.id)) errs.push(`${at}.id must be a non-empty string`);
+    else if (seen.has(c.id)) errs.push(`${at}.id "${c.id}" is duplicated`);
+    else seen.add(c.id);
+    if (!nonEmptyString(c.file)) errs.push(`${at}.file must be a non-empty string`);
+    if (!REACTION_EMOTIONS.includes(c.emotion)) {
+      errs.push(`${at}.emotion must be one of ${REACTION_EMOTIONS.join(", ")}`);
+    }
+    if (typeof c.durationMs !== "number" || !Number.isFinite(c.durationMs) || c.durationMs <= 0) {
+      errs.push(`${at}.durationMs must be a positive number`);
+    }
+    if (!nonEmptyString(c.source)) {
+      errs.push(`${at}.source is required \u2014 record where this clip came from (no un-provenanced footage)`);
+    }
+    if (!nonEmptyString(c.licenseId)) {
+      errs.push(`${at}.licenseId is required \u2014 record the licence/receipt proving the right to use it`);
+    }
+    if (c.acquiredAt != null && !/^\d{4}-\d{2}-\d{2}$/.test(String(c.acquiredAt))) {
+      errs.push(`${at}.acquiredAt must be an ISO date (YYYY-MM-DD)`);
+    }
+    if (c.faceBox != null) {
+      const f = c.faceBox;
+      if (!Array.isArray(f) || f.length !== 4 || !f.every(isFrac)) {
+        errs.push(`${at}.faceBox must be [x, y, w, h] fractions within 0..1`);
+      } else {
+        const [x, y, w, h] = f;
+        if (w <= 0 || h <= 0) errs.push(`${at}.faceBox width/height must be > 0`);
+        if (x + w > 1 + 1e-9 || y + h > 1 + 1e-9) errs.push(`${at}.faceBox must fit inside the source`);
+      }
+    }
+  });
+  return errs;
+}
+function assertReactionManifest(json) {
+  const errs = validateReactionManifest(json);
+  if (errs.length) throw new Error(`reaction manifest invalid:
+  - ${errs.join("\n  - ")}`);
+  return json;
+}
+function clipFocus(clip) {
+  if (!clip.faceBox) return { ...DEFAULT_FOCUS };
+  const [x, y, w, h] = clip.faceBox;
+  return { x: x + w / 2, y: y + h / 2 };
+}
+function reactionProps(clip, o = {}) {
+  return {
+    src: `${o.baseUrl ?? ""}${clip.file}`,
+    fit: "cover",
+    focus: clipFocus(clip),
+    startMs: o.startMs ?? 0,
+    sourceStartMs: o.sourceStartMs ?? 0,
+    loop: o.loop ?? true,
+    rate: o.rate ?? 1,
+    durationMs: clip.durationMs
+  };
+}
+function pickClips(m, emotion) {
+  return emotion ? m.clips.filter((c) => c.emotion === emotion) : [...m.clips];
+}
+
+// src/scene/paneChecks.ts
+var PAPER_LUM_FLOOR = 200;
+function px(f, x, y) {
+  const i = (y * f.w + x) * 4;
+  return [f.data[i], f.data[i + 1], f.data[i + 2]];
+}
+function lum(r, g, b) {
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function inkFractionInRow(f, y, x0, x1) {
+  const n = x1 - x0;
+  if (n <= 0 || y < 0 || y >= f.h) return 0;
+  let ink = 0;
+  const lo = Math.max(0, x0);
+  const hi = Math.min(f.w, x1);
+  for (let x = lo; x < hi; x++) {
+    const [r, g, b] = px(f, x, y);
+    const chroma = Math.max(r, g, b) - Math.min(r, g, b);
+    if (lum(r, g, b) < PAPER_LUM_FLOOR - 30 || chroma > 40) ink++;
+  }
+  return ink / n;
+}
+function checkPaneSafety(frames, o) {
+  const srcW = o.srcW ?? 1080;
+  const srcH = o.srcH ?? 1920;
+  const maxInkFrac = o.maxInkFrac ?? 0.08;
+  const frame = safeBox(srcW, srcH);
+  const pane = regionRect(o.region, srcW, srcH);
+  const y0Src = Math.max(frame.bottom, pane.y);
+  const y1Src = pane.y + pane.h;
+  const name = "PANE SAFE ZONE";
+  if (y1Src <= y0Src) {
+    return { name, pass: true, detail: "pane ends above the frame bottom-safe line (nothing to check)" };
+  }
+  const sy = frames.frameH / srcH;
+  const sx = frames.frameW / srcW;
+  const fy0 = Math.round(y0Src * sy);
+  const fy1 = Math.round(y1Src * sy);
+  const x0 = Math.round(pane.x * sx);
+  const x1 = Math.round((pane.x + pane.w) * sx);
+  const offenders = [];
+  for (const { tSec, f } of frames.show) {
+    let worst = 0;
+    for (let y = fy0; y < Math.min(fy1, f.h); y++) {
+      worst = Math.max(worst, inkFractionInRow(f, y, x0, x1));
+    }
+    if (worst > maxInkFrac) offenders.push({ tSec: +tSec.toFixed(2), inkFrac: +worst.toFixed(3) });
+  }
+  const pass = offenders.length === 0;
+  return {
+    name,
+    pass,
+    detail: pass ? `no pane content below the frame bottom-safe line (y=${Math.round(frame.bottom)}) across ${frames.show.length} frames` : `pane content under the platform caption/action rail in ${offenders.length} samples: ${JSON.stringify(offenders.slice(0, 6))}`
+  };
+}
+function checkSeamPresent(frames, o) {
+  const srcH = o.srcH ?? 1920;
+  const tolPx = o.tolPx ?? 6;
+  const minSpan = o.minSpan ?? 0.9;
+  const sy = frames.frameH / srcH;
+  const centre = Math.round(o.splitFrac * srcH * sy);
+  const band = Math.max(1, Math.round(tolPx * sy));
+  const missing = [];
+  for (const { tSec, f } of frames.show) {
+    let best = 0;
+    for (let y = centre - band; y <= centre + band; y++) {
+      best = Math.max(best, inkFractionInRow(f, y, 0, f.w));
+    }
+    if (best < minSpan) missing.push(+tSec.toFixed(2));
+  }
+  const pass = frames.show.length > 0 && missing.length === 0;
+  return {
+    name: "PANE SEAM PRESENT",
+    pass,
+    detail: frames.show.length === 0 ? "no frames sampled (cannot verify)" : pass ? `seam rule found within ${tolPx}px of y=${o.splitFrac * srcH | 0} in all ${frames.show.length} frames` : `seam missing/broken at t=${JSON.stringify(missing.slice(0, 6))} \u2014 did the split collapse?`
+  };
+}
+function faceLandsInPane(o) {
+  const frameW = o.frameW ?? 1080;
+  const frameH = o.frameH ?? 1920;
+  const pane = regionRect(o.region, frameW, frameH);
+  const b = fitBoxes(o.srcW, o.srcH, pane.w, pane.h, o.fit ?? "cover", o.focus);
+  const [fx, fy, fw, fh] = o.faceBox;
+  const faceSrc = { x: fx * o.srcW, y: fy * o.srcH, w: fw * o.srcW, h: fh * o.srcH };
+  const ix0 = Math.max(faceSrc.x, b.sx);
+  const iy0 = Math.max(faceSrc.y, b.sy);
+  const ix1 = Math.min(faceSrc.x + faceSrc.w, b.sx + b.sw);
+  const iy1 = Math.min(faceSrc.y + faceSrc.h, b.sy + b.sh);
+  const iw = Math.max(0, ix1 - ix0);
+  const ih = Math.max(0, iy1 - iy0);
+  const visibleFrac = faceSrc.w * faceSrc.h > 0 ? iw * ih / (faceSrc.w * faceSrc.h) : 0;
+  if (iw <= 0 || ih <= 0) {
+    return {
+      ok: false,
+      visibleFrac: 0,
+      frameRect: { x: 0, y: 0, w: 0, h: 0 },
+      reason: "the declared face is entirely outside the cover crop"
+    };
+  }
+  const kx = b.dw / b.sw;
+  const ky = b.dh / b.sh;
+  const frameRect2 = {
+    x: pane.x + b.dx + (ix0 - b.sx) * kx,
+    y: pane.y + b.dy + (iy0 - b.sy) * ky,
+    w: iw * kx,
+    h: ih * ky
+  };
+  const ok = visibleFrac > 0.999;
+  return {
+    ok,
+    visibleFrac,
+    frameRect: frameRect2,
+    ...ok ? {} : { reason: `only ${(visibleFrac * 100).toFixed(1)}% of the declared face survives the crop` }
+  };
+}
+
+// src/scene/variants.ts
+function gcd(a, b) {
+  while (b) {
+    const t = a % b;
+    a = b;
+    b = t;
+  }
+  return a;
+}
+function coprimeStride(total) {
+  if (total <= 2) return 1;
+  const start = Math.max(1, Math.round(total * 0.6180339887498949));
+  for (let s = start; s < start + total; s++) {
+    const c = (s - 1) % (total - 1) + 1;
+    if (gcd(c, total) === 1) return c;
+  }
+  return 1;
+}
+function variantIndices(n, sizes, seed = 0) {
+  const total = sizes.reduce((a, b) => a * b, 1);
+  if (total <= 0 || n <= 0) return [];
+  const stride = coprimeStride(total);
+  const out = [];
+  for (let k = 0; k < n; k++) {
+    let flat = ((seed + k * stride) % total + total) % total;
+    const tuple = [];
+    for (let a = sizes.length - 1; a >= 0; a--) {
+      tuple[a] = flat % sizes[a];
+      flat = Math.floor(flat / sizes[a]);
+    }
+    out.push(tuple);
+  }
+  return out;
+}
+function slugify(s, max = 32) {
+  const base = s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return (base || "hook").slice(0, max).replace(/-+$/, "");
+}
+function reactionVariants(o) {
+  if (!o.hooks.length) throw new Error("reactionVariants: `hooks` must not be empty");
+  if (!o.clips.length) throw new Error("reactionVariants: `clips` must not be empty");
+  const endings = o.endings?.length ? o.endings : [null];
+  const sizes = [o.hooks.length, o.clips.length, endings.length];
+  const total = sizes.reduce((a, b) => a * b, 1);
+  const n = o.n ?? total;
+  return variantIndices(n, sizes, o.seed ?? 0).map(([hi, ci, ei]) => {
+    const hook = o.hooks[hi];
+    const clip = o.clips[ci];
+    const ending = endings[ei];
+    const spec = reactionSplitSpec({
+      ...o.base,
+      hook,
+      reaction: reactionProps(clip, { baseUrl: o.baseUrl }),
+      ...ending ? { endCard: ending } : {}
+    });
+    return {
+      id: `${clip.id}--${slugify(hook)}--e${ei}`,
+      hook,
+      clipId: clip.id,
+      endingIndex: ei,
+      spec
+    };
+  });
+}
+
 // src/scene/gate.ts
 var AV_TOLERANCE_MS = 60;
 async function runGate(input) {
@@ -5200,6 +5870,11 @@ async function runGate(input) {
       }
       const errs = factory.validateProps(sl.p ?? {});
       for (const e of errs) errors.push({ check: "spec", message: e });
+      if (sl.region) {
+        for (const e of validateRegion(sl.region)) {
+          errors.push({ check: "spec", message: `layer "${sl.k}": ${e}` });
+        }
+      }
     }
   }
   try {
@@ -5281,12 +5956,12 @@ function mapBoxThroughLayout(base, b) {
   };
 }
 function followSrcBox(rn, focusBoxCanvas) {
-  const px = focusBoxCanvas.w * (FOLLOW_PAD - 1) / 2;
+  const px2 = focusBoxCanvas.w * (FOLLOW_PAD - 1) / 2;
   const py = focusBoxCanvas.h * (FOLLOW_PAD - 1) / 2;
   const src = {
-    x: Math.max(0, focusBoxCanvas.x - px),
+    x: Math.max(0, focusBoxCanvas.x - px2),
     y: Math.max(0, focusBoxCanvas.y - py),
-    w: focusBoxCanvas.w + 2 * px,
+    w: focusBoxCanvas.w + 2 * px2,
     h: focusBoxCanvas.h + 2 * py
   };
   src.w = Math.min(src.w, rn.canvas.width - src.x);
@@ -5503,13 +6178,18 @@ function contourMinimapDemoSpec(opts = {}) {
   };
 }
 export {
+  DEFAULT_FOCUS,
   DEFAULT_FUNCTION_COLORS,
+  DEFAULT_HOOK_CENTER_FRAC,
   FIFTHS_MAJOR,
   FIFTHS_MINOR,
   FOLLOW_BARS,
   FOLLOW_PAD,
+  FULL_REGION,
+  PAPER_LUM_FLOOR,
   PIANO_HIGH,
   PIANO_LOW,
+  REACTION_EMOTIONS,
   SCALE_INTERVALS,
   activeChord,
   activeCue,
@@ -5518,6 +6198,7 @@ export {
   applySchedule,
   applyToContext,
   assertGate,
+  assertReactionManifest,
   audioPlayheadLine,
   ballArc,
   ballX,
@@ -5530,15 +6211,19 @@ export {
   buildScene,
   cameraForFollow,
   cameraTransform,
+  checkPaneSafety,
+  checkSeamPresent,
   chordRibbonFactory,
   circleOfFifthsDemoSpec,
   circleOfFifthsFactory,
   clamp,
   clickTrackSchedule,
+  clipFocus,
   compositeRhythmFactory,
   contourMinimapDemoSpec,
   contourPoints,
   contourPolyline,
+  coprimeStride,
   countInLeadSec,
   countInSchedule,
   countdownFactory,
@@ -5563,10 +6248,12 @@ export {
   easeInOut,
   easeOut,
   endCardFactory,
+  faceLandsInPane,
   fallingKeyboardDemoScore,
   fallingKeyboardDemoSpec,
   fallingNotesFactory,
   firstMeasureBox,
+  fitBoxes,
   followBoxAt,
   followSrcBox,
   followWindowStart,
@@ -5585,9 +6272,11 @@ export {
   identityCamera,
   imageRevealFactory,
   inRange,
+  inkFractionInRow,
   intervalArcsFactory,
   invLerp,
   isBlackKey,
+  isFullRegion,
   karaokeCaptionFactory,
   kenBurns,
   keyCenterX,
@@ -5611,14 +6300,18 @@ export {
   measureSystemMap,
   timeToX as minimapTimeToX,
   msPerBeat,
+  needsSeek,
   notationFactory,
   notationLayout,
   noteColor,
   noteSetXRange,
+  paneSafeBox,
+  paneSeamFactory,
   parseKey,
   parseTimeSig,
   particleBurstFactory,
   pcToSlot,
+  pickClips,
   pitchAt,
   pitchContourFactory,
   pitchRange,
@@ -5633,7 +6326,11 @@ export {
   radialSpectrumFactory,
   rayEndpoints,
   rayPointAt,
+  reactionProps,
+  reactionSplitSpec,
+  reactionVariants,
   recordSceneSpec,
+  regionRect,
   registerLayer,
   registeredKeys,
   resolveAnchor,
@@ -5654,6 +6351,9 @@ export {
   slotAngle,
   slotPc,
   slotPoint,
+  slugify,
+  sourceSize,
+  sourceTimeMs,
   spectrumFactory,
   staffAnchor,
   staffKeyboardRayFactory,
@@ -5665,7 +6365,11 @@ export {
   transitionProgress,
   validateChordTrack,
   validateQuiz,
+  validateReactionManifest,
+  validateRegion,
   validateSections,
+  variantIndices,
+  videoSourceFactory,
   visualTimelineMs,
   vstackAudioPlayheadLine,
   vstackFollowBox,