@moldesk/adapters 0.0.3 → 0.0.4

package/dist/bindcraft2/index.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { MoldeskError } from "@moldesk/registry";
 import { runCommand } from "@moldesk/runtime";
 import { collectGlobOutputs } from "../outputs.js";
+import { describeBindCraft2Visualization } from "./visualization.js";
 const MODALITIES = ["binder", "peptide", "cyclic_peptide", "VHH", "ARP"];
 const RESOLVED = "moldesk-campaign.json";
 const SUMMARY = "moldesk-summary.json";
@@ -329,6 +330,7 @@ export const bindcraft2Adapter = {
         fs.writeFileSync(path.join(context.outputDir, SUMMARY), `${JSON.stringify(summary, null, 2)}\n`, { flag: "wx" });
         return collectGlobOutputs(context.outputDir, OUTPUTS);
     },
+    async describeVisualization(context, outputs) { return describeBindCraft2Visualization(context.inputPath, outputs); },
     async verifyInstallation(context) {
         if (context.platform !== "linux-x64")
             return { passed: false, output: "BindCraft2 supports Linux x64/NVIDIA only." };

package/dist/bindcraft2/visualization.d.ts

@@ -0,0 +1,8 @@
+import { type ReportDescription } from "@moldesk/visualizer/contract";
+import type { CollectedOutput } from "../index.js";
+/**
+ * Accepted/ranked designs first (rank taken from the ranked table, never invented), then
+ * refolded structures, then raw trajectories. A lower tier is included only as a whole and
+ * only if every scene fits the report limit, so no tier is ever cut off partway.
+ */
+export declare function describeBindCraft2Visualization(inputPath: string, outputs: readonly CollectedOutput[]): ReportDescription | undefined;

package/dist/bindcraft2/visualization.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+import { csvRecords, parseCsv } from "@moldesk/visualizer/csv";
+import { REPORT_LIMITS } from "@moldesk/visualizer/contract";
+import { ReportBuilder } from "../visualization.js";
+function readBounded(file) {
+    if (fs.statSync(file).size > REPORT_LIMITS.maxResourceBytes) {
+        throw new MoldeskError({ code: "VISUALIZATION_SOURCE_TOO_LARGE", message: `${path.basename(file)} is too large to show.`, remediation: "Use --no-visualize." });
+    }
+    return fs.readFileSync(file, "utf8");
+}
+/**
+ * The accepted structure for a ranked design is `<design>.cif`, or `<design>_*.cif` other
+ * than `<design>_monomer.cif` — the same rule the adapter's result probe enforces. Never
+ * guessed: more than one candidate is an error.
+ */
+function structureFor(design, accepted) {
+    const exact = accepted.find((o) => path.basename(o.path) === `${design}.cif`);
+    if (exact)
+        return exact;
+    const candidates = accepted.filter((o) => {
+        const name = path.basename(o.path);
+        return name.startsWith(`${design}_`) && name.endsWith(".cif") && name !== `${design}_monomer.cif`;
+    });
+    if (candidates.length !== 1) {
+        throw new MoldeskError({
+            code: "VISUALIZATION_AMBIGUOUS_STRUCTURE",
+            message: `${candidates.length === 0 ? "No" : "More than one"} accepted structure matches design "${design}".`,
+            remediation: "Use --no-visualize.",
+        });
+    }
+    return candidates[0];
+}
+/**
+ * Accepted/ranked designs first (rank taken from the ranked table, never invented), then
+ * refolded structures, then raw trajectories. A lower tier is included only as a whole and
+ * only if every scene fits the report limit, so no tier is ever cut off partway.
+ */
+export function describeBindCraft2Visualization(inputPath, outputs) {
+    const of = (id) => outputs.filter((o) => o.id === id).sort((a, b) => a.path.localeCompare(b.path));
+    const ranked = of("ranked")[0];
+    const accepted = of("accepted_structures");
+    const refolded = of("refolded_structures");
+    const trajectories = of("trajectory_structures");
+    if (accepted.length + refolded.length + trajectories.length === 0)
+        return undefined;
+    const builder = new ReportBuilder();
+    const cif = (o) => builder.resource({ kind: "output", path: o.path }, "mmcif", path.basename(o.path));
+    const addScene = (title, o, rank) => builder.scene({
+        id: `scene-${builder.sceneCount + 1}`,
+        title,
+        ...(rank === undefined ? {} : { rank }),
+        structures: [{ id: "structure-1", resourceId: cif(o) }],
+    });
+    if (ranked) {
+        const rows = csvRecords(parseCsv(readBounded(ranked.path)));
+        const ordered = rows
+            .map((row) => ({ design: row["design"], rank: Number(row["rank"]) }))
+            .sort((a, b) => a.rank - b.rank);
+        for (const { design, rank } of ordered) {
+            if (!design || !Number.isInteger(rank) || rank < 1) {
+                throw new MoldeskError({ code: "INVALID_REPORT", message: "The ranked table has an invalid design or rank.", remediation: "Use --no-visualize." });
+            }
+            addScene(`#${rank} · ${design}`, structureFor(design, accepted), rank);
+        }
+    }
+    const room = () => REPORT_LIMITS.maxScenes - builder.sceneCount;
+    if (refolded.length <= room())
+        for (const o of refolded)
+            addScene(`Refolded · ${path.basename(o.path, ".cif")}`, o);
+    if (trajectories.length <= room()) {
+        for (const o of trajectories)
+            addScene(`Trajectory · ${path.basename(path.dirname(o.path))} / ${path.basename(o.path, ".cif")}`, o);
+    }
+    const table = (title, id) => {
+        const o = of(id)[0];
+        if (o)
+            builder.table(title, builder.resource({ kind: "output", path: o.path }, "csv", path.basename(o.path)));
+    };
+    table("Ranked designs", "ranked");
+    table("Refolded designs", "refolded");
+    table("Trajectories", "trajectories");
+    return builder.build(`BindCraft2 — ${path.basename(inputPath)}`);
+}

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

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

package/dist/bindcraft2/visualization.test.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { validateDescription } from "@moldesk/visualizer";
+import { describeBindCraft2Visualization } from "./visualization.js";
+let out;
+beforeEach(() => {
+    out = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-bc2-viz-"));
+});
+afterEach(() => fs.rmSync(out, { recursive: true, force: true }));
+const file = (rel, content = "x") => {
+    const p = path.join(out, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+    return p;
+};
+const o = (id, rel, content) => ({ id, path: file(rel, content) });
+const titles = (d) => d.scenes.map((s) => s.title);
+describe("describeBindCraft2Visualization", () => {
+    it("returns undefined when there is no eligible structure", () => {
+        expect(describeBindCraft2Visualization("/in/c.json", [o("campaign", "moldesk-campaign.json")])).toBeUndefined();
+    });
+    it("orders accepted designs by the rank in the ranked table, with quoted cells, and sets verified ranks", () => {
+        const d = describeBindCraft2Visualization("/in/c.json", [
+            o("ranked", "3_Ranked/!_Ranked.csv", 'design,rank,sequence\nd_b,2,"AAA,BBB"\nd_a,1,CCC\n'),
+            o("accepted_structures", "3_Ranked/d_b.cif"),
+            o("accepted_structures", "3_Ranked/d_a.cif"),
+            o("accepted_structures", "3_Ranked/d_a_monomer.cif"),
+        ]);
+        expect(titles(d)).toEqual(["#1 · d_a", "#2 · d_b"]);
+        expect(d.scenes.map((s) => s.rank)).toEqual([1, 2]);
+        expect(d.resources.some((r) => r.source.path.endsWith("_monomer.cif"))).toBe(false);
+        expect(d.panels.some((p) => p.kind === "table" && p.title === "Ranked designs")).toBe(true);
+        validateDescription(d);
+    });
+    it("uses the single non-monomer <design>_*.cif and refuses ambiguous matches", () => {
+        const ranked = o("ranked", "3_Ranked/!_Ranked.csv", "design,rank\nd,1\n");
+        const ok = describeBindCraft2Visualization("/in/c.json", [ranked, o("accepted_structures", "3_Ranked/d_relaxed.cif"), o("accepted_structures", "3_Ranked/d_monomer.cif")]);
+        expect(ok.resources.find((r) => r.format === "mmcif").source.path).toMatch(/d_relaxed\.cif$/);
+        expect(() => describeBindCraft2Visualization("/in/c.json", [ranked, o("accepted_structures", "3_Ranked/d_a.cif"), o("accepted_structures", "3_Ranked/d_b.cif")])).toThrow(/More than one/);
+        expect(() => describeBindCraft2Visualization("/in/c.json", [ranked, o("accepted_structures", "3_Ranked/other.cif")])).toThrow(/No accepted/);
+    });
+    it("rejects an invalid rank instead of inventing one", () => {
+        expect(() => describeBindCraft2Visualization("/in/c.json", [o("ranked", "3_Ranked/!_Ranked.csv", "design,rank\nd,first\n"), o("accepted_structures", "3_Ranked/d.cif")])).toThrow(/invalid design or rank/);
+    });
+    it("falls back to refolded then trajectories (unranked) when nothing was accepted", () => {
+        const d = describeBindCraft2Visualization("/in/c.json", [
+            o("trajectory_structures", "1_Trajectories/t1/a.cif"),
+            o("refolded_structures", "2_Refolded/r1.cif"),
+            o("trajectories", "1_Trajectories/!_Trajectories.csv", "design,trajectory\na,1\n"),
+        ]);
+        expect(titles(d)).toEqual(["Refolded · r1", "Trajectory · t1 / a"]);
+        expect(d.scenes.every((s) => s.rank === undefined)).toBe(true);
+        validateDescription(d);
+    });
+    it("includes a lower tier only whole: an oversized trajectory set is left out, ranked stays", () => {
+        const outputs = [
+            o("ranked", "3_Ranked/!_Ranked.csv", "design,rank\nd,1\n"),
+            o("accepted_structures", "3_Ranked/d.cif"),
+        ];
+        for (let i = 0; i < 300; i++)
+            outputs.push({ id: "trajectory_structures", path: path.join(out, `1_Trajectories/t${i}/x.cif`) });
+        const d = describeBindCraft2Visualization("/in/c.json", outputs);
+        expect(titles(d)).toEqual(["#1 · d"]);
+        validateDescription(d);
+    });
+});

package/dist/boltz/index.js

@@ -4,6 +4,7 @@ import { MoldeskError } from "@moldesk/registry";
 import { runCommand } from "@moldesk/runtime";
 import { parse as parseYaml, YAMLParseError } from "yaml";
 import { collectGlobOutputs } from "../outputs.js";
+import { describeBoltzVisualization } from "./visualization.js";
 /**
  * Boltz's CLI writes `<out_dir>/boltz_results_<input_stem>/predictions/<record_id>/…`
  * (verified against both pinned source revisions' `src/boltz/main.py` and
@@ -186,6 +187,9 @@ export const boltzAdapter = {
     async collectOutputs(context) {
         return collectGlobOutputs(context.outputDir, OUTPUTS);
     },
+    async describeVisualization(context, outputs) {
+        return describeBoltzVisualization(context.inputPath, outputs);
+    },
     async verifyInstallation(context) {
         const venvBin = path.join(context.modelDir, ".venv", "bin");
         const python = path.join(venvBin, "python");

package/dist/boltz/visualization.d.ts

@@ -0,0 +1,9 @@
+import type { ReportDescription } from "@moldesk/visualizer/contract";
+import type { CollectedOutput } from "../index.js";
+/**
+ * One scene per predicted structure. Boltz's `_model_<n>` is an identifier (it is not
+ * ranked by confidence), so it only orders scenes deterministically; titles are
+ * "Prediction 1…", and no `rank` is set. Confidence/affinity files are attached only by
+ * exact name next to the structure — never by position in a sorted list.
+ */
+export declare function describeBoltzVisualization(inputPath: string, outputs: readonly CollectedOutput[]): ReportDescription | undefined;

package/dist/boltz/visualization.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { ReportBuilder } from "../visualization.js";
+const STRUCTURE = /^(.+)_model_(\d+)\.cif$/;
+/**
+ * One scene per predicted structure. Boltz's `_model_<n>` is an identifier (it is not
+ * ranked by confidence), so it only orders scenes deterministically; titles are
+ * "Prediction 1…", and no `rank` is set. Confidence/affinity files are attached only by
+ * exact name next to the structure — never by position in a sorted list.
+ */
+export function describeBoltzVisualization(inputPath, outputs) {
+    const exact = (id) => new Map(outputs.filter((o) => o.id === id).map((o) => [o.path, o]));
+    const confidence = exact("confidence");
+    const affinity = exact("affinity");
+    const predictions = [];
+    for (const output of outputs) {
+        if (output.id !== "structures")
+            continue;
+        const match = STRUCTURE.exec(path.basename(output.path));
+        if (!match)
+            continue;
+        predictions.push({ path: output.path, dir: path.dirname(output.path), record: match[1], model: Number(match[2]) });
+    }
+    if (predictions.length === 0)
+        return undefined;
+    predictions.sort((a, b) => a.dir.localeCompare(b.dir) || a.model - b.model);
+    const records = new Set(predictions.map((p) => p.dir));
+    const builder = new ReportBuilder();
+    const positionInRecord = new Map();
+    const affinityDone = new Set();
+    for (const p of predictions) {
+        const k = (positionInRecord.get(p.dir) ?? 0) + 1;
+        positionInRecord.set(p.dir, k);
+        const title = records.size > 1 ? `${p.record} — Prediction ${k}` : `Prediction ${k}`;
+        const sceneId = `scene-${builder.sceneCount + 1}`;
+        builder.scene({
+            id: sceneId,
+            title,
+            structures: [
+                { id: "structure-1", resourceId: builder.resource({ kind: "output", path: p.path }, "mmcif", path.basename(p.path)) },
+            ],
+        });
+        const conf = confidence.get(path.join(p.dir, `confidence_${p.record}_model_${p.model}.json`));
+        if (conf)
+            builder.table(`Confidence — ${title}`, builder.resource({ kind: "output", path: conf.path }, "json", path.basename(conf.path)));
+        const aff = affinity.get(path.join(p.dir, `affinity_${p.record}.json`));
+        if (aff && !affinityDone.has(aff.path)) {
+            affinityDone.add(aff.path);
+            builder.table(`Affinity — ${p.record}`, builder.resource({ kind: "output", path: aff.path }, "json", path.basename(aff.path)));
+        }
+    }
+    return builder.build(`Boltz — ${path.basename(inputPath)}`);
+}

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

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

package/dist/boltz/visualization.test.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { validateDescription } from "@moldesk/visualizer";
+import { describeBoltzVisualization } from "./visualization.js";
+const out = "/run/output";
+const dir = (record) => path.join(out, "boltz_results_job", "predictions", record);
+const cif = (record, n) => ({ id: "structures", path: path.join(dir(record), `${record}_model_${n}.cif`) });
+const conf = (record, n) => ({ id: "confidence", path: path.join(dir(record), `confidence_${record}_model_${n}.json`) });
+const aff = (record) => ({ id: "affinity", path: path.join(dir(record), `affinity_${record}.json`) });
+const resource = (d, id) => d.resources.find((r) => r.id === id);
+describe("describeBoltzVisualization", () => {
+    it("returns undefined when there are no structures", () => {
+        expect(describeBoltzVisualization("/in/job.yaml", [conf("a", 0)])).toBeUndefined();
+    });
+    it("makes one scene per model, ordered by model index, without inventing ranks", () => {
+        // Collected order deliberately scrambled: association must not depend on it.
+        const d = describeBoltzVisualization("/in/job.yaml", [cif("a", 2), cif("a", 0), cif("a", 10), conf("a", 10), conf("a", 0), conf("a", 2)]);
+        expect(d.scenes.map((s) => s.title)).toEqual(["Prediction 1", "Prediction 2", "Prediction 3"]);
+        expect(d.scenes.every((s) => s.rank === undefined)).toBe(true);
+        expect(d.scenes.map((s) => resource(d, s.structures[0].resourceId).source.path)).toEqual([
+            cif("a", 0).path,
+            cif("a", 2).path,
+            cif("a", 10).path,
+        ]);
+        expect(d.title).toBe("Boltz — job.yaml");
+        validateDescription(d);
+    });
+    it("pairs each structure only with its own confidence file", () => {
+        const d = describeBoltzVisualization("/in/job.yaml", [cif("a", 0), cif("a", 1), conf("a", 1)]);
+        const tables = d.panels.filter((p) => p.kind === "table");
+        expect(tables).toHaveLength(1);
+        expect(tables[0].kind === "table" && tables[0].title).toBe("Confidence — Prediction 2");
+        const t = tables[0];
+        expect(t.kind === "table" && resource(d, t.dataset.resourceId).source.path).toBe(conf("a", 1).path);
+    });
+    it("does not attach a confidence file from a different record", () => {
+        const d = describeBoltzVisualization("/in/job.yaml", [cif("a", 0), conf("b", 0)]);
+        expect(d.panels.filter((p) => p.kind === "table")).toEqual([]);
+    });
+    it("labels records and attaches affinity once per record", () => {
+        const d = describeBoltzVisualization("/in/job.yaml", [cif("a", 0), cif("a", 1), cif("b", 0), aff("a")]);
+        expect(d.scenes.map((s) => s.title)).toEqual(["a — Prediction 1", "a — Prediction 2", "b — Prediction 1"]);
+        const titles = d.panels.filter((p) => p.kind === "table").map((p) => p.kind === "table" && p.title);
+        expect(titles).toEqual(["Affinity — a"]);
+        validateDescription(d);
+    });
+    it("ignores .cif files that are not model predictions", () => {
+        const stray = { id: "structures", path: path.join(dir("a"), "ccd.cif") };
+        expect(describeBoltzVisualization("/in/job.yaml", [stray])).toBeUndefined();
+    });
+});

package/dist/diffdock/index.js

@@ -4,6 +4,7 @@ import { MoldeskError } from "@moldesk/registry";
 import { runCommand } from "@moldesk/runtime";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { collectGlobOutputs } from "../outputs.js";
+import { describeDiffDockVisualization } from "./visualization.js";
 /**
  * DiffDock-L's `inference.py` (gcorso/DiffDock @ 85c49b60d3e0b0182a59ee43a34a6d7036981284)
  * writes, per complex, `<out_dir>/<complex_name>/rank1.sdf` (the single top pose,
@@ -418,6 +419,9 @@ export const diffdockAdapter = {
         const summaryOutputs = collectGlobOutputs(context.outputDir, OUTPUTS.filter((o) => o.id === "poses_summary"));
         return [...poseOutputs, ...summaryOutputs];
     },
+    async describeVisualization(context, outputs) {
+        return describeDiffDockVisualization(context, outputs);
+    },
     async verifyInstallation(context) {
         const python = path.join(context.modelDir, ".venv", "bin", "python");
         const sourceDir = path.join(context.modelDir, "source");

package/dist/diffdock/visualization.d.ts

@@ -0,0 +1,10 @@
+import type { ReportDescription } from "@moldesk/visualizer/contract";
+import type { CollectedOutput, RunContext } from "../index.js";
+/**
+ * Receptor + each ranked pose in one scene. DiffDock writes poses in the coordinate frame
+ * of the receptor it was given, so no transform is applied; nothing is aligned. Rank and
+ * confidence come from the adapter's own pose summary. `rank1.sdf` duplicates the top
+ * `rank1_confidence*.sdf`, so only the ranked files become scenes. A missing receptor is an
+ * error, never a ligand-only report.
+ */
+export declare function describeDiffDockVisualization(context: Pick<RunContext, "inputPath" | "companionInputs">, outputs: readonly CollectedOutput[]): ReportDescription | undefined;

package/dist/diffdock/visualization.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+import { ReportBuilder } from "../visualization.js";
+const RECEPTOR_FORMATS = { ".pdb": "pdb", ".cif": "mmcif", ".mmcif": "mmcif" };
+function missingReceptor(message) {
+    return new MoldeskError({
+        code: "VISUALIZATION_RECEPTOR_MISSING",
+        message,
+        remediation: "The docking results are unaffected. A ligand shown without its receptor would misrepresent the result, so no report was created.",
+    });
+}
+/**
+ * Receptor + each ranked pose in one scene. DiffDock writes poses in the coordinate frame
+ * of the receptor it was given, so no transform is applied; nothing is aligned. Rank and
+ * confidence come from the adapter's own pose summary. `rank1.sdf` duplicates the top
+ * `rank1_confidence*.sdf`, so only the ranked files become scenes. A missing receptor is an
+ * error, never a ligand-only report.
+ */
+export function describeDiffDockVisualization(context, outputs) {
+    const summaryOutput = outputs.find((o) => o.id === "poses_summary");
+    const poseFiles = outputs.filter((o) => o.id === "ranked_poses");
+    if (!summaryOutput || poseFiles.length === 0)
+        return undefined;
+    const receptorPath = context.companionInputs?.find((c) => c.id === "protein")?.path;
+    if (!receptorPath)
+        throw missingReceptor("The staged receptor for this docking run is not available.");
+    const receptorFormat = RECEPTOR_FORMATS[path.extname(receptorPath).toLowerCase()];
+    if (!receptorFormat)
+        throw missingReceptor(`The receptor ${path.basename(receptorPath)} is not a PDB or mmCIF file.`);
+    const summary = JSON.parse(fs.readFileSync(summaryOutput.path, "utf8"));
+    const builder = new ReportBuilder();
+    const receptor = builder.resource({ kind: "input", path: receptorPath }, receptorFormat, path.basename(receptorPath));
+    for (const pose of [...summary.poses].sort((a, b) => a.rank - b.rank)) {
+        const file = poseFiles.find((o) => path.basename(o.path) === pose.sdfFile && path.basename(path.dirname(o.path)) === summary.complexName);
+        if (!file) {
+            throw new MoldeskError({ code: "VISUALIZATION_POSE_MISSING", message: `Pose ${pose.rank} is in the summary but its file was not collected.`, remediation: "Use --no-visualize." });
+        }
+        builder.scene({
+            id: `scene-${builder.sceneCount + 1}`,
+            title: `Pose ${pose.rank} (confidence ${pose.confidence})`,
+            rank: pose.rank,
+            structures: [
+                { id: "receptor", resourceId: receptor },
+                { id: "pose", resourceId: builder.resource({ kind: "output", path: file.path }, "sdf", pose.sdfFile) },
+            ],
+            components: [
+                { id: "receptor", structureId: "receptor", selection: { kind: "all" }, role: "receptor", label: "Receptor", representation: "cartoon" },
+                { id: "pose", structureId: "pose", selection: { kind: "all" }, role: "ligand", label: "Ligand pose", representation: "sticks" },
+            ],
+        });
+    }
+    builder.table("Poses", builder.resource({ kind: "output", path: summaryOutput.path }, "json", path.basename(summaryOutput.path)), [
+        { field: "rank", label: "Rank" },
+        { field: "confidence", label: "Confidence" },
+        { field: "sdfFile", label: "File" },
+        { field: "atomCount", label: "Atoms" },
+    ], "poses");
+    return builder.build(`DiffDock — ${path.basename(context.inputPath)}`);
+}

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

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

package/dist/diffdock/visualization.test.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { validateDescription } from "@moldesk/visualizer";
+import { describeDiffDockVisualization } from "./visualization.js";
+let dir;
+beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-dd-viz-"));
+});
+afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+const out = () => path.join(dir, "run", "output");
+const pose = (name) => ({ id: "ranked_poses", path: path.join(out(), "cplx", name) });
+const top = () => ({ id: "top_pose", path: path.join(out(), "cplx", "rank1.sdf") });
+function summary(poses) {
+    fs.mkdirSync(out(), { recursive: true });
+    const p = path.join(out(), "poses_summary.json");
+    fs.writeFileSync(p, JSON.stringify({ complexName: "cplx", topPoseFile: "rank1.sdf", poses }));
+    return { id: "poses_summary", path: p };
+}
+const POSES = [
+    { rank: 2, confidence: -1.23, sdfFile: "rank2_confidence-1.23.sdf" },
+    { rank: 1, confidence: 0.85, sdfFile: "rank1_confidence0.85.sdf" },
+];
+const receptorOf = () => ({ id: "protein", path: path.join(dir, "run", "input", "protein", "receptor.pdb") });
+describe("describeDiffDockVisualization", () => {
+    const outputs = () => [top(), pose("rank2_confidence-1.23.sdf"), pose("rank1_confidence0.85.sdf"), summary(POSES)];
+    it("puts the staged receptor and each ranked pose in one scene, sharing the receptor resource", () => {
+        const d = describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs: [receptorOf()] }, outputs());
+        expect(d.scenes.map((s) => [s.title, s.rank])).toEqual([
+            ["Pose 1 (confidence 0.85)", 1],
+            ["Pose 2 (confidence -1.23)", 2],
+        ]);
+        const receptors = d.resources.filter((r) => r.source.kind === "input");
+        expect(receptors).toHaveLength(1);
+        expect(receptors[0]).toMatchObject({ format: "pdb", source: { path: receptorOf().path } });
+        for (const s of d.scenes) {
+            expect(s.structures[0].resourceId).toBe(receptors[0].id);
+            expect(s.structures).toHaveLength(2);
+            expect(s.components?.map((c) => c.role)).toEqual(["receptor", "ligand"]);
+        }
+        validateDescription(d);
+    });
+    it("does not create a second scene for the rank1.sdf duplicate of the top pose", () => {
+        const d = describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs: [receptorOf()] }, outputs());
+        expect(d.resources.some((r) => r.source.path.endsWith(`${path.sep}rank1.sdf`))).toBe(false);
+    });
+    it("shows the pose summary as a table over its poses array", () => {
+        const d = describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs: [receptorOf()] }, outputs());
+        const table = d.panels.find((p) => p.kind === "table");
+        expect(table).toMatchObject({ title: "Poses", dataset: { rowsKey: "poses" } });
+    });
+    it.each([
+        ["no staged companions", undefined],
+        ["no protein companion", [{ id: "ligand", path: "/x/ligand.sdf" }]],
+        ["a receptor that is not PDB/mmCIF", [{ id: "protein", path: "/x/receptor.mol2" }]],
+    ])("refuses to describe a docking result with %s (never ligand-only)", (_name, companionInputs) => {
+        expect(() => describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs }, outputs())).toThrowError(expect.objectContaining({ code: "VISUALIZATION_RECEPTOR_MISSING" }));
+    });
+    it("accepts an mmCIF receptor", () => {
+        const d = describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs: [{ id: "protein", path: "/x/r.cif" }] }, outputs());
+        expect(d.resources.find((r) => r.source.kind === "input").format).toBe("mmcif");
+    });
+    it("errors when a summarized pose file was not collected, and returns undefined with no poses", () => {
+        expect(() => describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs: [receptorOf()] }, [pose("rank1_confidence0.85.sdf"), summary(POSES)])).toThrowError(expect.objectContaining({ code: "VISUALIZATION_POSE_MISSING" }));
+        expect(describeDiffDockVisualization({ inputPath: "/in/job.json", companionInputs: [receptorOf()] }, [])).toBeUndefined();
+    });
+});

package/dist/index.d.ts

@@ -78,6 +78,8 @@ export interface CollectedOutput {
     id: string;
     path: string;
 }
+/** Type-only: the adapter never loads the visualizer's Node or browser code. */
+export type ReportDescription = import("@moldesk/visualizer/contract").ReportDescription;
 export interface VerificationResult {
     passed: boolean;
     output?: string;
@@ -116,6 +118,18 @@ export interface ModelAdapterDefinition {
      * `runtime` only provide generic, validated staging.
      */
     resolveCompanionInputs?(inputPath: string): Promise<import("@moldesk/runtime").CompanionInputRef[]>;
+    /**
+     * Optional hook describing what a successful run produced, for the offline molecular
+     * report. Returns references to files (exact collected output paths, or staged input
+     * paths) plus scenes/panels — never bytes, HTML, or arbitrary paths; core resolves,
+     * verifies and embeds them. `undefined` means no report applies (not a failure);
+     * throwing a `MoldeskError` surfaces as a nonfatal warning on the run. Scientific
+     * associations (which confidence file belongs to which structure, what a rank means)
+     * belong here, matched against exact collected paths — never guessed by filename
+     * extension or global sort order.
+     */
+    describeVisualization?(context: RunContext, outputs: readonly CollectedOutput[]): Promise<ReportDescription | undefined>;
 }
 export { adapterCatalog, getAdapter, hasAdapter, validateAdapterCatalog } from "./catalog.js";
+export { ReportBuilder } from "./visualization.js";
 export { validateParams, type ParamValidationResult } from "./params.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { adapterCatalog, getAdapter, hasAdapter, validateAdapterCatalog } from "./catalog.js";
+export { ReportBuilder } from "./visualization.js";
 export { validateParams } from "./params.js";

package/dist/opendde/index.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { MoldeskError } from "@moldesk/registry";
 import { runCommand } from "@moldesk/runtime";
 import { collectGlobOutputs } from "../outputs.js";
+import { describeOpenDdeVisualization } from "./visualization.js";
 /**
  * Adapter-written copy of the job with every companion reference rewritten to its
  * staged path under the run's `input/` dir. Only written when the job references
@@ -469,6 +470,9 @@ export const openddeAdapter = {
         await exportPdb(context, collected.filter((o) => o.id === "structures").map((o) => o.path));
         return collectGlobOutputs(context.outputDir, OUTPUTS);
     },
+    async describeVisualization(context, outputs) {
+        return describeOpenDdeVisualization(context.inputPath, outputs);
+    },
     async verifyInstallation(context) {
         const venvBin = path.join(context.modelDir, ".venv", "bin");
         const python = path.join(venvBin, "python");

package/dist/opendde/visualization.d.ts

@@ -0,0 +1,8 @@
+import type { ReportDescription } from "@moldesk/visualizer/contract";
+import type { CollectedOutput } from "../index.js";
+/**
+ * One scene per (job, seed, sample) mmCIF. The adapter-written `.pdb` files are the same
+ * prediction in another format, so they are never scenes. Summary confidence is matched
+ * by exact job/seed/sample file name; the per-atom `full_data` files are not shown.
+ */
+export declare function describeOpenDdeVisualization(inputPath: string, outputs: readonly CollectedOutput[]): ReportDescription | undefined;

package/dist/opendde/visualization.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { ReportBuilder } from "../visualization.js";
+const STRUCTURE = /^(.+)_sample_(\d+)\.cif$/;
+const SEED_DIR = /^seed_(\d+)$/;
+/**
+ * One scene per (job, seed, sample) mmCIF. The adapter-written `.pdb` files are the same
+ * prediction in another format, so they are never scenes. Summary confidence is matched
+ * by exact job/seed/sample file name; the per-atom `full_data` files are not shown.
+ */
+export function describeOpenDdeVisualization(inputPath, outputs) {
+    const summaries = new Map(outputs.filter((o) => o.id === "confidence").map((o) => [o.path, o]));
+    const predictions = [];
+    for (const output of outputs) {
+        if (output.id !== "structures")
+            continue;
+        const name = STRUCTURE.exec(path.basename(output.path));
+        const dir = path.dirname(output.path);
+        const seed = SEED_DIR.exec(path.basename(path.dirname(dir)));
+        if (!name || !seed)
+            continue;
+        predictions.push({
+            path: output.path,
+            dir,
+            job: name[1],
+            seed: Number(seed[1]),
+            sample: Number(name[2]),
+        });
+    }
+    if (predictions.length === 0)
+        return undefined;
+    predictions.sort((a, b) => a.job.localeCompare(b.job) || a.seed - b.seed || a.sample - b.sample);
+    const jobs = new Set(predictions.map((p) => p.job));
+    const builder = new ReportBuilder();
+    const positionInJob = new Map();
+    for (const p of predictions) {
+        const k = (positionInJob.get(p.job) ?? 0) + 1;
+        positionInJob.set(p.job, k);
+        const label = `Prediction ${k} (seed ${p.seed}, sample ${p.sample})`;
+        const title = jobs.size > 1 ? `${p.job} — ${label}` : label;
+        builder.scene({
+            id: `scene-${builder.sceneCount + 1}`,
+            title,
+            structures: [
+                { id: "structure-1", resourceId: builder.resource({ kind: "output", path: p.path }, "mmcif", path.basename(p.path)) },
+            ],
+        });
+        const summary = summaries.get(path.join(p.dir, `${p.job}_summary_confidence_sample_${p.sample}.json`));
+        if (summary) {
+            builder.table(`Confidence — ${title}`, builder.resource({ kind: "output", path: summary.path }, "json", path.basename(summary.path)));
+        }
+    }
+    return builder.build(`OpenDDE — ${path.basename(inputPath)}`);
+}

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

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

package/dist/opendde/visualization.test.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { validateDescription } from "@moldesk/visualizer";
+import { describeOpenDdeVisualization } from "./visualization.js";
+const out = "/run/output";
+const pred = (job, seed) => path.join(out, job, `seed_${seed}`, "predictions");
+const cif = (job, seed, n) => ({ id: "structures", path: path.join(pred(job, seed), `${job}_sample_${n}.cif`) });
+const pdb = (job, seed, n) => ({ id: "structures_pdb", path: path.join(pred(job, seed), `${job}_sample_${n}.pdb`) });
+const summary = (job, seed, n) => ({ id: "confidence", path: path.join(pred(job, seed), `${job}_summary_confidence_sample_${n}.json`) });
+const atoms = (job, seed, n) => ({ id: "atom_confidence", path: path.join(pred(job, seed), `${job}_full_data_sample_${n}.json`) });
+describe("describeOpenDdeVisualization", () => {
+    it("returns undefined without structures", () => {
+        expect(describeOpenDdeVisualization("/in/j.json", [summary("t", 1, 0)])).toBeUndefined();
+    });
+    it("treats the exported PDB as the same prediction, not another scene", () => {
+        const d = describeOpenDdeVisualization("/in/j.json", [cif("t", 101, 0), pdb("t", 101, 0), summary("t", 101, 0), atoms("t", 101, 0)]);
+        expect(d.scenes).toHaveLength(1);
+        expect(d.resources.filter((r) => r.format === "mmcif")).toHaveLength(1);
+        expect(d.resources.some((r) => r.source.path.endsWith(".pdb"))).toBe(false);
+        expect(d.resources.some((r) => r.source.path.includes("full_data"))).toBe(false);
+        validateDescription(d);
+    });
+    it("orders by seed then sample numerically and matches confidence by exact job/seed/sample", () => {
+        const d = describeOpenDdeVisualization("/in/j.json", [
+            cif("t", 202, 0), cif("t", 101, 10), cif("t", 101, 2),
+            summary("t", 101, 2), summary("t", 202, 0),
+        ]);
+        expect(d.scenes.map((s) => s.title)).toEqual([
+            "Prediction 1 (seed 101, sample 2)",
+            "Prediction 2 (seed 101, sample 10)",
+            "Prediction 3 (seed 202, sample 0)",
+        ]);
+        const tables = d.panels.flatMap((p) => (p.kind === "table" ? [p] : []));
+        expect(tables.map((t) => t.title)).toEqual([
+            "Confidence — Prediction 1 (seed 101, sample 2)",
+            "Confidence — Prediction 3 (seed 202, sample 0)",
+        ]);
+        expect(d.scenes.every((s) => s.rank === undefined)).toBe(true);
+    });
+    it("prefixes the job name when several jobs ran, and skips non-prediction layouts", () => {
+        const stray = { id: "structures", path: path.join(out, "t", "not_seed", "predictions", "t_sample_0.cif") };
+        const d = describeOpenDdeVisualization("/in/j.json", [cif("a", 1, 0), cif("b", 1, 0), stray]);
+        expect(d.scenes.map((s) => s.title)).toEqual(["a — Prediction 1 (seed 1, sample 0)", "b — Prediction 1 (seed 1, sample 0)"]);
+    });
+});

package/dist/visualization.d.ts

@@ -0,0 +1,22 @@
+import type { ReportDescription, ResourceFormat, Scene, SourceRef } from "@moldesk/visualizer/contract";
+/**
+ * Small helper for adapters' `describeVisualization`: assigns report-local resource ids,
+ * reuses one resource when several scenes reference the same file, and puts the structure
+ * panel first. Holds descriptions only — file reads and verification happen in core.
+ */
+export declare class ReportBuilder {
+    private readonly resources;
+    private readonly byKey;
+    private readonly scenes;
+    private readonly panels;
+    /** Adds (or reuses) a resource for an exact collected output or staged input path. */
+    resource(source: SourceRef, format: ResourceFormat, label: string): string;
+    scene(scene: Scene): void;
+    /** A table over one JSON/CSV resource; empty `columns` shows every field present in the data. */
+    table(title: string, resourceId: string, columns?: Array<{
+        field: string;
+        label: string;
+    }>, rowsKey?: string): void;
+    get sceneCount(): number;
+    build(title: string): ReportDescription;
+}

package/dist/visualization.js

@@ -0,0 +1,44 @@
+/**
+ * Small helper for adapters' `describeVisualization`: assigns report-local resource ids,
+ * reuses one resource when several scenes reference the same file, and puts the structure
+ * panel first. Holds descriptions only — file reads and verification happen in core.
+ */
+export class ReportBuilder {
+    resources = [];
+    byKey = new Map();
+    scenes = [];
+    panels = [];
+    /** Adds (or reuses) a resource for an exact collected output or staged input path. */
+    resource(source, format, label) {
+        const key = `${source.kind}\0${source.path}`;
+        const existing = this.byKey.get(key);
+        if (existing)
+            return existing;
+        const id = `r${this.resources.length + 1}`;
+        this.resources.push({ id, source, format, label });
+        this.byKey.set(key, id);
+        return id;
+    }
+    scene(scene) {
+        this.scenes.push(scene);
+    }
+    /** A table over one JSON/CSV resource; empty `columns` shows every field present in the data. */
+    table(title, resourceId, columns = [], rowsKey) {
+        this.panels.push({
+            id: `table-${this.panels.length + 1}`,
+            kind: "table",
+            title,
+            dataset: { resourceId, ...(rowsKey === undefined ? {} : { rowsKey }) },
+            columns,
+        });
+    }
+    get sceneCount() {
+        return this.scenes.length;
+    }
+    build(title) {
+        const panels = this.scenes.length > 0
+            ? [{ id: "structures", kind: "structure", sceneIds: this.scenes.map((s) => s.id) }, ...this.panels]
+            : this.panels;
+        return { title, resources: this.resources, scenes: this.scenes, panels };
+    }
+}

package/dist/visualization.test.d.ts

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

package/dist/visualization.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { getAdapter } from "./index.js";
+import { ReportBuilder } from "./visualization.js";
+describe("adapter visualization hooks", () => {
+    it.each(["boltz", "opendde", "bindcraft2", "diffdock"])("%s describes its structure outputs", (name) => {
+        expect(typeof getAdapter(name)?.describeVisualization).toBe("function");
+    });
+    it.each(["proteinmpnn", "ligandmpnn"])("%s produces sequences, not coordinates, so it has no automatic report", (name) => {
+        expect(getAdapter(name)?.describeVisualization).toBeUndefined();
+    });
+});
+describe("ReportBuilder", () => {
+    it("reuses one resource for the same file and puts the structure panel first", () => {
+        const b = new ReportBuilder();
+        const a = b.resource({ kind: "input", path: "/r.pdb" }, "pdb", "r.pdb");
+        expect(b.resource({ kind: "input", path: "/r.pdb" }, "pdb", "r.pdb")).toBe(a);
+        // Same path, different kind is a different source.
+        expect(b.resource({ kind: "output", path: "/r.pdb" }, "pdb", "r.pdb")).not.toBe(a);
+        b.scene({ id: "s1", title: "S", structures: [{ id: "x", resourceId: a }] });
+        b.table("T", a);
+        const d = b.build("Title");
+        expect(d.panels.map((p) => p.kind)).toEqual(["structure", "table"]);
+        expect(d.resources).toHaveLength(2);
+    });
+    it("builds a chart-only description without a structure panel", () => {
+        const b = new ReportBuilder();
+        b.table("T", b.resource({ kind: "output", path: "/a.json" }, "json", "a.json"), [], "rows");
+        const d = b.build("t");
+        expect(d.scenes).toEqual([]);
+        expect(d.panels).toEqual([{ id: "table-1", kind: "table", title: "T", dataset: { resourceId: "r1", rowsKey: "rows" }, columns: [] }]);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldesk/adapters",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Thin model-specific adapters for MoleculeDesk (translation/verification only)",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,9 @@
   ],
   "dependencies": {
     "yaml": "^2.5.1",
-    "@moldesk/registry": "0.0.3",
-    "@moldesk/runtime": "0.0.3"
+    "@moldesk/registry": "0.0.4",
+    "@moldesk/visualizer": "0.0.4",
+    "@moldesk/runtime": "0.0.4"
   },
   "devDependencies": {
     "typescript": "^5.6.3",