npm - @moldesk/visualizer - Versions diffs - 0.0.0-stage → 0.0.5 - Mend

@moldesk/visualizer 0.0.0-stage → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/dist/assets/MOLSTAR_LICENSE.txt +21 -0
package/dist/assets/THIRD_PARTY_NOTICES.txt +5 -0
package/dist/assets/bundle.json +18 -0
package/dist/assets/viewer.css +114 -0
package/dist/assets/viewer.js +7724 -0
package/dist/bundle.d.ts +26 -0
package/dist/bundle.js +48 -0
package/dist/contract.d.ts +146 -0
package/dist/contract.js +433 -0
package/dist/contract.test.d.ts +1 -0
package/dist/contract.test.js +78 -0
package/dist/csv.d.ts +16 -0
package/dist/csv.js +93 -0
package/dist/csv.test.d.ts +1 -0
package/dist/csv.test.js +30 -0
package/dist/export.d.ts +23 -0
package/dist/export.js +61 -0
package/dist/fixtures.test.d.ts +1 -0
package/dist/fixtures.test.js +61 -0
package/dist/index.d.ts +5 -0
package/dist/index.js +6 -0
package/dist/limits.d.ts +24 -0
package/dist/limits.js +28 -0
package/dist/report.d.ts +53 -0
package/dist/report.js +195 -0
package/dist/update.d.ts +41 -0
package/dist/update.js +147 -0
package/dist/update.test.d.ts +1 -0
package/dist/update.test.js +167 -0
package/package.json +51 -3
package/README.md +0 -3

package/dist/report.js ADDED Viewed

@@ -0,0 +1,195 @@
+// Report envelope, trusted HTML template, and strict extraction/decoding.
+// Nothing here executes or evaluates report content.
+import { randomUUID } from "node:crypto";
+import { REPORT_LIMITS } from "./limits.js";
+import { sha256Hex, TEMPLATE_VERSION } from "./bundle.js";
+import { ContractError, validateReport, } from "./contract.js";
+export const ENVELOPE_MAGIC = "moldesk-molecular-report";
+export const ENVELOPE_ELEMENT_ID = "moldesk-report";
+const ENVELOPE_OPEN = `<script type="application/json" id="${ENVELOPE_ELEMENT_ID}">`;
+const SCRIPT_CLOSE = "</script>";
+export class ReportFormatError extends Error {
+    code = "INVALID_REPORT";
+    constructor(message) {
+        super(message);
+        this.name = "ReportFormatError";
+    }
+}
+/** Builds a validated report. Resource hashes are over the original bytes. */
+export function createReport(input) {
+    const report = {
+        schemaVersion: 1,
+        id: input.id ?? randomUUID(),
+        title: input.title,
+        resources: input.resources.map((r) => ({
+            id: r.id,
+            label: r.label,
+            format: r.format,
+            sha256: sha256Hex(r.bytes),
+            sizeBytes: r.bytes.byteLength,
+            encoding: "base64",
+            data: Buffer.from(r.bytes).toString("base64"),
+        })),
+        scenes: input.scenes,
+        panels: input.panels,
+        provenance: { createdAt: input.createdAt ?? new Date().toISOString(), ...input.provenance },
+    };
+    return validateReport(report);
+}
+export function buildEnvelope(report, bundle, lastUpdatedAt) {
+    const payload = Buffer.from(JSON.stringify(report), "utf8").toString("base64");
+    return {
+        magic: ENVELOPE_MAGIC,
+        envelopeVersion: 1,
+        payloadEncoding: "base64-json",
+        payload,
+        payloadSha256: sha256Hex(payload),
+        viewer: {
+            version: bundle.metadata.viewerVersion,
+            molstarVersion: bundle.metadata.molstarVersion,
+            bundleSha256: bundle.metadata.bundleSha256,
+            templateVersion: TEMPLATE_VERSION,
+        },
+        ...(lastUpdatedAt === undefined ? {} : { lastUpdatedAt }),
+    };
+}
+export function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+/** JSON that cannot terminate a script element or be misread as HTML. */
+function inertJson(value) {
+    return JSON.stringify(value).replace(/[<>&]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function cspHash(text) {
+    return `'sha256-${Buffer.from(sha256Hex(text), "hex").toString("base64")}'`;
+}
+/** Restrictive policy: no network of any kind; only the two hashed inline blocks may run/style. */
+export function contentSecurityPolicy(js, css) {
+    return [
+        "default-src 'none'",
+        `script-src ${cspHash(js)}`,
+        `style-src-elem ${cspHash(css)}`,
+        "img-src data: blob:",
+        "worker-src blob:",
+        "connect-src 'none'",
+        "font-src 'none'",
+        "object-src 'none'",
+        "base-uri 'none'",
+        "form-action 'none'",
+    ].join("; ");
+}
+/** Deterministic: same envelope + bundle always yields identical bytes. */
+export function renderHtml(envelope, bundle, title) {
+    const csp = contentSecurityPolicy(bundle.js, bundle.css);
+    return [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(csp)}">`,
+        `<title>${escapeHtml(title)}</title>`,
+        `<style>${bundle.css}</style>`,
+        "</head>",
+        "<body>",
+        '<div id="root"></div>',
+        `${ENVELOPE_OPEN}${inertJson(envelope)}${SCRIPT_CLOSE}`,
+        `<script>${bundle.js}${SCRIPT_CLOSE}`,
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+}
+/** Narrow exact extractor: exactly one envelope element, no HTML parsing, no script execution. */
+export function extractEnvelope(html) {
+    if (html.length > REPORT_LIMITS.maxReportFileBytes)
+        throw new ReportFormatError("Report file is too large");
+    const first = html.indexOf(ENVELOPE_OPEN);
+    if (first === -1)
+        throw new ReportFormatError("This file is not a MoleculeDesk molecular report");
+    if (html.indexOf(ENVELOPE_OPEN, first + 1) !== -1 || html.split(`id="${ENVELOPE_ELEMENT_ID}"`).length !== 2) {
+        throw new ReportFormatError("Report contains more than one report envelope");
+    }
+    const start = first + ENVELOPE_OPEN.length;
+    const end = html.indexOf(SCRIPT_CLOSE, start);
+    if (end === -1)
+        throw new ReportFormatError("Report envelope is not terminated");
+    let parsed;
+    try {
+        parsed = JSON.parse(html.slice(start, end));
+    }
+    catch {
+        throw new ReportFormatError("Report envelope is not valid JSON");
+    }
+    return validateEnvelope(parsed);
+}
+const ENVELOPE_KEYS = ["magic", "envelopeVersion", "payloadEncoding", "payload", "payloadSha256", "viewer", "lastUpdatedAt"];
+const VIEWER_KEYS = ["version", "molstarVersion", "bundleSha256", "templateVersion"];
+function validateEnvelope(value) {
+    const bad = (m) => {
+        throw new ReportFormatError(`Invalid report envelope: ${m}`);
+    };
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        bad("not an object");
+    const o = value;
+    if (Object.keys(o).some((k) => !ENVELOPE_KEYS.includes(k)))
+        bad("unknown field");
+    if (o.magic !== ENVELOPE_MAGIC)
+        bad("wrong magic");
+    if (o.envelopeVersion !== 1)
+        bad("unsupported envelope version");
+    if (o.payloadEncoding !== "base64-json")
+        bad("unsupported payload encoding");
+    if (typeof o.payload !== "string" || typeof o.payloadSha256 !== "string")
+        bad("missing payload");
+    const v = o.viewer;
+    if (typeof v !== "object" || v === null || Object.keys(v).some((k) => !VIEWER_KEYS.includes(k)))
+        bad("viewer metadata");
+    if (typeof v.version !== "string" ||
+        typeof v.molstarVersion !== "string" ||
+        typeof v.bundleSha256 !== "string" ||
+        typeof v.templateVersion !== "number") {
+        bad("viewer metadata");
+    }
+    if (o.lastUpdatedAt !== undefined && typeof o.lastUpdatedAt !== "string")
+        bad("lastUpdatedAt");
+    return o;
+}
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Verifies payload and every resource against its recorded digest, then validates the schema. */
+export function decodeEnvelope(envelope) {
+    const maxPayload = Math.ceil((REPORT_LIMITS.maxTotalResourceBytes * 4) / 3) * 2;
+    if (envelope.payload.length > maxPayload)
+        throw new ReportFormatError("Report payload is too large");
+    if (!BASE64.test(envelope.payload) || envelope.payload.length % 4 !== 0) {
+        throw new ReportFormatError("Report payload is not valid base64");
+    }
+    if (sha256Hex(envelope.payload) !== envelope.payloadSha256) {
+        throw new ReportFormatError("Report payload does not match its recorded digest");
+    }
+    let json;
+    try {
+        json = JSON.parse(Buffer.from(envelope.payload, "base64").toString("utf8"));
+    }
+    catch {
+        throw new ReportFormatError("Report payload is not valid JSON");
+    }
+    let report;
+    try {
+        report = validateReport(json);
+    }
+    catch (error) {
+        if (error instanceof ContractError)
+            throw new ReportFormatError(error.message);
+        throw error;
+    }
+    for (const r of report.resources) {
+        if (!BASE64.test(r.data))
+            throw new ReportFormatError(`Resource "${r.id}" is not valid base64`);
+        const bytes = Buffer.from(r.data, "base64");
+        if (bytes.byteLength !== r.sizeBytes || sha256Hex(bytes) !== r.sha256) {
+            throw new ReportFormatError(`Resource "${r.id}" does not match its recorded digest`);
+        }
+    }
+    return report;
+}

package/dist/update.d.ts ADDED Viewed

@@ -0,0 +1,41 @@
+import { type ViewerBundle } from "./bundle.js";
+export type UpdateStatus = "noop" | "replace" | "unsupported";
+export interface UpdatePlan {
+    status: UpdateStatus;
+    /** Why an update is unsupported. */
+    reason?: string;
+    targetPath: string;
+    outputPath?: string;
+    originalSha256: string;
+    originalSizeBytes: number;
+    payloadSha256?: string;
+    fromViewerVersion?: string;
+    toViewerVersion: string;
+    toBundleSha256: string;
+    /** Internal: state needed to commit safely. */
+    original: Buffer;
+    identity: {
+        ino: number;
+        dev: number;
+        size: number;
+        mtimeMs: number;
+        mode: number;
+    };
+    newHtml?: string;
+}
+export interface UpdateResult {
+    status: "updated" | "copied";
+    path: string;
+    backupPath?: string;
+    sha256: string;
+    sizeBytes: number;
+    payloadSha256: string;
+    viewerVersion: string;
+    bundleSha256: string;
+}
+export declare function planUpdate(target: string, options?: {
+    output?: string;
+    bundle?: ViewerBundle;
+    now?: () => Date;
+}): Promise<UpdatePlan>;
+export declare function applyUpdate(plan: UpdatePlan): Promise<UpdateResult>;

package/dist/update.js ADDED Viewed

@@ -0,0 +1,147 @@
+// Local viewer replacement. Inspects the target as data only; never executes it.
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { loadBundle, sha256Hex } from "./bundle.js";
+import { PublishError, writeFileExclusive } from "./export.js";
+import { REPORT_LIMITS } from "./limits.js";
+import { buildEnvelope, decodeEnvelope, extractEnvelope, ReportFormatError, renderHtml } from "./report.js";
+function identityOf(s) {
+    return { ino: s.ino, dev: s.dev, size: s.size, mtimeMs: s.mtimeMs, mode: s.mode & 0o777 };
+}
+async function readRegularFile(target) {
+    let stat;
+    try {
+        stat = await fsp.lstat(target);
+    }
+    catch {
+        throw new ReportFormatError(`Report not found: ${target}`);
+    }
+    if (stat.isSymbolicLink())
+        throw new ReportFormatError("Report path is a symbolic link");
+    if (!stat.isFile())
+        throw new ReportFormatError("Report path is not a regular file");
+    if (stat.size > REPORT_LIMITS.maxReportFileBytes)
+        throw new ReportFormatError("Report file is too large");
+    return { bytes: await fsp.readFile(target), stat };
+}
+export async function planUpdate(target, options = {}) {
+    const bundle = options.bundle ?? loadBundle();
+    const { bytes, stat } = await readRegularFile(target);
+    const html = bytes.toString("utf8");
+    const base = {
+        targetPath: target,
+        ...(options.output === undefined ? {} : { outputPath: options.output }),
+        originalSha256: sha256Hex(bytes),
+        originalSizeBytes: bytes.byteLength,
+        toViewerVersion: bundle.metadata.viewerVersion,
+        toBundleSha256: bundle.metadata.bundleSha256,
+        original: bytes,
+        identity: identityOf(stat),
+    };
+    const envelope = extractEnvelope(html);
+    const compat = bundle.metadata.compatible;
+    const unsupported = (reason) => ({ ...base, status: "unsupported", reason });
+    if (!compat.envelopeVersions.includes(envelope.envelopeVersion)) {
+        return unsupported("unsupported envelope version");
+    }
+    const report = decodeEnvelope(envelope); // throws on malformed/inconsistent payloads
+    if (!compat.schemaVersions.includes(report.schemaVersion))
+        return unsupported("unsupported report schema");
+    const common = {
+        ...base,
+        payloadSha256: envelope.payloadSha256,
+        fromViewerVersion: envelope.viewer.version,
+    };
+    // Same-bundle no-op only if the actual file equals a trusted reconstruction.
+    const sameBundle = envelope.viewer.bundleSha256 === bundle.metadata.bundleSha256 &&
+        envelope.viewer.templateVersion === bundle.metadata.templateVersion;
+    if (sameBundle && renderHtml(envelope, bundle, report.title) === html) {
+        return { ...common, status: "noop" };
+    }
+    const updated = {
+        ...buildEnvelope(report, bundle, (options.now?.() ?? new Date()).toISOString()),
+        // Payload kept verbatim, not re-serialized.
+        payload: envelope.payload,
+        payloadSha256: envelope.payloadSha256,
+    };
+    return { ...common, status: "replace", newHtml: renderHtml(updated, bundle, report.title) };
+}
+async function assertUnchanged(plan) {
+    let current;
+    try {
+        current = await readRegularFile(plan.targetPath);
+    }
+    catch {
+        throw new PublishError("REPORT_CONFLICT", "The report changed while the update was being prepared. Nothing was changed.");
+    }
+    const a = identityOf(current.stat);
+    const b = plan.identity;
+    if (a.ino !== b.ino ||
+        a.dev !== b.dev ||
+        a.size !== b.size ||
+        a.mtimeMs !== b.mtimeMs ||
+        sha256Hex(current.bytes) !== plan.originalSha256) {
+        throw new PublishError("REPORT_CONFLICT", "The report changed while the update was being prepared. Nothing was changed.");
+    }
+}
+async function writeUniqueBackup(target, bytes, mode) {
+    const { dir, name, ext } = path.parse(target);
+    for (let n = 0; n < 1000; n++) {
+        const candidate = path.join(dir, `${name}.backup${n === 0 ? "" : `-${n}`}${ext}`);
+        try {
+            await fsp.writeFile(candidate, bytes, { flag: "wx", mode });
+            return candidate;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    throw new PublishError("OUTPUT_EXISTS", "Could not find an unused backup file name");
+}
+function digestsOf(html) {
+    return { sha256: sha256Hex(html), sizeBytes: Buffer.byteLength(html) };
+}
+export async function applyUpdate(plan) {
+    if (plan.status === "unsupported") {
+        throw new PublishError("UNSUPPORTED_REPORT", plan.reason ?? "Report cannot be updated");
+    }
+    await assertUnchanged(plan);
+    const payloadSha256 = plan.payloadSha256 ?? "";
+    if (plan.outputPath !== undefined) {
+        const content = plan.status === "replace" ? plan.newHtml : plan.original;
+        await writeFileExclusive(plan.outputPath, content, plan.identity.mode);
+        return {
+            status: plan.status === "replace" ? "updated" : "copied",
+            path: plan.outputPath,
+            payloadSha256,
+            viewerVersion: plan.toViewerVersion,
+            bundleSha256: plan.toBundleSha256,
+            ...digestsOf(content),
+        };
+    }
+    if (plan.status === "noop" || plan.newHtml === undefined) {
+        throw new PublishError("REPORT_CONFLICT", "Nothing to update");
+    }
+    const backupPath = await writeUniqueBackup(plan.targetPath, plan.original, plan.identity.mode);
+    const tmp = path.join(path.dirname(plan.targetPath), `.${path.basename(plan.targetPath)}.tmp-${process.pid}-${randomUUID()}`);
+    try {
+        await fsp.writeFile(tmp, plan.newHtml, { flag: "wx", mode: plan.identity.mode });
+        await fsp.chmod(tmp, plan.identity.mode);
+        await fsp.rename(tmp, plan.targetPath);
+    }
+    catch (error) {
+        await fsp.rm(tmp, { force: true });
+        throw error;
+    }
+    return {
+        status: "updated",
+        path: plan.targetPath,
+        backupPath,
+        payloadSha256,
+        viewerVersion: plan.toViewerVersion,
+        bundleSha256: plan.toBundleSha256,
+        ...digestsOf(plan.newHtml),
+    };
+}

package/dist/update.test.d.ts ADDED Viewed

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

package/dist/update.test.js ADDED Viewed

@@ -0,0 +1,167 @@
+import { mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, chmodSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { computeBundleSha256, sha256Hex, TEMPLATE_VERSION } from "./bundle.js";
+import { exportReport, writeFileExclusive } from "./export.js";
+import { decodeEnvelope, extractEnvelope, ReportFormatError } from "./report.js";
+import { applyUpdate, planUpdate } from "./update.js";
+function fakeBundle(tag, version = "1.0.0") {
+    const js = `/* viewer ${tag} */ window.__v=${JSON.stringify(tag)};`;
+    const css = `/* css ${tag} */ body{margin:0}`;
+    const assets = { "viewer.js": sha256Hex(js), "viewer.css": sha256Hex(css) };
+    return {
+        js,
+        css,
+        metadata: {
+            viewerVersion: version,
+            molstarVersion: "5.12.0",
+            templateVersion: TEMPLATE_VERSION,
+            compatible: { envelopeVersions: [1], schemaVersions: [1] },
+            assets,
+            bundleSha256: computeBundleSha256(assets),
+        },
+    };
+}
+const PDB = new TextEncoder().encode("ATOM      1  N   ALA A   1      11.104  13.207   2.100  1.00 20.00           N\n");
+function input(title = "My protein") {
+    return {
+        title,
+        resources: [{ id: "r1", label: "p.pdb", format: "pdb", bytes: PDB }],
+        scenes: [{ id: "s1", title: "Structure", structures: [{ id: "a", resourceId: "r1" }] }],
+        panels: [],
+        provenance: {},
+    };
+}
+let dir;
+beforeEach(() => {
+    dir = mkdtempSync(path.join(os.tmpdir(), "moldesk-viz-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+describe("envelope", () => {
+    it("round-trips and survives hostile titles and molecular comments", () => {
+        const evil = '</script><script>alert(1)</script><img src=x onerror="y">';
+        const bytes = new TextEncoder().encode(`REMARK ${evil}\nATOM\n`);
+        const out = exportReport({ ...input(evil), resources: [{ id: "r1", label: evil, format: "pdb", bytes }] }, fakeBundle("a"));
+        // The only script elements are the inert envelope and the trusted viewer.
+        expect(out.html.match(/<script/g)).toHaveLength(2);
+        expect(out.html).not.toContain(evil);
+        const report = decodeEnvelope(extractEnvelope(out.html));
+        expect(report.title).toBe(evil);
+        expect(Buffer.from(report.resources[0].data, "base64").equals(Buffer.from(bytes))).toBe(true);
+        expect(report.resources[0].sha256).toBe(sha256Hex(bytes));
+    });
+    it("emits a CSP with matching hashes and no network allowances", () => {
+        const b = fakeBundle("a");
+        const { html } = exportReport(input(), b);
+        const csp = /Content-Security-Policy" content="([^"]+)"/.exec(html)[1].replace(/&#39;/g, "'");
+        expect(csp).toContain("connect-src 'none'");
+        expect(csp).toContain("default-src 'none'");
+        expect(csp).not.toContain("unsafe-eval");
+        expect(csp).toContain(`'sha256-${Buffer.from(sha256Hex(b.js), "hex").toString("base64")}'`);
+    });
+    it("rejects duplicate envelopes, non-reports, and tampered payloads", () => {
+        const { html } = exportReport(input(), fakeBundle("a"));
+        const block = /<script type="application\/json" id="moldesk-report">[\s\S]*?<\/script>/.exec(html)[0];
+        expect(() => extractEnvelope(html.replace("</body>", `${block}</body>`))).toThrow(/more than one/);
+        expect(() => extractEnvelope("<html><body>hi</body></html>")).toThrow(ReportFormatError);
+        const env = extractEnvelope(html);
+        expect(() => decodeEnvelope({ ...env, payloadSha256: "0".repeat(64) })).toThrow(/digest/);
+        expect(() => decodeEnvelope({ ...env, payload: "!!!" })).toThrow(/base64/);
+    });
+});
+describe("update", () => {
+    async function writeReport(bundle, name = "report.html") {
+        const file = path.join(dir, name);
+        writeFileSync(file, exportReport(input(), bundle).html);
+        return file;
+    }
+    it("is a no-op for the same bundle", async () => {
+        const b = fakeBundle("a");
+        const file = await writeReport(b);
+        expect((await planUpdate(file, { bundle: b })).status).toBe("noop");
+    });
+    it("does not trust same-version metadata when the scripts differ", async () => {
+        const b = fakeBundle("a");
+        const file = await writeReport(b);
+        writeFileSync(file, readFileSync(file, "utf8").replace("window.__v", "window.__evil"));
+        expect((await planUpdate(file, { bundle: b })).status).toBe("replace");
+    });
+    it("replaces with an older or newer local bundle, keeps payload, backs up the original", async () => {
+        const oldFile = await writeReport(fakeBundle("new", "2.0.0"));
+        const before = readFileSync(oldFile);
+        const payloadBefore = extractEnvelope(before.toString("utf8")).payload;
+        const plan = await planUpdate(oldFile, { bundle: fakeBundle("old", "1.0.0") });
+        expect(plan.status).toBe("replace");
+        const result = await applyUpdate(plan);
+        const after = readFileSync(oldFile, "utf8");
+        expect(after).toContain("viewer old");
+        expect(extractEnvelope(after).payload).toBe(payloadBefore);
+        expect(extractEnvelope(after).viewer.version).toBe("1.0.0");
+        expect(readFileSync(result.backupPath).equals(before)).toBe(true);
+        expect((await planUpdate(oldFile, { bundle: fakeBundle("old", "1.0.0") })).status).toBe("noop");
+    });
+    it("never overwrites an existing backup", async () => {
+        const file = await writeReport(fakeBundle("a"));
+        writeFileSync(path.join(dir, "report.backup.html"), "precious");
+        const result = await applyUpdate(await planUpdate(file, { bundle: fakeBundle("b") }));
+        expect(readFileSync(path.join(dir, "report.backup.html"), "utf8")).toBe("precious");
+        expect(path.basename(result.backupPath)).toBe("report.backup-1.html");
+    });
+    it("writes --output separately, leaves the original, refuses to overwrite", async () => {
+        const file = await writeReport(fakeBundle("a"));
+        const before = readFileSync(file);
+        const out = path.join(dir, "out.html");
+        const result = await applyUpdate(await planUpdate(file, { bundle: fakeBundle("b"), output: out }));
+        expect(result.backupPath).toBeUndefined();
+        expect(readFileSync(file).equals(before)).toBe(true);
+        expect(readFileSync(out, "utf8")).toContain("viewer b");
+        await expect(applyUpdate(await planUpdate(file, { bundle: fakeBundle("b"), output: out }))).rejects.toMatchObject({
+            code: "OUTPUT_EXISTS",
+        });
+    });
+    it("copies on no-op with --output", async () => {
+        const b = fakeBundle("a");
+        const file = await writeReport(b);
+        const out = path.join(dir, "copy.html");
+        const result = await applyUpdate(await planUpdate(file, { bundle: b, output: out }));
+        expect(result.status).toBe("copied");
+        expect(readFileSync(out).equals(readFileSync(file))).toBe(true);
+    });
+    it("rejects when the file changed after planning, leaving it untouched", async () => {
+        const file = await writeReport(fakeBundle("a"));
+        const plan = await planUpdate(file, { bundle: fakeBundle("b") });
+        writeFileSync(file, readFileSync(file, "utf8") + "<!-- edited -->");
+        const edited = readFileSync(file);
+        await expect(applyUpdate(plan)).rejects.toMatchObject({ code: "REPORT_CONFLICT" });
+        expect(readFileSync(file).equals(edited)).toBe(true);
+        expect(readdirSync(dir).filter((n) => n.includes("backup") || n.includes(".tmp-"))).toEqual([]);
+    });
+    it("preserves file mode", async () => {
+        const file = await writeReport(fakeBundle("a"));
+        chmodSync(file, 0o600);
+        await applyUpdate(await planUpdate(file, { bundle: fakeBundle("b") }));
+        expect(statSync(file).mode & 0o777).toBe(0o600);
+    });
+    it("rejects symlinks, ordinary HTML, and unsupported schemas without touching them", async () => {
+        const real = await writeReport(fakeBundle("a"));
+        const link = path.join(dir, "link.html");
+        symlinkSync(real, link);
+        await expect(planUpdate(link, { bundle: fakeBundle("b") })).rejects.toThrow(/symbolic link/);
+        const plain = path.join(dir, "plain.html");
+        writeFileSync(plain, "<html><script>alert(1)</script></html>");
+        await expect(planUpdate(plain, { bundle: fakeBundle("b") })).rejects.toThrow(/not a MoleculeDesk/);
+        const b = fakeBundle("b");
+        b.metadata.compatible.envelopeVersions = [99];
+        expect((await planUpdate(real, { bundle: b })).status).toBe("unsupported");
+    });
+});
+describe("writeFileExclusive", () => {
+    it("refuses an existing destination and cleans temp files", async () => {
+        const dest = path.join(dir, "x.html");
+        await writeFileExclusive(dest, "one");
+        await expect(writeFileExclusive(dest, "two")).rejects.toMatchObject({ code: "OUTPUT_EXISTS" });
+        expect(readFileSync(dest, "utf8")).toBe("one");
+        expect(readdirSync(dir)).toEqual(["x.html"]);
+    });
+});

package/package.json CHANGED Viewed

@@ -1,6 +1,54 @@
 {
   "name": "@moldesk/visualizer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.5",
+  "description": "Offline, self-contained Mol* molecular reports for MoleculeDesk",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pooriyapfn/moldesk.git",
+    "directory": "packages/visualizer"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    },
+    "./csv": {
+      "types": "./dist/csv.d.ts",
+      "default": "./dist/csv.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.16.11",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "esbuild": "0.28.2",
+    "molstar": "5.12.0",
+    "playwright-core": "1.63.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-viewer.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.browser.json",
+    "test": "vitest run",
+    "smoke": "node scripts/browser-smoke.mjs",
+    "measure": "node scripts/measure.mjs"
+  }
 }

package/README.md DELETED Viewed

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.