@moldesk/visualizer 0.0.0-stage → 0.0.5

package/dist/contract.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { ContractError, validateDescription, validateReport } from "./contract.js";
+const sha = "a".repeat(64);
+function report(overrides = {}) {
+    return {
+        schemaVersion: 1,
+        id: "r1",
+        title: "T",
+        resources: [
+            { id: "p", label: "p.pdb", format: "pdb", sha256: sha, sizeBytes: 3, encoding: "base64", data: "YWJj" },
+            { id: "t", label: "t.csv", format: "csv", sha256: sha, sizeBytes: 3, encoding: "base64", data: "YWJj" },
+        ],
+        scenes: [{ id: "s1", title: "S", structures: [{ id: "a", resourceId: "p" }] }],
+        panels: [],
+        provenance: { createdAt: "2026-10-10T00:00:00.000Z" },
+        ...overrides,
+    };
+}
+describe("validateReport", () => {
+    it("accepts a minimal report", () => {
+        expect(validateReport(report()).scenes).toHaveLength(1);
+    });
+    it("allows chart-only reports", () => {
+        expect(validateReport(report({ scenes: [] })).scenes).toEqual([]);
+    });
+    it.each([
+        ["unknown schema", { schemaVersion: 2 }],
+        ["unknown top-level key", { extra: 1 }],
+        ["scene referencing a data resource", { scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "t" }] }] }],
+        ["scene referencing a missing resource", { scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "zz" }] }] }],
+        ["duplicate scene ids", { scenes: [
+                    { id: "s", title: "S", structures: [{ id: "a", resourceId: "p" }] },
+                    { id: "s", title: "S", structures: [{ id: "a", resourceId: "p" }] },
+                ] }],
+        ["bad transform length", { scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "p", transform: [1, 2] }] }] }],
+        ["non-finite transform", { scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "p", transform: Array(16).fill(Infinity) }] }] }],
+        ["css injection color", { scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "p" }],
+                        components: [{ id: "c", structureId: "a", selection: { kind: "all" }, color: "red;background:url(x)" }] }] }],
+        ["table on a molecular resource", { panels: [{ id: "x", kind: "table", dataset: { resourceId: "p" }, columns: [] }] }],
+        ["panel referencing unknown scene", { panels: [{ id: "x", kind: "structure", sceneIds: ["nope"] }] }],
+        ["hash mismatch in size", { resources: [{ id: "p", label: "p", format: "pdb", sha256: sha, sizeBytes: 99, encoding: "base64", data: "YWJj" }] }],
+        ["bad sha", { resources: [{ id: "p", label: "p", format: "pdb", sha256: "xyz", sizeBytes: 3, encoding: "base64", data: "YWJj" }] }],
+    ])("rejects %s", (_name, overrides) => {
+        expect(() => validateReport(report(overrides))).toThrow(ContractError);
+    });
+    it("rejects __proto__ keys", () => {
+        const evil = JSON.parse('{"schemaVersion":1,"__proto__":{"x":1}}');
+        expect(() => validateReport(evil)).toThrow(ContractError);
+    });
+    it("rejects a __proto__ rowsKey", () => {
+        expect(() => validateReport(report({
+            resources: [
+                { id: "p", label: "p", format: "pdb", sha256: sha, sizeBytes: 3, encoding: "base64", data: "YWJj" },
+                { id: "j", label: "j", format: "json", sha256: sha, sizeBytes: 3, encoding: "base64", data: "YWJj" },
+            ],
+            panels: [{ id: "x", kind: "table", dataset: { resourceId: "j", rowsKey: "__proto__" }, columns: [] }],
+        }))).toThrow(ContractError);
+    });
+});
+describe("validateDescription", () => {
+    const base = {
+        title: "T",
+        resources: [{ id: "p", source: { kind: "output", path: "/run/output/a.cif" }, format: "mmcif", label: "a" }],
+        scenes: [{ id: "s", title: "S", structures: [{ id: "a", resourceId: "p" }] }],
+        panels: [],
+    };
+    it("accepts a description", () => {
+        expect(validateDescription(base).resources).toHaveLength(1);
+    });
+    it("rejects URL sources", () => {
+        const bad = { ...base, resources: [{ ...base.resources[0], source: { kind: "output", path: "https://x/a.cif" } }] };
+        expect(() => validateDescription(bad)).toThrow(/URLs are not allowed/);
+    });
+    it("rejects duplicate resource ids", () => {
+        const bad = { ...base, resources: [base.resources[0], base.resources[0]] };
+        expect(() => validateDescription(bad)).toThrow(/duplicate id/);
+    });
+});

package/dist/csv.d.ts

@@ -0,0 +1,16 @@
+export interface CsvTable {
+    header: string[];
+    rows: string[][];
+}
+export interface CsvOptions {
+    maxRows?: number;
+    maxCells?: number;
+    maxCellLength?: number;
+}
+export declare class CsvError extends Error {
+    readonly code = "INVALID_CSV";
+    constructor(message: string);
+}
+export declare function parseCsv(text: string, options?: CsvOptions): CsvTable;
+/** Rows as objects keyed by header; null-prototype so header names cannot hit Object.prototype. */
+export declare function csvRecords(table: CsvTable): Array<Record<string, string>>;

package/dist/csv.js

@@ -0,0 +1,93 @@
+// Bounded RFC 4180-style CSV parser. Browser-neutral: no Node or DOM imports,
+// so adapters and the viewer can share it. Cells are always returned as strings.
+import { REPORT_LIMITS } from "./limits.js";
+export class CsvError extends Error {
+    code = "INVALID_CSV";
+    constructor(message) {
+        super(message);
+        this.name = "CsvError";
+    }
+}
+export function parseCsv(text, options = {}) {
+    const maxRows = options.maxRows ?? REPORT_LIMITS.maxTableRows;
+    const maxCells = options.maxCells ?? REPORT_LIMITS.maxTableCells;
+    const maxCellLength = options.maxCellLength ?? REPORT_LIMITS.maxCellLength;
+    const records = [];
+    let row = [];
+    let cell = "";
+    let inQuotes = false;
+    let cells = 0;
+    let i = text.charCodeAt(0) === 0xfeff ? 1 : 0; // strip BOM
+    const endCell = () => {
+        row.push(cell);
+        cell = "";
+        if (++cells > maxCells)
+            throw new CsvError(`more than ${maxCells} cells`);
+    };
+    const endRow = () => {
+        endCell();
+        // Skip fully blank lines (a single empty cell).
+        if (!(row.length === 1 && row[0] === "")) {
+            records.push(row);
+            if (records.length > maxRows + 1)
+                throw new CsvError(`more than ${maxRows} rows`);
+        }
+        row = [];
+    };
+    for (; i < text.length; i++) {
+        const ch = text[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    cell += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                cell += ch;
+            }
+        }
+        else if (ch === '"' && cell === "") {
+            inQuotes = true;
+        }
+        else if (ch === ",") {
+            endCell();
+        }
+        else if (ch === "\n" || ch === "\r") {
+            if (ch === "\r" && text[i + 1] === "\n")
+                i++;
+            endRow();
+        }
+        else {
+            cell += ch;
+        }
+        if (cell.length > maxCellLength)
+            throw new CsvError(`cell longer than ${maxCellLength} characters`);
+    }
+    if (inQuotes)
+        throw new CsvError("unterminated quoted cell");
+    if (cell !== "" || row.length > 0)
+        endRow();
+    const header = records.shift();
+    if (!header)
+        throw new CsvError("empty CSV");
+    for (const [n, r] of records.entries()) {
+        if (r.length !== header.length) {
+            throw new CsvError(`row ${n + 2} has ${r.length} cells, expected ${header.length}`);
+        }
+    }
+    return { header, rows: records };
+}
+/** Rows as objects keyed by header; null-prototype so header names cannot hit Object.prototype. */
+export function csvRecords(table) {
+    return table.rows.map((r) => {
+        const rec = Object.create(null);
+        table.header.forEach((h, k) => {
+            rec[h] = r[k];
+        });
+        return rec;
+    });
+}

package/dist/csv.test.d.ts

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

package/dist/csv.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { CsvError, csvRecords, parseCsv } from "./csv.js";
+describe("parseCsv", () => {
+    it("parses quoted cells with commas, quotes and newlines", () => {
+        const t = parseCsv('design,note\r\nd1,"a, ""b""\nc"\r\nd2,plain\r\n');
+        expect(t.header).toEqual(["design", "note"]);
+        expect(t.rows).toEqual([
+            ["d1", 'a, "b"\nc'],
+            ["d2", "plain"],
+        ]);
+    });
+    it("strips BOM and skips blank lines", () => {
+        expect(parseCsv("a,b\n\n1,2\n").rows).toEqual([["1", "2"]]);
+    });
+    it("rejects ragged rows, unterminated quotes and empty input", () => {
+        expect(() => parseCsv("a,b\n1\n")).toThrow(CsvError);
+        expect(() => parseCsv('a\n"x')).toThrow(/unterminated/);
+        expect(() => parseCsv("")).toThrow(/empty/);
+    });
+    it("enforces bounds", () => {
+        expect(() => parseCsv("a\n1\n2\n3\n", { maxRows: 2 })).toThrow(/rows/);
+        expect(() => parseCsv("a,b\n1,2\n", { maxCells: 3 })).toThrow(/cells/);
+        expect(() => parseCsv("a\nxxxxxx\n", { maxCellLength: 3 })).toThrow(/longer/);
+    });
+    it("returns null-prototype records", () => {
+        const [rec] = csvRecords(parseCsv("__proto__,b\n1,2\n"));
+        expect(Object.getPrototypeOf(rec)).toBeNull();
+        expect(rec["__proto__"]).toBe("1");
+    });
+});

package/dist/export.d.ts

@@ -0,0 +1,23 @@
+import { type ViewerBundle } from "./bundle.js";
+import { type ReportInput } from "./report.js";
+import type { MolecularReportV1 } from "./contract.js";
+export interface ExportedReport {
+    html: string;
+    report: MolecularReportV1;
+    sha256: string;
+    sizeBytes: number;
+    sourceSha256: string[];
+    viewerVersion: string;
+    bundleSha256: string;
+}
+export declare class PublishError extends Error {
+    readonly code: "OUTPUT_EXISTS" | "REPORT_CONFLICT" | "UNSUPPORTED_REPORT" | "INVALID_REPORT";
+    constructor(code: "OUTPUT_EXISTS" | "REPORT_CONFLICT" | "UNSUPPORTED_REPORT" | "INVALID_REPORT", message: string);
+}
+export declare function exportReport(input: ReportInput, bundle?: ViewerBundle): ExportedReport;
+/**
+ * Writes `content` to a new file that must not already exist. Staged in the destination
+ * directory, then published with an exclusive link (copy fallback) so a concurrent writer
+ * is never overwritten.
+ */
+export declare function writeFileExclusive(dest: string, content: string | Uint8Array, mode?: number): Promise<void>;

package/dist/export.js

@@ -0,0 +1,61 @@
+// Trusted exporter: assembles a report HTML from verified bytes and publishes it safely.
+import { constants, promises as fsp } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { loadBundle, sha256Hex } from "./bundle.js";
+import { buildEnvelope, createReport, renderHtml } from "./report.js";
+export class PublishError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PublishError";
+    }
+}
+export function exportReport(input, bundle = loadBundle()) {
+    const report = createReport(input);
+    const envelope = buildEnvelope(report, bundle);
+    const html = renderHtml(envelope, bundle, report.title);
+    return {
+        html,
+        report,
+        sha256: sha256Hex(html),
+        sizeBytes: Buffer.byteLength(html),
+        sourceSha256: report.resources.map((r) => r.sha256),
+        viewerVersion: bundle.metadata.viewerVersion,
+        bundleSha256: bundle.metadata.bundleSha256,
+    };
+}
+/**
+ * Writes `content` to a new file that must not already exist. Staged in the destination
+ * directory, then published with an exclusive link (copy fallback) so a concurrent writer
+ * is never overwritten.
+ */
+export async function writeFileExclusive(dest, content, mode = 0o644) {
+    const tmp = path.join(path.dirname(dest), `.${path.basename(dest)}.tmp-${process.pid}-${randomUUID()}`);
+    try {
+        await fsp.writeFile(tmp, content, { flag: "wx", mode });
+        try {
+            await fsp.link(tmp, dest);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "EEXIST")
+                throw new PublishError("OUTPUT_EXISTS", `Refusing to overwrite existing file: ${dest}`);
+            if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV")
+                throw error;
+            try {
+                await fsp.copyFile(tmp, dest, constants.COPYFILE_EXCL);
+            }
+            catch (copyError) {
+                if (copyError.code === "EEXIST") {
+                    throw new PublishError("OUTPUT_EXISTS", `Refusing to overwrite existing file: ${dest}`);
+                }
+                throw copyError;
+            }
+        }
+    }
+    finally {
+        await fsp.rm(tmp, { force: true });
+    }
+}

package/dist/fixtures.test.d.ts

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

package/dist/fixtures.test.js

@@ -0,0 +1,61 @@
+import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { computeBundleSha256, sha256Hex, TEMPLATE_VERSION } from "./bundle.js";
+import { exportReport } from "./export.js";
+import { decodeEnvelope, extractEnvelope } from "./report.js";
+import { applyUpdate, planUpdate } from "./update.js";
+const fixtures = path.join(path.dirname(fileURLToPath(import.meta.url)), "../test/fixtures");
+function bundle(tag) {
+    const js = `/* ${tag} */`;
+    const css = `/* css ${tag} */`;
+    const assets = { "viewer.js": sha256Hex(js), "viewer.css": sha256Hex(css) };
+    return {
+        js,
+        css,
+        metadata: {
+            viewerVersion: "1.0.0",
+            molstarVersion: "5.12.0",
+            templateVersion: TEMPLATE_VERSION,
+            compatible: { envelopeVersions: [1], schemaVersions: [1] },
+            assets,
+            bundleSha256: computeBundleSha256(assets),
+        },
+    };
+}
+const FORMATS = { ".pdb": "pdb", ".cif": "mmcif", ".sdf": "sdf", ".json": "json" };
+const files = readdirSync(fixtures).filter((f) => f.slice(f.lastIndexOf(".")) in FORMATS);
+let dir;
+beforeEach(() => {
+    dir = mkdtempSync(path.join(os.tmpdir(), "moldesk-fixtures-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+describe("real structure fixtures", () => {
+    it("covers the scientific edge cases the browser smoke relies on", () => {
+        for (const f of ["1AAY.pdb", "1D3Z-3models.pdb", "1IGT-VH.pdb", "3HZ7.pdb", "HEM-only.pdb", "1CRN.cif", "1BNA.cif"]) {
+            expect(files).toContain(f);
+        }
+    });
+    it.each(files)("%s: original bytes survive export, decode, and a viewer update unchanged", async (name) => {
+        const original = new Uint8Array(readFileSync(path.join(fixtures, name)));
+        const format = FORMATS[name.slice(name.lastIndexOf("."))];
+        const exported = exportReport({
+            title: name,
+            resources: [{ id: "r", label: name, format, bytes: original }],
+            scenes: format === "json" ? [] : [{ id: "s", title: name, structures: [{ id: "a", resourceId: "r" }] }],
+            panels: [],
+            provenance: {},
+        }, bundle("a"));
+        const before = decodeEnvelope(extractEnvelope(exported.html));
+        expect(before.resources[0].sha256).toBe(sha256Hex(original));
+        expect(Buffer.from(before.resources[0].data, "base64").equals(Buffer.from(original))).toBe(true);
+        const file = path.join(dir, "r.html");
+        writeFileSync(file, exported.html);
+        await applyUpdate(await planUpdate(file, { bundle: bundle("b") }));
+        const after = decodeEnvelope(extractEnvelope(readFileSync(file, "utf8")));
+        expect(after.resources).toEqual(before.resources);
+        expect(after.scenes).toEqual(before.scenes);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./contract.js";
+export { BundleError, loadBundle, sha256Hex, type BundleMetadata, type ViewerBundle } from "./bundle.js";
+export { buildEnvelope, createReport, decodeEnvelope, extractEnvelope, renderHtml, ReportFormatError, type ReportEnvelopeV1, type ReportInput, } from "./report.js";
+export { exportReport, PublishError, writeFileExclusive, type ExportedReport } from "./export.js";
+export { applyUpdate, planUpdate, type UpdatePlan, type UpdateResult, type UpdateStatus } from "./update.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// Node APIs. Never loads the browser bundle as code; it is only read as text.
+export * from "./contract.js";
+export { BundleError, loadBundle, sha256Hex } from "./bundle.js";
+export { buildEnvelope, createReport, decodeEnvelope, extractEnvelope, renderHtml, ReportFormatError, } from "./report.js";
+export { exportReport, PublishError, writeFileExclusive } from "./export.js";
+export { applyUpdate, planUpdate } from "./update.js";

package/dist/limits.d.ts

@@ -0,0 +1,24 @@
+export declare const REPORT_LIMITS: {
+    /** Largest single source file (original bytes) embedded in a report. */
+    readonly maxResourceBytes: number;
+    /** Sum of all embedded original bytes in one report. */
+    readonly maxTotalResourceBytes: number;
+    /** Largest report HTML file the updater will read. Covers base64 overhead + viewer. */
+    readonly maxReportFileBytes: number;
+    readonly maxResources: 512;
+    readonly maxScenes: 256;
+    readonly maxStructuresPerScene: 64;
+    readonly maxComponentsPerScene: 128;
+    readonly maxPanels: 64;
+    readonly maxColumns: 64;
+    readonly maxSelectionIds: 1024;
+    readonly maxResidueRefs: 10000;
+    readonly maxIdLength: 128;
+    readonly maxLabelLength: 256;
+    readonly maxTitleLength: 512;
+    readonly maxFieldLength: 128;
+    /** Bounds for parsed tabular data (CSV rows or JSON arrays). */
+    readonly maxTableRows: 100000;
+    readonly maxTableCells: 2000000;
+    readonly maxCellLength: 4096;
+};

package/dist/limits.js

@@ -0,0 +1,28 @@
+// Named bounds for report contents. Shared by the Node exporter/updater and the
+// browser viewer, so it must stay free of Node and DOM imports. Values are
+// practical starting points; see docs/visualizer.md for measurements.
+const MiB = 1024 * 1024;
+export const REPORT_LIMITS = {
+    /** Largest single source file (original bytes) embedded in a report. */
+    maxResourceBytes: 64 * MiB,
+    /** Sum of all embedded original bytes in one report. */
+    maxTotalResourceBytes: 256 * MiB,
+    /** Largest report HTML file the updater will read. Covers base64 overhead + viewer. */
+    maxReportFileBytes: 400 * MiB,
+    maxResources: 512,
+    maxScenes: 256,
+    maxStructuresPerScene: 64,
+    maxComponentsPerScene: 128,
+    maxPanels: 64,
+    maxColumns: 64,
+    maxSelectionIds: 1024,
+    maxResidueRefs: 10_000,
+    maxIdLength: 128,
+    maxLabelLength: 256,
+    maxTitleLength: 512,
+    maxFieldLength: 128,
+    /** Bounds for parsed tabular data (CSV rows or JSON arrays). */
+    maxTableRows: 100_000,
+    maxTableCells: 2_000_000,
+    maxCellLength: 4096,
+};

package/dist/report.d.ts

@@ -0,0 +1,53 @@
+import { type ViewerBundle } from "./bundle.js";
+import { type MolecularReportV1, type Panel, type ResourceFormat, type Scene } from "./contract.js";
+export declare const ENVELOPE_MAGIC = "moldesk-molecular-report";
+export declare const ENVELOPE_ELEMENT_ID = "moldesk-report";
+export interface ReportEnvelopeV1 {
+    magic: typeof ENVELOPE_MAGIC;
+    envelopeVersion: 1;
+    payloadEncoding: "base64-json";
+    /** UTF-8 MolecularReportV1 JSON, base64. */
+    payload: string;
+    payloadSha256: string;
+    viewer: {
+        version: string;
+        molstarVersion: string;
+        bundleSha256: string;
+        templateVersion: number;
+    };
+    lastUpdatedAt?: string;
+}
+export declare class ReportFormatError extends Error {
+    readonly code = "INVALID_REPORT";
+    constructor(message: string);
+}
+export interface ReportInput {
+    title: string;
+    resources: Array<{
+        id: string;
+        label: string;
+        format: ResourceFormat;
+        bytes: Uint8Array;
+    }>;
+    scenes: Scene[];
+    panels: Panel[];
+    provenance: {
+        runId?: string;
+        model?: string;
+        modelVersion?: string;
+    };
+    id?: string;
+    createdAt?: string;
+}
+/** Builds a validated report. Resource hashes are over the original bytes. */
+export declare function createReport(input: ReportInput): MolecularReportV1;
+export declare function buildEnvelope(report: MolecularReportV1, bundle: ViewerBundle, lastUpdatedAt?: string): ReportEnvelopeV1;
+export declare function escapeHtml(text: string): string;
+/** Restrictive policy: no network of any kind; only the two hashed inline blocks may run/style. */
+export declare function contentSecurityPolicy(js: string, css: string): string;
+/** Deterministic: same envelope + bundle always yields identical bytes. */
+export declare function renderHtml(envelope: ReportEnvelopeV1, bundle: ViewerBundle, title: string): string;
+/** Narrow exact extractor: exactly one envelope element, no HTML parsing, no script execution. */
+export declare function extractEnvelope(html: string): ReportEnvelopeV1;
+/** Verifies payload and every resource against its recorded digest, then validates the schema. */
+export declare function decodeEnvelope(envelope: ReportEnvelopeV1): MolecularReportV1;