screencast-axi 0.1.0

package/dist/src/run.js

@@ -0,0 +1,321 @@
+import { rm } from "node:fs/promises";
+import { captureSize, openContext, resolveViewport } from "./browser.js";
+import { selectStrategy } from "./config.js";
+import { Director } from "./director.js";
+import { encode } from "./encode.js";
+import { ScreencastError } from "./errors.js";
+import { captureFailure } from "./forensics.js";
+import { hashSteps, hashText, upsertEntry } from "./manifest.js";
+import { mergeThemes, overlayInitScript, resolveOverlayTheme } from "./overlay.js";
+import { detectToolchain, missingFfmpegError } from "./toolchain.js";
+import { VERSION } from "./version.js";
+/**
+ * A take failed. Carries what was on screen when it did.
+ *
+ * The forensics are the point: without them a stale selector is a bare
+ * timeout, and fixing it means another forty-second run to see anything.
+ */
+export class ScenarioFailure extends ScreencastError {
+    scenarioId;
+    phase;
+    forensics;
+    lastStep;
+    constructor(init) {
+        super(init.message, "SCENARIO_FAILED", init.suggestions);
+        this.name = "ScenarioFailure";
+        this.scenarioId = init.scenarioId;
+        this.phase = init.phase;
+        this.forensics = init.forensics;
+        this.lastStep = init.lastStep;
+    }
+}
+/**
+ * Every declared narration line must appear once, in order.
+ *
+ * This is what stops the written workflow drifting from the recorded one: the
+ * same array becomes the burnt-in caption, the manifest's step list and the
+ * text a site renders beside the clip, so a line that never went on screen
+ * would be a caption promising something the video does not show.
+ */
+export function assertScriptComplete(steps, shown) {
+    const declared = steps?.length ?? 0;
+    if (declared === 0)
+        return;
+    const expected = Array.from({ length: declared }, (_, i) => i);
+    const sameLength = shown.length === expected.length;
+    const inOrder = sameLength && shown.every((value, index) => value === expected[index]);
+    if (inOrder)
+        return;
+    const missing = expected.filter((i) => !shown.includes(i));
+    throw new ScreencastError(`The take showed steps [${shown.join(", ")}] but the scenario declares ${declared}`, "SCRIPT_INCOMPLETE", [
+        missing.length > 0
+            ? `Never shown: ${missing.map((i) => `step ${i} ("${steps?.[i] ?? ""}")`).join(", ")}`
+            : "Every step ran, but not once each in order",
+        "Call `await d.step(i)` once per declared line, in order, inside run()",
+    ]);
+}
+export async function runScenario(options) {
+    const { scenario, config, mode } = options;
+    const log = options.log ?? (() => { });
+    const recording = mode === "record";
+    const outDir = options.outDir ?? config.outDir;
+    const baseUrl = options.baseUrl ?? scenario.baseUrl ?? config.baseUrl;
+    const pace = options.pace ?? scenario.pace ?? config.pace;
+    const viewport = await resolveViewport({
+        ...((options.device ?? scenario.device ?? config.device)
+            ? { device: options.device ?? scenario.device ?? config.device }
+            : {}),
+        ...((options.viewport ?? scenario.viewport)
+            ? { viewport: options.viewport ?? scenario.viewport }
+            : {}),
+        ...((options.orientation ?? scenario.orientation)
+            ? { orientation: options.orientation ?? scenario.orientation }
+            : {}),
+        ...(config.browser.deviceScaleFactor !== undefined
+            ? { deviceScaleFactor: config.browser.deviceScaleFactor }
+            : {}),
+    }, config.viewport);
+    // Fail before the browser opens, not forty seconds into a take that cannot
+    // possibly produce a file.
+    let toolchain = options.toolchain;
+    if (recording) {
+        toolchain = toolchain ?? (await detectToolchain());
+        if (!toolchain.ffmpeg)
+            throw missingFfmpegError();
+    }
+    const strategy = selectStrategy(config, scenario.auth, options.auth);
+    const authCtx = {
+        baseUrl,
+        rootDir: config.rootDir,
+        scenario: { id: scenario.id, title: scenario.title },
+        log: (message) => log(`  ${message}`),
+    };
+    // Before the browser opens, so an unreachable auth server costs a second
+    // rather than a take that has already started recording.
+    await strategy?.preflight?.(authCtx);
+    const patch = strategy?.prepareContext?.(authCtx) ?? {};
+    const opened = await openContext({
+        resolved: viewport,
+        headless: options.headed ? false : config.browser.headless,
+        args: config.browser.args,
+        ...(config.browser.profileDir ? { profileDir: config.browser.profileDir } : {}),
+        ...(recording ? { recordVideoDir: config.rawDir } : {}),
+        ...(config.browser.colorScheme ? { colorScheme: config.browser.colorScheme } : {}),
+        ...(config.browser.locale ? { locale: config.browser.locale } : {}),
+        ...(config.browser.timezoneId ? { timezoneId: config.browser.timezoneId } : {}),
+        ...(patch.storageState ? { storageState: patch.storageState } : {}),
+        ...(patch.httpCredentials ? { httpCredentials: patch.httpCredentials } : {}),
+    });
+    await opened.context.addInitScript({
+        content: overlayInitScript(resolveOverlayTheme(mergeThemes(config.overlay, scenario.overlay))),
+    });
+    // A rehearsal exists to fail fast. Playwright's 30s default is right for a
+    // take - a real app can genuinely take that long to settle - but it makes a
+    // rehearsal cost as much as the recording it was meant to replace, which
+    // defeats the point. A take keeps the generous default.
+    if (!recording) {
+        opened.context.setDefaultTimeout(config.timeouts.rehearseMs);
+    }
+    const director = new Director(opened.page, {
+        baseUrl,
+        pace,
+        settleMs: config.timeouts.settleMs,
+        ...(scenario.steps ? { steps: scenario.steps } : {}),
+    }, opened.createdAt);
+    /**
+     * Every host the page actually reached.
+     *
+     * Taken from the page rather than from the Director's own actions, which is
+     * the difference between reporting where a scenario was *told* to go and
+     * where it *went*: a navigation inside `setup()` never touches the Director,
+     * and a redirect lands somewhere the scenario never named. For a summary
+     * whose whole job is "is this safe to run", the second is the honest one.
+     */
+    const hosts = [];
+    opened.page.on("framenavigated", (frame) => {
+        if (frame !== opened.page.mainFrame())
+            return;
+        const host = hostOf(frame.url());
+        if (host && !hosts.includes(host))
+            hosts.push(host);
+    });
+    const ctx = {
+        baseUrl,
+        outDir,
+        rawDir: config.rawDir,
+        log: (message) => log(`  ${message}`),
+    };
+    let clipEndedAt = opened.createdAt;
+    let rawVideoPath = null;
+    let identity;
+    /**
+     * Turns a thrown error into a failure that carries the page's state.
+     *
+     * Gathered here, *before* the context closes. Closing first - which the
+     * original in-repo recorder had to do, since the capture is only finalised
+     * on close - threw the page away along with any chance of seeing why the
+     * take failed.
+     */
+    const fail = async (phase, error) => {
+        const forensics = await captureFailure({
+            page: opened.page,
+            rawDir: config.rawDir,
+            id: scenario.id,
+            error,
+        });
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ScenarioFailure({
+            scenarioId: scenario.id,
+            phase,
+            message: `${scenario.id}: ${message}`,
+            forensics,
+            lastStep: director.shownSteps.at(-1) ?? null,
+            suggestions: buildSuggestions(scenario.id, forensics, mode),
+        });
+    };
+    try {
+        log(`${scenario.id}: ${baseUrl} at ${viewport.viewport.width}x${viewport.viewport.height}`);
+        try {
+            if (strategy) {
+                identity = (await strategy.signIn?.(opened.page, authCtx)) ?? identity;
+                await strategy.assertSignedIn?.(opened.page, authCtx);
+                log(`  signed in via ${strategy.name}${identity ? ` as ${identity.label}` : ""}`);
+            }
+            await scenario.setup?.(opened.page, ctx);
+        }
+        catch (error) {
+            await fail("setup", error);
+        }
+        director.markClipStart();
+        try {
+            await scenario.run(director, ctx);
+            assertScriptComplete(scenario.steps, director.shownSteps);
+            await director.caption(null);
+            await director.beat(600);
+        }
+        catch (error) {
+            await fail("run", error);
+        }
+        clipEndedAt = Date.now();
+    }
+    finally {
+        await scenario.teardown?.(opened.page, ctx).catch(() => undefined);
+        const video = recording ? opened.page.video() : null;
+        // The capture is only written out when the context closes, so read the
+        // path afterwards rather than before.
+        await opened.close();
+        if (video)
+            rawVideoPath = await video.path().catch(() => null);
+    }
+    const trimStart = director.trimStartSeconds;
+    const durationMs = Math.max(0, clipEndedAt - opened.createdAt - Math.round(trimStart * 1000));
+    if (!recording) {
+        return {
+            id: scenario.id,
+            mode,
+            durationMs,
+            scaledPauseMs: director.scaledPauseMs,
+            pace,
+            viewport,
+            steps: scenario.steps ?? [],
+            performed: director.performed,
+            hosts,
+            ...(identity ? { identity } : {}),
+        };
+    }
+    if (!rawVideoPath) {
+        throw new ScreencastError("Playwright produced no video for this take", "NO_CAPTURE", [
+            "The context closed without writing a capture - check the raw directory is writable",
+            `Raw directory: ${config.rawDir}`,
+        ]);
+    }
+    // Never scale beyond what was captured: upscaling a 390px phone capture to
+    // a 1280px deliverable multiplies the file size without adding a pixel of
+    // detail. Height follows the source aspect rather than being measured, so a
+    // consumer can size the player before the video decodes.
+    const capture = captureSize(viewport);
+    const width = Math.min(config.deliverables.width, capture.width);
+    const height = Math.round(((width / capture.width) * capture.height) / 2) * 2;
+    const encoded = await encode({
+        ...config.deliverables,
+        ...options.deliverables,
+        width,
+        input: rawVideoPath,
+        outDir,
+        id: scenario.id,
+        trimStart,
+        ...(toolchain ? { toolchain } : {}),
+    });
+    if (!options.keepRaw)
+        await rm(rawVideoPath, { force: true });
+    // Everything after `<id>.`, not just the final extension: a poster and an
+    // animated WebP both end in `.webp`, and recording them both as "webp"
+    // leaves the manifest unable to tell them apart - which then reports the
+    // animation as an unclaimed file and never checks it for existence.
+    const formats = Object.keys(encoded.sizes).map((name) => name.slice(scenario.id.length + 1));
+    const entry = {
+        id: scenario.id,
+        title: scenario.title,
+        description: scenario.description,
+        ...(scenario.steps ? { steps: scenario.steps } : {}),
+        width,
+        height,
+        durationMs,
+        recordedAt: new Date().toISOString(),
+        pace,
+        ...(viewport.device ? { device: viewport.device } : {}),
+        formats,
+        ...(options.sourceText ? { sourceHash: hashText(options.sourceText) } : {}),
+        stepsHash: hashSteps(scenario.steps),
+        recorderVersion: VERSION,
+    };
+    const manifestPath = upsertEntry(outDir, entry);
+    log(`${scenario.id}: ${Object.keys(encoded.sizes).join(", ")}`);
+    return {
+        id: scenario.id,
+        mode,
+        durationMs,
+        scaledPauseMs: director.scaledPauseMs,
+        pace,
+        viewport,
+        steps: scenario.steps ?? [],
+        performed: director.performed,
+        hosts,
+        ...(identity ? { identity } : {}),
+        encoded,
+        manifestPath,
+        entry,
+    };
+}
+function buildSuggestions(id, forensics, mode) {
+    const out = [];
+    if (forensics.screenshot) {
+        out.push(`Open ${forensics.screenshot} to see what was on screen when it failed`);
+    }
+    const dead = forensics.nearMatches?.find((m) => m.count === 0);
+    const alive = forensics.nearMatches?.find((m) => m.count > 0);
+    if (dead && alive) {
+        out.push(`\`${alive.selector}\` matched ${alive.count} but \`${dead.selector}\` matched none - ` +
+            `the container rendered and its contents did not, which is usually data, not the selector`);
+    }
+    out.push("To find the right selector, drive the page live with a browser tool " +
+        "(for example `npx -y chrome-devtools-axi navigate <url>` then `snapshot`)");
+    if (mode === "record") {
+        out.push(`Re-check a fix in seconds with \`screencast-axi rehearse ${id}\``);
+    }
+    return out;
+}
+/**
+ * Turns a URL into the thing worth reporting: its host, or its scheme when it
+ * has none (a `file://` page has no host, and a blank entry answers nothing).
+ */
+function hostOf(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.host || `${parsed.protocol}//`;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/src/run.js.map

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

package/dist/src/skill.d.ts

@@ -0,0 +1,12 @@
+export declare const SKILL_NAME = "screencast-axi";
+/**
+ * Hard cap, enforced rather than documented.
+ *
+ * The installed SKILL.md is a discovery stub, not a manual: copies go stale
+ * the moment the CLI moves, and every line of it is loaded into an agent's
+ * context whether or not the task needs it. The CLI (`--help`,
+ * `<command> --help`, `guide <topic>`) is the source of truth. The cap exists
+ * so a future regeneration cannot quietly re-inflate the stub back into one.
+ */
+export declare const MAX_SKILL_MARKDOWN_CHARS = 2500;
+export declare function createSkillMarkdown(): string;

package/dist/src/skill.js

@@ -0,0 +1,69 @@
+export const SKILL_NAME = "screencast-axi";
+/**
+ * Hard cap, enforced rather than documented.
+ *
+ * The installed SKILL.md is a discovery stub, not a manual: copies go stale
+ * the moment the CLI moves, and every line of it is loaded into an agent's
+ * context whether or not the task needs it. The CLI (`--help`,
+ * `<command> --help`, `guide <topic>`) is the source of truth. The cap exists
+ * so a future regeneration cannot quietly re-inflate the stub back into one.
+ */
+export const MAX_SKILL_MARKDOWN_CHARS = 2500;
+const FRONTMATTER = `---
+name: ${SKILL_NAME}
+description: "Record product screencasts and demo clips of any website through the screencast-axi CLI - script a workflow as a Playwright scenario, rehearse its selectors, then encode it to mp4, webm and a poster with a synthetic cursor and captions. Use whenever a task needs a recorded walkthrough of a UI: a landing-page demo, a release-note clip, a feature tour, a bug reproduction, or a how-to."
+user-invocable: false
+author: Valentyn Morenko
+license: MIT
+metadata:
+  hermes:
+    tags: [screencast, video, playwright, demo, landing-page]
+    category: automation
+---`;
+const BODY = `# screencast-axi
+
+Records a scripted browser workflow as a watchable clip. Prefer this over
+hand-rolled Playwright video capture or a screen recorder.
+
+Use it whenever a task needs a recorded walkthrough of a UI: a landing-page
+demo, a feature tour, a release-note clip, a bug reproduction. Skip it when a
+still screenshot says the same thing - a clip costs far more to produce and to
+watch.
+
+## Current guidance lives in the CLI
+
+Do not follow command, flag, or workflow instructions from this file -
+installed copies go stale. Get the current source of truth from the CLI:
+
+- \`npx -y screencast-axi\` for the state of the clip library
+- \`npx -y screencast-axi --help\` for the command index
+- \`npx -y screencast-axi <command> --help\` for per-command usage
+- \`npx -y screencast-axi guide\` for topic-sized guidance, pulled one topic at
+  a time rather than read as a manual
+
+Three things worth knowing before the first run:
+
+1. Iterate with \`rehearse\`, not \`record\`: no encoding, so a stale selector
+   surfaces in seconds, and it prints every action the scenario took.
+2. \`--headed\` shows it happening in a real window. Offer it when someone
+   wants to see what a script does to their signed-in account before it runs.
+3. When a selector needs discovering, drive the page live with a browser tool
+   such as \`chrome-devtools-axi\`, then write the scenario.
+
+ffmpeg must be installed. Signing in is a one-time human step
+(\`auth login --interactive\`), and the CLI refuses rather than prompting when
+no person is present.
+
+You do not need screencast-axi installed globally - invoke it with
+\`npx -y screencast-axi <command>\`. If its output suggests a follow-up command
+starting with \`screencast-axi\`, run that as \`npx -y screencast-axi ...\`.
+`;
+export function createSkillMarkdown() {
+    const markdown = `${FRONTMATTER}\n\n${BODY}`;
+    if (markdown.length > MAX_SKILL_MARKDOWN_CHARS) {
+        throw new Error(`generated SKILL.md is ${markdown.length} chars; keep it a stub under ` +
+            `${MAX_SKILL_MARKDOWN_CHARS} and defer guidance to the CLI`);
+    }
+    return markdown;
+}
+//# sourceMappingURL=skill.js.map

package/dist/src/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/skill.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,MAAM,WAAW,GAAG;QACZ,UAAU;;;;;;;;;IASd,CAAC;AAEL,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCZ,CAAC;AAEF,MAAM,UAAU,mBAAmB;IACjC,MAAM,QAAQ,GAAG,GAAG,WAAW,OAAO,IAAI,EAAE,CAAC;IAC7C,IAAI,QAAQ,CAAC,MAAM,GAAG,wBAAwB,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,yBAAyB,QAAQ,CAAC,MAAM,+BAA+B;YACrE,GAAG,wBAAwB,gCAAgC,CAC9D,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/toolchain.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Locating the external encoders, and deciding how to make a poster.
+ *
+ * ffmpeg is not bundled: it is 80MB+ per platform, and *which* build you have
+ * matters. Many common builds (Homebrew's among them) ship without libwebp, so
+ * a package that bundled one would hide that difference rather than solve it.
+ * Instead the poster has a fallback chain, and this module is the single place
+ * that knows what is actually available.
+ */
+export interface RunResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Spawns `bin`, capturing both streams. Never throws on a non-zero exit. */
+export declare function run(bin: string, args: readonly string[]): Promise<RunResult>;
+/** Spawns `bin` and throws with the tail of stderr when it fails. */
+export declare function runOrThrow(bin: string, args: readonly string[]): Promise<void>;
+export interface BinaryInfo {
+    readonly path: string;
+    readonly version: string;
+    /** Where it came from, for `doctor` to report. */
+    readonly source: "env" | "ffmpeg-static" | "path";
+}
+/**
+ * ffmpeg, by the documented cascade: an explicit override, then an installed
+ * `ffmpeg-static`, then PATH.
+ *
+ * `ffmpeg-static` is not a dependency - it is the escape hatch for someone who
+ * would rather not install ffmpeg system-wide, and it is found only if they
+ * chose to add it.
+ */
+export declare function resolveFfmpeg(): Promise<BinaryInfo | null>;
+/** gif2webp, which turns the GIF pass into an animated WebP. */
+export declare function resolveGif2Webp(): Promise<BinaryInfo | null>;
+export declare function resolveCwebp(): Promise<BinaryInfo | null>;
+/** Whether this ffmpeg build can write WebP itself. */
+export declare function ffmpegSupportsWebp(ffmpeg: string): Promise<boolean>;
+/**
+ * How to produce the poster image, best first.
+ *
+ * - `ffmpeg`: the build has libwebp, so one process does it.
+ * - `cwebp`:  extract a PNG frame, then convert. What Homebrew needs.
+ * - `png`:    neither is available. Larger, still a valid poster - a missing
+ *             optimisation should not fail a recording.
+ */
+export type PosterEncoder = "ffmpeg" | "cwebp" | "png";
+export interface Toolchain {
+    readonly ffmpeg: BinaryInfo | null;
+    readonly cwebp: BinaryInfo | null;
+    readonly gif2webp: BinaryInfo | null;
+    readonly posterEncoder: PosterEncoder;
+}
+/**
+ * The poster route, given what is available. Pure, so the three branches can
+ * be tested without a machine that happens to have the right binaries.
+ */
+export declare function choosePosterEncoder(ffmpegHasWebp: boolean, hasCwebp: boolean): PosterEncoder;
+export declare function detectToolchain(): Promise<Toolchain>;
+/** Platform-appropriate install line, so an error is fixable in one step. */
+export declare function installHint(tool: "ffmpeg" | "cwebp"): string;
+export declare function missingFfmpegError(): Error;

package/dist/src/toolchain.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+/** Spawns `bin`, capturing both streams. Never throws on a non-zero exit. */
+export function run(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => (stdout += String(chunk)));
+        child.stderr.on("data", (chunk) => (stderr += String(chunk)));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+/** Spawns `bin` and throws with the tail of stderr when it fails. */
+export async function runOrThrow(bin, args) {
+    const result = await run(bin, args);
+    if (result.code !== 0) {
+        const tail = result.stderr.split("\n").slice(-25).join("\n");
+        throw new Error(`${bin} exited ${result.code}\n${tail}`);
+    }
+}
+const FFMPEG_ENV = "SCREENCAST_FFMPEG";
+const CWEBP_ENV = "SCREENCAST_CWEBP";
+function firstLine(text) {
+    return (text.split("\n")[0] ?? "").trim();
+}
+async function probe(bin, source) {
+    try {
+        const result = await run(bin, ["-version"]);
+        if (result.code !== 0)
+            return null;
+        return { path: bin, version: firstLine(result.stdout || result.stderr), source };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ffmpeg, by the documented cascade: an explicit override, then an installed
+ * `ffmpeg-static`, then PATH.
+ *
+ * `ffmpeg-static` is not a dependency - it is the escape hatch for someone who
+ * would rather not install ffmpeg system-wide, and it is found only if they
+ * chose to add it.
+ */
+export async function resolveFfmpeg() {
+    const override = process.env[FFMPEG_ENV];
+    if (override)
+        return probe(override, "env");
+    try {
+        // Computed specifier on purpose: this package is deliberately absent
+        // unless someone opted into it, so TypeScript must not try to resolve it.
+        const specifier = "ffmpeg-static";
+        const mod = (await import(specifier));
+        const bundled = typeof mod.default === "string" ? mod.default : null;
+        if (bundled) {
+            const found = await probe(bundled, "ffmpeg-static");
+            if (found)
+                return found;
+        }
+    }
+    catch {
+        // Not installed. Expected: it is an opt-in convenience, not a dependency.
+    }
+    return probe("ffmpeg", "path");
+}
+/** gif2webp, which turns the GIF pass into an animated WebP. */
+export async function resolveGif2Webp() {
+    return probe("gif2webp", "path");
+}
+export async function resolveCwebp() {
+    const override = process.env[CWEBP_ENV];
+    return probe(override ?? "cwebp", override ? "env" : "path");
+}
+/** Whether this ffmpeg build can write WebP itself. */
+export async function ffmpegSupportsWebp(ffmpeg) {
+    try {
+        const result = await run(ffmpeg, ["-hide_banner", "-encoders"]);
+        return result.code === 0 && /\blibwebp\b/.test(result.stdout);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The poster route, given what is available. Pure, so the three branches can
+ * be tested without a machine that happens to have the right binaries.
+ */
+export function choosePosterEncoder(ffmpegHasWebp, hasCwebp) {
+    if (ffmpegHasWebp)
+        return "ffmpeg";
+    if (hasCwebp)
+        return "cwebp";
+    return "png";
+}
+export async function detectToolchain() {
+    const ffmpeg = await resolveFfmpeg();
+    const cwebp = await resolveCwebp();
+    const gif2webp = await resolveGif2Webp();
+    const ffmpegHasWebp = ffmpeg !== null && (await ffmpegSupportsWebp(ffmpeg.path));
+    return {
+        ffmpeg,
+        cwebp,
+        gif2webp,
+        posterEncoder: choosePosterEncoder(ffmpegHasWebp, cwebp !== null),
+    };
+}
+/** Platform-appropriate install line, so an error is fixable in one step. */
+export function installHint(tool) {
+    const pkg = tool === "ffmpeg" ? "ffmpeg" : "webp";
+    switch (platform()) {
+        case "darwin":
+            return `brew install ${pkg}`;
+        case "win32":
+            return tool === "ffmpeg"
+                ? "winget install --id Gyan.FFmpeg"
+                : "winget install --id Google.WebP";
+        default:
+            return `sudo apt-get install ${pkg}`;
+    }
+}
+export function missingFfmpegError() {
+    return new Error(`ffmpeg was not found. Install it with \`${installHint("ffmpeg")}\`, ` +
+        `add \`ffmpeg-static\` as a dev dependency, or point ${FFMPEG_ENV} at a binary.`);
+}
+//# sourceMappingURL=toolchain.js.map

package/dist/src/toolchain.js.map

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