@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/validateScenesRender.d.ts

@@ -0,0 +1,186 @@
+import { type ArcThresholds } from "../lessonArc";
+import type { SceneFinding } from "./validateScenes";
+import { MAX_READING_WORDS_PER_SEC, READING_OVERHEAD_SEC } from "./validateBeats";
+/**
+ * validate_scenes's render mode: the checks a static read of scene source cannot make,
+ * because each one depends on what the camera and the layout actually produce.
+ *
+ *  - crop:        text inside the camera-transformed stage that lands outside the frame
+ *  - text size:   text that ends up below the design system's minimum on-screen size
+ *  - reading:     a beat that is on screen for less time than its text takes to read
+ *  - dead frames: a beat whose rendered pixels never change
+ *  - em dash:     an em dash anywhere in on-screen copy
+ *  - contrast:    text colour against the pixels actually rendered behind it
+ *  - safe area:   text inside the frame but outside the title-safe inset
+ *  - HUD overlap: scene text drawn over the chapter HUD
+ *
+ * Measurement is DOM-based, not pixel-based. The scene is mounted in a real browser through
+ * the remotionBridge, seeked to a handful of frames inside each beat, and measured with
+ * getBoundingClientRect. That gives exact coordinates with no anti-aliasing or colour
+ * threshold to tune. Dead frames are the one pixel check, since "nothing moved" has no DOM
+ * equivalent (a canvas or a video can change without a node changing).
+ *
+ * Stage content is told apart from screen-space overlay content through the two data
+ * attributes core writes (`data-ovs-camera-stage`, `data-ovs-overlay`). Overlay content
+ * (captions, HUD) is not transformed by the camera, so it cannot be cropped by it and is
+ * exempt from the crop check. It is still held to the size and reading checks.
+ */
+/**
+ * Silent reading budget for on-screen text: about 3.5 words a second plus 0.8 s to land on it,
+ * the same numbers validate_beats applies to onScreenText on a narration:"none" beat, imported
+ * so the two gates can never disagree about how long a card has to stay up. This is a different
+ * number from validateBeats's MIN_PACE/MAX_PACE, which is the pace of spoken narration.
+ */
+export { MAX_READING_WORDS_PER_SEC, READING_OVERHEAD_SEC };
+export interface TypeScaleMinimums {
+    body: number;
+    mono: number;
+    /** Small UI chips (Pill, ToolChip): never held to body's minimum, which they are not
+     * trying to meet, nor to mono's, which is about a different font role entirely. */
+    label: number;
+}
+/**
+ * Minimums used when a video has no design.ts. body/mono mirror DEFAULT_TYPE_SCALE in
+ * packages/core/src/designSystem.ts (body 26-34, mono 15-22); the values are copied rather
+ * than imported because this package does not depend on core, which is a template dependency.
+ * label has no DesignSystem.typeScale counterpart (that type has no label field) and is not
+ * read from design.ts below: it is a fixed floor, picked below Pill/ToolChip's own 18/20px
+ * defaults so a deliberately smaller label still passes, but a near-illegible one is flagged.
+ */
+export declare const DEFAULT_TYPE_MINIMUMS: TypeScaleMinimums;
+/**
+ * Reads the lower bound of `body` and `mono` from src/videos/<name>/design.ts when one
+ * exists. Regex rather than evaluating the file, since design.ts is TypeScript that imports
+ * core and cannot be loaded from here. Anything it cannot read falls back to the default.
+ */
+export declare function readTypeMinimums(videoDir: string): TypeScaleMinimums;
+export interface RenderBeat {
+    id: string;
+    start: number;
+    duration: number;
+}
+export interface RenderCheckInput {
+    projectRoot: string;
+    videoName: string;
+    compositionId: string;
+    beats: RenderBeat[];
+    fps: number;
+    minimums: TypeScaleMinimums;
+    /** An already-built bundle directory to measure against, instead of bundling the project again. */
+    bundleDir?: string;
+    /** Beat ids the brief marks as deliberate holds: unchanging frames there are not a dead-frames finding. */
+    deliberateHolds?: string[];
+    /** Count the glowing elements in each sampled frame against Supernova's one-at-a-time budget. Lessons only. */
+    glowBudget?: boolean;
+    /**
+     * Judge the lesson arc (the diagram inside the first seconds, no long static stretch) from the frames sampled
+     * here, with these thresholds. Lessons only, and only when every beat of the lesson is measured.
+     */
+    arc?: ArcThresholds;
+    /** The lesson's length in seconds, which bounds a static stretch that runs to the end. */
+    lessonSeconds?: number;
+}
+export interface RenderCheckResult {
+    findings: SceneFinding[];
+    beatsMeasured: number;
+    beatsSkipped: {
+        beatId: string;
+        reason: string;
+    }[];
+    bundleMs: number;
+    totalMs: number;
+}
+interface TextProbe {
+    text: string;
+    /** Font size as it appears in the output frame, camera scale included. */
+    fontPx: number;
+    mono: boolean;
+    /** Inside a data-ovs-label element (Pill, ToolChip): held to its own, lower minimum. */
+    label: boolean;
+    inStage: boolean;
+    opacity: number;
+    /** Fraction of the text box outside the frame, 0 to 1. */
+    croppedRatio: number;
+    /** Furthest overhang past any frame edge, in output pixels. */
+    overhangPx: number;
+    /** Inside a data-ovs-hud element (ChapterHud): chrome, exempt from size and reading checks. */
+    hud?: boolean;
+    /** Furthest the text box reaches past the title-safe inset, in output pixels (0 if inside). */
+    safeOverhangPx?: number;
+    /** Largest share of the text box covered by a HUD element it is not part of, 0 to 1. */
+    hudOverlap?: number;
+    /** The CSS text colour, r/g/b 0-255 and alpha 0-1 (alpha 0 for gradient or clipped text). */
+    rgba?: [number, number, number, number];
+    /** The text box in the output frame, used to read the background out of the screenshot. */
+    box?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    /** Background colour behind the text, read from the screenshot after the probe. */
+    bg?: [number, number, number] | null;
+}
+/**
+ * WCAG contrast ratio of text against an opaque background. The text colour is first
+ * composited over that background with its own alpha times its ancestors' opacity, which is
+ * what actually reaches the screen.
+ */
+export declare function contrastAgainst(rgba: [number, number, number, number], opacity: number, bg: [number, number, number]): number;
+/**
+ * The colour behind a text box, read from the rendered frame. Taken from a ring just outside
+ * the box rather than from inside it, because inside it a large or bold string can cover more
+ * than half the pixels and the median would be the glyph colour, not the surface. The median of
+ * each channel keeps a gradient or a soft shadow from skewing it. Falls back to the box
+ * interior when there is no ring (a box that fills the frame).
+ */
+export declare function backgroundBehind(pixels: Uint8Array, width: number, height: number, channels: number, box: {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+}, ringPx: number): [number, number, number] | null;
+/**
+ * Beat ids the brief marks `deliberateHold: true` in its shotList. A missing or unreadable brief
+ * means no holds are declared, which is the strict reading: unchanging frames get reported.
+ */
+export declare function readDeliberateHolds(videoDir: string): string[];
+/**
+ * The #rrggbb colours src/brand.ts sets, minus pure black and white (which nearly any frame
+ * contains, so they could not tell a branded render from an unbranded one). Empty when there is
+ * no brand file or it carries no hex colours.
+ */
+export declare function brandHexColors(projectRoot: string): string[];
+/**
+ * Pure: for each colour, the share of sampled pixels in a frame that match it. A stride keeps
+ * this cheap on a 1920x1080 frame; a flat brand surface is far larger than any stride skips.
+ */
+export declare function colorShares(pixels: Uint8Array, width: number, height: number, channels: number, colors: string[]): Map<string, number>;
+/** Pure: the palette finding, given the largest share each brand colour reached in any sampled frame. */
+export declare function judgeBrandPalette(maxShare: Map<string, number>): SceneFinding[];
+/**
+ * Pure: turns what was measured in one beat's sampled frames into findings. Split out of the
+ * browser loop so the judgement is testable without a browser.
+ */
+export declare function judgeBeat(opts: {
+    beat: RenderBeat;
+    fps: number;
+    minimums: TypeScaleMinimums;
+    samples: TextProbe[][];
+    /** Largest changed-pixel ratio between any two sampled frames, or null if not measured. */
+    maxChangedRatio: number | null;
+    /** The brief marks this beat as a deliberate hold, so unchanging frames are intended. */
+    deliberateHold?: boolean;
+}): SceneFinding[];
+/** What the glow helper in @openvidstudio/stem leaves in the DOM: an element per glow, tagged with its kind and level. */
+interface GlowProbe {
+    kind: string;
+    level: number;
+}
+/**
+ * The glow budget: one glowing element at a time. More than one in a sampled frame is a warning, more
+ * than two an error. A beat that holds a Nova is exempt: the payoff is allowed to be the moment
+ * everything lights up. The worst frame in the beat is the one reported, once.
+ */
+export declare function judgeGlow(beat: RenderBeat, samples: GlowProbe[][], frames: number[]): SceneFinding[];
+export declare function runRenderChecks(input: RenderCheckInput): Promise<RenderCheckResult>;