@vutex/vutex 0.0.0-stage → 0.0.1

package/bin/vutex.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { createJiti } from "jiti";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+const { runCli } = await jiti.import(join(here, "../src/cli/main.ts"));
+
+process.exit(await runCli(process.argv.slice(2)));

package/locales/en-US/cli.json

@@ -0,0 +1,18 @@
+{
+  "cli.intro": "vutex — language-neutral document typesetting and rendering",
+  "cli.cmd.render": "Render a document to the configured output format",
+  "cli.cmd.inspect": "Inspect input format and document metadata",
+  "cli.cmd.package": "Manage VuTeX resource packages (fonts, templates, profiles)",
+  "cli.cmd.package.list": "List resource packages from manifest and lockfile",
+  "cli.cmd.package.add": "Add a resource package alias to vutex.toml",
+  "cli.cmd.package.remove": "Remove a resource package alias from vutex.toml",
+  "cli.cmd.package.install": "Resolve and install resource packages into the project cache",
+  "cli.cmd.package.update": "Refresh the resource package lockfile",
+  "cli.cmd.package.doctor": "Check manifest, lockfile, and package cache health",
+  "cli.opt.output": "Output file path, or format id when writing to stdout",
+  "cli.opt.profile": "Named language profile from vutex.toml",
+  "cli.opt.input-format": "Override input format id",
+  "cli.opt.json": "Emit machine-readable JSON on stdout",
+  "cli.opt.package-name": "Resource package name to install",
+  "cli.opt.package-version": "Requested package version range"
+}

package/locales/locales.json

@@ -0,0 +1 @@
+["en-US"]

package/package.json

@@ -1,6 +1,53 @@
 {
+  "bin": {
+    "vutex": "bin/vutex.mjs"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@vmz/commander": "^0.2.0",
+    "jiti": "^2.4.2"
+  },
+  "description": "VuTeX: language-neutral document typesetting runtime and official CLI",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cli": "./src/cli/main.ts",
+    "./node": "./src/node/index.ts"
+  },
+  "files": [
+    "bin",
+    "locales",
+    "readme.md",
+    "src"
+  ],
+  "license": "MPL-2.0",
   "name": "@vutex/vutex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "optionalDependencies": {
+    "@vutex/vutex-darwin-arm64": "0.0.1",
+    "@vutex/vutex-darwin-x64": "0.0.1",
+    "@vutex/vutex-linux-arm64": "0.0.1",
+    "@vutex/vutex-linux-x64": "0.0.1",
+    "@vutex/vutex-win32-x64": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "projects/packages/vutex",
+    "type": "git",
+    "url": "git+https://github.com/notedge/VuTeX.git"
+  },
+  "scripts": {
+    "test": "tsx --test tests/package-manager.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "version": "0.0.1"
+}

package/readme.md

@@ -0,0 +1,18 @@
+# @vutex/vutex
+
+VuTeX TypeScript runtime facade and official CLI.
+
+```bash
+vutex render sample.nd --output out.svg
+vutex inspect sample.nd
+vutex package doctor
+```
+
+```ts
+import { createVuTeX } from "@vutex/vutex";
+
+const vutex = await createVuTeX({ projectRoot: process.cwd() });
+const result = await vutex.render("sample.nd", { output: "svg" });
+```
+
+Resource packages (fonts, templates, profiles) are managed by the VuTeX package manager via `vutex.toml`, not npm.

package/src/cli/cli.ts

@@ -0,0 +1,21 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createCli } from "@vmz/commander";
+
+import { registerInspectCommand } from "./commands/inspect.js";
+import { registerPackageCommands } from "./commands/package.js";
+import { registerRenderCommand } from "./commands/render.js";
+
+export function buildVuTeXCli() {
+    const localesRoot = join(dirname(fileURLToPath(import.meta.url)), "../../locales");
+    const cli = createCli("vutex")
+        .locales(localesRoot, { envKeys: ["VUTEX_LOCALE", "LOCALE", "LANG", "LC_ALL"] })
+        .intro("cli.intro");
+
+    registerRenderCommand(cli);
+    registerInspectCommand(cli);
+    registerPackageCommands(cli);
+
+    return cli;
+}

package/src/cli/commands/inspect.ts

@@ -0,0 +1,33 @@
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import { createVuTeXRuntime } from "../context.js";
+import { emitJson, presentDiagnostics } from "../diagnostics.js";
+import { ExitCode } from "../exit-codes.js";
+
+export function registerInspectCommand(cli: Cli): void {
+    cli.command("inspect", "cli.cmd.inspect")
+        .option("--json", "cli.opt.json")
+        .action(async (options: ParsedOptions) => {
+            const inputPath = options._[0];
+            if (!inputPath || typeof inputPath !== "string") {
+                return ExitCode.InvalidArgs;
+            }
+
+            const runtime = await createVuTeXRuntime();
+            const result = await runtime.inspect(inputPath);
+
+            if (options.json === true) {
+                emitJson(result);
+            } else {
+                console.log(`${result.inputFormat}\t${result.path}`);
+            }
+
+            if (result.diagnostics.length > 0) {
+                presentDiagnostics(result.diagnostics, options.json === true);
+            }
+
+            return result.diagnostics.some((item) => item.severity === "error")
+                ? ExitCode.ActionFailed
+                : ExitCode.Ok;
+        });
+}

package/src/cli/commands/package.ts

@@ -0,0 +1,99 @@
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import { createVuTeXRuntime } from "../context.js";
+import { emitHuman, emitJson } from "../diagnostics.js";
+import { ExitCode } from "../exit-codes.js";
+
+function readName(options: ParsedOptions): string | undefined {
+    const value = options._[0] ?? options.name;
+    return typeof value === "string" ? value : undefined;
+}
+
+export function registerPackageCommands(cli: Cli): void {
+    const group = cli.command("package", "cli.cmd.package");
+
+    group
+        .command("list", "cli.cmd.package.list")
+        .option("--json", "cli.opt.json")
+        .action(async (options: ParsedOptions) => {
+            const runtime = await createVuTeXRuntime();
+            const items = await runtime.packages.list();
+            if (options.json === true) {
+                emitJson({ packages: items });
+            } else {
+                for (const item of items) {
+                    emitHuman(`${item.name}\t${item.version}\t${item.source}`);
+                }
+            }
+            return ExitCode.Ok;
+        });
+
+    group
+        .command("add", "cli.cmd.package.add")
+        .action(async (options: ParsedOptions) => {
+            const name = readName(options);
+            if (!name) {
+                return ExitCode.InvalidArgs;
+            }
+            const runtime = await createVuTeXRuntime();
+            await runtime.packages.add(name, {
+                version: typeof options.version === "string" ? options.version : undefined,
+            });
+            return ExitCode.Ok;
+        });
+
+    group
+        .command("remove", "cli.cmd.package.remove")
+        .action(async (options: ParsedOptions) => {
+            const name = readName(options);
+            if (!name) {
+                return ExitCode.InvalidArgs;
+            }
+            const runtime = await createVuTeXRuntime();
+            await runtime.packages.remove(name);
+            return ExitCode.Ok;
+        });
+
+    group
+        .command("install", "cli.cmd.package.install")
+        .option("--name <name>", "cli.opt.package-name")
+        .option("--version <version>", "cli.opt.package-version")
+        .action(async (options: ParsedOptions) => {
+            const runtime = await createVuTeXRuntime();
+            await runtime.packages.install({
+                name: typeof options.name === "string" ? options.name : undefined,
+                version: typeof options.version === "string" ? options.version : undefined,
+            });
+            return ExitCode.Ok;
+        });
+
+    group
+        .command("update", "cli.cmd.package.update")
+        .action(async () => {
+            const runtime = await createVuTeXRuntime();
+            await runtime.packages.update();
+            return ExitCode.Ok;
+        });
+
+    group
+        .command("doctor", "cli.cmd.package.doctor")
+        .option("--json", "cli.opt.json")
+        .action(async (options: ParsedOptions) => {
+            const runtime = await createVuTeXRuntime();
+            const report = await runtime.packages.doctor();
+            if (options.json === true) {
+                emitJson(report);
+            } else if (report.ok) {
+                emitHuman("VuTeX resource packages look healthy");
+                for (const check of report.checks) {
+                    emitHuman(`  ok  ${check.id}: ${check.message}`);
+                }
+            } else {
+                emitHuman("VuTeX resource packages have issues");
+                for (const check of report.checks) {
+                    emitHuman(`  ${check.ok ? "ok" : "fail"}  ${check.id}: ${check.message}`);
+                }
+            }
+            return report.ok ? ExitCode.Ok : ExitCode.ActionFailed;
+        });
+}

package/src/cli/commands/render.ts

@@ -0,0 +1,38 @@
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import { createVuTeXRuntime } from "../context.js";
+import { emitJson, presentDiagnostics } from "../diagnostics.js";
+import { ExitCode } from "../exit-codes.js";
+
+export function registerRenderCommand(cli: Cli): void {
+    cli.command("render", "cli.cmd.render")
+        .option("-o, --output <file>", "cli.opt.output")
+        .option("--profile <name>", "cli.opt.profile")
+        .option("--input <format>", "cli.opt.input-format")
+        .option("--json", "cli.opt.json")
+        .action(async (options: ParsedOptions) => {
+            const inputPath = options._[0];
+            if (!inputPath || typeof inputPath !== "string") {
+                return ExitCode.InvalidArgs;
+            }
+
+            const runtime = await createVuTeXRuntime();
+            const result = await runtime.render(inputPath, {
+                output: typeof options.output === "string" ? options.output : undefined,
+                profile: typeof options.profile === "string" ? options.profile : undefined,
+                input: typeof options.input === "string" ? options.input : undefined,
+            });
+
+            if (options.json === true) {
+                emitJson(result);
+            } else if (result.svg) {
+                console.log(result.svg);
+            }
+
+            if (result.diagnostics.length > 0) {
+                presentDiagnostics(result.diagnostics, options.json === true);
+            }
+
+            return result.exitCode === 0 ? ExitCode.Ok : ExitCode.ActionFailed;
+        });
+}

package/src/cli/context.ts

@@ -0,0 +1,27 @@
+import { createVuTeX, type VuTeXRuntime } from "../index.js";
+import { loadVuTeXNode } from "../node/load.js";
+
+export type CliContext = {
+    runtime: VuTeXRuntime | null;
+    toolVersion: string;
+};
+
+export async function createVuTeXRuntime(projectRoot?: string): Promise<VuTeXRuntime> {
+    return createVuTeX({ projectRoot: projectRoot ?? process.cwd(), host: "node", backend: "native" });
+}
+
+export function loadBindings(): ReturnType<typeof loadVuTeXNode> | null {
+    try {
+        return loadVuTeXNode();
+    } catch {
+        return null;
+    }
+}
+
+export async function createContext(projectRoot?: string): Promise<CliContext> {
+    const bindings = loadBindings();
+    return {
+        runtime: bindings ? await createVuTeX({ projectRoot: projectRoot ?? process.cwd() }) : null,
+        toolVersion: bindings?.vutexVersion() ?? "0.0.0",
+    };
+}

package/src/cli/diagnostics.ts

@@ -0,0 +1,23 @@
+import type { VuTeXDiagnostic } from "../types.js";
+
+export function emitHuman(message: string): void {
+    console.error(message);
+}
+
+export function emitJson(value: unknown): void {
+    console.log(JSON.stringify(value, null, 2));
+}
+
+export function presentDiagnostics(
+    diagnostics: VuTeXDiagnostic[],
+    json: boolean,
+): void {
+    if (json) {
+        emitJson({ diagnostics });
+        return;
+    }
+    for (const item of diagnostics) {
+        const stage = item.stage ? `[${item.stage}] ` : "";
+        emitHuman(`${stage}${item.severity}: ${item.code} — ${item.message}`);
+    }
+}

package/src/cli/exit-codes.ts

@@ -0,0 +1,5 @@
+export const ExitCode = {
+    Ok: 0,
+    ActionFailed: 1,
+    InvalidArgs: 2,
+} as const;

package/src/cli/main.ts

@@ -0,0 +1,5 @@
+import { buildVuTeXCli } from "./cli.js";
+
+export async function runCli(argv: string[]): Promise<number> {
+    return await buildVuTeXCli().parse(argv);
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+import { loadVuTeXNode } from "./node/load.js";
+import { createVuTeXRuntime } from "./runtime.js";
+import type { CreateVuTeXOptions, VuTeXRuntime } from "./types.js";
+
+export type {
+    CreateVuTeXOptions,
+    FormulaDiagnostic,
+    FormulaMetrics,
+    FormulaRender,
+    FormulaRenderOptions,
+    InspectDocumentResult,
+    PackageDoctorReport,
+    PackageInstallOptions,
+    PackageRecord,
+    RenderDocumentOptions,
+    RenderDocumentResult,
+    VuTeXBackend,
+    VuTeXBindings,
+    VuTeXDiagnostic,
+    VuTeXHost,
+    VuTeXRuntime,
+} from "./types.js";
+
+export { loadVuTeXNode } from "./node/index.js";
+export { createVuTeXRuntime } from "./runtime.js";
+
+/** Create a VuTeX runtime for Node hosts (native binding). */
+export async function createVuTeX(options: CreateVuTeXOptions = {}): Promise<VuTeXRuntime> {
+    const backend = options.backend ?? "auto";
+    const host = options.host ?? "node";
+    if (host !== "node" && backend !== "native") {
+        throw new Error("createVuTeX scaffold currently supports Node native hosts only");
+    }
+    const bindings = loadVuTeXNode();
+    return createVuTeXRuntime(bindings, options);
+}

package/src/node/index.ts

@@ -0,0 +1 @@
+export { loadVuTeXNode } from "./load.js";

package/src/node/load.ts

@@ -0,0 +1,50 @@
+import { createRequire } from "node:module";
+
+import type { VuTeXBindings } from "../types.js";
+
+type NativeBinding = {
+    vutexVersion: () => string;
+    measureFormula: (source: string, optionsJson?: string) => string;
+    renderFormulaSvg: (source: string, optionsJson?: string) => string;
+    renderFormulaMathml: (source: string, optionsJson?: string) => string;
+    renderFormula: (source: string, optionsJson?: string) => string;
+    inspectDocument: (inputPath: string) => {
+        inputFormat: string;
+        path: string;
+        reportJson: string;
+    };
+    renderDocument: (inputPath: string, optionsJson?: string) => {
+        exitCode: number;
+        outputFormat: string;
+        svg?: string;
+        reportJson: string;
+    };
+};
+
+const PLATFORM_PACKAGES: Record<string, string> = {
+    "win32-x64": "@vutex/vutex-win32-x64",
+    "linux-x64": "@vutex/vutex-linux-x64",
+    "linux-arm64": "@vutex/vutex-linux-arm64",
+    "darwin-x64": "@vutex/vutex-darwin-x64",
+    "darwin-arm64": "@vutex/vutex-darwin-arm64",
+};
+
+/** Load the platform-specific Node-API binary from `@vutex/vutex-<platform>`. */
+export function loadVuTeXNode(): VuTeXBindings {
+    const key = `${process.platform}-${process.arch}`;
+    const pkg = PLATFORM_PACKAGES[key];
+    if (!pkg) {
+        throw new Error(`Unsupported platform for VuTeX native bindings: ${key}`);
+    }
+    const require = createRequire(import.meta.url);
+    const binding = require(pkg).default as NativeBinding;
+    return {
+        vutexVersion: () => binding.vutexVersion(),
+        measureFormula: (source, optionsJson) => binding.measureFormula(source, optionsJson),
+        renderFormulaSvg: (source, optionsJson) => binding.renderFormulaSvg(source, optionsJson),
+        renderFormulaMathml: (source, optionsJson) => binding.renderFormulaMathml(source, optionsJson),
+        renderFormula: (source, optionsJson) => binding.renderFormula(source, optionsJson),
+        inspectDocument: (inputPath) => binding.inspectDocument(inputPath),
+        renderDocument: (inputPath, optionsJson) => binding.renderDocument(inputPath, optionsJson),
+    };
+}

package/src/packages/lockfile.ts

@@ -0,0 +1,35 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import TOML from "@iarna/toml";
+
+export type LockedPackage = {
+    name: string;
+    version: string;
+    source: string;
+    contentHash: string;
+    dependencies: string[];
+};
+
+export type VuTeXLockfile = {
+    version: number;
+    packages: LockedPackage[];
+};
+
+export async function readLockfile(projectRoot: string): Promise<VuTeXLockfile | null> {
+    const path = join(projectRoot, "vutex.lock");
+    try {
+        const raw = await readFile(path, "utf8");
+        return TOML.parse(raw) as VuTeXLockfile;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+
+export async function writeLockfile(projectRoot: string, lockfile: VuTeXLockfile): Promise<void> {
+    const path = join(projectRoot, "vutex.lock");
+    await writeFile(path, `${TOML.stringify(lockfile)}\n`, "utf8");
+}

package/src/packages/manager.ts

@@ -0,0 +1,119 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import TOML from "@iarna/toml";
+
+import type { PackageDoctorReport, PackageInstallOptions, PackageRecord } from "../types.js";
+import { readLockfile, writeLockfile, type LockedPackage } from "./lockfile.js";
+import { readManifest } from "./manifest.js";
+
+function hashPlaceholder(name: string, version: string): string {
+    return `sha256:scaffold:${name}@${version}`;
+}
+
+export class PackageManager {
+    constructor(private readonly projectRoot: string) {}
+
+    async list(): Promise<PackageRecord[]> {
+        const lock = await readLockfile(this.projectRoot);
+        if (!lock) {
+            const manifest = await readManifest(this.projectRoot);
+            if (!manifest?.packages) {
+                return [];
+            }
+            return Object.entries(manifest.packages).map(([alias, version]) => ({
+                name: alias,
+                version,
+                source: "manifest",
+            }));
+        }
+        return lock.packages.map((item) => ({
+            name: item.name,
+            version: item.version,
+            source: item.source,
+        }));
+    }
+
+    async add(name: string, options: PackageInstallOptions = {}): Promise<void> {
+        const manifest = (await readManifest(this.projectRoot)) ?? {};
+        const packages = { ...(manifest.packages ?? {}) };
+        const alias = name.includes("/") ? name.split("/").pop() ?? name : name;
+        packages[alias] = options.version ?? "latest";
+        const next = {
+            ...manifest,
+            packages,
+        };
+        await writeFile(join(this.projectRoot, "vutex.toml"), `${TOML.stringify(next)}\n`, "utf8");
+    }
+
+    async remove(name: string): Promise<void> {
+        const manifest = await readManifest(this.projectRoot);
+        if (!manifest?.packages) {
+            return;
+        }
+        const packages = { ...manifest.packages };
+        delete packages[name];
+        const next = { ...manifest, packages };
+        await writeFile(join(this.projectRoot, "vutex.toml"), `${TOML.stringify(next)}\n`, "utf8");
+    }
+
+    async install(options: PackageInstallOptions = {}): Promise<void> {
+        const manifest = await readManifest(this.projectRoot);
+        const cacheDir = join(this.projectRoot, ".vutex", "packages");
+        await mkdir(cacheDir, { recursive: true });
+
+        const entries: LockedPackage[] = [];
+        const sourcePackages = manifest?.packages ?? {};
+        if (options.name) {
+            sourcePackages[options.name] = options.version ?? "latest";
+        }
+
+        for (const [alias, version] of Object.entries(sourcePackages)) {
+            entries.push({
+                name: alias,
+                version,
+                source: `@vutex/${alias}`,
+                contentHash: hashPlaceholder(alias, version),
+                dependencies: [],
+            });
+        }
+
+        await writeLockfile(this.projectRoot, {
+            version: 1,
+            packages: entries,
+        });
+    }
+
+    async update(): Promise<void> {
+        await this.install();
+    }
+
+    async doctor(): Promise<PackageDoctorReport> {
+        const checks: PackageDoctorReport["checks"] = [];
+        const manifest = await readManifest(this.projectRoot);
+        const lock = await readLockfile(this.projectRoot);
+
+        checks.push({
+            id: "manifest",
+            ok: manifest !== null,
+            message: manifest ? "vutex.toml present" : "vutex.toml missing (optional for scaffold)",
+        });
+
+        if (manifest?.packages && Object.keys(manifest.packages).length > 0) {
+            checks.push({
+                id: "lockfile",
+                ok: lock !== null && lock.packages.length > 0,
+                message: lock ? `vutex.lock tracks ${lock.packages.length} package(s)` : "vutex.lock missing",
+            });
+        } else {
+            checks.push({
+                id: "lockfile",
+                ok: true,
+                message: "no resource packages declared",
+            });
+        }
+
+        const ok = checks.every((check) => check.ok);
+        return { ok, checks };
+    }
+}

package/src/packages/manifest.ts

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import TOML from "@iarna/toml";
+
+export type VuTeXManifest = {
+    document?: {
+        input?: string;
+        output?: string;
+    };
+    profile?: {
+        name?: string;
+    };
+    packages?: Record<string, string>;
+};
+
+export async function readManifest(projectRoot: string): Promise<VuTeXManifest | null> {
+    const path = join(projectRoot, "vutex.toml");
+    try {
+        const raw = await readFile(path, "utf8");
+        return TOML.parse(raw) as VuTeXManifest;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}

package/src/runtime.ts

@@ -0,0 +1,87 @@
+import type {
+    CreateVuTeXOptions,
+    FormulaRender,
+    FormulaRenderOptions,
+    InspectDocumentOptions,
+    InspectDocumentResult,
+    RenderDocumentOptions,
+    RenderDocumentResult,
+    VuTeXBindings,
+    VuTeXDiagnostic,
+    VuTeXRuntime,
+} from "./types.js";
+import { PackageManager } from "./packages/manager.js";
+import { readManifest } from "./packages/manifest.js";
+
+function encodeFormulaOptions(options?: FormulaRenderOptions): string | undefined {
+    if (!options) {
+        return undefined;
+    }
+    return JSON.stringify({ displayMode: options.displayMode ?? "inline" });
+}
+
+function decodeFormulaRender(raw: string): FormulaRender {
+    return JSON.parse(raw) as FormulaRender;
+}
+
+function diagnosticsFromReport(reportJson: string): VuTeXDiagnostic[] {
+    try {
+        const report = JSON.parse(reportJson) as {
+            diagnostics?: VuTeXDiagnostic[];
+        };
+        return report.diagnostics ?? [];
+    } catch {
+        return [];
+    }
+}
+
+export function createVuTeXRuntime(
+    bindings: VuTeXBindings,
+    options: CreateVuTeXOptions = {},
+): VuTeXRuntime {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const packages = new PackageManager(projectRoot);
+
+    return {
+        version: () => bindings.vutexVersion(),
+        async render(inputPath, renderOptions = {}): Promise<RenderDocumentResult> {
+            const manifest = await readManifest(projectRoot);
+            const payload = JSON.stringify({
+                output: renderOptions.output ?? manifest?.document?.output ?? "svg",
+                profile: renderOptions.profile ?? manifest?.profile?.name,
+                input: renderOptions.input ?? manifest?.document?.input,
+            });
+            const response = bindings.renderDocument(inputPath, payload);
+            return {
+                exitCode: response.exitCode,
+                outputFormat: response.outputFormat,
+                svg: response.svg,
+                reportJson: response.reportJson,
+                diagnostics: diagnosticsFromReport(response.reportJson),
+            };
+        },
+        async inspect(inputPath, _options: InspectDocumentOptions = {}): Promise<InspectDocumentResult> {
+            const response = bindings.inspectDocument(inputPath);
+            return {
+                inputFormat: response.inputFormat,
+                path: response.path,
+                reportJson: response.reportJson,
+                diagnostics: diagnosticsFromReport(response.reportJson),
+            };
+        },
+        measureFormula(source, options) {
+            return decodeFormulaRender(bindings.measureFormula(source, encodeFormulaOptions(options)));
+        },
+        renderFormula(source, options) {
+            return decodeFormulaRender(bindings.renderFormula(source, encodeFormulaOptions(options)));
+        },
+        packages: {
+            list: () => packages.list(),
+            add: (name, opts) => packages.add(name, opts),
+            remove: (name) => packages.remove(name),
+            install: (opts) => packages.install(opts),
+            update: () => packages.update(),
+            doctor: () => packages.doctor(),
+        },
+    };
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+export type VuTeXHost = "node" | "browser" | "wasm";
+
+export type VuTeXBackend = "auto" | "native" | "wasm";
+
+export type CreateVuTeXOptions = {
+    projectRoot?: string;
+    host?: VuTeXHost;
+    backend?: VuTeXBackend;
+};
+
+export type RenderDocumentOptions = {
+    output?: string;
+    profile?: string;
+    input?: string;
+};
+
+export type InspectDocumentOptions = {
+    input?: string;
+};
+
+export type FormulaRenderOptions = {
+    displayMode?: "inline" | "block";
+};
+
+export type FormulaDiagnostic = {
+    code: string;
+    severity: "info" | "warning" | "error";
+    message: string;
+    start?: number;
+    end?: number;
+};
+
+export type FormulaMetrics = {
+    width: number;
+    height: number;
+    depth: number;
+    baseline: number;
+};
+
+export type FormulaRender = {
+    metrics: FormulaMetrics;
+    svg: string;
+    mathml?: string;
+    diagnostics: FormulaDiagnostic[];
+};
+
+export type VuTeXDiagnostic = {
+    code: string;
+    severity: "info" | "warning" | "error";
+    message: string;
+    stage?: string;
+    path?: string;
+    args?: Record<string, unknown>;
+    cause?: string;
+};
+
+export type RenderDocumentResult = {
+    exitCode: number;
+    outputFormat: string;
+    svg?: string;
+    reportJson: string;
+    diagnostics: VuTeXDiagnostic[];
+};
+
+export type InspectDocumentResult = {
+    inputFormat: string;
+    path: string;
+    reportJson: string;
+    diagnostics: VuTeXDiagnostic[];
+};
+
+export type PackageInstallOptions = {
+    name?: string;
+    version?: string;
+};
+
+export type PackageRecord = {
+    name: string;
+    version: string;
+    source: string;
+};
+
+export type PackageDoctorReport = {
+    ok: boolean;
+    checks: Array<{ id: string; ok: boolean; message: string }>;
+};
+
+export type VuTeXBindings = {
+    vutexVersion: () => string;
+    measureFormula: (source: string, optionsJson?: string) => string;
+    renderFormulaSvg: (source: string, optionsJson?: string) => string;
+    renderFormulaMathml: (source: string, optionsJson?: string) => string;
+    renderFormula: (source: string, optionsJson?: string) => string;
+    inspectDocument: (inputPath: string) => {
+        inputFormat: string;
+        path: string;
+        reportJson: string;
+    };
+    renderDocument: (inputPath: string, optionsJson?: string) => {
+        exitCode: number;
+        outputFormat: string;
+        svg?: string;
+        reportJson: string;
+    };
+};
+
+export type VuTeXRuntime = {
+    version: () => string;
+    render: (inputPath: string, options?: RenderDocumentOptions) => Promise<RenderDocumentResult>;
+    inspect: (inputPath: string, options?: InspectDocumentOptions) => Promise<InspectDocumentResult>;
+    measureFormula: (source: string, options?: FormulaRenderOptions) => FormulaRender;
+    renderFormula: (source: string, options?: FormulaRenderOptions) => FormulaRender;
+    packages: {
+        list: () => Promise<PackageRecord[]>;
+        add: (name: string, options?: PackageInstallOptions) => Promise<void>;
+        remove: (name: string) => Promise<void>;
+        install: (options?: PackageInstallOptions) => Promise<void>;
+        update: () => Promise<void>;
+        doctor: () => Promise<PackageDoctorReport>;
+    };
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.