@ludra/cli 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludra 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
+# @ludra/cli
 
-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.
+**The game engine built for AI agents.** This package provides the `ludra` command.
+
+Games are plain JSON, every error comes with a fix, and agents play-test their own games headlessly before a human ever touches them.
+
+```bash
+npx @ludra/cli new my-game
+cd my-game
+npx @ludra/cli check                                        # validate; every problem has a fix
+npx @ludra/cli play --inputs "right:1s, jump:0.4s" --ascii  # simulate and see the frame as text
+npx @ludra/cli test                                         # run tests/*.test.json
+npx @ludra/cli dev                                          # play it in the browser
+```
+
+Or install it once and use the short command:
+
+```bash
+npm install -g @ludra/cli
+ludra new my-game
+```
+
+| Command | What it does |
+| --- | --- |
+| `ludra new <folder>` | Create a game from the platformer template (art, effects and tests included) |
+| `ludra check [folder]` | Validate the scene and its assets |
+| `ludra play [folder]` | Deterministic headless run: timeline, events, ASCII map |
+| `ludra test [folder]` | Scripted inputs plus assertions such as `won == true` or `deaths == 0` |
+| `ludra components [name]` | Reference for every component, field and effect |
+| `ludra dev [folder]` | Browser runtime with keyboard controls, sound and live reload |
+
+Every command accepts `--json`. Requires Node.js 22.18 or newer.
+
+The engine runtime is published separately as [`@ludra/core`](https://www.npmjs.com/package/@ludra/core).
+
+Documentation, the Claude Code plugin and examples: **https://github.com/ersingvn/ludra**
+
+MIT licensed.

package/dist/commands/check.d.ts

@@ -0,0 +1,3 @@
+export declare function check(dir: string, options: {
+    json?: boolean;
+}): number;

package/dist/commands/check.js

@@ -0,0 +1,21 @@
+import { formatDiagnostics, paint } from "../format.js";
+import { loadProject, readScene } from "../project.js";
+export function check(dir, options) {
+    const project = loadProject(dir);
+    const { scene, diagnostics } = readScene(project);
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.length - errors;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: errors === 0, file: project.entryLabel, errors, warnings, diagnostics }, null, 2));
+        return errors > 0 ? 1 : 0;
+    }
+    if (diagnostics.length > 0)
+        console.log(`${formatDiagnostics(diagnostics, project.entryLabel)}\n`);
+    if (errors > 0) {
+        console.log(paint("red", `✗ ${project.entryLabel}: ${errors} error(s), ${warnings} warning(s)`));
+        return 1;
+    }
+    const count = scene?.entities.length ?? 0;
+    console.log(paint("green", `✓ ${project.entryLabel}: ${count} entities, ${warnings === 0 ? "no problems" : `${warnings} warning(s)`}`));
+    return 0;
+}

package/dist/commands/components.d.ts

@@ -0,0 +1,3 @@
+export declare function components(name: string | undefined, options: {
+    json?: boolean;
+}): number;

package/dist/commands/components.js

@@ -0,0 +1,55 @@
+import { COMPONENT_NAMES, COMPONENTS, EFFECT_FIELDS, EFFECTS_DESCRIPTION, EVENT_TYPES, isComponentName, PARTICLE_FIELDS, SOUND_PRESETS, } from "@ludra/core";
+import { pad, paint } from "../format.js";
+import { CliError } from "../project.js";
+const EFFECTS_EXAMPLE = `"effects": {
+    "collect": { "sound": "coin", "particles": { "count": 12, "color": "#ffd166", "speed": 140 } },
+    "die": { "sound": "explosion", "shake": 8, "particles": { "count": 24, "color": "#ff5d73" } }
+  }`;
+export function components(name, options) {
+    if (name !== undefined && name !== "effects" && !isComponentName(name)) {
+        throw new CliError(`Unknown component "${name}". Components: ${COMPONENT_NAMES.join(", ")}, plus "effects" for scene effects.`);
+    }
+    const names = name === undefined ? COMPONENT_NAMES : isComponentName(name) ? [name] : [];
+    const showEffects = name === undefined || name === "effects";
+    if (options.json) {
+        const effects = { description: EFFECTS_DESCRIPTION, events: EVENT_TYPES, soundPresets: SOUND_PRESETS, fields: EFFECT_FIELDS, particles: PARTICLE_FIELDS };
+        const output = Object.fromEntries(names.map((n) => [n, COMPONENTS[n]]));
+        console.log(JSON.stringify(showEffects ? { ...output, effects } : output, null, 2));
+        return 0;
+    }
+    for (const n of names) {
+        const spec = COMPONENTS[n];
+        console.log(`${paint("bold", n)} — ${spec.description}`);
+        if (spec.requires?.length)
+            console.log(paint("dim", `  requires: ${spec.requires.join(", ")}`));
+        printFields(spec.fields);
+        console.log();
+    }
+    if (showEffects) {
+        console.log(`${paint("bold", "effects")} (scene level, not a component) — ${EFFECTS_DESCRIPTION}`);
+        console.log(paint("dim", `  events: ${EVENT_TYPES.join(", ")}`));
+        console.log(paint("dim", `  sound presets: ${SOUND_PRESETS.join(", ")}`));
+        printFields(EFFECT_FIELDS);
+        console.log(`  ${pad("particles", 13)} ${pad("object", 34)} ${pad("optional", 18)} ${paint("dim", "A burst at the event position, with these fields:")}`);
+        printFields(PARTICLE_FIELDS, "    ");
+        console.log(paint("dim", `  example:\n  ${EFFECTS_EXAMPLE}`));
+        console.log();
+    }
+    return 0;
+}
+function printFields(fields, indent = "  ") {
+    for (const [field, fieldSpec] of Object.entries(fields)) {
+        // Pad before coloring so escape codes don't break the alignment.
+        const required = fieldSpec.default === undefined ? paint("yellow", pad("required", 18)) : pad(`default ${JSON.stringify(fieldSpec.default)}`, 18);
+        console.log(`${indent}${pad(field, 15 - indent.length)} ${pad(typeLabel(fieldSpec), 34)} ${required} ${paint("dim", fieldSpec.description)}`);
+    }
+}
+function typeLabel(spec) {
+    if (spec.type === "enum")
+        return spec.values.map((v) => `"${v}"`).join(" | ");
+    if (spec.type === "number" && spec.min !== undefined)
+        return `number ≥ ${spec.min}`;
+    if (spec.type === "frames")
+        return 'frames ("0", "1-4", "0,2")';
+    return spec.type;
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,4 @@
+/** Serves the game for a human to play, and reloads the page when the scene or its assets change. */
+export declare function dev(dir: string, options: {
+    port?: string;
+}): number;

package/dist/commands/dev.js

@@ -0,0 +1,67 @@
+import { paint } from "../format.js";
+import { CliError, loadProject } from "../project.js";
+import { createGameServer, PROJECT_PREFIX } from "../server.js";
+/** Serves the game for a human to play, and reloads the page when the scene or its assets change. */
+export function dev(dir, options) {
+    const project = loadProject(dir);
+    const port = Number(options.port ?? 5173);
+    if (!Number.isInteger(port) || port <= 0)
+        throw new CliError(`Invalid --port "${options.port}".`);
+    const { server } = createGameServer(project, (browserModule) => page(project, browserModule));
+    server.on("error", (err) => {
+        console.error(paint("red", err.code === "EADDRINUSE" ? `Port ${port} is in use. Try --port ${port + 1}.` : err.message));
+        process.exit(1);
+    });
+    server.listen(port, "127.0.0.1", () => {
+        console.log(paint("green", `▶ ${project.config.name} is running at http://localhost:${port}`));
+        console.log(paint("dim", `  Arrows/WASD to move, Space/Z to jump, M to mute, R to restart.`));
+        console.log(paint("dim", `  Editing ${project.entryLabel} or its images and sounds reloads the page. Ctrl+C to stop.`));
+    });
+    return 0;
+}
+function page(project, browserModule) {
+    const { width, height } = project.config.window;
+    const title = escapeHtml(project.config.name);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title} · Ludra</title>
+<style>
+  html, body { margin: 0; height: 100%; background: #0b0e14; color: #e6e6e6; font-family: system-ui, sans-serif; }
+  body { display: grid; place-items: center; }
+  canvas { max-width: 100vw; max-height: 100vh; box-shadow: 0 0 0 1px #2a3142; }
+  #errors { max-width: 900px; padding: 24px; white-space: pre-wrap; font: 14px/1.5 ui-monospace, monospace; color: #ff9b9b; }
+</style>
+</head>
+<body>
+<canvas id="game" width="${width}" height="${height}"></canvas>
+<pre id="errors" hidden></pre>
+<script type="module">
+import { startGame } from "${browserModule}";
+
+const data = await (await fetch("/__ludra/scene")).json();
+if (data.ok) {
+  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}" });
+} else {
+  document.getElementById("game").hidden = true;
+  const errors = document.getElementById("errors");
+  errors.hidden = false;
+  errors.textContent = "The scene has errors (run \`ludra check\`):\\n\\n" +
+    data.diagnostics.map((d) => d.severity + " " + d.code + " at " + d.path + "\\n  " + d.message + (d.fix ? "\\n  fix: " + d.fix : "")).join("\\n\\n");
+}
+
+const version = await (await fetch("/__ludra/version")).text();
+setInterval(async () => {
+  try {
+    if ((await (await fetch("/__ludra/version")).text()) !== version) location.reload();
+  } catch {}
+}, 1000);
+</script>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,3 @@
+export declare function create(dir: string | undefined, options: {
+    template?: string;
+}): number;

package/dist/commands/new.js

@@ -0,0 +1,46 @@
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { paint } from "../format.js";
+import { CliError } from "../project.js";
+/** Same relative location from `src/commands` and `dist/commands`. */
+const TEMPLATES_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
+export function create(dir, options) {
+    if (!dir)
+        throw new CliError("Usage: ludra new <folder> [--template platformer]");
+    const template = options.template ?? "platformer";
+    const source = join(TEMPLATES_DIR, template);
+    if (!existsSync(source)) {
+        throw new CliError(`Unknown template "${template}". Templates: ${readdirSync(TEMPLATES_DIR).join(", ")}.`);
+    }
+    const target = resolve(dir);
+    if (existsSync(target) && readdirSync(target).length > 0) {
+        throw new CliError(`${target} already exists and is not empty. Choose a new folder.`);
+    }
+    const name = basename(target);
+    cpSync(source, target, { recursive: true });
+    // npm never publishes files named .gitignore, so templates ship it as _gitignore.
+    const gitignore = join(target, "_gitignore");
+    if (existsSync(gitignore))
+        renameSync(gitignore, join(target, ".gitignore"));
+    for (const file of listFiles(target)) {
+        const text = readFileSync(file, "utf8");
+        if (text.includes("{{name}}"))
+            writeFileSync(file, text.replaceAll("{{name}}", name));
+    }
+    const shown = relative(process.cwd(), target) || ".";
+    console.log(paint("green", `✓ Created ${name} from the "${template}" template in ${shown}`));
+    console.log(`
+Next steps:
+  npx @ludra/cli check ${shown}          validate the scene
+  npx @ludra/cli play ${shown} --ascii   simulate it headlessly and see the final frame
+  npx @ludra/cli test ${shown}           run tests/*.test.json
+  npx @ludra/cli dev ${shown}            play it in the browser`);
+    return 0;
+}
+function listFiles(dir) {
+    return readdirSync(dir).flatMap((entry) => {
+        const path = join(dir, entry);
+        return statSync(path).isDirectory() ? listFiles(path) : [path];
+    });
+}

package/dist/commands/play.d.ts

@@ -0,0 +1,12 @@
+export interface PlayOptions {
+    inputs?: string;
+    duration?: string;
+    watch?: string;
+    every?: string;
+    ascii?: boolean;
+    columns?: string;
+    screenshot?: string;
+    out?: string;
+    json?: boolean;
+}
+export declare function play(dir: string, options: PlayOptions): Promise<number>;

package/dist/commands/play.js

@@ -0,0 +1,126 @@
+import { defaultDuration, InputScript, parseDuration, renderAscii, secondsToFrames, simulate, World, } from "@ludra/core";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { fixed, pad, padStart, paint } from "../format.js";
+import { captureScreenshots } from "../headless.js";
+import { CliError, loadProject, requireScene } from "../project.js";
+const MAX_EVENTS_SHOWN = 40;
+export async function play(dir, options) {
+    const project = loadProject(dir);
+    const scene = requireScene(project);
+    const script = parse(() => InputScript.parse(options.inputs ?? ""));
+    const frames = secondsToFrames(options.duration ? parse(() => parseDuration(options.duration)) : defaultDuration(script));
+    const every = Math.max(1, secondsToFrames(parse(() => parseDuration(options.every ?? "0.25s"))));
+    const world = new World(scene);
+    const watch = options.watch
+        ? options.watch.split(",").map((id) => id.trim()).filter(Boolean)
+        : world.entities.filter((e) => e.platformer).map((e) => e.id);
+    for (const id of watch) {
+        if (!world.get(id)) {
+            throw new CliError(`--watch: no entity "${id}". Entities: ${world.entities.map((e) => e.id).join(", ")}.`);
+        }
+    }
+    const rows = [];
+    simulate(world, script, frames, (w) => {
+        if (w.frame % every !== 0 && w.frame !== frames)
+            return;
+        const snapshot = w.snapshot();
+        const input = w.frame === 0 ? [] : [...script.at(w.frame - 1)];
+        rows.push({ time: w.time, input, entities: Object.fromEntries(watch.map((id) => [id, snapshot.entities[id] ?? null])) });
+    });
+    const columns = Number(options.columns ?? 80);
+    if (!Number.isInteger(columns) || columns < 10)
+        throw new CliError(`--columns must be a whole number of at least 10, got "${options.columns}".`);
+    const ascii = options.ascii ? renderAscii(world, { columns }) : undefined;
+    const screenshots = options.screenshot ? await takeScreenshots(project, options, frames) : undefined;
+    if (options.json) {
+        console.log(JSON.stringify({ duration: frames / 60, frames, inputs: options.inputs ?? "", timeline: rows, events: world.events, final: world.snapshot(), ascii, screenshots }, null, 2));
+        return 0;
+    }
+    console.log(paint("bold", `▶ ${project.config.name}: simulated ${fixed(frames / 60, 2)}s (${frames} frames)`) +
+        paint("dim", `  inputs: ${options.inputs?.trim() || "none"}`));
+    if (watch.length > 0)
+        printTimeline(rows, watch);
+    printEvents(world.events);
+    const outcome = world.won ? paint("green", "level complete") : "level not complete";
+    console.log(`\n${paint("bold", "Final:")} ${outcome} · score ${world.score} · deaths ${world.deaths} · ${world.entities.length} entities`);
+    if (ascii)
+        console.log(`\n${ascii}`);
+    if (screenshots) {
+        console.log(`\n${paint("bold", "Screenshots")} ${paint("dim", "(open these PNGs to see the frames)")}`);
+        for (const shot of screenshots)
+            console.log(`  ${pad(`${fixed(shot.time, 2)}s`, 7)} ${shot.file}`);
+    }
+    return 0;
+}
+/**
+ * Renders moments of the same run in a headless browser and writes them as
+ * PNGs. `--screenshot` is a comma list of times and/or "end".
+ */
+async function takeScreenshots(project, options, lastFrame) {
+    const requested = options.screenshot.split(",").map((part) => {
+        const token = part.trim();
+        if (token === "end")
+            return lastFrame;
+        const frame = secondsToFrames(parse(() => parseDuration(token)));
+        if (frame > lastFrame) {
+            throw new CliError(`--screenshot ${token} is after the end of the run (${fixed(lastFrame / 60, 2)}s). Use a longer --duration.`);
+        }
+        return frame;
+    });
+    const frames = [...new Set(requested)].sort((a, b) => a - b);
+    const outDir = resolve(project.dir, options.out ?? "screenshots");
+    mkdirSync(outDir, { recursive: true });
+    const captured = await captureScreenshots(project, { inputs: options.inputs ?? "", frames });
+    return captured.map((shot) => {
+        const path = join(outDir, `t-${fixed(shot.time, 2)}s.png`);
+        writeFileSync(path, Buffer.from(shot.png.slice(shot.png.indexOf(",") + 1), "base64"));
+        return { time: shot.time, frame: shot.frame, file: relative(process.cwd(), path).replaceAll("\\", "/") };
+    });
+}
+function printTimeline(rows, watch) {
+    const idWidth = Math.max(6, ...watch.map((id) => id.length));
+    console.log(paint("dim", `\n  ${pad("time", 7)} ${pad("input", 14)} ${pad("entity", idWidth)} ${padStart("x", 8)} ${padStart("y", 8)} ${padStart("vx", 8)} ${padStart("vy", 8)}  grounded`));
+    for (const row of rows) {
+        watch.forEach((id, i) => {
+            const e = row.entities[id];
+            const time = i === 0 ? pad(`${fixed(row.time, 2)}s`, 7) : " ".repeat(7);
+            const input = i === 0 ? pad(row.input.join("+") || "-", 14) : " ".repeat(14);
+            const values = e
+                ? `${padStart(fixed(e.x), 8)} ${padStart(fixed(e.y), 8)} ${padStart(fixed(e.vx), 8)} ${padStart(fixed(e.vy), 8)}  ${e.grounded ? "yes" : "no"}`
+                : paint("dim", "(removed)");
+            console.log(`  ${time} ${input} ${pad(id, idWidth)} ${values}`);
+        });
+    }
+}
+function printEvents(events) {
+    console.log(`\n${paint("bold", "Events")}${events.length === 0 ? paint("dim", " (none)") : ""}`);
+    for (const event of events.slice(0, MAX_EVENTS_SHOWN)) {
+        console.log(`  ${pad(`${fixed(event.time, 2)}s`, 7)} ${pad(event.type, 8)} ${describeEvent(event)}`);
+    }
+    if (events.length > MAX_EVENTS_SHOWN)
+        console.log(paint("dim", `  … ${events.length - MAX_EVENTS_SHOWN} more (use --json for all)`));
+}
+function describeEvent(event) {
+    switch (event.type) {
+        case "collect":
+            return `${event.entity} → ${event.item} (+${event.score})`;
+        case "stomp":
+            return `${event.entity} stomped ${event.enemy}${event.score ? ` (+${event.score})` : ""}`;
+        case "die":
+            return `${event.entity} ${event.cause === "fall" ? "fell out of the world" : `hit ${event.cause}`}, respawned`;
+        case "win":
+            return `${event.entity} reached ${event.goal}`;
+        default:
+            return event.entity;
+    }
+}
+/** Turns engine parse errors into user-facing CLI errors. */
+function parse(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        throw new CliError(err.message);
+    }
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,3 @@
+export declare function test(dir: string, options: {
+    json?: boolean;
+}): number;

package/dist/commands/test.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runTest } from "@ludra/core";
+import { paint } from "../format.js";
+import { loadProject, requireScene } from "../project.js";
+export function test(dir, options) {
+    const project = loadProject(dir);
+    const scene = requireScene(project);
+    const testsDir = join(project.dir, "tests");
+    const files = existsSync(testsDir) ? readdirSync(testsDir).filter((f) => f.endsWith(".test.json")).sort() : [];
+    if (files.length === 0) {
+        const message = 'No tests found. Add tests/<name>.test.json with { "tests": [{ "name": "...", "inputs": "right:1s", "assert": ["player.x > 300"] }] }.';
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message, files: [] }, null, 2));
+        else
+            console.log(paint("yellow", message));
+        return 1;
+    }
+    const results = files.map((file) => {
+        let cases;
+        try {
+            const parsed = JSON.parse(readFileSync(join(testsDir, file), "utf8"));
+            cases = parsed.tests;
+            if (!Array.isArray(cases))
+                throw new Error('expected { "tests": [...] }');
+        }
+        catch (err) {
+            return { file, error: err.message, tests: [] };
+        }
+        return { file, tests: cases.map((c) => runTest(scene, c)) };
+    });
+    const all = results.flatMap((r) => r.tests);
+    const failed = all.filter((t) => !t.pass).length + results.filter((r) => r.error).length;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: failed === 0, passed: all.length - failed, failed, files: results }, null, 2));
+        return failed > 0 ? 1 : 0;
+    }
+    for (const result of results) {
+        console.log(paint("bold", result.file));
+        if (result.error)
+            console.log(paint("red", `  ✗ could not read file: ${result.error}`));
+        for (const t of result.tests) {
+            console.log(t.pass ? paint("green", `  ✓ ${t.name}`) : paint("red", `  ✗ ${t.name}`));
+            if (t.error)
+                console.log(`      ${t.error}`);
+            for (const r of t.results) {
+                if (!r.pass)
+                    console.log(`      ${paint("red", "✗")} ${r.source}  ${paint("dim", "→")} ${r.message}`);
+            }
+        }
+    }
+    const summary = `\n${all.length - failed} passed, ${failed} failed`;
+    console.log(failed > 0 ? paint("red", summary) : paint("green", summary));
+    return failed > 0 ? 1 : 0;
+}

package/dist/format.d.ts

@@ -0,0 +1,11 @@
+import { styleText } from "node:util";
+import type { Diagnostic } from "@ludra/core";
+type Style = Parameters<typeof styleText>[0];
+/** Colors only when writing to a terminal; agents reading piped output get plain text. */
+export declare function paint(style: Style, text: string): string;
+export declare function formatDiagnostic(d: Diagnostic, file: string): string;
+export declare function formatDiagnostics(diagnostics: readonly Diagnostic[], file: string): string;
+export declare function fixed(n: number, digits?: number): string;
+export declare function pad(text: string, width: number): string;
+export declare function padStart(text: string, width: number): string;
+export {};

package/dist/format.js

@@ -0,0 +1,24 @@
+import { styleText } from "node:util";
+/** Colors only when writing to a terminal; agents reading piped output get plain text. */
+export function paint(style, text) {
+    return styleText(style, text, { stream: process.stdout });
+}
+export function formatDiagnostic(d, file) {
+    const icon = d.severity === "error" ? paint("red", "✗ error") : paint("yellow", "! warning");
+    const lines = [`${icon} ${d.code} ${paint("dim", `${file} → ${d.path}`)}`, `  ${d.message}`];
+    if (d.fix)
+        lines.push(`  ${paint("cyan", "fix:")} ${d.fix}`);
+    return lines.join("\n");
+}
+export function formatDiagnostics(diagnostics, file) {
+    return diagnostics.map((d) => formatDiagnostic(d, file)).join("\n\n");
+}
+export function fixed(n, digits = 1) {
+    return n.toFixed(digits);
+}
+export function pad(text, width) {
+    return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+export function padStart(text, width) {
+    return text.length >= width ? text : " ".repeat(width - text.length) + text;
+}

package/dist/headless.d.ts

@@ -0,0 +1,16 @@
+import type { CapturedFrame } from "@ludra/core/browser";
+import { type Project } from "./project.ts";
+/**
+ * Finds an installed Chromium-based browser: LUDRA_BROWSER if set, otherwise
+ * Chrome, Edge or Chromium in their usual places.
+ */
+export declare function findBrowser(): string | undefined;
+export interface ScreenshotRequest {
+    inputs: string;
+    frames: number[];
+}
+/**
+ * Renders frames of a project in a headless browser, using the same renderer
+ * players see. Starts a private game server and browser, and stops both.
+ */
+export declare function captureScreenshots(project: Project, request: ScreenshotRequest): Promise<CapturedFrame[]>;