@openvidstudio/mcp-server 0.1.0

package/dist/beats.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared beats.json TypeScript types, matching packages/docs/PLANNING.md §4's
+ * captureMethod field spec. These describe a beats.json that has already passed
+ * validate_beats -- tools that read an *unvalidated* beatsJson (validate_beats
+ * itself, write_beats_file's internal check) work off `unknown` instead, since
+ * the whole point of validation is to not assume this shape holds yet.
+ */
+import type { z } from "zod";
+import type { interactionSchema } from "./capture";
+export type CaptureMethod = "screenshot" | "recording" | "dom-demo" | "higgsfield";
+/**
+ * Derived from capture.ts's `interactionSchema` (the zod discriminated union
+ * capture_screenshot/capture_screen_recording actually enforce at replay time), via
+ * `z.infer`, rather than restated by hand -- this is the fix for the beats.ts/capture.ts
+ * Interaction fork (docs said "navigate"/"click"/"type"/"scroll"/"wait", capture.ts
+ * enforced "click"/"fill"/"select"/"hover"/"scroll"/"wait"; capture.ts is the real,
+ * enforced schema, so it's now the single source of truth both sides derive from and
+ * cannot drift apart from again). `import type` only: no runtime dependency on
+ * capture.ts (or its playwright import) is introduced by this type alias.
+ */
+export type Interaction = z.infer<typeof interactionSchema>;
+export interface CaptureVisual {
+    captureMethod: "screenshot" | "recording";
+    url: string;
+    interactions: Interaction[];
+}
+export interface DomDemoVisual {
+    captureMethod: "dom-demo";
+}
+export interface HiggsfieldVisual {
+    captureMethod: "higgsfield";
+    higgsfieldPrompt: string;
+}
+export type Visual = CaptureVisual | DomDemoVisual | HiggsfieldVisual;
+export interface Beat {
+    id: string;
+    start: number;
+    duration: number;
+    vo: string;
+    visual: Visual;
+}
+export interface BeatsFile {
+    /** 30fps assumed if omitted, per PLANNING.md / PIPELINE.md. */
+    fps?: number;
+    title: string;
+    beats: Beat[];
+}

package/dist/beats.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Shared beats.json TypeScript types, matching packages/docs/PLANNING.md §4's
+ * captureMethod field spec. These describe a beats.json that has already passed
+ * validate_beats -- tools that read an *unvalidated* beatsJson (validate_beats
+ * itself, write_beats_file's internal check) work off `unknown` instead, since
+ * the whole point of validation is to not assume this shape holds yet.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/capture.d.ts

@@ -0,0 +1,116 @@
+import type { Browser, Page } from "playwright";
+import { z } from "zod";
+/**
+ * Shared building blocks for capture_screenshot and capture_screen_recording:
+ * the Interaction type both replay identically, and CAPTURE.md's zoom-desync
+ * detection/compensation math, extracted once so the two tools' protocols
+ * cannot silently drift apart from each other.
+ */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/** CAPTURE.md's worked example. */
+export declare const DEFAULT_VIEWPORT: Viewport;
+export declare const viewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export type Interaction = {
+    type: "click";
+    selector: string;
+} | {
+    type: "fill";
+    selector: string;
+    value: string;
+} | {
+    type: "select";
+    selector: string;
+    value: string;
+} | {
+    type: "hover";
+    selector: string;
+} | {
+    type: "scroll";
+    selector?: string;
+    x?: number;
+    y?: number;
+} | {
+    type: "wait";
+    ms?: number;
+    selector?: string;
+};
+export declare const interactionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+    selector: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"fill">;
+    selector: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+    selector: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"hover">;
+    selector: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+    selector: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"wait">;
+    ms: z.ZodOptional<z.ZodNumber>;
+    selector: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+/**
+ * Replays a beat's interactions in array order. Shared verbatim by both capture
+ * tools so their replay semantics never drift apart -- called after navigation
+ * and (for both tools) after the zoom-desync compensation below, in the same
+ * effective CSS-pixel viewport CAPTURE.md measured.
+ */
+export declare function replayInteractions(page: Page, interactions: Interaction[] | undefined): Promise<void>;
+export declare const ZOOM_EPSILON = 0.01;
+export interface ZoomCompensation {
+    /** The viewport actually in effect for capture: `target` unchanged, or the compensated size. */
+    viewport: Viewport;
+    /** Measured zoom = target.width / (effective width before compensation). 1 means no desync. */
+    zoom: number;
+    /** The last-measured `[window.innerWidth, window.innerHeight]`. */
+    effective: Viewport;
+}
+/**
+ * Thrown when a single compensation attempt doesn't converge -- CAPTURE.md
+ * doesn't explicitly cover this case (it assumes the desync ratio is
+ * consistent), so this is surfaced as a real error rather than silently
+ * proceeding with a crop rect measured against the wrong effective viewport.
+ */
+export declare class ZoomCompensationError extends Error {
+    readonly target: Viewport;
+    readonly zoom: number;
+    readonly effective: Viewport;
+    constructor(target: Viewport, zoom: number, effective: Viewport);
+}
+/**
+ * CAPTURE.md's zoom-desync detection + compensation (protocol steps 1-2).
+ * Assumes the caller already called `page.setViewportSize(target)` and
+ * `page.goto(...)` -- this only measures and, if needed, re-requests a
+ * compensated viewport and re-verifies once.
+ *
+ * Never hardcodes a zoom constant (CAPTURE.md is explicit the ratio "can
+ * differ per machine/profile") -- it is measured live on every call. If the
+ * one compensation attempt doesn't bring the effective viewport back to
+ * `target` within `ZOOM_EPSILON`, throws `ZoomCompensationError` rather than
+ * silently proceeding.
+ */
+export declare function detectAndCompensateZoom(page: Page, target: Viewport): Promise<ZoomCompensation>;
+/**
+ * Playwright's bundled browser binary is not installed by a plain `npm
+ * install`/`pnpm install` (it needs a separate `npx playwright install
+ * chromium`, deliberately not wired as a postinstall script -- see this
+ * package's README/tool descriptions). Rather than let that surface as a
+ * cryptic native-binary launch error, catch it here and return a clear,
+ * actionable message.
+ */
+export declare function launchChromium(): Promise<Browser>;

package/dist/capture.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZoomCompensationError = exports.ZOOM_EPSILON = exports.interactionSchema = exports.viewportSchema = exports.DEFAULT_VIEWPORT = void 0;
+exports.replayInteractions = replayInteractions;
+exports.detectAndCompensateZoom = detectAndCompensateZoom;
+exports.launchChromium = launchChromium;
+const playwright_1 = require("playwright");
+const zod_1 = require("zod");
+/** CAPTURE.md's worked example. */
+exports.DEFAULT_VIEWPORT = { width: 1600, height: 1000 };
+exports.viewportSchema = zod_1.z.object({
+    width: zod_1.z.number().int().positive(),
+    height: zod_1.z.number().int().positive(),
+});
+exports.interactionSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("click"), selector: zod_1.z.string().min(1) }),
+    zod_1.z.object({ type: zod_1.z.literal("fill"), selector: zod_1.z.string().min(1), value: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal("select"), selector: zod_1.z.string().min(1), value: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal("hover"), selector: zod_1.z.string().min(1) }),
+    zod_1.z.object({
+        type: zod_1.z.literal("scroll"),
+        selector: zod_1.z.string().optional(),
+        x: zod_1.z.number().optional(),
+        y: zod_1.z.number().optional(),
+    }),
+    zod_1.z.object({ type: zod_1.z.literal("wait"), ms: zod_1.z.number().optional(), selector: zod_1.z.string().optional() }),
+]);
+/**
+ * Replays a beat's interactions in array order. Shared verbatim by both capture
+ * tools so their replay semantics never drift apart -- called after navigation
+ * and (for both tools) after the zoom-desync compensation below, in the same
+ * effective CSS-pixel viewport CAPTURE.md measured.
+ */
+async function replayInteractions(page, interactions) {
+    for (const interaction of interactions ?? []) {
+        switch (interaction.type) {
+            case "click":
+                await page.click(interaction.selector);
+                break;
+            case "fill":
+                await page.fill(interaction.selector, interaction.value);
+                break;
+            case "select":
+                await page.selectOption(interaction.selector, interaction.value);
+                break;
+            case "hover":
+                await page.hover(interaction.selector);
+                break;
+            case "scroll":
+                if (interaction.selector) {
+                    await page.$eval(interaction.selector, (el, coords) => el.scrollTo(coords.x ?? 0, coords.y ?? 0), { x: interaction.x, y: interaction.y });
+                }
+                else {
+                    await page.evaluate((coords) => window.scrollTo(coords.x ?? 0, coords.y ?? 0), { x: interaction.x, y: interaction.y });
+                }
+                break;
+            case "wait":
+                if (interaction.selector) {
+                    await page.waitForSelector(interaction.selector, { timeout: interaction.ms });
+                }
+                else {
+                    await page.waitForTimeout(interaction.ms ?? 500);
+                }
+                break;
+        }
+    }
+}
+exports.ZOOM_EPSILON = 0.01;
+/**
+ * Thrown when a single compensation attempt doesn't converge -- CAPTURE.md
+ * doesn't explicitly cover this case (it assumes the desync ratio is
+ * consistent), so this is surfaced as a real error rather than silently
+ * proceeding with a crop rect measured against the wrong effective viewport.
+ */
+class ZoomCompensationError extends Error {
+    constructor(target, zoom, effective) {
+        super(`Zoom-desync compensation did not converge: requested ${target.width}x${target.height}, measured zoom ` +
+            `${zoom.toFixed(4)} (per CAPTURE.md, this ratio is not hardcoded, it can differ per machine/profile), ` +
+            `but after one compensation attempt the effective viewport was ${effective.width}x${effective.height}, ` +
+            `not ${target.width}x${target.height} within ${(exports.ZOOM_EPSILON * 100).toFixed(0)}%. Refusing to proceed ` +
+            `with a screenshot/crop measured against the wrong effective viewport -- see packages/docs/CAPTURE.md.`);
+        this.target = target;
+        this.zoom = zoom;
+        this.effective = effective;
+        this.name = "ZoomCompensationError";
+    }
+}
+exports.ZoomCompensationError = ZoomCompensationError;
+async function measureEffectiveViewport(page) {
+    const [width, height] = await page.evaluate(() => [window.innerWidth, window.innerHeight]);
+    return { width, height };
+}
+function relativeDiff(actual, target) {
+    return Math.abs(actual - target) / target;
+}
+/**
+ * CAPTURE.md's zoom-desync detection + compensation (protocol steps 1-2).
+ * Assumes the caller already called `page.setViewportSize(target)` and
+ * `page.goto(...)` -- this only measures and, if needed, re-requests a
+ * compensated viewport and re-verifies once.
+ *
+ * Never hardcodes a zoom constant (CAPTURE.md is explicit the ratio "can
+ * differ per machine/profile") -- it is measured live on every call. If the
+ * one compensation attempt doesn't bring the effective viewport back to
+ * `target` within `ZOOM_EPSILON`, throws `ZoomCompensationError` rather than
+ * silently proceeding.
+ */
+async function detectAndCompensateZoom(page, target) {
+    const firstMeasurement = await measureEffectiveViewport(page);
+    const zoom = target.width / firstMeasurement.width;
+    if (Math.abs(zoom - 1) <= exports.ZOOM_EPSILON) {
+        return { viewport: target, zoom, effective: firstMeasurement };
+    }
+    const compensated = {
+        width: Math.round(target.width * zoom),
+        height: Math.round(target.height * zoom),
+    };
+    await page.setViewportSize(compensated);
+    const secondMeasurement = await measureEffectiveViewport(page);
+    const converged = relativeDiff(secondMeasurement.width, target.width) <= exports.ZOOM_EPSILON &&
+        relativeDiff(secondMeasurement.height, target.height) <= exports.ZOOM_EPSILON;
+    if (!converged) {
+        throw new ZoomCompensationError(target, zoom, secondMeasurement);
+    }
+    return { viewport: compensated, zoom, effective: secondMeasurement };
+}
+const BROWSER_NOT_INSTALLED_RE = /Executable doesn't exist at/;
+/**
+ * Playwright's bundled browser binary is not installed by a plain `npm
+ * install`/`pnpm install` (it needs a separate `npx playwright install
+ * chromium`, deliberately not wired as a postinstall script -- see this
+ * package's README/tool descriptions). Rather than let that surface as a
+ * cryptic native-binary launch error, catch it here and return a clear,
+ * actionable message.
+ */
+async function launchChromium() {
+    try {
+        return await playwright_1.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (BROWSER_NOT_INSTALLED_RE.test(message)) {
+            throw new Error(`Playwright's Chromium browser is not installed. Run "npx playwright install chromium" (in the ` +
+                `project, or wherever @openvidstudio/mcp-server is installed) and retry. Original error: ${message}`);
+        }
+        throw err;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * openvidstudio.config.json's shape, written by init_project into a *user's* project
+ * root (not this monorepo). hasHiggsfield is what import_higgsfield_clip's tool
+ * registration gates on (read once at server-startup by stdio.ts, see registerTools);
+ * targetDurationSeconds/videoConfig are read by stitch_composition and render_video for
+ * defaults not stated by beats.json itself.
+ */
+export interface VideoConfig {
+    fps: number;
+    width: number;
+    height: number;
+}
+export interface CaptureConfig {
+    /** The running app every capture points at unless a beat names its own url. */
+    appUrl: string;
+    width: number;
+    height: number;
+    /** Milliseconds to wait after load, so entrance animations finish before the shot. */
+    settleMs: number;
+}
+export interface NarrationConfig {
+    engine: "edge-tts" | "say" | "espeak";
+    voice: string;
+}
+export interface OpenvidstudioConfig {
+    hasHiggsfield: boolean;
+    targetDurationSeconds: number;
+    videoConfig: VideoConfig;
+    capture: CaptureConfig;
+    narration: NarrationConfig;
+}
+export interface ConfigPatch {
+    hasHiggsfield?: boolean;
+    targetDurationSeconds?: number;
+    videoConfig?: Partial<VideoConfig>;
+    capture?: Partial<CaptureConfig>;
+    narration?: Partial<NarrationConfig>;
+}
+/**
+ * Defaults chosen so a bare request works with no configuration.
+ *
+ * `settleMs` is deliberately not zero. A capture taken the instant a page loads
+ * catches entrance animations mid-flight, and the resulting frame looks broken
+ * rather than obviously wrong, so it survives review. 1200ms clears a typical
+ * entrance without making capture feel slow.
+ */
+export declare const DEFAULT_CONFIG: OpenvidstudioConfig;
+export declare const CONFIG_FILE_NAME = "openvidstudio.config.json";
+export declare function configPath(projectRoot: string): string;
+/** Reads openvidstudio.config.json, filling in defaults for any field it omits. */
+export declare function loadConfig(projectRoot: string): OpenvidstudioConfig;
+/**
+ * Merges `patch` over whatever config already exists (or the defaults, if none does),
+ * writes the result, and returns it. Only fields actually present in `patch` override
+ * the existing value -- an `undefined` field in `patch` (the common case, since every
+ * init_project input field is optional) never clobbers an existing real value.
+ */
+export declare function writeConfig(projectRoot: string, patch: ConfigPatch): OpenvidstudioConfig;

package/dist/config.js

@@ -0,0 +1,130 @@
+"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.CONFIG_FILE_NAME = exports.DEFAULT_CONFIG = void 0;
+exports.configPath = configPath;
+exports.loadConfig = loadConfig;
+exports.writeConfig = writeConfig;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Defaults chosen so a bare request works with no configuration.
+ *
+ * `settleMs` is deliberately not zero. A capture taken the instant a page loads
+ * catches entrance animations mid-flight, and the resulting frame looks broken
+ * rather than obviously wrong, so it survives review. 1200ms clears a typical
+ * entrance without making capture feel slow.
+ */
+exports.DEFAULT_CONFIG = {
+    hasHiggsfield: false,
+    targetDurationSeconds: 60,
+    videoConfig: { fps: 30, width: 1920, height: 1080 },
+    capture: { appUrl: "http://localhost:3000", width: 1440, height: 900, settleMs: 1200 },
+    narration: { engine: "edge-tts", voice: "en-US-AndrewNeural" },
+};
+exports.CONFIG_FILE_NAME = "openvidstudio.config.json";
+function configPath(projectRoot) {
+    return path.join(projectRoot, exports.CONFIG_FILE_NAME);
+}
+/** Reads openvidstudio.config.json, filling in defaults for any field it omits. */
+function loadConfig(projectRoot) {
+    const file = configPath(projectRoot);
+    if (!fs.existsSync(file)) {
+        return {
+            hasHiggsfield: exports.DEFAULT_CONFIG.hasHiggsfield,
+            targetDurationSeconds: exports.DEFAULT_CONFIG.targetDurationSeconds,
+            videoConfig: { ...exports.DEFAULT_CONFIG.videoConfig },
+            capture: { ...exports.DEFAULT_CONFIG.capture },
+            narration: { ...exports.DEFAULT_CONFIG.narration },
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        hasHiggsfield: raw.hasHiggsfield ?? exports.DEFAULT_CONFIG.hasHiggsfield,
+        targetDurationSeconds: raw.targetDurationSeconds ?? exports.DEFAULT_CONFIG.targetDurationSeconds,
+        videoConfig: {
+            fps: raw.videoConfig?.fps ?? exports.DEFAULT_CONFIG.videoConfig.fps,
+            width: raw.videoConfig?.width ?? exports.DEFAULT_CONFIG.videoConfig.width,
+            height: raw.videoConfig?.height ?? exports.DEFAULT_CONFIG.videoConfig.height,
+        },
+        capture: {
+            appUrl: raw.capture?.appUrl ?? exports.DEFAULT_CONFIG.capture.appUrl,
+            width: raw.capture?.width ?? exports.DEFAULT_CONFIG.capture.width,
+            height: raw.capture?.height ?? exports.DEFAULT_CONFIG.capture.height,
+            settleMs: raw.capture?.settleMs ?? exports.DEFAULT_CONFIG.capture.settleMs,
+        },
+        narration: {
+            engine: raw.narration?.engine ?? exports.DEFAULT_CONFIG.narration.engine,
+            voice: raw.narration?.voice ?? exports.DEFAULT_CONFIG.narration.voice,
+        },
+    };
+}
+/**
+ * Merges `patch` over whatever config already exists (or the defaults, if none does),
+ * writes the result, and returns it. Only fields actually present in `patch` override
+ * the existing value -- an `undefined` field in `patch` (the common case, since every
+ * init_project input field is optional) never clobbers an existing real value.
+ */
+function writeConfig(projectRoot, patch) {
+    const existing = loadConfig(projectRoot);
+    const merged = {
+        hasHiggsfield: patch.hasHiggsfield ?? existing.hasHiggsfield,
+        targetDurationSeconds: patch.targetDurationSeconds ?? existing.targetDurationSeconds,
+        videoConfig: {
+            fps: patch.videoConfig?.fps ?? existing.videoConfig.fps,
+            width: patch.videoConfig?.width ?? existing.videoConfig.width,
+            height: patch.videoConfig?.height ?? existing.videoConfig.height,
+        },
+        capture: {
+            appUrl: patch.capture?.appUrl ?? existing.capture.appUrl,
+            width: patch.capture?.width ?? existing.capture.width,
+            height: patch.capture?.height ?? existing.capture.height,
+            settleMs: patch.capture?.settleMs ?? existing.capture.settleMs,
+        },
+        narration: {
+            engine: patch.narration?.engine ?? existing.narration.engine,
+            voice: patch.narration?.voice ?? existing.narration.voice,
+        },
+    };
+    fs.mkdirSync(projectRoot, { recursive: true });
+    fs.writeFileSync(configPath(projectRoot), JSON.stringify(merged, null, 2) + "\n", "utf8");
+    return merged;
+}

package/dist/paths.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bundled copy of templates/default, produced by scripts/copy-template.mjs at build
+ * time and shipped inside the published npm package (see package.json's "files").
+ *
+ * This module compiles to dist/paths.js, so `__dirname` here is the package's own
+ * dist/ directory at runtime -- "../templates/default" resolves to
+ * <package root>/templates/default, never to the monorepo's own templates/default/
+ * (that path does not exist once this package is installed standalone in someone
+ * else's project). Deliberately kept in a top-level src/ module (not nested under
+ * src/tools/) so this one-line relative-path computation stays easy to audit.
+ */
+export declare const TEMPLATE_DIR: string;
+/**
+ * Bundled copy of packages/docs/*.md, produced by scripts/copy-docs.mjs at build time
+ * and shipped inside the published npm package (see package.json's "files"). Same
+ * __dirname-relative reasoning as TEMPLATE_DIR above: resolves to
+ * <package root>/docs, never the monorepo's own packages/docs/. init_project copies
+ * these into a scaffolded project's own docs/ folder (see tools/initProject.ts).
+ */
+export declare const DOCS_DIR: string;

package/dist/paths.js

@@ -0,0 +1,57 @@
+"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.DOCS_DIR = exports.TEMPLATE_DIR = void 0;
+const path = __importStar(require("node:path"));
+/**
+ * Bundled copy of templates/default, produced by scripts/copy-template.mjs at build
+ * time and shipped inside the published npm package (see package.json's "files").
+ *
+ * This module compiles to dist/paths.js, so `__dirname` here is the package's own
+ * dist/ directory at runtime -- "../templates/default" resolves to
+ * <package root>/templates/default, never to the monorepo's own templates/default/
+ * (that path does not exist once this package is installed standalone in someone
+ * else's project). Deliberately kept in a top-level src/ module (not nested under
+ * src/tools/) so this one-line relative-path computation stays easy to audit.
+ */
+exports.TEMPLATE_DIR = path.join(__dirname, "..", "templates", "default");
+/**
+ * Bundled copy of packages/docs/*.md, produced by scripts/copy-docs.mjs at build time
+ * and shipped inside the published npm package (see package.json's "files"). Same
+ * __dirname-relative reasoning as TEMPLATE_DIR above: resolves to
+ * <package root>/docs, never the monorepo's own packages/docs/. init_project copies
+ * these into a scaffolded project's own docs/ folder (see tools/initProject.ts).
+ */
+exports.DOCS_DIR = path.join(__dirname, "..", "docs");

package/dist/scenes/pngSize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Width and height from a PNG's IHDR chunk.
+ *
+ * A capture template needs the real dimensions of the file it is about to composite,
+ * otherwise the frame is a guess and the page comes out letterboxed or stretched.
+ * The header is fixed layout, so this is a 24 byte read rather than a dependency.
+ */
+export declare function pngSize(file: string): {
+    width: number;
+    height: number;
+} | null;

package/dist/scenes/pngSize.js

@@ -0,0 +1,75 @@
+"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.pngSize = pngSize;
+const fs = __importStar(require("node:fs"));
+/**
+ * Width and height from a PNG's IHDR chunk.
+ *
+ * A capture template needs the real dimensions of the file it is about to composite,
+ * otherwise the frame is a guess and the page comes out letterboxed or stretched.
+ * The header is fixed layout, so this is a 24 byte read rather than a dependency.
+ */
+function pngSize(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const head = Buffer.alloc(24);
+        if (fs.readSync(fd, head, 0, 24, 0) < 24)
+            return null;
+        // 8 byte signature, then a length + "IHDR" tag, then width and height.
+        const isPng = head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+        if (!isPng || head.subarray(12, 16).toString("ascii") !== "IHDR")
+            return null;
+        const width = head.readUInt32BE(16);
+        const height = head.readUInt32BE(20);
+        if (!width || !height)
+            return null;
+        return { width, height };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* nothing useful to do here */
+            }
+        }
+    }
+}