@ossclip/scenes 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Ahsan Ayaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note (not part of the MIT grant above, which covers this repository's own
+code): rendering depends on Remotion, which is source-available under its own
+two-tier licence — see https://github.com/remotion-dev/remotion/blob/main/LICENSE.md.

package/README.md

@@ -0,0 +1,20 @@
+# @ossclip/scenes
+
+Part of [**ossclip**](https://github.com/AhsanAyaz/ossclip) — a local-first CLI that turns a talking-head take into a finished short: silence and filler words cut, word-timed kinetic captions, face-aware framing, and LLM-planned code-rendered on-screen graphics.
+
+This package is the scene library and stage geometry — React components shared by the editor preview and the render.
+
+It is published so the CLI can depend on it and so the pieces are reusable, but the supported entry point is the CLI:
+
+```sh
+npm install -g ossclip
+ossclip doctor
+```
+
+APIs here move between rounds — pin an exact version if you depend on them directly.
+
+**Documentation:** [github.com/AhsanAyaz/ossclip](https://github.com/AhsanAyaz/ossclip)
+
+## Licence
+
+MIT. Rendering depends on [Remotion](https://www.remotion.dev/), which carries [its own two-tier licence](https://github.com/remotion-dev/remotion/blob/main/LICENSE.md).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ossclip/scenes",
+  "version": "0.1.0",
+  "description": "ossclip's scene library and stage geometry — React components shared by preview and render",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AhsanAyaz/ossclip.git",
+    "directory": "packages/scenes"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./geometry": "./src/geometry.ts"
+  },
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "dependencies": {
+    "zod": "^3.25.0",
+    "@ossclip/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "remotion": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
+    "remotion": "^4.0.0"
+  },
+  "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
+  "bugs": {
+    "url": "https://github.com/AhsanAyaz/ossclip/issues"
+  },
+  "author": "Muhammad Ahsan Ayaz"
+}

package/src/CaptionTrack.tsx

@@ -0,0 +1,209 @@
+import React from "react";
+import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import type { CaptionLine, SceneCue } from "@ossclip/core/browser";
+import { safeAreaFor, activeCueAt } from "./stage";
+import { captionAnchorAvoiding, regionsDuring, type OccupiedRegion } from "./source-fit";
+
+export interface CaptionTrackProps {
+  lines: CaptionLine[];
+  /** Scene cues, for layout-aware anchoring/visibility. Empty = always visible. */
+  cues?: SceneCue[];
+  /** Vertical center of the caption block, as a fraction of frame height. */
+  verticalAnchor?: number;
+  fontSizePx?: number;
+  activeColor?: string;
+  /**
+   * The comment-CTA word: at the moment it is ASKED FOR, the caption word
+   * renders quoted and capitalized — reinforcing the ask for muted viewers
+   * (FINDINGS §16).
+   */
+  ctaKeyword?: string;
+  /**
+   * When the ask is on screen, in output seconds — the CTA cue's own window.
+   * Required for the treatment to apply at all: quoting marks *the word you
+   * type in the comments*, so styling every ordinary use of it (nine times in
+   * one take) inverts the meaning and devalues the real ask (FINDINGS §22).
+   */
+  ctaWindow?: { startSec: number; endSec: number };
+  /**
+   * Bands where the SOURCE already has burned-in text. Captions relocate to
+   * clear them but are NEVER hidden — they are the accessibility layer, so a
+   * crowded caption still beats a missing one (FINDINGS §26).
+   */
+  sourceTextRegions?: OccupiedRegion[];
+}
+
+/**
+ * A caption word may sit slightly outside the cue that carries the ask — the
+ * cue starts at its anchor's first word, and speech runs on either side. The
+ * window is narrow enough that a near miss is glaring and the next occurrence
+ * of the word is seconds away, so a small pad is free insurance.
+ */
+const CTA_WINDOW_PAD_SEC = 0.4;
+
+/** `agents.` → `"AGENTS".` — quote-and-caps the word, punctuation kept outside. */
+export function ctaDisplay(text: string, keyword: string | undefined): string {
+  if (!keyword) return text;
+  const core = text.replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9]+$/g, "");
+  if (core.toLowerCase() !== keyword.toLowerCase()) return text;
+  return text.replace(core, `"${core.toUpperCase()}"`);
+}
+
+/** Is this caption word inside the CTA moment? No window ⇒ no treatment. */
+export function inCtaWindow(
+  startSec: number,
+  window: { startSec: number; endSec: number } | undefined,
+): boolean {
+  if (!window) return false;
+  return (
+    startSec >= window.startSec - CTA_WINDOW_PAD_SEC &&
+    startSec <= window.endSec + CTA_WINDOW_PAD_SEC
+  );
+}
+
+const LineView: React.FC<{
+  line: CaptionLine;
+  /** This line's first word's index in the WHOLE caption stream — the id the
+   * editor's retype override keys on (`OverrideDoc.captions`). */
+  wordOffset: number;
+  verticalAnchor: number;
+  fontSizePx: number;
+  activeColor: string;
+  ctaKeyword?: string;
+  ctaWindow?: { startSec: number; endSec: number };
+}> = ({ line, wordOffset, verticalAnchor, fontSizePx, activeColor, ctaKeyword, ctaWindow }) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+  const safeArea = safeAreaFor({ width, height });
+  // The parent <Sequence> starts at line.start, so local frame 0 === line.start.
+  const t = line.start + frame / fps;
+  return (
+    <AbsoluteFill style={{ pointerEvents: "none" }}>
+      <div
+        style={{
+          position: "absolute",
+          top: `${verticalAnchor * 100}%`,
+          left: 0,
+          right: 0,
+          transform: "translateY(-50%)",
+          display: "flex",
+          justifyContent: "center",
+          gap: "0.28em",
+          flexWrap: "wrap",
+          // Keep caption text clear of the platform's right-hand action rail.
+          paddingLeft: `${safeArea.left * 100}%`,
+          paddingRight: `${safeArea.right * 100}%`,
+          fontFamily:
+            "'Inter', 'Helvetica Neue', 'Arial Black', Arial, sans-serif",
+          fontWeight: 900,
+          fontSize: fontSizePx,
+          lineHeight: 1.15,
+          textAlign: "center",
+          color: "white",
+          WebkitTextStroke: "10px rgba(0,0,0,0.85)",
+          paintOrder: "stroke fill",
+          textShadow: "0 4px 24px rgba(0,0,0,0.55)",
+        }}
+      >
+        {line.words.map((w, i) => {
+          const active = t >= w.start && t <= Math.max(w.end, w.start + 0.12);
+          return (
+            <span
+              key={i}
+              // The editor double-click retypes a word in place; the RAW text
+              // rides along because the rendered text may be CTA-decorated,
+              // and the retype's stale-guard must compare against the truth.
+              data-caption-word={wordOffset + i}
+              data-caption-text={w.text}
+              style={{
+                display: "inline-block",
+                // Words are individually hit-testable for the editor (the
+                // 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",
+              }}
+            >
+              {/* Per WORD, not per line: a line straddling the cue boundary
+                  styles only the word actually inside the ask. */}
+              {ctaDisplay(w.text, inCtaWindow(w.start, ctaWindow) ? ctaKeyword : undefined)}
+            </span>
+          );
+        })}
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+/**
+ * Word-timed kinetic captions. All timings are OUTPUT time. When scene cues
+ * are provided, each line is anchored per the active layout's caption slot
+ * and hidden entirely while a graphic owns the frame (PHASE1 §1).
+ */
+export const CaptionTrack: React.FC<CaptionTrackProps> = ({
+  lines,
+  cues = [],
+  verticalAnchor = 0.76,
+  fontSizePx = 64,
+  activeColor = "#FFE14D",
+  ctaKeyword,
+  ctaWindow,
+  sourceTextRegions = [],
+}) => {
+  const { fps, width, height } = useVideoConfig();
+  const frame = { width, height };
+  // Each line's first-word index in the whole stream, so a word's id is
+  // stable regardless of which line the layout put it on.
+  const offsets: number[] = [];
+  let running = 0;
+  for (const line of lines) {
+    offsets.push(running);
+    running += line.words.length;
+  }
+  return (
+    <AbsoluteFill>
+      {lines.map((line, i) => {
+        const active = cues.length > 0 ? activeCueAt(cues, line.start) : null;
+        // ONE rect-aware path for every line (R11 Task 2b). The old split —
+        // `captionAnchorAvoiding` only when the source had burned-in text,
+        // the pure layout anchor otherwise — meant a hand-moved graphic box
+        // silently sat on top of the captions on a clean source, the common
+        // case. With no regions and no moved rect this resolves to exactly
+        // the layout anchor the old branch returned.
+        // A hand-set per-scene anchor (R15 §56) wins over the automatic
+        // chain outright — like every other hand edit, the user's placement
+        // is a decision, not an input to the avoidance search.
+        const anchor =
+          active?.captionY !== undefined
+            ? active.captionY
+            : cues.length > 0 || sourceTextRegions.length > 0
+              ? captionAnchorAvoiding(
+                  active?.layout ?? "full-bleed",
+                  regionsDuring(sourceTextRegions, line.start, line.end),
+                  active?.graphicRect,
+                  frame,
+                )
+              : verticalAnchor;
+        const from = Math.round(line.start * fps);
+        const durationInFrames = Math.max(1, Math.round((line.end - line.start) * fps));
+        return (
+          <Sequence key={i} from={from} durationInFrames={durationInFrames}>
+            <LineView
+              line={line}
+              wordOffset={offsets[i]!}
+              verticalAnchor={anchor}
+              // Per-scene size multiplier (R16 §64) — resolved per line like
+              // the anchor, from the cue the line starts under.
+              fontSizePx={fontSizePx * (active?.captionScale ?? 1)}
+              activeColor={activeColor}
+              ctaKeyword={ctaKeyword}
+              ctaWindow={ctaWindow}
+            />
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};

package/src/EdlVideo.tsx

@@ -0,0 +1,87 @@
+import React, { useMemo } from "react";
+import { AbsoluteFill, OffthreadVideo, Sequence, useVideoConfig } from "remotion";
+import type { KeptSpan } from "@ossclip/core/browser";
+
+export interface EdlVideoProps {
+  src: string;
+  /** Kept spans from the TimeMap (plain JSON — precomputed in the pipeline). */
+  spans: KeptSpan[];
+  /** Scale applied on alternating segments to conceal jump cuts. */
+  punchInScale?: number;
+  /** Removed gaps shorter than this don't toggle the punch-in (cut is invisible anyway). */
+  punchThresholdSec?: number;
+  /** Audio micro-fade at each cut boundary, in seconds. */
+  audioFadeSec?: number;
+  /**
+   * What shows where the video doesn't reach. Black by default — with a
+   * cover-cropped source it never shows at all. Under `--source-fit contain`
+   * the picture is INSET in its slot, so this backing would paint black bars
+   * over the stage's own backdrop; the composition passes `transparent` there
+   * and lets the backdrop through.
+   */
+  background?: string;
+}
+
+/**
+ * Plays the kept spans of the source back-to-back — the EDL made visible.
+ * Jump cuts are concealed by alternating a slight punch-in whenever the
+ * removed gap is long enough to produce a visible jump.
+ */
+export const EdlVideo: React.FC<EdlVideoProps> = ({
+  src,
+  spans,
+  punchInScale = 1.07,
+  punchThresholdSec = 0.15,
+  audioFadeSec = 0.01,
+  background = "black",
+}) => {
+  const { fps } = useVideoConfig();
+
+  const scales = useMemo(() => {
+    const out: number[] = [];
+    let punched = false;
+    for (let i = 0; i < spans.length; i++) {
+      const prev = spans[i - 1];
+      const gap = prev ? spans[i]!.srcIn - prev.srcOut : 0;
+      if (i > 0 && gap >= punchThresholdSec) punched = !punched;
+      out.push(punched ? punchInScale : 1);
+    }
+    return out;
+  }, [spans, punchInScale, punchThresholdSec]);
+
+  const fadeFrames = Math.max(1, Math.round(audioFadeSec * fps));
+
+  return (
+    <AbsoluteFill style={{ backgroundColor: background }}>
+      {spans.map((sp, i) => {
+        const from = Math.round(sp.outIn * fps);
+        const durationInFrames = Math.max(1, Math.round((sp.outOut - sp.outIn) * fps));
+        return (
+          <Sequence key={i} from={from} durationInFrames={durationInFrames} premountFor={fps}>
+            <AbsoluteFill style={{ transform: `scale(${scales[i]})` }}>
+              <OffthreadVideo
+                src={src}
+                trimBefore={Math.round(sp.srcIn * fps)}
+                trimAfter={Math.round(sp.srcOut * fps)}
+                style={{
+                  width: "100%",
+                  height: "100%",
+                  objectFit: "cover",
+                  // Crop bias set by VideoStage per layout (§11) — vertical
+                  // for a portrait source, horizontal for a landscape one.
+                  objectPosition: "var(--ossclip-obj-x, 50%) var(--ossclip-obj-y, 50%)",
+                }}
+                volume={(f) =>
+                  Math.max(
+                    0,
+                    Math.min(1, (f + 1) / fadeFrames, (durationInFrames - f) / fadeFrames),
+                  )
+                }
+              />
+            </AbsoluteFill>
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};

package/src/SceneLayer.tsx

@@ -0,0 +1,184 @@
+import React from "react";
+import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import type { SceneCue, Theme } from "@ossclip/core/browser";
+import { graphicSlotFor } from "./stage";
+import { fitScale } from "./fit";
+import { TitleCard } from "./components/TitleCard";
+import { StatCard } from "./components/StatCard";
+import { RuleCard } from "./components/RuleCard";
+import { StrikethroughReveal } from "./components/StrikethroughReveal";
+import { FlowDiagram } from "./components/FlowDiagram";
+import { TerminalMock } from "./components/TerminalMock";
+import { ChatMock } from "./components/ChatMock";
+import { ScreenshotFrame } from "./components/ScreenshotFrame";
+import { BulletList } from "./components/BulletList";
+import { compensateEdits, type ElementEdits } from "./editable";
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- props are registry-validated upstream */
+const COMPONENTS: Record<
+  NonNullable<SceneCue["component"]>,
+  React.FC<{ props: any; theme: Theme; widthPx?: number; heightPx?: number; edits?: ElementEdits }>
+> = {
+  TitleCard,
+  StatCard,
+  RuleCard,
+  StrikethroughReveal,
+  FlowDiagram,
+  TerminalMock,
+  ChatMock,
+  ScreenshotFrame,
+  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
+ * contrast; here the background is whatever pixels the footage happens to
+ * show, and a typographic component (TitleCard, StrikethroughReveal) can land
+ * white text on a bright wall. The slot gets a frosted scrim: theme-bg tint
+ * over a backdrop blur. Slot-shaped rather than a broadcast bottom-gradient
+ * so it FOLLOWS the box when the editor drags or resizes it.
+ */
+const OVER_VIDEO_LAYOUTS = new Set<SceneCue["layout"]>(["lower-third", "full-bleed"]);
+const SCRIM_ALPHA = 0.55;
+
+const scrimColor = (themeBg: string): string => {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(themeBg.trim());
+  const [r, g, b] = m
+    ? [0, 2, 4].map((i) => Number.parseInt(m[1]!.slice(i, i + 2), 16))
+    : [0, 0, 0];
+  return `rgba(${r}, ${g}, ${b}, ${SCRIM_ALPHA})`;
+};
+
+/**
+ * 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.
+ */
+const ExitFade: React.FC<{ durationInFrames: number; children: React.ReactNode }> = ({
+  durationInFrames,
+  children,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const remaining = (durationInFrames - frame) / fps;
+  const p = Math.min(1, Math.max(0, remaining / EXIT_SEC));
+  const ease = p * (2 - p);
+  return (
+    <div
+      style={{
+        width: "100%",
+        height: "100%",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        opacity: ease,
+        transform: ease < 1 ? `translateY(${(1 - ease) * 18}px)` : undefined,
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+/** Renders each cue's graphic into its layout's graphic slot, scene-local time. */
+export const SceneLayer: React.FC<{ cues: SceneCue[]; theme: Theme }> = ({ cues, theme }) => {
+  const { fps, width, height } = useVideoConfig();
+  return (
+    <AbsoluteFill style={{ pointerEvents: "none" }}>
+      {cues.map((cue) => {
+        // Plain cues (derived timeline filler) carry no graphic and no
+        // `data-edit-scene` — the talking head IS the scene. The component/
+        // props guards double as the type narrowing their optionality forces.
+        if (cue.kind === "plain" || !cue.component || !cue.props) return null;
+        // A cue may carry its own rect — routed there by source-text
+        // avoidance (FINDINGS §26) or set by hand in the editor (R11 Task
+        // 2). Never null (R13): a layout with no slot of its own
+        // (full-bleed) falls back to `FULL_BLEED_GRAPHIC_SLOT` rather than
+        // silently dropping the graphic — layout places the video, it does
+        // not veto the component.
+        const slot = graphicSlotFor(cue, { width, height });
+        const Component = COMPONENTS[cue.component];
+        const from = Math.round(cue.startSec * fps);
+        const durationInFrames = Math.max(1, Math.round((cue.endSec - cue.startSec) * fps));
+        const slotW = slot.w * width;
+        const slotH = slot.h * height;
+        // Over-video bands keep breathing room (R21 §100): the scrim fills
+        // the slot, the CONTENT solves against an inset box, so type never
+        // touches the band's edge. Elsewhere padding stays 0 — those slots
+        // sit on the stage background and already carry their own air.
+        const overVideo = OVER_VIDEO_LAYOUTS.has(cue.layout);
+        const pad = overVideo ? Math.min(24, Math.round(slotH * 0.12)) : 0;
+        const contentW = slotW - pad * 2;
+        const contentH = slotH - pad * 2;
+        // Fill the slot instead of floating at natural size in it (§23). The
+        // component lays out at contentW/scale and is then scaled up, so its
+        // rendered width is exactly the content width while its type grows.
+        const scale = fitScale(cue.component, cue.props, { widthPx: contentW, heightPx: contentH });
+        return (
+          <Sequence key={cue.id} from={from} durationInFrames={durationInFrames}>
+            <div
+              data-edit-scene={cue.id}
+              style={{
+                position: "absolute",
+                left: `${slot.x * 100}%`,
+                top: `${slot.y * 100}%`,
+                width: `${slot.w * 100}%`,
+                height: `${slot.h * 100}%`,
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                // The parent AbsoluteFill is `pointer-events: none` so
+                // scrubbing/other player controls pass through the graphic
+                // layer everywhere else; re-enable it just for this cue's
+                // box so the editor's `elementFromPoint` hit-test can reach
+                // its `data-edit-id` leaves at all.
+                pointerEvents: "auto",
+                // Content that cannot fit even at MIN_SCALE is clipped here
+                // rather than bleeding outside the platform safe area, which
+                // is what it did silently before (§6a).
+                overflow: "hidden",
+              }}
+            >
+              <ExitFade durationInFrames={durationInFrames}>
+                {overVideo ? (
+                  <div
+                    style={{
+                      position: "absolute",
+                      inset: 0,
+                      background: scrimColor(theme.bg),
+                      backdropFilter: "blur(14px)",
+                      WebkitBackdropFilter: "blur(14px)",
+                      borderRadius: theme.radiusPx,
+                    }}
+                  />
+                ) : null}
+                {/* position:relative so the content paints (and hit-tests)
+                    above the positioned scrim — document order alone loses. */}
+                <div style={{ width: contentW / scale, transform: `scale(${scale})`, position: "relative" }}>
+                  <Component
+                    props={cue.props}
+                    theme={theme}
+                    widthPx={contentW / scale}
+                    heightPx={contentH / scale}
+                    // Stored nudges are composition px; this wrapper scales by
+                    // `scale`, so they are counter-divided here or a drag lands
+                    // `scale`× past where it was dropped (PLAN Task 1).
+                    edits={compensateEdits(cue.elements, scale)}
+                  />
+                </div>
+              </ExitFade>
+            </div>
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};