@meltemi/diagrams-capture 0.0.0-stage → 1.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Architecture Studio contributors
+
+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

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @meltemi/diagrams-capture
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PNG, PDF and video captures of rendered SVG with the installed Edge, Chrome or Chromium, driven
+over the DevTools protocol, and video encoding with the installed FFmpeg. Nothing is downloaded:
+`MELTEMI_BROWSER` and `MELTEMI_FFMPEG` name other executables.
+
+It is part of [Meltemi Diagrams](https://github.com/askenaz-dev/meltemi-diagrams#readme), diagrams as code with a canvas, motion and
+exports. Every package of the product has the same version.
+
+## Install
+
+```bash
+npm install @meltemi/diagrams-capture
+```
+
+Node 22.12.0 or later. The package is an ES module with type declarations.
+
+## Use
+
+```js
+import { captureSync } from "@meltemi/diagrams-capture";
+
+// Writes a PNG at twice the pixels and a vector PDF page of the same SVG.
+captureSync([
+  { kind: "png", svg, width: 640, height: 360, scale: 2, out: "picture.png" },
+  { kind: "pdf", svg, width: 640, height: 360, out: "picture.pdf" },
+]);
+```
+
+## Documentation
+
+- [Export](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/language/export.md)
+- [Compatibility](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/compatibility.md)
+- [All documentation](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/README.md)
+
+## Licence
+
+MIT. Third-party components and their licences are listed in [THIRD_PARTY_LICENSES.md](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/THIRD_PARTY_LICENSES.md).

package/dist/browser.d.mts

@@ -0,0 +1,7 @@
+/** The executable of an installed Chromium browser, or null when there is none. */
+export function findBrowser(
+  env?: Record<string, string | undefined>,
+  platform?: string,
+): string | null;
+/** What to say when no browser is found. */
+export const NO_BROWSER: string;

package/dist/browser.mjs

@@ -0,0 +1,54 @@
+// Finds an installed Edge, Chrome or Chromium. Plain JavaScript, so a plain `node` can run it.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Where the usual Chromium browsers install, by platform. */
+function candidates(env, platform) {
+  const local = env.LOCALAPPDATA ?? "";
+  const programs = [
+    env["PROGRAMFILES(X86)"],
+    env.PROGRAMFILES,
+    "C:/Program Files (x86)",
+    "C:/Program Files",
+  ]
+    .filter(Boolean)
+    .map((p) => p.replace(/\\/g, "/"));
+  if (platform === "win32") {
+    return [
+      ...programs.map((p) => join(p, "Microsoft/Edge/Application/msedge.exe")),
+      ...programs.map((p) => join(p, "Google/Chrome/Application/chrome.exe")),
+      ...(local ? [join(local, "Google/Chrome/Application/chrome.exe")] : []),
+      ...(local ? [join(local, "Chromium/Application/chrome.exe")] : []),
+    ];
+  }
+  if (platform === "darwin") {
+    return [
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    ];
+  }
+  return [
+    "/usr/bin/microsoft-edge",
+    "/usr/bin/microsoft-edge-stable",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+  ];
+}
+
+/**
+ * The executable of an installed Chromium browser: `MELTEMI_BROWSER` when it is set, otherwise the
+ * first of the usual Edge, Chrome and Chromium locations that exists; null when there is none.
+ */
+export function findBrowser(env = process.env, platform = process.platform) {
+  const chosen = env.MELTEMI_BROWSER;
+  if (chosen) return existsSync(chosen) ? chosen : null;
+  return candidates(env, platform).find((path) => existsSync(path)) ?? null;
+}
+
+/** What to say when no browser is found. */
+export const NO_BROWSER =
+  "PNG and PDF exports need Edge, Chrome or Chromium installed; set MELTEMI_BROWSER to the browser's executable if it is somewhere else.";

package/dist/capture.d.mts

@@ -0,0 +1,29 @@
+/** One picture to capture. */
+export interface CaptureJob {
+  readonly kind: "png" | "pdf";
+  /** The SVG of the picture. */
+  readonly svg: string;
+  /** The size of the output in CSS pixels. */
+  readonly width: number;
+  readonly height: number;
+  /** PNG: pixels per CSS pixel. */
+  readonly scale?: number;
+  /** A CSS colour, or `transparent` (the default). */
+  readonly background?: string;
+}
+
+export interface CaptureOptions {
+  /** The browser's executable; found when absent. */
+  readonly browser?: string;
+  /** How long the browser may take to answer, in milliseconds. */
+  readonly timeout?: number;
+}
+
+/** The page a job is drawn on. */
+export function capturePage(job: CaptureJob): string;
+
+/** Captures the jobs in one browser session. */
+export function capture(
+  jobs: readonly CaptureJob[],
+  options?: CaptureOptions,
+): Promise<{ browser: string; results: Uint8Array[] }>;

package/dist/capture.mjs

@@ -0,0 +1,106 @@
+// PNG and PDF captures of SVG pictures with a headless Chromium browser. Plain JavaScript, so a
+// plain `node` (the worker of `captureSync`) can run it.
+import { findBrowser, NO_BROWSER } from "./browser.mjs";
+import { PipeSession } from "./cdp.mjs";
+import { capturePage, cssColor } from "./page.mjs";
+
+export { capturePage };
+
+/** Waits until the fonts and images of the page are ready and two frames have been drawn. */
+const READY = `(async () => {
+  await document.fonts.ready;
+  await Promise.all([...document.querySelectorAll("image")].map((image) => {
+    const href = image.getAttribute("href") || image.getAttribute("xlink:href");
+    if (!href) return null;
+    const img = new Image();
+    img.src = href;
+    return img.decode().catch(() => null);
+  }));
+  await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  return true;
+})()`;
+
+async function captureOne(session, job) {
+  const { targetId } = await session.send("Target.createTarget", { url: "about:blank" });
+  const { sessionId } = await session.send("Target.attachToTarget", { targetId, flatten: true });
+  const transparent = cssColor(job.background) === "transparent";
+  try {
+    await session.send("Page.enable", {}, sessionId);
+    await session.send(
+      "Emulation.setDeviceMetricsOverride",
+      {
+        width: Math.ceil(job.width),
+        height: Math.ceil(job.height),
+        deviceScaleFactor: job.kind === "png" ? (job.scale ?? 1) : 1,
+        mobile: false,
+      },
+      sessionId,
+    );
+    if (transparent) {
+      await session.send(
+        "Emulation.setDefaultBackgroundColorOverride",
+        { color: { r: 0, g: 0, b: 0, a: 0 } },
+        sessionId,
+      );
+    }
+    const { frameTree } = await session.send("Page.getFrameTree", {}, sessionId);
+    await session.send(
+      "Page.setDocumentContent",
+      { frameId: frameTree.frame.id, html: capturePage(job) },
+      sessionId,
+    );
+    await session.send(
+      "Runtime.evaluate",
+      { expression: READY, awaitPromise: true, returnByValue: true },
+      sessionId,
+    );
+    if (job.kind === "png") {
+      const { data } = await session.send(
+        "Page.captureScreenshot",
+        {
+          format: "png",
+          clip: { x: 0, y: 0, width: job.width, height: job.height, scale: 1 },
+          fromSurface: true,
+          captureBeyondViewport: false,
+        },
+        sessionId,
+      );
+      return Buffer.from(data, "base64");
+    }
+    const { data } = await session.send(
+      "Page.printToPDF",
+      {
+        printBackground: !transparent,
+        preferCSSPageSize: true,
+        marginTop: 0,
+        marginBottom: 0,
+        marginLeft: 0,
+        marginRight: 0,
+        displayHeaderFooter: false,
+        generateTaggedPDF: true,
+      },
+      sessionId,
+    );
+    return Buffer.from(data, "base64");
+  } finally {
+    await session.send("Target.closeTarget", { targetId }).catch(() => undefined);
+  }
+}
+
+/**
+ * Captures each job (`{ kind: "png" | "pdf", svg, width, height, scale?, background? }`) in one
+ * browser session; resolves to the browser's name and version and the files' bytes.
+ */
+export async function capture(jobs, options = {}) {
+  const executable = options.browser ?? findBrowser();
+  if (!executable) throw new Error(NO_BROWSER);
+  const session = await PipeSession.launch(executable, { timeout: options.timeout ?? 30_000 });
+  try {
+    const { product } = await session.send("Browser.getVersion");
+    const results = [];
+    for (const job of jobs) results.push(await captureOne(session, job));
+    return { browser: product, results };
+  } finally {
+    await session.close();
+  }
+}

package/dist/cdp.d.mts

@@ -0,0 +1,15 @@
+/** Arguments of the headless browser. */
+export function browserArgs(profile: string): string[];
+
+/** A DevTools protocol session with a browser over a pipe. */
+export class PipeSession {
+  static launch(executable: string, options?: { timeout?: number }): Promise<PipeSession>;
+  // Replies and events are plain JSON objects shaped by the DevTools protocol.
+  send(
+    method: string,
+    params?: Record<string, unknown>,
+    sessionId?: string,
+  ): Promise<Record<string, unknown>>;
+  waitFor(method: string, sessionId?: string): Promise<Record<string, unknown>>;
+  close(): Promise<void>;
+}

package/dist/cdp.mjs

@@ -0,0 +1,173 @@
+// A small client of the Chrome DevTools protocol over a pipe (`--remote-debugging-pipe`): the
+// browser reads commands on its fd 3 and writes replies and events on its fd 4, each message a JSON
+// text ended by a NUL. Plain JavaScript, so a plain `node` can run it.
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Arguments of a headless browser that does nothing but render what it is given. */
+export function browserArgs(profile) {
+  // Features that make the browser relaunch itself (and lose the pipe), call home or show screens.
+  const disabled = [
+    "AutoDeElevate",
+    "msForceBrowserSignIn",
+    "msEdgeUpdateLaunchServicesPreferredVersion",
+    "Translate",
+    "MediaRouter",
+    "OptimizationHints",
+    "DialMediaRouteProvider",
+    "GlobalMediaControls",
+    "PaintHolding",
+  ];
+  return [
+    "--headless",
+    "--remote-debugging-pipe",
+    `--user-data-dir=${profile}`,
+    // Edge relaunches itself on Windows without its file descriptors unless told not to.
+    "--edge-skip-compat-layer-relaunch",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--no-service-autorun",
+    "--disable-extensions",
+    "--disable-sync",
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-default-apps",
+    "--disable-breakpad",
+    "--disable-edgeupdater",
+    "--disable-updater-scheduler",
+    "--disable-search-engine-choice-screen",
+    "--disable-field-trial-config",
+    "--metrics-recording-only",
+    "--password-store=basic",
+    "--use-mock-keychain",
+    `--disable-features=${disabled.join(",")}`,
+    "--hide-scrollbars",
+    "--mute-audio",
+    "--force-color-profile=srgb",
+    "--font-render-hinting=none",
+    "--export-tagged-pdf",
+    ...(process.platform === "linux" && process.getuid?.() === 0 ? ["--no-sandbox"] : []),
+    "--no-startup-window",
+  ];
+}
+
+export class PipeSession {
+  /** Starts the browser. */
+  static async launch(executable, { timeout = 30_000 } = {}) {
+    const profile = mkdtempSync(join(tmpdir(), "meltemi-capture-"));
+    const child = spawn(executable, browserArgs(profile), {
+      stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const session = new PipeSession(child, profile, timeout);
+    await new Promise((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+    });
+    return session;
+  }
+
+  constructor(child, profile, timeout) {
+    this.child = child;
+    this.profile = profile;
+    this.timeout = timeout;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.listeners = [];
+    this.buffer = "";
+    this.stderr = "";
+    this.closed = false;
+    child.stdio[2].setEncoding("utf8");
+    child.stdio[2].on("data", (text) => {
+      // Kept for error messages only; the browser logs little in headless mode.
+      this.stderr = (this.stderr + text).slice(-4000);
+    });
+    child.stdio[4].setEncoding("utf8");
+    child.stdio[4].on("data", (text) => this.receive(text));
+    child.once("exit", (code) => {
+      this.closed = true;
+      const error = new Error(
+        `The browser stopped (exit code ${code}).${this.stderr ? ` ${this.stderr.trim().split("\n").pop()}` : ""}`,
+      );
+      for (const { reject } of this.pending.values()) reject(error);
+      this.pending.clear();
+    });
+  }
+
+  receive(text) {
+    this.buffer += text;
+    let end;
+    while ((end = this.buffer.indexOf("\0")) >= 0) {
+      const raw = this.buffer.slice(0, end);
+      this.buffer = this.buffer.slice(end + 1);
+      let message;
+      try {
+        message = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      if (message.id !== undefined && this.pending.has(message.id)) {
+        const { resolve, reject, timer } = this.pending.get(message.id);
+        clearTimeout(timer);
+        this.pending.delete(message.id);
+        if (message.error) reject(new Error(`${message.error.message} (${message.error.code})`));
+        else resolve(message.result ?? {});
+      } else if (message.method) {
+        for (const listener of [...this.listeners]) listener(message);
+      }
+    }
+  }
+
+  /** Sends a command and waits for its result. */
+  send(method, params = {}, sessionId) {
+    if (this.closed) return Promise.reject(new Error("The browser is closed."));
+    const id = this.nextId++;
+    const message = { id, method, params, ...(sessionId ? { sessionId } : {}) };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`The browser did not answer ${method} within ${this.timeout} ms.`));
+      }, this.timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      this.child.stdio[3].write(`${JSON.stringify(message)}\0`);
+    });
+  }
+
+  /** Waits for an event of a session. */
+  waitFor(method, sessionId) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.listeners = this.listeners.filter((l) => l !== listener);
+        reject(new Error(`The browser did not send ${method} within ${this.timeout} ms.`));
+      }, this.timeout);
+      const listener = (message) => {
+        if (message.method !== method || message.sessionId !== sessionId) return;
+        clearTimeout(timer);
+        this.listeners = this.listeners.filter((l) => l !== listener);
+        resolve(message.params);
+      };
+      this.listeners.push(listener);
+    });
+  }
+
+  /** Closes the browser and removes its temporary profile. */
+  async close() {
+    if (!this.closed) {
+      const exited = new Promise((resolve) => this.child.once("exit", resolve));
+      await this.send("Browser.close").catch(() => undefined);
+      const timer = new Promise((resolve) => setTimeout(resolve, 5000));
+      await Promise.race([exited, timer]);
+      if (!this.closed) this.child.kill();
+    }
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        rmSync(this.profile, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      }
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { findBrowser, NO_BROWSER } from "./browser.mjs";
+import { capture, capturePage, type CaptureJob, type CaptureOptions } from "./capture.mjs";
+import { NO_FFMPEG, captureVideo, encoderArgs, ffmpegVersion, findFfmpeg, frameTimes, type VideoJob, type VideoOptions } from "./video.mjs";
+export declare const PACKAGE_NAME = "@meltemi/diagrams-capture";
+export { capture, capturePage, findBrowser, NO_BROWSER, type CaptureJob, type CaptureOptions };
+export { NO_FFMPEG, captureVideo, encoderArgs, ffmpegVersion, findFfmpeg, frameTimes, type VideoJob, type VideoOptions, };
+/** A job of `captureSync`: where its file goes. */
+export interface FileJob extends CaptureJob {
+    readonly out: string;
+}
+/**
+ * Captures the pictures and videos and writes their files, waiting for the browser and FFmpeg: the
+ * same captures run in a child `node` process, for synchronous callers such as the command line.
+ * Returns the browser's and FFmpeg's versions and each video's frame count; throws with their
+ * message when one fails.
+ */
+export declare function captureSync(jobs: readonly FileJob[], options?: CaptureOptions & {
+    readonly videos?: readonly VideoJob[];
+    readonly ffmpeg?: string;
+}): {
+    browser: string;
+    ffmpeg: string;
+    frames: number[];
+};
+/** The size and colour type of a PNG file, from its header. */
+export declare function pngInfo(bytes: Uint8Array): {
+    width: number;
+    height: number;
+    alpha: boolean;
+};
+/**
+ * The output size for a picture: `size` when given (the picture is fitted and centred in it), or
+ * the picture's own size.
+ */
+export declare function outputSize(picture: {
+    readonly width: number;
+    readonly height: number;
+}, size: {
+    readonly width: number;
+    readonly height: number;
+} | null): {
+    width: number;
+    height: number;
+};
+//# 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":"AAEA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,YAAY,8BAA8B,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,CAAC;AAC/F,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,OAAQ,SAAQ,UAAU;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,OAAO,GAAE,cAAc,GAAG;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACrB,GACL;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAiBvD;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAY5F;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5D,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAC/D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAInC"}

package/dist/index.js

@@ -0,0 +1,59 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { findBrowser, NO_BROWSER } from "./browser.mjs";
+import { capture, capturePage } from "./capture.mjs";
+import { NO_FFMPEG, captureVideo, encoderArgs, ffmpegVersion, findFfmpeg, frameTimes, } from "./video.mjs";
+export const PACKAGE_NAME = "@meltemi/diagrams-capture";
+export { capture, capturePage, findBrowser, NO_BROWSER };
+export { NO_FFMPEG, captureVideo, encoderArgs, ffmpegVersion, findFfmpeg, frameTimes, };
+/**
+ * Captures the pictures and videos and writes their files, waiting for the browser and FFmpeg: the
+ * same captures run in a child `node` process, for synchronous callers such as the command line.
+ * Returns the browser's and FFmpeg's versions and each video's frame count; throws with their
+ * message when one fails.
+ */
+export function captureSync(jobs, options = {}) {
+    const browser = options.browser ?? findBrowser();
+    if (!browser)
+        throw new Error(NO_BROWSER);
+    const videos = options.videos ?? [];
+    const ffmpeg = videos.length > 0 ? (options.ffmpeg ?? findFfmpeg()) : null;
+    if (videos.length > 0 && !ffmpeg)
+        throw new Error(NO_FFMPEG);
+    const worker = fileURLToPath(new URL("./worker.mjs", import.meta.url));
+    const result = spawnSync(process.execPath, [worker], {
+        input: JSON.stringify({ jobs, videos, browser, ffmpeg, timeout: options.timeout ?? null }),
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+        windowsHide: true,
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(result.stderr.trim() || "The browser could not capture the picture.");
+    return JSON.parse(result.stdout);
+}
+/** The size and colour type of a PNG file, from its header. */
+export function pngInfo(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+    if (bytes.length < 33 || signature.some((b, i) => bytes[i] !== b)) {
+        throw new Error("Not a PNG file.");
+    }
+    const colorType = bytes[25];
+    return {
+        width: view.getUint32(16),
+        height: view.getUint32(20),
+        alpha: colorType === 4 || colorType === 6,
+    };
+}
+/**
+ * The output size for a picture: `size` when given (the picture is fitted and centred in it), or
+ * the picture's own size.
+ */
+export function outputSize(picture, size) {
+    return size
+        ? { width: size.width, height: size.height }
+        : { width: picture.width, height: picture.height };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/page.d.mts

@@ -0,0 +1,5 @@
+import type { CaptureJob } from "./capture.mjs";
+
+export function cssColor(color: string | undefined): string;
+export function capturePage(job: CaptureJob): string;
+export function frameTimes(durationMs: number, fps: number): number[];

package/dist/page.mjs

@@ -0,0 +1,34 @@
+// What a capture draws, without the browser that draws it: the page of a picture and the times of
+// a video's frames. Plain JavaScript with no Node module, so pages in a browser use it too.
+
+/** A CSS colour as written by a profile, or transparent when it is not a plain colour. */
+export function cssColor(color) {
+  if (!color || color === "transparent") return "transparent";
+  return /^[#\w(),.%\s-]+$/.test(color) ? color : "transparent";
+}
+
+/**
+ * The page a job is drawn on: the SVG at the job's size (its view box keeps the picture's ratio,
+ * centred), on the job's background, and a printed page of the same size.
+ */
+export function capturePage(job) {
+  const width = Math.round(job.width * 100) / 100;
+  const height = Math.round(job.height * 100) / 100;
+  const background = cssColor(job.background);
+  return [
+    "<!doctype html>",
+    '<html><head><meta charset="utf-8"><style>',
+    `@page { size: ${width}px ${height}px; margin: 0; }`,
+    `html, body { margin: 0; padding: 0; width: ${width}px; height: ${height}px; overflow: hidden; background: ${background}; }`,
+    `body > svg { display: block; width: ${width}px; height: ${height}px; }`,
+    "</style></head><body>",
+    job.svg,
+    "</body></html>",
+  ].join("\n");
+}
+
+/** The times of the frames of a video of `durationMs` at `fps`, in milliseconds. */
+export function frameTimes(durationMs, fps) {
+  const count = Math.max(1, Math.round((durationMs * fps) / 1000));
+  return Array.from({ length: count }, (_, i) => (i * 1000) / fps);
+}

package/dist/video.d.mts

@@ -0,0 +1,37 @@
+/** One video to capture and encode. */
+export interface VideoJob {
+  readonly format: "mp4" | "webm" | "gif";
+  /** The frames page: it defines `__draw(t)`. */
+  readonly html: string;
+  readonly width: number;
+  readonly height: number;
+  readonly fps: number;
+  readonly durationMs: number;
+  /** `transparent`, or a CSS colour. */
+  readonly background: string;
+  /** Where FFmpeg writes the video. */
+  readonly out: string;
+}
+
+export interface VideoOptions {
+  readonly browser?: string;
+  readonly ffmpeg?: string;
+  readonly timeout?: number;
+  readonly onFrame?: (done: number, total: number) => void;
+}
+
+export const NO_FFMPEG: string;
+export function findFfmpeg(
+  env?: Record<string, string | undefined>,
+  platform?: string,
+): string | null;
+export function ffmpegVersion(ffmpeg: string): string;
+export function encoderArgs(
+  format: "mp4" | "webm" | "gif",
+  options: { fps: number; transparent: boolean; out: string },
+): string[];
+export function frameTimes(durationMs: number, fps: number): number[];
+export function captureVideo(
+  job: VideoJob,
+  options?: VideoOptions,
+): Promise<{ browser: string; ffmpeg: string; frames: number }>;

package/dist/video.mjs

@@ -0,0 +1,201 @@
+// Videos of player documents: frames drawn in one browser page and encoded by the system FFmpeg.
+// Plain JavaScript, so a plain `node` (the worker of `captureSync`) can run it.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { findBrowser, NO_BROWSER } from "./browser.mjs";
+import { PipeSession } from "./cdp.mjs";
+import { frameTimes } from "./page.mjs";
+
+export { frameTimes };
+
+/** What to say when FFmpeg is not found. */
+export const NO_FFMPEG =
+  "Video exports need FFmpeg; install it (it is not bundled) or set MELTEMI_FFMPEG to the ffmpeg executable.";
+
+/**
+ * The FFmpeg executable: `MELTEMI_FFMPEG` when set, otherwise `ffmpeg` on the path or in the usual
+ * install folders; null when there is none.
+ */
+export function findFfmpeg(env = process.env, platform = process.platform) {
+  const chosen = env.MELTEMI_FFMPEG;
+  if (chosen) return existsSync(chosen) ? chosen : null;
+  const name = platform === "win32" ? "ffmpeg.exe" : "ffmpeg";
+  const path = env.PATH ?? env.Path ?? "";
+  for (const folder of path.split(delimiter)) {
+    if (folder && existsSync(join(folder, name))) return join(folder, name);
+  }
+  const usual =
+    platform === "win32"
+      ? ["C:/ProgramData/chocolatey/bin/ffmpeg.exe", "C:/ffmpeg/bin/ffmpeg.exe"]
+      : ["/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/opt/homebrew/bin/ffmpeg"];
+  return usual.find((p) => existsSync(p)) ?? null;
+}
+
+/** The version FFmpeg reports, such as `6.1.1`. */
+export function ffmpegVersion(ffmpeg) {
+  const result = spawnSync(ffmpeg, ["-hide_banner", "-version"], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  const match = /ffmpeg version (\S+)/.exec(result.stdout ?? "");
+  return match ? match[1].replace(/-.*$/, "") : "unknown";
+}
+
+/**
+ * The FFmpeg arguments that encode PNG frames read from standard input into `out` (decision
+ * 0026): H.264 MP4, VP9 WebM (with alpha when transparent) or a looping GIF with its own palette.
+ */
+export function encoderArgs(format, { fps, transparent, out }) {
+  const input = [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-y",
+    "-f",
+    "image2pipe",
+    "-framerate",
+    String(fps),
+    "-i",
+    "-",
+  ];
+  if (format === "mp4") {
+    return [
+      ...input,
+      "-vf",
+      "pad=ceil(iw/2)*2:ceil(ih/2)*2",
+      "-c:v",
+      "libx264",
+      "-preset",
+      "medium",
+      "-crf",
+      "18",
+      "-pix_fmt",
+      "yuv420p",
+      "-movflags",
+      "+faststart",
+      "-r",
+      String(fps),
+      out,
+    ];
+  }
+  if (format === "webm") {
+    return [
+      ...input,
+      "-c:v",
+      "libvpx-vp9",
+      "-b:v",
+      "0",
+      "-crf",
+      "32",
+      "-row-mt",
+      "1",
+      ...(transparent ? ["-pix_fmt", "yuva420p", "-auto-alt-ref", "0"] : ["-pix_fmt", "yuv420p"]),
+      "-r",
+      String(fps),
+      out,
+    ];
+  }
+  return [
+    ...input,
+    "-filter_complex",
+    "[0:v]split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle",
+    "-loop",
+    "0",
+    out,
+  ];
+}
+
+/** Writes a buffer to a stream, waiting when it asks to. */
+function write(stream, buffer) {
+  return new Promise((resolve, reject) => {
+    const ok = stream.write(buffer, (error) => (error ? reject(error) : undefined));
+    if (ok) resolve();
+    else stream.once("drain", resolve);
+  });
+}
+
+/**
+ * Captures a video: the frames page (`html`, which defines `__draw(t)`) at the output size, one
+ * screenshot per frame time, piped to FFmpeg. `onFrame(done, total)` reports progress. Resolves to
+ * the browser's and FFmpeg's versions and the number of frames.
+ */
+export async function captureVideo(job, options = {}) {
+  const browser = options.browser ?? findBrowser();
+  if (!browser) throw new Error(NO_BROWSER);
+  const ffmpeg = options.ffmpeg ?? findFfmpeg();
+  if (!ffmpeg) throw new Error(NO_FFMPEG);
+  const transparent = job.background === "transparent";
+  const times = frameTimes(job.durationMs, job.fps);
+  const encoder = spawn(
+    ffmpeg,
+    encoderArgs(job.format, { fps: job.fps, transparent, out: job.out }),
+    {
+      stdio: ["pipe", "ignore", "pipe"],
+      windowsHide: true,
+    },
+  );
+  let errors = "";
+  encoder.stderr.setEncoding("utf8");
+  encoder.stderr.on("data", (text) => (errors = (errors + text).slice(-4000)));
+  const finished = new Promise((resolve, reject) => {
+    encoder.once("error", reject);
+    encoder.once("exit", (code) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(`FFmpeg failed (exit code ${code}): ${errors.trim()}`)),
+    );
+  });
+  const session = await PipeSession.launch(browser, { timeout: options.timeout ?? 30_000 });
+  try {
+    const { product } = await session.send("Browser.getVersion");
+    const { targetId } = await session.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await session.send("Target.attachToTarget", { targetId, flatten: true });
+    await session.send("Page.enable", {}, sessionId);
+    await session.send(
+      "Emulation.setDeviceMetricsOverride",
+      { width: job.width, height: job.height, deviceScaleFactor: 1, mobile: false },
+      sessionId,
+    );
+    if (transparent) {
+      await session.send(
+        "Emulation.setDefaultBackgroundColorOverride",
+        { color: { r: 0, g: 0, b: 0, a: 0 } },
+        sessionId,
+      );
+    }
+    const { frameTree } = await session.send("Page.getFrameTree", {}, sessionId);
+    await session.send(
+      "Page.setDocumentContent",
+      { frameId: frameTree.frame.id, html: job.html },
+      sessionId,
+    );
+    for (const [i, t] of times.entries()) {
+      await session.send(
+        "Runtime.evaluate",
+        { expression: `__draw(${t})`, awaitPromise: true, returnByValue: true },
+        sessionId,
+      );
+      const { data } = await session.send(
+        "Page.captureScreenshot",
+        {
+          format: "png",
+          clip: { x: 0, y: 0, width: job.width, height: job.height, scale: 1 },
+          fromSurface: true,
+          captureBeyondViewport: false,
+        },
+        sessionId,
+      );
+      await write(encoder.stdin, Buffer.from(data, "base64"));
+      options.onFrame?.(i + 1, times.length);
+    }
+    encoder.stdin.end();
+    await finished;
+    return { browser: product, ffmpeg: ffmpegVersion(ffmpeg), frames: times.length };
+  } catch (error) {
+    encoder.kill();
+    throw error;
+  } finally {
+    await session.close();
+  }
+}

package/dist/worker.mjs

@@ -0,0 +1,36 @@
+// Runs captures for `captureSync`: reads `{ jobs, videos, browser, ffmpeg, timeout }` as JSON on
+// stdin, writes each picture to its `out` path (videos are written by FFmpeg), and prints
+// `{ browser, ffmpeg, frames }` as JSON. Plain JavaScript for a plain `node`.
+import { readFileSync, writeFileSync } from "node:fs";
+import { capture } from "./capture.mjs";
+import { captureVideo } from "./video.mjs";
+
+const input = JSON.parse(readFileSync(0, "utf8"));
+const options = {
+  browser: input.browser ?? undefined,
+  ffmpeg: input.ffmpeg ?? undefined,
+  timeout: input.timeout ?? undefined,
+};
+try {
+  let browser = "";
+  let ffmpeg = "";
+  const frames = [];
+  if (input.jobs?.length > 0) {
+    const result = await capture(
+      input.jobs.map(({ out: _out, ...job }) => job),
+      options,
+    );
+    browser = result.browser;
+    input.jobs.forEach((job, i) => writeFileSync(job.out, result.results[i]));
+  }
+  for (const video of input.videos ?? []) {
+    const result = await captureVideo(video, options);
+    browser = result.browser;
+    ffmpeg = result.ffmpeg;
+    frames.push(result.frames);
+  }
+  process.stdout.write(JSON.stringify({ browser, ffmpeg, frames }));
+} catch (error) {
+  process.stderr.write(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@meltemi/diagrams-capture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.9.0",
+  "description": "PNG, PDF and video captures of rendered SVG with the installed Edge, Chrome or Chromium over the DevTools protocol, and video encoding with the installed FFmpeg.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/askenaz-dev/meltemi-diagrams.git",
+    "directory": "packages/capture"
+  },
+  "homepage": "https://github.com/askenaz-dev/meltemi-diagrams/tree/main/packages/capture#readme",
+  "bugs": {
+    "url": "https://github.com/askenaz-dev/meltemi-diagrams/issues"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./page": {
+      "types": "./dist/page.d.mts",
+      "default": "./dist/page.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node build.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }