@ossclip/scenes 0.1.31 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/scenes",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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.31"
+    "@ossclip/core": "0.1.33"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/CoverInVideo.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import { AbsoluteFill, Img, Sequence, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+import {
+  coverInVideoFrames,
+  coverInVideoOpacity,
+  type CoverInVideoProps,
+} from "./cover-in-video";
+
+/** The overlay's own frame — inside the Sequence, so frame 0 is frame 1 of
+ * the video and the fade math (cover-in-video.ts) reads the local clock. */
+const CoverImage: React.FC<{ cover: CoverInVideoProps; durationInFrames: number }> = ({
+  cover,
+  durationInFrames,
+}) => {
+  const frame = useCurrentFrame();
+  return (
+    <AbsoluteFill
+      style={{
+        // Black behind the image, not transparent: the cover is rendered at
+        // the OUTPUT frame's exact size (produce renders it from `frame`), but
+        // an image that ever disagrees must letterbox against the same black
+        // the composition's own backdrop uses rather than flash the video
+        // through the margins.
+        backgroundColor: "black",
+        opacity: coverInVideoOpacity(frame, durationInFrames),
+      }}
+    >
+      <Img
+        // An http(s) URL passes through untouched, everything else is a name
+        // in the render's public dir — CoverComposition's exact rule, and the
+        // one that also lets the editor hand this component a `/media/…` URL
+        // (staticFile leaves an already-rooted path alone).
+        src={/^https?:\/\//.test(cover.fileName) ? cover.fileName : staticFile(cover.fileName)}
+        style={{ width: "100%", height: "100%", objectFit: "cover" }}
+      />
+    </AbsoluteFill>
+  );
+};
+
+/**
+ * `--cover-in-video`: the cover image over the short's first frames (see
+ * cover-in-video.ts for the overlay-not-insertion argument and the window
+ * bounds). Mounted ABOVE everything — video, scenes, captions, watermark —
+ * because a cover with a caption burned through it is not a cover.
+ *
+ * Deliberately invisible to the editor, the Watermark's rule for the same
+ * reason: no `data-edit-id`/`data-edit-scene` so hitTest.ts can never resolve
+ * it as a selection, and `pointerEvents: none` so a click at frame 0 falls
+ * through to whatever the overlay covers. It is a produce-time switch, not a
+ * scene element.
+ */
+export const CoverInVideo: React.FC<{ cover: CoverInVideoProps }> = ({ cover }) => {
+  const { fps } = useVideoConfig();
+  const { from, durationInFrames } = coverInVideoFrames(cover.durationSec, fps);
+  return (
+    <Sequence from={from} durationInFrames={durationInFrames} layout="none">
+      <AbsoluteFill style={{ pointerEvents: "none" }}>
+        <CoverImage cover={cover} durationInFrames={durationInFrames} />
+      </AbsoluteFill>
+    </Sequence>
+  );
+};

package/src/cover-in-video.ts

@@ -0,0 +1,72 @@
+import { frameWindow } from "./frames";
+
+/**
+ * The `--cover-in-video` overlay (core's cover-in-video.ts owns the WHY and
+ * the window derivation): the cover image painted over the opening frames,
+ * for the platforms that use frame 1 instead of an uploaded cover.
+ *
+ * Pure and JSX-free (house rule, `punch-plan.ts`'s posture): the gate, the
+ * frame math and the fade are the whole behavior, and this package carries no
+ * jsdom — none of it would be assertable if it lived inside the component.
+ */
+
+export interface CoverInVideoProps {
+  /** Image file name inside the render's public dir (or an absolute http(s) URL). */
+  fileName: string;
+  /** How long the overlay lasts, in OUTPUT seconds from frame 0. */
+  durationSec: number;
+}
+
+/**
+ * How many frames the overlay spends fading out. Long enough that the cut to
+ * video is a transition rather than a pop, short enough that it does not eat
+ * a meaningful slice of a window whose cap is half a second.
+ */
+export const COVER_IN_VIDEO_FADE_FRAMES = 4;
+
+/**
+ * Whether a render-props `coverInVideo` field is an overlay this renderer
+ * will mount — `punchPropsFor`'s posture (parse, never coerce, CLAUDE.md):
+ * render-props.json is user-visible and hand-editable, every pre-feature file
+ * has no key at all, and a mangled one must fall back to NO overlay rather
+ * than mount an `undefined` src or a NaN-frame Sequence over the hook.
+ */
+export function coverInVideoPropsFor(value: unknown): CoverInVideoProps | null {
+  if (typeof value !== "object" || value === null) return null;
+  const v = value as { fileName?: unknown; durationSec?: unknown };
+  if (typeof v.fileName !== "string" || v.fileName.length === 0) return null;
+  if (typeof v.durationSec !== "number" || !Number.isFinite(v.durationSec) || v.durationSec <= 0) {
+    return null;
+  }
+  return { fileName: v.fileName, durationSec: v.durationSec };
+}
+
+/**
+ * The overlay's `<Sequence>` window. Always from frame 0 — the whole point is
+ * frame 1 — and the end comes from the end TIME through `frameWindow`
+ * (FINDINGS §115), not from a rounded duration, so the overlay's last frame
+ * and the first uncovered frame can never be the same one.
+ */
+export function coverInVideoFrames(
+  durationSec: number,
+  fps: number,
+): { from: number; durationInFrames: number } {
+  return frameWindow(0, durationSec, fps);
+}
+
+/**
+ * Opacity at `frame` (SEQUENCE-relative, so 0 is the first covered frame) for
+ * a window `durationInFrames` long: solid, then a linear ramp over the last
+ * `COVER_IN_VIDEO_FADE_FRAMES`.
+ *
+ * The ramp is capped at the window's own length, so a sub-fade window (a 0.2s
+ * floor at a low fps) fades across what it has instead of starting below 1 —
+ * a cover that is never fully opaque looks like a rendering fault, not a
+ * transition.
+ */
+export function coverInVideoOpacity(frame: number, durationInFrames: number): number {
+  const fade = Math.min(COVER_IN_VIDEO_FADE_FRAMES, durationInFrames);
+  const remaining = durationInFrames - frame;
+  if (remaining >= fade) return 1;
+  return Math.min(1, Math.max(0, remaining / fade));
+}

package/src/index.ts

@@ -3,7 +3,9 @@ export { CaptionTrack, type CaptionTrackProps } from "./CaptionTrack";
 export { VideoStage } from "./VideoStage";
 export { SceneLayer } from "./SceneLayer";
 export { Watermark } from "./Watermark";
+export { CoverInVideo } from "./CoverInVideo";
 export * from "./stage";
 export * from "./watermark-layout";
+export * from "./cover-in-video";
 export * from "./punch-plan";
 export * from "./caption-visibility";