Add annotation overlay for the OncoTree (+ migrate frontend to pnpm)

.github/workflows/eslint.yml

@@ -8,10 +8,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v2
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
         with:
           node-version: 20.12.2
+          cache: pnpm
+          cache-dependency-path: web/src/main/javascript/pnpm-lock.yaml
       - name: Install node modules
-        run: npm install
+        run: pnpm install --frozen-lockfile
       - name: Run ESLint
-        run: npm run lint
+        run: pnpm run lint

.github/workflows/github-ci.yml

@@ -8,12 +8,17 @@ jobs:
         working-directory: web/src/main/javascript
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v2
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
         with:
           node-version: 20.12.2
+          cache: pnpm
+          cache-dependency-path: web/src/main/javascript/pnpm-lock.yaml
       - name: Install node modules
-        run: npm install
+        run: pnpm install --frozen-lockfile
       - name: Build frontend
-        run: npm run build
+        run: pnpm run build
       - name: Run unit tests
-        run: npm test
+        run: pnpm test

Dockerfile

@@ -1,10 +1,11 @@
 FROM node:20.12.2-alpine AS frontend-builder
+RUN corepack enable
 WORKDIR /app/frontend
-COPY web/src/main/javascript/package*.json ./
-RUN npm config set fetch-timeout 600000
-RUN npm ci
+COPY web/src/main/javascript/package.json web/src/main/javascript/pnpm-lock.yaml ./
+RUN pnpm config set fetch-timeout 600000
+RUN pnpm install --frozen-lockfile
 COPY web/src/main/javascript/ ./
-RUN npm run build
+RUN pnpm run build
 
 FROM golang:1.24.5-alpine AS backend-builder
 RUN apk add --no-cache git openssh-client

README.md

@@ -13,18 +13,78 @@ Read about our latest developments on our [News page](/docs/News.md).
 
 Users may submit their OncoTree related questions to the [OncoTree Users Google Group](https://groups.google.com/forum/#!forum/oncotree-users).
 
+## Annotation overlay
+
+The tree can be overlaid with custom annotations that map OncoTree codes to
+values. Each annotation may be a number, a text label, a gene list, or an
+object combining them, e.g.:
+
+```json
+{
+  "LUAD": { "label": "1204 samples", "value": 1204 },
+  "GB": { "genes": ["EGFR", "PTEN", "TP53"] }
+}
+```
+
+Each annotated node gets a small badge showing its value or gene count;
+hovering the node adds the full detail (value, gene list) to the node's
+tooltip. Collapsing a node rolls up its hidden descendants — values are summed
+and gene lists unioned.
+
+Annotations can be supplied four ways:
+
+1. **Paste or upload** JSON/CSV in the *Annotations* panel.
+2. **URL parameter** — `?annotations=<json>` where the value is raw
+   (URL-encoded) JSON or base64-encoded JSON (the panel's "Copy share link"
+   button produces the base64 form).
+3. **Embed via `postMessage`** — add `?embed` to the URL to hide the site
+   header and footer (leaving just the tree), then drive it from the host. Add
+   `allow="fullscreen"` to the `<iframe>` if you want the full-screen button to
+   work (browsers block fullscreen from an iframe otherwise):
+
+   ```html
+   <iframe src="https://…/?embed=1" allow="fullscreen"></iframe>
+   ```
+
+   When the app runs in an `<iframe>` it posts `{ type: "oncotree-ready" }` to
+   its parent; the parent then pushes annotations:
+
+   ```js
+   iframe.contentWindow.postMessage(
+     { type: "oncotree-annotations", annotations: { LUAD: 1204 } },
+     "*",
+   );
+   ```
+
+   The `annotations` payload may be an object, a JSON string, or `null` to
+   clear.
+
+   The parent can also drive the search, filtering the tree to the matching
+   node(s) (by code, name, or annotation content — gene/label/value):
+
+   ```js
+   iframe.contentWindow.postMessage(
+     { type: "oncotree-search", query: "EGFR" },
+     "*",
+   );
+   ```
+
+   Send an empty `query` (or `{ clear: true }`) to reset. The app posts back
+   `{ type: "oncotree-search-result", query, count }` with the number of
+   matches.
+
 ## Frontend Development
 
 All of the frontend code can be found at [/web/src/main/javascript](/web/src/main/javascript). The only configuration needed is to set `ONCOTREE_BASE_URL` 
 in [constants.ts](/web/src/main/javascript/src/shared/constants.ts). During development, it may be easiest to simply point to the public instance of 
 [OncoTree](https://oncotree.mskcc.org).
 
-Make sure you are using node version >=20.12.2.
+Make sure you are using node version >=20.12.2. The frontend uses [pnpm](https://pnpm.io/) as its package manager (enable it with `corepack enable`).
 
 To begin development run:
 ```
 cd ./web/src/main/javascript
-npm install && npm run dev
+pnpm install && pnpm run dev
 ```
 
 ## Building the Frontend
@@ -36,7 +96,7 @@ The frontend must be transpiled to static assets before bundling into a jar. To
 
     ```
     cd ./web/src/main/javascript
-    npm install && npm run build
+    pnpm install && pnpm run build
     ```
 3. The frontend assets are now up to date, and you are ready to bundle the jar.
 

scripts/deploy-gh-pages.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# Build the frontend as a static demo and publish it to the gh-pages branch of a
+# fork, served at https://<user>.github.io/<repo>/.
+#
+# The demo is fully self-contained: a snapshot of the OncoTree API is fetched at
+# build time and served alongside the app (same origin), so the running page
+# never makes a cross-origin request. This avoids CORS / Private Network Access
+# blocks when the page is embedded elsewhere. Configure via env vars:
+#
+#   DEPLOY_REMOTE   git remote/URL to push to            (default: inodb)
+#   DEPLOY_BASE     base path the site is served at       (default: /oncotree/)
+#   ONCOTREE_API    OncoTree API to snapshot at build time(default: https://oncotree.mskcc.org)
+#   TREE_VERSION    tree version to snapshot              (default: oncotree_latest_stable)
+#
+# Usage: scripts/deploy-gh-pages.sh
+set -euo pipefail
+
+DEPLOY_REMOTE="${DEPLOY_REMOTE:-inodb}"
+DEPLOY_BASE="${DEPLOY_BASE:-/oncotree/}"
+ONCOTREE_API="${ONCOTREE_API:-https://oncotree.mskcc.org}"
+TREE_VERSION="${TREE_VERSION:-oncotree_latest_stable}"
+
+# The app fetches `${API_BASE}/api/...`; point it at the deploy's own subpath so
+# requests resolve to the snapshot files staged below (same origin as the app).
+API_BASE="${DEPLOY_BASE%/}"
+
+repo_root="$(git rev-parse --show-toplevel)"
+js_dir="$repo_root/web/src/main/javascript"
+static_dir="$repo_root/web/src/main/resources/static"
+stage_dir="$(mktemp -d)"
+trap 'rm -rf "$stage_dir"' EXIT
+
+echo "Building static demo (base=$DEPLOY_BASE, apiBase=$API_BASE)..."
+cd "$js_dir"
+DEPLOY_BASE="$DEPLOY_BASE" VITE_ONCOTREE_BASE_URL="$API_BASE" pnpm run build
+
+echo "Staging build output..."
+cp -r "$static_dir/." "$stage_dir/"
+cp "$stage_dir/index.html" "$stage_dir/404.html" # SPA fallback for client routing
+touch "$stage_dir/.nojekyll"
+
+# The demo build (subpath base) overwrites the repo's committed build artifacts;
+# restore them so the working tree stays clean.
+git -C "$repo_root" checkout -- \
+  web/src/main/resources/static web/src/main/javascript/public 2>/dev/null || true
+
+echo "Snapshotting API from $ONCOTREE_API ..."
+mkdir -p "$stage_dir/api/tumorTypes"
+# GitHub Pages ignores the query string and serves these files for the app's
+# `/api/versions` and `/api/tumorTypes/tree?version=...` requests.
+curl -fsSL "$ONCOTREE_API/api/versions" -o "$stage_dir/api/versions"
+curl -fsSL "$ONCOTREE_API/api/tumorTypes/tree?version=$TREE_VERSION" \
+  -o "$stage_dir/api/tumorTypes/tree"
+
+remote_url="$(git -C "$repo_root" remote get-url "$DEPLOY_REMOTE")"
+echo "Publishing to $remote_url (gh-pages)..."
+cd "$stage_dir"
+git init -q
+git checkout -q -b gh-pages
+git add -A
+git commit -q -m "Deploy oncotree annotation overlay demo"
+git push -f "$remote_url" gh-pages
+
+echo "Done. Enable Pages once with:"
+echo "  gh api -X POST repos/<owner>/<repo>/pages -f source.branch=gh-pages -f source.path=/"

web/src/main/javascript/.husky/pre-commit

@@ -1 +1 @@
-npx lint-staged
+pnpm exec lint-staged

web/src/main/javascript/README.md

@@ -1,7 +1,7 @@
 # Running locally
 
 ```bash
-npm run dev
+pnpm run dev
 ```
 
 # React + TypeScript + Vite

web/src/main/javascript/jest.config.js

@@ -2,7 +2,10 @@
 export default {
     testEnvironment: "jsdom",
     transform: {
-      "^.+.tsx?$": ["ts-jest", {}],
+      "^.+.tsx?$": [
+        "ts-jest",
+        { tsconfig: { target: "ES2020", lib: ["ES2020", "DOM"] } },
+      ],
     },
   };