@framv/headless 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mens Reversa
+
+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.

package/README.md

@@ -0,0 +1 @@
+# HEADLESS\n\nPart of the Framv framework.\n

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { parseArgs } from "util";
+import { resolve } from "path";
+import { render } from "./runner.js";
+const VALID_FORMATS = ["svg", "png", "jpg", "webp", "mp4", "webm", "m4a", "ogg", "pdf"];
+const HELP = `
+framv — headless renderer powered by @framv/headless
+
+Usage:
+  framv --url <url> --output <file> --format <fmt> [options]
+
+Required:
+  --url         URL of the page to render
+  --output      Output file path
+  --format      Export format: svg | png | jpg | webp | mp4 | webm | m4a | ogg | pdf
+
+Options:
+  --selector    CSS selector for the element to render  [default: #framv-root]
+  --fps         Frames per second for video export      [default: 30]
+  --quality     Quality 0–1 for lossy formats           [default: 1]
+  --start       Start time in seconds                   [default: 0]
+  --end         End time in seconds                     [default: 5]
+  --width       Viewport / output width in pixels       [default: 1920]
+  --height      Viewport / output height in pixels      [default: 1080]
+  --time        Seek time (seconds) for static exports  [default: 0]
+  --executable  Path to a Chromium/Chrome binary
+  --help        Show this help message
+
+Examples:
+  framv --url http://localhost:3000 --output out.mp4 --format mp4 --end 10
+
+  framv \\
+    --url http://localhost:3000/intro/ --output intro.mp4 --format mp4 \\
+    --selector "#framv-canvas" --fps 30 --end 13 --width 1920 --height 1080
+
+  framv --url http://localhost:3000 --output frame.png --format png --time 2.5
+`.trim();
+async function main() {
+    const { values } = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            url: { type: "string" },
+            output: { type: "string" },
+            format: { type: "string" },
+            selector: { type: "string" },
+            fps: { type: "string" },
+            quality: { type: "string" },
+            start: { type: "string" },
+            end: { type: "string" },
+            width: { type: "string" },
+            height: { type: "string" },
+            time: { type: "string" },
+            executable: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        strict: false,
+    });
+    if (values.help) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    const url = str(values.url);
+    const output = str(values.output);
+    const format = str(values.format);
+    if (!url || !output || !format) {
+        console.error("Error: --url, --output, and --format are required.\n");
+        console.error(HELP);
+        process.exit(1);
+    }
+    if (!VALID_FORMATS.includes(format)) {
+        console.error(`Error: invalid --format "${format}". Must be one of: ${VALID_FORMATS.join(", ")}`);
+        process.exit(1);
+    }
+    const opts = {
+        url,
+        output: resolve(output),
+        format: format,
+        selector: str(values.selector),
+        fps: str(values.fps) ? parseFloat(str(values.fps)) : undefined,
+        quality: str(values.quality) ? parseFloat(str(values.quality)) : undefined,
+        start: str(values.start) ? parseFloat(str(values.start)) : undefined,
+        end: str(values.end) ? parseFloat(str(values.end)) : undefined,
+        width: str(values.width) ? parseInt(str(values.width)) : undefined,
+        height: str(values.height) ? parseInt(str(values.height)) : undefined,
+        time: str(values.time) ? parseFloat(str(values.time)) : undefined,
+        executablePath: str(values.executable),
+        onProgress: (p) => process.stdout.write(`\r  ${(p * 100).toFixed(1)}%`),
+    };
+    const isVideo = ["mp4", "webm", "m4a", "ogg"].includes(format);
+    const start = opts.start ?? 0;
+    const end = opts.end ?? 5;
+    const info = isVideo ? `${start}s–${end}s (${end - start}s @ ${opts.fps ?? 30}fps)` : `t=${opts.time ?? 0}s`;
+    console.log(`\nframv`);
+    console.log(`  url:    ${url}`);
+    console.log(`  output: ${opts.output}`);
+    console.log(`  format: ${format}  ${info}`);
+    if (opts.width || opts.height)
+        console.log(`  size:   ${opts.width ?? "auto"} × ${opts.height ?? "auto"}`);
+    console.log();
+    const t0 = Date.now();
+    try {
+        await render(opts);
+        process.stdout.write(`\r  100.0%\n`);
+        console.log(`\n  ✓ rendered in ${((Date.now() - t0) / 1000).toFixed(1)}s → ${opts.output}\n`);
+    }
+    catch (err) {
+        process.stdout.write("\n");
+        console.error(`\n  ✗ render failed: ${err.message}\n`);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { render } from "./runner.js";
+export type { RunnerOptions } from "./runner.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { render } from "./runner.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,63 @@
+import type { ExportSettings } from "@framv/core";
+/**
+ * Options for the headless renderer.
+ *
+ * The runner opens `url` in a headless Chromium browser, injects
+ * `@framv/core` into the page, then calls `exportElement` and writes
+ * the result to `output`.
+ */
+export interface RunnerOptions {
+    /** URL of the page to render. */
+    url: string;
+    /** Absolute or relative path to write the output file. */
+    output: string;
+    /** CSS selector for the element to render. Defaults to `#framv-root`. */
+    selector?: string;
+    /** Explicit path to a Chromium/Chrome executable. */
+    executablePath?: string;
+    /** Export format. */
+    format: ExportSettings["format"];
+    /** Frames per second for video export. Defaults to 30. */
+    fps?: number;
+    /** Quality 0–1 for lossy formats. Defaults to 1. */
+    quality?: number;
+    /** Start time in seconds for video/audio export. Defaults to 0. */
+    start?: number;
+    /** End time in seconds for video/audio export. Defaults to 5. */
+    end?: number;
+    /** Width override in pixels. */
+    width?: number;
+    /** Height override in pixels. */
+    height?: number;
+    /** Time in seconds to seek to for static image export. Defaults to 0. */
+    time?: number;
+    /** Progress callback called with a 0–1 value as frames are rendered. */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * Launch a headless browser, navigate to `options.url`, inject `@framv/core`,
+ * render the target element, and write the result to disk.
+ *
+ * The page may optionally expose `window.setFramvFrame(frameNumber)` which
+ * the runner will call before capturing each frame — useful for custom
+ * frame-driven animations (e.g. the framv video compositions).
+ *
+ * @example
+ * ```ts
+ * import { render } from '@framv/runner';
+ *
+ * await render({
+ *   url: 'http://localhost:3000/intro/',
+ *   output: './out/intro.mp4',
+ *   selector: '#framv-canvas',
+ *   format: 'mp4',
+ *   fps: 30,
+ *   start: 0,
+ *   end: 13,
+ *   width: 1920,
+ *   height: 1080,
+ * });
+ * ```
+ */
+export declare function render(options: RunnerOptions): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAclD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA+GlE"}

package/dist/runner.js

@@ -0,0 +1,107 @@
+import { createRequire } from "module";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+const _require = createRequire(import.meta.url);
+const _dirname = dirname(fileURLToPath(import.meta.url));
+/** Resolve the absolute path to @framv/core's dist directory. */
+function resolveCoreDistDir() {
+    const coreMain = _require.resolve("@framv/core");
+    return dirname(coreMain);
+}
+/**
+ * Launch a headless browser, navigate to `options.url`, inject `@framv/core`,
+ * render the target element, and write the result to disk.
+ *
+ * The page may optionally expose `window.setFramvFrame(frameNumber)` which
+ * the runner will call before capturing each frame — useful for custom
+ * frame-driven animations (e.g. the framv video compositions).
+ *
+ * @example
+ * ```ts
+ * import { render } from '@framv/runner';
+ *
+ * await render({
+ *   url: 'http://localhost:3000/intro/',
+ *   output: './out/intro.mp4',
+ *   selector: '#framv-canvas',
+ *   format: 'mp4',
+ *   fps: 30,
+ *   start: 0,
+ *   end: 13,
+ *   width: 1920,
+ *   height: 1080,
+ * });
+ * ```
+ */
+export async function render(options) {
+    const { url, output, selector = "#framv-root", executablePath, format, fps = 30, quality = 1, start = 0, end = 5, time = 0, width, height, onProgress } = options;
+    const puppeteer = await import("puppeteer");
+    const fs = await import("fs/promises");
+    const viewportWidth = width ?? 1920;
+    const viewportHeight = height ?? 1080;
+    const totalFrames = Math.ceil((end - start) * fps);
+    const coreDistDir = resolveCoreDistDir();
+    const browser = await puppeteer.default.launch({
+        headless: true,
+        args: ["--no-sandbox", "--disable-setuid-sandbox", "--enable-webgl", "--use-gl=angle", "--allow-file-access-from-files", "--disable-web-security"],
+        executablePath,
+    });
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({ width: viewportWidth, height: viewportHeight });
+        page.on("console", (msg) => console.log("PAGE LOG:", msg.text()));
+        page.on("pageerror", (err) => console.error("PAGE ERROR:", String(err)));
+        await page.goto(url, { waitUntil: "networkidle0" });
+        // Inject @framv/core into the page. Read the IIFE bundle and inject it
+        // via addScriptTag with inline content.
+        const { readFile } = await import("fs/promises");
+        const bundleContent = await readFile(`${coreDistDir}/bundle.iife.js`, "utf-8");
+        await page.evaluate((code) => {
+            const script = document.createElement("script");
+            script.textContent = code;
+            document.head.appendChild(script);
+        }, bundleContent);
+        // Wait for the IIFE to set window.Framv, then alias it as __framvCore.
+        await page.waitForFunction(() => typeof window.Framv !== "undefined", { timeout: 10000 });
+        await page.evaluate(() => {
+            window.__framvCore = window.Framv;
+        });
+        if (onProgress) {
+            await page.exposeFunction("__framvOnProgress", onProgress);
+        }
+        const result = await page.evaluate(async (sel, cfg, frames, hasProgressCb) => {
+            const win = window;
+            const { exportElement, settings: createSettings } = win.__framvCore;
+            const element = document.querySelector(sel);
+            if (!element)
+                throw new Error(`Element not found: ${sel}`);
+            const blob = await exportElement({
+                element,
+                settings: createSettings(cfg.format, cfg),
+                onProgress: async (progress) => {
+                    if (hasProgressCb && win.__framvOnProgress) {
+                        win.__framvOnProgress(progress);
+                    }
+                    // If the page exposes setFramvFrame, call it so custom frame-driven
+                    // animations (e.g. the framv video compositions) can seek to the
+                    // correct frame before this frame is captured.
+                    if (win.setFramvFrame) {
+                        const currentFrame = Math.floor(progress * frames);
+                        await win.setFramvFrame(currentFrame);
+                        // Let the browser paint the seeked frame before capture.
+                        await new Promise((r) => requestAnimationFrame(() => r()));
+                        await new Promise((r) => requestAnimationFrame(() => r()));
+                    }
+                    return true;
+                },
+            });
+            const buffer = await blob.arrayBuffer();
+            return Array.from(new Uint8Array(buffer));
+        }, selector, { format, fps, quality, start, end, time, width, height }, totalFrames, Boolean(onProgress));
+        await fs.writeFile(output, Buffer.from(result));
+    }
+    finally {
+        await browser.close();
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@framv/headless",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "framv": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "description": "Headless renderer for framv — render HTML/SVG elements to images or video via Puppeteer",
+  "keywords": [
+    "puppeteer",
+    "headless",
+    "renderer",
+    "video",
+    "png",
+    "svg",
+    "mp4",
+    "framv",
+    "cli"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsc -b",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\" --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@framv/core": "*",
+    "puppeteer": "^24.37.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@vitest/ui": "^4.0.18",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "author": "Mens Reversa",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mensreversa/framv.git",
+    "directory": "packages/headless"
+  },
+  "bugs": {
+    "url": "https://github.com/mensreversa/framv/issues"
+  }
+}