@ossclip/scenes 0.1.35 → 0.1.37

package/package.json

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

package/src/EdlVideo.tsx

@@ -1,7 +1,7 @@
 import React, { useMemo } from "react";
 import { AbsoluteFill, OffthreadVideo, Sequence, useVideoConfig } from "remotion";
 import type { KeptSpan } from "@ossclip/core/browser";
-import { frameWindow } from "./frames";
+import { frameWindow, playableSpans } from "./frames";
 import { punchScalesFor, type PunchPlan } from "./punch-plan";
 
 export interface EdlVideoProps {
@@ -30,6 +30,11 @@ export interface EdlVideoProps {
    * and lets the backdrop through.
    */
   background?: string;
+  /**
+   * Per-window user gain (cue `video.volume`), output clock. Empty/absent =
+   * unity everywhere — the pre-feature tree, byte for byte.
+   */
+  gain?: readonly GainSegment[];
 }
 
 /**
@@ -37,17 +42,43 @@ export interface EdlVideoProps {
  * Jump cuts are concealed by alternating a slight punch-in whenever the
  * removed gap is long enough to produce a visible jump.
  */
+/** One window of user audio gain on the OUTPUT clock (cue windows). */
+export interface GainSegment {
+  startSec: number;
+  endSec: number;
+  gain: number;
+}
+
+/**
+ * The user gain at one output second — 1 outside every segment. Last match
+ * wins, mirroring how later cues paint over earlier ones; windows come from
+ * cues, which tile rather than overlap, so the rule is a tiebreak, not a
+ * feature.
+ */
+export function gainAtSec(segments: readonly GainSegment[], sec: number): number {
+  let g = 1;
+  for (const s of segments) if (sec >= s.startSec && sec < s.endSec) g = s.gain;
+  return g;
+}
+
 export const EdlVideo: React.FC<EdlVideoProps> = ({
   src,
-  spans,
+  spans: rawSpans,
   punchInScale = 1.07,
   punch = null,
   punchThresholdSec = 0.15,
   audioFadeSec = 0.01,
   background = "black",
+  gain = [],
 }) => {
   const { fps } = useVideoConfig();
 
+  // A span whose source window rounds to zero frames would mount
+  // <OffthreadVideo trimBefore={n} trimAfter={n}> — a Remotion validation
+  // THROW that blanks the whole Player (the 2026-08-31 ADK crash). Filtered
+  // here, not just at the writers, so docs saved by older versions render.
+  const spans = useMemo(() => playableSpans(rawSpans, fps), [rawSpans, fps]);
+
   // Extracted to punch-plan.ts so the mask/parity interaction is testable
   // without mounting a composition; the loop there is the reference
   // implementation the Premiere export mirrors.
@@ -65,13 +96,24 @@ export const EdlVideo: React.FC<EdlVideoProps> = ({
         // duration that is one frame long also skews the fade ramp below,
         // which measures against `durationInFrames`.
         const { from, durationInFrames } = frameWindow(sp.outIn, sp.outOut, fps);
+        // premountFor 3s, up from 1s (field report 2026-08-31): each span is
+        // its own <video> seeking a large mezzanine, and one second of
+        // premount was not always enough — entering the next span played
+        // black/silent until a scrub-back forced a reload. Three seconds
+        // costs at most one extra warm element and covers a cold seek.
         return (
-          <Sequence key={i} from={from} durationInFrames={durationInFrames} premountFor={fps}>
+          <Sequence key={i} from={from} durationInFrames={durationInFrames} premountFor={fps * 3}>
             <AbsoluteFill style={{ transform: `scale(${scales[i]})` }}>
               <OffthreadVideo
                 src={src}
                 trimBefore={Math.round(sp.srcIn * fps)}
                 trimAfter={Math.round(sp.srcOut * fps)}
+                // A span whose media is STILL not ready pauses the player
+                // instead of playing on silently over a black frame — the
+                // stall is visible and recovers by itself, where the silent
+                // variant looked broken until the user scrubbed (same field
+                // report).
+                pauseWhenBuffering
                 style={{
                   width: "100%",
                   height: "100%",
@@ -80,12 +122,25 @@ export const EdlVideo: React.FC<EdlVideoProps> = ({
                   // for a portrait source, horizontal for a landscape one.
                   objectPosition: "var(--ossclip-obj-x, 50%) var(--ossclip-obj-y, 50%)",
                 }}
-                volume={(f) =>
-                  Math.max(
+                volume={(f) => {
+                  const fade = Math.max(
                     0,
                     Math.min(1, (f + 1) / fadeFrames, (durationInFrames - f) / fadeFrames),
-                  )
-                }
+                  );
+                  // User gain composes ON the fade. Boosts above 1 land in
+                  // the render via allowAmplificationDuringRender below, and
+                  // in the Player via its WebAudio gain node — which is OFF
+                  // by default: without useWebAudioApi the preview path is
+                  // literally `element.volume = Math.min(volume, 1)`
+                  // (remotion/use-amplification, shouldUseTraditionalVolume),
+                  // so a 200% take sounded identical to 100% (field report
+                  // 2026-08-31). Enabled only when a boost exists — the
+                  // routed-through-AudioContext path is the exception, not
+                  // the default audio graph.
+                  return fade * gainAtSec(gain, (from + f) / fps);
+                }}
+                allowAmplificationDuringRender
+                useWebAudioApi={gain.some((g) => g.gain > 1)}
               />
             </AbsoluteFill>
           </Sequence>

package/src/VideoStage.tsx

@@ -17,6 +17,7 @@ import {
   type SourceFit,
   type SpanLike,
 } from "./content-crop";
+import { colorGradeFilterId, stageFilterFor, type ColorGradeProps } from "./color-grade";
 
 /**
  * The stage (PHASE1 §1): a solid backdrop that fades in when a scene demotes
@@ -68,6 +69,13 @@ export const VideoStage: React.FC<{
    * without it there is nothing to fit and this falls back to cover.
    */
   sourceFit?: SourceFit;
+  /**
+   * The `--grade` SVG filter spec, already parsed by the composition
+   * (`colorGradePropsFor` — parse, never coerce). Absent/null means no grade
+   * and ZERO new DOM: no `<svg>`, no `url()` in the filter list, so a
+   * grade-less render builds the exact tree it always did.
+   */
+  colorGrade?: ColorGradeProps | null;
   children: React.ReactNode;
 }> = ({
   cues,
@@ -81,6 +89,7 @@ export const VideoStage: React.FC<{
   sourceSize,
   contentCropMode = "cover",
   sourceFit = "cover",
+  colorGrade,
   children,
 }) => {
   const frame = useCurrentFrame();
@@ -131,8 +140,33 @@ export const VideoStage: React.FC<{
   // consumed by it (see contentTransformFor's contract).
   const contentTransform = contentTransformFor(zoom, userScale, userDx, userDy);
 
+  // Value-derived id (see colorGradeFilterId): two stages in one document can
+  // only collide when their grades are identical, which makes the collision
+  // a no-op instead of one stage silently wearing the other's grade.
+  const gradeId = colorGrade ? colorGradeFilterId(colorGrade) : null;
+
   return (
     <AbsoluteFill>
+      {colorGrade ? (
+        // Zero-sized and absolute: the element exists only to define the
+        // filter the slot's `filter: url(#…)` references; it must never take
+        // layout space in the stage.
+        <svg width={0} height={0} style={{ position: "absolute" }} aria-hidden>
+          {/* colorInterpolationFilters="sRGB" is LOAD-BEARING: the SVG spec
+              defaults filter math to linearRGB, but core sampled the transfer
+              tables and built the matrix in sRGB (gamma) space — without the
+              override the browser un-gammas the pixels first and the whole
+              grade shifts brighter/washed. */}
+          <filter id={gradeId!} colorInterpolationFilters="sRGB">
+            <feComponentTransfer>
+              <feFuncR type="table" tableValues={colorGrade.tableR.join(" ")} />
+              <feFuncG type="table" tableValues={colorGrade.tableG.join(" ")} />
+              <feFuncB type="table" tableValues={colorGrade.tableB.join(" ")} />
+            </feComponentTransfer>
+            <feColorMatrix type="matrix" values={colorGrade.colorMatrix.join(" ")} />
+          </filter>
+        </svg>
+      ) : null}
       <AbsoluteFill style={{ background: theme.bg, opacity: backdrop }} />
       <div
         // Which scene's framing a grab on the picture edits (PLAN 2026-07-30
@@ -163,7 +197,9 @@ export const VideoStage: React.FC<{
           style={{
             position: "absolute",
             inset: 0,
-            filter: slot.blurPx > 0.5 ? `blur(${slot.blurPx}px)` : undefined,
+            // Grade before blur (stageFilterFor has the ordering argument);
+            // without a grade this is the exact blur string it always was.
+            filter: stageFilterFor(gradeId, slot.blurPx),
             transform: contentTransform,
             // Zoom toward the face, which the crop bias keeps in the upper part.
             transformOrigin: "50% 40%",

package/src/color-grade.ts

@@ -0,0 +1,82 @@
+import { z } from "zod/v4";
+
+/**
+ * The `--grade` color pipeline's render half (core's color-grade.ts owns the
+ * math: `gradeToSvgFilterSpec` decomposes the grade into per-channel transfer
+ * tables plus one 5x4 color matrix). This module is the props gate, the
+ * filter id and the CSS `filter:` composition — everything about the SVG
+ * filter that is assertable without a DOM.
+ *
+ * Pure and JSX-free (house rule, `sfx-track.ts`'s posture): the component
+ * just serializes these values into `<feFuncR tableValues>` and friends.
+ */
+
+/**
+ * The precomputed spec, verbatim from `gradeToSvgFilterSpec`: 0..1 transfer
+ * table samples per channel, and a row-major 5x4 feColorMatrix. Zod (parse,
+ * never coerce, CLAUDE.md) rather than the neighbours' hand-rolled checks
+ * because the shape is four numeric arrays — exactly what a schema states
+ * more legibly than a loop. zod/v4's `z.number()` already refuses NaN and
+ * ±Infinity, which is the whole finiteness story a hand parser would need.
+ */
+const colorGradeSchema = z.object({
+  tableR: z.array(z.number()),
+  tableG: z.array(z.number()),
+  tableB: z.array(z.number()),
+  // 20 exactly: feColorMatrix silently renders NOTHING (transparent output)
+  // on a malformed `values` list, which reads as "the video vanished", not
+  // "the grade is off" — so a truncated matrix must fail here instead.
+  colorMatrix: z.array(z.number()).length(20),
+});
+
+export type ColorGradeProps = z.infer<typeof colorGradeSchema>;
+
+/**
+ * Whether a render-props `colorGrade` field is a spec this renderer will
+ * mount — `punchPropsFor`'s posture: render-props.json is user-visible and
+ * hand-editable, every pre-feature file has no key at all, and a mangled
+ * spec must fall back to NO grade (zero new DOM) rather than an feColorMatrix
+ * that blanks the picture or tables full of `undefined`.
+ */
+export function colorGradePropsFor(value: unknown): ColorGradeProps | null {
+  const parsed = colorGradeSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * A DOM id for the filter, derived from the VALUES (FNV-1a over the sample
+ * list) rather than from a counter or a random suffix: SVG filter ids are
+ * document-global, and if two stages ever share a document (editor preview
+ * next to a thumbnail), a value-derived id makes collision harmless — equal
+ * ids mean equal filter definitions, so whichever `<filter>` wins the lookup
+ * applies the same grade. A counter would make the collision silently apply
+ * one stage's grade to the other.
+ */
+export function colorGradeFilterId(spec: ColorGradeProps): string {
+  const values = [...spec.tableR, ...spec.tableG, ...spec.tableB, ...spec.colorMatrix];
+  let hash = 0x811c9dc5;
+  for (const v of values) {
+    const s = String(v);
+    for (let i = 0; i < s.length; i++) {
+      hash ^= s.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193);
+    }
+  }
+  return `ossclip-grade-${(hash >>> 0).toString(16)}`;
+}
+
+/**
+ * The video slot's composed `filter:` value. One CSS filter list takes both
+ * an SVG `url()` reference and CSS filter functions; the grade goes FIRST so
+ * the blur softens the graded picture — blurring first would average raw
+ * pixels and then re-map the averages, visibly haloing hard edges. The 0.5px
+ * blur floor predates the grade (VideoStage has always skipped sub-pixel
+ * blurs) and is kept so a grade-less render emits the exact string it always
+ * did.
+ */
+export function stageFilterFor(gradeId: string | null, blurPx: number): string | undefined {
+  const parts: string[] = [];
+  if (gradeId) parts.push(`url(#${gradeId})`);
+  if (blurPx > 0.5) parts.push(`blur(${blurPx}px)`);
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}

package/src/frames.ts

@@ -28,3 +28,19 @@ export function frameWindow(
   const to = Math.round(endSec * fps);
   return { from, durationInFrames: Math.max(1, to - from) };
 }
+
+/**
+ * Drop spans whose SOURCE window rounds to zero frames at this fps. Such a
+ * span cannot be played — `<OffthreadVideo trimBefore={n} trimAfter={n}>` is
+ * a Remotion validation THROW, and inside the Player that error boundary
+ * blanks the entire preview and stops playback (the 2026-08-31 ADK crash:
+ * a 3-decimal-rounded user cut left a 125µs keep sliver). recut.ts absorbs
+ * new slivers at the source; this filter is the defense-in-depth for docs
+ * older versions already saved.
+ */
+export function playableSpans<T extends { srcIn: number; srcOut: number }>(
+  spans: readonly T[],
+  fps: number,
+): T[] {
+  return spans.filter((sp) => Math.round(sp.srcOut * fps) > Math.round(sp.srcIn * fps));
+}

package/src/index.ts

@@ -10,4 +10,5 @@ export * from "./watermark-layout";
 export * from "./cover-in-video";
 export * from "./sfx-track";
 export * from "./punch-plan";
+export * from "./color-grade";
 export * from "./caption-visibility";