@moldesk/core 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -12,5 +12,9 @@ export type { InstalledModel, InstalledPostInstallResult } from "./install-state
 export { createInstallationPlan, installModel, INSTALL_CONFIRMATION_DISK_BYTES, INSTALL_CONFIRMATION_DOWNLOAD_BYTES, requiresInstallConfirmation, runtimeFingerprint, uninstallModel, } from "./installation.js";
 export type { InstallationPlanResult, InstallCostEstimate, InstallModelOptions, InstallModelResult, UninstallModelOptions, } from "./installation.js";
 export { runModel } from "./run.js";
-export type { RunModelOptions, RunModelResult, RunRecord } from "./run.js";
+export type { RunArtifact, RunModelOptions, RunModelResult, RunRecord, RunWarning } from "./run.js";
+export { openInBrowser } from "@moldesk/runtime";
+export type { OpenResult } from "@moldesk/runtime";
+export { applyReportUpdate, asMoldeskError, createStandaloneReport, prepareReportUpdate } from "./visualization.js";
+export type { ReportUpdateOptions, StandaloneReportOptions, StandaloneReportResult, UpdatePlan, UpdateResult, } from "./visualization.js";
 export { VERSION } from "./version.js";

package/dist/index.js

@@ -6,4 +6,6 @@ export { evaluateCompatibility, shortReason } from "./compatibility.js";
 export { listInstalledModels, } from "./install-state.js";
 export { createInstallationPlan, installModel, INSTALL_CONFIRMATION_DISK_BYTES, INSTALL_CONFIRMATION_DOWNLOAD_BYTES, requiresInstallConfirmation, runtimeFingerprint, uninstallModel, } from "./installation.js";
 export { runModel } from "./run.js";
+export { openInBrowser } from "@moldesk/runtime";
+export { applyReportUpdate, asMoldeskError, createStandaloneReport, prepareReportUpdate } from "./visualization.js";
 export { VERSION } from "./version.js";

package/dist/run-report.d.ts

@@ -0,0 +1,47 @@
+import type { ModelAdapterDefinition, RunContext } from "@moldesk/adapters";
+import { type ViewerBundle } from "@moldesk/visualizer";
+export interface RunArtifact {
+    id: string;
+    kind: "molecular-report";
+    path: string;
+    sha256: string;
+    sizeBytes: number;
+    sourceSha256: string[];
+    viewerVersion: string;
+    bundleSha256: string;
+}
+export interface RunWarning {
+    code: string;
+    message: string;
+}
+export interface RunReportInput {
+    adapter: ModelAdapterDefinition;
+    context: RunContext;
+    runDirPath: string;
+    record: {
+        id: string;
+        model: string;
+        modelVersion: string;
+        input: Array<{
+            storedPath: string;
+            sha256: string;
+        }>;
+        outputs: Array<{
+            id: string;
+            path: string;
+            sha256: string;
+        }>;
+    };
+    signal?: AbortSignal;
+    /** Test seam; defaults to the installed viewer bundle. */
+    bundle?: ViewerBundle;
+}
+/**
+ * Builds `artifacts/viewer.html` for a successful run. Never throws: any failure becomes a
+ * warning so a successful scientific run stays successful. Cancellation yields a warning
+ * and no file. Writes nothing until the report is fully built and verified.
+ */
+export declare function generateRunReport(input: RunReportInput): Promise<{
+    artifact?: RunArtifact;
+    warning?: RunWarning;
+}>;

package/dist/run-report.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isWithinRoot } from "@moldesk/runtime";
+import { exportReport, REPORT_LIMITS, validateDescription, writeFileExclusive, } from "@moldesk/visualizer";
+import { MoldeskError } from "./errors.js";
+class Cancelled extends Error {
+}
+function refuse(code, message) {
+    return new MoldeskError({ code, message, remediation: "The model results are unaffected; re-run with --no-visualize to skip the report." });
+}
+function checkAbort(signal) {
+    if (signal?.aborted)
+        throw new Cancelled();
+}
+/**
+ * Resolves one adapter-declared source. Only exact paths the run already recorded (and
+ * checksummed) are allowed; the file is re-checked as a regular, non-symlink file inside
+ * the run directory at the moment of reading, and its bytes must still match the recorded
+ * checksum. The adapter never gets to request an arbitrary read.
+ */
+function readSource(kind, sourcePath, known, root) {
+    const expected = known.get(sourcePath);
+    if (expected === undefined) {
+        throw refuse("VISUALIZATION_SOURCE_NOT_ALLOWED", `The report referenced a ${kind} file that this run did not record: ${path.basename(sourcePath)}`);
+    }
+    const stat = fs.lstatSync(sourcePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw refuse("VISUALIZATION_SOURCE_NOT_ALLOWED", `${path.basename(sourcePath)} is not a regular file.`);
+    }
+    if (!isWithinRoot(root, fs.realpathSync(sourcePath))) {
+        throw refuse("VISUALIZATION_SOURCE_NOT_ALLOWED", `${path.basename(sourcePath)} resolves outside the run directory.`);
+    }
+    if (stat.size > REPORT_LIMITS.maxResourceBytes) {
+        throw refuse("VISUALIZATION_SOURCE_TOO_LARGE", `${path.basename(sourcePath)} is too large to embed (${stat.size} bytes).`);
+    }
+    const bytes = fs.readFileSync(sourcePath);
+    if (createHash("sha256").update(bytes).digest("hex") !== expected) {
+        throw refuse("VISUALIZATION_SOURCE_CHANGED", `${path.basename(sourcePath)} changed after it was checksummed.`);
+    }
+    return bytes;
+}
+/**
+ * Builds `artifacts/viewer.html` for a successful run. Never throws: any failure becomes a
+ * warning so a successful scientific run stays successful. Cancellation yields a warning
+ * and no file. Writes nothing until the report is fully built and verified.
+ */
+export async function generateRunReport(input) {
+    try {
+        checkAbort(input.signal);
+        const outputs = input.record.outputs.map(({ id, path: p }) => ({ id, path: p }));
+        const description = await input.adapter.describeVisualization?.(input.context, outputs);
+        if (!description)
+            return {};
+        checkAbort(input.signal);
+        const valid = validateDescription(description);
+        const knownOutputs = new Map(input.record.outputs.map((o) => [o.path, o.sha256]));
+        const knownInputs = new Map(input.record.input.map((i) => [i.storedPath, i.sha256]));
+        const roots = {
+            output: fs.realpathSync(path.join(input.runDirPath, "output")),
+            input: fs.realpathSync(path.join(input.runDirPath, "input")),
+        };
+        const resources = [];
+        for (const r of valid.resources) {
+            const bytes = readSource(r.source.kind, r.source.path, r.source.kind === "output" ? knownOutputs : knownInputs, roots[r.source.kind]);
+            resources.push({ id: r.id, label: r.label, format: r.format, bytes });
+            checkAbort(input.signal);
+        }
+        const exported = exportReport({
+            title: valid.title,
+            resources,
+            scenes: valid.scenes,
+            panels: valid.panels,
+            provenance: { runId: input.record.id, model: input.record.model, modelVersion: input.record.modelVersion },
+        }, input.bundle);
+        checkAbort(input.signal);
+        const artifactsDir = path.join(input.runDirPath, "artifacts");
+        fs.mkdirSync(artifactsDir, { recursive: true });
+        const dest = path.join(artifactsDir, "viewer.html");
+        await writeFileExclusive(dest, exported.html);
+        return {
+            artifact: {
+                id: "molecular-report",
+                kind: "molecular-report",
+                path: dest,
+                sha256: exported.sha256,
+                sizeBytes: exported.sizeBytes,
+                sourceSha256: exported.sourceSha256,
+                viewerVersion: exported.viewerVersion,
+                bundleSha256: exported.bundleSha256,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof Cancelled) {
+            return { warning: { code: "VISUALIZATION_CANCELLED", message: "Report generation was cancelled. The model results are unaffected." } };
+        }
+        const code = error instanceof MoldeskError ? error.code : typeof error?.code === "string" ? error.code : "VISUALIZATION_FAILED";
+        const message = error instanceof Error ? error.message : String(error);
+        return { warning: { code, message: `Could not create the molecular report: ${message}` } };
+    }
+}

package/dist/run.d.ts

@@ -1,5 +1,6 @@
 import { type RuntimeKind } from "@moldesk/registry";
 import { type MoldeskPaths, type RuntimeProvider, type SystemReport } from "@moldesk/runtime";
+import { type RunArtifact, type RunWarning } from "./run-report.js";
 /**
  * `runModel` only rejects for usage errors discovered before a run directory
  * is allocated (unknown model, not installed, invalid input/params — spec
@@ -21,6 +22,8 @@ export interface RunModelOptions {
     onLog?: (stream: "stdout" | "stderr", chunk: string) => void;
     /** Injected for testability; defaults to a real `PythonRuntimeProvider`. */
     runtimeProvider?: RuntimeProvider;
+    /** Create the offline molecular report for a successful run when the adapter describes one. Default true. */
+    visualize?: boolean;
 }
 export interface RunRecord {
     schemaVersion: 1;
@@ -76,7 +79,12 @@ export interface RunRecord {
         code: string;
         message: string;
     };
+    /** Derived files (not scientific outputs). Updating one later does not rewrite this record. */
+    artifacts?: RunArtifact[];
+    /** Nonfatal problems, e.g. the report could not be created. They never change `status`. */
+    warnings?: RunWarning[];
 }
+export type { RunArtifact, RunWarning };
 export interface RunModelResult {
     status: "succeeded" | "failed" | "cancelled";
     record: RunRecord;

package/dist/run.js

@@ -7,6 +7,7 @@ import { getMoldeskPaths, getSystemReport, redactEnv, runDir, stageCompanionInpu
 import { MoldeskError } from "./errors.js";
 import { digest, sha256File } from "./hash.js";
 import { listInstalledModels } from "./install-state.js";
+import { generateRunReport } from "./run-report.js";
 import { VERSION } from "./version.js";
 function runFailure(code, message, remediation, details) {
     return new MoldeskError({ code, message, remediation, details });
@@ -120,19 +121,20 @@ export async function runModel(modelName, inputPath, options = {}) {
     };
     // --- Step 6: write the initial record. From this point, every path below finalizes run.json. ---
     writeRunRecord(runDirPath, record);
+    const runContext = {
+        manifestName: manifest.name,
+        inputPath: storedInputPath,
+        outputDir,
+        modelDir: installed.installDir,
+        assetsDir: path.join(installed.installDir, "assets"),
+        params: effectiveParams,
+        runtimeExecutable: installed.runtime.python.executable,
+        platform: installed.runtime.python.platform,
+        ...(companionInputs.length > 0 ? { companionInputs } : {}),
+    };
     try {
         // --- Step 7: build the structured command. ---
-        const commandSpec = await adapter.command({
-            manifestName: manifest.name,
-            inputPath: storedInputPath,
-            outputDir,
-            modelDir: installed.installDir,
-            assetsDir: path.join(installed.installDir, "assets"),
-            params: effectiveParams,
-            runtimeExecutable: installed.runtime.python.executable,
-            platform: installed.runtime.python.platform,
-            ...(companionInputs.length > 0 ? { companionInputs } : {}),
-        });
+        const commandSpec = await adapter.command(runContext);
         record.command = {
             executable: commandSpec.executable,
             args: commandSpec.args,
@@ -173,17 +175,7 @@ export async function runModel(modelName, inputPath, options = {}) {
             };
         }
         else {
-            const collected = await adapter.collectOutputs({
-                manifestName: manifest.name,
-                inputPath: storedInputPath,
-                outputDir,
-                modelDir: installed.installDir,
-                assetsDir: path.join(installed.installDir, "assets"),
-                params: effectiveParams,
-                runtimeExecutable: installed.runtime.python.executable,
-                platform: installed.runtime.python.platform,
-                ...(companionInputs.length > 0 ? { companionInputs } : {}),
-            });
+            const collected = await adapter.collectOutputs(runContext);
             // --- Step 12: checksum + size each output. ---
             record.outputs = await Promise.all(collected.map(async (output) => ({
                 id: output.id,
@@ -198,6 +190,15 @@ export async function runModel(modelName, inputPath, options = {}) {
         record.status = options.signal?.aborted ? "cancelled" : "failed";
         record.error = toErrorInfo(error, "RUN_EXECUTION_FAILED");
     }
+    // --- Derived report. Deliberately outside the try/catch above: describing or exporting a
+    // report can only ever add a warning, never change the model's outcome or error. ---
+    if (record.status === "succeeded" && options.visualize !== false) {
+        const report = await generateRunReport({ adapter, context: runContext, runDirPath, record, signal: options.signal });
+        if (report.artifact)
+            record.artifacts = [report.artifact];
+        if (report.warning)
+            record.warnings = [report.warning];
+    }
     // --- Step 13: write the final record atomically. ---
     const finishedAt = new Date().toISOString();
     record.finishedAt = finishedAt;
@@ -212,6 +213,10 @@ export async function runModel(modelName, inputPath, options = {}) {
                 const target = path.join(options.outputDir, path.basename(output.path));
                 fs.copyFileSync(output.path, target, fs.constants.COPYFILE_EXCL);
             }
+            // The report is self-contained; copy it under a name that cannot collide with outputs.
+            for (const artifact of record.artifacts ?? []) {
+                fs.copyFileSync(artifact.path, path.join(options.outputDir, `moldesk-report-${record.id}.html`), fs.constants.COPYFILE_EXCL);
+            }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/run.visualization.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/run.visualization.test.js

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { getAdapter } from "@moldesk/adapters";
+import { decodeEnvelope, extractEnvelope } from "@moldesk/visualizer";
+import { runModel } from "./run.js";
+import { fakeProvider, homes, installFixture, tempPaths, writeInputFixture, writeSequenceOutput } from "./testSupport/run-fixture.js";
+const adapter = getAdapter("proteinmpnn");
+afterEach(() => {
+    delete adapter.describeVisualization;
+    for (const home of homes.splice(0))
+        fs.rmSync(home, { recursive: true, force: true });
+});
+const ok = (request) => ({
+    exitCode: 0,
+    stdoutPath: path.join(request.cwd, "stdout.log"),
+    stderrPath: path.join(request.cwd, "stderr.log"),
+});
+/** Plumbing fixture: ProteinMPNN's real output file, described as a one-scene report. */
+const describeSequences = async (_ctx, outputs) => {
+    const seq = outputs.find((o) => o.id === "sequences");
+    return {
+        title: "Test report",
+        resources: [{ id: "r1", source: { kind: "output", path: seq.path }, format: "pdb", label: "input.fa" }],
+        scenes: [{ id: "s1", title: "S", structures: [{ id: "a", resourceId: "r1" }] }],
+        panels: [],
+    };
+};
+async function run(hook, options = {}, behavior = (r) => { writeSequenceOutput(r); return ok(r); }) {
+    const paths = tempPaths();
+    await installFixture(paths);
+    const inputPath = writeInputFixture(paths.home);
+    if (hook)
+        adapter.describeVisualization = hook;
+    return { paths, result: await runModel("proteinmpnn", inputPath, { paths, runtimeProvider: fakeProvider(behavior), ...options }) };
+}
+describe("runModel visualization", () => {
+    it("adds a verified self-contained artifact without touching scientific outputs", async () => {
+        const { result } = await run(describeSequences);
+        expect(result.status).toBe("succeeded");
+        const [artifact] = result.record.artifacts;
+        expect(artifact.path).toBe(path.join(result.record.command.cwd, "artifacts", "viewer.html"));
+        expect(artifact.kind).toBe("molecular-report");
+        expect(artifact.sourceSha256).toEqual([result.record.outputs[0].sha256]);
+        expect(result.record.outputs.map((o) => o.id)).toEqual(["sequences"]);
+        expect(result.record.warnings).toBeUndefined();
+        const html = fs.readFileSync(artifact.path, "utf8");
+        const report = decodeEnvelope(extractEnvelope(html));
+        expect(Buffer.from(report.resources[0].data, "base64").toString()).toBe(">input\nMKV\n");
+        expect(report.provenance).toMatchObject({ runId: result.record.id, model: "proteinmpnn" });
+        const onDisk = JSON.parse(fs.readFileSync(path.join(result.record.command.cwd, "run.json"), "utf8"));
+        expect(onDisk.artifacts[0].sha256).toBe(artifact.sha256);
+    });
+    it("allows staged input sources", async () => {
+        const { result } = await run(async (ctx) => ({
+            title: "t",
+            resources: [{ id: "r1", source: { kind: "input", path: ctx.inputPath }, format: "pdb", label: "in.pdb" }],
+            scenes: [{ id: "s1", title: "S", structures: [{ id: "a", resourceId: "r1" }] }],
+            panels: [],
+        }));
+        expect(result.record.artifacts).toHaveLength(1);
+    });
+    it("keeps a successful run successful when the hook throws, with a warning", async () => {
+        const { result } = await run(async () => {
+            throw new Error("boom");
+        });
+        expect(result.status).toBe("succeeded");
+        expect(result.record.error).toBeUndefined();
+        expect(result.record.artifacts).toBeUndefined();
+        expect(result.record.warnings).toEqual([{ code: "VISUALIZATION_FAILED", message: "Could not create the molecular report: boom" }]);
+        expect(fs.existsSync(path.join(result.record.command.cwd, "artifacts"))).toBe(false);
+    });
+    it("surfaces a typed MoldeskError code from the hook as the warning code", async () => {
+        const { MoldeskError } = await import("./errors.js");
+        const { result } = await run(async () => {
+            throw new MoldeskError({ code: "VISUALIZATION_RECEPTOR_MISSING", message: "no receptor", remediation: "x" });
+        });
+        expect(result.status).toBe("succeeded");
+        expect(result.record.warnings[0].code).toBe("VISUALIZATION_RECEPTOR_MISSING");
+    });
+    it("treats undefined as 'no report applies': no artifact and no warning", async () => {
+        const { result } = await run(async () => undefined);
+        expect(result.record.artifacts).toBeUndefined();
+        expect(result.record.warnings).toBeUndefined();
+    });
+    it("works for adapters without the hook", async () => {
+        const { result } = await run(undefined);
+        expect(result.status).toBe("succeeded");
+        expect(result.record.artifacts).toBeUndefined();
+        expect(result.record.warnings).toBeUndefined();
+    });
+    it("refuses sources the run did not record, writing nothing", async () => {
+        const { result } = await run(async (ctx) => ({
+            title: "t",
+            resources: [{ id: "r1", source: { kind: "output", path: path.join(path.dirname(ctx.outputDir), "run.json") }, format: "json", label: "x" }],
+            scenes: [],
+            panels: [],
+        }));
+        expect(result.status).toBe("succeeded");
+        expect(result.record.warnings[0].code).toBe("VISUALIZATION_SOURCE_NOT_ALLOWED");
+        expect(fs.existsSync(path.join(result.record.command.cwd, "artifacts"))).toBe(false);
+    });
+    it("refuses a recorded output that was replaced by a symlink", async () => {
+        const { result } = await run(async (ctx, outputs) => {
+            const seq = outputs.find((o) => o.id === "sequences");
+            const target = path.join(path.dirname(ctx.outputDir), "elsewhere.fa");
+            fs.writeFileSync(target, ">input\nMKV\n");
+            fs.rmSync(seq.path);
+            fs.symlinkSync(target, seq.path);
+            return describeSequences(ctx, outputs);
+        });
+        expect(result.record.warnings[0].code).toBe("VISUALIZATION_SOURCE_NOT_ALLOWED");
+        expect(result.record.artifacts).toBeUndefined();
+    });
+    it("refuses a recorded output that changed after it was checksummed", async () => {
+        const { result } = await run(async (ctx, outputs) => {
+            fs.appendFileSync(outputs.find((o) => o.id === "sequences").path, ">tampered\n");
+            return describeSequences(ctx, outputs);
+        });
+        expect(result.record.warnings[0].code).toBe("VISUALIZATION_SOURCE_CHANGED");
+    });
+    it("rejects an invalid description with a warning", async () => {
+        const { result } = await run(async () => ({ title: "t", resources: [], scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "missing" }] }], panels: [] }));
+        expect(result.status).toBe("succeeded");
+        expect(result.record.warnings[0].code).toBe("INVALID_REPORT");
+    });
+    it("skips the hook entirely with visualize: false", async () => {
+        let called = false;
+        const { result } = await run(async (...args) => {
+            called = true;
+            return describeSequences(...args);
+        }, { visualize: false });
+        expect(called).toBe(false);
+        expect(result.record.artifacts).toBeUndefined();
+    });
+    it.each([
+        ["failed", () => ({ exitCode: 1 })],
+        ["cancelled", () => ({ exitCode: 0, cancelled: true })],
+    ])("never describes a %s run", async (status, outcome) => {
+        let called = false;
+        const { result } = await run(async () => {
+            called = true;
+            return undefined;
+        }, {}, (r) => ({ ...ok(r), ...outcome() }));
+        expect(result.status).toBe(status);
+        expect(called).toBe(false);
+    });
+    it("cancellation during report generation keeps the model outcome and writes nothing", async () => {
+        const controller = new AbortController();
+        const { result } = await run(async (...args) => {
+            const d = await describeSequences(...args);
+            controller.abort();
+            return d;
+        }, { signal: controller.signal });
+        expect(result.status).toBe("succeeded");
+        expect(result.record.warnings[0].code).toBe("VISUALIZATION_CANCELLED");
+        expect(fs.existsSync(path.join(result.record.command.cwd, "artifacts"))).toBe(false);
+    });
+    it("copies the report to --output under a collision-resistant name, never overwriting", async () => {
+        const paths = tempPaths();
+        await installFixture(paths);
+        adapter.describeVisualization = describeSequences;
+        const outputDir = path.join(paths.home, "results");
+        const exec = (inputName) => runModel("proteinmpnn", writeInputFixture(paths.home, inputName), {
+            paths,
+            outputDir,
+            runtimeProvider: fakeProvider((r) => {
+                writeSequenceOutput(r);
+                return ok(r);
+            }),
+        });
+        const first = await exec("a.pdb");
+        expect(first.exportError).toBeUndefined();
+        const copied = path.join(outputDir, `moldesk-report-${first.record.id}.html`);
+        expect(fs.readFileSync(copied).equals(fs.readFileSync(first.record.artifacts[0].path))).toBe(true);
+        expect(fs.existsSync(path.join(outputDir, "input.fa"))).toBe(true);
+        const second = await exec("b.pdb");
+        expect(second.status).toBe("succeeded");
+        expect(second.exportError?.code).toBe("OUTPUT_COLLISION");
+    });
+});

package/dist/testSupport/run-fixture.d.ts

@@ -0,0 +1,10 @@
+import { getMoldeskPaths, type InstallCommandRunner, type ExecuteRequest, type ExecutionResult, type RuntimeProvider } from "@moldesk/runtime";
+export declare const homes: string[];
+export declare function tempPaths(): import("@moldesk/runtime").MoldeskPaths;
+export declare function successfulInstallRunner(revision: string): InstallCommandRunner;
+/** Installs a real ProteinMPNN fixture (fake install commands, no network) so `runModel` has a genuine `InstalledModel` to resolve. */
+export declare function installFixture(paths: ReturnType<typeof getMoldeskPaths>): Promise<string>;
+/** A fake RuntimeProvider whose `execute()` is fully scripted by the test. */
+export declare function fakeProvider(behavior: (request: ExecuteRequest) => ExecutionResult | Promise<ExecutionResult>): RuntimeProvider;
+export declare function writeSequenceOutput(request: ExecuteRequest): void;
+export declare function writeInputFixture(dir: string, name?: string): string;

package/dist/testSupport/run-fixture.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getMoldeskPaths } from "@moldesk/runtime";
+import { listAvailableModels } from "@moldesk/registry";
+import { createInstallationPlan, installModel } from "../installation.js";
+export const homes = [];
+export function tempPaths() {
+    // Intentionally includes a space to exercise the "paths containing spaces" requirement.
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk core run "));
+    homes.push(home);
+    return getMoldeskPaths({ MOLDESK_HOME: home });
+}
+export function successfulInstallRunner(revision) {
+    return async (command, args) => {
+        if (command === "git" && args[0] === "init") {
+            const source = args[1];
+            fs.mkdirSync(path.join(source, "vanilla_model_weights"), { recursive: true });
+            fs.mkdirSync(path.join(path.dirname(source), "assets", "vanilla_model_weights"), { recursive: true });
+            fs.writeFileSync(path.join(source, "protein_mpnn_run.py"), "# pinned source\n");
+            fs.writeFileSync(path.join(source, "vanilla_model_weights", "v_48_020.pt"), "weights");
+            fs.writeFileSync(path.join(path.dirname(source), "assets", "vanilla_model_weights", "v_48_020.pt"), "weights");
+        }
+        if (command === "git" && args.includes("rev-parse"))
+            return { code: 0, stdout: `${revision}\n`, stderr: "" };
+        if (command === "uv" && args[0] === "venv")
+            fs.mkdirSync(path.join(args.at(-1), "bin"), { recursive: true });
+        if (command === "uv" && args.includes("freeze"))
+            return { code: 0, stdout: "numpy==1.26.4\ntorch==2.2.1\n", stderr: "" };
+        if (args[0] === "--version")
+            return { code: 0, stdout: "Python 3.11.9\n", stderr: "" };
+        return { code: 0, stdout: "", stderr: "" };
+    };
+}
+/** Installs a real ProteinMPNN fixture (fake install commands, no network) so `runModel` has a genuine `InstalledModel` to resolve. */
+export async function installFixture(paths) {
+    const manifest = { ...listAvailableModels().find((item) => item.name === "proteinmpnn"), assets: [] };
+    const runtime = manifest.runtimes.find((item) => item.kind === "python");
+    const planned = await createInstallationPlan(manifest, runtime, paths);
+    await installModel(planned, { paths, runner: successfulInstallRunner(manifest.source.revision), uvExecutable: "uv" });
+    return planned.targetDir;
+}
+/** A fake RuntimeProvider whose `execute()` is fully scripted by the test. */
+export function fakeProvider(behavior) {
+    return {
+        kind: "python",
+        async inspect() {
+            return { kind: "python", available: true };
+        },
+        async prepare(request) {
+            return { kind: "python", executable: request.targetDir, fingerprint: request.runtimeFingerprint };
+        },
+        async execute(request) {
+            request.onSpawn?.(4242);
+            return behavior(request);
+        },
+        async remove() { },
+    };
+}
+export function writeSequenceOutput(request) {
+    const seqsDir = path.join(request.cwd, "output", "seqs");
+    fs.mkdirSync(seqsDir, { recursive: true });
+    fs.writeFileSync(path.join(seqsDir, "input.fa"), ">input\nMKV\n");
+}
+export function writeInputFixture(dir, name = "input.pdb") {
+    fs.mkdirSync(dir, { recursive: true });
+    const inputPath = path.join(dir, name);
+    fs.writeFileSync(inputPath, "ATOM      1  N   MET A   1\n");
+    return inputPath;
+}

package/dist/visualization.d.ts

@@ -0,0 +1,41 @@
+import { type MolecularFormat, type UpdatePlan, type UpdateResult, type ViewerBundle } from "@moldesk/visualizer";
+import { MoldeskError } from "./errors.js";
+export interface StandaloneReportOptions {
+    /** Explicit report file. Must not already exist. Default: an owned path under the cache. */
+    outputPath?: string;
+    signal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
+    /** Test seam; defaults to the installed viewer bundle. */
+    bundle?: ViewerBundle;
+}
+export interface StandaloneReportResult {
+    id: string;
+    path: string;
+    fileUrl: string;
+    sha256: string;
+    sizeBytes: number;
+    format: MolecularFormat;
+    sourceSha256: string[];
+    viewerVersion: string;
+    bundleSha256: string;
+}
+/** Direct `moldesk view <file>`: one scene from one local PDB/mmCIF file. */
+export declare function createStandaloneReport(inputPath: string, options?: StandaloneReportOptions): Promise<StandaloneReportResult>;
+export type { UpdatePlan, UpdateResult };
+export interface ReportUpdateOptions {
+    /** Write the updated report here instead of replacing the original. Must not exist. */
+    outputPath?: string;
+    /** Test seam; defaults to the installed viewer bundle. */
+    bundle?: ViewerBundle;
+    now?: () => Date;
+}
+/**
+ * Inspects an existing report as data (never executing it) and decides whether the
+ * installed viewer would replace it. Nothing is written. The plan carries what is
+ * needed to detect a concurrent change between confirmation and commit.
+ */
+export declare function prepareReportUpdate(reportPath: string, options?: ReportUpdateOptions): Promise<UpdatePlan>;
+/** Commits a plan: backup + atomic replace in place, or an exclusive write to --output. */
+export declare function applyReportUpdate(plan: UpdatePlan): Promise<UpdateResult>;
+/** Maps typed visualizer errors onto MoldeskError so the CLI can pick exit codes by code. */
+export declare function asMoldeskError(error: unknown): MoldeskError;

package/dist/visualization.js

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { visualizationDir } from "@moldesk/runtime";
+import { applyUpdate, exportReport, planUpdate, REPORT_LIMITS, writeFileExclusive, } from "@moldesk/visualizer";
+import { MoldeskError } from "./errors.js";
+const EXTENSIONS = {
+    ".pdb": "pdb",
+    ".cif": "mmcif",
+    ".mmcif": "mmcif",
+};
+const URL_LIKE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+function invalid(message, remediation, code = "INVALID_VIEW_INPUT") {
+    return new MoldeskError({ code, message, remediation });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new MoldeskError({ code: "VIEW_CANCELLED", message: "Cancelled.", remediation: "Run the command again." });
+}
+/** Lightweight preflight only; real parsing stays in the browser's Mol*. */
+function preflight(text, format, file) {
+    if (text.includes("\0")) {
+        throw invalid(`${file} looks like a binary file, not a structure.`, "Provide a text PDB or mmCIF file.");
+    }
+    const ok = format === "pdb"
+        ? /^(ATOM  |HETATM)/m.test(text)
+        : /^data_\S*/m.test(text) && /^_atom_site\./m.test(text);
+    if (!ok) {
+        throw invalid(format === "pdb"
+            ? `${file} has no ATOM or HETATM records.`
+            : `${file} is not a macromolecular mmCIF file (no _atom_site category).`, format === "pdb"
+            ? "Provide a PDB file with coordinates."
+            : "Provide a macromolecular mmCIF. Arbitrary crystallographic CIF files are not supported.");
+    }
+}
+/** Direct `moldesk view <file>`: one scene from one local PDB/mmCIF file. */
+export async function createStandaloneReport(inputPath, options = {}) {
+    if (URL_LIKE.test(inputPath)) {
+        throw invalid("URLs are not supported.", "Download the file first and pass its local path.");
+    }
+    const file = path.resolve(inputPath);
+    const format = EXTENSIONS[path.extname(file).toLowerCase()];
+    if (!format) {
+        throw invalid(`Unsupported file type: ${path.basename(file)}`, "Use a .pdb, .cif, or .mmcif file.");
+    }
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        throw invalid(`File not found: ${file}`, "Check the path and try again.");
+    }
+    if (!stat.isFile())
+        throw invalid(`Not a regular file: ${file}`, "Pass a structure file, not a directory.");
+    if (stat.size === 0)
+        throw invalid(`File is empty: ${file}`, "Provide a non-empty structure file.");
+    if (stat.size > REPORT_LIMITS.maxResourceBytes) {
+        throw invalid(`File is too large (${stat.size} bytes; limit ${REPORT_LIMITS.maxResourceBytes}).`, "Use a smaller structure file.");
+    }
+    throwIfAborted(options.signal);
+    const bytes = fs.readFileSync(file);
+    preflight(bytes.toString("utf8"), format, path.basename(file));
+    throwIfAborted(options.signal);
+    const id = randomUUID();
+    const name = path.basename(file);
+    let exported;
+    try {
+        exported = exportReport({
+            id,
+            title: name,
+            resources: [{ id: "structure", label: name, format, bytes }],
+            scenes: [{ id: "scene-1", title: name, structures: [{ id: "structure-1", resourceId: "structure" }] }],
+            panels: [{ id: "structure-panel", kind: "structure", sceneIds: ["scene-1"] }],
+            provenance: {},
+        }, options.bundle);
+    }
+    catch (error) {
+        throw asMoldeskError(error);
+    }
+    throwIfAborted(options.signal);
+    const dest = options.outputPath !== undefined
+        ? path.resolve(options.outputPath)
+        : path.join(visualizationDir(id, options.env), "viewer.html");
+    if (options.outputPath !== undefined && fs.existsSync(dest) && fs.statSync(dest).isDirectory()) {
+        throw invalid(`--output must be a file path, not a directory: ${dest}`, "Pass a file name such as ./report.html.");
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    try {
+        await writeFileExclusive(dest, exported.html);
+    }
+    catch (error) {
+        throw asMoldeskError(error);
+    }
+    return {
+        id,
+        path: dest,
+        fileUrl: pathToFileURL(dest).href,
+        sha256: exported.sha256,
+        sizeBytes: exported.sizeBytes,
+        format,
+        sourceSha256: exported.sourceSha256,
+        viewerVersion: exported.viewerVersion,
+        bundleSha256: exported.bundleSha256,
+    };
+}
+/**
+ * Inspects an existing report as data (never executing it) and decides whether the
+ * installed viewer would replace it. Nothing is written. The plan carries what is
+ * needed to detect a concurrent change between confirmation and commit.
+ */
+export async function prepareReportUpdate(reportPath, options = {}) {
+    if (URL_LIKE.test(reportPath)) {
+        throw invalid("URLs are not supported.", "Pass the local path of a report file.", "INVALID_REPORT");
+    }
+    const target = path.resolve(reportPath);
+    const output = options.outputPath === undefined ? undefined : path.resolve(options.outputPath);
+    if (output !== undefined && output === target) {
+        throw invalid("--output must differ from the report being updated.", "Omit --output to update in place with a backup.", "OUTPUT_EXISTS");
+    }
+    try {
+        if (output !== undefined)
+            fs.mkdirSync(path.dirname(output), { recursive: true });
+        return await planUpdate(target, { output, bundle: options.bundle, now: options.now });
+    }
+    catch (error) {
+        throw asMoldeskError(error);
+    }
+}
+/** Commits a plan: backup + atomic replace in place, or an exclusive write to --output. */
+export async function applyReportUpdate(plan) {
+    try {
+        return await applyUpdate(plan);
+    }
+    catch (error) {
+        throw asMoldeskError(error);
+    }
+}
+const REMEDIATION = {
+    OUTPUT_EXISTS: "Choose a different --output path or remove the existing file.",
+    INVALID_REPORT: "Check that the file is a valid MoleculeDesk report.",
+    UNSUPPORTED_REPORT: "Your report has not been changed.",
+    REPORT_CONFLICT: "Run the command again.",
+    VISUALIZER_BUNDLE_INVALID: "Reinstall MoleculeDesk.",
+};
+/** Maps typed visualizer errors onto MoldeskError so the CLI can pick exit codes by code. */
+export function asMoldeskError(error) {
+    if (error instanceof MoldeskError)
+        return error;
+    const code = error?.code;
+    if (error instanceof Error && typeof code === "string" && code in REMEDIATION) {
+        return new MoldeskError({ code, message: error.message, remediation: REMEDIATION[code], cause: error });
+    }
+    return new MoldeskError({
+        code: "VISUALIZATION_FAILED",
+        message: error instanceof Error ? error.message : String(error),
+        remediation: "Try again; if this persists, report an issue.",
+        cause: error,
+    });
+}

package/dist/visualization.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/visualization.test.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { extractEnvelope, decodeEnvelope, loadBundle } from "@moldesk/visualizer";
+import { applyReportUpdate, createStandaloneReport, prepareReportUpdate } from "./visualization.js";
+const PDB = "ATOM      1  N   ALA A   1      11.104  13.207   2.100  1.00 20.00           N\nEND\n";
+const CIF = "data_x\nloop_\n_atom_site.group_PDB\n_atom_site.id\nATOM 1\n";
+let dir;
+let env;
+beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-view-"));
+    env = { ...process.env, MOLDESK_HOME: path.join(dir, "home") };
+});
+afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+const write = (name, content) => {
+    const p = path.join(dir, name);
+    fs.writeFileSync(p, content);
+    return p;
+};
+describe("createStandaloneReport", () => {
+    it("creates a report under the cache by default, preserving the original bytes", async () => {
+        const result = await createStandaloneReport(write("p.pdb", PDB), { env });
+        expect(result.path.startsWith(path.join(dir, "home", "cache", "visualizations"))).toBe(true);
+        expect(result.path.endsWith("viewer.html")).toBe(true);
+        expect(result.fileUrl).toBe(new URL(`file://${encodeURI(result.path)}`).href);
+        const report = decodeEnvelope(extractEnvelope(fs.readFileSync(result.path, "utf8")));
+        expect(Buffer.from(report.resources[0].data, "base64").toString()).toBe(PDB);
+        expect(report.scenes).toHaveLength(1);
+        expect(result.format).toBe("pdb");
+    });
+    it("accepts .cif and .mmcif as macromolecular mmCIF", async () => {
+        for (const [i, ext] of [".cif", ".mmcif", ".CIF"].entries()) {
+            const r = await createStandaloneReport(write(`s${i}${ext}`, CIF), { env, outputPath: path.join(dir, `out${i}.html`) });
+            expect(r.format).toBe("mmcif");
+        }
+    });
+    it("writes to --output, creating parents, and refuses to overwrite", async () => {
+        const out = path.join(dir, "nested", "report.html");
+        await createStandaloneReport(write("p.pdb", PDB), { env, outputPath: out });
+        expect(fs.existsSync(out)).toBe(true);
+        await expect(createStandaloneReport(write("q.pdb", PDB), { env, outputPath: out })).rejects.toMatchObject({ code: "OUTPUT_EXISTS" });
+        await expect(createStandaloneReport(write("q.pdb", PDB), { env, outputPath: dir })).rejects.toMatchObject({ code: "INVALID_VIEW_INPUT" });
+    });
+    it.each([
+        ["URL", () => "https://example.com/a.pdb"],
+        ["missing file", () => path.join(dir, "nope.pdb")],
+        ["directory", () => { fs.mkdirSync(path.join(dir, "d.pdb")); return path.join(dir, "d.pdb"); }],
+        ["unsupported extension", () => write("a.txt", PDB)],
+        ["empty file", () => write("e.pdb", "")],
+        ["binary file", () => write("b.pdb", Buffer.from([0x41, 0, 0x54, 0x4f, 0x4d]))],
+        ["PDB without atoms", () => write("n.pdb", "HEADER only\nREMARK nothing\n")],
+        ["CIF without atom_site", () => write("n.cif", "data_x\n_cell.length_a 1\n")],
+    ])("rejects %s before exporting", async (_name, make) => {
+        const input = make();
+        await expect(createStandaloneReport(input, { env })).rejects.toMatchObject({ code: "INVALID_VIEW_INPUT" });
+        expect(fs.existsSync(path.join(dir, "home", "cache", "visualizations"))).toBe(false);
+    });
+    it("is cancelled before writing when the signal is already aborted", async () => {
+        const controller = new AbortController();
+        controller.abort();
+        await expect(createStandaloneReport(write("p.pdb", PDB), { env, signal: controller.signal })).rejects.toMatchObject({ code: "VIEW_CANCELLED" });
+        expect(fs.existsSync(path.join(dir, "home"))).toBe(false);
+    });
+});
+describe("report update", () => {
+    const otherBundle = () => {
+        const real = loadBundle();
+        return { ...real, js: `${real.js}\n/* other build */`, metadata: { ...real.metadata, viewerVersion: "9.9.9", bundleSha256: "f".repeat(64) } };
+    };
+    const make = async () => (await createStandaloneReport(write("p.pdb", PDB), { env, outputPath: path.join(dir, "r.html") })).path;
+    it("is a no-op for a freshly generated report", async () => {
+        expect((await prepareReportUpdate(await make())).status).toBe("noop");
+    });
+    it("replaces in place with a backup when the installed bundle differs", async () => {
+        const file = await make();
+        const before = fs.readFileSync(file);
+        const plan = await prepareReportUpdate(file, { bundle: otherBundle() });
+        expect(plan.status).toBe("replace");
+        const result = await applyReportUpdate(plan);
+        expect(fs.readFileSync(result.backupPath).equals(before)).toBe(true);
+        expect(extractEnvelope(fs.readFileSync(file, "utf8")).viewer.version).toBe("9.9.9");
+    });
+    it("maps failures to typed MoldeskErrors without touching the file", async () => {
+        const file = await make();
+        await expect(prepareReportUpdate(file, { outputPath: file })).rejects.toMatchObject({ code: "OUTPUT_EXISTS" });
+        await expect(prepareReportUpdate("https://x.test/r.html")).rejects.toMatchObject({ code: "INVALID_REPORT" });
+        await expect(prepareReportUpdate(write("plain.html", "<html></html>"))).rejects.toMatchObject({ code: "INVALID_REPORT" });
+        const plan = await prepareReportUpdate(file, { bundle: otherBundle() });
+        fs.appendFileSync(file, "<!-- changed -->");
+        await expect(applyReportUpdate(plan)).rejects.toMatchObject({ code: "REPORT_CONFLICT" });
+        expect(fs.readFileSync(file, "utf8").endsWith("<!-- changed -->")).toBe(true);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldesk/core",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Shared engine logic for MoleculeDesk (CLI + desktop)",
   "license": "MIT",
   "type": "module",
@@ -19,9 +19,10 @@
     "dist"
   ],
   "dependencies": {
-    "@moldesk/runtime": "0.0.3",
-    "@moldesk/adapters": "0.0.3",
-    "@moldesk/registry": "0.0.3"
+    "@moldesk/adapters": "0.0.4",
+    "@moldesk/runtime": "0.0.4",
+    "@moldesk/visualizer": "0.0.4",
+    "@moldesk/registry": "0.0.4"
   },
   "devDependencies": {
     "typescript": "^5.6.3",