The aligner is dead. Long live the aligner.

[candytaco]

I had claude re-implement the mayavi aligner in webgl.

cortex.align.webgl_maual(<surface>, <transform>) gives a webgl viewer that can edit transforms.

Updated to show the data also on the surface in real-time as you move the transform.

Controls:
WASD or RMB to translate, QE to rotate, hold shift to move in 1/10th size increments. I've specifically removed the scaling/stretching options.

Aligner_.TZfs.aligner-test.-.Vivaldi.2026-09-19.13-28-07.webm

Edit histories are tracked and can be undone to any edit
Aligner_ TZfs aligner-test - Vivaldi 2026-09-19 21-51-39.webm

(I am very proud of the PR title, which, unlike the code, came solely from my brain)

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot review overview

🟡 Changes recommended

The save path has unresolved authorization, data-loss, completion, and rendering edge cases.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• Unauthenticated cross-origin access permits destructive saves · New
• Save returns before asynchronous persistence completes · New
• Unattached server breaks delayed browser reply handling · New
• Zero volume range causes invalid shader colormap calculations · New

[mvdoc]

@claude review

[claude]

Claude finished @mvdoc's task in 1m 52s —— View job

---

Review of #739 — the WebGL aligner

• Gather context (PR diff, files, prior Copilot review comments)
• Review cortex/webgl/aligner.py (new tornado server + save endpoint)
• Review cortex/align.py changes (webgl_manual entry point)
• Review cortex/webgl/resources/js/aligner.js and shaderlib.js changes
• Review tests in cortex/tests/test_webgl_aligner.py
• Post final review

This is a substantial, well-documented replacement of the mayavi aligner. The docstrings are thorough and the test suite (cortex/tests/test_webgl_aligner.py, 748 lines) is unusually complete, including headless-browser Playwright coverage. I independently verified the four issues Copilot's automated review already flagged — all four are real, confirmed against the current code, not artifacts of a stale diff:

1. /save has no auth/CSRF protection (cortex/webgl/aligner.py:511-539)
SaveHandler.post performs a destructive filesystem write (db.save_xfm) and deletion (clear_masks) with no token or Tornado XSRF check. WebApp (cortex/webgl/serve.py:334) binds via bind_sockets(port) with no address restriction, so this is reachable from any host that can route to the port, not just loopback. This is a shared risk with cortex.webgl.show, but that server is read-only — this is the first place the webgl server exposes a destructive write, so it's worth tightening (bind to 127.0.0.1 and/or require the per-session token that's already generated for RPC calls).

2. save() returns before the save actually completes (aligner.py:288-290, resources/js/aligner.js:998-1024)
JSAligner.save()'s docstring says it saves "like the Save button," but under the hood Aligner.prototype.save in JS fires an async $.ajax POST and returns the literal string "saving" immediately — success/failure is only reported later via showStatus(), which the Python side never sees. Confirmed by the test itself: test_aligner_in_headless_browser (test_webgl_aligner.py:506-511) has to separately poll recorder.wait(1) after calling handle.save(), rather than trusting the return value — i.e., the test works around the gap instead of exercising a contract that holds. A caller who calls .save() and then tears down the server immediately can lose the write silently.

3. get_client() / get_local_client() don't attach server (aligner.py:544-550)
The open_browser=True path manually does object.__setattr__(client, "server", server) (aligner.py:569) after calling get_client(), but get_client()/get_local_client() themselves don't do this. So the documented open_browser=False flow (server = webgl_manual(...); client = server.get_client()) produces a JSAligner whose _call sees server is None and silently falls back to WebApp.send's ~2s timeout instead of the intended 120s tagged-reply loop (aligner.py:200-232). This is masked in every current test by manually patching it in (e.g. test_webgl_aligner.py:455: object.__setattr__(handle, "server", server)), which means the "normal" documented path is untested. Worth setting self as server inside get_client/get_local_client directly.

4. Unguarded vmin == vmax division in aligner_volume shader (resources/js/shaderlib.js:1015)
float norm = (value - vmin) / (vmax - vmin); has no zero-denominator guard. show() in aligner.py:422-425 guards the initial value, but the colormap min/max sliders in the UI can still be moved to equal values interactively, producing NaN/Inf sampling. Note this mirrors an existing pattern elsewhere in shaderlib.js (e.g. lines 20-21), so it's not a new class of bug introduced by this PR, but it's worth a max(vmax - vmin, epsilon) guard in the new shader since it's easy to trigger from the aligner's own UI.

Everything else — the coordinate-frame math (reference_frame, world/coord conventions), mask invalidation on save, the transform-name validation (XFM_NAME regex blocking path traversal), and the CTM/mesh handling — looked correct and carefully commented. No functional issues found there.

No code changes were made — this was a review-only request, per the instructions ("review" → provide feedback, don't implement).
(branch: claude/awesome-wright-5bz9m3)

[candytaco]

This now adds a history panel so you can undo to any edit in the edit history

[candytaco]

@claude review

[claude]

Claude finished @candytaco's task in 1m 58s —— View job

---

Review of #739 — the WebGL aligner (update)

• Gather context (PR diff vs origin/main, prior Copilot/Claude review threads)
• Verify the four previously-flagged issues are actually fixed as claimed
• Review cortex/webgl/serve.py changes (loopback binding, token guard)
• Review cortex/align.py changes (webgl_manual entry point, mayavi removal)
• Review the newer, not-yet-reviewed commits (slice views / crosshair / picking)
• Review cortex/tests/test_webgl_aligner.py and test_webgl_headless.py
• Post final review

I re-checked the four issues Copilot and my earlier review flagged (/save auth, save() returning before completion, get_client() not attaching server, the shader's vmin == vmax division), and they're all genuinely fixed by b38ae14 — confirmed against the current code, not just the comment claiming it:

• serve.py now binds via bind_local_sockets/LOOPBACK by default (cortex/webgl/serve.py:52-113), and every handler is wrapped in TokenGuard (serve.py:344-379).
• SaveHandler.post (aligner.py:558) checks a per-page save_token with hmac-based same_token before touching the filesystem.
• Aligner.prototype.save (aligner.js:1179-1220) sets this._saveState = {status: "saving", ...} synchronously, before the async $.ajax fires, so JSAligner.save()'s poll loop (aligner.py:288-317) can't read a stale prior result.
• WebApp.get_client (aligner.py:593-604) now attaches server to the returned handle itself, so the documented open_browser=False path gets the real 120s tagged-reply loop.

Test coverage for all of this in test_webgl_aligner.py (1123 lines) is genuinely thorough, not superficial — e.g. test_save_needs_the_token_of_the_page and test_every_page_needs_the_session_token directly exercise the auth fix, and test_aligner_in_headless_browser asserts db.save_xfm was actually called by the time save() returns rather than polling afterwards.

New finding, in code not covered by the earlier reviews (the slice-view/crosshair/picking commits added since):

Crosshair can desync from the slice-plane images if a pick happens before "ortho views" is ever turned on — cortex/webgl/resources/js/mriview.js:1611-1645 (setCursor) and :1764-1779 (_showAllPlanes).

setCursor() only moves the slice planes to the picked voxel when this._sliceviews is already true:

if (this._sliceviews) {
    var slices = {x: voxel.x, y: voxel.y, z: voxel.z};
    for (var name in this.sliceplanes) { ... .update(slices[name]); }
}

But pick() (mriview.js:976-996) calls setCursor(coords) unconditionally, including while still in the plain 3D view (_sliceviews === false, the default state). In that case _cursorAt is set true and the crosshair's world position is recorded, but the three slice images are left wherever they were. Toggling into ortho view afterward (v key / menu) calls setSliceViews(true) → _showAllPlanes(), which makes the crosshair visible in all four views (_sliceviews===true && _cursorAt===true) — but the slice planes were never moved to the picked point's slice. The crosshair ends up shown against unrelated slice images, which directly contradicts the comment documenting the intent at mriview.js:1608-1609: "so that the four views agree on where it is."

This isn't exercised by the new tests: test_ortho_views_split_the_canvas always splits the view before picking, so the "pick first, then split" ordering is untested. A fix would be to drop the if (this._sliceviews) guard in setCursor (updating the plane's slice index is presumably harmless while the plane is hidden), or to re-apply the last picked voxel's slice indices when setSliceViews(true) turns ortho view on.

Fix this →

Minor / non-blocking:

• cortex/align.py:51-53 (webgl_manual docstring) describes only two display modes ("surface outlines... or the volume painted on the surface"), but there are actually three (slices/brain/surface, per aligner.py:48-50 and aligner.js:41-43), and it omits the history panel and depth/unfold controls that docs/align.rst documents accurately. Worth syncing the docstring with docs/align.rst at some point, but not a functional bug.
• cortex/tests/test_webgl_headless.py:914 — a docstring still says `ortho_views` (the old snake_case control name), while the control was renamed to "Show ortho views" in cc9461d/55a0925. Stale comment only.

Everything else — cortex/align.py's handling of reference/xfmname, the [webgl_aligner] config section replacing [mayavi_aligner], doc/image cleanup (no dangling references to deleted docs/aligner/*.png or mayavi_aligner anywhere in the repo), axes3d.js's per-view scissor/camera handling, and the CSS for the new ortho-view layout — checked out fine.
·