@niivue/nv-ext-save-html 1.0.0-rc.4 → 1.0.0-rc.40

package/README.md

@@ -13,10 +13,10 @@ Requires `@niivue/niivue` as a peer dependency.
 ## Usage
 
 ```ts
-import NiiVueGPU from '@niivue/niivue'
+import NiiVue from '@niivue/niivue'
 import { saveHTML } from '@niivue/nv-ext-save-html'
 
-const nv = new NiiVueGPU()
+const nv = new NiiVue()
 await nv.attachTo('gl1')
 await nv.loadVolumes([{ url: 'brain.nii.gz' }])
 

package/dist/gzip.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Gzip helpers built on the Web Streams API (available in all modern browsers).
+ *
+ * Split out of `index.ts` so it can be unit tested: `index.ts` imports
+ * `@niivue/niivue`, whose module graph uses Vite's `import.meta.glob` and cannot
+ * be loaded by the Bun test runner.
+ */
+/**
+ * Gzip-compress a Uint8Array.
+ *
+ * Start consuming `readable` BEFORE awaiting the write/close. A CompressionStream
+ * is a TransformStream whose readable side applies backpressure once its queue
+ * fills; if nothing is reading, `writer.write()` / `writer.close()` never settle
+ * and this hangs forever. In Chromium that happens for inputs as small as ~1 MB —
+ * i.e. every real document — so the read must already be in flight. (This is the
+ * same shape niivue's own `codecs/NVGz.ts` compress() uses.)
+ *
+ * `chunk` is a copy: a view backed by a SharedArrayBuffer (see the extension
+ * context's `acquireSharedBuffer`) cannot be enqueued directly.
+ */
+export declare function gzipCompress(data: Uint8Array): Promise<Uint8Array>;

package/dist/gzip.test.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { default as NiiVue } from '@niivue/niivue';
+export interface SaveHTMLOptions {
+    /**
+     * Fully self-contained niivue ESM bundle as a source code string.
+     *
+     * The bundle must export `NiiVue` as its **default export** and must
+     * have all dependencies (cbor-x, gl-matrix, nifti-reader-js, etc.) inlined.
+     *
+     * Build one with e.g. `vite build` using `rollupOptions.external: []`.
+     */
+    niivueBundleSource: string;
+    /** Canvas element ID in the generated HTML (default: `"gl1"`). */
+    canvasId?: string;
+    /** HTML `<title>` (default: `"NiiVue Scene"`). */
+    title?: string;
+}
+/**
+ * Generate a self-contained HTML string that embeds the current NiiVue scene.
+ *
+ * The returned HTML includes the niivue library and all loaded data (volumes,
+ * meshes, drawings, settings). Opening the HTML file in a browser will
+ * recreate the scene — no server or external files needed.
+ *
+ * @param nv      - The NiiVue instance whose scene to export.
+ * @param options - See {@link SaveHTMLOptions}.
+ * @returns A complete HTML document as a string.
+ */
+export declare function generateHTML(nv: NiiVue, options: SaveHTMLOptions): Promise<string>;
+/**
+ * Download the current NiiVue scene as a self-contained HTML file.
+ *
+ * Convenience wrapper around {@link generateHTML} that triggers a browser
+ * download.
+ *
+ * @param nv       - The NiiVue instance whose scene to export.
+ * @param filename - Name of the downloaded file (default: `"scene.html"`).
+ * @param options  - See {@link SaveHTMLOptions}.
+ */
+export declare function saveHTML(nv: NiiVue, filename: string | undefined, options: SaveHTMLOptions): Promise<void>;

package/dist/nv-ext-save-html.js

@@ -0,0 +1,128 @@
+async function l(e) {
+  const a = new CompressionStream("gzip"), t = new Uint8Array(e.byteLength);
+  t.set(e);
+  const n = new Response(a.readable).arrayBuffer(), o = a.writable.getWriter();
+  return await o.write(t), await o.close(), new Uint8Array(await n);
+}
+function d(e) {
+  const t = [];
+  for (let n = 0; n < e.length; n += 32768)
+    t.push(String.fromCharCode(...e.subarray(n, n + 32768)));
+  return btoa(t.join(""));
+}
+function u(e) {
+  return e.replace(/<\/script/gi, "<\\/script");
+}
+function p(e) {
+  return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function m(e, a, t, n) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${p(n)}</title>
+  <style>
+    html, body {
+      margin: 0;
+      padding: 0;
+      height: 100%;
+      width: 100%;
+      overflow: hidden;
+      background: #000;
+      font-family: system-ui, Arial, Helvetica, sans-serif;
+      user-select: none;
+    }
+    main {
+      position: relative;
+      width: 100%;
+      height: 100%;
+    }
+    canvas {
+      position: absolute;
+      width: 100%;
+      height: 100%;
+      cursor: crosshair;
+    }
+    canvas:focus {
+      outline: none;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <canvas id="${t}"></canvas>
+  </main>
+
+  <!-- NiiVue library bundle (inert — not executed by the browser) -->
+  <script id="__niivue_bundle__" type="text/plain">
+${u(e)}
+  <\/script>
+
+  <!-- NVD document data as gzip-compressed, base-64-encoded CBOR (inert) -->
+  <script id="__nvd_data__" type="text/plain">
+${a}
+  <\/script>
+
+  <!-- Loader: import the bundle, decode the document, restore the scene -->
+  <script type="module">
+    // 1. Dynamic-import the embedded niivue bundle
+    const bundleSrc = document.getElementById("__niivue_bundle__").textContent;
+    const blob = new Blob([bundleSrc], { type: "text/javascript" });
+    const blobUrl = URL.createObjectURL(blob);
+    const niivueModule = await import(blobUrl);
+    URL.revokeObjectURL(blobUrl);
+    const NiiVue = niivueModule.default ?? niivueModule.NiiVue;
+
+    // 2. Decode base-64, gzip-decompress, and wrap as a File
+    const base64 = document.getElementById("__nvd_data__").textContent.trim();
+    const raw = atob(base64);
+    const compressed = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i++) compressed[i] = raw.charCodeAt(i);
+    const ds = new DecompressionStream("gzip");
+    const writer = ds.writable.getWriter();
+    writer.write(compressed);
+    writer.close();
+    const bytes = new Uint8Array(await new Response(ds.readable).arrayBuffer());
+    const file = new File([bytes], "scene.nvd");
+
+    // 3. Create NiiVue, attach to canvas, and load the document
+    const nv = new NiiVue();
+    await nv.attachTo("${t}");
+    await nv.loadDocument(file);
+    // The serialized document has an empty matcap to avoid baking in
+    // environment-specific URLs. Restore the default matcap from this bundle.
+    if (nv.opts?.matcaps) {
+      const defaultMatcap = Object.values(nv.opts.matcaps)[0];
+      if (defaultMatcap) await nv.loadMatcap(defaultMatcap);
+    }
+  <\/script>
+</body>
+</html>`;
+}
+async function b(e, a) {
+  const {
+    niivueBundleSource: t,
+    canvasId: n = "gl1",
+    title: o = "NiiVue Scene"
+  } = a;
+  if (!t)
+    throw new Error(
+      "nv-ext-save-html: niivueBundleSource is required. Provide the full source of a self-contained niivue ESM bundle."
+    );
+  const r = e.volumeMatcap;
+  e.model.volume.matcap = "";
+  const i = e.serializeDocument();
+  e.model.volume.matcap = r;
+  const c = await l(i), s = d(c);
+  return m(t, s, n, o);
+}
+async function h(e, a = "scene.html", t) {
+  const n = await b(e, t), o = new Blob([n], { type: "text/html" }), r = URL.createObjectURL(o), i = document.createElement("a");
+  i.href = r, i.download = a, document.body.appendChild(i), i.click(), document.body.removeChild(i), URL.revokeObjectURL(r);
+}
+export {
+  b as generateHTML,
+  h as saveHTML
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niivue/nv-ext-save-html",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.40",
   "type": "module",
   "description": "Export a NiiVue scene as a self-contained HTML file",
   "main": "./dist/nv-ext-save-html.js",
@@ -16,10 +16,10 @@
     "dist"
   ],
   "peerDependencies": {
-    "@niivue/niivue": "1.0.0-rc.4"
+    "@niivue/niivue": "1.0.0-rc.40"
   },
   "devDependencies": {
-    "@niivue/niivue": "1.0.0-rc.4",
+    "@niivue/niivue": "1.0.0-rc.40",
     "typescript": "~5.8.3",
     "vite": "^6.3.2",
     "vite-plugin-dts": "^4.5.4"