Package the 3D field viewer's web assets in the installer (server-side serving is implemented, nothing ships the content)

[jcschaff]

Summary

FieldViewerServer can now serve the browser-based 3D field viewer's page itself, so the page and
its data share one origin (PR #1829). The server side is implemented and verified; the
packaging is not. Nothing produces or ships the web content it would serve, so in an installed
client the feature cannot work as designed.

This is not currently user-visible — the whole feature is behind vcell.fieldViewer.enabled, which
defaults to false — but it is what stands between the current state and a testable installed build.

Current behaviour

FieldViewerServer.staticRoot() looks for web content in:

1. -Dvcell.fieldViewer.staticDir=<dir>, else
2. <vcell.installDir>/webviewer

If neither exists it registers no static route and the browser is sent to
vcell.fieldViewer.url, which defaults to http://localhost:4400/ — a local static server a
developer runs from webapp-viewer/. That fallback is deliberate and right for developers, but on
an installed client nothing is listening there, so "View in 3D" would open a page that fails to
load.

What is missing

docker/build/installers/VCell.install4j packages only jars (lib), the license (resources),
BioNetGen/Perl, native libs and local solvers. There is no entry for web content — no webapp,
dist, webviewer or Angular reference anywhere in it — and site_deploy.yml stages none before
invoking install4j.

Three pieces are needed:

1. Fetching the bundle before the clientgen image is built. There is nothing to compile —
   the viewer is a static page with no framework and no bundler, so the directory is itself the
   deployable — but assets/vtk-wasm/ is gitignored and must be populated. npm run fetch:vtk-wasm does it.

   The localsolvers precedent argues for a download-maven-plugin execution, and it would
   work — but Ship the 3D field viewer's web content in the installers #1854 does it as a CI step instead, gated to the clientgen image. Solvers are
   downloaded into every build because developers actually run them locally; this bundle is only
   needed to build an installer, so putting it in maven would cost every developer a 12 MB download
   for a feature that is off by default.

2. Three lines in VCell.install4j. Note maven-jars is a poor template here: its
   mountPoint="719" is lib, not the install root. bionetgen (mountPoint id="1750" location="bionetgen") is the right precedent — a plain shared mount point relative to the
   install root, which is what vcell.installDir resolves to
   (${launcher:sys.launcherDirectory}). So: a vcellWebViewerPath compiler variable, a
   <mountPoint id="NNNN" location="webviewer"/>, and a <dirEntry> binding them.

3. A COPY in Dockerfile-clientgen-dev — COPY ./webapp-viewer /vcellclient/webviewer.

   site_deploy.yml needs no change, contrary to what this issue said earlier. It does not
   stage anything: it pulls the prebuilt vcell-clientgen image and runs build_installers.sh
   inside it, where mavenRootDir=/vcellclient refers to paths baked into the image. Everything
   the installer ships is COPYd in when that image is built by CI-full.yml (context: .,
   needs_maven: true), so the bundle must be on disk before that build — which is what step 1
   is for, and why the maven-download route is the tidy one: localsolvers/ already reaches the
   installer by exactly this path.

One decision that rides along

Full webapp, or a local-only build? — resolved, and it is neither. The viewer used to be a
webapp-ng route, whose index.html loads Bootstrap, the Auth0 theme and Google Fonts from CDNs;
an offline desktop user would have gotten unstyled content. It has been extracted into a standalone
webapp-viewer/ that contacts nothing but the client's own loopback server, so there is no webapp
build to configure and no CDN dependency to strip. See
docs/3d-renderer-design.md; the remaining design work
is the data-source seam (local loopback vs remote REST).

Size. ~12 MB, essentially all of it the wasm bundle, added to every
platform installer. Worth weighing against the current installer size before committing. Options if
that is too much: fetch the bundle on first use (reintroduces a network dependency at exactly the
moment a user is offline with a local simulation), or ship it only in some media.

Related

• PR PoC (flag-off): client-side vtk.wasm rendering of VCell FV fields, desktop → browser #1829 — the field viewer, including the static-serving implementation.
• docs/3d-renderer-design.md — design record; the "Serving the viewer page" open question tracks
  this.

---

Implemented in #1854 (stacked on #1829). Both docker behaviours were verified with real builds: the copy yields 12 MB of exactly the files the browser loads, and a skipped fetch stops the image build rather than shipping an installer whose viewer 404s.

[jcschaff]

npm run build_viewer now exists in webapp-ng (commit c3a7eeb) and is the build step this issue asks for — it is the only script that fetches the ~12 MB wasm bundle.

The fetch was deliberately removed from the shared build_* and start scripts at the same time, because CI-full.yml builds the webapp images with build_dev and build_stage, which put a fail-fast dependency on a GitHub release being reachable onto the deploy path for a feature that is off by default. Verified a shared build still succeeds without the bundle: the UMD loader comes from node_modules, not the fetch.

So of the three pieces listed above, the first is done. Remaining: a dirEntry mounting the build_viewer output at webviewer, and CI wiring to stage it.

One consequence to note: the deployed webapp no longer carries the bundle, so its /vtk-wasm spike route cannot render. That is consistent with the viewer being served by the desktop client, but if a web-facing viewer is wanted, it becomes part of the Mode B decision rather than something that happens by accident.