feat(viewer): resolve ?montage=<hash> against the registry

Extracts buildMontageFromSensors from the TSV path so both the BIDS
drag-drop loader and the new registry loader share sphere-fit, unit
inference, and region assignment.

- bids-loader.js: new buildMontageFromSensors (refactor of the
  post-parse half of buildMontageFromBIDS) + buildMontageFromRegistryDoc
  which consumes either the wrapped {database, data: doc} response or
  the bare doc.
- index.html: auto-load IIFE branches on qMontage first, fetches
  {api}/api/{db}/montages/{hash} via the new loadMontageFromRegistry
  helper, and builds the viewer montage directly (skipping the TSV
  round-trip). ?api= and ?db= pin the base URL and database name for
  dev/staging. Cache-bust: bids-loader.js?v=3.
- test-data/mock-api/: refreshed fixtures to match the real registry
  response shape ({database, data: {hash, modality, n_sensors, sensors,
  space_declared, units_declared}}); README rewritten.

Author: bruAristimunha

bids-loader.js

@@ -384,33 +384,28 @@
     return null;
   }
 
-  // ---- Main entry ---------------------------------------------
-  // Returns { label, count, electrodes, space, units, sphere, layoutStyle,
-  // modality } matching the shape of MONTAGES[key]. The `modality` field
-  // drives the viewer's rendering path ('sphere' vs 'flat').
-  api.buildMontageFromBIDS = function ({ tsvText, coordsystemJson, label, modality }) {
-    const parsed = api.parseElectrodesTSV(tsvText);
-    const meta = coordsystemJson
-      ? api.parseCoordsystem(coordsystemJson)
-      : { space: 'Other', units: null, landmarks: null };
-
-    // Resolve modality: explicit > inferred from coordsystem.json keys > "eeg".
+  // ---- Core sensor → montage pipeline -------------------------
+  // Used by both the TSV path (parse first) and the registry path (sensors
+  // already parsed server-side). Input is an array of ``{name, x, y, z,
+  // type?, material?}`` rows plus a ``meta = {space, units}`` object and
+  // the caller's chosen modality (explicit or resolved).
+  api.buildMontageFromSensors = function ({ sensors, meta, label, modality }) {
     const resolved = (
       (modality || '').toLowerCase() ||
-      inferModalityFromMeta(meta, coordsystemJson) ||
+      inferModalityFromMeta(meta, null) ||
       'eeg'
     );
 
     // Flat pipeline for non-spherical modalities. No sphere-fit, no unit
     // inference, no axis rotation. The viewer renders a simple scatter.
     if (!SPHERE_MODALITIES.has(resolved)) {
-      return buildFlatMontage({ raw: parsed, meta, label, modality: resolved });
+      return buildFlatMontage({ raw: sensors, meta, label, modality: resolved });
     }
 
     // Rotate into RAS+ if the declared space uses ALS (EEGLAB/CTF/4D/KIT).
     // Pure permutation + sign flip, safe to apply before sphere fitting.
     const axisXform = axisTransformForSpace(meta.space);
-    const raw = axisXform ? parsed.map(axisXform.apply) : parsed;
+    const raw = axisXform ? sensors.map(axisXform.apply) : sensors;
 
     const rawSphere = api.fitSphere(raw);
     if (!rawSphere) {
@@ -476,5 +471,68 @@
     };
   };
 
+  // ---- Main entry (TSV + coordsystem pipeline) ----------------
+  // Returns { label, count, electrodes, space, units, sphere, layoutStyle,
+  // modality } matching the shape of MONTAGES[key]. The `modality` field
+  // drives the viewer's rendering path ('sphere' vs 'flat').
+  api.buildMontageFromBIDS = function ({ tsvText, coordsystemJson, label, modality }) {
+    const parsed = api.parseElectrodesTSV(tsvText);
+    const meta = coordsystemJson
+      ? api.parseCoordsystem(coordsystemJson)
+      : { space: 'Other', units: null, landmarks: null };
+
+    // Let inferModalityFromMeta see the raw coordsystem.json keys — they
+    // carry the only modality hint outside of the URL.
+    const resolved = (
+      (modality || '').toLowerCase() ||
+      inferModalityFromMeta(meta, coordsystemJson) ||
+      'eeg'
+    );
+
+    return api.buildMontageFromSensors({
+      sensors: parsed,
+      meta,
+      label,
+      modality: resolved,
+    });
+  };
+
+  // ---- Registry pipeline (GET /api/{db}/montages/{hash}) -------
+  // The API returns ``{database, data: <montage doc>}``; pass either the
+  // wrapper or the inner doc here. Registry docs ship sensors already
+  // parsed plus declared space/units, so we bypass TSV parsing entirely.
+  api.buildMontageFromRegistryDoc = function (docOrResponse, { label } = {}) {
+    const doc = (docOrResponse && docOrResponse.data) ? docOrResponse.data : docOrResponse;
+    if (!doc || !Array.isArray(doc.sensors) || doc.sensors.length < 4) {
+      throw new Error('registry doc missing sensors array (need at least 4)');
+    }
+    // Normalize sensor rows. The digest pipeline writes `{name, x, y, z}`
+    // plus optional `type`/`material`; coerce to numbers defensively.
+    const sensors = doc.sensors
+      .map(s => ({
+        name: String(s.name || '').trim(),
+        x: +s.x, y: +s.y, z: +s.z,
+        type: s.type || '',
+        material: s.material || '',
+      }))
+      .filter(s => s.name && isFinite(s.x) && isFinite(s.y) && isFinite(s.z));
+    if (sensors.length < 4) {
+      throw new Error('registry doc has fewer than 4 electrodes with finite coordinates');
+    }
+    const meta = {
+      space: doc.space_declared || 'Other',
+      units: (doc.units_declared || '').toLowerCase() || null,
+      landmarks: null,
+    };
+    const hashTag = doc.hash ? ` · ${String(doc.hash).slice(0, 8)}` : '';
+    const fallbackLabel = `Registry${hashTag} · ${sensors.length}ch`;
+    return api.buildMontageFromSensors({
+      sensors,
+      meta,
+      label: label || fallbackLabel,
+      modality: doc.modality,
+    });
+  };
+
   window.BIDSLoader = api;
 })();

index.html

@@ -9,7 +9,7 @@
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600&display=swap" />
 <link rel="stylesheet" href="styles.css?v=4" />
 <script src="montages.js?v=6"></script>
-<script src="bids-loader.js?v=2"></script>
+<script src="bids-loader.js?v=3"></script>
 <script src="topo2d.js?v=6"></script>
 </head>
 <body>
@@ -731,10 +731,12 @@ <h3 class="rail-title"><span>Quick actions</span></h3>
 
    Three URL shapes, in priority order:
 
-     ?montage=<registry_id>
-         Fetches data.eegdash.org/api/eegdash/montages/<id>, resolves the
-         TSV and coordsystem URLs from the manifest, then loads. Primary
-         shape used by the iframe inside eegdash docs pages.
+     ?montage=<hash>   (optional ?api=<base>&db=<name> overrides)
+         GET <base>/api/<db>/montages/<hash> → registry doc with the
+         sensor coordinates already parsed server-side. Skips the TSV
+         round-trip. Primary shape used by the iframe inside eegdash
+         docs pages. ``?api=`` / ``?db=`` exist for pointing at a dev
+         registry without rebuilding the viewer.
 
      ?tsv=<url>&coords=<url>
          Direct fetch of two files. ?coords= is optional. Useful for
@@ -765,6 +767,7 @@ <h3 class="rail-title"><span>Quick actions</span></h3>
   const qCoords  = params.get('coords');
   const qDemo    = params.get('demo');
   const qApi     = params.get('api');
+  const qDb      = params.get('db');
 
   if (!qMontage && !qTsv && !qDemo) return;
 
@@ -773,7 +776,25 @@ <h3 class="rail-title"><span>Quick actions</span></h3>
     return;
   }
 
-  const sources = await resolveAutoloadSources({ qMontage, qTsv, qCoords, qDemo, qApi })
+  // Registry path: montage doc already carries sensor coordinates, so we
+  // skip the TSV round-trip and hand the doc straight to the sensor
+  // pipeline. This is the shape the eegdash docs iframe uses.
+  if (qMontage) {
+    try {
+      const montage = await loadMontageFromRegistry({ hash: qMontage, apiBase: qApi, database: qDb });
+      MONTAGES[LOADED_KEY] = montage;
+      upsertLoadedMontageButton(montage);
+      setMontage(LOADED_KEY);
+    } catch (err) {
+      console.error('[auto-load] registry fetch failed:', { hash: qMontage, err });
+      showLoadError(`Could not load montage: ${err.message}`);
+    }
+    return;
+  }
+
+  // Raw-file paths (?tsv= / ?demo=): fetch the TSV + optional coordsystem
+  // and feed them through the existing drag-drop pipeline.
+  const sources = await resolveAutoloadSources({ qTsv, qCoords, qDemo })
     .catch(err => { showLoadError(err.message); return null; });
   if (!sources) return;
 
@@ -786,19 +807,29 @@ <h3 class="rail-title"><span>Quick actions</span></h3>
   }
 })();
 
-/* Resolve query params to concrete URLs and a display label.
-   Returns { tsvUrl, coordsUrl | null, label }. */
-async function resolveAutoloadSources({ qMontage, qTsv, qCoords, qDemo, qApi }) {
-  if (qMontage) {
-    // Registry lookup. Base URL can be overridden with ?api=… for testing.
-    const apiBase = (qApi || 'https://data.eegdash.org').replace(/\/$/, '');
-    const regUrl = `${apiBase}/api/eegdash/montages/${encodeURIComponent(qMontage)}`;
-    const r = await fetchWithTimeout(regUrl);
-    if (!r.ok) throw new Error(`registry ${regUrl} → ${r.status}`);
-    const doc = await r.json();
-    if (!doc.tsv_url) throw new Error('registry doc missing tsv_url');
-    return { tsvUrl: doc.tsv_url, coordsUrl: doc.coords_url || null, label: doc.label || doc.id || qMontage };
+/* Fetch a registry montage doc and build an in-viewer montage. Rejects
+   with a user-readable Error on 404/timeout/malformed response. */
+async function loadMontageFromRegistry({ hash, apiBase, database }) {
+  const base = (apiBase || 'https://data.eegdash.org').replace(/\/+$/, '');
+  const db = (database || 'eegdash').replace(/[^a-z0-9_]/gi, '');
+  const regUrl = `${base}/api/${db}/montages/${encodeURIComponent(hash)}`;
+  const r = await fetchWithTimeout(regUrl);
+  if (r.status === 404) {
+    throw new Error(`no registry entry for montage ${hash}`);
   }
+  if (!r.ok) {
+    throw new Error(`registry ${regUrl} → ${r.status}`);
+  }
+  const body = await r.json().catch(() => null);
+  if (!body) throw new Error('registry returned non-JSON response');
+  return BIDSLoader.buildMontageFromRegistryDoc(body, {
+    label: `Registry · ${String(hash).slice(0, 8)}`,
+  });
+}
+
+/* Resolve direct-URL query params (?tsv/?demo) to concrete URLs.
+   Returns { tsvUrl, coordsUrl | null, label }. */
+async function resolveAutoloadSources({ qTsv, qCoords, qDemo }) {
   if (qTsv) {
     // Trust the caller. Accept any scheme so tests can point at localhost.
     return { tsvUrl: qTsv, coordsUrl: qCoords || null, label: extractLabelFromUrl(qTsv) };

test-data/mock-api/README.md

@@ -1,48 +1,55 @@
 # Mock eegdash registry API
 
-Used only for local testing of the `?montage=<id>` URL shape before the
-real backend endpoint (`https://data.eegdash.org/api/eegdash/montages/<id>`)
-is deployed.
+Used only for local testing of the `?montage=<hash>` URL shape. The real
+backend lives at `https://data.eegdash.org/api/eegdash/montages/<hash>`
+and returns the same schema.
 
 ## Serving locally
 
 The standard `python3 -m http.server` in the parent `electrode-explorer/`
 folder serves these files at
-`http://localhost:9876/test-data/mock-api/api/eegdash/montages/<id>`.
+`http://localhost:9876/test-data/mock-api/api/eegdash/montages/<hash>`.
 
 Point the app at this mock with `?api=<base>`, for example:
 
 ```
-http://localhost:9876/index.html?montage=biosemi-256-eeglab-v1&api=http%3A%2F%2Flocalhost%3A9876%2Ftest-data%2Fmock-api
+http://localhost:9876/index.html?montage=a1b2c3d4e5f60718&api=http%3A%2F%2Flocalhost%3A9876%2Ftest-data%2Fmock-api
 ```
 
+Available mock hashes: `a1b2c3d4e5f60718` (17-channel 10-20 subset),
+`biosemi-256-eeglab-v1` (256-channel BioSemi cap).
+
 ## File naming
 
-Mock response files have **no extension** (`biosemi-256-eeglab-v1`, not
-`.json`) because the real API path is
-`/api/eegdash/montages/biosemi-256-eeglab-v1`. Python's `http.server`
+Mock response files have **no extension** — the real API path is
+`/api/eegdash/montages/<hash>` without a suffix. Python's `http.server`
 serves them as `application/octet-stream`, which the browser still parses
 via `response.json()` without complaint.
 
 ## Schema
 
-Each file is a JSON document with the fields below. See `PLAN.md` Step 3
-for the canonical schema.
+Each file matches the `MontageResponse` shape returned by the real
+backend (`mongodb-eegdash-server/api/main.py::get_montage`):
 
 ```json
 {
-  "id":                       "biosemi-256-eeglab-v1",
-  "hash":                     "<sha1-of-sorted-names-and-rounded-coords>",
-  "n_channels":               256,
-  "space_declared":           "CTF | CapTrak | EEGLAB | MNI | …",
-  "units_declared":           "m | cm | mm",
-  "label":                    "BioSemi 256 (EEGLAB space)",
-  "representative_dataset":   "ds002578",
-  "representative_subject":   "sub-002",
-  "tsv_url":                  "https://…/electrodes.tsv",
-  "coords_url":               "https://…/coordsystem.json",
-  "first_seen_at":            "2026-04-21T00:00:00Z"
+  "database": "eegdash",
+  "data": {
+    "hash":            "<16-char sha1 prefix>",
+    "modality":        "eeg | ieeg | meg | nirs",
+    "n_sensors":       17,
+    "space_declared":  "CapTrak | EEGLAB | MNI | …",
+    "units_declared":  "m | cm | mm",
+    "sensors": [
+      {"name": "Fp1", "x": -29.44, "y": 83.92, "z": -6.99, "type": "EEG"},
+      …
+    ],
+    "first_seen":             "2026-04-21T00:00:00Z",
+    "representative_dataset": "ds…",
+    "representative_subject": "sub-…"
+  }
 }
 ```
 
-`tsv_url` is required; `coords_url` is optional.
+The viewer's `BIDSLoader.buildMontageFromRegistryDoc` consumes this
+directly — no TSV round-trip needed.