@kitsra/kavio-cli 0.1.0

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these
+terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# 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":""}

package/dist/index.js

@@ -0,0 +1,1037 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { socialMediaPresets } from "@kitsra/kavio-builder";
+import { compileTransitionOverlapWindows } from "@kitsra/kavio-core";
+import { schemaVersion, validateComposition } from "@kitsra/kavio-schema";
+import { renderBatch } from "@kitsra/kavio-render";
+const commands = new Set(["validate", "inspect", "migrate", "preview", "render", "presets"]);
+const VALUE_FLAGS = new Set(["--export", "--props", "--batch", "--out", "--concurrency"]);
+async function main(argv) {
+    const parsed = parseArgs(argv);
+    if ("errors" in parsed) {
+        emitFailure(parsed, parsed.command === "unknown" ? argv.includes("--json") : false);
+        return 1;
+    }
+    if (parsed.command === "help") {
+        writeStdout(helpText());
+        return 0;
+    }
+    if (parsed.command === "presets") {
+        return runPresets(parsed.file, parsed.json);
+    }
+    if (parsed.file === undefined) {
+        emitFailure({
+            command: parsed.command,
+            ok: false,
+            errors: [
+                cliError("CLI_FILE_REQUIRED", "", `Missing file argument for kavio ${parsed.command}.`, `Usage: kavio ${parsed.command} <file>`)
+            ]
+        }, parsed.json);
+        return 1;
+    }
+    switch (parsed.command) {
+        case "validate":
+            return await runValidate(parsed.file, parsed.json);
+        case "inspect":
+            return await runInspect(parsed.file, parsed.json);
+        case "migrate":
+            return await runMigrate(parsed.file, parsed.json);
+        case "preview":
+            return await runPreview(parsed.file, parsed.json);
+        case "render":
+            return await runRender(parsed);
+    }
+    return 0;
+}
+function runPresets(name, json) {
+    if (name !== undefined) {
+        const preset = findSocialMediaPreset(name);
+        if (preset === undefined) {
+            emitFailure({
+                command: "presets",
+                ok: false,
+                errors: [
+                    cliError("CLI_UNKNOWN_PRESET", "", `Unknown social media preset: ${name}`, `Run kavio presets to list supported preset ids.`)
+                ]
+            }, json);
+            return 1;
+        }
+        if (json) {
+            const output = { command: "presets", ok: true, preset };
+            writeJson(output);
+        }
+        else {
+            writeJson(preset.preset);
+        }
+        return 0;
+    }
+    if (json) {
+        const output = { command: "presets", ok: true, presets: socialMediaPresets };
+        writeJson(output);
+    }
+    else {
+        writeSocialMediaPresets(socialMediaPresets);
+    }
+    return 0;
+}
+function parseArgs(argv) {
+    let json = false;
+    let help = false;
+    let allExports = false;
+    let failFast = false;
+    let continueOnFrameError = false;
+    let exportName;
+    let propsFile;
+    let batchFile;
+    let outDir;
+    let concurrency;
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined) {
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        if (arg === "--all-exports") {
+            allExports = true;
+            continue;
+        }
+        if (arg === "--fail-fast") {
+            failFast = true;
+            continue;
+        }
+        if (arg === "--continue-on-frame-error") {
+            continueOnFrameError = true;
+            continue;
+        }
+        if (VALUE_FLAGS.has(arg)) {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("-")) {
+                return flagFailure(`Option ${arg} requires a value.`);
+            }
+            index += 1;
+            if (arg === "--export") {
+                exportName = value;
+            }
+            else if (arg === "--props") {
+                propsFile = value;
+            }
+            else if (arg === "--batch") {
+                batchFile = value;
+            }
+            else if (arg === "--out") {
+                outDir = value;
+            }
+            else {
+                const parsed = Number(value);
+                if (!Number.isInteger(parsed) || parsed < 1) {
+                    return flagFailure("--concurrency must be a positive integer.");
+                }
+                concurrency = parsed;
+            }
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return flagFailure(`Unknown option: ${arg}`);
+        }
+        positional.push(arg);
+    }
+    if (help || positional.length === 0) {
+        return { command: "help", json, allExports, failFast, continueOnFrameError };
+    }
+    const [command, file] = positional;
+    if (command === undefined || !commands.has(command)) {
+        return {
+            command: "unknown",
+            ok: false,
+            errors: [
+                cliError("CLI_UNKNOWN_COMMAND", "", command === undefined ? "Missing command." : `Unknown command: ${command}`, "Run kavio --help for supported commands.")
+            ]
+        };
+    }
+    if (positional.length > 2) {
+        return {
+            command: command,
+            ok: false,
+            errors: [
+                cliError("CLI_TOO_MANY_ARGUMENTS", "", `Too many arguments for kavio ${command}.`, `Usage: kavio ${command} <file>`)
+            ]
+        };
+    }
+    const parsed = { command: command, json, allExports, failFast, continueOnFrameError };
+    if (file !== undefined) {
+        parsed.file = file;
+    }
+    if (exportName !== undefined) {
+        parsed.exportName = exportName;
+    }
+    if (propsFile !== undefined) {
+        parsed.propsFile = propsFile;
+    }
+    if (batchFile !== undefined) {
+        parsed.batchFile = batchFile;
+    }
+    if (outDir !== undefined) {
+        parsed.outDir = outDir;
+    }
+    if (concurrency !== undefined) {
+        parsed.concurrency = concurrency;
+    }
+    return parsed;
+}
+function flagFailure(message) {
+    return {
+        command: "unknown",
+        ok: false,
+        errors: [cliError("CLI_UNKNOWN_FLAG", "", message, "Run kavio --help for supported options.")]
+    };
+}
+async function runValidate(file, json) {
+    const loaded = await loadJson(file);
+    if (!loaded.ok) {
+        emitFailure({ command: "validate", ok: false, errors: [loaded.error] }, json);
+        return 1;
+    }
+    const validation = validateComposition(loaded.document);
+    const output = {
+        command: "validate",
+        ok: validation.ok,
+        file: loaded.filePath,
+        errors: validation.errors
+    };
+    const version = readVersion(loaded.document);
+    if (version !== undefined) {
+        output.version = version;
+    }
+    if (json) {
+        writeJson(output);
+    }
+    else if (validation.ok) {
+        writeStdout(`Valid Kavio composition: ${loaded.filePath}\n`);
+    }
+    else {
+        writeValidationErrors("Invalid Kavio composition", loaded.filePath, validation);
+    }
+    return validation.ok ? 0 : 1;
+}
+async function runInspect(file, json) {
+    const loaded = await loadJson(file);
+    if (!loaded.ok) {
+        emitFailure({ command: "inspect", ok: false, errors: [loaded.error] }, json);
+        return 1;
+    }
+    const validation = validateComposition(loaded.document);
+    if (!validation.ok) {
+        if (json) {
+            writeJson({
+                command: "inspect",
+                ok: false,
+                file: loaded.filePath,
+                errors: validation.errors
+            });
+        }
+        else {
+            writeValidationErrors("Cannot inspect invalid Kavio composition", loaded.filePath, validation);
+        }
+        return 1;
+    }
+    const summary = inspectDocument(loaded.filePath, loaded.document);
+    const output = { command: "inspect", ok: true, summary };
+    if (json) {
+        writeJson(output);
+    }
+    else {
+        writeInspection(summary);
+    }
+    return 0;
+}
+async function runMigrate(file, json) {
+    const loaded = await loadJson(file);
+    if (!loaded.ok) {
+        emitFailure({ command: "migrate", ok: false, errors: [loaded.error] }, json);
+        return 1;
+    }
+    const version = readVersion(loaded.document);
+    if (version === undefined) {
+        emitFailure({
+            command: "migrate",
+            ok: false,
+            errors: [
+                cliError("CLI_MIGRATION_VERSION_REQUIRED", "version", "Cannot migrate a document without a string version.", `Current supported schema version is ${schemaVersion}.`)
+            ]
+        }, json);
+        return 1;
+    }
+    if (version !== schemaVersion) {
+        emitFailure({
+            command: "migrate",
+            ok: false,
+            errors: [
+                cliError("CLI_MIGRATION_UNSUPPORTED_VERSION", "version", `No migration path is available from ${version} to ${schemaVersion}.`, "This CLI currently supports the no-op 0.1 to 0.1 migration path.")
+            ]
+        }, json);
+        return 1;
+    }
+    const validation = validateComposition(loaded.document);
+    if (!validation.ok) {
+        if (json) {
+            writeJson({
+                command: "migrate",
+                ok: false,
+                file: loaded.filePath,
+                fromVersion: version,
+                toVersion: schemaVersion,
+                errors: validation.errors
+            });
+        }
+        else {
+            writeValidationErrors("Cannot migrate invalid Kavio composition", loaded.filePath, validation);
+        }
+        return 1;
+    }
+    const output = {
+        command: "migrate",
+        ok: true,
+        file: loaded.filePath,
+        changed: false,
+        fromVersion: version,
+        toVersion: schemaVersion,
+        document: loaded.document
+    };
+    if (json) {
+        writeJson(output);
+    }
+    else {
+        writeStderr(`No migration needed: ${loaded.filePath} is already schema ${schemaVersion}.\n`);
+        writeJson(loaded.document);
+    }
+    return 0;
+}
+async function runPreview(file, json) {
+    const loaded = await loadJson(file);
+    if (!loaded.ok) {
+        emitFailure({ command: "preview", ok: false, errors: [loaded.error] }, json);
+        return 1;
+    }
+    const validation = validateComposition(loaded.document);
+    if (!validation.ok) {
+        if (json) {
+            writeJson({
+                command: "preview",
+                ok: false,
+                file: loaded.filePath,
+                errors: validation.errors
+            });
+        }
+        else {
+            writeValidationErrors("Cannot preview invalid Kavio composition", loaded.filePath, validation);
+        }
+        return 1;
+    }
+    const document = loaded.document;
+    const summary = inspectDocument(loaded.filePath, document);
+    const assets = await loadPreviewAssets();
+    const server = createServer((request, response) => {
+        void servePreviewRequest(request, response, document, summary, assets).catch((error) => {
+            response.statusCode = 500;
+            response.setHeader("content-type", "text/plain; charset=utf-8");
+            response.end(`Preview server error: ${errorMessage(error)}\n`);
+        });
+    });
+    const port = await listenOnLocalhost(server);
+    const url = `http://127.0.0.1:${port}/`;
+    const output = {
+        command: "preview",
+        ok: true,
+        file: loaded.filePath,
+        url,
+        renderer: assets.renderer,
+        summary
+    };
+    if (json) {
+        writeJson(output);
+    }
+    else {
+        writeStdout(`Kavio preview: ${url}\n`);
+        writeStdout(`Composition: ${loaded.filePath}\n`);
+        writeStdout(`Renderer: ${formatPreviewRendererStatus(assets.renderer)}\n`);
+        writeStdout("Press Ctrl+C to stop the preview server.\n");
+    }
+    return 0;
+}
+async function runRender(parsed) {
+    const file = parsed.file;
+    if (file === undefined) {
+        emitFailure({
+            command: "render",
+            ok: false,
+            errors: [cliError("CLI_FILE_REQUIRED", "", "Missing file argument for kavio render.", "Usage: kavio render <file>")]
+        }, parsed.json);
+        return 1;
+    }
+    const loaded = await loadJson(file);
+    if (!loaded.ok) {
+        emitFailure({ command: "render", ok: false, errors: [loaded.error] }, parsed.json);
+        return 1;
+    }
+    const rows = await resolveRenderRows(parsed);
+    if (!rows.ok) {
+        emitFailure({ command: "render", ok: false, errors: [rows.error] }, parsed.json);
+        return 1;
+    }
+    const input = { template: loaded.document, rows: rows.rows };
+    if (parsed.exportName !== undefined) {
+        input.presets = [parsed.exportName];
+    }
+    const options = {
+        outDir: parsed.outDir ?? "renders",
+        failFast: parsed.failFast,
+        continueOnFrameError: parsed.continueOnFrameError
+    };
+    if (parsed.concurrency !== undefined) {
+        options.concurrency = parsed.concurrency;
+    }
+    let results;
+    try {
+        results = await renderBatch(input, options);
+    }
+    catch (error) {
+        emitFailure({
+            command: "render",
+            ok: false,
+            errors: [cliError("CLI_RENDER_FAILED", "", errorMessage(error), "Check export preset names and render inputs.")]
+        }, parsed.json);
+        return 1;
+    }
+    const succeeded = results.filter((item) => item.result.ok).length;
+    const ok = results.length > 0 && succeeded === results.length;
+    if (parsed.json) {
+        writeJson({
+            command: "render",
+            ok,
+            total: results.length,
+            succeeded,
+            outputs: results.map((item) => item.result.ok
+                ? { id: item.id, outputName: item.outputName, ok: true, outputPath: item.result.outputPath }
+                : { id: item.id, outputName: item.outputName, ok: false, errors: item.result.errors })
+        });
+    }
+    else {
+        for (const item of results) {
+            if (item.result.ok) {
+                writeStdout(`Rendered ${item.result.outputPath}\n`);
+            }
+            else {
+                writeStderr(`Failed ${item.outputName}:\n`);
+                for (const error of item.result.errors) {
+                    const path = error.path.length > 0 ? ` at ${error.path}` : "";
+                    writeStderr(`  - [${error.code}]${path} ${error.message}\n`);
+                }
+            }
+        }
+        writeStdout(`${succeeded}/${results.length} renders succeeded.\n`);
+    }
+    return ok ? 0 : 1;
+}
+async function resolveRenderRows(parsed) {
+    if (parsed.batchFile !== undefined) {
+        const batch = await loadJson(parsed.batchFile);
+        if (!batch.ok) {
+            return { ok: false, error: batch.error };
+        }
+        if (!Array.isArray(batch.document)) {
+            return {
+                ok: false,
+                error: cliError("CLI_BATCH_INVALID", "", "Batch file must be a JSON array of prop rows.", 'Each row is { "id"?: string, "props"?: object }.')
+            };
+        }
+        return { ok: true, rows: batch.document };
+    }
+    if (parsed.propsFile !== undefined) {
+        const props = await loadJson(parsed.propsFile);
+        if (!props.ok) {
+            return { ok: false, error: props.error };
+        }
+        if (typeof props.document !== "object" || props.document === null || Array.isArray(props.document)) {
+            return {
+                ok: false,
+                error: cliError("CLI_PROPS_INVALID", "", "Props file must be a JSON object.", 'Provide { "propName": value, ... }.')
+            };
+        }
+        const propValues = props.document;
+        return { ok: true, rows: [{ props: propValues }] };
+    }
+    return { ok: true, rows: [{}] };
+}
+async function loadJson(file) {
+    const filePath = resolve(process.cwd(), file);
+    try {
+        const source = await readFile(filePath, "utf8");
+        try {
+            return { ok: true, filePath, document: JSON.parse(source) };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: cliError("CLI_JSON_PARSE_FAILED", filePath, `Failed to parse JSON: ${errorMessage(error)}`, "Check the file for invalid JSON syntax.")
+            };
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: cliError("CLI_FILE_READ_FAILED", filePath, `Failed to read file: ${errorMessage(error)}`, "Check that the path exists and is readable.")
+        };
+    }
+}
+async function loadPreviewAssets() {
+    const browserRendererUrl = new URL("../../browser-renderer/dist/index.js", import.meta.url);
+    const coreUrl = new URL("../../core/dist/index.js", import.meta.url);
+    try {
+        const [browserRendererSource, coreSource] = await Promise.all([
+            readFile(browserRendererUrl, "utf8"),
+            readFile(coreUrl, "utf8")
+        ]);
+        return {
+            browserRendererSource,
+            coreSource,
+            renderer: {
+                available: true,
+                mode: "browser-renderer"
+            }
+        };
+    }
+    catch (error) {
+        return {
+            renderer: {
+                available: false,
+                mode: "placeholder",
+                reason: `Browser renderer package output is not available: ${errorMessage(error)}`
+            }
+        };
+    }
+}
+function listenOnLocalhost(server) {
+    return new Promise((resolveListen, rejectListen) => {
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (isListenAddress(address)) {
+                resolveListen(address.port);
+                return;
+            }
+            rejectListen(new Error("Preview server did not return a TCP address."));
+        });
+    });
+}
+function isListenAddress(value) {
+    return isRecord(value) && typeof value.port === "number";
+}
+async function servePreviewRequest(request, response, document, summary, assets) {
+    const path = normalizeRequestPath(request.url);
+    if (request.method !== undefined && request.method !== "GET" && request.method !== "HEAD") {
+        sendText(response, 405, "Method not allowed.\n");
+        return;
+    }
+    if (path === "/" || path === "/index.html") {
+        sendHtml(response, renderPreviewHtml(summary, assets.renderer));
+        return;
+    }
+    if (path === "/composition.json") {
+        sendJson(response, document);
+        return;
+    }
+    if (path === "/healthz") {
+        sendJson(response, {
+            ok: true,
+            command: "preview",
+            renderer: assets.renderer
+        });
+        return;
+    }
+    if (path === "/vendor/browser-renderer/index.js" && assets.browserRendererSource !== undefined) {
+        sendJavaScript(response, assets.browserRendererSource);
+        return;
+    }
+    if (path === "/vendor/core/index.js" && assets.coreSource !== undefined) {
+        sendJavaScript(response, assets.coreSource);
+        return;
+    }
+    sendText(response, 404, "Not found.\n");
+}
+function normalizeRequestPath(url) {
+    return (url ?? "/").split("?", 1)[0] ?? "/";
+}
+function inspectDocument(filePath, document) {
+    const fps = Number(document.composition.fps);
+    const durationSeconds = fps > 0 ? document.composition.durationFrames / fps : 0;
+    const composition = {
+        width: document.composition.width,
+        height: document.composition.height,
+        fps,
+        durationFrames: document.composition.durationFrames,
+        durationSeconds
+    };
+    if (document.composition.background !== undefined) {
+        composition.background = document.composition.background;
+    }
+    if (document.composition.colorSpace !== undefined) {
+        composition.colorSpace = document.composition.colorSpace;
+    }
+    return {
+        file: filePath,
+        version: document.version,
+        composition,
+        props: {
+            count: document.props === undefined ? 0 : Object.keys(document.props).length
+        },
+        assets: {
+            count: Object.keys(document.assets).length,
+            types: countTypes(Object.values(document.assets))
+        },
+        layers: {
+            count: document.layers.length,
+            types: countTypes(document.layers)
+        },
+        masks: inspectMasks(document),
+        tracks: {
+            count: document.tracks === undefined ? 0 : document.tracks.length,
+            clipCount: document.tracks === undefined ? 0 : document.tracks.reduce((total, track) => total + track.clips.length, 0),
+            transitionWindows: compileTransitionOverlapWindows(document.tracks).map((window) => ({
+                trackId: window.trackId,
+                previousClipId: window.previousClipId,
+                previousLayerId: window.previousLayerId,
+                nextClipId: window.nextClipId,
+                nextLayerId: window.nextLayerId,
+                startFrame: window.startFrame,
+                endFrame: window.endFrame,
+                durationFrames: window.durationFrames,
+                transitionType: window.transition.type
+            }))
+        },
+        audio: {
+            count: document.audio === undefined ? 0 : document.audio.length
+        },
+        exports: {
+            count: document.exports.length,
+            names: document.exports.map((entry, index) => readName(entry) ?? `export-${index + 1}`)
+        }
+    };
+}
+function inspectMasks(document) {
+    const summary = {
+        count: 0,
+        shapeCount: 0,
+        assetMasks: [],
+        proceduralMasks: [],
+        invertedCount: 0
+    };
+    for (const layer of document.layers) {
+        const mask = layer.mask;
+        if (!mask) {
+            continue;
+        }
+        summary.count += 1;
+        if (mask.invert === true) {
+            summary.invertedCount += 1;
+        }
+        switch (mask.source.kind) {
+            case "shape":
+                summary.shapeCount += 1;
+                break;
+            case "asset":
+                summary.assetMasks.push(withResolution({
+                    layerId: layer.id,
+                    asset: mask.source.asset,
+                    mode: mask.source.mode ?? "alpha"
+                }, mask.source.resolution));
+                break;
+            case "procedural":
+                summary.proceduralMasks.push(withResolution({
+                    layerId: layer.id,
+                    type: mask.source.type,
+                    seed: mask.source.seed,
+                    ...(mask.source.direction === undefined ? {} : { direction: mask.source.direction })
+                }, mask.source.resolution));
+                break;
+        }
+    }
+    return summary;
+}
+function withResolution(summary, resolution) {
+    return (resolution === undefined
+        ? summary
+        : {
+            ...summary,
+            width: resolution.width,
+            height: resolution.height
+        });
+}
+function countTypes(items) {
+    const counts = {};
+    for (const item of items) {
+        const type = readType(item) ?? "unknown";
+        counts[type] = (counts[type] ?? 0) + 1;
+    }
+    return counts;
+}
+function readVersion(value) {
+    if (!isRecord(value) || typeof value.version !== "string") {
+        return undefined;
+    }
+    return value.version;
+}
+function readType(value) {
+    if (!isRecord(value) || typeof value.type !== "string") {
+        return undefined;
+    }
+    return value.type;
+}
+function readName(value) {
+    if (!isRecord(value) || typeof value.name !== "string") {
+        return undefined;
+    }
+    return value.name;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function writeInspection(summary) {
+    writeStdout(`Kavio composition: ${summary.file}\n`);
+    writeStdout(`Version: ${summary.version}\n`);
+    writeStdout(`Size: ${summary.composition.width}x${summary.composition.height} @ ${summary.composition.fps}fps\n`);
+    writeStdout(`Duration: ${summary.composition.durationFrames} frames (${summary.composition.durationSeconds.toFixed(2)}s)\n`);
+    writeStdout(`Props: ${summary.props.count}\n`);
+    writeStdout(`Assets: ${summary.assets.count}${formatTypeCounts(summary.assets.types)}\n`);
+    writeStdout(`Layers: ${summary.layers.count}${formatTypeCounts(summary.layers.types)}\n`);
+    writeStdout(`Masks: ${summary.masks.count} (shape: ${summary.masks.shapeCount}, asset: ${summary.masks.assetMasks.length}, procedural: ${summary.masks.proceduralMasks.length}, inverted: ${summary.masks.invertedCount})\n`);
+    for (const mask of summary.masks.assetMasks) {
+        writeStdout(`  - asset ${mask.asset} on ${mask.layerId}, ${mask.mode}${formatResolution(mask.width, mask.height)}\n`);
+    }
+    for (const mask of summary.masks.proceduralMasks) {
+        writeStdout(`  - procedural ${mask.type} on ${mask.layerId}, seed ${mask.seed}${formatResolution(mask.width, mask.height)}\n`);
+    }
+    writeStdout(`Tracks: ${summary.tracks.count} (${summary.tracks.clipCount} clips, ${summary.tracks.transitionWindows.length} transition windows)\n`);
+    for (const window of summary.tracks.transitionWindows) {
+        writeStdout(`  - ${window.trackId}: ${window.previousClipId} -> ${window.nextClipId}, ${window.transitionType}, frames ${window.startFrame}-${window.endFrame - 1}\n`);
+    }
+    writeStdout(`Audio: ${summary.audio.count}\n`);
+    writeStdout(`Exports: ${summary.exports.count}\n`);
+    for (const exportName of summary.exports.names) {
+        writeStdout(`  - ${exportName}\n`);
+    }
+}
+function formatResolution(width, height) {
+    return width === undefined || height === undefined ? "" : `, ${width}x${height}`;
+}
+function writeSocialMediaPresets(presets) {
+    writeStdout("Kavio social media export presets:\n");
+    for (const preset of presets) {
+        writeStdout(`  ${preset.id.padEnd(24)} ${preset.label.padEnd(24)} ${String(preset.width).padStart(4)}x${String(preset.height).padEnd(4)} ${preset.aspectRatio.padEnd(4)} export: ${preset.defaultName}\n`);
+    }
+    writeStdout("\nUse `kavio presets <id>` to print a copy/pasteable export preset JSON object.\n");
+    writeStdout("Use `kavio presets --json` to print the full machine-readable preset catalog.\n");
+}
+function findSocialMediaPreset(name) {
+    const normalized = normalizePresetName(name);
+    return socialMediaPresets.find((preset) => normalizePresetName(preset.id) === normalized || normalizePresetName(preset.defaultName) === normalized);
+}
+function normalizePresetName(value) {
+    return value.trim().toLowerCase().replaceAll(/[\s_]+/g, "-");
+}
+function renderPreviewHtml(summary, renderer) {
+    const frameCount = Math.max(1, summary.composition.durationFrames);
+    const initialScale = Math.min(1, 720 / summary.composition.height, 960 / summary.composition.width);
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Kavio Preview</title>
+  ${renderer.available ? `<script type="importmap">${escapeHtml(JSON.stringify({ imports: { "@kitsra/kavio-core": "/vendor/core/index.js" } }))}</script>` : ""}
+  <style>
+    :root {
+      color-scheme: dark;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #101820;
+      color: #f5f7fa;
+    }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      grid-template-columns: minmax(260px, 320px) 1fr;
+    }
+    aside {
+      border-right: 1px solid #26313d;
+      padding: 20px;
+      background: #151f29;
+    }
+    main {
+      display: grid;
+      place-items: center;
+      min-width: 0;
+      padding: 24px;
+    }
+    h1 {
+      margin: 0 0 16px;
+      font-size: 20px;
+      font-weight: 650;
+    }
+    dl {
+      display: grid;
+      grid-template-columns: auto 1fr;
+      gap: 8px 12px;
+      margin: 0 0 18px;
+      font-size: 13px;
+    }
+    dt {
+      color: #a7b3c0;
+    }
+    dd {
+      margin: 0;
+      overflow-wrap: anywhere;
+    }
+    .status {
+      border: 1px solid #334150;
+      padding: 12px;
+      background: #101820;
+      font-size: 13px;
+      line-height: 1.45;
+    }
+    .viewport {
+      display: grid;
+      place-items: center;
+      max-width: 100%;
+      overflow: auto;
+    }
+    #stage {
+      width: ${summary.composition.width}px;
+      height: ${summary.composition.height}px;
+      transform: scale(${initialScale});
+      transform-origin: center;
+      background: #0b0f14;
+      box-shadow: 0 24px 80px rgba(0, 0, 0, 0.45);
+    }
+    #placeholder {
+      box-sizing: border-box;
+      width: 100%;
+      height: 100%;
+      display: grid;
+      align-content: center;
+      justify-items: center;
+      gap: 12px;
+      padding: 32px;
+      text-align: center;
+      color: #d9e2ec;
+      background:
+        linear-gradient(90deg, rgba(255,255,255,.06) 1px, transparent 1px),
+        linear-gradient(rgba(255,255,255,.06) 1px, transparent 1px),
+        #0b0f14;
+      background-size: 48px 48px;
+    }
+    code {
+      color: #b7f7d5;
+    }
+    @media (max-width: 760px) {
+      body {
+        grid-template-columns: 1fr;
+      }
+      aside {
+        border-right: 0;
+        border-bottom: 1px solid #26313d;
+      }
+    }
+  </style>
+</head>
+<body>
+  <aside>
+    <h1>Kavio Preview</h1>
+    <dl>
+      <dt>File</dt><dd>${escapeHtml(summary.file)}</dd>
+      <dt>Version</dt><dd>${escapeHtml(summary.version)}</dd>
+      <dt>Size</dt><dd>${summary.composition.width}x${summary.composition.height}</dd>
+      <dt>Frames</dt><dd>${summary.composition.durationFrames} @ ${summary.composition.fps}fps</dd>
+      <dt>Layers</dt><dd>${summary.layers.count}${escapeHtml(formatTypeCounts(summary.layers.types))}</dd>
+      <dt>Assets</dt><dd>${summary.assets.count}${escapeHtml(formatTypeCounts(summary.assets.types))}</dd>
+    </dl>
+    <div class="status" id="status">${escapeHtml(formatPreviewRendererStatus(renderer))}</div>
+  </aside>
+  <main>
+    <div class="viewport">
+      <div id="stage">
+        <div id="placeholder">
+          <strong>Preview shell ready</strong>
+          <span>Loaded ${frameCount} frame${frameCount === 1 ? "" : "s"} from <code>/composition.json</code>.</span>
+        </div>
+      </div>
+    </div>
+  </main>
+  <script type="application/json" id="kavio-summary">${escapeHtml(JSON.stringify(summary))}</script>
+  ${renderer.available
+        ? `<script type="module">
+const status = document.getElementById("status");
+const stage = document.getElementById("stage");
+try {
+  const composition = await fetch("/composition.json").then((response) => response.json());
+  const { installBrowserRendererRuntime } = await import("/vendor/browser-renderer/index.js");
+  const runtime = installBrowserRendererRuntime({ root: stage });
+  await runtime.loadComposition(composition);
+  const rendered = await runtime.renderFrame(0);
+  status.textContent = "Browser renderer loaded. Showing frame 0 with " + rendered.layers.length + " active layer(s).";
+} catch (error) {
+  status.textContent = "Preview placeholder active. Browser renderer package output was found, but could not run in this shell: " + String(error instanceof Error ? error.message : error);
+}
+</script>`
+        : ""}
+</body>
+</html>
+`;
+}
+function formatPreviewRendererStatus(renderer) {
+    if (renderer.available) {
+        return "browser-renderer package output available";
+    }
+    return renderer.reason === undefined ? "placeholder preview shell" : `placeholder preview shell (${renderer.reason})`;
+}
+function sendHtml(response, value) {
+    send(response, 200, "text/html; charset=utf-8", value);
+}
+function sendJson(response, value) {
+    send(response, 200, "application/json; charset=utf-8", `${JSON.stringify(value, null, 2)}\n`);
+}
+function sendJavaScript(response, value) {
+    send(response, 200, "text/javascript; charset=utf-8", value);
+}
+function sendText(response, statusCode, value) {
+    send(response, statusCode, "text/plain; charset=utf-8", value);
+}
+function send(response, statusCode, contentType, value) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", contentType);
+    response.setHeader("cache-control", "no-store");
+    response.end(value);
+}
+function writeValidationErrors(title, filePath, validation) {
+    writeStderr(`${title}: ${filePath}\n`);
+    for (const error of validation.errors) {
+        const path = error.path.length > 0 ? ` at ${error.path}` : "";
+        const hint = error.hint === undefined ? "" : ` Hint: ${error.hint}`;
+        writeStderr(`  - [${error.code}]${path} ${error.message}${hint}\n`);
+    }
+}
+function emitFailure(failure, json) {
+    if (json) {
+        writeJson(failure);
+        return;
+    }
+    for (const error of failure.errors) {
+        const hint = error.hint === undefined ? "" : `\n${error.hint}`;
+        writeStderr(`${error.message}${hint}\n`);
+    }
+}
+function cliError(code, path, message, hint) {
+    const error = {
+        code,
+        severity: "error",
+        message,
+        path,
+        stage: "io",
+        retryable: false
+    };
+    if (hint !== undefined) {
+        error.hint = hint;
+    }
+    return error;
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function formatTypeCounts(counts) {
+    const entries = Object.entries(counts);
+    if (entries.length === 0) {
+        return "";
+    }
+    return ` (${entries.map(([type, count]) => `${type}: ${count}`).join(", ")})`;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        switch (character) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            case "'":
+                return "&#39;";
+            default:
+                return character;
+        }
+    });
+}
+function helpText() {
+    return `Kavio CLI
+
+Usage:
+  kavio --help
+  kavio [--json] validate <file>
+  kavio [--json] inspect <file>
+  kavio [--json] migrate <file>
+  kavio [--json] preview <file>
+  kavio [--json] render <file> [render options]
+  kavio [--json] presets [preset-id]
+
+Options:
+  --json       Emit machine-readable JSON for CI and repair loops.
+  -h, --help   Show this help.
+
+Render options:
+  --export <name>            Render one named export preset.
+  --all-exports              Render every export preset (default).
+  --props <file.json>        Prop values for a single render.
+  --batch <file.json>        Array of prop rows -> rows x presets.
+  --out <dir>                Output directory (default: renders).
+  --concurrency <n>          Parallel jobs (default: 1).
+  --fail-fast                Abort the batch on first job failure.
+  --continue-on-frame-error  Tolerate per-frame capture failures.
+
+Commands:
+  validate     Validate a Kavio composition JSON file.
+  inspect      Print a composition summary.
+  migrate      Write the latest-schema JSON document to stdout.
+  preview      Start a local browser preview server.
+  render       Render a composition to MP4 (browser capture + FFmpeg).
+  presets      List social media export presets or print one export JSON object.
+`;
+}
+function writeJson(value) {
+    writeStdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+function writeStdout(value) {
+    process.stdout.write(value);
+}
+function writeStderr(value) {
+    process.stderr.write(value);
+}
+void main(process.argv.slice(2))
+    .then((exitCode) => {
+    process.exitCode = exitCode;
+})
+    .catch((error) => {
+    writeStderr(`Unexpected CLI failure: ${errorMessage(error)}\n`);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@kitsra/kavio-cli",
+  "version": "0.1.0",
+  "description": "Local CLI for Kavio validation, migration, preview, and rendering.",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kavio": "./dist/index.js"
+  },
+  "dependencies": {
+    "@kitsra/kavio-builder": "0.1.0",
+    "@kitsra/kavio-core": "0.1.0",
+    "@kitsra/kavio-render": "0.1.0",
+    "@kitsra/kavio-schema": "0.1.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -b tsconfig.json && node --test test/*.test.mjs"
+  }
+}