@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/scenes/cursorPoints.d.ts

@@ -0,0 +1,43 @@
+export interface ResolvedCursorPoint {
+    frame: number;
+    x: number;
+    y: number;
+    click: boolean;
+}
+export interface ResolvedCursorPath {
+    points: ResolvedCursorPoint[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Raw point count before frame assignment, for the scaffold_scene note. */
+    pointCount: number;
+}
+export type CursorTiming = {
+    kind: "even-spread";
+    durationFrames: number;
+} | {
+    kind: "real-time";
+    durationFrames: number;
+    fps: number;
+};
+/**
+ * Reads a capture's `<asset>.cursor.json` sidecar (see @openvidstudio/capture's
+ * writeCursorSidecar) and assigns each point a frame number, two different ways depending
+ * on what kind of beat this is:
+ *
+ * - A still (screenshot) has no video timeline for the sidecar's real atMs to be relative
+ *   to -- every interaction happened within a few hundred milliseconds of headless replay,
+ *   and using that directly would compress the whole cursor path into the opening instant
+ *   of a multi-second beat. Points are spread evenly across the beat's own duration
+ *   instead, using only their ORDER (kind: "even-spread").
+ * - A recording has a real timeline, and the sidecar's atMs is already rebased onto the
+ *   recording's own start and compressed by `speed` (see capture_screen_recording), so
+ *   frame = atMs/1000*fps places the cursor exactly in sync with what the video is doing
+ *   (kind: "real-time").
+ *
+ * Returns null when there's no sidecar (beat not yet captured, or it had no
+ * click/hover/fill/select interactions) rather than throwing -- same best-effort shape as
+ * pngSize/probeVideoDurationFrames.
+ */
+export declare function readCursorPoints(assetPathAbs: string, timing: CursorTiming): ResolvedCursorPath | null;

package/dist/scenes/cursorPoints.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCursorPoints = readCursorPoints;
+const fs = __importStar(require("node:fs"));
+const capture_1 = require("@openvidstudio/capture");
+/**
+ * Reads a capture's `<asset>.cursor.json` sidecar (see @openvidstudio/capture's
+ * writeCursorSidecar) and assigns each point a frame number, two different ways depending
+ * on what kind of beat this is:
+ *
+ * - A still (screenshot) has no video timeline for the sidecar's real atMs to be relative
+ *   to -- every interaction happened within a few hundred milliseconds of headless replay,
+ *   and using that directly would compress the whole cursor path into the opening instant
+ *   of a multi-second beat. Points are spread evenly across the beat's own duration
+ *   instead, using only their ORDER (kind: "even-spread").
+ * - A recording has a real timeline, and the sidecar's atMs is already rebased onto the
+ *   recording's own start and compressed by `speed` (see capture_screen_recording), so
+ *   frame = atMs/1000*fps places the cursor exactly in sync with what the video is doing
+ *   (kind: "real-time").
+ *
+ * Returns null when there's no sidecar (beat not yet captured, or it had no
+ * click/hover/fill/select interactions) rather than throwing -- same best-effort shape as
+ * pngSize/probeVideoDurationFrames.
+ */
+function readCursorPoints(assetPathAbs, timing) {
+    const sidecarPath = (0, capture_1.cursorSidecarPath)(assetPathAbs);
+    if (!fs.existsSync(sidecarPath))
+        return null;
+    let sidecar;
+    try {
+        sidecar = JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!sidecar.points || sidecar.points.length === 0)
+        return null;
+    const points = timing.kind === "even-spread"
+        ? spreadEvenly(sidecar.points, timing.durationFrames)
+        : addClickDwell(sidecar.points.map((p) => ({
+            frame: Math.min(Math.max(0, Math.round((p.atMs / 1000) * timing.fps)), Math.max(0, timing.durationFrames - 1)),
+            x: p.x,
+            y: p.y,
+            click: p.type === "click",
+        })), timing.durationFrames);
+    return { points, viewport: sidecar.viewport, pointCount: sidecar.points.length };
+}
+/**
+ * A real recording's raw interaction timeline keeps moving right through a click: the mouse
+ * doesn't stop just because the sidecar happened to log a click event at that instant. Left
+ * alone, CursorActor's path interpolates straight through the click frame and on to wherever
+ * the cursor goes next, so by the time the click ring is a few frames into its fade the
+ * cursor (and, before A7, the ring itself) has visibly moved off the target -- a real repro
+ * measured this ~100px off a real button.
+ *
+ * This inserts two extra keyframes around every click point, both pinned to the click's own
+ * x/y: one ~4 frames before it (arrive), one ~7 frames after (dwell). Between "arrive" and
+ * the click, and between the click and "dwell", consecutive keyframes share the same x/y, so
+ * CursorActor's interpolation is flat across that span -- the cursor visibly settles onto the
+ * target before the click and holds there briefly after, instead of arriving and departing on
+ * the same continuous sweep. Only affects real-time (recording) paths: an even-spread still
+ * already has margin between its points and no continuous motion to arrest.
+ */
+function addClickDwell(points, durationFrames) {
+    const ARRIVE_BEFORE = 4;
+    const DWELL_AFTER = 7;
+    const maxFrame = Math.max(0, durationFrames - 1);
+    const withDwell = [];
+    for (const p of points) {
+        withDwell.push(p);
+        if (p.click) {
+            withDwell.push({ frame: Math.max(0, p.frame - ARRIVE_BEFORE), x: p.x, y: p.y, click: false });
+            withDwell.push({ frame: Math.min(maxFrame, p.frame + DWELL_AFTER), x: p.x, y: p.y, click: false });
+        }
+    }
+    return withDwell.sort((a, b) => a.frame - b.frame);
+}
+function spreadEvenly(rawPoints, durationFrames) {
+    // Leave room at both ends for the entrance/exit rather than starting the cursor at
+    // frame 0 (before the caption/camera have settled in) or ending it on the very last
+    // frame (before the beat's own out-transition).
+    const margin = Math.round(durationFrames * 0.15);
+    const span = Math.max(1, durationFrames - margin * 2);
+    return rawPoints.map((p, i) => ({
+        frame: rawPoints.length === 1
+            ? Math.round(durationFrames * 0.5)
+            : Math.round(margin + (i / (rawPoints.length - 1)) * span),
+        x: p.x,
+        y: p.y,
+        click: p.type === "click",
+    }));
+}

package/dist/scenes/repoInfo.d.ts

@@ -0,0 +1,17 @@
+export interface RepoInfo {
+    owner: string;
+    name: string;
+    license?: string;
+    /** A simple guess, e.g. "TypeScript" -- not a real language-detection pass. */
+    language?: string;
+    /** True when neither a git remote nor package.json's "repository" field resolved anything real. */
+    isFallback: boolean;
+}
+/**
+ * Real owner/repo/license/language for the cta template's RepoCta card, so scaffold_scene
+ * never ships "your-org"/"your-repo" placeholders into a video for a project that has a
+ * real remote. Git remote wins over package.json's "repository" field, since the remote is
+ * where the video's `github.com/<owner>/<name>` caption actually has to resolve to push
+ * come to shove. Falls back to literal placeholders only when neither source has anything.
+ */
+export declare function detectRepoInfo(projectRoot: string): RepoInfo;

package/dist/scenes/repoInfo.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRepoInfo = detectRepoInfo;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+/**
+ * Real owner/repo/license/language for the cta template's RepoCta card, so scaffold_scene
+ * never ships "your-org"/"your-repo" placeholders into a video for a project that has a
+ * real remote. Git remote wins over package.json's "repository" field, since the remote is
+ * where the video's `github.com/<owner>/<name>` caption actually has to resolve to push
+ * come to shove. Falls back to literal placeholders only when neither source has anything.
+ */
+function detectRepoInfo(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    const fromGit = detectFromGitRemote(projectRoot);
+    const fromPkg = fromGit ? null : parseRepoSlug(packageJsonRepositoryUrl(pkg));
+    const slug = fromGit ?? fromPkg;
+    const license = typeof pkg?.license === "string" && pkg.license.trim() ? pkg.license.trim() : undefined;
+    const language = guessLanguage(projectRoot);
+    return {
+        owner: slug?.owner ?? "your-org",
+        name: slug?.name ?? "your-repo",
+        license,
+        language,
+        isFallback: slug === null,
+    };
+}
+function detectFromGitRemote(projectRoot) {
+    try {
+        const url = (0, node_child_process_1.execFileSync)("git", ["remote", "get-url", "origin"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return parseRepoSlug(url);
+    }
+    catch {
+        return null;
+    }
+}
+function packageJsonRepositoryUrl(pkg) {
+    const repo = pkg?.repository;
+    if (typeof repo === "string")
+        return repo;
+    if (repo && typeof repo === "object" && typeof repo.url === "string") {
+        return repo.url;
+    }
+    return undefined;
+}
+/** Handles https/ssh github.com URLs (with or without git+/.git) and the "github:owner/repo" shorthand. */
+function parseRepoSlug(url) {
+    if (!url)
+        return null;
+    const full = url.match(/github\.com[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i);
+    if (full)
+        return { owner: full[1], name: full[2] };
+    const shorthand = url.match(/^github:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i);
+    if (shorthand)
+        return { owner: shorthand[1], name: shorthand[2] };
+    return null;
+}
+function readPackageJson(projectRoot) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Simple guess from what config files exist at the project root, not real language detection. */
+function guessLanguage(projectRoot) {
+    const has = (rel) => fs.existsSync(path.join(projectRoot, rel));
+    if (has("tsconfig.json"))
+        return "TypeScript";
+    if (has("Cargo.toml"))
+        return "Rust";
+    if (has("go.mod"))
+        return "Go";
+    if (has("pyproject.toml") || has("requirements.txt") || has("setup.py"))
+        return "Python";
+    if (has("Gemfile"))
+        return "Ruby";
+    if (has("pom.xml") || has("build.gradle") || has("build.gradle.kts"))
+        return "Java";
+    if (has("package.json"))
+        return "JavaScript";
+    return undefined;
+}

package/dist/scenes/templates.d.ts

@@ -22,8 +22,8 @@
  *
  * 2. Real captures get their frame size from the file on disk, not from a guess.
  */
-export type SceneKind = "real-screenshot" | "real-recording" | "dom-demo" | "higgsfield-clip";
-export type TemplateName = "browser-capture" | "recording" | "terminal" | "split-panel" | "checklist" | "stat" | "code" | "comparison" | "cta" | "title";
+export type SceneKind = "real-screenshot" | "real-recording" | "dom-demo" | "higgsfield-clip" | "terminal-cast" | "existing-asset";
+export type TemplateName = "browser-capture" | "recording" | "terminal" | "split-panel" | "checklist" | "stat" | "code" | "comparison" | "cta" | "title" | "terminal-cast" | "existing-asset";
 export interface SceneContext {
     beatId: string;
     componentName: string;
@@ -32,11 +32,86 @@ export interface SceneContext {
     /** The beat's narration line, used for the caption. */
     vo: string;
     durationFrames: number;
+    /**
+     * The composition's frame size, read from the project's openvidstudio.config.json. Every
+     * coordinate a template writes (camera centre, frame position, safe width) comes from it, so a
+     * 1080x1920 project gets a centred camera and layouts that fit a phone. Defaults to 1920x1080.
+     */
+    stageWidth?: number;
+    stageHeight?: number;
     /** For capture templates. */
     url?: string;
     captureWidth?: number;
     captureHeight?: number;
+    /**
+     * The real recording's own length, in frames at the beat's fps, probed from the file on
+     * disk (see scenes/videoDuration.ts). When it's shorter than durationFrames -- almost
+     * every beat, since a beat's duration is planned and a recording's is whatever actually
+     * happened -- the recording template holds the true last frame for the remainder rather
+     * than whatever OffthreadVideo happens to show once asked for a frame past the source's
+     * own end. Absent (ffprobe unavailable, or the beat wasn't captured yet) falls back to
+     * the old unclamped behaviour.
+     */
+    recordingDurationFrames?: number;
+    /**
+     * Real click/hover/fill/select target centers from capture_screenshot/
+     * capture_screen_recording's cursor sidecar, already assigned a frame number by
+     * scaffold_scene (order-spread across the beat for a still; the sidecar's own real
+     * elapsed-time-based atMs for a recording, so the overlay stays in sync with what the
+     * video is actually doing). Coordinates are in the CSS-pixel space cursorViewport
+     * describes -- the template converts them into its own stage geometry, since only the
+     * template knows its own frame/crop math (BrowserFrame's content area for a still,
+     * object-fit: cover for a full-bleed recording).
+     */
+    cursorPoints?: {
+        frame: number;
+        x: number;
+        y: number;
+        click: boolean;
+    }[];
+    /** The CSS-pixel viewport cursorPoints' x/y were measured in. */
+    cursorViewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Serialized TermStep[] for the terminal-cast template, built at scaffold time from
+     * the real cast on disk. Inlined rather than fetched at render time for the same
+     * reason browser-capture reads pngSize at scaffold time: the artifact already exists
+     * by then, and a static scene renders deterministically with no delayRender dance.
+     */
+    termSteps?: string;
+    /** Terminal window title, taken from the recorded command. */
+    termTitle?: string;
+    /** For existing-asset: the staticFile-relative path and the mandatory credit. */
+    assetStaticPath?: string;
+    attribution?: string;
+    /**
+     * For the cta template: the real repo (git remote, falling back to package.json's
+     * "repository" field), its license, and a simple language guess -- so RepoCta never
+     * ships "your-org"/"your-repo" placeholders for a project that has a real remote.
+     */
+    repo?: {
+        owner: string;
+        name: string;
+        license?: string;
+        language?: string;
+        isFallback: boolean;
+    };
 }
+/** Caption timing: in after the opening settle, out before the cut. */
+/**
+ * The caption line for a beat, taken from its narration.
+ *
+ * A caption is not the whole VO line: it is the phrase a viewer reads while hearing it,
+ * and a long sentence does not fit on one line at 30px. The old rule was a hard
+ * `slice(0, 70)`, which cut mid-word and put "This is their real installer, rec" on screen.
+ *
+ * So: prefer the first complete sentence when there is one short enough, otherwise cut at
+ * the last word boundary that fits. Either way the line on screen is a whole thought, and
+ * the rest of the sentence is still spoken.
+ */
+export declare function captionLine(vo: string, max?: number): string;
 /** Pick a template from the beat's capture method and what its description talks about. */
 export declare function pickTemplate(kind: SceneKind, description: string): TemplateName;
 export declare function renderTemplate(template: TemplateName, ctx: SceneContext, kind: SceneKind): string;