@ossclip/scenes 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/scenes",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "ossclip's scene library and stage geometry — React components shared by preview and render",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^3.25.0",
-    "@ossclip/core": "0.1.5"
+    "@ossclip/core": "0.1.7"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/CaptionTrack.tsx

@@ -4,6 +4,7 @@ import type { CaptionLine, SceneCue } from "@ossclip/core/browser";
 import { safeAreaFor, activeCueAt } from "./stage";
 import { frameWindow } from "./frames";
 import { captionAnchorAvoiding, regionsDuring, type OccupiedRegion } from "./source-fit";
+import { CAPTION_POP_SEC, easeOutQuad } from "./motion";
 
 export interface CaptionTrackProps {
   lines: CaptionLine[];
@@ -107,7 +108,15 @@ const LineView: React.FC<{
         }}
       >
         {line.words.map((w, i) => {
-          const active = t >= w.start && t <= Math.max(w.end, w.start + 0.12);
+          const held = Math.max(w.end, w.start + 0.12);
+          const inWindow = t >= w.start && t <= held;
+          // Ramp from the word's OWN start, then hold — frame-driven, because
+          // the CSS transition this replaces only ever animated in the
+          // editor's real-time <Player>; the render seeks and screenshots,
+          // so no wall-clock time passes and the scale snapped (spec
+          // 2026-08-04). Same ease as the layer's entrance and exit.
+          const p = inWindow ? Math.min(1, (t - w.start) / CAPTION_POP_SEC) : 0;
+          const pop = easeOutQuad(p);
           return (
             <span
               key={i}
@@ -122,9 +131,11 @@ const LineView: React.FC<{
                 // parent layer stays pointer-events: none); harmless in the
                 // render, where nothing dispatches events.
                 pointerEvents: "auto",
-                transform: active ? "scale(1.08)" : "scale(1)",
-                color: active ? activeColor : "white",
-                transition: "transform 60ms linear",
+                transform: pop > 0 ? `scale(${1 + 0.08 * pop})` : "scale(1)",
+                // Colour stays keyed to the window, not the ramp: colour has
+                // no in-between worth animating, and lerping it would fight
+                // the stroke.
+                color: inWindow ? activeColor : "white",
               }}
             >
               {/* Per WORD, not per line: a line straddling the cue boundary

package/src/SceneLayer.tsx

@@ -14,6 +14,7 @@ import { ChatMock } from "./components/ChatMock";
 import { ScreenshotFrame } from "./components/ScreenshotFrame";
 import { BulletList } from "./components/BulletList";
 import { compensateEdits, type ElementEdits } from "./editable";
+import { easeOutQuad, entranceExitSec } from "./motion";
 
 /* eslint-disable @typescript-eslint/no-explicit-any -- props are registry-validated upstream */
 const COMPONENTS: Record<
@@ -31,11 +32,6 @@ const COMPONENTS: Record<
   BulletList,
 };
 
-/** Seconds a graphic spends leaving. Matches LAYOUT_TRANSITION_SEC's order of
- * magnitude so the graphic departs WITH the video slot's morph — the reported
- * failure was the split view closing first and the card then blinking out. */
-const EXIT_SEC = 0.3;
-
 /**
  * Layouts whose graphic slot sits over LIVE video (R20 §94). Everywhere else
  * the graphic lands on the stage background and the theme guarantees its
@@ -57,35 +53,86 @@ const scrimColor = (themeBg: string): string => {
 };
 
 /**
- * Uniform exit for every graphic (R16 §69). Components own their ENTRANCES
- * (staggered rises, per element); the exit lives here at the layer because it
- * is the cue's END doing the animating, and every component leaving the same
- * way is what makes the cut read as designed. Inside the cue's Sequence, so
- * frame 0 is the cue's own start.
+ * Uniform EXIT for every graphic, and an entrance for the SCRIM alone —
+ * both at the layer (R16 §69).
+ *
+ * Components own their content entrances: all nine stagger their elements
+ * in through anim.ts's useEnter springs, a fact this file stated correctly
+ * for a year, then briefly contradicted when a survey missed the springs
+ * and a layer-wide entrance double-animated everything. What never animated
+ * was the over-video scrim (R21 §100), which appeared at full opacity on
+ * the cue's first frame: "a half black box appears" (spec 2026-08-04). So
+ * the entrance here is the scrim's, and only the scrim's.
+ *
+ * The exit stays layer-wide: it is the cue's END doing the animating, and
+ * every component leaving the same way is what makes the cut read as
+ * designed. Both ends read their seconds from entranceExitSec, which
+ * shrinks the pair together on a cue too short to hold both — the scrim
+ * and the exit, that is; the components' content springs (anim.ts) predate
+ * the resolver and do not read it, so a long-staggered component can still
+ * overlap the exit on a short cue (see the spec's 'Neither end may eat the
+ * other' correction). Inside the cue's Sequence, so local frame 0 is the
+ * cue's own start.
  */
+const wrapperStyle = (ease: number): React.CSSProperties => ({
+  width: "100%",
+  height: "100%",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  opacity: ease,
+  // 18px over the exit's ~9 frames. Eased, so the peak step is 3.78px on the
+  // first frame, tapering below 0.25px — small enough to read smooth at 30fps
+  // without blur, which was the actual ask. (Used only by ExitFade since the
+  // entrance was scoped to the scrim; see ./motion for the seconds.)
+  transform: ease < 1 ? `translateY(${(1 - ease) * 18}px)` : undefined,
+});
+
 const ExitFade: React.FC<{ durationInFrames: number; children: React.ReactNode }> = ({
   durationInFrames,
   children,
 }) => {
   const frame = useCurrentFrame();
   const { fps } = useVideoConfig();
+  const { exitSec } = entranceExitSec(durationInFrames / fps);
   const remaining = (durationInFrames - frame) / fps;
-  const p = Math.min(1, Math.max(0, remaining / EXIT_SEC));
-  const ease = p * (2 - p);
+  const p = exitSec <= 0 ? 1 : Math.min(1, Math.max(0, remaining / exitSec));
+  return <div style={wrapperStyle(easeOutQuad(p))}>{children}</div>;
+};
+
+/**
+ * The scrim, carrying its own entrance. One div, deliberately: an ancestor
+ * wrapper with opacity < 1 forms a Backdrop Root, which empties the
+ * backdrop-filter's input — the band rendered as flat tint for the whole
+ * entrance and the blur snapped on when the ease hit 1. Opacity on the
+ * element itself composites the blurred band at partial alpha instead, so
+ * the frost fades in WITH the tint. Positioned absolute so it stays out of
+ * ExitFade's flex flow; painted before the content div in tree order, so
+ * content keeps painting above it (R21 §100).
+ */
+const Scrim: React.FC<{ durationInFrames: number; themeBg: string; radiusPx: number }> = ({
+  durationInFrames,
+  themeBg,
+  radiusPx,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const { enterSec } = entranceExitSec(durationInFrames / fps);
+  const p = enterSec <= 0 ? 1 : Math.min(1, Math.max(0, frame / fps / enterSec));
+  const ease = easeOutQuad(p);
   return (
     <div
       style={{
-        width: "100%",
-        height: "100%",
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "center",
+        position: "absolute",
+        inset: 0,
+        background: scrimColor(themeBg),
+        backdropFilter: "blur(14px)",
+        WebkitBackdropFilter: "blur(14px)",
+        borderRadius: radiusPx,
         opacity: ease,
         transform: ease < 1 ? `translateY(${(1 - ease) * 18}px)` : undefined,
       }}
-    >
-      {children}
-    </div>
+    />
   );
 };
 
@@ -151,15 +198,10 @@ export const SceneLayer: React.FC<{ cues: SceneCue[]; theme: Theme }> = ({ cues,
             >
               <ExitFade durationInFrames={durationInFrames}>
                 {overVideo ? (
-                  <div
-                    style={{
-                      position: "absolute",
-                      inset: 0,
-                      background: scrimColor(theme.bg),
-                      backdropFilter: "blur(14px)",
-                      WebkitBackdropFilter: "blur(14px)",
-                      borderRadius: theme.radiusPx,
-                    }}
+                  <Scrim
+                    durationInFrames={durationInFrames}
+                    themeBg={theme.bg}
+                    radiusPx={theme.radiusPx}
                   />
                 ) : null}
                 {/* position:relative so the content paints (and hit-tests)

package/src/motion.ts

@@ -0,0 +1,44 @@
+/**
+ * The layer's motion constants and the one curve every animated thing in the
+ * render shares. One module rather than per-file literals so the entrance,
+ * the exit, and the caption pop cannot drift onto different curves — the
+ * design's "reads as designed" claim (R16 §69) depends on them agreeing.
+ */
+
+/** Seconds a graphic spends arriving. Mirrors EXIT_SEC — one number, both ends. */
+export const ENTER_SEC = 0.3;
+
+/** Seconds a graphic spends leaving. Matches LAYOUT_TRANSITION_SEC's order of
+ * magnitude so the graphic departs WITH the video slot's morph — the reported
+ * failure was the split view closing first and the card then blinking out. */
+export const EXIT_SEC = 0.3;
+
+/**
+ * Seconds the caption's active word takes to reach its 1.08 emphasis. Four
+ * frames at 30fps: the original CSS transition said 60ms, which is 1.8
+ * frames — honouring it exactly would still read as a step.
+ */
+export const CAPTION_POP_SEC = 0.133;
+
+/** The exit's existing ease — fast start, soft landing. */
+export const easeOutQuad = (p: number): number => p * (2 - p);
+
+/**
+ * The entrance and exit seconds for a cue, shrunk proportionally when the cue
+ * is too short to hold both. Resolved together rather than clamped
+ * independently: two independent clamps can still sum past the duration, and
+ * the failure that produces — entrance and exit overlapping, their opacities
+ * multiplying into a dip halfway through a graphic's life — is invisible in
+ * a still and obvious in motion.
+ */
+export function entranceExitSec(
+  durationSec: number,
+  enterSec: number = ENTER_SEC,
+  exitSec: number = EXIT_SEC,
+): { enterSec: number; exitSec: number } {
+  if (durationSec <= 0) return { enterSec: 0, exitSec: 0 };
+  const total = enterSec + exitSec;
+  if (total <= durationSec) return { enterSec, exitSec };
+  const k = durationSec / total;
+  return { enterSec: enterSec * k, exitSec: exitSec * k };
+}

package/src/source-fit.ts

@@ -2,7 +2,6 @@ import { SCENE_REGISTRY, type Layout, type SceneCue } from "@ossclip/core/browse
 import {
   CAPTION_HALF_BAND,
   PORTRAIT_FRAME,
-  SAFE_AREA,
   freeBands,
   layoutSlots,
   safeAreaFor,
@@ -63,6 +62,45 @@ export function overlapFraction(
   return Math.min(1, covered / rect.h);
 }
 
+/**
+ * The video rect a routed graphic must stay clear of, or null when this
+ * layout intends the graphic to sit on the picture (R27 §120).
+ *
+ * Three clauses, all read from the slot table, none naming a layout. Deriving
+ * rather than listing is load-bearing twice: §120's own list of three missed
+ * `pip-bubble`, whose fully visible bubble sits 0.1 below its graphic; and
+ * clause 2's "in THIS frame" is what sends the landscape splits — which
+ * separate by X, with a full-height video — to clause 3 instead of skipping
+ * every scene in 16:9.
+ *
+ * No startSec/endSec: those exist on OccupiedRegion because burned-in titles
+ * are transient (§32) and the video slot is not. Absent already means
+ * "always" to `regionsDuring`.
+ */
+export function videoObstacleFor(
+  layout: Layout,
+  frame: FrameSize = PORTRAIT_FRAME,
+): OccupiedRegion | null {
+  const slots = layoutSlots(layout, undefined, [], frame);
+  // Clause 0 — no graphic slot, so there is nothing to keep clear of anything.
+  // NOT "this layout never reaches the placer": full-bleed is skipped as a
+  // CANDIDATE for having no slot, then borrows the default layout's geometry
+  // and reaches the placer anyway. Answering null here is what stops it being
+  // constrained by a video band that is not on its screen (§120).
+  if (!slots.graphic) return null;
+  // Clause 1 — graphic-only parks the pip rect at zero opacity.
+  if (slots.video.opacity === 0) return null;
+  const g = slots.graphic;
+  const v = slots.video.rect;
+  const overlap = Math.min(g.y + g.h, v.y + v.h) - Math.max(g.y, v.y);
+  // Clause 3 — they already share vertical space, so the layout means it.
+  // `> 0` rather than `>= 0`: touching edges count as clear, matching the
+  // `toBeLessThanOrEqual(0)` the §120 test asserts.
+  if (overlap > 0) return null;
+  // Clause 2 — authored apart, so routing must keep them apart.
+  return { y: v.y, h: v.h };
+}
+
 /**
  * Slide a graphic rect into the tallest band that the source's text leaves
  * free, keeping its size. Returns null when no free band can hold it — the
@@ -71,8 +109,27 @@ export function overlapFraction(
 export function placeInFreeBand(
   rect: { x: number; y: number; w: number; h: number },
   regions: readonly OccupiedRegion[],
+  /**
+   * The picture, when this layout authored the graphic clear of it (§120).
+   * Optional and defaulted so every existing caller keeps its behaviour;
+   * `videoObstacleFor` returns null for the layouts that intend the overlap.
+   */
+  videoObstacle?: OccupiedRegion | null,
+  /**
+   * The output frame. The band search is the other frame-dependent geometry in
+   * routing (R15): landscape has no platform chrome to dodge, so its insets are
+   * 0.06/0.12 against portrait's 0.12/0.22. Searching the portrait safe area in
+   * a 16:9 run refuses legal area — a band at [0.72, 0.88] is 0.16 tall and
+   * free, and portrait's floor of 0.78 hides all but 0.06 of it. Optional and
+   * portrait-defaulted so every existing caller keeps its behaviour.
+   */
+  frame: FrameSize = PORTRAIT_FRAME,
 ): { x: number; y: number; w: number; h: number } | null {
-  const [tallest] = freeBands({ start: SAFE_AREA.top, end: 1 - SAFE_AREA.bottom }, regions);
+  // freeBands merges overlapping blocked rects itself, so the obstacle can
+  // simply join the text regions rather than needing to be reconciled.
+  const blocked = videoObstacle ? [...regions, videoObstacle] : regions;
+  const safe = safeAreaFor(frame);
+  const [tallest] = freeBands({ start: safe.top, end: 1 - safe.bottom }, blocked);
   if (!tallest) return null;
   const bandHeight = tallest.end - tallest.start;
   if (bandHeight < MIN_ROUTED_SLOT_H) return null;
@@ -101,6 +158,13 @@ export interface SourceTextPlan {
   relayouts: Array<{ id: string; from: Layout; to: Layout }>;
   /** Scenes whose graphic was repositioned into a free band. */
   moved: Array<{ id: string; y: number; h: number }>;
+  /**
+   * Scenes moved to a layout that INTENDS a graphic over the picture, because
+   * no band was clear of both the source's text and the video (§120). Kept
+   * separate from `relayouts` because the reason differs, and a run that
+   * quietly changes a scene's visual character should say which happened.
+   */
+  overlaid: Array<{ id: string; from: Layout; to: Layout }>;
   /** Scenes dropped because no layout had a free slot. */
   skipped: Array<{ id: string; reason: string }>;
 }
@@ -113,13 +177,20 @@ export interface SourceTextPlan {
 export function routeAroundSourceText(
   cues: readonly SceneCue[],
   regions: readonly OccupiedRegion[],
+  /**
+   * The output frame. Portrait by default so every existing caller keeps its
+   * behaviour — but a 16:9 run MUST pass its own, because the splits separate
+   * by X there and the slot table answers differently (§120).
+   */
+  frame: FrameSize = PORTRAIT_FRAME,
 ): SourceTextPlan {
   if (regions.length === 0) {
-    return { cues: [...cues], relayouts: [], moved: [], skipped: [] };
+    return { cues: [...cues], relayouts: [], moved: [], overlaid: [], skipped: [] };
   }
   const out: SceneCue[] = [];
   const relayouts: SourceTextPlan["relayouts"] = [];
   const moved: SourceTextPlan["moved"] = [];
+  const overlaid: SourceTextPlan["overlaid"] = [];
   const skipped: SourceTextPlan["skipped"] = [];
 
   for (const cue of cues) {
@@ -145,7 +216,7 @@ export function routeAroundSourceText(
     ];
     let placed: Layout | null = null;
     for (const layout of candidates) {
-      const slot = layoutSlots(layout).graphic;
+      const slot = layoutSlots(layout, undefined, [], frame).graphic;
       if (!slot) continue;
       if (overlapFraction(slot, active) <= MAX_GRAPHIC_OVERLAP) {
         placed = layout;
@@ -161,16 +232,80 @@ export function routeAroundSourceText(
     // No layout is clear where it stands — so move the slot instead of losing
     // the scene. "Route around them, or skip" is the rule, and routing comes
     // first: the graphic keeps its size and slides into the largest free band.
-    const base = layoutSlots(cue.layout).graphic ?? layoutSlots(meta.defaultLayout).graphic;
-    const shifted = base ? placeInFreeBand(base, active) : null;
+    //
+    // The SLOT may be borrowed — `full-bleed` has none, so the default layout
+    // donates its geometry — but the OBSTACLE must come from `cue.layout`, the
+    // layout that actually renders. This path only moves the rect; it never
+    // changes the layout, so asking the donor hands the placer a video band
+    // that is not on screen. A full-bleed cue would dodge pip-bubble's bubble
+    // and be skipped "because of the video" — in a layout §120's own rule
+    // classifies as intending the overlap, and for which the obstacle is null.
+    const baseLayout = layoutSlots(cue.layout, undefined, [], frame).graphic
+      ? cue.layout
+      : meta.defaultLayout;
+    const base = layoutSlots(baseLayout, undefined, [], frame).graphic;
+    const shifted = base
+      ? placeInFreeBand(base, active, videoObstacleFor(cue.layout, frame), frame)
+      : null;
     if (shifted) {
       moved.push({ id: cue.id, y: shifted.y, h: shifted.h });
       out.push({ ...cue, graphicRect: shifted });
       continue;
     }
-    skipped.push({ id: cue.id, reason: "source already has on-screen text here" });
+
+    // Adding the video as an obstacle strictly shrinks the free space, so
+    // strictly more scenes would reach the skip below than before §120 — and
+    // R25 §118 shipped under-delivery accounting because missing graphics are
+    // a known pain. Before losing the scene, try the layouts this component
+    // ALREADY declares that intend a graphic over the picture.
+    //
+    // Note this is not the candidate loop again: there, an alternate had to be
+    // clear where it was authored. Here the graphic is free to slide within
+    // the alternate, because clause 3 means its video is not an obstacle —
+    // strictly more room, which is why it can succeed where the step above
+    // failed.
+    //
+    // Drawn from the registry's altLayouts rather than a global list of
+    // overlay layouts: seven systems are keyed to the closed component enum
+    // and four fail SILENTLY on an unknown value, so routing must not invent
+    // a placement the registry has not blessed.
+    let overlay: { layout: Layout; rect: { x: number; y: number; w: number; h: number } } | null =
+      null;
+    for (const alt of meta.altLayouts ?? []) {
+      if (videoObstacleFor(alt, frame) !== null) continue;
+      const slot = layoutSlots(alt, undefined, [], frame).graphic;
+      if (!slot) continue;
+      const moved2 = placeInFreeBand(slot, active, null, frame);
+      if (moved2) {
+        overlay = { layout: alt, rect: moved2 };
+        break;
+      }
+    }
+    if (overlay) {
+      overlaid.push({ id: cue.id, from: cue.layout, to: overlay.layout });
+      out.push({ ...cue, layout: overlay.layout, graphicRect: overlay.rect });
+      continue;
+    }
+
+    // Two different failures land here now, and naming the wrong one
+    // undercuts the §118 accounting this path exists to serve: the text may
+    // have covered everything, or it may have left a band that only the
+    // VIDEO made too small to use. Retrying without the obstacle is the
+    // cheapest way to ask which, and it runs only on the skip path.
+    // Same frame as the placement it is second-guessing. Portrait's safe
+    // window is a strict subset of landscape's, so a portrait-hardcoded
+    // diagnostic in a 16:9 run would find nothing free where the placement
+    // had looked wider — and wrongly blame the TEXT for a drop the video
+    // caused (R15).
+    const clearOfTextAlone = base ? placeInFreeBand(base, active, null, frame) !== null : false;
+    skipped.push({
+      id: cue.id,
+      reason: clearOfTextAlone
+        ? "no band clear of both the source's text and the video"
+        : "source already has on-screen text here",
+    });
   }
-  return { cues: out, relayouts, moved, skipped };
+  return { cues: out, relayouts, moved, overlaid, skipped };
 }
 
 /**